@vouchington/oauth-server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Ong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @vouchington/oauth-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-agnostic OAuth 2.0 authorization-server building blocks: RFC 6749 (code and refresh
+grants), RFC 7591 (dynamic client registration), RFC 7636 (PKCE, S256 only), RFC 7009 (revocation),
+RFC 8414 / 9728 (metadata), RFC 8707 (resource indicators), and RFC 9207 (`iss` on responses).
+
+The package never touches HTTP frameworks or databases. The application injects:
+
+- `ClientStore` / `ClientRegistry` — client lookup (return only active, eligible clients) and creation.
+- `GrantStore` — authorization-code and refresh-token persistence. `redeemAuthorizationCode` and
+  `redeemRefreshToken` run the package's verification callback inside the adapter's own
+  transaction and lock; the adapter persists the returned tokens and spends the secret atomically,
+  flags reuse with `replayed: true`, and decides what a replay or failed attempt revokes.
+- `HashSecret` — one-way hash for client secrets, codes, and tokens. Only hashes reach the stores.
+- `ScopePolicy` — a `ScopeCatalog` from `@vouchington/utils/scopes` plus the catalog surface.
+- `resolveResource` — maps a `resource` URL to `{ url, audience }` or `null`.
+- Consent, retention, ownership, rate limiting, and request routing.
+
+```ts
+import {
+  exchangeTokenGrant,
+  parseClientAuthentication,
+  parseFormBody,
+} from '@vouchington/oauth-server'
+
+const form = parseFormBody(contentType, body)
+const credentials = parseClientAuthentication(authorizationHeader, form)
+const tokens = await exchangeTokenGrant(form, credentials, { clients, grants, scopes, hashSecret })
+```
+
+Errors are `OAuthProtocolError`; `buildOAuthErrorResponse(error)` renders the RFC 6749 section 5.2
+body, status, and `WWW-Authenticate` challenge. Redirect URIs match by exact string, except RFC 8252
+loopback registrations that omit the port. Secret and PKCE comparisons are timing-safe.

package/dist/authorization.d.mts

@@ -0,0 +1,66 @@
+import { OAuthProtocolError } from './errors.mts';
+import type { ClientStore, GrantStore, HashSecret, OAuthClient, ResolveResource, ScopePolicy, TokenLifetimes } from './types.mts';
+/** Raw authorization endpoint parameters; everything but `clientId` and `redirectUri` is unchecked. */
+export interface AuthorizationParameters {
+    clientId: string;
+    redirectUri: string;
+    responseType: unknown;
+    scope: unknown;
+    resource: unknown;
+    state: unknown;
+    codeChallenge: unknown;
+    codeChallengeMethod: unknown;
+}
+export interface ValidatedAuthorizationRequest {
+    client: OAuthClient;
+    codeChallenge: string;
+    redirectUri: string;
+    resource: string;
+    scopes: string[];
+    state: string;
+}
+export interface AuthorizationDependencies {
+    clients: ClientStore;
+    scopes: ScopePolicy;
+    resolveResource: ResolveResource;
+}
+/**
+ * Validates an authorization request: code response type, state, scopes, RFC 8707 resource,
+ * S256 PKCE, a known client, an exactly registered redirect URI, and client scope coverage.
+ */
+export declare function validateAuthorizationRequest(input: AuthorizationParameters, deps: AuthorizationDependencies): Promise<ValidatedAuthorizationRequest>;
+/**
+ * RFC 6749 section 4.1.2.1: errors may only redirect to a registered redirect URI. Returns null
+ * when the client or URI cannot be trusted, in which case the application renders the error.
+ */
+export declare function authorizationErrorRedirect(input: {
+    clientId: string;
+    redirectUri: string;
+    state: unknown;
+    error: OAuthProtocolError;
+}, deps: {
+    clients: ClientStore;
+    issuer: string;
+}): Promise<string | null>;
+/** Redirect URL for a user who declined consent. */
+export declare function denyAuthorization(request: ValidatedAuthorizationRequest, issuer: string): string;
+export interface CodeIssuanceDependencies {
+    grants: Pick<GrantStore, 'saveAuthorizationCode'>;
+    hashSecret: HashSecret;
+    issuer: string;
+    lifetimes?: Partial<Pick<TokenLifetimes, 'authorizationCodeMs'>>;
+    /** Prefix for generated authorization codes. Defaults to "code_". */
+    codePrefix?: string;
+    now?: () => Date;
+}
+/**
+ * After the application records consent as `grantId` for `subject`, mints a single-use code bound
+ * to the client, redirect URI, resource, scopes and PKCE challenge, and builds the redirect URL.
+ */
+export declare function issueAuthorizationCode(request: ValidatedAuthorizationRequest, consent: {
+    grantId: string;
+    subject: string;
+}, deps: CodeIssuanceDependencies): Promise<{
+    code: string;
+    redirectUrl: string;
+}>;

package/dist/authorization.mjs

