spawnfile 0.1.14 → 0.1.18

package/dist/auth/targetSecretSourceFsPublishImmutable.js

@@ -2,48 +2,37 @@ import { constants } from "node:fs";
 import { link, lstat, open, unlink } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { TARGET_SECRET_SOURCE_ERROR, parseTargetSecretSourceOpaqueHandle } from "./targetSecretSourceRecordCommon.js";
+import { directoryIdentityOf, fileIdentityOf, sameDirectory, sameFileExact, sameFileInode, sameFileNode } from "./targetSecretSourceFsIdentity.js";
 const MAX_BYTES = 65_536;
 const MAX_ATTEMPTS = 512;
 const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
 const missing = (error) => error.code === "ENOENT";
 const exists = (error) => error.code === "EEXIST";
-const same = (a, b) => a.dev === b.dev && a.ino === b.ino && a.mode === b.mode && a.nlink === b.nlink && a.size === b.size && a.uid === b.uid;
-const sameNode = (a, b) => a.dev === b.dev && a.ino === b.ino && a.mode === b.mode && a.nlink === b.nlink && a.uid === b.uid;
-const sameInode = (a, b) => a.dev === b.dev && a.ino === b.ino && a.mode === b.mode && a.size === b.size && a.uid === b.uid;
 const ownerUid = () => {
     const value = process.getuid?.();
     return typeof value === "number" ? value : fail();
 };
