@hawcx/oauth-client 5.2.0 → 6.2.0

package/CHANGELOG.md

@@ -5,6 +5,361 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [6.2.0] - 2026-11-02
+
+Additive, apart from these `exchangeCode` / token-endpoint behaviour changes
+(details under Changed): a 3xx from the token endpoint is no longer followed
+and throws `TokenExchangeError`; a 2xx token response that is not a JSON
+object throws `TokenExchangeError` instead of a raw `SyntaxError`/`TypeError`
+(or being returned as-is); a 2xx body cut off mid-read throws a network
+`TokenExchangeError` carrying that 2xx `statusCode`.
+
+### Added
+
+- **Profile service client.** `ProfileClient` (`oauth.profile(options?)` or
+  `new ProfileClient(oauth, options?)`), built from a discovery-mode
+  `HawcxOAuth` with a `private_key_jwt` signer. Machine methods (RFC 6749 §4.4
+  `client_credentials`): `getUser`, `listUsers`/`iterUsers`, `createUser`,
+  `updateUser`, `replaceUser`, `deleteUser`, `getConsents`, `setConsent`,
+  `getAudit`/`iterAudit`. `forUser(idToken)` returns a `UserProfileClient`
+  (RFC 8693 exchange of the ID token for a `profile:self` token): `getMe`,
+  `updateMe`, `getMyConsents`, `setMyConsent`, `getMyAudit`/`iterMyAudit`.
+  Tokens are cached with early refresh and single-flight minting; expiry is
+  counted from when the token request was sent. The early refresh runs in the
+  background, so every caller (the one that triggered it included) gets the
+  still-valid cached token; if it fails (any error, e.g. a signer error too)
+  that token stays in use and no other early refresh is tried for 30 s (or
+  until expiry, if sooner). `forUser` tokens are not refreshed early (the OP
+  caps their `exp` at the ID token's), only at expiry. A 401 is
+  replayed once with a fresh token; for `forUser`, if that re-exchange fails
+  with a non-transient token error (e.g. `invalid_grant`, the ID token has
+  expired), the original 401 `ProfileApiError` is thrown (token error as
+  `cause`); GET/PUT/DELETE retry on transient
+  failures (Retry-After honoured, capped at 30 s); a token-endpoint network
+  error, 408, 429, 502, 503 or 504 is retried for every method within the same
+  budget (no profile request was sent), with backoff only (its Retry-After is
+  ignored); POST/PATCH are otherwise never
+  retried; a DELETE answered 404 counts as success once any earlier attempt of
+  the call may have run (no HTTP response, or 504; not 502, which is
+  ambiguous but left out because a false "deleted" is worse). Errors that
+  mean nothing was sent do not count: `fetch()` rejecting with a connect/DNS
+  or TLS-handshake code (ECONNREFUSED, ENOTFOUND, EAI_*, connect timeouts,
+  CERT_*/ERR_TLS_*/ERR_SSL_*), or a routing code (EHOSTUNREACH, ENETUNREACH,
+  EHOSTDOWN, ENETDOWN, EADDRNOTAVAIL) with `syscall: 'connect'`; an injected
+  `fetch` whose errors carry none of these counts as may-have-run. A failure
+  reading a 2xx body always counts, and its error keeps the 2xx status
+  (title `Response body read failed`) rather than 0, since the call ran.
+  Redirects are not
+  followed; path parameters, and `createUser`'s `user_id`, must be one segment
+  (`/`, `\` and control characters refused). `deleteUser` counts any 2xx as
+  success, whatever its body (empty, whitespace, not JSON, not an object).
+  Iterators stop on a null, missing or empty-string `next_cursor`. An
+  explicitly empty `scopes` list throws `HawcxError` when the client is built
+  (omit `scopes` for the client's default). `timeout` (default 10000) bounds
+  each token-endpoint call too, not only profile requests, whatever the
+  `HawcxOAuth` client's own `timeout`. `ProfilePatch.status` is `string` (no
+  `null`: the server answers 422 to a null status).
+- **`forUser` is for right after sign-in.** The OP caps the delegated token's
+  `exp` at the ID token's (`id_token_ttl_seconds`, 60 s by default), so pass
+  the ID token `exchangeCode` just returned; for later work on a user's
+  profile use the machine methods with their `user_id` (the `sub` claim).
+- **`ProfileApiError`** (`HawcxError` subclass) mapped from RFC 9457
+  problem+json: `status`, `title`, `detail`, `type`, `instance`, `requestId`,
+  `retryAfter`, `missing`, `fields`, `body`, `rawBody` (the body text, capped
+  at 4096 UTF-16 code units, kept out of `message`; on a malformed 2xx only
+  when the body is a markup page starting with `<`, since any other body may
+  be a mangled profile, i.e. PII). A Kong-style `{"message"}` body
+  (no non-blank `title`/`detail`) uses `message` as `detail`; `requestId`
+  falls back to the body's `request_id`. A non-204 2xx profile body that is
+  not a JSON object (or lacks a required field), and a 204, to any method but
+  `deleteUser`, throw `ProfileApiError` "Unexpected response body"; an
+  unparseable body "Invalid JSON response".
+
+### Changed
+
+- `exchangeCode` no longer follows redirects from the token endpoint: a 3xx is
+  now a `TokenExchangeError`, so the code, PKCE verifier and client assertion
+  are never re-posted to another host. A token-endpoint network error now
+  carries the underlying error as `cause` and sets the new
+  `TokenExchangeError.network` flag (`true` when no complete HTTP response
+  came back, including a 2xx body cut off mid-read, which keeps the 2xx in
+  `statusCode`). A 2xx token response
+  that was read in full but is not a JSON object now throws a non-network
+  `TokenExchangeError` ("Invalid JSON in token response") instead of a raw
+  `SyntaxError`/`TypeError`.
+
+## [6.1.0] - 2026-10-12
+
+Additive; no behaviour change for existing callers.
+
+### Added
+
+- **Custom domains.** Optional `customDomain` on
+  `HawcxOAuth.fromIssuer(...)` (e.g. `https://auth.example.com`), validated as
+  a raw string (same rules as the Python and Java SDKs): `scheme://host[:port]`
+  only, https (http only for loopback), ASCII/punycode hostname (no `*`, `_`,
+  trailing dot, numeric-looking last label) or canonical IP literal, port
+  1-65535 without leading zeros, no userinfo, path, query, fragment,
+  whitespace, `\` or `%`; IPv6 without embedded IPv4. Canonicalised
+  (lower-cased, default port dropped, IPv6 in RFC 5952 form, loopback checked
+  on the canonical host).
+  `null`/`undefined` = unset. An invalid value throws `HawcxOAuthError`
+  (`error: 'invalid_custom_domain'`) from `fromIssuer` before any fetch. It
+  changes only the browser URLs below; discovery, token exchange, JWKS and the
+  `iss` check stay on the issuer.
+- **`buildAuthorizeUrl(options)`** builds the `/authorize` URL from the
+  discovered `authorization_endpoint`: origin (custom domain if set, else the
+  endpoint's raw scheme and authority) + the
+  endpoint's raw path and query, copied verbatim, then `response_type=code`,
+  `client_id`, `redirect_uri`, `scope` (blank → `openid`), `state`,
+  `code_challenge`, `code_challenge_method=S256`, and optional `nonce`,
+  `prompt` (blank = empty or ASCII whitespace only → omitted) and `extraParams` (non-empty keys, string values,
+  insertion order kept). `extraParams` cannot set any SDK parameter, `request`
+  or `request_uri`, nor a name already in the endpoint query. Missing or blank `redirectUri` / `state` / `codeChallenge`
+  or a bad `extraParams` entry throws `HawcxOAuthError`
+  (`error: 'invalid_request'`).
+- **`buildEndSessionUrl(options?)`** builds the logout URL from the discovered
+  `end_session_endpoint` the same way; always sends `client_id`, plus
+  `post_logout_redirect_uri`, `id_token_hint` and `state` when non-blank.
+  `null` options = `{}`.
+- Both helpers are discovery-mode only (legacy mode throws `HawcxOAuthError`,
+  `error: 'issuer_mode_required'`). A discovered endpoint that is missing, not
+  https (loopback http ok), has userinfo, no host, any `#`, a character
+  outside printable ASCII or any of `` \ " < > ^ ` { | } ``, or a query that
+  already sets one of the helper's SDK parameters (authorize: also `request`,
+  `request_uri`) throws `DiscoveryError`
+  (`error: 'invalid_discovery_document'`) when the helper is called, never
+  from `fromIssuer`, so discovery documents without these fields keep working.
+- URLs are semantically, not byte-for-byte, equal across the Node, Python and
+  Java SDKs (parameter encoding differs on e.g. `~`, `*`, space).
+- New exported types `AuthorizeUrlOptions` and `EndSessionUrlOptions`.
+
+## [6.0.0] - 2026-10-10
+
+First public release since 5.2.0. **Major version** because of the BREAKING
+entries below, which change behaviour for configurations that 5.2.0 accepted.
+It contains everything from the internal release candidates 6.0.0-rc.1 and
+6.0.0-rc.2, plus one fix to `ClientAssertionSigner` made after rc.2.
+
+### Breaking — action needed when upgrading from 5.2.0
+
+- **Management API response signatures are verified by default
+  (TOB-HSDK-11).** `JwtBearerTransport` and `StepUpClient.withPrivateKeyJwt`
+  now verify `X-Response-Signature` on every successful response. This
+  reverses the 5.2.0 note that callers "may" verify the header themselves.
+  The SDK checks the following:
+  - the JWS uses ES256, ES384 or ES512 and verifies against
+    `${issuer}/.well-known/jwks.json`;
+  - `iat` is within `clockSkewSeconds` (default 300);
+  - `body_sha256` matches the exact response bytes;
+  - the token carries no `aud`, `sub` or `nonce`.
+
+  Responses with status 400 and above are not verified. hx_auth signs every
+  jwt-mode 2xx, so production traffic is unaffected. **Action needed** if any
+  of these apply:
+  - A gateway, CDN or proxy strips response headers. Every call fails with
+    `ResponseSignatureInvalidError`; let `X-Response-Signature` through.
+  - Mocks, stubs or contract-test harnesses built against 5.2.0 return
+    unsigned 2xx responses. Sign the responses, or disable verification in the
+    test harness.
+  - `baseUrl` is not the OP host, such as an internal service URL or local dev
+    with separate ports. The JWKS is fetched from `baseUrl` by default, so set
+    `issuer`.
+- **`baseUrl` (and `issuer`) values that used to be accepted now throw at
+  construction (TOB-HSDK-13).** The affected classes are `JwtBearerTransport`
+  and `StepUpClient.withPrivateKeyJwt` (`DelegationRequestError`),
+  `DelegationTransport` and the `DelegationClient`/`StepUpClient` ECIES
+  factories (`DelegationRequestError`), legacy `HawcxOAuth`
+  (`HawcxOAuthError`), and `HawcxOAuth.fromIssuer` (`DiscoveryError`):
+  - **Plain `http:` on a non-loopback host.** Examples:
+    `http://hawcx-api:8080` (docker-compose service name),
+    `http://0.0.0.0:8080`, `http://host.docker.internal:8080`, and in-cluster
+    service URLs behind a TLS-terminating gateway. Only `localhost`,
+    `127.0.0.1` and `[::1]` may use `http:`. **Action needed:** use `https:`,
+    or point the SDK at a loopback address.
+  - **Userinfo, query or fragment in the base.** For example
+    `https://user:pw@api.hawcx.com`, `https://api.hawcx.com?tenant=x` or
+    `https://api.hawcx.com#x`. **Action needed:** remove them.
+- **The signed JWT `aud` string changes for non-canonical base spellings
+  (TOB-HSDK-13).** Host case and default ports are now normalised, so
+  `baseUrl: 'https://API.Hawcx.com:443'` produces
+  `aud = https://api.hawcx.com/v1/...`, where 5.2.0 produced
+  `https://API.Hawcx.com:443/v1/...`. The new value is the one `fetch`
+  actually sends. **Action needed** only if a server compares `aud` by exact
+  string against a configured non-canonical value: update that value, or use
+  a canonical `baseUrl`. Canonical bases (lower-case host, no default port,
+  with or without a trailing slash or a path prefix) produce byte-identical
+  URLs and `aud`.
+
+### Added
+
+- New options on `JwtBearerTransport` and `StepUpClient.withPrivateKeyJwt`:
+  `issuer` (defaults to `baseUrl`), `verifyResponseSignature` (defaults to
+  `true`) and `clockSkewSeconds`. `verifyResponseSignature: false` is an
+  **emergency escape hatch** that restores the 5.2.0 behaviour and emits a
+  one-time process warning. `withPrivateKeyJwt` now also passes
+  `clockSkewSeconds` through to the transport.
+- New error classes, both subclasses of `DelegationResponseError`, exported
+  with a stable `code`:
+  - `ResponseSignatureInvalidError` (`response_signature_invalid`).
+  - `ResponseSignatureUnavailableError` (`response_signature_unavailable`).
+    It means the signing keys could not be fetched, and **the request may
+    already have been applied** server-side.
+
+### Changed
+
+- Every security-relevant URL is now parsed and joined with the WHATWG `URL`
+  API rather than by string concatenation (TOB-HSDK-13). This covers
+  `JwtBearerTransport` and `DelegationTransport` (`baseUrl` + endpoint),
+  legacy `new HawcxOAuth({ baseUrl })` (`/oauth2/token` and `/keys`), and the
+  `fromIssuer` issuer and discovery URL. Each joined URL must keep the base's
+  origin and stay under the base path prefix, or the SDK throws (fail
+  closed). An endpoint must be a relative path that starts with a single
+  `/`. It may not contain `//`, a backslash, whitespace or control
+  characters, a fragment, or a percent-encoded `/`, `.` or `\` (`%2f`,
+  `%2e`, `%5c`, any case) in its path.
+- Discovered `token_endpoint` and `jwks_uri` values carrying userinfo are now
+  rejected (`DiscoveryError`).
+- The `clearCache()` deprecation warning now says it will be removed in a
+  future major version rather than in 6.0.0. It is still deprecated (use
+  `refreshJwks()`) and still present in 6.0.0.
+
+### Fixed
+
+- **Discovery mode now sends `client_id` on the public-client (PKCE) token
+  exchange.** Previously `exchangeCode()` added `client_id` to the token form
+  only when a `private_key_jwt` signer was set; a public PKCE exchange sent
+  only the `X-Config-Id` header. The OP then fell back to the project's
+  default client (`token.legacy_config_id_fallback`) and stamped the id_token
+  `aud` with that client's id, so on a project with more than one public OIDC
+  client, an app using a non-default client failed verification with
+  "Unexpected JWT audience". `exchangeCode()` now always sends the configured
+  `clientId` as `client_id` in discovery mode (RFC 6749 §4.1.3), for public
+  and `private_key_jwt` clients alike; the OP resolves that specific client
+  and stamps `aud` with it. `X-Config-Id` is still sent.
+  - Single-client projects are unaffected: their `clientId` is the default
+    client, so the resolved client and `aud` are the same as before.
+  - Legacy mode (`new HawcxOAuth({ configId, baseUrl })`) has no `clientId`
+    and is unchanged: it sends no `client_id`.
+- `ClientAssertionSigner.sign()` now reads the clock once for `iat` and `exp`.
+  Two separate reads could straddle a second boundary and make the assertion
+  one second longer than its lifetime; at `withLifetimeSeconds(120)` that
+  exceeds the OP's 120s cap and the token exchange is rejected.
+
+## [6.0.0-rc.2] - 2026-10-10
+
+> **Release candidate, internal only.** Published to AWS CodeArtifact
+> (`npm-internal`), not public npm; the release workflow refuses to publish a
+> prerelease publicly. Contains everything in 6.0.0-rc.1 plus the fix below.
+> To install, point the `@hawcx` scope at CodeArtifact
+> (`aws codeartifact login --tool npm --domain hawcx --repository npm-internal --namespace @hawcx`)
+> and run `npm install @hawcx/oauth-client@6.0.0-rc.2`.
+
+### Fixed
+
+- **Discovery mode now sends `client_id` on the public-client (PKCE) token
+  exchange.** Previously `exchangeCode()` added `client_id` to the token form
+  only when a `private_key_jwt` signer was set; a public PKCE exchange sent
+  only the `X-Config-Id` header. The OP then fell back to the project's
+  default client (`token.legacy_config_id_fallback`) and stamped the id_token
+  `aud` with that client's id, so on a project with more than one public OIDC
+  client, an app using a non-default client failed verification with
+  "Unexpected JWT audience". `exchangeCode()` now always sends the configured
+  `clientId` as `client_id` in discovery mode (RFC 6749 §4.1.3), for public
+  and `private_key_jwt` clients alike; the OP resolves that specific client
+  and stamps `aud` with it. `X-Config-Id` is still sent.
+  - Single-client projects are unaffected: their `clientId` is the default
+    client, so the resolved client and `aud` are the same as before.
+  - Legacy mode (`new HawcxOAuth({ configId, baseUrl })`) has no `clientId`
+    and is unchanged: it sends no `client_id`.
+
+## [6.0.0-rc.1] - 2026-10-07
+
+> **Release candidate, internal only.** Published to AWS CodeArtifact
+> (`npm-internal`), not public npm; the release workflow refuses to publish a
+> prerelease publicly. **Major version** because of the BREAKING entries below,
+> which change behaviour for configurations that 5.2.0 accepted. To install,
+> point the `@hawcx` scope at CodeArtifact
+> (`aws codeartifact login --tool npm --domain hawcx --repository npm-internal --namespace @hawcx`)
+> and run `npm install @hawcx/oauth-client@6.0.0-rc.1`.
+
+### Security — management API response signatures are verified by default (TOB-HSDK-11)
+
+- **BREAKING — `JwtBearerTransport` and `StepUpClient.withPrivateKeyJwt` now
+  verify `X-Response-Signature` on every successful response, and this is on
+  by default.** This reverses the 5.2.0 note that callers "may" verify the
+  header themselves. The SDK checks the following:
+  - the JWS uses ES256, ES384 or ES512 and verifies against
+    `${issuer}/.well-known/jwks.json`;
+  - `iat` is within `clockSkewSeconds` (default 300);
+  - `body_sha256` matches the exact response bytes;
+  - the token carries no `aud`, `sub` or `nonce`.
+
+  Responses with status 400 and above are not verified. hx_auth signs every
+  jwt-mode 2xx, so production traffic is unaffected. The following will
+  **break**:
+  - A gateway, CDN or proxy that strips response headers. Every call fails
+    with `ResponseSignatureInvalidError`.
+  - Customer mocks, stubs and contract-test harnesses built against 5.2.0 that
+    return unsigned 2xx responses. Sign the responses, or disable verification
+    in the test harness.
+  - A `baseUrl` that is not the OP host, such as an internal service URL or
+    local dev with separate ports. The JWKS is fetched from `baseUrl` by
+    default, so set `issuer`.
+- New options on both: `issuer` (defaults to `baseUrl`),
+  `verifyResponseSignature` (defaults to `true`) and `clockSkewSeconds`.
+  `verifyResponseSignature: false` is an **emergency escape hatch** that
+  restores the 5.2.0 behaviour and emits a one-time process warning.
+  `withPrivateKeyJwt` now also passes `clockSkewSeconds` through to the
+  transport.
+- New error classes, both subclasses of `DelegationResponseError`, exported
+  with a stable `code`:
+  - `ResponseSignatureInvalidError` (`response_signature_invalid`).
+  - `ResponseSignatureUnavailableError` (`response_signature_unavailable`).
+    It means the signing keys could not be fetched, and **the request may
+    already have been applied** server-side.
+
+### Security — structured URL validation and joining (TOB-HSDK-13)
+
+- Every security-relevant URL is now parsed and joined with the WHATWG `URL`
+  API rather than by string concatenation. This covers `JwtBearerTransport`
+  and `DelegationTransport` (`baseUrl` + endpoint), legacy
+  `new HawcxOAuth({ baseUrl })` (`/oauth2/token` and `/keys`), and the
+  `fromIssuer` issuer and discovery URL. Each joined URL must keep the base's
+  origin and stay under the base path prefix, or the SDK throws (fail
+  closed). An endpoint must be a relative path that starts with a single
+  `/`. It may not contain `//`, a backslash, whitespace or control
+  characters, a fragment, or a percent-encoded `/`, `.` or `\` (`%2f`,
+  `%2e`, `%5c`, any case) in its path.
+- **BREAKING — `baseUrl` (and `issuer`) values that used to be accepted now
+  throw at construction.** The affected classes are `JwtBearerTransport` and
+  `StepUpClient.withPrivateKeyJwt` (`DelegationRequestError`),
+  `DelegationTransport` and the `DelegationClient`/`StepUpClient`
+  ECIES factories (`DelegationRequestError`), legacy `HawcxOAuth`
+  (`HawcxOAuthError`), and `HawcxOAuth.fromIssuer` (`DiscoveryError`):
+  - **Plain `http:` on a non-loopback host.** Examples:
+    `http://hawcx-api:8080` (docker-compose service name),
+    `http://0.0.0.0:8080`, `http://host.docker.internal:8080`, and in-cluster
+    service URLs behind a TLS-terminating gateway. Only `localhost`,
+    `127.0.0.1` and `[::1]` may use `http:`. Use `https:`, or point the SDK
+    at a loopback address.
+  - **Userinfo, query or fragment in the base.** For example
+    `https://user:pw@api.hawcx.com`, `https://api.hawcx.com?tenant=x` or
+    `https://api.hawcx.com#x`.
+- **BREAKING — the signed JWT `aud` string changes for non-canonical base
+  spellings.** Host case and default ports are now normalised, so
+  `baseUrl: 'https://API.Hawcx.com:443'` produces
+  `aud = https://api.hawcx.com/v1/...`, where 5.2.0 produced
+  `https://API.Hawcx.com:443/v1/...`. The new value is the one `fetch`
+  actually sends. A server that compares `aud` by exact string against a
+  configured non-canonical value will reject the new form. Canonical bases
+  (lower-case host, no default port, with or without a trailing slash or a
+  path prefix) produce byte-identical URLs and `aud`.
+- Discovered `token_endpoint` and `jwks_uri` values carrying userinfo are now
+  rejected (`DiscoveryError`).
+
 ## [5.2.0] - 2026-06-26
 
 ### Added — Management API authentication via `private_key_jwt` (Path A)

package/README.md

@@ -108,6 +108,7 @@ is the discovered `token_endpoint`, and EdDSA is the only accepted algorithm.
 | Module | Purpose |
 |--------|---------|
 | **OAuth** | Token exchange and JWT verification |
+| **Profile** | Hawcx profile service: users, consents, audit (machine or on behalf of a user) |
 | **Delegation** | Server-to-server user management (MFA, devices) |
 | **Step-Up** | Step-up authentication flows |
 
@@ -130,11 +131,56 @@ const oauth = await HawcxOAuth.fromIssuer({
   clientId: 'your-client-id',          // Required: expected `aud` on id_tokens
   timeout: 10000,                       // Optional: per-request timeout in ms
   discoveryTimeout: 5000,               // Optional: discovery fetch timeout in ms
+  customDomain: 'https://auth.example.com', // Optional: custom domain origin for browser URLs (a CNAME to Hawcx)
 });
 
 oauth.discoveryMetadata; // resolved OIDC discovery doc, for diagnostics
 ```
 
+`customDomain` must be `scheme://host[:port]` only: https (http only for
+loopback), an ASCII/punycode hostname (`xn--...` for IDN) or an IP literal,
+port 1-65535 without leading zeros, no userinfo, path, query or fragment (one
+trailing `/` allowed). IPv6 literals may not embed IPv4 (no `.`). It is
+canonicalised (lower-cased, default port dropped, IPv6 in RFC 5952 form, so
+`http://[0:0::1]` becomes `http://[::1]` and counts as loopback). `null`/`undefined` means unset. An invalid value (including `''`,
+whitespace, `*.example.com` or a trailing dot) throws `HawcxOAuthError`
+(`error: 'invalid_custom_domain'`) from `fromIssuer`, before any network call.
+The SDK only checks the form: `customDomain` must also be the TXT-verified
+domain registered for your client's own tenant, set up as a DNS CNAME to Hawcx
+(Hawcx serves its certificate). Another tenant's verified domain is always refused; when the tenant has
+custom-domain enforcement on, every host other than its own verified domains
+(including IP literals and single-label hosts) is refused too.
+
+##### Custom domain
+
+When you serve Hawcx sign-in on your own domain (`auth.example.com`, a DNS
+CNAME to Hawcx), the browser must go to `/authorize` and end-session on that
+domain, while token exchange, JWKS and the `iss` check stay on the Hawcx
+issuer.
+`customDomain` swaps only the scheme + host + port of the two browser URLs;
+everything server-to-server is unchanged.
+
+```typescript
+const oauth = await HawcxOAuth.fromIssuer({
+  issuer: 'https://api.hawcx.com',
+  configId: process.env.HAWCX_CONFIG_ID!,
+  clientId: process.env.HAWCX_CLIENT_ID!,
+  customDomain: 'https://auth.example.com',
+});
+
+// {issuer}/authorize → https://auth.example.com/authorize?response_type=code&client_id=...
+const loginUrl = oauth.buildAuthorizeUrl({ redirectUri, state, codeChallenge, nonce });
+
+// Token exchange still POSTs to https://api.hawcx.com/oauth2/token
+const { claims } = await oauth.exchangeCode(code, codeVerifier, redirectUri, nonce);
+
+// {issuer}/oauth2/end_session → https://auth.example.com/oauth2/end_session?client_id=...
+const logoutUrl = oauth.buildEndSessionUrl({ postLogoutRedirectUri, idTokenHint: idToken });
+```
+
+The `nonce` passed to `buildAuthorizeUrl` must be passed again to
+`exchangeCode` (4th argument).
+
 Throws `DiscoveryError` if the discovery document is unreachable, returns
 non-2xx, isn't valid JSON, or is missing any of `token_endpoint`,
 `jwks_uri`, `id_token_signing_alg_values_supported`.