@@ -0,0 +1,84 @@
+import { OAuthProtocolError, invalidRequest } from './errors.mjs';
+import { DEFAULT_TOKEN_LIFETIMES, DEFAULT_TOKEN_PREFIXES } from './lifetimes.mjs';
+import { validatePkceChallenge } from './pkce.mjs';
+import { matchesRegisteredRedirectUri } from './redirect-uri.mjs';
+import { buildAuthorizationResponseUrl } from './responses.mjs';
+import { assertClientMayRequestScopes, assertScopesMatchResource, parseScopeParameter, resolveRequiredResource, } from './scopes.mjs';
+import { generateOpaqueToken } from './secrets.mjs';
+const MAX_STATE_LENGTH = 1024;
+/**
+ * Validates an authorization request: code response type, state, scopes, RFC 8707 resource,
+ * S256 PKCE, a known client, an exactly registered redirect URI, and client scope coverage.
+ */
+export async function validateAuthorizationRequest(input, deps) {
+    if (input.responseType !== 'code') {
+        throw new OAuthProtocolError('unsupported_response_type', 'response_type must be code');
+    }
+    const state = input.state;
+    if (typeof state !== 'string' || state.length === 0 || state.length > MAX_STATE_LENGTH) {
+        throw invalidRequest('state is required');
+    }
+    const { scopes, audiences } = parseScopeParameter(input.scope, deps.scopes);
+    const resource = resolveRequiredResource(input.resource, deps.resolveResource);
+    assertScopesMatchResource(audiences, resource);
+    const codeChallenge = validatePkceChallenge(input.codeChallenge, input.codeChallengeMethod);
+    const client = await deps.clients.findClient(input.clientId);
+    if (!client)
+        throw new OAuthProtocolError('unauthorized_client', 'client is not registered');
+    if (!matchesRegisteredRedirectUri(input.redirectUri, client.redirectUris)) {
+        throw invalidRequest('redirect_uri is not registered for this client');
+    }
+    assertClientMayRequestScopes(deps.scopes, client.scopes, scopes);
+    return {
+        client,
+        codeChallenge,
+        redirectUri: input.redirectUri,
+        resource: resource.url,
+        scopes,
+        state,
+    };
+}
+/**
+ * RFC 6749 section 4.1.2.1: errors may only redirect to a registered redirect URI. Returns null
+ * when the client or URI cannot be trusted, in which case the application renders the error.
+ */
+export async function authorizationErrorRedirect(input, deps) {
+    const client = await deps.clients.findClient(input.clientId);
+    if (!client || !matchesRegisteredRedirectUri(input.redirectUri, client.redirectUris))
+        return null;
+    return buildAuthorizationResponseUrl(input.redirectUri, {
+        error: input.error.code,
+        error_description: input.error.message,
+        ...(typeof input.state === 'string' && input.state.length <= MAX_STATE_LENGTH
+            ? { state: input.state }
+            : {}),
+    }, deps.issuer);
+}
+/** Redirect URL for a user who declined consent. */
+export function denyAuthorization(request, issuer) {
+    return buildAuthorizationResponseUrl(request.redirectUri, { error: 'access_denied', state: request.state }, issuer);
+}
+/**
+ * After the application records consent as `grantId` for `subject`, mints a single-use code bound
+ * to the client, redirect URI, resource, scopes and PKCE challenge, and builds the redirect URL.
+ */
+export async function issueAuthorizationCode(request, consent, deps) {
+    const code = generateOpaqueToken(deps.codePrefix ?? DEFAULT_TOKEN_PREFIXES.authorizationCode);
+    const now = deps.now?.() ?? new Date();
+    await deps.grants.saveAuthorizationCode({
+        codeHash: deps.hashSecret('authorization-code', code),
+        clientId: request.client.clientId,
+        redirectUri: request.redirectUri,
+        resource: request.resource,
+        scopes: request.scopes,
+        codeChallenge: request.codeChallenge,
+        grantId: consent.grantId,
+        subject: consent.subject,
+        expiresAt: new Date(now.getTime() +
+            (deps.lifetimes?.authorizationCodeMs ?? DEFAULT_TOKEN_LIFETIMES.authorizationCodeMs)),
+    });
+    return {
+        code,
+        redirectUrl: buildAuthorizationResponseUrl(request.redirectUri, { code, state: request.state }, deps.issuer),
+    };
+}

package/dist/client-auth.d.mts

@@ -0,0 +1,4 @@
+import type { ClientCredentials } from './request.mts';
+import type { ClientStore, HashSecret, OAuthClient } from './types.mts';
+/** Authenticates a client at the token or revocation endpoint with a timing-safe secret check. */
+export declare function authenticateClient(store: ClientStore, credentials: ClientCredentials, hashSecret: HashSecret): Promise<OAuthClient>;

package/dist/client-auth.mjs

@@ -0,0 +1,19 @@
+import { invalidClient } from './errors.mjs';
+import { safeEqual } from './secrets.mjs';
+/** Authenticates a client at the token or revocation endpoint with a timing-safe secret check. */
+export async function authenticateClient(store, credentials, hashSecret) {
+    const client = await store.findClient(credentials.clientId);
+    if (!client)
+        throw invalidClient();
+    if (client.tokenEndpointAuthMethod === 'none') {
+        if (credentials.clientSecret !== undefined)
+            throw invalidClient('public client sent a secret');
+        return client;
+    }
+    if (!credentials.clientSecret || !client.clientSecretHash)
+        throw invalidClient();
+    const presented = hashSecret('client-secret', credentials.clientSecret);
+    if (!safeEqual(presented, client.clientSecretHash))
+        throw invalidClient();
+    return client;
+}

package/dist/client-metadata.d.mts

@@ -0,0 +1,7 @@
+import type { ClientAuthMethod } from './types.mts';
+export declare function validateRegistrationObject(input: unknown): Record<string, unknown>;
+export declare function validateClientName(value: unknown): string;
+/** RFC 7591 section 2 defaults an omitted method to client_secret_basic; callers may override. */
+export declare function validateAuthMethod(value: unknown, defaultMethod?: ClientAuthMethod): ClientAuthMethod;
+export declare function validateGrantTypes(value: unknown): string[];
+export declare function validateResponseTypes(value: unknown): string[];

package/dist/client-metadata.mjs

@@ -0,0 +1,46 @@
+import { invalidClientMetadata } from './errors.mjs';
+// RFC 7591 client-metadata validators. Only the code flow with refresh tokens is supported.
+export function validateRegistrationObject(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        throw invalidClientMetadata('registration metadata must be a JSON object');
+    }
+    return input;
+}
+export function validateClientName(value) {
+    if (typeof value !== 'string' ||
+        value.trim().length === 0 ||
+        value.length > 120 ||
+        /[\p{Cc}\p{Cf}]/u.test(value)) {
+        throw invalidClientMetadata('client_name must contain between 1 and 120 characters');
+    }
+    return value.trim();
+}
+/** RFC 7591 section 2 defaults an omitted method to client_secret_basic; callers may override. */
+export function validateAuthMethod(value, defaultMethod = 'client_secret_basic') {
+    if (value === undefined)
+        return defaultMethod;
+    if (value === 'none' || value === 'client_secret_basic')
+        return value;
+    throw invalidClientMetadata('token_endpoint_auth_method is not supported');
+}
+export function validateGrantTypes(value) {
+    const grantTypes = value ?? ['authorization_code', 'refresh_token'];
+    if (!Array.isArray(grantTypes) || grantTypes.length === 0) {
+        throw invalidClientMetadata('grant_types is invalid');
+    }
+    const unique = new Set(grantTypes);
+    if (unique.size !== grantTypes.length ||
+        !unique.has('authorization_code') ||
+        !unique.has('refresh_token') ||
+        unique.size !== 2) {
+        throw invalidClientMetadata('grant_types is not supported');
+    }
+    return ['authorization_code', 'refresh_token'];
+}
+export function validateResponseTypes(value) {
+    const responseTypes = value ?? ['code'];
+    if (!Array.isArray(responseTypes) || responseTypes.length !== 1 || responseTypes[0] !== 'code') {
+        throw invalidClientMetadata('only the code response type is supported');
+    }
+    return ['code'];
+}

package/dist/errors.d.mts

@@ -0,0 +1,13 @@
+export type OAuthErrorCode = 'access_denied' | 'invalid_client' | 'invalid_client_metadata' | 'invalid_grant' | 'invalid_redirect_uri' | 'invalid_request' | 'invalid_scope' | 'invalid_target' | 'server_error' | 'unauthorized_client' | 'unsupported_grant_type' | 'unsupported_response_type';
+/** Protocol failure carrying the RFC 6749 error code and the HTTP status a token endpoint uses. */
+export declare class OAuthProtocolError extends Error {
+    readonly code: OAuthErrorCode;
+    readonly status: number;
+    constructor(code: OAuthErrorCode, description: string, status?: number, options?: ErrorOptions);
+}
+export declare function invalidRequest(description: string): OAuthProtocolError;
+export declare function invalidGrant(description: string): OAuthProtocolError;
+export declare function invalidTarget(): OAuthProtocolError;
+export declare function invalidClientMetadata(description: string): OAuthProtocolError;
+export declare function invalidRedirectUri(description: string): OAuthProtocolError;
+export declare function invalidClient(description?: string): OAuthProtocolError;

