@opnli/atl-devkit 0.1.0

package/README.md

@@ -0,0 +1,143 @@
+# @opnli/atl-devkit
+
+**Add human consent to any AI agent in 3 lines.**
+
+The Agent Trust Layer (ATL) DevKit gives developers a drop-in consent
+gate for AI agents. When your agent tries to act on the world — read a
+file, call an API, run a command — the ATL holds the action and asks the
+human: **Allow or Block?**
+
+The human's decision is final. The audit trail is tamper-evident.
+There is no bypass.
+
+## Quick Start
+
+    const { createConsentGate } = require('@opnli/atl-devkit');
+    const gate = createConsentGate({ onConsent: askTheHuman, timeout: 60000 });
+    myProxy.onMessage((msg, raw) => {
+      const result = gate.inspect(msg, raw, false);
+      if (result.action === 'forward') send(raw);
+      // 'hold' means consent requested. Wait for gate.resolve(holdId, 'allow'|'deny')
+    });
+
+## Why This Exists
+
+AI agents are getting powerful. They can read your files, search the
+web, execute code, and call APIs — often without asking. The industry
+is moving fast on capability. Nobody is moving on trust.
+
+The ATL is the trust layer. It does not slow agents down. It puts the
+human in control of what agents do. **Be the enabler for the timid.
+Never be the barrier to the powerful.**
+
+## The Three Realities of Trust
+
+Every trust decision involves three realities:
+
+1. **Identity** — Know who is acting. (CARD credentials)
+2. **Consent** — Choose what is allowed. (This DevKit)
+3. **Accountability** — Check what happened. (Audit log)
+
+The DevKit delivers Consent and Accountability. Identity comes from
+the Opn.li Trust Network (https://opn.li) via CARD credentials.
+
+## Two Shield Levels
+
+### Green Shield — Consent Before Execution
+
+The agent requests permission to act. The action has **NOT happened
+yet**. The human decides whether it happens. This requires the agent
+platform to support pre-execution approval events.
+
+    Agent: "I want to run: npm install express"
+      -> ATL HOLDS the request
+      -> Human sees: "Your AI wants to run a shell command: npm install express"
+      -> Human clicks Allow -> command executes
+      -> Human clicks Block -> command never runs
+
+### Yellow Shield — Consent Before Delivery
+
+The agent executed an action, but the result has not been delivered to
+the UI. The ATL detects the execution via a sequence gap in the event
+stream and holds the result. The human decides whether to receive it.
+
+This works on **any platform** that streams sequential agent events —
+no platform modifications required.
+
+    Agent executes a tool (seqs 2-4 consumed internally)
+      -> ATL detects gap: seq jumped from 1 to 5
+      -> ATL HOLDS the result
+      -> Human sees: "Your AI executed an action. Allow the result?"
+      -> Human clicks Allow -> result delivered
+      -> Human clicks Block -> result dropped, agent notified
+
+## API
+
+### createConsentGate(options)
+
+Create a consent gate for an agent message stream.
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| onConsent | function | *required* | Called when consent is needed. Receives { holdId, runId, gapSize, shield, request }. |
+| onAudit | function | null | Called after each decision with { holdId, runId, decision, shield, gapSize, eventCount }. |
+| timeout | number | 60000 | Consent timeout in ms. Default deny after expiry. 0 to disable. |
+| greenShield | boolean | false | Enable Green Shield. When true, Yellow Shield is disabled. |
+
+**Returns:** { inspect, resolve, getState }
+
+#### gate.inspect(msg, raw, isBinary)
+
+Inspect a message from the agent platform. Call for every Gateway-to-Client message.
+
+Returns { action } where action is:
+- "forward" — Send to client normally
+- "hold" — Consent requested. Do NOT send. Includes holdId.
+- "drop" — Suppressed. Do NOT send.
+- "buffer" — Added to existing hold. Do NOT send.
+
+#### gate.resolve(holdId, decision)
+
+Resolve a consent decision. decision is "allow", "deny", or "timeout".
+
+Returns { decision, events[] } — on allow, events contains the held
+messages to forward. On deny/timeout, events is empty.
+
+### createAuditLogger(logPath)
+
+Create a tamper-evident audit logger.
+
+**Returns:** { writeEntry, verifyChain }
+
+#### logger.writeEntry(opts)
+
+Append a consent decision. opts: { holdId, runId, decision, shield, gapSize, eventCount }.
+
+#### logger.verifyChain()
+
+Verify hash chain integrity. Returns { valid, entries, brokenAt }.
+
+## Design Principles
+
+- **Non-invasive.** The ATL wraps agent platforms. It does not modify them.
+- **Fail-closed.** No response = no permission. Connection drop = denied.
+- **Platform-agnostic.** Works with any agent that streams sequential events.
+- **Honest.** Yellow Shield is consent before delivery, not before execution. We say so.
+- **Auditable.** Every decision is logged with a SHA-256 hash chain.
+
+## License
+
+Apache-2.0 — Openly Personal Networks, Inc. (https://opn.li)
+
+## The Agent Economy
+
+*My data + Your AI + My control = Living Intelligence*
+
+CROCbox is the reference implementation of the ATL. The DevKit is how
+every developer brings trust to their own agents. Together, we are
+building the Agent Economy — where humans control what AI does, not
+the other way around.
+
+Learn more at https://opn.li

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@opnli/atl-devkit",
+  "version": "0.1.0",
+  "description": "Add human consent to any AI agent in 3 lines. The Agent Trust Layer DevKit.",
+  "main": "src/index.js",
+  "keywords": [
+    "ai-agent",
+    "trust",
+    "consent",
+    "agent-trust-layer",
+    "human-in-the-loop",
+    "opnli",
+    "card"
+  ],
+  "author": "Opn.li — Openly Personal Networks, Inc.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/opnli/agent-trust-layer"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/audit-logger.js

@@ -0,0 +1,147 @@
+/**
+ * @opnli/atl-devkit — Audit Logger
+ * 
+ * Append-only JSONL audit log with SHA-256 hash chain.
+ * Every consent decision is recorded with timestamp, action, target,
+ * result, reason, and a cryptographic link to the previous entry.
+ * 
+ * Tamper-evident: modifying any entry breaks the hash chain.
+ * Honest disclosure: tamper-evident, not tamper-proof (INV-16).
+ * 
+ * Extracted from CROCbox ws-proxy.js — proven in production with
+ * 100+ entries verified in live testing.
+ * 
+ * @see OPN_ENG_CROC-E2E-Invariants_13MAR26_v2, INV-8, INV-16
+ */
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Create an audit logger that writes to the specified path.
+ * 
+ * @param {string} logPath — Absolute path to the JSONL audit log file.
+ * @returns {object} — { writeEntry, verifyChain }
+ */
+function createAuditLogger(logPath) {
+  // Ensure the directory exists
+  const dir = path.dirname(logPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  /**
+   * Append a consent decision to the audit log.
+   * 
+   * @param {object} opts
+   * @param {string} opts.holdId — Unique identifier for this consent hold
+   * @param {string} opts.runId — Agent run identifier
+   * @param {string} opts.decision — 'allow' | 'deny' | 'timeout'
+   * @param {string} opts.shield — 'yellow' | 'green'
+   * @param {number} opts.gapSize — Seq-gap size (Yellow) or 0 (Green)
+   * @param {number} opts.eventCount — Number of held events
+   * @param {object} [opts.extra] — Additional fields to include
+   * @returns {object} — The written entry (with hash)
+   */
+  function writeEntry(opts) {
+    const { holdId, runId, decision, shield, gapSize, eventCount, extra } = opts;
+
+    // Read last hash from file
+    let prevHash = 'genesis';
+    try {
+      const content = fs.readFileSync(logPath, 'utf8').trim();
+      if (content.length > 0) {
+        const lines = content.split('\n');
+        const lastEntry = JSON.parse(lines[lines.length - 1]);
+        prevHash = lastEntry.hash || 'genesis';
+      }
+    } catch (e) { /* file may not exist yet — genesis */ }
+
+    const reasonMap = {
+      'allow': 'user-consent',
+      'deny': 'user-deny',
+      'timeout': 'user-timeout'
+    };
+    const resultMap = {
+      'allow': 'allowed',
+      'deny': 'blocked',
+      'timeout': 'blocked'
+    };
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      action: shield + '-shield',
+      target: 'agent-event-stream',
+      result: resultMap[decision] || 'blocked',
+      reason: reasonMap[decision] || 'unknown',
+      detail: 'gap=' + gapSize + ' events-held=' + eventCount + ' holdId=' + holdId,
+      decision_id: holdId,
+      shield: shield,
+      runId: runId,
+      prev_hash: prevHash,
+      ...(extra || {})
+    };
+
+    const entryStr = JSON.stringify(entry);
+    entry.hash = crypto.createHash('sha256').update(entryStr + prevHash).digest('hex');
+
+    fs.appendFileSync(logPath, JSON.stringify(entry) + '\n');
+    return entry;
+  }
+
+  /**
+   * Verify the hash chain integrity of the audit log.
+   * 
+   * @returns {object} — { valid: boolean, entries: number, brokenAt: number|null }
+   */
+  function verifyChain() {
+    let content;
+    try {
+      content = fs.readFileSync(logPath, 'utf8').trim();
+    } catch (e) {
+      return { valid: true, entries: 0, brokenAt: null };
+    }
+
+    if (content.length === 0) {
+      return { valid: true, entries: 0, brokenAt: null };
+    }
+
+    const lines = content.split('\n');
+    let expectedPrevHash = 'genesis';
+
+    for (let i = 0; i < lines.length; i++) {
+      try {
+        const entry = JSON.parse(lines[i]);
+
+        // Check prev_hash links to previous entry
+        if (entry.prev_hash !== expectedPrevHash) {
+          return { valid: false, entries: lines.length, brokenAt: i };
+        }
+
+        // Recompute hash: strip hash field, serialize, hash with prev_hash
+        const storedHash = entry.hash;
+        const stripped = { ...entry };
+        delete stripped.hash;
+        const recomputed = crypto.createHash('sha256')
+          .update(JSON.stringify(stripped) + expectedPrevHash)
+          .digest('hex');
+
+        if (storedHash !== recomputed) {
+          return { valid: false, entries: lines.length, brokenAt: i };
+        }
+
+        expectedPrevHash = storedHash;
+      } catch (e) {
+        return { valid: false, entries: lines.length, brokenAt: i };
+      }
+    }
+
+    return { valid: true, entries: lines.length, brokenAt: null };
+  }
+
+  return { writeEntry, verifyChain };
+}
+
+module.exports = { createAuditLogger };

package/src/consent-gate.js

@@ -0,0 +1,280 @@
+/**
+ * @opnli/atl-devkit — Consent Gate
+ * 
+ * The core of the Agent Trust Layer. Inspects a stream of messages
+ * between an AI agent and its execution environment. When the agent
+ * acts on the world, the gate HOLDS the result and asks the human.
+ * 
+ * Two shield levels:
+ * 
+ *   GREEN SHIELD (Consent Before Execution):
+ *     The gate intercepts a pre-execution approval request. The action
+ *     has NOT happened yet. The human decides whether it happens.
+ *     Requires the agent platform to broadcast approval events.
+ * 
+ *   YELLOW SHIELD (Consent Before Delivery):
+ *     The gate detects that an action executed via a sequence gap in
+ *     the agent event stream. The action HAS happened, but the result
+ *     has not been delivered. The human decides whether to receive it.
+ *     Works on ANY platform that streams sequential agent events.
+ * 
+ * The gate is fail-closed: if the human doesn't respond within the
+ * timeout, the answer is NO. If the connection drops, the answer is
+ * NO. There is no bypass.
+ * 
+ * Three-line integration:
+ * 
+ *   const { createConsentGate } = require('@opnli/atl-devkit');
+ *   const gate = createConsentGate({ onConsent: showMyUI, timeout: 60000 });
+ *   myProxy.onMessage(gate.inspect);
+ * 
+ * @see OPN_ENG_CROC-E2E-Invariants_13MAR26_v2, INV-5, INV-7
+ */
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Create a consent gate for an agent message stream.
+ * 
+ * @param {object} options
+ * @param {function} options.onConsent — Called when consent is needed.
+ *   Receives: { holdId, runId, gapSize, heldEventCount, detectedAt, shield }
+ *   The integrator must call gate.resolve(holdId, 'allow'|'deny') when
+ *   the human decides.
+ * @param {function} [options.onAudit] — Called with audit entry after each
+ *   decision. Receives: { holdId, runId, decision, shield, gapSize, eventCount }
+ *   If not provided, decisions are not logged (bring your own logger).
+ * @param {number} [options.timeout=60000] — Consent timeout in ms.
+ *   Default deny after this period. Set to 0 to disable timeout.
+ * @param {boolean} [options.greenShield=false] — Enable Green Shield
+ *   interception of exec.approval.requested events. When true, Yellow
+ *   Shield seq-gap detection is disabled (Green supersedes Yellow).
+ * @returns {object} — { inspect, resolve, getState }
+ */
+function createConsentGate(options) {
+  const {
+    onConsent,
+    onAudit,
+    timeout = 60000,
+    greenShield = false
+  } = options;
+
+  if (typeof onConsent !== 'function') {
+    throw new Error('createConsentGate requires an onConsent callback');
+  }
+
+  // ── Per-runId sequence tracking (Yellow Shield) ────────────
+  // Key: runId, Value: { lastSeq, state, holdId }
+  //   state: 'streaming' | 'holding' | 'allowed' | 'denied'
+  const runState = new Map();
+
+  // ── Held events buffer ─────────────────────────────────────
+  // Key: holdId, Value: { runId, events[], gapSize, detectedAt,
+  //   shield, state: 'pending'|'allow'|'deny'|'timeout' }
+  const heldEvents = new Map();
+
+  // ── Pending Green Shield approvals ─────────────────────────
+  // Key: approvalId, Value: { id, request, holdId, createdAtMs, expiresAtMs }
+  const pendingApprovals = new Map();
+
+  /**
+   * Resolve a consent decision.
+   * 
+   * @param {string} holdId — The hold to resolve
+   * @param {string} decision — 'allow' | 'deny' | 'timeout'
+   * @returns {object|null} — { decision, events[] } on allow, null otherwise.
+   *   The caller is responsible for forwarding the returned events.
+   */
+  function resolve(holdId, decision) {
+    const held = heldEvents.get(holdId);
+    if (!held) return null;
+    if (held.state !== 'pending') return null;
+
+    held.state = decision;
+
+    // Audit callback
+    if (typeof onAudit === 'function') {
+      onAudit({
+        holdId: holdId,
+        runId: held.runId,
+        decision: decision,
+        shield: held.shield,
+        gapSize: held.gapSize,
+        eventCount: held.events.length
+      });
+    }
+
+    if (decision === 'allow') {
+      const run = runState.get(held.runId);
+      if (run) run.state = 'allowed';
+      const events = held.events.slice();
+      heldEvents.delete(holdId);
+      return { decision: 'allow', events: events };
+    } else {
+      const run = runState.get(held.runId);
+      if (run) run.state = 'denied';
+      heldEvents.delete(holdId);
+      return { decision: decision, events: [] };
+    }
+  }
+
+  /**
+   * Start the consent timeout timer for a hold.
+   * @private
+   */
+  function startTimeout(holdId) {
+    if (timeout <= 0) return;
+    setTimeout(function() {
+      const held = heldEvents.get(holdId);
+      if (held && held.state === 'pending') {
+        resolve(holdId, 'timeout');
+      }
+    }, timeout);
+  }
+
+  /**
+   * Inspect a message from the agent platform.
+   * 
+   * Call this for every message in the Gateway→Client direction.
+   * Returns an action telling the caller what to do.
+   * 
+   * @param {object} msg — Parsed JSON message from the agent platform
+   * @param {Buffer|string} raw — Raw message data for forwarding
+   * @param {boolean} isBinary — Whether the message is binary
+   * @returns {object} — { action: 'forward'|'hold'|'drop'|'buffer', ... }
+   *   'forward': Send to client normally. msg included.
+   *   'hold': Consent requested. Do NOT send to client. holdId included.
+   *   'drop': Message suppressed (denied run). Do NOT send to client.
+   *   'buffer': Added to existing hold. Do NOT send to client.
+   */
+  function inspect(msg, raw, isBinary) {
+    // ── GREEN SHIELD: Intercept exec.approval.requested ──────
+    if (msg.type === 'event' && msg.event === 'exec.approval.requested') {
+      const approval = msg.payload;
+      if (approval && approval.id) {
+        const holdId = 'gs-' + crypto.randomUUID().substring(0, 12);
+
+        pendingApprovals.set(approval.id, {
+          id: approval.id,
+          request: approval.request || {},
+          holdId: holdId,
+          createdAtMs: approval.createdAtMs || Date.now(),
+          expiresAtMs: approval.expiresAtMs || (Date.now() + 60000)
+        });
+
+        heldEvents.set(holdId, {
+          runId: approval.id,
+          events: [],
+          gapSize: 0,
+          detectedAt: Date.now(),
+          shield: 'green',
+          state: 'pending',
+          approvalId: approval.id
+        });
+
+        onConsent({
+          holdId: holdId,
+          runId: approval.id,
+          gapSize: 0,
+          heldEventCount: 0,
+          detectedAt: Date.now(),
+          shield: 'green',
+          request: approval.request || {}
+        });
+
+        startTimeout(holdId);
+        return { action: 'hold', holdId: holdId };
+      }
+    }
+
+    // Intercept resolved events (don't forward to UI)
+    if (msg.type === 'event' && msg.event === 'exec.approval.resolved') {
+      return { action: 'drop' };
+    }
+
+    // ── YELLOW SHIELD: Seq-gap detection on agent events ─────
+    if (!greenShield && msg.type === 'event' && msg.event === 'agent') {
+      const payload = msg.payload || {};
+      const runId = payload.runId;
+      const seq = payload.seq;
+      const stream = payload.stream;
+
+      if (runId && typeof seq === 'number') {
+        if (!runState.has(runId)) {
+          runState.set(runId, { lastSeq: 0, state: 'streaming', holdId: null });
+        }
+        const run = runState.get(runId);
+
+        // If holding, buffer this event
+        if (run.state === 'holding' && run.holdId) {
+          const held = heldEvents.get(run.holdId);
+          if (held && held.state === 'pending') {
+            held.events.push({ data: raw, isBinary: isBinary });
+            run.lastSeq = seq;
+            return { action: 'buffer', holdId: run.holdId };
+          }
+        }
+
+        // If denied, drop all further events for this run
+        if (run.state === 'denied') {
+          run.lastSeq = seq;
+          return { action: 'drop' };
+        }
+
+        // Seq-gap detection on assistant stream
+        if (stream === 'assistant' && run.lastSeq > 0 && seq > run.lastSeq + 1) {
+          const gapSize = seq - run.lastSeq - 1;
+          const holdId = 'ysh-' + crypto.randomUUID().substring(0, 12);
+
+          run.state = 'holding';
+          run.holdId = holdId;
+          run.lastSeq = seq;
+
+          heldEvents.set(holdId, {
+            runId: runId,
+            events: [{ data: raw, isBinary: isBinary }],
+            gapSize: gapSize,
+            detectedAt: Date.now(),
+            shield: 'yellow',
+            state: 'pending'
+          });
+
+          onConsent({
+            holdId: holdId,
+            runId: runId,
+            gapSize: gapSize,
+            heldEventCount: 1,
+            detectedAt: Date.now(),
+            shield: 'yellow'
+          });
+
+          startTimeout(holdId);
+          return { action: 'hold', holdId: holdId };
+        }
+
+        // Normal event — track and forward
+        run.lastSeq = seq;
+      }
+    }
+
+    // ── Default: forward ─────────────────────────────────────
+    return { action: 'forward' };
+  }
+
+  /**
+   * Get current state for diagnostics.
+   * @returns {object} — { activeHolds, trackedRuns, pendingApprovals }
+   */
+  function getState() {
+    return {
+      activeHolds: heldEvents.size,
+      trackedRuns: runState.size,
+      pendingApprovals: pendingApprovals.size
+    };
+  }
+
+  return { inspect, resolve, getState };
+}
+
+module.exports = { createConsentGate };

package/src/index.js

@@ -0,0 +1,48 @@
+/**
+ * @opnli/atl-devkit — The Agent Trust Layer DevKit
+ * 
+ * Add human consent to any AI agent in 3 lines.
+ * 
+ *   const { createConsentGate } = require('@opnli/atl-devkit');
+ *   const gate = createConsentGate({ onConsent: showMyUI, timeout: 60000 });
+ *   myProxy.onMessage(gate.inspect);
+ * 
+ * The Agent Trust Layer sits between an AI agent and the world it acts
+ * upon. When the agent tries to act — read a file, call an API, run a
+ * command — the ATL holds the action and asks the human: Allow or Block?
+ * 
+ * The human's decision is final. The audit trail is tamper-evident.
+ * There is no bypass. This is trust infrastructure for the Agent Economy.
+ * 
+ * Two shield levels:
+ * 
+ *   GREEN SHIELD — Consent Before Execution. The action has NOT happened
+ *   yet. The human decides whether it happens. Requires agent platform
+ *   support for pre-execution approval events.
+ * 
+ *   YELLOW SHIELD — Consent Before Delivery. The action HAS happened,
+ *   but the result has not been delivered. The human decides whether to
+ *   receive it. Works on ANY platform that streams sequential events.
+ * 
+ * Three Realities of Trust:
+ *   1. Identity — Know who is acting (CARD credentials)
+ *   2. Consent — Choose what is allowed (this DevKit)
+ *   3. Accountability — Check what happened (audit log)
+ * 
+ * My data + Your AI + My control = Living Intelligence
+ * 
+ * @see https://github.com/opnli/agent-trust-layer
+ * @see https://opn.li
+ * 
+ * Copyright (c) 2026 Openly Personal Networks, Inc.
+ * Licensed under Apache-2.0
+ */
+'use strict';
+
+const { createConsentGate } = require('./consent-gate');
+const { createAuditLogger } = require('./audit-logger');
+
+module.exports = {
+  createConsentGate,
+  createAuditLogger
+};