run402-mcp 3.7.13 → 3.8.0

package/dist/tools/project-key-cache-status.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { getSdk } from "../sdk.js";
+import { mapSdkError } from "../errors.js";
+export const projectKeyCacheStatusSchema = {
+    project_id: z.string().describe("Project ID to inspect in the local project-key credential cache"),
+};
+export async function handleProjectKeyCacheStatus(args) {
+    try {
+        const status = await getSdk().credentials.projectKeys.status(args.project_id);
+        const lines = [
+            `## Local Project-Key Cache: ${args.project_id}`,
+            ``,
+            `| Field | Value |`,
+            `|-------|-------|`,
+            `| source | \`${status.source}\` |`,
+            `| configured | ${status.configured} |`,
+            `| has_anon_key | ${status.has_anon_key} |`,
+            `| has_service_key | ${status.has_service_key} |`,
+            `| anon_key_prefix | ${status.anon_key_prefix ? `\`${status.anon_key_prefix}\`` : "(none)"} |`,
+            `| service_key_prefix | ${status.service_key_prefix ? `\`${status.service_key_prefix}\`` : "(none)"} |`,
+            `| anon_key_fingerprint | ${status.anon_key_fingerprint ? `\`${status.anon_key_fingerprint}\`` : "(none)"} |`,
+            `| service_key_fingerprint | ${status.service_key_fingerprint ? `\`${status.service_key_fingerprint}\`` : "(none)"} |`,
+            `| site_url | ${status.site_url ? `\`${status.site_url}\`` : "(none)"} |`,
+            `| cached_at | ${status.cached_at ?? "(unknown)"} |`,
+            `| profile | ${status.profile ? `\`${status.profile}\`` : "(unknown)"} |`,
+            `| cache_path | ${status.cache_path ? `\`${status.cache_path}\`` : "(unknown)"} |`,
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    catch (err) {
+        return mapSdkError(err, "reading local project-key cache status");
+    }
+}
+//# sourceMappingURL=project-key-cache-status.js.map

package/dist/tools/project-key-cache-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-key-cache-status.js","sourceRoot":"","sources":["../../src/tools/project-key-cache-status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iEAAiE,CAAC;CACnG,CAAC;AAIF,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,IAEjD;IACC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAE9E,MAAM,KAAK,GAAG;YACZ,+BAA+B,IAAI,CAAC,UAAU,EAAE;YAChD,EAAE;YACF,mBAAmB;YACnB,mBAAmB;YACnB,gBAAgB,MAAM,CAAC,MAAM,MAAM;YACnC,kBAAkB,MAAM,CAAC,UAAU,IAAI;YACvC,oBAAoB,MAAM,CAAC,YAAY,IAAI;YAC3C,uBAAuB,MAAM,CAAC,eAAe,IAAI;YACjD,uBAAuB,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,eAAe,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI;YAC9F,0BAA0B,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,kBAAkB,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI;YACvG,4BAA4B,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,oBAAoB,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI;YAC7G,+BAA+B,MAAM,CAAC,uBAAuB,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,uBAAuB,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI;YACtH,gBAAgB,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI;YACzE,iBAAiB,MAAM,CAAC,SAAS,IAAI,WAAW,IAAI;YACpD,eAAe,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI;YACzE,kBAAkB,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI;SACnF,CAAC;QAEF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;IACjE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,WAAW,CAAC,GAAG,EAAE,wCAAwC,CAAC,CAAC;IACpE,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402-mcp",
-  "version": "3.7.13",
+  "version": "3.8.0",
   "description": "MCP server for Run402 — AI-native Postgres databases with REST API, auth, storage, and row-level security. Pay with x402 USDC micropayments.",
   "type": "module",
   "main": "dist/index.js",

package/sdk/README.md

@@ -10,7 +10,7 @@ npm install @run402/sdk
 
 | Import | Use when |
 |---|---|
-| `@run402/sdk/node` | Running in Node 22 with the local keystore + allowance. Auto-loads the configured API base, `~/.config/run402/projects.json`, and signs x402 payments from `~/.config/run402/allowance.json`. Includes `r.actions.run(...)`, `r.up(...)`, `r.sites.deployDir(dir)`, `fileSetFromDir(dir)`, `loadDeployManifest(path)`, `normalizeDeployManifest(input)`, and `resolveRun402TargetProfile()`. |
+| `@run402/sdk/node` | Running in Node 22 with the local profile state, project-key credential cache, and allowance. Auto-loads the configured API base, profile `credentials/project-keys.v1.json`, and signs x402 payments from `~/.config/run402/allowance.json`. Includes `r.actions.run(...)`, `r.up(...)`, `r.sites.deployDir(dir)`, `fileSetFromDir(dir)`, `loadDeployManifest(path)`, `normalizeDeployManifest(input)`, and `resolveRun402TargetProfile()`. |
 | `@run402/sdk` | Isomorphic — works in Node, Deno, Bun, V8 isolates. No filesystem access. Bring your own `CredentialsProvider` (a session-token shim, a remote vault, anything that resolves project keys + auth headers). |
 
 ## Quick start (Node)
@@ -58,7 +58,7 @@ await r.up(
 
 For a self-hosted Run402 Core Gateway, run `run402 init --api-base=http://my-core:4020` once. The Node SDK then targets that API base by default; explicit `run402({ apiBase })` still wins.
 
-App build scripts should use the same target/profile store instead of parsing `target.json` or `projects.json`:
+App build scripts should use the same target/profile store instead of parsing `target.json` or project-key cache files:
 
 ```ts
 import { resolveRun402TargetProfile } from "@run402/sdk/node";
@@ -89,6 +89,8 @@ resolveRun402TargetProfile({
 
 Most operations are project-scoped. Bind once and skip the id arg on every call:
 
+`r.projects.list()` and `r.projects.get(id)` are server-authoritative project reads. `r.projects.use(id)` validates the project with the current principal and stores only an active project id in profile state; it does not require local project-key cache membership. `r.project(id)` binds the id without local lookup. Each namespace then follows its declared auth mode: control-plane operations such as custom domains default to principal/delegate auth with explicit `project_id`, while true data-plane/key operations use local project credentials and fail with `PROJECT_CREDENTIAL_NOT_FOUND` when the selected profile lacks cached keys.
+
 ```ts
 const p = await r.useProject(projectId);                                  // persists active project + returns scoped handle
 await p.assets.put("hello.txt", { content: "hi" });                       // no projectId arg
@@ -98,6 +100,18 @@ await p.apply({ site: { replace: files({ "index.html": "<h1>hi</h1>" }) } });
 
 `r.useProject(id)` writes the active project to the keystore (shared with concurrent CLI runs). For transient in-script scoping that does NOT mutate that state, use `r.project(id)` (or `r.project()` with no arg to resolve from whatever the keystore currently considers active).
 
+Local project keys live behind an explicit credential-cache namespace. These helpers are local/offline and are not authoritative project reads:
+
+```ts
+const status = await r.credentials.projectKeys.status(projectId); // redacted
+const serviceKey = process.env.RUN402_SERVICE_KEY!;
+await r.credentials.projectKeys.import(projectId, { serviceKey });
+const keys = await r.credentials.projectKeys.export(projectId, { reveal: true });
+await r.credentials.projectKeys.remove(projectId);
+```
+
+`status`/`list` report `source: "local_cache"`, profile/cache-path provenance, key presence, prefixes, and fingerprints without full secrets. `export(..., { reveal: true })` is the only SDK helper that emits cached secret key material.
+
 ## Quick start (isomorphic)
 
 ```ts
@@ -119,7 +133,8 @@ The `CredentialsProvider` interface has two required methods (`getAuth`, `getPro
 | Namespace | Highlights |
 |---|---|
 | `actions` | Node entry only (`@run402/sdk/node`). Generic recursive action runner: `actions.run({ type: Run402Action.Up | ProjectsProvision | TierSet, ... })`; `r.up(input, opts)` is the convenience for repo-level manifest deploys. Recursive mutations are approval-gated; `mode: "check" | "printSpec" | "plan" | { kind: "applyReviewed" }` distinguishes local validation, gateway review, and exact reviewed apply. Child gateway mutations derive idempotency keys from the root action. |
-| `projects` | `provision`, `delete`, `list`, `sql`, `rest`, `validateExpose`, `applyExpose`, `getExpose`, `getUsage`, `getSchema`, `info`, `keys`, `use`, `active`, `pin`, `getQuote` |
+| `projects` | `provision`, `delete`, `list`, `get`, `use`, `active`, `sql`, `rest`, `validateExpose`, `applyExpose`, `getExpose`, `getUsage`, `getSchema`, `info`, `keys`, `pin`, `getQuote`. `list`/`get`/`use` are server-authoritative; local key reads are moving to `credentials.projectKeys`. |
+| `credentials` | `projectKeys.list`, `projectKeys.status`, `projectKeys.import`, `projectKeys.export`, `projectKeys.remove` for explicit local project-key cache management. |
 | `r.project(id).apply` | **The unified apply primitive.** Callable hero — `r.project(id).apply(spec)` for atomic mixed writes (release slices + assets slice). Sub-methods: `.plan`, `.start`, `.resume`, `.upload`, `.commit`, `.status`, `.list`, `.events`, `.resolve`, `.getRelease`, `.getActiveRelease`, `.diff`. Underlying engine routes to `/apply/v1/*`. |
 | `ci` | GitHub Actions OIDC federation over `/ci/v1/*`: `createBinding`, `listBindings`, `getBinding`, `revokeBinding`, `exchangeToken`; plus canonical delegation helpers. `createBinding` accepts `asset_key_scopes` for per-key CI write authorization. |
 | `r.project(id).sites` | `deployDir` — Node entry only (`@run402/sdk/node`); thin wrapper over `r.project(id).apply({ site: dir(...) })` |
@@ -577,13 +592,16 @@ All failures throw subclasses of `Run402Error`. Every subclass carries a stable
 | Class | `kind` | When | Notable fields |
 |---|---|---|---|
 | `PaymentRequired` | `"payment_required"` | HTTP 402 | x402 payment requirements in `body` |
-| `ProjectNotFound` | `"project_not_found"` | Project ID not in the credential provider | `projectId` |
+| `ProjectNotFound` | `"project_not_found"` | Server-authoritative project lookup/authorization reports not found or hidden | `projectId` |
+| `ProjectCredentialNotFound` | `"local_error"` | A local project-key cache entry is required but missing for the selected profile | `projectId`, `details.source="local_cache"`, `nextActions` |
 | `Unauthorized` | `"unauthorized"` | HTTP 401 / 403 | — |
 | `ApiError` | `"api_error"` | Other non-2xx responses | `status`, `body` |
 | `NetworkError` | `"network_error"` | Fetch rejected with no HTTP response | `cause` |
 | `LocalError` | `"local_error"` | Local-host issues (filesystem, signing) | `cause` |
 | `Run402DeployError` | `"deploy_error"` | Structured envelope from the deploy state machine (v1.34+) | `code`, `phase`, `operationId`, `safeToRetry`, `mutationState`, `nextActions` |
 
+Project credential codes are deliberately distinct from project existence/authz. Branch on `isProjectCredentialNotFound`, `isProjectCredentialInvalid`, `isProjectCredentialExpired`, `isProjectCredentialProjectMismatch`, or the broad `isProjectCredentialError`. Gateway-returned `PROJECT_CREDENTIAL_INVALID`, `PROJECT_CREDENTIAL_EXPIRED`, and `PROJECT_CREDENTIAL_PROJECT_MISMATCH` pass through unchanged; the SDK does not rewrite them to `PROJECT_CREDENTIAL_NOT_FOUND`.
+
 **Branch with type guards, not `instanceof`.** `instanceof X` is an identity
 check on the class object — it fails silently when the consumer's runtime
 holds a different copy of the SDK (duplicate npm installs, bundler chunk

package/sdk/core-dist/config.d.ts

@@ -45,6 +45,9 @@ export declare function getProfilesDir(): string;
  */
 export declare function getConfigDir(): string;
 export declare function getKeystorePath(): string;
+export declare function getLegacyProjectsPath(): string;
+export declare function getProjectCredentialsPath(): string;
+export declare function getProfileStatePath(): string;
 export declare function getApiTargetConfigPath(): string;
 export declare function readApiTargetConfig(path?: string): ApiTargetConfig | null;
 export declare function saveApiTargetConfig(config: ApiTargetConfig, path?: string): void;

package/sdk/core-dist/config.js

@@ -119,8 +119,17 @@ export function getConfigDir() {
     return profile === DEFAULT_PROFILE ? base : join(base, "profiles", profile);
 }
 export function getKeystorePath() {
+    return getProjectCredentialsPath();
+}
+export function getLegacyProjectsPath() {
     return join(getConfigDir(), "projects.json");
 }
+export function getProjectCredentialsPath() {
+    return join(getConfigDir(), "credentials", "project-keys.v1.json");
+}
+export function getProfileStatePath() {
+    return join(getConfigDir(), "state.json");
+}
 export function getApiTargetConfigPath() {
     return join(getConfigDir(), "target.json");
 }

package/sdk/core-dist/keystore.d.ts

@@ -4,17 +4,25 @@ export interface StoredProject {
     site_url?: string;
     deployed_at?: string;
     last_deployment_id?: string;
+    cached_at?: string;
+    source?: string;
 }
 export interface KeyStore {
+    version?: 1;
+    source?: "local_cache";
     active_project_id?: string;
     previous_active_project_id?: string;
     projects: Record<string, StoredProject>;
+    migrated_from?: string;
+    migrated_at?: string;
 }
 /**
- * Load the keystore from disk.
- * Auto-migrates legacy formats:
+ * Load the project-key credential cache from disk.
+ * Auto-imports legacy `projects.json` formats into the new cache path when using
+ * the default location:
  * - Array format (CLI legacy): [{project_id, ...}] → {projects: {id: {...}}}
- * - Old field name: expires_at → lease_expires_at
+ * - Object format: {active_project_id, projects} → credentials cache + state.json
+ * - Old metadata fields: tier/expires_at/lease_expires_at are stripped
  */
 export declare function loadKeyStore(path?: string): KeyStore;
 export declare function saveKeyStore(store: KeyStore, path?: string): void;

package/sdk/core-dist/keystore.js

@@ -1,7 +1,8 @@
-import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, rmdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, rmdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
-import { getKeystorePath } from "./config.js";
+import { getLegacyProjectsPath, getProjectCredentialsPath } from "./config.js";
+import { clearActiveProjectId as clearProfileActiveProjectId, getActiveProjectId as getProfileActiveProjectId, recordMigration, setActiveProjectId as setProfileActiveProjectId, } from "./profile-state.js";
 function withFileLock(path, fn, { retries = 200, delayMs = 20 } = {}) {
     const lockDir = path + ".lock";
     mkdirSync(dirname(path), { recursive: true });
@@ -29,56 +30,107 @@ function withFileLock(path, fn, { retries = 200, delayMs = 20 } = {}) {
     }
     throw new Error(`Could not acquire keystore lock after ${retries} retries: ${lockDir}`);
 }
-/**
- * Load the keystore from disk.
- * Auto-migrates legacy formats:
- * - Array format (CLI legacy): [{project_id, ...}] → {projects: {id: {...}}}
- * - Old field name: expires_at → lease_expires_at
- */
-export function loadKeyStore(path) {
-    const p = path ?? getKeystorePath();
-    try {
-        const data = readFileSync(p, "utf-8");
-        const parsed = JSON.parse(data);
-        if (Array.isArray(parsed)) {
-            const projects = {};
-            for (const item of parsed) {
-                if (item.project_id) {
-                    projects[item.project_id] = {
-                        anon_key: item.anon_key,
-                        service_key: item.service_key,
-                        ...(item.site_url && { site_url: item.site_url }),
-                        ...(item.deployed_at && { deployed_at: item.deployed_at }),
-                    };
-                }
+function normalizeParsedKeyStore(parsed) {
+    if (Array.isArray(parsed)) {
+        const projects = {};
+        for (const item of parsed) {
+            if (item.project_id) {
+                projects[item.project_id] = {
+                    anon_key: item.anon_key,
+                    service_key: item.service_key,
+                    ...(item.site_url && { site_url: item.site_url }),
+                    ...(item.deployed_at && { deployed_at: item.deployed_at }),
+                    cached_at: new Date().toISOString(),
+                    source: "legacy_projects_json",
+                };
             }
-            return { projects };
         }
-        if (parsed && typeof parsed === "object" && parsed.projects) {
-            for (const proj of Object.values(parsed.projects)) {
-                const rec = proj;
-                delete rec.tier;
-                delete rec.lease_expires_at;
-                delete rec.expires_at;
-            }
-            return {
-                ...(parsed.active_project_id && { active_project_id: parsed.active_project_id }),
-                ...(parsed.previous_active_project_id && { previous_active_project_id: parsed.previous_active_project_id }),
-                projects: parsed.projects,
-            };
+        return { version: 1, source: "local_cache", projects };
+    }
+    if (parsed && typeof parsed === "object" && "projects" in parsed) {
+        const obj = parsed;
+        const rawProjects = obj.projects && typeof obj.projects === "object" && !Array.isArray(obj.projects)
+            ? obj.projects
+            : {};
+        const projects = {};
+        for (const [id, proj] of Object.entries(rawProjects)) {
+            const rec = { ...proj };
+            delete rec.tier;
+            delete rec.lease_expires_at;
+            delete rec.expires_at;
+            projects[id] = rec;
         }
-        return { projects: {} };
+        return {
+            version: 1,
+            source: "local_cache",
+            ...(typeof obj.active_project_id === "string" && { active_project_id: obj.active_project_id }),
+            ...(typeof obj.previous_active_project_id === "string" && { previous_active_project_id: obj.previous_active_project_id }),
+            projects,
+            ...(typeof obj.migrated_from === "string" && { migrated_from: obj.migrated_from }),
+            ...(typeof obj.migrated_at === "string" && { migrated_at: obj.migrated_at }),
+        };
+    }
+    return { version: 1, source: "local_cache", projects: {} };
+}
+function loadParsedKeyStore(path) {
+    try {
+        return normalizeParsedKeyStore(JSON.parse(readFileSync(path, "utf-8")));
     }
     catch {
-        return { projects: {} };
+        return { version: 1, source: "local_cache", projects: {} };
     }
 }
+function migrateLegacyProjectsJson(targetPath) {
+    const legacyPath = getLegacyProjectsPath();
+    if (existsSync(targetPath) || !existsSync(legacyPath))
+        return;
+    const legacy = loadParsedKeyStore(legacyPath);
+    const migratedAt = new Date().toISOString();
+    const cache = {
+        version: 1,
+        source: "local_cache",
+        projects: legacy.projects,
+        migrated_from: legacyPath,
+        migrated_at: migratedAt,
+    };
+    saveKeyStore(cache, targetPath);
+    if (legacy.active_project_id) {
+        setProfileActiveProjectId(legacy.active_project_id);
+    }
+    recordMigration("projects_json_import", {
+        legacy_path: legacyPath,
+        cache_path: targetPath,
+        project_count: Object.keys(legacy.projects).length,
+        imported_at: migratedAt,
+    });
+}
+/**
+ * Load the project-key credential cache from disk.
+ * Auto-imports legacy `projects.json` formats into the new cache path when using
+ * the default location:
+ * - Array format (CLI legacy): [{project_id, ...}] → {projects: {id: {...}}}
+ * - Object format: {active_project_id, projects} → credentials cache + state.json
+ * - Old metadata fields: tier/expires_at/lease_expires_at are stripped
+ */
+export function loadKeyStore(path) {
+    const p = path ?? getProjectCredentialsPath();
+    if (!path)
+        migrateLegacyProjectsJson(p);
+    return loadParsedKeyStore(p);
+}
 export function saveKeyStore(store, path) {
-    const p = path ?? getKeystorePath();
+    const p = path ?? getProjectCredentialsPath();
     const dir = dirname(p);
     mkdirSync(dir, { recursive: true });
-    const tmp = join(dir, `.projects.${randomBytes(4).toString("hex")}.tmp`);
-    writeFileSync(tmp, JSON.stringify(store, null, 2), { mode: 0o600 });
+    const cache = {
+        version: 1,
+        source: "local_cache",
+        ...(store.migrated_from ? { migrated_from: store.migrated_from } : {}),
+        ...(store.migrated_at ? { migrated_at: store.migrated_at } : {}),
+        projects: store.projects,
+    };
+    const tmp = join(dir, `.project-keys.${randomBytes(4).toString("hex")}.tmp`);
+    writeFileSync(tmp, JSON.stringify(cache, null, 2), { mode: 0o600 });
     renameSync(tmp, p);
     chmodSync(p, 0o600);
 }
@@ -87,55 +139,38 @@ export function getProject(projectId, path) {
     return store.projects[projectId];
 }
 export function saveProject(projectId, project, path) {
-    const p = path ?? getKeystorePath();
+    const p = path ?? getProjectCredentialsPath();
     withFileLock(p, () => {
         const store = loadKeyStore(p);
-        store.projects[projectId] = project;
+        store.projects[projectId] = { ...project, cached_at: project.cached_at ?? new Date().toISOString() };
         saveKeyStore(store, p);
     });
 }
 export function updateProject(projectId, update, path) {
-    const p = path ?? getKeystorePath();
+    const p = path ?? getProjectCredentialsPath();
     withFileLock(p, () => {
         const store = loadKeyStore(p);
         const existing = store.projects[projectId];
         if (existing) {
-            store.projects[projectId] = { ...existing, ...update };
+            store.projects[projectId] = { ...existing, ...update, cached_at: existing.cached_at ?? new Date().toISOString() };
             saveKeyStore(store, p);
         }
     });
 }
 export function removeProject(projectId, path) {
-    const p = path ?? getKeystorePath();
+    const p = path ?? getProjectCredentialsPath();
     withFileLock(p, () => {
         const store = loadKeyStore(p);
         delete store.projects[projectId];
-        if (store.active_project_id === projectId) {
-            const fallback = store.previous_active_project_id;
-            if (fallback && fallback !== projectId && store.projects[fallback]) {
-                store.active_project_id = fallback;
-            }
-            else {
-                delete store.active_project_id;
-            }
-            delete store.previous_active_project_id;
-        }
         saveKeyStore(store, p);
     });
+    if (!path)
+        clearProfileActiveProjectId(projectId);
 }
 export function getActiveProjectId(path) {
-    const store = loadKeyStore(path);
-    return store.active_project_id;
+    return getProfileActiveProjectId(path);
 }
 export function setActiveProjectId(projectId, path) {
-    const p = path ?? getKeystorePath();
-    withFileLock(p, () => {
-        const store = loadKeyStore(p);
-        if (store.active_project_id && store.active_project_id !== projectId) {
-            store.previous_active_project_id = store.active_project_id;
-        }
-        store.active_project_id = projectId;
-        saveKeyStore(store, p);
-    });
+    setProfileActiveProjectId(projectId, path);
 }
 //# sourceMappingURL=keystore.js.map

package/sdk/core-dist/profile-state.d.ts

@@ -0,0 +1,29 @@
+export interface ActiveProjectScope {
+    api_base?: string;
+    principal?: string | null;
+    profile?: string;
+}
+export interface ActiveProjectState {
+    project_id: string;
+    previous_project_id?: string;
+    api_base: string;
+    principal?: string | null;
+    profile: string;
+    updated_at: string;
+}
+export interface ProfileState {
+    version?: 1;
+    active_project_id?: string;
+    previous_active_project_id?: string;
+    active_projects?: Record<string, ActiveProjectState>;
+    migrations?: Record<string, unknown>;
+}
+export declare function loadProfileState(path?: string): ProfileState;
+export declare function saveProfileState(state: ProfileState, path?: string): void;
+export declare function defaultActiveProjectScope(scope?: ActiveProjectScope): Required<Pick<ActiveProjectScope, "api_base" | "profile">> & Pick<ActiveProjectScope, "principal">;
+export declare function activeProjectScopeKey(scope?: ActiveProjectScope): string;
+export declare function getActiveProjectId(path?: string, scope?: ActiveProjectScope): string | undefined;
+export declare function setActiveProjectId(projectId: string, path?: string, scope?: ActiveProjectScope): void;
+export declare function clearActiveProjectId(projectId: string, path?: string, scope?: ActiveProjectScope): void;
+export declare function recordMigration(marker: string, value: unknown, path?: string): void;
+//# sourceMappingURL=profile-state.d.ts.map

package/sdk/core-dist/profile-state.js

@@ -0,0 +1,137 @@
+import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, rmdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { getActiveProfile, getApiBase, getProfileStatePath } from "./config.js";
+function withFileLock(path, fn, { retries = 200, delayMs = 20 } = {}) {
+    const lockDir = path + ".lock";
+    mkdirSync(dirname(path), { recursive: true });
+    for (let i = 0; i < retries; i++) {
+        try {
+            mkdirSync(lockDir, { mode: 0o700 });
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "EEXIST")
+                throw e;
+            const until = Date.now() + delayMs;
+            while (Date.now() < until) { /* spin */ }
+            continue;
+        }
+        try {
+            return fn();
+        }
+        finally {
+            try {
+                rmdirSync(lockDir);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    throw new Error(`Could not acquire profile-state lock after ${retries} retries: ${lockDir}`);
+}
+export function loadProfileState(path) {
+    const p = path ?? getProfileStatePath();
+    try {
+        const parsed = JSON.parse(readFileSync(p, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+export function saveProfileState(state, path) {
+    const p = path ?? getProfileStatePath();
+    const dir = dirname(p);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.state.${randomBytes(4).toString("hex")}.tmp`);
+    writeFileSync(tmp, JSON.stringify({ version: 1, ...state }, null, 2), { mode: 0o600 });
+    renameSync(tmp, p);
+    chmodSync(p, 0o600);
+}
+export function defaultActiveProjectScope(scope = {}) {
+    return {
+        api_base: scope.api_base ?? getApiBase(),
+        profile: scope.profile ?? getActiveProfile(),
+        principal: scope.principal ?? null,
+    };
+}
+export function activeProjectScopeKey(scope = {}) {
+    const resolved = defaultActiveProjectScope(scope);
+    return JSON.stringify({
+        api_base: resolved.api_base,
+        profile: resolved.profile,
+        principal: resolved.principal ?? "unknown",
+    });
+}
+export function getActiveProjectId(path, scope = {}) {
+    const state = loadProfileState(path);
+    const key = activeProjectScopeKey(scope);
+    return state.active_projects?.[key]?.project_id ?? state.active_project_id;
+}
+export function setActiveProjectId(projectId, path, scope = {}) {
+    const p = path ?? getProfileStatePath();
+    withFileLock(p, () => {
+        const state = loadProfileState(p);
+        const key = activeProjectScopeKey(scope);
+        const resolved = defaultActiveProjectScope(scope);
+        const current = state.active_projects?.[key]?.project_id ?? state.active_project_id;
+        const previous = current && current !== projectId ? current : undefined;
+        state.active_projects = state.active_projects ?? {};
+        state.active_projects[key] = {
+            project_id: projectId,
+            ...(previous ? { previous_project_id: previous } : {}),
+            api_base: resolved.api_base,
+            principal: resolved.principal ?? null,
+            profile: resolved.profile,
+            updated_at: new Date().toISOString(),
+        };
+        state.active_project_id = projectId;
+        if (previous)
+            state.previous_active_project_id = previous;
+        else
+            delete state.previous_active_project_id;
+        saveProfileState(state, p);
+    });
+}
+export function clearActiveProjectId(projectId, path, scope = {}) {
+    const p = path ?? getProfileStatePath();
+    withFileLock(p, () => {
+        const state = loadProfileState(p);
+        const key = activeProjectScopeKey(scope);
+        const scoped = state.active_projects?.[key];
+        if (scoped?.project_id === projectId && state.active_projects) {
+            if (scoped.previous_project_id) {
+                state.active_projects[key] = {
+                    ...scoped,
+                    project_id: scoped.previous_project_id,
+                    previous_project_id: undefined,
+                    updated_at: new Date().toISOString(),
+                };
+            }
+            else {
+                delete state.active_projects[key];
+            }
+        }
+        if (state.active_project_id === projectId) {
+            if (state.previous_active_project_id && state.previous_active_project_id !== projectId) {
+                state.active_project_id = state.previous_active_project_id;
+            }
+            else {
+                delete state.active_project_id;
+            }
+            delete state.previous_active_project_id;
+        }
+        saveProfileState(state, p);
+    });
+}
+export function recordMigration(marker, value, path) {
+    const p = path ?? getProfileStatePath();
+    withFileLock(p, () => {
+        const state = loadProfileState(p);
+        state.migrations = { ...(state.migrations ?? {}), [marker]: value };
+        saveProfileState(state, p);
+    });
+}
+//# sourceMappingURL=profile-state.js.map

package/sdk/dist/credentials.d.ts

@@ -2,15 +2,15 @@
  * Credential provider interface for the Run402 SDK.
  *
  * The SDK's request kernel calls `getAuth` before each request to obtain
- * signed auth headers, and `getProject` to resolve per-project anon/service
- * keys. All filesystem, environment, and session-state access lives inside
- * provider implementations — never in the kernel.
+ * signed auth headers, and `getProjectCredentials` to resolve per-project
+ * anon/service keys. All filesystem, environment, and session-state access
+ * lives inside provider implementations — never in the kernel.
  *
  * Node consumers use {@link NodeCredentialsProvider} from `@run402/sdk/node`
  * which wraps the local keystore + allowance. Sandbox consumers supply their
  * own implementation bound to a session token issued by the supervisor.
  *
- * The two required methods (`getAuth`, `getProject`) support every API call.
+ * The two required methods (`getAuth`, `getProjectCredentials`) support every API call.
  * The optional methods let providers opt in to local persistence (keystore
  * writes, active-project tracking). Namespace methods that need a missing
  * optional method throw a descriptive error at runtime.
@@ -23,6 +23,13 @@ export interface ProjectKeys {
     last_deployment_id?: string;
     mailbox_id?: string;
     mailbox_address?: string;
+    cached_at?: string;
+}
+export interface ProjectCredentialCacheInfo {
+    source: "local_cache";
+    cache_path?: string;
+    wallet?: string;
+    profile?: string;
 }
 export interface AllowanceData {
     address: string;
@@ -78,10 +85,18 @@ export interface CredentialsProvider {
      */
     getAuth(path: string, metadata?: AuthRequestMeta): Promise<Record<string, string> | null>;
     /**
-     * Resolve the anon/service keys for a project. Returns null if the project
-     * is not known to this provider — the kernel then throws ProjectNotFound.
+     * Resolve the anon/service keys for a project. Returns null when local
+     * credentials are absent. This is a credential-cache lookup, not a project
+     * existence check.
+     */
+    getProjectCredentials?(id: string): Promise<ProjectKeys | null>;
+    /**
+     * @deprecated Use `getProjectCredentials`. This alias is retained only for
+     * older custom providers; first-party SDK code must use the explicit name.
      */
-    getProject(id: string): Promise<ProjectKeys | null>;
+    getProject?(id: string): Promise<ProjectKeys | null>;
+    /** List locally cached project credentials. Optional and local-cache only; not project inventory. */
+    listProjectCredentials?(): Promise<Record<string, ProjectKeys>>;
     /**
      * Persist project keys after a successful provision or deploy. Optional:
      * providers without local storage (pure session providers) may omit this.
@@ -103,6 +118,8 @@ export interface CredentialsProvider {
     createAllowance?(): Promise<AllowanceData>;
     /** Return the absolute path to the local allowance file, for diagnostic output. Optional. */
     getAllowancePath?(): string;
+    /** Return safe provenance for the local project credential cache. Optional. */
+    getProjectCredentialCacheInfo?(): ProjectCredentialCacheInfo;
     /**
      * Return the active wallet's display identity (local name + address + cached
      * server label). The Node provider derives this from the active profile;