@nanobpm/urban 0.66.2 → 0.68.0

package/dist/context/pii/classifier.d.ts

@@ -0,0 +1,55 @@
+import type { MemoryRecord } from "../schema/index.ts";
+/** The categories of PII / sensitive material the classifier recognises. */
+export type PiiKind = "email" | "phone" | "ssn" | "credit-card" | "ip-address" | "aws-access-key-id" | "private-key" | "jwt";
+/** A single located detection. */
+export interface PiiFinding {
+    /** Which category matched. */
+    readonly kind: PiiKind;
+    /**
+     * Dotted path to the offending field within the candidate. Empty (`""`) when
+     * the candidate is a bare string. For array elements the index is appended,
+     * e.g. `evidence.0`.
+     */
+    readonly path: string;
+    /** Character offset of the match within that field's text. */
+    readonly index: number;
+    /**
+     * A length-only placeholder for the matched substring (e.g. `[redacted:17]`).
+     * Contains NO part of the value, so a finding can be logged/surfaced without
+     * re-leaking any character of the PII/secret it located.
+     */
+    readonly excerpt: string;
+    /** Human-readable explanation of why this was flagged. */
+    readonly reason: string;
+}
+/**
+ * The classification decision. `clean: true` means no PII was found; otherwise
+ * `findings` is a non-empty list of located detections.
+ */
+export type PiiClassification = {
+    readonly clean: true;
+    readonly findings: readonly [];
+} | {
+    readonly clean: false;
+    readonly findings: readonly PiiFinding[];
+};
+/**
+ * Anything the classifier can inspect: a bare string, a {@link MemoryRecord}, or
+ * any plain object whose string / string-array properties should be scanned.
+ * Nested objects and arrays are walked recursively, so PII buried in a
+ * sub-object is still found; non-string leaf values (numbers, booleans, `null`)
+ * are ignored, so a record's numeric `schemaVersion` or an ISO `createdAt`
+ * timestamp never trips a false positive.
+ */
+export type PiiCandidate = string | MemoryRecord | Readonly<Record<string, unknown>>;
+/**
+ * Classify a candidate for PII. PURE and deterministic — no I/O, no shared
+ * state. Returns `{ clean: true }` when nothing is found, otherwise
+ * `{ clean: false, findings }` with a located reason for every hit.
+ *
+ * Inspect a whole {@link MemoryRecord} (every string / string-array field is
+ * scanned), a single field's text, or any plain object.
+ */
+export declare function classifyPii(candidate: PiiCandidate): PiiClassification;
+/** Convenience predicate: `true` when the candidate carries no detected PII. */
+export declare function isPiiClean(candidate: PiiCandidate): boolean;

package/dist/context/pii/classifier.js

