@idpartners/client-attestation-sdk 0.0.0-stage → 1.0.0

package/dist/validator/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resource-server access-token validation: JWT signature + scope/audience checks in a fixed,
+ * cross-language error-precedence order, plus optional RFC 7662 introspection.
+ *
+ * This is the validator counterpart to the client-side builder SDK, and mirrors the Python
+ * `client_attestation_sdk.token_validator` package so every port reports the same verdict for the shared vectors.
+ */
+export { AccessTokenValidator } from "./validator.js";
+export type { HttpPost, Claims, ValidatorOptions } from "./validator.js";
+export type { HttpGet } from "./jwks.js";
+export type { Logger, LogAttributes, LogLevel } from "../logging.js";
+export { DEFAULT_ALGORITHMS, DEFAULT_TOKEN_TYPES } from "./config.js";
+export type { ValidatorConfig, ResolvedConfig, IntrospectionConfig, IntrospectionAuthMethod, } from "./config.js";
+export type { ValidationResult } from "./result.js";
+export type { ValidationError } from "./errors.js";
+export * as errors from "./errors.js";
+export { ProtectedResource, bearerToken } from "./resource.js";
+export type { ProtectedResourceMetadata, AuthDecision } from "./resource.js";
+export declare const VALIDATOR_VERSION = "1.0.0";

package/dist/validator/index.js

@@ -0,0 +1,12 @@
+/**
+ * Resource-server access-token validation: JWT signature + scope/audience checks in a fixed,
+ * cross-language error-precedence order, plus optional RFC 7662 introspection.
+ *
+ * This is the validator counterpart to the client-side builder SDK, and mirrors the Python
+ * `client_attestation_sdk.token_validator` package so every port reports the same verdict for the shared vectors.
+ */
+export { AccessTokenValidator } from "./validator.js";
+export { DEFAULT_ALGORITHMS, DEFAULT_TOKEN_TYPES } from "./config.js";
+export * as errors from "./errors.js";
+export { ProtectedResource, bearerToken } from "./resource.js";
+export const VALIDATOR_VERSION = "1.0.0";

package/dist/validator/jwks.d.ts

@@ -0,0 +1,2 @@
+/** Fetch a URL and return its body text. Injectable so tests can avoid real network I/O. */
+export type HttpGet = (url: string) => Promise<string>;

package/dist/validator/jwks.js

