@zieglar/pi-chat-exchange 0.0.0-stage → 0.2.0

package/dist/runtime/desktop-manifest.js

@@ -0,0 +1,65 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, normalize } from "node:path";
+import { admitExecutable, admitInstallationDirectory, qualifyNodeExecutable } from "./executables.js";
+const SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+const invalid = () => { throw new Error("CE_DESKTOP_CONFIG_INVALID"); };
+/** Explicit preparation of an unpacked, operator-owned LOCAL copy. This never
+ * installs/registers/launches the plugin, resolves binding credentials or opens Store. */
+export function configureDesktopManifest(pluginRoot, nodePath) {
+    let fd;
+    let temporary;
+    try {
+        if (!isAbsolute(pluginRoot) || normalize(pluginRoot) !== pluginRoot || realpathSync(pluginRoot) !== pluginRoot)
+            invalid();
+        admitInstallationDirectory(pluginRoot);
+        const root = lstatSync(pluginRoot);
+        if (!root.isDirectory() || root.uid !== process.geteuid?.() || (root.mode & 0o777) !== 0o700)
+            invalid();
+        const server = lstatSync(join(pluginRoot, "server"));
+        const launcher = lstatSync(join(pluginRoot, "server/launch.mjs"));
+        if (!server.isDirectory() || server.isSymbolicLink() || !launcher.isFile() || launcher.isSymbolicLink())
+            invalid();
+        const manifestPath = join(pluginRoot, "mcp.json");
+        fd = openSync(manifestPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const original = fstatSync(fd);
+        if (!original.isFile() || original.uid !== process.geteuid?.() || original.nlink !== 1 || original.size > 16_384 || (original.mode & 0o022) !== 0)
+            invalid();
+        const text = readFileSync(fd, "utf8");
+        if (Buffer.byteLength(text) > 16_384)
+            invalid();
+        const template = JSON.parse(text);
+        if (template.$schema !== SCHEMA || Object.keys(template).sort().join(",") !== "$schema,mcpServers" ||
+            template.mcpServers === null || typeof template.mcpServers !== "object" || Array.isArray(template.mcpServers) ||
+            Object.keys(template.mcpServers).length !== 0)
+            invalid();
+        closeSync(fd);
+        fd = undefined;
+        const command = admitExecutable(nodePath);
+        qualifyNodeExecutable(command);
+        const manifest = { $schema: SCHEMA, mcpServers: { "pi-chat-exchange": {
+                    type: "stdio", command, args: ["${PLUGIN_ROOT}/server/launch.mjs"], cwd: "${PLUGIN_ROOT}",
+                } } };
+        temporary = join(pluginRoot, `.mcp-${randomUUID()}.tmp`);
+        fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        writeFileSync(fd, `${JSON.stringify(manifest, undefined, 2)}\n`);
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        const current = lstatSync(manifestPath);
+        if (current.dev !== original.dev || current.ino !== original.ino || current.size !== original.size || current.mtimeMs !== original.mtimeMs)
+            invalid();
+        renameSync(temporary, manifestPath);
+        temporary = undefined;
+    }
+    catch {
+        invalid();
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        if (temporary !== undefined)
+            rmSync(temporary, { force: true });
+    }
+}
+//# sourceMappingURL=desktop-manifest.js.map

package/dist/runtime/diagnostics.js

@@ -0,0 +1,34 @@
+import { APPROVED_RUNTIME_TUPLES, assertHostRuntimeEligibility } from "../storage/runtime.js";
+import { ExecutableRefusal, diagnoseTunnelClient, resolveApprovedNode } from "./executables.js";
+/** No profile, credential, Store or transport access. Host uses the actual
+ * in-memory SQLite/API battery; only an admitted Node child is executed. */
+export function diagnoseInstallation(options = {}) {
+    let host = "QUALIFIED";
+    try {
+        assertHostRuntimeEligibility();
+    }
+    catch {
+        host = "STORAGE_RUNTIME_INELIGIBLE";
+    }
+    let child;
+    try {
+        child = resolveApprovedNode(options) === undefined ? "CE_NODE_UNAVAILABLE" : "QUALIFIED";
+    }
+    catch (error) {
+        child = error instanceof ExecutableRefusal ? error.code : "CE_NODE_INELIGIBLE";
+    }
+    return { host, child, client: diagnoseTunnelClient(options) };
+}
+export function installationDiagnosticMessage(result) {
+    return `ce-tunnel doctor: Pi host=${result.host} (in-memory SQLite/runtime check); MCP child=${result.child}; client=${result.client}. ` +
+        "Client trust is metadata only, not compatibility or connectivity. No client executed; no profile/Store/transport changes. " +
+        "For a missing client, install separately; for rejected trust, repair the private installation and its ancestors/ACLs or select a trusted absolute CE_TUNNEL_CLIENT_PATH outside projects. Never use PATH fallback or relax trust. " +
+        "Select an independently qualified MCP child with CE_NODE_PATH. " + hostRuntimeRepairMessage() +
+        ". Installation checks are not transport, delivery, ACK or completion evidence.";
+}
+/** No raw subprocess output, paths, configuration values or exception causes. */
+export function hostRuntimeRepairMessage(nodeVersion = process.version) {
+    const current = /^v\d+\.\d+\.\d+$/.test(nodeVersion) ? nodeVersion : "unrecognized";
+    return `current Pi Node ${current}; requires approved Node ${APPROVED_RUNTIME_TUPLES.map(({ nodeVersion: version }) => version).join(" or ")} with approved SQLite; restart Pi using a trusted absolute approved Node executable. CE_NODE_PATH selects the MCP child only, not the running Pi host; each qualifies independently and need not use the same executable; mise is not required`;
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/runtime/executables.js

@@ -0,0 +1,222 @@
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, existsSync, lstatSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
+import { APPROVED_RUNTIME_TUPLES, REQUIRED_SQLITE_CAPABILITIES, assertRuntimeEligibility } from "../storage/runtime.js";
+/** These are locations, not PATH search. Every discovered file still needs admission. */
+const SYSTEM_DIRECTORIES = ["/usr/local/bin", "/usr/bin", "/bin", "/opt/homebrew/bin"];
+export class ExecutableRefusal extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "ExecutableRefusal";
+    }
+}
+const untrusted = () => { throw new ExecutableRefusal("CE_EXECUTABLE_UNTRUSTED"); };
+function within(root, path) {
+    const delta = relative(root, path);
+    return delta === "" || (delta !== ".." && !delta.startsWith(`..${sep}`) && !isAbsolute(delta));
+}
+function currentProjectRoot() {
+    let directory = realpathSync(process.cwd());
+    for (;;) {
+        if (existsSync(join(directory, ".git")))
+            return directory;
+        const parent = dirname(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+}
+/** macOS ACL grants are independent of POSIX mode. Only absent ACLs or
+ * deny-only ACLs are admitted; unknown output/probe failure is fail-closed.
+ * The OS utility is fixed, never discovered through PATH or supplied by callers. */
+function assertDarwinAclSafe(path) {
+    if (process.platform !== "darwin")
+        return;
+    const output = execFileSync("/bin/ls", ["-lde", path], {
+        cwd: "/", env: { PATH: "/usr/bin:/bin", LANG: "C", LC_ALL: "C" },
+        shell: false, timeout: 5_000, killSignal: "SIGKILL", maxBuffer: 16_384,
+        encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+    });
+    const lines = output.trimEnd().split("\n");
+    const header = lines.shift() ?? "";
+    if (!/^[bcdlps-][rwxStTs-]{9}[+@ ]/.test(header))
+        untrusted();
+    for (const entry of lines) {
+        if (!/^\s*\d+: \S+ deny [a-z_,]+$/.test(entry))
+            untrusted();
+    }
+    if (header[10] === "+" && lines.length === 0)
+        untrusted();
+}
+/** Admission is deliberately before probing. Same-account filesystem mutation is
+ * outside this boundary; a private installation is required, not a signature claim. */
+function admitPath(path, options, kind) {
+    try {
+        if (!isAbsolute(path) || normalize(path) !== path || /[\x00-\x1f\x7f]/.test(path))
+            untrusted();
+        const project = options.projectRoot === undefined ? currentProjectRoot() : realpathSync(options.projectRoot);
+        const uid = process.geteuid?.();
+        if (uid === undefined)
+            untrusted();
+        const visited = new Set();
+        const check = (candidate) => {
+            if (visited.has(candidate))
+                return;
+            if (visited.size >= 256 || (project !== undefined && within(project, candidate)) || candidate.split(sep).some((part) => part === "node_modules" || part === ".git"))
+                untrusted();
+            visited.add(candidate);
+            const stat = lstatSync(candidate);
+            if (stat.uid !== 0 && stat.uid !== uid)
+                untrusted();
+            if (!stat.isSymbolicLink()) {
+                assertDarwinAclSafe(candidate);
+                // OS-owned sticky temp roots protect independently owned private children.
+                const stickyRoot = stat.isDirectory() && stat.uid === 0 && (stat.mode & 0o1000) !== 0;
+                if ((stat.mode & 0o022) !== 0 && !stickyRoot)
+                    untrusted();
+            }
+            const parent = dirname(candidate);
+            if (parent !== candidate)
+                check(parent);
+            if (stat.isSymbolicLink())
+                check(realpathSync(candidate));
+        };
+        check(path);
+        const canonical = realpathSync(path);
+        check(canonical);
+        const stat = statSync(canonical);
+        if (kind === "executable") {
+            if (!stat.isFile())
+                untrusted();
+            accessSync(canonical, constants.X_OK);
+        }
+        else if (!stat.isDirectory())
+            untrusted();
+        return canonical;
+    }
+    catch {
+        return untrusted();
+    }
+}
+export function admitExecutable(path, options = {}) {
+    return admitPath(path, options, "executable");
+}
+export function admitInstallationDirectory(path, options = {}) {
+    return admitPath(path, options, "directory");
+}
+// Inline probe imports builtins only; no project loader, package resolution,
+// configuration, Store, credentials, network or inherited Node options.
+const NODE_PROBE = `
+const { DatabaseSync } = require('node:sqlite');
+const db = new DatabaseSync(':memory:');
+try {
+  const row = db.prepare('SELECT sqlite_source_id() AS sourceId').get();
+  const compileOptions = db.prepare('PRAGMA compile_options').all().map(option => {
+    const value = Object.values(option)[0];
+    if (typeof value !== 'string') throw new Error('invalid compile option');
+    return value;
+  }).sort();
+  db.enableDefensive(true);
+  db.exec('PRAGMA writable_schema=ON');
+  if (db.prepare('PRAGMA writable_schema').get()?.writable_schema !== 0) throw new Error('defensive mode unavailable');
+  db.exec('CREATE TABLE runtime_probe (value INTEGER); BEGIN');
+  if (db.isTransaction !== true) throw new Error('transaction state unavailable');
+  if (db.prepare('INSERT INTO runtime_probe VALUES (?)').run(1).changes !== 1
+      || db.prepare('SELECT value FROM runtime_probe').get()?.value !== 1
+      || db.prepare('SELECT value FROM runtime_probe').all().length !== 1) throw new Error('statement APIs unavailable');
+  db.exec('ROLLBACK');
+  if (db.isTransaction !== false) throw new Error('transaction state unavailable');
+  process.stdout.write(JSON.stringify({nodeVersion:process.version,sqliteVersion:process.versions.sqlite,sqliteSourceId:row.sourceId,platform:process.platform,arch:process.arch,compileOptions,sqliteCapabilities:${JSON.stringify(REQUIRED_SQLITE_CAPABILITIES)}}));
+} finally { db.close(); }
+`;
+export function qualifyNodeExecutable(path, options = {}) {
+    const canonical = admitExecutable(path, options);
+    try {
+        const text = execFileSync(canonical, ["--input-type=commonjs", "-e", NODE_PROBE], {
+            cwd: "/", env: { PATH: "/usr/bin:/bin", LANG: "C", LC_ALL: "C" },
+            shell: false, timeout: 5_000, killSignal: "SIGKILL", maxBuffer: 16_384,
+            encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+        });
+        const identity = JSON.parse(text);
+        assertRuntimeEligibility(identity);
+        return identity;
+    }
+    catch {
+        throw new ExecutableRefusal("CE_NODE_INELIGIBLE");
+    }
+}
+export function resolveApprovedNode(options = {}) {
+    const env = options.env ?? {};
+    const qualify = (path) => {
+        const canonical = admitExecutable(path, options);
+        qualifyNodeExecutable(canonical, options);
+        return canonical;
+    };
+    if (env.CE_NODE_PATH !== undefined)
+        return qualify(env.CE_NODE_PATH);
+    const legacyRoot = env.MISE_DATA_DIR ?? join(options.homeDir ?? homedir(), ".local/share/mise");
+    const candidates = [
+        options.execPath ?? process.execPath,
+        ...(options.systemDirectories ?? SYSTEM_DIRECTORIES).map((directory) => join(directory, "node")),
+        ...(isAbsolute(legacyRoot) ? APPROVED_RUNTIME_TUPLES.map(({ nodeVersion }) => join(legacyRoot, "installs/node", nodeVersion.slice(1), "bin/node")) : []),
+    ];
+    for (const path of new Set(candidates)) {
+        try {
+            return qualify(path);
+        }
+        catch { /* Discovery candidates may be absent or unqualified. */ }
+    }
+    return undefined;
+}
+/** Diagnostic-only closed outcome. Same runtime admission, retaining discovery
+ * refusals instead of laundering rejected installations as absent. Explicit
+ * overrides are authoritative: even an absent override is a refusal. */
+export function diagnoseTunnelClient(options = {}) {
+    const env = options.env ?? {};
+    if (env.CE_TUNNEL_CLIENT_PATH !== undefined) {
+        try {
+            admitExecutable(env.CE_TUNNEL_CLIENT_PATH, options);
+            return "TRUSTED_METADATA_ONLY";
+        }
+        catch {
+            return "CE_EXECUTABLE_UNTRUSTED";
+        }
+    }
+    let rejected = false;
+    for (const directory of options.systemDirectories ?? SYSTEM_DIRECTORIES) {
+        const candidate = join(directory, "tunnel-client");
+        try {
+            lstatSync(candidate);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                rejected = true;
+            continue;
+        }
+        try {
+            admitExecutable(candidate, options);
+            return "TRUSTED_METADATA_ONLY";
+        }
+        catch {
+            rejected = true;
+        }
+    }
+    return rejected ? "CE_EXECUTABLE_UNTRUSTED" : "CE_TUNNEL_CLIENT_MISSING";
+}
+/** Discovery is metadata-only: never execute a client to find or qualify it. */
+export function resolveTunnelClient(options = {}) {
+    const env = options.env ?? {};
+    if (env.CE_TUNNEL_CLIENT_PATH !== undefined)
+        return admitExecutable(env.CE_TUNNEL_CLIENT_PATH, options);
+    for (const directory of options.systemDirectories ?? SYSTEM_DIRECTORIES) {
+        try {
+            return admitExecutable(join(directory, "tunnel-client"), options);
+        }
+        catch { /* Next controlled location. */ }
+    }
+    return undefined;
+}
+//# sourceMappingURL=executables.js.map

package/dist/storage/capability.js

@@ -0,0 +1,221 @@
+import { randomBytes } from "node:crypto";
+import { StoreLifecycleError } from "./errors.js";
+import { CAPABILITY_PATTERN, HOST_CAPABILITY_BYTES } from "./participant-identity.js";
+import { deriveCapabilityDigest, digestsMatch, readHostSecretDigest } from "./trust-root.js";
+import { parseSessionRow, SESSION_COLUMNS } from "./session-state.js";
+/**
+ * Host Capability authorization plane (CE-0002-B3-P1B).
+ *
+ * A Host Capability is a 256-bit CSPRNG bearer token issued by the trusted
+ * host. Only an HMAC digest keyed by the host secret is persisted
+ * (`participant_capability.capability_digest`), so:
+ *
+ * - a Session ID or Participant ID alone never grants authorization — only
+ *   presenting the token does;
+ * - the stored digest cannot be replayed into another store, because the host
+ *   secret keys the derivation;
+ * - a token is bound to one trust generation, one Participant, and one exact
+ *   scope, so it cannot be widened or transferred;
+ * - an operator trust-root recovery invalidates every outstanding token twice
+ *   over: by revocation (P1A) and by generation binding.
+ *
+ * Operational scopes are phase-bounded: P1 create/bind/join, P2 attach/resume/
+ * takeover, P3A send/metadata-only read, P4C payload_read, and the P3B
+ * authorization-plane-only `ack`. No durable ACK operation, receipt, audit
+ * row, or public surface exists yet: `ack` admits the acknowledgment
+ * authority into the capability plane (issuance, classification, revocation)
+ * and the current-Owner authorization chain only, and no other scope gains
+ * acknowledgment authority. `resume`, `takeover`, `send`, `read`,
+ * `payload_read`, and `ack` are Session-bound: each authorizes only the
+ * Session it was durably issued to.
+ * Verification always happens inside the caller's owned transaction, against
+ * the same consistent snapshot as the mutation it authorizes. Refusals are a
+ * single sanitized classification: the capability plane is never an oracle
+ * that distinguishes "unknown" from "revoked", "expired", or "wrong scope".
+ */
+export const P1_CAPABILITY_SCOPES = ["create", "bind", "join"];
+export function isP1CapabilityScope(value) {
+    return typeof value === "string" && P1_CAPABILITY_SCOPES.includes(value);
+}
+/** CE-0002-B3-P2A: Session binding/acquisition (`attach`) and owner
+ * renewal/release/verification (`resume`). */
+export const P2A_CAPABILITY_SCOPES = ["attach", "resume"];
+/** CE-0002-B3-P2B: explicit Owner takeover. Session-bound like `resume`:
+ * a takeover capability authorizes only the Session it was durably issued to
+ * (the prospective new Owner Session), never a Session presented at will. */
+export const P2B_CAPABILITY_SCOPES = ["takeover"];
+/** CE-0002-B3-P3A: durable storage send and protected metadata read. */
+export const P3A_CAPABILITY_SCOPES = ["send", "read"];
+/** CE-0002-B3-P4C: independent payload access authority. This scope does not
+ * widen the historical metadata-only `read` scope and grants no operation by
+ * itself; a later protected Storage operation must enforce ownership, fencing,
+ * lease, membership, endpoint, and Message eligibility in one transaction. */
+export const P4C_CAPABILITY_SCOPES = ["payload_read"];
+/** CE-0002-B3-P3B: independent ACK authority. Admission to this private
+ * authorization plane does not implement an ACK operation or receipt. */
+export const P3B_CAPABILITY_SCOPES = ["ack"];
+/** Scopes whose authority is durably bound to exactly one Session. */
+export const SESSION_BOUND_CAPABILITY_SCOPES = [
+    "resume",
+    "takeover",
+    ...P3A_CAPABILITY_SCOPES,
+    ...P4C_CAPABILITY_SCOPES,
+    ...P3B_CAPABILITY_SCOPES,
+];
+export function isSessionBoundCapabilityScope(value) {
+    return typeof value === "string" && SESSION_BOUND_CAPABILITY_SCOPES.includes(value);
+}
+export const OPERATIONAL_CAPABILITY_SCOPES = [
+    ...P1_CAPABILITY_SCOPES,
+    ...P2A_CAPABILITY_SCOPES,
+    ...P2B_CAPABILITY_SCOPES,
+    ...P3A_CAPABILITY_SCOPES,
+    ...P4C_CAPABILITY_SCOPES,
+    ...P3B_CAPABILITY_SCOPES,
+];
+export function isOperationalCapabilityScope(value) {
+    return typeof value === "string" && OPERATIONAL_CAPABILITY_SCOPES.includes(value);
+}
+/** Cryptographically random bearer token: `cap_` + 256 bits of hex. */
+export function generateCapability(tokenBytes) {
+    const generated = (tokenBytes ?? (() => randomBytes(HOST_CAPABILITY_BYTES)))();
+    if (!(generated instanceof Uint8Array) || generated.byteLength !== HOST_CAPABILITY_BYTES) {
+        throw new Error("capability generator did not return exactly 256 bits");
+    }
+    return `cap_${Buffer.from(generated).toString("hex")}`;
+}
+function tokenBody(capability) {
+    if (typeof capability !== "string" || !CAPABILITY_PATTERN.test(capability))
+        return undefined;
+    return capability.slice("cap_".length);
+}
+/** Current trust generation inside an owned transaction, with the same
+ * append-only maximum rule the open path uses. Returns undefined when the
+ * durable generation row is missing or structurally invalid; callers decide
+ * whether that is corruption or a refusal. */
+export function currentGenerationInTransaction(tx) {
+    const row = tx
+        .prepare("SELECT generation, secret_digest FROM host_trust_root ORDER BY generation DESC LIMIT 1")
+        .get();
+    if (row === undefined)
+        return undefined;
+    if (typeof row.generation !== "number" ||
+        !Number.isSafeInteger(row.generation) ||
+        row.generation < 1 ||
+        typeof row.secret_digest !== "string" ||
+        !/^[0-9a-f]{64}$/.test(row.secret_digest)) {
+        return undefined;
+    }
+    return { generation: row.generation, secret_digest: row.secret_digest };
+}
+export function capabilityRow(tx, digest) {
+    const row = tx
+        .prepare("SELECT capability_digest, participant_id, scope, trust_generation, created_at, expires_at, revoked_at, session_id FROM participant_capability WHERE capability_digest = ?")
+        .get(digest);
+    if (row === undefined)
+        return undefined;
+    if (typeof row.capability_digest !== "string" ||
+        typeof row.participant_id !== "string" ||
+        typeof row.scope !== "string" ||
+        typeof row.trust_generation !== "number" ||
+        typeof row.created_at !== "string" ||
+        !(row.expires_at === null || typeof row.expires_at === "string") ||
+        !(row.revoked_at === null || typeof row.revoked_at === "string") ||
+        !(row.session_id === null || typeof row.session_id === "string")) {
+        return undefined;
+    }
+    return row;
+}
+function instantOf(value) {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/**
+ * Classifies one presented capability inside an owned transaction.
+ *
+ * The host trust root is re-validated per authorization: the live secret file
+ * must still pass the artifact policy and still match the persisted
+ * fingerprint of the current generation. A trust-root failure propagates as a
+ * typed trust-root refusal (fail closed), never as a capability rejection: a
+ * missing generation row is STORAGE_CORRUPT and a fingerprint disagreement is
+ * STORAGE_TRUST_ROOT_MISMATCH.
+ */
+export function classifyCapability(tx, databasePath, presentation) {
+    const token = tokenBody(presentation.capability);
+    if (token === undefined || !isOperationalCapabilityScope(presentation.scope))
+        return "MALFORMED";
+    const now = instantOf(presentation.now);
+    if (now === undefined)
+        return "MALFORMED";
+    const generation = currentGenerationInTransaction(tx);
+    if (generation === undefined) {
+        throw new StoreLifecycleError("STORAGE_CORRUPT", "a v2 store has no host trust root generation");
+    }
+    // Host-secret trust validation: artifact policy plus fingerprint agreement.
+    // CE-0002-B3-P1B-R1 (MINOR-2): a trust-root failure is a typed trust-root
+    // refusal, never an opaque capability rejection, matching this module's
+    // documented classification and `issueCapability`. Fail-closed either way:
+    // the mutation is refused and nothing is written.
+    if (!digestsMatch(readHostSecretDigest(databasePath), generation.secret_digest)) {
+        throw new StoreLifecycleError("STORAGE_TRUST_ROOT_MISMATCH", "the host secret does not match the persisted trust-root fingerprint");
+    }
+    const digest = deriveCapabilityDigest(databasePath, {
+        generation: generation.generation,
+        participantId: presentation.participantId,
+        scope: presentation.scope,
+        token,
+    });
+    const row = capabilityRow(tx, digest);
+    if (row === undefined) {
+        // Either the token is forged, or it was derived under another generation,
+        // Participant, or scope. All are indistinguishable by construction.
+        return "UNKNOWN";
+    }
+    if (row.participant_id !== presentation.participantId)
+        return "PARTICIPANT_MISMATCH";
+    if (row.scope !== presentation.scope)
+        return "SCOPE_MISMATCH";
+    // Session-bound scopes (CE-0002-B3-P2A-R1 `resume`; CE-0002-B3-P2B
+    // `takeover`): the capability authorizes only the Session it was durably
+    // issued to. A legacy unbound (NULL) or differently bound row can never
+    // authorize: fail closed. The check runs against the durable row inside the
+    // caller's transaction, so the binding cannot be swapped between check and
+    // effect.
+    if (isSessionBoundCapabilityScope(presentation.scope) && row.session_id !== presentation.sessionId) {
+        return "SESSION_MISMATCH";
+    }
+    // CE-0002-B3-P2C-B (D7): a Session-bound capability is lifecycle-bound.
+    // The persisted `detached_at` of its bound Session is the source of
+    // truth, so a DETACHED Session makes the capability permanently unusable
+    // for every presenter — read-time invalidation only; no capability row is
+    // ever rewritten as a side effect of Detach. P3A `send`/`read`, P4C
+    // `payload_read`, and P3B `ack` inherit this check inside the
+    // caller's transaction: a Session-bound capability whose binding is missing
+    // or malformed is inconsistent durable state — refused as corruption,
+    // never adopted (schema v4 makes row deletion trigger-impossible, so this
+    // is privileged tampering or foreign state).
+    if (isSessionBoundCapabilityScope(row.scope) && row.session_id !== null) {
+        const sessionRow = tx
+            .prepare(`${SESSION_COLUMNS} WHERE participant_id = ? AND session_id = ?`)
+            .get(row.participant_id, row.session_id);
+        const binding = sessionRow === undefined ? undefined : parseSessionRow(sessionRow);
+        if (binding === undefined || binding.participantId !== row.participant_id || binding.sessionId !== row.session_id) {
+            throw new StoreLifecycleError("STORAGE_OWNERSHIP_CORRUPT", "stored Session lifecycle state is inconsistent; operator review required");
+        }
+        if (binding.state === "DETACHED")
+            return "SESSION_DETACHED";
+    }
+    if (row.trust_generation !== generation.generation)
+        return "WRONG_GENERATION";
+    if (row.revoked_at !== null)
+        return "REVOKED";
+    if (row.expires_at !== null) {
+        const expiry = instantOf(row.expires_at);
+        if (expiry === undefined)
+            return "MALFORMED";
+        if (expiry <= now)
+            return "EXPIRED";
+    }
+    return "VALID";
+}
+//# sourceMappingURL=capability.js.map

package/dist/storage/connection.js

@@ -0,0 +1,94 @@
+import { DatabaseSync } from "node:sqlite";
+import { assertSecureDatabaseArtifacts, prepareDatabasePath, exclusivelyCreateDatabase, pathStat, withRestrictiveUmask, } from "./filesystem.js";
+import { assertRuntimeEligibility, readRuntimeIdentity, } from "./runtime.js";
+export const DEFAULT_BUSY_TIMEOUT_MS = 1_000;
+export const MAX_BUSY_TIMEOUT_MS = 5_000;
+export const WAL_AUTOCHECKPOINT_PAGES = 1_000;
+export class ConnectionPolicyError extends Error {
+    code = "STORAGE_CONNECTION_POLICY_INVALID";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ConnectionPolicyError";
+    }
+}
+export function assertStorageRuntimeEligibility(options) {
+    assertRuntimeEligibility((options.runtimeIdentity ?? readRuntimeIdentity)());
+}
+function readPragma(db, name) {
+    const row = db.prepare(`PRAGMA ${name}`).get();
+    return row === undefined ? undefined : Object.values(row)[0];
+}
+function assertPragma(db, name, expected) {
+    const actual = readPragma(db, name);
+    if (actual !== expected) {
+        throw new ConnectionPolicyError(`SQLite refused required PRAGMA ${name}: expected ${String(expected)}, received ${String(actual)}`);
+    }
+}
+function initializeWriterPolicy(db, busyTimeoutMs) {
+    db.enableDefensive(true);
+    db.exec(`
+    PRAGMA journal_mode=WAL;
+    PRAGMA synchronous=FULL;
+    PRAGMA foreign_keys=ON;
+    PRAGMA recursive_triggers=ON;
+    PRAGMA trusted_schema=OFF;
+    PRAGMA busy_timeout=${busyTimeoutMs};
+    PRAGMA wal_autocheckpoint=${WAL_AUTOCHECKPOINT_PAGES};
+  `);
+    if (process.platform === "darwin") {
+        db.exec("PRAGMA fullfsync=ON; PRAGMA checkpoint_fullfsync=ON;");
+    }
+    assertPragma(db, "journal_mode", "wal");
+    assertPragma(db, "synchronous", 2);
+    assertPragma(db, "foreign_keys", 1);
+    assertPragma(db, "recursive_triggers", 1);
+    assertPragma(db, "trusted_schema", 0);
+    assertPragma(db, "busy_timeout", busyTimeoutMs);
+    assertPragma(db, "wal_autocheckpoint", WAL_AUTOCHECKPOINT_PAGES);
+    if (process.platform === "darwin") {
+        assertPragma(db, "fullfsync", 1);
+        assertPragma(db, "checkpoint_fullfsync", 1);
+    }
+}
+export function openStorageConnection(options, validateExisting, createExclusive = false) {
+    const busyTimeoutMs = options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+    if (!Number.isSafeInteger(busyTimeoutMs) || busyTimeoutMs < 1 || busyTimeoutMs > MAX_BUSY_TIMEOUT_MS) {
+        throw new ConnectionPolicyError(`busy timeout must be an integer from 1 to ${MAX_BUSY_TIMEOUT_MS} milliseconds`);
+    }
+    assertStorageRuntimeEligibility(options);
+    const databasePath = prepareDatabasePath(options);
+    assertSecureDatabaseArtifacts(databasePath);
+    if (createExclusive || pathStat(databasePath) === undefined) {
+        if (validateExisting !== undefined)
+            throw new ConnectionPolicyError("existing store disappeared before writer open");
+        exclusivelyCreateDatabase(databasePath);
+    }
+    let db;
+    try {
+        db = withRestrictiveUmask(() => new DatabaseSync(databasePath, { defensive: true, timeout: busyTimeoutMs }));
+        // Revalidate identity/compatibility before persistent writer PRAGMAs.
+        // A read transaction gives these checks one consistent schema/data snapshot.
+        if (validateExisting !== undefined) {
+            db.exec("BEGIN");
+            try {
+                validateExisting(db);
+            }
+            finally {
+                db.exec("ROLLBACK");
+            }
+        }
+        initializeWriterPolicy(db, busyTimeoutMs);
+        assertSecureDatabaseArtifacts(databasePath);
+        return db;
+    }
+    catch (error) {
+        if (db !== undefined)
+            db.close();
+        if (error instanceof ConnectionPolicyError)
+            throw error;
+        throw new ConnectionPolicyError("failed to establish the required SQLite connection policy", {
+            cause: error,
+        });
+    }
+}
+//# sourceMappingURL=connection.js.map