@@ -0,0 +1,250 @@
+// Slice S6 CORE (pii guard-core) — the PII *classifier*.
+//
+// A PURE, dependency-free function that inspects candidate memory-record content
+// and reports whether it carries personally-identifiable information (PII) or
+// PII-adjacent secrets. It is the analytical core the mandatory pre-commit guard
+// (`./guard.ts`) is built on: the guard decides *policy* (default-DENY), this
+// module decides *facts* (what looks like PII and where).
+//
+// Design goals:
+//  - PURE & deterministic: same input → same classification, no I/O, no state.
+//    Safe to call on a hot path (S3 runs it before every commit) and trivial to
+//    unit-test and reuse (the S6 CI slice reuses it to scan staged records).
+//  - By-construction MVP: the context substrate is *no-PII*, so the classifier
+//    is deliberately conservative-to-strict — it errs toward flagging obfuscated
+//    look-alikes (e.g. `name (at) host dot com`) because a false *positive* is a
+//    safe rejection while a false *negative* would launder PII into the record.
+//  - Located findings: every hit reports the field `path` and offset so callers
+//    (and humans) can see exactly what was flagged and why.
+function luhnValid(digits) {
+    const only = digits.replace(/\D/g, "");
+    if (only.length < 13 || only.length > 19)
+        return false;
+    let sum = 0;
+    let alternate = false;
+    for (let i = only.length - 1; i >= 0; i--) {
+        let n = only.charCodeAt(i) - 48;
+        if (alternate) {
+            n *= 2;
+            if (n > 9)
+                n -= 9;
+        }
+        sum += n;
+        alternate = !alternate;
+    }
+    return sum % 10 === 0;
+}
+function validIpv4(match) {
+    return match.split(".").every((octet) => {
+        const n = Number(octet);
+        return octet.length <= 3 && n >= 0 && n <= 255;
+    });
+}
+// Detectors run against the raw text. `pattern` MUST be global (`g`) so every
+// occurrence is reported, not just the first.
+const DETECTORS = [
+    {
+        kind: "private-key",
+        reason: "PEM private-key block",
+        pattern: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/g,
+    },
+    {
+        kind: "aws-access-key-id",
+        reason: "AWS access key id",
+        pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
+    },
+    {
+        kind: "jwt",
+        reason: "JSON Web Token",
+        pattern: /\beyJ[A-Za-z0-9_-]{5,}\.eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b/g,
+    },
+    {
+        kind: "ssn",
+        reason: "US Social Security Number",
+        pattern: /\b\d{3}-\d{2}-\d{4}\b/g,
+    },
+    {
+        kind: "credit-card",
+        reason: "credit-card number (Luhn-valid)",
+        pattern: /\b(?:\d[ -]?){13,19}\b/g,
+        accept: luhnValid,
+    },
+    {
+        kind: "phone",
+        reason: "telephone number",
+        // Optional country code, then 3-3-4 grouping with separators — deliberately
+        // strict so ISO timestamps / ids (4-2-2, 3-1-1…) do not match.
+        pattern: /(?:\+?\d{1,3}[\s.-]?)?(?:\(\d{3}\)|\d{3})[\s.-]\d{3}[\s.-]\d{4}\b/g,
+    },
+    {
+        kind: "ip-address",
+        reason: "IPv4 address",
+        pattern: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+        accept: validIpv4,
+    },
+    {
+        kind: "email",
+        reason: "email address",
+        pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+    },
+];
+// Obfuscated-email detector. Real-world PII is often written to evade naive
+// scanners: `alice (at) example dot com`, `alice[at]example[dot]com`. We
+// normalise those spellings back to `@`/`.` on a COPY of the text and re-run the
+// plain email detector; a hit is reported at the original field. Because the
+// MVP is no-PII by construction we accept the (safe) risk of flagging a benign
+// "X at Y dot Z" phrase — a false positive is a rejected write, never a leak.
+//
+// The two obfuscation spellings are matched in ONE left-to-right pass (the `at`
+// alternation first, then `dot`) so a normalised offset can be mapped straight
+// back to the original text — a normalising `.replace()` chain would shift every
+// offset after a rewritten run and mis-locate the finding.
+const OBFUSCATION_TOKEN = /(\s*[([{]?\s*(?:at|@)\s*[)\]}]?\s*)|(\s*[([{]?\s*(?:dot|\.)\s*[)\]}]?\s*)/gi;
+/**
+ * Normalise obfuscated `@`/`.` spellings back to their canonical characters.
+ * Returns the normalised text plus a `map` where `map[i]` is the index in the
+ * ORIGINAL text that normalised character `i` originated from, so a match found
+ * in the normalised copy can be reported at its true original offset.
+ */
+function deobfuscate(text) {
+    let out = "";
+    const map = [];
+    let last = 0;
+    OBFUSCATION_TOKEN.lastIndex = 0;
+    let m = OBFUSCATION_TOKEN.exec(text);
+    while (m !== null) {
+        for (let i = last; i < m.index; i++) {
+            out += text[i];
+            map.push(i);
+        }
+        out += m[1] !== undefined ? "@" : ".";
+        map.push(m.index);
+        last = m.index + m[0].length;
+        if (m.index === OBFUSCATION_TOKEN.lastIndex)
+            OBFUSCATION_TOKEN.lastIndex++;
+        m = OBFUSCATION_TOKEN.exec(text);
+    }
+    for (let i = last; i < text.length; i++) {
+        out += text[i];
+        map.push(i);
+    }
+    return { text: out, map };
+}
+function redact(match) {
+    // Findings are explicitly logged/surfaced, so the excerpt must never contain
+    // ANY part of the sensitive value — even the first/last characters would leak
+    // PII/secrets into logs. Emit a length-only placeholder: useful for
+    // debugging ("how long was it?") without re-leaking a single character.
+    return `[redacted:${match.trim().length}]`;
+}
+function scanText(path, text) {
+    const findings = [];
+    for (const detector of DETECTORS) {
+        detector.pattern.lastIndex = 0;
+        let m = detector.pattern.exec(text);
+        while (m !== null) {
+            const value = m[0];
+            if (!detector.accept || detector.accept(value)) {
+                findings.push({
+                    kind: detector.kind,
+                    path,
+                    index: m.index,
+                    excerpt: redact(value),
+                    reason: detector.reason,
+                });
+            }
+            // Guard against zero-width matches looping forever.
+            if (m.index === detector.pattern.lastIndex)
+                detector.pattern.lastIndex++;
+            m = detector.pattern.exec(text);
+        }
+    }
+    // Obfuscated email pass — only add hits the plain pass did not already report.
+    const { text: normalised, map } = deobfuscate(text);
+    if (normalised !== text) {
+        const emailDetector = DETECTORS.find((d) => d.kind === "email");
+        if (emailDetector) {
+            // Dedupe per LOCATION, not per field: a field-wide "already saw an email"
+            // flag would drop every obfuscated hit as soon as one plain email exists
+            // anywhere in the field (under-reporting a mixed plain+obfuscated field).
+            const plainEmailIndices = new Set(findings.filter((f) => f.kind === "email").map((f) => f.index));
+            emailDetector.pattern.lastIndex = 0;
+            let em = emailDetector.pattern.exec(normalised);
+            while (em !== null) {
+                // Map the offset in the normalised copy back to the original text so the
+                // finding is located where the obfuscated value actually is.
+                const originalIndex = map[em.index] ?? em.index;
+                if (!plainEmailIndices.has(originalIndex)) {
+                    findings.push({
+                        kind: "email",
+                        path,
+                        index: originalIndex,
+                        excerpt: redact(em[0]),
+                        reason: "obfuscated email address",
+                    });
+                }
+                if (em.index === emailDetector.pattern.lastIndex)
+                    emailDetector.pattern.lastIndex++;
+                em = emailDetector.pattern.exec(normalised);
+            }
+        }
+    }
+    return findings;
+}
+/**
+ * Flatten a candidate into the `(path, text)` fields the detectors scan. String
+ * leaves are scanned; every object / array is walked RECURSIVELY so PII nested
+ * inside sub-objects or arrays of objects cannot slip past the default-deny
+ * guard as a false negative. Non-string, non-container leaves (numbers,
+ * booleans, `null`) are ignored. A `WeakSet` breaks any accidental reference
+ * cycle so a self-referential candidate cannot loop forever.
+ */
+function collectFields(candidate) {
+    if (typeof candidate === "string")
+        return [{ path: "", text: candidate }];
+    const fields = [];
+    const seen = new WeakSet();
+    const walk = (value, path) => {
+        if (typeof value === "string") {
+            fields.push({ path, text: value });
+            return;
+        }
+        if (value === null || typeof value !== "object")
+            return;
+        if (seen.has(value))
+            return;
+        seen.add(value);
+        if (Array.isArray(value)) {
+            value.forEach((entry, i) => walk(entry, path === "" ? `${i}` : `${path}.${i}`));
+            return;
+        }
+        for (const [key, v] of Object.entries(value)) {
+            walk(v, path === "" ? key : `${path}.${key}`);
+        }
+    };
+    for (const [key, value] of Object.entries(candidate)) {
+        walk(value, key);
+    }
+    return fields;
+}
+/**
+ * Classify a candidate for PII. PURE and deterministic — no I/O, no shared
+ * state. Returns `{ clean: true }` when nothing is found, otherwise
+ * `{ clean: false, findings }` with a located reason for every hit.
+ *
+ * Inspect a whole {@link MemoryRecord} (every string / string-array field is
+ * scanned), a single field's text, or any plain object.
+ */
+export function classifyPii(candidate) {
+    const findings = [];
+    for (const { path, text } of collectFields(candidate)) {
+        findings.push(...scanText(path, text));
+    }
+    if (findings.length === 0)
+        return { clean: true, findings: [] };
+    return { clean: false, findings };
+}
+/** Convenience predicate: `true` when the candidate carries no detected PII. */
+export function isPiiClean(candidate) {
+    return classifyPii(candidate).clean;
+}