package/dist/errors.mjs

@@ -0,0 +1,29 @@
+/** Protocol failure carrying the RFC 6749 error code and the HTTP status a token endpoint uses. */
+export class OAuthProtocolError extends Error {
+    code;
+    status;
+    constructor(code, description, status = 400, options) {
+        super(description, options);
+        this.name = 'OAuthProtocolError';
+        this.code = code;
+        this.status = status;
+    }
+}
+export function invalidRequest(description) {
+    return new OAuthProtocolError('invalid_request', description);
+}
+export function invalidGrant(description) {
+    return new OAuthProtocolError('invalid_grant', description);
+}
+export function invalidTarget() {
+    return new OAuthProtocolError('invalid_target', 'resource is not supported');
+}
+export function invalidClientMetadata(description) {
+    return new OAuthProtocolError('invalid_client_metadata', description);
+}
+export function invalidRedirectUri(description) {
+    return new OAuthProtocolError('invalid_redirect_uri', description);
+}
+export function invalidClient(description = 'client authentication failed') {
+    return new OAuthProtocolError('invalid_client', description, 401);
+}

package/dist/index.d.mts

@@ -0,0 +1,16 @@
+export * from './authorization.mts';
+export * from './client-auth.mts';
+export * from './client-metadata.mts';
+export * from './errors.mts';
+export * from './lifetimes.mts';
+export * from './metadata.mts';
+export * from './pkce.mts';
+export * from './redirect-uri.mts';
+export * from './registration.mts';
+export * from './request.mts';
+export * from './responses.mts';
+export * from './revocation.mts';
+export * from './scopes.mts';
+export * from './secrets.mts';
+export * from './token.mts';
+export type * from './types.mts';

package/dist/index.mjs

@@ -0,0 +1,15 @@
+export * from './authorization.mjs';
+export * from './client-auth.mjs';
+export * from './client-metadata.mjs';
+export * from './errors.mjs';
+export * from './lifetimes.mjs';
+export * from './metadata.mjs';
+export * from './pkce.mjs';
+export * from './redirect-uri.mjs';
+export * from './registration.mjs';
+export * from './request.mjs';
+export * from './responses.mjs';
+export * from './revocation.mjs';
+export * from './scopes.mjs';
+export * from './secrets.mjs';
+export * from './token.mjs';

package/dist/lifetimes.d.mts

@@ -0,0 +1,4 @@
+import type { TokenLifetimes, TokenPrefixes } from './types.mts';
+/** Safe defaults; callers override any of them. */
+export declare const DEFAULT_TOKEN_LIFETIMES: TokenLifetimes;
+export declare const DEFAULT_TOKEN_PREFIXES: TokenPrefixes;

package/dist/lifetimes.mjs

@@ -0,0 +1,11 @@
+/** Safe defaults; callers override any of them. */
+export const DEFAULT_TOKEN_LIFETIMES = {
+    authorizationCodeMs: 5 * 60 * 1000,
+    accessTokenMs: 60 * 60 * 1000,
+    refreshTokenMs: 30 * 24 * 60 * 60 * 1000,
+};
+export const DEFAULT_TOKEN_PREFIXES = {
+    authorizationCode: 'code_',
+    accessToken: 'access_',
+    refreshToken: 'refresh_',
+};

package/dist/metadata.d.mts

@@ -0,0 +1,41 @@
+export interface AuthorizationServerMetadataOptions {
+    issuer: string;
+    scopesSupported: readonly string[];
+    /** Absolute endpoint URLs; each defaults to the issuer plus its conventional path. */
+    endpoints?: {
+        authorization?: string;
+        token?: string;
+        registration?: string;
+        revocation?: string;
+    };
+    /** Extra RFC 8414 members, such as application-specific capability flags. */
+    extra?: Readonly<Record<string, unknown>>;
+}
+/** RFC 8414 metadata for the supported subset: code + refresh grants, S256 PKCE, RFC 9207 iss. */
+export declare function buildAuthorizationServerMetadata(options: AuthorizationServerMetadataOptions): {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint: string;
+    revocation_endpoint: string;
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    code_challenge_methods_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    revocation_endpoint_auth_methods_supported: string[];
+    scopes_supported: string[];
+    authorization_response_iss_parameter_supported: boolean;
+};
+/** RFC 9728 metadata document for one protected resource. */
+export declare function buildProtectedResourceMetadata(options: {
+    resource: string;
+    issuer: string;
+    scopesSupported: readonly string[];
+}): {
+    resource: string;
+    authorization_servers: string[];
+    bearer_methods_supported: string[];
+    scopes_supported: string[];
+};
+/** RFC 9728 inserts the well-known segment between the origin and the resource path. */
+export declare function protectedResourceMetadataUrl(resource: string): string;

package/dist/metadata.mjs

@@ -0,0 +1,35 @@
+/** RFC 8414 metadata for the supported subset: code + refresh grants, S256 PKCE, RFC 9207 iss. */
+export function buildAuthorizationServerMetadata(options) {
+    const { issuer, endpoints = {} } = options;
+    const methods = ['client_secret_basic', 'none'];
+    return {
+        issuer,
+        authorization_endpoint: endpoints.authorization ?? `${issuer}/authorize`,
+        token_endpoint: endpoints.token ?? `${issuer}/token`,
+        registration_endpoint: endpoints.registration ?? `${issuer}/register`,
+        revocation_endpoint: endpoints.revocation ?? `${issuer}/revoke`,
+        response_types_supported: ['code'],
+        grant_types_supported: ['authorization_code', 'refresh_token'],
+        code_challenge_methods_supported: ['S256'],
+        token_endpoint_auth_methods_supported: methods,
+        revocation_endpoint_auth_methods_supported: methods,
+        scopes_supported: options.scopesSupported.toSorted(),
+        authorization_response_iss_parameter_supported: true,
+        ...options.extra,
+    };
+}
+/** RFC 9728 metadata document for one protected resource. */
+export function buildProtectedResourceMetadata(options) {
+    return {
+        resource: options.resource,
+        authorization_servers: [options.issuer],
+        bearer_methods_supported: ['header'],
+        scopes_supported: options.scopesSupported.toSorted(),
+    };
+}
+/** RFC 9728 inserts the well-known segment between the origin and the resource path. */
+export function protectedResourceMetadataUrl(resource) {
+    const url = new URL(resource);
+    const path = url.pathname === '/' ? '' : url.pathname;
+    return `${url.origin}/.well-known/oauth-protected-resource${path}${url.search}`;
+}

