larkin 0.4.2 → 0.4.6

package/dist/platform/process-boundary-trace.cjs

@@ -0,0 +1,108 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceProcessBoundary = traceProcessBoundary;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function inspect(role, file) {
+    try {
+        const stat = node_fs_1.default.lstatSync(file);
+        return {
+            role,
+            exists: true,
+            regularFile: stat.isFile(),
+            directory: stat.isDirectory(),
+            symlink: stat.isSymbolicLink(),
+            mode: stat.mode & 0o777,
+        };
+    }
+    catch (error) {
+        const code = error.code;
+        return { role, exists: false, ...(code === "ELOOP" ? { symlink: true } : {}) };
+    }
+}
+function errorCategory(error) {
+    const code = error && typeof error === "object" && "code" in error
+        ? String(error.code || "") : "";
+    if (code === "ENOENT")
+        return "missing";
+    if (code === "EACCES" || code === "EPERM")
+        return "permission";
+    if (code === "ELOOP")
+        return "symlink";
+    if (code === "EEXIST")
+        return "conflict";
+    if (code === "EINVAL" || code === "EBADMSG" || code === "ERR_INVALID_ARG_VALUE")
+        return "invalid";
+    return "runtime";
+}
+function safePhase(value) {
+    const phase = typeof value === "string" ? value : "unknown";
+    return /^[a-z0-9:_-]{1,80}$/i.test(phase) ? phase : "unknown";
+}
+function safeEpoch(value) {
+    if (typeof value !== "string" && typeof value !== "number" && !(value instanceof Date))
+        return null;
+    const text = value instanceof Date ? value.toISOString() : String(value);
+    const time = Date.parse(text);
+    return Number.isFinite(time) ? new Date(time).toISOString() : null;
+}
+/**
+ * Opt-in, content-free diagnostics for process-boundary startup investigations.
+ * The trace intentionally emits roles and metadata only: never a cwd, home,
+ * config/profile/target path, or exception text. Diagnostics are inert unless an
+ * absolute 0600 destination is explicitly supplied by a test or operator.
+ */
+function traceProcessBoundary(env, phase, fields = {}) {
+    const file = env.LARKIN_PROCESS_BOUNDARY_TRACE_FILE;
+    if (!file || !node_path_1.default.isAbsolute(file) || /[\0\r\n]/.test(file))
+        return;
+    try {
+        const configRoot = fields.configDir || env.LARKIN_CONFIG_DIR || env.LARKIN_HOME || null;
+        const record = {
+            at: new Date().toISOString(),
+            epoch: safeEpoch(fields.epoch ?? env.LARKIN_DAEMON_EPOCH ?? new Date().toISOString()),
+            pid: process.pid,
+            ppid: process.ppid,
+            phase: safePhase(phase),
+            configuredRoots: {
+                configDir: Boolean(env.LARKIN_CONFIG_DIR || fields.configDir),
+                larkinHome: Boolean(env.LARKIN_HOME),
+                piAgentDir: Boolean(env.PI_CODING_AGENT_DIR),
+            },
+            pathRoles: [
+                ...(configRoot ? [inspect("config-root", configRoot)] : []),
+                ...(fields.targetDir ? [inspect("provider-target", fields.targetDir)] : []),
+            ],
+        };
+        if (typeof fields.agentId === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(fields.agentId))
+            record.agentId = fields.agentId;
+        if (Number.isInteger(fields.childPid) && Number(fields.childPid) > 0)
+            record.childPid = Number(fields.childPid);
+        if (typeof fields.distribution === "string" && /^(builtin|external)$/.test(fields.distribution))
+            record.distribution = fields.distribution;
+        if (typeof fields.requested === "string" && /^(builtin|external|migration|startup)$/.test(fields.requested))
+            record.requested = fields.requested;
+        if (typeof fields.targetDirExisted === "boolean")
+            record.targetDirExisted = fields.targetDirExisted;
+        if (fields.error !== undefined)
+            record.errorCategory = errorCategory(fields.error);
+        const bytes = Buffer.from(`${JSON.stringify(record)}\n`);
+        const fd = node_fs_1.default.openSync(file, node_fs_1.default.constants.O_WRONLY | node_fs_1.default.constants.O_APPEND | node_fs_1.default.constants.O_CREAT | (node_fs_1.default.constants.O_NOFOLLOW || 0), 0o600);
+        try {
+            const stat = node_fs_1.default.fstatSync(fd);
+            if (!stat.isFile() || (typeof process.getuid === "function" && stat.uid !== process.getuid()) || (stat.mode & 0o077) !== 0)
+                return;
+            node_fs_1.default.writeSync(fd, bytes);
+            node_fs_1.default.fchmodSync(fd, 0o600);
+        }
+        finally {
+            node_fs_1.default.closeSync(fd);
+        }
+    }
+    catch {
+        // Diagnostics must never alter startup behavior.
+    }
+}