package/dist/context/pii/guard.d.ts

@@ -0,0 +1,63 @@
+import { type PiiCandidate, type PiiClassification, type PiiFinding } from "./classifier.ts";
+/**
+ * Thrown by {@link PiiGuard.assert} (and the default guard) when a candidate
+ * carries PII. Carries the located {@link PiiFinding}s so callers can log /
+ * surface exactly what was rejected without re-running the classifier.
+ */
+export declare class PiiGuardError extends Error {
+    /** The located detections that caused the rejection (never empty). */
+    readonly findings: readonly PiiFinding[];
+    constructor(findings: readonly PiiFinding[]);
+}
+/**
+ * A pre-commit guard. The published seam S3 registers as its default,
+ * non-bypassable write-path check.
+ *
+ * Implementations MUST be default-DENY: {@link assert} throws on any detected
+ * PII and returns normally only for clean content.
+ */
+export interface PiiGuard {
+    /** Stable identifier (useful when a registry holds several guards). */
+    readonly name: string;
+    /**
+     * Non-throwing classification — returns the decision so a caller can inspect
+     * findings without catching. Does not enforce policy on its own.
+     */
+    inspect(candidate: PiiCandidate): PiiClassification;
+    /**
+     * Default-DENY enforcement. Returns `void` when the candidate is clean;
+     * THROWS {@link PiiGuardError} (carrying the findings) when PII is detected.
+     * This is the method a write path calls immediately before committing.
+     */
+    assert(candidate: PiiCandidate): void;
+}
+/**
+ * Options for {@link createPiiGuard}. Additive and backward-compatible; the
+ * default (no options) is the mandatory, no-PII-by-construction guard.
+ */
+export interface PiiGuardOptions {
+    /** Override the guard's `name` (defaults to `"pre-commit-pii-guard"`). */
+    readonly name?: string;
+    /**
+     * An ADDITIONAL classifier, unioned with the built-in {@link classifyPii}.
+     * The built-in classifier ALWAYS runs; this override's findings are merged on
+     * top, so an override can only make the guard STRICTER — it can never suppress
+     * a built-in detection or otherwise disable enforcement (a guard is always
+     * default-DENY). Intended for tests and for a future stricter policy.
+     */
+    readonly classify?: (candidate: PiiCandidate) => PiiClassification;
+}
+/**
+ * Build a default-DENY PII guard. With no options this returns the same policy
+ * as {@link preCommitPiiGuard}: it classifies with the built-in classifier and
+ * rejects any candidate that carries PII. A caller-supplied `classify` runs IN
+ * ADDITION to the built-in classifier (findings are unioned), so it can only
+ * ever make the guard stricter — never weaker.
+ */
+export declare function createPiiGuard(options?: PiiGuardOptions): PiiGuard;
+/**
+ * The ready-to-use default guard. S3 registers THIS instance as the
+ * non-optional, default pre-commit step on every write path so that PII is
+ * blocked by construction. Do not gate it behind a caller opt-in.
+ */
+export declare const preCommitPiiGuard: PiiGuard;

