run402 3.0.0 → 3.2.0

package/core-dist/write-auth-session.js

@@ -0,0 +1,174 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, renameSync, statSync, rmSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes, createHash } from "node:crypto";
+import { getConfigBaseDir } from "./config.js";
+const DEFAULT_TTL_MS = 30 * 60 * 1000;
+/**
+ * Path to the approval cache: `{base}/write-auth-session.json`.
+ * `RUN402_WRITE_AUTH_SESSION_PATH` overrides for testing.
+ */
+export function getWriteAuthSessionPath() {
+    return (process.env.RUN402_WRITE_AUTH_SESSION_PATH ||
+        join(getConfigBaseDir(), "write-auth-session.json"));
+}
+/** Stable short hash binding an approval to a control-plane session token. */
+export function hashControlPlaneSession(token) {
+    return createHash("sha256").update(token).digest("hex").slice(0, 32);
+}
+/** Tighten 0600 if group/other-readable, warning once. Best-effort, POSIX-only. */
+function selfHealPermissions(p) {
+    if (process.platform === "win32")
+        return;
+    try {
+        const mode = statSync(p).mode & 0o777;
+        if ((mode & 0o077) !== 0) {
+            chmodSync(p, 0o600);
+            process.stderr.write(`warning: tightened permissions on ${p} from ${mode.toString(8)} to 600 (was readable by other users).\n`);
+        }
+    }
+    catch {
+        // Best-effort; never block a read on a chmod/stat failure.
+    }
+}
+function isApproval(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const a = x;
+    return (typeof a.write_auth_token === "string" &&
+        a.write_auth_token.length > 0 &&
+        typeof a.action === "string" &&
+        typeof a.api_origin === "string" &&
+        typeof a.control_plane_session_hash === "string" &&
+        typeof a.expires_at === "number" &&
+        Number.isFinite(a.expires_at));
+}
+/**
+ * Read all cached approvals. Returns `[]` for the "no cache" cases (absent,
+ * unreadable, unparseable). Throws when the file parses as JSON but the shape
+ * is wrong, so a corrupted cache surfaces a clear fix-it.
+ */
+export function readApprovals(path) {
+    const p = path ?? getWriteAuthSessionPath();
+    if (!existsSync(p))
+        return [];
+    selfHealPermissions(p);
+    let raw;
+    try {
+        raw = readFileSync(p, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("write-auth-session.json must contain a JSON object. Delete it and re-run 'run402 operator approve' to recreate it.");
+    }
+    const approvals = parsed.approvals;
+    if (!Array.isArray(approvals)) {
+        throw new Error("write-auth-session.json missing an 'approvals' array. Delete it and re-run 'run402 operator approve'.");
+    }
+    return approvals.filter(isApproval);
+}
+function writeApprovals(approvals, path) {
+    const p = path ?? getWriteAuthSessionPath();
+    const dir = dirname(p);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.write-auth-session.${randomBytes(4).toString("hex")}.tmp`);
+    writeFileSync(tmp, JSON.stringify({ approvals }, null, 2), { mode: 0o600 });
+    renameSync(tmp, p);
+    chmodSync(p, 0o600);
+}
+function sameTarget(a, b) {
+    return (a.org_id ?? null) === (b.org_id ?? null) && (a.project_id ?? null) === (b.project_id ?? null);
+}
+function sameKey(a, b) {
+    return (a.api_origin === b.api_origin &&
+        a.control_plane_session_hash === b.control_plane_session_hash &&
+        a.action === b.action &&
+        sameTarget(a, b));
+}
+/**
+ * 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 function saveApproval(approval, path) {
+    const existing = readApprovals(path).filter((a) => !sameKey(a, approval));
+    existing.push(approval);
+    writeApprovals(existing, path);
+}
+/** Delete the whole approval cache — local half of `operator logout`. Idempotent. */
+export function clearApprovals(path) {
+    const p = path ?? getWriteAuthSessionPath();
+    try {
+        rmSync(p, { force: true });
+    }
+    catch {
+        // Best-effort: a failed unlink should never crash logout.
+    }
+}
+/** Whether an approval is past its usable life (with a small skew buffer). */
+export function isApprovalExpired(approval, nowMs = Date.now(), skewMs = 10_000) {
+    return nowMs + skewMs >= approval.expires_at;
+}
+/**
+ * Return the cached approval matching ALL of `(apiOrigin, cpSessionHash,
+ * capability, target)` and still live, or `null` if none matches or it is
+ * expired. This is the exact-match the gateway's target gate requires — a
+ * non-match (wrong action/target/origin/session) fails closed.
+ */
+export function loadLiveApproval(q, path, nowMs = Date.now()) {
+    for (const a of readApprovals(path)) {
+        if (a.api_origin === q.apiOrigin &&
+            a.control_plane_session_hash === q.cpSessionHash &&
+            a.action === q.capability &&
+            sameTarget(a, q.target) &&
+            !isApprovalExpired(a, nowMs)) {
+            return a;
+        }
+    }
+    return null;
+}
+/** Parse a gateway-returned session expiry (ISO string or epoch) to epoch ms. */
+function sessionExpiryMs(session, nowMs) {
+    const raw = session?.expires_at ?? session?.absolute_expires_at;
+    if (typeof raw === "number" && Number.isFinite(raw))
+        return raw > 1e12 ? raw : raw * 1000;
+    if (typeof raw === "string") {
+        const ms = Date.parse(raw);
+        if (Number.isFinite(ms))
+            return ms;
+    }
+    return nowMs + DEFAULT_TTL_MS;
+}
+/**
+ * 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 function approvalFromTokenResponse(resp, binding, nowMs = Date.now()) {
+    const amr = Array.isArray(resp.session?.amr)
+        ? resp.session.amr.filter((a) => typeof a === "string")
+        : undefined;
+    return {
+        write_auth_token: resp.write_auth_token,
+        token_type: typeof resp.token_type === "string" ? resp.token_type : "write_auth",
+        header: typeof resp.header === "string" ? resp.header : "X-Run402-Write-Auth",
+        action: binding.action,
+        ...(binding.target.org_id ? { org_id: binding.target.org_id } : {}),
+        ...(binding.target.project_id ? { project_id: binding.target.project_id } : {}),
+        expires_at: sessionExpiryMs(resp.session, nowMs),
+        control_plane_session_hash: binding.controlPlaneSessionHash,
+        control_plane_principal_id: binding.controlPlanePrincipalId,
+        api_origin: binding.apiOrigin,
+        ...(amr ? { amr } : {}),
+        minted_at: nowMs,
+    };
+}
+//# sourceMappingURL=write-auth-session.js.map

package/lib/deploy-v2.mjs

@@ -34,6 +34,8 @@ import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { API, allowanceAuthHeaders, getActiveProjectId, resolveProjectId } from "./config.mjs";
 import { normalizeArgv } from "./argparse.mjs";
+import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
+import { withAutoApprove } from "./operator.mjs";
 
 const APPLY_HELP = `run402 deploy apply — Unified deploy primitive (v1.34+)
 
@@ -810,18 +812,21 @@ async function applyCmd(args) {
       credentials: githubActionsCredentials({ projectId: releaseSpec.project, apiBase: API }),
       disablePaidFetch: true,
     };
-  } else {
-    // Preserve the aggressive early exit when no allowance is configured.
+  } else if (!loadLiveControlPlaneSession()) {
+    // Aggressive early exit when no allowance is configured — unless a
+    // wallet-less human is deploying via their operator (control-plane) session.
     allowanceAuthHeaders("/apply/v1/plans");
   }
 
   try {
-    const result = await getSdk(sdkOpts)._applyEngine.apply(releaseSpec, {
-      onEvent: makeStderrEventWriter(opts.quiet),
-      idempotencyKey,
-      allowWarnings: opts.allowWarnings,
-      allowWarningCodes: opts.allowWarningCodes,
-    });
+    const result = await withAutoApprove(() =>
+      getSdk(sdkOpts)._applyEngine.apply(releaseSpec, {
+        onEvent: makeStderrEventWriter(opts.quiet),
+        idempotencyKey,
+        allowWarnings: opts.allowWarnings,
+        allowWarningCodes: opts.allowWarningCodes,
+      }),
+    );
     console.log(JSON.stringify(result, null, 2));
   } catch (err) {
     reportDeployApplyError(err, useGithubActionsOidc);

package/lib/functions.mjs

@@ -87,12 +87,12 @@ Notes:
     export default async (req: Request) => Response
   Deploy may require payment if the project lease has expired.
 
-  The deploy response includes:
-  - runtime_version: the bundled @run402/functions version (e.g. "1.48.0")
-  - deps_resolved: map of each --deps name to the actually-installed
-    concrete version (e.g. {"lodash":"4.17.21"})
-  - warnings (optional, top-level, sibling to the record): non-fatal
-    notes such as bundle-size advisories
+  Deploy routes through the unified apply engine (functions.patch.set), not
+  a legacy admin route. The result sets runtime_version and deps_resolved to
+  null (apply returns release-level data, not per-function build metadata) -
+  read the resolved versions from 'run402 functions list', whose records
+  carry both. The result still includes an optional top-level warnings:
+  string[] for non-fatal notes such as bundle-size advisories.
 
 Examples:
   run402 functions deploy prj_abc123 stripe-webhook --file handler.ts

package/lib/operator.mjs

@@ -23,7 +23,7 @@ import { createServer } from "node:http";
 import { randomBytes, createHash } from "node:crypto";
 import { fail, reportSdkError } from "./sdk-errors.mjs";
 import { getSdk } from "./sdk.mjs";
-import { claimWalletOrg, isStepUpRequired } from "#sdk/node";
+import { claimWalletOrg, isStepUpRequired, isOperatorApprovalRequired } from "#sdk/node";
 import { normalizeArgv, hasHelp, assertKnownFlags, flagValue } from "./argparse.mjs";
 import {
   saveOperatorSession,
@@ -38,8 +38,33 @@ import {
   clearControlPlaneSession,
   readControlPlaneSession,
   isControlPlaneSessionExpired,
+  loadLiveControlPlaneSession,
   controlPlaneSessionFromTokenResponse,
 } from "../core-dist/control-plane-session.js";
+import {
+  saveApproval,
+  clearApprovals,
+  readApprovals,
+  hashControlPlaneSession,
+  approvalFromTokenResponse,
+} from "../core-dist/write-auth-session.js";
+import { getApiBase } from "../core-dist/config.js";
+
+/** Gateway write-auth capabilities → required target scope. */
+const APPROVAL_ACTIONS = {
+  "org.project.create": "org",
+  "project.deploy": "project",
+  "project.secret.write": "project",
+};
+
+/** True when `url` is same-origin as the API base (confirm_url validation). */
+function sameApiOrigin(url) {
+  try {
+    return new URL(url).origin === new URL(getApiBase()).origin;
+  } catch {
+    return false;
+  }
+}
 
 const CLIENT_NAME = "run402 CLI";
 
@@ -57,6 +82,8 @@ Usage:
   run402 operator whoami
   run402 operator logout
   run402 operator claim-wallet-org [--org <id>] [--name <label>]
+  run402 operator approve --action <cap> (--org <id> | --project <id>) [--no-open]
+  run402 operator status
 
 Subcommands:
   login            Sign in via the browser. Default = device-flow READ session (powers
@@ -68,6 +95,12 @@ Subcommands:
   claim-wallet-org Claim an org owned by your wallet's agent into your human identity
                    (ownership transfer). Dual proof: your write-capable session
                    ('login --loopback' first) + a fresh signature from the active wallet.
+  approve          Mint a passkey operator-approval scoped to one (action, target) so a
+                   wallet-less human can provision/deploy. --action is one of
+                   org.project.create (--org), project.deploy (--project),
+                   project.secret.write (--project). Requires 'login --loopback' first.
+  status           Show the control-plane login state + each cached approval (action,
+                   target, expiry). Local, no network.
 
 Options:
   --no-open  (login) Do not auto-open the browser; just print the URL.
@@ -275,6 +308,8 @@ async function loopbackLogin(args, { stepUp }) {
   close();
 
   const cached = controlPlaneSessionFromTokenResponse(session);
+  // A fresh control-plane session invalidates any approvals bound to the old one.
+  clearApprovals();
   saveControlPlaneSession(cached);
   process.stderr.write(`\nSigned in (write-capable, provenance=${cached.provenance}).\n`);
 
@@ -394,6 +429,7 @@ async function logout(args) {
   }
   clearOperatorSession();
   clearControlPlaneSession();
+  clearApprovals();
   console.log(JSON.stringify({ revoked, cleared: true }));
 }
 
@@ -510,12 +546,203 @@ async function claimWalletOrgCmd(args) {
   }
 }
 
+/**
+ * Run the scoped operator-approval ceremony (loopback + passkey) and cache the
+ * minted approval. Requires a live control-plane session. Returns the cached
+ * approval (or exits non-zero via fail/reportSdkError). Reused by the
+ * `operator approve` verb AND the TTY auto-approve path in provision/deploy.
+ */
+export async function mintApproval({ action, orgId, projectId, noOpen = false }) {
+  const cp = loadLiveControlPlaneSession();
+  if (!cp) {
+    return fail({
+      code: "OPERATOR_LOGIN_REQUIRED",
+      message: "No control-plane session. Run 'run402 operator login --loopback' first, then approve.",
+      hint: "operator approval is minted on top of your write-capable control-plane session.",
+    });
+  }
+  const sdk = getSdk();
+  const { codeVerifier, codeChallenge, state } = pkce();
+  const { ready, codePromise, close } = startLoopbackServer({ expectedState: state, timeoutMs: 300_000 });
+
+  let port;
+  try {
+    port = await ready;
+  } catch (err) {
+    close();
+    return fail({ code: "OPERATOR_APPROVE_FAILED", message: `Could not start the loopback server: ${err.message}` });
+  }
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+  let challenge;
+  try {
+    challenge = await sdk.operator.approval.requestChallenge({
+      action,
+      orgId: orgId ?? undefined,
+      projectId: projectId ?? undefined,
+      cliRedirectUri: redirectUri,
+      codeChallenge,
+      state,
+      token: cp.control_plane_session_token,
+    });
+  } catch (err) {
+    close();
+    return reportSdkError(err);
+  }
+
+  const confirmUrl = challenge?.confirm_url;
+  if (!confirmUrl || !sameApiOrigin(confirmUrl)) {
+    close();
+    return fail({
+      code: "OPERATOR_APPROVE_BAD_CONFIRM_URL",
+      message: "The gateway returned a confirm_url that is not same-origin as the API base; aborting.",
+    });
+  }
+  const targetLabel = orgId ? `org ${orgId}` : projectId ? `project ${projectId}` : "(no target)";
+  process.stderr.write(
+    `\nTo approve '${action}' for ${targetLabel}, open and approve with your passkey:\n  ${confirmUrl}\n\n`,
+  );
+  if (!noOpen && process.stderr.isTTY) {
+    openBrowser(confirmUrl);
+    process.stderr.write("(opening your browser…)\n\n");
+  }
+  process.stderr.write("Waiting for passkey approval…\n");
+
+  let code;
+  try {
+    code = await codePromise;
+  } catch (err) {
+    close();
+    return fail({ code: "OPERATOR_APPROVE_FAILED", message: err.message, hint: "Run 'run402 operator approve' to try again." });
+  }
+
+  let token;
+  try {
+    token = await sdk.operator.approval.exchangeClaimCode({ code, codeVerifier, state });
+  } catch (err) {
+    close();
+    return reportSdkError(err);
+  }
+  close();
+
+  const approval = approvalFromTokenResponse(token, {
+    action,
+    target: { org_id: orgId ?? undefined, project_id: projectId ?? undefined },
+    apiOrigin: new URL(getApiBase()).origin,
+    controlPlaneSessionHash: hashControlPlaneSession(cp.control_plane_session_token),
+    controlPlanePrincipalId: cp.principal_id || "",
+  });
+  saveApproval(approval);
+  process.stderr.write(`\nApproved '${action}' for ${targetLabel}.\n`);
+  return approval;
+}
+
+/**
+ * Run a write action; on `OperatorApprovalRequiredError` AND an interactive
+ * TTY (CLI), run the scoped approval ceremony and retry once. In MCP / CI /
+ * non-TTY the typed error is rethrown unchanged — the agent relays the resolved
+ * `operator approve …` command rather than a browser opening unexpectedly.
+ */
+export async function withAutoApprove(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (!isOperatorApprovalRequired(err) || !process.stderr.isTTY) throw err;
+    const action = err.capability;
+    const target = err.target || {};
+    if (!action) throw err;
+    process.stderr.write(`\nThis '${action}' needs a one-time operator approval. Opening the browser to approve…\n`);
+    await mintApproval({ action, orgId: target.org_id ?? undefined, projectId: target.project_id ?? undefined });
+    return await fn(); // retry once with the now-cached approval
+  }
+}
+
+/**
+ * `operator approve --action <cap> (--org <id> | --project <id>)` — mint a
+ * passkey approval scoped to one (action, target). Hidden alias: `write-auth`.
+ */
+async function approve(args) {
+  assertKnownFlags(
+    args,
+    ["--help", "-h", "--no-open", "--action", "--org", "--project"],
+    ["--action", "--org", "--project"],
+  );
+  const action = flagValue(args, "--action");
+  const org = flagValue(args, "--org");
+  const project = flagValue(args, "--project");
+
+  if (!action || !APPROVAL_ACTIONS[action]) {
+    fail({
+      code: "BAD_FLAG",
+      message: `--action must be one of: ${Object.keys(APPROVAL_ACTIONS).join(", ")}`,
+      details: { flag: "--action", value: action, allowed: Object.keys(APPROVAL_ACTIONS) },
+    });
+  }
+  const scope = APPROVAL_ACTIONS[action];
+  if (scope === "org" && !org) fail({ code: "BAD_FLAG", message: `--org <id> is required for --action ${action}` });
+  if (scope === "project" && !project) fail({ code: "BAD_FLAG", message: `--project <id> is required for --action ${action}` });
+  if (scope === "org" && project) fail({ code: "BAD_FLAG", message: `--project is not valid for org-scoped --action ${action}; use --org` });
+  if (scope === "project" && org) fail({ code: "BAD_FLAG", message: `--org is not valid for project-scoped --action ${action}; use --project` });
+
+  const approval = await mintApproval({
+    action,
+    orgId: org ?? undefined,
+    projectId: project ?? undefined,
+    noOpen: args.includes("--no-open"),
+  });
+  console.log(
+    JSON.stringify({
+      approved: true,
+      action,
+      ...(org ? { org_id: org } : {}),
+      ...(project ? { project_id: project } : {}),
+      expires_at: new Date(approval.expires_at).toISOString(),
+    }),
+  );
+}
+
+/** `operator status` — operator-login state + each cached approval's (action, target, expiry). */
+async function status(args) {
+  assertKnownFlags(args, ["--help", "-h"]);
+  const now = Date.now();
+  const cp = readControlPlaneSession();
+  const liveCp = cp && !isControlPlaneSessionExpired(cp, now) ? cp : null;
+  const approvals = readApprovals()
+    .filter((a) => a.expires_at > now)
+    .map((a) => ({
+      action: a.action,
+      org_id: a.org_id ?? null,
+      project_id: a.project_id ?? null,
+      expires_at: new Date(a.expires_at).toISOString(),
+    }));
+  const out = {
+    operator_login: liveCp
+      ? { active: true, provenance: liveCp.provenance, amr: liveCp.amr, expires_at: new Date(liveCp.expires_at).toISOString() }
+      : { active: false },
+    approvals,
+  };
+  if (liveCp) {
+    process.stderr.write(`Operator login: active (${liveCp.provenance})\n`);
+    process.stderr.write(
+      approvals.length
+        ? `Approvals (${approvals.length}):\n` +
+            approvals.map((a) => `  - ${a.action} ${a.org_id || a.project_id || ""} (expires ${a.expires_at})`).join("\n") +
+            "\n"
+        : "Approvals: none. Run 'run402 operator approve --action <cap> --org|--project <id>'.\n",
+    );
+  } else {
+    process.stderr.write("Operator login: none. Run 'run402 operator login --loopback'.\n");
+  }
+  console.log(JSON.stringify(out, null, 2));
+}
+
 export async function run(sub, args = []) {
   args = normalizeArgv(args);
   if (!sub || sub === "--help" || sub === "-h" || hasHelp(args)) {
     console.log(HELP);
     process.exit(0);
   }
+  if (sub === "write-auth") sub = "approve"; // hidden alias (transport name)
   switch (sub) {
     case "login":
       await login(args);
@@ -532,6 +759,12 @@ export async function run(sub, args = []) {
     case "claim-wallet-org":
       await claimWalletOrgCmd(args);
       break;
+    case "approve":
+      await approve(args);
+      break;
+    case "status":
+      await status(args);
+      break;
     default:
       fail({
         code: "BAD_USAGE",

package/lib/projects.mjs

@@ -1,6 +1,8 @@
 import { readFileSync } from "fs";
 import { loadKeyStore, API, allowanceAuthHeaders, resolveProjectId, getActiveProjectId } 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";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail, parseFlagJson } from "./sdk-errors.mjs";
 import { assertKnownFlags, failBadProjectId, flagValue, hasHelp, normalizeArgv, positionalArgs, resolvePositionalProject, validateRegularFile } from "./argparse.mjs";
@@ -302,13 +304,16 @@ async function provision(args) {
       });
     }
   }
-  // Preserve the aggressive early exit when no allowance is configured —
-  // gives the user a more specific prompt than the SDK's 401/402 path.
-  allowanceAuthHeaders("/projects/v1");
+  // Aggressive early exit when no agent allowance is configured — but only when
+  // there's also no operator (control-plane) session, since a wallet-less human
+  // provisions into an org via their operator approval instead of a wallet.
+  if (!loadLiveControlPlaneSession()) allowanceAuthHeaders("/projects/v1");
 
   const activeBefore = getActiveProjectId();
   try {
-    const data = await getSdk().projects.provision({ tier: opts.tier, name: opts.name, orgId: opts.orgId });
+    const data = await withAutoApprove(() =>
+      getSdk().projects.provision({ tier: opts.tier, name: opts.name, orgId: opts.orgId }),
+    );
     const activeAfter = getActiveProjectId();
     const out = { ...data };
     if (activeBefore && activeAfter && activeBefore !== activeAfter) {

package/lib/sdk.mjs

@@ -10,5 +10,7 @@
 import { run402 } from "#sdk/node";
 
 export function getSdk(opts = {}) {
-  return run402(opts);
+  // surface: "cli" opts the default credential resolution into `auto` — wallet
+  // if present, else the operator (control-plane) session + matched approval.
+  return run402({ surface: "cli", ...opts });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {