@tpsdev-ai/flair 0.6.1 → 0.6.2

package/dist/bridges/runtime/allow-list.js

@@ -0,0 +1,198 @@
+/**
+ * Trust allow-list for npm code-plugin bridges.
+ *
+ * A Shape B bridge is arbitrary JavaScript fetched from npm. The spec §7
+ * requires explicit operator opt-in on first use: `flair bridge allow <name>`
+ * records the approval; subsequent invocations see the bridge on the
+ * allow-list and skip the prompt. `flair bridge revoke <name>` removes it.
+ *
+ * Approvals are pinned to a concrete package location and its package.json
+ * content digest. A name-only approval is not enough: a malicious package
+ * squatting on an allowed short-name in a different `node_modules` tree
+ * (e.g. the user approved `mem0` in ProjectA, then cd'd into ProjectB which
+ * ships a planted `node_modules/flair-bridge-mem0`) would otherwise load
+ * under the existing trust record. Each entry therefore captures:
+ *
+ *   - packageDir:        canonical (realpath) directory where the approved
+ *                        package lives on disk at allow-time.
+ *   - packageJsonSha256: hex sha256 of the package's package.json content.
+ *   - version:           the package's self-reported version (display only;
+ *                        the sha is what enforces identity).
+ *
+ * At load-time, `verifyAllow(discovered)` re-checks all three. A change in
+ * any triggers a BridgeRuntimeError pointing the operator back at
+ * `flair bridge allow` — either the move is intentional (re-approve) or
+ * it is a squat (refuse).
+ *
+ * Design notes:
+ *  - YAML (Shape A) + built-in bridges skip this gate entirely. They don't
+ *    execute arbitrary JS.
+ *  - The store is a simple JSON file at ~/.flair/bridges-allowed.json.
+ *    No separate DB, no Harper dependency — the trust decision should
+ *    still work when Flair's own service is down.
+ *  - Migration: older entries from 0.6.0/0.6.1 carry only {name, allowedAt}.
+ *    `verifyAllow` treats those as invalid and forces re-approval on next
+ *    load. Acceptable cost — no known external consumers pre-1.0.
+ */
+import { promises as fsp } from "node:fs";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+function resolvePath(opts) {
+    return opts?.path ?? join(homedir(), ".flair", "bridges-allowed.json");
+}
+function hasEntryFields(e) {
+    return (typeof e?.name === "string" &&
+        typeof e?.allowedAt === "string" &&
+        typeof e?.packageDir === "string" &&
+        typeof e?.packageJsonSha256 === "string");
+}
+async function read(path) {
+    if (!existsSync(path))
+        return { allowed: [] };
+    try {
+        const raw = await fsp.readFile(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.allowed))
+            return { allowed: [] };
+        // Keep structurally valid entries only. Legacy name-only rows are
+        // dropped here so `verifyAllow` reports not-allowed (forcing re-approve).
+        return {
+            allowed: parsed.allowed.filter(hasEntryFields).map((e) => ({
+                name: e.name,
+                allowedAt: e.allowedAt,
+                packageDir: e.packageDir,
+                packageJsonSha256: e.packageJsonSha256,
+                ...(typeof e.version === "string" ? { version: e.version } : {}),
+            })),
+        };
+    }
+    catch {
+        return { allowed: [] };
+    }
+}
+async function write(path, data) {
+    await fsp.mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    await fsp.rename(tmp, path);
+}
+/**
+ * Canonicalize a filesystem path. Resolves symlinks so node_modules hoisting
+ * and pnpm-style content-addressed stores still hash-match reliably.
+ */
+async function canonical(path) {
+    try {
+        return await fsp.realpath(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * Hash a package's package.json file. The sha changes whenever the package
+ * contents "change enough to matter" — version bumps, name changes, and
+ * realistically most substantive updates touch package.json. It is NOT a
+ * hash of every file in the package; that would be slower and more fragile
+ * without closing the meaningful attack paths (since a squatter needs the
+ * right package.json anyway to survive discovery).
+ */
+export async function digestPackage(packageDir) {
+    const canonicalDir = await canonical(packageDir);
+    const pkgJsonPath = join(canonicalDir, "package.json");
+    const raw = await fsp.readFile(pkgJsonPath, "utf-8");
+    const sha = createHash("sha256").update(raw).digest("hex");
+    let version;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.version === "string")
+            version = parsed.version;
+    }
+    catch {
+        // A malformed package.json is itself a refusal signal — but leave that
+        // to the import path; here we just decline to record a version.
+    }
+    return { canonicalDir, sha256: sha, version };
+}
+/**
+ * Check if a name appears in the allow-list. Useful for UI listings; NOT a
+ * trust decision — use `verifyAllow` for load-time security checks.
+ */
+export async function isAllowed(name, opts) {
+    const data = await read(resolvePath(opts));
+    return data.allowed.some((e) => e.name === name);
+}
+/**
+ * Load-time trust check. Verifies the discovered package still matches the
+ * approval record by canonical path AND package.json sha. Anything else is
+ * a refusal — the operator must re-run `flair bridge allow <name>`.
+ */
+export async function verifyAllow(discovered, opts) {
+    const data = await read(resolvePath(opts));
+    const entry = data.allowed.find((e) => e.name === discovered.name);
+    if (!entry)
+        return { ok: false, reason: "not-allowed" };
+    // Guard: if we ever loaded a partial record, refuse. Belt-and-braces;
+    // read() already filters these, but if someone hand-edits the file we
+    // don't want to silently bypass the check.
+    if (!entry.packageDir || !entry.packageJsonSha256) {
+        return { ok: false, reason: "entry-incomplete", entry };
+    }
+    let observed;
+    try {
+        observed = await digestPackage(discovered.path);
+    }
+    catch {
+        return { ok: false, reason: "package-missing", entry };
+    }
+    if (observed.canonicalDir !== entry.packageDir) {
+        return { ok: false, reason: "path-mismatch", entry, observedPath: observed.canonicalDir };
+    }
+    if (observed.sha256 !== entry.packageJsonSha256) {
+        return { ok: false, reason: "digest-mismatch", entry, observedDigest: observed.sha256 };
+    }
+    return { ok: true, entry };
+}
+/**
+ * Approve a package for code-plugin execution. `packageDir` must be the
+ * directory holding the package.json — typically discovered via
+ * `flair bridge list` and passed through by the CLI layer.
+ */
+export async function allow(name, packageDir, opts) {
+    const listPath = resolvePath(opts);
+    const data = await read(listPath);
+    const { canonicalDir, sha256, version } = await digestPackage(packageDir);
+    const now = new Date().toISOString();
+    const existing = data.allowed.find((e) => e.name === name);
+    if (existing && existing.packageDir === canonicalDir && existing.packageJsonSha256 === sha256) {
+        return { alreadyAllowed: true, updated: false, entry: existing };
+    }
+    const entry = {
+        name,
+        allowedAt: now,
+        packageDir: canonicalDir,
+        packageJsonSha256: sha256,
+        ...(version ? { version } : {}),
+    };
+    data.allowed = data.allowed.filter((e) => e.name !== name);
+    data.allowed.push(entry);
+    data.allowed.sort((a, b) => a.name.localeCompare(b.name));
+    await write(listPath, data);
+    return { alreadyAllowed: false, updated: !!existing, entry };
+}
+export async function revoke(name, opts) {
+    const path = resolvePath(opts);
+    const data = await read(path);
+    const before = data.allowed.length;
+    data.allowed = data.allowed.filter((e) => e.name !== name);
+    if (data.allowed.length === before) {
+        return { wasAllowed: false };
+    }
+    await write(path, data);
+    return { wasAllowed: true };
+}
+export async function list(opts) {
+    const data = await read(resolvePath(opts));
+    return data.allowed;
+}

package/dist/bridges/runtime/import-runner.js

@@ -26,7 +26,11 @@ export async function runImport(opts) {
     let total = 0;
     let imported = 0;
     let skipped = 0;
-    for await (const m of importFromYaml(opts.descriptor, { cwd: opts.cwd, ctx: opts.ctx })) {
+    const iterable = opts.source
+        ?? (opts.descriptor
+            ? importFromYaml(opts.descriptor, { cwd: opts.cwd, ctx: opts.ctx })
+            : (() => { throw new BridgeRuntimeError({ bridge: opts.bridgeName, op: "import", field: "(source)", expected: "descriptor or source", got: "neither", hint: "runImport requires exactly one of opts.descriptor (YAML) or opts.source (AsyncIterable)" }); })());
+    for await (const m of iterable) {
         total++;
         const resolvedAgent = m.agentId ?? opts.agentId;
         if (!resolvedAgent) {
@@ -35,7 +39,7 @@ export async function runImport(opts) {
             // the operator should know whether this is a descriptor bug or a
             // missing flag.
             throw new BridgeRuntimeError({
-                bridge: opts.descriptor.name,
+                bridge: opts.bridgeName,
                 op: "import",
                 field: "agentId",
                 expected: "set on record OR provided via --agent",
@@ -86,7 +90,7 @@ export async function runImport(opts) {
         catch (err) {
             // Wrap PUT errors so they read consistently with other BridgeRuntimeErrors.
             throw new BridgeRuntimeError({
-                bridge: opts.descriptor.name,
+                bridge: opts.bridgeName,
                 op: "import",
                 record: total,
                 field: "(write)",

package/dist/bridges/runtime/load-bridge.js

@@ -0,0 +1,126 @@
+/**
+ * Unified loader for all bridge sources (replaces load-descriptor.ts).
+ *
+ * Returns a `LoadedBridge` discriminated union. Runners dispatch on
+ * `.kind`:
+ *   - "yaml": use the existing YAML runtime (applyMap, parseRecords, etc.)
+ *   - "code": call the plugin's bridge.import() / bridge.export() directly
+ *
+ * For code-plugin sources (npm packages), the allow-list gate runs first:
+ * if not allowed, throw a BridgeRuntimeError pointing the operator at
+ * `flair bridge allow <name>`.
+ */
+import { BridgeRuntimeError } from "../types.js";
+import { loadYamlDescriptor } from "./yaml-loader.js";
+import { BUILTIN_BY_NAME } from "../builtins/index.js";
+import { loadCodePlugin } from "./load-plugin.js";
+import { verifyAllow } from "./allow-list.js";
+export async function loadBridge(discovered, opts = {}) {
+    switch (discovered.source) {
+        case "builtin": {
+            const builtin = BUILTIN_BY_NAME.get(discovered.name);
+            if (!builtin) {
+                throw new BridgeRuntimeError({
+                    bridge: discovered.name,
+                    op: "import",
+                    field: "(builtin)",
+                    expected: "registered built-in name",
+                    got: discovered.name,
+                    hint: `built-in "${discovered.name}" not in the registry — likely code drift between discover.ts and builtins/index.ts`,
+                });
+            }
+            return { kind: "yaml", descriptor: builtin.descriptor, source: discovered };
+        }
+        case "project-yaml":
+        case "user-yaml": {
+            const descriptor = await loadYamlDescriptor(discovered.path);
+            return { kind: "yaml", descriptor, source: discovered };
+        }
+        case "npm-package": {
+            if (!opts.skipAllowCheck) {
+                const verdict = await verifyAllow(discovered, { path: opts.allowListPath });
+                if (!verdict.ok) {
+                    throw new BridgeRuntimeError({
+                        bridge: discovered.name,
+                        op: "import",
+                        path: discovered.path,
+                        field: "(trust)",
+                        expected: verdict.reason === "not-allowed" ? "allow-listed code plugin" : "approved package at recorded location/digest",
+                        got: verdict.reason,
+                        hint: trustHint(discovered.name, verdict),
+                        context: trustContext(discovered, verdict),
+                    });
+                }
+            }
+            const plugin = await loadCodePlugin(discovered, { importer: opts.importer });
+            return { kind: "code", plugin, source: discovered };
+        }
+    }
+}
+function trustContext(discovered, verdict) {
+    switch (verdict.reason) {
+        case "not-allowed":
+            return { name: discovered.name };
+        case "path-mismatch":
+            return {
+                name: discovered.name,
+                approvedPath: verdict.entry.packageDir,
+                observedPath: verdict.observedPath,
+                approvedVersion: verdict.entry.version ?? "(unknown)",
+                approvedAt: verdict.entry.allowedAt,
+            };
+        case "digest-mismatch":
+            return {
+                name: discovered.name,
+                packagePath: verdict.entry.packageDir,
+                approvedVersion: verdict.entry.version ?? "(unknown)",
+                approvedDigest: verdict.entry.packageJsonSha256,
+                observedDigest: verdict.observedDigest,
+                approvedAt: verdict.entry.allowedAt,
+            };
+        case "entry-incomplete":
+            return { name: discovered.name };
+        case "package-missing":
+            return {
+                name: discovered.name,
+                approvedPath: verdict.entry?.packageDir ?? "(unknown)",
+                discoveredPath: discovered.path,
+            };
+    }
+}
+function trustHint(name, verdict) {
+    const reapprove = `flair bridge allow ${name}`;
+    switch (verdict.reason) {
+        case "not-allowed":
+            return `npm code plugins run arbitrary JavaScript. First-use approval required. Run: ${reapprove}`;
+        case "path-mismatch":
+            return `approved package lives at ${verdict.entry.packageDir}, but a different package with the same name was discovered at ${verdict.observedPath}. This is how local squatting attacks present. If the new location is intentional, re-run: ${reapprove}`;
+        case "digest-mismatch":
+            return `package.json contents changed since approval (recorded sha ${verdict.entry.packageJsonSha256.slice(0, 12)}…, observed ${verdict.observedDigest.slice(0, 12)}…). Re-run if the update is intentional: ${reapprove}`;
+        case "entry-incomplete":
+            return `allow-list entry for "${name}" is missing a location/digest (likely from a pre-fix Flair version). Re-run: ${reapprove}`;
+        case "package-missing":
+            return `package at ${verdict.entry?.packageDir ?? "(unknown)"} could not be read; allow-list verification cannot proceed`;
+    }
+}
+/**
+ * Kept as a shim for code paths that still call the old name. Remove once
+ * all call sites move to loadBridge directly.
+ *
+ * Returns the YAML descriptor when the source produces one; throws for
+ * code plugins (they don't have a YamlBridgeDescriptor representation).
+ */
+export async function loadDescriptor(discovered) {
+    const loaded = await loadBridge(discovered);
+    if (loaded.kind === "yaml")
+        return loaded.descriptor;
+    throw new BridgeRuntimeError({
+        bridge: discovered.name,
+        op: "import",
+        path: discovered.path,
+        field: "(kind)",
+        expected: "yaml descriptor",
+        got: "code plugin",
+        hint: "this code path expected a YAML descriptor; the bridge is a code plugin — caller should dispatch on loadBridge().kind instead",
+    });
+}

package/dist/bridges/runtime/load-plugin.js

@@ -0,0 +1,127 @@
+/**
+ * Dynamic loader for Shape B code-plugin bridges.
+ *
+ * Given a discovered `npm-package` source, dynamic-import the package,
+ * validate that it exports a `MemoryBridge`, and return the loaded module.
+ * The import is done via `createRequire` relative to the package root so
+ * scoped packages and deep nested deps resolve correctly.
+ *
+ * Validation is deliberately minimal: `name`, `version`, `kind`, and at
+ * least one of `import` / `export` must be present and look right. The
+ * spec §6 contract is "duck-type at runtime, strict error messages."
+ */
+import { pathToFileURL } from "node:url";
+import { BridgeRuntimeError } from "../types.js";
+const DEFAULT_IMPORTER = (spec) => import(spec);
+export async function loadCodePlugin(discovered, opts = {}) {
+    if (discovered.source !== "npm-package") {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            field: "source",
+            expected: "npm-package",
+            got: discovered.source,
+            hint: "loadCodePlugin only handles Shape B (npm code plugin) bridges; YAML descriptors go through the YAML loader",
+        });
+    }
+    const importer = opts.importer ?? DEFAULT_IMPORTER;
+    // Package root path — the entry point is resolved by Node's package.json
+    // "main"/"exports" fields. Use a file:// URL so Node resolves it as a
+    // filesystem path rather than a bare specifier.
+    const spec = pathToFileURL(discovered.path + "/").href;
+    let mod;
+    try {
+        mod = await importer(spec);
+    }
+    catch (err) {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "(import)",
+            expected: "importable npm package",
+            got: err?.code ?? "import error",
+            hint: `could not dynamic-import ${spec}: ${err?.message ?? err}`,
+        });
+    }
+    const candidate = pickBridgeExport(mod);
+    if (!candidate) {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "exports",
+            expected: "named `bridge` export or default export implementing MemoryBridge",
+            got: typeof mod === "object" && mod !== null ? `exports=${Object.keys(mod).join(",") || "(empty)"}` : typeof mod,
+            hint: `flair-bridge-<name> packages must export \`bridge\` (or default-export) a MemoryBridge. See specs/FLAIR-BRIDGES.md §6`,
+        });
+    }
+    // Validate the shape. Keep this minimal — we trust the plugin author
+    // to build a working MemoryBridge; we just need enough to route calls.
+    validateBridge(discovered, candidate);
+    return candidate;
+}
+function pickBridgeExport(mod) {
+    if (!mod || typeof mod !== "object")
+        return null;
+    const m = mod;
+    if (isBridgeLike(m.bridge))
+        return m.bridge;
+    if (isBridgeLike(m.default))
+        return m.default;
+    if (isBridgeLike(m))
+        return m;
+    return null;
+}
+function isBridgeLike(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const o = x;
+    return typeof o.name === "string" && (typeof o.import === "function" || typeof o.export === "function");
+}
+function validateBridge(discovered, b) {
+    if (typeof b.name !== "string" || !b.name) {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "name",
+            expected: "non-empty string",
+            got: JSON.stringify(b.name),
+            hint: "MemoryBridge.name must be a non-empty string matching the npm package's flair-bridge-<name>",
+        });
+    }
+    if (b.name !== discovered.name) {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "name",
+            expected: `"${discovered.name}" (from package name flair-bridge-${discovered.name})`,
+            got: `"${b.name}"`,
+            hint: "MemoryBridge.name must match the npm package's public name suffix — mismatch would surprise discovery and allow-list lookups",
+        });
+    }
+    if (b.kind !== "file" && b.kind !== "api") {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "kind",
+            expected: `"file" | "api"`,
+            got: JSON.stringify(b.kind),
+            hint: "MemoryBridge.kind must be 'file' or 'api'",
+        });
+    }
+    if (typeof b.import !== "function" && typeof b.export !== "function") {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "(methods)",
+            expected: "at least one of `import` or `export`",
+            got: "neither",
+            hint: "MemoryBridge needs at least one of import/export implemented. See spec §6",
+        });
+    }
+}

