@glinr/theauth 0.4.2

package/dist/types-BiUe9e8u.d.ts

@@ -0,0 +1,426 @@
+import { z } from 'zod';
+
+interface KavachError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type Result<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: KavachError;
+};
+interface McpConfig {
+    /** Enable MCP authorization server */
+    enabled: boolean;
+    /** Enforce auth on all MCP requests */
+    enforceAuth?: boolean;
+    /** Custom scopes supported by this server */
+    scopes?: string[];
+    /** Issuer URL (typically your base URL) */
+    issuer?: string;
+    /** Base URL for MCP endpoints */
+    baseUrl?: string;
+    /** Secret key for signing JWTs (must be >= 32 chars) */
+    signingSecret?: string;
+    /** Access token TTL in seconds (default: 3600) */
+    accessTokenTtl?: number;
+    /** Refresh token TTL in seconds (default: 604800 = 7 days) */
+    refreshTokenTtl?: number;
+    /** Authorization code TTL in seconds (default: 600 = 10 minutes) */
+    codeTtl?: number;
+    /** Allowed resource URIs for RFC 8707 */
+    allowedResources?: string[];
+    /** Login page URL - where users are redirected to authenticate */
+    loginPage?: string;
+    /** Consent page URL - where users approve scopes */
+    consentPage?: string;
+    /**
+     * Clients that are pre-registered at startup.
+     *
+     * These are stored via `storeClient` when the module is created,
+     * so they behave identically to dynamically-registered clients.
+     * Useful for first-party apps, CLIs, or test fixtures that should
+     * always exist without a prior registration call.
+     */
+    preRegisteredClients?: Array<{
+        clientId: string;
+        clientSecret?: string;
+        redirectUris: string[];
+        clientName?: string;
+        scope?: string;
+    }>;
+    /** Custom token claims generator */
+    getAdditionalClaims?: (userId: string, scopes: string[]) => Promise<Record<string, unknown>>;
+    /**
+     * Emit IETF agentic JWT claims on issued access tokens.
+     *
+     * When true, any claims returned by `getAgenticContext` are embedded in
+     * the token payload using the registered draft-goswami-agentic-jwt-00 claim
+     * names. Claims with no available context value are omitted. Off by default.
+     *
+     * @default false
+     */
+    emitAgenticJwtClaims?: boolean;
+    /**
+     * Resolve agentic context for a given user at token issuance time.
+     *
+     * Called only when `emitAgenticJwtClaims` is true. Return only the claims
+     * you can populate; absent fields are skipped rather than fabricated.
+     *
+     * TODO(v3): wire this through kavach.ts so the trust module can provide
+     * trust_tier automatically without requiring the caller to implement it.
+     */
+    getAgenticContext?: (userId: string) => Promise<{
+        agentId?: string;
+        agentType?: "autonomous" | "delegated" | "supervised";
+        trustTier?: "unverified" | "low" | "standard" | "elevated" | "high";
+    }>;
+}
+interface McpServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint: string;
+    jwks_uri?: string;
+    scopes_supported: string[];
+    response_types_supported: string[];
+    response_modes_supported: string[];
+    grant_types_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    code_challenge_methods_supported: string[];
+    service_documentation?: string;
+    revocation_endpoint?: string;
+}
+interface McpProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    jwks_uri?: string;
+    scopes_supported: string[];
+    bearer_methods_supported: string[];
+    resource_signing_alg_values_supported?: string[];
+}
+interface McpClient {
+    clientId: string;
+    clientSecret: string | null;
+    clientName: string | null;
+    clientUri: string | null;
+    logoUri: string | null;
+    redirectUris: string[];
+    grantTypes: string[];
+    responseTypes: string[];
+    tokenEndpointAuthMethod: string;
+    scope: string | null;
+    contacts: string[] | null;
+    tosUri: string | null;
+    policyUri: string | null;
+    softwareId: string | null;
+    softwareVersion: string | null;
+    clientType: "public" | "confidential";
+    disabled: boolean;
+    userId: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface McpClientRegistrationRequest {
+    redirect_uris: string[];
+    token_endpoint_auth_method?: string;
+    grant_types?: string[];
+    response_types?: string[];
+    client_name?: string;
+    client_uri?: string;
+    logo_uri?: string;
+    scope?: string;
+    contacts?: string[];
+    tos_uri?: string;
+    policy_uri?: string;
+    software_id?: string;
+    software_version?: string;
+}
+interface McpClientRegistrationResponse {
+    client_id: string;
+    client_secret?: string;
+    client_id_issued_at: number;
+    client_secret_expires_at?: number;
+    redirect_uris: string[];
+    token_endpoint_auth_method: string;
+    grant_types: string[];
+    response_types: string[];
+    client_name?: string;
+    client_uri?: string;
+    logo_uri?: string;
+    scope?: string;
+    contacts?: string[];
+    tos_uri?: string;
+    policy_uri?: string;
+    software_id?: string;
+    software_version?: string;
+}
+interface McpAuthorizationCode {
+    code: string;
+    clientId: string;
+    userId: string;
+    redirectUri: string;
+    scope: string[];
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+    resource: string | null;
+    expiresAt: Date;
+    createdAt: Date;
+}
+interface McpAuthorizeRequest {
+    response_type: string;
+    client_id: string;
+    redirect_uri: string;
+    scope?: string;
+    state?: string;
+    code_challenge: string;
+    code_challenge_method: string;
+    resource?: string;
+}
+interface McpAuthorizeResult {
+    redirectUri: string;
+    code: string;
+    state: string | null;
+}
+interface McpAccessToken {
+    accessToken: string;
+    refreshToken: string | null;
+    tokenType: "Bearer";
+    expiresIn: number;
+    scope: string[];
+    clientId: string;
+    userId: string;
+    resource: string | null;
+    expiresAt: Date;
+    createdAt: Date;
+}
+interface McpTokenRequest {
+    grant_type: string;
+    code?: string;
+    redirect_uri?: string;
+    client_id?: string;
+    client_secret?: string;
+    code_verifier?: string;
+    refresh_token?: string;
+    resource?: string;
+    scope?: string;
+}
+interface McpTokenResponse {
+    access_token: string;
+    token_type: "Bearer";
+    expires_in: number;
+    refresh_token?: string;
+    scope: string;
+}
+interface McpTokenPayload {
+    sub: string;
+    iss: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    jti: string;
+    scope: string;
+    client_id: string;
+}
+interface McpSession {
+    userId: string;
+    clientId: string;
+    scopes: string[];
+    resource: string | null;
+    expiresAt: Date;
+    tokenId: string;
+}
+interface McpAuthContext {
+    config: Required<Pick<McpConfig, "issuer" | "baseUrl" | "accessTokenTtl" | "refreshTokenTtl" | "codeTtl">> & McpConfig;
+    /** Store a client registration */
+    storeClient: (client: McpClient) => Promise<void>;
+    /** Find a client by ID */
+    findClient: (clientId: string) => Promise<McpClient | null>;
+    /** Store an authorization code */
+    storeAuthorizationCode: (code: McpAuthorizationCode) => Promise<void>;
+    /** Find and consume an authorization code (must delete after finding) */
+    consumeAuthorizationCode: (code: string) => Promise<McpAuthorizationCode | null>;
+    /** Store an access token record */
+    storeToken: (token: McpAccessToken) => Promise<void>;
+    /** Find a token by refresh token value */
+    findTokenByRefreshToken: (refreshToken: string) => Promise<McpAccessToken | null>;
+    /** Revoke a token (by access token value) */
+    revokeToken: (accessToken: string) => Promise<void>;
+    /** Resolve the authenticated user ID (e.g., from session cookie) */
+    resolveUserId: (request: Request) => Promise<string | null>;
+}
+interface ApproveConsentParams {
+    /** Authenticated user who approved the consent */
+    userId: string;
+    clientId: string;
+    /** Space-separated scope string or array */
+    scope: string | string[];
+    state?: string;
+    redirectUri: string;
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+    resource?: string;
+}
+interface McpAuthModule {
+    /** Get OAuth 2.0 Authorization Server Metadata */
+    getMetadata: () => McpServerMetadata;
+    /** Get Protected Resource Metadata (RFC 9728) */
+    getProtectedResourceMetadata: () => McpProtectedResourceMetadata;
+    /** Register a new OAuth client (RFC 7591) */
+    registerClient: (body: McpClientRegistrationRequest) => Promise<Result<McpClientRegistrationResponse>>;
+    /** Handle authorization request */
+    authorize: (request: Request) => Promise<Result<McpAuthorizeResult>>;
+    /**
+     * Issue an authorization code after a user has explicitly approved consent.
+     *
+     * When `config.consentPage` is set, `authorize` redirects to that page
+     * instead of issuing a code directly.  The consent page must call this
+     * method after the user clicks "Allow".
+     */
+    approveConsent: (params: ApproveConsentParams) => Promise<Result<{
+        redirectUri: string;
+    }>>;
+    /** Handle token exchange */
+    token: (request: Request) => Promise<Result<McpTokenResponse>>;
+    /** Validate an access token */
+    validateToken: (token: string, requiredScopes?: string[]) => Promise<Result<McpSession>>;
+    /** Middleware that validates Bearer tokens and returns session */
+    middleware: (request: Request) => Promise<Result<McpSession>>;
+    /** Build a step-up challenge response (403) indicating required scopes */
+    buildStepUpResponse: (options: {
+        currentScopes: string[];
+        requiredScopes: string[];
+        resource?: string;
+    }) => Response;
+    /** Validate token and check scopes. Returns session if valid, or a Response to send back */
+    requireScopes: (request: Request, requiredScopes: string[]) => Promise<{
+        authorized: true;
+        session: McpSession;
+    } | {
+        authorized: false;
+        response: Response;
+    }>;
+}
+declare const McpClientRegistrationSchema: z.ZodObject<{
+    redirect_uris: z.ZodArray<z.ZodString, "many">;
+    token_endpoint_auth_method: z.ZodOptional<z.ZodDefault<z.ZodEnum<["none", "client_secret_basic", "client_secret_post"]>>>;
+    grant_types: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodEnum<["authorization_code", "refresh_token"]>, "many">>>;
+    response_types: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodEnum<["code"]>, "many">>>;
+    client_name: z.ZodOptional<z.ZodString>;
+    client_uri: z.ZodOptional<z.ZodString>;
+    logo_uri: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    contacts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    tos_uri: z.ZodOptional<z.ZodString>;
+    policy_uri: z.ZodOptional<z.ZodString>;
+    software_id: z.ZodOptional<z.ZodString>;
+    software_version: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    redirect_uris: string[];
+    client_name?: string | undefined;
+    client_uri?: string | undefined;
+    grant_types?: ("authorization_code" | "refresh_token")[] | undefined;
+    response_types?: "code"[] | undefined;
+    token_endpoint_auth_method?: "client_secret_basic" | "client_secret_post" | "none" | undefined;
+    logo_uri?: string | undefined;
+    scope?: string | undefined;
+    contacts?: string[] | undefined;
+    tos_uri?: string | undefined;
+    policy_uri?: string | undefined;
+    software_id?: string | undefined;
+    software_version?: string | undefined;
+}, {
+    redirect_uris: string[];
+    client_name?: string | undefined;
+    client_uri?: string | undefined;
+    grant_types?: ("authorization_code" | "refresh_token")[] | undefined;
+    response_types?: "code"[] | undefined;
+    token_endpoint_auth_method?: "client_secret_basic" | "client_secret_post" | "none" | undefined;
+    logo_uri?: string | undefined;
+    scope?: string | undefined;
+    contacts?: string[] | undefined;
+    tos_uri?: string | undefined;
+    policy_uri?: string | undefined;
+    software_id?: string | undefined;
+    software_version?: string | undefined;
+}>;
+declare const McpAuthorizeRequestSchema: z.ZodObject<{
+    response_type: z.ZodLiteral<"code">;
+    client_id: z.ZodString;
+    redirect_uri: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    code_challenge: z.ZodString;
+    code_challenge_method: z.ZodLiteral<"S256">;
+    resource: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    client_id: string;
+    redirect_uri: string;
+    code_challenge: string;
+    code_challenge_method: "S256";
+    response_type: "code";
+    resource?: string | undefined;
+    scope?: string | undefined;
+    state?: string | undefined;
+}, {
+    client_id: string;
+    redirect_uri: string;
+    code_challenge: string;
+    code_challenge_method: "S256";
+    response_type: "code";
+    resource?: string | undefined;
+    scope?: string | undefined;
+    state?: string | undefined;
+}>;
+declare const McpTokenRequestSchema: z.ZodDiscriminatedUnion<"grant_type", [z.ZodObject<{
+    grant_type: z.ZodLiteral<"authorization_code">;
+    code: z.ZodString;
+    redirect_uri: z.ZodString;
+    client_id: z.ZodString;
+    client_secret: z.ZodOptional<z.ZodString>;
+    code_verifier: z.ZodString;
+    resource: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    client_id: string;
+    code: string;
+    redirect_uri: string;
+    grant_type: "authorization_code";
+    code_verifier: string;
+    resource?: string | undefined;
+    client_secret?: string | undefined;
+}, {
+    client_id: string;
+    code: string;
+    redirect_uri: string;
+    grant_type: "authorization_code";
+    code_verifier: string;
+    resource?: string | undefined;
+    client_secret?: string | undefined;
+}>, z.ZodObject<{
+    grant_type: z.ZodLiteral<"refresh_token">;
+    refresh_token: z.ZodString;
+    client_id: z.ZodString;
+    client_secret: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    resource: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    client_id: string;
+    refresh_token: string;
+    grant_type: "refresh_token";
+    resource?: string | undefined;
+    client_secret?: string | undefined;
+    scope?: string | undefined;
+}, {
+    client_id: string;
+    refresh_token: string;
+    grant_type: "refresh_token";
+    resource?: string | undefined;
+    client_secret?: string | undefined;
+    scope?: string | undefined;
+}>]>;
+type McpTokenRequestParsed = z.infer<typeof McpTokenRequestSchema>;
+
+export { type ApproveConsentParams as A, type KavachError as K, type McpAuthContext as M, type Result as R, type McpAuthorizeResult as a, type McpServerMetadata as b, type McpProtectedResourceMetadata as c, type McpClientRegistrationResponse as d, type McpSession as e, type McpConfig as f, type McpAuthModule as g, type McpTokenResponse as h, type McpAccessToken as i, type McpAuthorizationCode as j, type McpAuthorizeRequest as k, McpAuthorizeRequestSchema as l, type McpClient as m, type McpClientRegistrationRequest as n, McpClientRegistrationSchema as o, type McpTokenPayload as p, type McpTokenRequest as q, type McpTokenRequestParsed as r, McpTokenRequestSchema as s };