run402 2.30.0 → 2.32.0

package/cli.mjs

@@ -48,6 +48,7 @@ Commands:
   billing     Email billing accounts, Stripe tier checkout, email packs
   contracts   KMS contract wallets ($0.04/day rental + $0.000005/sign)
   agent       Manage agent identity (contact info)
+  operator    Operator (human/email) session — login, then overview across your wallets
   service     Run402 service health and availability (status, health)
   cache       Inspect and invalidate the SSR origin cache (inspect, invalidate)
   doctor      Health and config diagnostics (machine-readable with --json)
@@ -244,6 +245,11 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "operator": {
+    const { run } = await import("./lib/operator.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "auth": {
     const { run } = await import("./lib/auth.mjs");
     await run(sub, rest);

package/core-dist/operator-session.js

@@ -0,0 +1,154 @@
+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 operator session: `{base}/operator-session.json`, at the
+ * BASE config dir — NOT the per-profile dir, because the session is email-
+ * scoped and shared across all local named wallets. `RUN402_OPERATOR_SESSION_PATH`
+ * overrides for testing, mirroring `RUN402_ALLOWANCE_PATH`.
+ */
+export function getOperatorSessionPath() {
+    return process.env.RUN402_OPERATOR_SESSION_PATH || join(getConfigBaseDir(), "operator-session.json");
+}
+/**
+ * If the session file is readable by group or other (any low 0o077 bit set),
+ * tighten it to 0600 and warn once on stderr — the bearer token is as sensitive
+ * as the allowance private key. Best-effort: POSIX-only, silent elsewhere.
+ * Mirrors the self-heal in `allowance.ts`.
+ */
+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 operator session from disk.
+ *
+ * Returns `null` for the "no session cached" cases (file absent, unreadable, or
+ * unparseable JSON) — callers treat that as "not logged in" and point at
+ * `run402 operator login`. Throws a structured `Error` when the file parses as
+ * JSON but the shape is wrong, so a corrupted cache surfaces a clear fix-it
+ * instead of a downstream `TypeError`.
+ */
+export function readOperatorSession(path) {
+    const p = path ?? getOperatorSessionPath();
+    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 {
+        // Unparseable input reads as "no session" rather than an error — consumers
+        // already handle null with a friendly "run 'run402 operator login'".
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`operator-session.json must contain a JSON object (got ${Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed}). Delete the file and run 'run402 operator login' to recreate it.`);
+    }
+    const data = parsed;
+    if (typeof data.operator_session_token !== "string" || data.operator_session_token.length === 0) {
+        throw new Error("operator-session.json missing valid 'operator_session_token'. Run 'run402 operator login' to refresh it.");
+    }
+    if (typeof data.email !== "string" || data.email.length === 0) {
+        throw new Error("operator-session.json missing valid 'email'. Run 'run402 operator login' to refresh it.");
+    }
+    if (typeof data.expires_at !== "number" || !Number.isFinite(data.expires_at)) {
+        throw new Error("operator-session.json missing valid 'expires_at'. Run 'run402 operator login' to refresh it.");
+    }
+    if (!Array.isArray(data.wallets) || data.wallets.some((w) => typeof w !== "string")) {
+        throw new Error("operator-session.json has an invalid 'wallets' list. Run 'run402 operator login' to refresh it.");
+    }
+    return {
+        operator_session_token: data.operator_session_token,
+        token_type: typeof data.token_type === "string" ? data.token_type : "Bearer",
+        email: data.email,
+        wallets: data.wallets,
+        expires_at: data.expires_at,
+        absolute_expires_at: typeof data.absolute_expires_at === "string" ? data.absolute_expires_at : "",
+    };
+}
+/** Persist an operator session atomically (temp-file + rename), mode 0600. */
+export function saveOperatorSession(data, path) {
+    const p = path ?? getOperatorSessionPath();
+    const dir = dirname(p);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.operator-session.${randomBytes(4).toString("hex")}.tmp`);
+    writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+    renameSync(tmp, p);
+    chmodSync(p, 0o600);
+}
+/**
+ * Delete the cached operator session — the local half of `operator logout`.
+ * Best-effort and idempotent: a missing file is a no-op.
+ */
+export function clearOperatorSession(path) {
+    const p = path ?? getOperatorSessionPath();
+    try {
+        rmSync(p, { force: true });
+    }
+    catch {
+        // Best-effort: a failed unlink should never crash logout.
+    }
+}
+/**
+ * Whether a cached session is past its usable life. The access token
+ * (`expires_at`, ~30m) always expires before the absolute cap (~12h), so
+ * checking it is sufficient; the absolute cap is honored defensively. A small
+ * skew buffer treats a session expiring within `skewMs` as already expired, so
+ * we never send a token that dies mid-flight.
+ */
+export function isOperatorSessionExpired(session, nowMs = Date.now(), skewMs = 10_000) {
+    if (nowMs + skewMs >= session.expires_at)
+        return true;
+    if (session.absolute_expires_at) {
+        const cap = Date.parse(session.absolute_expires_at);
+        if (Number.isFinite(cap) && nowMs + skewMs >= cap)
+            return true;
+    }
+    return false;
+}
+/**
+ * Read the cached session and return it only if still usable; `null` if absent
+ * or expired. The bearer fetch path and `operator overview` use this so an
+ * expired cache surfaces as "not logged in" instead of a server 401.
+ */
+export function loadLiveOperatorSession(path, nowMs = Date.now()) {
+    const s = readOperatorSession(path);
+    if (!s)
+        return null;
+    return isOperatorSessionExpired(s, nowMs) ? null : s;
+}
+/**
+ * Map a gateway token payload (relative `expires_in`) into the cached shape
+ * (absolute `expires_at`). `nowMs` is injectable for deterministic tests.
+ */
+export function operatorSessionFromTokenResponse(resp, nowMs = Date.now()) {
+    return {
+        operator_session_token: resp.operator_session_token,
+        token_type: resp.token_type ?? "Bearer",
+        email: resp.email ?? "",
+        wallets: Array.isArray(resp.wallets) ? resp.wallets.filter((w) => typeof w === "string") : [],
+        expires_at: nowMs + (typeof resp.expires_in === "number" ? resp.expires_in : 0) * 1000,
+        absolute_expires_at: resp.absolute_expires_at ?? "",
+    };
+}
+//# sourceMappingURL=operator-session.js.map

package/lib/jobs.mjs

@@ -1,4 +1,7 @@
-import { readFileSync } from "node:fs";
+import { createWriteStream, mkdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 
 import { getSdk } from "./sdk.mjs";
 import { resolveProjectId } from "./config.mjs";
@@ -8,6 +11,7 @@ import {
   flagValue,
   normalizeArgv,
   parseIntegerFlag,
+  positionalArgs,
   requirePositionalCount,
   validateRegularFile,
 } from "./argparse.mjs";
@@ -18,10 +22,11 @@ Usage:
   run402 jobs <subcommand> [args...] [options]
 
 Subcommands:
-  submit   --file <path>|--stdin   Submit a managed job request
-  get      <job_id>                Get a job run
-  logs     <job_id>                Read job logs
-  cancel   <job_id>                Cancel a queued or running job
+  submit          --file <path>|--stdin   Submit a managed job request
+  get             <job_id>                Get a job run
+  logs            <job_id>                Read job logs
+  cancel          <job_id>                Cancel a queued or running job
+  artifacts get   <job_id> <file>         Download a completed job's artifact
 
 Examples:
   run402 jobs submit --file job.json
@@ -29,6 +34,7 @@ Examples:
   run402 jobs get job_abc123
   run402 jobs logs job_abc123 --tail 100
   run402 jobs cancel job_abc123
+  run402 jobs artifacts get job_abc123 proof.json --output ./proof.json
 
 Notes:
   - --project defaults to the active project from 'run402 projects use'
@@ -85,6 +91,35 @@ Usage:
 
 Options:
   --project <id>    Project ID (defaults to the active project)
+`,
+  artifacts: `run402 jobs artifacts — Download outputs from a completed managed job
+
+Usage:
+  run402 jobs artifacts get <job_id> <file> --output <path> [--project <id>]
+
+Actions:
+  get <job_id> <file>   Download the named artifact to a local file
+
+Recorded artifact filenames (per run): proof.json, public.json,
+prove-output.log, prove-time.log, verify-output.log. Use 'run402 jobs get
+<job_id>' and read the 'artifacts' map for the exact set on a given run.
+`,
+  "artifacts get": `run402 jobs artifacts get — Download a completed job's artifact
+
+Usage:
+  run402 jobs artifacts get <job_id> <file> --output <path> [--project <id>]
+
+Options:
+  --output, -o <path>   Local destination path (required)
+  --project <id>        Project ID (defaults to the active project)
+
+The job must be completed and the filename must be in its recorded artifact
+set (see the 'artifacts' map from 'run402 jobs get <job_id>'); otherwise the
+gateway returns 404. Prints a JSON envelope { job_id, filename, project_id,
+output, ... } on success.
+
+Example:
+  run402 jobs artifacts get job_abc123 proof.json --output ./proof.json
 `,
 };
 
@@ -257,6 +292,83 @@ async function cancel(jobId, args = []) {
   }
 }
 