package/dist/cli.js

@@ -3544,7 +3544,7 @@ bridge
     const cwd = opts.cwd ?? srcArg ?? process.cwd();
     const { discover } = await import("./bridges/discover.js");
     const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
-    const { loadDescriptor } = await import("./bridges/runtime/load-descriptor.js");
+    const { loadBridge } = await import("./bridges/runtime/load-bridge.js");
     const { runImport } = await import("./bridges/runtime/import-runner.js");
     const { makeContext } = await import("./bridges/runtime/context.js");
     const { BridgeRuntimeError } = await import("./bridges/types.js");
@@ -3554,9 +3554,9 @@ bridge
         console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
         process.exit(1);
     }
-    let descriptor;
+    let loaded;
     try {
-        descriptor = await loadDescriptor(target);
+        loaded = await loadBridge(target);
     }
     catch (err) {
         printBridgeError(err);
@@ -3591,10 +3591,10 @@ bridge
         if (ev.type === "done") {
             const noun = (n) => `${n} ${n === 1 ? "memory" : "memories"}`;
             if (opts.dryRun) {
-                console.log(`\n${descriptor.name}: would import ${noun(ev.total)}. Re-run without --dry-run to write to Flair.`);
+                console.log(`\n${target.name}: would import ${noun(ev.total)}. Re-run without --dry-run to write to Flair.`);
             }
             else {
-                console.log(`\n${descriptor.name}: imported ${ev.imported}/${ev.total} memories${ev.skipped > 0 ? ` (${ev.skipped} skipped)` : ""}.`);
+                console.log(`\n${target.name}: imported ${ev.imported}/${ev.total} memories${ev.skipped > 0 ? ` (${ev.skipped} skipped)` : ""}.`);
             }
             return;
         }
@@ -3611,15 +3611,40 @@ bridge
         }
     };
     try {
-        await runImport({
-            descriptor,
-            cwd,
-            agentId,
-            dryRun: !!opts.dryRun,
-            putMemory,
-            onProgress,
-            ctx,
-        });
+        if (loaded.kind === "yaml") {
+            await runImport({
+                bridgeName: target.name,
+                descriptor: loaded.descriptor,
+                cwd,
+                agentId,
+                dryRun: !!opts.dryRun,
+                putMemory,
+                onProgress,
+                ctx,
+            });
+        }
+        else {
+            // Code plugin: invoke bridge.import(opts, ctx) directly; the plugin
+            // returns an AsyncIterable of BridgeMemory that runImport processes.
+            if (!loaded.plugin.import) {
+                console.error(`Bridge "${name}" is a code plugin without an import() function — can only export through it.`);
+                process.exit(1);
+            }
+            // Code-plugin options: pass through all --X flags as a single object.
+            // The plugin's declared `options` descriptor validates what it actually cares about.
+            const pluginOpts = { ...opts };
+            const source = loaded.plugin.import(pluginOpts, ctx);
+            await runImport({
+                bridgeName: target.name,
+                source,
+                cwd,
+                agentId,
+                dryRun: !!opts.dryRun,
+                putMemory,
+                onProgress,
+                ctx,
+            });
+        }
     }
     catch (err) {
         if (err instanceof BridgeRuntimeError) {
@@ -3651,7 +3676,7 @@ bridge
     const cwd = opts.cwd ?? dst;
     const { discover } = await import("./bridges/discover.js");
     const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
-    const { loadDescriptor } = await import("./bridges/runtime/load-descriptor.js");
+    const { loadBridge } = await import("./bridges/runtime/load-bridge.js");
     const { runExport } = await import("./bridges/runtime/export-runner.js");
     const { makeContext } = await import("./bridges/runtime/context.js");
     const { BridgeRuntimeError } = await import("./bridges/types.js");
@@ -3661,18 +3686,22 @@ bridge
         console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
         process.exit(1);
     }
-    let descriptor;
+    let loaded;
     try {
-        descriptor = await loadDescriptor(target);
+        loaded = await loadBridge(target);
     }
     catch (err) {
         printBridgeError(err);
         process.exit(1);
     }
-    if (!descriptor.export) {
+    if (loaded.kind === "yaml" && !loaded.descriptor.export) {
         console.error(`Bridge "${name}" has no export block — cannot export through it.`);
         process.exit(1);
     }
+    if (loaded.kind === "code" && !loaded.plugin.export) {
+        console.error(`Bridge "${name}" is a code plugin without an export() function — can only import through it.`);
+        process.exit(1);
+    }
     const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
     const ctx = makeContext({ bridge: name });
     // Memory fetcher — paginates GET /Memory?agentId=... applying any
@@ -3710,10 +3739,10 @@ bridge
     const onProgress = (ev) => {
         if (ev.type === "done") {
             if (opts.dryRun) {
-                console.log(`\n${descriptor.name}: would export ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total. Re-run without --dry-run to write.`);
+                console.log(`\n${target.name}: would export ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total. Re-run without --dry-run to write.`);
             }
             else {
-                console.log(`\n${descriptor.name}: exported ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total.`);
+                console.log(`\n${target.name}: exported ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total.`);
             }
             return;
         }
@@ -3733,15 +3762,28 @@ bridge
         process.stdout.write(`\r  filtering memory ${ev.ordinal}...`.padEnd(60));
     };
     try {
-        await runExport({
-            descriptor,
-            cwd,
-            fetchMemories,
-            filters: { agentId, subject: opts.subject, source: opts.source, since: opts.since },
-            dryRun: !!opts.dryRun,
-            ctx,
-            onProgress,
-        });
+        if (loaded.kind === "yaml") {
+            await runExport({
+                descriptor: loaded.descriptor,
+                cwd,
+                fetchMemories,
+                filters: { agentId, subject: opts.subject, source: opts.source, since: opts.since },
+                dryRun: !!opts.dryRun,
+                ctx,
+                onProgress,
+            });
+        }
+        else {
+            // Code plugin export: invoke plugin.export(memoryStream, opts, ctx) directly.
+            // Plugin writes to its target however it likes (HTTP, file, etc.).
+            if (opts.dryRun) {
+                console.log(`${target.name}: dry-run not supported for code-plugin exports; aborting before invoking plugin.export().`);
+                process.exit(2);
+            }
+            const pluginOpts = { ...opts };
+            await loaded.plugin.export(fetchMemories({ agentId, subject: opts.subject, source: opts.source, since: opts.since }), pluginOpts, ctx);
+            console.log(`${target.name}: code-plugin export completed. Record count not reported by the plugin.`);
+        }
     }
     catch (err) {
         if (err instanceof BridgeRuntimeError) {
@@ -3762,7 +3804,7 @@ bridge
     const cwd = opts.cwd ?? process.cwd();
     const { discover } = await import("./bridges/discover.js");
     const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
-    const { loadDescriptor } = await import("./bridges/runtime/load-descriptor.js");
+    const { loadBridge } = await import("./bridges/runtime/load-bridge.js");
     const { runRoundTrip } = await import("./bridges/runtime/roundtrip.js");
     const { BridgeRuntimeError } = await import("./bridges/types.js");
     const found = await discover({ builtins: builtinDiscoveryRecords() });
@@ -3771,25 +3813,30 @@ bridge
         console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
         process.exit(1);
     }
-    let descriptor;
+    let loaded;
     try {
-        descriptor = await loadDescriptor(target);
+        loaded = await loadBridge(target);
     }
     catch (err) {
         printBridgeError(err);
         process.exit(1);
     }
+    if (loaded.kind === "code") {
+        console.error(`Bridge "${name}" is a code plugin — round-trip testing for code plugins lands in slice 3d (requires mocked fetch transport).`);
+        console.error(`For now, code plugins should ship their own tests alongside the npm package.`);
+        process.exit(2);
+    }
     try {
-        const result = await runRoundTrip({ descriptor, cwd, fixturePath: opts.fixture });
+        const result = await runRoundTrip({ descriptor: loaded.descriptor, cwd, fixturePath: opts.fixture });
         if (opts.json) {
             console.log(JSON.stringify(result, null, 2));
             process.exit(result.passed ? 0 : 1);
         }
         if (result.passed) {
-            console.log(`✅ ${descriptor.name} round-trip passed (${result.expectedCount} record${result.expectedCount === 1 ? "" : "s"}).`);
+            console.log(`✅ ${target.name} round-trip passed (${result.expectedCount} record${result.expectedCount === 1 ? "" : "s"}).`);
             process.exit(0);
         }
-        console.log(`❌ ${descriptor.name} round-trip failed.`);
+        console.log(`❌ ${target.name} round-trip failed.`);
         console.log(`   expected ${result.expectedCount} records, got ${result.actualCount} back.`);
         if (result.missingInPass2.length > 0) {
             console.log(`   missing from re-import (${result.missingInPass2.length}):`);
@@ -3825,11 +3872,92 @@ bridge
         process.exit(1);
     }
 });
+bridge
+    .command("allow <name>")
+    .description("Approve an npm code-plugin bridge for execution. Approval is pinned to the package's location and package.json contents — a malicious package squatting on the same name in a different node_modules tree will be refused at load-time.")
+    .action(async (name) => {
+    const { discover } = await import("./bridges/discover.js");
+    const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
+    const { allow } = await import("./bridges/runtime/allow-list.js");
+    const found = await discover({ builtins: builtinDiscoveryRecords() });
+    const target = found.find((b) => b.name === name);
+    if (!target) {
+        console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
+        process.exit(1);
+    }
+    if (target.source !== "npm-package") {
+        console.error(`"${name}" is a ${target.source} bridge; only npm code plugins require allow-list approval.`);
+        console.error(`YAML and built-in bridges run via the descriptor runtime and don't execute arbitrary JS.`);
+        process.exit(1);
+    }
+    try {
+        const result = await allow(name, target.path);
+        if (result.alreadyAllowed) {
+            console.log(`${name} was already allowed at ${result.entry.packageDir} — no change.`);
+            return;
+        }
+        const verb = result.updated ? "re-approved" : "allowed";
+        console.log(`✓ ${name} ${verb}.`);
+        console.log(`  location: ${result.entry.packageDir}`);
+        console.log(`  version:  ${result.entry.version ?? "(not declared)"}`);
+        console.log(`  digest:   ${result.entry.packageJsonSha256.slice(0, 16)}…`);
+        console.log(`  If the package later moves or its package.json content changes, execution is refused until you re-run this command.`);
+        console.log(`  Revoke anytime with: flair bridge revoke ${name}`);
+    }
+    catch (err) {
+        console.error(`Failed to approve "${name}": ${err?.message ?? err}`);
+        process.exit(1);
+    }
+});
+bridge
+    .command("revoke <name>")
+    .description("Revoke approval for an npm code-plugin bridge (future invocations will require `flair bridge allow <name>` again)")
+    .action(async (name) => {
+    const { revoke } = await import("./bridges/runtime/allow-list.js");
+    const result = await revoke(name);
+    if (!result.wasAllowed) {
+        console.log(`${name} was not on the allow-list — no change.`);
+        return;
+    }
+    console.log(`✓ ${name} revoked. Future invocations require \`flair bridge allow ${name}\` again.`);
+});
+bridge
+    .command("allow-list")
+    .description("Show the allow-listed code-plugin bridges")
+    .option("--json", "Emit raw JSON")
+    .action(async (opts) => {
+    const { list: listAllowed } = await import("./bridges/runtime/allow-list.js");
+    const entries = await listAllowed();
+    if (opts.json) {
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+    }
+    if (entries.length === 0) {
+        console.log("No code-plugin bridges are allow-listed yet.");
+        console.log("Allow one with: flair bridge allow <name>");
+        return;
+    }
+    const nameW = Math.max(4, ...entries.map((e) => e.name.length));
+    const verW = Math.max(7, ...entries.map((e) => (e.version ?? "—").length));
+    console.log(`  ${"name".padEnd(nameW)}  ${"version".padEnd(verW)}  allowed-at               location / digest`);
+    for (const e of entries) {
+        console.log(`  ${e.name.padEnd(nameW)}  ${(e.version ?? "—").padEnd(verW)}  ${e.allowedAt}  ${e.packageDir}`);
+        console.log(`  ${" ".repeat(nameW)}  ${" ".repeat(verW)}  ${" ".repeat(24)}  sha256:${e.packageJsonSha256.slice(0, 16)}…`);
+    }
+});
 function printBridgeError(err) {
     // Pretty-print BridgeRuntimeError as the structured shape from §10 of the
     // spec, plus a one-line human summary so the operator gets both.
     const detail = err?.detail;
     if (detail && typeof detail === "object") {
+        // Trust-check failures get a dedicated, operator-facing rendering.
+        // Dumping the full spec-§10 JSON is useful when an operator is
+        // debugging a broken YAML descriptor; for trust errors it buries the
+        // one thing that matters — the command to re-approve.
+        if (detail.field === "(trust)") {
+            printTrustError(detail);
+            return;
+        }
         console.error(`Bridge error: ${detail.hint ?? err.message}`);
         console.error(JSON.stringify(detail, null, 2));
     }
@@ -3837,6 +3965,73 @@ function printBridgeError(err) {
         console.error(`Bridge error: ${err.message ?? String(err)}`);
     }
 }
+function printTrustError(detail) {
+    const name = detail.bridge ?? "(unknown)";
+    const ctx = detail.context ?? {};
+    const reapprove = `  flair bridge allow ${name}`;
+    const bar = "─".repeat(60);
+    const header = (title) => {
+        console.error("");
+        console.error(`⚠ ${title} — ${name}`);
+        console.error(bar);
+    };
+    const footer = (label) => {
+        console.error("");
+        console.error(`${label}:`);
+        console.error(reapprove);
+        console.error("");
+    };
+    switch (detail.got) {
+        case "not-allowed":
+            header("Approval required");
+            console.error("This bridge is an npm code plugin — it runs arbitrary JavaScript.");
+            console.error("First-use approval is required before Flair will execute it.");
+            footer("Approve it with");
+            return;
+        case "path-mismatch":
+            header("Trust check failed: package location changed");
+            console.error("A different package with the same name was discovered. This is how");
+            console.error("local squatting attacks present — a planted `node_modules/flair-bridge-*`");
+            console.error("in an unrelated project tree.");
+            console.error("");
+            console.error(`  approved: ${ctx.approvedPath ?? "(unknown)"}`);
+            console.error(`            version ${ctx.approvedVersion ?? "?"} at ${ctx.approvedAt ?? "?"}`);
+            console.error(`  now:      ${ctx.observedPath ?? "(unknown)"}`);
+            footer("If the new location is intentional, re-approve");
+            return;
+        case "digest-mismatch":
+            header("Trust check failed: package contents changed");
+            console.error("The package.json at the approved location has changed since you");
+            console.error("approved this bridge. This fires on every upgrade — it's a trust");
+            console.error("event, not an error. If the update is intentional, re-approve.");
+            console.error("");
+            console.error(`  location:          ${ctx.packagePath ?? "(unknown)"}`);
+            console.error(`  approved version:  ${ctx.approvedVersion ?? "?"}   (at ${ctx.approvedAt ?? "?"})`);
+            console.error(`  approved digest:   sha256:${(ctx.approvedDigest ?? "").slice(0, 16)}…`);
+            console.error(`  observed digest:   sha256:${(ctx.observedDigest ?? "").slice(0, 16)}…`);
+            footer("Re-approve");
+            return;
+        case "entry-incomplete":
+            header("Trust check failed: approval record is incomplete");
+            console.error("The allow-list entry for this bridge is missing a location or digest.");
+            console.error("This usually means the record was created by a pre-fix Flair version");
+            console.error("(0.6.0 / 0.6.1) that only stored the name. Re-approve to upgrade.");
+            footer("Re-approve");
+            return;
+        case "package-missing":
+            header("Trust check failed: approved package missing on disk");
+            console.error("The package location recorded at allow-time is no longer readable.");
+            console.error("");
+            console.error(`  approved at:  ${ctx.approvedPath ?? "(unknown)"}`);
+            console.error(`  discovered:   ${ctx.discoveredPath ?? "(unknown)"}`);
+            footer("Reinstall the package, then re-approve");
+            return;
+        default:
+            // Unknown trust sub-reason — fall back to the raw structured print.
+            console.error(`Bridge error (trust): ${detail.hint ?? detail.got ?? "unknown"}`);
+            console.error(JSON.stringify(detail, null, 2));
+    }
+}
 // ─── flair backup ────────────────────────────────────────────────────────────
 program
     .command("backup")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",

package/dist/bridges/runtime/load-descriptor.js

@@ -1,46 +0,0 @@
-/**
- * Unified descriptor loader.
- *
- * Given a discovered bridge, resolve it into a `YamlBridgeDescriptor`
- * that the runtime executor can drive — regardless of whether the
- * descriptor came from the in-tree built-in registry, a project-local
- * YAML, a user-scoped YAML, or an npm package.
- *
- * Code-plugin bridges (Shape B, npm packages) are not supported in
- * slice 2 — calling `loadDescriptor` on one returns a structured error
- * pointing at slice 3.
- */
-import { BridgeRuntimeError } from "../types.js";
-import { loadYamlDescriptor } from "./yaml-loader.js";
-import { BUILTIN_BY_NAME } from "../builtins/index.js";
-export async function loadDescriptor(discovered) {
-    switch (discovered.source) {
-        case "builtin": {
-            const builtin = BUILTIN_BY_NAME.get(discovered.name);
-            if (!builtin) {
-                throw new BridgeRuntimeError({
-                    bridge: discovered.name,
-                    op: "import",
-                    field: "(builtin)",
-                    expected: `registered built-in name`,
-                    got: discovered.name,
-                    hint: `discovery surfaced built-in "${discovered.name}" but the registry has no entry — likely a code drift between discover.ts and builtins/index.ts`,
-                });
-            }
-            return builtin.descriptor;
-        }
-        case "project-yaml":
-        case "user-yaml":
-            return await loadYamlDescriptor(discovered.path);
-        case "npm-package":
-            throw new BridgeRuntimeError({
-                bridge: discovered.name,
-                op: "import",
-                path: discovered.path,
-                field: "(kind)",
-                expected: "yaml file or built-in",
-                got: "npm code plugin",
-                hint: "code-plugin bridge runtime ships in slice 3 of FLAIR-BRIDGES (alongside the `flair bridge allow` trust prompt). Use a YAML descriptor in the meantime, or wait for slice 3.",
-            });
-    }
-}