metergraph-cli 0.2.2 → 0.2.4

package/src/auth-oauth.js

@@ -1,6 +1,14 @@
 import { createHash, randomBytes } from "node:crypto";
 
-import { AGENT_CONTRACT_VERSION, AUTH_PATHS, METADATA_SCOPE } from "./constants.js";
+import {
+  AGENT_CONTRACT_VERSION,
+  AUTH_PATHS,
+  DEBUG_SCOPE,
+  EXPERIMENT_START_KEY_SCOPES,
+  EXPERIMENT_START_SCOPE,
+  METADATA_SCOPE,
+  WORKFLOW_SCOPES,
+} from "./constants.js";
 import { parseJsonObject } from "./http.js";
 import { failureOf, send } from "./transport.js";
 
@@ -28,6 +36,7 @@ const MAX_EXPIRES_IN = 366 * 24 * 60 * 60;
 // metadata and in the setup discovery document. Without it the CLI registers
 // a new public client for each sign in, as servers without the field expect.
 export const CLI_CLIENT_ID_FIELD = "metergraph_cli_client_id";
+export const WORKSPACE_HINT_FIELD = "metergraph_workspace_hint_supported";
 
 // The access token claim that names the workspace the grant is for. The
 // claim is a sanity check only; the CLI does not verify token signatures.
@@ -54,7 +63,7 @@ const stop = (outcome, reason) => ({ ok: false, outcome, reason });
 // fixed path on this origin. A server that does not advertise the Metadata
 // scope, S256 or public clients is unsupported; there is no fallback to
 // another scope.
