run402 3.7.13 → 3.8.0

package/lib/credentials.mjs

@@ -0,0 +1,273 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import {
+  activeProfile,
+  getProject,
+  loadKeyStore,
+  projectCredentialsFile,
+  removeProject,
+  saveProject,
+} from "./config.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs } from "./argparse.mjs";
+import { fail } from "./sdk-errors.mjs";
+
+const HELP = `run402 credentials — Manage local credential material
+
+Usage:
+  run402 credentials <subcommand> [args...]
+
+Subcommands:
+  project-keys  Manage the local project-key cache
+
+Examples:
+  run402 credentials project-keys list
+  run402 credentials project-keys status --project prj_abc123
+  run402 credentials project-keys import --project prj_abc123 --service-key-stdin
+  run402 credentials project-keys export --project prj_abc123 --reveal
+`;
+
+const PROJECT_KEYS_HELP = `run402 credentials project-keys — Manage local project-key cache entries
+
+Usage:
+  run402 credentials project-keys <subcommand> [options]
+
+Subcommands:
+  list                                List cached project-key entries, redacted
+  status --project <id>               Show one cached entry, redacted
+  import --project <id> --service-key-stdin
+  import --project <id> --service-key-env <env>
+  export --project <id> --reveal       Print cached keys, including secrets
+  remove --project <id>                Remove one cached key entry
+
+Notes:
+  - This is a LOCAL CACHE surface. It is not project inventory.
+  - list/status never reveal full keys.
+  - export requires --reveal.
+  - import accepts service keys through stdin or an environment variable, not argv.
+`;
+
+function parseProjectKeyFlags(args, extraKnown = [], valueFlagsExtra = []) {
+  const parsed = normalizeArgv(args);
+  const valueFlags = ["--project", ...valueFlagsExtra];
+  assertKnownFlags(parsed, ["--project", "--help", "-h", ...extraKnown], valueFlags);
+  return {
+    projectId: flagValue(parsed, "--project"),
+    parsed,
+    rest: positionalArgs(parsed, valueFlags),
+  };
+}
+
+function fingerprint(value) {
+  if (!value) return null;
+  return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+
+function prefix(value) {
+  if (!value) return null;
+  return `${value.slice(0, 8)}...`;
+}
+
+function provenance() {
+  const profile = activeProfile();
+  return {
+    source: "local_cache",
+    cache_path: projectCredentialsFile(),
+    wallet: profile,
+    profile,
+  };
+}
+
+function redactedEntry(projectId, entry) {
+  return {
+    project_id: projectId,
+    configured: Boolean(entry),
+    has_anon_key: Boolean(entry?.anon_key),
+    has_service_key: Boolean(entry?.service_key),
+    anon_key_prefix: prefix(entry?.anon_key),
+    service_key_prefix: prefix(entry?.service_key),
+    anon_key_fingerprint: fingerprint(entry?.anon_key),
+    service_key_fingerprint: fingerprint(entry?.service_key),
+    site_url: entry?.site_url ?? null,
+    cached_at: entry?.cached_at ?? null,
+    ...provenance(),
+  };
+}
+
+function requireProjectFlag(projectId, usage) {
+  if (!projectId) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --project <id>.",
+      hint: usage,
+    });
+  }
+  return projectId;
+}
+
+function requireCachedProject(projectId) {
+  const entry = getProject(projectId);
+  if (!entry) {
+    fail({
+      code: "PROJECT_CREDENTIAL_NOT_FOUND",
+      message: `No local project credentials cached for ${projectId}.`,
+      hint: "Import keys with `run402 credentials project-keys import --project <id> --service-key-stdin` if this operation truly requires local project credentials.",
+      details: { project_id: projectId, ...provenance() },
+      next_actions: [{
+        type: "run_command",
+        command: `run402 credentials project-keys import --project ${projectId} --service-key-stdin`,
+        why: "Import a service key for credential-required operations.",
+      }],
+    });
+  }
+  return entry;
+}
+
+async function list(args) {
+  const { rest } = parseProjectKeyFlags(args);
+  if (rest.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for project-keys list: ${rest[0]}` });
+  }
+  const store = loadKeyStore(projectCredentialsFile());
+  const projects = Object.entries(store.projects ?? {})
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([projectId, entry]) => redactedEntry(projectId, entry));
+  console.log(JSON.stringify({ projects, ...provenance() }, null, 2));
+}
+
+async function status(args) {
+  const { projectId, rest } = parseProjectKeyFlags(args);
+  if (rest.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for project-keys status: ${rest[0]}` });
+  }
+  const id = requireProjectFlag(projectId, "run402 credentials project-keys status --project <id>");
+  console.log(JSON.stringify(redactedEntry(id, getProject(id)), null, 2));
+}
+
+function readSecretInput(parsed) {
+  const fromEnv = flagValue(parsed, "--service-key-env");
+  const fromStdin = parsed.includes("--service-key-stdin");
+  if (fromEnv && fromStdin) {
+    fail({ code: "BAD_USAGE", message: "Use either --service-key-env or --service-key-stdin, not both." });
+  }
+  if (fromEnv) {
+    const value = process.env[fromEnv];
+    if (!value) {
+      fail({
+        code: "BAD_ENV",
+        message: `Environment variable ${fromEnv} is empty or unset.`,
+        details: { env: fromEnv },
+      });
+    }
+    return value.trim();
+  }
+  if (fromStdin) return readFileSync(0, "utf-8").trim();
+  fail({
+    code: "BAD_USAGE",
+    message: "Import requires --service-key-stdin or --service-key-env <env>.",
+    hint: "Do not pass service keys as command-line values; argv can leak through shell history and process listings.",
+  });
+}
+
+async function importKey(args) {
+  const { projectId, parsed, rest } = parseProjectKeyFlags(
+    args,
+    ["--service-key-stdin", "--service-key-env", "--anon-key-env"],
+    ["--service-key-env", "--anon-key-env"],
+  );
+  if (rest.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for project-keys import: ${rest[0]}` });
+  }
+  const id = requireProjectFlag(projectId, "run402 credentials project-keys import --project <id> --service-key-stdin");
+  const serviceKey = readSecretInput(parsed);
+  if (!serviceKey) {
+    fail({ code: "BAD_USAGE", message: "Service key input was empty." });
+  }
+  const anonEnv = flagValue(parsed, "--anon-key-env");
+  const anonKey = anonEnv ? process.env[anonEnv] : undefined;
+  if (anonEnv && !anonKey) {
+    fail({ code: "BAD_ENV", message: `Environment variable ${anonEnv} is empty or unset.`, details: { env: anonEnv } });
+  }
+  const existing = getProject(id);
+  saveProject(id, {
+    anon_key: anonKey ?? existing?.anon_key ?? "",
+    service_key: serviceKey,
+    site_url: existing?.site_url,
+    deployed_at: existing?.deployed_at,
+    last_deployment_id: existing?.last_deployment_id,
+    source: "manual_import",
+    cached_at: new Date().toISOString(),
+  });
+  console.log(JSON.stringify({ imported: true, ...redactedEntry(id, getProject(id)) }, null, 2));
+}
+
+async function exportKey(args) {
+  const { projectId, parsed, rest } = parseProjectKeyFlags(args, ["--reveal"]);
+  if (rest.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for project-keys export: ${rest[0]}` });
+  }
+  const id = requireProjectFlag(projectId, "run402 credentials project-keys export --project <id> --reveal");
+  if (!parsed.includes("--reveal")) {
+    fail({
+      code: "REVEAL_REQUIRED",
+      message: "Exporting full project keys requires --reveal.",
+      hint: "Use `run402 credentials project-keys status --project <id>` for redacted output.",
+      details: { project_id: id, ...provenance() },
+    });
+  }
+  const entry = requireCachedProject(id);
+  console.log(JSON.stringify({ project_id: id, ...entry, ...provenance(), revealed: true }, null, 2));
+}
+
+async function remove(args) {
+  const { projectId, rest } = parseProjectKeyFlags(args);
+  if (rest.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for project-keys remove: ${rest[0]}` });
+  }
+  const id = requireProjectFlag(projectId, "run402 credentials project-keys remove --project <id>");
+  const existed = Boolean(getProject(id));
+  removeProject(id, projectCredentialsFile());
+  console.log(JSON.stringify({ project_id: id, removed: existed, ...provenance() }, null, 2));
+}
+
+async function runProjectKeys(sub, args) {
+  if (!sub || sub === "--help" || sub === "-h") {
+    console.log(PROJECT_KEYS_HELP);
+    process.exit(0);
+  }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
+    console.log(PROJECT_KEYS_HELP);
+    process.exit(0);
+  }
+  switch (sub) {
+    case "list": await list(args); break;
+    case "status": await status(args); break;
+    case "import": await importKey(args); break;
+    case "export": await exportKey(args); break;
+    case "remove": await remove(args); break;
+    default:
+      fail({
+        code: "UNKNOWN_SUBCOMMAND",
+        message: `Unknown credentials project-keys subcommand: ${sub}`,
+        hint: "Run `run402 credentials project-keys --help` for usage.",
+        details: { command: "credentials project-keys", subcommand: sub },
+      });
+  }
+}
+
+export async function run(sub, args = []) {
+  if (!sub || sub === "--help" || sub === "-h") {
+    console.log(HELP);
+    process.exit(0);
+  }
+  if (sub === "project-keys") {
+    const [projectKeySub, ...rest] = Array.isArray(args) ? args : [];
+    await runProjectKeys(projectKeySub, rest);
+    return;
+  }
+  fail({
+    code: "UNKNOWN_SUBCOMMAND",
+    message: `Unknown credentials subcommand: ${sub}`,
+    hint: "Run `run402 credentials --help` for usage.",
+    details: { command: "credentials", subcommand: sub },
+  });
+}

package/lib/domains.mjs

@@ -9,14 +9,15 @@ Usage:
   run402 domains <subcommand> [args...]
 
 Subcommands:
-  add    <domain> <subdomain_name> [--project <id>]   Register a custom domain
-  list   [--project <id>]                              List custom domains for a project
-  status <domain> [--project <id>]                     Check domain DNS/SSL status
-  delete <domain> --confirm [--project <id>]           Release a custom domain. Requires --confirm.
+  add    <domain> <subdomain_name> [--project <id>] [--auth principal|service-key]
+  list   [--project <id>] [--auth principal|service-key]
+  status <domain> [--project <id>] [--auth principal|service-key]
+  delete <domain> --confirm [--project <id>] [--auth principal|service-key]
 
 Examples:
   run402 domains add example.com myapp
-  run402 domains add example.com myapp --project prj_123
+	  run402 domains add example.com myapp --project prj_123
+	  run402 domains list --project prj_123 --auth service-key
   run402 domains list
   run402 domains status example.com
   run402 domains delete example.com --confirm
@@ -31,7 +32,7 @@ const SUB_HELP = {
   add: `run402 domains add — Register a custom domain for a project
 
 Usage:
-  run402 domains add <domain> <subdomain_name> [--project <id>]
+  run402 domains add <domain> <subdomain_name> [--project <id>] [--auth principal|service-key]
 
 Arguments:
   <domain>            Custom domain (e.g. example.com)
@@ -39,6 +40,8 @@ Arguments:
 
 Options:
   --project <id>      Project ID (defaults to the active project)
+  --auth <mode>       principal (default, server-authoritative) or service-key
+                      (uses local project-key cache)
 
 Notes:
   - After adding, configure DNS as shown in the response
@@ -52,10 +55,14 @@ Examples:
   list: `run402 domains list — List custom domains for a project
 
 Usage:
-  run402 domains list [--project <id>]
+  run402 domains list [--project <id>] [--auth principal|service-key]
 
-Arguments:
-  <id>                Project ID (defaults to the active project)
+	Arguments:
+	  <id>                Project ID (defaults to the active project)
+
+Options:
+  --auth <mode>       principal (default, server-authoritative) or service-key
+                      (uses local project-key cache)
 
 Examples:
   run402 domains list
@@ -64,13 +71,15 @@ Examples:
   status: `run402 domains status — Check DNS/SSL status of a custom domain
 
 Usage:
-  run402 domains status <domain> [--project <id>]
+  run402 domains status <domain> [--project <id>] [--auth principal|service-key]
 
 Arguments:
   <domain>            Custom domain to check
 
 Options:
   --project <id>      Project ID (defaults to the active project)
+  --auth <mode>       principal (default, server-authoritative) or service-key
+                      (uses local project-key cache)
 
 Examples:
   run402 domains status example.com
@@ -79,7 +88,7 @@ Examples:
   delete: `run402 domains delete — Release a custom domain
 
 Usage:
-  run402 domains delete <domain> --confirm [--project <id>]
+  run402 domains delete <domain> --confirm [--project <id>] [--auth principal|service-key]
 
 Arguments:
   <domain>            Custom domain to release
@@ -89,6 +98,8 @@ Options:
                       project and clears its DNS/SSL configuration
                       (irreversible)
   --project <id>      Project ID (defaults to the active project)
+  --auth <mode>       principal (default, server-authoritative) or service-key
+                      (uses local project-key cache)
 
 Examples:
   run402 domains delete example.com --confirm
@@ -97,17 +108,26 @@ Examples:
 
 function parseProjectFlag(args, extraKnown = []) {
   const parsedArgs = normalizeArgv(args);
-  const valueFlags = ["--project"];
+  const valueFlags = ["--project", "--auth"];
   assertKnownFlags(parsedArgs, [...valueFlags, ...extraKnown, "--help", "-h"], valueFlags);
+  const auth = flagValue(parsedArgs, "--auth") ?? "principal";
+  if (auth !== "principal" && auth !== "service-key") {
+    fail({
+      code: "BAD_FLAG",
+      message: "--auth must be one of: principal, service-key.",
+      details: { flag: "--auth", value: auth, allowed: ["principal", "service-key"] },
+    });
+  }
   return {
     project: flagValue(parsedArgs, "--project"),
+    authMode: auth === "service-key" ? "service_key" : "principal",
     rest: positionalArgs(parsedArgs, valueFlags),
     args: parsedArgs,
   };
 }
 
 async function add(args) {
-  const { project, rest } = parseProjectFlag(args);
+  const { project, authMode, rest } = parseProjectFlag(args);
   const domain = rest[0];
   const subdomainName = rest[1];
   if (!domain || !subdomainName) {
@@ -122,7 +142,7 @@ async function add(args) {
   }
   const projectId = resolveProjectId(project);
   try {
-    const data = await getSdk().domains.add(projectId, { domain, subdomainName });
+    const data = await getSdk().domains.add(projectId, { domain, subdomainName, authMode });
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -131,7 +151,7 @@ async function add(args) {
 
 async function list(args) {
   const argList = Array.isArray(args) ? args : [];
-  const { project, rest } = parseProjectFlag(argList);
+  const { project, authMode, rest } = parseProjectFlag(argList);
   if (rest.length > 0) {
     fail({
       code: "BAD_USAGE",
@@ -141,7 +161,7 @@ async function list(args) {
   }
   const projectId = resolveProjectId(project);
   try {
-    const data = await getSdk().domains.list(projectId);
+    const data = await getSdk().domains.list(projectId, { authMode });
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -149,7 +169,7 @@ async function list(args) {
 }
 
 async function status(args) {
-  const { project, rest } = parseProjectFlag(args);
+  const { project, authMode, rest } = parseProjectFlag(args);
   const domain = rest[0];
   if (!domain) {
     fail({
@@ -163,7 +183,7 @@ async function status(args) {
   }
   const projectId = resolveProjectId(project);
   try {
-    const data = await getSdk().domains.status(projectId, domain);
+    const data = await getSdk().domains.status(projectId, domain, { authMode });
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -171,7 +191,7 @@ async function status(args) {
 }
 
 async function deleteDomain(args) {
-  const { project, rest, args: parsedArgs } = parseProjectFlag(args, ["--confirm"]);
+  const { project, authMode, rest, args: parsedArgs } = parseProjectFlag(args, ["--confirm"]);
   const domain = rest[0];
   if (!domain) {
     fail({
@@ -192,7 +212,7 @@ async function deleteDomain(args) {
   }
   const projectId = resolveProjectId(project);
   try {
-    await getSdk().domains.remove(domain, { projectId });
+    await getSdk().domains.remove(domain, { projectId, authMode });
     console.log(JSON.stringify({ domain, project_id: projectId, released: true }));
   } catch (err) {
     reportSdkError(err);

package/lib/next-actions.mjs

@@ -46,6 +46,13 @@ export function createProjectAction() {
   });
 }
 
+export function selectProjectAction() {
+  return nextAction("edit_request", {
+    command: "run402 projects use <project_id>",
+    why: "Select a server-visible project, or pass --project <project_id> on the command.",
+  });
+}
+
 export function setTierAction(tier = "prototype") {
   return nextAction("renew_tier", {
     command: `run402 tier set ${tier}`,

package/lib/projects.mjs

@@ -1,5 +1,5 @@
 import { readFileSync } from "fs";
-import { loadKeyStore, API, allowanceAuthHeaders, resolveProjectId, getActiveProjectId, isCoreApiTarget } from "./config.mjs";
+import { allowanceAuthHeaders, resolveProjectId, getActiveProjectId, isCoreApiTarget } from "./config.mjs";
 import { loadLiveOperatorSession } from "../core-dist/operator-session.js";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
 import { withAutoApprove } from "./operator.mjs";
@@ -19,8 +19,7 @@ Subcommands:
   list [--org <id>] [--all]               List your projects from the server (name, site_url, custom domains, org_id, active marker)
   rename <id> --name <label>              Rename a project (fix an auto-generated name)
   get   [id]                              Authoritative server read: status, org, tier, active deploy, mailbox, usage vs limits (live; no keys)
-  info  [id]                              Show local project details: REST URL, keys (local keystore only)
-  keys  [id]                              Print anon_key and service_key as JSON (local keystore only)
+  current                                 Show the active project pointer and validation status
   sql   [id] "<query>" [--file <path>] [--params '<json>']  Run a SQL query (supports parameterized queries)
   rest  [id] <table> [params]             Query a table via the REST API (PostgREST)
   usage [id]                              Show compute/storage usage for a project
@@ -45,7 +44,7 @@ Examples:
   run402 projects list --all
   run402 projects rename prj_abc123 --name "My Site"
   run402 projects get prj_abc123
-  run402 projects info prj_abc123
+  run402 projects current
   run402 projects sql prj_abc123 "SELECT * FROM users LIMIT 5"
   run402 projects sql prj_abc123 "SELECT * FROM users WHERE id = $1" --params '[42]'
   run402 projects sql prj_abc123 --file setup.sql
@@ -56,7 +55,6 @@ Examples:
   run402 projects validate-expose prj_abc123 --file manifest.json
   run402 projects apply-expose prj_abc123 --file manifest.json
   run402 projects get-expose prj_abc123
-  run402 projects keys prj_abc123
   run402 projects delete prj_abc123 --confirm
 
 Global options (any command):
@@ -69,7 +67,9 @@ Notes:
   - Most commands that take <id> default to the active project when omitted
     (set it with 'run402 projects use <id>'). Project IDs start with 'prj_';
     any first positional that doesn't is treated as the next argument instead.
-  - 'list' is a SERVER read, not the local keystore: it shows every project the
+  - 'list', 'get', and 'use' are SERVER-authoritative project identity flows.
+    Local project keys live under 'run402 credentials project-keys ...'.
+  - 'list' is a SERVER read, not the local key cache: it shows every project the
     active wallet can reach (membership-scoped), with name, site_url, custom
     domains, and org_id. '--org <id>' filters to one org; '--all' reads the
     cross-wallet inventory for every wallet controlling your operator email
@@ -129,7 +129,7 @@ Examples:
   run402 projects list --all
   run402 projects list --wallet work
 `,
-  rename: `run402 projects rename — Rename a project
+	  rename: `run402 projects rename — Rename a project
 
 Usage:
   run402 projects rename <id> --name <label>
@@ -147,6 +147,16 @@ Notes:
 
 Examples:
   run402 projects rename prj_abc123 --name "My Site"
+	`,
+  current: `run402 projects current — Inspect active project selection
+
+Usage:
+  run402 projects current
+
+Notes:
+  - The active project pointer is local non-secret profile state, not proof that
+    local project keys exist.
+  - The command attempts an authoritative server read and reports validation.
 `,
   provision: `run402 projects provision — Provision a new Postgres project
 
@@ -541,28 +551,55 @@ async function get(projectId) {
   }
 }
 
-async function info(projectId) {
+async function current() {
+  const projectId = getActiveProjectId();
+  const out = {
+    active_project_id: projectId ?? null,
+    source: "profile_state",
+    validation: { checked: false, ok: false },
+  };
+  if (!projectId) {
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
   try {
-    const data = await getSdk().projects.info(projectId);
-    console.log(JSON.stringify({
-      project_id: projectId,
-      rest_url: `${API}/rest/v1`,
-      anon_key: data.anon_key,
-      service_key: data.service_key,
-      site_url: data.site_url || null,
-    }, null, 2));
+    const detail = await getSdk().projects.get(projectId);
+    out.validation = { checked: true, ok: true };
+    out.project = detail;
   } catch (err) {
-    reportSdkError(err);
-  }
+    out.validation = {
+      checked: true,
+      ok: false,
+      code: err?.code ?? null,
+      message: err?.message ?? String(err),
+    };
+  }
+  console.log(JSON.stringify(out, null, 2));
 }
 
-async function keys(projectId) {
-  try {
-    const data = await getSdk().projects.keys(projectId);
-    console.log(JSON.stringify({ project_id: projectId, anon_key: data.anon_key, service_key: data.service_key }, null, 2));
-  } catch (err) {
-    reportSdkError(err);
-  }
+function commandMoved(name) {
+  fail({
+    code: "COMMAND_MOVED",
+    message: `run402 projects ${name} moved to the explicit local credential-cache surface.`,
+    hint: "Use `run402 credentials project-keys status/export --project <id>`.",
+    details: {
+      old_command: `projects ${name}`,
+      new_command: name === "keys" ? "credentials project-keys export --reveal" : "credentials project-keys status",
+      source: "local_cache",
+    },
+    next_actions: [
+      {
+        type: "run_command",
+        command: "run402 credentials project-keys status --project <id>",
+        why: "Inspect cached key presence without revealing secrets.",
+      },
+      {
+        type: "run_command",
+        command: "run402 credentials project-keys export --project <id> --reveal",
+        why: "Reveal cached project keys only when you explicitly need secret material.",
+      },
+    ],
+  });
 }
 
 async function sqlCmd(projectId, args = []) {
@@ -794,10 +831,11 @@ export async function run(sub, args) {
     case "provision": await provision(args); break;
     case "use":       await use(args[0]); break;
     case "list":      await list(args); break;
+    case "current":   await current(); break;
     case "rename":    { const { projectId, rest } = resolvePositionalProject(args, { rejectBareFirst: true, valueFlags: FLAGS_BY_SUB.rename.values }); await rename(projectId, rest); break; }
     case "get":       { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await get(projectId); break; }
-    case "info":      { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await info(projectId); break; }
-    case "keys":      { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await keys(projectId); break; }
+    case "info":      commandMoved("info"); break;
+    case "keys":      commandMoved("keys"); break;
     case "sql":       { const { projectId, rest } = resolvePositionalProject(args, { maxBarePositionals: 1, valueFlags: FLAGS_BY_SUB.sql.values, rejectBareFirstWhenFlagPresent: ["--file"] }); await sqlCmd(projectId, rest); break; }
     case "rest":      { const { projectId, rest: restArgs } = resolvePositionalProject(args); await rest(projectId, restArgs[0], restArgs[1]); break; }
     case "usage":     { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await usage(projectId); break; }

package/lib/sdk-errors.mjs

@@ -4,9 +4,8 @@
  * Maps SDK `Run402Error` subclasses into the CLI's canonical error envelope:
  * `{status: "error", code, message, retryable, safe_to_retry, ...}` on stderr,
  * `process.exit(1)`. Preserves specific behaviors:
- *   - `ProjectNotFound` → canonical envelope with `code: "PROJECT_NOT_FOUND"`
- *     and `details.source: "local_registry"` so callers can distinguish the
- *     local-registry miss from a gateway 404.
+ *   - `ProjectCredentialNotFound` → preserves
+ *     `code: "PROJECT_CREDENTIAL_NOT_FOUND"` and local-cache provenance.
  *   - HTML / non-JSON error bodies → `body_preview` field (first 500 chars),
  *     matching GH-84 behavior.
  *   - Network errors → `{status: "error", message: "..."}`.
@@ -66,6 +65,18 @@ export function parseFlagJson(name, value) {
 }
 
 export function reportSdkError(err) {
+  if (err?.name === "ProjectCredentialNotFound" || err?.code === "PROJECT_CREDENTIAL_NOT_FOUND") {
+    fail({
+      code: "PROJECT_CREDENTIAL_NOT_FOUND",
+      message: err?.message || "Local project credentials are not cached.",
+      hint: "This is a local credential-cache miss, not proof that the project does not exist. Use a principal-auth command, or import keys with `run402 credentials project-keys import --project <id> --service-key-stdin` for credential-required operations.",
+      details: err?.details,
+      next_actions: err?.nextActions,
+      retryable: err?.retryable ?? false,
+      safe_to_retry: err?.safeToRetry ?? true,
+    });
+  }
+
   if (err?.name === "ProjectNotFound") {
     const id = err.projectId || "";
     const hint = id && !String(id).startsWith("prj_")
@@ -117,6 +128,16 @@ export function reportSdkError(err) {
       "Returned as 403 even when the project does not exist, so verify the project id too.";
   }
 
+  if (typeof payload.code === "string" && payload.code.startsWith("PROJECT_CREDENTIAL_") && payload.hint === undefined) {
+    if (payload.code === "PROJECT_CREDENTIAL_PROJECT_MISMATCH") {
+      payload.hint =
+        "The supplied service key belongs to a different project than the explicit project id. Select the matching project key, or omit service-key mode and use the default principal-auth path when the command supports it.";
+    } else if (payload.code === "PROJECT_CREDENTIAL_INVALID" || payload.code === "PROJECT_CREDENTIAL_EXPIRED") {
+      payload.hint =
+        "The project credential was present but rejected by the server. Re-import or rotate the project key, or use a principal-auth command when available.";
+    }
+  }
+
   // Keep `status: "error"` as the outer envelope even if the response body
   // happened to contain its own `status` field (e.g. `{"status":"degraded"}`
   // from /health 503 responses). Downstream scripts match on this sentinel.