package/dist/pkce.d.mts

@@ -0,0 +1,6 @@
+/** RFC 7636 S256 challenge for a verifier. The plain method is never accepted. */
+export declare function createPkceChallenge(verifier: string): string;
+export declare function validatePkceChallenge(challenge: unknown, method: unknown): string;
+export declare function validatePkceVerifier(verifier: unknown): string;
+/** Timing-safe check that `verifier` produced the stored S256 `challenge`. */
+export declare function verifyPkce(challenge: string, verifier: string): boolean;

package/dist/pkce.mjs

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+import { invalidGrant, invalidRequest } from './errors.mjs';
+import { safeEqual } from './secrets.mjs';
+const PKCE_CHALLENGE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+const PKCE_VERIFIER_PATTERN = /^[A-Za-z0-9._~-]{43,128}$/;
+/** RFC 7636 S256 challenge for a verifier. The plain method is never accepted. */
+export function createPkceChallenge(verifier) {
+    return createHash('sha256').update(verifier).digest('base64url');
+}
+export function validatePkceChallenge(challenge, method) {
+    if (method !== 'S256')
+        throw invalidRequest('code_challenge_method must be S256');
+    if (typeof challenge !== 'string' || !PKCE_CHALLENGE_PATTERN.test(challenge)) {
+        throw invalidRequest('code_challenge is invalid');
+    }
+    return challenge;
+}
+export function validatePkceVerifier(verifier) {
+    if (typeof verifier !== 'string' || !PKCE_VERIFIER_PATTERN.test(verifier)) {
+        throw invalidGrant('code_verifier is invalid');
+    }
+    return verifier;
+}
+/** Timing-safe check that `verifier` produced the stored S256 `challenge`. */
+export function verifyPkce(challenge, verifier) {
+    return safeEqual(challenge, createPkceChallenge(verifier));
+}

package/dist/redirect-uri.d.mts

@@ -0,0 +1,15 @@
+export declare const MAX_REDIRECT_URIS = 10;
+export declare const MAX_REDIRECT_URI_LENGTH = 2048;
+/**
+ * Validates registered redirect URIs: HTTPS or loopback HTTP, no wildcards, userinfo or fragments,
+ * no duplicates. By default URIs are serialized; pass `serialize: false` to keep the exact strings
+ * for simple string comparison.
+ */
+export declare function validateRedirectUris(values: unknown, options?: {
+    serialize?: boolean;
+}): string[];
+/**
+ * Exact string match. RFC 8252 loopback registrations (127.0.0.1 and [::1]) may omit the ephemeral
+ * port; every other part of the URI must still match exactly.
+ */
+export declare function matchesRegisteredRedirectUri(requestedUri: string, registeredUris: readonly string[]): boolean;

package/dist/redirect-uri.mjs

@@ -0,0 +1,67 @@
+import { invalidRedirectUri } from './errors.mjs';
+export const MAX_REDIRECT_URIS = 10;
+export const MAX_REDIRECT_URI_LENGTH = 2048;
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+const LOOPBACK_REQUEST = /^http:\/\/(127\.0\.0\.1|\[::1\]):([0-9]+)([/?].*)?$/u;
+/**
+ * Validates registered redirect URIs: HTTPS or loopback HTTP, no wildcards, userinfo or fragments,
+ * no duplicates. By default URIs are serialized; pass `serialize: false` to keep the exact strings
+ * for simple string comparison.
+ */
+export function validateRedirectUris(values, options = {}) {
+    if (!Array.isArray(values) || values.length === 0 || values.length > MAX_REDIRECT_URIS) {
+        throw invalidRedirectUri(`redirect_uris must contain between 1 and ${MAX_REDIRECT_URIS} entries`);
+    }
+    const result = [];
+    for (const value of values)
+        result.push(validateOne(value, options.serialize !== false));
+    if (new Set(result).size !== result.length) {
+        throw invalidRedirectUri('redirect_uris contains duplicates');
+    }
+    return result;
+}
+function validateOne(value, serialize) {
+    if (typeof value !== 'string' ||
+        value.length > MAX_REDIRECT_URI_LENGTH ||
+        /[\s\p{Cc}\p{Z}]/u.test(value)) {
+        throw invalidRedirectUri('redirect_uris contains an invalid URI');
+    }
+    let uri;
+    try {
+        uri = new URL(value);
+    }
+    catch {
+        throw invalidRedirectUri('redirect_uris contains an invalid URI');
+    }
+    if (value.includes('*'))
+        throw invalidRedirectUri('redirect URIs cannot contain wildcards');
+    if (uri.username || uri.password || uri.hash) {
+        throw invalidRedirectUri('redirect URIs cannot contain userinfo or fragments');
+    }
+    const loopbackHttp = uri.protocol === 'http:' && LOOPBACK_HOSTNAMES.has(uri.hostname);
+    if (uri.protocol !== 'https:' && !loopbackHttp) {
+        throw invalidRedirectUri('redirect URIs must use HTTPS or loopback HTTP');
+    }
+    const redirectUri = serialize ? uri.toString() : value;
+    if (redirectUri.length > MAX_REDIRECT_URI_LENGTH) {
+        throw invalidRedirectUri('redirect_uris contains an invalid URI');
+    }
+    return redirectUri;
+}
+/**
+ * Exact string match. RFC 8252 loopback registrations (127.0.0.1 and [::1]) may omit the ephemeral
+ * port; every other part of the URI must still match exactly.
+ */
+export function matchesRegisteredRedirectUri(requestedUri, registeredUris) {
+    if (registeredUris.includes(requestedUri))
+        return true;
+    const requested = LOOPBACK_REQUEST.exec(requestedUri);
+    if (!requested)
+        return false;
+    if (Number(requested[2]) > 65_535)
+        return false;
+    const suffix = requested[3] ?? '';
+    // Registration serializes a portless root URI with a trailing slash.
+    return (registeredUris.includes(`http://${requested[1]}${suffix}`) ||
+        (suffix === '' && registeredUris.includes(`http://${requested[1]}/`)));
+}

package/dist/registration.d.mts

@@ -0,0 +1,32 @@
+import type { ClientAuthMethod, ClientRegistry, HashSecret, ScopePolicy } from './types.mts';
+export interface RegistrationDependencies {
+    registry: ClientRegistry;
+    scopes: ScopePolicy;
+    hashSecret: HashSecret;
+    /** Prefix for generated client ids. Defaults to "client_". */
+    clientIdPrefix?: string;
+    /** Prefix for generated client secrets. Defaults to "secret_". */
+    clientSecretPrefix?: string;
+    /** Used when the request omits token_endpoint_auth_method. Defaults to client_secret_basic. */
+    defaultAuthMethod?: ClientAuthMethod;
+    now?: () => Date;
+}
+/** RFC 7591 section 3.2.1 client information response. */
+export interface RegisteredClient {
+    client_id: string;
+    client_id_issued_at: number;
+    client_name: string;
+    client_secret?: string;
+    client_secret_expires_at?: 0;
+    grant_types: string[];
+    redirect_uris: string[];
+    response_types: string[];
+    scope: string;
+    token_endpoint_auth_method: ClientAuthMethod;
+}
+/**
+ * Validates RFC 7591 metadata and persists the client through the injected registry. The secret is
+ * returned once and only its hash is stored. `context` is passed through to `createClient` so the
+ * application can attach ownership or other policy.
+ */
+export declare function registerClient(input: unknown, deps: RegistrationDependencies, context?: unknown): Promise<RegisteredClient>;

