@spacefast/common 0.0.13 → 0.0.17

package/dist/utils/local-space-state.js

@@ -1,6 +1,9 @@
-import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 import { z } from "zod";
+import { createOneShotReplayIdentity } from "./one-shot-replay.js";
+import { SecureLocalFileConflictError, secureReadFile, secureWriteFile, } from "./secure-local-file.js";
 export const LOCAL_SPACE_STATE_DIR_NAME = ".spacefast";
 export const LEGACY_LOCAL_SPACE_STATE_DIR_NAME = ".stattic";
 export const LOCAL_SPACE_LINK_FILE_NAME = "space.json";
@@ -15,8 +18,9 @@ export const LOCAL_SPACE_STATE_FILE_NAME = "state.json";
  * `.spacefast/state.json` is the local credential/cache axis: it records the
  * resolved `spaceId`, provider `apiUrl`, anonymous `claimToken` before claim,
  * durable `accessToken` after continuation, and small publish caches such as
- * `lastVersionId`. It is secret, machine-written, gitignored, and merge-written
- * so newer tools preserve unknown fields from older/newer tools.
+ * `lastVersionId`. It is secret, machine-written, gitignored, and merge-written.
+ * The strict versioned schema fails closed instead of letting an older tool
+ * reinterpret fields written under a contract it does not understand.
  */
 export const localSpaceLinkSchema = z
     .object({
@@ -25,8 +29,9 @@ export const localSpaceLinkSchema = z
     apiBaseUrl: z.string().min(1).optional(),
 })
     .loose();
-export const localSpaceStateSchema = z
-    .object({
+export const LOCAL_SPACE_STATE_SCHEMA_VERSION = 1;
+export const localSpaceStateSchema = z.strictObject({
+    schemaVersion: z.literal(LOCAL_SPACE_STATE_SCHEMA_VERSION),
     spaceId: z.string().min(1).optional(),
     apiUrl: z.string().min(1).optional(),
     teamSlug: z.string().min(1).optional(),
@@ -35,10 +40,56 @@ export const localSpaceStateSchema = z
     expiresAt: z.string().min(1).optional(),
     accessToken: z.string().min(1).optional(),
     lastVersionId: z.string().min(1).optional(),
+    pendingOperationId: z.string().min(1).optional(),
     lastVersionUrl: z.string().min(1).optional(),
     lastSpaceUrl: z.string().min(1).optional(),
-})
-    .loose();
+    /** Secret per-checkout entropy used only to namespace replay-safe first publishes. */
+    anonymousPublishNonce: z.string().min(32).optional(),
+    /** Unsettled first-publish mutation. Retries must reuse this exact key. */
+    pendingPublish: z
+        .object({
+        key: z.string().min(1),
+        principal: z.string().regex(/^[0-9a-f]{64}$/),
+        kind: z.enum(["anonymous", "authenticated"]),
+        intent: z.string().min(1).optional(),
+        createdAt: z.string().datetime(),
+    })
+        .strict()
+        .optional(),
+    /** Settled creation receipt identity retained for invocations that began before its commit. */
+    creationReplay: z
+        .object({
+        key: z.string().min(1),
+        principal: z.string().regex(/^[0-9a-f]{64}$/),
+        kind: z.enum(["anonymous", "authenticated"]),
+        intent: z.string().min(1).optional(),
+        createdAt: z.string().datetime(),
+    })
+        .strict()
+        .optional(),
+    /** Random replay capability reserved before consuming a claim credential. */
+    pendingCredentialReplay: z
+        .object({
+        operation: z.enum(["claim-rotate", "claim-exchange"]),
+        credentialFingerprint: z.string().regex(/^[0-9a-f]{64}$/),
+        key: z.string().min(1),
+        principal: z.string().regex(/^[0-9a-f]{64}$/),
+        createdAt: z.string().datetime(),
+    })
+        .strict()
+        .optional(),
+});
+export class LocalSpaceStateConflictError extends Error {
+    name = "LocalSpaceStateConflictError";
+}
+export class LocalSpaceStateError extends Error {
+    path;
+    constructor(filePath, cause) {
+        super(`Checkout state at ${filePath} is invalid or unreadable. Spacefast refuses to guess. Fix or remove the file, then re-link with \`sf link\`.${cause instanceof Error ? ` ${cause.message}` : ""}`, cause === undefined ? undefined : { cause });
+        this.name = "LocalSpaceStateError";
+        this.path = filePath;
+    }
+}
 export function localSpaceStateDir(root) {
     return path.join(root, LOCAL_SPACE_STATE_DIR_NAME);
 }