package/dist/context/pii/guard.js

@@ -0,0 +1,94 @@
+// Slice S6 CORE (pii guard-core) — the MANDATORY pre-commit PII guard.
+//
+// This is the enforcement seam S3 (git substrate / governance) consumes. It
+// wraps the pure classifier (`./classifier.ts`) in a default-DENY policy: a
+// candidate carrying PII is REJECTED (the guard throws); clean content passes
+// through untouched.
+//
+// ┌────────────────────────────────────────────────────────────────────────┐
+// │ CONTRACT — read before wiring:                                          │
+// │   guard.assert(candidate)  → returns void when clean, THROWS            │
+// │                              PiiGuardError when PII is detected.        │
+// │   guard.inspect(candidate) → non-throwing; returns the classification.  │
+// │                                                                          │
+// │ S3 MUST register `preCommitPiiGuard` (or a `createPiiGuard()` instance) │
+// │ as the NON-OPTIONAL, default pre-commit step on EVERY write path, so    │
+// │ PII is blocked BY CONSTRUCTION — not merely when a caller opts in. The  │
+// │ later S6 CI slice adds a build-time classification workflow +           │
+// │ erasure/immutability docs on TOP of this in-process guard; it must not  │
+// │ weaken or bypass it.                                                    │
+// └────────────────────────────────────────────────────────────────────────┘
+//
+// This slice owns the classifier + guard ONLY. It has no git / network access
+// and does NOT import `../git` (S3 imports us — the dependency points one way to
+// keep the graph acyclic).
+import { classifyPii, } from "./classifier.js";
+/**
+ * Thrown by {@link PiiGuard.assert} (and the default guard) when a candidate
+ * carries PII. Carries the located {@link PiiFinding}s so callers can log /
+ * surface exactly what was rejected without re-running the classifier.
+ */
+export class PiiGuardError extends Error {
+    /** The located detections that caused the rejection (never empty). */
+    findings;
+    constructor(findings) {
+        const summary = findings
+            .map((f) => `${f.kind}${f.path ? ` @ ${f.path}` : ""}`)
+            .join(", ");
+        super(`PII pre-commit guard rejected the write: ${summary}`);
+        this.name = "PiiGuardError";
+        // Defensively snapshot: a caller mutating the array it passed in must never
+        // retroactively change what this error reports it rejected.
+        this.findings = Object.freeze([...findings]);
+    }
+}
+/**
+ * Build a default-DENY PII guard. With no options this returns the same policy
+ * as {@link preCommitPiiGuard}: it classifies with the built-in classifier and
+ * rejects any candidate that carries PII. A caller-supplied `classify` runs IN
+ * ADDITION to the built-in classifier (findings are unioned), so it can only
+ * ever make the guard stricter — never weaker.
+ */
+export function createPiiGuard(options = {}) {
+    const name = options.name ?? "pre-commit-pii-guard";
+    const override = options.classify;
+    // The built-in classifier ALWAYS runs; an override can only ADD findings.
+    // This makes the `classify` option unable to disable the default-DENY guard.
+    const classify = (candidate) => {
+        const base = classifyPii(candidate);
+        if (override === undefined)
+            return base;
+        const extra = override(candidate);
+        const findings = [...base.findings, ...extra.findings];
+        // Derive the verdict from the merged findings — the single source of truth.
+        // A guard is default-DENY, so any `!clean` classification MUST carry the
+        // findings that justify it; a non-clean result with no findings would make
+        // `assert` throw a PiiGuardError whose summary is empty, contradicting the
+        // "findings are never empty" contract. Surface that override bug loudly
+        // rather than as a confusing, empty rejection.
+        if (findings.length === 0 && (!base.clean || !extra.clean)) {
+            throw new TypeError("PII classifier override returned a non-clean classification with no findings; " +
+                "an override may only ADD located findings, never report PII without locating it.");
+        }
+        return findings.length === 0
+            ? { clean: true, findings: [] }
+            : { clean: false, findings };
+    };
+    return {
+        name,
+        inspect(candidate) {
+            return classify(candidate);
+        },
+        assert(candidate) {
+            const result = classify(candidate);
+            if (!result.clean)
+                throw new PiiGuardError(result.findings);
+        },
+    };
+}
+/**
+ * The ready-to-use default guard. S3 registers THIS instance as the
+ * non-optional, default pre-commit step on every write path so that PII is
+ * blocked by construction. Do not gate it behind a caller opt-in.
+ */
+export const preCommitPiiGuard = createPiiGuard();

