@dereekb/oauth-resource 14.4.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@dereekb/oauth-resource",
+  "version": "14.4.0",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    "./express": {
+      "types": "./express/index.d.ts",
+      "import": "./express/index.esm.js",
+      "default": "./express/index.esm.js"
+    },
+    "./firebase": {
+      "types": "./firebase/index.d.ts",
+      "import": "./firebase/index.esm.js",
+      "default": "./firebase/index.esm.js"
+    },
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.esm.js",
+      "default": "./index.esm.js"
+    }
+  },
+  "peerDependencies": {
+    "@dereekb/firebase": "14.4.0",
+    "@dereekb/util": "14.4.0",
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
+    "firebase": "^12.18.0",
+    "jose": "^6.2.12",
+    "make-error": "^1.3.6"
+  },
+  "devDependencies": {
+    "supertest": "^7.2.2"
+  },
+  "peerDependenciesMeta": {
+    "@dereekb/firebase": {
+      "optional": true
+    },
+    "cors": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "firebase": {
+      "optional": true
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.esm.js",
+  "types": "./index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/src/lib/auth/index.d.ts

@@ -0,0 +1 @@
+export * from './oauth.resource.auth';

package/src/lib/auth/oauth.resource.auth.d.ts

@@ -0,0 +1,55 @@
+import { type UnixDateTimeSecondsNumber } from '@dereekb/util';
+import { type VerifiedBearer } from '../verify/verify.bearer';
+/**
+ * The verified caller attached to a request by a resource server's bearer middleware.
+ *
+ * Structurally identical to the MCP TypeScript SDK's `AuthInfo` (`@modelcontextprotocol/server`),
+ * so an MCP host can assign one to `req.auth` and the SDK's `toNodeHandler` forwards it to the
+ * handler as `authInfo` with no cast. The type is declared locally on purpose: taking an
+ * SDK peer dependency just to borrow a five-field interface would pull the whole MCP install
+ * graph into a service that only needs to check a signature.
+ */
+export interface OAuthResourceAuthInfo {
+    /**
+     * The raw bearer token as presented.
+     */
+    readonly token: string;
+    /**
+     * The OAuth client the token was issued to (`client_id`), or a stand-in when the token carries
+     * no client (see {@link oauthResourceAuthInfoForVerifiedBearer}).
+     */
+    readonly clientId: string;
+    /**
+     * Scopes granted on the token, split out of the space-delimited `scope` claim.
+     */
+    readonly scopes: string[];
+    /**
+     * Token expiry, as unix epoch seconds (the `exp` claim).
+     */
+    readonly expiresAt?: UnixDateTimeSecondsNumber;
+    /**
+     * Anything else the resource server wants to carry through to its handlers.
+     */
+    readonly extra?: Record<string, unknown>;
+}
+/**
+ * Fallback `clientId` used for a verified Firebase ID token, which names no OAuth client.
+ */
+export declare const FIREBASE_AUTH_INFO_CLIENT_ID = "firebase";
+/**
+ * Splits a space-delimited OAuth `scope` claim into its entries.
+ *
+ * @param scope - The raw `scope` claim value, if any.
+ * @returns The scope entries, empty when the claim is absent or not a string.
+ */
+export declare function scopesFromScopeClaim(scope: unknown): string[];
+/**
+ * Converts a {@link VerifiedBearer} into the {@link OAuthResourceAuthInfo} attached to the request.
+ *
+ * A token with no `client_id` claim is not from an OAuth client: a Firebase ID token reports
+ * {@link FIREBASE_AUTH_INFO_CLIENT_ID}, and any other issuer falls back to the subject.
+ *
+ * @param verified - The verified bearer token.
+ * @returns The auth info.
+ */
+export declare function oauthResourceAuthInfoForVerifiedBearer(verified: VerifiedBearer): OAuthResourceAuthInfo;

package/src/lib/challenge/bearer.challenge.d.ts

@@ -0,0 +1,73 @@
+import { type Maybe } from '@dereekb/util';
+import { type OAuthResourceErrorCode } from '../error/oauth.resource.error';
+/**
+ * The RFC 6750 §3 `error` codes a resource server emits on a `WWW-Authenticate: Bearer` challenge.
+ */
+export type BearerChallengeErrorCode = 'invalid_request' | 'invalid_token' | 'insufficient_scope';
+export interface BuildBearerChallengeConfig {
+    /**
+     * The RFC 6750 `error` token. Any string is accepted so a consumer can emit a code this union
+     * does not enumerate.
+     */
+    readonly error: BearerChallengeErrorCode | string;
+    /**
+     * Protection space name. Omitted by default — a resource server that serves exactly one
+     * protection space does not need it.
+     */
+    readonly realm?: Maybe<string>;
+    /**
+     * Absolute URL of the RFC 9728 protected-resource metadata document, so a client can discover
+     * the authorization server from the challenge alone rather than relying on origin-rooted
+     * path-walkback (which 404s whenever the resource is not mounted at the origin root).
+     */
+    readonly resourceMetadataUrl?: Maybe<string>;
+    /**
+     * Human-readable explanation (`error_description`).
+     */
+    readonly errorDescription?: Maybe<string>;
+    /**
+     * Space-delimited scopes required for the request, meaningful with `insufficient_scope`.
+     */
+    readonly scope?: Maybe<string>;
+}
+export interface BearerChallengeErrorCodeConfig {
+    /**
+     * The failure's code.
+     */
+    readonly code: OAuthResourceErrorCode;
+    /**
+     * Whether the request presented a bearer token at all.
+     */
+    readonly hadToken: boolean;
+}
+/**
+ * Builds the `WWW-Authenticate: Bearer ...` challenge string emitted alongside a 401 / 403 on an
+ * OAuth-protected route.
+ *
+ * Per RFC 6750 §3 / RFC 7235, auth-params are comma-separated. Parameter order is not significant
+ * to a client; this emits `realm`, `resource_metadata`, `error`, `error_description`, `scope`.
+ *
+ * @param config - The error token plus the optional realm / metadata / description / scope params.
+ * @returns The header value, e.g. `Bearer resource_metadata="…", error="invalid_token"`.
+ */
+export declare function buildBearerChallenge(config: BuildBearerChallengeConfig): string;
+/**
+ * Selects the RFC 6750 §3 `error` token for a failure: `insufficient_scope` for a policy (403)
+ * failure, `invalid_token` when a token was presented but failed, and `invalid_request` when the
+ * request carried no token at all.
+ *
+ * @param config - The failure code and whether a token was presented.
+ * @returns The RFC 6750 error token.
+ */
+export declare function bearerChallengeErrorForCode(config: BearerChallengeErrorCodeConfig): BearerChallengeErrorCode;
+/**
+ * The `Authorization` header scheme prefix a bearer token is presented with.
+ */
+export declare const BEARER_AUTHORIZATION_PREFIX = "Bearer ";
+/**
+ * Reads the raw bearer token out of an `Authorization` header value.
+ *
+ * @param header - The raw `Authorization` header value, if any.
+ * @returns The token, or `undefined` when the header is absent, uses another scheme, or is empty.
+ */
+export declare function readBearerToken(header: Maybe<string>): string | undefined;

package/src/lib/challenge/index.d.ts

@@ -0,0 +1 @@
+export * from './bearer.challenge';

package/src/lib/error/index.d.ts

@@ -0,0 +1 @@
+export * from './oauth.resource.error';

package/src/lib/error/oauth.resource.error.d.ts

@@ -0,0 +1,76 @@
+import { type CodedError, type Maybe } from '@dereekb/util';
+import { BaseError } from 'make-error';
+/**
+ * Stable error code raised by the resource-server verification layer.
+ *
+ * `unauthorized` maps to a 401 (the token is missing / malformed / untrusted / invalid) and
+ * `forbidden` to a 403 (the token verified but failed a policy gate). The distinction is what
+ * selects the RFC 6750 challenge's `error` token — see {@link bearerChallengeErrorForCode}.
+ */
+export type OAuthResourceErrorCode = 'unauthorized' | 'forbidden';
+/**
+ * HTTP status paired with each {@link OAuthResourceErrorCode}.
+ */
+export declare const OAUTH_RESOURCE_ERROR_STATUS_CODES: Readonly<Record<OAuthResourceErrorCode, number>>;
+export interface OAuthResourceErrorInput {
+    readonly code: OAuthResourceErrorCode;
+    readonly message: string;
+    /**
+     * HTTP status. Defaults to the status paired with `code` in {@link OAUTH_RESOURCE_ERROR_STATUS_CODES}.
+     */
+    readonly status?: Maybe<number>;
+    /**
+     * Extra machine-readable context carried onto the error envelope.
+     */
+    readonly details?: Maybe<Record<string, unknown>>;
+}
+/**
+ * The default JSON body emitted for a rejected request.
+ */
+export interface OAuthResourceErrorEnvelope {
+    readonly error: {
+        readonly code: OAuthResourceErrorCode;
+        readonly message: string;
+        readonly details?: Record<string, unknown>;
+    };
+}
+/**
+ * Error raised when a bearer token fails verification or a policy gate.
+ *
+ * Consumers that already have their own API error type do not have to catch and re-wrap this one:
+ * pass an {@link OAuthResourceErrorFactory} on the verification options and the verifier throws
+ * that type instead.
+ */
+export declare class OAuthResourceError extends BaseError implements CodedError {
+    readonly code: OAuthResourceErrorCode;
+    readonly status: number;
+    readonly details?: Record<string, unknown>;
+    constructor(input: OAuthResourceErrorInput);
+    /**
+     * Builds the default JSON error body for this error.
+     *
+     * @returns The error envelope.
+     */
+    toEnvelope(): OAuthResourceErrorEnvelope;
+}
+/**
+ * Creates the error thrown when verification fails.
+ *
+ * The seam that keeps this package error-type agnostic: supply one to map every rejection onto an
+ * app's own error type (and therefore its own response envelope).
+ */
+export type OAuthResourceErrorFactory = (input: OAuthResourceErrorInput) => Error;
+/**
+ * Default {@link OAuthResourceErrorFactory}, producing an {@link OAuthResourceError}.
+ *
+ * @param input - The code, message, status, and details of the failure.
+ * @returns The error to throw.
+ */
+export declare const defaultOAuthResourceErrorFactory: OAuthResourceErrorFactory;
+/**
+ * Returns true when the input is an {@link OAuthResourceError}.
+ *
+ * @param error - The value to test.
+ * @returns Whether the value is an {@link OAuthResourceError}.
+ */
+export declare function isOAuthResourceError(error: unknown): error is OAuthResourceError;

package/src/lib/index.d.ts

@@ -0,0 +1,6 @@
+export * from './auth';
+export * from './challenge';
+export * from './error';
+export * from './issuer';
+export * from './metadata';
+export * from './verify';

package/src/lib/issuer/index.d.ts

@@ -0,0 +1 @@
+export * from './issuer.profile';

package/src/lib/issuer/issuer.profile.d.ts

@@ -0,0 +1,98 @@
+import { type Maybe } from '@dereekb/util';
+import { type JWTVerifyGetKey } from 'jose';
+/**
+ * Which family a trusted issuer belongs to.
+ *
+ * `firebase` is a Firebase Auth ID token issuer (`https://securetoken.google.com/<projectId>`);
+ * `oidc` is any OAuth 2.0 / OpenID Connect authorization server — a dbx-components
+ * `@dereekb/firebase-server/oidc` provider, Auth0, Okta, and so on.
+ */
+export type IssuerProfileKind = 'firebase' | 'oidc';
+/**
+ * One trusted token issuer: how to recognize its tokens (`iss`), which
+ * audiences it may name, and how to fetch its verification keys.
+ */
+export interface IssuerProfile {
+    readonly kind: IssuerProfileKind;
+    readonly issuer: string;
+    readonly audiences: readonly string[];
+    /**
+     * Resolves the JWKS key getter. Lazy so a discovery failure at boot does
+     * not take the service down — it surfaces as a 401 on the request instead.
+     */
+    readonly getKey: () => Promise<JWTVerifyGetKey>;
+}
+/**
+ * Trusted issuer profiles, keyed by their `iss` value. The `iss` claim on an incoming token
+ * selects the profile that verifies it.
+ */
+export type IssuerProfiles = ReadonlyMap<string, IssuerProfile>;
+/**
+ * Google's public JWKS for Firebase ID tokens (the `securetoken` signer).
+ */
+export declare const FIREBASE_SECURETOKEN_JWKS_URL = "https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com";
+/**
+ * Path appended to an issuer to read its OpenID Connect discovery document.
+ */
+export declare const OPENID_CONFIGURATION_PATH = "/.well-known/openid-configuration";
+/**
+ * Builds the `iss` value Firebase stamps on a project's ID tokens.
+ *
+ * @param projectId - The Firebase project id.
+ * @returns The issuer URL.
+ */
+export declare function firebaseIssuerForProject(projectId: string): string;
+/**
+ * An OIDC issuer to trust. The string form takes the shared `audiences` and discovers its JWKS;
+ * the object form overrides either.
+ */
+export type BuildIssuerProfilesOidcIssuerInput = string | OidcIssuerProfileConfig;
+export interface OidcIssuerProfileConfig {
+    readonly issuer: string;
+    /**
+     * Audiences accepted on this issuer's tokens. Defaults to {@link BuildIssuerProfilesConfig.audiences}.
+     */
+    readonly audiences?: Maybe<readonly string[]>;
+    /**
+     * Overrides how this issuer's verification keys are resolved, bypassing discovery.
+     *
+     * This is the seam the whole design rests on: a test injects `createLocalJWKSet()`, and an
+     * authorization server verifying its OWN tokens in-process injects its local key set rather
+     * than making an HTTP call back to itself.
+     */
+    readonly getKey?: Maybe<() => Promise<JWTVerifyGetKey>>;
+}
+export interface BuildIssuerProfilesConfig {
+    /**
+     * Firebase project ids whose ID tokens are trusted. Each contributes a `firebase` profile whose
+     * only accepted audience is the project id itself.
+     */
+    readonly firebaseProjectIds?: Maybe<readonly string[]>;
+    /**
+     * OAuth/OIDC issuers to trust.
+     */
+    readonly oidcIssuers?: Maybe<readonly BuildIssuerProfilesOidcIssuerInput[]>;
+    /**
+     * Audiences accepted on OIDC tokens — this resource server's identity. Typically its origin
+     * plus any RFC 8707 resource-indicator URLs pointed at it.
+     */
+    readonly audiences?: Maybe<readonly string[]>;
+    /**
+     * JWKS URL used for the Firebase leg. Defaults to {@link FIREBASE_SECURETOKEN_JWKS_URL}.
+     */
+    readonly firebaseJwksUrl?: Maybe<string>;
+    /**
+     * `fetch` used for OIDC discovery; injected in specs. Defaults to the global.
+     */
+    readonly fetch?: Maybe<typeof fetch>;
+}
+/**
+ * Builds the issuer → profile map the bearer verifier dispatches on: one
+ * Firebase profile per trusted project id (sharing Google's JWKS) and one
+ * OIDC profile per trusted issuer (JWKS discovered from
+ * `{iss}/.well-known/openid-configuration`, falling back to `{iss}/jwks`).
+ *
+ * @param config - The trusted project ids / issuers / audiences + optional fetch.
+ * @returns Profiles keyed by their `iss` value.
+ */
+export declare function buildIssuerProfiles(config: BuildIssuerProfilesConfig): IssuerProfiles;

package/src/lib/metadata/index.d.ts

@@ -0,0 +1 @@
+export * from './protected-resource.metadata';

package/src/lib/metadata/protected-resource.metadata.d.ts

@@ -0,0 +1,64 @@
+import { type Maybe } from '@dereekb/util';
+/**
+ * RFC 9728 §3 well-known path for OAuth 2.0 protected-resource metadata.
+ */
+export declare const OAUTH_PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+/**
+ * Builds the RFC 9728 §3.1 path-suffixed well-known path for a resource — the form MCP clients
+ * try first (e.g. `/.well-known/oauth-protected-resource/mcp` for a resource served at `/mcp`).
+ *
+ * @param resourcePath - The resource's path on the origin, with or without a leading slash.
+ * @returns The path-suffixed well-known path.
+ */
+export declare function oauthProtectedResourcePathForResource(resourcePath: string): string;
+/**
+ * RFC 9728 protected-resource metadata document.
+ *
+ * Snake-cased because it is the wire document, served verbatim.
+ */
+export interface OAuthProtectedResourceMetadata {
+    readonly resource: string;
+    readonly authorization_servers: readonly string[];
+    readonly scopes_supported: readonly string[];
+    readonly bearer_methods_supported: readonly string[];
+    readonly resource_documentation?: string;
+    readonly resource_name?: string;
+}
+export interface BuildProtectedResourceMetadataConfig {
+    /**
+     * The resource identifier clients pass as the RFC 8707 `resource` parameter, e.g.
+     * `https://db.example.com/mcp`.
+     */
+    readonly resource: string;
+    /**
+     * Issuers of the authorization servers that may issue tokens for this resource.
+     */
+    readonly authorizationServers: readonly string[];
+    /**
+     * Scopes this resource understands, advertised to clients so they can request them up-front.
+     */
+    readonly scopesSupported?: Maybe<readonly string[]>;
+    /**
+     * How a bearer token may be presented. Defaults to `['header']` — the only method this package's
+     * middleware reads.
+     */
+    readonly bearerMethodsSupported?: Maybe<readonly string[]>;
+    /**
+     * Human-readable name of the resource.
+     */
+    readonly resourceName?: Maybe<string>;
+    /**
+     * URL of human-readable documentation for the resource.
+     */
+    readonly resourceDocumentation?: Maybe<string>;
+}
+/**
+ * Builds the RFC 9728 protected-resource metadata document.
+ *
+ * Hand-rolled deliberately: the MCP SDK's builder also wants the authorization-server metadata
+ * document, which a resource server never hosts — it points at one instead.
+ *
+ * @param config - The resource identifier, its authorization servers, and the advertised scopes.
+ * @returns The metadata document.
+ */
+export declare function buildProtectedResourceMetadata(config: BuildProtectedResourceMetadataConfig): OAuthProtectedResourceMetadata;

package/src/lib/verify/index.d.ts

@@ -0,0 +1 @@
+export * from './verify.bearer';

package/src/lib/verify/verify.bearer.d.ts

@@ -0,0 +1,95 @@
+import { type Maybe, type PromiseOrValue, type Seconds } from '@dereekb/util';
+import { type JWTPayload } from 'jose';
+import { type OAuthResourceErrorFactory } from '../error/oauth.resource.error';
+import { type IssuerProfile, type IssuerProfileKind, type IssuerProfiles } from '../issuer/issuer.profile';
+/**
+ * A verified bearer token: which issuer profile matched, the subject, and
+ * the full claim set.
+ */
+export interface VerifiedBearer {
+    readonly kind: IssuerProfileKind;
+    readonly issuer: string;
+    readonly subject: string;
+    readonly claims: JWTPayload;
+    readonly token: string;
+}
+/**
+ * Additional policy applied to a token that already passed signature + standard claim validation.
+ *
+ * Returning `false` rejects the token as `forbidden` (403 / `insufficient_scope`), not
+ * `unauthorized` — the token is valid, the caller is simply not allowed.
+ */
+export type VerifyBearerClaimPredicate = (claims: JWTPayload, profile: IssuerProfile) => PromiseOrValue<boolean>;
+export interface VerifyBearerOptions {
+    readonly profiles: IssuerProfiles;
+    /**
+     * Accept unsigned (`alg: none`) Firebase emulator ID tokens. Never set this in production —
+     * an unsigned token proves nothing.
+     */
+    readonly firebaseEmulator?: Maybe<boolean>;
+    /**
+     * Claims that must be present and truthy on the token, e.g. an app's onboarded flag. A missing
+     * claim rejects with `forbidden`.
+     */
+    readonly requiredClaims?: Maybe<readonly string[]>;
+    /**
+     * Arbitrary additional policy gate, evaluated after {@link requiredClaims}.
+     */
+    readonly claimPredicate?: Maybe<VerifyBearerClaimPredicate>;
+    /**
+     * Which issuer kinds {@link requiredClaims} / {@link claimPredicate} apply to.
+     *
+     * Defaults to {@link DEFAULT_BEARER_CLAIM_GATE_KINDS} (`['firebase']`): app-account claims live
+     * on a Firebase ID token, while an OAuth access token from the authorization server carries
+     * scopes instead and is gated by scope, not by account claims.
+     */
+    readonly claimGateKinds?: Maybe<readonly IssuerProfileKind[]>;
+    /**
+     * Signing algorithms accepted. Defaults to {@link BEARER_ALGORITHMS}.
+     */
+    readonly algorithms?: Maybe<readonly string[]>;
+    /**
+     * Leeway applied to `exp` / `nbf` / `iat` / `auth_time`. Defaults to
+     * {@link BEARER_CLOCK_TOLERANCE_SECONDS}.
+     */
+    readonly clockToleranceSeconds?: Maybe<Seconds>;
+    /**
+     * Builds the thrown error, letting a consumer surface its own API error type.
+     * Defaults to {@link defaultOAuthResourceErrorFactory}.
+     */
+    readonly errorFactory?: Maybe<OAuthResourceErrorFactory>;
+    /**
+     * Clock source in seconds; injected in specs.
+     */
+    readonly nowSeconds?: Maybe<() => number>;
+}
+/**
+ * Leeway applied to `exp` / `nbf` / `iat` / `auth_time`.
+ */
+export declare const BEARER_CLOCK_TOLERANCE_SECONDS: Seconds;
+/**
+ * The signing algorithms accepted by default (Firebase and oidc-provider both sign RS256).
+ */
+export declare const BEARER_ALGORITHMS: readonly string[];
+/**
+ * Issuer kinds the claim gates apply to by default.
+ */
+export declare const DEFAULT_BEARER_CLAIM_GATE_KINDS: readonly IssuerProfileKind[];
+/**
+ * Verifies a bearer JWT against the trusted issuer profiles: the `iss`
+ * claim selects the profile, the profile's JWKS verifies the RS256
+ * signature, and jose enforces `iss` / `aud` / `exp` / `nbf` / `iat` with a
+ * 60 s tolerance. Firebase tokens additionally get the `auth_time` sanity
+ * check and the optional claim gates. Under the Firebase emulator an
+ * unsigned (`alg: none`) token is accepted after the same claim checks —
+ * the emulator never signs, and the flag is never set in production.
+ *
+ * Scopes are deliberately NOT enforced here: a resource server's scope policy is per-route, so it
+ * belongs to the caller (see the Express adapter's `requiredScopes`).
+ *
+ * @param token - The raw bearer token.
+ * @param options - Trusted profiles + policy.
+ * @returns The verified token.
+ * @throws {OAuthResourceError} `unauthorized` for any malformed / untrusted / invalid token; `forbidden` when a claim gate fails. Replaceable via {@link VerifyBearerOptions.errorFactory}.
+ */
+export declare function verifyBearerJwt(token: string, options: VerifyBearerOptions): Promise<VerifiedBearer>;