@idpartners/client-attestation-sdk 1.0.0 → 1.2.0

package/README.md

@@ -4,29 +4,30 @@ Client-side builder SDK for **OAuth Attestation-Based Client Authentication**
 (`draft-ietf-oauth-attestation-based-client-auth`). Mints the three artifacts a client
 presents at the token endpoint:
 
-- **Client Attestation JWT** (`typ=oauth-client-attestation+jwt`) — issued by a Client Attester,
+- **Client Attestation JWT** (`typ=oauth-client-attestation+jwt`) - issued by a Client Attester,
   names the client (`sub` = `client_id`) and binds its instance key via `cnf.jwk`.
-- **Client Attestation PoP JWT** (`typ=oauth-client-attestation-pop+jwt`) — proves possession of
+- **Client Attestation PoP JWT** (`typ=oauth-client-attestation-pop+jwt`) - proves possession of
   the instance key (PoP method `attestation_pop_jwt`).
-- **DPoP proof JWT** (`typ=dpop+jwt`) — combined mode (PoP method `dpop_combined`); its embedded
+- **DPoP proof JWT** (`typ=dpop+jwt`) - combined mode (PoP method `dpop_combined`); its embedded
   `jwk` header is the instance key bound in the attestation's `cnf`.
 
-This is one port of a polyglot SDK; it emits byte-compatible artifacts with the Java and Python
+This is one port of a polyglot SDK; it emits wire-compatible artifacts with the Java, Python and Go
 ports and is judged by a shared Java verifier. Built on [panva `jose`](https://github.com/panva/jose).
 `kid` values are RFC 7638 JWK thumbprints (SHA-256, base64url); `iat`/`exp` are integer epoch seconds.
 
-## Install / build
+## Install
 
 Requires **Node 20+**, or an edge runtime with WebCrypto and `fetch` (Cloudflare Workers, Vercel Edge,
 Deno Deploy) with no Node compatibility layer needed. Crypto, encoding and HTTP use web-standard APIs, and
 nothing imports a Node built-in at load time, so the builders, the one-call `ClientAttestation` flow, the
 issuance client and the token validator all work on the edge.
 
-CI tests this in a real Workers runtime: `npm run test:edge` bundles the package as an edge bundler would
-and runs it in [`workerd`](https://github.com/cloudflare/workerd), Cloudflare's open-source Workers runtime
+CI tests this in a real Workers runtime: `npm run test:edge` bundles the sources as an edge bundler would
+and runs them in [`workerd`](https://github.com/cloudflare/workerd), Cloudflare's open-source Workers runtime
 (1.20261007.1, compatibility date 2026-10-01, Node compatibility switched off). It generates keys, builds an
-attestation, a PoP and a DPoP proof, and runs the token validator against the shared validation vectors.
-Vercel Edge and Deno Deploy are not tested directly.
+attestation, a PoP and a DPoP proof, runs the token validator against the shared validation vectors, and
+checks `autoDetectEvidence` and `HttpSvidSource` there. The one-call flow and the issuance client are not
+run in workerd. Vercel Edge and Deno Deploy are not tested directly.
 
 Evidence gathering is the part that needs Node. Each of these loads the built-in it needs on first use; the
 two sources throw a `ClientAttestationError` naming themselves from `fetch` on a runtime without it:
@@ -42,23 +43,61 @@ two sources throw a `ClientAttestationError` naming themselves from `fetch` on a
 npm install @idpartners/client-attestation-sdk
 ```
 
+The package is ESM only (`"type": "module"`, no `require` export), so load it with `import`.
+
 To build from a clone:
 
 ```bash
-npm install
+cd typescript   # from the repository root
+npm ci
 npm run build   # tsc -> dist/
 ```
 
-## Usage
+The package exports ESM. Import from `@idpartners/client-attestation-sdk` or
+`@idpartners/client-attestation-sdk/validator`.
+
+## Get a token and call an API
+
+The attester must trust the workload identity and map it to an authorised client.
+Set `CLIENT_ATTESTATION_TOKEN_FILE` to an identity token file with the attester's evidence
+audience. `ATTESTER_URL`, `EVIDENCE_AUDIENCE` and `API_URL` are application variables.
+`EVIDENCE_AUDIENCE` is the audience your identity token carries, and the attester's discovery document must
+name it too.
+
+```bash
+export ATTESTER_URL=https://attester.example.com
+export EVIDENCE_AUDIENCE=https://attester.example.com/evidence
+export API_URL=https://api.example.com/data
+export CLIENT_ATTESTATION_TOKEN_FILE=/absolute/path/to/identity-token.jwt
+```
+
+Save as `call-api.mjs` in the application that installed the package:
+
+```js
+import { ClientAttestation } from "@idpartners/client-attestation-sdk";
+
+const ca = new ClientAttestation(process.env.ATTESTER_URL, { evidenceAudience: process.env.EVIDENCE_AUDIENCE });
+const response = await ca.fetch(process.env.API_URL);
+if (!response.ok) throw new Error(`API returned HTTP ${response.status}`);
+console.log(response.status);
+```
+
+Run `node call-api.mjs`. Retain `ca` for later calls so it reuses the token cache.
+`ca.fetch` attaches the access token and a DPoP proof when required. DPoP binds the token to
+a client key and requires a signed proof for each request.
+See [Configuration](../docs/configuration.md) for the options and evidence sources.
+
+## Build a credential offline
 
 jose's crypto is async, so key factories and `build()` return promises.
+This complete example generates temporary keys and needs no server.
 
 ```ts
 import {
   ClientAttestationBuilder,
   ClientAttestationCredential,
   SigningKeyPair,
-} from "client-attestation-sdk";
+} from "@idpartners/client-attestation-sdk";
 
 // Attester side: issue the attestation.
 const attester = await SigningKeyPair.generate("ES256");     // or SigningKeyPair.fromJwk(jwk, "ES256")
@@ -67,9 +106,6 @@ const attestation = await new ClientAttestationBuilder(attester, "https://attest
   .clientId("https://rp.example.com")
   .confirmationKey(instance)
   .expiresIn(300)
-  // optional: .authorizationDetails(...) / .workload(...) / .operator(sub, issuer?) —
-  // operator names who's accountable for running the client (RFC 8693 may_act-shaped; an
-  // assertion, not proof of authorisation), distinct from clientId and from the principal.
   .build();
 
 // Client side: produce token-request headers.
@@ -80,8 +116,13 @@ const popHeaders = await cred.popHeaders("https://rp.example.com", "https://as.e
 
 const dpopHeaders = await cred.dpopHeaders("POST", "https://as.example.com/as/token.oauth2");
 // { "OAuth-Client-Attestation": "...", "DPoP": "..." }
+console.log(Object.keys(popHeaders), Object.keys(dpopHeaders));
 ```
 
+Save as `build-credential.mjs` and run `node build-credential.mjs` after installing the package.
+The code also runs as TypeScript. A production authorisation server must trust the attester's
+signing key before it accepts a credential.
+
 The one-call `ClientAttestation` orchestration class (see the [root README](../README.md#get-a-token-in-one-call))
 wraps this: `{ popMethod: "dpop_combined" }` in its options switches it to DPoP mode, and a fetched
 challenge is carried through automatically as the PoP JWT's `challenge` claim or the DPoP proof's `nonce`
@@ -92,7 +133,12 @@ parameter. `DRAFT_REVISION` names the draft revision implemented (`"10"`).
 ### Presenting the token at a resource
 
 ```ts
-const ca = new ClientAttestation("pf.example.com", { popMethod: "dpop_combined" });
+import { ClientAttestation } from "@idpartners/client-attestation-sdk";
+
+const ca = new ClientAttestation("pf.example.com", {
+  evidenceAudience: "https://attester.example.com", // the audience your attester expects the identity token for
+  popMethod: "dpop_combined",
+});
 await ca.fetch("https://api.example.com/things");                     // headers + one nonce retry
 const headers = await ca.requestHeaders("GET", "https://api.example.com/things");
 ```
@@ -104,23 +150,31 @@ token and returns `Authorization: DPoP <t>` plus a fresh `DPoP` proof (`htm`, `h
 fragment, `ath`, and the last `DPoP-Nonce` that origin sent). `authorizationHeader()` still works, but for
 a DPoP-bound token it returns only the `DPoP` scheme - a resource will also want the proof.
 
-`ca.fetch` resends once when a resource answers with a `use_dpop_nonce` challenge (401
+For a DPoP-bound token, `ca.fetch` resends once when a resource answers with a `use_dpop_nonce` challenge (401
 `WWW-Authenticate: DPoP error="use_dpop_nonce"`, or a 400 JSON error) and a `DPoP-Nonce`. String,
 `URLSearchParams`, `ArrayBuffer` and `Request` bodies are resent; a one-shot `ReadableStream` body is not,
-and the challenge response is returned instead. The token request itself retries once on an AS's
-`use_dpop_nonce` demand.
+and the challenge response is returned instead. `ca.fetch` uses the global `fetch` with
+`redirect: "manual"`, so a redirect comes back to you and credentials are never resent to its target. In
+`dpop_combined` mode the token request itself retries once when the AS answers 400 `use_dpop_nonce` with
+a `DPoP-Nonce`.
 
 ### Failing closed
 
 - If the attester advertises a `challenge_endpoint` and the challenge cannot be fetched, `token()` throws
   `ClientAttestationError`. Pass `requireChallenge: false` to mint without one instead.
 - `CLIENT_ATTESTATION_TOKEN_FILE` or `SPIFFE_ENDPOINT_SOCKET` pointing at a missing path throws
-  `EvidenceNotFound` naming the variable - it never falls through to another identity source.
+  `EvidenceNotFound` naming the variable - it never falls through to another identity source. Auto-detect
+  checks `CLIENT_ATTESTATION_SVID` first, then the token file, then the SPIRE socket, so a variable is
+  only checked if nothing before it matched. `EvidenceNotFound` extends `Error`, not
+  `ClientAttestationError`.
 - `challengeAtToken: false` keeps the attester challenge in the mint's instance proof but leaves it out
   of the token-endpoint PoP `challenge` claim / DPoP `nonce` - for attesters that consume a challenge at
   mint and reject it when the token request presents it again.
 - The attester URL and every endpoint the attester advertises must be `https`, except loopback
   (`localhost`, `127.0.0.1`, `::1`). Pass `allowInsecure: true` for, say, an in-cluster plain-http PF.
+  `AttestationIssuanceClient.create` (its endpoint and every call its profile makes) and
+  `OpenBaoTransitSigner.create` (the vault address) follow the same rule and take the same `allowInsecure`
+  option.
 
 ### Other attesters
 
@@ -130,14 +184,80 @@ directly and skip discovery: `new ClientAttestation({ metadata: { evidenceAudien
 tokenEndpoint } })`. `AttestationIssuanceClient.create` takes `{ profile }` too. See
 [`docs/attester-profiles.md`](../docs/attester-profiles.md).
 
+## Resource server: validate an access token
+
+The validator is the second entry point, `@idpartners/client-attestation-sdk/validator`. The order of
+checks and the error codes are shared with the other ports and pinned by
+[`validation/SEMANTICS.md`](../validation/SEMANTICS.md).
+
+```ts
+import { AccessTokenValidator, ProtectedResource } from "@idpartners/client-attestation-sdk/validator";
+
+const validator = new AccessTokenValidator({
+  issuer: "https://issuer.example.com",
+  audiences: ["https://api.example.com"],
+  jwksUri: "https://issuer.example.com/jwks",
+  requiredScopes: ["read"],
+});
+const result = await validator.validate(accessToken);
+if (!result.valid) console.log(result.error);   // e.g. "expired", "insufficient_scope"
+// validate() ignores cnf: refuse result.claims.cnf unless you verify the sender proof (see below)
+
+const resource = new ProtectedResource("https://api.example.com", ["https://issuer.example.com"], validator);
+const decision = await resource.authenticate(request.headers.get("authorization"));
+// decision.status is 401, or 403 for missing scope; send decision.wwwAuthenticate back
+```
+
+By default a token's header `typ`, when present, must be `at+jwt`; pass `acceptedTokenTypes: null` for an
+issuer that stamps something else. `jwksUri` and the introspection `endpoint` must use https unless their
+host is loopback (`localhost`, `127.0.0.1`, `::1`); `allowInsecure: true` lifts that.
+
+`validate` checks the token only. It doesn't look at `cnf`, so a DPoP- or mTLS-bound token is `valid`
+without its sender proof: refuse one unless you verify that proof. `ProtectedResource.authenticate` is the
+request guard, and it refuses a token with a `cnf` claim with 401, because it never sees the sender proof.
+A runnable server is in
+[`examples/protected-resource-server.ts`](examples/protected-resource-server.ts).
+
 The validator's `ProtectedResource` strips control characters from every quoted `WWW-Authenticate` value,
 and validation failures never echo the token's own `alg`, `kid`, `iss` or `aud` back in
 `error_description`.
 
-## Test & interop
+## Token validator
+
+This fragment runs inside a resource-server request handler that supplies `accessToken`:
+
+```ts
+import { AccessTokenValidator } from "@idpartners/client-attestation-sdk/validator";
+
+const validator = new AccessTokenValidator({
+  issuer: "https://issuer.example.com",
+  audiences: ["https://api.example.com"],
+  jwksUri: "https://issuer.example.com/jwks",
+  requiredScopes: ["read"],
+});
+
+// In the handler:
+// const result = await validator.validate(accessToken);
+// if (!result.valid) reject(result.error);
+```
+
+`validate` checks the JWT signature and claims. `validateActive` uses RFC 7662 introspection
+with configured resource-server credentials. It does not first run `validate`.
+See [resource configuration](../docs/configuration.md#resource-server-configuration) and the
+[resource-server example](../docs/examples.md#protected-resource-examples).
+`ProtectedResource.authenticate` handles Bearer requests. It does not verify DPoP proofs.
+
+## Build, test and package
 
 ```bash
-npm test        # vitest — self-verifies each artifact with jose
+npm test        # vitest - self-verifies each artifact with jose
+npm run coverage
 npm run test:edge   # the same SDK in workerd, Cloudflare's Workers runtime, with no Node compatibility
+npm run build
+npm pack        # builds and creates a local .tgz archive; does not publish
 npm run emit    # writes ../vectors/out/typescript.json for the cross-language Java verifier
 ```
+
+Run these from `typescript/`. See [Build and test](../docs/building.md#typescript) for outputs
+and cross-language checks, [Examples](../docs/examples.md) for server prerequisites, and
+[Deployment](../docs/deployment.md) for deploying an application with the SDK.

package/dist/attester.d.ts

@@ -44,14 +44,14 @@ export interface AttesterProfile {
     /** Exchange the evidence and a proof of the instance key for an attestation. */
     mint(transport: AttesterTransport, metadata: AttesterMetadata, request: MintRequest): Promise<MintResult>;
 }
-/** Everything a profile needs to mint one attestation. */
+/**
+ * Everything a profile needs to mint one attestation. The evidence and the challenge are getters over
+ * private fields, so `JSON.stringify` and `console.log` of a request show neither.
+ */
 export declare class MintRequest {
+    #private;
     /** The fresh key the attestation will be bound to (its `cnf`). */
     readonly instanceKey: SigningKeyPair;
-    /** The workload's platform identity token (a JWT-SVID or equivalent). */
-    readonly evidence: string;
-    /** The attester-issued challenge, if any. */
-    readonly challenge?: string;
     /** Set by {@link AttestationIssuanceClient}; unset in the evidence-first one-call flow. */
     readonly clientId?: string;
     /** Optional RFC 9396 access request. */
@@ -66,7 +66,15 @@ export declare class MintRequest {
         authorizationDetails?: Array<Record<string, unknown>>;
         operator?: Record<string, unknown>;
     });
-    /** Sign `claims` as a compact JWS with the instance key, under header `typ` (no `jwk`). */
+    /** The workload's platform identity token (a JWT-SVID or equivalent). */
+    get evidence(): string;
+    /** The attester-issued challenge, if any. */
+    get challenge(): string | undefined;
+    /**
+     * Sign `claims` as a compact JWS with the instance key, under header `typ` (no `jwk`). `typ` may not be
+     * one the SDK's own credentials use (`ATTESTATION_TYP`, `POP_TYP`, `DPOP_TYP`): a profile could otherwise
+     * have the instance key sign a Client Attestation PoP or DPoP proof with claims of its choosing.
+     */
     sign(claims: Record<string, unknown>, typ: string): Promise<string>;
     /** A proof of possession of the instance key: `{aud, jti, iat[, challenge]}` signed with it. */
     instanceProof(typ: string, audience: string | undefined): Promise<string>;

package/dist/attester.js

@@ -9,16 +9,18 @@
  * {@link ClientAttestation} and {@link AttestationIssuanceClient} use {@link PingFederateProfile} unless
  * told otherwise, which is exactly the behaviour of earlier releases. See docs/attester-profiles.md.
  */
+import { ATTESTATION_TYP, DPOP_TYP, POP_TYP } from "./builders.js";
 import { ClientAttestationError } from "./errors.js";
 import { signCompact } from "./signing-key-pair.js";
-/** Everything a profile needs to mint one attestation. */
+/**
+ * Everything a profile needs to mint one attestation. The evidence and the challenge are getters over
+ * private fields, so `JSON.stringify` and `console.log` of a request show neither.
+ */
 export class MintRequest {
     /** The fresh key the attestation will be bound to (its `cnf`). */
     instanceKey;
-    /** The workload's platform identity token (a JWT-SVID or equivalent). */
-    evidence;
-    /** The attester-issued challenge, if any. */
-    challenge;
+    #evidence;
+    #challenge;
     /** Set by {@link AttestationIssuanceClient}; unset in the evidence-first one-call flow. */
     clientId;
     /** Optional RFC 9396 access request. */
@@ -27,14 +29,29 @@ export class MintRequest {
     operator;
     constructor(init) {
         this.instanceKey = init.instanceKey;
-        this.evidence = init.evidence;
-        this.challenge = init.challenge;
+        this.#evidence = init.evidence;
+        this.#challenge = init.challenge;
         this.clientId = init.clientId;
         this.authorizationDetails = init.authorizationDetails;
         this.operator = init.operator;
     }
-    /** Sign `claims` as a compact JWS with the instance key, under header `typ` (no `jwk`). */
-    sign(claims, typ) {
+    /** The workload's platform identity token (a JWT-SVID or equivalent). */
+    get evidence() {
+        return this.#evidence;
+    }
+    /** The attester-issued challenge, if any. */
+    get challenge() {
+        return this.#challenge;
+    }
+    /**
+     * Sign `claims` as a compact JWS with the instance key, under header `typ` (no `jwk`). `typ` may not be
+     * one the SDK's own credentials use (`ATTESTATION_TYP`, `POP_TYP`, `DPOP_TYP`): a profile could otherwise
+     * have the instance key sign a Client Attestation PoP or DPoP proof with claims of its choosing.
+     */
+    async sign(claims, typ) {
+        if (reservedTyp(typ)) {
+            throw new Error(`typ ${JSON.stringify(typ)} is reserved for the SDK's own credentials; a profile cannot sign it with the instance key`);
+        }
         return signCompact(claims, this.instanceKey, typ, false);
     }
     /** A proof of possession of the instance key: `{aud, jti, iat[, challenge]}` signed with it. */
@@ -49,6 +66,14 @@ export class MintRequest {
         return this.sign(claims, typ);
     }
 }
+/**
+ * Whether `typ` names one of the SDK's own credential types, compared as RFC 7515 section 4.1.9 says a
+ * verifier may: case-insensitively, with or without the `application/` prefix.
+ */
+function reservedTyp(typ) {
+    const t = String(typ).trim().toLowerCase().replace(/^application\//, "");
+    return t === ATTESTATION_TYP || t === POP_TYP || t === DPOP_TYP;
+}
 /**
  * The PingFederate profile's discovery document path.
  *
@@ -108,9 +133,8 @@ export class PingFederateProfile {
         const response = await transport.requestJson("mint", "POST", metadata.attestationEndpoint, body);
         const attestation = response.attestation;
         if (typeof attestation !== "string" || !attestation) {
-            throw new ClientAttestationError("attester response contained no attestation", {
-                body: JSON.stringify(response),
-            });
+            // No body: a 2xx mint response may hold the attestation under another name.
+            throw new ClientAttestationError("attester response contained no attestation");
         }
         const expiresIn = response.expires_in;
         return { attestation, expiresIn: typeof expiresIn === "number" ? expiresIn : undefined };

package/dist/builders.d.ts

@@ -16,7 +16,12 @@ export declare class ClientAttestationBuilder {
     constructor(attesterKey: SigningKeyPair | JwsSigner, issuer: string);
     /** The client being attested — becomes the attestation `sub` (= `client_id`). */
     clientId(clientId: string): this;
-    /** Binds the client instance key as `cnf.jwk`. Must be a public JWK. */
+    /**
+     * Binds the client instance key as `cnf.jwk`: an EC (`crv` P-256, P-384 or P-521, `x`, `y`) or RSA
+     * (`n`, `e`) public key. Throws for one carrying private or secret members (`d`, `p`, `q`, `dp`, `dq`,
+     * `qi`, `oth`, `k`) or another `kty`. Only those members and an optional `kid` are copied into the
+     * attestation.
+     */
     confirmationJwk(publicInstanceJwk: JWK): this;
     /** Convenience: binds the public half of the given instance key as `cnf.jwk`. */
     confirmationKey(instanceKey: SigningKeyPair): this;
@@ -75,8 +80,11 @@ export declare class DpopProofBuilder {
     /** The request's HTTP method (`htm`, upper-cased when built); defaults to `POST`. */
     method(htm: string | null | undefined): this;
     /**
-     * The target URL (`htu`) — required. Normalised when built: query and fragment are dropped, and
-     * scheme and host lower-cased (RFC 9449 section 4.2).
+     * The target URL (`htu`) — required. Normalised when built (RFC 9449 section 4.2) by the rule in
+     * vectors/README.md: userinfo, query, fragment and a default port are dropped, and scheme and host
+     * lower-cased. `build` refuses a URL that is not an absolute http(s) URL with a valid ASCII host, port
+     * and path, or that has a backslash, ASCII whitespace or a control character before its query or
+     * fragment.
      */
     uri(htu: string): this;
     /** The server challenge, carried in DPoP `nonce`. */

package/dist/builders.js

@@ -35,9 +35,14 @@ export class ClientAttestationBuilder {
         this.#clientId = clientId;
         return this;
     }
-    /** Binds the client instance key as `cnf.jwk`. Must be a public JWK. */
+    /**
+     * Binds the client instance key as `cnf.jwk`: an EC (`crv` P-256, P-384 or P-521, `x`, `y`) or RSA
+     * (`n`, `e`) public key. Throws for one carrying private or secret members (`d`, `p`, `q`, `dp`, `dq`,
+     * `qi`, `oth`, `k`) or another `kty`. Only those members and an optional `kid` are copied into the
+     * attestation.
+     */
     confirmationJwk(publicInstanceJwk) {
-        this.#cnfJwk = publicInstanceJwk;
+        this.#cnfJwk = confirmationJwkMembers(publicInstanceJwk);
         return this;
     }
     /** Convenience: binds the public half of the given instance key as `cnf.jwk`. */
@@ -122,14 +127,61 @@ export class ClientAttestationBuilder {
         return signExternal(claims, this.#attesterKey, ATTESTATION_TYP);
     }
     #resolveExpiry(iat) {
+        let exp;
         if (this.#expiresAt !== null) {
-            return this.#expiresAt;
+            exp = this.#expiresAt;
+        }
+        else if (this.#ttl !== null) {
+            exp = iat + this.#ttl;
+        }
+        else {
+            throw new Error("expiry is required: call expiresAt(...) or expiresIn(...)");
+        }
+        if (!(exp > iat)) {
+            throw new Error(`attestation exp (${exp}) must be after iat (${iat})`);
+        }
+        return exp;
+    }
+}
+/** JWK members that carry private or secret key material (RFC 7518 section 6). */
+const PRIVATE_JWK_MEMBERS = ["d", "p", "q", "dp", "dq", "qi", "oth", "k"];
+/** The public members a `cnf.jwk` of each key type must carry. */
+const CONFIRMATION_JWK_MEMBERS = { EC: ["crv", "x", "y"], RSA: ["n", "e"] };
+/**
+ * The public key to bind as `cnf.jwk`: `kty`, the key type's public members and an optional `kid`, in the
+ * order the input has them. Refuses private or secret members, another `kty` or curve, or a missing member,
+ * so a private key is never signed into an attestation.
+ */
+function confirmationJwkMembers(jwk) {
+    if (jwk === null || typeof jwk !== "object" || Array.isArray(jwk)) {
+        throw new Error("cnf.jwk must be a JWK object");
+    }
+    const members = jwk;
+    for (const member of PRIVATE_JWK_MEMBERS) {
+        if (member in members) {
+            throw new Error(`cnf.jwk must be a public key: it carries the private member '${member}'`);
         }
-        if (this.#ttl !== null) {
-            return iat + this.#ttl;
+    }
+    const kty = members.kty;
+    const required = typeof kty === "string" && Object.hasOwn(CONFIRMATION_JWK_MEMBERS, kty)
+        ? CONFIRMATION_JWK_MEMBERS[kty]
+        : undefined;
+    if (!required) {
+        throw new Error(`cnf.jwk must be an EC or RSA public key, not kty ${JSON.stringify(kty)}`);
+    }
+    for (const member of required) {
+        if (typeof members[member] !== "string" || members[member] === "") {
+            throw new Error(`cnf.jwk (kty ${kty}) is missing '${member}'`);
         }
-        throw new Error("expiry is required: call expiresAt(...) or expiresIn(...)");
     }
+    if (kty === "EC" && !["P-256", "P-384", "P-521"].includes(members.crv)) {
+        throw new Error(`cnf.jwk curve must be P-256, P-384 or P-521, not ${JSON.stringify(members.crv)}`);
+    }
+    if ("kid" in members && (typeof members.kid !== "string" || members.kid === "")) {
+        throw new Error("cnf.jwk kid must be a non-empty string");
+    }
+    const keep = new Set(["kty", "kid", ...required]);
+    return Object.fromEntries(Object.entries(members).filter(([k]) => keep.has(k)));
 }
 /**
  * Builds a Client Attestation PoP JWT proving possession of the instance key. Client side of
@@ -208,8 +260,11 @@ export class DpopProofBuilder {
         return this;
     }
     /**
-     * The target URL (`htu`) — required. Normalised when built: query and fragment are dropped, and
-     * scheme and host lower-cased (RFC 9449 section 4.2).
+     * The target URL (`htu`) — required. Normalised when built (RFC 9449 section 4.2) by the rule in
+     * vectors/README.md: userinfo, query, fragment and a default port are dropped, and scheme and host
+     * lower-cased. `build` refuses a URL that is not an absolute http(s) URL with a valid ASCII host, port
+     * and path, or that has a backslash, ASCII whitespace or a control character before its query or
+     * fragment.
      */
     uri(htu) {
         this.#htu = htu;
@@ -265,20 +320,106 @@ export async function accessTokenHash(accessToken) {
     return base64url.encode(new Uint8Array(digest));
 }
 /**
- * The DPoP `htu` for a URL: scheme, host, port and path, with no query and no fragment. Scheme and host
- * are lower-cased and a default port dropped; a URL with no path keeps none (no slash is invented).
+ * Throws unless `url` is free of backslashes, ASCII whitespace and control characters before its query or
+ * fragment (the part that becomes `htu`). URL parsers disagree on where such a URL goes - WHATWG reads
+ * `https://evil.example\@as.example/t` as a request to evil.example, `urllib.parse` as one to
+ * as.example - so a proof's `htu` could name a different server from the one the request reaches.
  *
  * @internal
  */
-export function normalizeHtu(url) {
+export function checkHtu(url) {
+    const head = url.split(/[?#]/, 1)[0];
+    if (/[\x00-\x20\x7f\\]/.test(head)) {
+        throw new Error("uri (htu) must not contain a backslash, whitespace or control character");
+    }
+}
+/** The schemes an `htu` may have, with their default ports. */
+const HTU_DEFAULT_PORTS = { http: "80", https: "443" };
+const HTU_NOT_ABSOLUTE = "uri (htu) must be an absolute http or https URL with a host";
+const HTU_HOST = "uri (htu) has an invalid host";
+const HTU_PORT = "uri (htu) has an invalid port";
+const HTU_PATH = "uri (htu) has an invalid path";
+/**
+ * `[origin, path]` of a request URL's `htu`, by the rule in vectors/README.md that every port applies
+ * alike: an absolute http(s) URL with a host; scheme and host lower-cased (ASCII only, an IPv6 literal as
+ * written); no userinfo; the port as a plain number and dropped when it is the scheme's default; the path
+ * as written with non-ASCII characters percent-encoded (UTF-8); no query or fragment. It
+ * is read from the string itself, not through WHATWG `URL`, which would also resolve dot-segments,
+ * compress IPv6 and convert IDN hosts. Anything else throws.
+ *
+ * @internal
+ */
+export function htuParts(url) {
+    checkHtu(url);
     const bare = url.split(/[?#]/, 1)[0];
-    let parsed;
+    const sep = bare.indexOf("://");
+    const scheme = sep < 0 ? "" : bare.slice(0, sep).toLowerCase();
+    if (!Object.hasOwn(HTU_DEFAULT_PORTS, scheme)) {
+        throw new Error(HTU_NOT_ABSOLUTE);
+    }
+    const rest = bare.slice(sep + 3);
+    const slash = rest.indexOf("/");
+    const authority = slash < 0 ? rest : rest.slice(0, slash);
+    const path = slash < 0 ? "" : rest.slice(slash);
+    const hostport = authority.slice(authority.lastIndexOf("@") + 1);
+    let host;
+    let port = "";
+    if (hostport.startsWith("[")) {
+        const close = hostport.indexOf("]");
+        const literal = close < 0 ? "" : hostport.slice(1, close);
+        const after = close < 0 ? "" : hostport.slice(close + 1);
+        if (!literal.includes(":") || !/^[0-9A-Fa-f:.]*$/.test(literal) || (after !== "" && after[0] !== ":")) {
+            throw new Error(HTU_HOST);
+        }
+        host = `[${literal.toLowerCase()}]`;
+        port = after.slice(1);
+    }
+    else {
+        const colon = hostport.indexOf(":");
+        host = colon < 0 ? hostport : hostport.slice(0, colon);
+        port = colon < 0 ? "" : hostport.slice(colon + 1);
+        if (host === "") {
+            throw new Error(HTU_NOT_ABSOLUTE);
+        }
+        if (!/^[A-Za-z0-9\-._~]+$/.test(host)) {
+            throw new Error(HTU_HOST);
+        }
+        host = host.toLowerCase();
+    }
+    if (port !== "") {
+        const digits = port.replace(/^0+/, "");
+        if (!/^[0-9]+$/.test(port) || digits.length > 5 || Number(digits) > 65535) {
+            throw new Error(HTU_PORT);
+        }
+        const n = String(Number(digits));
+        if (n !== HTU_DEFAULT_PORTS[scheme]) {
+            host += `:${n}`;
+        }
+    }
+    return [`${scheme}://${host}`, encodeHtuPath(path)];
+}
+/**
+ * `path` with every non-ASCII character percent-encoded as UTF-8 (upper-case hex) and every ASCII
+ * character kept as written, `%XX` escapes, a lone `%` and characters outside RFC 3986 `pchar` included:
+ * those are what the HTTP client sends, and a server compares `htu` after RFC 3986 section 6.2.2
+ * normalisation, which decodes only unreserved characters. (`checkHtu` has already refused controls,
+ * whitespace and backslash.) A lone surrogate is refused.
+ */
+function encodeHtuPath(path) {
     try {
-        parsed = new URL(bare);
+        return path.replace(/[^\x00-\x7f]+/g, (run) => encodeURIComponent(run)); // throws on a lone surrogate
     }
     catch {
-        return bare;
+        throw new Error(HTU_PATH);
     }
-    const hasPath = /^[a-z][a-z0-9+.-]*:\/\/[^/]*\//i.test(bare);
-    return `${parsed.protocol}//${parsed.host}${hasPath ? parsed.pathname : ""}`;
+}
+/**
+ * The DPoP `htu` for a URL (RFC 9449 section 4.2): the origin and path {@link htuParts} gives. A URL
+ * with no path keeps none (no slash is invented).
+ *
+ * @internal
+ */
+export function normalizeHtu(url) {
+    const [origin, path] = htuParts(url);
+    return origin + path;
 }

package/dist/errors.d.ts

@@ -2,7 +2,11 @@
  * The SDK's error types. {@link ClientAttestationError} is the base for every failure of the
  * one-call flow; {@link TransportError} is the subclass for anything that went wrong on the wire.
  */
-/** A step in the flow failed. `status` and `body` are set for HTTP failures. */
+/**
+ * A step in the flow failed. `status` and `body` are set for HTTP failures: `body` is at most the first 512
+ * characters of a non-2xx response, and unset for a 2xx response that could not be used, since that body
+ * may hold a token, attestation or SVID.
+ */
 export declare class ClientAttestationError extends Error {
     readonly status?: number;
     readonly body?: string;
@@ -17,7 +21,7 @@ export type TransportFailure = "network" | "timeout" | "redirect" | "too_large"
 /**
  * An outbound HTTP call failed: unreachable, timed out, redirected, oversized, non-2xx, or malformed
  * JSON (see {@link kind}). `status` is set when a response was received; `body` holds at most the first
- * 512 characters of it.
+ * 512 characters of a non-2xx one.
  */
 export declare class TransportError extends ClientAttestationError {
     readonly kind: TransportFailure;