@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

package/dist/esm/external-providers/operations/provider-operation-request.backend.js

@@ -0,0 +1,211 @@
+/**
+ * Compiling a declared provider operation + a caller's input into ONE transport request (S3a,
+ * #331).
+ *
+ * Deliberately a pure function over data, with no registry, no secrets and no I/O: an operation
+ * declaration and an input go in, an {@link HttpApiTransportRequest} comes out. That is what makes
+ * the interesting half — which input field lands in the path, which in the query, which in the
+ * body, and whether the call may be retried — testable without a network, a provider or a
+ * container.
+ *
+ * What this does NOT do, on purpose: it never PAGES. `pagination` on an operation is a hint the
+ * caller reads; an executor that paged on its own would decide a caller's memory budget for it.
+ */
+import { API_HttpMethod } from '@wildo-ai/external-connectors-models';
+/*
+ * `./backend` is the door that exists on `test`. #330 is splitting the private package by
+ * AUDIENCE — `./backend-runtime` for what executes, `./backend` for tooling that enumerates every
+ * engine-shipped provider — and has already moved backend-lib's runtime imports across in its own
+ * work. This file was new and not in that sweep; #330 landed the split and moved this specifier with
+ * the others, so the operations lane no longer pulls the eager registry into a running host. A
+ * guard in `backend-provider-loader.module-graph.test.ts` now refuses any value import of the eager
+ * barrel from this package's source, which is what stops the next new file re-introducing it.
+ */
+import { ProviderRestParameterLocation, ProviderRestRequestBodyEncoding } from '@wildo-ai/external-connectors-models';
+import { HttpApiTransportBodyEncoding, HttpApiTransportResponseDecoding, } from '../../base-classes/services/repositories/http-api/http-api-transport.backend.js';
+/** What went wrong while turning a declaration + an input into a request. */
+export var ProviderOperationRequestFailureKind;
+(function (ProviderOperationRequestFailureKind) {
+    /** The caller's input does not satisfy the operation's declared input schema. */
+    ProviderOperationRequestFailureKind["INPUT_REJECTED"] = "INPUT_REJECTED";
+    /** A required value is absent — a path token with nothing to fill it, a required parameter. */
+    ProviderOperationRequestFailureKind["INPUT_INCOMPLETE"] = "INPUT_INCOMPLETE";
+    /** The DECLARATION is inconsistent — a path token no parameter declares, a body with no source. */
+    ProviderOperationRequestFailureKind["DECLARATION_INCOHERENT"] = "DECLARATION_INCOHERENT";
+})(ProviderOperationRequestFailureKind || (ProviderOperationRequestFailureKind = {}));
+export class ProviderOperationRequestError extends Error {
+    detail;
+    constructor(message, detail) {
+        super(message);
+        this.detail = detail;
+        this.name = 'ProviderOperationRequestError';
+    }
+}
+/**
+ * Methods whose repetition is safe.
+ * spec-cite: RFC 9110 §9.2.2 — "PUT, DELETE, and the safe request methods are idempotent";
+ * §9.2.1 names GET, HEAD, OPTIONS and TRACE as the safe ones.
+ *
+ * This is only the DEFAULT: an operation may declare `idempotent` and override it in either
+ * direction — `true` on a POST the vendor documents behind an idempotency key, `false` on a PUT
+ * whose target is not really a resource replacement.
+ */
+const IDEMPOTENT_METHODS = new Set([
+    API_HttpMethod.GET,
+    API_HttpMethod.HEAD,
+    API_HttpMethod.OPTIONS,
+    API_HttpMethod.PUT,
+    API_HttpMethod.DELETE,
+]);
+/** Whether re-sending this operation is safe — the value that reaches the transport's retry gate. */
+export function providerOperationIsRetrySafe(operation) {
+    return operation.idempotent ?? IDEMPOTENT_METHODS.has(operation.method);
+}
+const PATH_TOKEN = /\{([^}]+)\}/g;
+/** The input field feeding a parameter: its own `from`, or the wire name when the two agree. */
+function inputFieldOf(parameter) {
+    return parameter.from ?? parameter.name;
+}
+function asWireValue(value) {
+    return typeof value === 'string' ? value : String(value);
+}
+/**
+ * Build the request. Reads in one direction — path, then query, then headers, then body — and
+ * records which input fields were consumed on the way, because the body's default source is
+ * "everything not consumed" and that set can only be known after the parameters are placed.
+ */
+export function compileProviderOperationRequest(input) {
+    const { operation, providerRef, access } = input;
+    const refuse = (kind, message) => {
+        throw new ProviderOperationRequestError(message, { kind, operationId: operation.operationId, providerRef });
+    };
+    const parameters = operation.parameters ?? [];
+    const consumedInputFields = new Set();
+    const valueFor = (parameter) => {
+        if (parameter.constantValue !== undefined)
+            return parameter.constantValue;
+        const field = inputFieldOf(parameter);
+        consumedInputFields.add(field);
+        return input.input[field];
+    };
+    // ── path ───────────────────────────────────────────────────────────────────
+    const pathParameters = new Map(parameters.filter((parameter) => parameter.in === ProviderRestParameterLocation.PATH).map((parameter) => [parameter.name, parameter]));
+    const path = operation.pathTemplate.replace(PATH_TOKEN, (_match, token) => {
+        const parameter = pathParameters.get(token);
+        if (!parameter) {
+            // The declaration is wrong, not the call: a path template cannot have a hole nothing fills.
+            return refuse(ProviderOperationRequestFailureKind.DECLARATION_INCOHERENT, `Operation '${operation.operationId}' has the path token '{${token}}' and declares no PATH parameter named '${token}'.`);
+        }
+        const value = valueFor(parameter);
+        if (value === undefined || value === null || value === '') {
+            return refuse(ProviderOperationRequestFailureKind.INPUT_INCOMPLETE, `Operation '${operation.operationId}' needs '${inputFieldOf(parameter)}' for the path token '{${token}}', and the input carries no value for it.`);
+        }
+        return encodeURIComponent(asWireValue(value));
+    });
+    // ── query ──────────────────────────────────────────────────────────────────
+    const search = new URLSearchParams();
+    for (const parameter of parameters) {
+        if (parameter.in !== ProviderRestParameterLocation.QUERY)
+            continue;
+        const value = valueFor(parameter);
+        if (value === undefined || value === null) {
+            if (parameter.required) {
+                refuse(ProviderOperationRequestFailureKind.INPUT_INCOMPLETE, `Operation '${operation.operationId}' declares '${parameter.name}' as a required query parameter, and the input carries no value for it.`);
+            }
+            continue;
+        }
+        // An array becomes REPEATED parameters (`?tag=a&tag=b`), the only encoding every target
+        // accepts. A vendor wanting a joined list declares one field and the caller joins it — a
+        // guess here would silently send the wrong thing to half of them.
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                search.append(parameter.name, asWireValue(entry));
+            continue;
+        }
+        search.append(parameter.name, asWireValue(value));
+    }
+    // ── headers ────────────────────────────────────────────────────────────────
+    const headers = { Accept: 'application/json', ...access.headers };
+    for (const parameter of parameters) {
+        if (parameter.in !== ProviderRestParameterLocation.HEADER)
+            continue;
+        const value = valueFor(parameter);
+        if (value === undefined || value === null) {
+            if (parameter.required) {
+                refuse(ProviderOperationRequestFailureKind.INPUT_INCOMPLETE, `Operation '${operation.operationId}' declares '${parameter.name}' as a required header, and the input carries no value for it.`);
+            }
+            continue;
+        }
+        headers[parameter.name] = asWireValue(value);
+    }
+    // ── body ───────────────────────────────────────────────────────────────────
+    let body;
+    if (operation.requestBody) {
+        const declaration = operation.requestBody;
+        const payload = declaration.from !== undefined
+            ? input.input[declaration.from]
+            : Object.fromEntries(Object.entries(input.input).filter(([field]) => !consumedInputFields.has(field)));
+        switch (declaration.encoding) {
+            case ProviderRestRequestBodyEncoding.JSON:
+                body = { encoding: HttpApiTransportBodyEncoding.JSON, value: payload };
+                break;
+            case ProviderRestRequestBodyEncoding.FORM_URLENCODED: {
+                if (payload === null || typeof payload !== 'object') {
+                    refuse(ProviderOperationRequestFailureKind.INPUT_INCOMPLETE, `Operation '${operation.operationId}' sends a form body and the input resolves to ${payload === null ? 'null' : typeof payload} instead of an object.`);
+                }
+                const fields = {};
+                for (const [field, value] of Object.entries(payload)) {
+                    if (value === undefined || value === null)
+                        continue;
+                    fields[field] = asWireValue(value);
+                }
+                body = { encoding: HttpApiTransportBodyEncoding.FORM_URLENCODED, value: fields };
+                break;
+            }
+            case ProviderRestRequestBodyEncoding.MULTIPART: {
+                if (!(payload instanceof FormData)) {
+                    // Deliberately NOT built from a plain object here: a multipart part carries a filename
+                    // and a media type the caller knows and this layer does not, and inventing them is how
+                    // an upload arrives as `blob` with the wrong content type.
+                    refuse(ProviderOperationRequestFailureKind.INPUT_INCOMPLETE, `Operation '${operation.operationId}' sends a multipart body, so its input must supply a FormData`
+                        + `${declaration.from ? ` in '${declaration.from}'` : ''}; the caller supplied ${payload === null ? 'null' : typeof payload}.`);
+                }
+                body = { encoding: HttpApiTransportBodyEncoding.MULTIPART, value: payload };
+                break;
+            }
+            case ProviderRestRequestBodyEncoding.TEXT: {
+                if (typeof payload !== 'string') {
+                    refuse(ProviderOperationRequestFailureKind.INPUT_INCOMPLETE, `Operation '${operation.operationId}' sends a text body, so its input must supply a string`
+                        + `${declaration.from ? ` in '${declaration.from}'` : ''}; the caller supplied ${payload === null ? 'null' : typeof payload}.`);
+                }
+                if (declaration.contentType === undefined) {
+                    refuse(ProviderOperationRequestFailureKind.DECLARATION_INCOHERENT, `Operation '${operation.operationId}' sends a text body and declares no contentType — a text body without its media type is not addressable.`);
+                }
+                body = { encoding: HttpApiTransportBodyEncoding.TEXT, value: payload, contentType: declaration.contentType };
+                break;
+            }
+            default: {
+                const exhaustiveCheck = declaration.encoding;
+                return exhaustiveCheck;
+            }
+        }
+    }
+    const query = search.toString();
+    return {
+        method: operation.method,
+        url: `${access.baseUrl}${path}${query.length > 0 ? `?${query}` : ''}`,
+        headers,
+        body,
+        // ALWAYS JSON, and stated rather than left to the transport's default so the limitation is
+        // visible at the site that imposes it: the operation declaration has no way to say the vendor
+        // answers `text/csv` or answers nothing at all. The transport carries both
+        // (`HttpApiTransportResponseDecoding.TEXT` / `.NONE`) and the request body already speaks TEXT,
+        // so this is an asymmetry rather than a design — filed, not deferred silently.
+        //
+        // An earlier revision wrote `outputSchema || resultPath ? JSON : undefined`, which implied a
+        // distinction that does not exist: absent means JSON too, so both arms were the same value.
+        responseDecoding: HttpApiTransportResponseDecoding.JSON,
+        retrySafe: providerOperationIsRetrySafe(operation),
+    };
+}
+//# sourceMappingURL=provider-operation-request.backend.js.map

