@poa-box/agent 0.1.0

package/dist/lib/brain-signing.js

@@ -0,0 +1,256 @@
+"use strict";
+/**
+ * Brain-layer change signing — ECDSA over snapshot bytes.
+ *
+ * Each brain CRDT change gets wrapped in a signed envelope before being
+ * written to the blockstore. The envelope's sig authenticates the full
+ * Automerge snapshot against an Ethereum address derived from the
+ * existing POP_PRIVATE_KEY. No Nostr keys, no Schnorr, no second PKI.
+ *
+ * Envelope format (v1):
+ *
+ *     {
+ *       v: 1,
+ *       author: "0xABCD...",        // Ethereum address (lowercase)
+ *       timestamp: 1776200000,      // unix seconds
+ *       automerge: "0xDEADBEEF",    // full Automerge.save() bytes, hex
+ *       sig: "0xABC..."             // ECDSA over keccak256(author|ts|automerge)
+ *     }
+ *
+ * Serialized as UTF-8 JSON, stored as a raw-codec IPLD block. The CID
+ * covers the whole envelope, so the sig is content-addressed alongside
+ * the data it authenticates.
+ *
+ * On read, the projection layer:
+ *   1. Unmarshal the envelope JSON
+ *   2. Verify the sig recovers to `author`
+ *   3. Check `author` against the allowlist at
+ *      agent/brain/Config/brain-allowlist.json
+ *   4. If all OK, extract the Automerge bytes and merge
+ *
+ * Sync layer stays permissionless — any peer can gossip any CID. Auth
+ * happens at read time so the network is resilient against relay
+ * operators (there are none, but the principle stands for any future
+ * transport).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signBrainChange = signBrainChange;
+exports.verifyBrainChange = verifyBrainChange;
+exports.unwrapAutomergeBytes = unwrapAutomergeBytes;
+exports.getAllowlistPath = getAllowlistPath;
+exports.loadAllowlist = loadAllowlist;
+exports.isAllowedAuthor = isAllowedAuthor;
+exports.authenticateAndAuthorize = authenticateAndAuthorize;
+exports.isAuthorizedAuthor = isAuthorizedAuthor;
+const ethers_1 = require("ethers");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const brain_paths_1 = require("./brain-paths");
+/**
+ * Canonical message that gets signed. Kept deterministic and simple —
+ * just concatenate the fields in a fixed order, hash, sign. Changing
+ * this format is a breaking change; bump the version when it happens.
+ */
+function canonicalMessage(author, timestamp, automergeHex) {
+    return [
+        'pop-brain-change/v1',
+        author.toLowerCase(),
+        String(timestamp),
+        automergeHex.toLowerCase(),
+    ].join('|');
+}
+function bytesToHex(bytes) {
+    return '0x' + Buffer.from(bytes).toString('hex');
+}
+function hexToBytes(hex) {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    return Uint8Array.from(Buffer.from(clean, 'hex'));
+}
+/**
+ * Sign an Automerge snapshot with the wallet derived from POP_PRIVATE_KEY.
+ * Returns a v1 envelope ready to be JSON-encoded and written as a block.
+ */
+async function signBrainChange(automergeBytes, privateKey) {
+    const key = privateKey || process.env.POP_PRIVATE_KEY;
+    if (!key) {
+        throw new Error('No private key for brain signing (set POP_PRIVATE_KEY)');
+    }
+    const wallet = new ethers_1.ethers.Wallet(key);
+    const author = wallet.address.toLowerCase();
+    const timestamp = Math.floor(Date.now() / 1000);
+    const automergeHex = bytesToHex(automergeBytes);
+    const message = canonicalMessage(author, timestamp, automergeHex);
+    // signMessage applies the standard EIP-191 personal_sign prefix,
+    // so verification uses verifyMessage (not recoverAddress on a raw hash).
+    const sig = await wallet.signMessage(message);
+    return {
+        v: 1,
+        author,
+        timestamp,
+        automerge: automergeHex,
+        sig,
+    };
+}
+/**
+ * Verify an envelope's signature and return the recovered author.
+ * Throws if the envelope is malformed or the signature doesn't verify.
+ *
+ * NOTE: this only checks authenticity (sig corresponds to `author`);
+ * it does NOT check authorization (whether `author` is allowed to
+ * write to this doc). That's the allowlist check — see isAllowedAuthor.
+ */
+function verifyBrainChange(envelope) {
+    if (envelope.v !== 1) {
+        throw new Error(`Unsupported brain envelope version: ${envelope.v}`);
+    }
+    if (!envelope.author || !envelope.timestamp || !envelope.automerge || !envelope.sig) {
+        throw new Error('Malformed brain envelope: missing required field');
+    }
+    const message = canonicalMessage(envelope.author, envelope.timestamp, envelope.automerge);
+    const recovered = ethers_1.ethers.utils.verifyMessage(message, envelope.sig).toLowerCase();
+    if (recovered !== envelope.author.toLowerCase()) {
+        throw new Error(`Brain envelope signature mismatch: expected ${envelope.author}, recovered ${recovered}`);
+    }
+    return recovered;
+}
+/**
+ * Extract the Automerge snapshot bytes from an envelope.
+ * Does NOT verify the signature — caller must run verifyBrainChange first.
+ */
+function unwrapAutomergeBytes(envelope) {
+    return hexToBytes(envelope.automerge);
+}
+/**
+ * Path to the git-tracked brain-allowlist.json. Single source of truth
+ * for who is permitted to write to brain docs. Edited via governance
+ * (or via `pop brain allowlist add/remove`, which writes to the same
+ * file and leaves the git review gate in place).
+ *
+ * Exported so command handlers can write to the same path without
+ * hard-coding it independently.
+ */
+function getAllowlistPath() {
+    return (0, path_1.join)((0, brain_paths_1.getRepoBrainRoot)(), 'Config', 'brain-allowlist.json');
+}
+function loadAllowlist() {
+    const p = getAllowlistPath();
+    if (!(0, fs_1.existsSync)(p))
+        return [];
+    try {
+        const raw = JSON.parse((0, fs_1.readFileSync)(p, 'utf8'));
+        // Accept either a list or an { entries: [...] } wrapper for future flex.
+        const list = Array.isArray(raw) ? raw : raw.entries || [];
+        return list.map(e => ({
+            address: String(e.address).toLowerCase(),
+            name: e.name,
+            addedAt: e.addedAt,
+            addedBy: e.addedBy,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Check whether a given address is in the allowlist.
+ * Case-insensitive on the address.
+ */
+function isAllowedAuthor(address) {
+    const needle = address.toLowerCase();
+    const list = loadAllowlist();
+    return list.some(e => e.address === needle);
+}
+/**
+ * Combined auth check: verify signature + allowlist membership.
+ * Returns the authenticated author on success; throws otherwise.
+ */
+function authenticateAndAuthorize(envelope) {
+    const author = verifyBrainChange(envelope);
+    if (!isAllowedAuthor(author)) {
+        throw new Error(`Brain change rejected: author ${author} not in allowlist`);
+    }
+    return author;
+}
+/**
+ * Async authorization check: on-chain org membership first, static
+ * JSON allowlist second. Does NOT throw — returns a result object the
+ * caller can inspect for logging purposes. Callers then decide whether
+ * to reject the change or accept it based on `.allowed`.
+ *
+ * This is the new canonical authorization for brain read paths.
+ */
+async function isAuthorizedAuthor(address) {
+    const addr = address.toLowerCase();
+    // Lazy import to keep brain-signing.ts free of subgraph / helia deps
+    // for the pure-function sign/verify side. The read-path verify that
+    // calls this runs in an async context that already pulls in brain.ts.
+    const { isOrgMember } = await Promise.resolve().then(() => __importStar(require('./brain-membership')));
+    try {
+        const onChain = await isOrgMember(addr);
+        if (onChain) {
+            // Also a static match? Just informational — both-agree is the
+            // healthy steady state for genesis agents.
+            const staticMatch = isAllowedAuthor(addr);
+            return {
+                allowed: true,
+                mode: staticMatch ? 'both-agree' : 'dynamic',
+                fallbackReason: '',
+            };
+        }
+        // Not a member. Still honor the static JSON for emergency overrides.
+        if (isAllowedAuthor(addr)) {
+            return {
+                allowed: true,
+                mode: 'static-fallback',
+                fallbackReason: 'not an active org member but present in static brain-allowlist.json (emergency override)',
+            };
+        }
+        return {
+            allowed: false,
+            mode: 'dynamic',
+            fallbackReason: 'not an active org member and not in static allowlist',
+        };
+    }
+    catch (err) {
+        // Subgraph unreachable → fall back to static JSON.
+        const staticMatch = isAllowedAuthor(addr);
+        return {
+            allowed: staticMatch,
+            mode: 'static-fallback',
+            fallbackReason: `dynamic allowlist unreachable (${err?.message ?? 'unknown error'}), using static fallback`,
+        };
+    }
+}

package/dist/lib/brain.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Brain layer — peer-to-peer CRDT substrate for shared agent thinking.
+ *
+ * Replaces the git-tracked markdown files (shared.md, projects.md,
+ * discussions.json, goals.md) with Automerge documents synced over
+ * libp2p-gossipsub + Bitswap via an embedded Helia node. No Argus-operated
+ * service in the hot path; peer-to-peer only.
+ *
+ * This file intentionally isolates the ESM import boundary. Helia and its
+ * libp2p dependencies are pure ESM, while the rest of the project compiles
+ * to CommonJS. Dynamic `await import()` is the clean way to bridge the gap
+ * without touching every other source file's module system.
+ *
+ * Plan: /Users/hudsonheadley/.claude/plans/cheeky-nibbling-raven.md
+ *
+ * Current status: MVP step 1 — initialize a Helia node, report peer info.
+ * CRDT/Automerge/gossipsub layers come in subsequent steps.
+ */
+/**
+ * Where the brain layer persists its blocks and state.
+ * One directory per agent. Survives heartbeat cycles, not in git.
+ */
+export declare function getBrainHome(): string;
+export interface BrainNodeInfo {
+    peerId: string;
+    peerIdSource: 'persisted' | 'freshly-generated';
+    listeningAddrs: string[];
+    connectedPeers: number;
+    bootstrapPeerCount: number;
+    heliaVersion: string;
+    blockstorePath: string;
+    peerKeyPath: string;
+    subscribedTopics: string[];
+    topicPeerCounts: Record<string, number>;
+}
+/**
+ * Gossipsub topic name for a brain doc. Versioned so we can bump the
+ * wire format later without silently crossing streams with old peers.
+ */
+export declare function topicForDoc(docId: string): string;
+/**
+ * Head-CID announcement payload. Broadcast on the doc's gossipsub topic
+ * after every successful applyBrainChange. The announcement is ONLY a
+ * pointer — the actual block is fetched via Bitswap in step 6. For step
+ * 5 subscribers just log the announcement.
+ *
+ * Note: the payload is NOT signature-verified at the subscribe layer.
+ * "Auth at read, permissionless at sync" — any peer can gossip any CID,
+ * and readers enforce the allowlist when they actually load the doc
+ * (openBrainDoc verifies the signed envelope before returning the doc).
+ */
+export interface BrainHeadAnnouncement {
+    v: 1;
+    docId: string;
+    cid: string;
+    author: string;
+    timestamp: number;
+}
+export declare function initBrainNode(): Promise<any>;
+/**
+ * Gather a human-readable summary of the local brain node state.
+ */
+export declare function getBrainNodeInfo(): Promise<BrainNodeInfo>;
+export declare function publishBrainHead(docId: string, cid: string, author: string): Promise<void>;
+/**
+ * Subscribe to a doc's gossipsub topic and invoke `onAnnouncement` for
+ * every incoming head-CID announcement. Malformed payloads are logged
+ * and skipped — the sync layer is permissionless, so a subscriber must
+ * not crash on bad input from a misbehaving peer.
+ *
+ * Returns an unsubscribe function that removes the handler and the
+ * topic subscription.
+ */
+export declare function subscribeBrainTopic(docId: string, onAnnouncement: (ann: BrainHeadAnnouncement, from: string) => void): Promise<() => void>;
+/**
+ * Clean shutdown. Call before exiting a long-lived process.
+ * Safe to call when no node was initialized.
+ */
+export declare function stopBrainNode(): Promise<void>;
+/**
+ * Open an Automerge document by ID. If the manifest has a head CID for
+ * this ID, loads the state from the blockstore. Otherwise returns a fresh
+ * empty doc — seeded from the canonical genesis file if one exists for
+ * this docId (task #352), or a plain `Automerge.init()` as a last resort.
+ *
+ * Returns the doc plus its current head CID (null for new docs) so the
+ * caller can tell whether this was a load or an init.
+ */
+export declare function openBrainDoc<T = any>(docId: string): Promise<{
+    doc: any;
+    headCid: string | null;
+}>;
+/**
+ * Apply a change function to a brain doc and persist the new state.
+ *
+ * Writes the new full-state snapshot as a raw IPLD block, computes its
+ * CID, updates the heads manifest. Returns the new CID.
+ *
+ * Snapshot-per-write is simpler than delta-based persistence for MVP;
+ * the tradeoff is that Automerge.save() produces the full state each
+ * time. For the shared.md / projects.md scale (KB-range docs) this is
+ * fine. When docs grow, switch to saving incremental changes via
+ * Automerge.getChanges() and a linked-list of block CIDs.
+ */
+export declare function applyBrainChange<T = any>(docId: string, changeFn: (doc: T) => void, options?: {
+    allowInvalidShape?: boolean;
+}): Promise<{
+    headCid: string;
+    doc: any;
+    author: string;
+}>;
+/**
+ * Import a raw Automerge snapshot as the new local head for a brain doc.
+ *
+ * Task #353 (HB#348): the post-HB#352 follow-up for migrating the 3 existing
+ * Argus agents off their pre-genesis disjoint Automerge state. The HB#341
+ * export step pinned argus's current state for all 3 canonical docs to IPFS
+ * (Qm...). This function is the receive side: load those bytes into vigil_01
+ * or sentinel_01's brain home as the new shared head so their subsequent
+ * writes build on argus's root instead of their own disjoint root.
+ *
+ * ## Semantics
+ *
+ * - Load the bytes via `Automerge.load()` to validate structural integrity.
+ *   Throws if the bytes are corrupt or not an Automerge snapshot.
+ * - Run the standard write-time schema validator (#346) unless
+ *   `opts.allowInvalidShape` is set.
+ * - Sign a new envelope via `signBrainChange` — the importing agent becomes
+ *   the envelope author for the new head, even though the Automerge content
+ *   is preserved from the source.
+ * - Write the envelope as a new IPLD block, update the manifest, publish the
+ *   head CID via gossipsub (same as applyBrainChange's persist+publish flow).
+ *
+ * ## Safety
+ *
+ * This function REPLACES the local head. If the local brain home already
+ * has content for this docId, that state becomes orphaned (the old envelope
+ * stays in the blockstore, but the manifest no longer points at it). Callers
+ * must decide whether to preserve local-only content before calling:
+ *
+ *   1. `pop brain read --doc <id> --json` to snapshot local state
+ *   2. `pop brain import-snapshot --doc <id> --file <canonical-bytes>`
+ *   3. Replay local-only lessons via `pop brain append-lesson` calls on the
+ *      new shared baseline
+ *
+ * The CLI wrapper (`pop brain import-snapshot`) enforces a `--force` flag
+ * requirement when a local head exists, so there are no accidental replaces.
+ */
+export declare function importBrainDoc(docId: string, automergeBytes: Uint8Array, opts?: {
+    allowInvalidShape?: boolean;
+}): Promise<{
+    headCid: string;
+    doc: any;
+    author: string;
+}>;
+/**
+ * List all known brain doc IDs + their current head CIDs.
+ * Reads the manifest file directly — doesn't require Helia to be running.
+ */
+export declare function listBrainDocs(): Array<{
+    docId: string;
+    headCid: string;
+}>;
+export type BrainSyncResult = {
+    action: 'skip';
+    reason: string;
+    headCid: string;
+} | {
+    action: 'adopt';
+    reason: string;
+    headCid: string;
+} | {
+    action: 'merge';
+    reason: string;
+    headCid: string;
+} | {
+    action: 'reject';
+    reason: string;
+};
+/**
+ * Given a remote head-CID announcement, fetch the block (via Bitswap if
+ * not already local), verify it, merge with the local doc, and update
+ * the manifest. Returns the action taken.
+ *
+ * Does NOT re-publish after merging. The next local write (via
+ * applyBrainChange) will publish from the merged state. This avoids
+ * gossip ping-pong where two peers would keep producing "merge heads"
+ * and broadcasting them at each other.
+ */
+export declare function fetchAndMergeRemoteHead(docId: string, remoteCidStr: string): Promise<BrainSyncResult>;
+/**
+ * Projection helper — returns the current Automerge doc as a plain
+ * JS object (for JSON display). Wraps openBrainDoc and Automerge.clone.
+ */
+export declare function readBrainDoc(docId: string): Promise<{
+    doc: any;
+    headCid: string | null;
+}>;