@@ -0,0 +1,150 @@
+var _a;
+/**
+ * Resolves issuer signing keys — from a static JWKS or a `jwksUri` (fetched and cached, refreshed on an
+ * unknown `kid` and when the cached set grows old).
+ *
+ * A `jwksUri` provider never fetches more than once per `minRefreshSeconds`, however many unknown `kid`
+ * values it is shown, and concurrent misses share one fetch. Without that, a stream of tokens with made-up
+ * `kid` values turns every request into a request to the issuer.
+ */
+import { importJWK } from "jose";
+import { TransportError } from "../errors.js";
+import { request } from "../http.js";
+import { emit, failureReason, hostOf, NOOP_LOGGER } from "../logging.js";
+/** @internal */
+export const MAX_JWKS_BYTES = 512 * 1024;
+/** @internal */
+export const DEFAULT_MIN_REFRESH_SECONDS = 30;
+/** @internal */
+export const DEFAULT_MAX_AGE_SECONDS = 3600;
+const FETCH_TIMEOUT_MS = 10_000;
+const defaultGet = async (url) => {
+    // the shared transport refuses redirects and caps the body at MAX_JWKS_BYTES while reading it
+    const resp = await request(url, { method: "GET", timeoutMs: FETCH_TIMEOUT_MS, maxBytes: MAX_JWKS_BYTES });
+    if (!resp.ok) {
+        throw new TransportError(`GET ${url} failed: ${resp.status}`, "status", { status: resp.status });
+    }
+    return resp.body;
+};
+/** Best-effort JWS `alg` for a JWK that omits `alg`, from its key type / curve. */
+function algorithmFor(jwk) {
+    if (jwk.kty === "EC") {
+        return { "P-256": "ES256", "P-384": "ES384", "P-521": "ES512" }[jwk.crv ?? ""] ?? "ES256";
+    }
+    if (jwk.kty === "RSA") {
+        return "RS256";
+    }
+    if (jwk.kty === "OKP") {
+        return "EdDSA";
+    }
+    return "RS256";
+}
+/** @internal */
+export class JwksProvider {
+    #static;
+    #jwksUri;
+    #httpGet;
+    #minRefreshMs;
+    #maxAgeMs;
+    #clock;
+    #logger;
+    /** kid -> key, plus the JWK's declared `alg` (a JWK that declares one is only used for that alg). */
+    #keys = new Map();
+    #loaded = null;
+    #inFlight = null;
+    #loadedAt = null;
+    #lastAttempt = null;
+    /** Why the last fetch failed, or `null` after a successful one. */
+    lastError = null;
+    constructor(opts) {
+        this.#static = opts.jwks != null;
+        this.#jwksUri = opts.jwksUri;
+        this.#httpGet = opts.httpGet ?? defaultGet;
+        this.#minRefreshMs = (opts.minRefreshSeconds ?? DEFAULT_MIN_REFRESH_SECONDS) * 1000;
+        this.#maxAgeMs = (opts.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS) * 1000;
+        this.#clock = opts.clock ?? Date.now;
+        this.#logger = opts.logger ?? NOOP_LOGGER;
+        if (opts.jwks != null) {
+            this.#loaded = _a.#parse(opts.jwks).then((keys) => {
+                this.#keys = keys;
+            });
+        }
+    }
+    static async #parse(jwks) {
+        const keys = new Map();
+        for (const jwk of jwks.keys ?? []) {
+            const alg = jwk.alg ?? algorithmFor(jwk);
+            try {
+                keys.set(jwk.kid, { key: await importJWK(jwk, alg), alg: jwk.alg });
+            }
+            catch {
+                continue;
+            }
+        }
+        return keys;
+    }
+    /**
+     * Resolve the verification key for a header `kid` (and `alg`). Falls back to the single configured key
+     * when the header carries no `kid`. Returns `undefined` when no key can be found; never rejects — a
+     * failed fetch leaves its reason in {@link lastError}.
+     */
+    async resolve(kid, alg) {
+        if (this.#loaded) {
+            await this.#loaded;
+        }
+        if (!this.#static && this.#jwksUri && (this.#lookup(kid) === undefined || this.#stale())) {
+            await this.#refresh();
+        }
+        const entry = this.#lookup(kid);
+        if (entry === undefined || (alg != null && entry.alg != null && entry.alg !== alg)) {
+            return undefined;
+        }
+        return entry.key;
+    }
+    #lookup(kid) {
+        if (kid != null) {
+            return this.#keys.get(kid);
+        }
+        return this.#keys.size === 1 ? this.#keys.values().next().value : undefined;
+    }
+    #stale() {
+        return this.#loadedAt === null || this.#clock() - this.#loadedAt >= this.#maxAgeMs;
+    }
+    #refresh() {
+        if (this.#inFlight) {
+            return this.#inFlight;
+        }
+        const now = this.#clock();
+        if (this.#lastAttempt !== null && now - this.#lastAttempt < this.#minRefreshMs) {
+            emit(this.#logger, "debug", "jwks.refetch_throttled", { host: hostOf(this.#jwksUri) });
+            return Promise.resolve();
+        }
+        this.#lastAttempt = now;
+        this.#inFlight = (async () => {
+            try {
+                const body = await this.#httpGet(this.#jwksUri);
+                if (body.length > MAX_JWKS_BYTES) {
+                    throw new TransportError(`JWKS is larger than ${MAX_JWKS_BYTES} bytes`, "too_large");
+                }
+                this.#keys = await _a.#parse(JSON.parse(body));
+                this.#loadedAt = this.#clock();
+                this.lastError = null;
+                emit(this.#logger, "debug", "jwks.fetched", { host: hostOf(this.#jwksUri), keys: this.#keys.size });
+            }
+            catch (exc) {
+                emit(this.#logger, "warn", "jwks.fetch_failed", {
+                    host: hostOf(this.#jwksUri),
+                    reason: failureReason(exc),
+                    status: exc instanceof TransportError ? exc.status : undefined,
+                });
+                // keep serving the keys already held
+                this.lastError = `JWKS fetch failed: ${exc instanceof Error ? exc.message : String(exc)}`;
+            }
+            finally {
+                this.#inFlight = null;
+            }
+        })();
+        return this.#inFlight;
+    }
+}
+_a = JwksProvider;

