run402 2.39.3 → 2.40.0

package/README.md

@@ -2,7 +2,7 @@
 
 Command-line interface for [Run402](https://run402.com) — provision Postgres databases, deploy static sites, run Node 22 serverless functions, host content-addressed CDN assets, send email, sign on-chain. Paid autonomously with x402 USDC on Base. **Prototype tier is free on testnet.**
 
-For the full CLI reference (every flag, every subcommand) see **<https://run402.com/llms-cli.txt>**.
+For the full CLI reference (every flag, every subcommand) see **<https://docs.run402.com/llms-cli.txt>**.
 
 ## Install
 
@@ -243,7 +243,7 @@ run402 functions --help
 
 The canonical, comprehensive CLI reference — every flag, every subcommand, edge cases, troubleshooting — lives at:
 
-**<https://run402.com/llms-cli.txt>**
+**<https://docs.run402.com/llms-cli.txt>**
 
 Same content also at [`cli/llms-cli.txt`](./llms-cli.txt) in the repo. Treat that file as authoritative; this README is a quick-orientation landing page.
 

package/cli.mjs

@@ -30,7 +30,7 @@ Commands:
   deploy      Unified deploy operations (requires active tier)
   ci          Link GitHub Actions OIDC deploy bindings
   transfer    Two-party project transfer (init, preview, list, accept, cancel)
-  org         Org membership + roles (whoami, list, members, add-member, set-role, remove-member)
+  org         Org membership, invites & audit (whoami, list, member, invite, audit)
   grants      Per-project capability grants for agent/CI principals (create, revoke)
   jobs        Submit and inspect fixed platform-managed jobs
   functions   Manage serverless functions (deploy, invoke, logs, list, delete)

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

@@ -0,0 +1,114 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, renameSync, statSync, rmSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { getConfigBaseDir } from "./config.js";
+/**
+ * Path to the cached control-plane session: `{base}/control-plane-session.json`.
+ * `RUN402_CONTROL_PLANE_SESSION_PATH` overrides for testing.
+ */
+export function getControlPlaneSessionPath() {
+    return (process.env.RUN402_CONTROL_PLANE_SESSION_PATH ||
+        join(getConfigBaseDir(), "control-plane-session.json"));
+}
+/** 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.
+    }
+}
+/**
+ * Load the cached control-plane session. Returns `null` for the "no session"
+ * 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 readControlPlaneSession(path) {
+    const p = path ?? getControlPlaneSessionPath();
+    if (!existsSync(p))
+        return null;
+    selfHealPermissions(p);
+    let raw;
+    try {
+        raw = readFileSync(p, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        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.");
+    }
+    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.");
+    }
+    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.");
+    }
+    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",
+        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,
+    };
+}
+/** Persist a control-plane session atomically (temp-file + rename), mode 0600. */
+export function saveControlPlaneSession(data, path) {
+    const p = path ?? getControlPlaneSessionPath();
+    const dir = dirname(p);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.control-plane-session.${randomBytes(4).toString("hex")}.tmp`);
+    writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+    renameSync(tmp, p);
+    chmodSync(p, 0o600);
+}
+/** Delete the cached control-plane session — local half of `operator logout`. Idempotent. */
+export function clearControlPlaneSession(path) {
+    const p = path ?? getControlPlaneSessionPath();
+    try {
+        rmSync(p, { force: true });
+    }
+    catch {
+        // Best-effort: a failed unlink should never crash logout.
+    }
+}
+/** Whether a cached session is past its usable life (with a small skew buffer). */
+export function isControlPlaneSessionExpired(session, nowMs = Date.now(), skewMs = 10_000) {
+    return nowMs + skewMs >= session.expires_at;
+}
+/** Read the cached session and return it only if still usable; `null` if absent or expired. */
+export function loadLiveControlPlaneSession(path, nowMs = Date.now()) {
+    const s = readControlPlaneSession(path);
+    if (!s)
+        return null;
+    return isControlPlaneSessionExpired(s, nowMs) ? null : s;
+}
+/** Map a gateway token payload (relative `expires_in`) into the cached shape (absolute `expires_at`). */
+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",
+        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,
+    };
+}
+//# sourceMappingURL=control-plane-session.js.map

package/lib/deploy-v2.mjs

@@ -93,7 +93,7 @@ Options:
   --allow-warnings        Continue past plan warnings that require confirmation
 
 Output:
-  stdout: { "status": "ok", "release_id": "rel_...", "operation_id": "op_...", "urls": {...}, "warnings": [...] }
+  stdout: { "release_id": "rel_...", "operation_id": "op_...", "urls": {...}, "warnings": [...] }
   stderr: one JSON event per line (suppressed with --quiet or --final-only)
 
 Secrets:
@@ -141,7 +141,7 @@ the pointer-swap activation). The gateway re-runs only the failed phase
 forward — SQL is never replayed.
 
 Output:
-  stdout: { "status": "ok", "release_id": "...", "operation_id": "...", "urls": {...} }
+  stdout: { "release_id": "...", "operation_id": "...", "urls": {...} }
   stderr: one JSON event per line (suppressed with --quiet)
 `;
 
@@ -155,7 +155,7 @@ Options:
   --limit <n>             Maximum number of operations to return
 
 Output:
-  stdout: { "status": "ok", "operations": [...], "cursor": "..." | null }
+  stdout: { "operations": [...], "cursor": "..." | null }
 `;
 
 const EVENTS_HELP = `run402 deploy events — Fetch the recorded event stream for a deploy operation
@@ -167,7 +167,7 @@ Options:
   --project <id>          Project ID that owns the operation (default: active project)
 
 Output:
-  stdout: { "status": "ok", "events": [...] }
+  stdout: { "events": [...] }
 `;
 
 const RELEASE_HELP = `run402 deploy release — Inspect deploy release inventory and diffs
@@ -183,8 +183,8 @@ Subcommands:
   diff      Diff two release targets
 
 Output:
-  get/active: { "status": "ok", "release": {...} }  # includes route inventory and inventory warnings when returned
-  diff:       { "status": "ok", "diff": {...} }     # includes route added/removed/changed diff buckets
+  get/active: { "release": {...} }  # includes route inventory and inventory warnings when returned
+  diff:       { "diff": {...} }     # includes route added/removed/changed diff buckets
 `;
 
 const RELEASE_GET_HELP = `run402 deploy release get — Fetch a release inventory by id
@@ -197,7 +197,7 @@ Options:
   --site-limit <n>        Maximum site path entries to include (gateway default: 5000)
 
 Output:
-  stdout: { "status": "ok", "release": {...} }  # preserves full routes inventory and warnings
+  stdout: { "release": {...} }  # preserves full routes inventory and warnings
 `;
 
 const RELEASE_ACTIVE_HELP = `run402 deploy release active — Fetch the active release inventory
@@ -210,7 +210,7 @@ Options:
   --site-limit <n>        Maximum site path entries to include (gateway default: 5000)
 
 Output:
-  stdout: { "status": "ok", "release": {...} }  # preserves full routes inventory and warnings
+  stdout: { "release": {...} }  # preserves full routes inventory and warnings
 `;
 
 const RELEASE_DIFF_HELP = `run402 deploy release diff — Diff two release targets
@@ -225,7 +225,7 @@ Options:
   --limit <n>             Maximum entries per site diff bucket (gateway default: 1000)
 
 Output:
-  stdout: { "status": "ok", "diff": {...} }  # preserves routes.added/removed/changed
+  stdout: { "diff": {...} }  # preserves routes.added/removed/changed
 `;
 
 const DIAGNOSE_HELP = `run402 deploy diagnose — Diagnose a Run402 public URL
@@ -244,7 +244,7 @@ Options:
   --method <method>       HTTP method to diagnose (default: GET)
 
 Output:
-  stdout: { "status": "ok", "would_serve": true|false, "diagnostic_status": 200|404|..., "match": "...", "summary": "...", "request": {...}, "warnings": [...], "resolution": {...}, "next_steps": [...] }
+  stdout: { "would_serve": true|false, "diagnostic_status": 200|404|..., "match": "...", "summary": "...", "request": {...}, "warnings": [...], "resolution": {...}, "next_steps": [...] }
 `;
 
 const RESOLVE_HELP = `run402 deploy resolve — Low-level deploy URL diagnostics
@@ -326,7 +326,6 @@ Options:
 
 Output:
   stdout: {
-    "status": "ok",
     "release_id": "rel_old_abc123",
     "operation_id": "op_...",
     "previous_release_id": "rel_new_xxx",

package/lib/image.mjs

@@ -20,7 +20,7 @@ Examples:
   run402 image generate "portrait of a cat CEO" --aspect portrait --output cat.png
 
 Output (without --output):
-  { "status": "ok", "aspect": "square", "content_type": "image/png", "image": "<base64>" }
+  { "aspect": "square", "content_type": "image/png", "image": "<base64>" }
 
 Notes:
   - Requires a funded allowance (run402 allowance create && run402 allowance fund)

package/lib/operator.mjs

@@ -19,6 +19,8 @@
 
 import { setTimeout as sleep } from "node:timers/promises";
 import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { randomBytes, createHash } from "node:crypto";
 import { fail, reportSdkError } from "./sdk-errors.mjs";
 import { getSdk } from "./sdk.mjs";
 import { normalizeArgv, hasHelp, assertKnownFlags } from "./argparse.mjs";
@@ -30,6 +32,13 @@ import {
   isOperatorSessionExpired,
   operatorSessionFromTokenResponse,
 } from "../core-dist/operator-session.js";
+import {
+  saveControlPlaneSession,
+  clearControlPlaneSession,
+  readControlPlaneSession,
+  isControlPlaneSessionExpired,
+  controlPlaneSessionFromTokenResponse,
+} from "../core-dist/control-plane-session.js";
 
 const CLIENT_NAME = "run402 CLI";
 
@@ -40,19 +49,25 @@ The operator is YOU, the human, identified by email — distinct from the agent
 For a single wallet's account state, use 'run402 status'.
 
 Usage:
-  run402 operator login [--no-open]
+  run402 operator login [--no-open]              (read session, device-flow)
+  run402 operator login --loopback [--no-open]   (write session, loopback-PKCE)
+  run402 operator login --step-up                (fresh write session for high-stakes ops)
   run402 operator overview
   run402 operator whoami
   run402 operator logout
 
 Subcommands:
-  login      Sign in via the browser (device-authorization, like 'aws sso login')
+  login      Sign in via the browser. Default = device-flow READ session (powers
+             'overview'). --loopback = write-capable control-plane session
+             (aws-sso-style, passkey-fresh). --step-up = re-mint a fresh write session.
   overview   Account view across ALL wallets controlling your email (requires login)
-  whoami     Show the cached session (email, wallets, expiry) — local, no network
-  logout     Revoke the session server-side and clear the local cache
+  whoami     Show the cached session(s) — local, no network
+  logout     Revoke the session server-side and clear the local cache(s)
 
 Options:
-  --no-open  (login) Do not auto-open the browser; just print the URL + code.
+  --no-open  (login) Do not auto-open the browser; just print the URL.
+  --loopback (login) Use the loopback-PKCE write login instead of the device flow.
+  --step-up  (login) Re-mint a fresh write session (implies --loopback).
 
 Notes:
   - The session is cached at the base config dir, shared across named wallets.
@@ -96,8 +111,154 @@ function openBrowser(url) {
   }
 }
 
+/** Output shape for the write (control-plane) session. NEVER includes the token. */
+function controlPlaneView(session, nowMs = Date.now()) {
+  return {
+    logged_in: true,
+    kind: "control_plane_session",
+    provenance: session.provenance,
+    principal_id: session.principal_id || null,
+    amr: session.amr,
+    expires_at: new Date(session.expires_at).toISOString(),
+    expires_in_seconds: Math.max(0, Math.round((session.expires_at - nowMs) / 1000)),
+    write_capable: true,
+  };
+}
+
+const base64url = (buf) => buf.toString("base64url");
+
+/** Generate PKCE (S256) + CSRF state + replay nonce for the loopback flow. */
+function pkce() {
+  const codeVerifier = base64url(randomBytes(32));
+  const codeChallenge = base64url(createHash("sha256").update(codeVerifier).digest());
+  return { codeVerifier, codeChallenge, state: base64url(randomBytes(16)), nonce: base64url(randomBytes(16)) };
+}
+
+/**
+ * Start a 127.0.0.1 loopback server (RFC 8252) that captures exactly one
+ * redirect. Returns the bound port (via `ready`), a promise for the auth code,
+ * and a `close()`. State is validated here to reject CSRF before exchange.
+ */
+function startLoopbackServer({ expectedState, timeoutMs }) {
+  let resolveCode;
+  let rejectCode;
+  const codePromise = new Promise((res, rej) => {
+    resolveCode = res;
+    rejectCode = rej;
+  });
+  let timer;
+  const server = createServer((req, res) => {
+    let u;
+    try {
+      u = new URL(req.url, "http://127.0.0.1");
+    } catch {
+      res.writeHead(400).end("bad request");
+      return;
+    }
+    if (u.pathname !== "/callback") {
+      res.writeHead(404).end("not found");
+      return;
+    }
+    const code = u.searchParams.get("code");
+    const gotState = u.searchParams.get("state");
+    const errParam = u.searchParams.get("error");
+    res.writeHead(200, { "content-type": "text/html" });
+    res.end(
+      "<!doctype html><html><body style=\"font-family:system-ui;padding:3rem\">" +
+        "<h2>run402 - you're signed in.</h2><p>You can close this window and return to your terminal.</p></body></html>",
+    );
+    cleanup();
+    if (errParam) rejectCode(new Error(`authorization error: ${errParam}`));
+    else if (!code) rejectCode(new Error("no authorization code on the loopback redirect"));
+    else if (gotState !== expectedState) rejectCode(new Error("state mismatch on the loopback redirect (possible CSRF) - aborted"));
+    else resolveCode(code);
+  });
+  function cleanup() {
+    clearTimeout(timer);
+    try {
+      server.close();
+    } catch {
+      // already closing
+    }
+  }
+  timer = setTimeout(() => {
+    cleanup();
+    rejectCode(new Error("timed out waiting for browser approval"));
+  }, timeoutMs);
+  server.on("error", (e) => {
+    cleanup();
+    rejectCode(e);
+  });
+  const ready = new Promise((res, rej) => {
+    server.once("error", rej);
+    server.listen(0, "127.0.0.1", () => res(server.address().port));
+  });
+  return { ready, codePromise, close: cleanup };
+}
+
+/**
+ * Loopback-PKCE write-login (RFC 8252, the aws-sso-style flow). Mints a
+ * write-capable control-plane session via the browser passkey ceremony, caches
+ * it (mode 0600), and prints metadata only - never the token.
+ */
+async function loopbackLogin(args, { stepUp }) {
+  const noOpen = args.includes("--no-open");
+  const sdk = getSdk();
+  const { codeVerifier, codeChallenge, state, nonce } = pkce();
+  const { ready, codePromise, close } = startLoopbackServer({ expectedState: state, timeoutMs: 300_000 });
+
+  let port;
+  try {
+    port = await ready;
+  } catch (err) {
+    close();
+    return fail({ code: "OPERATOR_LOOPBACK_FAILED", message: `Could not start the loopback server: ${err.message}` });
+  }
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const authorizeUrl = sdk.operator.buildCliAuthorizeUrl({ redirectUri, codeChallenge, state, nonce });
+
+  process.stderr.write(
+    `\nTo ${stepUp ? "re-authenticate (step-up)" : "sign in (write-capable)"}, open:\n  ${authorizeUrl}\n\n`,
+  );
+  if (!noOpen && process.stderr.isTTY) {
+    openBrowser(authorizeUrl);
+    process.stderr.write("(opening your browser…)\n\n");
+  }
+  process.stderr.write("Waiting for approval…\n");
+
+  let code;
+  try {
+    code = await codePromise;
+  } catch (err) {
+    close();
+    return fail({
+      code: "OPERATOR_LOGIN_FAILED",
+      message: err.message,
+      hint: "Run 'run402 operator login --loopback' to try again.",
+    });
+  }
+
+  let session;
+  try {
+    session = await sdk.operator.exchangeCliToken({ code, codeVerifier, redirectUri, state });
+  } catch (err) {
+    return reportSdkError(err);
+  }
+
+  const cached = controlPlaneSessionFromTokenResponse(session);
+  saveControlPlaneSession(cached);
+  process.stderr.write(`\nSigned in (write-capable, provenance=${cached.provenance}).\n`);
+  console.log(JSON.stringify(controlPlaneView(cached)));
+}
+
 async function login(args) {
-  assertKnownFlags(args, ["--help", "-h", "--no-open"]);
+  assertKnownFlags(args, ["--help", "-h", "--no-open", "--loopback", "--device", "--step-up"]);
+  // Loopback-PKCE = the write-capable control-plane login (--loopback/--step-up).
+  // The default stays the device-flow READ session (which powers 'overview');
+  // --device forces it explicitly.
+  if (args.includes("--loopback") || args.includes("--step-up")) {
+    return loopbackLogin(args, { stepUp: args.includes("--step-up") });
+  }
   const noOpen = args.includes("--no-open");
   const sdk = getSdk();
 
@@ -184,6 +345,7 @@ async function logout(args) {
     }
   }
   clearOperatorSession();
+  clearControlPlaneSession();
   console.log(JSON.stringify({ revoked, cleared: true }));
 }
 
@@ -219,17 +381,27 @@ async function whoami(args) {
   assertKnownFlags(args, ["--help", "-h"]);
   const now = Date.now();
   const session = readOperatorSession();
-  if (!session) {
-    console.log(JSON.stringify({ logged_in: false, reason: "no_session", hint: "Run 'run402 operator login' to sign in." }));
-    process.exitCode = 1;
+  const cp = readControlPlaneSession();
+  const liveCp = cp && !isControlPlaneSessionExpired(cp, now) ? cp : null;
+
+  if (session && !isOperatorSessionExpired(session, now)) {
+    const view = sessionView(session, now);
+    if (liveCp) view.control_plane = controlPlaneView(liveCp, now);
+    console.log(JSON.stringify(view));
     return;
   }
-  if (isOperatorSessionExpired(session, now)) {
-    console.log(JSON.stringify({ logged_in: false, reason: "expired", email: session.email, hint: "Run 'run402 operator login' to sign in again." }));
+  // No live device-flow READ session — fall back to the write session if present.
+  if (liveCp) {
+    console.log(JSON.stringify(controlPlaneView(liveCp, now)));
+    return;
+  }
+  if (!session) {
+    console.log(JSON.stringify({ logged_in: false, reason: "no_session", hint: "Run 'run402 operator login' to sign in." }));
     process.exitCode = 1;
     return;
   }
-  console.log(JSON.stringify(sessionView(session, now)));
+  console.log(JSON.stringify({ logged_in: false, reason: "expired", email: session.email, hint: "Run 'run402 operator login' to sign in again." }));
+  process.exitCode = 1;
 }
 
 export async function run(sub, args = []) {