package/dist/context/pii/index.d.ts

@@ -1 +1,2 @@
-export {};
+export { type PiiKind, type PiiFinding, type PiiClassification, type PiiCandidate, classifyPii, isPiiClean, } from "./classifier.ts";
+export { type PiiGuard, type PiiGuardOptions, PiiGuardError, createPiiGuard, preCommitPiiGuard, } from "./guard.ts";

package/dist/context/pii/index.js

@@ -1 +1,24 @@
-export {};
+// @nanobpm/urban/context/pii — slice S6 CORE (pii guard-core).
+//
+// The enforcement seam of the Urban context layer. It publishes two things:
+//
+//  1. A PURE PII classifier (`classifyPii`) — inspects candidate record content
+//     and returns a located clean/violation decision. Reusable on any hot path
+//     and by the S6 CI slice's build-time scan.
+//  2. A MANDATORY, default-DENY pre-commit guard (`preCommitPiiGuard` /
+//     `createPiiGuard`) built on the classifier. S3 (git substrate / governance)
+//     registers this as the NON-OPTIONAL default pre-commit step on every write
+//     path, so PII is blocked BY CONSTRUCTION — not merely when a caller opts in.
+//
+// Contract summary (see ./guard.ts and ./NOTES.md for detail):
+//   guard.assert(candidate)  → void when clean, THROWS PiiGuardError on PII.
+//   guard.inspect(candidate) → non-throwing PiiClassification.
+//
+// The MVP substrate is no-PII by construction; this slice builds neither a
+// mutable/erasure backend nor the CI workflow (that is the later S6 CI slice,
+// which layers a build-time net + erasure/immutability docs on top of this).
+//
+// This slice imports the record types from `../schema` but NOT `../git`: S3
+// imports us, so the dependency points one way and the graph stays acyclic.
+export { classifyPii, isPiiClean, } from "./classifier.js";
+export { PiiGuardError, createPiiGuard, preCommitPiiGuard, } from "./guard.js";