+async function artifactsGet(args = []) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(SUB_HELP["artifacts get"]);
+    process.exit(0);
+  }
+  const parsed = normalizeArgv(args);
+  const valueFlags = ["--project", "--output", "-o"];
+  assertKnownFlags(parsed, ["--project", "--output", "-o", "--help", "-h"], valueFlags);
+  const positionals = positionalArgs(parsed, valueFlags);
+  if (positionals.length < 2) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing job_id and/or artifact filename.",
+      hint: "Use `run402 jobs artifacts get <job_id> <file> --output <path>`.",
+    });
+  }
+  if (positionals.length > 2) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Unexpected argument: ${positionals[2]}`,
+      hint: "Use `run402 jobs artifacts get <job_id> <file> --output <path>`.",
+    });
+  }
+  const [jobId, filename] = positionals;
+  const output = flagValue(parsed, "--output") ?? flagValue(parsed, "-o");
+  if (!output) {
+    fail({
+      code: "BAD_USAGE",
+      message: "--output <file> required",
+      hint: "Use `run402 jobs artifacts get <job_id> <file> --output <path>`.",
+    });
+  }
+  const projectId = resolveProjectId(flagValue(parsed, "--project"));
+
+  let res;
+  try {
+    res = await getSdk().jobs.downloadArtifact(projectId, jobId, filename);
+  } catch (err) {
+    reportSdkError(err);
+    return;
+  }
+  if (!res.body) {
+    fail({ code: "EMPTY_BODY", message: "Empty response body" });
+  }
+
+  const outPath = resolve(output);
+  const contentType = res.headers.get("content-type");
+  const contentLength = Number(res.headers.get("content-length") ?? 0);
+  mkdirSync(dirname(outPath), { recursive: true });
+  await pipeline(Readable.fromWeb(res.body), createWriteStream(outPath));
+  console.log(
+    JSON.stringify({
+      job_id: jobId,
+      filename,
+      project_id: projectId,
+      output: outPath,
+      ...(contentType ? { content_type: contentType } : {}),
+      ...(contentLength > 0 ? { size_bytes: contentLength } : {}),
+    }),
+  );
+}
+
+async function artifacts(args = []) {
+  const action = args[0];
+  if (!action || action === "--help" || action === "-h") {
+    console.log(SUB_HELP.artifacts);
+    process.exit(0);
+  }
+  if (action === "get") {
+    await artifactsGet(args.slice(1));
+    return;
+  }
+  console.error(`Unknown jobs artifacts action: ${action}\n`);
+  console.log(SUB_HELP.artifacts);
+  process.exit(1);
+}
+
 function splitJobIdArg(args = [], valueFlags = []) {
   const flagsWithValues = new Set(valueFlags);
   for (let i = 0; i < args.length; i += 1) {
@@ -279,6 +391,13 @@ export async function run(sub, args = []) {
     console.log(HELP);
     process.exit(0);
   }
+  // Nested group: route before the flat-help interceptor so per-action --help
+  // (e.g. `jobs artifacts get --help`) resolves to the action's own help,
+  // mirroring `deploy release`.
+  if (sub === "artifacts") {
+    await artifacts(Array.isArray(args) ? args : []);
+    return;
+  }
   if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
     console.log(SUB_HELP[sub] || HELP);
     process.exit(0);

package/lib/operator.mjs

@@ -0,0 +1,261 @@
+/**
+ * run402 operator — the operator (human / email) session.
+ *
+ * The operator is YOU, the human, identified by email — distinct from the
+ * AGENT (your wallet / SIWX identity). One browser login spans every wallet
+ * that verified your email, so `operator overview` returns the cross-wallet
+ * union. For a single wallet's account state, use `run402 status`.
+ *
+ * Auth: browser-delegated device-authorization grant (RFC 8628, the
+ * `aws sso login` model). The CLI never performs WebAuthn — the browser does,
+ * via the existing magic-link / passkey flows — and the CLI brokers the
+ * resulting operator-session token, cached at the BASE config dir (shared
+ * across named wallets, since the session is email-scoped).
+ *
+ * Agent-first: JSON to stdout. `login` additionally prints the verification URL
+ * + user code to stderr (human-in-the-loop) and degrades gracefully when not a
+ * TTY. Gated on the gateway device-auth bridge (kychee-com/run402-private#443).
+ */
+
+import { setTimeout as sleep } from "node:timers/promises";
+import { spawn } from "node:child_process";
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { getSdk } from "./sdk.mjs";
+import { normalizeArgv, hasHelp, assertKnownFlags } from "./argparse.mjs";
+import {
+  saveOperatorSession,
+  clearOperatorSession,
+  loadLiveOperatorSession,
+  readOperatorSession,
+  isOperatorSessionExpired,
+  operatorSessionFromTokenResponse,
+} from "../core-dist/operator-session.js";
+
+const CLIENT_NAME = "run402 CLI";
+
+const HELP = `run402 operator — operator (human / email) session
+
+The operator is YOU, the human, identified by email — distinct from the agent
+(your wallet). One browser login spans every wallet that verified your email.
+For a single wallet's account state, use 'run402 status'.
+
+Usage:
+  run402 operator login [--no-open]
+  run402 operator overview
+  run402 operator whoami
+  run402 operator logout
+
+Subcommands:
+  login      Sign in via the browser (device-authorization, like 'aws sso login')
+  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
+
+Options:
+  --no-open  (login) Do not auto-open the browser; just print the URL + code.
+
+Notes:
+  - The session is cached at the base config dir, shared across named wallets.
+  - 'overview' requires 'login' and never falls back to a single wallet.
+  - JSON to stdout; 'login' prints the URL + code to stderr (human-in-the-loop).
+`;
+
+/** Shared output shape for `whoami` and the `login` success result. */
+function sessionView(session, nowMs = Date.now()) {
+  return {
+    logged_in: true,
+    email: session.email,
+    wallets: session.wallets,
+    wallet_count: session.wallets.length,
+    expires_at: new Date(session.expires_at).toISOString(),
+    absolute_expires_at: session.absolute_expires_at || null,
+    expires_in_seconds: Math.max(0, Math.round((session.expires_at - nowMs) / 1000)),
+  };
+}
+
+/** Best-effort, cross-platform browser open. Never throws. */
+function openBrowser(url) {
+  try {
+    let cmd;
+    let cmdArgs;
+    if (process.platform === "darwin") {
+      cmd = "open";
+      cmdArgs = [url];
+    } else if (process.platform === "win32") {
+      cmd = "cmd";
+      cmdArgs = ["/c", "start", "", url];
+    } else {
+      cmd = "xdg-open";
+      cmdArgs = [url];
+    }
+    const child = spawn(cmd, cmdArgs, { stdio: "ignore", detached: true });
+    child.on("error", () => {}); // ignore: the URL is also printed to stderr
+    child.unref();
+  } catch {
+    // Best-effort only — the human can always copy the printed URL.
+  }
+}
+
+async function login(args) {
+  assertKnownFlags(args, ["--help", "-h", "--no-open"]);
+  const noOpen = args.includes("--no-open");
+  const sdk = getSdk();
+
+  let start;
+  try {
+    start = await sdk.operator.deviceStart({ clientName: CLIENT_NAME });
+  } catch (err) {
+    return reportSdkError(err);
+  }
+
+  // Human-in-the-loop prompt → stderr, so stdout stays clean for the final JSON.
+  const target = start.verification_uri_complete || start.verification_uri;
+  process.stderr.write(
+    `\nTo authorize the ${CLIENT_NAME}, open:\n  ${start.verification_uri}\n` +
+      `and enter the code:  ${start.user_code}\n\n`,
+  );
+  if (!noOpen && process.stderr.isTTY) {
+    openBrowser(target);
+    process.stderr.write("(opening your browser…)\n\n");
+  }
+  process.stderr.write("Waiting for approval…\n");
+
+  // Poll loop — honor the server interval, back off on slow_down, and stop at
+  // the device-code deadline. if/else (not switch) so the sync scanner doesn't
+  // mistake the poll states for CLI subcommands.
+  let intervalMs = Math.max(1, Number(start.interval) || 5) * 1000;
+  const deadline = Date.now() + Math.max(1, Number(start.expires_in) || 600) * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    let result;
+    try {
+      result = await sdk.operator.devicePoll(start.device_code);
+    } catch (err) {
+      return reportSdkError(err);
+    }
+    if (result.kind === "approved") {
+      const session = operatorSessionFromTokenResponse(result.session);
+      saveOperatorSession(session);
+      process.stderr.write(`\nSigned in as ${session.email}.\n`);
+      console.log(JSON.stringify(sessionView(session)));
+      return;
+    }
+    if (result.kind === "authorization_pending") continue;
+    if (result.kind === "slow_down") {
+      intervalMs += 5000;
+      continue;
+    }
+    if (result.kind === "access_denied") {
+      fail({
+        code: "OPERATOR_LOGIN_DENIED",
+        message: "Authorization was denied in the browser.",
+        hint: "Run 'run402 operator login' to try again.",
+      });
+    }
+    if (result.kind === "expired_token") {
+      fail({
+        code: "OPERATOR_LOGIN_EXPIRED",
+        message: "The device code expired before approval.",
+        hint: "Run 'run402 operator login' to get a fresh code.",
+      });
+    }
+    fail({ code: "OPERATOR_LOGIN_FAILED", message: `Unexpected device poll result: ${result.kind}` });
+  }
+  fail({
+    code: "OPERATOR_LOGIN_TIMEOUT",
+    message: "Timed out waiting for browser approval.",
+    hint: "Run 'run402 operator login' to try again.",
+  });
+}
+
+async function logout(args) {
+  assertKnownFlags(args, ["--help", "-h"]);
+  const session = loadLiveOperatorSession();
+  let revoked = false;
+  if (session) {
+    try {
+      await getSdk().operator.revoke({ token: session.operator_session_token });
+      revoked = true;
+    } catch {
+      // Best-effort: a failed server revoke (expired token, offline) must not
+      // block clearing the local cache. The local token is removed regardless.
+      revoked = false;
+    }
+  }
+  clearOperatorSession();
+  console.log(JSON.stringify({ revoked, cleared: true }));
+}
+
+async function overview(args) {
+  assertKnownFlags(args, ["--help", "-h"]);
+  const session = loadLiveOperatorSession();
+  if (!session) {
+    fail({
+      code: "OPERATOR_LOGIN_REQUIRED",
+      message: "No operator session. Run 'run402 operator login' to sign in.",
+      hint: "operator overview shows the union across all wallets controlling your email; for a single wallet use 'run402 status'.",
+    });
+  }
+  try {
+    const result = await getSdk().operator.overview({ token: session.operator_session_token });
+    console.log(JSON.stringify(result, null, 2));
+  } catch (err) {
+    // 401/403 means the session was revoked or expired server-side. Clear the
+    // stale cache and point at re-login instead of leaving a dead token behind.
+    if (err && (err.status === 401 || err.status === 403)) {
+      clearOperatorSession();
+      fail({
+        code: "OPERATOR_SESSION_INVALID",
+        message: "Operator session is no longer valid (revoked or expired).",
+        hint: "Run 'run402 operator login' to sign in again.",
+      });
+    }
+    reportSdkError(err);
+  }
+}
+
+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;
+    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." }));
+    process.exitCode = 1;
+    return;
+  }
+  console.log(JSON.stringify(sessionView(session, now)));
+}
+
+export async function run(sub, args = []) {
+  args = normalizeArgv(args);
+  if (!sub || sub === "--help" || sub === "-h" || hasHelp(args)) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  switch (sub) {
+    case "login":
+      await login(args);
+      break;
+    case "logout":
+      await logout(args);
+      break;
+    case "overview":
+      await overview(args);
+      break;
+    case "whoami":
+      await whoami(args);
+      break;
+    default:
+      fail({
+        code: "BAD_USAGE",
+        message: `Unknown subcommand: operator ${sub}`,
+        hint: "Run 'run402 operator --help' for usage.",
+      });
+  }
+}

package/package.json

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