package/dist/registration.mjs

@@ -0,0 +1,56 @@
+import { validateAuthMethod, validateClientName, validateGrantTypes, validateRegistrationObject, validateResponseTypes, } from './client-metadata.mjs';
+import { OAuthProtocolError, invalidClientMetadata } from './errors.mjs';
+import { validateRedirectUris } from './redirect-uri.mjs';
+import { parseScopeParameter } from './scopes.mjs';
+import { generateOpaqueToken } from './secrets.mjs';
+/**
+ * Validates RFC 7591 metadata and persists the client through the injected registry. The secret is
+ * returned once and only its hash is stored. `context` is passed through to `createClient` so the
+ * application can attach ownership or other policy.
+ */
+export async function registerClient(input, deps, context) {
+    const metadata = validateRegistrationObject(input);
+    const clientName = validateClientName(metadata.client_name);
+    const redirectUris = validateRedirectUris(metadata.redirect_uris);
+    const method = validateAuthMethod(metadata.token_endpoint_auth_method, deps.defaultAuthMethod);
+    const grantTypes = validateGrantTypes(metadata.grant_types);
+    const responseTypes = validateResponseTypes(metadata.response_types);
+    const scopes = parseRegistrationScopes(metadata.scope, deps.scopes);
+    const clientId = generateOpaqueToken(deps.clientIdPrefix ?? 'client_', 24);
+    const clientSecret = method === 'client_secret_basic'
+        ? generateOpaqueToken(deps.clientSecretPrefix ?? 'secret_')
+        : undefined;
+    const issuedAt = deps.now?.() ?? new Date();
+    await deps.registry.createClient({
+        clientId,
+        clientName,
+        redirectUris,
+        scopes,
+        tokenEndpointAuthMethod: method,
+        clientSecretHash: clientSecret ? deps.hashSecret('client-secret', clientSecret) : null,
+        grantTypes,
+        responseTypes,
+        issuedAt,
+    }, context);
+    return {
+        client_id: clientId,
+        client_id_issued_at: Math.floor(issuedAt.getTime() / 1000),
+        client_name: clientName,
+        ...(clientSecret ? { client_secret: clientSecret, client_secret_expires_at: 0 } : {}),
+        grant_types: grantTypes,
+        redirect_uris: redirectUris,
+        response_types: responseTypes,
+        scope: scopes.join(' '),
+        token_endpoint_auth_method: method,
+    };
+}
+function parseRegistrationScopes(value, policy) {
+    try {
+        return parseScopeParameter(value, policy).scopes;
+    }
+    catch (err) {
+        if (err instanceof OAuthProtocolError)
+            throw invalidClientMetadata(err.message);
+        throw err;
+    }
+}

package/dist/request.d.mts

@@ -0,0 +1,14 @@
+export interface ClientCredentials {
+    clientId: string;
+    clientSecret?: string;
+}
+/** Parses an RFC 6749 form body, rejecting other media types and repeated parameters. */
+export declare function parseFormBody(contentType: string | undefined, body: Buffer | string): URLSearchParams;
+/** Parses an RFC 7591 registration body, which must be a JSON object. */
+export declare function parseRegistrationBody(contentType: string | undefined, body: Buffer | string): unknown;
+export declare function requiredFormValue(form: URLSearchParams, name: string): string;
+/**
+ * Reads client credentials from HTTP Basic or, for public clients, a bare `client_id`.
+ * `client_secret_post` and mixing both methods are rejected.
+ */
+export declare function parseClientAuthentication(authorization: string | undefined, form: URLSearchParams): ClientCredentials;

package/dist/request.mjs

@@ -0,0 +1,76 @@
+import { invalidClient, invalidClientMetadata, invalidRequest } from './errors.mjs';
+function mediaType(contentType) {
+    return contentType?.split(';', 1)[0]?.trim().toLowerCase();
+}
+/** Parses an RFC 6749 form body, rejecting other media types and repeated parameters. */
+export function parseFormBody(contentType, body) {
+    if (mediaType(contentType) !== 'application/x-www-form-urlencoded') {
+        throw invalidRequest('content type must be form encoded');
+    }
+    const form = new URLSearchParams(typeof body === 'string' ? body : body.toString('utf8'));
+    for (const name of new Set(form.keys())) {
+        if (form.getAll(name).length !== 1)
+            throw invalidRequest(`${name} must not be repeated`);
+    }
+    return form;
+}
+/** Parses an RFC 7591 registration body, which must be a JSON object. */
+export function parseRegistrationBody(contentType, body) {
+    if (mediaType(contentType) !== 'application/json') {
+        throw invalidClientMetadata('registration metadata must use application/json');
+    }
+    try {
+        return JSON.parse(typeof body === 'string' ? body : body.toString('utf8'));
+    }
+    catch {
+        throw invalidClientMetadata('registration metadata must be valid JSON');
+    }
+}
+export function requiredFormValue(form, name) {
+    const value = form.get(name);
+    if (!value)
+        throw invalidRequest(`${name} is required`);
+    return value;
+}
+/**
+ * Reads client credentials from HTTP Basic or, for public clients, a bare `client_id`.
+ * `client_secret_post` and mixing both methods are rejected.
+ */
+export function parseClientAuthentication(authorization, form) {
+    const bodyClientId = form.get('client_id');
+    const bodyClientSecret = form.get('client_secret');
+    if (!authorization) {
+        if (!bodyClientId)
+            throw invalidClient('client_id is required');
+        if (bodyClientSecret !== null)
+            throw invalidClient('client_secret_post is not supported');
+        return { clientId: bodyClientId };
+    }
+    const match = /^basic +(.+)$/i.exec(authorization);
+    if (!match || bodyClientId || bodyClientSecret !== null)
+        throw invalidClient();
+    const decoded = decodeBasicCredentials(match[1]);
+    const separator = decoded.indexOf(':');
+    if (separator < 1)
+        throw invalidClient();
+    return {
+        clientId: decodeFormComponent(decoded.slice(0, separator)),
+        clientSecret: decodeFormComponent(decoded.slice(separator + 1)),
+    };
+}
+function decodeBasicCredentials(encoded) {
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || encoded.length % 4 !== 0)
+        throw invalidClient();
+    const decoded = Buffer.from(encoded, 'base64').toString('utf8');
+    if (decoded.includes('�'))
+        throw invalidClient();
+    return decoded;
+}
+function decodeFormComponent(value) {
+    try {
+        return decodeURIComponent(value.replaceAll('+', ' '));
+    }
+    catch {
+        throw invalidClient();
+    }
+}

