@ttoss/http-server-mcp 0.14.0 → 0.15.0

package/dist/index.d.cts

@@ -665,8 +665,254 @@ declare namespace Application {
   const HttpError: typeof HttpErrors.HttpError;
 }
 //#endregion
-//#region src/index.d.ts
+//#region src/authServerTypes.d.ts
 type Context$1 = Application.Context;
+/**
+ * OAuth 2.0 client metadata as supplied by a client during Dynamic Client
+ * Registration (RFC 7591). Apps may persist additional fields verbatim.
+ */
+interface OAuthClientMetadata {
+  /** Allowed redirect URIs. At least one is required for the auth-code flow. */
+  redirect_uris: string[];
+  /** Human-readable client name shown on consent screens. */
+  client_name?: string;
+  /** OAuth grant types the client will use. Defaults to auth-code + refresh. */
+  grant_types?: string[];
+  /** OAuth response types the client will use. Defaults to `['code']`. */
+  response_types?: string[];
+  /**
+   * Client authentication method at the token endpoint. `'none'` registers a
+   * public client (no secret issued); anything else registers a confidential
+   * client and a `client_secret` is generated.
+   */
+  token_endpoint_auth_method?: string;
+  /** Space-separated scopes the client may request. */
+  scope?: string;
+  [key: string]: unknown;
+}
+/**
+ * A registered OAuth client as persisted by the app's {@link ClientStore}.
+ */
+interface OAuthClient extends OAuthClientMetadata {
+  /** Unique client identifier issued by the authorization server. */
+  client_id: string;
+  /** Client secret for confidential clients. Absent for public clients. */
+  client_secret?: string;
+  /** Unix timestamp (seconds) when the client was registered. */
+  client_id_issued_at?: number;
+}
+/**
+ * App-provided store for OAuth clients. ttoss owns protocol mechanics; the app
+ * owns persistence (DynamoDB, Postgres, in-memory, …).
+ */
+interface ClientStore {
+  /** Look up a client by its `client_id`. Return `undefined` if unknown. */
+  get: (clientId: string) => Promise<OAuthClient | undefined> | OAuthClient | undefined;
+  /** Persist a newly registered client. */
+  register: (client: OAuthClient) => Promise<void> | void;
+}
+/**
+ * A short-lived authorization code with its bound PKCE challenge and the
+ * details needed to issue tokens when the code is later exchanged.
+ */
+interface StoredAuthorizationCode {
+  /** The opaque authorization code value. */
+  code: string;
+  /** The `client_id` the code was issued to. */
+  clientId: string;
+  /** The redirect URI the code was issued for (must match on exchange). */
+  redirectUri: string;
+  /** The PKCE `code_challenge` (S256) bound to this code. */
+  codeChallenge: string;
+  /** The scopes granted to this code. */
+  scopes: string[];
+  /** The authenticated end-user subject identifier. */
+  subject: string;
+  /** Unix timestamp (milliseconds) after which the code is invalid. */
+  expiresAt: number;
+}
+/**
+ * App-provided store for authorization codes. Codes are single-use and
+ * short-lived; the app decides where to persist them.
+ */
+interface AuthCodeStore {
+  /** Persist an authorization code. */
+  save: (code: StoredAuthorizationCode) => Promise<void> | void;
+  /** Look up an authorization code by its value. */
+  get: (code: string) => Promise<StoredAuthorizationCode | undefined> | StoredAuthorizationCode | undefined;
+  /** Remove an authorization code (called on exchange to enforce single use). */
+  delete: (code: string) => Promise<void> | void;
+}
+/** Tokens returned by the app's {@link McpAuthServerOptions.issueTokens} hook. */
+interface IssuedTokens {
+  /** The access token string (JWT, opaque, …). */
+  accessToken: string;
+  /** Optional refresh token enabling the `refresh_token` grant. */
+  refreshToken?: string;
+  /** Access token lifetime in seconds, surfaced as `expires_in`. */
+  expiresIn?: number;
+  /** Granted scopes as a space-separated string. Defaults to the bound scopes. */
+  scope?: string;
+}
+/** Arguments passed to {@link McpAuthServerOptions.issueTokens}. */
+interface IssueTokensArgs {
+  /** The authenticated end-user subject identifier. */
+  subject: string;
+  /** The scopes granted to the token. */
+  scopes: string[];
+  /** The client the tokens are being issued to. */
+  client: OAuthClient;
+}
+/** The validated authorization request passed to the consent/login hook. */
+interface AuthorizeRequest {
+  /** The requesting `client_id`. */
+  clientId: string;
+  /** The validated redirect URI. */
+  redirectUri: string;
+  /** The requested scopes. */
+  scopes: string[];
+  /** Opaque CSRF/state value to echo back on redirect. */
+  state?: string;
+  /** The PKCE `code_challenge`. */
+  codeChallenge: string;
+  /** The PKCE challenge method (always `'S256'`). */
+  codeChallengeMethod: string;
+}
+/** Arguments passed to {@link McpAuthServerOptions.onAuthorize}. */
+interface OnAuthorizeArgs {
+  /** The Koa context, so the app can read cookies/session or write a response. */
+  ctx: Context$1;
+  /** The resolved client making the request. */
+  client: OAuthClient;
+  /** The validated authorization request. */
+  request: AuthorizeRequest;
+}
+/**
+ * Result of the app's consent/login hook.
+ *
+ * `approved: true` means the end-user is authenticated and has consented — the
+ * authorization server issues a code and redirects. `approved: false` means the
+ * app has taken over the response (e.g. redirected to its own login/consent
+ * page); the authorization server does nothing further.
+ */
+type OnAuthorizeResult = {
+  approved: true;
+  subject: string;
+  scopes?: string[];
+} | {
+  approved: false;
+};
+/** Arguments passed to {@link McpAuthServerOptions.onRefreshToken}. */
+interface OnRefreshTokenArgs {
+  /** The refresh token presented by the client. */
+  refreshToken: string;
+  /** The authenticated client. */
+  client: OAuthClient;
+  /** Scopes requested in the refresh request (may be empty). */
+  scopes: string[];
+}
+/**
+ * Result of validating a refresh token. Return `undefined` to reject the token.
+ */
+type OnRefreshTokenResult = {
+  subject: string;
+  scopes: string[];
+} | undefined;
+/** Configuration for {@link createMcpAuthServer}. */
+interface McpAuthServerOptions {
+  /** The authorization server's issuer identifier (its base URL). */
+  issuer: string;
+  /** App-provided store for dynamic clients. */
+  clientStore: ClientStore;
+  /** App-provided store for short-lived authorization codes. */
+  authCodeStore: AuthCodeStore;
+  /**
+   * App-owned token minting. ttoss never sees the user model or signing keys —
+   * it hands you the subject/scopes/client and you return the tokens.
+   */
+  issueTokens: (args: IssueTokensArgs) => Promise<IssuedTokens> | IssuedTokens;
+  /**
+   * App-owned login/consent. Called on every `/authorize` request; return the
+   * authenticated subject to approve, or take over the response to show your
+   * own login/consent UI and return `{ approved: false }`.
+   */
+  onAuthorize: (args: OnAuthorizeArgs) => Promise<OnAuthorizeResult> | OnAuthorizeResult;
+  /**
+   * App-owned refresh-token validation. Required to support the `refresh_token`
+   * grant; when omitted, refresh requests get `unsupported_grant_type`.
+   */
+  onRefreshToken?: (args: OnRefreshTokenArgs) => Promise<OnRefreshTokenResult> | OnRefreshTokenResult;
+  /** Scopes advertised in discovery metadata (`scopes_supported`). */
+  scopesSupported?: string[];
+  /**
+   * When set, also serves `/.well-known/oauth-protected-resource` (RFC 9728)
+   * pairing this resource URL with the issuer as its authorization server.
+   */
+  resource?: string;
+  /**
+   * Authorization code lifetime in seconds.
+   * @default 600
+   */
+  authorizationCodeTtl?: number;
+  /** Override the default endpoint paths. */
+  endpoints?: {
+    /** @default '/authorize' */authorize?: string; /** @default '/token' */
+    token?: string; /** @default '/register' */
+    register?: string;
+  };
+}
+//#endregion
+//#region src/authServer.d.ts
+/**
+ * Creates transport-agnostic OAuth 2.1 Authorization Server primitives for MCP.
+ *
+ * Mounts the authorization endpoint (`/authorize`, PKCE S256 required), token
+ * endpoint (`/token`, `authorization_code` + `refresh_token` grants), Dynamic
+ * Client Registration (`/register`, RFC 7591), and AS metadata discovery
+ * (`/.well-known/oauth-authorization-server`, RFC 8414). When `resource` is
+ * set, it also serves the protected-resource metadata (RFC 9728).
+ *
+ * ttoss owns only the protocol mechanics — the app supplies its own stores,
+ * token signing/verification, and login/consent UI through the option hooks, so
+ * the user model, JWT/IAM, and authentication never leave the consuming app.
+ *
+ * @param options - Authorization server configuration and pluggable hooks.
+ * @returns A Koa `Router` exposing `routes()` / `allowedMethods()`.
+ *
+ * @example
+ * ```typescript
+ * import { App, bodyParser } from '@ttoss/http-server';
+ * import { createMcpAuthServer } from '@ttoss/http-server-mcp';
+ *
+ * const authServer = createMcpAuthServer({
+ *   issuer: 'https://api.soat.dev',
+ *   clientStore,
+ *   authCodeStore,
+ *   issueTokens: async ({ subject, scopes }) => ({
+ *     accessToken: signJwt({ sub: subject, scope: scopes.join(' ') }),
+ *     refreshToken: createRefreshToken(subject),
+ *     expiresIn: 3600,
+ *   }),
+ *   onAuthorize: async ({ ctx }) => {
+ *     const session = await getSession(ctx);
+ *     if (!session) {
+ *       ctx.redirect('/login');
+ *       return { approved: false };
+ *     }
+ *     return { approved: true, subject: session.userId };
+ *   },
+ *   scopesSupported: ['mcp:access'],
+ * });
+ *
+ * const app = new App();
+ * app.use(bodyParser());
+ * app.use(authServer.routes());
+ * ```
+ */
+declare const createMcpAuthServer: (options: McpAuthServerOptions) => Router;
+//#endregion
+//#region src/index.d.ts
+type Context$2 = Application.Context;
 /**
  * Options for a single `apiCall` request.
  */