@@ -209,6 +255,61 @@ interface JwtClaims {
 }
 ```
 
+#### `buildAuthorizeUrl(options: AuthorizeUrlOptions): string`
+
+Build the browser `/authorize` URL (discovery mode only; no network I/O).
+Base is the discovered `authorization_endpoint` (`{issuer}/authorize`), with
+its origin replaced by `customDomain` when set (otherwise the endpoint's scheme
+and authority are kept exactly as discovered). Its path and query are copied
+verbatim; the SDK parameters are appended after them. The URLs are
+semantically, not byte-for-byte, equal to the Python and Java SDKs' (parameter
+encoding of e.g. `~`, `*` and space differs).
+
+```typescript
+const url = oauth.buildAuthorizeUrl({
+  redirectUri: 'https://app.example.com/auth/callback', // Required
+  state,                                                 // Required
+  codeChallenge,                                         // Required (S256)
+  nonce,                                                 // Optional, recommended; pass again to exchangeCode
+  scope: 'openid email',                                 // Optional, default 'openid'
+  prompt: 'login',                                       // Optional
+  extraParams: { login_hint: 'a@example.com' },          // Optional
+});
+```
+
+Always sets `response_type=code`, `client_id` and `code_challenge_method=S256`.
+Blank (empty or ASCII-whitespace-only: space, `\t`, `\n`, `\v`, `\f`, `\r`;
+NBSP is not blank) optional values are omitted; a blank `scope`
+becomes `openid`. `extraParams` keys must be non-empty and values strings, and
+cannot be any parameter the SDK sets, `request`, `request_uri`, or a name
+already in the endpoint's query (names are case-sensitive). Throws
+`HawcxOAuthError` (`error: 'invalid_request'`) for a missing or blank required
+option or a bad `extraParams` entry, `HawcxOAuthError`
+(`error: 'issuer_mode_required'`) in legacy mode, and `DiscoveryError`
+(`error: 'invalid_discovery_document'`) if the discovered
+`authorization_endpoint` is missing, not https, has userinfo, a `#`, any
+character outside printable ASCII or any of `` \ " < > ^ ` { | } ``, or its query
+already sets one of the SDK's parameters, `request` or `request_uri`.
+
+#### `buildEndSessionUrl(options?: EndSessionUrlOptions): string`
+
+Build the browser logout URL from the discovered `end_session_endpoint`
+(`{issuer}/oauth2/end_session`, same `customDomain` origin swap). Always sends
+`client_id`; blank options are omitted. `buildEndSessionUrl(null)` is the same
+as `buildEndSessionUrl({})`.
+
+```typescript
+const url = oauth.buildEndSessionUrl({
+  postLogoutRedirectUri: 'https://app.example.com/', // Optional
+  idTokenHint: idToken,                              // Optional
+  state,                                             // Optional
+});
+```
+
+Same errors as `buildAuthorizeUrl` for legacy mode and the discovered
+`end_session_endpoint` (whose query may not set `client_id`,
+`post_logout_redirect_uri`, `id_token_hint` or `state`).
+
 #### `refreshJwks(): void`
 
 Reset the JWKS cache so the next verification refetches keys (useful for testing
@@ -251,6 +352,122 @@ try {
 
 ---
 
+## Profile Module
+
+`ProfileClient` calls the Hawcx profile service (`{issuer}/profile/v1/...`).
+Backend only: it is built from a discovery-mode `HawcxOAuth` with a
+`private_key_jwt` signer (see [Confidential clients](#confidential-clients-private_key_jwt)).
+
+Client configuration in the Hawcx admin console:
+
+- **Machine** (`ProfileClient`): `client_credentials` with
+  `allowed_scopes` covering what you call (`users:read`, `users:write`,
+  `users:delete`, `consent:read`, `consent:write`, `audit:read`).
+- **On behalf of a user** (`forUser`): `token_exchange_scopes: ["profile:self"]`,
+  and the user's ID token must have been issued to this same client.
+
+```typescript
+import { HawcxOAuth, ClientAssertionSigner, ProfileApiError } from '@hawcx/oauth-client';
+
+const oauth = (
+  await HawcxOAuth.fromIssuer({ issuer, configId, clientId })
+).withClientAssertion(ClientAssertionSigner.ed25519FromJwk(privateJwk));
+
+const profiles = oauth.profile(); // or new ProfileClient(oauth, options)
+
+// Machine: any user in the tenant
+const user = await profiles.getUser('user-123');
+await profiles.updateUser('user-123', { display_name: 'Ada', locale: null }); // null clears, omitted = unchanged
+await profiles.setConsent('user-123', 'marketing', { status: 'granted' });
+for await (const p of profiles.iterUsers({ status: 'active' })) console.log(p.user_id);
+
+// On behalf of the user, right after sign-in with the ID token you just received
+const me = profiles.forUser(idToken);
+const mine = await me.getMe();
+await me.updateMe({ given_name: 'Ada' });
+```
+
+Machine methods: `getUser`, `listUsers`, `iterUsers`, `createUser`,
+`updateUser`, `replaceUser`, `deleteUser`, `getConsents`, `setConsent`,
+`getAudit`, `iterAudit`. User methods: `getMe`, `updateMe`, `getMyConsents`,
+`setMyConsent`, `getMyAudit`, `iterMyAudit`.
+
+`forUser` only works with a fresh ID token: the OP caps the delegated token's
+lifetime at the ID token's `exp`, and ID tokens live 60 s by default
+(`id_token_ttl_seconds`). Use it with the ID token you just received at
+sign-in; for later work on a user's profile, use the machine methods with
+their `user_id` (the ID token's `sub` claim).
+
+List methods take
+`{ cursor?, limit? }` and return `{ items, nextCursor }` (consents:
+`{ current, history, nextCursor }`).
+
+Options (all optional): `baseUrl` (default `{issuer}/profile`; https, http only
+for loopback), `scopes` (machine; default: none sent, so the OP grants all the
+client's allowed scopes; an empty list throws), `audience` (exchange, default
+`hx-profile`), `timeout` (ms, default 10000; bounds token-endpoint calls as
+well as profile requests), `maxRetries` (default 2), `fetch`.
+
+Behaviour: access tokens are cached (expiry counted from when the token
+request was sent) and refreshed before expiry in the background, so callers
+keep the still-valid token meanwhile (one in-flight request shared by
+concurrent callers); a failed early refresh keeps that token and is not
+retried for 30 s (or until expiry); `forUser` tokens are re-exchanged only at
+expiry; a 401 re-mints the token and replays the request once (for `forUser`,
+if the re-exchange fails, e.g. `invalid_grant`, the original 401 is thrown);
+`deleteUser` treats any 2xx as success, whatever the body; GET/PUT/DELETE are retried on network errors, 408, 429, 502-504
+from the profile service (honouring its `Retry-After`, capped at 30 s); a
+token-endpoint network error, 408, 429, 502, 503 or 504 is retried for every
+method, POST/PATCH included, since no profile request was sent, using backoff
+only (the token endpoint's `Retry-After` is ignored); all retries share the
+same `maxRetries` budget; POST/PATCH are otherwise never retried; redirects are
+not followed; a DELETE answered 404 counts as success if any earlier attempt of
+the same call may have run (it got no HTTP response, or got 504), and that
+stays true whatever later attempts answer; a 502 (ambiguous, but a false
+"deleted" is worse than a false 404) or a failure before anything was sent
+does not count: any error with `syscall` `connect`/`getaddrinfo`, or,
+with no `syscall`, refused, DNS, connect timeout or TLS handshake codes
+(unreachable-host/network codes need `syscall: 'connect'`, since they can also
+hit an established keep-alive socket); an error from an injected `fetch` with
+no recognised `code`/`errno` counts as may-have-run;
+iterators stop on a null or empty `next_cursor`, or if the server repeats a
+cursor.
+
+Errors: profile-service failures throw `ProfileApiError` (a `HawcxError`) with
+`status` (`0` = no response: network error/timeout; a 2xx whose body was cut
+off mid-read keeps that status, title `Response body read failed`, detail the
+error name, since the call ran), `title`, `detail`, `type`, `instance`,
+`requestId`, `retryAfter`, `missing` (403 insufficient scope), `fields` (422)
+the parsed JSON `body`, and `rawBody` (the body text, e.g. a gateway's HTML
+error page, capped at 4096 characters, never in `message`; on a malformed 2xx
+only when the body is a markup page starting with `<`, since any other body
+may be a mangled profile, i.e. PII); a body
+with no non-blank `title`/`detail` but a string
+`message` (Kong) uses `message` as `detail`, and `requestId` falls back to the
+body's `request_id`; a 2xx body that is not JSON (`Invalid JSON response`) or
+is not a JSON object / lacks a required field, or a 204 to anything but
+`deleteUser` (`Unexpected response body`), is a `ProfileApiError` with the 2xx
+status. Token failures throw
+`TokenExchangeError` (`statusCode`, `error`, `network`: `true` when no
+complete HTTP response came back, i.e. no response at all, `statusCode`
+undefined, or a 2xx whose body was cut off mid-read, `statusCode` set; for
+`exchangeCode` the latter means the code is already spent). Invalid arguments (empty `userId`/`purpose`/`idToken`)
+throw `HawcxError` before any request, as do `userId`/`purpose` values, and
+`createUser`'s `user_id`, that are `.`/`..` or contain `/`, `\` or control
+characters.
+
+```typescript
+try {
+  await profiles.createUser({ user_id: 'user-123', given_name: 'Ada', family_name: 'Lovelace' });
+} catch (err) {
+  if (err instanceof ProfileApiError && err.status === 409) {
+    /* profile already exists */
+  } else throw err;
+}
+```
+
+---
+
 ## Delegation Module
 
 Server-to-server API for managing users, MFA, and devices. Requires a Hawcx secret key.
@@ -479,6 +696,36 @@ object, a PKCS#8 PEM string, or a pre-imported jose `KeyLike`.
 Each request is signed with a short-lived per-request EdDSA JWT whose `aud` is the
 full request URL and whose `body_sha256` claim covers the exact bytes sent.
 
+Every successful response is authenticated too. The SDK verifies the
+`X-Response-Signature` JWS (ES256/ES384/ES512) against
+`${issuer}/.well-known/jwks.json`. It also checks that the JWS `iat` is within
+`clockSkewSeconds` (default 300) and that its `body_sha256` matches the exact
+response bytes. `issuer` defaults to `baseUrl`, because the management API and
+the OP share a host in every Hawcx environment. Set `issuer` explicitly if they
+differ, for example in local development.
+
+> **Scope:** by default the JWKS comes from the **same origin as the API**.
+> Verification therefore protects against tampering *between* that origin and
+> you: caches, proxies and gateways, or a compromised downstream service. It
+> does **not** protect against a compromised origin. If you need that, pin
+> `issuer` to a separately trusted host.
+
+Failures throw one of two subclasses of `DelegationResponseError`, each with a
+stable `code`:
+
+- `ResponseSignatureInvalidError` (`code: 'response_signature_invalid'`): the
+  header is missing or empty, or the signature does not verify. Treat the
+  response as untrusted.
+- `ResponseSignatureUnavailableError` (`code: 'response_signature_unavailable'`):
+  the signing keys could not be obtained. The JWKS fetch failed, timed out or
+  returned something unusable, or a newly rotated `kid` arrived while refetching
+  was cooling down. **The server has already processed the request**, so a
+  non-idempotent write such as `consumeReceipt` may have been applied. Reconcile
+  state rather than retrying blindly.
+
+`verifyResponseSignature: false` turns verification off. It is an emergency
+escape hatch only, and it logs a one-time process warning.
+
 ### Methods
 
 #### `stepUp.startToken(options): Promise<StepUpStartTokenResponse>`

package/dist/client-assertion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-assertion.d.ts","sourceRoot":"","sources":["../src/client-assertion.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAmC,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAKjE,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,2DACwB,CAAC;AAK3D,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,iEAAiE;IACjE,OAAO,CAAC,UAAU,CAAC,CAAuB;IAE1C,OAAO;IAUP;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,GAAG,GAAG,MAAM,GAAG,qBAAqB;IA0BtE;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,qBAAqB;IAkB3E;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,qBAAqB;IAazE;;;;OAIG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB;IAK3D,OAAO,CAAC,SAAS;IAYjB;;;;;;OAMG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAYhE"}
+{"version":3,"file":"client-assertion.d.ts","sourceRoot":"","sources":["../src/client-assertion.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAmC,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAKjE,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,2DACwB,CAAC;AAK3D,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,iEAAiE;IACjE,OAAO,CAAC,UAAU,CAAC,CAAuB;IAE1C,OAAO;IAUP;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,GAAG,GAAG,MAAM,GAAG,qBAAqB;IA0BtE;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,qBAAqB;IAkB3E;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,qBAAqB;IAazE;;;;OAIG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB;IAK3D,OAAO,CAAC,SAAS;IAYjB;;;;;;OAMG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAgBhE"}