@watchlight/sdk 0.2.0 → 0.4.0

package/README.md

@@ -108,6 +108,78 @@ const search = governTool(
 mutated); `governTools(tools, { intentFor })` maps an array. Intent defaults to
 the tool's name. Fail-closed. `@langchain/core` is a peer dependency.
 
+## Gate a consequential action — runtime context, per-user, human-in-the-loop
+
+For money-moving (or any high-stakes) tool calls, pass **runtime facts** into the
+policy, attribute the decision to the **acting user**, get a **correlation id**
+back, and route the risky ones to a **human**.
+
+```ts
+import { govern, NeedsApproval } from "@watchlight/sdk";
+
+// principal / resource / context can each be a value or (args) => value
+const book = govern.tool(bookTrip, {
+  intent: "book",
+  principal: (o) => `User::"${o.userId}"`,
+  resource:  (o) => `trip/${o.tripId}`,
+  context:   (o) => ({ amount: o.amount, limit: o.perActionLimit, refundable: o.refundable }),
+  onNeedsApproval: async ({ decisionId }) => askUser(decisionId), // one-tap human confirm
+});
+```
+```
+permit(principal, action == Action::"book", resource)
+when { context.amount <= context.limit && context.refundable };
+```
+
+Or use the low-level primitive directly (any framework):
+
+```ts
+const d = await govern.authorize({
+  principal: `User::"${userId}"`, action: "wire", resource: `acct/${to}`, context: { amount },
+});
+// d.decision → "Allow" | "Deny" | "NeedsApproval"
+// d.decisionId → store next to your booking row for reconstruction
+
+if (d.decision === "NeedsApproval") {
+  await getHumanConfirmation();
+  const token = govern.mintApproval({ action: "wire", resource: `acct/${to}` }); // single-use, TTL, bound
+  await govern.authorize({ principal: `User::"${userId}"`, action: "wire", resource: `acct/${to}`, context: { amount }, approval: token });
+}
+```
+
+- **Three-state verdict** — `NeedsApproval` is surfaced when a matched permit is
+  annotated `@enforcement_effect("require_approval")`.
+- **Correlation id** — every decision returns `decisionId` (also in the audit
+  line), so you can join it to your own records.
+- The audit line now carries `decision_id` + the resolved `principal`, and stays
+  value-free (no context values).
+
+## Strip PII before the agent reads a document
+
+Redact PII from text before it reaches the agent — deterministic, in-process,
+fail-closed. Extract your document to text first (never hand the agent the
+original PDF — its hidden layers leak), then sanitize:
+
+```ts
+import { govern } from "@watchlight/sdk";
+
+const text = await extractPdfText("statement.pdf"); // your extractor
+const { text: safe, report } = govern.sanitize(text, { resource: "statement.pdf" });
+
+// safe → "Card on file: <CREDIT_CARD_1>  SSN: <SSN_1>  ..."
+// report → { mode:"tag", counts:{ CREDIT_CARD:1, SSN:1, ... }, total, ... }  (value-free)
+await agent.read(safe);
+```
+
+The deterministic detector covers structured PII — email, phone, SSN, credit card
+(Luhn-validated), IBAN, IPv4, API keys. Modes: `tag` (consistent `<EMAIL_1>`
+placeholders, default), `mask` (`[EMAIL]`), `hash`. `govern.sanitize` records a
+**value-free** audit entry (counts by type + mode — never the values).
+
+A pure `sanitize(text, opts)` is also exported. Fail-closed: it throws
+`SanitizeError` rather than return partially-redacted text. Names/addresses need
+NER (Enterprise); recall is bounded by the enabled detectors.
+
 ## Value-free audit
 
 `.watchlight/audit.jsonl` records **who / what intent / which tool / the

package/dist/backend.d.ts

