primitive-admin 1.2.0-alpha.7 → 1.2.0-alpha.9

package/dist/src/lib/credentials-lock.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The cross-process lock and atomic replace every project-mode credentials
+ * write goes through (#4492).
+ *
+ * Several CLI processes write one credentials file — one agent per git
+ * worktree, all sharing the main worktree's login — so a write is a locked
+ * read-modify-write, and the file is replaced by a rename, never rewritten in
+ * place: a reader never sees a partial file.
+ *
+ * The lock is `credentials.json.lock`, created exclusively and holding its
+ * owner's token (`<pid>:<random>`). A lock older than {@link LOCK_STALE_MS}
+ * was left by a crashed process; a contender reclaims it by renaming it to a
+ * name of its own, which exactly one contender can do, and removes it only if
+ * it still holds the token it read — otherwise a live lock was moved, and it
+ * is put back unless another writer took the lock meanwhile. A holder proves,
+ * immediately before it commits, that it still owns the lock and that the file
+ * is still the version it read — a holder whose lock was moved away and put
+ * back may have missed another writer's commit in between — and releases only
+ * its own lock.
+ *
+ * Node has no advisory file lock, so one window remains: between a holder's
+ * checks and its rename, a contender that just misreclaimed that lock could
+ * let a third writer in. Every other interleaving ends in a failed write,
+ * never a lost update.
+ */
+/** A lock untouched for this long was left by a crashed process. */
+export declare const LOCK_STALE_MS = 10000;
+/** How long a writer waits for a held lock before it fails. */
+export declare const LOCK_WAIT_MS = 5000;
+/** The lock on a credentials directory, held by this process. */
+export interface CredentialsLock {
+    /** The lock file. */
+    readonly path: string;
+    /** This holder's token, the lock file's content while it holds it. */
+    readonly token: string;
+    /** Whether the lock file still holds this holder's token. */
+    ownsLock(): boolean;
+    /** Remove the lock if, and only if, this holder still owns it. Never throws. */
+    release(): void;
+}
+/** A write that could not take, or lost, the lock on a credentials file. */
+export declare class CredentialsLockedError extends Error {
+    constructor(lockPath: string);
+}
+/**
+ * Reclaim the stale lock at `lockPath`, whose content was `seen` when it was
+ * judged stale: rename it to a name of `token`'s own, then remove it if it
+ * still holds `seen`, or put it back if it does not (a live writer took the
+ * lock in between). Gone already is not an error: another contender won.
+ */
+export declare function reclaimStaleLock(lockPath: string, token: string, seen: string): void;
+/**
+ * Put a live lock that a reclaimer moved to `moved` back at `lockPath` — but
+ * only if no other writer has taken the lock since, which a rename would
+ * silently replace. When one has, the displaced holder has lost the lock and
+ * fails its ownership check. The caller removes `moved` either way.
+ */
+export declare function restoreDisplacedLock(moved: string, lockPath: string): void;
+/**
+ * The version of the file at `path` as a writer read it: what an atomic
+ * replace changes (the inode) and what an in-place write changes (size and
+ * times). `"absent"` when there is no file.
+ */
+export declare function fileVersion(path: string): string;
+/**
+ * Take the lock on the credentials file in `dir`, waiting up to
+ * {@link LOCK_WAIT_MS} for another writer and reclaiming a stale lock. Throws
+ * {@link CredentialsLockedError} naming the lock when it stays held.
+ */
+export declare function acquireCredentialsLock(dir: string): CredentialsLock;
+/**
+ * Replace `path` with `content` while `lock` is held: write a private
+ * temporary file beside it, check the lock is still this holder's and, when
+ * `readVersion` is given, that `path` is still the {@link fileVersion} the
+ * holder read under the lock, then rename the temporary file over `path`. A
+ * holder that lost the lock, or whose read another writer's commit has
+ * overtaken, removes its temporary file and throws
+ * {@link CredentialsLockedError}, leaving `path` as it was.
+ */
+export declare function replaceFileUnderLock(lock: CredentialsLock, path: string, content: string, readVersion?: string): void;

package/dist/src/lib/credentials-lock.js

@@ -0,0 +1,222 @@
+/**
+ * The cross-process lock and atomic replace every project-mode credentials
+ * write goes through (#4492).
+ *
+ * Several CLI processes write one credentials file — one agent per git
+ * worktree, all sharing the main worktree's login — so a write is a locked
+ * read-modify-write, and the file is replaced by a rename, never rewritten in
+ * place: a reader never sees a partial file.
+ *
+ * The lock is `credentials.json.lock`, created exclusively and holding its
+ * owner's token (`<pid>:<random>`). A lock older than {@link LOCK_STALE_MS}
+ * was left by a crashed process; a contender reclaims it by renaming it to a
+ * name of its own, which exactly one contender can do, and removes it only if
+ * it still holds the token it read — otherwise a live lock was moved, and it
+ * is put back unless another writer took the lock meanwhile. A holder proves,
+ * immediately before it commits, that it still owns the lock and that the file
+ * is still the version it read — a holder whose lock was moved away and put
+ * back may have missed another writer's commit in between — and releases only
+ * its own lock.
+ *
+ * Node has no advisory file lock, so one window remains: between a holder's
+ * checks and its rename, a contender that just misreclaimed that lock could
+ * let a third writer in. Every other interleaving ends in a failed write,
+ * never a lost update.
+ */
+import { randomBytes } from "crypto";
+import { chmodSync, linkSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "fs";
+import { basename, dirname, join } from "path";
+/** A lock untouched for this long was left by a crashed process. */
+export const LOCK_STALE_MS = 10_000;
+/** How long a writer waits for a held lock before it fails. */
+export const LOCK_WAIT_MS = 5_000;
+const RETRY_MS = 25;
+const LOCKED_FILE = "credentials.json";
+/** A write that could not take, or lost, the lock on a credentials file. */
+export class CredentialsLockedError extends Error {
+    constructor(lockPath) {
+        super(`credentials file is locked: ${lockPath}`);
+        this.name = "CredentialsLockedError";
+    }
+}
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+const isMissing = (err) => err?.code === "ENOENT";
+/**
+ * Reclaim the stale lock at `lockPath`, whose content was `seen` when it was
+ * judged stale: rename it to a name of `token`'s own, then remove it if it
+ * still holds `seen`, or put it back if it does not (a live writer took the
+ * lock in between). Gone already is not an error: another contender won.
+ */
+export function reclaimStaleLock(lockPath, token, seen) {
+    const moved = `${lockPath}.stale.${token}`;
+    try {
+        renameSync(lockPath, moved);
+    }
+    catch (err) {
+        if (isMissing(err))
+            return;
+        throw err;
+    }
+    let content;
+    try {
+        content = readFileSync(moved, "utf-8");
+    }
+    catch {
+        return;
+    }
+    if (content !== seen)
+        restoreDisplacedLock(moved, lockPath);
+    try {
+        unlinkSync(moved);
+    }
+    catch {
+        // Swept by the next release.
+    }
+}
+/**
+ * Put a live lock that a reclaimer moved to `moved` back at `lockPath` — but
+ * only if no other writer has taken the lock since, which a rename would
+ * silently replace. When one has, the displaced holder has lost the lock and
+ * fails its ownership check. The caller removes `moved` either way.
+ */
+export function restoreDisplacedLock(moved, lockPath) {
+    try {
+        linkSync(moved, lockPath);
+    }
+    catch {
+        // Taken by another writer, or no hard links here: the displaced holder
+        // has lost the lock.
+    }
+}
+/**
+ * The version of the file at `path` as a writer read it: what an atomic
+ * replace changes (the inode) and what an in-place write changes (size and
+ * times). `"absent"` when there is no file.
+ */
+export function fileVersion(path) {
+    try {
+        const s = statSync(path);
+        return `${s.dev}:${s.ino}:${s.size}:${s.mtimeMs}:${s.ctimeMs}`;
+    }
+    catch (err) {
+        if (isMissing(err))
+            return "absent";
+        throw err;
+    }
+}
+/** Remove what crashed writers left in `dir`: old reclaimed locks and temp files. */
+function sweep(dir) {
+    try {
+        for (const name of readdirSync(dir)) {
+            if (!name.startsWith(`${LOCKED_FILE}.lock.stale.`) && !(name.startsWith(`${LOCKED_FILE}.`) && name.endsWith(".tmp"))) {
+                continue;
+            }
+            const path = join(dir, name);
+            if (Date.now() - statSync(path).mtimeMs > LOCK_STALE_MS)
+                unlinkSync(path);
+        }
+    }
+    catch {
+        // Best effort.
+    }
+}
+/**
+ * Take the lock on the credentials file in `dir`, waiting up to
+ * {@link LOCK_WAIT_MS} for another writer and reclaiming a stale lock. Throws
+ * {@link CredentialsLockedError} naming the lock when it stays held.
+ */
+export function acquireCredentialsLock(dir) {
+    const path = join(dir, `${LOCKED_FILE}.lock`);
+    const token = `${process.pid}:${randomBytes(8).toString("hex")}`;
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            writeFileSync(path, token, { flag: "wx", mode: 0o600 });
+            break;
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                throw err;
+        }
+        let held;
+        let seen;
+        try {
+            held = statSync(path);
+            seen = readFileSync(path, "utf-8");
+        }
+        catch (err) {
+            if (isMissing(err))
+                continue;
+            throw err;
+        }
+        if (Date.now() - held.mtimeMs > LOCK_STALE_MS) {
+            reclaimStaleLock(path, token, seen);
+            continue;
+        }
+        if (Date.now() >= deadline)
+            throw new CredentialsLockedError(path);
+        sleep(RETRY_MS);
+    }
+    const ownsLock = () => {
+        try {
+            return readFileSync(path, "utf-8") === token;
+        }
+        catch {
+            return false;
+        }
+    };
+    return {
+        path,
+        token,
+        ownsLock,
+        release() {
+            try {
+                if (ownsLock())
+                    unlinkSync(path);
+            }
+            catch {
+                // Already gone.
+            }
+            sweep(dir);
+        },
+    };
+}
+/**
+ * Replace `path` with `content` while `lock` is held: write a private
+ * temporary file beside it, check the lock is still this holder's and, when
+ * `readVersion` is given, that `path` is still the {@link fileVersion} the
+ * holder read under the lock, then rename the temporary file over `path`. A
+ * holder that lost the lock, or whose read another writer's commit has
+ * overtaken, removes its temporary file and throws
+ * {@link CredentialsLockedError}, leaving `path` as it was.
+ */
+export function replaceFileUnderLock(lock, path, content, readVersion) {
+    const tmp = join(dirname(path), `${basename(path)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    writeFileSync(tmp, content, { mode: 0o600 });
+    try {
+        if (!lock.ownsLock())
+            throw new CredentialsLockedError(lock.path);
+        if (readVersion !== undefined && fileVersion(path) !== readVersion) {
+            throw new CredentialsLockedError(lock.path);
+        }
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // Never written, or already renamed.
+        }
+        throw err;
+    }
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Best-effort on Windows / unusual filesystems.
+    }
+}
+//# sourceMappingURL=credentials-lock.js.map

package/dist/src/lib/credentials-lock.js.map

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

package/dist/src/lib/credentials-store.d.ts

@@ -42,6 +42,21 @@
  * the committed environment whose tree it shares — has no slot of its own: it
  * reads and writes its parent's, so one login and one logout cover the parent
  * and all of its children.
+ *
+ * A slot records the server that issued it (#4492). A slot is keyed by
+ * environment name while the environment's `apiUrl` is committed, so a branch
+ * switch can point `dev` at another server than the one its stored tokens
+ * came from. A slot recording another server than the invoking environment's
+ * is never used (its tokens are not sent), and credentials from another server
+ * than the slot's environment's are never stored. A slot written before this
+ * records no server; it is read against the environment's `apiUrl`, and its
+ * next write records one.
+ *
+ * In a linked git worktree the project's file is the main worktree's
+ * (#4492, `credentials-home.ts`), so one login serves every worktree of the
+ * repository that holds the project. Every project-mode write is a locked
+ * read-modify-write with an atomic replace (`credentials-lock.ts`), because
+ * several processes — one per worktree — write that one file.
  */
 import type { Credentials } from "../types/index.js";
 export declare const PROJECT_LOCAL_DIR = ".primitive";
@@ -53,6 +68,12 @@ export declare function isProjectMode(): boolean;
  * whether we're in project mode or legacy mode.
  */
 export declare function getCredentialsFilePath(): string;
+/**
+ * The credentials file of the project at `projectRoot`: its own
+ * `.primitive/credentials.json`, or in a linked git worktree the main
+ * worktree's for the same project (#4492).
+ */
+export declare function credentialsFileForProject(projectRoot: string): string;
 /**
  * Declare that THIS command may fall back to `~/.primitive/credentials.json`
  * when no project is in scope. Called at the top of `login`, `logout`, `init`
@@ -65,6 +86,12 @@ export declare function allowGlobalCredentials(): void;
  * boundary in one process, the way `resetEnvResolver()` does for the resolver.
  */
 export declare function resetGlobalCredentialsAllowance(): void;
+/**
+ * Whether two server URLs name the same server: scheme and host compare
+ * case-insensitively and the path with trailing slashes removed. A URL that
+ * does not parse compares as its trailing-slash-trimmed string.
+ */
+export declare function sameServer(a: string, b: string): boolean;
 /** The variable a CI job puts its admin token in (#3890). */
 export declare const PRIMITIVE_TOKEN_VAR = "PRIMITIVE_TOKEN";
 /** The token in `PRIMITIVE_TOKEN`, or null when it is unset or blank. */
@@ -84,6 +111,13 @@ export declare function environmentToken(): string | null;
  * refusal: the environment is resolved first, exactly as for a stored login.
  */
 export declare function loadCredentialsStore(): Credentials | null;
+/**
+ * The current environment's stored login when its slot records another server
+ * than the environment's, blended with the server it RECORDS; null otherwise.
+ * For `logout` alone, which revokes such a login at the server that issued it
+ * and so never sends its tokens anywhere else.
+ */
+export declare function mismatchedLogin(): Credentials | null;
 /**
  * The environments that share the current environment's login (#4511): the
  * one whose slot holds it, and its child environments on this machine. Null
@@ -93,6 +127,21 @@ export declare function loginEnvironments(): {
     parent: string;
     children: string[];
 } | null;
+/**
+ * What a login, logout or not-logged-in refusal adds about a linked git
+ * worktree (#4492). Each is null when it has nothing to say: outside a
+ * project, and where the project's login is its own.
+ */
+export declare const worktreeLoginNotes: {
+    /** After a login stored in another worktree's file: where it went. */
+    storedElsewhere(): string | null;
+    /** After a logout of `slot`'s login, when more than one worktree uses it. */
+    sharedLogout(slot: string): string | null;
+    /** A linked worktree's own credentials file, which is never read. */
+    ignoredFile(): string | null;
+    /** After "not logged in", when git is why a linked worktree has no login. */
+    notLoggedIn(): string | null;
+};
 /**
  * The logins still held in the slots of the current login's child
  * environments: sessions signed in to a child before children used their
@@ -105,9 +154,10 @@ export declare function leftoverChildLogins(): Credentials[];
  * Saves credentials. In project mode, writes to the per-env slot in the
  * project credentials file. In legacy mode, writes the global file.
  *
- * The serverUrl on the incoming Credentials is used as-is for legacy
- * mode, and ignored in project mode (the env's apiUrl is canonical). In a
- * child environment the parent's slot is written (#4511).
+ * In project mode the slot records the incoming `serverUrl`, which must be
+ * the same server as the slot's environment's `apiUrl`: credentials from
+ * another server are refused with `server-mismatch` and nothing is written
+ * (#4492). In a child environment the parent's slot is written (#4511).
  */
 export declare function saveCredentialsStore(credentials: Credentials): void;
 /**
@@ -144,7 +194,9 @@ export declare function removeCredentialsSlotInProject(projectRoot: string, envN
  * Writes the credentials slot for the named environment in a specific
  * project's credentials file. Used by `primitive init` to carry the session
  * it just authenticated into the freshly scaffolded project, so the first
- * in-project CLI command works without a second `primitive login`.
+ * in-project CLI command works without a second `primitive login`. The slot
+ * records the credentials' server, which must be the named environment's
+ * `apiUrl` in the project's config (#4492).
  */
 export declare function seedCredentialsForEnvInProject(projectRoot: string, envName: string, credentials: Credentials): void;
 /**