actor-gate 0.1.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "actor-gate",
+  "version": "0.1.0",
+  "description": "Schema-agnostic Next.js auth library for direct and MCP authentication flows.",
+  "type": "module",
+  "private": false,
+  "exports": {
+    ".": "./src/index.js",
+    "./core": "./src/core/index.js",
+    "./config": "./src/config/index.js",
+    "./express": "./src/express/index.js",
+    "./next": "./src/next/index.js",
+    "./mcp": "./src/mcp/index.js",
+    "./testing": "./src/testing/index.js"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config/base-config.d.ts

@@ -0,0 +1,17 @@
+import type { AuthActor } from '../core/types/auth-contract';
+export type BaseAuthConfigInput<TActors extends readonly [AuthActor, ...AuthActor[]], TClientSession> = {
+    actors: TActors;
+    session: {
+        parseClientSession: (input: unknown) => TClientSession;
+        isExpired: (session: TClientSession, nowUnix: number) => boolean;
+    };
+};
+export type BaseAuthConfig<TActors extends readonly [AuthActor, ...AuthActor[]], TClientSession> = {
+    kind: 'base';
+    actors: TActors;
+    actorSet: ReadonlySet<TActors[number]>;
+    session: BaseAuthConfigInput<TActors, TClientSession>['session'];
+};
+export declare function defineBaseAuthConfig<TActors extends readonly [AuthActor, ...AuthActor[]], TClientSession>(input: BaseAuthConfigInput<TActors, TClientSession>): BaseAuthConfig<TActors, TClientSession>;
+export type InferAuthActor<TConfig> = TConfig extends BaseAuthConfig<infer TActors, unknown> ? TActors[number] : never;
+export type InferClientSession<TConfig> = TConfig extends BaseAuthConfig<readonly [AuthActor, ...AuthActor[]], infer T> ? T : never;

package/src/config/base-config.js

@@ -0,0 +1,33 @@
+function assertNonEmptyActor(value) {
+    if (value.trim().length === 0) {
+        throw new Error('actors cannot contain empty values.');
+    }
+}
+function normalizeActors(actors) {
+    if (actors.length === 0) {
+        throw new Error('actors must contain at least one actor.');
+    }
+    const normalized = [];
+    const seen = new Set();
+    for (const actor of actors) {
+        assertNonEmptyActor(actor);
+        if (seen.has(actor)) {
+            throw new Error(`actors cannot contain duplicates: "${actor}".`);
+        }
+        seen.add(actor);
+        normalized.push(actor);
+    }
+    if (!seen.has('USER')) {
+        throw new Error('actors must include the reserved USER actor.');
+    }
+    return normalized;
+}
+export function defineBaseAuthConfig(input) {
+    const actors = normalizeActors(input.actors);
+    return {
+        kind: 'base',
+        actors: [...actors],
+        actorSet: new Set(actors),
+        session: input.session,
+    };
+}

package/src/config/index.d.ts

@@ -0,0 +1,5 @@
+export { defineBaseAuthConfig, type BaseAuthConfig, type BaseAuthConfigInput, type InferAuthActor, type InferClientSession, } from './base-config';
+export { defineNextJsPublicAuthConfig, type NextJsAuthEndpointSet, type NextJsPublicAuthConfig, type NextJsPublicAuthPaths, toSerializableNextJsPublicAuthConfig, type SerializableNextJsPublicAuthConfig, } from './nextjs-public-config';
+export { defineNextJsServerAuthConfig, type DefineNextJsServerAuthConfigInput, type NextJsServerAuthConfig, type NextJsServerCookieConfig, type NextJsServerCsrfConfig, } from './nextjs-server-config';
+export { defineReactAuthConfig, type DefineReactAuthConfigInput, type ReactAuthConfig, } from './react-config';
+export { ReactAuthClient, createReactAuthClient, type AuthClientStorage, type CreateReactAuthClientInput, } from './react-client';

package/src/config/index.js

@@ -0,0 +1,5 @@
+export { defineBaseAuthConfig, } from './base-config';
+export { defineNextJsPublicAuthConfig, toSerializableNextJsPublicAuthConfig, } from './nextjs-public-config';
+export { defineNextJsServerAuthConfig, } from './nextjs-server-config';
+export { defineReactAuthConfig, } from './react-config';
+export { ReactAuthClient, createReactAuthClient, } from './react-client';

package/src/config/nextjs-public-config.d.ts

@@ -0,0 +1,46 @@
+import type { AuthActor } from '../core/types/auth-contract';
+import { type AuthRouteAction } from '../next/shared/auth-routes';
+import { type BuildAuthRewritesOptions, type NextRewrite } from '../next/rewrites';
+import type { BaseAuthConfig } from './base-config';
+export type NextJsAuthEndpointSet = {
+    refresh: string;
+    logout: string;
+    loginStart: string;
+    loginFinish: string;
+    authorize: string;
+    authorizeConfirm: string;
+    token: string;
+    wellKnownOauthProtectedResource: string;
+    wellKnownOauthAuthorizationServer: string;
+    wellKnownOpenidConfiguration: string;
+    mcp: string;
+};
+export type NextJsPublicAuthPaths = {
+    authBasePath: string;
+    mcpPath: string;
+    authorizePath: string;
+    tokenPath: string;
+    wellKnownBase: string;
+};
+export type NextJsPublicAuthConfig<TActors extends readonly [AuthActor, ...AuthActor[]], TClientSession> = {
+    kind: 'nextjs_public';
+    base: BaseAuthConfig<TActors, TClientSession>;
+    paths: NextJsPublicAuthPaths;
+    endpoints: {
+        internal: NextJsAuthEndpointSet;
+        public: NextJsAuthEndpointSet;
+    };
+    rewrites: readonly NextRewrite[];
+    getAuthRoutePath: (action: AuthRouteAction) => string;
+};
+export type SerializableNextJsPublicAuthConfig = {
+    kind: 'nextjs_public_serializable';
+    paths: NextJsPublicAuthPaths;
+    endpoints: {
+        internal: NextJsAuthEndpointSet;
+        public: NextJsAuthEndpointSet;
+    };
+    rewrites: readonly NextRewrite[];
+};
+export declare function defineNextJsPublicAuthConfig<TActors extends readonly [AuthActor, ...AuthActor[]], TClientSession>(base: BaseAuthConfig<TActors, TClientSession>, options?: BuildAuthRewritesOptions): NextJsPublicAuthConfig<TActors, TClientSession>;
+export declare function toSerializableNextJsPublicAuthConfig<TActors extends readonly [AuthActor, ...AuthActor[]], TClientSession>(config: NextJsPublicAuthConfig<TActors, TClientSession>): SerializableNextJsPublicAuthConfig;

package/src/config/nextjs-public-config.js

@@ -0,0 +1,89 @@
+import { buildAuthRoutePath, } from '../next/shared/auth-routes';
+import { buildAuthRewrites, } from '../next/rewrites';
+function normalizePath(path) {
+    const trimmed = path.trim();
+    if (trimmed.length === 0) {
+        throw new Error('Path must be a non-empty string.');
+    }
+    const withLeadingSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    if (withLeadingSlash.length === 1) {
+        return withLeadingSlash;
+    }
+    return withLeadingSlash.endsWith('/')
+        ? withLeadingSlash.slice(0, -1)
+        : withLeadingSlash;
+}
+function joinPath(basePath, suffix) {
+    const normalizedBase = normalizePath(basePath);
+    const cleanedSuffix = suffix.replace(/^\/+/, '').replace(/\/+$/, '');
+    if (normalizedBase === '/') {
+        return `/${cleanedSuffix}`;
+    }
+    return `${normalizedBase}/${cleanedSuffix}`;
+}
+function resolvePaths(options) {
+    return {
+        authBasePath: normalizePath(options?.authBasePath ?? '/api/auth'),
+        mcpPath: normalizePath(options?.mcpPath ?? '/api/mcp'),
+        authorizePath: normalizePath(options?.authorizePath ?? '/api/authorize'),
+        tokenPath: normalizePath(options?.tokenPath ?? '/api/token'),
+        wellKnownBase: normalizePath(options?.wellKnownBase ?? '/api/well-known'),
+    };
+}
+function buildInternalEndpoints(authBasePath) {
+    return {
+        refresh: buildAuthRoutePath('refresh', { authBasePath }),
+        logout: buildAuthRoutePath('logout', { authBasePath }),
+        loginStart: buildAuthRoutePath('login_start', { authBasePath }),
+        loginFinish: buildAuthRoutePath('login_finish', { authBasePath }),
+        authorize: buildAuthRoutePath('authorize', { authBasePath }),
+        authorizeConfirm: buildAuthRoutePath('authorize_confirm', { authBasePath }),
+        token: buildAuthRoutePath('token', { authBasePath }),
+        wellKnownOauthProtectedResource: buildAuthRoutePath('well_known_oauth_protected_resource', { authBasePath }),
+        wellKnownOauthAuthorizationServer: buildAuthRoutePath('well_known_oauth_authorization_server', { authBasePath }),
+        wellKnownOpenidConfiguration: buildAuthRoutePath('well_known_openid_configuration', { authBasePath }),
+        mcp: joinPath(authBasePath, 'mcp'),
+    };
+}
+function buildPublicEndpoints(paths) {
+    return {
+        refresh: buildAuthRoutePath('refresh'),
+        logout: buildAuthRoutePath('logout'),
+        loginStart: buildAuthRoutePath('login_start'),
+        loginFinish: buildAuthRoutePath('login_finish'),
+        authorize: paths.authorizePath,
+        authorizeConfirm: joinPath(paths.authorizePath, 'confirm'),
+        token: paths.tokenPath,
+        wellKnownOauthProtectedResource: joinPath(paths.wellKnownBase, 'oauth-protected-resource'),
+        wellKnownOauthAuthorizationServer: joinPath(paths.wellKnownBase, 'oauth-authorization-server'),
+        wellKnownOpenidConfiguration: joinPath(paths.wellKnownBase, 'openid-configuration'),
+        mcp: paths.mcpPath,
+    };
+}
+export function defineNextJsPublicAuthConfig(base, options) {
+    const paths = resolvePaths(options);
+    const rewrites = buildAuthRewrites(paths);
+    const internalEndpoints = buildInternalEndpoints(paths.authBasePath);
+    return {
+        kind: 'nextjs_public',
+        base,
+        paths,
+        endpoints: {
+            internal: internalEndpoints,
+            public: buildPublicEndpoints(paths),
+        },
+        rewrites,
+        getAuthRoutePath: action => buildAuthRoutePath(action, paths),
+    };
+}
+export function toSerializableNextJsPublicAuthConfig(config) {
+    return {
+        kind: 'nextjs_public_serializable',
+        paths: { ...config.paths },
+        endpoints: {
+            internal: { ...config.endpoints.internal },
+            public: { ...config.endpoints.public },
+        },
+        rewrites: config.rewrites.map(rewrite => ({ ...rewrite })),
+    };
+}

package/src/config/nextjs-server-config.d.ts

@@ -0,0 +1,32 @@
+import type { AuthActor } from '../core/types/auth-contract';
+import type { NextJsPublicAuthConfig } from './nextjs-public-config';
+export type NextJsServerCookieConfig = {
+    accessTokenCookieName?: string;
+    refreshTokenCookieName?: string;
+    path?: string;
+    sameSite?: 'lax' | 'strict' | 'none';
+    secure?: boolean;
+    secureInProduction?: boolean;
+};
+export type NextJsServerCsrfConfig = {
+    enabled?: boolean;
+    headerName?: string;
+    cookieName?: string;
+    bodyFieldName?: string;
+    ignorePaths?: readonly string[];
+};
+export type DefineNextJsServerAuthConfigInput<TServices, TAdapters extends Record<string, unknown> = Record<string, never>> = {
+    services: TServices;
+    adapters?: TAdapters;
+    cookies?: NextJsServerCookieConfig;
+    csrf?: NextJsServerCsrfConfig;
+};
+export type NextJsServerAuthConfig<TActors extends readonly [AuthActor, ...AuthActor[]], TClientSession, TServices, TAdapters extends Record<string, unknown> = Record<string, never>> = {
+    kind: 'nextjs_server';
+    publicConfig: NextJsPublicAuthConfig<TActors, TClientSession>;
+    services: TServices;
+    adapters?: TAdapters;
+    cookies?: NextJsServerCookieConfig;
+    csrf?: NextJsServerCsrfConfig;
+};
+export declare function defineNextJsServerAuthConfig<TActors extends readonly [AuthActor, ...AuthActor[]], TClientSession, TServices, TAdapters extends Record<string, unknown> = Record<string, never>>(publicConfig: NextJsPublicAuthConfig<TActors, TClientSession>, input: DefineNextJsServerAuthConfigInput<TServices, TAdapters>): NextJsServerAuthConfig<TActors, TClientSession, TServices, TAdapters>;

package/src/config/nextjs-server-config.js

@@ -0,0 +1,10 @@
+export function defineNextJsServerAuthConfig(publicConfig, input) {
+    return {
+        kind: 'nextjs_server',
+        publicConfig,
+        services: input.services,
+        ...(input.adapters === undefined ? {} : { adapters: input.adapters }),
+        ...(input.cookies === undefined ? {} : { cookies: input.cookies }),
+        ...(input.csrf === undefined ? {} : { csrf: input.csrf }),
+    };
+}

package/src/config/react-client.d.ts

@@ -0,0 +1,23 @@
+import type { AuthActor } from '../core/types/auth-contract';
+import type { ReactAuthConfig } from './react-config';
+export type AuthClientStorage = {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+};
+export type CreateReactAuthClientInput = {
+    storage?: AuthClientStorage;
+};
+export declare class ReactAuthClient<TActors extends readonly [AuthActor, ...AuthActor[]], TClientSession> {
+    private readonly config;
+    private readonly storage;
+    constructor(config: ReactAuthConfig<TActors, TClientSession>, input?: CreateReactAuthClientInput);
+    get sessionStorageKey(): string;
+    get endpoints(): ReactAuthConfig<TActors, TClientSession>['endpoints'];
+    parseClientSession(input: unknown): TClientSession;
+    isSessionExpired(session: TClientSession): boolean;
+    readStoredSession(): TClientSession | null;
+    writeStoredSession(session: TClientSession | null): void;
+    clearStoredSession(): void;
+}
+export declare function createReactAuthClient<TActors extends readonly [AuthActor, ...AuthActor[]], TClientSession>(config: ReactAuthConfig<TActors, TClientSession>, input?: CreateReactAuthClientInput): ReactAuthClient<TActors, TClientSession>;

package/src/config/react-client.js

@@ -0,0 +1,69 @@
+export class ReactAuthClient {
+    config;
+    storage;
+    constructor(config, input = {}) {
+        this.config = config;
+        this.storage = input.storage;
+    }
+    get sessionStorageKey() {
+        return this.config.sessionStorageKey;
+    }
+    get endpoints() {
+        return this.config.endpoints;
+    }
+    parseClientSession(input) {
+        return this.config.parseClientSession(input);
+    }
+    isSessionExpired(session) {
+        return this.config.isSessionExpired(session);
+    }
+    readStoredSession() {
+        if (!this.storage) {
+            return null;
+        }
+        const raw = this.storage.getItem(this.config.sessionStorageKey);
+        if (!raw) {
+            return null;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.storage.removeItem(this.config.sessionStorageKey);
+            return null;
+        }
+        let session;
+        try {
+            session = this.config.parseClientSession(parsed);
+        }
+        catch {
+            this.storage.removeItem(this.config.sessionStorageKey);
+            return null;
+        }
+        if (this.config.isSessionExpired(session)) {
+            this.storage.removeItem(this.config.sessionStorageKey);
+            return null;
+        }
+        return session;
+    }
+    writeStoredSession(session) {
+        if (!this.storage) {
+            return;
+        }
+        if (session === null) {
+            this.storage.removeItem(this.config.sessionStorageKey);
+            return;
+        }
+        this.storage.setItem(this.config.sessionStorageKey, JSON.stringify(session));
+    }
+    clearStoredSession() {
+        if (!this.storage) {
+            return;
+        }
+        this.storage.removeItem(this.config.sessionStorageKey);
+    }
+}
+export function createReactAuthClient(config, input) {
+    return new ReactAuthClient(config, input);
+}

package/src/config/react-config.d.ts

@@ -0,0 +1,18 @@
+import type { AuthActor } from '../core/types/auth-contract';
+import type { NextJsAuthEndpointSet, NextJsPublicAuthConfig } from './nextjs-public-config';
+export type DefineReactAuthConfigInput = {
+    sessionStorageKey?: string;
+    queryKey?: readonly [string, ...string[]];
+    nowUnix?: () => number;
+    useInternalEndpoints?: boolean;
+};
+export type ReactAuthConfig<TActors extends readonly [AuthActor, ...AuthActor[]], TClientSession> = {
+    kind: 'react';
+    publicConfig: NextJsPublicAuthConfig<TActors, TClientSession>;
+    sessionStorageKey: string;
+    queryKey: readonly [string, ...string[]];
+    endpoints: Pick<NextJsAuthEndpointSet, 'refresh' | 'logout' | 'loginStart' | 'loginFinish'>;
+    parseClientSession: (input: unknown) => TClientSession;
+    isSessionExpired: (session: TClientSession) => boolean;
+};
+export declare function defineReactAuthConfig<TActors extends readonly [AuthActor, ...AuthActor[]], TClientSession>(publicConfig: NextJsPublicAuthConfig<TActors, TClientSession>, input?: DefineReactAuthConfigInput): ReactAuthConfig<TActors, TClientSession>;

package/src/config/react-config.js

@@ -0,0 +1,38 @@
+function resolveNonEmptyString(value, fieldName) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error(`${fieldName} must be a non-empty string.`);
+    }
+    return trimmed;
+}
+function resolveSessionStorageKey(key) {
+    return resolveNonEmptyString(key ?? 'direct-user-auth-session', 'sessionStorageKey');
+}
+function resolveQueryKey(queryKey) {
+    const resolved = queryKey ?? ['auth', 'session'];
+    if (resolved.length === 0) {
+        throw new Error('queryKey must contain at least one segment.');
+    }
+    const normalized = resolved.map(segment => resolveNonEmptyString(segment, 'queryKey segment'));
+    return normalized;
+}
+export function defineReactAuthConfig(publicConfig, input = {}) {
+    const nowUnix = input.nowUnix ?? (() => Math.floor(Date.now() / 1000));
+    const endpointSource = input.useInternalEndpoints
+        ? publicConfig.endpoints.internal
+        : publicConfig.endpoints.public;
+    return {
+        kind: 'react',
+        publicConfig,
+        sessionStorageKey: resolveSessionStorageKey(input.sessionStorageKey),
+        queryKey: resolveQueryKey(input.queryKey),
+        endpoints: {
+            refresh: endpointSource.refresh,
+            logout: endpointSource.logout,
+            loginStart: endpointSource.loginStart,
+            loginFinish: endpointSource.loginFinish,
+        },
+        parseClientSession: value => publicConfig.base.session.parseClientSession(value),
+        isSessionExpired: session => publicConfig.base.session.isExpired(session, nowUnix()),
+    };
+}

