Skip to content
Crosswalker
🚧 Early alpha — building the foundation. See the roadmap →

v0.1.8 — Audit trail T1 default

Updated

Implement the v0.1 audit trail floor — Tier 1 = git commits + Ed25519-signed releases for shared mapping bundles + auto-generated FRE 902(13) certification PDF available on demand. Per Ch 08 synthesis (audit-trail tenability) + v0.1 stack pivot §8 + Ch 15 4-tier audit model.

Status

Section titled “Status”

📋 Planning

Dependencies

Section titled “Dependencies”

Scope

Section titled “Scope”

In:

  • Git-commit-on-write hook — every Tier 1 generation pass produces one commit; commit message includes recipe ID + recipe hash + concept count + summary diff
  • Ed25519 release-manifest signing — when a user publishes a Tier 1 bundle, optionally sign with their Ed25519 key; signature lives in _crosswalker_manifest.json at vault root
  • FRE 902(13) PDF certification — on-demand generation of a compliance-export certification template suitable for evidence submission in US litigation
  • Settings toggle — “Sign on commit” + key-management UX (point at git config or OS keychain; don’t reinvent)
  • Logging-infrastructure production-hardening sub-phase — the wide-event NDJSON substrate from Phase 3.5a/b/c is the same shape as the audit trail itself ({ts, level, category, op, msg, trace_id, ...}). Consolidate them into one substrate. See dedicated section below.

Out:

  • T2 / T3 audit profiles (OpenTimestamps, RFC 3161, Sigstore Rekor v2 + in-toto, eIDAS QTSA + W3C VC) — opt-in compliance-export mode for v1.0+
  • PQC dual-sign migration — 2027+ work per NIST IR 8547 timeline

Concrete tasks

Section titled “Concrete tasks”

Audit trail (primary scope)

Section titled “Audit trail (primary scope)”
  • Git integration — src/audit/git-commit.ts; uses simple-git or shells out to system git; produces deterministic commit messages
  • Ed25519 sign helper — src/audit/sign.ts; @noble/curves or equivalent; uses key from settings (path-to-PEM or OS keychain reference)
  • Release manifest writer — _crosswalker_manifest.json at vault root; includes recipe IDs + recipe hashes + Ed25519 signatures
  • FRE 902(13) PDF template — src/audit/fre-902.ts; produces a one-page PDF using pdf-lib or equivalent; includes vault hash, signed manifest, signer identity
  • Settings UI — toggle for “Sign on commit”; key-source selector (git config, file path, keychain)
  • Tests — sign + verify roundtrip; commit-on-write produces consistent message; FRE 902(13) renders without errors

Logging-infrastructure production-hardening sub-phase

Section titled “Logging-infrastructure production-hardening sub-phase”

Rationale: the audit trail and the wide-event debug log are the same substrate. Phase 3.5a/b/c shipped a solid NDJSON wide-event logger (src/utils/debug.ts, 422 LOC, trace correlation via withTrace, categories, levels). For v0.1.8 we promote it from “debug-only” to “production-grade observability” by closing four gaps surfaced during Phase 4.5 testing (2026-05-18):

  • Bundle stripping — add esbuild define flag (__DEBUG__); wrap trace/info-level emit sites in if (__DEBUG__); production build (bun run build) strips the verbose emit code, keeping only error/warn paths. Bundle audit before vs. after — current main.js is ~650KB; target 50KB+ reduction.
  • Log rotation — cap at MAX_LOG_LINES setting (default ~10k); when exceeded, archive oldest half to crosswalker-debug.log.1 and truncate primary file. Prevents indefinite growth in long-lived vaults.
  • Settings surface — expose logLevel: 'error' | 'warn' | 'info' | 'trace' dropdown in settings tab; default info. Power users + bug reporters can crank to trace; everyone else gets quiet logs.
  • “Copy redacted log slice for bug report” command — palette command that grabs the last N events, scrubs absolute paths + usernames + email-shaped strings, and copies the JSON array to clipboard. Lowers OSS issue-triage friction.
  • Audit-log promotion — the audit-trail events from this milestone (audit/commit-written, audit/signed, audit/manifest-published) emit through the same DebugLog substrate but to a separate crosswalker-audit.log file (NDJSON, non-rotating, non-stripped). One logger, two output streams — same JSON shape both places.

Total estimated effort: ~6 hours (separate commit from the audit-trail primary work).

Success criteria

Section titled “Success criteria”
  • Every successful generation pass produces exactly one git commit with deterministic message
  • Signed releases verify cleanly with openssl or gpg --verify (depending on signature format)
  • FRE 902(13) PDF includes all required fields per the FRE 902(13) statutory text
  • Settings toggle off → no signing (opt-in)
  • No Tier 2/Tier 3 audit dependencies in v0.1.8 — all that’s deferred to opt-in compliance-export mode
  • Logging sub-phase: production main.js size drops measurably after __DEBUG__ stripping; log rotation prevents crosswalker-debug.log from growing past MAX_LOG_LINES; logLevel setting works end-to-end; “Copy redacted log slice” command produces clipboard JSON with no absolute paths or usernames

Files to touch

Section titled “Files to touch”
  • src/audit/git-commit.ts — new
  • src/audit/sign.ts — new
  • src/audit/fre-902.ts — new (PDF template)
  • src/audit/manifest.ts — new (_crosswalker_manifest.json writer)
  • src/main.ts — wire commit hook to generation events
  • src/settings/settings-tab.ts — new audit section
  • tests/audit/sign-verify.test.ts — new

Open questions

Section titled “Open questions”
  • Do we shell out to system git, or use a JS library? simple-git exists but adds a dep. Shell-out is closer to user expectations; library is more portable across environments
  • Key management UX — referencing a file path vs. integrating with macOS Keychain / Windows Credential Manager / Linux secret-service. Pick one v0.1 default; cross-platform parity is v1.0+
  • FRE 902(13) PDF — fully programmatic via pdf-lib, or a templated approach (JSX-PDF / hbs)?
Section titled “Related”

Concept pages:

Agent context:

  • Vision — file-based canonical state enables git-native audit
  • Tradeoffs — T1 (git) vs. T2 (OpenTimestamps/RFC 3161) vs. T3 (Sigstore Rekor + in-toto, eIDAS QTSA)
  • Decisions

Design decisions (synthesis logs):

Research deliverables:

External references:

Other milestones: