@idpartners/client-attestation-sdk 1.0.0 → 1.2.0

package/dist/validator/jwks.js

@@ -26,6 +26,25 @@ const defaultGet = async (url) => {
     }
     return resp.body;
 };
+/** The JWK members only a private or symmetric key carries (RFC 7518 section 6). */
+const PRIVATE_MEMBERS = ["d", "p", "q", "dp", "dq", "qi", "k"];
+/**
+ * Whether a JWK may verify a signature: not when its `use` is present and not `sig`, its `key_ops` is present
+ * and lacks `verify`, or it carries private members. Checked on the JWK as published, before jose's
+ * `importJWK` (which drops `use`) sees it.
+ */
+function verifiesSignatures(jwk) {
+    if (typeof jwk !== "object" || jwk === null || Array.isArray(jwk)) {
+        return false; // not a JWK at all: skipped like any key that can't be read
+    }
+    if ("use" in jwk && jwk.use !== "sig") {
+        return false;
+    }
+    if ("key_ops" in jwk && !(Array.isArray(jwk.key_ops) && jwk.key_ops.includes("verify"))) {
+        return false;
+    }
+    return !PRIVATE_MEMBERS.some((member) => member in jwk);
+}
 /** Best-effort JWS `alg` for a JWK that omits `alg`, from its key type / curve. */
 function algorithmFor(jwk) {
     if (jwk.kty === "EC") {
@@ -48,8 +67,8 @@ export class JwksProvider {
     #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();
+    /** The usable keys, in document order: kid-less JWKs are distinct keys, and the first of a duplicate kid wins. */
+    #keys = [];
     #loaded = null;
     #inFlight = null;
     #loadedAt = null;
@@ -62,7 +81,7 @@ export class JwksProvider {
         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.#clock = opts.clock ?? (() => performance.now());
         this.#logger = opts.logger ?? NOOP_LOGGER;
         if (opts.jwks != null) {
             this.#loaded = _a.#parse(opts.jwks).then((keys) => {
@@ -71,11 +90,20 @@ export class JwksProvider {
         }
     }
     static async #parse(jwks) {
-        const keys = new Map();
-        for (const jwk of jwks.keys ?? []) {
-            const alg = jwk.alg ?? algorithmFor(jwk);
+        const keys = [];
+        for (const published of (jwks.keys ?? [])) {
+            if (!verifiesSignatures(published)) {
+                continue;
+            }
+            // Imported without its key_ops: verifiesSignatures has checked them, and jose would hand them to
+            // WebCrypto as the key's usages, which refuses a public key with any usage but "verify" (a JWK exported
+            // from a key pair says ["sign","verify"]). Every later import of this entry (resolve) uses this copy.
+            const { key_ops: _keyOps, ...jwk } = published;
+            // a JWK jose can't read at all is skipped; its key type and curve say how to read it
+            const inferred = algorithmFor(jwk);
             try {
-                keys.set(jwk.kid, { key: await importJWK(jwk, alg), alg: jwk.alg });
+                const key = await importJWK(jwk, inferred);
+                keys.push({ kid: jwk.kid, jwk, alg: jwk.alg, imported: new Map([[inferred, key]]) });
             }
             catch {
                 continue;
@@ -85,34 +113,51 @@ export class JwksProvider {
     }
     /**
      * 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}.
+     * when the header carries no `kid`. Returns `undefined` when no key can be found, and `null` when the key
+     * found can't be used with `alg` (an EC key of another curve, an RSA key for an EC algorithm); 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();
+        if (!this.#static && this.#jwksUri) {
+            const held = this.#lookup(kid, alg) !== undefined;
+            if (!held || this.#stale()) {
+                await this.#refresh(held);
+            }
         }
-        const entry = this.#lookup(kid);
-        if (entry === undefined || (alg != null && entry.alg != null && entry.alg !== alg)) {
+        const entry = this.#lookup(kid, alg);
+        if (entry === undefined) {
             return undefined;
         }
-        return entry.key;
+        const as = alg ?? entry.alg ?? algorithmFor(entry.jwk);
+        if (!entry.imported.has(as)) {
+            entry.imported.set(as, await importJWK(entry.jwk, as).catch(() => null));
+        }
+        return entry.imported.get(as) ?? null;
     }
-    #lookup(kid) {
+    /**
+     * For a `kid`, the first key with that `kid` that may be used for `alg`; without one, the sole key when the
+     * set holds exactly one. An empty `kid` names no key.
+     */
+    #lookup(kid, alg) {
+        const allowed = (entry) => alg == null || entry.alg == null || entry.alg === alg;
         if (kid != null) {
-            return this.#keys.get(kid);
+            return kid === "" ? undefined : this.#keys.find((entry) => entry.kid === kid && allowed(entry));
         }
-        return this.#keys.size === 1 ? this.#keys.values().next().value : undefined;
+        return this.#keys.length === 1 && allowed(this.#keys[0]) ? this.#keys[0] : undefined;
     }
     #stale() {
         return this.#loadedAt === null || this.#clock() - this.#loadedAt >= this.#maxAgeMs;
     }
-    #refresh() {
+    /**
+     * A caller that already holds a usable (if stale) key never waits for another request's fetch: it goes on
+     * with the key it has. One without a key waits for a fetch in flight, which may bring its key.
+     */
+    #refresh(haveKey) {
         if (this.#inFlight) {
-            return this.#inFlight;
+            return haveKey ? Promise.resolve() : this.#inFlight;
         }
         const now = this.#clock();
         if (this.#lastAttempt !== null && now - this.#lastAttempt < this.#minRefreshMs) {
@@ -129,7 +174,7 @@ export class JwksProvider {
                 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 });
+                emit(this.#logger, "debug", "jwks.fetched", { host: hostOf(this.#jwksUri), keys: this.#keys.length });
             }
             catch (exc) {
                 emit(this.#logger, "warn", "jwks.fetch_failed", {

package/dist/validator/resource.d.ts

@@ -1,4 +1,4 @@
-import type { ValidationResult } from "./result.js";
+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;
@@ -34,4 +34,12 @@ export declare class ProtectedResource {
     metadataUrl(): string;
     challenge(error?: string, errorDescription?: string | null): string;
     authenticate(authorizationHeader?: string | null, requiredScopes?: string[]): Promise<AuthDecision>;
+    /**
+     * {@link authenticate} for tokens checked by RFC 7662 introspection ({@link AccessTokenValidator.validateActive}),
+     * such as opaque tokens, with the same rules: the response's `aud` must name this resource, so a response
+     * without one is refused (401), and a sender-constrained token (`cnf`) is refused (401). A failed
+     * introspection call is not a verdict: it rejects, as `validateActive` does, and the caller answers it (503,
+     * say).
+     */
+    authenticateActive(authorizationHeader?: string | null, requiredScopes?: string[]): Promise<AuthDecision>;
 }

package/dist/validator/resource.js

@@ -8,13 +8,48 @@
  * a request guard that binds the token audience to this resource (RFC 8707). Protocol-neutral — not MCP-only.
  */
 import * as errors from "./errors.js";
+import { failure } from "./result.js";
 const WELL_KNOWN = "/.well-known/oauth-protected-resource";
+const BEARER = "bearer";
 /** 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;
+    // One linear pass, no regex: a backtracking pattern here costs quadratic or cubic time on a hostile header.
+    // The result is what Go's RE2 (?i)^\s*Bearer\s+(.+?)\s*$ returns, so every port extracts the same token.
+    const h = authorizationHeader;
+    const n = h.length;
+    let i = 0;
+    while (i < n && isSpace(h.charCodeAt(i)))
+        i++;
+    if (n - i <= BEARER.length)
+        return null;
+    for (let k = 0; k < BEARER.length; k++, i++) {
+        if ((h.charCodeAt(i) | 0x20) !== BEARER.charCodeAt(k))
+            return null;
+    }
+    if (!isSpace(h.charCodeAt(i)))
+        return null;
+    let end = n;
+    while (end > i && isSpace(h.charCodeAt(end - 1)))
+        end--;
+    if (end === i) {
+        // Only whitespace after the scheme: RE2 takes the last non-LF whitespace character after the first.
+        for (let j = n - 1; j > i; j--) {
+            if (h[j] !== "\n")
+                return h[j];
+        }
+        return null;
+    }
+    let start = i + 1;
+    while (isSpace(h.charCodeAt(start)))
+        start++;
+    const token = h.slice(start, end);
+    return token.includes("\n") ? null : token;
+}
+/** RE2's `\s`: space, tab, LF, FF and CR. */
+function isSpace(c) {
+    return c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0c || c === 0x0d;
 }
 /**
  * An OAuth-protected resource server. The `validator` must accept `resource` as an audience — that binds
@@ -64,11 +99,30 @@ export class ProtectedResource {
         return "Bearer " + params.join(", ");
     }
     async authenticate(authorizationHeader, requiredScopes) {
+        return this.#guard(authorizationHeader, (token) => this.#validator.validate(token, requiredScopes));
+    }
+    /**
+     * {@link authenticate} for tokens checked by RFC 7662 introspection ({@link AccessTokenValidator.validateActive}),
+     * such as opaque tokens, with the same rules: the response's `aud` must name this resource, so a response
+     * without one is refused (401), and a sender-constrained token (`cnf`) is refused (401). A failed
+     * introspection call is not a verdict: it rejects, as `validateActive` does, and the caller answers it (503,
+     * say).
+     */
+    async authenticateActive(authorizationHeader, requiredScopes) {
+        return this.#guard(authorizationHeader, (token) => this.#validator.validateActive(token, requiredScopes));
+    }
+    async #guard(authorizationHeader, validate) {
         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);
+        let result = await validate(token);
+        if (result.valid && !result.audience.includes(this.resource)) {
+            result = failure(errors.INVALID_AUDIENCE, "token audience is not this resource");
+        }
+        if (result.valid && result.claims.cnf != null) {
+            result = failure(errors.INVALID_TOKEN, "sender-constrained token requires proof verification");
+        }
         if (result.valid) {
             return { authorized: true, result, status: 200 };
         }

package/dist/validator/strict.js

@@ -19,7 +19,12 @@ const SEGMENT = /^[A-Za-z0-9_-]*$/;
  */
 export class Malformed extends Error {
 }
-function decodeSegment(segment) {
+/**
+ * One segment of a compact JWS: unpadded base64url in its canonical form (no non-zero padding bits).
+ *
+ * @internal
+ */
+export function decodeSegment(segment) {
     if (!SEGMENT.test(segment) || segment.length % 4 === 1) {
         throw new Malformed("malformed token");
     }

package/dist/validator/validator.js

@@ -92,11 +92,16 @@ export class AccessTokenValidator {
             return failure(errors.UNSUPPORTED_ALGORITHM, "algorithm not accepted");
         }
         const kid = header.kid;
-        const key = kid == null || typeof kid === "string" ? await this.#jwks.resolve(kid ?? undefined, alg) : null;
-        if (key == null) {
-            return failure(errors.KEY_NOT_FOUND, this.#jwks.lastError ?? "no signing key for this kid");
+        const key = kid == null || typeof kid === "string" ? await this.#jwks.resolve(kid ?? undefined, alg) : undefined;
+        if (key === undefined) {
+            // a fetch failure's detail (internal host, dial error, IdP body) went to the logger as jwks.fetch_failed;
+            // the description lands in WWW-Authenticate, in front of anyone
+            return failure(errors.KEY_NOT_FOUND, this.#jwks.lastError !== null ? "signing keys unavailable" : "no signing key for this kid");
         }
         try {
+            if (key === null) {
+                throw new Error("the key can't be used with this algorithm");
+            }
             await compactVerify(token, key, { algorithms: [alg] });
         }
         catch {
@@ -174,15 +179,14 @@ export class AccessTokenValidator {
             "Content-Type": "application/x-www-form-urlencoded",
             Accept: "application/json",
         };
-        const authMethod = cfg.authMethod ?? "client_secret_basic";
-        if (authMethod === "client_secret_basic") {
-            const raw = `${cfg.clientId}:${cfg.clientSecret}`;
-            headers.Authorization = `Basic ${base64(raw)}`;
-        }
-        else {
+        if (cfg.authMethod === "client_secret_post") {
             form.set("client_id", cfg.clientId);
             form.set("client_secret", cfg.clientSecret);
         }
+        else {
+            // client_secret_basic: resolveConfig refuses anything but the two, or unset
+            headers.Authorization = basicAuthorization(cfg.clientId, cfg.clientSecret);
+        }
         try {
             const data = await this.#httpPost(cfg.endpoint, form.toString(), headers);
             if (data === null || typeof data !== "object" || Array.isArray(data)) {
@@ -232,8 +236,35 @@ export class AccessTokenValidator {
         }
     }
 }
-function base64(value) {
-    return base64Encode(utf8Encode(value));
+/**
+ * The `client_secret_basic` Authorization header value (RFC 6749 section 2.3.1): the client id and the secret
+ * are each form-urlencoded (Appendix B), joined with `:` and base64'd. The encoding is the same bytes as
+ * Python's `urllib.parse.quote_plus(s, safe="")`: each UTF-8 byte of `A-Z a-z 0-9 - . _ ~` stays as it is, a
+ * space becomes `+`, and every other byte is `%XX` with uppercase hex (so `:` is `%3A`, `%` is `%25`, `+` is
+ * `%2B` and `*` is `%2A`). Not `encodeURIComponent`, which leaves `! ' ( ) *` alone, nor `URLSearchParams`,
+ * which leaves `*` alone and encodes `~`. validation/SEMANTICS.md, Introspection.
+ *
+ * @internal
+ */
+export function basicAuthorization(clientId, clientSecret) {
+    return `Basic ${base64Encode(utf8Encode(`${formEncode(clientId)}:${formEncode(clientSecret)}`))}`;
+}
+const HEX = "0123456789ABCDEF";
+function formEncode(value) {
+    let out = "";
+    for (const b of utf8Encode(value)) {
+        const unreserved = (b >= 0x30 && b <= 0x39) || // 0-9
+            (b >= 0x41 && b <= 0x5a) || // A-Z
+            (b >= 0x61 && b <= 0x7a) || // a-z
+            b === 0x2d || b === 0x2e || b === 0x5f || b === 0x7e; // - . _ ~
+        if (unreserved)
+            out += String.fromCharCode(b);
+        else if (b === 0x20)
+            out += "+";
+        else
+            out += "%" + HEX[b >> 4] + HEX[b & 0x0f];
+    }
+    return out;
 }
 function errMessage(exc) {
     return exc instanceof Error ? exc.message : String(exc);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idpartners/client-attestation-sdk",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Client-side builder SDK for OAuth Attestation-Based Client Authentication",
   "type": "module",
   "main": "dist/index.js",