package/dist/responses.d.mts

@@ -0,0 +1,18 @@
+import type { OAuthProtocolError } from './errors.mts';
+/** Headers every authorization-server response should carry. */
+export declare const OAUTH_RESPONSE_HEADERS: Readonly<Record<string, string>>;
+export interface OAuthErrorResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: {
+        error: string;
+        error_description: string;
+    };
+}
+/** RFC 6749 section 5.2 error response. A 401 invalid_client names the Basic challenge. */
+export declare function buildOAuthErrorResponse(error: OAuthProtocolError, realm?: string): OAuthErrorResponse;
+/**
+ * RFC 6749 section 4.1.2 / RFC 9207 authorization response URL. Always carries `iss` so a client
+ * talking to several servers can reject a mixed-up response.
+ */
+export declare function buildAuthorizationResponseUrl(redirectUri: string, parameters: Readonly<Record<string, string>>, issuer: string): string;

package/dist/responses.mjs

@@ -0,0 +1,29 @@
+/** Headers every authorization-server response should carry. */
+export const OAUTH_RESPONSE_HEADERS = {
+    'Cache-Control': 'no-store',
+    Pragma: 'no-cache',
+    'Referrer-Policy': 'no-referrer',
+    'X-Robots-Tag': 'noindex, nofollow',
+};
+/** RFC 6749 section 5.2 error response. A 401 invalid_client names the Basic challenge. */
+export function buildOAuthErrorResponse(error, realm = 'token') {
+    return {
+        status: error.status,
+        headers: {
+            ...OAUTH_RESPONSE_HEADERS,
+            ...(error.code === 'invalid_client' ? { 'WWW-Authenticate': `Basic realm="${realm}"` } : {}),
+        },
+        body: { error: error.code, error_description: error.message },
+    };
+}
+/**
+ * RFC 6749 section 4.1.2 / RFC 9207 authorization response URL. Always carries `iss` so a client
+ * talking to several servers can reject a mixed-up response.
+ */
+export function buildAuthorizationResponseUrl(redirectUri, parameters, issuer) {
+    const redirect = new URL(redirectUri);
+    for (const [name, value] of Object.entries(parameters))
+        redirect.searchParams.set(name, value);
+    redirect.searchParams.set('iss', issuer);
+    return redirect.toString();
+}

package/dist/revocation.d.mts

@@ -0,0 +1,12 @@
+import { type ClientCredentials } from './request.mts';
+import type { ClientStore, GrantStore, HashSecret } from './types.mts';
+/**
+ * RFC 7009 revocation. Authenticates the client, then asks the store to revoke the token under
+ * both secret purposes because the token type is not known from the hash. Unknown tokens are not an
+ * error, so callers answer 200 on success.
+ */
+export declare function revokeToken(form: URLSearchParams, credentials: ClientCredentials, deps: {
+    clients: ClientStore;
+    grants: Pick<GrantStore, 'revokeToken'>;
+    hashSecret: HashSecret;
+}): Promise<void>;

package/dist/revocation.mjs

@@ -0,0 +1,13 @@
+import { authenticateClient } from './client-auth.mjs';
+import { requiredFormValue } from './request.mjs';
+/**
+ * RFC 7009 revocation. Authenticates the client, then asks the store to revoke the token under
+ * both secret purposes because the token type is not known from the hash. Unknown tokens are not an
+ * error, so callers answer 200 on success.
+ */
+export async function revokeToken(form, credentials, deps) {
+    const client = await authenticateClient(deps.clients, credentials, deps.hashSecret);
+    const token = requiredFormValue(form, 'token');
+    await deps.grants.revokeToken(deps.hashSecret('refresh-token', token), client.clientId);
+    await deps.grants.revokeToken(deps.hashSecret('access-token', token), client.clientId);
+}

package/dist/scopes.d.mts

@@ -0,0 +1,17 @@
+import type { ProtectedResource, ResolveResource, ScopePolicy } from './types.mts';
+/** Parses a space-delimited scope parameter against the caller's scope catalog. */
+export declare function parseScopeParameter(value: unknown, policy: ScopePolicy): {
+    scopes: string[];
+    audiences: string[];
+};
+/** RFC 8707: accepts exactly one of the canonical resources the server publishes. */
+export declare function resolveRequiredResource(value: unknown, resolveResource: ResolveResource): ProtectedResource;
+export declare function assertScopesMatchResource(audiences: readonly string[], resource: ProtectedResource): void;
+/** RFC 8707 makes `resource` optional at the token endpoint; when present it must match the grant. */
+export declare function assertTokenRequestResource(requested: string | undefined, bound: string): void;
+/**
+ * True when every requested scope is covered by the granted scopes. Unknown scopes (for example a
+ * scope removed from the catalog after registration) never cover anything.
+ */
+export declare function scopesCover(policy: ScopePolicy, granted: readonly string[], requested: readonly string[]): boolean;
+export declare function assertClientMayRequestScopes(policy: ScopePolicy, clientScopes: readonly string[], requested: readonly string[]): void;

package/dist/scopes.mjs

@@ -0,0 +1,53 @@
+import { OAuthProtocolError, invalidTarget } from './errors.mjs';
+/** Parses a space-delimited scope parameter against the caller's scope catalog. */
+export function parseScopeParameter(value, policy) {
+    if (typeof value !== 'string')
+        throw new OAuthProtocolError('invalid_scope', 'scope is required');
+    const result = policy.catalog.validateScopeSet(value.split(' ').filter(Boolean), {
+        surface: policy.surface,
+        allowMixedAudiences: true,
+    });
+    if (!result.valid) {
+        throw new OAuthProtocolError('invalid_scope', `invalid scope set: ${result.code}`);
+    }
+    return { scopes: result.scopes, audiences: result.audiences };
+}
+/** RFC 8707: accepts exactly one of the canonical resources the server publishes. */
+export function resolveRequiredResource(value, resolveResource) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new OAuthProtocolError('invalid_request', 'resource is required');
+    }
+    const resource = resolveResource(value);
+    if (!resource)
+        throw invalidTarget();
+    return resource;
+}
+export function assertScopesMatchResource(audiences, resource) {
+    if (!audiences.every((audience) => audience === resource.audience)) {
+        throw new OAuthProtocolError('invalid_scope', 'scope does not match the requested resource');
+    }
+}
+/** RFC 8707 makes `resource` optional at the token endpoint; when present it must match the grant. */
+export function assertTokenRequestResource(requested, bound) {
+    if (requested !== undefined && requested !== bound)
+        throw invalidTarget();
+}
+/**
+ * True when every requested scope is covered by the granted scopes. Unknown scopes (for example a
+ * scope removed from the catalog after registration) never cover anything.
+ */
+export function scopesCover(policy, granted, requested) {
+    try {
+        return policy.catalog.hasEveryScope(granted, requested);
+    }
+    catch (err) {
+        if (err instanceof RangeError)
+            return false;
+        throw err;
+    }
+}
+export function assertClientMayRequestScopes(policy, clientScopes, requested) {
+    if (!scopesCover(policy, clientScopes, requested)) {
+        throw new OAuthProtocolError('invalid_scope', 'requested scope is not registered for this client');
+    }
+}

