run402-mcp 4.93.2 → 4.95.0

package/sdk/core-dist/control-plane-session.d.ts

@@ -1,33 +1,40 @@
 /**
- * A cached **control-plane session** — the human principal's bearer, minted by
- * the loopback-PKCE flow (`run402 operator login --loopback`). Distinct from the
- * device-flow {@link OperatorSession} (read-only): this one carries `provenance`
- * (`loopback_pkce`) and `amr`. It authorizes most control-plane operations, but
- * since gateway v1.85/v1.87 it is NOT sufficient on its own for the high-stakes
- * writes `provision` / `deploy` / secrets — those additionally require a
- * passkey-fresh **operator approval** (`X-Run402-Write-Auth`, minted by
- * `run402 operator approve`; see {@link WriteAuthApproval}). Cached at the BASE
- * config dir (email/principal-scoped, shared across local named wallets), mode
- * 0600 — the token is as sensitive as the allowance key.
+ * The cached **sign-in session** — a person's one Run402 session, bound to
+ * their principal and graded by how it was minted: `loopback` (`run402 login`,
+ * the loopback-PKCE browser ceremony; full, step-up-able) or `device`
+ * (`run402 login --device`, RFC 8628; read-only — the gateway refuses every
+ * mutation with `SESSION_READ_ONLY`). The wire token class is
+ * `control_plane_session`. The session authorizes most control-plane writes,
+ * but provisioning, deploying, and writing secrets additionally need a
+ * passkey-signed **write approval** (`X-Run402-Write-Approval`, minted by
+ * `run402 approve`; see `write-approvals.ts`). Cached at the BASE config dir
+ * (principal-scoped, shared across local named wallets), mode 0600 — the token
+ * is as sensitive as the wallet key.
  *
  * Stored shape vs the gateway payload: the gateway returns a relative
  * `expires_in` (seconds); we persist the absolute `expires_at` (epoch ms) so a
  * cached session can be expiry-checked without knowing when it was written.
  */
+/** How a sign-in session was minted, as the gateway reports it. */
+export type SessionGrade = "browser" | "loopback" | "device";
 export interface ControlPlaneSessionCache {
     control_plane_session_token: string;
     token_type: string;
-    provenance: string;
+    grade: SessionGrade;
     principal_id: string;
     amr: string[];
     /** Epoch ms when the session expires (issued_at + expires_in). */
     expires_at: number;
 }