package/dist/platform/process-boundary-trace.mjs

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import path from "node:path";
+function inspect(role, file) {
+    try {
+        const stat = fs.lstatSync(file);
+        return {
+            role,
+            exists: true,
+            regularFile: stat.isFile(),
+            directory: stat.isDirectory(),
+            symlink: stat.isSymbolicLink(),
+            mode: stat.mode & 0o777,
+        };
+    }
+    catch (error) {
+        const code = error.code;
+        return { role, exists: false, ...(code === "ELOOP" ? { symlink: true } : {}) };
+    }
+}
+function errorCategory(error) {
+    const code = error && typeof error === "object" && "code" in error
+        ? String(error.code || "") : "";
+    if (code === "ENOENT")
+        return "missing";
+    if (code === "EACCES" || code === "EPERM")
+        return "permission";
+    if (code === "ELOOP")
+        return "symlink";
+    if (code === "EEXIST")
+        return "conflict";
+    if (code === "EINVAL" || code === "EBADMSG" || code === "ERR_INVALID_ARG_VALUE")
+        return "invalid";
+    return "runtime";
+}
+function safePhase(value) {
+    const phase = typeof value === "string" ? value : "unknown";
+    return /^[a-z0-9:_-]{1,80}$/i.test(phase) ? phase : "unknown";
+}
+function safeEpoch(value) {
+    if (typeof value !== "string" && typeof value !== "number" && !(value instanceof Date))
+        return null;
+    const text = value instanceof Date ? value.toISOString() : String(value);
+    const time = Date.parse(text);
+    return Number.isFinite(time) ? new Date(time).toISOString() : null;
+}
+/**
+ * Opt-in, content-free diagnostics for process-boundary startup investigations.
+ * The trace intentionally emits roles and metadata only: never a cwd, home,
+ * config/profile/target path, or exception text. Diagnostics are inert unless an
+ * absolute 0600 destination is explicitly supplied by a test or operator.
+ */
+export function traceProcessBoundary(env, phase, fields = {}) {
+    const file = env.LARKIN_PROCESS_BOUNDARY_TRACE_FILE;
+    if (!file || !path.isAbsolute(file) || /[\0\r\n]/.test(file))
+        return;
+    try {
+        const configRoot = fields.configDir || env.LARKIN_CONFIG_DIR || env.LARKIN_HOME || null;
+        const record = {
+            at: new Date().toISOString(),
+            epoch: safeEpoch(fields.epoch ?? env.LARKIN_DAEMON_EPOCH ?? new Date().toISOString()),
+            pid: process.pid,
+            ppid: process.ppid,
+            phase: safePhase(phase),
+            configuredRoots: {
+                configDir: Boolean(env.LARKIN_CONFIG_DIR || fields.configDir),
+                larkinHome: Boolean(env.LARKIN_HOME),
+                piAgentDir: Boolean(env.PI_CODING_AGENT_DIR),
+            },
+            pathRoles: [
+                ...(configRoot ? [inspect("config-root", configRoot)] : []),
+                ...(fields.targetDir ? [inspect("provider-target", fields.targetDir)] : []),
+            ],
+        };
+        if (typeof fields.agentId === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(fields.agentId))
+            record.agentId = fields.agentId;
+        if (Number.isInteger(fields.childPid) && Number(fields.childPid) > 0)
+            record.childPid = Number(fields.childPid);
+        if (typeof fields.distribution === "string" && /^(builtin|external)$/.test(fields.distribution))
+            record.distribution = fields.distribution;
+        if (typeof fields.requested === "string" && /^(builtin|external|migration|startup)$/.test(fields.requested))
+            record.requested = fields.requested;
+        if (typeof fields.targetDirExisted === "boolean")
+            record.targetDirExisted = fields.targetDirExisted;
+        if (fields.error !== undefined)
+            record.errorCategory = errorCategory(fields.error);
+        const bytes = Buffer.from(`${JSON.stringify(record)}\n`);
+        const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | (fs.constants.O_NOFOLLOW || 0), 0o600);
+        try {
+            const stat = fs.fstatSync(fd);
+            if (!stat.isFile() || (typeof process.getuid === "function" && stat.uid !== process.getuid()) || (stat.mode & 0o077) !== 0)
+                return;
+            fs.writeSync(fd, bytes);
+            fs.fchmodSync(fd, 0o600);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        // Diagnostics must never alter startup behavior.
+    }
+}