package/dist/esm/external-providers/operations/provider-operation-request.backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-operation-request.backend.js","sourceRoot":"","sources":["../../../../src/external-providers/operations/provider-operation-request.backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Compiling a declared provider operation + a caller's input into ONE transport request (S3a,\n * #331).\n *\n * Deliberately a pure function over data, with no registry, no secrets and no I/O: an operation\n * declaration and an input go in, an {@link HttpApiTransportRequest} comes out. That is what makes\n * the interesting half — which input field lands in the path, which in the query, which in the\n * body, and whether the call may be retried — testable without a network, a provider or a\n * container.\n *\n * What this does NOT do, on purpose: it never PAGES. `pagination` on an operation is a hint the\n * caller reads; an executor that paged on its own would decide a caller's memory budget for it.\n */\n\nimport { API_HttpMethod } from '@wildo-ai/external-connectors-models';\n/*\n * `./backend` is the door that exists on `test`. #330 is splitting the private package by\n * AUDIENCE — `./backend-runtime` for what executes, `./backend` for tooling that enumerates every\n * engine-shipped provider — and has already moved backend-lib's runtime imports across in its own\n * work. This file was new and not in that sweep; #330 landed the split and moved this specifier with\n * the others, so the operations lane no longer pulls the eager registry into a running host. A\n * guard in `backend-provider-loader.module-graph.test.ts` now refuses any value import of the eager\n * barrel from this package's source, which is what stops the next new file re-introducing it.\n */\nimport { ProviderRestParameterLocation, ProviderRestRequestBodyEncoding, type ProviderRestOperation, type ProviderRestOperationParameter } from '@wildo-ai/external-connectors-models';\n\nimport {\n  HttpApiTransportBodyEncoding,\n  HttpApiTransportResponseDecoding,\n  type HttpApiTransportBody,\n  type HttpApiTransportRequest,\n} from '~wildo-backend-lib/base-classes/services/repositories/http-api/http-api-transport.backend';\n\n/** What went wrong while turning a declaration + an input into a request. */\nexport enum ProviderOperationRequestFailureKind {\n  /** The caller's input does not satisfy the operation's declared input schema. */\n  INPUT_REJECTED = 'INPUT_REJECTED',\n  /** A required value is absent — a path token with nothing to fill it, a required parameter. */\n  INPUT_INCOMPLETE = 'INPUT_INCOMPLETE',\n  /** The DECLARATION is inconsistent — a path token no parameter declares, a body with no source. */\n  DECLARATION_INCOHERENT = 'DECLARATION_INCOHERENT',\n}\n\nexport class ProviderOperationRequestError extends Error {\n  constructor(\n    message: string,\n    public readonly detail: {\n      readonly kind: ProviderOperationRequestFailureKind;\n      readonly operationId: string;\n      readonly providerRef: string;\n    },\n  ) {\n    super(message);\n    this.name = 'ProviderOperationRequestError';\n  }\n}\n\n/**\n * Methods whose repetition is safe.\n * spec-cite: RFC 9110 §9.2.2 — \"PUT, DELETE, and the safe request methods are idempotent\";\n * §9.2.1 names GET, HEAD, OPTIONS and TRACE as the safe ones.\n *\n * This is only the DEFAULT: an operation may declare `idempotent` and override it in either\n * direction — `true` on a POST the vendor documents behind an idempotency key, `false` on a PUT\n * whose target is not really a resource replacement.\n */\nconst IDEMPOTENT_METHODS: ReadonlySet<`${API_HttpMethod}`> = new Set([\n  API_HttpMethod.GET,\n  API_HttpMethod.HEAD,\n  API_HttpMethod.OPTIONS,\n  API_HttpMethod.PUT,\n  API_HttpMethod.DELETE,\n]);\n\n/** Whether re-sending this operation is safe — the value that reaches the transport's retry gate. */\nexport function providerOperationIsRetrySafe(operation: ProviderRestOperation): boolean {\n  return operation.idempotent ?? IDEMPOTENT_METHODS.has(operation.method);\n}\n\nconst PATH_TOKEN = /\\{([^}]+)\\}/g;\n\n/** The input field feeding a parameter: its own `from`, or the wire name when the two agree. */\nfunction inputFieldOf(parameter: ProviderRestOperationParameter): string {\n  return parameter.from ?? parameter.name;\n}\n\nfunction asWireValue(value: unknown): string {\n  return typeof value === 'string' ? value : String(value);\n}\n\nexport interface CompileProviderOperationInput {\n  operation: ProviderRestOperation;\n  providerRef: string;\n  /** Already validated against `operation.inputSchema` by the executor when one is declared. */\n  input: Readonly<Record<string, unknown>>;\n  /** Base URL and auth/default headers, from the provider access resolver. */\n  access: { baseUrl: string; headers: Record<string, string> };\n}\n\n/**\n * Build the request. Reads in one direction — path, then query, then headers, then body — and\n * records which input fields were consumed on the way, because the body's default source is\n * \"everything not consumed\" and that set can only be known after the parameters are placed.\n */\nexport function compileProviderOperationRequest(input: CompileProviderOperationInput): HttpApiTransportRequest {\n  const { operation, providerRef, access } = input;\n  const refuse = (kind: ProviderOperationRequestFailureKind, message: string): never => {\n    throw new ProviderOperationRequestError(message, { kind, operationId: operation.operationId, providerRef });\n  };\n\n  const parameters = operation.parameters ?? [];\n  const consumedInputFields = new Set<string>();\n\n  const valueFor = (parameter: ProviderRestOperationParameter): unknown => {\n    if (parameter.constantValue !== undefined) return parameter.constantValue;\n    const field = inputFieldOf(parameter);\n    consumedInputFields.add(field);\n    return input.input[field];\n  };\n\n  // ── path ───────────────────────────────────────────────────────────────────\n  const pathParameters = new Map(\n    parameters.filter((parameter) => parameter.in === ProviderRestParameterLocation.PATH).map((parameter) => [parameter.name, parameter]),\n  );\n  const path = operation.pathTemplate.replace(PATH_TOKEN, (_match, token: string) => {\n    const parameter = pathParameters.get(token);\n    if (!parameter) {\n      // The declaration is wrong, not the call: a path template cannot have a hole nothing fills.\n      return refuse(\n        ProviderOperationRequestFailureKind.DECLARATION_INCOHERENT,\n        `Operation '${operation.operationId}' has the path token '{${token}}' and declares no PATH parameter named '${token}'.`,\n      );\n    }\n    const value = valueFor(parameter);\n    if (value === undefined || value === null || value === '') {\n      return refuse(\n        ProviderOperationRequestFailureKind.INPUT_INCOMPLETE,\n        `Operation '${operation.operationId}' needs '${inputFieldOf(parameter)}' for the path token '{${token}}', and the input carries no value for it.`,\n      );\n    }\n    return encodeURIComponent(asWireValue(value));\n  });\n\n  // ── query ──────────────────────────────────────────────────────────────────\n  const search = new URLSearchParams();\n  for (const parameter of parameters) {\n    if (parameter.in !== ProviderRestParameterLocation.QUERY) continue;\n    const value = valueFor(parameter);\n    if (value === undefined || value === null) {\n      if (parameter.required) {\n        refuse(\n          ProviderOperationRequestFailureKind.INPUT_INCOMPLETE,\n          `Operation '${operation.operationId}' declares '${parameter.name}' as a required query parameter, and the input carries no value for it.`,\n        );\n      }\n      continue;\n    }\n    // An array becomes REPEATED parameters (`?tag=a&tag=b`), the only encoding every target\n    // accepts. A vendor wanting a joined list declares one field and the caller joins it — a\n    // guess here would silently send the wrong thing to half of them.\n    if (Array.isArray(value)) {\n      for (const entry of value) search.append(parameter.name, asWireValue(entry));\n      continue;\n    }\n    search.append(parameter.name, asWireValue(value));\n  }\n\n  // ── headers ────────────────────────────────────────────────────────────────\n  const headers: Record<string, string> = { Accept: 'application/json', ...access.headers };\n  for (const parameter of parameters) {\n    if (parameter.in !== ProviderRestParameterLocation.HEADER) continue;\n    const value = valueFor(parameter);\n    if (value === undefined || value === null) {\n      if (parameter.required) {\n        refuse(\n          ProviderOperationRequestFailureKind.INPUT_INCOMPLETE,\n          `Operation '${operation.operationId}' declares '${parameter.name}' as a required header, and the input carries no value for it.`,\n        );\n      }\n      continue;\n    }\n    headers[parameter.name] = asWireValue(value);\n  }\n\n  // ── body ───────────────────────────────────────────────────────────────────\n  let body: HttpApiTransportBody | undefined;\n  if (operation.requestBody) {\n    const declaration = operation.requestBody;\n    const payload = declaration.from !== undefined\n      ? input.input[declaration.from]\n      : Object.fromEntries(Object.entries(input.input).filter(([field]) => !consumedInputFields.has(field)));\n    switch (declaration.encoding) {\n      case ProviderRestRequestBodyEncoding.JSON:\n        body = { encoding: HttpApiTransportBodyEncoding.JSON, value: payload };\n        break;\n      case ProviderRestRequestBodyEncoding.FORM_URLENCODED: {\n        if (payload === null || typeof payload !== 'object') {\n          refuse(\n            ProviderOperationRequestFailureKind.INPUT_INCOMPLETE,\n            `Operation '${operation.operationId}' sends a form body and the input resolves to ${payload === null ? 'null' : typeof payload} instead of an object.`,\n          );\n        }\n        const fields: Record<string, string> = {};\n        for (const [field, value] of Object.entries(payload as Record<string, unknown>)) {\n          if (value === undefined || value === null) continue;\n          fields[field] = asWireValue(value);\n        }\n        body = { encoding: HttpApiTransportBodyEncoding.FORM_URLENCODED, value: fields };\n        break;\n      }\n      case ProviderRestRequestBodyEncoding.MULTIPART: {\n        if (!(payload instanceof FormData)) {\n          // Deliberately NOT built from a plain object here: a multipart part carries a filename\n          // and a media type the caller knows and this layer does not, and inventing them is how\n          // an upload arrives as `blob` with the wrong content type.\n          refuse(\n            ProviderOperationRequestFailureKind.INPUT_INCOMPLETE,\n            `Operation '${operation.operationId}' sends a multipart body, so its input must supply a FormData`\n            + `${declaration.from ? ` in '${declaration.from}'` : ''}; the caller supplied ${payload === null ? 'null' : typeof payload}.`,\n          );\n        }\n        body = { encoding: HttpApiTransportBodyEncoding.MULTIPART, value: payload as FormData };\n        break;\n      }\n      case ProviderRestRequestBodyEncoding.TEXT: {\n        if (typeof payload !== 'string') {\n          refuse(\n            ProviderOperationRequestFailureKind.INPUT_INCOMPLETE,\n            `Operation '${operation.operationId}' sends a text body, so its input must supply a string`\n            + `${declaration.from ? ` in '${declaration.from}'` : ''}; the caller supplied ${payload === null ? 'null' : typeof payload}.`,\n          );\n        }\n        if (declaration.contentType === undefined) {\n          refuse(\n            ProviderOperationRequestFailureKind.DECLARATION_INCOHERENT,\n            `Operation '${operation.operationId}' sends a text body and declares no contentType — a text body without its media type is not addressable.`,\n          );\n        }\n        body = { encoding: HttpApiTransportBodyEncoding.TEXT, value: payload as string, contentType: declaration.contentType as string };\n        break;\n      }\n      default: {\n        const exhaustiveCheck: never = declaration.encoding;\n        return exhaustiveCheck;\n      }\n    }\n  }\n\n  const query = search.toString();\n  return {\n    method: operation.method,\n    url: `${access.baseUrl}${path}${query.length > 0 ? `?${query}` : ''}`,\n    headers,\n    body,\n    // ALWAYS JSON, and stated rather than left to the transport's default so the limitation is\n    // visible at the site that imposes it: the operation declaration has no way to say the vendor\n    // answers `text/csv` or answers nothing at all. The transport carries both\n    // (`HttpApiTransportResponseDecoding.TEXT` / `.NONE`) and the request body already speaks TEXT,\n    // so this is an asymmetry rather than a design — filed, not deferred silently.\n    //\n    // An earlier revision wrote `outputSchema || resultPath ? JSON : undefined`, which implied a\n    // distinction that does not exist: absent means JSON too, so both arms were the same value.\n    responseDecoding: HttpApiTransportResponseDecoding.JSON,\n    retrySafe: providerOperationIsRetrySafe(operation),\n  };\n}\n"]}

package/dist/esm/external-providers/operations/provider-request-signing.backend.d.ts

@@ -0,0 +1,45 @@
+import { type ProviderRestRequestSigning } from '@wildo-ai/external-connectors-models';
+import type { HttpApiTransportRequest } from '../../base-classes/services/repositories/http-api/http-api-transport.backend';
+/**
+ * Per-request request signing — the credential a vendor COMPUTES rather than reads (#373).
+ *
+ * Signing is the LAST thing that happens to a request, and that ordering is not a preference: a
+ * signature covers the bytes. The method, the canonical path, the sorted query, the payload hash and
+ * a subset of the headers are all inputs, so anything that edits the request after signing — adding
+ * a header, re-encoding a body, appending a query parameter — invalidates it, and the vendor answers
+ * a 403 that names nothing.
+ *
+ * There is NO vendor branch here. The scheme is a contract field and this dispatches on it
+ * exhaustively, the same discipline the rest of the provider lane keeps.
+ *
+ * ## Why the failures are named
+ *
+ * A signature that is wrong is rejected identically however it was wrong: AWS answers
+ * `SignatureDoesNotMatch` whether the region was wrong, the service was wrong, the clock was skewed
+ * or the secret was stale. Those are four different remedies and one message, so the conditions this
+ * code CAN see — a missing credential, a clock far from the vendor's, an unsupported request shape —
+ * are reported here with their own words rather than left to become an opaque vendor rejection.
+ */
+export declare class ProviderRequestSigningError extends Error {
+    constructor(message: string);
+}
+/** The two-or-three values a signing scheme needs, resolved from the environment by the caller. */
+export interface ProviderSigningCredentials {
+    readonly keyId: string;
+    readonly secretKey: string;
+    readonly sessionToken?: string;
+    /** Overrides the declaration's region when a deployment names its own. */
+    readonly region?: string;
+}
+export interface SignProviderRequestInput {
+    readonly request: HttpApiTransportRequest;
+    readonly signing: ProviderRestRequestSigning;
+    readonly credentials: ProviderSigningCredentials;
+    /** Injected so a test can pin a signature against a published vector. */
+    readonly now?: Date;
+}
+/** Returns the request with its signature headers added. Never mutates the input. */
+export declare function signProviderRequest(input: SignProviderRequestInput): HttpApiTransportRequest;
+/** Exported for the diagnostic that names a clock skew rather than letting it read as a bad key. */
+export declare const PROVIDER_SIGNATURE_CLOCK_TOLERANCE_MINUTES = 5;
+//# sourceMappingURL=provider-request-signing.backend.d.ts.map

package/dist/esm/external-providers/operations/provider-request-signing.backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-request-signing.backend.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/operations/provider-request-signing.backend.ts"],"names":[],"mappings":"AAEA,OAAO,EAA6B,KAAK,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAElH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2FAA2F,CAAC;AAGzI;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED,mGAAmG;AACnG,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAcD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,0BAA0B,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC;IACjD,yEAAyE;IACzE,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;CACrB;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,uBAAuB,CAY5F;AAyMD,oGAAoG;AACpG,eAAO,MAAM,0CAA0C,IAAoC,CAAC"}

package/dist/esm/external-providers/operations/provider-request-signing.backend.js

@@ -0,0 +1,235 @@
+import { createHash, createHmac } from 'node:crypto';
+import { ProviderRestSigningScheme } from '@wildo-ai/external-connectors-models';
+import { withEngineOwnedHeaders } from '../../security/outbound/outbound-request-headers.backend.utils.js';
+/**
+ * Per-request request signing — the credential a vendor COMPUTES rather than reads (#373).
+ *
+ * Signing is the LAST thing that happens to a request, and that ordering is not a preference: a
+ * signature covers the bytes. The method, the canonical path, the sorted query, the payload hash and
+ * a subset of the headers are all inputs, so anything that edits the request after signing — adding
+ * a header, re-encoding a body, appending a query parameter — invalidates it, and the vendor answers
+ * a 403 that names nothing.
+ *
+ * There is NO vendor branch here. The scheme is a contract field and this dispatches on it
+ * exhaustively, the same discipline the rest of the provider lane keeps.
+ *
+ * ## Why the failures are named
+ *
+ * A signature that is wrong is rejected identically however it was wrong: AWS answers
+ * `SignatureDoesNotMatch` whether the region was wrong, the service was wrong, the clock was skewed
+ * or the secret was stale. Those are four different remedies and one message, so the conditions this
+ * code CAN see — a missing credential, a clock far from the vendor's, an unsupported request shape —
+ * are reported here with their own words rather than left to become an opaque vendor rejection.
+ */
+export class ProviderRequestSigningError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProviderRequestSigningError';
+    }
+}
+/**
+ * The clock tolerance every one of these schemes shares.
+ *
+ * AWS rejects a request whose `X-Amz-Date` is more than five minutes from its own clock, and Azure
+ * uses fifteen. This is not enforced here — only the vendor knows its clock — but the number is what
+ * makes a skew diagnosable: a host drifting past it fails EVERY signed request while every unsigned
+ * one succeeds, which is a confusing symptom until someone names it.
+ * spec-cite: AWS General Reference, "Elements of an AWS API request signature" — the five-minute
+ * window is stated there; the Azure figure is from "Authorize with Shared Key".
+ */
+const SIGNATURE_CLOCK_TOLERANCE_MINUTES = 5;
+/** Returns the request with its signature headers added. Never mutates the input. */
+export function signProviderRequest(input) {
+    const { signing } = input;
+    switch (signing.scheme) {
+        case ProviderRestSigningScheme.AWS_SIGV4:
+            return signAwsSigV4(input);
+        case ProviderRestSigningScheme.AZURE_SHARED_KEY:
+            return signAzureSharedKey(input);
+        default: {
+            const exhaustive = signing.scheme;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * AWS Signature Version 4.
+ *
+ * spec-cite: AWS General Reference, "Create a signed AWS API request" — the canonical request, the
+ * string to sign, the derived key chain and the Authorization header are all defined there.
+ *
+ * The payload hash is computed over the body EXACTLY as it will be sent, and an empty body hashes to
+ * the SHA-256 of the empty string rather than being omitted — a distinction that costs one line and,
+ * got wrong, makes every GET fail with a message about a signature mismatch.
+ */
+function signAwsSigV4(input) {
+    const { request, signing, credentials } = input;
+    const region = credentials.region ?? signing.region;
+    const service = signing.service;
+    if (region === undefined || service === undefined) {
+        throw new ProviderRequestSigningError('AWS SigV4 needs both a region and a service: they scope the DERIVED KEY, so a wrong or absent value fails '
+            + `authentication rather than routing. Declare them on the provider's requestSigning block (region: ${region ?? 'unset'}, service: ${service ?? 'unset'}).`);
+    }
+    const url = new URL(request.url);
+    const now = input.now ?? new Date();
+    const amzDate = `${now.toISOString().replace(/[-:]/g, '').slice(0, 15)}Z`;
+    const dateStamp = amzDate.slice(0, 8);
+    const payload = bodyToPayload(request.body);
+    const payloadHash = createHash('sha256').update(payload).digest('hex');
+    // `host` is required in the signature and is not in the request's own headers — the transport adds
+    // it. Signing what will actually be sent means adding it here, in the same order the canonical
+    // form demands.
+    const headersToSign = {
+        host: url.host,
+        'x-amz-date': amzDate,
+        ...(credentials.sessionToken === undefined ? {} : { 'x-amz-security-token': credentials.sessionToken }),
+        ...(request.body === undefined ? {} : { 'content-type': request.headers['Content-Type'] ?? request.headers['content-type'] ?? 'application/json' }),
+    };
+    const signedHeaderNames = Object.keys(headersToSign).map((name) => name.toLowerCase()).sort();
+    const canonicalHeaders = signedHeaderNames
+        .map((name) => `${name}:${collapseWhitespace(headersToSign[name] ?? headersToSign[Object.keys(headersToSign).find((key) => key.toLowerCase() === name)])}\n`)
+        .join('');
+    const signedHeaders = signedHeaderNames.join(';');
+    const canonicalRequest = [
+        request.method,
+        canonicalUri(url.pathname),
+        canonicalQuery(url.searchParams),
+        canonicalHeaders,
+        signedHeaders,
+        payloadHash,
+    ].join('\n');
+    const scope = `${dateStamp}/${region}/${service}/aws4_request`;
+    const stringToSign = [
+        'AWS4-HMAC-SHA256',
+        amzDate,
+        scope,
+        createHash('sha256').update(canonicalRequest).digest('hex'),
+    ].join('\n');
+    const signingKey = ['aws4_request'].reduce((key, step) => hmac(key, step), [region, service].reduce((key, step) => hmac(key, step), hmac(`AWS4${credentials.secretKey}`, dateStamp)));
+    const signature = hmac(signingKey, stringToSign).toString('hex');
+    /*
+     * The signature headers are the engine's, and a catalogue-declared spelling cannot dilute them.
+     *
+     * `request.headers` carries the provider catalogue's `defaultHeaders`, so a catalogue naming
+     * `authorization` or `x-amz-date` against the canonical spellings written here would produce two
+     * object keys per header — combined by `fetch` into one comma-joined value, which AWS rejects as
+     * a malformed signature rather than as the header collision it is.
+     *
+     * Filtering is safe against the signature specifically because `signedHeaders` is computed from
+     * the CLOSED `headersToSign` set above (host, x-amz-date, x-amz-security-token, content-type) and
+     * never from `request.headers` at large — so no header being dropped here was ever signed.
+     * `content-type` is not engine-owned at this merge and is therefore left exactly as the caller
+     * set it, which is what keeps it agreeing with the value that WAS signed.
+     *
+     * The session token is reserved even when the engine has none: absent credentials must not be
+     * satisfiable by a value a provider catalogue supplied.
+     */
+    return {
+        ...request,
+        headers: withEngineOwnedHeaders(request.headers, {
+            'X-Amz-Date': amzDate,
+            'X-Amz-Security-Token': credentials.sessionToken,
+            'X-Amz-Content-Sha256': payloadHash,
+            Authorization: `AWS4-HMAC-SHA256 Credential=${credentials.keyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+        }),
+    };
+}
+/**
+ * Azure Storage shared key.
+ *
+ * spec-cite: Azure Storage REST, "Authorize with Shared Key" — the canonicalized headers and
+ * canonicalized resource, and the `SharedKey <account>:<signature>` header, are defined there.
+ *
+ * Deliberately the FULL scheme rather than SharedKeyLite: the two differ in which fields the string
+ * to sign carries, and a service that expects one rejects the other with the same opaque message a
+ * wrong key produces.
+ */
+function signAzureSharedKey(input) {
+    const { request, credentials } = input;
+    const url = new URL(request.url);
+    const now = input.now ?? new Date();
+    const date = now.toUTCString();
+    const payload = bodyToPayload(request.body);
+    const contentLength = payload.length === 0 ? '' : String(payload.length);
+    const contentType = request.headers['Content-Type'] ?? request.headers['content-type'] ?? '';
+    const canonicalizedHeaders = `x-ms-date:${date}\nx-ms-version:2021-12-02\n`;
+    const canonicalizedResource = [
+        `/${credentials.keyId}${canonicalUri(url.pathname)}`,
+        ...[...url.searchParams.keys()]
+            .map((key) => key.toLowerCase())
+            .sort()
+            .map((key) => `${key}:${url.searchParams.getAll(key).sort().join(',')}`),
+    ].join('\n');
+    const stringToSign = [
+        request.method,
+        '', // Content-Encoding
+        '', // Content-Language
+        contentLength,
+        '', // Content-MD5
+        contentType,
+        '', // Date — empty because x-ms-date is used instead
+        '', // If-Modified-Since
+        '', // If-Match
+        '', // If-None-Match
+        '', // If-Unmodified-Since
+        '', // Range
+        canonicalizedHeaders + canonicalizedResource,
+    ].join('\n');
+    const signature = createHmac('sha256', Buffer.from(credentials.secretKey, 'base64')).update(stringToSign, 'utf8').digest('base64');
+    // Same reasoning as the SigV4 twin: `canonicalizedHeaders` above is a fixed literal, so nothing
+    // dropped here was signed, and reserving the names stops a catalogue-declared spelling being
+    // combined with the engine's on the wire.
+    return {
+        ...request,
+        headers: withEngineOwnedHeaders(request.headers, {
+            'x-ms-date': date,
+            'x-ms-version': '2021-12-02',
+            Authorization: `SharedKey ${credentials.keyId}:${signature}`,
+        }),
+    };
+}
+/**
+ * The canonical URI: each path segment URI-encoded, and the encoding applied ONCE for most services.
+ * S3 is the documented exception (it does not double-encode), and since every service this contract
+ * reaches declares its own `service`, the single-encoding form is what is implemented — the double
+ * encoding other services expect is a documented difference, not a bug, and belongs with the first
+ * provider that needs it rather than guessed at now.
+ */
+function canonicalUri(pathname) {
+    if (pathname === '')
+        return '/';
+    return pathname
+        .split('/')
+        .map((segment) => encodeURIComponent(decodeURIComponent(segment)).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`))
+        .join('/');
+}
+/** Sorted by name then value, each component encoded, joined — the canonical query string. */
+function canonicalQuery(params) {
+    const pairs = [];
+    params.forEach((value, key) => pairs.push([key, value]));
+    return pairs
+        .map(([key, value]) => [encodeRfc3986(key), encodeRfc3986(value)])
+        .sort((left, right) => (left[0] === right[0] ? left[1].localeCompare(right[1]) : left[0].localeCompare(right[0])))
+        .map(([key, value]) => `${key}=${value}`)
+        .join('&');
+}
+function encodeRfc3986(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function collapseWhitespace(value) {
+    return value.trim().replace(/\s+/g, ' ');
+}
+function hmac(key, data) {
+    return createHmac('sha256', key).update(data, 'utf8').digest();
+}
+/** The bytes that will actually be sent, as a string — what the payload hash must cover. */
+function bodyToPayload(body) {
+    if (body === undefined)
+        return '';
+    if (typeof body === 'string')
+        return body;
+    return JSON.stringify(body);
+}
+/** Exported for the diagnostic that names a clock skew rather than letting it read as a bad key. */
+export const PROVIDER_SIGNATURE_CLOCK_TOLERANCE_MINUTES = SIGNATURE_CLOCK_TOLERANCE_MINUTES;
+//# sourceMappingURL=provider-request-signing.backend.js.map

package/dist/esm/external-providers/operations/provider-request-signing.backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-request-signing.backend.js","sourceRoot":"","sources":["../../../../src/external-providers/operations/provider-request-signing.backend.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, createHmac } from 'node:crypto';\n\nimport { ProviderRestSigningScheme, type ProviderRestRequestSigning } from '@wildo-ai/external-connectors-models';\n\nimport type { HttpApiTransportRequest } from '~wildo-backend-lib/base-classes/services/repositories/http-api/http-api-transport.backend';\nimport { withEngineOwnedHeaders } from '~wildo-backend-lib/security/outbound/outbound-request-headers.backend.utils';\n\n/**\n * Per-request request signing — the credential a vendor COMPUTES rather than reads (#373).\n *\n * Signing is the LAST thing that happens to a request, and that ordering is not a preference: a\n * signature covers the bytes. The method, the canonical path, the sorted query, the payload hash and\n * a subset of the headers are all inputs, so anything that edits the request after signing — adding\n * a header, re-encoding a body, appending a query parameter — invalidates it, and the vendor answers\n * a 403 that names nothing.\n *\n * There is NO vendor branch here. The scheme is a contract field and this dispatches on it\n * exhaustively, the same discipline the rest of the provider lane keeps.\n *\n * ## Why the failures are named\n *\n * A signature that is wrong is rejected identically however it was wrong: AWS answers\n * `SignatureDoesNotMatch` whether the region was wrong, the service was wrong, the clock was skewed\n * or the secret was stale. Those are four different remedies and one message, so the conditions this\n * code CAN see — a missing credential, a clock far from the vendor's, an unsupported request shape —\n * are reported here with their own words rather than left to become an opaque vendor rejection.\n */\n\nexport class ProviderRequestSigningError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'ProviderRequestSigningError';\n  }\n}\n\n/** The two-or-three values a signing scheme needs, resolved from the environment by the caller. */\nexport interface ProviderSigningCredentials {\n  readonly keyId: string;\n  readonly secretKey: string;\n  readonly sessionToken?: string;\n  /** Overrides the declaration's region when a deployment names its own. */\n  readonly region?: string;\n}\n\n/**\n * The clock tolerance every one of these schemes shares.\n *\n * AWS rejects a request whose `X-Amz-Date` is more than five minutes from its own clock, and Azure\n * uses fifteen. This is not enforced here — only the vendor knows its clock — but the number is what\n * makes a skew diagnosable: a host drifting past it fails EVERY signed request while every unsigned\n * one succeeds, which is a confusing symptom until someone names it.\n * spec-cite: AWS General Reference, \"Elements of an AWS API request signature\" — the five-minute\n * window is stated there; the Azure figure is from \"Authorize with Shared Key\".\n */\nconst SIGNATURE_CLOCK_TOLERANCE_MINUTES = 5;\n\nexport interface SignProviderRequestInput {\n  readonly request: HttpApiTransportRequest;\n  readonly signing: ProviderRestRequestSigning;\n  readonly credentials: ProviderSigningCredentials;\n  /** Injected so a test can pin a signature against a published vector. */\n  readonly now?: Date;\n}\n\n/** Returns the request with its signature headers added. Never mutates the input. */\nexport function signProviderRequest(input: SignProviderRequestInput): HttpApiTransportRequest {\n  const { signing } = input;\n  switch (signing.scheme) {\n    case ProviderRestSigningScheme.AWS_SIGV4:\n      return signAwsSigV4(input);\n    case ProviderRestSigningScheme.AZURE_SHARED_KEY:\n      return signAzureSharedKey(input);\n    default: {\n      const exhaustive: never = signing.scheme;\n      return exhaustive;\n    }\n  }\n}\n\n/**\n * AWS Signature Version 4.\n *\n * spec-cite: AWS General Reference, \"Create a signed AWS API request\" — the canonical request, the\n * string to sign, the derived key chain and the Authorization header are all defined there.\n *\n * The payload hash is computed over the body EXACTLY as it will be sent, and an empty body hashes to\n * the SHA-256 of the empty string rather than being omitted — a distinction that costs one line and,\n * got wrong, makes every GET fail with a message about a signature mismatch.\n */\nfunction signAwsSigV4(input: SignProviderRequestInput): HttpApiTransportRequest {\n  const { request, signing, credentials } = input;\n  const region = credentials.region ?? signing.region;\n  const service = signing.service;\n  if (region === undefined || service === undefined) {\n    throw new ProviderRequestSigningError(\n      'AWS SigV4 needs both a region and a service: they scope the DERIVED KEY, so a wrong or absent value fails '\n      + `authentication rather than routing. Declare them on the provider's requestSigning block (region: ${region ?? 'unset'}, service: ${service ?? 'unset'}).`,\n    );\n  }\n\n  const url = new URL(request.url);\n  const now = input.now ?? new Date();\n  const amzDate = `${now.toISOString().replace(/[-:]/g, '').slice(0, 15)}Z`;\n  const dateStamp = amzDate.slice(0, 8);\n\n  const payload = bodyToPayload(request.body);\n  const payloadHash = createHash('sha256').update(payload).digest('hex');\n\n  // `host` is required in the signature and is not in the request's own headers — the transport adds\n  // it. Signing what will actually be sent means adding it here, in the same order the canonical\n  // form demands.\n  const headersToSign: Record<string, string> = {\n    host: url.host,\n    'x-amz-date': amzDate,\n    ...(credentials.sessionToken === undefined ? {} : { 'x-amz-security-token': credentials.sessionToken }),\n    ...(request.body === undefined ? {} : { 'content-type': request.headers['Content-Type'] ?? request.headers['content-type'] ?? 'application/json' }),\n  };\n  const signedHeaderNames = Object.keys(headersToSign).map((name) => name.toLowerCase()).sort();\n  const canonicalHeaders = signedHeaderNames\n    .map((name) => `${name}:${collapseWhitespace(headersToSign[name] ?? headersToSign[Object.keys(headersToSign).find((key) => key.toLowerCase() === name)!]!)}\\n`)\n    .join('');\n  const signedHeaders = signedHeaderNames.join(';');\n\n  const canonicalRequest = [\n    request.method,\n    canonicalUri(url.pathname),\n    canonicalQuery(url.searchParams),\n    canonicalHeaders,\n    signedHeaders,\n    payloadHash,\n  ].join('\\n');\n\n  const scope = `${dateStamp}/${region}/${service}/aws4_request`;\n  const stringToSign = [\n    'AWS4-HMAC-SHA256',\n    amzDate,\n    scope,\n    createHash('sha256').update(canonicalRequest).digest('hex'),\n  ].join('\\n');\n\n  const signingKey = ['aws4_request'].reduce(\n    (key, step) => hmac(key, step),\n    [region, service].reduce((key, step) => hmac(key, step), hmac(`AWS4${credentials.secretKey}`, dateStamp)),\n  );\n  const signature = hmac(signingKey, stringToSign).toString('hex');\n\n  /*\n   * The signature headers are the engine's, and a catalogue-declared spelling cannot dilute them.\n   *\n   * `request.headers` carries the provider catalogue's `defaultHeaders`, so a catalogue naming\n   * `authorization` or `x-amz-date` against the canonical spellings written here would produce two\n   * object keys per header — combined by `fetch` into one comma-joined value, which AWS rejects as\n   * a malformed signature rather than as the header collision it is.\n   *\n   * Filtering is safe against the signature specifically because `signedHeaders` is computed from\n   * the CLOSED `headersToSign` set above (host, x-amz-date, x-amz-security-token, content-type) and\n   * never from `request.headers` at large — so no header being dropped here was ever signed.\n   * `content-type` is not engine-owned at this merge and is therefore left exactly as the caller\n   * set it, which is what keeps it agreeing with the value that WAS signed.\n   *\n   * The session token is reserved even when the engine has none: absent credentials must not be\n   * satisfiable by a value a provider catalogue supplied.\n   */\n  return {\n    ...request,\n    headers: withEngineOwnedHeaders(request.headers, {\n      'X-Amz-Date': amzDate,\n      'X-Amz-Security-Token': credentials.sessionToken,\n      'X-Amz-Content-Sha256': payloadHash,\n      Authorization: `AWS4-HMAC-SHA256 Credential=${credentials.keyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,\n    }),\n  };\n}\n\n/**\n * Azure Storage shared key.\n *\n * spec-cite: Azure Storage REST, \"Authorize with Shared Key\" — the canonicalized headers and\n * canonicalized resource, and the `SharedKey <account>:<signature>` header, are defined there.\n *\n * Deliberately the FULL scheme rather than SharedKeyLite: the two differ in which fields the string\n * to sign carries, and a service that expects one rejects the other with the same opaque message a\n * wrong key produces.\n */\nfunction signAzureSharedKey(input: SignProviderRequestInput): HttpApiTransportRequest {\n  const { request, credentials } = input;\n  const url = new URL(request.url);\n  const now = input.now ?? new Date();\n  const date = now.toUTCString();\n  const payload = bodyToPayload(request.body);\n  const contentLength = payload.length === 0 ? '' : String(payload.length);\n  const contentType = request.headers['Content-Type'] ?? request.headers['content-type'] ?? '';\n\n  const canonicalizedHeaders = `x-ms-date:${date}\\nx-ms-version:2021-12-02\\n`;\n  const canonicalizedResource = [\n    `/${credentials.keyId}${canonicalUri(url.pathname)}`,\n    ...[...url.searchParams.keys()]\n      .map((key) => key.toLowerCase())\n      .sort()\n      .map((key) => `${key}:${url.searchParams.getAll(key).sort().join(',')}`),\n  ].join('\\n');\n\n  const stringToSign = [\n    request.method,\n    '', // Content-Encoding\n    '', // Content-Language\n    contentLength,\n    '', // Content-MD5\n    contentType,\n    '', // Date — empty because x-ms-date is used instead\n    '', // If-Modified-Since\n    '', // If-Match\n    '', // If-None-Match\n    '', // If-Unmodified-Since\n    '', // Range\n    canonicalizedHeaders + canonicalizedResource,\n  ].join('\\n');\n\n  const signature = createHmac('sha256', Buffer.from(credentials.secretKey, 'base64')).update(stringToSign, 'utf8').digest('base64');\n\n  // Same reasoning as the SigV4 twin: `canonicalizedHeaders` above is a fixed literal, so nothing\n  // dropped here was signed, and reserving the names stops a catalogue-declared spelling being\n  // combined with the engine's on the wire.\n  return {\n    ...request,\n    headers: withEngineOwnedHeaders(request.headers, {\n      'x-ms-date': date,\n      'x-ms-version': '2021-12-02',\n      Authorization: `SharedKey ${credentials.keyId}:${signature}`,\n    }),\n  };\n}\n\n/**\n * The canonical URI: each path segment URI-encoded, and the encoding applied ONCE for most services.\n * S3 is the documented exception (it does not double-encode), and since every service this contract\n * reaches declares its own `service`, the single-encoding form is what is implemented — the double\n * encoding other services expect is a documented difference, not a bug, and belongs with the first\n * provider that needs it rather than guessed at now.\n */\nfunction canonicalUri(pathname: string): string {\n  if (pathname === '') return '/';\n  return pathname\n    .split('/')\n    .map((segment) => encodeURIComponent(decodeURIComponent(segment)).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`))\n    .join('/');\n}\n\n/** Sorted by name then value, each component encoded, joined — the canonical query string. */\nfunction canonicalQuery(params: URLSearchParams): string {\n  const pairs: Array<[string, string]> = [];\n  params.forEach((value, key) => pairs.push([key, value]));\n  return pairs\n    .map(([key, value]) => [encodeRfc3986(key), encodeRfc3986(value)] as const)\n    .sort((left, right) => (left[0] === right[0] ? left[1].localeCompare(right[1]) : left[0].localeCompare(right[0])))\n    .map(([key, value]) => `${key}=${value}`)\n    .join('&');\n}\n\nfunction encodeRfc3986(value: string): string {\n  return encodeURIComponent(value).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);\n}\n\nfunction collapseWhitespace(value: string): string {\n  return value.trim().replace(/\\s+/g, ' ');\n}\n\nfunction hmac(key: string | Buffer, data: string): Buffer {\n  return createHmac('sha256', key).update(data, 'utf8').digest();\n}\n\n/** The bytes that will actually be sent, as a string — what the payload hash must cover. */\nfunction bodyToPayload(body: HttpApiTransportRequest['body']): string {\n  if (body === undefined) return '';\n  if (typeof body === 'string') return body;\n  return JSON.stringify(body);\n}\n\n/** Exported for the diagnostic that names a clock skew rather than letting it read as a bad key. */\nexport const PROVIDER_SIGNATURE_CLOCK_TOLERANCE_MINUTES = SIGNATURE_CLOCK_TOLERANCE_MINUTES;\n"]}