-/** The token payload returned by `POST /agent/v1/control-plane/cli/token`. */
+/**
+ * The token payload returned by `POST /agent/v1/control-plane/cli/token`
+ * (grade `loopback`) and `POST /agent/v1/control-plane/cli/device/token`
+ * (grade `device`).
+ */
 export interface ControlPlaneSessionTokenResponse {
     control_plane_session_token: string;
     token_type?: string;
-    provenance?: string;
+    grade?: string;
     principal_id?: string;
     amr?: string[];
     expires_in?: number;
@@ -45,7 +52,7 @@ export declare function getControlPlaneSessionPath(): string;
 export declare function readControlPlaneSession(path?: string): ControlPlaneSessionCache | null;
 /** Persist a control-plane session atomically (temp-file + rename), mode 0600. */
 export declare function saveControlPlaneSession(data: ControlPlaneSessionCache, path?: string): void;
-/** Delete the cached control-plane session — local half of `operator logout`. Idempotent. */
+/** Delete the cached sign-in session — local half of `run402 logout`. Idempotent. */
 export declare function clearControlPlaneSession(path?: string): void;
 /** Whether a cached session is past its usable life (with a small skew buffer). */
 export declare function isControlPlaneSessionExpired(session: ControlPlaneSessionCache, nowMs?: number, skewMs?: number): boolean;
@@ -53,4 +60,12 @@ export declare function isControlPlaneSessionExpired(session: ControlPlaneSessio
 export declare function loadLiveControlPlaneSession(path?: string, nowMs?: number): ControlPlaneSessionCache | null;
 /** Map a gateway token payload (relative `expires_in`) into the cached shape (absolute `expires_at`). */
 export declare function controlPlaneSessionFromTokenResponse(resp: ControlPlaneSessionTokenResponse, nowMs?: number): ControlPlaneSessionCache;
+/**
+ * Delete the session caches of the retired email-scoped session
+ * (`{base}/operator-session.json`) and the retired approval cache file
+ * (`{base}/write-auth-session.json`). Neither is read any more; `run402 login`
+ * and `run402 logout` call this so a stale token does not linger on disk.
+ * Best-effort and idempotent.
+ */
+export declare function clearRetiredSessionCaches(): void;
 //# sourceMappingURL=control-plane-session.d.ts.map

package/sdk/core-dist/control-plane-session.js

@@ -10,6 +10,14 @@ export function getControlPlaneSessionPath() {
     return (process.env.RUN402_CONTROL_PLANE_SESSION_PATH ||
         join(getConfigBaseDir(), "control-plane-session.json"));
 }
+/**
+ * Read a wire grade. An unknown or absent value is treated as `device` (the
+ * read-only grade) so a cache the client cannot classify never claims more
+ * authority than the gateway will grant.
+ */
+function toGrade(raw) {
+    return raw === "browser" || raw === "loopback" || raw === "device" ? raw : "device";
+}
 /** Tighten 0600 if group/other-readable, warning once. Best-effort, POSIX-only. */
 function selfHealPermissions(p) {
     if (process.platform === "win32")
@@ -50,20 +58,20 @@ export function readControlPlaneSession(path) {
         return null;
     }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("control-plane-session.json must contain a JSON object. Delete it and run 'run402 operator login --loopback' to recreate it.");
+        throw new Error("control-plane-session.json must contain a JSON object. Delete it and run 'run402 login' to recreate it.");
     }
     const data = parsed;
     if (typeof data.control_plane_session_token !== "string" ||
         data.control_plane_session_token.length === 0) {
-        throw new Error("control-plane-session.json missing valid 'control_plane_session_token'. Run 'run402 operator login --loopback' to refresh it.");
+        throw new Error("control-plane-session.json missing valid 'control_plane_session_token'. Run 'run402 login' to refresh it.");
     }
     if (typeof data.expires_at !== "number" || !Number.isFinite(data.expires_at)) {
-        throw new Error("control-plane-session.json missing valid 'expires_at'. Run 'run402 operator login --loopback' to refresh it.");
+        throw new Error("control-plane-session.json missing valid 'expires_at'. Run 'run402 login' to refresh it.");
     }
     return {
         control_plane_session_token: data.control_plane_session_token,
         token_type: typeof data.token_type === "string" ? data.token_type : "Bearer",
-        provenance: typeof data.provenance === "string" ? data.provenance : "loopback_pkce",
+        grade: toGrade(data.grade),
         principal_id: typeof data.principal_id === "string" ? data.principal_id : "",
         amr: Array.isArray(data.amr) ? data.amr.filter((a) => typeof a === "string") : [],
         expires_at: data.expires_at,
@@ -79,7 +87,7 @@ export function saveControlPlaneSession(data, path) {
     renameSync(tmp, p);
     chmodSync(p, 0o600);
 }
-/** Delete the cached control-plane session — local half of `operator logout`. Idempotent. */
+/** Delete the cached sign-in session — local half of `run402 logout`. Idempotent. */
 export function clearControlPlaneSession(path) {
     const p = path ?? getControlPlaneSessionPath();
     try {
@@ -105,10 +113,27 @@ export function controlPlaneSessionFromTokenResponse(resp, nowMs = Date.now()) {
     return {
         control_plane_session_token: resp.control_plane_session_token,
         token_type: resp.token_type ?? "Bearer",
-        provenance: resp.provenance ?? "loopback_pkce",
+        grade: toGrade(resp.grade),
         principal_id: resp.principal_id ?? "",
         amr: Array.isArray(resp.amr) ? resp.amr.filter((a) => typeof a === "string") : [],
         expires_at: nowMs + (typeof resp.expires_in === "number" ? resp.expires_in : 0) * 1000,
     };
 }
+/**
+ * Delete the session caches of the retired email-scoped session
+ * (`{base}/operator-session.json`) and the retired approval cache file
+ * (`{base}/write-auth-session.json`). Neither is read any more; `run402 login`
+ * and `run402 logout` call this so a stale token does not linger on disk.
+ * Best-effort and idempotent.
+ */
+export function clearRetiredSessionCaches() {
+    for (const name of ["operator-session.json", "write-auth-session.json"]) {
+        try {
+            rmSync(join(getConfigBaseDir(), name), { force: true });
+        }
+        catch {
+            // Best-effort: a failed unlink never blocks login or logout.
+        }
+    }
+}
 //# sourceMappingURL=control-plane-session.js.map

package/sdk/core-dist/keystore.js

@@ -3,7 +3,7 @@ import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { getLegacyProjectsPath, getProjectCredentialsPath } from "./config.js";
 import { clearActiveProjectId as clearProfileActiveProjectId, getActiveProjectId as getProfileActiveProjectId, recordMigration, setActiveProjectId as setProfileActiveProjectId, } from "./profile-state.js";
-import { readAllowance } from "./allowance.js";
+import { readWallet } from "./wallet.js";
 function withFileLock(path, fn, { retries = 200, delayMs = 20 } = {}) {
     const lockDir = path + ".lock";
     mkdirSync(dirname(path), { recursive: true });
@@ -99,7 +99,7 @@ function migrateLegacyProjectsJson(targetPath) {
         // Scoped the same way every other write in this module now is (see
         // `currentPrincipal`'s doc comment) — an unscoped write here is exactly
         // what poisons the "unknown"-principal bucket for good on a machine that
-        // migrates before its wallet allowance exists yet.
+        // migrates before its wallet exists yet.
         setProfileActiveProjectId(legacy.active_project_id, undefined, { principal: currentPrincipal() });
     }
     recordMigration("projects_json_import", {
@@ -174,7 +174,7 @@ export function removeProject(projectId, path) {
 }
 /**
  * The active-project scope's `principal`, derived from the CURRENT wallet's
- * allowance — matching exactly what `NodeCredentialsProvider.setActiveProject`
+ * wallet — matching exactly what `NodeCredentialsProvider.setActiveProject`
  * (sdk/src/node/credentials.ts) writes after `projects.provision` /
  * `projects.use`. Without this, every reader here used the profile-state
  * module's own default (empty) scope, which resolves to a FIXED
@@ -185,7 +185,7 @@ export function removeProject(projectId, path) {
  * `profile-state.ts#getActiveProjectId` happens to agree), but once the
  * "unknown" bucket is EVER populated by any principal-less write — the
  * one-time legacy `projects.json` migration below, or any provision/`use`
- * call made before this machine had a wallet allowance — it never gets
+ * call made before this machine had a wallet — it never gets
  * updated again (real wallet operations write to the principal-keyed
  * bucket, not "unknown") and PERMANENTLY shadows every later wallet-scoped
  * activation for every caller that reads through this module: `resolveProjectId`
@@ -197,13 +197,13 @@ export function removeProject(projectId, path) {
  * stale "unknown"-bucket entry first and never falls through to the
  * freshly-updated flat value.
  *
- * Best-effort: an unreadable/malformed allowance degrades to `null` (the
+ * Best-effort: an unreadable/malformed wallet degrades to `null` (the
  * "unknown" bucket callers tolerate), never a
- * throw — this is a read-scoping concern, not an allowance-validity one.
+ * throw — this is a read-scoping concern, not a wallet-validity one.
  */
 function currentPrincipal() {
     try {
-        return readAllowance()?.address ?? null;
+        return readWallet()?.address ?? null;
     }
     catch {
         return null;

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

@@ -3,7 +3,7 @@
  *
  * A "wallet" is a whole config directory. The reserved `default` wallet lives
  * at the base config dir (zero migration for existing installs); every named
- * wallet lives under `{base}/profiles/<name>/` with its own `allowance.json`,
+ * wallet lives under `{base}/profiles/<name>/` with its own `wallet.json`,
  * `projects.json`, and this module's non-secret `meta.json`.
  *
  * Two levels of active state, mirroring the wallet → project model:
@@ -40,10 +40,10 @@ export declare function profileDir(name: string): string;
 export declare function ensureProfileDir(name: string): string;
 export declare function readMeta(name: string): ProfileMeta | null;
 export declare function writeMeta(name: string, meta: ProfileMeta): void;
-/** True when a wallet's `allowance.json` exists on disk. */
+/** True when a wallet's `wallet.json` exists on disk. */
 export declare function profileExists(name: string): boolean;
 /**
- * All wallet names on disk: `default` (only if a root allowance.json exists)
+ * All wallet names on disk: `default` (only if a root wallet.json exists)
  * plus every valid directory under `profiles/`.
  */
 export declare function listProfileNames(): string[];

package/sdk/core-dist/profiles.js

@@ -3,7 +3,7 @@
  *
  * A "wallet" is a whole config directory. The reserved `default` wallet lives
  * at the base config dir (zero migration for existing installs); every named
- * wallet lives under `{base}/profiles/<name>/` with its own `allowance.json`,
+ * wallet lives under `{base}/profiles/<name>/` with its own `wallet.json`,
  * `projects.json`, and this module's non-secret `meta.json`.
  *
  * Two levels of active state, mirroring the wallet → project model:
@@ -17,7 +17,7 @@
 import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, existsSync, readdirSync, rmSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
-import { getConfigBaseDir, getProfilesDir, DEFAULT_PROFILE, isValidProfileName, } from "./config.js";
+import { getConfigBaseDir, getProfilesDir, DEFAULT_PROFILE, isValidProfileName, moveWalletFiles, WALLET_FILE_NAME, } from "./config.js";
 import { describeRejectedValue } from "./redact.js";
 function atomicWrite(p, content, mode) {
     const dir = dirname(p);
@@ -114,17 +114,19 @@ export function writeMeta(name, meta) {
     atomicWrite(metaPath(name), JSON.stringify(meta, null, 2), 0o600);
 }
 // --- enumeration + lifecycle ---
-/** True when a wallet's `allowance.json` exists on disk. */
+/** True when a wallet's `wallet.json` exists on disk. */
 export function profileExists(name) {
-    return existsSync(join(profileDir(name), "allowance.json"));
+    moveWalletFiles();
+    return existsSync(join(profileDir(name), WALLET_FILE_NAME));
 }
 /**
- * All wallet names on disk: `default` (only if a root allowance.json exists)
+ * All wallet names on disk: `default` (only if a root wallet.json exists)
  * plus every valid directory under `profiles/`.
  */
 export function listProfileNames() {
+    moveWalletFiles();
     const names = [];
-    if (existsSync(join(getConfigBaseDir(), "allowance.json"))) {
+    if (existsSync(join(getConfigBaseDir(), WALLET_FILE_NAME))) {
         names.push(DEFAULT_PROFILE);
     }
     try {
@@ -184,7 +186,7 @@ export function renameProfile(oldName, newName) {
             /* best-effort */
         }
         const base = getConfigBaseDir();
-        for (const f of ["allowance.json", "projects.json", "meta.json"]) {
+        for (const f of [WALLET_FILE_NAME, "projects.json", "meta.json"]) {
             const src = join(base, f);
             if (existsSync(src))
                 renameSync(src, join(dest, f));

package/sdk/core-dist/{allowance-auth.d.ts → wallet-auth.d.ts}

@@ -1,8 +1,8 @@
 /**
- * Allowance auth helper — generates SIWX (Sign-In With X / EIP-4361) headers for Run402 API.
+ * SIWX auth helper — generates SIWX (Sign-In With X / EIP-4361) headers for Run402 API.
  * Uses @noble/curves (lighter than viem) for signing.
  */
-import type { AllowanceData } from "./allowance.js";
+import type { WalletData } from "./wallet.js";
 export interface SIWxAuthHeaders {
     "SIGN-IN-WITH-X": string;
 }
@@ -22,7 +22,7 @@ interface SIWEMessageOpts {
     resources?: string[];
 }
 export interface SIWxAuthOptions extends SIWEMessageOpts {
-    allowance: Pick<AllowanceData, "address" | "privateKey">;
+    wallet: Pick<WalletData, "address" | "privateKey">;
     type?: "eip191";
 }
 /**
@@ -33,10 +33,10 @@ export declare function formatSIWEMessage(opts: SIWEMessageOpts, address: string
 export declare function buildSIWxAuthHeaders(opts: SIWxAuthOptions): SIWxAuthHeaders;
 /**
  * Get SIWX auth headers for the Run402 API.
- * Returns null if no allowance is configured.
+ * Returns null if no local wallet is configured.
  *
  * @param path - API path (e.g. "/projects/v1") used to build the SIWE uri field.
  */
-export declare function getAllowanceAuthHeaders(path: string, allowancePath?: string): SIWxAuthHeaders | null;
+export declare function getWalletAuthHeaders(path: string, walletPath?: string): SIWxAuthHeaders | null;
 export {};
-//# sourceMappingURL=allowance-auth.d.ts.map
+//# sourceMappingURL=wallet-auth.d.ts.map

package/{core/dist/allowance-auth.js → sdk/core-dist/wallet-auth.js}

@@ -1,12 +1,12 @@
 /**
- * Allowance auth helper — generates SIWX (Sign-In With X / EIP-4361) headers for Run402 API.
+ * SIWX auth helper — generates SIWX (Sign-In With X / EIP-4361) headers for Run402 API.
  * Uses @noble/curves (lighter than viem) for signing.
  */
 import { randomBytes } from "node:crypto";
 import { secp256k1 } from "@noble/curves/secp256k1.js";
 import { keccak_256 } from "@noble/hashes/sha3.js";
 import { bytesToHex } from "@noble/hashes/utils.js";
-import { readAllowance } from "./allowance.js";
+import { readWallet } from "./wallet.js";
 import { getApiBase } from "./config.js";
 /**
  * EIP-55 mixed-case checksum encoding.
@@ -21,7 +21,7 @@ export function toChecksumAddress(address) {
     return checksummed;
 }
 /**
- * EIP-191 personal_sign: sign a message with the allowance's private key.
+ * EIP-191 personal_sign: sign a message with the wallet's private key.
  */
 function personalSign(privateKeyHex, address, message) {
     const msgBytes = new TextEncoder().encode(message);
@@ -86,11 +86,11 @@ export function formatSIWEMessage(opts, address) {
     return lines.join("\n");
 }
 export function buildSIWxAuthHeaders(opts) {
-    const message = formatSIWEMessage(opts, opts.allowance.address);
-    const signature = personalSign(opts.allowance.privateKey, opts.allowance.address, message);
+    const message = formatSIWEMessage(opts, opts.wallet.address);
+    const signature = personalSign(opts.wallet.privateKey, opts.wallet.address, message);
     const payload = {
         domain: opts.domain,
-        address: toChecksumAddress(opts.allowance.address),
+        address: toChecksumAddress(opts.wallet.address),
         statement: opts.statement,
         uri: opts.uri,
         version: opts.version ?? "1",
@@ -110,18 +110,18 @@ export function buildSIWxAuthHeaders(opts) {
 }
 /**
  * Get SIWX auth headers for the Run402 API.
- * Returns null if no allowance is configured.
+ * Returns null if no local wallet is configured.
  *
  * @param path - API path (e.g. "/projects/v1") used to build the SIWE uri field.
  */
-export function getAllowanceAuthHeaders(path, allowancePath) {
-    // readAllowance throws on a malformed-shape allowance file. The
-    // CLI's higher-level readAllowance wrapper surfaces this as a structured
-    // BAD_ALLOWANCE_FILE envelope; here we preserve the public contract that
+export function getWalletAuthHeaders(path, walletPath) {
+    // readWallet throws on a malformed-shape wallet file. The
+    // CLI's higher-level readWallet wrapper surfaces this as a structured
+    // BAD_WALLET_FILE envelope; here we preserve the public contract that
     // this helper returns SIWxAuthHeaders | null. Re-throw so callers above
     // the CLI's wrapper (e.g. SDK paid-fetch) can decide whether to swallow it.
-    const allowance = readAllowance(allowancePath);
-    if (!allowance || !allowance.address || !allowance.privateKey)
+    const localWallet = readWallet(walletPath);
+    if (!localWallet || !localWallet.address || !localWallet.privateKey)
         return null;
     const apiBase = getApiBase();
     const url = new URL(apiBase);
@@ -132,7 +132,7 @@ export function getAllowanceAuthHeaders(path, allowancePath) {
     const issuedAt = now.toISOString();
     const expirationTime = new Date(now.getTime() + 5 * 60 * 1000).toISOString();
     return buildSIWxAuthHeaders({
-        allowance,
+        wallet: localWallet,
         domain,
         uri,
         statement: "Sign in to Run402",
@@ -151,4 +151,4 @@ function messageChainId(chainId) {
 function payloadChainId(chainId) {
     return typeof chainId === "number" ? `eip155:${chainId}` : chainId;
 }
-//# sourceMappingURL=allowance-auth.js.map
+//# sourceMappingURL=wallet-auth.js.map

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

@@ -0,0 +1,22 @@
+export interface WalletData {
+    address: string;
+    privateKey: string;
+    created?: string;
+    funded?: boolean;
+    lastFaucet?: string;
+    rail?: "x402" | "mpp" | "lightning";
+    /** The Lightning wallet (`run402 init lightning`): a budgeted wallet on Run402's Hub. `nwc` is the pairing secret. */
+    lightning?: WalletLightning;
+}
+export interface WalletLightning {
+    wallet_id: string;
+    nwc: string;
+    lightning_address: string | null;
+    budget_sats: number;
+    starter_sats: number;
+    custody: "run402_hub";
+    minted_at: string;
+}
+export declare function readWallet(path?: string): WalletData | null;
+export declare function saveWallet(data: WalletData, path?: string): void;
+//# sourceMappingURL=wallet.d.ts.map

package/sdk/core-dist/{allowance.js → wallet.js}

@@ -1,36 +1,36 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, renameSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
-import { getAllowancePath } from "./config.js";
+import { getWalletPath } from "./config.js";
 // 0x-prefixed 40-hex EVM address.
 const ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
 // 0x-prefixed 64-hex secp256k1 private key (32 bytes).
 const PRIVATE_KEY_RE = /^0x[a-fA-F0-9]{64}$/;
 /**
- * Load the agent allowance from disk.
+ * Load the agent wallet from disk.
  *
- * Returns `null` for the two "no allowance configured" cases:
+ * Returns `null` for the two "no local wallet configured" cases:
  *   - the file does not exist
  *   - the file exists but is not parseable JSON (preserve existing UX —
- *     consumers print "no_allowance" and tell the user to run init)
+ *     consumers print "no_wallet" and tell the user to run init)
  *
  * Throws a structured `Error` when the file parses as JSON but the
  * shape is wrong (missing/wrong-type/wrong-length fields). Without this guard
  * downstream callers crash with raw stack traces:
- *   - `cli/lib/status.mjs` reaches for `allowance.address.toLowerCase()`
+ *   - `cli/lib/status.mjs` reaches for `wallet.address.toLowerCase()`
  *     and crashes with `TypeError: Cannot read properties of undefined`.
- *   - `core/src/allowance-auth.ts` passes a malformed `privateKey` to
+ *   - `core/src/wallet-auth.ts` passes a malformed `privateKey` to
  *     `@noble/curves` which throws "expected 32 bytes, got N".
  *
- * The CLI's `cli/lib/config.mjs:readAllowance()` wrapper and the MCP
+ * The CLI's `cli/lib/config.mjs:readWallet()` wrapper and the MCP
  * `src/tools/{status,init}.ts` callers translate the throw into their own
- * structured envelopes (`code: BAD_ALLOWANCE_FILE`).
+ * structured envelopes (`code: BAD_WALLET_FILE`).
  */
 /**
- * If an allowance file is readable by group or other (any of the low 0o077
+ * If a wallet file is readable by group or other (any of the low 0o077
  * bits set), tighten it to 0600 and warn once on stderr. This self-heals the
  * historical case where a legacy world-readable `wallet.json` (mode 0644) was
- * migrated to `allowance.json` via a mode-preserving rename, leaving the
+ * migrated to `wallet.json` via a mode-preserving rename, leaving the
  * private key exposed on a shared machine. Best-effort: POSIX-only and silent
  * on platforms without meaningful Unix modes (e.g. Windows).
  */
@@ -48,8 +48,8 @@ function selfHealPermissions(p) {
         // Best-effort; never block a read on a chmod/stat failure.
     }
 }
-export function readAllowance(path) {
-    const p = path ?? getAllowancePath();
+export function readWallet(path) {
+    const p = path ?? getWalletPath();
     if (!existsSync(p))
         return null;
     selfHealPermissions(p);
@@ -66,31 +66,31 @@ export function readAllowance(path) {
     }
     catch {
         // Preserve historical UX — completely unparseable input reads as "no
-        // allowance configured" rather than as an error. Consumers already handle
+        // wallet configured" rather than as an error. Consumers already handle
         // null with a friendly "run 'run402 init'" message.
         return null;
     }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error(`allowance.json must contain a JSON object (got ${Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed}). Back up the file and run 'run402 init' to recreate it.`);
+        throw new Error(`wallet.json must contain a JSON object (got ${Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed}). Back up the file and run 'run402 init' to recreate it.`);
     }
     const data = parsed;
     if (typeof data.address !== "string" || !ADDRESS_RE.test(data.address)) {
-        throw new Error("allowance.json missing valid 'address' (expected 0x-prefixed 40-hex string). " +
+        throw new Error("wallet.json missing valid 'address' (expected 0x-prefixed 40-hex string). " +
             "Back up the file and run 'run402 init' to recreate it.");
     }
     if (typeof data.privateKey !== "string" || !PRIVATE_KEY_RE.test(data.privateKey)) {
-        throw new Error("allowance.json missing valid 'privateKey' (expected 0x-prefixed 64-hex string). " +
+        throw new Error("wallet.json missing valid 'privateKey' (expected 0x-prefixed 64-hex string). " +
             "Back up the file and run 'run402 init' to recreate it.");
     }
     return data;
 }
-export function saveAllowance(data, path) {
-    const p = path ?? getAllowancePath();
+export function saveWallet(data, path) {
+    const p = path ?? getWalletPath();
     const dir = dirname(p);
     mkdirSync(dir, { recursive: true });
-    const tmp = join(dir, `.allowance.${randomBytes(4).toString("hex")}.tmp`);
+    const tmp = join(dir, `.wallet.${randomBytes(4).toString("hex")}.tmp`);
     writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
     renameSync(tmp, p);
     chmodSync(p, 0o600);
 }
-//# sourceMappingURL=allowance.js.map
+//# sourceMappingURL=wallet.js.map

package/sdk/core-dist/{write-auth-session.d.ts → write-approvals.d.ts}

@@ -1,19 +1,20 @@
 /**
- * Cache of **operator-approval** tokens — the passkey-fresh write-auth tokens a
- * wallet-less human mints to provision/deploy (gateway v1.85/v1.87). Distinct
- * from the control-plane session ({@link ControlPlaneSessionCache}) it pairs
- * with: the gateway scopes each token to one `(action, target)`, so this is a
+ * Cache of **write approvals** — the passkey-signed, target-scoped tokens a
+ * wallet-less person mints with `run402 approve` to provision, deploy, or write
+ * secrets from the command line. Distinct from the sign-in session
+ * ({@link ControlPlaneSessionCache}) it pairs with, and never a step-up. The
+ * gateway scopes each token to one `(action, target)`, so this is a
  * **multi-entry** cache keyed by `(api_origin, control_plane_session_hash,
  * action, target)`. An `org.project.create` approval for org Y and a
  * `project.deploy` approval for project X coexist.
  *
  * Stored at the BASE config dir (principal-scoped), mode 0600 — as sensitive as
- * the allowance key. The token dies with its control-plane session; the
+ * the wallet key. The token dies with its sign-in session; the
  * `control_plane_session_hash` binding lets the client drop a stale approval
- * locally rather than replay it into a `WRITE_AUTH_BINDING_MISMATCH`.
+ * locally rather than replay it into a `WRITE_APPROVAL_BINDING_MISMATCH`.
  */
-export interface WriteAuthApproval {
-    write_auth_token: string;
+export interface WriteApproval {
+    write_approval_token: string;
     token_type: string;
     header: string;
     /** Gateway capability: `org.project.create` | `project.deploy` | `project.secret.write`. */
@@ -30,13 +31,14 @@ export interface WriteAuthApproval {
     amr?: string[];
     minted_at: number;
 }
-/** The token payload from `POST /agent/v1/control-plane/write-auth/cli/token`. */
-export interface WriteAuthTokenResponse {
-    write_auth_token: string;
+/** The token payload from `POST /agent/v1/control-plane/write-approval/cli/token`. */
+export interface WriteApprovalTokenResponse {
+    write_approval_token: string;
     token_type?: string;
     header?: string;
-    /** The write-auth session; its expiry is the token's expiry. */
+    /** The write-approval session; its idle expiry is the token's expiry. */
     session?: {
+        idle_expires_at?: string | number;
         expires_at?: string | number;
         absolute_expires_at?: string | number;
         amr?: string[];
@@ -45,15 +47,15 @@ export interface WriteAuthTokenResponse {
     [k: string]: unknown;
 }
 /** A capability target — exactly one of these is set per approval. */
-export interface WriteAuthTargetKey {
+export interface WriteApprovalTargetKey {
     org_id?: string;
     project_id?: string;
 }
 /**
- * Path to the approval cache: `{base}/write-auth-session.json`.
- * `RUN402_WRITE_AUTH_SESSION_PATH` overrides for testing.
+ * Path to the approval cache: `{base}/write-approvals.json`.
+ * `RUN402_WRITE_APPROVALS_PATH` overrides for testing.
  */
-export declare function getWriteAuthSessionPath(): string;
+export declare function getWriteApprovalsPath(): string;
 /** Stable short hash binding an approval to a control-plane session token. */
 export declare function hashControlPlaneSession(token: string): string;
 /**
@@ -61,17 +63,17 @@ export declare function hashControlPlaneSession(token: string): string;
  * unreadable, unparseable). Throws when the file parses as JSON but the shape
  * is wrong, so a corrupted cache surfaces a clear fix-it.
  */
-export declare function readApprovals(path?: string): WriteAuthApproval[];
+export declare function readApprovals(path?: string): WriteApproval[];
 /**
  * Persist an approval. Replaces any existing entry with the same
  * `(api_origin, control_plane_session_hash, action, target)` key and leaves
  * every other entry intact (multi-entry, non-thrashing). Atomic, mode 0600.
  */
-export declare function saveApproval(approval: WriteAuthApproval, path?: string): void;
-/** Delete the whole approval cache — local half of `operator logout`. Idempotent. */
+export declare function saveApproval(approval: WriteApproval, path?: string): void;
+/** Delete the whole approval cache — local half of `run402 logout`. Idempotent. */
 export declare function clearApprovals(path?: string): void;
 /** Whether an approval is past its usable life (with a small skew buffer). */
-export declare function isApprovalExpired(approval: WriteAuthApproval, nowMs?: number, skewMs?: number): boolean;
+export declare function isApprovalExpired(approval: WriteApproval, nowMs?: number, skewMs?: number): boolean;
 /**
  * Return the cached approval matching ALL of `(apiOrigin, cpSessionHash,
  * capability, target)` and still live, or `null` if none matches or it is
@@ -82,18 +84,18 @@ export declare function loadLiveApproval(q: {
     apiOrigin: string;
     cpSessionHash: string;
     capability: string;
-    target: WriteAuthTargetKey;
-}, path?: string, nowMs?: number): WriteAuthApproval | null;
+    target: WriteApprovalTargetKey;
+}, path?: string, nowMs?: number): WriteApproval | null;
 /**
  * Build a cache entry from the gateway token response + the binding context
  * (the cp-session it was minted under, the API origin, and the `(action,
  * target)` it covers). Expiry is taken from the returned `session`.
  */
-export declare function approvalFromTokenResponse(resp: WriteAuthTokenResponse, binding: {
+export declare function approvalFromTokenResponse(resp: WriteApprovalTokenResponse, binding: {
     action: string;
-    target: WriteAuthTargetKey;
+    target: WriteApprovalTargetKey;
     apiOrigin: string;
     controlPlaneSessionHash: string;
     controlPlanePrincipalId: string;
-}, nowMs?: number): WriteAuthApproval;
-//# sourceMappingURL=write-auth-session.d.ts.map
+}, nowMs?: number): WriteApproval;
+//# sourceMappingURL=write-approvals.d.ts.map