@redaktyn/cli 1.1.1 → 1.2.0

package/README.md

@@ -193,6 +193,58 @@ After generating the JSON:
 
 ---
 
+## `redaktyn-connect` and `redaktyn-invite` — a developer who never holds admin credentials
+
+`redaktyn-import` and `redaktyn-scan` normally need an OWNER/ADMIN login token and the workspace
+passphrase. That is the right thing for an admin, and the wrong thing to hand a developer who only has to
+enrol one engagement's secrets. An invite gives them the narrow version instead.
+
+**Admin: mint a single-use link for one project.**
+
+```bash
+export REDAKTYN_SERVER_URL=https://redaktyn-api.onrender.com
+export REDAKTYN_TOKEN=...                 # OWNER/ADMIN login token
+export REDAKTYN_PASSPHRASE='...'          # stays on this machine
+
+redaktyn-invite --project acme-engagement --can-enrol --expires-days 3
+# -> https://redaktyn.com/connect?code=ABCD1234#w=...
+```
+
+The project's scanning key is derived locally and sealed under a one-time key that exists only in the link's
+`#fragment`. The server stores ciphertext it cannot open, and the fragment is never sent to it. `--can-enrol`
+is off unless you ask: without it the link is scan-only. A link carries a key for **one** device, so it works
+once.
+
+**Developer: connect once, then work.**
+
+```bash
+redaktyn-connect                 # prompts for the link, so it stays out of shell history
+redaktyn-import --env .env                 # dry run, no environment variables needed
+redaktyn-import --env .env --apply
+redaktyn-scan --staged                     # also uses the saved key
+redaktyn-connect --status | --logout
+```
+
+What the developer has, and does not have:
+
+| | |
+|---|---|
+| Can | scan, and (with `--can-enrol`) register and re-fingerprint secrets **on that one project** |
+| Cannot | enrol anywhere else, delete or edit a secret, see another project's digests, or reach any admin route |
+| Holds | that project's key only (`HKDF(workspace key, project id)`), never the workspace key or passphrase |
+| Revoked by | an admin removing the device (`DELETE /api/users/:id`): it stops working at once, not when a token expires |
+
+The session lives in `~/.config/redaktyn/session.json` (directory `0700`, file `0600`), the same protection
+`~/.aws/credentials` relies on. It is a file and not the OS keychain on purpose: macOS `security
+add-generic-password` takes the secret as a command-line argument, which any process on the machine can read
+with `ps` while it runs. The token renews itself; if the session cannot be renewed, or an admin removed the
+device, the command says to ask for a new link. An admin's own `REDAKTYN_TOKEN` in the environment always takes
+precedence over a saved session.
+
+**Server note:** `--can-enrol` needs the `InviteEnrolGrant` table. Schema changes here are applied by hand
+(`npx prisma db push`), and an invite minted before that is refused with `ENROL_GRANTS_UNAVAILABLE` rather
+than quietly becoming a plain link.
+
 ## `redaktyn-import` — bulk enrollment from files and vaults
 
 Enrollment used to mean typing every secret into the dashboard by hand, so coverage was

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@redaktyn/cli",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Redaktyn CLI: bulk-enrol secrets from a .env or any vault (--project aware), local fingerprints, git/directory digest scans. Digests are computed on your machine; secret values never leave it.",
   "type": "module",
   "bin": {
     "redaktyn-fingerprint": "./redaktyn-fingerprint.mjs",
     "redaktyn-import": "./redaktyn-import.mjs",
     "redaktyn-scan": "./redaktyn-scan.mjs",
-    "redaktyn-verify": "./redaktyn-verify.mjs"
+    "redaktyn-verify": "./redaktyn-verify.mjs",
+    "redaktyn-connect": "./redaktyn-connect.mjs",
+    "redaktyn-invite": "./redaktyn-invite.mjs"
   },
   "dependencies": {
     "@redaktyn/shared": "^1.0.0"
@@ -37,10 +39,13 @@
     "access": "public"
   },
   "files": [
+    "README.md",
+    "redaktyn-connect.mjs",
     "redaktyn-fingerprint.mjs",
     "redaktyn-import.mjs",
+    "redaktyn-invite.mjs",
     "redaktyn-scan.mjs",
-    "redaktyn-verify.mjs",
-    "README.md"
+    "redaktyn-session.mjs",
+    "redaktyn-verify.mjs"
   ]
 }

