@nanobpm/urban 0.70.0 → 0.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.70.0",
+	"version": "0.71.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/context/README.md

@@ -58,3 +58,47 @@ barrel.
 - `npm run test:conformance --workspace @nanobpm/urban` runs the conformance
   corpus.
 - `npm run check:pii --workspace @nanobpm/urban` runs the PII gate.
+
+## PII: no-PII by construction, and the immutability-vs-erasure boundary
+
+The MVP substrate is **no-PII by construction**. Nothing here stores personal
+data, and two independent nets keep it that way:
+
+1. **In-process, at write time (S6-core + S3).** `@nanobpm/urban/context/pii`
+   ships a pure classifier (`classifyPii`) and a mandatory, default-DENY
+   pre-commit guard (`preCommitPiiGuard`). S3's `ContextWriter` registers that
+   guard as a **non-optional** pre-commit step on **every** write path
+   (`PreCommitGuardRegistry`, seeded non-removably), so a record carrying PII is
+   rejected **before any commit** — a caller cannot opt out.
+
+2. **Build-time, in CI (this slice, s6-pii-ci).** `npm run check:pii` walks the
+   S3 record layout (`records/<scope>/<scopeRef-bucket>/<id>.json`, where
+   `<scopeRef-bucket>` is the sanitised `scopeRef` or the shared `_` bucket when a
+   record carries no `scopeRef` — see `recordRelativePath`) and re-classifies
+   every record with the **same** `classifyPii`, failing the build on any violation.
+   The `.github/workflows/urban-context-pii.yml` workflow runs it (plus
+   build/typecheck/test) as a second line of defence in case content reaches a
+   git-backed context by some path other than the writer.
+
+### Why the guard, not erasure
+
+The substrate is an **append-only git history**. "Deleting" a record is just
+another commit that removes the file from the *tip*; every prior value remains
+in the reachable history (and in every clone, fork, and reflog). On this
+substrate there is **no true erasure** — you cannot unpublish a fact that was
+ever committed short of a history rewrite that every consumer must also adopt.
+Because real erasure is not achievable append-only, the only sound MVP policy is
+to **never admit PII in the first place** — hence the by-construction guard + CI
+net above rather than an after-the-fact delete.
+
+### The seam left for a future PII/mutable backend
+
+Real erasure (GDPR-style "right to be forgotten", tombstoning, crypto-shredding)
+requires a **mutable** substrate that can genuinely destroy a value, not merely
+append over it. The write path is already abstracted over the substrate
+(`WriteSubstrate` / `GitWriteSubstrate` in `@nanobpm/urban/context/git`) and the
+binding layer does not assume "public git only", so a future opt-in
+PII/mutable backend can slot in behind that seam and offer erasure semantics
+**without** touching the record schema, the layout, or this guard. That backend
+is intentionally **not built** in the MVP — only its seam is documented here, and
+the deferred implementation is tracked in nano-ide#393.

package/src/context/pii/check-pii.test.ts

