@idpartners/client-attestation-sdk 0.2.0 → 1.0.0

package/dist/validator/index.d.ts

@@ -3,16 +3,17 @@
  * 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
- * `token_validator` package so every port reports the same verdict for the shared vectors.
+ * `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 { resolveConfig, DEFAULT_ALGORITHMS, DEFAULT_TOKEN_TYPES } from "./config.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 = "0.2.0";
+export declare const VALIDATOR_VERSION = "1.0.0";

package/dist/validator/index.js

@@ -3,10 +3,10 @@
  * 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
- * `token_validator` package so every port reports the same verdict for the shared vectors.
+ * `client_attestation_sdk.token_validator` package so every port reports the same verdict for the shared vectors.
  */
 export { AccessTokenValidator } from "./validator.js";
-export { resolveConfig, DEFAULT_ALGORITHMS, DEFAULT_TOKEN_TYPES } from "./config.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 = "0.2.0";
+export const VALIDATOR_VERSION = "1.0.0";

package/dist/validator/jwks.d.ts

@@ -1,39 +1,2 @@
-/**
- * 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 { type CryptoKey, type JSONWebKeySet } from "jose";
-/** An imported verification key, as returned by jose's `importJWK`. */
-export type VerificationKey = CryptoKey | Uint8Array;
 /** Fetch a URL and return its body text. Injectable so tests can avoid real network I/O. */
 export type HttpGet = (url: string) => Promise<string>;
-export declare const MAX_JWKS_BYTES: number;
-export declare const DEFAULT_MIN_REFRESH_SECONDS = 30;
-export declare const DEFAULT_MAX_AGE_SECONDS = 3600;
-export interface JwksProviderOptions {
-    jwks?: JSONWebKeySet;
-    jwksUri?: string;
-    httpGet?: HttpGet;
-    /** Minimum time between fetches. Defaults to {@link DEFAULT_MIN_REFRESH_SECONDS}. */
-    minRefreshSeconds?: number;
-    /** Refresh a fetched set once it is this old. Defaults to {@link DEFAULT_MAX_AGE_SECONDS}. */
-    maxAgeSeconds?: number;
-    /** Milliseconds clock, injectable for tests. Defaults to `Date.now`. */
-    clock?: () => number;
-}
-export declare class JwksProvider {
-    #private;
-    /** Why the last fetch failed, or `null` after a successful one. */
-    lastError: string | null;
-    constructor(opts: JwksProviderOptions);
-    /**
-     * 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}.
-     */
-    resolve(kid: string | undefined, alg?: string): Promise<VerificationKey | undefined>;
-}

package/dist/validator/jwks.js

@@ -8,16 +8,21 @@ var _a;
  * `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 Error(`GET ${url} failed: ${resp.status}`);
+        throw new TransportError(`GET ${url} failed: ${resp.status}`, "status", { status: resp.status });
     }
     return resp.body;
 };
@@ -34,6 +39,7 @@ function algorithmFor(jwk) {
     }
     return "RS256";
 }
+/** @internal */
 export class JwksProvider {
     #static;
     #jwksUri;
@@ -41,6 +47,7 @@ export class JwksProvider {
     #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;
@@ -56,6 +63,7 @@ export class JwksProvider {
         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;
@@ -108,6 +116,7 @@ export class JwksProvider {
         }
         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;
@@ -115,13 +124,19 @@ export class JwksProvider {
             try {
                 const body = await this.#httpGet(this.#jwksUri);
                 if (body.length > MAX_JWKS_BYTES) {
-                    throw new Error(`JWKS is larger than ${MAX_JWKS_BYTES} 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)}`;
             }

package/dist/validator/resource.d.ts

@@ -35,8 +35,3 @@ export declare class ProtectedResource {
     challenge(error?: string, errorDescription?: string | null): string;
     authenticate(authorizationHeader?: string | null, requiredScopes?: string[]): Promise<AuthDecision>;
 }
-/**
- * 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.
- */
-export declare function quote(value: string): string;

package/dist/validator/resource.js

@@ -89,6 +89,8 @@ function httpError(error) {
 /**
  * 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

package/dist/validator/result.d.ts

@@ -15,5 +15,3 @@ export interface ValidationResult {
     /** The `exp` claim (integer epoch seconds) when present. */
     expiresAt: number | null;
 }
-export declare function success(claims: Record<string, unknown>, scopes: string[], audience: string[]): ValidationResult;
-export declare function failure(error: ValidationError, description?: string): ValidationResult;

package/dist/validator/result.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function success(claims, scopes, audience) {
     const sub = claims.sub;
     const exp = claims.exp;
@@ -12,6 +13,7 @@ export function success(claims, scopes, audience) {
         expiresAt: exp == null ? null : Number(exp),
     };
 }
+/** @internal */
 export function failure(error, description) {
     return {
         valid: false,

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

@@ -1,4 +1,5 @@
 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). */
@@ -11,6 +12,13 @@ export type HttpPost = (url: string, body: string, headers: Record<string, strin
 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 {