package/redaktyn-connect.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * redaktyn-connect: set this machine up from an invite link, so enrolling secrets
+ * never needs an admin login or the workspace passphrase.
+ *
+ *   redaktyn-connect                 prompts for the link (kept out of shell history)
+ *   redaktyn-connect --stdin         reads the link from standard input
+ *   redaktyn-connect '<link>'        quote it: the part after # is the key
+ *   redaktyn-connect --status        what this machine is connected to
+ *   redaktyn-connect --logout        forget the session on this machine
+ *
+ * After connecting, `redaktyn-import --env .env` needs no environment variables.
+ * Ask your admin for the link; they create it with `redaktyn-invite`.
+ */
+import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+import * as readline from "node:readline";
+
+import { SessionError, connectWithInvite, deleteSession, loadSession, sessionDir } from "./redaktyn-session.mjs";
+
+function help() {
+  console.log(`redaktyn-connect: set this machine up from an invite link
+
+  redaktyn-connect                 prompt for the link (not saved in shell history)
+  redaktyn-connect --stdin         read the link from standard input
+  redaktyn-connect '<link>'        pass the link; quote it, the key is after the #
+  redaktyn-connect --status        show what this machine is connected to
+  redaktyn-connect --logout        forget the session on this machine
+
+  --server <url>   Override the server (default: the link's own address)
+
+The session is stored in ${sessionDir()} (readable only by you).`);
+}
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (a) => { rl.close(); resolve(a.trim()); });
+  });
+}
+async function readStdin() {
+  let s = "";
+  for await (const c of process.stdin) s += c;
+  return s.trim();
+}
+
+function show(s) {
+  console.log(`Connected to ${s.orgName ?? s.orgId}${s.projectName ? `, project ${s.projectName}` : ""}.`);
+  console.log(`  server        ${s.serverUrl}`);
+  console.log(`  can enrol     ${s.canEnrol ? "yes, on this project only" : "no (scan only). Ask for an invite that allows enrolling."}`);
+  console.log(`  key           ${s.keyFingerprint} (a fingerprint, never the key)`);
+}
+
+export async function main(argv) {
+  const args = argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) return help(), 0;
+  if (args.includes("--logout")) {
+    const had = !!loadSession();
+    deleteSession();
+    console.log(had ? "Forgot this machine's Redaktyn session." : "There was no session to forget.");
+    return 0;
+  }
+  if (args.includes("--status")) {
+    const s = loadSession();
+    if (!s) { console.log("Not connected. Run: redaktyn-connect"); return 1; }
+    show(s);
+    return 0;
+  }
+  const si = args.indexOf("--server");
+  const server = si >= 0 ? args[si + 1] : undefined;
+  let link = args.find((a, i) => !a.startsWith("--") && args[i - 1] !== "--server");
+  if (args.includes("--stdin")) link = await readStdin();
+  if (!link) {
+    if (!process.stdin.isTTY) { console.error("Pass the link, use --stdin, or run this in a terminal."); return 2; }
+    link = await ask("Invite link: ");
+  }
+  try {
+    const s = await connectWithInvite(link, { serverUrl: server });
+    show(s);
+    console.log("\nNext: redaktyn-import --env .env     (add --apply to register)");
+    return 0;
+  } catch (e) {
+    if (e instanceof SessionError) { console.error(e.message); return 1; }
+    throw e;
+  }
+}
+
+function realArgv1() { try { return realpathSync(process.argv[1]); } catch { return process.argv[1]; } }
+if (process.argv[1] && import.meta.url === pathToFileURL(realArgv1()).href) {
+  main(process.argv).then((c) => process.exit(c), (e) => { console.error(e.message); process.exit(1); });
+}