-export async function discover(origin, signal) {
+export async function discover(origin, signal, baseScope = METADATA_SCOPE) {
   const expected = endpointsFor(origin);
 
   const prm = await fetchMetadata(origin, [
@@ -74,6 +83,9 @@ export async function discover(origin, signal) {
   if (resource.scopes_supported !== undefined && !includes(resource.scopes_supported, METADATA_SCOPE)) {
     return stop("unsupported", "metadata_scope_unsupported");
   }
+  if (resource.scopes_supported !== undefined && !includes(resource.scopes_supported, baseScope)) {
+    return stop("unsupported", "debug_scope_unsupported");
+  }
   if (resource.bearer_methods_supported !== undefined && !includes(resource.bearer_methods_supported, "header")) {
     return stop("unsupported", "oauth_metadata_invalid");
   }
@@ -97,6 +109,7 @@ export async function discover(origin, signal) {
   if (!includes(server.scopes_supported, METADATA_SCOPE)) {
     return stop("unsupported", "metadata_scope_unsupported");
   }
+  if (!includes(server.scopes_supported, baseScope)) return stop("unsupported", "debug_scope_unsupported");
   if (!includes(server.code_challenge_methods_supported, "S256")) return stop("unsupported", "pkce_unsupported");
   if (!includes(server.token_endpoint_auth_methods_supported, "none")) {
     return stop("unsupported", "public_client_unsupported");
@@ -122,6 +135,9 @@ export async function discover(origin, signal) {
     endpoints: expected,
     requireIss: server.authorization_response_iss_parameter_supported === true,
     offeredClientId: offered,
+    // The consent page can match a workspace the person named by slug or
+    // name, and offers approval for that workspace alone.
+    workspaceHint: server[WORKSPACE_HINT_FIELD] === true,
   };
 }
 
@@ -137,9 +153,9 @@ export function offeredClientId(doc) {
 // The client for one sign in: the pre-registered client the service offered,
 // or a newly registered one when it offered none. The offered client accepts
 // the loopback redirect on any port, so it needs no registration request.
-export async function clientFor(endpoints, offered, redirectUri, signal) {
+export async function clientFor(endpoints, offered, redirectUri, signal, scopes = [METADATA_SCOPE]) {
   if (offered !== null) return { ok: true, clientId: offered };
-  return register(endpoints, redirectUri, signal);
+  return register(endpoints, redirectUri, signal, scopes);
 }
 
 async function fetchMetadata(origin, paths, signal) {
@@ -164,7 +180,7 @@ function includes(list, value) {
 // Dynamic client registration for a public client bound to one exact
 // loopback redirect. A response that carries a client secret, a different
 // redirect or another authentication method is refused.
-export async function register(endpoints, redirectUri, signal) {
+export async function register(endpoints, redirectUri, signal, scopes = [METADATA_SCOPE]) {
   const response = await send(endpoints.origin, AUTH_PATHS.registration, {
     method: "POST",
     signal,
@@ -175,7 +191,7 @@ export async function register(endpoints, redirectUri, signal) {
       grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
       token_endpoint_auth_method: "none",
-      scope: METADATA_SCOPE,
+      scope: scopes.join(" "),
     },
   });
   const failure = failureOf(response);
@@ -229,13 +245,18 @@ export function newPkce() {
 // also approve the first ingest key for a new setup family. The service
 // returns that receipt next to the code; it is redeemed separately with its
 // own PKCE verifier.
-export function authorizationUrl(endpoints, { clientId, redirectUri, state, challenge, signup, ingestSetup = null }) {
+// scopes is the access asked for: Metadata, or Debug with the chosen workflow
+// permissions. workspaceHint, when given, is the workspace the person named,
+// sent only to a service that advertises it.
+export function authorizationUrl(endpoints, {
+  clientId, redirectUri, state, challenge, signup, ingestSetup = null, scopes = [METADATA_SCOPE], workspaceHint = null,
+}) {
   const url = new URL(endpoints.authorization);
   url.search = new URLSearchParams({
     response_type: "code",
     client_id: clientId,
     redirect_uri: redirectUri,
-    scope: METADATA_SCOPE,
+    scope: scopes.join(" "),
     state,
     code_challenge: challenge,
     code_challenge_method: "S256",
@@ -245,6 +266,7 @@ export function authorizationUrl(endpoints, { clientId, redirectUri, state, chal
       ingest_setup_family_id: ingestSetup.familyId,
       ingest_setup_code_challenge: ingestSetup.challenge,
     }),
+    ...(workspaceHint === null ? {} : { workspace_hint: workspaceHint }),
   }).toString();
   if (!signup) return url.href;
   const entry = new URL(`${endpoints.origin}${AUTH_PATHS.signup}`);
@@ -254,7 +276,7 @@ export function authorizationUrl(endpoints, { clientId, redirectUri, state, chal
 
 // Exchanges an authorization code. Codes are single use, so there is never
 // a retry.
-export async function exchangeCode(endpoints, { clientId, redirectUri, code, verifier }, signal) {
+export async function exchangeCode(endpoints, { clientId, redirectUri, code, verifier, scopes = [METADATA_SCOPE] }, signal) {
   const response = await send(endpoints.origin, AUTH_PATHS.token, {
     method: "POST",
     signal,
@@ -272,13 +294,13 @@ export async function exchangeCode(endpoints, { clientId, redirectUri, code, ver
   if (failure !== null) return { ok: false, ...failure };
   if (response.status === 400 || response.status === 401) return stop("authorization_failed", "code_rejected");
   if (response.status !== 200) return stop("unsupported", "unexpected_status");
-  return validateGrant(parseJsonObject(response), endpoints, clientId, { requireRefresh: true });
+  return validateGrant(parseJsonObject(response), endpoints, clientId, { requireRefresh: true, scopes });
 }
 
 // Refreshes a grant once. The result says whether the refresh token may have
 // been consumed without the CLI learning its replacement (ambiguous), so the
 // caller never retries with it.
-export async function refreshGrant(endpoints, { clientId, refreshToken }, signal) {
+export async function refreshGrant(endpoints, { clientId, refreshToken, scopes = [METADATA_SCOPE] }, signal) {
   const response = await send(endpoints.origin, AUTH_PATHS.token, {
     method: "POST",
     signal,
@@ -288,7 +310,7 @@ export async function refreshGrant(endpoints, { clientId, refreshToken }, signal
       refresh_token: refreshToken,
       client_id: clientId,
       resource: endpoints.resource,
-      scope: METADATA_SCOPE,
+      scope: scopes.join(" "),
     },
   });
   if (response.kind === "error" && !response.sent) {
@@ -306,16 +328,17 @@ export async function refreshGrant(endpoints, { clientId, refreshToken }, signal
   if (response.kind !== "response" || response.status !== 200 || response.tooLarge) {
     return { ok: false, outcome: "login_required", reason: "refresh_interrupted", ambiguous: true };
   }
-  const result = validateGrant(parseJsonObject(response), endpoints, clientId, { requireRefresh: false });
+  const result = validateGrant(parseJsonObject(response), endpoints, clientId, { requireRefresh: false, scopes });
   // A 200 that cannot be used may still have rotated the refresh token.
   return result.ok ? result : { ...result, ambiguous: true };
 }
 
-// Accepts only a Bearer grant for exactly the Metadata scope with bounded,
-// non-empty tokens and an expiry. The access token claims must name this
-// issuer, resource and client and one workspace. These are sanity checks on
-// what the server said, not a signature check.
-export function validateGrant(body, endpoints, clientId, { requireRefresh }) {
+// Accepts only a Bearer grant for exactly the scopes asked for (Metadata, or
+// Debug with the chosen workflow permissions) with bounded, non-empty tokens and an expiry. The
+// access token claims must name this issuer, resource and client and one
+// workspace. These are sanity checks on what the server said, not a
+// signature check.
+export function validateGrant(body, endpoints, clientId, { requireRefresh, scopes = [METADATA_SCOPE] }) {
   if (body === null) return stop("verification_failed", "token_response_invalid");
   if (typeof body.token_type !== "string" || body.token_type.toLowerCase() !== "bearer") {
     return stop("verification_failed", "token_type_invalid");
@@ -334,9 +357,7 @@ export function validateGrant(body, endpoints, clientId, { requireRefresh }) {
   if (!Number.isInteger(body.expires_in) || body.expires_in < 1 || body.expires_in > MAX_EXPIRES_IN) {
     return stop("verification_failed", "token_response_invalid");
   }
-  if (typeof body.scope !== "string" || body.scope !== METADATA_SCOPE) {
-    return stop("verification_failed", "scope_mismatch");
-  }
+  if (!sameScopes(body.scope, scopes)) return stop("verification_failed", "scope_mismatch");
 
   const claims = decodeClaims(body.access_token);
   if (claims === null) return stop("verification_failed", "token_claims_invalid");
@@ -344,7 +365,7 @@ export function validateGrant(body, endpoints, clientId, { requireRefresh }) {
   const audience = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
   if (!audience.includes(endpoints.resource)) return stop("verification_failed", "resource_mismatch");
   if (claims.client_id !== clientId) return stop("verification_failed", "client_mismatch");
-  if (claims.scope !== undefined && claims.scope !== METADATA_SCOPE) {
+  if (claims.scope !== undefined && !sameScopes(claims.scope, scopes)) {
     return stop("verification_failed", "scope_mismatch");
   }
   const tenant = normalizeUuid(claims[TENANT_CLAIM]);
@@ -365,6 +386,13 @@ export function validateGrant(body, endpoints, clientId, { requireRefresh }) {
   };
 }
 
+// Whether a space-separated scope string names exactly these scopes.
+export function sameScopes(value, scopes) {
+  if (typeof value !== "string") return false;
+  const given = value.split(" ");
+  return given.length === scopes.length && new Set(given).size === given.length && scopes.every((scope) => given.includes(scope));
+}
+
 function decodeClaims(token) {
   const parts = token.split(".");
   if (parts.length !== 3 || !/^[A-Za-z0-9_-]+$/.test(parts[1])) return null;
@@ -378,32 +406,53 @@ function decodeClaims(token) {
   }
 }
 
+// What a credential's scopes amount to: "metadata" for exactly the Metadata
+// scope, "debug" for Debug with any of the workflow permissions, or null for
+// anything else, including Replay.
+export function credentialAccess(scopes) {
+  if (!Array.isArray(scopes) || !scopes.every((scope) => typeof scope === "string")) return null;
+  if (new Set(scopes).size !== scopes.length) return null;
+  if (scopes.length === 1 && scopes[0] === METADATA_SCOPE) return "metadata";
+  if (!scopes.includes(DEBUG_SCOPE)) return null;
+  return scopes.every((scope) => scope === DEBUG_SCOPE || WORKFLOW_SCOPES.includes(scope)) ? "debug" : null;
+}
+
 // Asks the service, with the access token, which workspace and profile the
 // grant is for and what it may do. The answers are server-authoritative:
 //   GET /v1/agent/workspace: workspace.id, provenance.workspace_id and the
 //     expected workspace must agree, provenance.deployment_profile must be
-//     the profile seen before sign in, access.scopes must be exactly the
-//     Metadata scope and content.included must be false. Capture being
+//     the profile seen before sign in, access.scopes must be what this use
+//     accepts (below) and content.included must be false. Capture being
 //     enabled for the workspace (content.captured) is not a reason to refuse.
 //   GET /v1/agent/capabilities: provenance.workspace_id and both
-//     provenance.deployment_profile and deployment_profile must match, and
-//     every capability that reads content or replays, or calls a configured
-//     provider, must be unavailable to this grant.
+//     provenance.deployment_profile and deployment_profile must match. For a
+//     Metadata credential, every capability that reads content or replays,
+//     or calls a configured provider, must be unavailable.
 // Nothing else is read: no telemetry, content or provider requests.
-// Returns { ok: true, workspaceId, documents } or { ok: false, outcome, reason, denied }
-// where denied means the service refused the token (401 or 403).
+// Returns { ok: true, workspaceId, access, scopes, documents } or
+// { ok: false, outcome, reason, denied } where denied means the service
+// refused the token (401 or 403).
 // workspaceId is the workspace the credential must be for. Only an agent key
 // with nothing to pin it to passes anyWorkspace: true with workspaceId null,
 // and then the workspace the service reports is checked for consistency and
 // returned as the verified one.
-export async function verifyContext(origin, accessToken, { profile, workspaceId, anyWorkspace = false }, signal) {
+// access says what this use accepts:
+//   "metadata": exactly the Metadata scope (sign in).
+//   "read": Metadata, or Debug with any workflow permissions, which a person
+//     grants for writing evaluations and starting analyses (the read
+//     commands). Replay is refused.
+//     A read command still sends only its own Metadata requests.
+//   "experiment_start": Debug with the start grant (experiments start).
+export async function verifyContext(origin, accessToken, { profile, workspaceId, anyWorkspace = false, access = "metadata" }, signal) {
   const workspace = await bearerJson(origin, AUTH_PATHS.workspace, accessToken, WORKSPACE_BYTES, signal, "workspace");
   if (!workspace.ok) return workspace;
   if (workspaceId === null && anyWorkspace === true) {
     workspaceId = normalizeUuid(workspace.body.workspace?.id);
     if (workspaceId === null) return stop("verification_failed", "workspace_response_invalid");
   }
-  const checked = checkWorkspace(workspace.body, { profile, workspaceId });
+  const checked = access === "experiment_start"
+    ? checkStartWorkspace(workspace.body, { profile, workspaceId })
+    : checkWorkspace(workspace.body, { profile, workspaceId, debug: access === "read" });
   if (!checked.ok) return checked;
 
   const capabilities = await bearerJson(
@@ -415,17 +464,26 @@ export async function verifyContext(origin, accessToken, { profile, workspaceId,
     "capabilities",
   );
   if (!capabilities.ok) return capabilities;
-  const allowed = checkCapabilities(capabilities.body, { profile, workspaceId });
+  const allowed = access === "experiment_start"
+    ? checkStartCapabilities(capabilities.body, { profile, workspaceId })
+    : checkCapabilities(capabilities.body, { profile, workspaceId, access: checked.access });
   if (!allowed.ok) return allowed;
   // The verified documents stay in memory for read commands, which print
   // only fields they validate themselves.
-  return { ok: true, workspaceId, documents: { workspace: workspace.body, capabilities: capabilities.body } };
+  return {
+    ok: true,
+    workspaceId,
+    access: checked.access,
+    scopes: checked.scopes,
+    documents: { workspace: workspace.body, capabilities: capabilities.body },
+  };
 }
 
 // Both documents carry the service's contract version string in
 // schema_version. Any other value, including a number, is a contract this
 // CLI does not know.
-export function checkWorkspace(body, { profile, workspaceId }) {
+// debug: true accepts Debug with workflow permissions as well as Metadata.
+export function checkWorkspace(body, { profile, workspaceId, debug = false }) {
   const id = normalizeUuid(body.workspace?.id);
   if (body.schema_version !== AGENT_CONTRACT_VERSION || id === null || !isObject(body.provenance)) {
     return stop("verification_failed", "workspace_response_invalid");
@@ -435,16 +493,51 @@ export function checkWorkspace(body, { profile, workspaceId }) {
   }
   if (body.provenance.deployment_profile !== profile) return stop("verification_failed", "profile_mismatch");
   const scopes = body.access?.scopes;
-  if (!Array.isArray(scopes) || scopes.length !== 1 || scopes[0] !== METADATA_SCOPE) {
+  const access = credentialAccess(scopes);
+  if (access === null || (access === "debug" && !debug)) {
     return stop("verification_failed", "scope_mismatch");
   }
   if (!isObject(body.content) || body.content.included !== false) {
     return stop("verification_failed", "content_access_granted");
   }
+  return { ok: true, access, scopes: [...scopes].sort() };
+}
+
+// A start key's workspace document: the same identity checks as
+// checkWorkspace, and Debug with the start grant (other workflow permissions
+// may come with it; Replay may not).
+export function checkStartWorkspace(body, { profile, workspaceId }) {
+  const identity = checkWorkspace({ ...body, access: { scopes: [METADATA_SCOPE] } }, { profile, workspaceId });
+  if (!identity.ok) return identity;
+  const scopes = body.access?.scopes;
+  if (credentialAccess(scopes) !== "debug" || !EXPERIMENT_START_KEY_SCOPES.every((scope) => scopes.includes(scope))) {
+    return stop("permission_denied", "experiment_start_not_granted");
+  }
+  return { ok: true, access: "debug", scopes: [...scopes].sort() };
+}
+
+// A start key's capabilities document: the same identity checks as
+// checkCapabilities, and the start capability offered to this key.
+export function checkStartCapabilities(body, { profile, workspaceId }) {
+  if (body.schema_version !== AGENT_CONTRACT_VERSION || !isObject(body.provenance) || !isObject(body.agent)) {
+    return stop("verification_failed", "capabilities_response_invalid");
+  }
+  if (normalizeUuid(body.provenance.workspace_id) !== workspaceId) {
+    return stop("verification_failed", "workspace_context_mismatch");
+  }
+  if (body.provenance.deployment_profile !== profile || body.deployment_profile !== profile) {
+    return stop("verification_failed", "profile_mismatch");
+  }
+  const start = body.agent.experiment_start;
+  if (!isObject(start) || start.available !== true || start.required_scope !== EXPERIMENT_START_SCOPE || start.mutates !== true) {
+    return stop("capability_unavailable", "experiment_start_unavailable");
+  }
   return { ok: true };
 }
 
-export function checkCapabilities(body, { profile, workspaceId }) {
+// access is the credential's ("metadata" or "debug"). A Debug credential is
+// offered content and starts by design; the read commands never use them.
+export function checkCapabilities(body, { profile, workspaceId, access = "metadata" }) {
   if (body.schema_version !== AGENT_CONTRACT_VERSION || !isObject(body.provenance) || !isObject(body.agent)) {
     return stop("verification_failed", "capabilities_response_invalid");
   }
@@ -456,6 +549,10 @@ export function checkCapabilities(body, { profile, workspaceId }) {
   }
   for (const entry of Object.values(body.agent)) {
     if (!isObject(entry)) return stop("verification_failed", "capabilities_response_invalid");
+    if (access !== "metadata" && entry.required_scope === "agent:replay" && entry.available !== false) {
+      return stop("verification_failed", "scope_mismatch");
+    }
+    if (access !== "metadata") continue;
     const sensitive =
       entry.content !== false ||
       entry.privacy_class !== "metadata" ||

package/src/auth-session.js

@@ -1,6 +1,6 @@
-import { endpointsFor, refreshGrant, verifyContext } from "./auth-oauth.js";
+import { endpointsFor, refreshGrant, sameScopes, verifyContext } from "./auth-oauth.js";
 import { readBinding, resolveProject } from "./auth-binding.js";
-import { Stop, openStore, readCredential, resolveConfigDir, withSlotLock, writeCredential } from "./auth-store.js";
+import { Stop, openStore, readProjectCredential, resolveConfigDir, withSlotLock, writeCredential } from "./auth-store.js";
 import { AUTH_HTTP_TIMEOUT_MS, METADATA_SCOPE } from "./constants.js";
 import { deadline } from "./transport.js";
 
@@ -14,7 +14,7 @@ const REFRESH_MARGIN_MS = 60 * 1000;
 export const LOCK_WAIT_MS = AUTH_HTTP_TIMEOUT_MS + 5000;
 
 // Resolves with
-//   { ok: true, session: { origin, workspaceId, profile, scopes, accessToken }, documents, knownCredentials }
+//   { ok: true, session: { origin, workspaceId, profile, access, scopes, accessToken }, documents, knownCredentials }
 //   { ok: false, outcome, reason }
 // documents holds the workspace and capabilities documents the service
 // returned during verification, already checked by verifyContext.
@@ -25,7 +25,7 @@ export async function verifiedSession({ project = null, configDir = null, cancel
     const store = openStore(resolveConfigDir(configDir), { create: false });
     const found = readBinding(root);
     if (found === null) return stop("login_required", "not_signed_in");
-    return await sessionFor(found.binding, store, cancel);
+    return await sessionFor(found.binding, store, cancel, root);
   } catch (error) {
     if (error instanceof Stop) return stop(error.outcome, error.reason);
     throw error;
@@ -34,10 +34,10 @@ export async function verifiedSession({ project = null, configDir = null, cancel
 
 // The same, for a binding and store already read by the caller. store may be
 // null when the private store does not exist.
-export async function sessionFor(binding, store, cancel) {
+export async function sessionFor(binding, store, cancel, root) {
   if (store === null) return stop("login_required", "credential_missing");
   const slot = binding.credential_slot;
-  let record = readCredential(store, slot);
+  let record = readProjectCredential(store, slot, root);
   if (record === null) return stop("login_required", "credential_missing");
   const context = checkIdentity(record, binding);
   if (!context.ok) return context;
@@ -52,7 +52,7 @@ export async function sessionFor(binding, store, cancel) {
   if (record.refresh_pending || record.expires_at - Date.now() <= REFRESH_MARGIN_MS) {
     let refreshed;
     try {
-      refreshed = await withSlotLock(store, slot, () => refreshLocked(store, slot, binding, cancel), {
+      refreshed = await withSlotLock(store, slot, () => refreshLocked(store, slot, binding, cancel, root), {
         waitMs: LOCK_WAIT_MS,
         signal: cancel,
       });
@@ -68,12 +68,18 @@ export async function sessionFor(binding, store, cancel) {
   }
 
   const limit = deadline(AUTH_HTTP_TIMEOUT_MS, cancel);
+  // A Debug sign in (login --role debug) is verified as Debug with workflow
+  // permissions, and must still hold exactly the scopes it was granted.
+  const debug = record.scope !== METADATA_SCOPE;
   const verified = await verifyContext(
     binding.origin,
     record.access_token,
-    { profile: binding.deployment_profile, workspaceId: binding.workspace_id },
+    { profile: binding.deployment_profile, workspaceId: binding.workspace_id, access: debug ? "read" : "metadata" },
     limit.signal,
   );
+  if (verified.ok && debug && !sameScopes(record.scope, verified.scopes)) {
+    return stop("verification_failed", "scope_mismatch");
+  }
   if (!verified.ok) {
     // The service refused a token that was valid when issued: the grant was
     // revoked, or the user lost access to the workspace. Fail closed.
@@ -87,7 +93,8 @@ export async function sessionFor(binding, store, cancel) {
       origin: binding.origin,
       workspaceId: binding.workspace_id,
       profile: binding.deployment_profile,
-      scopes: [METADATA_SCOPE],
+      access: verified.access,
+      scopes: verified.scopes,
       accessToken: record.access_token,
     },
     documents: verified.documents,
@@ -127,8 +134,8 @@ function checkContext(record, binding) {
 // unusable answer, a failed save or a killed process) leaves the mark, so the
 // possibly consumed refresh token is never sent again and the user is asked
 // to reconnect.
-async function refreshLocked(store, slot, binding, cancel) {
-  const current = readCredential(store, slot);
+async function refreshLocked(store, slot, binding, cancel, root) {
+  const current = readProjectCredential(store, slot, root);
   if (current === null) return stop("login_required", "credential_missing");
   const context = checkContext(current, binding);
   if (!context.ok) return context;
@@ -139,7 +146,7 @@ async function refreshLocked(store, slot, binding, cancel) {
   const limit = deadline(AUTH_HTTP_TIMEOUT_MS, cancel);
   const result = await refreshGrant(
     endpoints,
-    { clientId: current.client_id, refreshToken: current.refresh_token },
+    { clientId: current.client_id, refreshToken: current.refresh_token, scopes: current.scope.split(" ") },
     limit.signal,
   );
   if (!result.ok) {

package/src/auth-store.js

@@ -1,11 +1,11 @@
 import { spawnSync } from "node:child_process";
-import { randomBytes } from "node:crypto";
-import fs from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import fs, { withRollback } from "./anchored-fs.js";
 import os from "node:os";
 import path from "node:path";
 
 import { systemRoot } from "./auth-browser.js";
-import { AUTH_PATHS, METADATA_SCOPE, SUPPORTED_PROFILES } from "./constants.js";
+import { AUTH_PATHS, SUPPORTED_PROFILES, isLoginScope } from "./constants.js";
 import { parseOrigin } from "./origin.js";
 
 // Per-user credential storage for the delegated Metadata OAuth grant. Only
@@ -90,6 +90,7 @@ export function openStore(dir, { create }) {
     return { dir, credentials };
   } catch (error) {
     if (error instanceof Stop) throw error;
+    if (error.code === "ENOTSUP") throw new Stop("unsupported", "secure_writes_unavailable");
     throw new Stop("filesystem_error", "credential_store_unavailable");
   }
 }
@@ -111,6 +112,7 @@ export function readCredential(store, slot) {
     content = readPrivateFile(file);
   } catch (error) {
     if (error instanceof Stop) throw error;
+    if (error.code === "ENOTSUP") throw new Stop("unsupported", "secure_writes_unavailable");
     throw new Stop("filesystem_error", "credential_store_unavailable");
   }
   if (content === null) return null;
@@ -119,6 +121,20 @@ export function readCredential(store, slot) {
   return record;
 }
 
+
+// Only a private record created for this canonical checkout authorizes use or
+// retirement. Public bindings and copied slot names carry no such authority.
+export function projectIdentity(root) {
+  const canonical = fs.realpathSync(root);
+  const identity = fs.statSync(canonical, { bigint: true });
+  return createHash("sha256").update(`${canonical}\0${identity.dev}\0${identity.ino}`).digest("hex");
+}
+
+export function readProjectCredential(store, slot, root) {
+  const record = readCredential(store, slot);
+  return record?.project_id === projectIdentity(root) ? record : null;
+}
+
 // Atomically replaces the slot file with record.
 export function writeCredential(store, slot, record) {
   if (!validRecord(record)) throw new Error("credential record is not valid");
@@ -127,6 +143,7 @@ export function writeCredential(store, slot, record) {
     writePrivateFile(store.credentials, `${slot}.json`, content);
   } catch (error) {
     if (error instanceof Stop) throw error;
+    if (error.code === "ENOTSUP") throw new Stop("unsupported", "secure_writes_unavailable");
     throw new Stop("filesystem_error", "credential_write_failed");
   }
 }
@@ -143,6 +160,7 @@ export function deleteCredential(store, slot) {
     return true;
   } catch (error) {
     if (error instanceof Stop) throw error;
+    if (error.code === "ENOTSUP") throw new Stop("unsupported", "secure_writes_unavailable");
     throw new Stop("filesystem_error", "credential_write_failed");
   }
 }
@@ -165,6 +183,7 @@ export async function withSlotLock(store, slot, work, { waitMs, signal = null })
       fs.closeSync(fd);
       break;
     } catch (error) {
+      if (error.code === "ENOTSUP") throw new Stop("unsupported", "secure_writes_unavailable");
       if (error.code !== "EEXIST") throw new Stop("filesystem_error", "credential_store_unavailable");
       if (Date.now() >= until) throw new Stop("conflict", "credential_locked");
       await pause(50, signal);
@@ -175,7 +194,7 @@ export async function withSlotLock(store, slot, work, { waitMs, signal = null })
     return await work();
   } finally {
     try {
-      fs.unlinkSync(lock);
+      withRollback(() => fs.unlinkSync(lock));
     } catch {
       // Reported by the next run as a held lock.
     }
@@ -197,7 +216,9 @@ function pause(ms, signal) {
 
 export function validRecord(record) {
   if (record === null || typeof record !== "object" || Array.isArray(record)) return false;
-  if (Object.keys(record).sort().join() !== RECORD_KEYS) return false;
+  const keys = Object.keys(record).filter((key) => key !== "project_id").sort().join();
+  if (keys !== RECORD_KEYS) return false;
+  if (Object.hasOwn(record, "project_id") && !/^[0-9a-f]{64}$/.test(record.project_id)) return false;
   const origin = parseOrigin(record.origin);
   return (
     record.schema_version === 1 &&
@@ -207,7 +228,7 @@ export function validRecord(record) {
     SUPPORTED_PROFILES.includes(record.deployment_profile) &&
     typeof record.workspace_id === "string" &&
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(record.workspace_id) &&
-    record.scope === METADATA_SCOPE &&
+    isLoginScope(record.scope) &&
     printable(record.client_id, 256) &&
     printable(record.access_token, 8192) &&
     printable(record.refresh_token, 4096) &&
@@ -373,7 +394,7 @@ function writePrivateFile(dir, name, content) {
     fs.renameSync(temp, dest);
   } catch (error) {
     try {
-      fs.unlinkSync(temp);
+      withRollback(() => fs.unlinkSync(temp));
     } catch {
       // Already renamed or never created.
     }