@occasiolabs/occasio 0.8.1

package/src/attest/sign.js

@@ -0,0 +1,186 @@
+'use strict';
+
+/**
+ * sign.js — wrap a Occasio Phase-0 attestation in an in-toto Statement v1
+ * envelope and Sigstore-sign it keyless. Outputs (a) a populated
+ * `signature` object to inline in the predicate JSON, and (b) the Sigstore
+ * Bundle as a sidecar file for cryptographic verification.
+ *
+ * Two signing modes:
+ *   - 'ci'   — GitHub Actions OIDC. Reads ACTIONS_ID_TOKEN_REQUEST_URL /
+ *              ACTIONS_ID_TOKEN_REQUEST_TOKEN and exchanges for a Sigstore
+ *              identity token. The standard CI flow.
+ *   - 'token'— `--oidc-token <jwt>` was provided explicitly (CI-emulate
+ *              for tests + manual runs).
+ *
+ * No local browser flow in Phase 1 by design (see plan: lokaler Browser-Flow
+ * wird später nachgerüstet falls Bedarf da ist).
+ *
+ * The function is decoupled from sigstore-js via lazy require so tests can
+ * stub the module without paying its import cost on every CLI invocation.
+ */
+
+const crypto = require('crypto');
+const { canonicalize } = require('./canonicalize');
+
+const PREDICATE_TYPE =
+  'https://github.com/occasiolabs/occasio/spec/agent-attestation/v1';
+const STATEMENT_TYPE     = 'https://in-toto.io/Statement/v1';
+const DSSE_PAYLOAD_TYPE  = 'application/vnd.in-toto+json';
+const SIGSTORE_AUDIENCE  = 'sigstore';
+
+// ── in-toto Statement envelope ───────────────────────────────────────────────
+
+/**
+ * Build the in-toto Statement v1 that will be signed. The `subject` carries
+ * the audit-chain commitment: `last_hash` is itself a SHA-256 over the entire
+ * run-id slice (each prev_hash chains back to GENESIS), so signing it commits
+ * cryptographically to every event in the slice.
+ */
+function buildInTotoStatement(attestation) {
+  if (!attestation || !attestation.audit_chain || !attestation.audit_chain.last_hash) {
+    throw new Error('sign: attestation has no audit_chain.last_hash — refusing to sign an empty slice');
+  }
+  // The predicate JSON we sign should NOT carry a placeholder `signature` field;
+  // signature metadata is filled into the predicate AFTER signing succeeds.
+  const { signature: _omit, ...predicate } = attestation;
+
+  return {
+    _type:         STATEMENT_TYPE,
+    predicateType: PREDICATE_TYPE,
+    subject: [
+      {
+        name:   `occasio:run:${attestation.subject.run_id}`,
+        digest: { sha256: attestation.audit_chain.last_hash },
+      },
+    ],
+    predicate,
+  };
+}
+
+// ── OIDC token acquisition ───────────────────────────────────────────────────
+
+/**
+ * Fetch a Sigstore-audience identity token from the GitHub Actions OIDC
+ * provider. Requires `permissions: id-token: write` in the workflow.
+ * Returns the JWT string.
+ */
+async function fetchGithubActionsToken() {
+  const url      = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
+  const reqToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+  if (!url || !reqToken) {
+    throw new Error(
+      "sign: GitHub Actions OIDC env vars missing. " +
+      "Workflow needs `permissions: id-token: write`. " +
+      "Vars: ACTIONS_ID_TOKEN_REQUEST_URL, ACTIONS_ID_TOKEN_REQUEST_TOKEN."
+    );
+  }
+  const fetchUrl = `${url}&audience=${encodeURIComponent(SIGSTORE_AUDIENCE)}`;
+  const res = await fetch(fetchUrl, {
+    headers: { Authorization: `Bearer ${reqToken}` },
+  });
+  if (!res.ok) {
+    throw new Error(`sign: OIDC token request failed: ${res.status} ${res.statusText}`);
+  }
+  const body = await res.json();
+  if (!body || typeof body.value !== 'string') {
+    throw new Error('sign: OIDC token response missing `value`');
+  }
+  return body.value;
+}
+
+// ── identity decoding (best-effort, no signature check) ──────────────────────
+
+/**
+ * Decode the OIDC JWT payload for the `iss` + `sub` claims. We only use these
+ * for the human-readable `signature.identity` field — the cryptographic
+ * binding is in the Sigstore certificate, not here. Best-effort: if decoding
+ * fails we fall back to `'unknown'`.
+ */
+function decodeIdentity(jwt) {
+  try {
+    const parts = jwt.split('.');
+    const claims = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    if (claims.sub) return claims.sub;        // GitHub: workflow ref
+    if (claims.iss && claims.email) return `${claims.iss}#${claims.email}`;
+    return claims.iss || 'unknown';
+  } catch { return 'unknown'; }
+}
+
+// ── Bundle parsing (extract Rekor entry URL for human display) ───────────────
+
+function extractRekorEntry(bundle) {
+  try {
+    const entry = bundle?.verificationMaterial?.tlogEntries?.[0];
+    if (!entry || !entry.logIndex) return null;
+    // Public Rekor instance URL format. Private Sigstore deployments would
+    // need a different base URL — Phase 1 supports public-good only.
+    return `https://search.sigstore.dev/?logIndex=${entry.logIndex}`;
+  } catch { return null; }
+}
+
+// ── public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Sign an attestation. Returns { bundle, signatureBlock, statementJSON }.
+ *
+ *   ctx.oidcToken         — explicit JWT (token-mode); takes precedence
+ *   ctx.signMode          — 'ci' | 'token' (auto-detected if absent)
+ *   ctx.sigstoreModule    — DI for tests; defaults to require('sigstore')
+ *   ctx.now               — DI for tests; defaults to () => new Date()
+ *   ctx.tlogUpload        — default true (Rekor log entry). Set false in tests.
+ */
+async function signAttestation(attestation, ctx = {}) {
+  const statement = buildInTotoStatement(attestation);
+  // Canonical JSON: makes byte-equivalence in verify.js deterministic across
+  // runtime versions and re-serialisation steps. The verifier re-canonicalises
+  // the parsed predicate from the bundle before comparing — both sides agree.
+  const statementJSON = canonicalize(statement);
+  const payload = Buffer.from(statementJSON, 'utf8');
+
+  // Token acquisition
+  let identityToken;
+  let mode = ctx.signMode;
+  if (ctx.oidcToken) {
+    identityToken = ctx.oidcToken;
+    mode = mode || 'token';
+  } else {
+    mode = mode || (process.env.GITHUB_ACTIONS === 'true' ? 'ci' : null);
+    if (mode !== 'ci') {
+      throw new Error(
+        "sign: no OIDC token. Pass --oidc-token <jwt> or run inside " +
+        "GitHub Actions with `permissions: id-token: write`."
+      );
+    }
+    identityToken = await fetchGithubActionsToken();
+  }
+
+  // Sigstore sign (keyless)
+  const sigstore = ctx.sigstoreModule || require('sigstore');
+  const bundle = await sigstore.attest(payload, DSSE_PAYLOAD_TYPE, {
+    identityToken,
+    tlogUpload: ctx.tlogUpload !== false,
+  });
+
+  const now = (ctx.now ? ctx.now() : new Date()).toISOString();
+  const signatureBlock = {
+    type:            'sigstore-cosign-keyless',
+    identity:        decodeIdentity(identityToken),
+    rekor_entry:     extractRekorEntry(bundle),
+    signed_at:       now,
+    envelope_sha256: crypto.createHash('sha256').update(payload).digest('hex'),
+  };
+
+  return { bundle, signatureBlock, statementJSON };
+}
+
+module.exports = {
+  signAttestation,
+  buildInTotoStatement,
+  PREDICATE_TYPE,
+  STATEMENT_TYPE,
+  DSSE_PAYLOAD_TYPE,
+  // for tests
+  _decodeIdentity: decodeIdentity,
+  _extractRekorEntry: extractRekorEntry,
+};