package/redaktyn-import.mjs

@@ -48,6 +48,7 @@ import {
   deriveProjectKey,
   enrollPayload,
 } from "./redaktyn-fingerprint.mjs";
+import { freshSession, loadSession } from "./redaktyn-session.mjs";
 
 /* ═══════════════════════════════════════════════════════════════
    Colors
@@ -945,8 +946,16 @@ async function resolveProject(serverUrl, token, wanted) {
   return matches[0];
 }
 
-async function fetchExistingSecrets(serverUrl, token) {
+async function fetchExistingSecrets(serverUrl, token, viaSession = false) {
   const r = await apiRequest(serverUrl, token, "GET", "/api/secrets");
+  if (viaSession && (r.status === 401 || r.status === 403)) {
+    // A connected developer is not holding an admin token, so telling them to set
+    // one would send them the wrong way. Their device was removed or ended.
+    throw new UsageError(
+      "This machine's Redaktyn session is no longer valid: the device was removed or its session ended. " +
+        "Ask your admin for a new invite link and run `redaktyn-connect` again."
+    );
+  }
   if (r.status === 401) {
     throw new UsageError(
       "Server rejected the token (401). REDAKTYN_TOKEN must be a current OWNER or ADMIN login token."
@@ -1411,6 +1420,59 @@ async function resolveCredentials(args) {
   return { serverUrl, token, orgId, passphrase };
 }
 
+/**
+ * Who is enrolling, and with which key.
+ *
+ * Two ways in. An admin sets REDAKTYN_TOKEN and the workspace passphrase and may
+ * name any project with --project. A developer who ran `redaktyn-connect` has a
+ * saved session instead: its key is already the project's key, so no passphrase or
+ * admin token is involved, and it can only ever act on the project its invite named.
+ * An admin's environment wins when both exist, so a shell set up for admin work is
+ * never silently downgraded to a developer session.
+ */
+async function resolveIdentity(args) {
+  const adminEnv = process.env["REDAKTYN_TOKEN"] || process.env["REDAKTYN_JWT"];
+  const saved = adminEnv ? null : loadSession();
+  if (saved) {
+    let session;
+    try {
+      session = await freshSession(saved);
+    } catch (e) {
+      throw new UsageError(e.message);
+    }
+    if (args.project) {
+      const w = args.project.trim().toLowerCase();
+      if (w !== String(session.projectId).toLowerCase() && w !== String(session.projectName || "").toLowerCase()) {
+        throw new UsageError(
+          `This machine is connected to project "${session.projectName ?? session.projectId}" only, not "${args.project}". ` +
+            "Drop --project, or ask for an invite to the other project."
+        );
+      }
+    }
+    if (!session.projectId) throw new UsageError("This session is not tied to a project. Ask for a new invite link.");
+    if (args.apply && !session.canEnrol) {
+      throw new UsageError(
+        "This invite lets you scan but not enrol secrets. Ask your admin for a link made with: redaktyn-invite --can-enrol"
+      );
+    }
+    return {
+      serverUrl: args.server || session.serverUrl,
+      token: session.token,
+      key: Buffer.from(session.key, "hex"),
+      project: { id: session.projectId, name: session.projectName ?? session.projectId, usesOrgKey: session.projectUsesOrgKey === true },
+      viaSession: true,
+    };
+  }
+  const { serverUrl, token, orgId, passphrase } = await resolveCredentials(args);
+  const orgKey = await deriveKey(passphrase, orgId);
+  const project = args.project ? await resolveProject(serverUrl, token, args.project) : null;
+  // A project with its own key hashes under HKDF(orgKey, projectId); the default
+  // project carries the org key itself. Filing a digest under the wrong one lists
+  // as ACTIVE and matches nothing, which is why the server also checks.
+  const key = project && !project.usesOrgKey ? deriveProjectKey(orgKey, project.id) : orgKey;
+  return { serverUrl, token, key, project, viaSession: false };
+}
+
 async function main() {
   const args = parseArgs(process.argv);
   if (args.help) {
@@ -1437,15 +1499,8 @@ async function main() {
     );
   }
 
-  const { serverUrl, token, orgId, passphrase } = await resolveCredentials(args);
-
+  const { serverUrl, token, key, project, viaSession } = await resolveIdentity(args);
   const minLength = args.minLength ?? DEFAULT_MIN_LENGTH;
-  const orgKey = await deriveKey(passphrase, orgId);
-  const project = args.project ? await resolveProject(serverUrl, token, args.project) : null;
-  // A project with its own key hashes under HKDF(orgKey, projectId); the default
-  // project carries the org key itself. Filing a digest under the wrong one lists
-  // as ACTIVE and matches nothing, which is why the server also checks.
-  const key = project && !project.usesOrgKey ? deriveProjectKey(orgKey, project.id) : orgKey;
 
   const candidates = [];
   const rejected = [];
@@ -1471,7 +1526,7 @@ async function main() {
     });
   }
 
-  let existing = await fetchExistingSecrets(serverUrl, token);
+  let existing = await fetchExistingSecrets(serverUrl, token, viaSession);
   // Compared only with the chosen project's own secrets: the same label in
   // another project is a different secret under a different key.
   if (project) existing = existing.filter((s) => s && s.projectId === project.id);

package/redaktyn-invite.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * redaktyn-invite: for an admin. Mint a single-use invite link for one project,
+ * optionally allowing the person who redeems it from the CLI to enrol secrets.
+ *
+ *   redaktyn-invite --project acme-engagement --can-enrol
+ *
+ * Needs what any admin action needs: REDAKTYN_SERVER_URL, REDAKTYN_TOKEN (OWNER or
+ * ADMIN login token) and REDAKTYN_PASSPHRASE. The passphrase stays on this machine:
+ * it derives the project's key, which is sealed under a one-time key that exists
+ * only in the link's #fragment. The server stores ciphertext it cannot open.
+ *
+ * Send the link over a channel you trust. Whoever opens it first (once) gets the
+ * project's key and, with --can-enrol, the right to register secrets on it.
+ */
+import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+import * as readline from "node:readline";
+
+import { deriveKey, deriveProjectKey } from "./redaktyn-fingerprint.mjs";
+import { SessionError, apiJson, sealInviteKey } from "./redaktyn-session.mjs";
+
+function help() {
+  console.log(`redaktyn-invite: mint a single-use invite link for one project
+
+  --project <name|id>   The project the link is for (required)
+  --can-enrol           Let the redeeming CLI register secrets on that project
+  --expires-days <n>    Link lifetime (default 7)
+  --name <text>         Name to show for the person
+  --email <address>     Restrict the link to this email
+  --app-url <url>       Address to put in the link (default https://redaktyn.com)
+  --server <url>        API address (default REDAKTYN_SERVER_URL)
+
+Environment: REDAKTYN_SERVER_URL, REDAKTYN_TOKEN (OWNER/ADMIN), REDAKTYN_PASSPHRASE`);
+}
+
+function parse(argv) {
+  const o = { project: null, canEnrol: false, days: 7, name: null, email: null, appUrl: "https://redaktyn.com", server: null, help: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    const need = () => { const v = argv[++i]; if (v === undefined || v.startsWith("--")) throw new SessionError(`${a} needs a value`); return v; };
+    if (a === "--help" || a === "-h") o.help = true;
+    else if (a === "--project") o.project = need();
+    else if (a === "--can-enrol" || a === "--can-enroll") o.canEnrol = true;
+    else if (a === "--expires-days") o.days = Number(need());
+    else if (a === "--name") o.name = need();
+    else if (a === "--email") o.email = need();
+    else if (a === "--app-url") o.appUrl = need();
+    else if (a === "--server") o.server = need();
+    else throw new SessionError(`Unknown flag: ${a}`);
+  }
+  if (!Number.isInteger(o.days) || o.days < 1 || o.days > 365) throw new SessionError("--expires-days must be 1 to 365");
+  return o;
+}
+
+function promptHidden(q) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+    process.stderr.write(q + " ");
+    rl._writeToOutput = () => {};
+    rl.question("", (a) => { process.stderr.write("\n"); rl.close(); resolve(a); });
+  });
+}
+function orgIdFrom(token) {
+  try { return JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString()).orgId; } catch { return null; }
+}
+
+export async function main(argv) {
+  const o = parse(argv);
+  if (o.help) return help(), 0;
+  if (!o.project) throw new SessionError("Say which project the link is for: --project <name|id>");
+  const server = o.server || process.env["REDAKTYN_SERVER_URL"];
+  const token = process.env["REDAKTYN_TOKEN"];
+  if (!server || !token) throw new SessionError("Set REDAKTYN_SERVER_URL and REDAKTYN_TOKEN (an OWNER or ADMIN login token).");
+  const orgId = orgIdFrom(token);
+  if (!orgId) throw new SessionError("That token carries no org id.");
+  let passphrase = process.env["REDAKTYN_PASSPHRASE"];
+  if (!passphrase) {
+    if (!process.stdin.isTTY) throw new SessionError("Set REDAKTYN_PASSPHRASE (used locally to derive the key, never sent).");
+    passphrase = await promptHidden("Workspace passphrase:");
+  }
+
+  const pr = await apiJson(server, "GET", "/api/projects", { token });
+  if (!pr.ok || !Array.isArray(pr.data)) throw new SessionError(`GET /api/projects failed (${pr.status}). Is the token an OWNER/ADMIN token?`);
+  const want = o.project.trim();
+  const found = pr.data.filter((p) => p.id === want).length ? pr.data.filter((p) => p.id === want) : pr.data.filter((p) => String(p.name).toLowerCase() === want.toLowerCase());
+  if (found.length !== 1) throw new SessionError(found.length ? `"${want}" matches several projects; pass the id.` : `No project "${want}". Known: ${pr.data.map((p) => p.name).join(", ")}.`);
+  const project = found[0];
+  if (project.status === "CLOSED") throw new SessionError(`Project ${project.name} is closed.`);
+
+  const orgKey = await deriveKey(passphrase, orgId);
+  const key = project.usesOrgKey ? orgKey : deriveProjectKey(orgKey, project.id);
+  const { w, blob } = await sealInviteKey(key, project.usesOrgKey ? 1 : 2);
+
+  const r = await apiJson(server, "POST", "/api/invites", {
+    token,
+    body: {
+      projectId: project.id, keyBlob: blob, maxUses: 1, expiresInDays: o.days,
+      ...(o.canEnrol ? { canEnrol: true } : {}),
+      ...(o.name ? { assignedName: o.name } : {}), ...(o.email ? { assignedEmail: o.email } : {}),
+    },
+  });
+  if (!r.ok) throw new SessionError(`The server refused the invite (${r.status}): ${r.data?.error || r.text.slice(0, 200)}`);
+
+  const link = `${o.appUrl.replace(/\/+$/, "")}/connect?code=${r.data.code}#w=${w}`;
+  console.log(`Invite for project ${project.name}${o.canEnrol ? " (may enrol secrets)" : " (scan only)"}, single use, expires in ${o.days} day(s):\n`);
+  console.log(link);
+  console.log(`\nSend it over a channel you trust: whoever opens it first gets this project's key.`);
+  console.log(`They run:  redaktyn-connect   and paste it.   Revoke before use: DELETE /api/invites/${r.data.id}`);
+  return 0;
+}
+
+function realArgv1() { try { return realpathSync(process.argv[1]); } catch { return process.argv[1]; } }
+if (process.argv[1] && import.meta.url === pathToFileURL(realArgv1()).href) {
+  main(process.argv).then((c) => process.exit(c), (e) => { console.error(e.message); process.exit(e instanceof SessionError ? 1 : 2); });
+}