package/src/core/adapters/access-token-revocation-adapter.d.ts

@@ -0,0 +1,8 @@
+export interface AccessTokenRevocationAdapter {
+    revokeJti(input: {
+        jti: string;
+        expiresAtUnix: number;
+        reason?: string;
+    }): Promise<void>;
+    isRevoked(jti: string): Promise<boolean>;
+}

package/src/core/adapters/access-token-revocation-adapter.js

@@ -0,0 +1 @@
+export {};

package/src/core/adapters/access-token-transport-adapter.d.ts

@@ -0,0 +1,15 @@
+import type { AuthActor } from '../types/auth-contract';
+export type AccessTokenSource = 'bearer' | 'cookie';
+export interface AccessTokenTransportInput {
+    authorizationHeader?: string;
+    cookies?: Record<string, string | undefined>;
+}
+export interface AccessTokenTransportAdapter<TActor extends AuthActor = AuthActor> {
+    extractAccessToken(input: {
+        transport: AccessTokenTransportInput;
+        actorHint?: TActor;
+    }): {
+        token: string | null;
+        source?: AccessTokenSource;
+    };
+}

package/src/core/adapters/access-token-transport-adapter.js

@@ -0,0 +1 @@
+export {};

package/src/core/adapters/authorization-code-adapter.d.ts