package/dist/validator/resource.d.ts

@@ -0,0 +1,37 @@
+import type { ValidationResult } from "./result.js";
+import type { AccessTokenValidator } from "./validator.js";
+/** Extract the token from an `Authorization: Bearer <token>` header value, or null. */
+export declare function bearerToken(authorizationHeader?: string | null): string | null;
+/** RFC 9728 protected-resource metadata document. */
+export interface ProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    bearer_methods_supported: string[];
+    scopes_supported?: string[];
+}
+/** The outcome of guarding a request. */
+export interface AuthDecision {
+    authorized: boolean;
+    result?: ValidationResult;
+    status: number;
+    wwwAuthenticate?: string;
+    error?: string;
+    errorDescription?: string | null;
+}
+/**
+ * An OAuth-protected resource server. The `validator` must accept `resource` as an audience — that binds
+ * incoming tokens to this resource (RFC 8707), which MCP servers MUST enforce. The constructor refuses one
+ * that doesn't.
+ */
+export declare class ProtectedResource {
+    #private;
+    readonly resource: string;
+    readonly authorizationServers: string[];
+    readonly scopesSupported: string[];
+    constructor(resource: string, authorizationServers: string[], validator: AccessTokenValidator, scopesSupported?: string[]);
+    metadata(): ProtectedResourceMetadata;
+    metadataPath(): string;
+    metadataUrl(): string;
+    challenge(error?: string, errorDescription?: string | null): string;
+    authenticate(authorizationHeader?: string | null, requiredScopes?: string[]): Promise<AuthDecision>;
+}

package/dist/validator/resource.js