package/redaktyn-scan.mjs

@@ -299,18 +299,38 @@ async function main() {
     process.exit(2);
   }
 
+  // A machine set up with `redaktyn-connect` scans with its saved project key and
+  // token, no environment needed. Any REDAKTYN_* credential in the environment
+  // takes precedence, so an existing pipeline behaves exactly as before.
+  const envCreds =
+    process.env["REDAKTYN_DEVICE_TOKEN"] || process.env["REDAKTYN_TOKEN"] || process.env["REDAKTYN_JWT"] ||
+    process.env["REDAKTYN_PASSPHRASE"];
+  let saved = null;
+  if (!envCreds) {
+    const { loadSession, freshSession } = await import("./redaktyn-session.mjs");
+    if (loadSession()) {
+      try {
+        saved = await freshSession();
+      } catch (e) {
+        console.error(e.message);
+        process.exit(2);
+      }
+    }
+  }
+
   const serverUrl =
-    args.server || process.env["REDAKTYN_SERVER_URL"] || process.env["REDAKTYN_SERVER"];
+    args.server || saved?.serverUrl || process.env["REDAKTYN_SERVER_URL"] || process.env["REDAKTYN_SERVER"];
   const token =
+    saved?.token ||
     process.env["REDAKTYN_DEVICE_TOKEN"] ||
     process.env["REDAKTYN_TOKEN"] ||
     process.env["REDAKTYN_JWT"];
