@hawcx/oauth-client 5.2.0 → 6.2.0

package/dist/internal/url.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Structured URL validation and joining for security-relevant URLs
+ * (TOB-HSDK-13).
+ *
+ * Every URL the SDK sends a credential, a signed request, or an
+ * authorization code to — or fetches verification keys from — is built and
+ * checked here with the WHATWG `URL` parser instead of string concatenation
+ * and prefix/substring checks.  String concatenation lets a malformed base or
+ * path change the request host, e.g.
+ *
+ *   'https://api.hawcx.com' + '.attacker.example/v1/x'
+ *     → https://api.hawcx.com.attacker.example/v1/x
+ *   'https://api.hawcx.com' + '@attacker.example/v1/x'
+ *     → https://attacker.example/v1/x   (api.hawcx.com becomes userinfo)
+ *
+ * Invariants enforced by this module:
+ *  - A base URL is absolute, `https:` (or `http:` only for the exact loopback
+ *    hostnames `localhost`, `127.0.0.1`, `[::1]`), carries no userinfo, and no
+ *    query or fragment.
+ *  - A joined URL is built from a *relative path* only (leading `/`, not `//`,
+ *    no backslash, no whitespace/control characters, no fragment, and no
+ *    percent-encoded `/`, `.` or `\` in the path), and the
+ *    result is re-parsed and asserted to have exactly the base's origin and to
+ *    stay under the base's path prefix.  Any failure throws (fail closed).
+ *
+ * Not part of the public API (not re-exported from the package index).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLoopbackHostname = isLoopbackHostname;
+exports.assertSecureUrl = assertSecureUrl;
+exports.parseSecureBaseUrl = parseSecureBaseUrl;
+exports.safeJoinUrl = safeJoinUrl;
+exports.parseCustomDomain = parseCustomDomain;
+const net_1 = require("net");
+/** Exact hostnames (as reported by `URL#hostname`) allowed to use plain http. */
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+/** C0 controls, space and DEL — stripped or rewritten silently by the URL parser. */
+// eslint-disable-next-line no-control-regex
+const CONTROL_OR_SPACE = /[\u0000- \u007f]/;
+/**
+ * Percent-encoded path separators and dots (`%2f`, `%2e`, `%5c`, any case).
+ * WHATWG resolves `%2e%2e` as a dot segment but leaves `%2f` encoded, so e.g.
+ * `/..%2fevil` keeps the origin yet lands outside the intended prefix once a
+ * server or proxy decodes it.  No legitimate endpoint needs these.
+ */
+const ENCODED_SEPARATOR_OR_DOT = /%(2f|2e|5c)/i;
+/** True when `hostname` is one of the exact loopback hostnames. */
+function isLoopbackHostname(hostname) {
+    return LOOPBACK_HOSTNAMES.has(hostname);
+}
+/**
+ * Parse `raw` and require it to be a secure absolute URL: `https:`, or
+ * `http:` only for an exact loopback hostname; no username/password.
+ *
+ * Query and fragment are permitted here (e.g. a discovered `jwks_uri` may
+ * legitimately carry a query); use {@link parseSecureBaseUrl} for a base that
+ * paths are appended to.
+ *
+ * @returns the parsed URL
+ */
+function assertSecureUrl(label, raw, makeError) {
+    if (typeof raw !== 'string' || raw.length === 0) {
+        throw makeError(`${label} must be a non-empty URL string`);
+    }
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch (err) {
+        throw makeError(`${label} is not a valid URL: ${raw}`, err);
+    }
+    if (u.username !== '' || u.password !== '') {
+        throw makeError(`${label} must not contain credentials (userinfo): ${redact(u)}`);
+    }
+    if (u.protocol === 'https:') {
+        return u;
+    }
+    if (u.protocol === 'http:' && isLoopbackHostname(u.hostname)) {
+        return u;
+    }
+    throw makeError(`${label} must use https (got: ${raw}). Plaintext http is permitted only for loopback hosts.`);
+}
+/**
+ * Validate a base URL (see {@link assertSecureUrl}) and additionally reject a
+ * query or fragment, which would otherwise swallow any appended path.
+ */
+function parseSecureBaseUrl(label, raw, makeError) {
+    const u = assertSecureUrl(label, raw, makeError);
+    // `u.search`/`u.hash` are '' for both "no ?" and a bare trailing "?", so
+    // check the raw string too.
+    if (u.search !== '' || u.hash !== '' || raw.includes('?') || raw.includes('#')) {
+        throw makeError(`${label} must not contain a query or fragment: ${raw}`);
+    }
+    // Strip a single trailing slash — the same normalisation the SDK has always
+    // applied with `.replace(/\/$/, '')` — so valid bases join to the exact same
+    // string as before.
+    const pathPrefix = u.pathname.replace(/\/$/, '');
+    return { origin: u.origin, pathPrefix };
+}
+/**
+ * Join a relative `path` onto a validated base and return the absolute URL
+ * string.  For a canonical base (lower-case host, no default port) this is
+ * byte-identical to the historical `base.replace(/\/$/, '') + path`.
+ *
+ * Throws unless `path` is a plain relative path and the result keeps the
+ * base's exact origin and stays under its path prefix.
+ */
+function safeJoinUrl(base, path, label, makeError) {
+    if (typeof path !== 'string' || !path.startsWith('/')) {
+        throw makeError(`${label} must be a relative path starting with '/' (got: ${String(path)})`);
+    }
+    if (path.startsWith('//')) {
+        throw makeError(`${label} must not be scheme-relative ('//'): ${path}`);
+    }
+    if (path.includes('\\')) {
+        throw makeError(`${label} must not contain a backslash: ${path}`);
+    }
+    if (CONTROL_OR_SPACE.test(path)) {
+        throw makeError(`${label} must not contain whitespace or control characters`);
+    }
+    if (path.includes('#')) {
+        throw makeError(`${label} must not contain a fragment: ${path}`);
+    }
+    // Path part only: a query string cannot move the origin or the path.
+    const pathPart = path.split('?', 1)[0];
+    if (ENCODED_SEPARATOR_OR_DOT.test(pathPart)) {
+        throw makeError(`${label} must not contain percent-encoded '/', '.' or '\\' in its path: ${path}`);
+    }
+    // Build from the parsed origin + prefix, never from the caller's raw base
+    // string: the path always begins after a complete authority.
+    let joined;
+    try {
+        joined = new URL(base.origin + base.pathPrefix + path);
+    }
+    catch (err) {
+        throw makeError(`${label} produced an invalid URL`, err);
+    }
+    // Fail closed: the request must not leave the configured origin…
+    if (joined.origin !== base.origin || joined.username !== '' || joined.password !== '') {
+        throw makeError(`${label} resolves outside the configured origin ${base.origin}`);
+    }
+    // …nor climb out of the configured path prefix via dot segments
+    // (including percent-encoded `%2e%2e`, which the URL parser resolves).
+    if (base.pathPrefix !== '' && !joined.pathname.startsWith(base.pathPrefix + '/')) {
+        throw makeError(`${label} resolves outside the configured base path ${base.pathPrefix}`);
+    }
+    return joined.href;
+}
+/** Raw-string shape of a custom domain (cross-SDK contract §1). */
+const CUSTOM_DOMAIN_SHAPE = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/(\[[0-9A-Fa-f:.]+\]|[^/:?#@[\]]+)(?::([^/]*))?\/?$/;
+const DNS_LABEL = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+const IPV4_OCTET = /^(0|[1-9][0-9]{0,2})$/;
+/**
+ * Validate a browser-facing custom domain as a raw string (no WHATWG parse,
+ * which would strip whitespace, decode `%2e`, accept `*` or a trailing dot)
+ * and return its canonical origin: `scheme://host[:port]`, lower-cased,
+ * default port dropped.  Same rules as the Python and Java SDKs.
+ */
+function parseCustomDomain(raw, makeError) {
+    const bad = (why) => makeError(`customDomain ${why}: ${JSON.stringify(raw)}`);
+    if (typeof raw !== 'string' || raw === '')
+        throw bad('must be a non-empty string');
+    // Printable ASCII only, checked before lower-casing (U+212A Kelvin sign lower-cases to 'k').
+    if (/[^\x21-\x7e]|[\\%]/.test(raw)) {
+        throw bad('must be printable ASCII (punycode for IDN) without whitespace, backslash or %');
+    }
+    const m = CUSTOM_DOMAIN_SHAPE.exec(raw);
+    if (m === null)
+        throw bad('must be scheme://host[:port] only (no userinfo, path, query or fragment)');
+    const scheme = m[1].toLowerCase();
+    let host = m[2].toLowerCase();
+    const port = m[3];
+    if (host.startsWith('[')) {
+        if (host.includes('.') || !(0, net_1.isIPv6)(host.slice(1, -1))) {
+            throw bad('has an invalid IPv6 literal (embedded IPv4 not allowed)');
+        }
+        // WHATWG serialises IPv6 in RFC 5952 form: `[0:0::1]` -> `[::1]` (contract R7).
+        host = new URL(`http://${host}`).hostname;
+    }
+    else if (/^[0-9.]+$/.test(host) && host.split('.').length === 4) {
+        if (!host.split('.').every((o) => IPV4_OCTET.test(o) && Number(o) <= 255)) {
+            throw bad('has a non-canonical IPv4 address');
+        }
+    }
+    else {
+        const labels = host.split('.');
+        if (host.length > 253 ||
+            !labels.every((l) => l.length <= 63 && DNS_LABEL.test(l)) ||
+            !/^[a-z]/.test(labels[labels.length - 1])) {
+            throw bad('has an invalid hostname (ASCII/punycode labels only, last label starts with a letter)');
+        }
+    }
+    if (port !== undefined && !(/^[1-9][0-9]{0,4}$/.test(port) && Number(port) <= 65535)) {
+        throw bad('has an invalid port');
+    }
+    if (scheme !== 'https' && !(scheme === 'http' && isLoopbackHostname(host))) {
+        throw bad('must use https (http only for loopback)');
+    }
+    const defaultPort = scheme === 'https' ? '443' : '80';
+    return `${scheme}://${host}${port === undefined || port === defaultPort ? '' : ':' + port}`;
+}
+/** Render a URL for an error message with any credentials removed. */
+function redact(u) {
+    const copy = new URL(u.href);
+    copy.username = '';
+    copy.password = '';
+    return copy.href;
+}
+//# sourceMappingURL=url.js.map

package/dist/internal/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/internal/url.ts"],"names":[],"mappings":"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"}

package/dist/management/jwt_transport.d.ts

@@ -28,7 +28,13 @@ import type { JsonObject } from '../delegation/transport';
  */
 export type HttpFetch = (url: string, init: RequestInit) => Promise<Response>;
 export interface JwtBearerTransportOptions {
-    /** Base URL of the management API, e.g. `https://api.hawcx.com` */
+    /**
+     * Base URL of the management API, e.g. `https://api.hawcx.com`.  Must be
+     * `https:` (plain `http:` only for `localhost` / `127.0.0.1` / `[::1]`),
+     * without credentials, query or fragment.  May carry a path prefix
+     * (e.g. `https://gateway.example.com/hawcx`).  Validated at construction;
+     * an invalid value throws `DelegationRequestError`.
+     */
     baseUrl: string;
     /** Tenant config identifier; forwarded as `X-Config-Id`. */
     configId: string;
@@ -60,6 +66,36 @@ export interface JwtBearerTransportOptions {
      * (Node >= 18).  Pass a capturing fake in tests.
      */
     http?: HttpFetch;
+    /**
+     * OIDC issuer whose `${issuer}/.well-known/jwks.json` publishes the key that
+     * signs management responses (the same JWKS that verifies ID tokens).
+     * Defaults to `baseUrl` — in every Hawcx environment the management API and
+     * the OP share one public host (e.g. `https://api.hawcx.com`).  Set this
+     * only when they differ (e.g. local dev with separate ports).  Same URL
+     * rules as `baseUrl`.
+     */
+    issuer?: string;
+    /**
+     * Verify the `X-Response-Signature` JWS on every successful response
+     * (default: `true`).  A response with a missing or invalid signature is
+     * rejected with `DelegationResponseError`.
+     *
+     * Failures throw `ResponseSignatureInvalidError` (bad/missing signature) or
+     * `ResponseSignatureUnavailableError` (signing keys could not be fetched —
+     * the request may already have been applied server-side); both extend
+     * `DelegationResponseError` and expose a stable `code`.
+     *
+     * **Emergency escape hatch only.**  Setting `false` makes the SDK trust any
+     * response body it receives, unauthenticated; a one-time process warning is
+     * emitted.  Do not disable in production.
+     */
+    verifyResponseSignature?: boolean;
+    /**
+     * Allowed difference in seconds between local time and the response
+     * signature's `iat` (default: 300) — same default as the ECIES transport's
+     * response timestamp skew.
+     */
+    clockSkewSeconds?: number;
 }
 /**
  * Drop-in transport for the management API that authenticates via a per-request
@@ -77,6 +113,8 @@ export declare class JwtBearerTransport {
     private readonly jwtTtlSeconds;
     private readonly timeoutMs;
     private readonly http;
+    /** `null` only when verification was explicitly disabled. */
+    private readonly responseVerifier;
     /** Lazily-imported (and memoised) signing key. */
     private keyPromise?;
     private readonly importKeyFn;
@@ -85,7 +123,7 @@ export declare class JwtBearerTransport {
     /**
      * Mint a per-request EdDSA JWT.
      *
-     * @param audience - full request URL (`baseUrl + endpoint`), pinned per-call
+     * @param audience - full request URL (base joined with endpoint), pinned per-call
      * @param bodySha256 - base64url (no-padding) of SHA-256 over the exact body bytes
      */
     private mintJwt;
@@ -95,7 +133,10 @@ export declare class JwtBearerTransport {
      * Matches the signature of `DelegationTransport.send` so the two transports
      * are drop-in substitutes behind `StepUpClient`.
      *
-     * @param options.endpoint - API path, e.g. `/v1/management/stepup/start-token`
+     * @param options.endpoint - API path relative to `baseUrl`, e.g.
+     *   `/v1/management/stepup/start-token`.  Must start with a single `/`;
+     *   anything that would resolve off the configured origin or out of its path
+     *   prefix throws `DelegationRequestError` before the request is signed.
      * @param options.payload  - request body; serialised once and hashed; the
      *   EXACT same bytes are sent and hashed — no double-serialisation.
      * @param options.headers  - optional extra headers merged last (win over built-ins)

package/dist/management/jwt_transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt_transport.d.ts","sourceRoot":"","sources":["../../src/management/jwt_transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAmC,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAK1D;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC;IACvC,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IAEjC,kDAAkD;IAClD,OAAO,CAAC,UAAU,CAAC,CAAuB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;gBAE7C,OAAO,EAAE,yBAAyB;IAyB9C,OAAO,CAAC,SAAS;IAajB;;;;;OAKG;YACW,OAAO;IAiBrB;;;;;;;;;;OAUG;IACG,IAAI,CAAC,IAAI,SAAS,UAAU,EAAE,IAAI,SAAS,UAAU,EAAE,OAAO,EAAE;QACpE,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,IAAI,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,IAAI,CAAC;CAiFlB"}
+{"version":3,"file":"jwt_transport.d.ts","sourceRoot":"","sources":["../../src/management/jwt_transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAmC,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAc1D;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC;IACvC,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;OAaG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IACjC,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmC;IAEpE,kDAAkD;IAClD,OAAO,CAAC,UAAU,CAAC,CAAuB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;gBAE7C,OAAO,EAAE,yBAAyB;IAgE9C,OAAO,CAAC,SAAS;IAajB;;;;;OAKG;YACW,OAAO;IAiBrB;;;;;;;;;;;;;OAaG;IACG,IAAI,CAAC,IAAI,SAAS,UAAU,EAAE,IAAI,SAAS,UAAU,EAAE,OAAO,EAAE;QACpE,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,IAAI,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,IAAI,CAAC;CAgGlB"}

package/dist/management/jwt_transport.js

@@ -25,6 +25,12 @@ const node_crypto_1 = require("node:crypto");
 const node_crypto_2 = require("node:crypto");
 const jose_1 = require("jose");
 const exceptions_1 = require("../delegation/exceptions");
+const url_1 = require("../internal/url");
+const response_signature_1 = require("./response_signature");
+/** Config/URL errors surface as `DelegationRequestError`, like other request failures. */
+const urlError = (message, cause) => new exceptions_1.DelegationRequestError(message, cause === undefined ? {} : { cause });
+/** Emit the "verification disabled" warning at most once per process. */
+let responseSignatureDisabledWarned = false;
 /**
  * Drop-in transport for the management API that authenticates via a per-request
  * EdDSA JWT (`private_key_jwt`, Path A).
@@ -35,13 +41,49 @@ const exceptions_1 = require("../delegation/exceptions");
  */
 class JwtBearerTransport {
     constructor(options) {
-        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        // Parsed and validated once (TOB-HSDK-13): every signed request is built
+        // from this structured origin + path prefix, never by string concatenation.
+        this.baseUrl = (0, url_1.parseSecureBaseUrl)('baseUrl', options.baseUrl, urlError);
         this.configId = options.configId;
         this.kid = options.kid;
         this.clientId = options.clientId;
         this.jwtTtlSeconds = options.jwtTtlSeconds ?? 60;
         this.timeoutMs = (options.timeoutSeconds ?? 15) * 1000;
         this.http = options.http ?? ((...args) => fetch(...args));
+        // Response authentication (TOB-HSDK-11).  The JWKS URL is derived from the
+        // validated issuer with the same structured join as request URLs.
+        //
+        // DEFAULT ISSUER = baseUrl, i.e. JWKS = ${baseUrl}/.well-known/jwks.json,
+        // fetched without X-Config-Id.  This holds today because the OP's single
+        // global ISSUER is the management API host and its global JWKS carries the
+        // response-signing kid.  REVISIT under hawcx_core_oauth#67 (per-tenant
+        // issuer / discovery_mode cutover): if a tenant's signing kid moves to a
+        // per-tenant JWKS, this default stops containing it and every management
+        // call fails closed (ResponseSignatureUnavailable/Invalid).  Callers can
+        // already override via the `issuer` option; whoever lands #67 must update
+        // this default (e.g. derive a per-tenant issuer) and the README.
+        const issuer = options.issuer === undefined
+            ? this.baseUrl
+            : (0, url_1.parseSecureBaseUrl)('issuer', options.issuer, urlError);
+        if (options.verifyResponseSignature === false) {
+            this.responseVerifier = null;
+            if (!responseSignatureDisabledWarned) {
+                responseSignatureDisabledWarned = true;
+                process.emitWarning('[@hawcx/oauth-client] JwtBearerTransport: verifyResponseSignature is disabled — ' +
+                    'management API responses will NOT be authenticated. Use only as a temporary escape hatch.', { type: 'Warning', code: 'HAWCX_RESPONSE_SIGNATURE_DISABLED' });
+            }
+        }
+        else {
+            const clockSkewSeconds = options.clockSkewSeconds ?? 300;
+            if (!Number.isFinite(clockSkewSeconds) || clockSkewSeconds < 0) {
+                throw new exceptions_1.DelegationRequestError('clockSkewSeconds must be a non-negative number');
+            }
+            this.responseVerifier = new response_signature_1.ResponseSignatureVerifier({
+                jwksUri: (0, url_1.safeJoinUrl)(issuer, '/.well-known/jwks.json', 'JWKS URL', urlError),
+                clockSkewSeconds,
+                timeoutMs: this.timeoutMs,
+            });
+        }
         const key = options.oidcSigningKey;
         if (typeof key === 'string') {
             // PKCS#8 PEM
@@ -72,7 +114,7 @@ class JwtBearerTransport {
     /**
      * Mint a per-request EdDSA JWT.
      *
-     * @param audience - full request URL (`baseUrl + endpoint`), pinned per-call
+     * @param audience - full request URL (base joined with endpoint), pinned per-call
      * @param bodySha256 - base64url (no-padding) of SHA-256 over the exact body bytes
      */
     async mintJwt(audience, bodySha256) {
@@ -95,7 +137,10 @@ class JwtBearerTransport {
      * Matches the signature of `DelegationTransport.send` so the two transports
      * are drop-in substitutes behind `StepUpClient`.
      *
-     * @param options.endpoint - API path, e.g. `/v1/management/stepup/start-token`
+     * @param options.endpoint - API path relative to `baseUrl`, e.g.
+     *   `/v1/management/stepup/start-token`.  Must start with a single `/`;
+     *   anything that would resolve off the configured origin or out of its path
+     *   prefix throws `DelegationRequestError` before the request is signed.
      * @param options.payload  - request body; serialised once and hashed; the
      *   EXACT same bytes are sent and hashed — no double-serialisation.
      * @param options.headers  - optional extra headers merged last (win over built-ins)
@@ -107,7 +152,9 @@ class JwtBearerTransport {
         // SHA-256 → base64url without padding (RFC 7515 §2).
         const hash = (0, node_crypto_2.createHash)('sha256').update(bodyBytes).digest();
         const bodySha256 = hash.toString('base64url').replace(/=+$/, '');
-        const url = this.baseUrl + endpoint;
+        // Join structurally and assert the result stays on the configured origin
+        // BEFORE signing: the JWT `aud` and the request target are this one value.
+        const url = (0, url_1.safeJoinUrl)(this.baseUrl, endpoint, 'endpoint', urlError);
         let jwt;
         try {
             jwt = await this.mintJwt(url, bodySha256);
@@ -168,6 +215,15 @@ class JwtBearerTransport {
                 responseBody: errorBody,
             });
         }
+        // Authenticate every response we are about to return as success — any
+        // status below 400, i.e. every 2xx (and any stray 1xx/3xx, which the
+        // server never sends signed and so fail closed).  Error responses (>= 400)
+        // are unsigned by design and were rejected above.  The hash covers the raw
+        // bytes from `arrayBuffer()`, not `text`: UTF-8 decoding replaces invalid
+        // sequences and would let distinct byte strings hash the same.
+        if (this.responseVerifier !== null) {
+            await this.responseVerifier.verify(response.headers.get(response_signature_1.RESPONSE_SIGNATURE_HEADER), responseData);
+        }
         let parsed;
         try {
             parsed = JSON.parse(text);

package/dist/management/jwt_transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"jwt_transport.js","sourceRoot":"","sources":["../../src/management/jwt_transport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"jwt_transport.js","sourceRoot":"","sources":["../../src/management/jwt_transport.ts"],"names":[],"mappings":"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"}

package/dist/management/response_signature.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Verification of the management API's `X-Response-Signature` (TOB-HSDK-11).
+ *
+ * Every successful jwt-mode (Path A) management response from hx_auth carries
+ * `X-Response-Signature`: a compact JWS signed with the shared OAuth signing
+ * key that the OP publishes at `${issuer}/.well-known/jwks.json` — the same
+ * JWKS that verifies ID tokens.  Its payload is exactly
+ *
+ *   { "body_sha256": base64url(sha256(<exact response body bytes>)), "iat": <unix s> }
+ *
+ * Verifying it restores the response authentication the legacy ECIES
+ * transport always had (signature + timestamp skew on every response).
+ *
+ * Checks, all fail-closed:
+ *  - the header is present and is a compact JWS whose protected header names
+ *    a `kid`;
+ *  - `alg` is one of ES256 / ES384 / ES512 (the server's KMS key is an EC key
+ *    and the alg follows its curve).  `none`, HS*, RS*, EdDSA are rejected —
+ *    this forecloses alg-substitution / key-confusion;
+ *  - the signature verifies against the issuer JWKS (jose `RemoteJWKSet`:
+ *    cached, and refetched once when the `kid` is unknown — key rotation);
+ *  - `iat` is present and within ±clockSkewSeconds of local time;
+ *  - the payload is a response signature, not some other token minted with
+ *    the same key (TOB-HSDK-9 type confusion): `body_sha256` is required and
+ *    `aud`, `sub`, `nonce` must be absent — an ID token always carries
+ *    `aud`/`sub`;
+ *  - `body_sha256` equals base64url(sha256(raw body bytes)), compared in
+ *    constant time.  The hash is taken over the raw bytes as received, before
+ *    any decoding or JSON parsing.
+ *
+ * Failures are split so callers can react correctly:
+ *  - {@link ResponseSignatureInvalidError} (`code: 'response_signature_invalid'`)
+ *    — missing/empty header or a signature that does not verify;
+ *  - {@link ResponseSignatureUnavailableError}
+ *    (`code: 'response_signature_unavailable'`) — the signing keys could not
+ *    be obtained (JWKS fetch failed / timed out / non-200 / malformed, or the
+ *    kid is unknown while jose's refetch cooldown suppresses a refetch).  The
+ *    request may already have been applied server-side.
+ * Both subclass `DelegationResponseError` and carry fixed, non-leaky messages.
+ *
+ * Not part of the public API (not re-exported from the package index).
+ */
+/** Response-signature header name (HTTP headers are case-insensitive). */
+export declare const RESPONSE_SIGNATURE_HEADER = "X-Response-Signature";
+export interface ResponseSignatureVerifierOptions {
+    /** Absolute, already-validated JWKS URL (`${issuer}/.well-known/jwks.json`). */
+    jwksUri: string;
+    /** Allowed |now − iat| in seconds. */
+    clockSkewSeconds: number;
+    /** Bound on each JWKS fetch, in ms. */
+    timeoutMs: number;
+}
+export declare class ResponseSignatureVerifier {
+    private readonly jwks;
+    private readonly clockSkewSeconds;
+    constructor(options: ResponseSignatureVerifierOptions);
+    /**
+     * Verify `signature` (the header value, or null when absent) over the EXACT
+     * response body bytes.  Resolves on success; throws
+     * {@link ResponseSignatureInvalidError} or
+     * {@link ResponseSignatureUnavailableError} otherwise.
+     */
+    verify(signature: string | null, body: Uint8Array): Promise<void>;
+}
+//# sourceMappingURL=response_signature.d.ts.map

package/dist/management/response_signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response_signature.d.ts","sourceRoot":"","sources":["../../src/management/response_signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AASH,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,yBAAyB,CAAC;AAoBhE,MAAM,WAAW,gCAAgC;IAC/C,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,gBAAgB,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwC;IAC7D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,OAAO,EAAE,gCAAgC;IAUrD;;;;;OAKG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAgGxE"}