chore: implement auth middleware and schema refactor

Author: ryanbas21

e2e/mock-api-v2/README.md

@@ -1,109 +1,87 @@
-### Mock Api
+A mock API server for simulating Ping Identity and OpenID Connect flows, built using [Effect](https://effect.website/) and [@effect/platform](https://github.com/Effect-TS/platform). This service is designed for end-to-end testing and development, providing realistic responses for authentication and authorization scenarios.
 
-## Docs
+## Features
 
-you can run the server and visit `http://localhost:9443/docs#` to visit the swagger docs
-The swagger docs are automatically created (with effect-http) by way of the schemas that are defined in the [spec file]('./src/spec.ts')
+- Implements endpoints for:
 
-## Creating an endpoint in the Api specification
+  - Healthcheck
+  - OpenID Connect Discovery
+  - Davinci Authorization
+  - Token acquisition
+  - UserInfo (protected, requires Bearer token)
 
-To create an endpoint, visit the [spec]('./src/spec.ts') file and add your endpoint. For organization and cleanliness, endpoints can be abstracted into the [endpoints]('./src/endpoints/') folder.
+- Uses Effect and @effect/platform for functional, type-safe API definition and handling.
+- Includes middleware for logging, CORS, cookie management, and Bearer token authorization.
 
-When an endpoint is made, you can add it to the [`spec`]('./src/spec.ts') `pipe`.
+## Tech Stack
 
-## Handling your new endpoint
+- [Effect](https://effect.website/)
+- [@effect/platform](https://github.com/Effect-TS/platform)
+- Node.js (via @effect/platform-node)
+- TypeScript
 
-When you have created an endpoint in the specification, you need to now handle the endpoint. This is the actual code implementation of your endpoint.
+## Getting Started
 
-handlers are saved in the [handlers]('./src/handlers/') folder.
+### Install dependencies
 
-You use RouterBuilder.handler, passing in the [api spec]('./src/spec.ts') and the name of the route, and then an Effect returning function (`Effect.gen` is the simplest form of this).
-
-The request arguments, you define in your endpoint specification, (query params, path params, request bodies, etc) are the arguments passed to the callback function of `RouterBuilder.handler`.
-
-Ensure that you also add your `handler` to the RouterBuilder.handle [here]('./src/main.ts');
-
-## Adding a journey / flow to the response map
-
-If you are adding a flow to the response map the first thing to do is open up [responseMap]('./src/responses/index.ts')
-
-This file is a `map` of Names -> Array<Step> where a Step is the response you want to return (in order). Order is key here.
-
-If the Response you want to return is not already defined as a schema, you will have to define a new Schema and add the response.
-
-A schema is defined in the schemas folder [here]('./src/schemas/');
-A response is defined in the responses folder [here]('./src/responses/')
-
-This is still a work in progress in terms of making it more scalable.
-
-## Validating your code in Test
-
-After adding a journey/flow to the response map and defining a schema, you next want to have some validation on the submitted request. You can do this by adding it to the `validator` function [here]('./src/helpers/match.ts');
-
-This functions job is to `match` the type passed in, and validate based on the condition provided. If it passes, a boolean is returned, if it fails, a new Error should be returned.
-
-## Services
-
-To make it so types line up easier, each route, has a service dedicated to itself. The service under the hood, uses the `Requester` service. The `Requester` service is to mimic a call to the authorization server.
-
-Let's look at the `Authorize` service. This service is the workhorse of the `authorize` handler.
-
-`Authorize`, the service, uses `Requester` which will fetch a response from the authorization server.
-
-After retrieving the response, the service will catch any errors that may be thrown, and mold them into HttpErrors to respond back to the client.
-
-In a mock environment, rather than fetching from the client, authorization service will grab the next response from the `responseMap`.
+```sh
+pnpm install
+```
 
-In a live environment, it will forward a request to the Fetch service, and return that response.
+### Build
 
-## Creating Errors
+```sh
+pnpm build
+```
 
-If you want to create an error, it is simple. This is the skeleton of how to create an Error in `Effect`
+### Run the server
 
-```
-class MyErrorName {
-  readonly _tag  = 'MyErrorName'
-}
+```sh
+pnpm serve
 ```
 
-The `_tag` is important as this is the name of the error, and how we can `catchTags` in our error handling. For simplicity, you can name is the same as your error class.
+The server will start on port `9443`.
 
-## Handling Errors
+### Run tests
 
-We want to return our errors back to the client, but typically we need an error response body that informs the client of the issue.
+```sh
+pnpm test
+```
 
-You should add your error responses to the response folder [here]('./src/responses');
+## API Overview
 
-In the service where you want to handle your error, you will see a `catchTags` function.
+### Healthcheck
 
-Let's pause here to understand the `Effect` type.
+- `GET /healthcheck`
+- Returns `"Healthy"` if the server is running.
 
-```ts
-Effect<Success, Error, Requirements>;
-```
+### OpenID Connect Discovery
 
-When reading an Effect type, the first generic, is what is returned if the effect is successful.
+- `GET /:envid/as/.well-known/openid-configuration`
+- Returns a static OpenID configuration response.
 
-The second argument is what is returned if the effect is unsuccessful.
+### Davinci Authorization
 
-The third argument is any services (or layers) that are required to run this effect.
+- `GET /:envid/as/authorize`
+- Accepts query parameters for authorization.
+- Returns a mock authorization response.
 
-So if we have an `effect` like this `Effect<Users, HttpError.HttpError | NoSuchElementException, never>`
+### Token Endpoint
 
-This tells us the `effect` returns `users`, and can error two ways, `NoSuchElementException`, and with an `HttpError`.
+- `POST /:envid/as/token`
+- Returns a mock access token response.
 
-We would rather handle this `NoSuchElementException` and send back to the client an HttpError informing them of the error that occurred.
+### UserInfo (Protected)
 
-We can do something like this now
+- `GET /:envid/as/userinfo`
+- Requires a valid Bearer token.
+- Returns mock user information.
 
-```ts
-Effect.catchTag('NoSuchElementException', () =>
-  HttpError.unauthorizedError('no such element found'),
-);
-```
+## Notes
 
-This will return a 401 with that message.
+- The `customHtmlRoutes` and related endpoints are not currently implemented.
+- All endpoints return static or mock data for testing purposes.
 
-When handling errors, we try to keep the handler always returning an `HttpError`, so we should handle any other errors we have deeper in the call stack, to return HttpError unless there is a valid reason to allow the error to bubble up.
+## License
 
-If you have a shape of an error that you want to return from a handler, that does not match the current schema, you can add it to the `api spec`.
+MIT © Ping Identity Corporation

e2e/mock-api-v2/src/errors/index.ts

@@ -15,6 +15,7 @@ class FetchError {
 class InvalidProtectNode {
   readonly _tag = 'InvalidProtectNode';
 }
+
 class UnableToFindNextStep {
   readonly _tag = 'UnableToFindNextStep';
 }

e2e/mock-api-v2/src/handlers/userinfo.handler.ts

@@ -8,16 +8,18 @@ import { Effect } from 'effect';
 import { MockApi } from '../spec.js';
 import { UserInfo } from '../services/userinfo.service.js';
 import { HttpApiBuilder } from '@effect/platform';
+import { BearerToken } from '../middleware/Authorization.js';
 
 /**
  * TODO: Need to implement an Authorization middleware
  */
 const UserInfoMockHandler = HttpApiBuilder.group(MockApi, 'Protected Requests', (handlers) =>
   handlers.handle('UserInfo', () =>
     Effect.gen(function* () {
+      const authToken = yield* BearerToken;
       const { getUserInfo } = yield* UserInfo;
 
-      const response = yield* getUserInfo;
+      const response = yield* getUserInfo(authToken);
 
       return response;
     }),

e2e/mock-api-v2/src/main.ts

@@ -18,6 +18,7 @@ import { TokensMock } from './services/tokens.service.js';
 import { TokensHandler } from './handlers/token.handler.js';
 import { UserInfoMockHandler } from './handlers/userinfo.handler.js';
 import { UserInfoMockService } from './services/userinfo.service.js';
+import { AuthorizationMock } from './middleware/Authorization.js';
 
 const APIMock = HttpApiBuilder.api(MockApi).pipe(
   Layer.provide(HealthCheckLive),
@@ -34,7 +35,7 @@ const ServerMock = HttpApiBuilder.serve(HttpMiddleware.logger).pipe(
   Layer.provide(TokensMock),
   Layer.provide(UserInfoMockService),
   Layer.provide(IncrementStepIndexMock),
-  // Layer.provide(AuthorizationLive),
+  Layer.provide(AuthorizationMock),
   Layer.provide(HttpApiBuilder.middlewareCors()),
   HttpServer.withLogAddress,
   Layer.provide(NodeHttpServer.layer(createServer, { port: 9443 })),

e2e/mock-api-v2/src/middleware/Authorization.ts

@@ -1,41 +1,43 @@
-// import { Unauthorized } from '@effect/platform/HttpApiError';
-// import { UserInfoTagged } from '../schemas/userinfo/userinfo.schema.js';
-// import { HttpApiMiddleware, HttpApiSecurity } from '@effect/platform';
-// import { Effect, Layer, Redacted } from 'effect';
-//
-// class Authorization extends HttpApiMiddleware.Tag<Authorization>()('Authorization', {
-//   // Define the error schema for unauthorized access
-//   failure: Unauthorized,
-//   // Specify the resource this middleware will provide
-//   provides: UserInfoTagged,
-//   // Add security definitions
-//   security: {
-//     // ┌─── Custom name for the security definition
-//     // ▼
-//     myBearer: HttpApiSecurity.bearer,
-//     // Additional security definitions can be added here.
-//     // They will attempt to be resolved in the order they are defined.
-//   },
-// }) {}
-//
-// const AuthorizationLive = Layer.effect(
-//   Authorization,
-//   Effect.gen(function* () {
-//     yield* Effect.log('creating Authorization middleware');
-//
-//     // Return the security handlers for the middleware
-//     return {
-//       // Define the handler for the Bearer token
-//       // The Bearer token is redacted for security
-//       myBearer: (bearerToken) =>
-//         Effect.gen(function* () {
-//           yield* Effect.log('checking bearer token', Redacted.value(bearerToken));
-//
-//           // Pass through bearer token for future requests?
-//           return bearerToken;
-//         }),
-//     };
-//   }),
-// );
-//
-// export { Authorization, AuthorizationLive };
+import { Unauthorized } from '@effect/platform/HttpApiError';
+import { HttpApiMiddleware, HttpApiSecurity } from '@effect/platform';
+import { Brand, Context, Effect, Layer, Redacted } from 'effect';
+
+type BearerTokenValue = string & Brand.Brand<'BearerToken'>;
+const BearerTokenValue = Brand.nominal<BearerTokenValue>();
+
+// Define a service that holds the bearer token
+class BearerToken extends Context.Tag('BearerToken')<BearerToken, BearerTokenValue>() {}
+
+class Authorization extends HttpApiMiddleware.Tag<Authorization>()('Authorization', {
+  failure: Unauthorized,
+  provides: BearerToken, // Declare that this middleware provides the bearer token
+  security: {
+    myBearer: HttpApiSecurity.bearer,
+  },
+}) {}
+
+const AuthorizationMock = Layer.effect(
+  Authorization,
+  Effect.gen(function* () {
+    yield* Effect.log('creating Authorization middleware');
+
+    return {
+      myBearer: (bearerToken) =>
+        Effect.gen(function* () {
+          const tokenValue = Redacted.value(bearerToken);
+          yield* Effect.log('checking bearer token', tokenValue);
+
+          // Here you could add validation logic if needed
+          // For now, we just pass through any token
+          if (!tokenValue || tokenValue.trim() === '') {
+            return yield* Effect.fail(new Unauthorized());
+          }
+
+          // Return the token value so routes can access it
+          return BearerTokenValue(tokenValue);
+        }),
+    };
+  }),
+);
+
+export { Authorization, AuthorizationMock, BearerToken };

e2e/mock-api-v2/src/schemas/custom-html-template/custom-html-template-request.schema.ts

@@ -5,18 +5,12 @@
  * of the MIT license. See the LICENSE file for details.
  */
 import { Schema } from 'effect';
+import { FormDataResponseUsernamePassword, PingProtectSDKResponse } from './form-data.schema.js';
 
 /**
  * Schemas of what FormData may look like in a Ping Request
  *
  */
-const FormDataResponseUsernamePassword = Schema.Struct({
-  username: Schema.String,
-  password: Schema.String,
-});
-
-const PingProtectSDKResponse = Schema.Struct({ pingprotectsdk: Schema.String });
-
 const PossibleFormDatas = Schema.Struct({
   value: Schema.Union(FormDataResponseUsernamePassword, PingProtectSDKResponse),
 });

e2e/mock-api-v2/src/schemas/custom-html-template/custom-html-template-response.schema.ts

@@ -5,22 +5,10 @@
  * of the MIT license. See the LICENSE file for details.
  */
 import { Schema } from 'effect';
+import { ProtectSDKRequestFormData, UsernamePasswordFormData } from './form-data.schema.js';
 
 const PingOnePathParams = Schema.Struct({ envid: Schema.String, connectionid: Schema.String });
 
-const ProtectSDKRequestFormData = Schema.Struct({
-  value: Schema.Struct({
-    protectsdk: Schema.String,
-  }),
-});
-
-const UsernamePasswordFormData = Schema.Struct({
-  value: Schema.Struct({
-    username: Schema.String,
-    password: Schema.String,
-  }),
-});
-
 const PossibleFormDatas = Schema.Union(ProtectSDKRequestFormData, UsernamePasswordFormData);
 
 const _PingOneCustomHtmlResponseBody = Schema.Struct({

e2e/mock-api-v2/src/schemas/custom-html-template/form-data.schema.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+import { Schema } from 'effect';
+
+const FormDataResponseUsernamePassword = Schema.Struct({
+  username: Schema.String,
+  password: Schema.String,
+});
+
+const PingProtectSDKResponse = Schema.Struct({ pingprotectsdk: Schema.String });
+
+const ProtectSDKRequestFormData = Schema.Struct({
+  value: Schema.Struct({
+    protectsdk: Schema.String,
+  }),
+});
+
+const UsernamePasswordFormData = Schema.Struct({
+  value: Schema.Struct({
+    username: Schema.String,
+    password: Schema.String,
+  }),
+});
+
+export {
+  FormDataResponseUsernamePassword,
+  PingProtectSDKResponse,
+  ProtectSDKRequestFormData,
+  UsernamePasswordFormData,
+};

e2e/mock-api-v2/src/schemas/userinfo/userinfo.schema.ts

@@ -4,7 +4,7 @@
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
  */
-import { Context, Schema } from 'effect';
+import { Schema } from 'effect';
 
 class UserInfoSchema extends Schema.Class<UserInfoSchema>('UserInfo')(
   Schema.Struct({
@@ -20,6 +20,4 @@ class UserInfoSchema extends Schema.Class<UserInfoSchema>('UserInfo')(
   }),
 ) {}
 
-class UserInfoTagged extends Context.Tag('UserInfoTagged')<UserInfoTagged, UserInfoSchema>() {}
-
-export { UserInfoTagged, UserInfoSchema };
+export { UserInfoSchema };