@@ -0,0 +1,21 @@
+export type PkceCodeMethod = 'S256' | 'plain';
+export interface AuthorizationCodeAdapter<TUserId> {
+    create(input: {
+        userId: TUserId;
+        codeHash: string;
+        clientId: string;
+        redirectUri: string;
+        codeChallenge: string;
+        codeMethod: PkceCodeMethod;
+        expiresAtUnix: number;
+    }): Promise<void>;
+    consume(codeHash: string, nowUnix: number): Promise<{
+        userId: TUserId;
+        clientId: string;
+        redirectUri: string;
+        codeChallenge: string;
+        codeMethod: PkceCodeMethod;
+        expiresAtUnix: number;
+        consumedAtUnix?: number | null;
+    } | null>;
+}

package/src/core/adapters/authorization-code-adapter.js

@@ -0,0 +1 @@
+export {};

package/src/core/adapters/authorization-hooks.d.ts

@@ -0,0 +1,13 @@
+import type { AuthActor } from '../types/auth-contract';
+export interface AuthorizationHooks<TActor extends AuthActor, TUserId> {
+    canCallMcpTool?(input: {
+        actor: TActor;
+        userId: TUserId;
+        clientId?: string;
+        toolName: string;
+        scopes: string[];
+    }): Promise<{
+        allowed: boolean;
+        reason?: string;
+    }>;
+}

