primitive-admin 1.2.0-alpha.1 → 1.2.0-alpha.11

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

@@ -0,0 +1,302 @@
+/**
+ * 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 only while holding
+ * the reclaim guard (`credentials.json.lock.reclaim`), re-reading the lock's
+ * age and token under the guard from one open file, so a reclaimer never moves
+ * a lock another contender has just taken. The reclaim renames the lock to a
+ * name of its own and removes it only if it still holds the token it read —
+ * otherwise a live lock was moved (by a reclaimer without the guard), 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, closeSync, fstatSync, linkSync, openSync, 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. Only the contender holding the reclaim guard
+ * (`<lock>.reclaim`) reclaims, and it inspects the lock again under the guard:
+ * no other reclaimer can move the lock meanwhile, and no writer can create one
+ * while it exists, so the lock it inspects is the lock it removes. Without the
+ * guard, a contender that judged the old lock stale could move away the fresh
+ * lock another contender had just taken, and a third writer could take the
+ * lock before it was put back. A contender that does not get the guard returns
+ * and retries. Gone already is not an error: another contender won.
+ */
+export function reclaimStaleLock(lockPath, token, seen) {
+    const guard = `${lockPath}.reclaim`;
+    if (!takeReclaimGuard(guard, token))
+        return;
+    try {
+        let now;
+        try {
+            now = inspectLock(lockPath);
+        }
+        catch (err) {
+            if (isMissing(err))
+                return;
+            throw err;
+        }
+        if (now.seen !== seen || Date.now() - now.mtimeMs <= LOCK_STALE_MS)
+            return;
+        moveStaleLock(lockPath, token, seen);
+    }
+    finally {
+        try {
+            if (readFileSync(guard, "utf-8") === token)
+                unlinkSync(guard);
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+/**
+ * Take the reclaim guard at `guard` for `token`. A guard older than
+ * {@link LOCK_STALE_MS} was left by a reclaimer that crashed; it is removed so
+ * the next attempt can take it.
+ */
+function takeReclaimGuard(guard, token) {
+    try {
+        writeFileSync(guard, token, { flag: "wx", mode: 0o600 });
+        return true;
+    }
+    catch (err) {
+        if (err?.code !== "EEXIST")
+            throw err;
+    }
+    try {
+        if (Date.now() - statSync(guard).mtimeMs > LOCK_STALE_MS)
+            unlinkSync(guard);
+    }
+    catch {
+        // Released or removed meanwhile.
+    }
+    return false;
+}
+/**
+ * Rename the stale lock at `lockPath` 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: a reclaimer without the guard, such as an older
+ * CLI, can still interleave).
+ */
+function moveStaleLock(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.
+    }
+}
+/**
+ * The age and content of the lock at `path`, read through one open file so
+ * both describe the same lock. Read by path one after the other, another
+ * contender could reclaim the stale lock and take a fresh one in between: the
+ * age would be the stale lock's and the token the live one's, and reclaiming
+ * on that reading removes a live lock.
+ */
+function inspectLock(path) {
+    const fd = openSync(path, "r");
+    try {
+        return { mtimeMs: fstatSync(fd).mtimeMs, seen: readFileSync(fd, "utf-8") };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * 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;
+        try {
+            held = inspectLock(path);
+        }
+        catch (err) {
+            if (isMissing(err))
+                continue;
+            throw err;
+        }
+        const { seen } = held;
+        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

@@ -7,11 +7,13 @@
  *
  * Mode A (project mode): credentials live at
  *   <projectRoot>/.primitive/credentials.json
- * with per-environment slots:
+ * with one login per server (#4512), keyed by normalized server URL:
  *   {
- *     "environments": {
- *       "dev":  { "accessToken": "...", "refreshToken": "...", ... },
- *       "prod": { ... }
+ *     "servers": {
+ *       "https://api.example.com": {
+ *         "login": { "accessToken": "...", "refreshToken": "...", ... },
+ *         "leftovers": { "staging": { ... } }
+ *       }
  *     }
  *   }
  *
@@ -33,10 +35,40 @@
  * project either. The last two are the divergence from the intent's "login and
  * init and nothing else", adjudicated on #3154 as finding F1.
  *
+ * A fifth, `apps delete`, says it pinned to a server (#4905,
+ * `allowGlobalCredentialsForServer()`): the server `PRIMITIVE_SERVER_URL`
+ * names, or production when it is unset, as `login` resolves it. The global
+ * login is used only when that server issued it, so the command still never
+ * acts against whatever server the last `login` targeted.
+ *
  * The opt-in is per ACTION, not per argv: `primitive --env prod login` and
  * `primitive login` reach the same line, so there is no flag shape for a
  * pre-parse to miss. And it only PERMITS the global file — inside a project
- * all four still use the per-environment slots.
+ * all five still use the project's file.
+ *
+ * Every environment on a server — committed or machine-local — reads and
+ * writes that server's one login, so one login and one logout cover them all
+ * (#4512). A server's `leftovers` are logins an older CLI stored per
+ * environment: never read, revoked by `logout`.
+ *
+ * Before #4512 a login lived in a per-environment slot under `environments`,
+ * a child environment (#4511) using its parent's. Such a slot is read only
+ * while the file has no entry for its server. The first write for a server
+ * creates the entry and moves the server's legacy slots out: a mere copy of
+ * the login being written is dropped, any other becomes a leftover. From then
+ * on a cleared login stays cleared; no legacy slot is read for that server.
+ *
+ * A login records the server that issued it (#4492), and credentials from
+ * another server than the environment's are never stored. A legacy slot
+ * recording another server than the invoking environment's is never used (its
+ * tokens are not sent); a legacy slot that records no server is read against
+ * the environment's `apiUrl`.
+ *
+ * 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";
@@ -48,57 +80,180 @@ 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`
  * and `bootstrap`, and nowhere else.
  */
 export declare function allowGlobalCredentials(): void;
+/**
+ * Declare that THIS command may use the global credentials file when no
+ * project is in scope, but only for `serverUrl`: a stored login another server
+ * issued is refused with `server-mismatch` before any of its tokens is sent,
+ * credentials from another server are never written, and `PRIMITIVE_TOKEN` is
+ * sent to `serverUrl`. Called by `apps delete` (#4905), and nowhere else.
+ */
+export declare function allowGlobalCredentialsForServer(serverUrl: string): void;
 /**
  * Drop the declaration again. One invocation runs one command, so nothing in
  * the CLI calls this — it exists so a test file can exercise both sides of the
  * boundary in one process, the way `resetEnvResolver()` does for the resolver.
  */
 export declare function resetGlobalCredentialsAllowance(): void;
+/**
+ * The login command for the global login of `serverUrl`, up to its `--app`
+ * value: prefixed with `PRIMITIVE_SERVER_URL=<server>` unless the server is
+ * production, which `login` targets when the variable is unset.
+ */
+export declare function globalLoginCommand(serverUrl: string): string;
+/**
+ * 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 partition a login exchanges in when it builds on no stored login: the
+ * one `PRIMITIVE_GLOBAL_ADMIN_APP_ID` names, which only the live test harness
+ * sets. Deployed servers ignore the header for admin identity.
+ */
+export declare function partitionFromEnvironment(): string | undefined;
+/** The token in `PRIMITIVE_TOKEN`, or null when it is unset or blank. */
+export declare function environmentToken(): string | null;
 /**
  * Reads credentials for the current environment (project mode) or the
  * legacy global file. Returns the standard Credentials shape so existing
  * callers don't need to change.
  *
- * In project mode, we blend the per-env stored creds with the serverUrl
- * and appId from primitive/config.json to produce the Credentials the rest of
- * the CLI expects.
+ * In project mode, we blend the server's stored login with the serverUrl
+ * from primitive/config.json to produce the Credentials the rest of the CLI
+ * expects (#4512). Before the server's first write a legacy slot is read
+ * instead: the environment's own, or its parent's for a child environment
+ * (#4511), and any child slot found to be a copy of that login is removed.
+ *
+ * `PRIMITIVE_TOKEN` (#3890), when set, takes precedence over any stored
+ * login and no file is read. It does not loosen the outside-a-project
+ * refusal: the environment is resolved first, exactly as for a stored login.
+ *
+ * Outside a project under a server pin (#4905), the global login is returned
+ * only when the pinned server issued it, and `PRIMITIVE_TOKEN` is for the
+ * pinned server.
  */
 export declare function loadCredentialsStore(): Credentials | null;
 /**
- * Saves credentials. In project mode, writes to the per-env slot in the
- * project credentials file. In legacy mode, writes the global file.
+ * The current environment's legacy login when its slot records another server
+ * than the environment's, blended with the server it RECORDS; null otherwise,
+ * and always once the environment's server has a login entry (#4512). 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 (#4512): every
+ * environment of the project on its server, committed and machine-local, in
+ * config order; and the committed environment whose tree the current one
+ * uses, which names the login. Null outside a project, where there is one
+ * global login.
+ */
+export declare function loginEnvironments(): {
+    tree: string;
+    environments: 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 on the current environment's server that no command reads: the
+ * server's leftovers (#4512), or before its first write the legacy slots on
+ * it other than the one the environment reads — sessions signed in to another
+ * environment, and copies that kept a step-up or a refresh token of their own
+ * (#4511). `logout` revokes them before {@link clearLeftoverLogins} removes
+ * them. Empty outside a project.
+ */
+export declare function leftoverLogins(): Credentials[];
+/**
+ * Saves credentials. In project mode, writes the login of the environment's
+ * server (#4512), migrating the server's legacy slots at its first write. 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 project mode the login records the incoming `serverUrl`, which must be
+ * the same server as the environment's `apiUrl`: credentials from another
+ * server are refused with `server-mismatch` and nothing is written (#4492).
+ * In legacy mode under a server pin (#4905), so are credentials from another
+ * server than the pinned one.
  */
 export declare function saveCredentialsStore(credentials: Credentials): void;
 /**
  * Clears credentials for the current environment (project mode) or
- * deletes the legacy file (legacy mode).
+ * deletes the legacy file (legacy mode). In project mode that is the login of
+ * the environment's server; its entry and leftovers stay, so a legacy slot is
+ * never read for the server again (#4512). Before the server's first write it
+ * is the legacy slot the environment reads, and the child slots holding only
+ * that login's session (#4511), which its caller has just revoked. A slot
+ * holding another session or a step-up of its own stays for `logout` to
+ * revoke ({@link clearLeftoverLogins}).
  */
 export declare function clearCredentialsStore(): void;
 /**
- * Removes the credentials slot for the named environment in a specific
- * project's credentials file. Used by `env remove` so stale tokens from a
- * previously-removed environment can never be silently re-used if the same
- * name is later added back. Never throws.
+ * Removes the logins {@link leftoverLogins} returned, once `logout` has
+ * revoked them: the server's leftovers, or before its first write the other
+ * legacy slots on it. No-op outside a project.
+ */
+export declare function clearLeftoverLogins(): void;
+/**
+ * Removes what a removed environment leaves in a specific project's
+ * credentials file, so stale tokens from a previously-removed environment can
+ * never be silently re-used if the same name is later added back: a legacy
+ * slot or leftover of its name, and the login of the removed environment's
+ * server `removedApiUrl` when no remaining environment uses it (#4512). No
+ * other server's entry is touched: the file is shared by every worktree
+ * (#4492), and a server this worktree does not use may be another worktree's
+ * machine-local environment's. For the same reason the removed server's
+ * login stays while an environment of any worktree sharing the file uses it,
+ * or while that cannot be told. Used by `env remove`, after the environment
+ * left the config at `configPath`. Returns whether anything was removed.
+ * Never throws.
+ */
+export declare function clearCredentialsForEnvInProject(projectRoot: string, envName: string, configPath?: string, removedApiUrl?: string): boolean;
+/**
+ * Removes the legacy slot and the leftovers named `envName` in a specific
+ * project's credentials file; a server's login, which every environment on
+ * the server uses, is never one of them (#4512). Returns false when there was
+ * none; throws when there was one and the file could not be rewritten, so a
+ * caller that must not lose track of a login can tell the two apart.
  */
-export declare function clearCredentialsForEnvInProject(projectRoot: string, envName: string): void;
+export declare function removeCredentialsSlotInProject(projectRoot: string, envName: string): boolean;
 /**
- * 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
+ * Writes `credentials` as their server's login in a specific project's
+ * credentials file (#4512). 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`.
  */
-export declare function seedCredentialsForEnvInProject(projectRoot: string, envName: string, credentials: Credentials): void;
+export declare function seedCredentialsForServerInProject(projectRoot: string, credentials: Credentials): void;
 /**
- * Lists all environments that have stored credentials in project mode.
- * Returns an empty array in legacy mode.
+ * Lists the environments of the project that have a login to use: every
+ * environment on a server holding a login, and before a server's first write
+ * the environments with a legacy slot of their own. Returns an empty array in
+ * legacy mode.
  */
 export declare function listAuthenticatedEnvironments(): string[];