@idpartners/client-attestation-sdk 1.0.1 → 1.4.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

@@ -7,8 +7,14 @@ export interface AttesterMetadata {
     attestationEndpoint?: string;
     /** The authorization server's token endpoint. A profile fills in its own fallback. */
     tokenEndpoint?: string;
-    /** The draft's challenge endpoint, if the attester issues challenges. */
+    /** The attester's challenge endpoint (CAS section 4.1), if the attester issues challenges for the mint. */
     challengeEndpoint?: string;
+    /**
+     * The authorization server's challenge endpoint (draft -11 section 6.3), if it issues challenges for
+     * the token request: `POST`ed before each token request, and its `attestation_challenge` carried as
+     * the PoP JWT's `challenge` claim or the DPoP proof's `nonce`. PingFederate: `/federation/attestation-challenge`.
+     */
+    tokenChallengeEndpoint?: string;
     /** The Client Attestation PoP `aud` (the AS issuer); falls back to the token endpoint URL. */
     popAudience?: string;
     /** The raw discovery document, when there was one; returned by `ClientAttestation.discovery()`. */
@@ -44,14 +50,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 +72,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>;
@@ -77,8 +91,8 @@ export declare const INSTANCE_PROOF_TYP = "oauth-attestation-instance-proof+jwt"
  * The attester this SDK was built against (PingFederate), and the default.
  *
  * - Discovery: `GET {attesterUrl}/.well-known/client-attester`, a JSON object with `evidence_audience`,
- *   `attestation_endpoint`, `challenge_endpoint`, `token_endpoint` and `pop_audience`. With no
- *   `token_endpoint`, `{attesterUrl}/as/token.oauth2`.
+ *   `attestation_endpoint`, `challenge_endpoint`, `token_endpoint`, `token_challenge_endpoint` and
+ *   `pop_audience`. With no `token_endpoint`, `{attesterUrl}/as/token.oauth2`.
  * - Mint: `POST attestation_endpoint` with JSON `{[client_id,] instance_key, svid, proof
  *   [, authorization_details][, operator]}`, where `proof` is `{aud: evidence_audience, jti, iat
  *   [, challenge]}` signed by the instance key with `typ` `oauth-attestation-instance-proof+jwt`. The

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.
  *
@@ -61,8 +86,8 @@ export const INSTANCE_PROOF_TYP = "oauth-attestation-instance-proof+jwt";
  * The attester this SDK was built against (PingFederate), and the default.
  *
  * - Discovery: `GET {attesterUrl}/.well-known/client-attester`, a JSON object with `evidence_audience`,
- *   `attestation_endpoint`, `challenge_endpoint`, `token_endpoint` and `pop_audience`. With no
- *   `token_endpoint`, `{attesterUrl}/as/token.oauth2`.
+ *   `attestation_endpoint`, `challenge_endpoint`, `token_endpoint`, `token_challenge_endpoint` and
+ *   `pop_audience`. With no `token_endpoint`, `{attesterUrl}/as/token.oauth2`.
  * - Mint: `POST attestation_endpoint` with JSON `{[client_id,] instance_key, svid, proof
  *   [, authorization_details][, operator]}`, where `proof` is `{aud: evidence_audience, jti, iat
  *   [, challenge]}` signed by the instance key with `typ` `oauth-attestation-instance-proof+jwt`. The
@@ -84,6 +109,7 @@ export class PingFederateProfile {
             // discovery document still works from the host alone.
             tokenEndpoint: str("token_endpoint") ?? attesterUrl + PingFederateProfile.DEFAULT_TOKEN_PATH,
             challengeEndpoint: str("challenge_endpoint"),
+            tokenChallengeEndpoint: str("token_challenge_endpoint"),
             popAudience: str("pop_audience"),
             document: doc,
         };
@@ -108,9 +134,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 };
@@ -130,6 +155,7 @@ export function metadataDocument(metadata) {
         ["attestation_endpoint", metadata.attestationEndpoint],
         ["challenge_endpoint", metadata.challengeEndpoint],
         ["token_endpoint", metadata.tokenEndpoint],
+        ["token_challenge_endpoint", metadata.tokenChallengeEndpoint],
         ["pop_audience", metadata.popAudience],
     ];
     for (const [key, value] of fields)

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`. */