package/dist/secrets.d.mts

@@ -0,0 +1,4 @@
+/** Opaque URL-safe random value with a caller-chosen prefix. */
+export declare function generateOpaqueToken(prefix: string, bytes?: number): string;
+/** Constant-time string equality. Digesting first hides length differences from the comparison. */
+export declare function safeEqual(left: string, right: string): boolean;

package/dist/secrets.mjs

@@ -0,0 +1,11 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+/** Opaque URL-safe random value with a caller-chosen prefix. */
+export function generateOpaqueToken(prefix, bytes = 32) {
+    return `${prefix}${randomBytes(bytes).toString('base64url')}`;
+}
+/** Constant-time string equality. Digesting first hides length differences from the comparison. */
+export function safeEqual(left, right) {
+    const a = createHash('sha256').update(left).digest();
+    const b = createHash('sha256').update(right).digest();
+    return timingSafeEqual(a, b);
+}

package/dist/token.d.mts

@@ -0,0 +1,19 @@
+import { type ClientCredentials } from './request.mts';
+import type { ClientStore, GrantStore, HashSecret, ScopePolicy, TokenLifetimes, TokenPrefixes, TokenResponse } from './types.mts';
+export interface TokenDependencies {
+    clients: ClientStore;
+    grants: GrantStore;
+    scopes: ScopePolicy;
+    hashSecret: HashSecret;
+    lifetimes?: Partial<TokenLifetimes>;
+    prefixes?: Partial<TokenPrefixes>;
+    now?: () => Date;
+    /** Generates refresh family ids. Defaults to `crypto.randomUUID`. */
+    newFamilyId?: () => string;
+}
+/**
+ * Handles the token endpoint for `authorization_code` and `refresh_token` grants: authenticates the
+ * client, then verifies the grant inside the store's redeem transaction. Codes and refresh tokens are
+ * single use; the adapter owns the transaction and decides what a failed redemption spends.
+ */
+export declare function exchangeTokenGrant(form: URLSearchParams, credentials: ClientCredentials, deps: TokenDependencies): Promise<TokenResponse>;

package/dist/token.mjs

@@ -0,0 +1,124 @@
+import { authenticateClient } from './client-auth.mjs';
+import { OAuthProtocolError, invalidGrant } from './errors.mjs';
+import { DEFAULT_TOKEN_LIFETIMES, DEFAULT_TOKEN_PREFIXES } from './lifetimes.mjs';
+import { validatePkceVerifier, verifyPkce } from './pkce.mjs';
+import { requiredFormValue } from './request.mjs';
+import { assertTokenRequestResource, parseScopeParameter, scopesCover } from './scopes.mjs';
+import { generateOpaqueToken } from './secrets.mjs';
+/**
+ * Handles the token endpoint for `authorization_code` and `refresh_token` grants: authenticates the
+ * client, then verifies the grant inside the store's redeem transaction. Codes and refresh tokens are
+ * single use; the adapter owns the transaction and decides what a failed redemption spends.
+ */
+export async function exchangeTokenGrant(form, credentials, deps) {
+    const client = await authenticateClient(deps.clients, credentials, deps.hashSecret);
+    const grantType = form.get('grant_type');
+    const resource = form.has('resource') ? requiredFormValue(form, 'resource') : undefined;
+    if (grantType === 'authorization_code') {
+        return exchangeAuthorizationCode(form, client, resource, deps);
+    }
+    if (grantType === 'refresh_token')
+        return exchangeRefreshToken(form, client, resource, deps);
+    throw new OAuthProtocolError('unsupported_grant_type', 'grant_type is not supported');
+}
+async function exchangeAuthorizationCode(form, client, resource, deps) {
+    const code = requiredFormValue(form, 'code');
+    const redirectUri = requiredFormValue(form, 'redirect_uri');
+    const verifier = validatePkceVerifier(form.get('code_verifier'));
+    let response;
+    await deps.grants.redeemAuthorizationCode(deps.hashSecret('authorization-code', code), (record) => {
+        const now = (deps.now?.() ?? new Date()).getTime();
+        assertCodeUsable(record, client, redirectUri, verifier, now);
+        assertTokenRequestResource(resource, record.resource);
+        const lifetimes = { ...DEFAULT_TOKEN_LIFETIMES, ...deps.lifetimes };
+        const issued = buildTokens({
+            client,
+            subject: record,
+            familyId: (deps.newFamilyId ?? crypto.randomUUID.bind(crypto))(),
+            generation: 0,
+            refreshExpiresAt: new Date(now + lifetimes.refreshTokenMs),
+            now,
+            deps,
+        });
+        response = issued.response;
+        return issued.tokens;
+    });
+    return response;
+}
+function assertCodeUsable(record, client, redirectUri, verifier, now) {
+    if (!record ||
+        record.replayed ||
+        record.clientId !== client.clientId ||
+        record.expiresAt.getTime() <= now ||
+        record.redirectUri !== redirectUri ||
+        !verifyPkce(record.codeChallenge, verifier)) {
+        throw invalidGrant('authorization code is invalid');
+    }
+}
+async function exchangeRefreshToken(form, client, resource, deps) {
+    const token = requiredFormValue(form, 'refresh_token');
+    const requestedScope = form.has('scope') ? requiredFormValue(form, 'scope') : undefined;
+    let response;
+    await deps.grants.redeemRefreshToken(deps.hashSecret('refresh-token', token), (record) => {
+        const now = (deps.now?.() ?? new Date()).getTime();
+        if (!record ||
+            record.replayed ||
+            record.revoked ||
+            record.clientId !== client.clientId ||
+            record.expiresAt.getTime() <= now ||
+            record.familyExpiresAt.getTime() <= now) {
+            throw invalidGrant('refresh token is invalid');
+        }
+        assertTokenRequestResource(resource, record.resource);
+        let scopes = record.scopes;
+        if (requestedScope !== undefined) {
+            const requested = parseScopeParameter(requestedScope, deps.scopes).scopes;
+            if (!scopesCover(deps.scopes, record.scopes, requested)) {
+                throw new OAuthProtocolError('invalid_scope', 'scope exceeds the original grant');
+            }
+            scopes = requested;
+        }
+        const issued = buildTokens({
+            client,
+            subject: { ...record, scopes },
+            familyId: record.familyId,
+            generation: record.generation + 1,
+            refreshExpiresAt: record.familyExpiresAt,
+            now,
+            deps,
+        });
+        response = issued.response;
+        return issued.tokens;
+    });
+    return response;
+}
+function buildTokens(input) {
+    const { client, subject, deps, now } = input;
+    const prefixes = { ...DEFAULT_TOKEN_PREFIXES, ...deps.prefixes };
+    const lifetimes = { ...DEFAULT_TOKEN_LIFETIMES, ...deps.lifetimes };
+    const accessToken = generateOpaqueToken(prefixes.accessToken);
+    const refreshToken = generateOpaqueToken(prefixes.refreshToken);
+    // An access token never outlives the refresh family that authorizes it.
+    const accessExpiresAt = new Date(Math.min(now + lifetimes.accessTokenMs, input.refreshExpiresAt.getTime()));
+    const tokens = {
+        clientId: client.clientId,
+        grantId: subject.grantId,
+        subject: subject.subject,
+        familyId: input.familyId,
+        generation: input.generation,
+        resource: subject.resource,
+        scopes: subject.scopes,
+        accessTokenHash: deps.hashSecret('access-token', accessToken),
+        accessExpiresAt,
+        refreshTokenHash: deps.hashSecret('refresh-token', refreshToken),
+        refreshExpiresAt: input.refreshExpiresAt,
+    };
+    const response = {
+        access_token: accessToken,
+        expires_in: Math.max(0, Math.floor((accessExpiresAt.getTime() - now) / 1000)),
+        refresh_token: refreshToken,
+        scope: subject.scopes.join(' '),
+        token_type: 'Bearer',
+    };
+    return { tokens, response };
+}