@@ -0,0 +1,98 @@
+/**
+ * OAuth 2.0/2.1 protected-resource conventions on top of {@link AccessTokenValidator}.
+ *
+ * A {@link ProtectedResource} is the resource-server side of any OAuth-protected HTTP service — an MCP
+ * server (OAuth 2.1 resource server per the MCP authorization spec), an A2A agent, or a plain REST API. It
+ * adds what the validator itself doesn't: RFC 9728 Protected Resource Metadata
+ * (`/.well-known/oauth-protected-resource`), RFC 6750 bearer extraction + `WWW-Authenticate` challenges, and
+ * a request guard that binds the token audience to this resource (RFC 8707). Protocol-neutral — not MCP-only.
+ */
+import * as errors from "./errors.js";
+const WELL_KNOWN = "/.well-known/oauth-protected-resource";
+/** Extract the token from an `Authorization: Bearer <token>` header value, or null. */
+export function bearerToken(authorizationHeader) {
+    if (!authorizationHeader)
+        return null;
+    const match = /^\s*Bearer\s+(.+?)\s*$/i.exec(authorizationHeader);
+    return match ? match[1] : null;
+}
+/**
+ * An OAuth-protected resource server. The `validator` must accept `resource` as an audience — that binds
+ * incoming tokens to this resource (RFC 8707), which MCP servers MUST enforce. The constructor refuses one
+ * that doesn't.
+ */
+export class ProtectedResource {
+    resource;
+    authorizationServers;
+    scopesSupported;
+    #validator;
+    constructor(resource, authorizationServers, validator, scopesSupported = []) {
+        if (!validator.config.audiences.includes(resource)) {
+            throw new Error(`the validator does not accept this resource (${resource}) as an audience`);
+        }
+        this.resource = resource;
+        this.authorizationServers = authorizationServers;
+        this.#validator = validator;
+        this.scopesSupported = scopesSupported;
+    }
+    metadata() {
+        const md = {
+            resource: this.resource,
+            authorization_servers: this.authorizationServers,
+            bearer_methods_supported: ["header"],
+        };
+        if (this.scopesSupported.length > 0)
+            md.scopes_supported = this.scopesSupported;
+        return md;
+    }
+    metadataPath() {
+        const path = new URL(this.resource).pathname;
+        return path && path !== "/" ? WELL_KNOWN + path : WELL_KNOWN;
+    }
+    metadataUrl() {
+        const u = new URL(this.resource);
+        return `${u.protocol}//${u.host}${this.metadataPath()}`;
+    }
+    challenge(error, errorDescription) {
+        const params = [];
+        if (error) {
+            params.push(`error="${quote(error)}"`);
+            if (errorDescription)
+                params.push(`error_description="${quote(errorDescription)}"`);
+        }
+        params.push(`resource_metadata="${quote(this.metadataUrl())}"`);
+        return "Bearer " + params.join(", ");
+    }
+    async authenticate(authorizationHeader, requiredScopes) {
+        const token = bearerToken(authorizationHeader);
+        if (token == null) {
+            return { authorized: false, status: 401, wwwAuthenticate: this.challenge(), errorDescription: "authentication required" };
+        }
+        const result = await this.#validator.validate(token, requiredScopes);
+        if (result.valid) {
+            return { authorized: true, result, status: 200 };
+        }
+        const [status, oauthError] = httpError(result.error);
+        return {
+            authorized: false,
+            result,
+            status,
+            error: oauthError,
+            errorDescription: result.errorDescription,
+            wwwAuthenticate: this.challenge(oauthError, result.errorDescription),
+        };
+    }
+}
+function httpError(error) {
+    return error === errors.INSUFFICIENT_SCOPE ? [403, "insufficient_scope"] : [401, "invalid_token"];
+}
+/**
+ * Make a value safe inside a quoted-string header parameter: drop CR, LF and every other control
+ * character (0x00-0x1F, 0x7F) so nothing can split or forge a header, then escape backslash and quote.
+ *
+ * @internal
+ */
+export function quote(value) {
+    // eslint-disable-next-line no-control-regex
+    return value.replace(/[\x00-\x1f\x7f]/g, "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}

package/dist/validator/result.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The outcome of validating an access token: either a valid token (with its subject, granted scopes,
+ * audience and claims) or a failure carrying a stable `error` code (see {@link ./errors}).
+ */
+import type { ValidationError } from "./errors.js";
+export interface ValidationResult {
+    valid: boolean;
+    /** Stable error code when `valid` is false; `null` when valid. */
+    error: ValidationError | null;
+    errorDescription: string | null;
+    subject: string | null;
+    scopes: string[];
+    audience: string[];
+    claims: Record<string, unknown>;
+    /** The `exp` claim (integer epoch seconds) when present. */
+    expiresAt: number | null;
+}

package/dist/validator/result.js

@@ -0,0 +1,28 @@
+/** @internal */
+export function success(claims, scopes, audience) {
+    const sub = claims.sub;
+    const exp = claims.exp;
+    return {
+        valid: true,
+        error: null,
+        errorDescription: null,
+        subject: typeof sub === "string" ? sub : null,
+        scopes,
+        audience,
+        claims,
+        expiresAt: exp == null ? null : Number(exp),
+    };
+}
+/** @internal */
+export function failure(error, description) {
+    return {
+        valid: false,
+        error,
+        errorDescription: description ?? null,
+        subject: null,
+        scopes: [],
+        audience: [],
+        claims: {},
+        expiresAt: null,
+    };
+}

package/dist/validator/strict.d.ts

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

package/dist/validator/strict.js

@@ -0,0 +1,202 @@
+/**
+ * The strict parsing every port applies to a token before trusting any of it (validation/SEMANTICS.md):
+ * compact serialisation, strict JSON objects, NumericDates and claim types. A failure throws
+ * {@link Malformed}; its message is generic and never quotes token bytes.
+ */
+import { base64url } from "jose";
+/**
+ * Deepest object/array nesting a header, payload or introspection response may have.
+ *
+ * @internal
+ */
+export const MAX_DEPTH = 64;
+const MAX_SAFE = Number.MAX_SAFE_INTEGER;
+const SEGMENT = /^[A-Za-z0-9_-]*$/;
+/**
+ * The input is not well-formed; the token is invalid.
+ *
+ * @internal
+ */
+export class Malformed extends Error {
+}
+function decodeSegment(segment) {
+    if (!SEGMENT.test(segment) || segment.length % 4 === 1) {
+        throw new Malformed("malformed token");
+    }
+    const data = base64url.decode(segment);
+    if (base64url.encode(data) !== segment) {
+        throw new Malformed("malformed token"); // non-zero padding bits: not the canonical encoding
+    }
+    return data;
+}
+/**
+ * The header object and payload bytes of a compact JWS. The payload is returned undecoded: it is only
+ * parsed once the signature over it verifies.
+ *
+ * @internal
+ */
+export function splitCompact(token) {
+    if (typeof token !== "string") {
+        throw new Malformed("malformed token");
+    }
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+        throw new Malformed("malformed token");
+    }
+    const [headerBytes, payload] = parts.map(decodeSegment);
+    const header = parseObject(headerBytes, "header");
+    if ("crit" in header) {
+        // we implement no JWS extension, so RFC 7515 section 4.1.11 says reject any crit
+        throw new Malformed("header has crit");
+    }
+    return { header, payload };
+}
+/**
+ * `data` as a strict RFC 8259 JSON object: UTF-8 without a BOM, no duplicate member names at any depth,
+ * at most {@link MAX_DEPTH} levels deep. (`JSON.parse` already refuses NaN, trailing commas and the like.)
+ *
+ * @internal
+ */
+export function parseObject(data, what = "payload") {
+    let text;
+    try {
+        // fatal: invalid UTF-8 is an error, not U+FFFD; ignoreBOM: keep a BOM so JSON.parse refuses it
+        text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(data);
+    }
+    catch {
+        throw new Malformed(`${what} is not UTF-8`);
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Malformed(`${what} is not JSON`);
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Malformed(`${what} is not a JSON object`);
+    }
+    checkStructure(text, what);
+    return value;
+}
+/**
+ * Walk JSON text that `JSON.parse` has already accepted, refusing a duplicate member name in any object
+ * (names compared after unescaping) and nesting deeper than {@link MAX_DEPTH}. Iterative, so depth can't
+ * exhaust the stack.
+ */
+function checkStructure(text, what) {
+    // one frame per open container: a Set of member names for an object, null for an array
+    const stack = [];
+    let expectName = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '"') {
+            let j = i + 1;
+            while (text[j] !== '"') {
+                j += text[j] === "\\" ? 2 : 1;
+            }
+            const top = stack[stack.length - 1];
+            if (expectName && top) {
+                const name = JSON.parse(text.slice(i, j + 1));
+                if (top.has(name)) {
+                    throw new Malformed(`${what} is not a strict JSON object (duplicate member name)`);
+                }
+                top.add(name);
+                expectName = false;
+            }
+            i = j;
+        }
+        else if (ch === "{" || ch === "[") {
+            stack.push(ch === "{" ? new Set() : null);
+            if (stack.length > MAX_DEPTH) {
+                throw new Malformed(`${what} is nested too deeply`);
+            }
+            expectName = ch === "{";
+        }
+        else if (ch === "}" || ch === "]") {
+            stack.pop();
+        }
+        else if (ch === ",") {
+            expectName = stack[stack.length - 1] != null;
+        }
+    }
+}
+/**
+ * A NumericDate claim as an integer (fractions truncate toward zero), `undefined` when absent or null.
+ * Anything but a finite JSON number within ±(2^53 − 1) is malformed.
+ *
+ * @internal
+ */
+export function numericDate(claims, name) {
+    const value = claims[name];
+    if (value == null) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Malformed(`${name} is not a NumericDate`);
+    }
+    if (Math.abs(value) > MAX_SAFE) {
+        throw new Malformed(`${name} is out of range`);
+    }
+    return Math.trunc(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+/**
+ * `aud` as a list: absent or null is empty, a string is one entry, an array must hold only strings.
+ *
+ * @internal
+ */
+export function audience(claims) {
+    const value = claims.aud;
+    if (value == null) {
+        return [];
+    }
+    if (typeof value === "string") {
+        return [value];
+    }
+    if (isStringArray(value)) {
+        return [...value];
+    }
+    throw new Malformed("aud is not a string or an array of strings");
+}
+/** Split on U+0020 only, as RFC 6749 section 3.3 says; runs of spaces make no empty scopes. */
+function split(text) {
+    return text.split(" ").filter((s) => s.length > 0);
+}
+/**
+ * Granted scopes: from `scope` (a space-delimited string) when present, else `scp` (a space-delimited string,
+ * as Microsoft Entra ID issues it, or an array of strings). Either one present with any other shape is
+ * malformed.
+ *
+ * @internal
+ */
+export function scopes(claims) {
+    const { scope, scp } = claims;
+    if (scope != null && typeof scope !== "string") {
+        throw new Malformed("scope is not a string");
+    }
+    if (scp != null && typeof scp !== "string" && !isStringArray(scp)) {
+        throw new Malformed("scp is not a string or an array of strings");
+    }
+    if (scope != null) {
+        return split(scope);
+    }
+    if (typeof scp === "string") {
+        return split(scp);
+    }
+    return scp != null ? [...scp] : [];
+}
+/**
+ * `sub`, `undefined` when absent or null; any other non-string is malformed.
+ *
+ * @internal
+ */
+export function subject(claims) {
+    const value = claims.sub;
+    if (value != null && typeof value !== "string") {
+        throw new Malformed("sub is not a string");
+    }
+    return value ?? undefined;
+}

package/dist/validator/validator.d.ts

@@ -0,0 +1,41 @@
+import { type ResolvedConfig, type ValidatorConfig } from "./config.js";
+import { type Logger } from "../logging.js";
+import { type HttpGet } from "./jwks.js";
+import { type ValidationResult } from "./result.js";
+/** Claims as decoded from a JWT payload (or an introspection response). */
+export type Claims = Record<string, unknown>;
+/**
+ * Inject a POST transport (mirrors Python's `http_post`). Resolves to the parsed JSON response body.
+ */
+export type HttpPost = (url: string, body: string, headers: Record<string, string>) => Promise<Claims>;
+/** Optional injectable transports, primarily so tests can mock network I/O. */
+export interface ValidatorOptions {
+    httpPost?: HttpPost;
+    httpGet?: HttpGet;
+    /**
+     * Where to send log events (`token.validated`, `jwks.*`, `http.failed`; see docs/logging.md). Unset,
+     * nothing is logged. Tokens and client secrets are never logged.
+     */
+    logger?: Logger;
+    /** Epoch-millisecond clock that `exp` / `nbf` / `iat` are checked against. Defaults to `Date.now`. */
+    clock?: () => number;
+}
+/** Validates access tokens for a resource server. */
+export declare class AccessTokenValidator {
+    #private;
+    readonly config: ResolvedConfig;
+    constructor(config: ValidatorConfig, opts?: ValidatorOptions);
+    /**
+     * Locally validate a JWT access token. Returns the first failure in the fixed contract order, or a
+     * success result exposing subject / scopes / audience / claims.
+     */
+    validate(token: string, requiredScopes?: string[]): Promise<ValidationResult>;
+    /**
+     * RFC 7662: POST the token to the AS introspection endpoint and return the parsed response.
+     */
+    introspect(token: string, tokenTypeHint?: string): Promise<Claims>;
+    /**
+     * Introspect the token and enforce `active` plus scope/audience from the response.
+     */
+    validateActive(token: string, requiredScopes?: string[]): Promise<ValidationResult>;
+}