primitive-admin 1.2.0-alpha.0 → 1.2.0-alpha.10

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

@@ -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,16 +35,51 @@
  * 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 { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "fs";
 import { homedir } from "os";
-import { join } from "path";
-import { getCurrentEnvironment, getProjectConfig } from "./env-resolver.js";
-import { missingConfigMessage, PrimitiveEnvError } from "./env-resolver-core.js";
+import { dirname, join } from "path";
+import { getCurrentEnvironment, getProjectConfig, } from "./env-resolver.js";
+import { missingConfigMessage, PROJECT_CONFIG_FILENAME, PROJECT_TREE_DIR, PrimitiveEnvError, readLocalState, } from "./env-resolver-core.js";
+import { DEFAULT_SERVER_URL, PRODUCTION_SERVER_URL } from "./constants.js";
+import { normalizeServerUrl } from "./channel.js";
+import { credentialsRootFor, ignoredLocalCredentialsFile, oldGitHint, otherSharingProjectRoots, sharedWorktreeCount, } from "./credentials-home.js";
+import { acquireCredentialsLock, fileVersion, replaceFileUnderLock } from "./credentials-lock.js";
+import { sessionIdOfToken } from "./session-id.js";
 export const PROJECT_LOCAL_DIR = ".primitive";
 export const PROJECT_CREDENTIALS_FILENAME = "credentials.json";
 /**
@@ -86,17 +123,30 @@ export function isProjectMode() {
  */
 export function getCredentialsFilePath() {
     const env = resolveCurrentEnvironment();
-    if (env) {
-        return join(env.projectRoot, PROJECT_LOCAL_DIR, PROJECT_CREDENTIALS_FILENAME);
-    }
+    if (env)
+        return credentialsFileForProject(env.projectRoot);
     return getLegacyCredentialsFile();
 }
 /**
- * Set by the four actions that may read or write the global credentials file
+ * 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 function credentialsFileForProject(projectRoot) {
+    return join(credentialsRootFor(projectRoot), PROJECT_LOCAL_DIR, PROJECT_CREDENTIALS_FILENAME);
+}
+/**
+ * Set by the actions that may read or write the global credentials file
  * with no project in scope. Process-wide, because one invocation runs one
  * command; never reset, because a command does not stop being `login`.
  */
 let globalCredentialsAllowed = false;
+/**
+ * The server a pinned allowance names (#4905): the global login is used only
+ * when this server issued it, and only its credentials are written. Null for
+ * the unpinned allowance of the login family.
+ */
+let globalCredentialsServer = null;
 /**
  * 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`
@@ -105,6 +155,17 @@ let globalCredentialsAllowed = false;
 export function allowGlobalCredentials() {
     globalCredentialsAllowed = true;
 }
+/**
+ * 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 function allowGlobalCredentialsForServer(serverUrl) {
+    globalCredentialsAllowed = true;
+    globalCredentialsServer = trimSlash(serverUrl);
+}
 /**
  * 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
@@ -112,6 +173,25 @@ export function allowGlobalCredentials() {
  */
 export function resetGlobalCredentialsAllowance() {
     globalCredentialsAllowed = false;
+    globalCredentialsServer = null;
+}
+/**
+ * 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 function globalLoginCommand(serverUrl) {
+    const prefix = sameServer(serverUrl, PRODUCTION_SERVER_URL) ? "" : `PRIMITIVE_SERVER_URL=${serverUrl} `;
+    return `${prefix}primitive login --app`;
+}
+/** The refusal of a global login another server than the pinned one issued. */
+function globalReadMismatch(stored, pinned) {
+    const issuer = stored ?? "a server it does not record";
+    const target = stored ? ` To target ${stored}, set PRIMITIVE_SERVER_URL=${stored}.` : "";
+    return new PrimitiveEnvError("server-mismatch", `The login in ${getLegacyCredentialsFile()} was issued by ${issuer}, but this command targets ` +
+        `${pinned} (PRIMITIVE_SERVER_URL, or production when it is unset); its tokens were not sent.` +
+        `${target} To sign in to ${pinned}, run '${globalLoginCommand(pinned)} <app-id>' (or --app all); ` +
+        `it replaces the stored login.`);
 }
 /**
  * Resolves the current environment. If an environment CAN'T be resolved
@@ -169,6 +249,7 @@ function legacyCredentialsRecord(credentials) {
         role: credentials.role,
         name: credentials.name,
         globalAdminAppId: credentials.globalAdminAppId,
+        stepUp: credentials.stepUp,
     };
 }
 /**
@@ -176,28 +257,318 @@ function legacyCredentialsRecord(credentials) {
  * an empty shape when the file is missing or unreadable.
  */
 function loadProjectCredentialsFile(projectRoot) {
-    const path = join(projectRoot, PROJECT_LOCAL_DIR, PROJECT_CREDENTIALS_FILENAME);
+    const path = credentialsFileForProject(projectRoot);
     const data = readJsonFile(path);
-    if (!data || typeof data !== "object" || !data.environments) {
-        return { environments: {} };
-    }
+    const isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+    if (!isRecord(data))
+        return { environments: {}, servers: {} };
+    const file = {
+        environments: isRecord(data.environments) ? data.environments : {},
+        servers: isRecord(data.servers) ? data.servers : {},
+    };
     // EVERY slot, not just the one about to be written: each write reserializes
     // the whole file, so a stale key anywhere would survive forever.
-    for (const slot of Object.values(data.environments)) {
+    for (const slot of Object.values(file.environments)) {
         stripRetiredCurrentApp(slot);
     }
-    return data;
+    for (const entry of Object.values(file.servers)) {
+        stripRetiredCurrentApp(entry?.login);
+        for (const slot of Object.values(entry?.leftovers ?? {}))
+            stripRetiredCurrentApp(slot);
+    }
+    return file;
 }
-function writeProjectCredentialsFile(projectRoot, file) {
-    const dir = join(projectRoot, PROJECT_LOCAL_DIR);
+/**
+ * The one way a project's credentials file is written: take the lock, read
+ * the file, apply `mutate`, and — when it reports a change — replace the file
+ * atomically while still holding the lock. Throws when the lock stays held by
+ * another writer, or is lost or overtaken by another writer's commit before
+ * this one; the file is then unchanged.
+ */
+function updateProjectCredentialsFile(projectRoot, mutate) {
+    const path = credentialsFileForProject(projectRoot);
+    const dir = dirname(path);
     ensureDir(dir);
-    const path = join(dir, PROJECT_CREDENTIALS_FILENAME);
-    writeFileSync(path, JSON.stringify(file, null, 2), { mode: 0o600 });
+    const lock = acquireCredentialsLock(dir);
+    try {
+        const readVersion = fileVersion(path);
+        const file = loadProjectCredentialsFile(projectRoot);
+        if (mutate(file))
+            replaceFileUnderLock(lock, path, JSON.stringify(file, null, 2), readVersion);
+    }
+    finally {
+        lock.release();
+    }
+}
+const trimSlash = (url) => url.replace(/\/+$/, "");
+/**
+ * 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 function sameServer(a, b) {
+    try {
+        const x = new URL(a);
+        const y = new URL(b);
+        return (x.protocol.toLowerCase() === y.protocol.toLowerCase() &&
+            x.host.toLowerCase() === y.host.toLowerCase() &&
+            trimSlash(x.pathname) === trimSlash(y.pathname));
+    }
+    catch {
+        return trimSlash(a) === trimSlash(b);
+    }
+}
+/** The refusal of credentials issued by another server than the slot's environment's. */
+function writeMismatch(envName, incoming, configured) {
+    return new PrimitiveEnvError("server-mismatch", `These credentials were issued by ${incoming}, but the "${envName}" login is for ${configured}; ` +
+        `nothing was stored. Run 'primitive -e ${envName} login' to sign in to ${configured}, or run ` +
+        `this command outside a project or from an environment that points at ${incoming}.`);
+}
+/** Whether a stored slot records a server other than `apiUrl`. */
+function recordsOtherServer(stored, apiUrl) {
+    return stored.serverUrl !== undefined && !sameServer(stored.serverUrl, apiUrl);
+}
+/** The slot record for `credentials`, recording the server that issued them. */
+function storedRecord(credentials) {
+    return {
+        serverUrl: credentials.serverUrl,
+        accessToken: credentials.accessToken,
+        refreshToken: credentials.refreshToken,
+        expiresAt: credentials.expiresAt,
+        adminId: credentials.adminId,
+        email: credentials.email,
+        role: credentials.role,
+        name: credentials.name,
+        globalAdminAppId: credentials.globalAdminAppId,
+        stepUp: credentials.stepUp,
+    };
+}
+/**
+ * The slot holding `env`'s login (#4511). A child environment uses its
+ * parent's slot, and the children of a slot are the machine-local entries of
+ * its tree on its server. A machine-local entry on another server is not a
+ * child: a login for one server says nothing about another, so it keeps a slot
+ * of its own.
+ */
+function loginSlotOf(env) {
+    const own = { slot: env.name, children: [], serverUrl: env.config.apiUrl };
+    const project = getProjectConfig();
+    const parent = project?.environments[env.tree];
+    if (!project || !parent)
+        return own;
+    const onParentServer = (apiUrl) => sameServer(apiUrl, parent.apiUrl);
+    if (env.local && !onParentServer(env.config.apiUrl))
+        return own;
+    const children = Object.entries(readLocalState(env.projectConfigPath, project).environments)
+        .filter(([, entry]) => entry.tree === env.tree && onParentServer(entry.apiUrl))
+        .map(([name]) => name);
+    return { slot: env.tree, children, serverUrl: parent.apiUrl };
+}
+/** Whether two stored logins hold the same server session. */
+function sameSession(a, b) {
+    const sid = sessionIdOfToken(a.accessToken);
+    if (sid !== undefined)
+        return sid === sessionIdOfToken(b.accessToken);
+    return Boolean(a.accessToken) && a.accessToken === b.accessToken;
+}
+/** The expiry (`exp`, in seconds) a JWT carries, or undefined. */
+function expiryOfToken(token) {
+    if (!token)
+        return undefined;
     try {
-        chmodSync(path, 0o600);
+        const payload = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf-8"));
+        return typeof payload?.exp === "number" ? payload.exp : undefined;
     }
     catch {
-        // Best-effort on Windows / weird filesystems
+        return undefined;
+    }
+}
+/**
+ * Whether `slot`'s refresh token may outlive `login`'s: a copy refreshed in
+ * the child since it was made. It can still revoke the session after the
+ * parent's token has expired, so it is not thrown away unrevoked. Only an
+ * identical token, or one known to expire no later, is said not to.
+ */
+function outlivesRefresh(slot, login) {
+    if (slot.refreshToken === login.refreshToken)
+        return false;
+    const mine = expiryOfToken(slot.refreshToken);
+    const theirs = expiryOfToken(login.refreshToken);
+    return mine === undefined || theirs === undefined || mine > theirs;
+}
+/**
+ * Whether `slot` holds a live step-up `login` does not: one a `login --scope
+ * admin` in the child stored beside the copied login. A step-up is a session
+ * of its own, which revoking the login's does not end.
+ */
+function ownStepUp(slot, login) {
+    const stepUp = slot.stepUp;
+    if (!stepUp || new Date(stepUp.expiresAt).getTime() <= Date.now())
+        return false;
+    const sessionOf = (s) => s.sessionId || sessionIdOfToken(s.accessToken) || s.accessToken;
+    return !login.stepUp || sessionOf(stepUp) !== sessionOf(login.stepUp);
+}
+/**
+ * The child slots that are mere copies of `login`: written when a child was
+ * registered before children used their parent's login, holding its session
+ * and nothing a logout could still need. A child slot holding another
+ * session, a step-up of its own, or a refresh token that may outlive the
+ * parent's is not one: it stays (it is never read) until `logout` revokes it.
+ */
+function copiedChildSlots(file, login, children) {
+    return children.filter((name) => {
+        const slot = file.environments[name];
+        return (slot !== undefined &&
+            sameSession(slot, login) &&
+            !outlivesRefresh(slot, login) &&
+            !ownStepUp(slot, login));
+    });
+}
+/**
+ * Removes the {@link copiedChildSlots} of the login in `slot`, deciding again
+ * under the lock against the file as it is then. Best-effort, so a read never
+ * fails on a file it cannot rewrite or a lock it cannot take.
+ */
+function dropCopiedChildSlots(projectRoot, file, slot, children) {
+    const login = file.environments[slot];
+    if (!login || copiedChildSlots(file, login, children).length === 0)
+        return;
+    try {
+        updateProjectCredentialsFile(projectRoot, (current) => {
+            const currentLogin = current.environments[slot];
+            if (!currentLogin)
+                return false;
+            const copies = copiedChildSlots(current, currentLogin, children);
+            for (const name of copies)
+                delete current.environments[name];
+            return copies.length > 0;
+        });
+    }
+    catch {
+        // The copies are ignored either way; the next read tries again.
+    }
+}
+/**
+ * The key of `apiUrl`'s login in `servers` (#4512): scheme, host and port,
+ * and the path without trailing slashes. A URL that does not parse keys as
+ * its trailing-slash-trimmed string.
+ */
+function serverKey(apiUrl) {
+    return normalizeServerUrl(apiUrl) ?? trimSlash(apiUrl);
+}
+/**
+ * The server of every environment of the project whose config is at
+ * `configPath`, committed and machine-local, by name in config order. Null
+ * when the config cannot be read, so a caller never takes "no environment"
+ * for an answer it did not get.
+ */
+function environmentServers(configPath) {
+    const config = readJsonFile(configPath);
+    if (!config?.environments || typeof config.environments !== "object")
+        return null;
+    const servers = {};
+    for (const [name, entry] of Object.entries(config.environments)) {
+        if (typeof entry?.apiUrl === "string")
+            servers[name] = entry.apiUrl;
+    }
+    try {
+        for (const [name, entry] of Object.entries(readLocalState(configPath).environments)) {
+            if (!(name in servers))
+                servers[name] = entry.apiUrl;
+        }
+    }
+    catch {
+        // An unreadable local state names no machine-local environment.
+    }
+    return servers;
+}
+/** The project config of a project root, where `init` and `env remove` find it. */
+function configPathOf(projectRoot) {
+    return join(projectRoot, PROJECT_TREE_DIR, PROJECT_CONFIG_FILENAME);
+}
+/**
+ * The legacy slots of `file` that belong to `server`: one recording that
+ * server, and one named after an environment on it, whatever it records. The
+ * latter is the slot that environment read; one recording another server was
+ * never used there, and keeps its server so `logout` revokes it where it was
+ * issued.
+ */
+function legacySlotsOn(file, server, servers) {
+    const on = (apiUrl) => apiUrl !== undefined && serverKey(apiUrl) === server;
+    return Object.entries(file.environments)
+        .filter(([name, slot]) => on(slot.serverUrl) || on(servers?.[name]))
+        .map(([name]) => name);
+}
+/**
+ * Create `servers[server]` for the login about to be written, moving the
+ * server's legacy slots out of `environments`. A slot holding `login`'s
+ * session that nothing a logout needs is dropped (an identical or older
+ * refresh token, no live step-up of its own, #4511's rules); any other slot
+ * becomes a leftover. No-op once the server has an entry.
+ */
+function migrateServer(file, server, login, servers) {
+    const existing = file.servers[server];
+    if (existing)
+        return existing;
+    const leftovers = {};
+    for (const name of legacySlotsOn(file, server, servers)) {
+        const slot = file.environments[name];
+        const copy = sameSession(slot, login) && !outlivesRefresh(slot, login) && !ownStepUp(slot, login);
+        if (!copy)
+            leftovers[name] = slot;
+        delete file.environments[name];
+    }
+    const entry = Object.keys(leftovers).length > 0 ? { leftovers } : {};
+    file.servers[server] = entry;
+    return entry;
+}
+/** The variable a CI job puts its admin token in (#3890). */
+export const PRIMITIVE_TOKEN_VAR = "PRIMITIVE_TOKEN";
+/**
+ * The partition header the live test harness needs when no credentials file
+ * names one. Deployed servers ignore the header for admin identity.
+ */
+const PARTITION_VAR = "PRIMITIVE_GLOBAL_ADMIN_APP_ID";
+/**
+ * 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 function partitionFromEnvironment() {
+    return process.env[PARTITION_VAR]?.trim() || undefined;
+}
+/** The token in `PRIMITIVE_TOKEN`, or null when it is unset or blank. */
+export function environmentToken() {
+    const value = process.env[PRIMITIVE_TOKEN_VAR]?.trim();
+    return value ? value : null;
+}
+/**
+ * Credentials made from `PRIMITIVE_TOKEN` for `serverUrl` (#3890): the token
+ * verbatim (an opaque CI token or a JWT), no refresh token, an expiry far
+ * enough away that no refresh is ever attempted, and no identity, which the
+ * server answers for. Null when the variable is unset or blank.
+ */
+function environmentCredentials(serverUrl) {
+    const token = environmentToken();
+    if (!token)
+        return null;
+    const partition = process.env[PARTITION_VAR]?.trim();
+    return {
+        source: "env",
+        serverUrl,
+        accessToken: token,
+        refreshToken: "",
+        expiresAt: "9999-12-31T23:59:59.000Z",
+        adminId: "",
+        email: "",
+        role: "admin",
+        ...(partition ? { globalAdminAppId: partition } : {}),
+    };
+}
+/** Refuse to write credentials `PRIMITIVE_TOKEN` supplied. */
+function assertStorable(credentials) {
+    if (credentials.source === "env") {
+        throw new Error("Credentials from PRIMITIVE_TOKEN are never written to disk.");
     }
 }
 /**
@@ -205,21 +576,72 @@ function writeProjectCredentialsFile(projectRoot, file) {
  * 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 function loadCredentialsStore() {
     const env = resolveCurrentEnvironment();
+    const fromEnvironment = environmentCredentials(env ? env.config.apiUrl : globalCredentialsServer ?? DEFAULT_SERVER_URL.replace(/\/$/, ""));
+    if (fromEnvironment)
+        return fromEnvironment;
     if (!env) {
-        return loadLegacyCredentials();
+        const stored = loadLegacyCredentials();
+        if (stored &&
+            globalCredentialsServer !== null &&
+            (!stored.serverUrl || !sameServer(stored.serverUrl, globalCredentialsServer))) {
+            throw globalReadMismatch(stored.serverUrl, globalCredentialsServer);
+        }
+        return stored;
     }
     const file = loadProjectCredentialsFile(env.projectRoot);
-    const stored = file.environments[env.name];
+    const entry = file.servers[serverKey(env.config.apiUrl)];
+    if (entry)
+        return entry.login ? storedCredentials(env.config.apiUrl, entry.login) : null;
+    const { slot, children } = loginSlotOf(env);
+    const stored = file.environments[slot];
     if (!stored)
         return null;
+    if (recordsOtherServer(stored, env.config.apiUrl)) {
+        throw new PrimitiveEnvError("server-mismatch", `The "${env.name}" login in ${getCredentialsFilePath()} was issued by ${stored.serverUrl}, ` +
+            `but "${env.name}" now points at ${env.config.apiUrl}; its tokens were not sent. ` +
+            `Run 'primitive -e ${env.name} login' to sign in there.`);
+    }
+    dropCopiedChildSlots(env.projectRoot, file, slot, children);
+    return storedCredentials(env.config.apiUrl, stored);
+}
+/**
+ * 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 function mismatchedLogin() {
+    const env = resolveCurrentEnvironment();
+    if (!env || environmentToken())
+        return null;
+    const file = loadProjectCredentialsFile(env.projectRoot);
+    if (file.servers[serverKey(env.config.apiUrl)])
+        return null;
+    const stored = file.environments[loginSlotOf(env).slot];
+    if (!stored || !recordsOtherServer(stored, env.config.apiUrl))
+        return null;
+    return storedCredentials(stored.serverUrl, stored);
+}
+function storedCredentials(serverUrl, stored) {
     return {
-        serverUrl: env.config.apiUrl,
+        serverUrl,
         accessToken: stored.accessToken,
         refreshToken: stored.refreshToken,
         expiresAt: stored.expiresAt,
@@ -228,18 +650,114 @@ export function loadCredentialsStore() {
         role: stored.role,
         name: stored.name,
         globalAdminAppId: stored.globalAdminAppId,
+        ...(stored.stepUp ? { stepUp: stored.stepUp } : {}),
     };
 }
 /**
- * Saves credentials. In project mode, writes to the per-env slot in the
- * project credentials file. In legacy mode, writes the global file.
+ * 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 function loginEnvironments() {
+    const env = resolveCurrentEnvironment();
+    if (!env)
+        return null;
+    const server = serverKey(env.config.apiUrl);
+    const servers = environmentServers(env.projectConfigPath) ?? {};
+    const environments = Object.entries(servers)
+        .filter(([, apiUrl]) => serverKey(apiUrl) === server)
+        .map(([name]) => name);
+    return { tree: env.tree, environments: environments.length > 0 ? environments : [env.name] };
+}
+/** The current project's root, or null outside a project or when it cannot be resolved. */
+function currentProjectRoot() {
+    try {
+        return getCurrentEnvironment()?.projectRoot ?? null;
+    }
+    catch {
+        return 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 const worktreeLoginNotes = {
+    /** After a login stored in another worktree's file: where it went. */
+    storedElsewhere() {
+        const root = currentProjectRoot();
+        if (!root || credentialsRootFor(root) === root)
+            return null;
+        return `Stored in ${credentialsFileForProject(root)}, shared with every git worktree of this repository that holds this project.`;
+    },
+    /** After a logout of `slot`'s login, when more than one worktree uses it. */
+    sharedLogout(slot) {
+        const root = currentProjectRoot();
+        if (!root || sharedWorktreeCount(root) < 2)
+            return null;
+        return `The ${slot} login is shared by every git worktree of this repository that holds this project, so all of them are signed out.`;
+    },
+    /** A linked worktree's own credentials file, which is never read. */
+    ignoredFile() {
+        const root = currentProjectRoot();
+        const ignored = root ? ignoredLocalCredentialsFile(root) : null;
+        if (!root || !ignored)
+            return null;
+        return `Ignored ${ignored}: this worktree uses the shared login in ${credentialsFileForProject(root)}. You can delete the ignored file.`;
+    },
+    /** After "not logged in", when git is why a linked worktree has no login. */
+    notLoggedIn() {
+        const root = currentProjectRoot();
+        return root ? oldGitHint(root) : 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 function leftoverLogins() {
+    const env = resolveCurrentEnvironment();
+    if (!env)
+        return [];
+    const file = loadProjectCredentialsFile(env.projectRoot);
+    const server = serverKey(env.config.apiUrl);
+    const entry = file.servers[server];
+    const stored = entry
+        ? Object.values(entry.leftovers ?? {})
+        : legacyLeftovers(file, env).map((name) => file.environments[name]);
+    return stored.map((slot) => storedCredentials(slot.serverUrl ?? env.config.apiUrl, slot));
+}
+/** The legacy slots on `env`'s server other than the one it reads. */
+function legacyLeftovers(file, env) {
+    const own = loginSlotOf(env).slot;
+    return legacySlotsOn(file, serverKey(env.config.apiUrl), environmentServers(env.projectConfigPath)).filter((name) => name !== own);
+}
+/**
+ * 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 function saveCredentialsStore(credentials) {
+    assertStorable(credentials);
     const env = resolveCurrentEnvironment();
     if (!env) {
+        if (globalCredentialsServer !== null && !sameServer(credentials.serverUrl, globalCredentialsServer)) {
+            throw new PrimitiveEnvError("server-mismatch", `These credentials were issued by ${credentials.serverUrl}, but this command targets ` +
+                `${globalCredentialsServer}; nothing was stored.`);
+        }
         ensureDir(getLegacyConfigDir());
         writeFileSync(getLegacyCredentialsFile(), JSON.stringify(legacyCredentialsRecord(credentials), null, 2), { mode: 0o600 });
         try {
@@ -250,22 +768,29 @@ export function saveCredentialsStore(credentials) {
         }
         return;
     }
-    const file = loadProjectCredentialsFile(env.projectRoot);
-    file.environments[env.name] = {
-        accessToken: credentials.accessToken,
-        refreshToken: credentials.refreshToken,
-        expiresAt: credentials.expiresAt,
-        adminId: credentials.adminId,
-        email: credentials.email,
-        role: credentials.role,
-        name: credentials.name,
-        globalAdminAppId: credentials.globalAdminAppId,
-    };
-    writeProjectCredentialsFile(env.projectRoot, file);
+    if (!sameServer(credentials.serverUrl, env.config.apiUrl)) {
+        throw writeMismatch(env.name, credentials.serverUrl, env.config.apiUrl);
+    }
+    writeServerLogin(env.projectRoot, environmentServers(env.projectConfigPath), credentials);
+}
+/** Write `credentials` as their server's login in the project at `projectRoot`. */
+function writeServerLogin(projectRoot, servers, credentials) {
+    const record = storedRecord(credentials);
+    const server = serverKey(credentials.serverUrl);
+    updateProjectCredentialsFile(projectRoot, (file) => {
+        migrateServer(file, server, record, servers).login = record;
+        return true;
+    });
 }
 /**
  * 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 function clearCredentialsStore() {
     const env = resolveCurrentEnvironment();
@@ -280,57 +805,167 @@ export function clearCredentialsStore() {
         }
         return;
     }
+    if (!existsSync(credentialsFileForProject(env.projectRoot)))
+        return;
+    const server = serverKey(env.config.apiUrl);
+    const { slot, children } = loginSlotOf(env);
+    updateProjectCredentialsFile(env.projectRoot, (file) => {
+        const entry = file.servers[server];
+        if (entry) {
+            if (!entry.login)
+                return false;
+            delete entry.login;
+            return true;
+        }
+        const login = file.environments[slot];
+        if (!login)
+            return false;
+        for (const name of children) {
+            const child = file.environments[name];
+            if (child && sameSession(child, login) && !ownStepUp(child, login)) {
+                delete file.environments[name];
+            }
+        }
+        delete file.environments[slot];
+        return true;
+    });
+}
+/**
+ * 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 function clearLeftoverLogins() {
+    const env = resolveCurrentEnvironment();
+    if (!env)
+        return;
+    const server = serverKey(env.config.apiUrl);
     const file = loadProjectCredentialsFile(env.projectRoot);
-    delete file.environments[env.name];
-    writeProjectCredentialsFile(env.projectRoot, file);
+    const entry = file.servers[server];
+    if (entry ? !entry.leftovers : legacyLeftovers(file, env).length === 0)
+        return;
+    updateProjectCredentialsFile(env.projectRoot, (current) => {
+        const currentEntry = current.servers[server];
+        if (currentEntry) {
+            if (!currentEntry.leftovers)
+                return false;
+            delete currentEntry.leftovers;
+            return true;
+        }
+        const names = legacyLeftovers(current, env);
+        for (const name of names)
+            delete current.environments[name];
+        return names.length > 0;
+    });
 }
 /**
- * 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 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 function clearCredentialsForEnvInProject(projectRoot, envName) {
+export function clearCredentialsForEnvInProject(projectRoot, envName, configPath = configPathOf(projectRoot), removedApiUrl) {
     try {
-        const file = loadProjectCredentialsFile(projectRoot);
-        if (file.environments[envName]) {
-            delete file.environments[envName];
-            writeProjectCredentialsFile(projectRoot, file);
+        const removed = removeCredentialsSlotInProject(projectRoot, envName);
+        if (removedApiUrl === undefined)
+            return removed;
+        const server = serverKey(removedApiUrl);
+        const others = otherSharingProjectRoots(projectRoot);
+        if (!others)
+            return removed;
+        for (const path of [configPath, ...others.map(configPathOf)]) {
+            const servers = environmentServers(path);
+            if (!servers)
+                return removed;
+            if (Object.values(servers).some((apiUrl) => serverKey(apiUrl) === server))
+                return removed;
         }
+        if (!loadProjectCredentialsFile(projectRoot).servers[server])
+            return removed;
+        updateProjectCredentialsFile(projectRoot, (file) => {
+            if (!file.servers[server])
+                return false;
+            delete file.servers[server];
+            return true;
+        });
+        return true;
     }
     catch {
         // Best-effort — removal is not a hard requirement for env removal to succeed.
+        return false;
     }
 }
+/** Whether `file` holds a legacy slot or a leftover named `envName`. */
+function holdsSlotOf(file, envName) {
+    return (file.environments[envName] !== undefined ||
+        Object.values(file.servers).some((entry) => entry.leftovers?.[envName] !== undefined));
+}
+/**
+ * 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 function removeCredentialsSlotInProject(projectRoot, envName) {
+    if (!holdsSlotOf(loadProjectCredentialsFile(projectRoot), envName))
+        return false;
+    let removed = false;
+    updateProjectCredentialsFile(projectRoot, (file) => {
+        removed = holdsSlotOf(file, envName);
+        delete file.environments[envName];
+        for (const entry of Object.values(file.servers)) {
+            if (!entry.leftovers?.[envName])
+                continue;
+            delete entry.leftovers[envName];
+            if (Object.keys(entry.leftovers).length === 0)
+                delete entry.leftovers;
+        }
+        return removed;
+    });
+    return removed;
+}
 /**
- * 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 function seedCredentialsForEnvInProject(projectRoot, envName, credentials) {
-    const file = loadProjectCredentialsFile(projectRoot);
-    file.environments[envName] = {
-        accessToken: credentials.accessToken,
-        refreshToken: credentials.refreshToken,
-        expiresAt: credentials.expiresAt,
-        adminId: credentials.adminId,
-        email: credentials.email,
-        role: credentials.role,
-        name: credentials.name,
-        globalAdminAppId: credentials.globalAdminAppId,
-    };
-    writeProjectCredentialsFile(projectRoot, file);
+export function seedCredentialsForServerInProject(projectRoot, credentials) {
+    assertStorable(credentials);
+    writeServerLogin(projectRoot, environmentServers(configPathOf(projectRoot)), credentials);
 }
 /**
- * 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 function listAuthenticatedEnvironments() {
     const env = resolveCurrentEnvironment();
     if (!env)
         return [];
     const file = loadProjectCredentialsFile(env.projectRoot);
-    return Object.keys(file.environments);
+    const servers = environmentServers(env.projectConfigPath) ?? {};
+    const names = new Set();
+    for (const [name, apiUrl] of Object.entries(servers)) {
+        const entry = file.servers[serverKey(apiUrl)];
+        if (entry ? entry.login : file.environments[name])
+            names.add(name);
+    }
+    for (const name of Object.keys(file.environments)) {
+        const apiUrl = servers[name];
+        if (apiUrl === undefined || !file.servers[serverKey(apiUrl)])
+            names.add(name);
+    }
+    return [...names];
 }
 //# sourceMappingURL=credentials-store.js.map