diff --git a/docs/architecture/security.md b/docs/architecture/security.md index 14d2b5cd24..3525c63b36 100644 --- a/docs/architecture/security.md +++ b/docs/architecture/security.md @@ -1616,6 +1616,11 @@ Task inbox webhooks and memory webhooks share one sender (`server/core/webhooks. `sha256:/`, not text (`server/observability/event_args.py`). - **Errors.** A 500 carries only the request id, never exception text. - **Repository.** `make lint` runs `scripts/gates/check_no_secrets.py` over tracked files. +- **SDK boundaries.** Bounded [transport property tests](../development/testing.md#sdk-transport-properties) + generate origin variants, credential-header casing and request IDs. They assert that a refused + origin reads no provider token and sends nothing, requests carry one selected credential, + inspection and logs omit that credential, and request IDs fit the wire header boundary. + The property-testing dependency runs only in the development suite, through mocked requests. ## Invariants diff --git a/docs/development/testing.md b/docs/development/testing.md index d1c4729681..718779a618 100644 --- a/docs/development/testing.md +++ b/docs/development/testing.md @@ -49,6 +49,22 @@ Keep CI's system tools beside the locked Python environment. Release-script test example, call `jq`. Record missing tools or an unsupported platform separately from a failure introduced by the diff. +### SDK transport properties + +`sdk/typescript/src/transport.property.test.ts` uses `fast-check` to exercise the transport's +origin binding, credential handling and request-ID header boundary through public requests. +The suite uses 100 generated trials per property, bounds generated strings and uses mocked +fetch and token providers. Failures additionally run shrinking and replay evaluations over +those bounded inputs. It needs no server, live credential or network access. Run it with: + +```bash +npm --prefix sdk/typescript test -- src/transport.property.test.ts +``` + +The default seed is fixed for reproducible CI. Set `LOOM_FUZZ_SEED` to explore another seed. +On a failure, copy the reported seed and shrink path into `LOOM_FUZZ_SEED` and `LOOM_FUZZ_PATH`, +then select that property with Vitest's `-t` option to replay its counterexample. + ## Integration tests The integration suite runs against a live server, the way CI's `integration` job does: diff --git a/sdk/typescript/package-lock.json b/sdk/typescript/package-lock.json index 24551acdf3..a987e9aa06 100644 --- a/sdk/typescript/package-lock.json +++ b/sdk/typescript/package-lock.json @@ -19,6 +19,7 @@ "@openai/agents": "0.22.0", "@types/node": "^22.0.0", "ai": "7.0.172", + "fast-check": "4.10.2", "publint": "^0.3.24", "tsdown": "^0.23.0", "typedoc": "^0.28.20", @@ -4074,6 +4075,29 @@ "dev": true, "license": "MIT" }, + "node_modules/fast-check": { + "version": "4.10.2", + "resolved": "https://registry.npmjs.org/fast-check/-/fast-check-4.10.2.tgz", + "integrity": "sha512-iK2f+YrcmoeGqk6fA0ea2bptcu/itMIm4NfEozq6N25+aG6h7s5HZbB/k1aV7b5w5sFLMCbbtRUsTVR+BgC3xw==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://github.com/sponsors/dubzzz" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fast-check" + } + ], + "license": "MIT", + "dependencies": { + "pure-rand": "^8.0.0" + }, + "engines": { + "node": ">=12.17.0" + } + }, "node_modules/fast-sha256": { "version": "1.3.0", "resolved": "https://registry.npmjs.org/fast-sha256/-/fast-sha256-1.3.0.tgz", @@ -6868,6 +6892,23 @@ "node": ">=6" } }, + "node_modules/pure-rand": { + "version": "8.4.2", + "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-8.4.2.tgz", + "integrity": "sha512-vvuOGgcuPJAirlHvuQw1TrOiw7ptaIXXmIbNuiNOY6lNGJJH49PQ1Kj4nd783nPdQhQdicgOjVI2yI/9BD6/Ng==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://github.com/sponsors/dubzzz" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fast-check" + } + ], + "license": "MIT" + }, "node_modules/quansync": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/quansync/-/quansync-1.0.0.tgz", diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json index 1cf5bc85aa..9f8a0a9fd9 100644 --- a/sdk/typescript/package.json +++ b/sdk/typescript/package.json @@ -183,6 +183,7 @@ "@openai/agents": "0.22.0", "@types/node": "^22.0.0", "ai": "7.0.172", + "fast-check": "4.10.2", "publint": "^0.3.24", "tsdown": "^0.23.0", "typedoc": "^0.28.20", diff --git a/sdk/typescript/src/transport.property.test.ts b/sdk/typescript/src/transport.property.test.ts new file mode 100644 index 0000000000..9516b3e38f --- /dev/null +++ b/sdk/typescript/src/transport.property.test.ts @@ -0,0 +1,171 @@ +import { inspect } from "node:util"; +import fc from "fast-check"; +import { describe, expect, it } from "vitest"; +import { AuthError } from "./errors.js"; +import { type FetchLike, Transport } from "./transport.js"; + +const parameters = { + numRuns: 100, + seed: Number(process.env.LOOM_FUZZ_SEED ?? 0x6c6f6f6d), + path: process.env.LOOM_FUZZ_PATH, +}; + +const token = fc + .array(fc.constantFrom(..."abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-"), { maxLength: 48 }) + .map((letters) => `credential-${letters.join("")}-fixture`); + +const baseUrl = fc + .record({ + scheme: fc.constantFrom("http", "https"), + host: fc.constantFrom("LOOM.TEST", "loom.test", "xn--bcher-kva.test", "127.0.0.1", "[::1]"), + port: fc.constantFrom("", ":80", ":443", ":7777"), + path: fc.array(fc.constantFrom("api", "%2f", "%5c", "\u2603"), { maxLength: 4 }), + }) + .map(({ scheme, host, port, path }) => `${scheme}://${host}${port}/${path.join("/")}`); + +function recorder() { + const calls: Array<{ url: string; headers: Record }> = []; + const fetch: FetchLike = async (url, init) => { + calls.push({ url, headers: { ...(init.headers as Record) } }); + return new Response("{}", { status: 200 }); + }; + return { calls, fetch }; +} + +function capturedLogger() { + const logs: string[] = []; + const log = (...values: unknown[]) => { + logs.push(inspect(values, { depth: null, customInspect: false })); + }; + return { logs, logger: { debug: log, info: log, warn: log, error: log } }; +} + +function expectPrivateOutput(outputs: string[], secret: string) { + for (const output of outputs) expect(output).not.toContain(secret); +} + +describe("Transport properties", () => { + it("detects nested log credentials before the supplied object is changed", () => { + const { logs, logger } = capturedLogger(); + const secret = "credential-leak-control-fixture"; + const headers = { Authorization: `Bearer ${secret}` }; + logger.debug("request", { context: { headers } }); + headers.Authorization = "redacted-later"; + + expect(logs).toHaveLength(1); + expect(logs[0]).not.toContain("redacted-later"); + expect(() => expectPrivateOutput(logs, secret)).toThrow(); + }); + + it("binds provider tokens to the canonical server origin before reading them", async () => { + await fc.assert( + fc.asyncProperty( + baseUrl, + token, + fc.constantFrom("protocol", "hostname", "port"), + async (url, secret, changed) => { + const origin = new URL(url).origin; + const other = new URL(origin); + if (changed === "protocol") other.protocol = other.protocol === "http:" ? "https:" : "http:"; + else if (changed === "hostname") other.hostname = "other.loom.test"; + else other.port = other.port === "444" ? "445" : "444"; + expect(other.origin).not.toBe(origin); + + for (const allowed of [true, false]) { + const { calls, fetch } = recorder(); + let reads = 0; + const transport = new Transport({ + baseUrl: url, + tokenProvider: { + origin: allowed ? origin : other.origin, + token: () => { + reads++; + return secret; + }, + }, + fetch, + retry: { maxAttempts: 1 }, + logLevel: "off", + }); + if (allowed) { + await expect(transport.post("memory.get", {})).resolves.toEqual({}); + expect(reads).toBe(1); + expect(calls).toHaveLength(1); + expect(new URL(calls[0].url).origin).toBe(origin); + expect(calls[0].headers.Authorization).toBe(`Bearer ${secret}`); + } else { + await expect(transport.post("memory.get", {})).rejects.toBeInstanceOf(AuthError); + expect(reads).toBe(0); + expect(calls).toHaveLength(0); + } + } + }, + ), + parameters, + ); + }); + + it("sends one selected credential while inspection and logs keep it private", async () => { + const authorization = fc + .array(fc.boolean(), { minLength: 13, maxLength: 13 }) + .map((upper) => Array.from("authorization", (letter, i) => (upper[i] ? letter.toUpperCase() : letter)).join("")); + await fc.assert( + fc.asyncProperty(token, authorization, async (secret, header) => { + const { calls, fetch } = recorder(); + const { logs, logger } = capturedLogger(); + const transport = new Transport({ + baseUrl: "https://loom.test", + apiKey: ` ${secret} `, + headers: { Authorization: "caller-supplied", [header]: "caller-supplied" }, + fetch, + retry: { maxAttempts: 1 }, + logger, + logLevel: "debug", + }); + await transport.post("memory.get", {}); + expect(calls).toHaveLength(1); + const credentials = Object.entries(calls[0].headers).filter(([name]) => name.toLowerCase() === "authorization"); + expect(credentials).toEqual([["Authorization", `Bearer ${secret}`]]); + const outputs = [JSON.stringify(transport), inspect(transport), ...logs]; + expectPrivateOutput(outputs, secret); + expectPrivateOutput(outputs, "caller-supplied"); + }), + parameters, + ); + }); + + it("keeps request IDs within the wire header boundary", async () => { + const validId = fc + .array(fc.constantFrom(..."abcABC012._-"), { minLength: 1, maxLength: 64 }) + .map((parts) => parts.join("")); + const requestId = fc.oneof( + fc.string({ maxLength: 256 }), + validId, + fc.tuple(validId, fc.constantFrom("\r", "\n", "\u2028", "\u2029")).map(([id, ending]) => id + ending), + fc.array(fc.integer({ min: 0, max: 0x10ffff }), { maxLength: 48 }).map((parts) => String.fromCodePoint(...parts)), + fc.constantFrom("", "\r", "\n", "\u0000", "x".repeat(65)), + ); + await fc.assert( + fc.asyncProperty(requestId, async (supplied) => { + const { calls, fetch } = recorder(); + const transport = new Transport({ + baseUrl: "https://loom.test", + fetch, + retry: { maxAttempts: 1 }, + logLevel: "off", + }); + await transport.post("memory.get", {}, { requestId: supplied }); + expect(calls).toHaveLength(1); + const sent = calls[0].headers["X-Request-Id"]; + expect(sent.length).toBeGreaterThan(0); + expect(sent.length).toBeLessThanOrEqual(64); + expect(sent).not.toMatch(/[^A-Za-z0-9._-]/); + expect(new Headers(calls[0].headers).get("X-Request-Id")).toBe(sent); + if (supplied.length > 0 && supplied.length <= 64 && !/[^A-Za-z0-9._-]/.test(supplied)) + expect(sent).toBe(supplied); + else expect(sent).not.toBe(supplied); + }), + parameters, + ); + }); +});