package/dist/runtime/pi-artifact-provenance.cjs

@@ -0,0 +1,147 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PI_RUNTIME_ARTIFACT_NAMES = exports.PI_RUNTIME_ARTIFACT_MANIFEST = void 0;
+exports.recordPiRuntimeArtifactProvenance = recordPiRuntimeArtifactProvenance;
+exports.attestedPiRuntimeArtifactNames = attestedPiRuntimeArtifactNames;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const secure_metadata_js_1 = require("../platform/secure-metadata.cjs");
+exports.PI_RUNTIME_ARTIFACT_MANIFEST = ".larkin-pi-owned-artifacts.json";
+exports.PI_RUNTIME_ARTIFACT_NAMES = [".larkin-official-pi-package", "models-store.json", "npm"];
+const MAX_FILE_BYTES = 256 * 1024 * 1024;
+const MAX_ENTRIES = 4096;
+function digest(value) {
+    return node_crypto_1.default.createHash("sha256").update(value).digest("hex");
+}
+function assertSafeEntry(file, label) {
+    const stat = node_fs_1.default.lstatSync(file);
+    if (stat.isSymbolicLink())
+        throw new Error(`${label} must not be a symlink`);
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        throw new Error(`${label} owner is unsafe`);
+    return stat;
+}
+function identity(file, label) {
+    const stat = assertSafeEntry(file, label);
+    const mode = stat.mode & 0o777;
+    if (stat.isFile()) {
+        if (stat.size > MAX_FILE_BYTES)
+            throw new Error(`${label} is too large`);
+        const bytes = node_fs_1.default.readFileSync(file);
+        return { kind: "file", mode, device: String(stat.dev), inode: String(stat.ino), bytes: bytes.length, digest: digest(bytes) };
+    }
+    if (!stat.isDirectory())
+        throw new Error(`${label} has an unsupported type`);
+    const entries = node_fs_1.default.readdirSync(file).sort();
+    if (entries.length > MAX_ENTRIES)
+        throw new Error(`${label} has too many entries`);
+    const children = entries.map((name) => {
+        if (name === "." || name === ".." || name.includes("/"))
+            throw new Error(`${label} contains an unsafe entry`);
+        const child = identity(node_path_1.default.join(file, name), `${label} child`);
+        return [name, child.kind, child.mode, child.device, child.inode, child.bytes, child.digest];
+    });
+    return {
+        kind: "directory", mode, device: String(stat.dev), inode: String(stat.ino),
+        bytes: children.reduce((sum, child) => sum + Number(child[5]), 0), digest: digest(JSON.stringify(children)),
+    };
+}
+function sameIdentity(actual, expected) {
+    return actual.kind === expected.kind && actual.mode === expected.mode
+        && actual.device === expected.device && actual.inode === expected.inode
+        && actual.bytes === expected.bytes && actual.digest === expected.digest;
+}
+function readManifest(file) {
+    try {
+        const stat = assertSafeEntry(file, "Pi artifact provenance manifest");
+        if (!stat.isFile() || !(0, secure_metadata_js_1.exactMode)(stat, 0o600) || stat.size > 1024 * 1024)
+            throw new Error("Pi artifact provenance manifest is unsafe");
+        const value = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+        if (value?.version !== 1 || value.owner !== "larkin-builtin-pi" || !value.directory || !value.artifacts)
+            throw new Error("Pi artifact provenance manifest is invalid");
+        return value;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function writeManifest(file, value) {
+    const temp = `${file}.tmp-${process.pid}`;
+    const fd = node_fs_1.default.openSync(temp, "wx", 0o600);
+    try {
+        node_fs_1.default.writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+        node_fs_1.default.fsyncSync(fd);
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+    node_fs_1.default.renameSync(temp, file);
+}
+/** Record only allowed entries that were absent at the runtime spawn boundary. */
+function recordPiRuntimeArtifactProvenance(targetDir, beforeEntries, boundaryAt = Date.now()) {
+    const target = assertSafeEntry(targetDir, "Pi provider target");
+    if (!target.isDirectory() || !(0, secure_metadata_js_1.exactMode)(target, 0o700))
+        throw new Error("Pi provider target is unsafe");
+    const manifestFile = node_path_1.default.join(targetDir, exports.PI_RUNTIME_ARTIFACT_MANIFEST);
+    const existing = readManifest(manifestFile);
+    const manifest = existing ?? {
+        version: 1, owner: "larkin-builtin-pi", directory: { device: String(target.dev), inode: String(target.ino) },
+        recordedAt: new Date(boundaryAt).toISOString(), artifacts: {},
+    };
+    if (manifest.directory.device !== String(target.dev) || manifest.directory.inode !== String(target.ino))
+        throw new Error("Pi artifact provenance target identity changed");
+    let changed = false;
+    for (const [name, expected] of Object.entries(manifest.artifacts)) {
+        if (!exports.PI_RUNTIME_ARTIFACT_NAMES.includes(name) || name.includes("/") || !expected)
+            throw new Error("Pi artifact provenance entry is invalid");
+        const actual = identity(node_path_1.default.join(targetDir, name), `Pi artifact ${name}`);
+        const sameOwner = actual.kind === expected.kind && actual.mode === expected.mode
+            && actual.device === expected.device && actual.inode === expected.inode;
+        if (!sameOwner)
+            throw new Error(`Pi artifact ${name} provenance identity changed`);
+        if (!sameIdentity(actual, expected)) {
+            manifest.artifacts[name] = actual;
+            changed = true;
+        }
+    }
+    for (const name of exports.PI_RUNTIME_ARTIFACT_NAMES) {
+        if (beforeEntries.has(name) || manifest.artifacts[name])
+            continue;
+        const file = node_path_1.default.join(targetDir, name);
+        if (!node_fs_1.default.existsSync(file))
+            continue;
+        const actual = identity(file, `Pi artifact ${name}`);
+        const stat = node_fs_1.default.lstatSync(file);
+        if (stat.birthtimeMs + 1 < boundaryAt && stat.mtimeMs + 1 < boundaryAt)
+            throw new Error(`Pi artifact ${name} predates runtime provenance boundary`);
+        manifest.artifacts[name] = actual;
+        changed = true;
+    }
+    if (changed)
+        writeManifest(manifestFile, manifest);
+}
+/** Return the names that are both explicitly attested and unchanged. */
+function attestedPiRuntimeArtifactNames(targetDir) {
+    const target = assertSafeEntry(targetDir, "Pi provider target");
+    if (!target.isDirectory())
+        throw new Error("Pi provider target is unsafe");
+    const manifest = readManifest(node_path_1.default.join(targetDir, exports.PI_RUNTIME_ARTIFACT_MANIFEST));
+    if (!manifest || manifest.directory.device !== String(target.dev) || manifest.directory.inode !== String(target.ino))
+        return new Set();
+    const names = new Set();
+    for (const [name, expected] of Object.entries(manifest.artifacts)) {
+        if (!exports.PI_RUNTIME_ARTIFACT_NAMES.includes(name) || !expected)
+            continue;
+        const actual = identity(node_path_1.default.join(targetDir, name), `Pi artifact ${name}`);
+        if (!sameIdentity(actual, expected))
+            throw new Error(`Pi artifact ${name} provenance changed`);
+        names.add(name);
+    }
+    return names;
+}

package/dist/runtime/pi-artifact-provenance.mjs

@@ -0,0 +1,139 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { exactMode } from "../platform/secure-metadata.mjs";
+export const PI_RUNTIME_ARTIFACT_MANIFEST = ".larkin-pi-owned-artifacts.json";
+export const PI_RUNTIME_ARTIFACT_NAMES = [".larkin-official-pi-package", "models-store.json", "npm"];
+const MAX_FILE_BYTES = 256 * 1024 * 1024;
+const MAX_ENTRIES = 4096;
+function digest(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}
+function assertSafeEntry(file, label) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink())
+        throw new Error(`${label} must not be a symlink`);
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        throw new Error(`${label} owner is unsafe`);
+    return stat;
+}
+function identity(file, label) {
+    const stat = assertSafeEntry(file, label);
+    const mode = stat.mode & 0o777;
+    if (stat.isFile()) {
+        if (stat.size > MAX_FILE_BYTES)
+            throw new Error(`${label} is too large`);
+        const bytes = fs.readFileSync(file);
+        return { kind: "file", mode, device: String(stat.dev), inode: String(stat.ino), bytes: bytes.length, digest: digest(bytes) };
+    }
+    if (!stat.isDirectory())
+        throw new Error(`${label} has an unsupported type`);
+    const entries = fs.readdirSync(file).sort();
+    if (entries.length > MAX_ENTRIES)
+        throw new Error(`${label} has too many entries`);
+    const children = entries.map((name) => {
+        if (name === "." || name === ".." || name.includes("/"))
+            throw new Error(`${label} contains an unsafe entry`);
+        const child = identity(path.join(file, name), `${label} child`);
+        return [name, child.kind, child.mode, child.device, child.inode, child.bytes, child.digest];
+    });
+    return {
+        kind: "directory", mode, device: String(stat.dev), inode: String(stat.ino),
+        bytes: children.reduce((sum, child) => sum + Number(child[5]), 0), digest: digest(JSON.stringify(children)),
+    };
+}
+function sameIdentity(actual, expected) {
+    return actual.kind === expected.kind && actual.mode === expected.mode
+        && actual.device === expected.device && actual.inode === expected.inode
+        && actual.bytes === expected.bytes && actual.digest === expected.digest;
+}
+function readManifest(file) {
+    try {
+        const stat = assertSafeEntry(file, "Pi artifact provenance manifest");
+        if (!stat.isFile() || !exactMode(stat, 0o600) || stat.size > 1024 * 1024)
+            throw new Error("Pi artifact provenance manifest is unsafe");
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (value?.version !== 1 || value.owner !== "larkin-builtin-pi" || !value.directory || !value.artifacts)
+            throw new Error("Pi artifact provenance manifest is invalid");
+        return value;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function writeManifest(file, value) {
+    const temp = `${file}.tmp-${process.pid}`;
+    const fd = fs.openSync(temp, "wx", 0o600);
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(temp, file);
+}
+/** Record only allowed entries that were absent at the runtime spawn boundary. */
+export function recordPiRuntimeArtifactProvenance(targetDir, beforeEntries, boundaryAt = Date.now()) {
+    const target = assertSafeEntry(targetDir, "Pi provider target");
+    if (!target.isDirectory() || !exactMode(target, 0o700))
+        throw new Error("Pi provider target is unsafe");
+    const manifestFile = path.join(targetDir, PI_RUNTIME_ARTIFACT_MANIFEST);
+    const existing = readManifest(manifestFile);
+    const manifest = existing ?? {
+        version: 1, owner: "larkin-builtin-pi", directory: { device: String(target.dev), inode: String(target.ino) },
+        recordedAt: new Date(boundaryAt).toISOString(), artifacts: {},
+    };
+    if (manifest.directory.device !== String(target.dev) || manifest.directory.inode !== String(target.ino))
+        throw new Error("Pi artifact provenance target identity changed");
+    let changed = false;
+    for (const [name, expected] of Object.entries(manifest.artifacts)) {
+        if (!PI_RUNTIME_ARTIFACT_NAMES.includes(name) || name.includes("/") || !expected)
+            throw new Error("Pi artifact provenance entry is invalid");
+        const actual = identity(path.join(targetDir, name), `Pi artifact ${name}`);
+        const sameOwner = actual.kind === expected.kind && actual.mode === expected.mode
+            && actual.device === expected.device && actual.inode === expected.inode;
+        if (!sameOwner)
+            throw new Error(`Pi artifact ${name} provenance identity changed`);
+        if (!sameIdentity(actual, expected)) {
+            manifest.artifacts[name] = actual;
+            changed = true;
+        }
+    }
+    for (const name of PI_RUNTIME_ARTIFACT_NAMES) {
+        if (beforeEntries.has(name) || manifest.artifacts[name])
+            continue;
+        const file = path.join(targetDir, name);
+        if (!fs.existsSync(file))
+            continue;
+        const actual = identity(file, `Pi artifact ${name}`);
+        const stat = fs.lstatSync(file);
+        if (stat.birthtimeMs + 1 < boundaryAt && stat.mtimeMs + 1 < boundaryAt)
+            throw new Error(`Pi artifact ${name} predates runtime provenance boundary`);
+        manifest.artifacts[name] = actual;
+        changed = true;
+    }
+    if (changed)
+        writeManifest(manifestFile, manifest);
+}
+/** Return the names that are both explicitly attested and unchanged. */
+export function attestedPiRuntimeArtifactNames(targetDir) {
+    const target = assertSafeEntry(targetDir, "Pi provider target");
+    if (!target.isDirectory())
+        throw new Error("Pi provider target is unsafe");
+    const manifest = readManifest(path.join(targetDir, PI_RUNTIME_ARTIFACT_MANIFEST));
+    if (!manifest || manifest.directory.device !== String(target.dev) || manifest.directory.inode !== String(target.ino))
+        return new Set();
+    const names = new Set();
+    for (const [name, expected] of Object.entries(manifest.artifacts)) {
+        if (!PI_RUNTIME_ARTIFACT_NAMES.includes(name) || !expected)
+            continue;
+        const actual = identity(path.join(targetDir, name), `Pi artifact ${name}`);
+        if (!sameIdentity(actual, expected))
+            throw new Error(`Pi artifact ${name} provenance changed`);
+        names.add(name);
+    }
+    return names;
+}