-const directoryIdentity = (value, uid) => {
-    if (!value.isDirectory() || value.isSymbolicLink() || value.uid !== uid || (value.mode & 0o7777) !== 0o700)
-        fail();
-    return { dev: value.dev, ino: value.ino, mode: value.mode, nlink: 0, size: 0, uid: value.uid };
-};
-const fileIdentity = (value, uid, links, zero = false) => {
-    if (!value.isFile() || value.isSymbolicLink() || value.uid !== uid || !links.includes(value.nlink)
-        || (value.mode & 0o7777) !== 0o600 || value.size < 0 || value.size > MAX_BYTES || (zero && value.size !== 0))
-        fail();
-    return { dev: value.dev, ino: value.ino, mode: value.mode, nlink: value.nlink, size: value.size, uid: value.uid };
-};
-const yieldTurn = () => new Promise((resolve) => setImmediate(resolve));
+const directoryIdentity = (value, uid) => directoryIdentityOf(value, uid);
+const fileIdentity = (value, uid, links, zero = false) => fileIdentityOf(value, uid, links, MAX_BYTES, zero);
+const contentionDelay = (attempt) => new Promise((resolve) => setTimeout(resolve, Math.min(5, 1 + Math.floor(attempt / 32))));
 export const initializeTargetSecretSourceFsPublishImmutable = async (options) => {
     if (!options || typeof options !== "object" || !Array.isArray(options.directory_chain) || options.directory_chain.length < 1
         || options.directory_chain.some((entry) => typeof entry !== "string" || entry.length < 1))
         fail();
     const uid = ownerUid();
     const paths = [...options.directory_chain];
-    const roots = await Promise.all(paths.map(async (path) => directoryIdentity(await lstat(path), uid)));
+    const roots = await Promise.all(paths.map(async (path) => directoryIdentity(await lstat(path, { bigint: true }), uid)));
     const checkChain = async () => {
         for (let index = 0; index < paths.length; index += 1) {
-            const named = directoryIdentity(await lstat(paths[index]), uid);
-            if (!same(named, roots[index]))
+            const named = directoryIdentity(await lstat(paths[index], { bigint: true }), uid);
+            if (!sameDirectory(named, roots[index]))
                 fail();
             let fd;
             try {
                 fd = await open(paths[index], constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
-                const opened = directoryIdentity(await fd.stat(), uid);
-                const after = directoryIdentity(await lstat(paths[index]), uid);
-                if (!same(opened, roots[index]) || !same(after, roots[index]))
+                const opened = directoryIdentity(await fd.stat({ bigint: true }), uid);
+                const after = directoryIdentity(await lstat(paths[index], { bigint: true }), uid);
+                if (!sameDirectory(opened, roots[index]) || !sameDirectory(after, roots[index]))
                     fail();
             }
             catch {
@@ -60,13 +49,13 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
         let fd;
         try {
             fd = await open(paths.at(-1), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
-            const opened = directoryIdentity(await fd.stat(), uid);
-            if (!same(opened, roots.at(-1)))
+            const opened = directoryIdentity(await fd.stat({ bigint: true }), uid);
+            if (!sameDirectory(opened, roots.at(-1)))
                 fail();
             await fd.sync();
-            const after = directoryIdentity(await fd.stat(), uid);
-            const named = directoryIdentity(await lstat(paths.at(-1)), uid);
-            if (!same(after, roots.at(-1)) || !same(named, roots.at(-1)))
+            const after = directoryIdentity(await fd.stat({ bigint: true }), uid);
+            const named = directoryIdentity(await lstat(paths.at(-1), { bigint: true }), uid);
+            if (!sameDirectory(after, roots.at(-1)) || !sameDirectory(named, roots.at(-1)))
                 fail();
         }
         catch {
@@ -81,8 +70,8 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
         await checkChain();
         let before;
         try {
-            const beforeInfo = await lstat(path);
-            if (beforeInfo.nlink === 0) {
+            const beforeInfo = await lstat(path, { bigint: true });
+            if (beforeInfo.nlink === 0n) {
                 fileIdentity(beforeInfo, uid, [0], true);
                 return null;
             }
@@ -93,6 +82,7 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
                 return null;
             return fail();
         }
+        await options.hookForTest?.("after_zero_lstat", path);
         let fd;
         try {
             try {
@@ -105,16 +95,16 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
             }
             if (!fd)
                 return fail();
-            const openedInfo = await fd.stat();
-            if (openedInfo.nlink === 0) {
+            const openedInfo = await fd.stat({ bigint: true });
+            if (openedInfo.nlink === 0n) {
                 fileIdentity(openedInfo, uid, [0], true);
                 return null;
             }
             const opened = fileIdentity(openedInfo, uid, links, true);
             let after;
             try {
-                const afterInfo = await lstat(path);
-                if (afterInfo.nlink === 0) {
+                const afterInfo = await lstat(path, { bigint: true });
+                if (afterInfo.nlink === 0n) {
                     fileIdentity(afterInfo, uid, [0], true);
                     return null;
                 }
@@ -125,7 +115,7 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
                     return null;
                 return fail();
             }
-            if (!sameInode(before, opened) || !sameInode(opened, after) || !same(before, opened) || !same(opened, after))
+            if (!sameFileInode(before, opened) || !sameFileInode(opened, after) || !sameFileExact(before, opened) || !sameFileExact(opened, after))
                 return null;
             return opened;
         }
@@ -139,15 +129,16 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
     const unlinkExact = async (path, expected) => {
         await checkChain();
         const current = await snapshotZero(path, [1, 2]);
-        if (current === null || !sameInode(current, expected) || !same(current, expected))
+        if (current === null || !sameFileInode(current, expected) || !sameFileExact(current, expected))
             return false;
         const immediate = await snapshotZero(path, [1, 2]);
         if (immediate === null) {
             await syncDirectory();
             return false;
         }
-        if (!sameInode(immediate, expected) || !same(immediate, expected))
+        if (!sameFileInode(immediate, expected) || !sameFileExact(immediate, expected))
             return false;
+        await options.hookForTest?.("before_unlink_exact", path);
         try {
             await unlink(path);
         }
@@ -164,21 +155,22 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
         await checkChain();
         let before;
         try {
-            before = fileIdentity(await lstat(path), uid, [1]);
+            before = fileIdentity(await lstat(path, { bigint: true }), uid, [1]);
         }
         catch (error) {
             if (missing(error))
                 return "absent";
             return fail();
         }
+        await options.hookForTest?.("after_final_lstat", path);
         if (before.size > expected.length)
             fail();
         let fd;
         let bytes;
         try {
             fd = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
-            const opened = fileIdentity(await fd.stat(), uid, [1]);
-            if (!sameNode(before, opened) || opened.size > expected.length)
+            const opened = fileIdentity(await fd.stat({ bigint: true }), uid, [1]);
+            if (!sameFileNode(before, opened) || opened.size > expected.length)
                 fail();
             bytes = new Uint8Array(opened.size);
             let offset = 0;
@@ -188,18 +180,20 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
                     fail();
                 offset += read.bytesRead;
             }
-            const after = fileIdentity(await fd.stat(), uid, [1]);
-            const named = fileIdentity(await lstat(path), uid, [1]);
-            if (!sameNode(opened, after) || !sameNode(opened, named))
+            const after = fileIdentity(await fd.stat({ bigint: true }), uid, [1]);
+            const named = fileIdentity(await lstat(path, { bigint: true }), uid, [1]);
+            if (!sameFileNode(opened, after) || !sameFileNode(opened, named))
                 fail();
-            if (!same(opened, after) || !same(opened, named))
+            if (!sameFileExact(opened, after) || !sameFileExact(opened, named))
                 return "prefix";
             for (let index = 0; index < bytes.length; index += 1)
                 if (bytes[index] !== expected[index])
                     fail();
             return bytes.length === expected.length ? "exact" : "prefix";
         }
-        catch {
+        catch (error) {
+            if (missing(error))
+                return "absent";
             return fail();
         }
         finally {
@@ -213,15 +207,24 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
         try {
             fd = await open(token, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
             await fd.chmod(0o600);
-            const opened = fileIdentity(await fd.stat(), uid, [1], true);
+            await options.hookForTest?.("after_token_open", token);
+            // An identical publisher may link or finish tearing down this token as soon
+            // as O_EXCL makes the pathname visible, before its creator reaches fstat.
+            const openedInfo = await fd.stat({ bigint: true });
+            if (openedInfo.nlink === 0n) {
+                fileIdentity(openedInfo, uid, [0], true);
+                return null;
+            }
+            const opened = fileIdentity(openedInfo, uid, [1, 2], true);
             await fd.sync();
-            const afterInfo = await fd.stat();
-            if (afterInfo.nlink === 0) {
+            await options.hookForTest?.("after_token_sync", token);
+            const afterInfo = await fd.stat({ bigint: true });
+            if (afterInfo.nlink === 0n) {
                 fileIdentity(afterInfo, uid, [0], true);
                 return null;
             }
             const after = fileIdentity(afterInfo, uid, [1, 2], true);
-            if (!sameInode(opened, after))
+            if (!sameFileInode(opened, after))
                 fail();
             await syncDirectory();
             await options.hookForTest?.("after_token_create", token);
@@ -271,6 +274,13 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
             await proveOwned();
             const claim = `${final}.claim`;
             const token = `${final}.token.${publicationHandle}`;
+            const retryContention = async (attempt, contestedPath, reason) => {
+                options.contentionForTest?.(reason, attempt);
+                await options.hookForTest?.("before_contention_retry", contestedPath);
+                if (attempt >= MAX_ATTEMPTS - 1)
+                    fail();
+                await contentionDelay(attempt);
+            };
             const proveFinal = async () => {
                 if (await readFinal(final, owned) !== "exact")
                     return false;
@@ -288,14 +298,22 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
                     return;
                 }
                 if (claimState !== null && tokenState === null) {
-                    if (finalState !== "exact" || claimState.nlink !== 1) {
-                        await yieldTurn();
+                    if (finalState !== "exact" || claimState.nlink !== 1n) {
+                        await retryContention(attempt, claim, "orphan-claim-not-cleanable");
                         continue;
                     }
                     if (!await proveFinal())
                         fail();
                     if (!await unlinkExact(claim, claimState)) {
-                        await yieldTurn();
+                        const latestClaim = await snapshotZero(claim, [1, 2]);
+                        if (latestClaim === null) {
+                            if (!await proveFinal())
+                                fail();
+                            return;
+                        }
+                        if (!sameFileInode(latestClaim, claimState))
+                            fail();
+                        await retryContention(attempt, claim, "orphan-claim-cleanup-race");
                         continue;
                     }
                     return;
@@ -304,11 +322,11 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
                 if (ownedToken === null)
                     ownedToken = await createToken(token);
                 if (ownedToken === null) {
-                    await yieldTurn();
+                    await retryContention(attempt, token, "token-election-race");
                     continue;
                 }
                 let currentClaim = await snapshotZero(claim, [1, 2]);
-                if (currentClaim === null && ownedToken.nlink === 1) {
+                if (currentClaim === null && ownedToken.nlink === 1n) {
                     try {
                         await checkChain();
                         await link(token, claim);
@@ -323,21 +341,21 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
                     ownedToken = await snapshotZero(token, [1, 2]);
                 }
                 if (!currentClaim || !ownedToken) {
-                    await yieldTurn();
+                    await retryContention(attempt, claim, "topology-observation-race");
                     continue;
                 }
                 if (currentClaim.dev !== ownedToken.dev || currentClaim.ino !== ownedToken.ino) {
                     await options.hookForTest?.("after_mismatch_snapshot", token);
-                    if (ownedToken.nlink === 1) {
+                    if (ownedToken.nlink === 1n) {
                         const latest = await snapshotZero(token, [1, 2]);
-                        if (latest?.nlink === 1 && same(latest, ownedToken))
+                        if (latest?.nlink === 1n && sameFileExact(latest, ownedToken))
                             await unlinkExact(token, latest);
                     }
-                    await yieldTurn();
+                    await retryContention(attempt, claim, "foreign-token-race");
                     continue;
                 }
-                if (currentClaim.nlink !== 2 || ownedToken.nlink !== 2) {
-                    await yieldTurn();
+                if (currentClaim.nlink !== 2n || ownedToken.nlink !== 2n) {
+                    await retryContention(attempt, claim, "link-count-race");
                     continue;
                 }
                 const state = await readFinal(final, owned);
@@ -346,18 +364,21 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
                     try {
                         fd = await open(final, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
                         await fd.chmod(0o600);
-                        const empty = fileIdentity(await fd.stat(), uid, [1], true);
+                        await options.hookForTest?.("after_final_open", final);
+                        const created = fileIdentity(await fd.stat({ bigint: true }), uid, [1]);
+                        if (created.size > owned.length)
+                            fail();
                         await options.hookForTest?.("after_final_create", final);
-                        const split = Math.max(1, Math.floor(owned.length / 2));
-                        let offset = 0;
+                        const split = Math.max(created.size, 1, Math.floor(owned.length / 2));
+                        let offset = created.size;
                         while (offset < split)
                             offset += await writeSome(fd, owned, offset, split - offset);
                         await options.hookForTest?.("after_partial_write", final);
                         while (offset < owned.length)
                             offset += await writeSome(fd, owned, offset, owned.length - offset);
                         await fd.sync();
-                        const complete = fileIdentity(await fd.stat(), uid, [1]);
-                        if (empty.dev !== complete.dev || empty.ino !== complete.ino || complete.size !== owned.length)
+                        const complete = fileIdentity(await fd.stat({ bigint: true }), uid, [1]);
+                        if (!sameFileNode(created, complete) || complete.size !== owned.length)
                             fail();
                         await options.hookForTest?.("after_file_sync", final);
                     }
@@ -373,15 +394,15 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
                     let fd;
                     try {
                         fd = await open(final, constants.O_RDWR | constants.O_NOFOLLOW);
-                        const before = fileIdentity(await fd.stat(), uid, [1]);
+                        const before = fileIdentity(await fd.stat({ bigint: true }), uid, [1]);
                         if (before.size > owned.length)
                             fail();
                         let offset = before.size;
                         while (offset < owned.length)
                             offset += await writeSome(fd, owned, offset, owned.length - offset);
                         await fd.sync();
-                        const after = fileIdentity(await fd.stat(), uid, [1]);
-                        if (before.dev !== after.dev || before.ino !== after.ino || after.size !== owned.length)
+                        const after = fileIdentity(await fd.stat({ bigint: true }), uid, [1]);
+                        if (!sameFileNode(before, after) || after.size !== owned.length)
                             fail();
                     }
                     catch {
@@ -392,7 +413,7 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
                     }
                 }
                 if (!await proveFinal()) {
-                    await yieldTurn();
+                    await retryContention(attempt, final, "final-write-race");
                     continue;
                 }
                 await syncDirectory();
@@ -401,8 +422,8 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
                 await options.hookForTest?.("after_exact_token_snapshot", token);
                 const exactClaim = await snapshotZero(claim, [1, 2]);
                 if (!exactToken || !exactClaim || exactToken.dev !== exactClaim.dev || exactToken.ino !== exactClaim.ino
-                    || exactToken.nlink !== 2 || exactClaim.nlink !== 2) {
-                    await yieldTurn();
+                    || exactToken.nlink !== 2n || exactClaim.nlink !== 2n) {
+                    await retryContention(attempt, claim, "cleanup-snapshot-race");
                     continue;
                 }
                 await unlinkExact(token, exactToken);
@@ -413,8 +434,20 @@ export const initializeTargetSecretSourceFsPublishImmutable = async (options) =>
                         fail();
                     return;
                 }
-                if (remainingClaim.nlink !== 1 || !await unlinkExact(claim, remainingClaim)) {
-                    await yieldTurn();
+                if (remainingClaim.nlink !== 1n) {
+                    await retryContention(attempt, claim, "claim-final-cleanup-race");
+                    continue;
+                }
+                if (!await unlinkExact(claim, remainingClaim)) {
+                    const latestClaim = await snapshotZero(claim, [1, 2]);
+                    if (latestClaim === null) {
+                        if (!await proveFinal())
+                            fail();
+                        return;
+                    }
+                    if (!sameFileInode(latestClaim, remainingClaim))
+                        fail();
+                    await retryContention(attempt, claim, "claim-final-cleanup-race");
                     continue;
                 }
                 await options.hookForTest?.("after_claim_cleanup", claim);

package/dist/auth/targetSecretSourceFsRead.js

@@ -2,6 +2,7 @@ import { Buffer } from "node:buffer";
 import { constants } from "node:fs";
 import { lstat, mkdir, open } from "node:fs/promises";
 import { MAX_JSON_GRAPH_STRING_BYTES, TARGET_SECRET_SOURCE_ERROR, parseTargetSecretSourceOpaqueHandle } from "./targetSecretSourceRecordCommon.js";
+import { directoryIdentityOf, fileIdentityOf, sameDirectory, sameFileExact } from "./targetSecretSourceFsIdentity.js";
 import { parseTargetSecretSourceAliasRecordBytes, parseTargetSecretSourceVersionRecordBytes } from "./targetSecretSourceVersionRecords.js";
 import { parseTargetSecretSourceGrantRecordBytes, parseTargetSecretSourceRedemptionRecordBytes, parseTargetSecretSourceRevocationRecordBytes } from "./targetSecretSourceGrantRecords.js";
 import { resolveAuthHome, resolveSpawnfileHome, resolveTargetSecretAliasPath, resolveTargetSecretAliasesDirectory, resolveTargetSecretGrantPath, resolveTargetSecretGrantsDirectory, resolveTargetSecretRedemptionPath, resolveTargetSecretRedemptionsDirectory, resolveTargetSecretRevocationPath, resolveTargetSecretRevocationsDirectory, resolveTargetSecretVersionPath, resolveTargetSecretVersionsDirectory, resolveTargetSecretsRoot } from "./paths.js";
@@ -9,18 +10,8 @@ const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
 const absent = (error) => error.code === "ENOENT";
 const uid = () => { const value = process.getuid?.(); if (typeof value !== "number")
     return fail(); return value; };
-const directoryIdentity = (info, owner) => {
-    if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== BigInt(owner) || (info.mode & 4095n) !== 448n)
-        return fail();
-    return { birthtimeNs: info.birthtimeNs, dev: info.dev, ino: info.ino, mode: info.mode, uid: info.uid };
-};
-const fileIdentity = (info, owner) => {
-    if (!info.isFile() || info.isSymbolicLink() || info.uid !== BigInt(owner) || info.nlink !== 1n || info.size < 0n || info.size > BigInt(MAX_JSON_GRAPH_STRING_BYTES) || (info.mode & 4095n) !== 384n)
-        return fail();
-    return { birthtimeNs: info.birthtimeNs, ctimeNs: info.ctimeNs, dev: info.dev, ino: info.ino, mode: info.mode, nlink: info.nlink, size: Number(info.size), uid: info.uid };
-};
-const sameDirectory = (left, right) => left.birthtimeNs === right.birthtimeNs && left.dev === right.dev && left.ino === right.ino && left.mode === right.mode && left.uid === right.uid;
-const sameFile = (left, right) => left.birthtimeNs === right.birthtimeNs && left.ctimeNs === right.ctimeNs && left.dev === right.dev && left.ino === right.ino && left.mode === right.mode && left.nlink === right.nlink && left.size === right.size && left.uid === right.uid;
+const directoryIdentity = (info, owner) => directoryIdentityOf(info, owner);
+const fileIdentity = (info, owner) => fileIdentityOf(info, owner, [1], MAX_JSON_GRAPH_STRING_BYTES);
 const initializeDirectory = async (directory, owner, create) => {
     let info;
     try {
@@ -134,7 +125,7 @@ const readRecord = async (file, expected, parse, chain, owner, hooks) => {
     let bytes;
     try {
         const opened = fileIdentity(await handle.stat({ bigint: true }), owner);
-        if (!sameFile(before, opened))
+        if (!sameFileExact(before, opened))
             return fail();
         bytes = Buffer.alloc(opened.size + 1);
         let offset = 0;
@@ -152,7 +143,7 @@ const readRecord = async (file, expected, parse, chain, owner, hooks) => {
         catch {
             return fail();
         }
-        if (offset !== opened.size || !sameFile(opened, after) || !sameFile(opened, pathname))
+        if (offset !== opened.size || !sameFileExact(opened, after) || !sameFileExact(opened, pathname))
             return fail();
         await checkChain(chain, owner);
         const content = Uint8Array.from(bytes.subarray(0, offset));

package/dist/auth/trainingAuth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Grok is deliberately absent. `spawnfile.training-container.v3` holds the one
+ * dedicated training Grok login in a broker-owned realm volume seeded from a
+ * read-only bootstrap leaf, and judges spend it through short inference grants
+ * (D2). Staging a Grok credential into a shared runtime home would put a
+ * rotating login where the evaluator and the image both reach it.
+ */
+export type TrainingAuthProvider = "codex" | "claude";
+export interface TrainingAuthStageOptions {
+    /** Caller-provisioned, existing private runtime home; never a host home mount. */
+    home: string;
+    provider: TrainingAuthProvider;
+    /** Explicit provisioned leaf; default is the fixed training ingress. */
+    source?: string;
+}
+/** Stages opaque credential bytes once. Never imports configuration, logs bytes, or overwrites renewed auth. */
+export declare const stageTrainingAuth: (options: TrainingAuthStageOptions) => Promise<{
+    version: "spawnfile.training-auth-stage.v1";
+    provider: TrainingAuthProvider;
+    destination: string;
+}>;

package/dist/auth/trainingAuth.js

@@ -0,0 +1,86 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, realpath, unlink } from "node:fs/promises";
+import path from "node:path";
+const targets = {
+    codex: [".daimon-inbound", "codex-auth"],
+    claude: [".claude", ".credentials.json"]
+};
+/** Stages opaque credential bytes once. Never imports configuration, logs bytes, or overwrites renewed auth. */
+export const stageTrainingAuth = async (options) => {
+    if (!Object.hasOwn(targets, options.provider))
+        throw Error("Unsupported training auth provider");
+    const home = path.resolve(options.home), source = options.source ?? `/run/paideia-auth/${options.provider}`;
+    if (!path.isAbsolute(options.home) || await realpath(home) !== home || !(await lstat(home)).isDirectory())
+        throw Error("Training home must be a canonical existing directory");
+    if (!path.isAbsolute(source) || await realpath(source) !== path.resolve(source))
+        throw Error("Training auth source must be a canonical regular leaf");
+    const input = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await input.stat({ bigint: true });
+        if (!before.isFile() || before.size < 1n || before.size > 1048576n)
+            throw Error("Training auth source must be a bounded nonempty regular leaf");
+        const [folder, leaf] = targets[options.provider];
+        const directory = path.join(home, folder);
+        try {
+            await mkdir(directory, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const existing = await lstat(directory);
+        if (!existing.isDirectory() || existing.isSymbolicLink() || existing.mode % 512 !== 0o700 || await realpath(directory) !== directory)
+            throw Error("Training auth directory must be private and canonical");
+        const bytes = Buffer.alloc(Number(before.size) + 1);
+        let primary;
+        const destination = path.join(directory, leaf), temporary = path.join(directory, `.stage-${randomUUID()}`);
+        try {
+            let length = 0;
+            while (length < bytes.length) {
+                const read = await input.read(bytes, length, bytes.length - length, null);
+                if (read.bytesRead === 0)
+                    break;
+                length += read.bytesRead;
+            }
+            const after = await input.stat({ bigint: true });
+            if (BigInt(length) !== before.size || after.size !== before.size || after.mtimeNs !== before.mtimeNs || after.ctimeNs !== before.ctimeNs || after.ino !== before.ino || after.dev !== before.dev || after.birthtimeNs !== before.birthtimeNs)
+                throw Error("Training auth source changed during staging");
+            const output = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            try {
+                await output.writeFile(bytes.subarray(0, length));
+                await output.sync();
+            }
+            finally {
+                await output.close();
+            }
+            // Exclusive publication preserves renewed credentials and never exposes a partial leaf.
+            try {
+                await link(temporary, destination);
+            }
+            catch (error) {
+                if (error.code === "EEXIST")
+                    throw Error("Training auth already present; renewed credential preserved");
+                throw error;
+            }
+        }
+        catch (error) {
+            primary = error;
+            throw error;
+        }
+        finally {
+            bytes.fill(0);
+            await unlink(temporary).catch((error) => {
+                if (error.code === "ENOENT")
+                    return;
+                if (primary)
+                    throw new AggregateError([primary, error], "Training auth staging failed and temporary cleanup is incomplete");
+                throw error;
+            });
+        }
+        return { version: "spawnfile.training-auth-stage.v1", provider: options.provider, destination };
+    }
+    finally {
+        await input.close();
+    }
+};

package/dist/auth/trainingGrokWriteback.d.ts

@@ -0,0 +1,4 @@
+/** Reads only private, bounded, canonical leaves. Errors never include credential bytes. */
+export declare const readTrainingGrokLeaf: (file: string) => Promise<Buffer>;
+/** A settled journal proves rotation; native expiry orders credentials across independent realms. */
+export declare const writeBackTrainingGrokCredential: (profile: string, candidate: string, journalFile: string) => Promise<boolean>;