@@ -48,27 +99,53 @@ export function localSpaceStatePath(root) {
 export function localSpaceLinkPath(root) {
     return path.join(localSpaceStateDir(root), LOCAL_SPACE_LINK_FILE_NAME);
 }
-function legacyStatePath(root) {
-    return path.join(root, LEGACY_LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_STATE_FILE_NAME);
-}
 function legacyLinkPath(root) {
     return path.join(root, LEGACY_LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME);
 }
-async function readJsonFile(filePath) {
-    const raw = await readFile(filePath, "utf8").catch(() => undefined);
+async function readJsonFileWithRaw(root, relativePath) {
+    const raw = await secureReadFile({ root, relativePath, encoding: "utf8" }).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
     if (raw === undefined)
         return undefined;
     try {
-        return JSON.parse(raw);
+        return { raw, value: JSON.parse(raw) };
     }
     catch {
-        return undefined;
+        return { raw, value: undefined };
     }
 }
+async function readJsonFile(root, relativePath) {
+    return (await readJsonFileWithRaw(root, relativePath))?.value;
+}
 function parseState(value) {
     const parsed = localSpaceStateSchema.safeParse(value);
     return parsed.success ? parsed.data : null;
 }
+async function readStateFileAttempt(root, relativePath, attempt) {
+    let file;
+    try {
+        file = await readJsonFileWithRaw(root, relativePath);
+    }
+    catch (error) {
+        if (error instanceof SecureLocalFileConflictError && attempt < LOCAL_STATE_MUTATION_ATTEMPTS) {
+            await waitForMutationRetry(attempt);
+            return readStateFileAttempt(root, relativePath, attempt + 1);
+        }
+        throw new LocalSpaceStateError(path.join(root, relativePath), error);
+    }
+    if (!file)
+        return undefined;
+    const state = parseState(file.value);
+    if (!state)
+        throw new LocalSpaceStateError(path.join(root, relativePath));
+    return { raw: file.raw, state };
+}
+async function readStateFile(root, relativePath) {
+    return readStateFileAttempt(root, relativePath, 1);
+}
 function parseLink(value) {
     const parsed = localSpaceLinkSchema.safeParse(value);
     return parsed.success ? parsed.data : null;
@@ -84,21 +161,29 @@ export async function readLocalSpaceLink(root) {
  * legacy `.stattic/space.json` path to users so migrations stay visible.
  */
 export async function readLocalSpaceLinkWithPath(root) {
-    const primary = parseLink(await readJsonFile(localSpaceLinkPath(root)));
+    const primary = parseLink(await readJsonFile(root, path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME)));
     if (primary) {
         return { link: primary, path: localSpaceLinkPath(root) };
     }
-    const legacy = parseLink(await readJsonFile(legacyLinkPath(root)));
+    const legacy = parseLink(await readJsonFile(root, path.join(LEGACY_LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME)));
     return legacy ? { link: legacy, path: legacyLinkPath(root) } : null;
 }
 export async function readLocalSpaceStateAt(root) {
     const statePath = localSpaceStatePath(root);
-    const state = parseState(await readJsonFile(statePath)) ??
-        parseState(await readJsonFile(legacyStatePath(root)));
+    const primaryState = await readStateFile(root, path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_STATE_FILE_NAME));
+    const legacyState = primaryState
+        ? undefined
+        : await readStateFile(root, path.join(LEGACY_LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_STATE_FILE_NAME));
+    const state = primaryState?.state ?? legacyState?.state ?? null;
     const linkPath = localSpaceLinkPath(root);
-    const link = parseLink(await readJsonFile(linkPath)) ?? parseLink(await readJsonFile(legacyLinkPath(root)));
+    const link = parseLink(await readJsonFile(root, path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME))) ??
+        parseLink(await readJsonFile(root, path.join(LEGACY_LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME)));
     if (!state && !link)
         return null;
+    const committedSpaceId = linkSpaceId(link);
+    if (state?.spaceId && committedSpaceId && state.spaceId !== committedSpaceId) {
+        throw new LocalSpaceStateError(statePath, new Error(`The committed link selects ${committedSpaceId}, but secret state belongs to ${state.spaceId}.`));
+    }
     return {
         root,
         statePath: state ? statePath : null,
@@ -112,6 +197,7 @@ export async function readLocalSpaceStateAt(root) {
         claimUrl: state?.claimUrl,
         expiresAt: state?.expiresAt,
         lastVersionId: state?.lastVersionId,
+        pendingOperationId: state?.pendingOperationId,
     };
 }
 function isWithinBoundary(current, boundary) {
@@ -148,36 +234,68 @@ export async function findUpward(probe, startDir = process.cwd(), boundary) {
 export async function discoverLocalSpaceState(startDir = process.cwd(), boundary) {
     return findUpward(readLocalSpaceStateAt, startDir, boundary);
 }
-async function writeJsonAtomic(filePath, value, mode) {
-    await mkdir(path.dirname(filePath), { recursive: true });
-    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
-    try {
-        await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, {
-            encoding: "utf8",
-            ...(mode ? { mode } : {}),
-        });
-        if (mode) {
-            await chmod(tempPath, mode).catch(() => undefined);
+async function writeJsonAtomic(input) {
+    await secureWriteFile({
+        root: input.root,
+        relativePath: input.relativePath,
+        data: `${JSON.stringify(input.value, null, 2)}\n`,
+        overwrite: true,
+        mode: input.mode ?? 0o644,
+        ...(input.expectedContent === undefined ? {} : { expectedContent: input.expectedContent }),
+        ...(input.beforeCommit ? { beforeCommit: input.beforeCommit } : {}),
+        ...(input.afterBackup ? { afterBackup: input.afterBackup } : {}),
+    });
+}
+const LOCAL_STATE_MUTATION_ATTEMPTS = 250;
+async function waitForMutationRetry(attempt) {
+    await delay(Math.min(10, Math.max(1, attempt)));
+}
+async function ensureStateGitignored(root, onConflict) {
+    const entries = [
+        `${LOCAL_SPACE_STATE_DIR_NAME}/${LOCAL_SPACE_STATE_FILE_NAME}`,
+        `/.spacefast-*`,
+        `${LOCAL_SPACE_STATE_DIR_NAME}/.spacefast-*`,
+        `${LOCAL_SPACE_STATE_DIR_NAME}/.space-link-*.tmp`,
+    ];
+    /* eslint-disable no-await-in-loop -- each optimistic write retry must re-read the latest file before deciding whether another attempt is safe. */
+    for (let attempt = 1; attempt <= LOCAL_STATE_MUTATION_ATTEMPTS; attempt += 1) {
+        try {
+            const existing = await secureReadFile({
+                root,
+                relativePath: ".gitignore",
+                encoding: "utf8",
+            }).catch((error) => {
+                if (error.code === "ENOENT")
+                    return null;
+                throw error;
+            });
+            const raw = existing ?? "";
+            const lines = raw.split(/\r?\n/);
+            const missing = entries.filter((entry) => !lines.includes(entry));
+            if (missing.length === 0)
+                return;
+            const prefix = raw.length > 0 && !raw.endsWith("\n") ? "\n" : "";
+            await secureWriteFile({
+                root,
+                relativePath: ".gitignore",
+                data: `${raw}${prefix}${missing.join("\n")}\n`,
+                overwrite: existing !== null,
+                mode: 0o644,
+                expectedContent: existing,
+            });
+            return;
         }
-        await rename(tempPath, filePath);
-        if (mode) {
-            await chmod(filePath, mode).catch(() => undefined);
+        catch (error) {
+            if (error instanceof SecureLocalFileConflictError)
+                await onConflict?.();
+            if (!(error instanceof SecureLocalFileConflictError) ||
+                attempt === LOCAL_STATE_MUTATION_ATTEMPTS) {
+                throw error;
+            }
+            await waitForMutationRetry(attempt);
         }
     }
-    catch (error) {
-        await rm(tempPath, { force: true }).catch(() => undefined);
-        throw error;
-    }
-}
-async function ensureStateGitignored(root) {
-    const gitignorePath = path.join(root, ".gitignore");
-    const entry = `${LOCAL_SPACE_STATE_DIR_NAME}/${LOCAL_SPACE_STATE_FILE_NAME}`;
-    const raw = await readFile(gitignorePath, "utf8").catch(() => "");
-    const lines = raw.split(/\r?\n/);
-    if (lines.includes(entry))
-        return;
-    const prefix = raw.length > 0 && !raw.endsWith("\n") ? "\n" : "";
-    await writeFile(gitignorePath, `${raw}${prefix}${entry}\n`, "utf8");
+    /* eslint-enable no-await-in-loop */
 }
 function assignDefined(target, input) {
     for (const [key, value] of Object.entries(input)) {
@@ -203,50 +321,233 @@ export async function writeLocalSpaceLink(root, link) {
         ...(link.team ? { team: link.team } : {}),
         ...(link.apiBaseUrl ? { apiBaseUrl: link.apiBaseUrl } : {}),
     });
-    await writeJsonAtomic(filePath, payload);
+    await writeJsonAtomic({
+        root,
+        relativePath: path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME),
+        value: payload,
+    });
     return filePath;
 }
+export async function mutateLocalSpaceState(root, mutate, options = {}) {
+    const stateRelativePath = path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_STATE_FILE_NAME);
+    await ensureStateGitignored(root, options.onConflict);
+    /* eslint-disable no-await-in-loop -- compare-and-swap retries are intentionally serialized against the latest committed state. */
+    for (let attempt = 1; attempt <= LOCAL_STATE_MUTATION_ATTEMPTS; attempt += 1) {
+        try {
+            const primaryState = await readJsonFileWithRaw(root, stateRelativePath);
+            const legacyState = primaryState
+                ? undefined
+                : await readJsonFileWithRaw(root, path.join(LEGACY_LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_STATE_FILE_NAME));
+            const source = primaryState ?? legacyState;
+            const parsed = source ? localSpaceStateSchema.safeParse(source.value) : null;
+            if (source && !parsed?.success) {
+                throw new Error(`Local Spacefast state at ${localSpaceStatePath(root)} is invalid.`);
+            }
+            const current = parsed?.success
+                ? parsed.data
+                : { schemaVersion: LOCAL_SPACE_STATE_SCHEMA_VERSION };
+            // The callback may run again after a compare-and-swap collision. Keeping it
+            // synchronous makes remote effects and other one-shot work impossible here.
+            const payload = localSpaceStateSchema.parse({
+                ...mutate(structuredClone(current)),
+                schemaVersion: LOCAL_SPACE_STATE_SCHEMA_VERSION,
+            });
+            const serialized = `${JSON.stringify(payload, null, 2)}\n`;
+            if (primaryState?.raw === serialized)
+                return payload;
+            await writeJsonAtomic({
+                root,
+                relativePath: stateRelativePath,
+                value: payload,
+                mode: 0o600,
+                expectedContent: primaryState?.raw ?? null,
+                ...(options.beforeCommit ? { beforeCommit: options.beforeCommit } : {}),
+                ...(options.afterBackup ? { afterBackup: options.afterBackup } : {}),
+            });
+            return payload;
+        }
+        catch (error) {
+            if (error instanceof SecureLocalFileConflictError)
+                await options.onConflict?.();
+            if (!(error instanceof SecureLocalFileConflictError) ||
+                attempt === LOCAL_STATE_MUTATION_ATTEMPTS) {
+                throw error;
+            }
+            await waitForMutationRetry(attempt);
+        }
+    }
+    /* eslint-enable no-await-in-loop */
+    throw new LocalSpaceStateConflictError("Local Spacefast state stayed busy for too long.");
+}
 export async function writeLocalSpaceState(root, state) {
-    const filePath = localSpaceStatePath(root);
-    const payload = localSpaceStateSchema.parse(state);
-    await writeJsonAtomic(filePath, payload, 0o600);
-    await ensureStateGitignored(root);
-    return filePath;
+    await mutateLocalSpaceState(root, () => state);
+    return localSpaceStatePath(root);
 }
-export async function saveLocalSpaceState(root, input) {
-    const existing = parseState(await readJsonFile(localSpaceStatePath(root))) ??
-        parseState(await readJsonFile(legacyStatePath(root))) ??
-        {};
-    const next = { ...existing };
-    assignPresent(next, {
-        spaceId: input.spaceId,
-        apiUrl: input.apiUrl,
-        teamSlug: input.teamSlug,
-        lastVersionId: input.lastVersionId,
-        lastVersionUrl: input.lastVersionUrl,
-        lastSpaceUrl: input.lastSpaceUrl,
+function credentialFingerprint(credential) {
+    return createHash("sha256").update(credential).digest("hex");
+}
+function sameCredentialReplay(left, right) {
+    return (left?.operation === right.operation &&
+        left.credentialFingerprint === right.credentialFingerprint &&
+        left.key === right.key &&
+        left.principal === right.principal);
+}
+/** Reserve random replay custody before a claim token can be consumed. */
+export async function reserveLocalCredentialReplay(root, input) {
+    const identity = createOneShotReplayIdentity(`sf-${input.operation}`);
+    const candidate = {
+        operation: input.operation,
+        credentialFingerprint: credentialFingerprint(input.claimToken),
+        ...identity,
+        createdAt: new Date().toISOString(),
+    };
+    let reserved = candidate;
+    await mutateLocalSpaceState(root, (current) => {
+        if (current.claimToken !== input.claimToken) {
+            const mayReserveExplicitCredential = input.allowUnstoredClaimToken && !current.claimToken && !current.accessToken;
+            if (!mayReserveExplicitCredential) {
+                throw new LocalSpaceStateConflictError("The checkout claim credential changed before Spacefast reserved its replay identity.");
+            }
+        }
+        const existing = current.pendingCredentialReplay;
+        if (existing) {
+            if (existing.operation === candidate.operation &&
+                existing.credentialFingerprint === candidate.credentialFingerprint) {
+                reserved = existing;
+                return current;
+            }
+            throw new LocalSpaceStateConflictError("Another checkout credential transition is still unresolved.");
+        }
+        return { ...current, pendingCredentialReplay: candidate };
     });
-    if (input.accessToken) {
-        assignDefined(next, {
-            accessToken: input.accessToken,
-            claimToken: undefined,
-            claimUrl: undefined,
-            expiresAt: undefined,
+    return reserved;
+}
+function credentialMatches(state, expected) {
+    return state.claimToken === expected.claimToken && state.accessToken === expected.accessToken;
+}
+export async function saveLocalSpaceState(root, input) {
+    await mutateLocalSpaceState(root, (existing) => {
+        if (existing.spaceId && existing.spaceId !== input.spaceId && !input.replaceSpace) {
+            throw new LocalSpaceStateConflictError(`Local Spacefast state changed from ${input.spaceId} to ${existing.spaceId}.`);
+        }
+        const replacingSpace = input.replaceSpace && existing.spaceId !== input.spaceId;
+        const credentialBase = replacingSpace
+            ? { schemaVersion: LOCAL_SPACE_STATE_SCHEMA_VERSION }
+            : existing;
+        const next = { ...existing };
+        if (replacingSpace) {
+            for (const key of [
+                "spaceId",
+                "apiUrl",
+                "teamSlug",
+                "claimToken",
+                "claimUrl",
+                "expiresAt",
+                "accessToken",
+                "lastVersionId",
+                "pendingOperationId",
+                "lastVersionUrl",
+                "lastSpaceUrl",
+                "pendingPublish",
+                "pendingCredentialReplay",
+            ]) {
+                delete next[key];
+            }
+        }
+        assignPresent(next, {
+            spaceId: input.spaceId,
+            apiUrl: input.apiUrl,
+            teamSlug: input.teamSlug,
+            lastVersionId: input.lastVersionId,
+            pendingOperationId: input.pendingOperationId,
+            lastVersionUrl: input.lastVersionUrl,
+            lastSpaceUrl: input.lastSpaceUrl,
         });
+        const transitionAlreadyApplied = (input.accessToken !== undefined && credentialBase.accessToken === input.accessToken) ||
+            (input.claimToken !== undefined && credentialBase.claimToken === input.claimToken);
+        if (input.credentialReplay &&
+            !sameCredentialReplay(credentialBase.pendingCredentialReplay, input.credentialReplay) &&
+            !transitionAlreadyApplied) {
+            throw new LocalSpaceStateConflictError("The checkout replay reservation changed while Spacefast was saving its replacement.");
+        }
+        if (input.expectedCredential &&
+            !credentialMatches(credentialBase, input.expectedCredential) &&
+            !transitionAlreadyApplied) {
+            throw new LocalSpaceStateConflictError("The checkout credential changed while Spacefast was saving its replacement.");
+        }
+        const maySetCredential = input.expectedCredential
+            ? credentialMatches(credentialBase, input.expectedCredential) || transitionAlreadyApplied
+            : !credentialBase.claimToken && !credentialBase.accessToken;
+        let credentialTransitionCommitted = false;
+        if (input.accessToken &&
+            (maySetCredential || credentialBase.accessToken === input.accessToken)) {
+            assignDefined(next, {
+                accessToken: input.accessToken,
+                claimToken: undefined,
+                claimUrl: undefined,
+                expiresAt: undefined,
+            });
+            credentialTransitionCommitted = true;
+        }
+        else if (input.claimToken &&
+            (maySetCredential || credentialBase.claimToken === input.claimToken)) {
+            assignDefined(next, {
+                claimToken: input.claimToken,
+                claimUrl: input.claimUrl,
+                expiresAt: input.expiresAt,
+                accessToken: undefined,
+            });
+            credentialTransitionCommitted = true;
+        }
+        if (input.credentialReplay && credentialTransitionCommitted) {
+            delete next.pendingCredentialReplay;
+        }
+        return localSpaceStateSchema.parse(next);
+    });
+    const statePath = localSpaceStatePath(root);
+    const linkRelativePath = path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME);
+    const desiredLink = localSpaceLinkSchema.parse({
+        space: input.spaceId,
+        apiBaseUrl: input.apiUrl,
+        ...(input.teamSlug ? { team: input.teamSlug } : {}),
+    });
+    const primaryLinkFile = await readJsonFileWithRaw(root, linkRelativePath);
+    const primaryLink = primaryLinkFile ? parseLink(primaryLinkFile.value) : null;
+    if (primaryLinkFile && !primaryLink) {
+        throw new LocalSpaceStateError(localSpaceLinkPath(root));
     }
-    else if (input.claimToken) {
-        assignDefined(next, {
-            claimToken: input.claimToken,
-            claimUrl: input.claimUrl,
-            expiresAt: input.expiresAt,
-            accessToken: undefined,
-        });
+    let wroteLink = false;
+    const mustWriteLink = !primaryLink || (input.replaceSpace && primaryLink.space !== input.spaceId);
+    if (mustWriteLink) {
+        if (!input.replaceSpace && !primaryLink) {
+            const inheritedLink = await readLocalSpaceLink(root);
+            if (inheritedLink && inheritedLink.space !== input.spaceId) {
+                throw new LocalSpaceStateConflictError(`The committed checkout link selects ${inheritedLink.space}, not ${input.spaceId}.`);
+            }
+            if (inheritedLink) {
+                return { statePath, linkPath: localSpaceLinkPath(root), wroteLink };
+            }
+        }
+        try {
+            await writeJsonAtomic({
+                root,
+                relativePath: linkRelativePath,
+                value: desiredLink,
+                expectedContent: primaryLinkFile?.raw ?? null,
+            });
+            wroteLink = true;
+        }
+        catch (error) {
+            if (!(error instanceof SecureLocalFileConflictError))
+                throw error;
+            const winner = await readLocalSpaceLink(root);
+            if (winner?.space !== input.spaceId) {
+                throw new LocalSpaceStateConflictError(`The committed checkout link changed before Spacefast could select ${input.spaceId}.`);
+            }
+        }
     }
-    const statePath = await writeLocalSpaceState(root, next);
-    const existingLink = await readLocalSpaceLink(root);
-    const wroteLink = !existingLink;
-    if (!existingLink) {
-        await writeLocalSpaceLink(root, { space: input.spaceId, apiBaseUrl: input.apiUrl });
+    else if (primaryLink.space !== input.spaceId) {
+        throw new LocalSpaceStateConflictError(`The committed checkout link selects ${primaryLink.space}, not ${input.spaceId}.`);
     }
     return { statePath, linkPath: localSpaceLinkPath(root), wroteLink };
 }

package/dist/utils/one-shot-replay.d.ts

@@ -0,0 +1,14 @@
+export type OneShotReplayIdentity = {
+    key: string;
+    principal: string;
+};
+/**
+ * Creates an unguessable capability for replaying one shown-once response.
+ *
+ * Neither value is derived from the credential consumed by the mutation. A
+ * caller holding only that old credential therefore cannot locate the stored
+ * response after the credential is revoked.
+ */
+export declare function createOneShotReplayIdentity(prefix: string): OneShotReplayIdentity;
+/** Production headers for one one-shot attempt (or one device-poll sequence). */
+export declare function oneShotReplayHeaders(identity: OneShotReplayIdentity, sequence?: number): Record<"idempotency-key" | "x-spacefast-idempotency-principal", string>;

package/dist/utils/one-shot-replay.js

@@ -0,0 +1,21 @@
+import { randomBytes } from "node:crypto";
+/**
+ * Creates an unguessable capability for replaying one shown-once response.
+ *
+ * Neither value is derived from the credential consumed by the mutation. A
+ * caller holding only that old credential therefore cannot locate the stored
+ * response after the credential is revoked.
+ */
+export function createOneShotReplayIdentity(prefix) {
+    return {
+        key: `${prefix}-${randomBytes(32).toString("hex")}`,
+        principal: randomBytes(32).toString("hex"),
+    };
+}
+/** Production headers for one one-shot attempt (or one device-poll sequence). */
+export function oneShotReplayHeaders(identity, sequence) {
+    return {
+        "idempotency-key": sequence === undefined ? identity.key : `${identity.key}-${sequence}`,
+        "x-spacefast-idempotency-principal": identity.principal,
+    };
+}

package/dist/utils/page-preview.d.ts

@@ -0,0 +1,7 @@
+/**
+ * One URL, one representation. A file's bare path always serves its bytes;
+ * the preview page is reachable only under this query flag.
+ */
+export declare const PAGE_PREVIEW_QUERY = "spacefast_view";
+/** The preview page for a file whose bytes live at `fileHref`. */
+export declare function previewPageHref(fileHref: string): string;

package/dist/utils/page-preview.js

@@ -0,0 +1,9 @@
+/**
+ * One URL, one representation. A file's bare path always serves its bytes;
+ * the preview page is reachable only under this query flag.
+ */
+export const PAGE_PREVIEW_QUERY = "spacefast_view";
+/** The preview page for a file whose bytes live at `fileHref`. */
+export function previewPageHref(fileHref) {
+    return `${fileHref}${fileHref.includes("?") ? "&" : "?"}${PAGE_PREVIEW_QUERY}=1`;
+}

package/dist/utils/pages.d.ts

@@ -1,4 +1,5 @@
 import { type CustomPageId, type SitePageId } from "../contracts/pages.js";
+export { PAGE_PREVIEW_QUERY, previewPageHref } from "./page-preview.js";
 export type PageTheme = {
     accent?: string | undefined;
     background?: string | undefined;
@@ -19,16 +20,6 @@ export type PagePreviewFile = {
     size?: string;
     mime?: string;
 };
-/**
- * One URL, one representation. A file's bare path always serves its bytes;
- * the preview page is reachable only under this query flag. The alternative —
- * negotiating on `Accept` at the bare path — depends on `Vary`, which the edge
- * ignores, so whichever client arrived first pinned that representation for
- * everyone (an `<img>` could poison the human's link for a year).
- */
-export declare const PAGE_PREVIEW_QUERY = "spacefast_view";
-/** The preview page for a file whose bytes live at `fileHref`. */
-export declare function previewPageHref(fileHref: string): string;
 export type PageExpansionContext = {
     page: SitePageId | "layout";
     theme?: PageTheme;
@@ -44,7 +35,7 @@ export type PageExpansionContext = {
 };
 export type PageDiagnostic = {
     severity: "warning" | "error";
-    code: "page_source_too_large" | "unknown_page_template" | "unknown_page_element" | "page_element_not_allowed" | "page_document_required" | "layout_missing_content" | "index_files_missing" | "page_indexable";
+    code: "page_source_too_large" | "unknown_page_template" | "unknown_page_element" | "page_element_not_allowed" | "page_document_required" | "layout_missing_content" | "index_files_missing" | "access_lanes_missing" | "access_csp_form_action_missing_self" | "page_indexable";
     message: string;
     path: string;
 };