package/src/core/adapters/authorization-hooks.js

@@ -0,0 +1 @@
+export {};

package/src/core/adapters/index.d.ts

@@ -0,0 +1,14 @@
+export type { AccessTokenRevocationAdapter } from './access-token-revocation-adapter';
+export type { AccessTokenSource, AccessTokenTransportAdapter, AccessTokenTransportInput, } from './access-token-transport-adapter';
+export type { AuthorizationCodeAdapter, PkceCodeMethod as AdapterPkceCodeMethod, } from './authorization-code-adapter';
+export type { AuthorizationHooks } from './authorization-hooks';
+export type { LoginMethodAdapter } from './login-method-adapter';
+export type { AuthAuditEvent, AuthAuditEventName, ObservabilityConfig, ObservabilityHooks, } from './observability-hooks';
+export type { OAuthClientAdapter } from './oauth-client-adapter';
+export type { OAuthClientManagementAdapter } from './oauth-client-management-adapter';
+export type { OAuthGrantType } from './oauth-grant-type';
+export type { OAuthPolicy } from './oauth-policy';
+export type { PendingAuthRequestAdapter } from './pending-auth-request-adapter';
+export type { RefreshTokenAdapter } from './refresh-token-adapter';
+export type { SessionAdapter } from './session-adapter';
+export type { TokenAdapter } from './token-adapter';