-  const passphrase = process.env["REDAKTYN_PASSPHRASE"];
+  const passphrase = saved ? "session" : process.env["REDAKTYN_PASSPHRASE"];
   const envOrgId = args.orgId || process.env["REDAKTYN_ORG_ID"];
 
   if (!serverUrl || !token || !passphrase) {
     console.error(
-      "Missing env: REDAKTYN_SERVER_URL, REDAKTYN_PASSPHRASE, and REDAKTYN_DEVICE_TOKEN (or REDAKTYN_TOKEN)."
+      "Not connected. Run `redaktyn-connect` with an invite link, or set REDAKTYN_SERVER_URL, REDAKTYN_PASSPHRASE and REDAKTYN_DEVICE_TOKEN (or REDAKTYN_TOKEN)."
     );
     process.exit(2);
   }
@@ -377,7 +397,7 @@ async function main() {
     process.exit(2);
   }
 
-  const key = await deriveHmacKeyFromPassphrase(passphrase, orgId);
+  const key = saved ? new Uint8Array(Buffer.from(saved.key, "hex")) : await deriveHmacKeyFromPassphrase(passphrase, orgId);
   const stats = { total: 0, passesRun: [], exhausted: false, truncatedChars: false };
   const endpoint = `${serverUrl.replace(/\/+$/, "")}/api/cli/scan`;
 

package/redaktyn-session.mjs