package/dist/runtime/core/modules/pages.js

@@ -592,6 +592,13 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-subform-title { font-weight:600; font-size:.85rem; margin-bottom:.4rem; }
 .pc-prompt { font-size:.85rem; color:var(--nano-text-muted); margin-bottom:.4rem; white-space:pre-wrap; }
 .pc-textarea { width:100%; min-height:4rem; padding:.5rem; border:1px solid var(--nano-edge); border-radius:.4rem; font:inherit; background:var(--nano-inset); color:var(--nano-text); }
+/* Schema-derived multi-field detail.form widgets (#372): a short free-text
+   <input> and an enumerated-choice <select>, styled to match .pc-textarea so a
+   select/text/textarea form reads as one coherent set. A field hidden by its
+   conditional.hide expression carries the plain [hidden] attribute (display:none
+   by default), so no extra rule is needed to remove it from the layout. */
+.pc-input, .pc-select { width:100%; padding:.5rem .6rem; border:1px solid var(--nano-edge); border-radius:.4rem; font:inherit; background:var(--nano-inset); color:var(--nano-text); }
+.pc-subform .pc-field label { font-size:.8rem; color:var(--nano-text-muted); }
 .pc-collapse-header { display:flex; align-items:center; gap:.5rem; width:100%; margin:0 0 .75rem; padding:0; background:transparent; border:0; color:inherit; font:inherit; font-size:1rem; font-weight:600; cursor:pointer; text-align:left; }
 .pc-chevron-inline { color:var(--nano-text-faint); font-size:.75rem; width:1em; }
 .pc-card-body[hidden] { display:none; }