@@ -8,7 +8,16 @@ export interface AuthorizeRequest {
 export interface Decision {
     decision: string;
     reason: string;
+    /** Per-decision correlation id (the engine's `request_id`) — join to your own
+     *  records. */
+    decisionId?: string;
+    /** True when a matched permit carries the `require_approval` enforcement
+     *  effect: the action is permitted only after a human confirmation. */
+    needsApproval?: boolean;
 }
+/** Derive `needsApproval` from a decision's details: a permitting policy result
+ *  annotated `@enforcement_effect("require_approval")`. */
+export declare function deriveNeedsApproval(details: unknown): boolean;
 export interface GovernanceBackend {
     readonly kind: "in-process" | "networked";
     /** A short human label for the dev announce line. */

package/dist/backend.js

@@ -14,8 +14,20 @@
 // Fail-closed everywhere: any transport/engine error resolves to Deny.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NetworkedBackend = exports.InProcessBackend = void 0;
+exports.deriveNeedsApproval = deriveNeedsApproval;
 exports.selectBackend = selectBackend;
 const engine_1 = require("@watchlight/engine");
+/** Derive `needsApproval` from a decision's details: a permitting policy result
+ *  annotated `@enforcement_effect("require_approval")`. */
+function deriveNeedsApproval(details) {
+    const results = details?.policy_results;
+    // Only the policy that actually matched this request (`applicable: true`)
+    // counts — a non-matching require_approval policy elsewhere in the set must not
+    // flag this decision.
+    return Array.isArray(results)
+        ? results.some((r) => r?.applicable === true && r?.enforcement_effect === "require_approval")
+        : false;
+}
 /** DE default — the compiled engine in-process. */
 class InProcessBackend {
     constructor() {
@@ -40,13 +52,18 @@ class InProcessBackend {
     }
     async authorize(req) {
         const engine = await this._ready();
-        const resp = await engine.authorize({
+        const resp = (await engine.authorize({
             principal: req.principal,
             action: req.action,
             resource: req.resource,
             context: req.context ?? {},
-        });
-        return { decision: resp.decision ?? "Deny", reason: resp.reason ?? "" };
+        }));
+        return {
+            decision: resp.decision ?? "Deny",
+            reason: resp.reason ?? "",
+            decisionId: resp.request_id,
+            needsApproval: deriveNeedsApproval(resp.details),
+        };
     }
     engine() {
         return this._ready();
@@ -91,7 +108,12 @@ class NetworkedBackend {
             if (!resp.ok)
                 return { decision: "Deny", reason: `APDP error: ${resp.status}` };
             const data = (await resp.json());
-            return { decision: data.decision ?? "Deny", reason: data.reason ?? "" };
+            return {
+                decision: data.decision ?? "Deny",
+                reason: data.reason ?? "",
+                decisionId: data.request_id,
+                needsApproval: deriveNeedsApproval(data.details),
+            };
         }
         catch (e) {
             // Fail-closed: an unreachable control plane denies.

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 import { Scope } from "./attenuation";
+import { type SanitizeOptions, type SanitizeResult } from "./sanitize";
 export { Scope, DE_MAX_DEPTH, AttenuationDenied, DevEditionCeiling } from "./attenuation";
 export { governedHooks } from "./claude-agent";
 export type { GovernedHooksOptions, GovernedHooksResult } from "./claude-agent";
 export { governTool, governTools } from "./langchain";
 export type { LangChainToolLike, GovernToolOptions, GovernToolsOptions, } from "./langchain";
+export { sanitize, SanitizeError, DETECTOR_VERSION } from "./sanitize";
+export type { PiiType, RedactMode, SanitizeOptions, SanitizeReport, SanitizeResult, } from "./sanitize";
 export type { GovernanceBackend, Decision, AuthorizeRequest } from "./backend";
 export { InProcessBackend, NetworkedBackend } from "./backend";
 /** Raised when the policy engine refuses a governed tool call (fail-closed). */
@@ -13,6 +16,32 @@ export declare class Denied extends Error {
     readonly reason: string;
     constructor(tool: string, intent: string, reason: string);
 }
+/** Raised when a governed call is permitted only after a human confirmation
+ *  (the matched permit carries the `require_approval` enforcement effect) and no
+ *  valid approval was supplied. Fail-closed: the tool body did NOT run. */
+export declare class NeedsApproval extends Error {
+    readonly tool: string;
+    readonly intent: string;
+    readonly decisionId?: string;
+    readonly reason: string;
+    constructor(tool: string, intent: string, decisionId: string | undefined, reason: string);
+}
+/** A per-call binding: a fixed value, or a function of the tool's arguments. */
+export type Binding<A extends unknown[]> = string | ((...args: A) => string);
+/** A record of attributes passed into Cedar `context.*`, or a function of args. */
+export type ContextBinding<A extends unknown[]> = Record<string, unknown> | ((...args: A) => Record<string, unknown>);
+/** Full result of {@link Watchlight.authorize}. */
+export interface AuthorizeResult {
+    /** `"Allow"` | `"Deny"` | `"NeedsApproval"`. */
+    decision: "Allow" | "Deny" | "NeedsApproval";
+    allowed: boolean;
+    needsApproval: boolean;
+    /** True when a valid approval token downgraded a NeedsApproval to Allow. */
+    approved: boolean;
+    /** Per-decision correlation id (engine `request_id`) — join to your records. */
+    decisionId?: string;
+    reason: string;
+}
 /** A function governed by {@link Watchlight.tool} — always async (the engine's
  *  authorize path is async in WebAssembly). */
 export type Governed<A extends unknown[], R> = (...args: A) => Promise<Awaited<R>>;
@@ -77,6 +106,24 @@ export declare class Watchlight {
      */
     tool<A extends unknown[], R>(fn: (...args: A) => R, opts: {
         intent: string;
+        /** Acting principal, e.g. `User::"u1"` — value or `(args) => value`.
+         *  Defaults to the agent. */
+        principal?: Binding<A>;
+        /** Cedar resource entity — value or `(args) => value`. Defaults to
+         *  `tool/<name>`. */
+        resource?: Binding<A>;
+        /** Attributes for Cedar `context.*` — object or `(args) => object`. */
+        context?: ContextBinding<A>;
+        /** Human-in-the-loop hook. Called when the decision is `NeedsApproval`;
+         *  return `true` to proceed (records an approval), `false`/absent to hold
+         *  (throws `NeedsApproval`). */
+        onNeedsApproval?: (info: {
+            intent: string;
+            resource: string;
+            principal: string;
+            decisionId?: string;
+            reason: string;
+        }) => boolean | Promise<boolean>;
     }): Governed<A, R>;
     /**
      * Authorize a raw `(intent, tool)` pair, audit the decision, and return it.
@@ -88,8 +135,52 @@ export declare class Watchlight {
         allowed: boolean;
         decision: string;
         reason: string;
+        decisionId?: string;
     }>;
-    private _authorize;
+    /**
+     * Authorize an action with full control — per-call `principal`, `resource`,
+     * and Cedar `context` — and get a correlation id back. The low-level primitive
+     * behind {@link tool}; use it directly for any consequential action.
+     *
+     * Returns a three-state verdict: `Allow` / `Deny` / `NeedsApproval`. A
+     * `NeedsApproval` (matched permit annotated `require_approval`) is downgraded
+     * to `Allow` when a valid single-use `approval` token — from
+     * {@link mintApproval}, minted after a human confirms — is supplied.
+     * Fail-closed and audited (value-free).
+     */
+    authorize(req: {
+        action: string;
+        principal?: string;
+        resource?: string;
+        context?: Record<string, unknown>;
+        /** A token from {@link mintApproval} (after human confirmation). */
+        approval?: string;
+    }): Promise<AuthorizeResult>;
+    /**
+     * Mint a single-use approval token for a specific `(principal, action,
+     * resource)`, to pass to {@link authorize} after a human confirms a
+     * `NeedsApproval` decision. Local HMAC, TTL-bounded (default 2 min). In
+     * Enterprise these are KMS-signed and recorded in signed lineage.
+     */
+    mintApproval(challenge: {
+        action: string;
+        principal?: string;
+        resource?: string;
+    }, opts?: {
+        ttlMs?: number;
+    }): string;
+    /**
+     * Strip PII from text before an agent reads it (governed data minimization).
+     * Deterministic, fail-closed. Writes a value-free `sanitization` record to the
+     * audit trail (counts by PII type + mode — never the values) and returns the
+     * redacted text plus the report. Operates on extracted text — extract a
+     * document to text first (never hand the agent a "redacted PDF").
+     */
+    sanitize(content: string, opts?: SanitizeOptions & {
+        intent?: string;
+        resource?: string;
+    }): SanitizeResult;
+    private _auditSanitize;
     private _announce;
     private _audit;
 }

package/dist/sanitize.d.ts

@@ -0,0 +1,36 @@
+/** PII categories the deterministic detector recognizes. */
+export type PiiType = "EMAIL" | "PHONE" | "SSN" | "CREDIT_CARD" | "IBAN" | "IPV4" | "API_KEY";
+/** How a detected value is replaced. */
+export type RedactMode = "tag" | "mask" | "hash";
+export declare const DETECTOR_VERSION = "de-rules-1";
+/** Raised when sanitization cannot complete — fail-closed: the caller must NOT
+ *  fall back to raw content. */
+export declare class SanitizeError extends Error {
+    constructor(message: string);
+}
+export interface SanitizeOptions {
+    /** Replacement strategy. Default `"tag"` (consistent `<EMAIL_1>` placeholders). */
+    mode?: RedactMode;
+    /** Restrict to these PII types. Default: all deterministic types. */
+    types?: PiiType[];
+}
+export interface SanitizeReport {
+    mode: RedactMode;
+    detectorVersion: string;
+    /** Count of redactions per type. Value-free by construction — never the values. */
+    counts: Partial<Record<PiiType, number>>;
+    /** Total redactions. */
+    total: number;
+}
+export interface SanitizeResult {
+    /** The redacted text, safe to hand to an agent. */
+    text: string;
+    /** Value-free summary of what was redacted (for the audit trail). */
+    report: SanitizeReport;
+}
+/**
+ * Redact PII from `text`. Pure and deterministic. Fail-closed: throws
+ * {@link SanitizeError} on any internal error rather than returning partially
+ * processed (potentially leaking) text.
+ */
+export declare function sanitize(text: string, opts?: SanitizeOptions): SanitizeResult;

package/dist/sanitize.js

@@ -0,0 +1,155 @@
+"use strict";
+// govern.sanitize — governed data minimization at the agent boundary.
+//
+// Strip PII from text BEFORE an agent reads it. Deterministic, in-process,
+// fail-closed. This is the Developer-Edition baseline detector: high-precision
+// STRUCTURED PII via rules (email, phone, SSN, credit card w/ Luhn, IBAN, IPv4,
+// API keys). Names/addresses need NER — an opt-in / Enterprise stage — so recall
+// is honestly bounded by the enabled detectors and surfaced in the report.
+//
+// Operates on extracted TEXT. Document extraction (PDF/docx → text, across all
+// layers) is a separate step: you never hand the agent a "redacted PDF" (its
+// hidden layers leak) — you hand it redacted text.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SanitizeError = exports.DETECTOR_VERSION = void 0;
+exports.sanitize = sanitize;
+const node_crypto_1 = require("node:crypto");
+exports.DETECTOR_VERSION = "de-rules-1";
+/** Raised when sanitization cannot complete — fail-closed: the caller must NOT
+ *  fall back to raw content. */
+class SanitizeError extends Error {
+    constructor(message) {
+        super(`sanitize failed (fail-closed): ${message}`);
+        this.name = "SanitizeError";
+    }
+}
+exports.SanitizeError = SanitizeError;
+// ── deterministic detectors ─────────────────────────────────────────
+// Each returns [start, end) match spans over the input. High precision first;
+// CREDIT_CARD is Luhn-validated to cut false positives.
+const luhnOk = (digits) => {
+    let sum = 0;
+    let alt = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let d = digits.charCodeAt(i) - 48;
+        if (d < 0 || d > 9)
+            return false;
+        if (alt) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        alt = !alt;
+    }
+    return sum % 10 === 0;
+};
+const DETECTORS = [
+    { type: "EMAIL", re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g },
+    // API keys / tokens with well-known prefixes (before generic patterns).
+    { type: "API_KEY", re: /\b(?:sk-[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16})\b/g },
+    { type: "SSN", re: /\b(?!000|666|9\d\d)\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/g },
+    {
+        type: "CREDIT_CARD",
+        re: /\b(?:\d[ -]?){13,19}\b/g,
+        valid: (m) => {
+            const d = m.replace(/[ -]/g, "");
+            return d.length >= 13 && d.length <= 19 && luhnOk(d);
+        },
+    },
+    { type: "IBAN", re: /\b[A-Z]{2}\d{2}(?:[ ]?[A-Za-z0-9]{4}){2,7}(?:[ ]?[A-Za-z0-9]{1,3})?\b/g },
+    {
+        type: "IPV4",
+        re: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+        valid: (m) => m.split(".").every((o) => Number(o) <= 255),
+    },
+    {
+        type: "PHONE",
+        re: /(?<!\d)(?:\+?\d{1,3}[ .-]?)?(?:\(\d{2,4}\)[ .-]?)?\d{3}[ .-]?\d{4}(?!\d)/g,
+        // Require at least 10 digits total to avoid matching short number runs.
+        valid: (m) => (m.replace(/\D/g, "").length >= 10),
+    },
+];
+function detect(text, types) {
+    const enabled = new Set(types);
+    const spans = [];
+    for (const det of DETECTORS) {
+        if (!enabled.has(det.type))
+            continue;
+        det.re.lastIndex = 0;
+        let m;
+        while ((m = det.re.exec(text)) !== null) {
+            const value = m[0];
+            if (det.valid && !det.valid(value))
+                continue;
+            spans.push({ start: m.index, end: m.index + value.length, type: det.type, value });
+            if (m.index === det.re.lastIndex)
+                det.re.lastIndex++; // guard zero-width
+        }
+    }
+    // Resolve overlaps: sort by start, then longest; drop any span overlapping one
+    // already kept (first detector wins by the DETECTORS order via stable sort).
+    spans.sort((a, b) => a.start - b.start || b.end - b.start - (a.end - a.start));
+    const kept = [];
+    let lastEnd = -1;
+    for (const s of spans) {
+        if (s.start >= lastEnd) {
+            kept.push(s);
+            lastEnd = s.end;
+        }
+    }
+    return kept;
+}
+function replacement(span, mode, counters, perType) {
+    if (mode === "mask")
+        return `[${span.type}]`;
+    if (mode === "hash") {
+        const h = (0, node_crypto_1.createHash)("sha256").update(span.value).digest("hex").slice(0, 8);
+        return `<${span.type}_${h}>`;
+    }
+    // tag: consistent per value (same value → same tag within this call).
+    const key = `${span.type}:${span.value}`;
+    let tag = counters.get(key);
+    if (!tag) {
+        const n = (perType.get(span.type) ?? 0) + 1;
+        perType.set(span.type, n);
+        tag = `<${span.type}_${n}>`;
+        counters.set(key, tag);
+    }
+    return tag;
+}
+/**
+ * Redact PII from `text`. Pure and deterministic. Fail-closed: throws
+ * {@link SanitizeError} on any internal error rather than returning partially
+ * processed (potentially leaking) text.
+ */
+function sanitize(text, opts = {}) {
+    const mode = opts.mode ?? "tag";
+    const types = opts.types ?? DETECTORS.map((d) => d.type);
+    if (typeof text !== "string") {
+        throw new SanitizeError("input must be a string (extract document text first)");
+    }
+    try {
+        const spans = detect(text, types);
+        const counters = new Map();
+        const perTypeTag = new Map();
+        const counts = {};
+        // Rebuild the string, replacing spans left→right.
+        let out = "";
+        let cursor = 0;
+        for (const s of spans) {
+            out += text.slice(cursor, s.start);
+            out += replacement(s, mode, counters, perTypeTag);
+            cursor = s.end;
+            counts[s.type] = (counts[s.type] ?? 0) + 1;
+        }
+        out += text.slice(cursor);
+        return {
+            text: out,
+            report: { mode, detectorVersion: exports.DETECTOR_VERSION, counts, total: spans.length },
+        };
+    }
+    catch (e) {
+        throw new SanitizeError(String(e?.message ?? e));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watchlight/sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Watchlight Developer Edition govern glue for Node/TypeScript — declare intent, govern a tool with a fail-closed in-process policy decision, and get a value-free audit trail. Glue over @watchlight/engine; zero decision logic in JS.",
   "type": "commonjs",
   "main": "./dist/index.js",
@@ -15,7 +15,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node test/govern.test.mjs && node test/claude-agent.test.mjs && node test/graduation.test.mjs && node test/langchain.test.mjs",
+    "test": "npm run build && for t in govern claude-agent graduation langchain sanitize action-gate; do node test/$t.test.mjs || exit 1; done",
     "prepublishOnly": "npm run build"
   },
   "keywords": [