package/src/attest/verify.js

@@ -0,0 +1,192 @@
+'use strict';
+
+/**
+ * verify.js — re-verify a signed Occasio Agent Attestation end-to-end.
+ *
+ * Three independent checks, in order — each must pass:
+ *   1. Sigstore bundle is cryptographically valid against Fulcio/Rekor.
+ *   2. The DSSE payload inside the bundle parses as an in-toto Statement v1
+ *      whose `predicate` field, when re-stringified, matches the attestation
+ *      JSON we hold (modulo the `signature` field, which is metadata-only and
+ *      excluded before comparison).
+ *   3. The audit chain (`chain_file` in the attestation) verifies via the
+ *      same walker that `occasio audit verify` uses, AND the
+ *      `first_hash`/`last_hash` claimed in the attestation exist in that
+ *      chain in the correct order.
+ *
+ * Returns:
+ *   { ok, checks: [{ name, ok, detail }], identity, rekor_entry }
+ *
+ * Phase 1 keeps the verifier strict: any failure → ok:false. Callers (CLI,
+ * View-Evidence page) render the `checks` list verbatim — no aggregation.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { verifyFile } = require('../audit/verifier');
+const { DSSE_PAYLOAD_TYPE, PREDICATE_TYPE } = require('./sign');
+const { canonicalize } = require('./canonicalize');
+
+/**
+ * Verify a saved attestation pair.
+ *
+ *   attestationPath — path to the predicate JSON (Phase-0 / Phase-1 shape)
+ *   bundlePath      — path to the Sigstore Bundle sidecar
+ *   ctx.sigstoreModule  — DI for tests
+ */
+async function verifyAttestation(attestationPath, bundlePath, ctx = {}) {
+  const checks = [];
+  let identity = null, rekor_entry = null;
+
+  // Load both files up front; surface any I/O failure as the first check.
+  let attestation, bundle;
+  try {
+    attestation = JSON.parse(fs.readFileSync(attestationPath, 'utf8'));
+  } catch (e) {
+    checks.push({ name: 'read attestation', ok: false, detail: e.message });
+    return { ok: false, checks, identity, rekor_entry };
+  }
+  try {
+    bundle = JSON.parse(fs.readFileSync(bundlePath, 'utf8'));
+  } catch (e) {
+    checks.push({ name: 'read bundle', ok: false, detail: e.message });
+    return { ok: false, checks, identity, rekor_entry };
+  }
+
+  // ── 1. Sigstore signature ───────────────────────────────────────────────
+  try {
+    const sigstore = ctx.sigstoreModule || require('sigstore');
+    // sigstore.verify with no data arg verifies the bundle's embedded payload.
+    await sigstore.verify(bundle);
+    checks.push({ name: 'sigstore signature', ok: true });
+    // Surface the Fulcio identity for human display (not for trust decisions —
+    // sigstore.verify already enforced the cert chain).
+    rekor_entry = (() => {
+      try { return bundle.verificationMaterial?.tlogEntries?.[0]?.logIndex || null; }
+      catch { return null; }
+    })();
+    identity = attestation?.signature?.identity || null;
+  } catch (e) {
+    checks.push({ name: 'sigstore signature', ok: false, detail: e.message });
+    return { ok: false, checks, identity, rekor_entry };
+  }
+
+  // ── 2. DSSE payload ↔ attestation predicate equivalence ────────────────
+  try {
+    const env = bundle.dsseEnvelope;
+    if (!env || !env.payload) throw new Error('bundle missing dsseEnvelope.payload');
+    if (env.payloadType !== DSSE_PAYLOAD_TYPE) {
+      throw new Error(`unexpected payloadType: ${env.payloadType}`);
+    }
+    const stmtJson = Buffer.from(env.payload, 'base64').toString('utf8');
+    const stmt = JSON.parse(stmtJson);
+
+    if (stmt.predicateType !== PREDICATE_TYPE) {
+      throw new Error(`unexpected predicateType: ${stmt.predicateType}`);
+    }
+    // Recompute what we WOULD have signed for this attestation, ignoring the
+    // signature metadata field. Canonical JSON on both sides — any key-order
+    // or whitespace divergence between runtimes/versions becomes invisible,
+    // and only real semantic mismatches surface.
+    const { signature: _omit, ...predicateExpected } = attestation;
+    if (canonicalize(stmt.predicate) !== canonicalize(predicateExpected)) {
+      throw new Error('attestation predicate differs from DSSE payload predicate');
+    }
+    checks.push({ name: 'bundle payload matches attestation', ok: true });
+  } catch (e) {
+    checks.push({ name: 'bundle payload matches attestation', ok: false, detail: e.message });
+    return { ok: false, checks, identity, rekor_entry };
+  }
+
+  // ── 3. Audit chain integrity + hash commitments ─────────────────────────
+  try {
+    const chainFile = attestation?.audit_chain?.chain_file;
+    if (!chainFile) throw new Error('attestation missing audit_chain.chain_file');
+    if (!fs.existsSync(chainFile)) throw new Error(`chain file not found: ${chainFile}`);
+
+    const ver = verifyFile(chainFile);
+    if (!ver.ok) {
+      throw new Error(`chain broken at line(s): ${(ver.errors || []).map(e => e.line).join(', ')}`);
+    }
+
+    // Confirm the claimed first/last hashes actually appear in the chain in
+    // the right relative order. Walk lines once; reuse existing readJsonl path.
+    const lines = fs.readFileSync(chainFile, 'utf8').split('\n').filter(Boolean);
+    let firstIdx = -1, lastIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+      let row;
+      try { row = JSON.parse(lines[i]); } catch { continue; }
+      if (row.hash === attestation.audit_chain.first_hash && firstIdx === -1) firstIdx = i;
+      if (row.hash === attestation.audit_chain.last_hash) lastIdx = i;
+    }
+    if (firstIdx === -1) throw new Error(`first_hash not found in chain`);
+    if (lastIdx  === -1) throw new Error(`last_hash not found in chain`);
+    if (lastIdx < firstIdx) throw new Error(`last_hash precedes first_hash in chain`);
+
+    checks.push({ name: 'audit chain integrity', ok: true,
+      detail: `chain_length=${ver.chained}, slice rows ${firstIdx + 1}..${lastIdx + 1}` });
+  } catch (e) {
+    checks.push({ name: 'audit chain integrity', ok: false, detail: e.message });
+    return { ok: false, checks, identity, rekor_entry };
+  }
+
+  return {
+    ok: checks.every(c => c.ok),
+    checks, identity, rekor_entry,
+  };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+async function runAttestVerifyCli(args) {
+  args = args || [];
+  if (args.length === 0 || args[0].startsWith('-') && args[0] !== '--help') {
+    process.stderr.write('Usage: occasio attest verify <attestation.json> [--bundle <path>]\n');
+    process.exit(2);
+  }
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(
+      'Usage: occasio attest verify <attestation.json> [--bundle <path>]\n' +
+      '\n' +
+      'Default bundle path: <attestation>.sigstore.json (sidecar convention).\n'
+    );
+    return;
+  }
+  const attestationPath = path.resolve(args[0]);
+  const bundleIdx = args.indexOf('--bundle');
+  const bundlePath = bundleIdx >= 0
+    ? path.resolve(args[bundleIdx + 1])
+    : attestationPath.replace(/\.json$/i, '') + '.sigstore.json';
+
+  const col = {
+    g: s => `\x1b[32m${s}\x1b[0m`,
+    r: s => `\x1b[31m${s}\x1b[0m`,
+    d: s => `\x1b[2m${s}\x1b[0m`,
+    b: s => `\x1b[1m${s}\x1b[0m`,
+  };
+
+  process.stdout.write(`${col.b('Verifying')} ${attestationPath}\n`);
+  process.stdout.write(`  bundle: ${bundlePath}\n\n`);
+
+  let result;
+  try {
+    result = await verifyAttestation(attestationPath, bundlePath);
+  } catch (e) {
+    process.stderr.write(`${col.r('✗')} verify crashed: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  for (const c of result.checks) {
+    const mark = c.ok ? col.g('✓') : col.r('✗');
+    process.stdout.write(`  ${mark} ${c.name}`);
+    if (c.detail) process.stdout.write(`  ${col.d(c.detail)}`);
+    process.stdout.write('\n');
+  }
+  if (result.identity)    process.stdout.write(`\n  ${col.d('identity:')}    ${result.identity}\n`);
+  if (result.rekor_entry) process.stdout.write(`  ${col.d('rekor index:')} ${result.rekor_entry}\n`);
+
+  process.exit(result.ok ? 0 : 1);
+}
+
+module.exports = { verifyAttestation, runAttestVerifyCli };

package/src/audit/errors.js

@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+ * Audit-layer error classes.
+ *
+ * AuditWriteError signals that the auditor could not append a row to its
+ * sink. v0.6.4 treats this as session-fatal — see src/index.js's request
+ * handler for the abort behaviour. The dropped row is attached so a
+ * supervisor / log scraper can recover it from stderr if needed.
+ */
+
+class AuditWriteError extends Error {
+  constructor(cause, droppedRow) {
+    super(`audit write failed: ${cause && cause.message ? cause.message : cause}`);
+    this.name        = 'AuditWriteError';
+    this.cause       = cause;
+    this.droppedRow  = droppedRow;
+  }
+}
+
+module.exports = { AuditWriteError };

package/src/audit/input-normalizer.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * Audit input normalizer (ARCH-27).
+ *
+ * Produces a safe, governance-useful `tool_inputs` object for each tool call.
+ * The guiding principle: log file-system metadata (what was accessed, where),
+ * never log content-search strings or anything that could be a credential value.
+ *
+ * Per-tool scope:
+ *   read_file       → { path }                           resolved absolute path
+ *   find_files      → { pattern?, path? }                glob pattern only if structurally a glob
+ *   grep            → { path?, glob? }                   pattern OMITTED intentionally
+ *   todo_write      → { count }                          item count only, no content
+ *   todo_read       → (absent)
+ *   shell tools     → (absent)
+ *   all others      → (absent)
+ */
+
+const os   = require('os');
+const path = require('path');
+const { scanSecrets, redactSecrets } = require('../analyzer');
+
+// Glob metacharacters that distinguish structural patterns from content strings.
+const GLOB_META = /[*?[{!]/;
+
+/**
+ * Normalize tool inputs to a safe, loggable shape.
+ *
+ * @param {string} toolName   Canonical tool name (e.g. 'read_file')
+ * @param {object} toolInput  Raw tool input from the BoundaryEvent
+ * @returns {object|undefined}  Safe input object, or undefined if nothing to log
+ */
+function normalizeToolInputsForAudit(toolName, toolInput) {
+  if (!toolInput) return undefined;
+
+  switch (toolName) {
+    case 'read_file': {
+      const raw = toolInput.file_path;
+      if (typeof raw !== 'string' || !raw) return undefined;
+      const resolved = expandAndResolve(raw);
+      const { value: masked, wasMasked } = scanAndMask(resolved);
+      const out = { path: masked };
+      if (wasMasked) out.path_masked = true;
+      return out;
+    }
+
+    case 'find_files': {
+      const rawPattern = toolInput.pattern;
+      const rawPath    = toolInput.path;
+      const out = {};
+
+      if (typeof rawPattern === 'string' && rawPattern) {
+        // Only log if it looks like a real glob (has metacharacters) or is short enough
+        // to be safe. A long string with no glob syntax is likely a content string.
+        if (GLOB_META.test(rawPattern) || rawPattern.length <= 80) {
+          const { value: masked, wasMasked } = scanAndMask(rawPattern);
+          out.pattern = masked;
+          if (wasMasked) out.pattern_masked = true;
+        }
+        // else: no metacharacters AND > 80 chars → omit (outside safe envelope)
+      }
+
+      if (typeof rawPath === 'string' && rawPath) {
+        out.path = expandAndResolve(rawPath);
+      }
+
+      return Object.keys(out).length ? out : undefined;
+    }
+
+    case 'grep': {
+      // Pattern intentionally omitted — free-form search strings can contain
+      // arbitrary sensitive content the built-in scanner cannot bound.
+      // Log only WHERE the agent searched (path + file-filter).
+      const out = {};
+      const rawPath = toolInput.path;
+      const rawGlob = toolInput.glob;
+
+      if (typeof rawPath === 'string' && rawPath) {
+        out.path = expandAndResolve(rawPath);
+      }
+      if (typeof rawGlob === 'string' && rawGlob) {
+        out.glob = rawGlob;
+      }
+
+      return Object.keys(out).length ? out : undefined;
+    }
+
+    case 'todo_write': {
+      const count = Array.isArray(toolInput.todos) ? toolInput.todos.length : 0;
+      return { count };
+    }
+
+    // todo_read, shell_bash, shell_powershell, unknown tools → nothing to log
+    default:
+      return undefined;
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/** Expand leading ~ and path.resolve to absolute. */
+function expandAndResolve(p) {
+  if (typeof p !== 'string') return p;
+  const expanded = p.startsWith('~') ? os.homedir() + p.slice(1) : p;
+  return path.resolve(expanded);
+}
+
+/**
+ * Scan a short string (path, pattern) for embedded secrets.
+ * Returns the original value if clean, or a redacted version if a hit was found.
+ * This is a safeguard for edge cases (e.g., a filename that IS a token); it is
+ * not expected to fire under normal use.
+ */
+function scanAndMask(value) {
+  const hits = scanSecrets(value);
+  if (!hits || hits.length === 0) return { value, wasMasked: false };
+  return { value: redactSecrets(value), wasMasked: true };
+}
+
+module.exports = { normalizeToolInputsForAudit };