@@ -0,0 +1,196 @@
+// Slice s6-pii-ci — tests for the build-time PII gate (`scripts/check-pii.ts`).
+//
+// These seed records into the SAME S3 path/namespace layout the writer uses
+// (`recordRelativePath`), then run the real check-pii.ts script against a local
+// temp substrate and assert its exit code: non-zero on a seeded PII violation,
+// zero on clean content. Nothing touches the network.
+
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { after, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { recordRelativePath } from "../git/index.ts";
+import type { MemoryRecord } from "../schema/index.ts";
+
+const execFileAsync = promisify(execFile);
+const HERE = dirname(fileURLToPath(import.meta.url));
+// packages/urban/src/context/pii → packages/urban/scripts/check-pii.ts
+const CHECK_PII = join(HERE, "..", "..", "..", "scripts", "check-pii.ts");
+const TEMP_ROOTS: string[] = [];
+
+after(async () => {
+  await Promise.all(TEMP_ROOTS.map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+function record(overrides: Partial<MemoryRecord>): MemoryRecord {
+  const base: MemoryRecord = {
+    schemaVersion: 1,
+    id: "rec-1",
+    scope: "epic",
+    scopeRef: "issue-303",
+    mode: "empirical",
+    provenance: "measured",
+    authority: "authoritative",
+    statement: "the measured throughput was 42 rps",
+    createdAt: "2026-01-01T00:00:00Z",
+  };
+  return { ...base, ...overrides };
+}
+
+/** Write a record into a substrate root at its canonical S3 layout path. */
+async function seed(root: string, rec: MemoryRecord): Promise<void> {
+  const rel = recordRelativePath(rec);
+  const abs = join(root, rel);
+  await mkdir(dirname(abs), { recursive: true });
+  await writeFile(abs, `${JSON.stringify(rec, null, 2)}\n`, "utf8");
+}
+
+/** Write raw file content into a substrate root at a record's canonical path. */
+async function seedRaw(root: string, rec: MemoryRecord, content: string): Promise<void> {
+  const rel = recordRelativePath(rec);
+  const abs = join(root, rel);
+  await mkdir(dirname(abs), { recursive: true });
+  await writeFile(abs, content, "utf8");
+}
+
+async function makeRoot(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "s6ci-substrate-"));
+  TEMP_ROOTS.push(dir);
+  return dir;
+}
+
+/** Run check-pii.ts against a root; resolve with its exit code + stderr. */
+async function runCheck(root: string): Promise<{ code: number; stderr: string; stdout: string }> {
+  try {
+    const { stdout, stderr } = await execFileAsync(
+      process.execPath,
+      ["--experimental-strip-types", CHECK_PII, root],
+      { cwd: root },
+    );
+    return { code: 0, stdout, stderr };
+  } catch (error) {
+    return {
+      code: numberProp(error, "code") ?? 1,
+      stdout: stringProp(error, "stdout"),
+      stderr: stringProp(error, "stderr"),
+    };
+  }
+}
+
+function numberProp(error: unknown, key: string): number | undefined {
+  const value =
+    typeof error === "object" && error !== null ? Reflect.get(error, key) : undefined;
+  return typeof value === "number" ? value : undefined;
+}
+
+function stringProp(error: unknown, key: string): string {
+  const value =
+    typeof error === "object" && error !== null ? Reflect.get(error, key) : undefined;
+  return typeof value === "string" ? value : "";
+}
+
+test("check:pii passes (exit 0) on clean records in the S3 layout", async () => {
+  const root = await makeRoot();
+  await seed(root, record({ id: "clean-a" }));
+  await seed(
+    root,
+    record({ id: "clean-b", scope: "repo", scopeRef: undefined, statement: "latency held at 42ms" }),
+  );
+
+  const { code, stdout } = await runCheck(root);
+  assert.equal(code, 0, `expected clean content to pass; stdout=${stdout}`);
+  assert.match(stdout, /no PII detected/);
+});
+
+test("check:pii fails (non-zero) on a seeded PII violation in the S3 layout", async () => {
+  const root = await makeRoot();
+  await seed(root, record({ id: "clean-a" }));
+  // A record whose statement carries an email address — a PII violation.
+  await seed(
+    root,
+    record({ id: "leaky", statement: "reported by alice.example@contoso.com during the run" }),
+  );
+
+  const { code, stderr } = await runCheck(root);
+  assert.equal(code, 1, "expected a seeded PII violation to fail the build");
+  assert.match(stderr, /PII detected/);
+  assert.match(stderr, /email/);
+  // The gate must NOT re-leak the raw PII it caught (length-only redaction).
+  assert.doesNotMatch(stderr, /alice\.example@contoso\.com/);
+});
+
+test("check:pii catches PII in a JSON array record (arrays are not plain objects)", async () => {
+  const root = await makeRoot();
+  // A record file whose top-level JSON value is an array carrying an email
+  // address. Arrays must NOT be narrowed as plain objects — they fall through
+  // to the raw-text scan, so the leak is still caught.
+  await seedRaw(
+    root,
+    record({ id: "arr-leak" }),
+    `${JSON.stringify(["contact alice.example@contoso.com for details"], null, 2)}\n`,
+  );
+
+  const { code, stderr } = await runCheck(root);
+  assert.equal(code, 1, "expected a PII violation inside a JSON array record to fail the build");
+  assert.match(stderr, /PII detected/);
+  assert.match(stderr, /email/);
+  assert.doesNotMatch(stderr, /alice\.example@contoso\.com/);
+});
+
+test("check:pii is a no-op (exit 0) on a root with no records/ layout", async () => {
+  const root = await makeRoot();
+  const { code, stdout } = await runCheck(root);
+  assert.equal(code, 0);
+  assert.match(stdout, /0 record\(s\) scanned/);
+});
+
+test("check:pii does not follow a symlink record into a target outside the root", async () => {
+  const root = await makeRoot();
+  // A secret file OUTSIDE the substrate root (e.g. a CI secret the scanner
+  // should never touch), carrying an email address.
+  const secret = join(await makeRoot(), "ci-secret.txt");
+  await writeFile(secret, "token owner: alice.example@contoso.com\n", "utf8");
+  // A symlink placed at a canonical record path that points at that secret. The
+  // scanner must reject non-regular files (symlinks) up front — otherwise a
+  // crafted `records/**.json` symlink would make it read and classify content
+  // outside the intended substrate root.
+  const rel = recordRelativePath(record({ id: "evil-link" }));
+  const linkPath = join(root, rel);
+  await mkdir(dirname(linkPath), { recursive: true });
+  await symlink(secret, linkPath);
+
+  const { code, stdout } = await runCheck(root);
+  assert.equal(code, 0, `symlinked record must be skipped, not scanned; stdout=${stdout}`);
+  assert.match(stdout, /0 record\(s\) scanned/);
+});
+
+test("check:pii does not follow a symlinked DIRECTORY into a target outside the root", async () => {
+  const root = await makeRoot();
+  // A directory OUTSIDE the substrate root holding a record-shaped file that
+  // carries an email address — content the scanner must never reach.
+  const outsideDir = join(await makeRoot(), "outside-bucket");
+  await mkdir(outsideDir, { recursive: true });
+  await writeFile(
+    join(outsideDir, "rec-leak.json"),
+    `${JSON.stringify(record({ id: "rec-leak", statement: "owned by alice.example@contoso.com" }), null, 2)}\n`,
+    "utf8",
+  );
+  // Symlink an INTERMEDIATE bucket directory in the layout to that outside dir.
+  // `records/epic/issue-303` → outsideDir makes `records/epic/issue-303/rec-leak.json`
+  // look like a canonical record path. `readdir(recursive:true)` would follow
+  // the symlinked directory and scan (and re-leak) the outside file; the walk
+  // must refuse to descend into any symlinked directory.
+  const bucketLink = join(root, "records", "epic", "issue-303");
+  await mkdir(dirname(bucketLink), { recursive: true });
+  await symlink(outsideDir, bucketLink);
+
+  const { code, stdout, stderr } = await runCheck(root);
+  assert.equal(code, 0, `symlinked bucket dir must not be traversed; stderr=${stderr}`);
+  assert.match(stdout, /0 record\(s\) scanned/);
+  // And it must never re-leak the outside PII it refused to scan.
+  assert.doesNotMatch(stderr, /alice\.example@contoso\.com/);
+});