@flowdot.ai/guardian-agent 0.1.0

package/LICENSE

@@ -0,0 +1,40 @@
+@flowdot.ai/guardian-agent — TypeScript reference implementation of the
+guardian-agent runtime supervisor spec.
+Copyright (C) 2026  FlowDot LLC
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more
+details.
+
+You should have received a copy of the GNU Affero General Public License along
+with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Full license text: https://www.gnu.org/licenses/agpl-3.0.txt
+
+---
+
+COMMERCIAL LICENSING
+
+For use cases where the terms of the AGPL-3.0 are not suitable — including
+proprietary deployment, embedding in closed-source products, or distribution
+without source-availability obligations — a commercial license is available.
+
+Contact: licensing@flowdot.ai
+
+---
+
+SPEC DOCUMENT
+
+The canonical specification document lives at
+https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md
+and is dual-licensed under AGPL-3.0-or-later and CC BY-SA 4.0. The CC BY-SA 4.0
+licensing is intended to encourage citation and adaptation in research, policy,
+and standards work.
+
+See https://creativecommons.org/licenses/by-sa/4.0/ for the CC BY-SA 4.0 terms.

package/README.md

@@ -0,0 +1,281 @@
+# @flowdot.ai/guardian-agent
+
+> TypeScript reference implementation of the [guardian-agent spec](https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md). A runtime supervisor for tool-using LLM agents: tamper-evident audit log, tool-permission policy, HITL approval gates, emergency-stop, plus a runtime-safety layer (honeytokens, capability tripwires, per-class rate limits, two-key operator gates, heartbeat) and offline analysis tools.
+
+**Status**: v0.1.0 on npm · tracks SPEC v0.5 · v0.10 feature milestone hit · interface stabilizing toward v1.0
+
+```bash
+npm install @flowdot.ai/guardian-agent
+```
+
+> Note on versioning: milestone labels in this README (v0.1, v0.2, …, v0.10) refer to **feature milestones** in the [ROADMAP](./ROADMAP.md), not semver. The package's npm semver lives in `package.json`. Until the public API freezes for v1.0, expect minor-version churn — pin a specific minor in production.
+
+The Python reference implementation lives at [`flowdot-llc/guardian-agent`](https://github.com/flowdot-llc/guardian-agent). This repository is the parallel TypeScript implementation. Both conform to the same versioned [spec](https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md); the spec is the canonical contract, not either implementation.
+
+---
+
+## Why a second language
+
+Python serves the research and evaluation ecosystem (LangChain, AutoGen, MCP Python clients, eval labs). TypeScript serves the production-runtime ecosystem — Node servers, Electron apps, TypeScript MCP clients, LangChain.js, and the broader JS agent tooling. The same spec, in both places, is how a single supervisory contract reaches both worlds.
+
+Cross-language interop is real and intended:
+
+- An audit log written by the Python implementation can be read and verified by the TypeScript implementation, and vice versa.
+- A `permissions.yaml` is honored identically by both.
+- A gate callback URL hosted by one can be invoked by the other.
+- An `estop` triggered in one produces an audit event identical in structure to one triggered in the other.
+
+## What's included
+
+The library bundles three concentric layers. Each is independently usable; together they form the canonical supervisor.
+
+**Trust foundation** (v0.1 – v0.7):
+
+1. **Audit log** — hash-chained JSONL, optionally ed25519-signed. Every tool call gets a structured record. `guardian-verify` CLI confirms chain + signature integrity.
+2. **Tool-permission policy** — HMAC-signed YAML policy with `once`/`session`/`forever`/`banned` scopes and glob-matched tool names. Model-aware `when` clauses (`model.provider`, `model.id`, `attribution_path`).
+3. **HITL approval gate** — four reference adapters: CLI prompt, async webhook, programmatic callback, LiveKit data channel. Custom `GateOptionSet` lets consumers define their own button sets.
+4. **Emergency stop** — `EStopLocal` for single-process deployments, `EStopHub` middleware + poller for hub-coordinated deployments (HTTP 423 Locked).
+
+**Runtime safety layer** (v0.8 – v0.9):
+
+5. **External chain attestation** ([SPEC §11](https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md#11-external-chain-attestation-v030)) — periodically publish chain heads to an external append-only store. Closes the "compromised runtime forges its own log" gap. Reference adapters: `httpAttestor`, `nullAttestor`. Fail-soft on attestor outage.
+6. **Honeytokens** ([SPEC §12](https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md#12-honeytokens-v030)) — consumer-supplied value patterns + phantom tool names. Zero false positives by construction. Library ships **no default tokens**.
+7. **Capability tags + Yellow-line tripwires** ([SPEC §13](https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md#13-capability-tagging--tripwires-v030)) — tag tools with classes (`credential`, `network-egress`, `write`, ...) and define combination rules. v0.x ships Yellow-only (audit-row, no behavior change); Red-line auto-stop ships after real-surface telemetry calibrates thresholds.
+8. **Per-capability rate limits** ([SPEC §14](https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md#14-per-capability-rate-limits-v030)) — `MultiRateLimiter` with conservative defaults (credential=2/s, delete=1/s, network-egress=5/s).
+9. **Two-key operator authorization** ([SPEC §15](https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md#15-two-key-operator-authorization-v040)) — suspend dispatch pending fresh operator confirmation. Library defines the suspend/resume contract; consumers wire the transport.
+10. **Dead-man's heartbeat** ([SPEC §16](https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md#16-dead-mans-heartbeat-v040)) — soft warn + hard E-stop on missed liveness signals. Opt-in (default OFF).
+
+**Offline analysis tools** (v0.10):
+
+11. **`guardian-baseline`** ([SPEC §17](https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md#17-behavioral-baselines-offline-v050)) — descriptive statistics on audit streams. `--check` flags σ-deviations. **Reports only; not a runtime tripwire.**
+12. **`guardian-correlator`** ([SPEC §18](https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md#18-cross-surface-correlation-offline-v050)) — overlapping sessions + args-hash collisions + sequence-similarity matches across multiple audit logs for the same agent_id.
+
+---
+
+## Demos
+
+Three minimal demos show the supervisor enforcing a single primitive end-to-end. Each one is a deterministic `tsx` script — anyone with this repo can reproduce these on their machine by cloning and running `npm install && npm run demo:N`.
+
+### Demo 1 — Tamper-evident audit log
+
+Hash-chained + ed25519-signed audit records detect any post-hoc edit, down to a single byte. ([`examples/demo/demo-1-tamper.ts`](./examples/demo/demo-1-tamper.ts))
+
+![Tamper-evident audit log](./examples/demo/demo-1-tamper.gif)
+
+### Demo 2 — HITL approval gate
+
+A tool tagged `requiresOperatorConfirmation: true` suspends dispatch and asks a configured `operatorGate` for a decision. Denial means the tool body never executes. ([`examples/demo/demo-2-gate.ts`](./examples/demo/demo-2-gate.ts))
+
+![HITL approval gate](./examples/demo/demo-2-gate.gif)
+
+### Demo 3 — Honeytoken catches exfiltration
+
+Planted tokens that never appear in real workflows. Any tool call whose args contain one is, by construction, an attack. Hit triggers `x_honeytoken_triggered` + emergency-stop, and the E-stop is sticky — subsequent calls also throw. ([`examples/demo/demo-3-honeytoken.ts`](./examples/demo/demo-3-honeytoken.ts))
+
+![Honeytoken catches exfiltration](./examples/demo/demo-3-honeytoken.gif)
+
+Run them yourself:
+
+```bash
+npm install
+npm run demo:1   # tamper-evident audit log
+npm run demo:2   # HITL approval gate
+npm run demo:3   # honeytoken catches exfiltration
+```
+
+---
+
+## Quickstart
+
+```typescript
+import {
+  AuditLogWriter,
+  EStopLocal,
+  GuardianRuntime,
+} from '@flowdot.ai/guardian-agent';
+
+const audit = new AuditLogWriter({
+  path: './audit.jsonl',
+  agentId: 'agent_demo',
+  sessionId: 'sess_quickstart',
+});
+const estop = new EStopLocal({ audit });
+const runtime = new GuardianRuntime({
+  agentId: 'agent_demo',
+  sessionId: 'sess_quickstart',
+  audit,
+  estop,
+});
+
+// Wrap any tool function — MCP, LangChain.js, native async fn:
+const listAccounts = runtime.tool(
+  async (broker: string) => [
+    { id: 'acct_001', broker, balanceUsd: 12_345.67 },
+  ],
+  { name: 'list_accounts', capabilities: ['read'] },
+);
+
+// Your agent code calls these as normal. The runtime intercepts every call,
+// records tool_call → policy_check → tool_result in the audit log.
+const accounts = await listAccounts('schwab');
+
+// Hit the kill switch from anywhere — another async context, a signal, an
+// HTTP endpoint:
+await estop.press({ reason: 'operator manual halt', initiator: 'operator' });
+
+// Clean shutdown — flushes audit, attestation if configured:
+await runtime.close();
+```
+
+### Adding the v0.8 safety layer
+
+```typescript
+import {
+  AuditLogWriter,
+  EStopLocal,
+  GuardianRuntime,
+  httpAttestor,
+  defineHoneytokenSet,
+} from '@flowdot.ai/guardian-agent';
+
+const audit = new AuditLogWriter({
+  path: './audit.jsonl',
+  agentId: 'agent_demo',
+  sessionId: 'sess_quickstart',
+  // v0.8: external attestation
+  attestor: httpAttestor({ url: 'https://attestor.example/v1/heads' }),
+  attestEvery: 100,
+});
+const estop = new EStopLocal({ audit });
+const runtime = new GuardianRuntime({
+  agentId: 'agent_demo',
+  sessionId: 'sess_quickstart',
+  audit,
+  estop,
+  // v0.8: honeytokens
+  honeytokens: defineHoneytokenSet('production', [
+    { id: 'fake-aws', pattern: /AKIA[0-9A-Z]{16}/ },
+    { id: 'recovery-key', value: 'fd_recovery_canary_REPLACE_ME' },
+  ], ['delete_account_unsafe']),
+  // v0.8: capability rules (Yellow-only)
+  capabilityRules: [
+    {
+      id: 'exfil-shape',
+      combination: ['credential', 'network-egress', 'write'],
+      window_ms: 60_000,
+      level: 'yellow',
+    },
+  ],
+});
+```
+
+### v0.9: operator confirmation + heartbeat
+
+```typescript
+import {
+  GuardianRuntime,
+  callbackOperatorGate,
+  HeartbeatMonitor,
+} from '@flowdot.ai/guardian-agent';
+
+const runtime = new GuardianRuntime({
+  agentId: 'agent_demo',
+  sessionId: 'sess_quickstart',
+  audit,
+  estop,
+  operatorGate: callbackOperatorGate(async (req) => {
+    // Show req to a real human (UI modal, IPC, webhook) and return their decision.
+    const approved = await operatorUI.prompt(req);
+    return { decision: approved ? 'approved' : 'denied', operator_id: 'alice' };
+  }),
+  operatorTimeoutMs: 5 * 60_000,
+});
+
+const sensitiveTool = runtime.tool(
+  async () => doDangerousThing(),
+  {
+    name: 'wire_transfer',
+    capabilities: ['network-egress', 'credential'],
+    requiresOperatorConfirmation: true,
+    operatorConfirmationReason: 'sensitive_action',
+  },
+);
+
+// Heartbeat — opt-in. Surface MUST call heartbeat() from its main loop.
+const heartbeat = new HeartbeatMonitor({
+  softMs: 30_000,
+  hardMs: 90_000,
+  audit,
+  estop,
+});
+heartbeat.start();
+setInterval(() => heartbeat.heartbeat(), 10_000);
+```
+
+### Offline analysis
+
+```bash
+# Produce a per-agent_id statistical baseline
+node dist/cli/guardian-baseline.js ~/.flowdot/audit/cli.jsonl
+
+# Check a new session against the saved baseline
+node dist/cli/guardian-baseline.js ~/.flowdot/audit/cli.jsonl --check --sigma 3
+
+# Cross-surface correlation
+node dist/cli/guardian-correlator.js \
+  ~/.flowdot/audit/cli.jsonl:cli \
+  ~/.flowdot/audit/mcp.jsonl:mcp \
+  --out ~/.flowdot/audit/correlations.jsonl
+```
+
+See [`examples/quickstart.ts`](./examples/quickstart.ts) for a runnable version.
+
+## What it is NOT
+
+It is deliberately small. Not an agent harness. Not a platform. Not a workflow builder. Not an observability dashboard. Not a model evaluation suite. It is the supervisor primitive only.
+
+Some things the library deliberately does NOT do:
+
+- **Ship default honeytokens.** Library shipping plausible-looking fake credentials gets picked up by secret scanners + creates support load. Consumers register their own.
+- **Promote Red-line capability rules without telemetry.** Yellow-only until real-surface data shows zero organic fires.
+- **Use baselines as runtime tripwires.** Statistical anomaly detection is descriptive output, not a gate. Operator decides what to do.
+- **Reason about agent intent.** Every primitive is a deterministic predicate over inputs.
+
+## Relationship to FlowDot
+
+FlowDot's commercial platform — hub, CLI, native Electron app, mobile, MCP server — uses this library directly. FlowDot's `flowdot-cli` and `mcp-server` supervisors are thin per-surface glue around the library's `GuardianRuntime` + `AuditLogWriter` + `EStopLocal`. The runtime-safety layer (attestation / honeytokens / capability tripwires / two-key / heartbeat) is wired through both surfaces.
+
+The library itself is independent. Other Node-shaped agent projects can adopt the same supervisor primitives without depending on FlowDot's commercial stack.
+
+## Project status & roadmap
+
+Pre-alpha. Releases track the Python implementation milestone-for-milestone:
+
+- **v0.1 – v0.7** ✅ Audit log + signatures + policy + gates + estop + model-aware policy.
+- **v0.8** ✅ External attestation, honeytokens, capability tags + Yellow-line, per-capability rate limits.
+- **v0.9** ✅ Two-key operator auth, dead-man's heartbeat.
+- **v0.10** ✅ Offline `guardian-baseline` + `guardian-correlator` tools.
+- **v0.11+** — Red-line capability auto-stop (after Yellow telemetry calibration). Python port. Cross-language conformance corpus.
+- **v1.0** — Stable API, conformance suite in both languages, at least one production deployment outside FlowDot, published red-team study.
+
+Full plan: [ROADMAP.md](./ROADMAP.md). Canonical spec: [SPEC.md](https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md).
+
+## Verification + testing posture
+
+- **539 tests passing, 100% line + branch + function coverage** on the library.
+- **Negative-corpus harness** replays real production audit logs (`~/.flowdot/audit/{cli,mcp}.jsonl`) through every safety detector at default thresholds; required outcome is zero false positives, and the bar is met.
+- **No false E-stops, ever** is a hard rule. Any mechanism that could E-stop a session ships with thresholds calibrated against real-workload data.
+
+## License
+
+AGPL-3.0-or-later. See [LICENSE](./LICENSE).
+
+**Dual licensing.** FlowDot LLC, as sole copyright holder of this code, also licenses it under proprietary terms for use inside its own commercial products (`@flowdot.ai/cli`, `@flowdot.ai/mcp-server`, etc.). This is the standard open-core arrangement and does not affect downstream users — your obligations under AGPL-3.0 are exactly as written in [LICENSE](./LICENSE). If you want a commercial license for your own (non-FlowDot) use, contact `licensing@flowdot.ai`.
+
+## Citation
+
+```
+Mousseau, E. (2026). @flowdot.ai/guardian-agent: TypeScript reference
+implementation of the guardian-agent spec. v0.10.
+https://github.com/flowdot-llc/guardian-agent-ts
+```

package/ROADMAP.md

@@ -0,0 +1,109 @@
+# @flowdot.ai/guardian-agent — roadmap
+
+**Last updated**: 2026-05-14
+
+This package tracks the Python reference implementation milestone-for-milestone. The spec at [`flowdot-llc/guardian-agent/SPEC.md`](https://github.com/flowdot-llc/guardian-agent/blob/main/SPEC.md) is the canonical contract for both.
+
+## v0.1.0 — Package skeleton and audit log ✅
+
+- [x] Package scaffolding: `package.json`, `tsconfig.json`, AGPL-3.0 license, README.
+- [x] Public type surface matching the spec (`GuardianRuntime`, `Policy`, `GateRequest`, `GateResponse`, `ModelAttribution`).
+- [x] JSONL audit log writer with hash chain.
+- [x] `runtime.tool(fn, opts)` wrapper that records `tool_call` + `tool_result` events.
+- [x] Quickstart example.
+- [x] `vitest` suite exercising every record kind defined in spec §2.4.
+
+## v0.2.0 — Tool-permission scoping ✅
+
+- [x] YAML policy loader matching spec §3.
+- [x] Wildcard tool-name matching with specificity rules.
+- [x] `policy_check` event emission.
+- [x] Resolution order (banned > forever > session > once > default).
+
+## v0.3.0 — HITL approval gate ✅
+
+- [x] `cliApprovalGate` — synchronous-feeling stdin prompt.
+- [x] `asyncCallbackGate(url)` — POSTs `GateRequest`, awaits JSON response.
+- [x] `programmaticGate(handler)` — async handler.
+- [x] `dataChannelGate` — LiveKit-shaped wire frames.
+- [x] `allow_session` / `always_allow` semantics with policy file persistence.
+
+## v0.4.0 — Emergency-stop ✅
+
+- [x] `EStopLocal` API + audit emission.
+- [x] `EStopHub` adapter + middleware (HTTP 423 Locked).
+- [x] `EStopPoller` pull-based safety net.
+- [x] `AbortController`-style cross-async halt via `EStopLocal.abortSignal`.
+- [x] `GuardianHaltedError` class; audit log flush on halt.
+
+## v0.5.0 — Signed audit logs ✅
+
+- [x] ed25519 via Node's `crypto`.
+- [x] `guardian-verify` CLI for chain + signature integrity.
+- [x] Recovery hook on abnormal-shutdown re-open (`onTipRecovered` + `x_session_recovered`).
+
+## v0.6.0 — Model-aware policy ✅
+
+- [x] `PolicyWhen.model.provider` + `model.id` glob clauses (SPEC §3 open question resolved).
+- [x] `ModelAttribution` carried through the audit pipeline.
+
+## v0.7.0 — Attribution-path policy + custom gate options ✅
+
+- [x] `ModelAttribution` extended with `surface` + `aggregator` for the canonical chain `surface/aggregator/provider/id`.
+- [x] `PolicyWhen.attribution_path` — flat-glob matcher (`*` matches `/`).
+- [x] Custom `GateOptionSet` system (FLOWDOT_FIVE + CLASSIC_FOUR defaults + `defineGateOptionSet()`).
+
+## v0.8.0 — Runtime safety foundation ✅
+
+- [x] **External chain attestation** (SPEC §11) — `Attestor` interface, `httpAttestor` + `nullAttestor` reference adapters, fail-soft `x_chain_attested` / `x_chain_attestation_failed`.
+- [x] **Honeytokens** (SPEC §12) — value + phantom-tool matchers; zero-default-tokens by design.
+- [x] **Capability tags + Yellow-line tripwires** (SPEC §13) — canonical capability classes, `CapabilityWindow` sliding-window evaluator, audit-only Yellow events.
+- [x] **Per-capability rate limits** (SPEC §14) — `MultiRateLimiter` with `DEFAULT_BUCKETS` (credential=2/s, delete=1/s, etc.).
+
+## v0.9.0 — Operator gates ✅
+
+- [x] **Two-key operator authorization** (SPEC §15) — `OperatorConfirmationGate` interface, `callbackOperatorGate` + `denyAllOperatorGate` reference adapters, `gate_id` correlation across pending/approved/denied rows, timeout-as-denied.
+- [x] **Dead-man's heartbeat** (SPEC §16) — `HeartbeatMonitor` with soft + hard windows, opt-in (default OFF), `x_heartbeat_warning` + `estop_press { reason: 'heartbeat_missed' }`.
+
+## v0.10.0 — Offline analysis tools ✅
+
+- [x] **`guardian-baseline` CLI** (SPEC §17) — per-agent_id statistical profile + `--check` σ-deviation reports. Not a runtime tripwire.
+- [x] **`guardian-correlator` CLI** (SPEC §18) — overlapping sessions + args-hash collisions + sequence similarity, writes `x_cross_surface_match` JSONL to its own log.
+
+## v0.11+ — Red-line + Python port (next)
+
+- [ ] **Red-line capability rules** (SPEC §13.3) — promotion path from Yellow → Red after demonstrated zero organic fires in real-surface telemetry. Auto-presses EStop on fire.
+- [ ] **Python port** — faithful translation of every primitive to `guardian-agent` (Python). Same SPEC, same JSON corpus.
+- [ ] **Cross-language conformance corpus** — shared test fixtures both implementations must round-trip.
+- [ ] **Soak harness** — long-running real-workload replay producing the Yellow telemetry the Red-line promotion needs.
+
+## v1.0.0 — Stable
+
+Same exit criteria as Python v1.0.0:
+- [ ] No breaking spec changes for 90 days.
+- [ ] Conformance test suite passes in both languages.
+- [ ] At least one production deployment outside FlowDot.
+- [ ] Published red-team study citing this implementation.
+
+## Non-goals through v1.0
+
+- A web UI.
+- An HTTP server. The library exposes types and adapter callables; you bring your HTTP layer.
+- Bun/Deno-specific optimizations. Targeting Node 20+ LTS first.
+- Becoming an agent framework. Composes with LangChain.js, MCP clients, AutoGen-TS, native async fns.
+- Default honeytokens. Library never ships plausible-looking decoys; consumers register their own.
+- A baseline-as-runtime-tripwire. Statistical profiles are descriptive reports, not gates.
+
+## Sync with Python implementation
+
+The two repos release in lockstep when possible. If one ships a feature ahead of the other:
+
+- **Spec changes ship in the [Python repo](https://github.com/flowdot-llc/guardian-agent) first**, because that's where SPEC.md lives. The TS repo follows.
+- **Bug fixes can ship independently.**
+- **Conformance test fixtures are shared.** Both implementations run the same JSON test corpus from the spec repo.
+
+## Test counts (current)
+
+- guardian-agent-ts: **535/535** at **100% line + branch + function coverage**.
+- FlowDot surface integrations: mcp-server **153/153**, flowdot-cli **666/666**.
+- Negative-corpus harness (real `~/.flowdot/audit/{cli,mcp}.jsonl` replay) — zero false positives on every v0.8-v0.10 detector at default thresholds.

package/dist/audit/attestor.d.ts

@@ -0,0 +1,102 @@
+/**
+ * External chain attestation. SPEC §2.7 (v0.3.0+).
+ *
+ * Why this exists: the local audit log is hash-chained + ed25519-signed, but
+ * the writer's signing key lives on the same machine as the writer. If the
+ * runtime is fully compromised, an attacker can sign a fabricated chain just
+ * as easily as the legitimate writer. Attestation closes that gap by
+ * periodically publishing the current chain head + its signature to an
+ * external append-only store the local process cannot rewrite. A later
+ * verifier can cross-check the local chain against the external receipts;
+ * any divergence indicates tamper.
+ *
+ * The library defines the `Attestor` interface + a reference HTTP adapter.
+ * Production deployments may use S3 with object-lock + versioning, a
+ * Sigstore Rekor transparency log, or a second-party receiver. Library
+ * never assumes a specific backend.
+ *
+ * Failure mode: attestor errors are NEVER fatal. A failed attestation is
+ * itself an audit row (`x_chain_attestation_failed`). The supervisor
+ * continues. An adversary who can DoS the attestation endpoint cannot use
+ * that to halt the agent's session.
+ */
+import type { AuditRecord } from '../types.js';
+/**
+ * Payload sent to the attestor for one attestation event. The `head` is the
+ * hash of the most-recently-appended record (NOT a synthesized commitment).
+ * `signature` is the signature of that record. `recordCount` is the total
+ * number of records appended to the chain in this session up to and
+ * including the head record.
+ */
+export interface AttestationPayload {
+    /** Agent id, mirrors the audit record's `agent_id`. */
+    agentId: string;
+    /** Session id, mirrors the audit record's `session_id`. */
+    sessionId: string;
+    /** `sha256:<hex>` of the canonical-JSON of the head record. */
+    head: string;
+    /** Head record's `ed25519:<base64url>` signature (when signing is enabled). */
+    signature: string | null;
+    /** Total records appended in this session through the head. */
+    recordCount: number;
+    /** ISO-8601 timestamp at which the attestation was emitted. */
+    ts: string;
+    /** Schema version of the payload itself; bumped on incompatible changes. */
+    v: '1';
+}
+/**
+ * Receipt the attestor MAY return. When provided, the receipt id is recorded
+ * on the local `x_chain_attested` audit row, letting verifiers correlate
+ * external receipts with local chain heads.
+ */
+export interface AttestationReceipt {
+    /** Attestor-assigned id (URL fragment, Rekor log index, S3 version id...). */
+    receiptId: string;
+    /** Optional URL where the receipt can be inspected. */
+    url?: string;
+}
+/**
+ * The contract a consumer implements (or wires from a reference adapter).
+ * One method, takes a payload, returns a receipt or throws.
+ */
+export interface Attestor {
+    /**
+     * Publish an attestation. Implementations MUST NOT mutate `payload`.
+     * Implementations MAY return synchronously or asynchronously.
+     *
+     * Throwing here is an expected failure mode; callers (AuditLogWriter)
+     * catch and convert to `x_chain_attestation_failed` audit rows.
+     */
+    publish(payload: AttestationPayload): Promise<AttestationReceipt> | AttestationReceipt;
+}
+export interface HttpAttestorOptions {
+    /** Endpoint URL. The attestor POSTs the JSON payload here. */
+    url: string;
+    /** Optional headers (auth bearer, content-type override, etc.). */
+    headers?: Record<string, string>;
+    /** Request timeout in ms. Default 5000. */
+    timeoutMs?: number;
+    /** Optional fetch implementation override (testing). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Reference HTTP attestor: POSTs the payload as JSON, expects a JSON
+ * `{ receiptId, url? }` response. 2xx → success; anything else → throws.
+ *
+ * This adapter is INTENTIONALLY MINIMAL. Production deployments will want
+ * retries, auth refresh, content-addressed bodies, etc. — those belong in
+ * the consumer's adapter, not the library.
+ */
+export declare function httpAttestor(options: HttpAttestorOptions): Attestor;
+/**
+ * No-op attestor that returns synthetic receipts. Use in tests, or when a
+ * consumer wants the supervisor to log `x_chain_attested` rows for audit
+ * shape parity without actually publishing externally.
+ */
+export declare function nullAttestor(): Attestor;
+/**
+ * Build the canonical payload from a head record + the running record count.
+ * Pure: same inputs → same payload. Exposed for tests.
+ */
+export declare function payloadFromRecord(record: AuditRecord, recordCount: number, headHash: string): AttestationPayload;
+//# sourceMappingURL=attestor.d.ts.map

package/dist/audit/attestor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestor.d.ts","sourceRoot":"","sources":["../../src/audit/attestor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAC;IACX,4EAA4E;IAC5E,CAAC,EAAE,GAAG,CAAC;CACR;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;CACxF;AAMD,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,QAAQ,CAkCnE;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,QAAQ,CAQvC;AAMD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,kBAAkB,CAUpB"}

package/dist/audit/attestor.js

@@ -0,0 +1,103 @@
+/**
+ * External chain attestation. SPEC §2.7 (v0.3.0+).
+ *
+ * Why this exists: the local audit log is hash-chained + ed25519-signed, but
+ * the writer's signing key lives on the same machine as the writer. If the
+ * runtime is fully compromised, an attacker can sign a fabricated chain just
+ * as easily as the legitimate writer. Attestation closes that gap by
+ * periodically publishing the current chain head + its signature to an
+ * external append-only store the local process cannot rewrite. A later
+ * verifier can cross-check the local chain against the external receipts;
+ * any divergence indicates tamper.
+ *
+ * The library defines the `Attestor` interface + a reference HTTP adapter.
+ * Production deployments may use S3 with object-lock + versioning, a
+ * Sigstore Rekor transparency log, or a second-party receiver. Library
+ * never assumes a specific backend.
+ *
+ * Failure mode: attestor errors are NEVER fatal. A failed attestation is
+ * itself an audit row (`x_chain_attestation_failed`). The supervisor
+ * continues. An adversary who can DoS the attestation endpoint cannot use
+ * that to halt the agent's session.
+ */
+/**
+ * Reference HTTP attestor: POSTs the payload as JSON, expects a JSON
+ * `{ receiptId, url? }` response. 2xx → success; anything else → throws.
+ *
+ * This adapter is INTENTIONALLY MINIMAL. Production deployments will want
+ * retries, auth refresh, content-addressed bodies, etc. — those belong in
+ * the consumer's adapter, not the library.
+ */
+export function httpAttestor(options) {
+    const url = options.url;
+    const headers = options.headers ?? {};
+    const timeoutMs = options.timeoutMs ?? 5000;
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new Error('httpAttestor: global fetch is not available; supply fetchImpl');
+    }
+    return {
+        async publish(payload) {
+            const controller = new AbortController();
+            const t = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const res = await fetchImpl(url, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json', ...headers },
+                    body: JSON.stringify(payload),
+                    signal: controller.signal,
+                });
+                if (!res.ok) {
+                    throw new Error(`httpAttestor: ${res.status} ${res.statusText}`);
+                }
+                const body = (await res.json());
+                if (!body.receiptId || typeof body.receiptId !== 'string') {
+                    throw new Error('httpAttestor: response missing receiptId');
+                }
+                const r = { receiptId: body.receiptId };
+                if (typeof body.url === 'string')
+                    r.url = body.url;
+                return r;
+            }
+            finally {
+                clearTimeout(t);
+            }
+        },
+    };
+}
+// ============================================================================
+// nullAttestor — for tests and explicit-disable scenarios
+// ============================================================================
+/**
+ * No-op attestor that returns synthetic receipts. Use in tests, or when a
+ * consumer wants the supervisor to log `x_chain_attested` rows for audit
+ * shape parity without actually publishing externally.
+ */
+export function nullAttestor() {
+    let n = 0;
+    return {
+        publish() {
+            n += 1;
+            return { receiptId: `null-${n}` };
+        },
+    };
+}
+// ============================================================================
+// Helper: build a payload from a record + count.
+// ============================================================================
+/**
+ * Build the canonical payload from a head record + the running record count.
+ * Pure: same inputs → same payload. Exposed for tests.
+ */
+export function payloadFromRecord(record, recordCount, headHash) {
+    return {
+        agentId: record.agent_id,
+        sessionId: record.session_id,
+        head: headHash,
+        signature: record.signature ?? null,
+        recordCount,
+        ts: new Date().toISOString(),
+        v: '1',
+    };
+}
+//# sourceMappingURL=attestor.js.map

package/dist/audit/attestor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestor.js","sourceRoot":"","sources":["../../src/audit/attestor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAsEH;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4B;IACvD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IACxB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACtC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAC5C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC;IACxD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;IACnF,CAAC;IACD,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,OAA2B;YACvC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;YAC1D,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;oBAC/B,MAAM,EAAE,MAAM;oBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,OAAO,EAAE;oBAC3D,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;oBAC7B,MAAM,EAAE,UAAU,CAAC,MAAM;iBAC1B,CAAC,CAAC;gBACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;oBACZ,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;gBACnE,CAAC;gBACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAgC,CAAC;gBAC/D,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;oBAC1D,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;gBAC9D,CAAC;gBACD,MAAM,CAAC,GAAuB,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;gBAC5D,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ;oBAAE,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;gBACnD,OAAO,CAAC,CAAC;YACX,CAAC;oBAAS,CAAC;gBACT,YAAY,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,0DAA0D;AAC1D,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO;QACL,OAAO;YACL,CAAC,IAAI,CAAC,CAAC;YACP,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,iDAAiD;AACjD,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAmB,EACnB,WAAmB,EACnB,QAAgB;IAEhB,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,QAAQ;QACxB,SAAS,EAAE,MAAM,CAAC,UAAU;QAC5B,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI;QACnC,WAAW;QACX,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,CAAC,EAAE,GAAG;KACP,CAAC;AACJ,CAAC"}