@atlasauth/backend 0.14.1 → 0.16.0

package/dist/oauth-resource.d.ts

@@ -0,0 +1,225 @@
+import { type Jwks } from './jwks-cache';
+/**
+ * Protecting YOUR API — or your own MCP server — with access tokens Atlas
+ * issues to OAuth clients (authorization code, device, client credentials,
+ * token exchange). Atlas is the authorization server; your API is the
+ * resource server. This module:
+ *  - verifies the access token locally against the instance JWKS (cached;
+ *    no call to Atlas on the hot path): signature, `iss`, `exp`/`nbf`, that it
+ *    IS an access token, and that its `aud` names your API (RFC 8707);
+ *  - enforces required scopes;
+ *  - enforces sender constraint: a DPoP-bound token (`cnf.jkt`) must arrive
+ *    with a valid DPoP proof for the same key (RFC 9449), and is never accepted
+ *    as a plain Bearer token;
+ *  - answers failures with the RFC 6750 / RFC 9728 `WWW-Authenticate`
+ *    challenge (`resource_metadata`, `insufficient_scope` + the scopes needed),
+ *    which is exactly what an MCP client needs to discover how to sign in;
+ *  - builds the RFC 9728 protected-resource metadata document to serve at
+ *    `/.well-known/oauth-protected-resource` on your API's host.
+ *  - accepts OPAQUE access tokens too (an API, client or instance set to the
+ *    `opaque` format): with `introspection` configured, a token that is not a
+ *    JWT is validated at Atlas's introspection endpoint (RFC 7662) with your
+ *    API's own client credentials, and the answer is cached briefly;
+ * Framework-agnostic: hand it any request with `method`, `url` and `headers`.
+ */
+/** Clock skew tolerated on `exp`/`nbf` and on DPoP proof `iat`. */
+export declare const ACCESS_TOKEN_CLOCK_SKEW_SECONDS = 5;
+/** How old a DPoP proof may be. */
+export declare const DPOP_PROOF_MAX_AGE_SECONDS = 300;
+export interface AccessTokenClaims {
+    iss: string;
+    sub: string;
+    aud?: string | string[];
+    exp: number;
+    iat?: number;
+    scope?: string;
+    client_id?: string;
+    azp?: string;
+    permissions?: string[];
+    cnf?: {
+        jkt?: string;
+        'x5t#S256'?: string;
+    };
+    token_use?: string;
+    [claim: string]: unknown;
+}
+export interface ResourceRequestLike {
+    method?: string;
+    /** Absolute URL, or a path (combined with `resource` origin for the DPoP `htu` check). */
+    url?: string;
+    headers: Record<string, string | string[] | undefined> | {
+        get(name: string): string | null;
+    };
+}
+/** Replay guard for DPoP proof `jti`s. The in-memory one is for a single process. */
+export interface DpopReplayStore {
+    /** Record `jti` until `expiresAt` (ms); return false when it was already seen. */
+    claim(jti: string, expiresAt: number): Promise<boolean> | boolean;
+}
+/**
+ * Server-provided DPoP nonces (RFC 9449 §8). `current()` is the nonce the API
+ * hands out in the `DPoP-Nonce` response header; `valid()` accepts the nonces
+ * still in force. A verifier given a source requires every DPoP proof to carry
+ * one, answering `use_dpop_nonce` (with a fresh nonce) otherwise.
+ */
+export interface DpopNonceSource {
+    current(): string | Promise<string>;
+    valid(nonce: string): boolean | Promise<boolean>;
+}
+/**
+ * An in-process nonce source: a random nonce per window; the current and the
+ * previous window's nonce are accepted. Use it when one process serves the API
+ * (or with sticky routing); behind several processes, use
+ * {@link hmacDpopNonceSource} with a shared secret.
+ */
+export declare function memoryDpopNonceSource(options?: {
+    windowSeconds?: number;
+    now?: () => number;
+}): DpopNonceSource;
+/**
+ * A stateless nonce source shared by every process holding the same secret (at
+ * least 32 bytes): the nonce for a window is base64url(HMAC-SHA256(secret,
+ * "atlas-dpop-nonce:" ‖ uint64-BE(window number))). A nonce is good in the window
+ * it was issued in and the next one. The derivation is the same in every Atlas
+ * server SDK, so services in different languages sharing the secret agree.
+ */
+export declare function hmacDpopNonceSource(secret: string | Uint8Array, options?: {
+    windowSeconds?: number;
+    now?: () => number;
+}): DpopNonceSource;
+export declare function memoryDpopReplayStore(max?: number): DpopReplayStore;
+export interface AccessTokenVerifierOptions {
+    /** Your Atlas instance's issuer (frontend API origin), e.g. https://clerk.example.com. */
+    issuer: string;
+    /**
+     * Your API's identifier (the Resource Server identifier registered in Atlas,
+     * RFC 8707 `resource`). The token's `aud` must contain one of these. Pass
+     * `false` only to accept tokens with no audience (userinfo-style tokens).
+     */
+    audience: string | readonly string[] | false;
+    /** Scopes every request must carry (all of them). */
+    requiredScopes?: readonly string[];
+    /** The JWKS URL; default `${issuer}/.well-known/jwks.json`. */
+    jwksUrl?: string;
+    /** A static key set (tests / offline). Mutually exclusive with `jwksUrl`. */
+    jwks?: Jwks;
+    /**
+     * Where your protected-resource metadata lives, advertised in every 401 as
+     * `resource_metadata` so an MCP / OAuth client can discover Atlas. Typically
+     * `https://api.example.com/.well-known/oauth-protected-resource`.
+     */
+    resourceMetadataUrl?: string;
+    /** Require a DPoP-bound token on every request (never accept plain Bearer). */
+    requireDpop?: boolean;
+    /** The public origin of this API, for DPoP `htu` when `request.url` is a path. */
+    publicOrigin?: string;
+    dpopReplayStore?: DpopReplayStore;
+    /**
+     * Require a server-provided nonce in every DPoP proof (RFC 9449 §8). A proof
+     * without a valid one is refused with `use_dpop_nonce`; every result carries
+     * `dpopNonce`, to send as the `DPoP-Nonce` response header (the framework
+     * adapters do). See {@link memoryDpopNonceSource} / {@link hmacDpopNonceSource}.
+     */
+    dpopNonces?: DpopNonceSource;
+    /** `WWW-Authenticate` realm. */
+    realm?: string;
+    /**
+     * Validate opaque access tokens (and, with `introspectJwts`, JWTs too) at
+     * Atlas's introspection endpoint. The client must be a confidential client
+     * your API lists in its `introspection_client_ids` (or the client the tokens
+     * are issued to).
+     */
+    introspection?: IntrospectionOptions;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+export interface IntrospectionOptions {
+    clientId: string;
+    clientSecret: string;
+    /** Default `${issuer}/oauth2/introspect`. */
+    endpoint?: string;
+    /** How long an active answer is reused, in seconds (default 60; never past the token's `exp`). */
+    cacheTtlSeconds?: number;
+    /** How long an inactive answer is reused, in seconds (default 10; 0 disables). */
+    negativeCacheTtlSeconds?: number;
+    /** Most answers kept (default 10 000). */
+    cacheMax?: number;
+    /**
+     * Also introspect JWT access tokens, so a revoked grant or a banned user is
+     * refused before the token expires (one cached call per token). Default false:
+     * JWTs are verified locally.
+     */
+    introspectJwts?: boolean;
+}
+/**
+ * RFC 7662 introspection with a small TTL cache keyed by the token's SHA-256
+ * (the token itself is never kept). Returns the claims of an active token, or
+ * null for an inactive one; throws when Atlas could not be reached.
+ */
+export declare function createIntrospector(issuer: string, options: IntrospectionOptions, deps?: {
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}): (token: string) => Promise<AccessTokenClaims | null>;
+export type AccessTokenErrorCode = 'invalid_request' | 'invalid_token' | 'insufficient_scope' | 'invalid_dpop_proof' | 'use_dpop_nonce';
+export type AccessTokenResult = {
+    ok: true;
+    claims: AccessTokenClaims;
+    scopes: string[];
+    subject: string;
+    clientId: string | null;
+    dpopBound: boolean;
+    /** With `dpopNonces`: send as the `DPoP-Nonce` response header. */
+    dpopNonce?: string;
+} | {
+    ok: false;
+    status: 400 | 401 | 403;
+    error: AccessTokenErrorCode | null;
+    description: string;
+    /** Set this response header verbatim. */
+    wwwAuthenticate: string;
+    /** With `dpopNonces`: send as the `DPoP-Nonce` response header (always, on `use_dpop_nonce`). */
+    dpopNonce?: string;
+};
+/**
+ * Build an RFC 6750 / RFC 9449 / RFC 9728 `WWW-Authenticate` challenge.
+ * Without an `error`, it is the bare "authentication required" challenge
+ * (no token was sent), as RFC 6750 §3.1 asks.
+ */
+export declare function buildWwwAuthenticate(opts: {
+    scheme?: 'Bearer' | 'DPoP';
+    realm?: string;
+    error?: AccessTokenErrorCode | null;
+    description?: string;
+    scope?: readonly string[];
+    resourceMetadataUrl?: string;
+    dpopAlgs?: readonly string[];
+}): string;
+/**
+ * A reusable verifier (one JWKS cache for the life of the process). Call it per
+ * request; it never throws for a bad token — it returns the status + challenge.
+ */
+export declare function createAccessTokenVerifier(options: AccessTokenVerifierOptions): (request: ResourceRequestLike, extra?: {
+    requiredScopes?: readonly string[];
+}) => Promise<AccessTokenResult>;
+/** One-shot form of {@link createAccessTokenVerifier} (builds a fresh JWKS cache each call — prefer the factory). */
+export declare function verifyAccessToken(request: ResourceRequestLike, options: AccessTokenVerifierOptions): Promise<AccessTokenResult>;
+/**
+ * The RFC 9728 protected-resource metadata document for your API. Serve it as
+ * JSON at `https://<your api host>/.well-known/oauth-protected-resource` (and,
+ * for a resource with a path, at `/.well-known/oauth-protected-resource<path>`),
+ * and point `resourceMetadataUrl` at it. Atlas can also serve this document for
+ * you when the API is registered with metadata publishing turned on.
+ */
+export declare function protectedResourceMetadata(opts: {
+    /** Your API's identifier (the same value as the verifier's `audience`). */
+    resource: string;
+    /** Your Atlas instance issuer. */
+    issuer: string;
+    scopesSupported?: readonly string[];
+    resourceName?: string;
+    resourceDocumentation?: string;
+    /** Advertise that tokens must be DPoP-bound. */
+    dpopBoundAccessTokensRequired?: boolean;
+}): Record<string, unknown>;
+/** The RFC 9728 well-known path for a resource identifier (path-inserted form). */
+export declare function protectedResourceMetadataPath(resource: string): string;