package/src/core/adapters/index.js

@@ -0,0 +1 @@
+export {};

package/src/core/adapters/login-method-adapter.d.ts

@@ -0,0 +1,7 @@
+export interface LoginMethodAdapter<TUserId> {
+    method: string;
+    start?(input: unknown): Promise<void>;
+    finish(input: unknown): Promise<{
+        userId: TUserId;
+    } | null>;
+}

package/src/core/adapters/login-method-adapter.js

@@ -0,0 +1 @@
+export {};

package/src/core/adapters/oauth-client-adapter.d.ts

@@ -0,0 +1,13 @@
+import type { AuthActor } from '../types/auth-contract';
+import type { OAuthGrantType } from './oauth-grant-type';
+export interface OAuthClientAdapter<TActor extends AuthActor, TUserId> {
+    validateClient(input: {
+        clientId: string;
+        clientSecret: string | null;
+        grantType: OAuthGrantType;
+    }): Promise<{
+        clientId: string;
+        actor: TActor;
+        userId: TUserId;
+    } | null>;
+}

package/src/core/adapters/oauth-client-adapter.js

@@ -0,0 +1 @@
+export {};

package/src/core/adapters/oauth-client-management-adapter.d.ts

@@ -0,0 +1,23 @@
+import type { AuthActor } from '../types/auth-contract';
+export interface OAuthClientManagementAdapter<TActor extends AuthActor, TUserId> {
+    create(input: {
+        userId: TUserId;
+        actor: TActor;
+        displayName: string;
+        requestedScopes?: string[];
+    }): Promise<{
+        clientId: string;
+        clientSecretPlaintext: string;
+    }>;
+    rotateSecret(clientId: string): Promise<{
+        clientSecretPlaintext: string;
+    }>;
+    setDisabled(clientId: string, disabled: boolean): Promise<void>;
+    listByUser(userId: TUserId): Promise<Array<{
+        clientId: string;
+        actor: TActor;
+        disabled: boolean;
+        createdAtUnix: number;
+        lastRotatedAtUnix?: number | null;
+    }>>;
+}

package/src/core/adapters/oauth-client-management-adapter.js

@@ -0,0 +1 @@
+export {};

package/src/core/adapters/oauth-grant-type.d.ts

@@ -0,0 +1 @@
+export type OAuthGrantType = 'authorization_code' | 'refresh_token' | 'client_credentials';

package/src/core/adapters/oauth-grant-type.js

@@ -0,0 +1 @@
+export {};

package/src/core/adapters/oauth-policy.d.ts

@@ -0,0 +1,9 @@
+import type { AuthActor } from '../types/auth-contract';
+import type { OAuthGrantType } from './oauth-grant-type';
+export interface OAuthPolicy<TActor extends AuthActor = AuthActor> {
+    isAllowedClientId(clientId: string): boolean;
+    isAllowedRedirectUri(uri: string): boolean;
+    isAllowedActor(actor: TActor): boolean;
+    isAllowedGrantType?(grantType: OAuthGrantType, clientId: string): boolean;
+    requiredScopeForMcp: string;
+}

package/src/core/adapters/oauth-policy.js

@@ -0,0 +1 @@
+export {};

package/src/core/adapters/observability-hooks.d.ts

@@ -0,0 +1,31 @@
+import type { AuthActor } from '../types/auth-contract';
+export type AuthAuditEventName = 'access_token_issued' | 'access_token_rejected' | 'refresh_token_rotated' | 'refresh_token_reuse_detected' | 'session_revoked' | 'oauth_authorize_started' | 'oauth_code_issued' | 'oauth_token_exchanged' | 'oauth_client_authenticated' | 'mcp_tool_call_denied';
+export interface AuthAuditEvent<TActor extends AuthActor = AuthActor> {
+    name: AuthAuditEventName;
+    atUnix: number;
+    requestId?: string;
+    actor?: TActor;
+    userId?: string;
+    clientId?: string;
+    sessionId?: string;
+    jti?: string;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ObservabilityHooks<TActor extends AuthActor = AuthActor> {
+    onAuditEvent?: (event: AuthAuditEvent<TActor>) => void | Promise<void>;
+    onMetric?: (input: {
+        name: string;
+        value?: number;
+        tags?: Record<string, string>;
+    }) => void | Promise<void>;
+    onError?: (input: {
+        where: string;
+        error: unknown;
+        requestId?: string;
+    }) => void | Promise<void>;
+}
+export interface ObservabilityConfig<TActor extends AuthActor = AuthActor> {
+    hooks?: ObservabilityHooks<TActor>;
+    nonBlockingHooks?: boolean;
+}

package/src/core/adapters/observability-hooks.js

@@ -0,0 +1 @@
+export {};