@noopolis/daimon 0.1.1 → 0.2.0

package/dist/runtime/grokSubscriptionRealm.js

@@ -0,0 +1,435 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { spawn } from "node:child_process";
+import { lstat, open, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { terminateChild, trackCliChild } from "../pi/cliProcess.js";
+import { GROK_SUBSCRIPTION_REALM } from "./contractManifest.js";
+import { hasRefreshablePortableCredential } from "./portableCredentialAuth.js";
+import { asGrokAuthenticationRejected } from "./grokAuthenticationError.js";
+const AUTH_FILE = "auth.json";
+const JOURNAL_FILE = "lease.json";
+const STALE_FILE = "stale.json";
+const BOOTSTRAP_FILE = "bootstrap.json";
+const LEASE_FILE = ".daimon-lease";
+const MAX_CONTROL_BYTES = 4_096;
+export async function startGrokSubscriptionRealm(configuredAgents, options = {}) {
+    const durablePath = options.durablePath ?? GROK_SUBSCRIPTION_REALM.durableMountPath;
+    const bootstrapPath = options.bootstrapPath ?? GROK_SUBSCRIPTION_REALM.bootstrapMountPath;
+    await verifyPrivateDirectory(durablePath);
+    const lease = await acquireRealmLease(durablePath, options);
+    const agents = new Map(configuredAgents.map((agent) => [agent.id, agent]));
+    let tail = Promise.resolve();
+    let closed = false;
+    let closePromise;
+    let bootstrapDigest;
+    try {
+        bootstrapDigest = await initializeRealm(durablePath, bootstrapPath, agents);
+    }
+    catch (error) {
+        await terminateChild(lease).catch(() => undefined);
+        throw redact(error);
+    }
+    const withCredential = async (agent, operation) => {
+        if (closed || agents.get(agent.id)?.runtimeHomePath !== agent.runtimeHomePath)
+            throw redact();
+        let release;
+        const prior = tail;
+        tail = new Promise((resolve) => { release = resolve; });
+        await prior;
+        try {
+            if (closed)
+                throw redact();
+            return await runLeasedTurn(durablePath, bootstrapDigest, agent, operation, options.onTransitionForTest);
+        }
+        finally {
+            release();
+        }
+    };
+    return {
+        withCredential,
+        close: () => closePromise ??= (async () => {
+            closed = true;
+            await tail;
+            await terminateChild(lease);
+        })()
+    };
+}
+async function initializeRealm(durablePath, bootstrapPath, agents) {
+    const bootstrap = await readCredential(bootstrapPath);
+    try {
+        const observedBootstrap = await readBootstrap(path.join(durablePath, BOOTSTRAP_FILE));
+        const journal = await readJournal(path.join(durablePath, JOURNAL_FILE));
+        if (journal !== undefined) {
+            await recoverJournal(durablePath, journal, agents, observedBootstrap?.bootstrap_digest ?? bootstrap.digest);
+        }
+        const stale = await readStale(path.join(durablePath, STALE_FILE));
+        const authority = await readOptionalAuthority(path.join(durablePath, AUTH_FILE));
+        const shouldImport = stale !== undefined
+            ? stale.bootstrap_digest !== bootstrap.digest
+            : authority === undefined || (observedBootstrap !== undefined
+                && observedBootstrap.bootstrap_digest !== bootstrap.digest);
+        authority?.bytes.fill(0);
+        if (shouldImport) {
+            await atomicCredentialWrite(path.join(durablePath, AUTH_FILE), bootstrap.bytes);
+            await unlink(path.join(durablePath, STALE_FILE)).catch(ignoreMissing);
+            await syncDirectory(durablePath);
+        }
+        if (shouldImport || observedBootstrap === undefined) {
+            await writeBootstrap(path.join(durablePath, BOOTSTRAP_FILE), bootstrap.digest);
+        }
+        if (await readStale(path.join(durablePath, STALE_FILE)) !== undefined)
+            throw redact();
+        return bootstrap.digest;
+    }
+    finally {
+        bootstrap.bytes.fill(0);
+    }
+}
+async function runLeasedTurn(durablePath, bootstrapDigest, agent, operation, onTransition) {
+    if (await readStale(path.join(durablePath, STALE_FILE)) !== undefined)
+        throw redact();
+    await verifyPrivateDirectory(path.dirname(path.join(agent.runtimeHomePath, GROK_SUBSCRIPTION_REALM.agentCredentialRelativePath)));
+    const target = path.join(agent.runtimeHomePath, GROK_SUBSCRIPTION_REALM.agentCredentialRelativePath);
+    await assertAbsent(target);
+    const authority = await readCredential(path.join(durablePath, AUTH_FILE));
+    const journalPath = path.join(durablePath, JOURNAL_FILE);
+    try {
+        await writeJournal(journalPath, { agent_id: agent.id, source_digest: authority.digest, state: "preparing", version: "noopolis.daimon.grok-credential-lease.v1" });
+        await atomicCredentialWrite(target, authority.bytes);
+        await writeJournal(journalPath, { agent_id: agent.id, source_digest: authority.digest, state: "active", version: "noopolis.daimon.grok-credential-lease.v1" });
+    }
+    finally {
+        authority.bytes.fill(0);
+    }
+    let result;
+    let operationError;
+    try {
+        result = await operation();
+    }
+    catch (error) {
+        operationError = error;
+    }
+    if (asGrokAuthenticationRejected(operationError) !== undefined) {
+        await unlink(target).catch(ignoreMissing);
+        await syncDirectory(path.dirname(target));
+        await markStale(durablePath, bootstrapDigest);
+        throw redact();
+    }
+    const candidate = await tryReadCredential(target);
+    if (candidate === undefined) {
+        await unlink(target).catch(ignoreMissing);
+        await syncDirectory(path.dirname(target));
+        await markStale(durablePath, bootstrapDigest);
+        throw redact(operationError);
+    }
+    try {
+        await writeJournal(journalPath, {
+            agent_id: agent.id,
+            promoted_digest: candidate.digest,
+            source_digest: authority.digest,
+            state: "promoting",
+            version: "noopolis.daimon.grok-credential-lease.v1"
+        });
+        await onTransition?.("promotion_prepared");
+        await atomicCredentialWrite(path.join(durablePath, AUTH_FILE), candidate.bytes);
+        await onTransition?.("authority_replaced");
+        await writeJournal(journalPath, {
+            agent_id: agent.id,
+            promoted_digest: candidate.digest,
+            source_digest: authority.digest,
+            state: "promoted",
+            version: "noopolis.daimon.grok-credential-lease.v1"
+        });
+        await unlink(target).catch(ignoreMissing);
+        await syncDirectory(path.dirname(target));
+        await unlink(journalPath).catch(ignoreMissing);
+        await syncDirectory(durablePath);
+    }
+    finally {
+        candidate.bytes.fill(0);
+    }
+    if (operationError !== undefined)
+        throw operationError;
+    return result;
+}
+async function recoverJournal(durablePath, journal, agents, bootstrapDigest) {
+    const agent = agents.get(journal.agent_id);
+    const target = agent === undefined ? undefined
+        : path.join(agent.runtimeHomePath, GROK_SUBSCRIPTION_REALM.agentCredentialRelativePath);
+    if (target !== undefined)
+        await verifyPrivateDirectory(path.dirname(target));
+    const authority = await readCredential(path.join(durablePath, AUTH_FILE));
+    const authorityDigest = authority.digest;
+    try {
+        const expected = journal.state === "promoted" ? [journal.promoted_digest]
+            : journal.state === "promoting" ? [journal.source_digest, journal.promoted_digest]
+                : [journal.source_digest];
+        if (!expected.includes(authorityDigest)) {
+            if (target !== undefined) {
+                await unlink(target).catch(ignoreMissing);
+                await syncDirectory(path.dirname(target));
+            }
+            await markStale(durablePath, bootstrapDigest);
+            return;
+        }
+    }
+    finally {
+        authority.bytes.fill(0);
+    }
+    if (journal.state === "promoted") {
+        if (target !== undefined) {
+            await unlink(target).catch(ignoreMissing);
+            await syncDirectory(path.dirname(target));
+        }
+        await unlink(path.join(durablePath, JOURNAL_FILE)).catch(ignoreMissing);
+        await syncDirectory(durablePath);
+        return;
+    }
+    if (journal.state === "preparing") {
+        if (target !== undefined)
+            await unlink(target).catch(ignoreMissing);
+        await unlink(path.join(durablePath, JOURNAL_FILE)).catch(ignoreMissing);
+        await syncDirectory(durablePath);
+        return;
+    }
+    const candidate = target === undefined ? undefined : await tryReadCredential(target);
+    if (candidate === undefined) {
+        if (target !== undefined) {
+            await unlink(target).catch(ignoreMissing);
+            await syncDirectory(path.dirname(target));
+        }
+        await markStale(durablePath, bootstrapDigest);
+        return;
+    }
+    try {
+        if (journal.state === "promoting" && candidate.digest !== journal.promoted_digest) {
+            await markStale(durablePath, bootstrapDigest);
+            return;
+        }
+        if (journal.state === "active")
+            await writeJournal(path.join(durablePath, JOURNAL_FILE), { ...journal, promoted_digest: candidate.digest, state: "promoting" });
+        if (authorityDigest === journal.source_digest) {
+            await atomicCredentialWrite(path.join(durablePath, AUTH_FILE), candidate.bytes);
+        }
+        await writeJournal(path.join(durablePath, JOURNAL_FILE), {
+            ...journal, promoted_digest: candidate.digest, state: "promoted"
+        });
+        await unlink(target).catch(ignoreMissing);
+        await syncDirectory(path.dirname(target));
+        await unlink(path.join(durablePath, JOURNAL_FILE)).catch(ignoreMissing);
+        await syncDirectory(durablePath);
+    }
+    finally {
+        candidate.bytes.fill(0);
+    }
+}
+async function markStale(durablePath, bootstrapDigest) {
+    await atomicJsonWrite(path.join(durablePath, STALE_FILE), {
+        bootstrap_digest: bootstrapDigest,
+        version: "noopolis.daimon.grok-credential-stale.v1"
+    });
+    await unlink(path.join(durablePath, JOURNAL_FILE)).catch(ignoreMissing);
+    await syncDirectory(durablePath);
+}
+async function readCredential(file) {
+    let handle;
+    try {
+        const before = await lstat(file);
+        assertCredentialIdentity(before);
+        handle = await open(file, constants.O_RDONLY | noFollow());
+        const opened = await handle.stat();
+        assertCredentialIdentity(opened);
+        if (!sameIdentity(before, opened))
+            throw new Error("changed");
+        const bytes = await handle.readFile();
+        const after = await handle.stat();
+        if (!sameIdentity(opened, after) || !hasRefreshablePortableCredential("grok", bytes)) {
+            bytes.fill(0);
+            throw new Error("invalid");
+        }
+        return { bytes, digest: createHash("sha256").update(bytes).digest("hex") };
+    }
+    catch {
+        throw redact();
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function tryReadCredential(file) {
+    try {
+        return await readCredential(file);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readOptionalAuthority(file) {
+    try {
+        return await readCredential(file);
+    }
+    catch {
+        try {
+            await lstat(file);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+        }
+        throw redact();
+    }
+}
+async function atomicCredentialWrite(file, bytes) {
+    await atomicWrite(file, bytes, GROK_SUBSCRIPTION_REALM.fileMode);
+    const checked = await readCredential(file);
+    checked.bytes.fill(0);
+}
+async function atomicJsonWrite(file, value) {
+    await atomicWrite(file, Buffer.from(`${JSON.stringify(value)}\n`), 0o600);
+}
+async function atomicWrite(file, bytes, mode) {
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | noFollow(), mode);
+        await handle.writeFile(bytes);
+        await handle.chmod(mode);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, file);
+        await syncDirectory(path.dirname(file));
+    }
+    catch {
+        throw redact();
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+async function writeJournal(file, value) { await atomicJsonWrite(file, value); }
+async function readJournal(file) {
+    return readPrivateJson(file, (value) => {
+        const candidate = value;
+        if (candidate.version !== "noopolis.daimon.grok-credential-lease.v1" || !["active", "preparing", "promoted", "promoting"].includes(candidate.state ?? "")
+            || typeof candidate.agent_id !== "string" || !candidate.agent_id || !/^[a-f0-9]{64}$/u.test(candidate.source_digest ?? "")
+            || (["promoted", "promoting"].includes(candidate.state ?? "") && !/^[a-f0-9]{64}$/u.test(candidate.promoted_digest ?? "")))
+            throw new Error("invalid");
+        return candidate;
+    });
+}
+async function readStale(file) {
+    return readPrivateJson(file, (value) => {
+        const candidate = value;
+        if (candidate.version !== "noopolis.daimon.grok-credential-stale.v1" || typeof candidate.bootstrap_digest !== "string" || !/^[a-f0-9]{64}$/u.test(candidate.bootstrap_digest))
+            throw new Error("invalid");
+        return { bootstrap_digest: candidate.bootstrap_digest };
+    });
+}
+async function readBootstrap(file) {
+    return readPrivateJson(file, (value) => {
+        const candidate = value;
+        if (candidate.version !== "noopolis.daimon.grok-bootstrap-observation.v1" || typeof candidate.bootstrap_digest !== "string" || !/^[a-f0-9]{64}$/u.test(candidate.bootstrap_digest))
+            throw new Error("invalid");
+        return { bootstrap_digest: candidate.bootstrap_digest };
+    });
+}
+async function writeBootstrap(file, bootstrapDigest) {
+    await atomicJsonWrite(file, {
+        bootstrap_digest: bootstrapDigest,
+        version: "noopolis.daimon.grok-bootstrap-observation.v1"
+    });
+}
+async function readPrivateJson(file, parse) {
+    let handle;
+    let bytes;
+    try {
+        const before = await lstat(file);
+        assertPrivateFileIdentity(before, MAX_CONTROL_BYTES);
+        handle = await open(file, constants.O_RDONLY | noFollow());
+        const opened = await handle.stat();
+        assertPrivateFileIdentity(opened, MAX_CONTROL_BYTES);
+        if (!sameIdentity(before, opened))
+            throw new Error("changed");
+        bytes = await handle.readFile();
+        const after = await handle.stat();
+        if (!sameIdentity(opened, after))
+            throw new Error("changed");
+        return parse(JSON.parse(bytes.toString("utf8")));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw redact();
+    }
+    finally {
+        bytes?.fill(0);
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function verifyPrivateDirectory(directory) {
+    try {
+        const entry = await lstat(directory);
+        if (!entry.isDirectory() || entry.isSymbolicLink() || entry.uid !== process.getuid?.() || (entry.mode & 0o777) !== GROK_SUBSCRIPTION_REALM.directoryMode)
+            throw new Error("unsafe");
+    }
+    catch {
+        throw redact();
+    }
+}
+async function assertAbsent(file) {
+    try {
+        await lstat(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+    }
+    throw redact();
+}
+async function acquireRealmLease(durablePath, options) {
+    let lock;
+    let child;
+    try {
+        lock = await open(path.join(durablePath, LEASE_FILE), constants.O_CREAT | constants.O_RDWR | noFollow(), 0o600);
+        const entry = await lock.stat();
+        if (!entry.isFile() || entry.uid !== process.getuid?.() || entry.nlink !== 1 || (entry.mode & 0o777) !== 0o600)
+            throw new Error("unsafe");
+        child = trackCliChild(spawn(options.shell ?? "/bin/sh", ["-c", "\"$1\" --exclusive --nonblock --conflict-exit-code 73 3 || exit 73; printf 'ready\\n'; IFS= read -r _hold || :", "daimon-grok-lease", options.flock ?? "flock"], { detached: process.platform !== "win32", env: { LANG: "C", LC_ALL: "C", PATH: process.env.PATH }, stdio: ["pipe", "pipe", "ignore", lock.fd] }));
+        await waitForReady(child);
+        return child;
+    }
+    catch {
+        if (child !== undefined)
+            await terminateChild(child).catch(() => undefined);
+        throw redact();
+    }
+    finally {
+        await lock?.close().catch(() => undefined);
+    }
+}
+async function waitForReady(child) {
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("timeout")), 5_000);
+        child.stdout?.once("data", (value) => { clearTimeout(timer); value.toString("utf8") === "ready\n" ? resolve() : reject(new Error("invalid")); });
+        child.once("close", () => { clearTimeout(timer); reject(new Error("closed")); });
+        child.once("error", () => { clearTimeout(timer); reject(new Error("failed")); });
+    });
+}
+async function syncDirectory(directory) { const handle = await open(directory, constants.O_RDONLY); try {
+    await handle.sync();
+}
+finally {
+    await handle.close();
+} }
+const ignoreMissing = (error) => { if (error.code !== "ENOENT")
+    throw error; };
+const noFollow = () => constants.O_NOFOLLOW ?? 0;
+const sameIdentity = (left, right) => left.dev === right.dev && left.ino === right.ino && left.mode === right.mode && left.nlink === right.nlink && left.size === right.size && left.uid === right.uid && left.mtimeMs === right.mtimeMs;
+const assertCredentialIdentity = (entry) => { if (!entry.isFile() || entry.isSymbolicLink() || Number(entry.uid) !== process.getuid?.() || Number(entry.nlink) !== 1 || (Number(entry.mode) & 0o777) !== GROK_SUBSCRIPTION_REALM.fileMode || Number(entry.size) < 1 || Number(entry.size) > GROK_SUBSCRIPTION_REALM.maxCredentialBytes)
+    throw new Error("unsafe"); };
+const assertPrivateFileIdentity = (entry, maxBytes) => { if (!entry.isFile() || entry.isSymbolicLink() || Number(entry.uid) !== process.getuid?.() || Number(entry.nlink) !== 1 || (Number(entry.mode) & 0o777) !== 0o600 || Number(entry.size) < 1 || Number(entry.size) > maxBytes)
+    throw new Error("unsafe"); };
+const redact = (_cause) => new Error("Grok subscription credential realm is unavailable or stale");

package/dist/runtime/grokSubscriptionRealmTypes.d.ts

@@ -0,0 +1,26 @@
+import type { OrganizationRuntimeAgentConfig } from "./organizationRuntime.js";
+export type GrokAgent = OrganizationRuntimeAgentConfig & {
+    engine: {
+        kind: "grok";
+    };
+};
+export type GrokCredentialJournal = Readonly<{
+    agent_id: string;
+    promoted_digest?: string;
+    source_digest: string;
+    state: "active" | "preparing" | "promoted" | "promoting";
+    version: "noopolis.daimon.grok-credential-lease.v1";
+}>;
+export type GrokSubscriptionRealm = Readonly<{
+    withCredential<T>(agent: GrokAgent, operation: () => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}>;
+export type GrokSubscriptionRealmOptions = Readonly<{
+    bootstrapPath?: string;
+    durablePath?: string;
+    flock?: string;
+    /** @internal deterministic crash-transition test seam. */
+    onTransitionForTest?: (stage: "authority_replaced" | "promotion_prepared") => Promise<void> | void;
+    shell?: string;
+}>;
+//# sourceMappingURL=grokSubscriptionRealmTypes.d.ts.map

package/dist/runtime/grokSubscriptionRealmTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grokSubscriptionRealmTypes.d.ts","sourceRoot":"","sources":["../../src/runtime/grokSubscriptionRealmTypes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAE/E,MAAM,MAAM,SAAS,GAAG,8BAA8B,GAAG;IAAE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAEtF,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,WAAW,CAAC;IACzD,OAAO,EAAE,0CAA0C,CAAC;CACrD,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACnG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC"}

package/dist/runtime/grokSubscriptionRealmTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/grokWorkerAttestation.d.ts

@@ -0,0 +1,170 @@
+import { type GrokWorkerTmpOptions } from "./grokWorkerTmpAttestation.js";
+/**
+ * The per-turn freshness watermark taken before the worker is launched: the
+ * exact inode and its byte length at that moment. Everything at or below
+ * `size` is pre-turn history and is never read back — a `ProfileApplied` down
+ * there is a replay, not evidence about this turn.
+ */
+export type GrokWorkerAttestationSnapshot = Readonly<{
+    dev: number;
+    ino: number;
+    size: number;
+    denyPaths: readonly string[];
+}>;
+type Snapshot = GrokWorkerAttestationSnapshot;
+export declare class GrokWorkerAttestationFailure extends Error {
+    readonly failureClass: "profile_missing" | "profile_invalid";
+    constructor(failureClass: "profile_missing" | "profile_invalid");
+}
+/**
+ * Reads the `deny` list out of a worker sandbox profile, but only after the
+ * bytes match `profileSha256` exactly.
+ *
+ * There is no minimum length, and a populated list is supported. Grok 1.0.13
+ * refused to start on any non-empty `deny` (its mode-000 placeholders failed
+ * an EACCES "__GROK_INSIDE_BWRAP spoof" check), so deployments rendered
+ * `deny = []`. Grok 1.0.34 runs every profile inside bubblewrap and enforces a
+ * non-empty list, and since its strict base reads all of `/run`, `/var` and
+ * `/tmp`, the deny list is what keeps evaluator and host-bind paths away from
+ * the worker. `grokWorkerSandboxProfile.ts` renders these bytes.
+ *
+ * The integrity guarantee is the hash pin, not the length. `profileSha256`
+ * comes from `/etc/daimon-engine-broker/service.json`, which the root
+ * provisioning phase writes `0440 root:2100` with `flag: 'wx'` and computes
+ * from the same `profileFor()` bytes it writes to the profile; the broker
+ * reads that config as uid 2100 and cannot rewrite it. A weaker profile
+ * therefore cannot be attested: changing any byte — dropping
+ * `restrict_network`, swapping `extends = "strict"` for a permissive base,
+ * renaming the profile — changes the digest and fails here. And the deny list
+ * this returns is not merely parsed and discarded: it is carried into the
+ * snapshot and re-asserted against the kernel's own `ProfileApplied`
+ * `deny_paths` by `parseGrokWorkerProfileApplied`, which independently
+ * requires `enforced`, `restrict_network`, `platform === "linux/landlock"`
+ * and the exact workspace. A length floor would only have caught a Spawnfile
+ * rendering bug that produced a trivial profile *and* pinned it consistently
+ * — and Spawnfile's own tests pin the rendered bytes.
+ */
+export declare function parseGrokWorkerSandboxProfile(bytes: Uint8Array, profileSha256: string): readonly string[];
+/**
+ * Pre-launch half of the per-turn attestation. Besides the pinned profile and
+ * the events watermark it requires the 1.0.34 layout: events under
+ * `$GROK_HOME/sessions/` (the root `sandbox-events.jsonl` stays empty on
+ * 1.0.34), and a root-owned read-only worker home whose `config.toml` hashes to
+ * the declared renderer output (`grokWorkerHomeAttestation.ts`).
+ *
+ * It also refuses a deny list bubblewrap could not materialize
+ * (`grokWorkerDenyPlacement.ts`), naming the entry and the ancestor that stops
+ * it. Without this the worker dies with a bare `bwrap: Can't create file at
+ * …: Permission denied` on *every* turn, because one unplaceable entry makes
+ * Grok refuse the whole profile. The broker cannot descend into a directory
+ * opened to the worker's group alone (`<runtime home>/tool-state` under a
+ * `2000:<worker> 0710` home), so an `EACCES` there is left undecided; root
+ * provisioning, which holds `CAP_DAC_READ_SEARCH`, is the authority that
+ * decides every entry.
+ */
+export declare function prepareGrokWorkerAttestation(input: Readonly<{
+    profilePath: string;
+    eventsPath: string;
+    profileSha256: string;
+    workerUid: number;
+    workerGid?: number;
+    brokerGid: number;
+    configSha256: string;
+    registeredWorkers?: readonly Readonly<{
+        profilePath: string;
+        workerUid: number;
+    }>[];
+}>, profileOwner?: Readonly<{
+    uid: number;
+    gid: number;
+    tmp?: GrokWorkerTmpOptions;
+}>): Promise<Snapshot>;
+/** The per-turn attestation input for one registration, carrying every registered worker so sibling temp is attested too. */
+export declare const grokBrokerAttestationInput: <T extends Readonly<{
+    profilePath: string;
+    eventsPath: string;
+    profileSha256: string;
+    workerUid: number;
+}>>(registration: T, registrations: readonly Readonly<{
+    profilePath: string;
+    workerUid: number;
+}>[], configSha256: string) => T & {
+    brokerGid: number;
+    configSha256: string;
+    registeredWorkers: {
+        profilePath: string;
+        workerUid: number;
+    }[];
+};
+/**
+ * The accepted `ProfileApplied` line of one turn, as an absolute byte range of
+ * the events file plus its digest.
+ */
+export type GrokWorkerAttestationLock = {
+    accepted?: Readonly<{
+        offset: number;
+        length: number;
+        digest: string;
+    }>;
+    refused?: GrokWorkerAttestationFailure["failureClass"];
+};
+/**
+ * The per-turn isolation guard: every model request of a turn, and the
+ * post-turn check, go through the same lock.
+ *
+ * Why the first verification is trustworthy: the proxy awaits this guard before
+ * *every* upstream request, including the first, and the only worker-uid
+ * process that exists before request 1 is the Grok the launcher started under
+ * the pinned profile — tool children are created only after a model response.
+ * So the event accepted at request 1 was written before any tool child could
+ * write to the (worker-owned) events file. Later requests must find that exact
+ * line, byte for byte, at the same offset: a `ProfileApplied` appended later —
+ * which a tool child could forge — is never a substitute, and once a turn has
+ * been refused it stays refused.
+ */
+export declare function createGrokWorkerIsolationGuard(input: Parameters<typeof verifyGrokWorkerAttestation>[0], before: Snapshot): () => Promise<void>;
+export declare function verifyGrokWorkerAttestation(input: Readonly<{
+    eventsPath: string;
+    workerUid: number;
+    brokerGid: number;
+    workspace: string;
+}>, before: Snapshot, lock?: GrokWorkerAttestationLock): Promise<void>;
+/**
+ * Requires one fully-conforming `ProfileApplied` event *somewhere* in the
+ * fresh region — not as its last line.
+ *
+ * `sandbox-events.jsonl` is not a profile log. Grok (1.0.13 and 1.0.34) writes its whole
+ * sandbox event vocabulary there — verified by reading the shipped binary:
+ * `ProfileApplied, ApplyFailed, FsViolation, NetViolation, BypassGranted,
+ * BypassDenied` (one contiguous enum blob beside the record fields
+ * `timestamp, event_type, read_only_paths, deny_paths, operation, target,
+ * command, tool_call_id`, emitted from `xai_grok_sandbox::logging`), and its
+ * own embedded documentation says so outright: "Sandbox events (profile
+ * applied, violations) are logged to `~/.grok/sandbox-events.jsonl`" (1.0.34
+ * moved the file to `~/.grok/sessions/`; a 1.0.34 turn logs `ProfileApplied`
+ * followed by an `FsViolation` for every denied read).
+ *
+ * Requiring `ProfileApplied` to be the *last* line therefore failed on the
+ * first denied access of any turn: the violation Grok logged next became the
+ * last line, this threw, the proxy's per-request isolation guard refused, and
+ * the turn died `profile_invalid`. Denials are the normal operating state of
+ * a working sandbox, so that check turned the sandbox doing its job into a
+ * turn failure.
+ *
+ * Scanning the region is not weaker. The region is fresh by construction —
+ * the caller reads only bytes above the pre-launch dev/ino/size watermark, so
+ * nothing here predates this turn and a stale or replayed event below it is
+ * unreachable. Both forms are equally forgeable by the same single actor (a
+ * worker-uid process, which can only exist by being a Grok that the launcher
+ * already started under the pinned profile), and both detect the failure this
+ * guard exists for: a Grok that came up without kernel enforcement, which
+ * emits no conforming `ProfileApplied` at all.
+ */
+export declare function parseGrokWorkerProfileApplied(bytes: Uint8Array, workspace: string, denyPaths?: readonly string[]): void;
+/** Byte range (within `bytes`) of the first fully-conforming `ProfileApplied` line. */
+export declare function locateGrokWorkerProfileApplied(bytes: Uint8Array, workspace: string, denyPaths?: readonly string[]): Readonly<{
+    offset: number;
+    length: number;
+}>;
+export {};
+//# sourceMappingURL=grokWorkerAttestation.d.ts.map

package/dist/runtime/grokWorkerAttestation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grokWorkerAttestation.d.ts","sourceRoot":"","sources":["../../src/runtime/grokWorkerAttestation.ts"],"names":[],"mappings":"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"}