From b026f4529c2460b054d75a27712fc3da1118aa1b Mon Sep 17 00:00:00 2001 From: Antoine Date: Fri, 13 Nov 2026 23:09:40 +0100 Subject: [PATCH 1/3] fix(core): share one header and URL sanitizer for request facts [SAP-5145] fetch, axios and node-http each kept their own short header list and reported the URL and its query string as sent. They now share one list in @sapiom/core that leaves out credential headers (bt-api-key, api-key and similar, matching the Sapiom API's stored-facts list) and masks credential query values and userinfo in url and urlParsed.search. Only the facts change; the outgoing request is unchanged. --- .changeset/facts-credential-sanitization.md | 8 + .../axios/src/http-client.integration.test.ts | 46 ++++++ packages/axios/src/interceptors.ts | 52 +++---- packages/core/src/index.ts | 7 + .../core/src/utils/facts-sanitization.test.ts | 142 ++++++++++++++++++ packages/core/src/utils/facts-sanitization.ts | 137 +++++++++++++++++ .../fetch/src/http-client.integration.test.ts | 64 ++++++++ packages/fetch/src/interceptors.ts | 51 +++---- .../src/http-client.integration.test.ts | 52 +++++++ packages/node-http/src/interceptors.ts | 38 ++--- 10 files changed, 505 insertions(+), 92 deletions(-) create mode 100644 .changeset/facts-credential-sanitization.md create mode 100644 packages/core/src/utils/facts-sanitization.test.ts create mode 100644 packages/core/src/utils/facts-sanitization.ts diff --git a/.changeset/facts-credential-sanitization.md b/.changeset/facts-credential-sanitization.md new file mode 100644 index 000000000..db4c65f63 --- /dev/null +++ b/.changeset/facts-credential-sanitization.md @@ -0,0 +1,8 @@ +--- +"@sapiom/core": minor +"@sapiom/fetch": patch +"@sapiom/axios": patch +"@sapiom/node-http": patch +--- + +Request and response facts now share one header and URL sanitizer. `@sapiom/fetch`, `@sapiom/axios` and `@sapiom/node-http` leave out the same credential headers (`authorization`, cookies, `x-api-key`, `api-key`, `bt-api-key` and other `*-api-key` / `*token*` / `*secret*` / `*password*` headers, payment signatures, `x-sapiom-*` key and token headers), and mask credential query values (`key`, `api_key`, `token`, `access_token`, `signature`, `sig`, `password`, …) and `user:pass@` in the reported `url` and `urlParsed.search`. Only the facts change: the outgoing request is sent exactly as before. `@sapiom/core` exports the helpers (`sanitizeHeadersForFacts`, `sanitizeUrlForFacts`, `isSensitiveHeaderName`, `isSensitiveQueryParam`). diff --git a/packages/axios/src/http-client.integration.test.ts b/packages/axios/src/http-client.integration.test.ts index 3330653d4..b9598fc07 100644 --- a/packages/axios/src/http-client.integration.test.ts +++ b/packages/axios/src/http-client.integration.test.ts @@ -979,3 +979,49 @@ describe("Axios HTTP Client Integration Tests", () => { }); }); }); + +describe("Facts sanitization", () => { + it("leaves credential headers out of facts and masks credential query values, without changing the request", async () => { + const axiosInstance = axios.create({ baseURL: "https://api.example.com" }); + const mockAxios = new MockAdapter(axiosInstance); + const { client: sapiomClient, mocks } = createMockSapiomClient(); + mocks.create.mockResolvedValue({ + id: "tx-facts", + status: TransactionStatus.AUTHORIZED, + } as any); + mocks.complete.mockResolvedValue({ + transaction: { id: "tx-facts", status: "completed" }, + } as any); + mockAxios + .onGet(/\/geocode/) + .reply( + 200, + { ok: true }, + { "set-cookie": "sid=FAKE", "x-request-id": "r-1" }, + ); + + const client = withSapiom(axiosInstance, { sapiomClient }); + await client.get("/geocode?key=FAKEKEY&address=Paris", { + headers: { "bt-api-key": "FAKEBT", accept: "application/json" }, + }); + await flushPromises(); + + const request = mocks.create.mock.calls[0][0].requestFacts!.request as any; + expect(request.url).toBe( + "https://api.example.com/geocode?key=[REDACTED]&address=Paris", + ); + expect(request.urlParsed.search).toBe("?key=[REDACTED]&address=Paris"); + // axios merges the header into its default `Accept`. + expect(request.headers).toEqual({ Accept: "application/json" }); + const response = (mocks.complete.mock.calls[0][1].responseFacts as any) + .facts; + expect(response.headers["set-cookie"]).toBeUndefined(); + expect(response.headers["x-request-id"]).toBe("r-1"); + + // The request itself still carries the real URL and headers. + const sent = mockAxios.history.get[0]; + expect(sent.url).toBe("/geocode?key=FAKEKEY&address=Paris"); + expect(sent.headers?.["bt-api-key"]).toBe("FAKEBT"); + mockAxios.restore(); + }); +}); diff --git a/packages/axios/src/interceptors.ts b/packages/axios/src/interceptors.ts index ee95ac892..89c3fbd82 100644 --- a/packages/axios/src/interceptors.ts +++ b/packages/axios/src/interceptors.ts @@ -17,6 +17,8 @@ import { HttpClientResponseFacts, HttpClientErrorFacts, FailureMode, + sanitizeHeadersForFacts, + sanitizeUrlForFacts, } from "@sapiom/core"; import type { TransactionPollingConfig } from "@sapiom/core"; @@ -394,7 +396,7 @@ export function addAuthorizationInterceptor( protocol: parsed.protocol, hostname: parsed.hostname, pathname: parsed.pathname, - search: parsed.search, + search: sanitizeUrlForFacts(parsed.search), port: parsed.port ? parseInt(parsed.port) : null, }; } catch { @@ -407,25 +409,21 @@ export function addAuthorizationInterceptor( }; } - const sanitizedHeaders: Record = {}; - if (axiosConfig.headers) { - Object.entries(axiosConfig.headers as Record).forEach( - ([key, value]) => { - const lowerKey = key.toLowerCase(); - if ( - !lowerKey.includes("auth") && - !lowerKey.includes("key") && - !lowerKey.includes("token") - ) { - sanitizedHeaders[key] = String(value); - } - }, - ); - } + // Shared list, plus this integration's broader substring rule (kept so no + // header it left out before is reported now). + const sanitizedHeaders = sanitizeHeadersForFacts( + axiosConfig.headers + ? Object.entries(axiosConfig.headers as Record) + : undefined, + (lowerKey) => + lowerKey.includes("auth") || + lowerKey.includes("key") || + lowerKey.includes("token"), + ); const requestFacts: HttpClientRequestFacts = { method, - url: fullUrl, + url: sanitizeUrlForFacts(fullUrl), urlParsed, headers: sanitizedHeaders, hasBody: !!axiosConfig.data, @@ -789,21 +787,11 @@ export function addCompletionInterceptor( const startTime = (axiosConfig as any).__sapiomStartTime || Date.now(); const durationMs = Date.now() - startTime; - const sanitizedHeaders: Record = {}; - const sensitiveHeaders = new Set([ - "set-cookie", - "authorization", - "x-api-key", - ]); - if (response.headers) { - Object.entries(response.headers as Record).forEach( - ([key, value]) => { - if (!sensitiveHeaders.has(key.toLowerCase())) { - sanitizedHeaders[key] = String(value); - } - }, - ); - } + const sanitizedHeaders = sanitizeHeadersForFacts( + response.headers + ? Object.entries(response.headers as Record) + : undefined, + ); const facts: HttpClientResponseFacts = { status: response.status, diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index d29c9d008..9a1001413 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -52,6 +52,13 @@ export type { // Telemetry export { captureUserCallSite, getRuntimeInfo } from "./utils/telemetry.js"; +export { + REDACTED_FACT_VALUE, + isSensitiveHeaderName, + isSensitiveQueryParam, + sanitizeHeadersForFacts, + sanitizeUrlForFacts, +} from "./utils/facts-sanitization.js"; export type { CallSiteInfo, RuntimeInfo } from "./types/telemetry.js"; // Types diff --git a/packages/core/src/utils/facts-sanitization.test.ts b/packages/core/src/utils/facts-sanitization.test.ts new file mode 100644 index 000000000..01b2f2f37 --- /dev/null +++ b/packages/core/src/utils/facts-sanitization.test.ts @@ -0,0 +1,142 @@ +import { + REDACTED_FACT_VALUE, + isSensitiveHeaderName, + isSensitiveQueryParam, + sanitizeHeadersForFacts, + sanitizeUrlForFacts, +} from "./facts-sanitization"; + +describe("facts sanitization", () => { + describe("isSensitiveHeaderName", () => { + it.each([ + "authorization", + "Authorization", + "proxy-authorization", + "cookie", + "set-cookie", + "payment-signature", + "x-payment", + "x-api-key", + "api-key", + "apikey", + "bt-api-key", + "BT-Trace-Id", + "x-goog-api-key", + "x-auth-token", + "x-client-secret", + "x-db-password", + "x-license-key", + "x-sapiom-api-key", + "x-sapiom-service-key", + "x-sapiom-signature", + "x-sapiom-workflow-token", + ])("leaves out %s", (name) => { + expect(isSensitiveHeaderName(name)).toBe(true); + }); + + it.each([ + "content-type", + "accept", + "user-agent", + "x-request-id", + "x-sapiom-transaction-id", + "x-sapiom-trace-id", + ])("keeps %s", (name) => { + expect(isSensitiveHeaderName(name)).toBe(false); + }); + }); + + describe("isSensitiveQueryParam", () => { + it.each([ + "key", + "KEY", + "api_key", + "apikey", + "token", + "access_token", + "secret", + "signature", + "sig", + "password", + "X-Amz-Signature", + "api%5Fkey", + ])("masks %s", (name) => { + expect(isSensitiveQueryParam(name)).toBe(true); + }); + + it.each(["q", "limit", "keyword", "monkey", "author"])( + "keeps %s", + (name) => { + expect(isSensitiveQueryParam(name)).toBe(false); + }, + ); + }); + + describe("sanitizeUrlForFacts", () => { + it("masks credential query values and keeps every other part as it was", () => { + expect( + sanitizeUrlForFacts( + "https://api.example.com/v1/geocode?key=abc123&address=Paris&access_token=t#top", + ), + ).toBe( + `https://api.example.com/v1/geocode?key=${REDACTED_FACT_VALUE}&address=Paris&access_token=${REDACTED_FACT_VALUE}#top`, + ); + }); + + it("masks userinfo", () => { + expect( + sanitizeUrlForFacts("https://alice:hunter2@api.example.com/x"), + ).toBe(`https://${REDACTED_FACT_VALUE}@api.example.com/x`); + }); + + it("works on a bare search string", () => { + expect(sanitizeUrlForFacts("?token=abc&q=1")).toBe( + `?token=${REDACTED_FACT_VALUE}&q=1`, + ); + expect(sanitizeUrlForFacts("")).toBe(""); + }); + + it("returns a URL with nothing to mask unchanged", () => { + const url = "https://api.example.com/search?q=a%20b&limit=10&keyword=k"; + expect(sanitizeUrlForFacts(url)).toBe(url); + }); + }); + + describe("sanitizeHeadersForFacts", () => { + it("drops sensitive headers from a record and stringifies the rest", () => { + expect( + sanitizeHeadersForFacts({ + "bt-api-key": "k", + "api-key": "k", + Authorization: "Bearer t", + "content-type": "application/json", + "content-length": 42, + "x-empty": undefined, + }), + ).toEqual({ "content-type": "application/json", "content-length": "42" }); + }); + + it("accepts a Headers entries iterable", () => { + const headers = new Map([ + ["set-cookie", "sid=1"], + ["accept", "*/*"], + ]); + expect(sanitizeHeadersForFacts(headers.entries())).toEqual({ + accept: "*/*", + }); + }); + + it("applies an extra exclusion on top of the shared list", () => { + expect( + sanitizeHeadersForFacts( + { "x-idempotency-key-id": "1", accept: "*/*" }, + (name) => name.includes("key"), + ), + ).toEqual({ accept: "*/*" }); + }); + + it("returns an empty record for no headers", () => { + expect(sanitizeHeadersForFacts(undefined)).toEqual({}); + }); + }); +}); diff --git a/packages/core/src/utils/facts-sanitization.ts b/packages/core/src/utils/facts-sanitization.ts new file mode 100644 index 000000000..8f2895a1a --- /dev/null +++ b/packages/core/src/utils/facts-sanitization.ts @@ -0,0 +1,137 @@ +/** + * Header and URL sanitization for the request and response facts the SDK + * reports with a transaction. + * + * Facts describe a call (method, host, path, status, content type). They + * should never carry the credentials the call was made with. The HTTP + * integrations (`@sapiom/fetch`, `@sapiom/axios`, `@sapiom/node-http`) share + * this one list, so they leave out the same headers and mask the same URL + * parts. The Sapiom API masks the same names again when it stores facts. + */ + +/** The value a masked URL query parameter or userinfo is replaced with. */ +export const REDACTED_FACT_VALUE = "[REDACTED]"; + +/** Header names that always carry a credential. */ +const SENSITIVE_HEADER_EXACT = new Set([ + "authorization", + "proxy-authorization", + "cookie", + "set-cookie", + "payment-signature", + "x-payment", + "x-payment-response", +]); + +/** A name that names a credential: `x-api-key`, `bt-api-key`, `client_secret`, … */ +const CREDENTIAL_NAME = + /api[-_]?key|apikey|token|secret|password|passwd|credential|signature|private[-_]?key/i; + +/** Header names only: anything with `auth` in it, and any `*-key` / `*_key`. */ +const SENSITIVE_HEADER_EXTRA = /auth|(?:^|[-_])key$/i; + +/** Every `bt-*` header, and `x-sapiom-*` headers that carry a key, token or signature. */ +const SENSITIVE_HEADER_PREFIX = + /^bt-|^x-sapiom-.*(?:key|token|secret|signature|auth)/i; + +/** Query parameters whose value is a credential (matched case-insensitively). */ +const SENSITIVE_QUERY_EXACT = new Set(["key", "sig", "auth", "pwd", "pass"]); + +const USERINFO = /^([a-z][a-z0-9+.-]*:\/\/)([^/?#@\s]+)@/i; + +/** + * Whether a header must be left out of facts: `Authorization`, cookies, + * API-key, token, secret and password headers (`x-api-key`, `bt-api-key`, + * `api-key`, `x-auth-token`, …), payment signatures, and `x-sapiom-*` + * credential headers. Case-insensitive. + */ +export function isSensitiveHeaderName(name: string): boolean { + const lower = name.trim().toLowerCase(); + return ( + SENSITIVE_HEADER_EXACT.has(lower) || + CREDENTIAL_NAME.test(lower) || + SENSITIVE_HEADER_EXTRA.test(lower) || + SENSITIVE_HEADER_PREFIX.test(lower) + ); +} + +/** + * Whether a URL query parameter carries a credential: `key`, `api_key`, + * `apikey`, `token`, `access_token`, `secret`, `signature`, `sig`, + * `password`, `X-Amz-Signature`, … Case-insensitive, on the decoded name. + */ +export function isSensitiveQueryParam(name: string): boolean { + let decoded = name; + try { + decoded = decodeURIComponent(name.replace(/\+/g, " ")); + } catch { + // A malformed escape: match on the raw name. + } + const lower = decoded.trim().toLowerCase(); + return ( + SENSITIVE_QUERY_EXACT.has(lower) || + CREDENTIAL_NAME.test(lower) || + /(?:^|[-_])sig$/.test(lower) + ); +} + +/** + * The headers to report in facts: every header except the sensitive ones, + * values as strings (`String(value)`). Accepts a `Headers`-style entries + * iterable or a plain record. An `undefined` or `null` value is skipped. + * + * @param exclude An extra test for headers to leave out, on top of + * {@link isSensitiveHeaderName}. + */ +export function sanitizeHeadersForFacts( + headers: + | Iterable<[string, unknown]> + | Record + | null + | undefined, + exclude?: (lowerName: string) => boolean, +): Record { + const sanitized: Record = {}; + if (!headers) return sanitized; + const entries: Iterable<[string, unknown]> = + Symbol.iterator in Object(headers) && + typeof (headers as Iterable)[Symbol.iterator] === "function" + ? (headers as Iterable<[string, unknown]>) + : Object.entries(headers as Record); + for (const [key, value] of entries) { + if (value === undefined || value === null) continue; + if (isSensitiveHeaderName(key)) continue; + if (exclude?.(key.toLowerCase())) continue; + sanitized[key] = String(value); + } + return sanitized; +} + +/** + * `url` with credential query-parameter values and `user:pass@` userinfo + * replaced by `[REDACTED]`. Works on an absolute or relative URL or a bare + * query string (`?a=1`, as in `URL.search`); everything else is kept exactly + * as it was. + */ +export function sanitizeUrlForFacts(url: string): string { + const withoutUserinfo = url.replace( + USERINFO, + (_match, scheme: string) => `${scheme}${REDACTED_FACT_VALUE}@`, + ); + const queryStart = withoutUserinfo.indexOf("?"); + if (queryStart === -1) return withoutUserinfo; + const hashStart = withoutUserinfo.indexOf("#", queryStart); + const queryEnd = hashStart === -1 ? withoutUserinfo.length : hashStart; + const query = withoutUserinfo + .slice(queryStart + 1, queryEnd) + .split("&") + .map((pair) => { + const eq = pair.indexOf("="); + if (eq === -1 || eq === pair.length - 1) return pair; + return isSensitiveQueryParam(pair.slice(0, eq)) + ? `${pair.slice(0, eq + 1)}${REDACTED_FACT_VALUE}` + : pair; + }) + .join("&"); + return `${withoutUserinfo.slice(0, queryStart + 1)}${query}${withoutUserinfo.slice(queryEnd)}`; +} diff --git a/packages/fetch/src/http-client.integration.test.ts b/packages/fetch/src/http-client.integration.test.ts index c91abb52c..38e725c3f 100644 --- a/packages/fetch/src/http-client.integration.test.ts +++ b/packages/fetch/src/http-client.integration.test.ts @@ -809,3 +809,67 @@ describe("HTTP Client Integration Tests", () => { }); }); }); + +describe("Facts sanitization", () => { + let mocks: jest.Mocked; + let mockSapiomClient: SapiomClient; + + beforeAll(() => { + fetchMock.mockGlobal(); + }); + + beforeEach(() => { + const setup = createMockSapiomClient(); + mockSapiomClient = setup.client; + mocks = setup.mocks; + fetchMock.removeRoutes(); + fetchMock.clearHistory(); + }); + + afterAll(() => { + fetchMock.unmockGlobal(); + }); + + it("leaves credential headers out of facts and masks credential query values, without changing the request", async () => { + mocks.create.mockResolvedValue({ + id: "tx-facts", + status: TransactionStatus.AUTHORIZED, + } as any); + mocks.complete.mockResolvedValue({ + transaction: { id: "tx-facts", status: "completed" }, + } as any); + fetchMock.get("begin:https://api.example.com/geocode", { + status: 200, + body: { ok: true }, + headers: { "set-cookie": "sid=FAKE", "x-request-id": "r-1" }, + }); + + const fetch = createFetch({ sapiomClient: mockSapiomClient }); + await fetch("https://api.example.com/geocode?key=FAKEKEY&address=Paris", { + headers: { + "bt-api-key": "FAKEBT", + "api-key": "FAKEAPI", + accept: "application/json", + }, + }); + await flushPromises(); + + const request = mocks.create.mock.calls[0][0].requestFacts!.request as any; + expect(request.url).toBe( + "https://api.example.com/geocode?key=[REDACTED]&address=Paris", + ); + expect(request.urlParsed.search).toBe("?key=[REDACTED]&address=Paris"); + expect(request.headers).toEqual({ accept: "application/json" }); + const response = (mocks.complete.mock.calls[0][1].responseFacts as any) + .facts; + expect(response.headers["set-cookie"]).toBeUndefined(); + expect(response.headers["x-request-id"]).toBe("r-1"); + + // The request itself still carries the real URL and headers. + const sent = fetchMock.callHistory.lastCall()!; + expect(sent.url).toBe( + "https://api.example.com/geocode?key=FAKEKEY&address=Paris", + ); + expect(JSON.stringify(sent.options.headers)).toContain("FAKEBT"); + }); +}); diff --git a/packages/fetch/src/interceptors.ts b/packages/fetch/src/interceptors.ts index 1d8b352cd..fe3bcbdce 100644 --- a/packages/fetch/src/interceptors.ts +++ b/packages/fetch/src/interceptors.ts @@ -8,6 +8,8 @@ import { HttpClientRequestFacts, HttpClientResponseFacts, HttpClientErrorFacts, + sanitizeHeadersForFacts, + sanitizeUrlForFacts, } from "@sapiom/core"; import type { FailureMode, TransactionPollingConfig } from "@sapiom/core"; @@ -191,27 +193,15 @@ export async function handleAuthorization( protocol: parsedUrl.protocol.replace(":", ""), hostname: parsedUrl.hostname, pathname: parsedUrl.pathname, - search: parsedUrl.search, + search: sanitizeUrlForFacts(parsedUrl.search), port: parsedUrl.port ? parseInt(parsedUrl.port) : null, }; - const sanitizedHeaders: Record = {}; - const sensitiveHeaders = new Set([ - "authorization", - "cookie", - "x-api-key", - "x-auth-token", - ]); - - for (const [key, value] of request.headers.entries()) { - if (!sensitiveHeaders.has(key.toLowerCase())) { - sanitizedHeaders[key] = value; - } - } + const sanitizedHeaders = sanitizeHeadersForFacts(request.headers.entries()); const requestFacts: HttpClientRequestFacts = { method, - url, + url: sanitizeUrlForFacts(url), urlParsed, headers: sanitizedHeaders, hasBody: request.body !== null, @@ -370,7 +360,10 @@ export async function handlePayment( // If no transaction ID exists (authorization was skipped/failed in failureMode:open), // create one on-demand so we can still handle the 402 payment flow. if (!existingTransactionId) { - const requestMetadata = { ...defaultMetadata, ...((request as any).__sapiom || {}) }; + const requestMetadata = { + ...defaultMetadata, + ...((request as any).__sapiom || {}), + }; const callSite = captureUserCallSite(); const parsedUrl = new URL(request.url); @@ -388,12 +381,12 @@ export async function handlePayment( }), request: { method: request.method.toUpperCase(), - url: request.url, + url: sanitizeUrlForFacts(request.url), urlParsed: { protocol: parsedUrl.protocol.replace(":", ""), hostname: parsedUrl.hostname, pathname: parsedUrl.pathname, - search: parsedUrl.search, + search: sanitizeUrlForFacts(parsedUrl.search), port: parsedUrl.port ? parseInt(parsedUrl.port) : null, }, headers: {}, @@ -422,7 +415,11 @@ export async function handlePayment( // Write the transaction ID back to the original request so // handleCompletion (which reads X-Sapiom-Transaction-Id from // request headers) can complete this on-demand transaction. - setHeader(request.headers, "X-Sapiom-Transaction-Id", existingTransactionId); + setHeader( + request.headers, + "X-Sapiom-Transaction-Id", + existingTransactionId, + ); } catch (error) { if (config.failureMode === "closed") throw error; console.error( @@ -537,19 +534,9 @@ export function handleCompletion( const durationMs = Date.now() - startTime; const isSuccess = response !== null && response.ok; - const sanitizedHeaders: Record = {}; - if (response) { - const sensitiveHeaders = new Set([ - "set-cookie", - "authorization", - "x-api-key", - ]); - for (const [key, value] of response.headers.entries()) { - if (!sensitiveHeaders.has(key.toLowerCase())) { - sanitizedHeaders[key] = value; - } - } - } + const sanitizedHeaders = response + ? sanitizeHeadersForFacts(response.headers.entries()) + : {}; let responseFacts: | { source: string; version: string; facts: Record } diff --git a/packages/node-http/src/http-client.integration.test.ts b/packages/node-http/src/http-client.integration.test.ts index 36c60a812..de0125cf4 100644 --- a/packages/node-http/src/http-client.integration.test.ts +++ b/packages/node-http/src/http-client.integration.test.ts @@ -640,3 +640,55 @@ describe("Node-HTTP Client Integration Tests", () => { }); }); }); + +describe("Facts sanitization", () => { + afterEach(() => { + nock.cleanAll(); + }); + + it("leaves credential headers out of facts and masks credential query values, without changing the request", async () => { + const { client: sapiomClient, mocks } = createMockSapiomClient(); + mocks.create.mockResolvedValue({ + id: "tx-facts", + status: TransactionStatus.AUTHORIZED, + } as any); + mocks.complete.mockResolvedValue({ + transaction: { id: "tx-facts", status: "completed" }, + } as any); + const scope = nock("https://api.example.com", { + reqheaders: { "bt-api-key": "FAKEBT" }, + }) + .get("/geocode") + .query({ key: "FAKEKEY", address: "Paris" }) + .reply( + 200, + { ok: true }, + { "set-cookie": "sid=FAKE", "x-request-id": "r-1" }, + ); + + const client = createClient({ sapiomClient }); + await client.request({ + method: "GET", + url: "https://api.example.com/geocode?key=FAKEKEY&address=Paris", + headers: { + "bt-api-key": "FAKEBT", + "api-key": "FAKEAPI", + accept: "application/json", + }, + }); + await flushPromises(); + + // nock matched the real key and header: the request itself is unchanged. + expect(scope.isDone()).toBe(true); + const request = mocks.create.mock.calls[0][0].requestFacts!.request as any; + expect(request.url).toBe( + "https://api.example.com/geocode?key=[REDACTED]&address=Paris", + ); + expect(request.urlParsed.search).toBe("?key=[REDACTED]&address=Paris"); + expect(request.headers).toEqual({ accept: "application/json" }); + const response = (mocks.complete.mock.calls[0][1].responseFacts as any) + .facts; + expect(response.headers["set-cookie"]).toBeUndefined(); + expect(response.headers["x-request-id"]).toBe("r-1"); + }); +}); diff --git a/packages/node-http/src/interceptors.ts b/packages/node-http/src/interceptors.ts index 3cf168e9d..cf924b248 100644 --- a/packages/node-http/src/interceptors.ts +++ b/packages/node-http/src/interceptors.ts @@ -12,6 +12,8 @@ import { HttpClientResponseFacts, HttpClientErrorFacts, FailureMode, + sanitizeHeadersForFacts, + sanitizeUrlForFacts, } from "@sapiom/core"; import type { TransactionPollingConfig } from "@sapiom/core"; @@ -196,27 +198,17 @@ export async function handleAuthorization( protocol: parsedUrl.protocol.replace(":", ""), hostname: parsedUrl.hostname, pathname: parsedUrl.pathname, - search: parsedUrl.search, + search: sanitizeUrlForFacts(parsedUrl.search), port: parsedUrl.port ? parseInt(parsedUrl.port) : null, }; - const sanitizedHeaders: Record = {}; - const sensitiveHeaders = new Set([ - "authorization", - "cookie", - "x-api-key", - "x-auth-token", - ]); - - for (const [key, value] of Object.entries(request.headers)) { - if (!sensitiveHeaders.has(key.toLowerCase())) { - sanitizedHeaders[key] = value; - } - } + const sanitizedHeaders = sanitizeHeadersForFacts( + Object.entries(request.headers), + ); const requestFacts: HttpClientRequestFacts = { method, - url, + url: sanitizeUrlForFacts(url), urlParsed, headers: sanitizedHeaders, hasBody: !!request.body, @@ -459,19 +451,9 @@ export function handleCompletion( const isSuccess = response !== null && response.status >= 200 && response.status < 300; - const sanitizedHeaders: Record = {}; - if (response?.headers) { - const sensitiveHeaders = new Set([ - "set-cookie", - "authorization", - "x-api-key", - ]); - Object.entries(response.headers).forEach(([key, value]) => { - if (!sensitiveHeaders.has(key.toLowerCase())) { - sanitizedHeaders[key] = String(value); - } - }); - } + const sanitizedHeaders = sanitizeHeadersForFacts( + response?.headers ? Object.entries(response.headers) : undefined, + ); let responseFacts: | { source: string; version: string; facts: Record } From a77dc5591d54bd71f6e05d98d1a1d06da2c4d32a Mon Sep 17 00:00:00 2001 From: Antoine Date: Fri, 13 Nov 2026 23:24:34 +0100 Subject: [PATCH 2/3] fix(core): leave Sapiom-Identity out of facts, mask userinfo with @, keep relative queries out of pathname [SAP-5145] --- .../axios/src/http-client.integration.test.ts | 27 ++++++ packages/axios/src/interceptors.ts | 9 +- packages/core/README.md | 87 +++++++++++-------- .../core/src/utils/facts-sanitization.test.ts | 10 +++ packages/core/src/utils/facts-sanitization.ts | 8 +- 5 files changed, 101 insertions(+), 40 deletions(-) diff --git a/packages/axios/src/http-client.integration.test.ts b/packages/axios/src/http-client.integration.test.ts index b9598fc07..cc6255241 100644 --- a/packages/axios/src/http-client.integration.test.ts +++ b/packages/axios/src/http-client.integration.test.ts @@ -981,6 +981,33 @@ describe("Axios HTTP Client Integration Tests", () => { }); describe("Facts sanitization", () => { + it("keeps a relative URL's query out of urlParsed.pathname when there is no baseURL", async () => { + const axiosInstance = axios.create(); + const mockAxios = new MockAdapter(axiosInstance); + const { client: sapiomClient, mocks } = createMockSapiomClient(); + mocks.create.mockResolvedValue({ + id: "tx-rel", + status: TransactionStatus.AUTHORIZED, + } as any); + mocks.complete.mockResolvedValue({ + transaction: { id: "tx-rel", status: "completed" }, + } as any); + mockAxios.onGet(/\/geocode/).reply(200, { ok: true }); + + const client = withSapiom(axiosInstance, { sapiomClient }); + await client.get("/geocode?key=FAKEKEY&address=Paris#top"); + await flushPromises(); + + const request = mocks.create.mock.calls[0][0].requestFacts!.request as any; + expect(request.urlParsed.pathname).toBe("/geocode"); + expect(request.urlParsed.search).toBe("?key=[REDACTED]&address=Paris"); + expect(JSON.stringify(request)).not.toContain("FAKEKEY"); + expect(mockAxios.history.get[0].url).toBe( + "/geocode?key=FAKEKEY&address=Paris#top", + ); + mockAxios.restore(); + }); + it("leaves credential headers out of facts and masks credential query values, without changing the request", async () => { const axiosInstance = axios.create({ baseURL: "https://api.example.com" }); const mockAxios = new MockAdapter(axiosInstance); diff --git a/packages/axios/src/interceptors.ts b/packages/axios/src/interceptors.ts index 89c3fbd82..8765c72b4 100644 --- a/packages/axios/src/interceptors.ts +++ b/packages/axios/src/interceptors.ts @@ -400,11 +400,16 @@ export function addAuthorizationInterceptor( port: parsed.port ? parseInt(parsed.port) : null, }; } catch { + // A relative endpoint with no baseURL: keep the query out of the pathname. + const queryAt = endpoint.search(/[?#]/); + const pathname = queryAt === -1 ? endpoint : endpoint.slice(0, queryAt); + const query = + queryAt === -1 ? "" : endpoint.slice(queryAt).split("#")[0]; urlParsed = { protocol: "", hostname: "", - pathname: endpoint, - search: "", + pathname, + search: query.startsWith("?") ? sanitizeUrlForFacts(query) : "", port: null, }; } diff --git a/packages/core/README.md b/packages/core/README.md index 9c1a22048..40d4e93b6 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -32,22 +32,22 @@ yarn add @sapiom/core ### Direct API Client ```typescript -import { SapiomClient } from '@sapiom/core'; +import { SapiomClient } from "@sapiom/core"; const client = new SapiomClient({ apiKey: process.env.SAPIOM_API_KEY, - baseURL: 'https://api.sapiom.ai' // optional + baseURL: "https://api.sapiom.ai", // optional }); // Create a transaction const transaction = await client.transactions.create({ - service: 'api', - action: 'call', - resource: 'completion', + service: "api", + action: "call", + resource: "completion", qualifiers: { - model: 'gpt-4', - tokens: 1000 - } + model: "gpt-4", + tokens: 1000, + }, }); // Check transaction status @@ -63,17 +63,20 @@ npm install @sapiom/axios axios ``` ```typescript -import axios from 'axios'; -import { withSapiom } from '@sapiom/axios'; - -const client = withSapiom(axios.create({ - baseURL: 'https://api.example.com' -}), { - apiKey: process.env.SAPIOM_API_KEY -}); +import axios from "axios"; +import { withSapiom } from "@sapiom/axios"; + +const client = withSapiom( + axios.create({ + baseURL: "https://api.example.com", + }), + { + apiKey: process.env.SAPIOM_API_KEY, + }, +); // Automatically handles 402 payment flows -const response = await client.get('/premium-endpoint'); +const response = await client.get("/premium-endpoint"); ``` See [@sapiom/axios](../axios/README.md) for complete documentation. @@ -87,14 +90,14 @@ npm install @sapiom/fetch ``` ```typescript -import { createFetch } from '@sapiom/fetch'; +import { createFetch } from "@sapiom/fetch"; const safeFetch = createFetch({ - apiKey: process.env.SAPIOM_API_KEY + apiKey: process.env.SAPIOM_API_KEY, }); // Drop-in replacement for native fetch -const response = await safeFetch('https://api.example.com/data'); +const response = await safeFetch("https://api.example.com/data"); ``` See [@sapiom/fetch](../fetch/README.md) for complete documentation. @@ -108,15 +111,15 @@ npm install @sapiom/node-http ``` ```typescript -import { createClient } from '@sapiom/node-http'; +import { createClient } from "@sapiom/node-http"; const client = createClient({ - apiKey: process.env.SAPIOM_API_KEY + apiKey: process.env.SAPIOM_API_KEY, }); const response = await client.request({ - method: 'GET', - url: 'https://api.example.com/data' + method: "GET", + url: "https://api.example.com/data", }); ``` @@ -133,6 +136,7 @@ new SapiomClient(config: SapiomClientConfig) ``` **Config options:** + - `apiKey: string` - Required: Your Sapiom API key - `baseURL?: string` - Optional: API base URL (default: https://api.sapiom.ai) - `servicesDomain?: string` - Optional: Services domain for gateway clients (default: services.sapiom.ai) @@ -186,21 +190,21 @@ client.transactions.getPaymentDetails(transaction): PaymentDetails | null ```typescript // Store one secret under an external ref -await client.vault.set('agent-123', 'OPENAI_API_KEY', { - value: 'sk-...' +await client.vault.set("agent-123", "OPENAI_API_KEY", { + value: "sk-...", }); // Read one secret. Missing keys return null. -const openaiKey = await client.vault.get('agent-123', 'OPENAI_API_KEY'); +const openaiKey = await client.vault.get("agent-123", "OPENAI_API_KEY"); // Read a subset of secrets from the same ref -const secrets = await client.vault.getMany('agent-123', [ - 'OPENAI_API_KEY', - 'ANTHROPIC_API_KEY' +const secrets = await client.vault.getMany("agent-123", [ + "OPENAI_API_KEY", + "ANTHROPIC_API_KEY", ]); // Remove one key -await client.vault.deleteKey('agent-123', 'OPENAI_API_KEY'); +await client.vault.deleteKey("agent-123", "OPENAI_API_KEY"); ``` ## HTTP Integrations @@ -231,6 +235,15 @@ All HTTP integrations accept a config object: } ``` +### What request facts contain + +The HTTP integrations report each call's method, URL, headers and status as transaction facts. They never report the credentials the call was made with: + +- Headers left out: `Authorization`, `Proxy-Authorization`, cookies, `Sapiom-Identity`, payment signatures (`payment-signature`, `x-payment`), any name containing `api-key`, `apikey`, `token`, `secret`, `password`, `credential`, `signature` or `auth`, any `*-key`, every `bt-*`, and `x-sapiom-*` key, token and signature headers. +- URL (`url` and `urlParsed.search`): values of credential query parameters (`key`, `api_key`, `apikey`, `token`, `access_token`, `secret`, `signature`, `sig`, `password`, `X-Amz-Signature`, …) and any `user:pass@` are reported as `[REDACTED]`. The rest of the URL is reported as it is. + +Only the facts change; the request goes out with its real URL and headers. The same rules are exported for custom integrations: `isSensitiveHeaderName`, `isSensitiveQueryParam`, `sanitizeHeadersForFacts` and `sanitizeUrlForFacts`. + ### Environment Variables All integrations automatically read from environment: @@ -261,7 +274,11 @@ try { ### Custom HTTP Adapter ```typescript -import type { HttpClientAdapter, HttpRequest, HttpResponse } from '@sapiom/core'; +import type { + HttpClientAdapter, + HttpRequest, + HttpResponse, +} from "@sapiom/core"; class MyCustomAdapter implements HttpClientAdapter { async request(config: HttpRequest): Promise { @@ -273,11 +290,11 @@ class MyCustomAdapter implements HttpClientAdapter { ### Payment Error Detection ```typescript -import { isPaymentRequiredError, extractX402Response } from '@sapiom/core'; +import { isPaymentRequiredError, extractX402Response } from "@sapiom/core"; if (isPaymentRequiredError(error)) { const x402Response = extractX402Response(error); - console.log('Payment required:', x402Response); + console.log("Payment required:", x402Response); } ``` @@ -292,7 +309,7 @@ import type { HttpResponse, X402Response, X402PaymentRequirement, -} from '@sapiom/core'; +} from "@sapiom/core"; ``` ## License diff --git a/packages/core/src/utils/facts-sanitization.test.ts b/packages/core/src/utils/facts-sanitization.test.ts index 01b2f2f37..c516325e5 100644 --- a/packages/core/src/utils/facts-sanitization.test.ts +++ b/packages/core/src/utils/facts-sanitization.test.ts @@ -30,6 +30,7 @@ describe("facts sanitization", () => { "x-sapiom-service-key", "x-sapiom-signature", "x-sapiom-workflow-token", + "Sapiom-Identity", ])("leaves out %s", (name) => { expect(isSensitiveHeaderName(name)).toBe(true); }); @@ -89,6 +90,15 @@ describe("facts sanitization", () => { ).toBe(`https://${REDACTED_FACT_VALUE}@api.example.com/x`); }); + it("masks a password that itself contains @, and not an @ in the query", () => { + expect( + sanitizeUrlForFacts("https://alice:p@ss@api.example.com/x?q=a@b"), + ).toBe(`https://${REDACTED_FACT_VALUE}@api.example.com/x?q=a@b`); + expect(sanitizeUrlForFacts("https://api.example.com/x?q=a@b")).toBe( + "https://api.example.com/x?q=a@b", + ); + }); + it("works on a bare search string", () => { expect(sanitizeUrlForFacts("?token=abc&q=1")).toBe( `?token=${REDACTED_FACT_VALUE}&q=1`, diff --git a/packages/core/src/utils/facts-sanitization.ts b/packages/core/src/utils/facts-sanitization.ts index 8f2895a1a..75211fd93 100644 --- a/packages/core/src/utils/facts-sanitization.ts +++ b/packages/core/src/utils/facts-sanitization.ts @@ -21,6 +21,7 @@ const SENSITIVE_HEADER_EXACT = new Set([ "payment-signature", "x-payment", "x-payment-response", + "sapiom-identity", ]); /** A name that names a credential: `x-api-key`, `bt-api-key`, `client_secret`, … */ @@ -37,13 +38,14 @@ const SENSITIVE_HEADER_PREFIX = /** Query parameters whose value is a credential (matched case-insensitively). */ const SENSITIVE_QUERY_EXACT = new Set(["key", "sig", "auth", "pwd", "pass"]); -const USERINFO = /^([a-z][a-z0-9+.-]*:\/\/)([^/?#@\s]+)@/i; +// Greedy up to the last `@` before the path, query or fragment: a password may itself contain `@`. +const USERINFO = /^([a-z][a-z0-9+.-]*:\/\/)([^/?#\s]*)@/i; /** * Whether a header must be left out of facts: `Authorization`, cookies, * API-key, token, secret and password headers (`x-api-key`, `bt-api-key`, - * `api-key`, `x-auth-token`, …), payment signatures, and `x-sapiom-*` - * credential headers. Case-insensitive. + * `api-key`, `x-auth-token`, …), payment signatures, the `Sapiom-Identity` + * token, and `x-sapiom-*` credential headers. Case-insensitive. */ export function isSensitiveHeaderName(name: string): boolean { const lower = name.trim().toLowerCase(); From aaa3e41f193868fd5d0abb0561136ce53d4cbed3 Mon Sep 17 00:00:00 2001 From: Antoine Date: Fri, 13 Nov 2026 23:41:30 +0100 Subject: [PATCH 3/3] docs(core): keep the README change to the request-facts section [SAP-5145] --- packages/core/README.md | 78 ++++++++++++++---------------- packages/fetch/src/interceptors.ts | 11 +---- 2 files changed, 37 insertions(+), 52 deletions(-) diff --git a/packages/core/README.md b/packages/core/README.md index 40d4e93b6..dc2ca7d25 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -32,22 +32,22 @@ yarn add @sapiom/core ### Direct API Client ```typescript -import { SapiomClient } from "@sapiom/core"; +import { SapiomClient } from '@sapiom/core'; const client = new SapiomClient({ apiKey: process.env.SAPIOM_API_KEY, - baseURL: "https://api.sapiom.ai", // optional + baseURL: 'https://api.sapiom.ai' // optional }); // Create a transaction const transaction = await client.transactions.create({ - service: "api", - action: "call", - resource: "completion", + service: 'api', + action: 'call', + resource: 'completion', qualifiers: { - model: "gpt-4", - tokens: 1000, - }, + model: 'gpt-4', + tokens: 1000 + } }); // Check transaction status @@ -63,20 +63,17 @@ npm install @sapiom/axios axios ``` ```typescript -import axios from "axios"; -import { withSapiom } from "@sapiom/axios"; - -const client = withSapiom( - axios.create({ - baseURL: "https://api.example.com", - }), - { - apiKey: process.env.SAPIOM_API_KEY, - }, -); +import axios from 'axios'; +import { withSapiom } from '@sapiom/axios'; + +const client = withSapiom(axios.create({ + baseURL: 'https://api.example.com' +}), { + apiKey: process.env.SAPIOM_API_KEY +}); // Automatically handles 402 payment flows -const response = await client.get("/premium-endpoint"); +const response = await client.get('/premium-endpoint'); ``` See [@sapiom/axios](../axios/README.md) for complete documentation. @@ -90,14 +87,14 @@ npm install @sapiom/fetch ``` ```typescript -import { createFetch } from "@sapiom/fetch"; +import { createFetch } from '@sapiom/fetch'; const safeFetch = createFetch({ - apiKey: process.env.SAPIOM_API_KEY, + apiKey: process.env.SAPIOM_API_KEY }); // Drop-in replacement for native fetch -const response = await safeFetch("https://api.example.com/data"); +const response = await safeFetch('https://api.example.com/data'); ``` See [@sapiom/fetch](../fetch/README.md) for complete documentation. @@ -111,15 +108,15 @@ npm install @sapiom/node-http ``` ```typescript -import { createClient } from "@sapiom/node-http"; +import { createClient } from '@sapiom/node-http'; const client = createClient({ - apiKey: process.env.SAPIOM_API_KEY, + apiKey: process.env.SAPIOM_API_KEY }); const response = await client.request({ - method: "GET", - url: "https://api.example.com/data", + method: 'GET', + url: 'https://api.example.com/data' }); ``` @@ -136,7 +133,6 @@ new SapiomClient(config: SapiomClientConfig) ``` **Config options:** - - `apiKey: string` - Required: Your Sapiom API key - `baseURL?: string` - Optional: API base URL (default: https://api.sapiom.ai) - `servicesDomain?: string` - Optional: Services domain for gateway clients (default: services.sapiom.ai) @@ -190,21 +186,21 @@ client.transactions.getPaymentDetails(transaction): PaymentDetails | null ```typescript // Store one secret under an external ref -await client.vault.set("agent-123", "OPENAI_API_KEY", { - value: "sk-...", +await client.vault.set('agent-123', 'OPENAI_API_KEY', { + value: 'sk-...' }); // Read one secret. Missing keys return null. -const openaiKey = await client.vault.get("agent-123", "OPENAI_API_KEY"); +const openaiKey = await client.vault.get('agent-123', 'OPENAI_API_KEY'); // Read a subset of secrets from the same ref -const secrets = await client.vault.getMany("agent-123", [ - "OPENAI_API_KEY", - "ANTHROPIC_API_KEY", +const secrets = await client.vault.getMany('agent-123', [ + 'OPENAI_API_KEY', + 'ANTHROPIC_API_KEY' ]); // Remove one key -await client.vault.deleteKey("agent-123", "OPENAI_API_KEY"); +await client.vault.deleteKey('agent-123', 'OPENAI_API_KEY'); ``` ## HTTP Integrations @@ -274,11 +270,7 @@ try { ### Custom HTTP Adapter ```typescript -import type { - HttpClientAdapter, - HttpRequest, - HttpResponse, -} from "@sapiom/core"; +import type { HttpClientAdapter, HttpRequest, HttpResponse } from '@sapiom/core'; class MyCustomAdapter implements HttpClientAdapter { async request(config: HttpRequest): Promise { @@ -290,11 +282,11 @@ class MyCustomAdapter implements HttpClientAdapter { ### Payment Error Detection ```typescript -import { isPaymentRequiredError, extractX402Response } from "@sapiom/core"; +import { isPaymentRequiredError, extractX402Response } from '@sapiom/core'; if (isPaymentRequiredError(error)) { const x402Response = extractX402Response(error); - console.log("Payment required:", x402Response); + console.log('Payment required:', x402Response); } ``` @@ -309,7 +301,7 @@ import type { HttpResponse, X402Response, X402PaymentRequirement, -} from "@sapiom/core"; +} from '@sapiom/core'; ``` ## License diff --git a/packages/fetch/src/interceptors.ts b/packages/fetch/src/interceptors.ts index fe3bcbdce..f9a5b39a4 100644 --- a/packages/fetch/src/interceptors.ts +++ b/packages/fetch/src/interceptors.ts @@ -360,10 +360,7 @@ export async function handlePayment( // If no transaction ID exists (authorization was skipped/failed in failureMode:open), // create one on-demand so we can still handle the 402 payment flow. if (!existingTransactionId) { - const requestMetadata = { - ...defaultMetadata, - ...((request as any).__sapiom || {}), - }; + const requestMetadata = { ...defaultMetadata, ...((request as any).__sapiom || {}) }; const callSite = captureUserCallSite(); const parsedUrl = new URL(request.url); @@ -415,11 +412,7 @@ export async function handlePayment( // Write the transaction ID back to the original request so // handleCompletion (which reads X-Sapiom-Transaction-Id from // request headers) can complete this on-demand transaction. - setHeader( - request.headers, - "X-Sapiom-Transaction-Id", - existingTransactionId, - ); + setHeader(request.headers, "X-Sapiom-Transaction-Id", existingTransactionId); } catch (error) { if (config.failureMode === "closed") throw error; console.error(