package/dist/types.d.mts

@@ -0,0 +1,123 @@
+import type { ScopeCatalog } from '@vouchington/utils/scopes';
+export type ClientAuthMethod = 'none' | 'client_secret_basic';
+/** Distinct purposes let the application derive independent hashes for each secret kind. */
+export type SecretPurpose = 'client-secret' | 'access-token' | 'refresh-token' | 'authorization-code';
+/** Application-supplied one-way hash (for example a keyed HMAC) used for every stored secret. */
+export type HashSecret = (purpose: SecretPurpose, value: string) => string;
+export interface ScopePolicy {
+    catalog: ScopeCatalog;
+    /** Catalog surface that OAuth clients may request, for example "oauth". */
+    surface: string;
+}
+/** RFC 8707 protected resource. `audience` is matched against the scope catalog audiences. */
+export interface ProtectedResource {
+    url: string;
+    audience: string;
+}
+export type ResolveResource = (value: string) => ProtectedResource | null;
+export interface OAuthClient {
+    clientId: string;
+    clientName: string;
+    redirectUris: readonly string[];
+    scopes: readonly string[];
+    tokenEndpointAuthMethod: ClientAuthMethod;
+    /** Hash produced by `HashSecret('client-secret', ...)`; null for public clients. */
+    clientSecretHash: string | null;
+}
+export interface NewOAuthClient extends OAuthClient {
+    grantTypes: string[];
+    responseTypes: string[];
+    issuedAt: Date;
+}
+/** Returns only clients that may currently authorize; revoked or ineligible clients are null. */
+export interface ClientStore {
+    findClient(clientId: string): Promise<OAuthClient | null>;
+}
+export interface ClientRegistry extends ClientStore {
+    /** `context` is the opaque value the application passed to `registerClient`, such as an owner. */
+    createClient(client: NewOAuthClient, context?: unknown): Promise<void>;
+}
+export interface AuthorizationCodeRecord {
+    clientId: string;
+    redirectUri: string;
+    resource: string;
+    scopes: readonly string[];
+    codeChallenge: string;
+    grantId: string;
+    subject: string;
+    expiresAt: Date;
+    /** True when the code had already been consumed before this call. */
+    replayed: boolean;
+}
+export interface RefreshTokenRecord {
+    clientId: string;
+    grantId: string;
+    subject: string;
+    familyId: string;
+    generation: number;
+    resource: string;
+    scopes: readonly string[];
+    /** Expiry of the whole refresh family; rotated refresh tokens never extend it. */
+    familyExpiresAt: Date;
+    expiresAt: Date;
+    revoked: boolean;
+    /** True when the token had already been rotated before this call. */
+    replayed: boolean;
+}
+export interface IssuedTokens {
+    clientId: string;
+    grantId: string;
+    subject: string;
+    familyId: string;
+    generation: number;
+    resource: string;
+    scopes: readonly string[];
+    accessTokenHash: string;
+    accessExpiresAt: Date;
+    refreshTokenHash: string;
+    refreshExpiresAt: Date;
+}
+export interface AuthorizationCodeGrant {
+    codeHash: string;
+    clientId: string;
+    redirectUri: string;
+    resource: string;
+    scopes: readonly string[];
+    codeChallenge: string;
+    grantId: string;
+    subject: string;
+    expiresAt: Date;
+}
+export interface GrantStore {
+    saveAuthorizationCode(code: AuthorizationCodeGrant): Promise<void>;
+    /**
+     * Looks up the code and calls `redeem` with the record (or null when unknown) inside the
+     * adapter's own transaction, holding a lock so concurrent exchanges cannot both succeed. If
+     * `redeem` returns tokens, the adapter must persist them and mark the code spent atomically. If
+     * it throws, no tokens may be persisted and the error must propagate; the adapter decides whether
+     * a failed attempt spends the code. An already-spent code is passed with `replayed: true` so the
+     * adapter can revoke what it issued.
+     */
+    redeemAuthorizationCode(codeHash: string, redeem: (record: AuthorizationCodeRecord | null) => IssuedTokens | Promise<IssuedTokens>): Promise<void>;
+    /** Same contract for refresh tokens: persist the rotated pair and spend the old token atomically. */
+    redeemRefreshToken(tokenHash: string, redeem: (record: RefreshTokenRecord | null) => IssuedTokens | Promise<IssuedTokens>): Promise<void>;
+    /** Revoke the access or refresh token (and its family) when it belongs to `clientId`. */
+    revokeToken(tokenHash: string, clientId: string): Promise<void>;
+}
+export interface TokenResponse {
+    access_token: string;
+    expires_in: number;
+    refresh_token: string;
+    scope: string;
+    token_type: 'Bearer';
+}
+export interface TokenLifetimes {
+    authorizationCodeMs: number;
+    accessTokenMs: number;
+    refreshTokenMs: number;
+}
+export interface TokenPrefixes {
+    authorizationCode: string;
+    accessToken: string;
+    refreshToken: string;
+}

package/dist/types.mjs

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

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@vouchington/oauth-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Generic OAuth 2.0 authorization-server building blocks with injected stores (RFC 6749, 7591, 7636, 8414).",
+  "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/oauth-server#readme",
+  "license": "MIT",
+  "author": "Jonathan Ong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vouchington/vouchington-platform.git",
+    "directory": "packages/oauth-server"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@vouchington/utils": "^0.7.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json"
+  }
 }