@nfinitmonkeys/clan-engine 0.3.0 → 0.4.1

package/dist/brain-build.d.ts

@@ -13,7 +13,12 @@
  * an opt-in HOOK (opts.curate): the caller brings the LLM, the engine stays
  * zero-LLM and re-gates everything the curator returns.
  */
-import type { ClanIdentity, GeneratedFile, BrainCurator } from './types.js';
+import type { ClanIdentity, GeneratedFile, BrainCurator, BrainOwner } from './types.js';
+/** Fence tag that holds a serialized EncryptedPage inside a private page's body.
+ *  A private page keeps its Markdown frontmatter (with `private: true`) so the
+ *  vault stays browsable/round-trippable, but the body is replaced by this fenced
+ *  JSON block — the plaintext body never touches disk. */
+export declare const ENCRYPTED_FENCE = "clan-encrypted";
 export interface HeldBack {
     from: string;
     reasons: string[];
@@ -34,16 +39,44 @@ export interface BrainBuildOpts {
      *  scanSensitive + create-only; a throwing curator falls back to the
      *  mechanical pages with a note in the report. */
     curate?: BrainCurator;
+    /** The clan itself as an encrypted-brain recipient (alphaId + X25519 public
+     *  key). Required to WRITE a page whose source frontmatter carries
+     *  `private: true`: such a page is sanitizer-EXEMPT (that is the whole point)
+     *  but its body is encrypted to this owner BEFORE any write. Without an owner,
+     *  a private page is HELD BACK ("run clan keys init first") and its plaintext
+     *  is NEVER written. The private key never reaches the engine. */
+    owner?: BrainOwner;
 }
+/** True when a rendered page's content carries an encrypted (private) body —
+ *  i.e. it holds a fenced `clan-encrypted` block. Used by scanners/tests to
+ *  assert a private page never persisted plaintext. */
+export declare function isPrivatePageContent(content: string): boolean;
+/** Extract the EncryptedPage JSON from a private page's rendered content (the
+ *  fenced `clan-encrypted` block). Returns null when the page is not private /
+ *  the fence is absent or unparseable. The inverse of the write-time encode. */
+export declare function decodePrivatePage(content: string): unknown | null;
 /**
- * Mine existing files into brain pages. Every candidate is scanned; flagged
- * ones are held back. Returns create-candidate pages + the held-back report.
- * Without opts.curate the call stays synchronous (existing callers unchanged);
- * with a curator it returns a Promise of the curated (re-gated) result.
+ * Encrypt a private page's plaintext body to the owner and render the full page
+ * content (frontmatter preserved, body replaced by a fenced `clan-encrypted`
+ * block). clan-crypto is imported lazily so the engine core loads without it;
+ * the owner's private key is NEVER involved — only its public identity. Throws
+ * if clan-crypto is unavailable so the caller can hold the page back rather than
+ * write plaintext.
+ */
+export declare function encryptPrivatePage(frontmatterBlock: string, title: string, plaintextBody: string, owner: BrainOwner): Promise<string>;
+/**
+ * Mine existing files into brain pages. Every NON-PRIVATE candidate is scanned;
+ * flagged ones are held back. A candidate whose source frontmatter declares
+ * `private: true` is sanitizer-EXEMPT but is ENCRYPTED to opts.owner before its
+ * page is emitted (its plaintext body never appears on disk); without an owner
+ * it is HELD BACK ("run clan keys init first") — plaintext is never written.
+ *
+ * The call stays synchronous ONLY when there is neither a curator nor a private
+ * candidate (existing callers unchanged); a curator OR any private page (which
+ * needs async encryption) makes it return a Promise of the (re-gated) result.
  */
 export declare function brainBuild(repo: string, identity: ClanIdentity, opts?: BrainBuildOpts & {
     curate?: undefined;
+    owner?: undefined;
 }): BrainBuildResult;
-export declare function brainBuild(repo: string, identity: ClanIdentity, opts: BrainBuildOpts & {
-    curate: BrainCurator;
-}): Promise<BrainBuildResult>;
+export declare function brainBuild(repo: string, identity: ClanIdentity, opts: BrainBuildOpts): BrainBuildResult | Promise<BrainBuildResult>;

package/dist/brain-build.js

@@ -16,8 +16,14 @@
 import { readFileSync, existsSync, readdirSync, lstatSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
+import YAML from 'yaml';
 import { brainRoot, markerLines } from './templates.js';
 import { scanSensitive } from './sanitize.js';
+/** Fence tag that holds a serialized EncryptedPage inside a private page's body.
+ *  A private page keeps its Markdown frontmatter (with `private: true`) so the
+ *  vault stays browsable/round-trippable, but the body is replaced by this fenced
+ *  JSON block — the plaintext body never touches disk. */
+export const ENCRYPTED_FENCE = 'clan-encrypted';
 function slugify(s) {
     return String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'untitled';
 }
@@ -31,6 +37,66 @@ function read(p) { try {
 catch {
     return null;
 } }
+/** Read the YAML frontmatter of a source file (between the first two `---`).
+ *  Returns null when there is no leading frontmatter block or it won't parse. */
+function frontmatter(content) {
+    if (!content.startsWith('---'))
+        return null;
+    const end = content.indexOf('\n---', 3);
+    if (end === -1)
+        return null;
+    try {
+        const doc = YAML.parse(content.slice(3, end));
+        return doc && typeof doc === 'object' && !Array.isArray(doc) ? doc : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when a source file's frontmatter declares `private: true`. A private
+ *  page is exempt from sanitizer hold-back but MUST be encrypted before write. */
+function declaredPrivate(content) {
+    return frontmatter(content)?.private === true;
+}
+/** Serialize an EncryptedPage into a fenced `clan-encrypted` block. This is the
+ *  on-disk body of a private page: the plaintext body is replaced by this fence
+ *  so no plaintext ever touches the vault. Round-trippable via decodePrivatePage. */
+function fenceEncrypted(page) {
+    return '```' + ENCRYPTED_FENCE + '\n' + JSON.stringify(page) + '\n```';
+}
+/** True when a rendered page's content carries an encrypted (private) body —
+ *  i.e. it holds a fenced `clan-encrypted` block. Used by scanners/tests to
+ *  assert a private page never persisted plaintext. */
+export function isPrivatePageContent(content) {
+    return new RegExp('```' + ENCRYPTED_FENCE + '\\b').test(content);
+}
+/** Extract the EncryptedPage JSON from a private page's rendered content (the
+ *  fenced `clan-encrypted` block). Returns null when the page is not private /
+ *  the fence is absent or unparseable. The inverse of the write-time encode. */
+export function decodePrivatePage(content) {
+    const m = new RegExp('```' + ENCRYPTED_FENCE + '\\s*\\n([\\s\\S]*?)\\n```').exec(content);
+    if (!m)
+        return null;
+    try {
+        return JSON.parse(m[1]);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Encrypt a private page's plaintext body to the owner and render the full page
+ * content (frontmatter preserved, body replaced by a fenced `clan-encrypted`
+ * block). clan-crypto is imported lazily so the engine core loads without it;
+ * the owner's private key is NEVER involved — only its public identity. Throws
+ * if clan-crypto is unavailable so the caller can hold the page back rather than
+ * write plaintext.
+ */
+export async function encryptPrivatePage(frontmatterBlock, title, plaintextBody, owner) {
+    const crypto = await import('@nfinitmonkeys/clan-crypto');
+    const page = crypto.encryptPage(plaintextBody, [{ alphaId: owner.alphaId, spkiB64: owner.spkiB64 }]);
+    return `---\n${frontmatterBlock}\n---\n\n# ${title}\n\n${fenceEncrypted(page)}\n`;
+}
 function listMd(dir, depth = 3) {
     if (depth < 0 || !existsSync(dir))
         return [];
@@ -89,7 +155,7 @@ function mineDocs(repo) {
             continue;
         const rel = f.slice(repo.length + 1);
         const title = (/^#\s+(.+)$/m.exec(body)?.[1] ?? rel).trim();
-        out.push({ category: 'sources', slug: slugify(rel.replace(/\.md$/, '')), title, type: 'source', from: rel, body });
+        out.push({ category: 'sources', slug: slugify(rel.replace(/\.md$/, '')), title, type: 'source', from: rel, body, private: declaredPrivate(body) });
     }
     return out;
 }
@@ -185,10 +251,24 @@ function mineMemory(repo, home) {
         if (!body || body.length < 40)
             continue;
         const title = (/^name:\s*(.+)$/m.exec(body)?.[1] ?? base.replace(/\.md$/, '')).trim();
-        out.push({ category: 'sources', slug: 'memory--' + slugify(base.replace(/\.md$/, '')), title, type: 'source', from: `session-memory/${base}`, body });
+        out.push({ category: 'sources', slug: 'memory--' + slugify(base.replace(/\.md$/, '')), title, type: 'source', from: `session-memory/${base}`, body, private: declaredPrivate(body) });
     }
     return out;
 }
+/** Frontmatter block for a mined page. Private pages carry `private: true` so a
+ *  later query knows to decrypt; the body is JSON-quoted scalars only. */
+function pageFrontmatter(c, title) {
+    const lines = [
+        `name: ${JSON.stringify(title)}`,
+        `description: ${JSON.stringify('mined from ' + c.from)}`,
+        `type: ${JSON.stringify(c.type)}`,
+        `source: ${JSON.stringify(c.from)}`,
+    ];
+    if (c.private)
+        lines.push('private: true');
+    lines.push(markerLines());
+    return lines.join('\n');
+}
 export function brainBuild(repo, identity, opts = {}) {
     const home = opts.home ?? homedir();
     const candidates = [
@@ -203,15 +283,22 @@ export function brainBuild(repo, identity, opts = {}) {
     const root = brainRoot(identity);
     const pages = [];
     const heldBack = [];
+    const notes = [];
     const sourceNotes = [];
     const seen = new Set();
+    // Private candidates that survived path/create-only gating, deferred for async
+    // encryption. { path, title, frontmatter, body } — body encrypted before write.
+    const privateJobs = [];
     for (const c of candidates) {
-        // Scan the body AND the derived title AND the source path — a secret/PHI in
-        // a filename or heading is just as leaky as one in the body.
-        const scan = scanSensitive(`${c.body}\n${c.title}\n${c.from}`, { hipaa: opts.hipaa });
-        if (scan.flagged) {
-            heldBack.push({ from: c.from, reasons: scan.reasons });
-            continue;
+        // A private page is EXEMPT from the sanitizer hold-back (that is the point —
+        // it will be encrypted, never written in the clear). Non-private pages are
+        // scanned on body + title + source path exactly as before.
+        if (!c.private) {
+            const scan = scanSensitive(`${c.body}\n${c.title}\n${c.from}`, { hipaa: opts.hipaa });
+            if (scan.flagged) {
+                heldBack.push({ from: c.from, reasons: scan.reasons });
+                continue;
+            }
         }
         // Unique slug within its category (suffix on collision — never silently drop).
         let path = `${root}/wiki/${c.category}/${c.slug}.md`;
@@ -222,29 +309,63 @@ export function brainBuild(repo, identity, opts = {}) {
         // existing brain page, so a programmatic caller can't overwrite memory.
         if (existsSync(join(repo, path)))
             continue;
+        const title = oneLine(c.title);
+        const fm = pageFrontmatter(c, title);
+        if (c.private) {
+            if (!opts.owner) {
+                // No clan keypair → refuse to write plaintext. Hold it back with a clear
+                // remediation, exactly like a sanitizer trip.
+                heldBack.push({ from: c.from, reasons: ['private-page-needs-key: run `clan keys init` first'] });
+                continue;
+            }
+            privateJobs.push({ path, title, fm, body: c.body, from: c.from });
+            sourceNotes.push(`${path} ← ${c.from} (private)`);
+            continue;
+        }
         // Safe frontmatter: JSON-quote scalars so a title/path containing ':' '#'
         // a newline, or a leading '-' can't break the YAML.
-        const title = oneLine(c.title);
         pages.push({
             path,
             managed: true,
-            content: `---\nname: ${JSON.stringify(title)}\ndescription: ${JSON.stringify('mined from ' + c.from)}\ntype: ${JSON.stringify(c.type)}\nsource: ${JSON.stringify(c.from)}\n${markerLines()}\n---\n\n# ${title}\n\n${c.body}\n`,
+            content: `---\n${fm}\n---\n\n# ${title}\n\n${c.body}\n`,
         });
         sourceNotes.push(`${path} ← ${c.from}`);
     }
-    const mech = { pages, heldBack, scanned: candidates.length, notes: [] };
-    if (!opts.curate)
-        return mech;
-    return runCurate(repo, identity, opts, mech, sourceNotes);
+    const scanned = candidates.length;
+    // Assemble: encrypt any private jobs (async), then optionally curate.
+    const needsAsync = privateJobs.length > 0 || !!opts.curate;
+    if (!needsAsync)
+        return { pages, heldBack, scanned, notes };
+    return (async () => {
+        for (const job of privateJobs) {
+            try {
+                const content = await encryptPrivatePage(job.fm, job.title, job.body, opts.owner);
+                pages.push({ path: job.path, managed: true, content });
+            }
+            catch (e) {
+                // clan-crypto unavailable → hold the page back rather than write plaintext.
+                heldBack.push({ from: job.from, reasons: [`private-page-encrypt-failed: ${e.message}`] });
+            }
+        }
+        const mech = { pages, heldBack, scanned, notes };
+        if (!opts.curate)
+            return mech;
+        return runCurate(repo, identity, opts, mech, sourceNotes);
+    })();
 }
 /** Apply the caller's curation hook, then re-gate its output. The curated set
  *  REPLACES the mechanical pages, but the invariants survive curation:
  *  scanSensitive on every body+path, create-only, and vault-root confinement
  *  (an LLM cannot aim a write at .claude/, .mcp.json, or outside the brain). */
 async function runCurate(repo, identity, opts, mech, sourceNotes) {
+    // Encrypted (private) pages are NEVER handed to the curator — the LLM can't
+    // (and must not) rewrite ciphertext. They pass through verbatim; only the
+    // plaintext mechanical pages are offered for curation.
+    const encrypted = mech.pages.filter(p => isPrivatePageContent(p.content));
+    const plain = mech.pages.filter(p => !isPrivatePageContent(p.content));
     let curated;
     try {
-        curated = await opts.curate({ pages: mech.pages, identity, sourceNotes });
+        curated = await opts.curate({ pages: plain, identity, sourceNotes });
         if (!Array.isArray(curated))
             throw new Error('curator returned non-array');
     }
@@ -252,7 +373,7 @@ async function runCurate(repo, identity, opts, mech, sourceNotes) {
         return { ...mech, notes: [...mech.notes, `curation failed: ${e.message}; mechanical pages used`] };
     }
     const root = brainRoot(identity);
-    const pages = [];
+    const pages = [...encrypted];
     const heldBack = [...mech.heldBack];
     const notes = [...mech.notes];
     let outside = 0;

package/dist/index.d.ts

@@ -6,14 +6,14 @@
  * from here, so their output can never drift again. The conversational wizard
  * drives these same verbs; the LLM improvises the conversation, never the writes.
  */
-export { ENGINE_VERSION, LAYOUT_VERSION, GENERATED_BY, type Tier, type Mode, type ClanIdentity, type GeneratedFile, type PlanAction, type Plan, type InspectResult, type InventoryItem, type NodeState, type McpServerInfo, type Journal, type JournalOp, type ApplyResult, type DoctorCheck, type BrainCurateInput, type BrainCurator, } from './types.js';
+export { ENGINE_VERSION, LAYOUT_VERSION, GENERATED_BY, type Tier, type Mode, type ClanIdentity, type GeneratedFile, type PlanAction, type Plan, type InspectResult, type InventoryItem, type NodeState, type McpServerInfo, type Journal, type JournalOp, type ApplyResult, type DoctorCheck, type BrainCurateInput, type BrainCurator, type BrainOwner, } from './types.js';
 export { inspect } from './inspect.js';
 export { reconcile, type ReconcileOptions } from './reconcile.js';
 export { apply, type ApplyOptions } from './apply.js';
 export { undo, listJournals, type UndoResult } from './undo.js';
 export { doctor } from './doctor.js';
 export { scanInventory, writeInventoryManifest } from './inventory.js';
-export { brainBuild, type BrainBuildResult, type BrainBuildOpts, type HeldBack } from './brain-build.js';
+export { brainBuild, encryptPrivatePage, decodePrivatePage, isPrivatePageContent, ENCRYPTED_FENCE, type BrainBuildResult, type BrainBuildOpts, type HeldBack } from './brain-build.js';
 export { scanSensitive, type ScanResult } from './sanitize.js';
 export { planMcpJson, planDistrictMcpJson, jungleLocalServer, districtBoxCreds, type JungleCreds } from './mcp.js';
 export { planBrainHook } from './hooks.js';

package/dist/index.js

@@ -13,7 +13,7 @@ export { apply } from './apply.js';
 export { undo, listJournals } from './undo.js';
 export { doctor } from './doctor.js';
 export { scanInventory, writeInventoryManifest } from './inventory.js';
-export { brainBuild } from './brain-build.js';
+export { brainBuild, encryptPrivatePage, decodePrivatePage, isPrivatePageContent, ENCRYPTED_FENCE } from './brain-build.js';
 export { scanSensitive } from './sanitize.js';
 export { planMcpJson, planDistrictMcpJson, jungleLocalServer, districtBoxCreds } from './mcp.js';
 export { planBrainHook } from './hooks.js';

package/dist/types.d.ts

@@ -6,7 +6,7 @@
  *  file's marker so a future engine can tell "my old output" from "my current
  *  output" and run migrations. Bump LAYOUT_VERSION when the template SHAPE
  *  changes (a path moves, a format changes); bump ENGINE_VERSION freely. */
-export declare const ENGINE_VERSION = "0.3.0";
+export declare const ENGINE_VERSION = "0.4.1";
 export declare const LAYOUT_VERSION = 1;
 /** The marker key written into generated-file frontmatter / headers. */
 export declare const GENERATED_BY = "clan-engine";
@@ -59,6 +59,17 @@ export interface BrainCurateInput {
  *  re-gates EVERY curated body through scanSensitive + create-only regardless —
  *  an LLM echoing a secret from context is held back like a mined one. */
 export type BrainCurator = (input: BrainCurateInput) => Promise<GeneratedFile[]>;
+/**
+ * The clan itself as an encrypted-brain recipient — its alphaId plus its X25519
+ * ENCRYPTION public key (SPKI DER base64, the same convention as
+ * step_up_devices.public_key_spki). Handed to brain-build so a page marked
+ * `private: true` can be encrypted to the owner BEFORE any write. The private
+ * half NEVER reaches the engine; only this public identity does. Shape matches
+ * @nfinitmonkeys/clan-crypto's Recipient. */
+export interface BrainOwner {
+    alphaId: string;
+    spkiB64: string;
+}
 export type ActionKind = 'create' | 'update' | 'backup-replace' | 'merge' | 'append' | 'remove' | 'skip';
 export interface PlanAction {
     kind: ActionKind;

package/dist/types.js

@@ -6,7 +6,7 @@
  *  file's marker so a future engine can tell "my old output" from "my current
  *  output" and run migrations. Bump LAYOUT_VERSION when the template SHAPE
  *  changes (a path moves, a format changes); bump ENGINE_VERSION freely. */
-export const ENGINE_VERSION = '0.3.0';
+export const ENGINE_VERSION = '0.4.1';
 export const LAYOUT_VERSION = 1;
 /** The marker key written into generated-file frontmatter / headers. */
 export const GENERATED_BY = 'clan-engine';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nfinitmonkeys/clan-engine",
-  "version": "0.3.0",
-  "description": "Deterministic setup engine for Nfinit Monkeys clans \u2014 the single template + reconciliation authority behind the published CLIs and the internal fleet tooling. Idempotent, dry-run-by-default, non-destructive.",
+  "version": "0.4.1",
+  "description": "Deterministic setup engine for Nfinit Monkeys clans — the single template + reconciliation authority behind the published CLIs and the internal fleet tooling. Idempotent, dry-run-by-default, non-destructive.",
   "type": "module",
   "bin": {
     "clan-engine": "./dist/cli.js"
@@ -37,5 +37,8 @@
   },
   "dependencies": {
     "yaml": "^2.9.0"
+  },
+  "optionalDependencies": {
+    "@nfinitmonkeys/clan-crypto": "^0.2.0"
   }
 }