@@ -858,7 +1104,7 @@ interface McpRouterOptions {
    * getApiHeaders: () => ({ 'x-internal-key': process.env.INTERNAL_API_KEY! })
    * ```
    */
-  getApiHeaders?: (ctx: Context$1) => Record<string, string>;
+  getApiHeaders?: (ctx: Context$2) => Record<string, string>;
   /**
    * OAuth / JWT authentication configuration for the MCP endpoint.
    *
@@ -1066,4 +1312,4 @@ declare const createProtectedResourceMetadataMiddleware: (args: {
   authorizationServers: string[];
 }) => Application.Middleware;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, apiCall, checkScopes, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };
+export { ApiCallOptions, AuthCodeStore, AuthorizeRequest, ClientStore, CognitoUserPoolConfig, Context$1 as Context, IssueTokensArgs, IssuedTokens, JsonObjectSchema, McpAuthOptions, McpAuthServerOptions, McpRouterOptions, McpServer, OAuthClient, OAuthClientMetadata, OnAuthorizeArgs, OnAuthorizeResult, OnRefreshTokenArgs, OnRefreshTokenResult, RegisterToolFromSchemaParams, StoredAuthorizationCode, apiCall, checkScopes, createMcpAuthServer, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };

package/dist/index.d.mts

@@ -665,8 +665,254 @@ declare namespace Application {
   const HttpError: typeof HttpErrors.HttpError;
 }
 //#endregion
-//#region src/index.d.ts
+//#region src/authServerTypes.d.ts
 type Context$1 = Application.Context;
+/**
+ * OAuth 2.0 client metadata as supplied by a client during Dynamic Client
+ * Registration (RFC 7591). Apps may persist additional fields verbatim.
+ */
+interface OAuthClientMetadata {
+  /** Allowed redirect URIs. At least one is required for the auth-code flow. */
+  redirect_uris: string[];
+  /** Human-readable client name shown on consent screens. */
+  client_name?: string;
+  /** OAuth grant types the client will use. Defaults to auth-code + refresh. */
+  grant_types?: string[];
+  /** OAuth response types the client will use. Defaults to `['code']`. */
+  response_types?: string[];
+  /**
+   * Client authentication method at the token endpoint. `'none'` registers a
+   * public client (no secret issued); anything else registers a confidential
+   * client and a `client_secret` is generated.
+   */
+  token_endpoint_auth_method?: string;
+  /** Space-separated scopes the client may request. */
+  scope?: string;
+  [key: string]: unknown;
+}
+/**
+ * A registered OAuth client as persisted by the app's {@link ClientStore}.
+ */
+interface OAuthClient extends OAuthClientMetadata {
+  /** Unique client identifier issued by the authorization server. */
+  client_id: string;
+  /** Client secret for confidential clients. Absent for public clients. */
+  client_secret?: string;
+  /** Unix timestamp (seconds) when the client was registered. */
+  client_id_issued_at?: number;
+}
+/**
+ * App-provided store for OAuth clients. ttoss owns protocol mechanics; the app
+ * owns persistence (DynamoDB, Postgres, in-memory, …).
+ */
+interface ClientStore {
+  /** Look up a client by its `client_id`. Return `undefined` if unknown. */
+  get: (clientId: string) => Promise<OAuthClient | undefined> | OAuthClient | undefined;
+  /** Persist a newly registered client. */
+  register: (client: OAuthClient) => Promise<void> | void;
+}
+/**
+ * A short-lived authorization code with its bound PKCE challenge and the
+ * details needed to issue tokens when the code is later exchanged.
+ */
+interface StoredAuthorizationCode {
+  /** The opaque authorization code value. */
+  code: string;
+  /** The `client_id` the code was issued to. */
+  clientId: string;
+  /** The redirect URI the code was issued for (must match on exchange). */
+  redirectUri: string;
+  /** The PKCE `code_challenge` (S256) bound to this code. */
+  codeChallenge: string;
+  /** The scopes granted to this code. */
+  scopes: string[];
+  /** The authenticated end-user subject identifier. */
+  subject: string;
+  /** Unix timestamp (milliseconds) after which the code is invalid. */
+  expiresAt: number;
+}
+/**
+ * App-provided store for authorization codes. Codes are single-use and
+ * short-lived; the app decides where to persist them.
+ */
+interface AuthCodeStore {
+  /** Persist an authorization code. */
+  save: (code: StoredAuthorizationCode) => Promise<void> | void;
+  /** Look up an authorization code by its value. */
+  get: (code: string) => Promise<StoredAuthorizationCode | undefined> | StoredAuthorizationCode | undefined;
+  /** Remove an authorization code (called on exchange to enforce single use). */
+  delete: (code: string) => Promise<void> | void;
+}
+/** Tokens returned by the app's {@link McpAuthServerOptions.issueTokens} hook. */
+interface IssuedTokens {
+  /** The access token string (JWT, opaque, …). */
+  accessToken: string;
+  /** Optional refresh token enabling the `refresh_token` grant. */
+  refreshToken?: string;
+  /** Access token lifetime in seconds, surfaced as `expires_in`. */
+  expiresIn?: number;
+  /** Granted scopes as a space-separated string. Defaults to the bound scopes. */
+  scope?: string;
+}
+/** Arguments passed to {@link McpAuthServerOptions.issueTokens}. */
+interface IssueTokensArgs {
+  /** The authenticated end-user subject identifier. */
+  subject: string;
+  /** The scopes granted to the token. */
+  scopes: string[];
+  /** The client the tokens are being issued to. */
+  client: OAuthClient;
+}
+/** The validated authorization request passed to the consent/login hook. */
+interface AuthorizeRequest {
+  /** The requesting `client_id`. */
+  clientId: string;
+  /** The validated redirect URI. */
+  redirectUri: string;
+  /** The requested scopes. */
+  scopes: string[];
+  /** Opaque CSRF/state value to echo back on redirect. */
+  state?: string;
+  /** The PKCE `code_challenge`. */
+  codeChallenge: string;
+  /** The PKCE challenge method (always `'S256'`). */
+  codeChallengeMethod: string;
+}
+/** Arguments passed to {@link McpAuthServerOptions.onAuthorize}. */
+interface OnAuthorizeArgs {
+  /** The Koa context, so the app can read cookies/session or write a response. */
+  ctx: Context$1;
+  /** The resolved client making the request. */
+  client: OAuthClient;
+  /** The validated authorization request. */
+  request: AuthorizeRequest;
+}
+/**
+ * Result of the app's consent/login hook.
+ *
+ * `approved: true` means the end-user is authenticated and has consented — the
+ * authorization server issues a code and redirects. `approved: false` means the
+ * app has taken over the response (e.g. redirected to its own login/consent
+ * page); the authorization server does nothing further.
+ */
+type OnAuthorizeResult = {
+  approved: true;
+  subject: string;
+  scopes?: string[];
+} | {
+  approved: false;
+};
+/** Arguments passed to {@link McpAuthServerOptions.onRefreshToken}. */
+interface OnRefreshTokenArgs {
+  /** The refresh token presented by the client. */
+  refreshToken: string;
+  /** The authenticated client. */
+  client: OAuthClient;
+  /** Scopes requested in the refresh request (may be empty). */
+  scopes: string[];
+}
+/**
+ * Result of validating a refresh token. Return `undefined` to reject the token.
+ */
+type OnRefreshTokenResult = {
+  subject: string;
+  scopes: string[];
+} | undefined;
+/** Configuration for {@link createMcpAuthServer}. */
+interface McpAuthServerOptions {
+  /** The authorization server's issuer identifier (its base URL). */
+  issuer: string;
+  /** App-provided store for dynamic clients. */
+  clientStore: ClientStore;
+  /** App-provided store for short-lived authorization codes. */
+  authCodeStore: AuthCodeStore;
+  /**
+   * App-owned token minting. ttoss never sees the user model or signing keys —
+   * it hands you the subject/scopes/client and you return the tokens.
+   */
+  issueTokens: (args: IssueTokensArgs) => Promise<IssuedTokens> | IssuedTokens;
+  /**
+   * App-owned login/consent. Called on every `/authorize` request; return the
+   * authenticated subject to approve, or take over the response to show your
+   * own login/consent UI and return `{ approved: false }`.
+   */
+  onAuthorize: (args: OnAuthorizeArgs) => Promise<OnAuthorizeResult> | OnAuthorizeResult;
+  /**
+   * App-owned refresh-token validation. Required to support the `refresh_token`
+   * grant; when omitted, refresh requests get `unsupported_grant_type`.
+   */
+  onRefreshToken?: (args: OnRefreshTokenArgs) => Promise<OnRefreshTokenResult> | OnRefreshTokenResult;
+  /** Scopes advertised in discovery metadata (`scopes_supported`). */
+  scopesSupported?: string[];
+  /**
+   * When set, also serves `/.well-known/oauth-protected-resource` (RFC 9728)
+   * pairing this resource URL with the issuer as its authorization server.
+   */
+  resource?: string;
+  /**
+   * Authorization code lifetime in seconds.
+   * @default 600
+   */
+  authorizationCodeTtl?: number;
+  /** Override the default endpoint paths. */
+  endpoints?: {
+    /** @default '/authorize' */authorize?: string; /** @default '/token' */
+    token?: string; /** @default '/register' */
+    register?: string;
+  };
+}
+//#endregion
+//#region src/authServer.d.ts
+/**
+ * Creates transport-agnostic OAuth 2.1 Authorization Server primitives for MCP.
+ *
+ * Mounts the authorization endpoint (`/authorize`, PKCE S256 required), token
+ * endpoint (`/token`, `authorization_code` + `refresh_token` grants), Dynamic
+ * Client Registration (`/register`, RFC 7591), and AS metadata discovery
+ * (`/.well-known/oauth-authorization-server`, RFC 8414). When `resource` is
+ * set, it also serves the protected-resource metadata (RFC 9728).
+ *
+ * ttoss owns only the protocol mechanics — the app supplies its own stores,
+ * token signing/verification, and login/consent UI through the option hooks, so
+ * the user model, JWT/IAM, and authentication never leave the consuming app.
+ *
+ * @param options - Authorization server configuration and pluggable hooks.
+ * @returns A Koa `Router` exposing `routes()` / `allowedMethods()`.
+ *
+ * @example
+ * ```typescript
+ * import { App, bodyParser } from '@ttoss/http-server';
+ * import { createMcpAuthServer } from '@ttoss/http-server-mcp';
+ *
+ * const authServer = createMcpAuthServer({
+ *   issuer: 'https://api.soat.dev',
+ *   clientStore,
+ *   authCodeStore,
+ *   issueTokens: async ({ subject, scopes }) => ({
+ *     accessToken: signJwt({ sub: subject, scope: scopes.join(' ') }),
+ *     refreshToken: createRefreshToken(subject),
+ *     expiresIn: 3600,
+ *   }),
+ *   onAuthorize: async ({ ctx }) => {
+ *     const session = await getSession(ctx);
+ *     if (!session) {
+ *       ctx.redirect('/login');
+ *       return { approved: false };
+ *     }
+ *     return { approved: true, subject: session.userId };
+ *   },
+ *   scopesSupported: ['mcp:access'],
+ * });
+ *
+ * const app = new App();
+ * app.use(bodyParser());
+ * app.use(authServer.routes());
+ * ```
+ */
+declare const createMcpAuthServer: (options: McpAuthServerOptions) => Router;
+//#endregion
+//#region src/index.d.ts
+type Context$2 = Application.Context;
 /**
  * Options for a single `apiCall` request.
  */
@@ -858,7 +1104,7 @@ interface McpRouterOptions {
    * getApiHeaders: () => ({ 'x-internal-key': process.env.INTERNAL_API_KEY! })
    * ```
    */
-  getApiHeaders?: (ctx: Context$1) => Record<string, string>;
+  getApiHeaders?: (ctx: Context$2) => Record<string, string>;
   /**
    * OAuth / JWT authentication configuration for the MCP endpoint.
    *
@@ -1066,4 +1312,4 @@ declare const createProtectedResourceMetadataMiddleware: (args: {
   authorizationServers: string[];
 }) => Application.Middleware;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, apiCall, checkScopes, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };
+export { ApiCallOptions, AuthCodeStore, AuthorizeRequest, ClientStore, CognitoUserPoolConfig, Context$1 as Context, IssueTokensArgs, IssuedTokens, JsonObjectSchema, McpAuthOptions, McpAuthServerOptions, McpRouterOptions, McpServer, OAuthClient, OAuthClientMetadata, OnAuthorizeArgs, OnAuthorizeResult, OnRefreshTokenArgs, OnRefreshTokenResult, RegisterToolFromSchemaParams, StoredAuthorizationCode, apiCall, checkScopes, createMcpAuthServer, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };