actor-gate 0.1.0

package/src/core/adapters/pending-auth-request-adapter.d.ts

@@ -0,0 +1,18 @@
+export interface PendingAuthRequestAdapter<TPendingAuthRequest> {
+    create(input: {
+        requestId: string;
+        payload: TPendingAuthRequest;
+        expiresAtUnix: number;
+    }): Promise<void>;
+    find(requestId: string): Promise<{
+        payload: TPendingAuthRequest;
+        expiresAtUnix: number;
+        consumedAtUnix?: number | null;
+    } | null>;
+    consume(requestId: string, nowUnix: number): Promise<{
+        payload: TPendingAuthRequest;
+        expiresAtUnix: number;
+        consumedAtUnix?: number | null;
+    } | null>;
+    delete(requestId: string): Promise<void>;
+}

package/src/core/adapters/pending-auth-request-adapter.js

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

package/src/core/adapters/refresh-token-adapter.d.ts

@@ -0,0 +1,24 @@
+export interface RefreshTokenAdapter<TSessionId> {
+    create(input: {
+        sessionId: TSessionId;
+        tokenHash: string;
+        expiresAtUnix: number;
+        familyId: string;
+        parentTokenHash?: string;
+    }): Promise<void>;
+    find(tokenHash: string): Promise<{
+        sessionId: TSessionId;
+        familyId: string;
+        expiresAtUnix: number;
+        revokedAtUnix?: number | null;
+    } | null>;
+    consume(tokenHash: string, nowUnix: number): Promise<{
+        sessionId: TSessionId;
+        familyId: string;
+        expiresAtUnix: number;
+        consumedAtUnix?: number | null;
+        revokedAtUnix?: number | null;
+    } | null>;
+    revoke(tokenHash: string, nowUnix: number): Promise<void>;
+    revokeFamily(familyId: string, nowUnix: number): Promise<void>;
+}

package/src/core/adapters/refresh-token-adapter.js

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

package/src/core/adapters/session-adapter.d.ts

@@ -0,0 +1,14 @@
+import type { AuthActor, SessionRecord } from '../types/auth-contract';
+export interface SessionAdapter<TSessionId, TUserId, TActor extends AuthActor, TServerSessionData extends Record<string, unknown> = Record<string, never>> {
+    create(input: {
+        userId: TUserId;
+        actor: TActor;
+        clientId?: string;
+        userAgent?: string;
+        ipAddress?: string;
+        ttlSeconds: number;
+        serverSessionData?: TServerSessionData;
+    }): Promise<SessionRecord<TSessionId, TUserId, TActor, TServerSessionData>>;
+    findById(sessionId: TSessionId): Promise<SessionRecord<TSessionId, TUserId, TActor, TServerSessionData> | null>;
+    revoke(sessionId: TSessionId, nowUnix: number): Promise<void>;
+}

package/src/core/adapters/session-adapter.js

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

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

@@ -0,0 +1,15 @@
+import type { AccessClaims, AuthActor } from '../types/auth-contract';
+export interface TokenAdapter<TActor extends AuthActor = AuthActor, TExtClaims extends Record<string, unknown> = Record<string, never>> {
+    signAccessToken(input: {
+        sub: string;
+        uid: string;
+        actor: TActor;
+        cid?: string;
+        ver: number;
+        jti: string;
+        audience: string;
+        expiresInSeconds: number;
+        ext?: TExtClaims;
+    }): string;
+    verifyAccessToken(token: string): AccessClaims<TActor, TExtClaims>;
+}

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

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

package/src/core/http/bearer-challenge.d.ts

@@ -0,0 +1,6 @@
+export type BearerChallengeOptions = {
+    error?: string;
+    resourceMetadataUrl?: string;
+    scope?: string;
+};
+export declare function buildBearerChallengeHeader(options?: BearerChallengeOptions): string;

package/src/core/http/bearer-challenge.js

@@ -0,0 +1,16 @@
+function escapeQuotedAttribute(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function appendQuotedAttribute(attributes, key, value) {
+    if (!value) {
+        return;
+    }
+    attributes.push(`${key}="${escapeQuotedAttribute(value)}"`);
+}
+export function buildBearerChallengeHeader(options = {}) {
+    const headerParts = ['Bearer'];
+    appendQuotedAttribute(headerParts, 'scope', options.scope);
+    appendQuotedAttribute(headerParts, 'resource_metadata', options.resourceMetadataUrl);
+    appendQuotedAttribute(headerParts, 'error', options.error);
+    return headerParts.join(', ');
+}

package/src/core/ids/id-codec.d.ts

@@ -0,0 +1,6 @@
+export interface IdCodec<T> {
+    toClaim(value: T): string;
+    fromClaim(value: string): T;
+}
+export declare const stringIdCodec: IdCodec<string>;
+export declare const numberIdCodec: IdCodec<number>;

package/src/core/ids/id-codec.js

@@ -0,0 +1,30 @@
+function isCanonicalPositiveIntegerClaim(value) {
+    return /^[1-9]\d*$/u.test(value);
+}
+function assertSafePositiveInteger(value, operation) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${operation} expects a positive safe integer.`);
+    }
+}
+export const stringIdCodec = {
+    toClaim(value) {
+        return value;
+    },
+    fromClaim(value) {
+        return value;
+    },
+};
+export const numberIdCodec = {
+    toClaim(value) {
+        assertSafePositiveInteger(value, 'numberIdCodec.toClaim');
+        return String(value);
+    },
+    fromClaim(value) {
+        if (!isCanonicalPositiveIntegerClaim(value)) {
+            throw new Error('numberIdCodec.fromClaim expects a positive integer claim.');
+        }
+        const parsed = Number(value);
+        assertSafePositiveInteger(parsed, 'numberIdCodec.fromClaim');
+        return parsed;
+    },
+};

package/src/core/index.d.ts

@@ -0,0 +1,9 @@
+export { buildBearerChallengeHeader, type BearerChallengeOptions, } from './http/bearer-challenge';
+export { base64UrlEncode, createS256CodeChallenge, verifyPkce, type PkceCodeMethod, type VerifyPkceParams, } from './oauth/pkce';
+export { numberIdCodec, stringIdCodec, type IdCodec } from './ids/id-codec';
+export { decodeSubjectClaims, encodeSubjectClaims, type AuthContext, type SubjectClaims, } from './tokens/id-claims';
+export * from './services/index';
+export { DEFAULT_TOKEN_CLAIMS_VERSION, buildAccessClaims, parseAccessClaims, type BuildAccessClaimsInput, } from './tokens/access-claims';
+export { buildClientSession } from './sessions/client-session';
+export type { AccessClaims, AuthActor, ClientSession, SessionRecord, UserActor, } from './types/auth-contract';
+export type * from './adapters/index';

package/src/core/index.js

@@ -0,0 +1,7 @@
+export { buildBearerChallengeHeader, } from './http/bearer-challenge';
+export { base64UrlEncode, createS256CodeChallenge, verifyPkce, } from './oauth/pkce';
+export { numberIdCodec, stringIdCodec } from './ids/id-codec';
+export { decodeSubjectClaims, encodeSubjectClaims, } from './tokens/id-claims';
+export * from './services/index';
+export { DEFAULT_TOKEN_CLAIMS_VERSION, buildAccessClaims, parseAccessClaims, } from './tokens/access-claims';
+export { buildClientSession } from './sessions/client-session';

package/src/core/oauth/pkce.d.ts

@@ -0,0 +1,9 @@
+export type PkceCodeMethod = 'plain' | 'S256';
+export type VerifyPkceParams = {
+    codeVerifier: string;
+    codeChallenge: string;
+    codeMethod: string;
+};
+export declare function base64UrlEncode(value: Uint8Array): string;
+export declare function createS256CodeChallenge(codeVerifier: string): string;
+export declare function verifyPkce(params: VerifyPkceParams): boolean;

package/src/core/oauth/pkce.js

@@ -0,0 +1,30 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+export function base64UrlEncode(value) {
+    return Buffer.from(value)
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/u, '');
+}
+export function createS256CodeChallenge(codeVerifier) {
+    const digest = createHash('sha256').update(codeVerifier, 'utf8').digest();
+    return base64UrlEncode(digest);
+}
+function constantTimeEqual(left, right) {
+    const leftBuffer = Buffer.from(left, 'utf8');
+    const rightBuffer = Buffer.from(right, 'utf8');
+    if (leftBuffer.length !== rightBuffer.length) {
+        return false;
+    }
+    return timingSafeEqual(leftBuffer, rightBuffer);
+}
+export function verifyPkce(params) {
+    if (params.codeMethod === 'plain') {
+        return constantTimeEqual(params.codeVerifier, params.codeChallenge);
+    }
+    if (params.codeMethod === 'S256') {
+        const computedChallenge = createS256CodeChallenge(params.codeVerifier);
+        return constantTimeEqual(computedChallenge, params.codeChallenge);
+    }
+    return false;
+}

package/src/core/services/access-token-service.d.ts

@@ -0,0 +1,42 @@
+import type { AccessTokenRevocationAdapter } from '../adapters/access-token-revocation-adapter';
+import type { ObservabilityConfig } from '../adapters/observability-hooks';
+import type { SessionAdapter } from '../adapters/session-adapter';
+import type { TokenAdapter } from '../adapters/token-adapter';
+import type { IdCodec } from '../ids/id-codec';
+import type { AuthActor, SessionRecord } from '../types/auth-contract';
+import type { IssuedAccessToken, ValidatedAccessTokenResult } from './contracts';
+import { type RevocationGuarantee, type SessionMode } from './revocation-policy';
+export type AccessTokenService<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TServerSessionData extends Record<string, unknown> = Record<string, never>, TClientSessionData extends Record<string, unknown> = Record<string, never>, TExtClaims extends Record<string, unknown> = Record<string, never>> = {
+    issueAccessToken(input: {
+        session: SessionRecord<TSessionId, TUserId, TActor, TServerSessionData>;
+        requestId?: string;
+    }): Promise<IssuedAccessToken<TSessionId, TUserId, TActor, TExtClaims, TClientSessionData>>;
+    validateAccessToken(input: {
+        accessToken: string;
+        requestId?: string;
+        expectedAudience?: string;
+        allowedActors?: readonly TActor[] | ReadonlySet<TActor>;
+    }): Promise<ValidatedAccessTokenResult<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>>;
+};
+export type CreateAccessTokenServiceInput<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TServerSessionData extends Record<string, unknown> = Record<string, never>, TClientSessionData extends Record<string, unknown> = Record<string, never>, TExtClaims extends Record<string, unknown> = Record<string, never>> = {
+    tokenAdapter: TokenAdapter<TActor, TExtClaims>;
+    sessionIdCodec: IdCodec<TSessionId>;
+    userIdCodec: IdCodec<TUserId>;
+    sessionAdapter?: SessionAdapter<TSessionId, TUserId, TActor, TServerSessionData>;
+    accessTokenRevocationAdapter?: AccessTokenRevocationAdapter;
+    sessionMode?: SessionMode;
+    revocationGuarantee?: RevocationGuarantee;
+    boundedRevocationCacheSeconds?: number;
+    audience: string;
+    accessTokenTtlSeconds: number;
+    tokenClaimsVersion?: number;
+    nowUnix?: () => number;
+    buildExtClaims?: (input: {
+        session: SessionRecord<TSessionId, TUserId, TActor, TServerSessionData>;
+    }) => TExtClaims;
+    buildClientSessionData?: (input: {
+        session: SessionRecord<TSessionId, TUserId, TActor, TServerSessionData>;
+    }) => TClientSessionData;
+    observability?: ObservabilityConfig<TActor>;
+};
+export declare function createAccessTokenService<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TServerSessionData extends Record<string, unknown> = Record<string, never>, TClientSessionData extends Record<string, unknown> = Record<string, never>, TExtClaims extends Record<string, unknown> = Record<string, never>>(input: CreateAccessTokenServiceInput<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>): AccessTokenService<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>;

package/src/core/services/access-token-service.js

@@ -0,0 +1,304 @@
+import { buildClientSession } from '../sessions/client-session';
+import { decodeSubjectClaims } from '../tokens/id-claims';
+import { buildAccessClaims, parseAccessClaims } from '../tokens/access-claims';
+import { AuthServiceError, isAuthServiceError } from './auth-error';
+import { createRevocationDecisionEngine, shouldValidateSession, } from './revocation-policy';
+import { emitAuditEvent, emitMetric, reportServiceError, } from './observability';
+function assertPositiveSafeInteger(value, fieldName) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: `${fieldName} must be a positive safe integer.`,
+        });
+    }
+}
+function normalizeAllowedActors(actors) {
+    if (actors === undefined) {
+        return null;
+    }
+    if (actors instanceof Set) {
+        return actors;
+    }
+    return new Set(actors);
+}
+export function createAccessTokenService(input) {
+    if (input.audience.length === 0) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'audience must be a non-empty string.',
+        });
+    }
+    assertPositiveSafeInteger(input.accessTokenTtlSeconds, 'accessTokenTtlSeconds');
+    const sessionMode = input.sessionMode ?? 'hybrid';
+    const revocationGuarantee = input.revocationGuarantee ?? 'strict';
+    const boundedRevocationCacheSeconds = input.boundedRevocationCacheSeconds ?? 30;
+    if (sessionMode === 'stateful' && !input.sessionAdapter) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'sessionAdapter is required when sessionMode is stateful.',
+        });
+    }
+    if (revocationGuarantee === 'bounded') {
+        assertPositiveSafeInteger(boundedRevocationCacheSeconds, 'boundedRevocationCacheSeconds');
+    }
+    const nowUnix = input.nowUnix ?? (() => Math.floor(Date.now() / 1000));
+    const revocationDecisionEngine = createRevocationDecisionEngine();
+    return {
+        async issueAccessToken({ session, requestId }) {
+            const issuedAtUnix = nowUnix();
+            try {
+                const claims = buildAccessClaims({
+                    session,
+                    sessionIdCodec: input.sessionIdCodec,
+                    userIdCodec: input.userIdCodec,
+                    audience: input.audience,
+                    accessTokenTtlSeconds: input.accessTokenTtlSeconds,
+                    ...(input.tokenClaimsVersion === undefined
+                        ? {}
+                        : { tokenClaimsVersion: input.tokenClaimsVersion }),
+                    nowUnix: issuedAtUnix,
+                    ...(input.buildExtClaims === undefined
+                        ? {}
+                        : { buildExtClaims: input.buildExtClaims }),
+                });
+                const accessToken = input.tokenAdapter.signAccessToken({
+                    sub: claims.sub,
+                    uid: claims.uid,
+                    actor: claims.actor,
+                    ...(claims.cid === undefined ? {} : { cid: claims.cid }),
+                    ver: claims.ver,
+                    jti: claims.jti,
+                    audience: claims.aud,
+                    expiresInSeconds: claims.exp - claims.iat,
+                    ...(claims.ext === undefined ? {} : { ext: claims.ext }),
+                });
+                const clientSession = buildClientSession({
+                    session,
+                    ...(input.buildClientSessionData === undefined
+                        ? {}
+                        : { buildClientSessionData: input.buildClientSessionData }),
+                });
+                await emitAuditEvent({
+                    observability: input.observability,
+                    requestId,
+                    event: {
+                        name: 'access_token_issued',
+                        atUnix: issuedAtUnix,
+                        actor: claims.actor,
+                        userId: claims.uid,
+                        ...(claims.cid === undefined ? {} : { clientId: claims.cid }),
+                        sessionId: claims.sub,
+                        jti: claims.jti,
+                    },
+                });
+                await emitMetric({
+                    observability: input.observability,
+                    requestId,
+                    metric: {
+                        name: 'auth.access_token.issued',
+                        value: 1,
+                        tags: { actor: String(claims.actor) },
+                    },
+                });
+                return {
+                    accessToken,
+                    claims,
+                    clientSession,
+                };
+            }
+            catch (error) {
+                if (isAuthServiceError(error)) {
+                    throw error;
+                }
+                await reportServiceError({
+                    observability: input.observability,
+                    where: 'access-token-service.issueAccessToken',
+                    error,
+                    requestId,
+                });
+                throw new AuthServiceError({
+                    code: 'system_error',
+                    message: 'Failed to issue access token.',
+                    cause: error,
+                });
+            }
+        },
+        async validateAccessToken({ accessToken, requestId, expectedAudience, allowedActors, }) {
+            const now = nowUnix();
+            let parsedClaims;
+            const reject = async (error) => {
+                await emitAuditEvent({
+                    observability: input.observability,
+                    requestId,
+                    event: {
+                        name: 'access_token_rejected',
+                        atUnix: now,
+                        ...(parsedClaims === undefined
+                            ? {}
+                            : {
+                                actor: parsedClaims.actor,
+                                userId: parsedClaims.uid,
+                                clientId: parsedClaims.cid,
+                                sessionId: parsedClaims.sub,
+                                jti: parsedClaims.jti,
+                            }),
+                        reason: error.code,
+                    },
+                });
+                await emitMetric({
+                    observability: input.observability,
+                    requestId,
+                    metric: {
+                        name: 'auth.access_token.rejected',
+                        value: 1,
+                        tags: { code: error.code },
+                    },
+                });
+                throw error;
+            };
+            try {
+                try {
+                    parsedClaims = parseAccessClaims({
+                        claims: input.tokenAdapter.verifyAccessToken(accessToken),
+                        ...(input.tokenClaimsVersion === undefined
+                            ? {}
+                            : { tokenClaimsVersion: input.tokenClaimsVersion }),
+                    });
+                }
+                catch (error) {
+                    return reject(new AuthServiceError({
+                        code: 'invalid_token',
+                        message: 'Access token verification failed.',
+                        cause: error,
+                    }));
+                }
+                const audience = expectedAudience ?? input.audience;
+                if (parsedClaims.aud !== audience) {
+                    return reject(new AuthServiceError({
+                        code: 'invalid_token',
+                        message: 'Access token audience mismatch.',
+                    }));
+                }
+                if (parsedClaims.exp <= now) {
+                    return reject(new AuthServiceError({
+                        code: 'token_expired',
+                        message: 'Access token has expired.',
+                    }));
+                }
+                const allowedActorSet = normalizeAllowedActors(allowedActors);
+                if (allowedActorSet && !allowedActorSet.has(parsedClaims.actor)) {
+                    return reject(new AuthServiceError({
+                        code: 'forbidden',
+                        message: 'Actor is not allowed for this resource.',
+                    }));
+                }
+                if (await revocationDecisionEngine.isAccessTokenRevoked({
+                    jti: parsedClaims.jti,
+                    nowUnix: now,
+                    revocationGuarantee,
+                    boundedRevocationCacheSeconds,
+                    ...(input.accessTokenRevocationAdapter === undefined
+                        ? {}
+                        : {
+                            accessTokenRevocationAdapter: input.accessTokenRevocationAdapter,
+                        }),
+                })) {
+                    return reject(new AuthServiceError({
+                        code: 'token_revoked',
+                        message: 'Access token was revoked.',
+                    }));
+                }
+                let authContext;
+                try {
+                    authContext = decodeSubjectClaims({
+                        claims: parsedClaims,
+                        sessionIdCodec: input.sessionIdCodec,
+                        userIdCodec: input.userIdCodec,
+                    });
+                }
+                catch (error) {
+                    return reject(new AuthServiceError({
+                        code: 'invalid_token',
+                        message: 'Access token subject claims are invalid.',
+                        cause: error,
+                    }));
+                }
+                let session;
+                let clientSession;
+                if (shouldValidateSession({
+                    sessionMode,
+                    hasSessionAdapter: input.sessionAdapter !== undefined,
+                })) {
+                    const foundSession = await input.sessionAdapter.findById(authContext.sessionId);
+                    if (!foundSession) {
+                        return reject(new AuthServiceError({
+                            code: 'session_not_found',
+                            message: 'Session was not found.',
+                        }));
+                    }
+                    session = foundSession;
+                    if (session.userId !== authContext.userId) {
+                        return reject(new AuthServiceError({
+                            code: 'unauthorized',
+                            message: 'Session user does not match token user.',
+                        }));
+                    }
+                    if (session.actor !== parsedClaims.actor) {
+                        return reject(new AuthServiceError({
+                            code: 'unauthorized',
+                            message: 'Session actor does not match token actor.',
+                        }));
+                    }
+                    if (session.clientId !== parsedClaims.cid) {
+                        return reject(new AuthServiceError({
+                            code: 'unauthorized',
+                            message: 'Session client does not match token client.',
+                        }));
+                    }
+                    if (session.revokedAt !== undefined &&
+                        session.revokedAt !== null &&
+                        session.revokedAt <= now) {
+                        return reject(new AuthServiceError({
+                            code: 'session_revoked',
+                            message: 'Session was revoked.',
+                        }));
+                    }
+                    if (session.expiresAt <= now) {
+                        return reject(new AuthServiceError({
+                            code: 'session_expired',
+                            message: 'Session has expired.',
+                        }));
+                    }
+                    clientSession = buildClientSession({
+                        session,
+                        ...(input.buildClientSessionData === undefined
+                            ? {}
+                            : { buildClientSessionData: input.buildClientSessionData }),
+                    });
+                }
+                return {
+                    claims: parsedClaims,
+                    authContext,
+                    ...(session === undefined ? {} : { session }),
+                    ...(clientSession === undefined ? {} : { clientSession }),
+                };
+            }
+            catch (error) {
+                if (isAuthServiceError(error)) {
+                    throw error;
+                }
+                await reportServiceError({
+                    observability: input.observability,
+                    where: 'access-token-service.validateAccessToken',
+                    error,
+                    requestId,
+                });
+                throw new AuthServiceError({
+                    code: 'system_error',
+                    message: 'Failed to validate access token.',
+                    cause: error,
+                });
+            }
+        },
+    };
+}

package/src/core/services/auth-error.d.ts

@@ -0,0 +1,14 @@
+export type AuthServiceErrorCode = 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'invalid_token' | 'token_expired' | 'token_revoked' | 'session_not_found' | 'session_revoked' | 'session_expired' | 'unauthorized' | 'forbidden' | 'system_error';
+export declare class AuthServiceError extends Error {
+    readonly code: AuthServiceErrorCode;
+    readonly details?: Record<string, unknown>;
+    readonly cause?: unknown;
+    constructor(input: {
+        code: AuthServiceErrorCode;
+        message: string;
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+export declare function isAuthServiceError(error: unknown): error is AuthServiceError;
+export declare function authErrorToHttpStatus(code: AuthServiceErrorCode): number;

package/src/core/services/auth-error.js

@@ -0,0 +1,47 @@
+export class AuthServiceError extends Error {
+    code;
+    details;
+    cause;
+    constructor(input) {
+        super(input.message);
+        this.name = 'AuthServiceError';
+        this.code = input.code;
+        if (input.details !== undefined) {
+            this.details = input.details;
+        }
+        if (input.cause !== undefined) {
+            this.cause = input.cause;
+        }
+    }
+}
+export function isAuthServiceError(error) {
+    return error instanceof AuthServiceError;
+}
+export function authErrorToHttpStatus(code) {
+    switch (code) {
+        case 'invalid_request':
+            return 400;
+        case 'invalid_client':
+            return 401;
+        case 'invalid_grant':
+            return 400;
+        case 'invalid_token':
+            return 401;
+        case 'token_expired':
+            return 401;
+        case 'token_revoked':
+            return 401;
+        case 'session_not_found':
+            return 401;
+        case 'session_revoked':
+            return 401;
+        case 'session_expired':
+            return 401;
+        case 'unauthorized':
+            return 401;
+        case 'forbidden':
+            return 403;
+        case 'system_error':
+            return 500;
+    }
+}

package/src/core/services/contracts.d.ts

@@ -0,0 +1,23 @@
+import type { AuthContext } from '../tokens/id-claims';
+import type { AccessClaims, AuthActor, ClientSession, SessionRecord } from '../types/auth-contract';
+export type RefreshTokenMode = 'reuse' | 'rotate' | 'rotate_with_reuse_detection';
+export type RefreshTokenReuseRevokeScope = 'token' | 'family' | 'session';
+export type IssuedAccessToken<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TExtClaims extends Record<string, unknown> = Record<string, never>, TClientSessionData extends Record<string, unknown> = Record<string, never>> = {
+    accessToken: string;
+    claims: AccessClaims<TActor, TExtClaims>;
+    clientSession?: ClientSession<TSessionId, TUserId, TActor, TClientSessionData>;
+};
+export type ValidatedAccessTokenResult<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TServerSessionData extends Record<string, unknown> = Record<string, never>, TClientSessionData extends Record<string, unknown> = Record<string, never>, TExtClaims extends Record<string, unknown> = Record<string, never>> = {
+    claims: AccessClaims<TActor, TExtClaims>;
+    authContext: AuthContext<TSessionId, TUserId>;
+    session?: SessionRecord<TSessionId, TUserId, TActor, TServerSessionData>;
+    clientSession?: ClientSession<TSessionId, TUserId, TActor, TClientSessionData>;
+};
+export type OAuthPendingRequest = {
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    codeMethod: 'S256' | 'plain';
+    scopes: string[];
+    state?: string;
+};

package/src/core/services/contracts.js

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