@@ -0,0 +1,201 @@
+/**
+ * The CLI's own enrolment: redeeming an invite so a developer can enrol secrets
+ * without ever holding an admin login or the workspace passphrase.
+ *
+ * What an invite hands a device is exactly what the browser extension gets: the
+ * project's scanning key, sealed under a one-time key that lives only in the link's
+ * fragment, plus a short-lived device token. The server never sees the unsealed key.
+ * This module redeems the link, unseals the key locally, keeps the result in a file
+ * only the current user can read, and renews the token as it ages.
+ *
+ * Why a file and not the OS keychain: macOS `security add-generic-password` takes
+ * the secret as a command-line argument, which any process on the machine can read
+ * with `ps` for as long as it runs. A 0600 file in a 0700 directory is the same
+ * protection `~/.aws/credentials` and `~/.ssh` rely on, without that window.
+ */
+import { createHash, randomBytes, webcrypto } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const TOKEN_REFRESH_AFTER_MS = 20 * 60 * 60 * 1000; // tokens last 24h
+export const INVITE_KEY_BYTES = 32;
+
+export class SessionError extends Error {}
+
+/* ── where it lives ─────────────────────────────────────────── */
+
+export function sessionDir() {
+  const base =
+    process.env["REDAKTYN_CONFIG_DIR"] ||
+    (process.env["XDG_CONFIG_HOME"] ? join(process.env["XDG_CONFIG_HOME"], "redaktyn") : join(homedir(), ".config", "redaktyn"));
+  return base;
+}
+const sessionFile = () => join(sessionDir(), "session.json");
+const deviceFile = () => join(sessionDir(), "device-id");
+
+function ensureDir() {
+  mkdirSync(sessionDir(), { recursive: true, mode: 0o700 });
+  try { chmodSync(sessionDir(), 0o700); } catch { /* best effort on exotic filesystems */ }
+}
+
+/** Written to a temp file and renamed, so a crash never leaves half a session. */
+function writePrivate(path, text) {
+  ensureDir();
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, text, { mode: 0o600 });
+  try { chmodSync(tmp, 0o600); } catch { /* ignore */ }
+  renameSync(tmp, path);
+}
+
+export function loadSession() {
+  const f = sessionFile();
+  if (!existsSync(f)) return null;
+  try {
+    const s = JSON.parse(readFileSync(f, "utf8"));
+    if (s && s.token && s.key && s.serverUrl && s.orgId) return s;
+  } catch { /* fall through */ }
+  return null;
+}
+export function saveSession(session) {
+  writePrivate(sessionFile(), JSON.stringify(session, null, 2) + "\n");
+}
+export function deleteSession() {
+  const f = sessionFile();
+  if (existsSync(f)) rmSync(f);
+  return true;
+}
+
+/** Stable per machine, so reconnecting the same CLI does not spend another seat. */
+export function deviceId() {
+  const f = deviceFile();
+  if (existsSync(f)) {
+    const v = readFileSync(f, "utf8").trim();
+    if (/^cli-[a-f0-9]{32}$/.test(v)) return v;
+  }
+  const id = `cli-${randomBytes(16).toString("hex")}`;
+  writePrivate(f, id + "\n");
+  return id;
+}
+
+/* ── the invite link ────────────────────────────────────────── */
+
+const b64uToBytes = (t) => Buffer.from(t.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+export const bytesToB64u = (b) => Buffer.from(b).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+
+/** `https://host/connect?code=ABC#w=KEY` -> { origin, code, w }. */
+export function parseInviteLink(link) {
+  let url;
+  try {
+    url = new URL(String(link).trim());
+  } catch {
+    throw new SessionError("That is not an invite link. It looks like https://…/connect?code=…#w=…");
+  }
+  const code = url.searchParams.get("code");
+  const w = new URLSearchParams(url.hash.replace(/^#/, "")).get("w");
+  if (!code) throw new SessionError("The link has no invite code.");
+  if (!w) {
+    throw new SessionError(
+      "The link has no key part (the bit after #w=). Copy the whole link, including everything after the #, and quote it so the shell does not cut it."
+    );
+  }
+  if (b64uToBytes(w).length !== INVITE_KEY_BYTES) throw new SessionError("The key part of the link is the wrong length.");
+  return { origin: url.origin, code, w };
+}
+
+/** AES-GCM, no AAD: the exact inverse of wrapScanKeyForInvite in the extension. */
+export async function unsealInviteKey(blob, wB64u) {
+  if (!blob || typeof blob !== "object" || (blob.v !== 1 && blob.v !== 2) || typeof blob.iv !== "string" || typeof blob.ct !== "string") {
+    throw new SessionError("The server sent no sealed key for this invite.");
+  }
+  const key = await webcrypto.subtle.importKey("raw", b64uToBytes(wB64u), { name: "AES-GCM" }, false, ["decrypt"]);
+  try {
+    const plain = await webcrypto.subtle.decrypt({ name: "AES-GCM", iv: Buffer.from(blob.iv, "base64") }, key, Buffer.from(blob.ct, "base64"));
+    const out = Buffer.from(plain);
+    if (out.length !== INVITE_KEY_BYTES) throw new Error("length");
+    return out;
+  } catch {
+    throw new SessionError("Could not open the sealed key with this link. The link may be incomplete or altered.");
+  }
+}
+
+/** Seal a 32-byte key for a link: returns the blob to POST and the link's `w`. */
+export async function sealInviteKey(keyBytes, scope) {
+  const w = randomBytes(INVITE_KEY_BYTES);
+  const iv = randomBytes(12);
+  const aes = await webcrypto.subtle.importKey("raw", w, { name: "AES-GCM" }, false, ["encrypt"]);
+  const ct = Buffer.from(await webcrypto.subtle.encrypt({ name: "AES-GCM", iv }, aes, keyBytes));
+  return { w: bytesToB64u(w), blob: { v: scope, iv: iv.toString("base64"), ct: ct.toString("base64") } };
+}
+
+/* ── talking to the server ──────────────────────────────────── */
+
+const trim = (u) => u.replace(/\/+$/, "");
+
+export async function apiJson(serverUrl, method, path, { token, body } = {}) {
+  let res;
+  try {
+    res = await fetch(`${trim(serverUrl)}${path}`, {
+      method,
+      headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), ...(body ? { "Content-Type": "application/json" } : {}) },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+  } catch (e) {
+    throw new SessionError(`Cannot reach ${trim(serverUrl)}: ${e.message}`);
+  }
+  const text = await res.text();
+  let data = null;
+  try { data = text ? JSON.parse(text) : null; } catch { data = null; }
+  return { status: res.status, ok: res.ok, data, text };
+}
+
+/** Redeem a link and keep the result. Returns the saved session. */
+export async function connectWithInvite(link, { serverUrl } = {}) {
+  const { origin, code, w } = parseInviteLink(link);
+  const server = serverUrl || process.env["REDAKTYN_SERVER_URL"] || origin;
+  const r = await apiJson(server, "POST", "/api/auth/connect", {
+    body: { inviteCode: code, extensionId: deviceId(), client: "cli" },
+  });
+  if (!r.ok) {
+    const why = r.data?.error || r.text.slice(0, 200) || `HTTP ${r.status}`;
+    throw new SessionError(`The server refused the invite (${r.status}): ${why}`);
+  }
+  const d = r.data || {};
+  if (!d.token || !d.keyBlob) {
+    throw new SessionError("The server accepted the invite but sent no sealed key, so nothing could be set up. Ask for a new link.");
+  }
+  const key = await unsealInviteKey(d.keyBlob, w);
+  const session = {
+    serverUrl: trim(server),
+    orgId: d.orgId,
+    orgName: d.orgName ?? null,
+    projectId: d.projectId ?? null,
+    projectName: d.projectName ?? null,
+    projectUsesOrgKey: d.projectUsesOrgKey ?? null,
+    canEnrol: d.canEnrol === true,
+    token: d.token,
+    tokenIssuedAt: Date.now(),
+    key: key.toString("hex"),
+    keyFingerprint: createHash("sha256").update(key).digest("hex").slice(0, 8),
+    connectedAt: new Date().toISOString(),
+  };
+  saveSession(session);
+  return session;
+}
+
+/** Renew the token if it is getting old. A refusal means the device was removed. */
+export async function freshSession(session = loadSession()) {
+  if (!session) throw new SessionError("Not connected. Run: redaktyn-connect '<invite link>'");
+  if (Date.now() - (session.tokenIssuedAt || 0) < TOKEN_REFRESH_AFTER_MS) return session;
+  const r = await apiJson(session.serverUrl, "POST", "/api/auth/refresh", { token: session.token });
+  if (!r.ok || !r.data?.token) {
+    const code = r.data?.code;
+    const hint = code === "ENROLLMENT_REVOKED" || code === "SESSION_REVOKED"
+      ? "This device was removed by an admin."
+      : "The session could not be renewed (it may have passed its maximum age).";
+    throw new SessionError(`${hint} Ask for a new invite link and run redaktyn-connect again.`);
+  }
+  const next = { ...session, token: r.data.token, tokenIssuedAt: Date.now() };
+  saveSession(next);
+  return next;
+}