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, + ); + }); +}); diff --git a/tests/integration/test_scim_person_live_ch.py b/tests/integration/test_scim_person_live_ch.py index 34818825b7..a3eeafaa1b 100644 --- a/tests/integration/test_scim_person_live_ch.py +++ b/tests/integration/test_scim_person_live_ch.py @@ -125,13 +125,17 @@ async def people(monkeypatch: pytest.MonkeyPatch) -> AsyncIterator[People]: query_all, query_one = client.query_all, client.query_one async def all_rows(sql: str, params: dict[str, Any] | None = None, **kwargs: Any) -> Any: + observing_person = ch.current_query_tag() == "auth.scim_people" answer = await query_all(sql, params=params, **kwargs) - made.results.append((sql, ch.statement_settings(sql), answer)) + if observing_person: + made.results.append((sql, ch.statement_settings(sql), answer)) return answer async def one_row(sql: str, params: dict[str, Any] | None = None, **kwargs: Any) -> Any: + observing_person = ch.current_query_tag() == "auth.scim_people" answer = await query_one(sql, params=params, **kwargs) - made.results.append((sql, ch.statement_settings(sql), answer)) + if observing_person: + made.results.append((sql, ch.statement_settings(sql), answer)) return answer monkeypatch.setattr(client, "query_all", all_rows) diff --git a/tests/unit/test_scim_person_query_observation.py b/tests/unit/test_scim_person_query_observation.py new file mode 100644 index 0000000000..a0f9ef7f06 --- /dev/null +++ b/tests/unit/test_scim_person_query_observation.py @@ -0,0 +1,116 @@ +"""Person-query evidence excludes reads from independent background tasks.""" + +from __future__ import annotations + +import asyncio +from contextvars import Context +from typing import Any + +import pytest + +from server.auth import scim_people +from server.core import ch, rmt_carry +from server.settings import settings +from tests.integration.test_scim_person_live_ch import people as person_fixture +from tests.unit.test_ch_client_hygiene import _client, _FakeAsync + + +class Queries: + def __init__(self) -> None: + self.started = asyncio.Event() + self.background_done = asyncio.Event() + self.block_person = False + self.transport: list[tuple[str, dict[str, Any]]] = [] + + async def connect(self) -> None: + pass + + async def disconnect(self) -> None: + pass + + async def _read(self, sql: str) -> dict[str, Any]: + self.transport.append((sql, ch.statement_settings(sql, cls="read"))) + if sql == "SELECT 1 AS person" and self.block_person: + self.started.set() + await self.background_done.wait() + return {"n": 0, "at": None, "altered": None} + + async def query_one(self, sql: str, params: Any = None) -> dict[str, Any]: + return await self._read(sql) + + async def query_all(self, sql: str, params: Any = None) -> list[dict[str, Any]]: + return [await self._read(sql)] + + +@pytest.fixture +async def recording(monkeypatch): + client = Queries() + monkeypatch.setattr(ch, "get_client", lambda: client) + stream = person_fixture.__wrapped__(monkeypatch) + observed = await anext(stream) + try: + yield observed, client + finally: + await stream.aclose() + + +@pytest.mark.parametrize("read_timeout", [0, 2.5]) +@pytest.mark.parametrize("many", [False, True]) +async def test_background_schema_reads_do_not_enter_person_evidence( + recording, monkeypatch, read_timeout, many +): + observed, client = recording + monkeypatch.setattr(settings, "ch_timeout_read_s", read_timeout) + client.block_person = True + + async def background(): + await client.started.wait() + try: + with ch.query_tag("rmt_carry.columns"): + await rmt_carry._schema_stamp(client) + finally: + client.background_done.set() + + watcher = asyncio.create_task(background(), context=Context()) + try: + with ch.statement_timeout(1.75), ch.query_tag("auth.scim_people"): + query = client.query_all if many else client.query_one + await query("SELECT 1 AS person") + await watcher + finally: + if not watcher.done(): + watcher.cancel() + await asyncio.gather(watcher, return_exceptions=True) + + assert len(client.transport) == 2 + assert any("system.tables" in sql for sql, _ in client.transport) + assert [sql for sql, _, _ in observed.results] == ["SELECT 1 AS person"] + assert 0 < observed.results[0][1]["max_execution_time"] <= 1.75 + + +@pytest.mark.parametrize("many", [False, True]) +async def test_unbounded_person_reads_remain_visible(recording, monkeypatch, many): + observed, client = recording + monkeypatch.setattr(settings, "ch_timeout_read_s", 0) + with ch.query_tag("auth.scim_people"): + query = client.query_all if many else client.query_one + await query("SELECT 1 AS person") + assert len(observed.results) == 1 + with pytest.raises(KeyError, match="max_execution_time"): + assert 0 < observed.results[0][1]["max_execution_time"] <= 1.75 + + +@pytest.mark.parametrize("read_timeout", [0, 2.5]) +@pytest.mark.parametrize("many", [False, True]) +async def test_actual_person_reader_applies_its_finite_budget_to_driver( + monkeypatch, read_timeout, many +): + driver = _FakeAsync() + client = _client(monkeypatch, driver, ch_timeout_read_s=read_timeout) + monkeypatch.setattr(ch, "get_client", lambda: client) + decision = scim_people._Decision("org", "owner", "owner@example.test", scim_people._now() + 10) + with ch.statement_timeout(1.75), ch.query_tag("auth.scim_people"): + await decision.query("SELECT 1 AS person", {}, many=many) + calls = [applied for kind, sql, applied in driver.calls if sql == "SELECT 1 AS person"] + assert len(calls) == 1 + assert 0 < calls[0]["max_execution_time"] <= 1.75