@kedge/cli 0.9.0 → 0.10.1

package/src/keys-save.ts

@@ -0,0 +1,343 @@
+// `kedge keys create --save` (docs/proposals/p0.10-agent-path.md §6.2): a key
+// made through a credential reference with a CLI session, and saved to
+// `.env.local` beside the store's identity. Every step survives a lost answer:
+// a ref is recorded before it's sent, a recorded ref whose key was never saved
+// is voided before another is made (revoking a key that committed unseen, or
+// fencing one still in flight), and each key is saved before the next step.
+// Only refs this checkout recorded are ever voided, so no one else's key, nor
+// a key someone named the same, is ever touched.
+import { createHash, randomBytes } from "node:crypto";
+import type { DatabaseSync } from "node:sqlite";
+import { NeedsPerson } from "./cf";
+import { OLDER_KEDGE, type SessionDeps, withCliSession } from "./cli-session";
+import { DeployRefused } from "./deploy";
+import { ENV_FILE, type RefRecord, readEnvLocal, saveEnv, stateDb, withStoreLock } from "./local-state";
+import { storeRequest } from "./store-api";
+import type { StoreTarget } from "./target";
+
+/** The `.env.local` names a saved key goes under. */
+export const ENV = {
+  store: "KEDGE_KEYS_STORE",
+  storefront: "KEDGE_STOREFRONT_ID",
+  publishable: "KEDGE_PUBLISHABLE_KEY",
+  secret: "KEDGE_SECRET_KEY",
+} as const;
+
+export type Wanted =
+  | { kind: "publishable"; name: string; origins: readonly string[] }
+  | { kind: "secret"; name: string; grants: readonly string[] };
+
+export interface SaveDeps {
+  cwd: string;
+  fetch: typeof fetch;
+  session: SessionDeps;
+  log: (s: string) => void;
+  now?: () => number;
+}
+
+/** A store's identity as records bind to it (§4): account, Worker and database, never the URL. */
+export const identityOf = (t: StoreTarget) => `${t.identity.account}/${t.identity.worker}/${t.identity.database}`;
+
+const newRef = () => randomBytes(32).toString("base64url");
+const keyDigest = (key: string) => createHash("sha256").update(key).digest("hex");
+
+/** What the server answers for a ref: its state and what it made. */
+interface RefAnswer {
+  state: "used" | "fenced" | "revoked";
+  storefront_id: string | null;
+  key_id: string | null;
+  key?: string;
+}
+
+/** Makes (or confirms) the wanted key for `target`, saved in `.env.local`; returns what's saved. */
+export async function keysSave(target: StoreTarget, wanted: Wanted, d: SaveDeps): Promise<Record<string, string>> {
+  return withStoreLock(d.cwd, "keys create --save", () => keysSaveHeld(target, wanted, d));
+}
+
+/** The same, for a command already holding the checkout's lock (`smoke`): taking it again would refuse itself. */
+export async function keysSaveHeld(target: StoreTarget, wanted: Wanted, d: SaveDeps): Promise<Record<string, string>> {
+  const db = stateDb(d.cwd);
+  try {
+    return await save(db, target, wanted, d);
+  } finally {
+    db.close();
+  }
+}
+
+async function save(db: DatabaseSync, target: StoreTarget, wanted: Wanted, d: SaveDeps) {
+  const now = d.now ?? Date.now;
+  const store = identityOf(target);
+  const envName = wanted.kind === "publishable" ? ENV.publishable : ENV.secret;
+  const refs = () =>
+    db
+      .prepare("SELECT * FROM credential_ref WHERE store = ? AND env_name = ? ORDER BY created_at")
+      .all(store, envName) as unknown as (RefRecord & { created_at: number })[];
+  const set = (ref: string, a: Partial<RefRecord>) => {
+    const cols = Object.keys(a);
+    db.prepare(`UPDATE credential_ref SET ${cols.map((c) => `${c} = ?`).join(", ")}, updated_at = ? WHERE ref = ?`).run(
+      ...cols.map((c) => (a as Record<string, string | null>)[c] ?? null),
+      now(),
+      ref,
+    );
+  };
+
+  // 1. Every key .env.local holds is bound to its store by the ref this checkout recorded for it, by
+  // digest, never by a label beside it: a key with no such ref, or one for another store, would be sent
+  // to the wrong store or relabelled as this one's (codex code r11, r13). So any such key, of either
+  // kind, is the person's to remove before anything is saved beside it.
+  moveLocalBundle(db, d);
+  // Each store's keys in its own file (p0.10.1 §4): kedge dev's apart from Cloudflare's.
+  const envFile = target.kind === "local" ? ENV_FILE.local : ENV_FILE.production;
+  const env = readEnvLocal(d.cwd, envFile);
+  const all = db.prepare("SELECT * FROM credential_ref").all() as unknown as RefRecord[];
+  const foreign: string[] = [];
+  for (const name of [ENV.publishable, ENV.secret]) {
+    const value = env[name];
+    if (!value) continue;
+    const digest = keyDigest(value);
+    const ref = all.find((r) => r.key_digest === digest && r.env_name === name);
+    if (!ref || ref.store !== store) {
+      foreign.push(name);
+      continue;
+    }
+    // A crash between the rename and marking it saved leaves its ref `used` (codex code r10).
+    if (ref.state === "used") set(ref.ref, { state: "saved" });
+  }
+  const sf = env[ENV.storefront];
+  if (sf && !all.some((r) => r.store === store && r.storefront_id === sf)) foreign.push(ENV.storefront);
+  if (foreign.length)
+    throw new NeedsPerson(
+      `${envFile} holds ${foreign.join(", ")} that this checkout didn't make for this store: remove ${foreign.length === 1 ? "that line" : "those lines"}, or save this store's keys in its own checkout, then run this again`,
+    );
+  const saved = env[envName];
+  if (saved && (await works(target, wanted, saved, d))) {
+    if (wanted.kind === "publishable") await allowOrigins(target, env[ENV.storefront], wanted.origins, d);
+    return pick(env, wanted);
+  }
+
+  const grants = wanted.kind === "secret" ? ["api_key:write", ...wanted.grants] : ["storefront:write"];
+  const made = await withCliSession(target, grants, d.session, async (auth) => {
+    const call = async (method: string, path: string, body: unknown) => {
+      const r = await storeRequest(d.fetch, new URL(path, target.url), {
+        method,
+        headers: { ...auth, "content-type": "application/json" },
+        body: JSON.stringify(body),
+      });
+      // A Worker from before P0.10 has no such route: nothing was made, and nothing is sent again.
+      if (r.status === 404) throw new DeployRefused(OLDER_KEDGE);
+      // Settling a ref needs every permission its key grants: one this session can't hold is an Owner's to void.
+      if (r.status === 403 && path.endsWith("/void"))
+        throw new NeedsPerson(
+          `credential ref ${path.split("/")[3]} made a key this command can't revoke: an Owner can revoke it in the admin's API keys, then run this again`,
+        );
+      if (!r.ok)
+        throw new DeployRefused(
+          `${method} ${path} answered ${r.status} ${String((r.body.error as { code?: string } | undefined)?.code ?? "")}`,
+        );
+      return r.body as unknown as RefAnswer;
+    };
+
+    // 2. Every ref of ours not yet saved, and a saved one whose key stopped working, is settled first.
+    let storefront =
+      wanted.kind === "publishable" ? (refs().find((r) => r.storefront_id)?.storefront_id ?? null) : null;
+    for (const r of refs()) {
+      if (r.state === "fenced" || r.state === "revoked") continue;
+      const a = await call("POST", `/admin/credential-refs/${r.ref}/void`, { kind: r.kind });
+      set(r.ref, { state: a.state, storefront_id: a.storefront_id, key_id: a.key_id });
+      // A storefront's ref voided after it landed still names the storefront: the next key goes on it.
+      if (a.storefront_id) storefront = a.storefront_id;
+    }
+
+    // 3. A new ref, recorded before it's sent.
+    const ref = newRef();
+    const kind: RefRecord["kind"] = wanted.kind === "secret" ? "secret" : storefront ? "publishable" : "storefront";
+    const t = now();
+    db.prepare(
+      "INSERT INTO credential_ref (ref, store, kind, state, storefront_id, key_id, env_name, created_at, updated_at) VALUES (?, ?, ?, 'recorded', ?, NULL, ?, ?, ?)",
+    ).run(ref, store, kind, storefront, envName, t, t);
+    const body =
+      wanted.kind === "secret"
+        ? { kind, name: wanted.name, grants: wanted.grants.map((permission) => ({ permission, row_scope: "all" })) }
+        : kind === "publishable"
+          ? { kind, name: wanted.name, storefront_id: storefront }
+          : { kind, name: wanted.name, allowed_origins: wanted.origins };
+    const made = await call("PUT", `/admin/credential-refs/${ref}`, body);
+    if (!made.key)
+      throw new DeployRefused("the store made the key but answered no key: run this again to void and replace it");
+    // The key's digest, never the key, before .env.local is written: what binds the file's key to this ref.
+    set(ref, {
+      state: made.state,
+      storefront_id: made.storefront_id,
+      key_id: made.key_id,
+      key_digest: keyDigest(made.key),
+    });
+
+    // 4. Saved before anything else happens, then marked saved.
+    const values: Record<string, string> = { [ENV.store]: store, [envName]: made.key };
+    if (made.storefront_id) values[ENV.storefront] = made.storefront_id;
+    saveEnv(d.cwd, values, envFile);
+    set(ref, { state: "saved" });
+    d.log(`saved ${Object.keys(values).join(", ")} to .env.local`);
+    return values;
+  });
+  // A key on a storefront that already existed was made without the origins asked for now.
+  if (wanted.kind === "publishable") await allowOrigins(target, made[ENV.storefront], wanted.origins, d);
+  return made;
+}
+
+/**
+ * The storefront allows every origin asked for, keeping those it lists
+ * (codex code r14): a key a browser on that origin can't use is no key, and
+ * replacing the key never changes its storefront's origins. The write carries
+ * the list it was built from, so it commits only while that's still the list:
+ * an origin an Owner removed meanwhile is never put back, and a concurrent
+ * addition never lost (codex code r16). A conflict is read again, three times at most.
+ */
+async function allowOrigins(
+  target: StoreTarget,
+  storefront: string | undefined,
+  origins: readonly string[],
+  d: SaveDeps,
+): Promise<void> {
+  if (!origins.length) return;
+  if (!storefront) throw new DeployRefused("no storefront was saved to allow those origins on");
+  await withCliSession(target, ["storefront:read", "storefront:write"], d.session, async (auth) => {
+    const read = async () => {
+      const list = await storeRequest(d.fetch, new URL("/admin/storefronts", target.url), {
+        method: "GET",
+        headers: auth,
+      });
+      if (!list.ok) throw new DeployRefused(`GET /admin/storefronts answered ${list.status}`);
+      const sf = (list.body.storefronts as { id: string; allowed_origins: string[] }[] | undefined)?.find(
+        (s) => s.id === storefront,
+      );
+      if (!sf) throw new DeployRefused(`storefront ${storefront} no longer exists`);
+      return sf.allowed_origins;
+    };
+    const first = await read();
+    // What this command adds is fixed by its first read: a retry never adds an origin that was already
+    // there then and has gone since, which is someone removing it on purpose (codex code r17).
+    const adding = origins.filter((o) => !first.includes(o));
+    if (!adding.length) return;
+    let current = first;
+    for (let attempt = 1; ; attempt++) {
+      const removed = origins.filter((o) => first.includes(o) && !current.includes(o));
+      if (removed.length)
+        throw new NeedsPerson(
+          `${removed.join(", ")} was removed from storefront ${storefront} while this ran: ask whoever removed it before adding it back`,
+        );
+      const next = [...current, ...adding.filter((o) => !current.includes(o))];
+      if (next.length === current.length) return;
+      const put = await storeRequest(d.fetch, new URL(`/admin/storefronts/${storefront}/origins`, target.url), {
+        method: "PUT",
+        headers: { ...auth, "content-type": "application/json" },
+        body: JSON.stringify({ allowed_origins: next, expected: current }),
+      });
+      if (put.ok) {
+        d.log(`storefront ${storefront} now allows ${adding.join(", ")}`);
+        return;
+      }
+      const code = (put.body.error as { code?: string } | undefined)?.code;
+      if (code !== "CONFLICT" || attempt >= 3)
+        throw new DeployRefused(`PUT /admin/storefronts/${storefront}/origins answered ${put.status} ${code ?? ""}`);
+      current = await read();
+    }
+  });
+}
+
+/** An origin as the store accepts one (db's `origins`): a scheme, host and optional port, nothing else. */
+export function badOrigins(origins: readonly string[]): string[] {
+  return origins.filter((o) => {
+    try {
+      const u = new URL(o);
+      return (u.protocol !== "https:" && u.protocol !== "http:") || u.origin !== o;
+    } catch {
+      return true;
+    }
+  });
+}
+
+/**
+ * A 0.10.0 checkout saved `kedge dev`'s keys in `.env.local`, where they'd block
+ * Cloudflare's (p0.10.1 §4). Under the lock, before anything else, the bundle
+ * proven local moves to `.env.development.local`: each key whose digest matches
+ * a ref recorded for a `local/…` store, the storefront a local ref recorded, and
+ * a `local/…` store marker. Nothing unproven moves. The destination is written
+ * first and read back, then only names it now holds are removed from
+ * `.env.local`; a run stopped between the two finishes the removal next time.
+ * A destination already holding one of those names with another value is a handoff.
+ */
+function moveLocalBundle(db: DatabaseSync, d: SaveDeps): void {
+  const prod = readEnvLocal(d.cwd, ENV_FILE.production);
+  const refs = (db.prepare("SELECT * FROM credential_ref").all() as unknown as RefRecord[]).filter((r) =>
+    r.store.startsWith("local/"),
+  );
+  const moving: Record<string, string> = {};
+  for (const name of [ENV.publishable, ENV.secret]) {
+    const value = prod[name];
+    if (value && refs.some((r) => r.env_name === name && r.key_digest === keyDigest(value))) moving[name] = value;
+  }
+  const sf = prod[ENV.storefront];
+  if (sf && refs.some((r) => r.storefront_id === sf)) moving[ENV.storefront] = sf;
+  if (prod[ENV.store]?.startsWith("local/")) moving[ENV.store] = prod[ENV.store] as string;
+  const names = Object.keys(moving);
+  if (!names.length) return;
+  const dev = readEnvLocal(d.cwd, ENV_FILE.local);
+  const clash = names.filter((n) => dev[n] !== undefined && dev[n] !== moving[n]);
+  if (clash.length)
+    throw new NeedsPerson(
+      `${ENV_FILE.production} holds kedge dev's ${clash.join(", ")}, and ${ENV_FILE.local} holds others: keep one, remove the other line, then run this again`,
+    );
+  saveEnv(d.cwd, moving, ENV_FILE.local);
+  const landed = readEnvLocal(d.cwd, ENV_FILE.local);
+  saveEnv(
+    d.cwd,
+    {},
+    ENV_FILE.production,
+    names.filter((n) => landed[n] === moving[n]),
+  );
+  d.log(`moved kedge dev's ${names.join(", ")} from ${ENV_FILE.production} to ${ENV_FILE.local}`);
+}
+
+/**
+ * Whether a saved key still does its job (§6.2): a publishable key passes the
+ * storefront gate; a secret key holds its grants. Only a definite answer
+ * decides: the key refused (401, 403), or its permissions read and short.
+ * Anything else (429, 5xx, a shape it doesn't know) stops with nothing
+ * changed, since replacing a working key revokes it for everyone using it
+ * (codex code r15).
+ */
+async function works(target: StoreTarget, wanted: Wanted, key: string, d: SaveDeps): Promise<boolean> {
+  const inconclusive = (what: string, status: number) =>
+    new DeployRefused(`couldn't check the saved key (${what} answered ${status}); nothing was changed: run this again`);
+  if (wanted.kind === "publishable") {
+    // The storefront gate judges the key before the route: a product that doesn't exist is 404 to a working key.
+    const r = await storeRequest(d.fetch, new URL("/store/products/kedge-key-check?currency=USD", target.url), {
+      method: "GET",
+      headers: { "x-kedge-key": key },
+    });
+    if (r.status === 401 || r.status === 403) return false;
+    if (r.status === 404 || r.status === 400 || r.ok) return true;
+    throw inconclusive("the storefront gate", r.status);
+  }
+  const r = await storeRequest(d.fetch, new URL("/admin/meta/me", target.url), {
+    method: "GET",
+    headers: { authorization: `Bearer ${key}` },
+  });
+  if (r.status === 401 || r.status === 403) return false;
+  if (!r.ok || !Array.isArray(r.body.permissions)) throw inconclusive("/admin/meta/me", r.status);
+  // `{ code, scopes }` per permission (server/src/meta-routes.ts:114); a saved key needs each for every row (codex code r10).
+  const held = new Map(
+    (r.body.permissions as { code?: string; scopes?: string[] }[]).map((p) => [p.code, p.scopes ?? []]),
+  );
+  return wanted.grants.every((g) => held.get(g)?.includes("all") === true);
+}
+
+const pick = (env: Record<string, string>, wanted: Wanted) =>
+  Object.fromEntries(
+    Object.entries(env).filter(([k]) =>
+      wanted.kind === "publishable"
+        ? [ENV.store, ENV.storefront, ENV.publishable].includes(k as never)
+        : [ENV.store, ENV.secret].includes(k as never),
+    ),
+  );

package/src/local-state.ts

@@ -0,0 +1,122 @@
+// A store checkout's local state (docs/proposals/p0.10-agent-path.md §6.2):
+// one lock the operating system releases, a record of every credential
+// reference before it's sent, and `.env.local` rewritten whole.
+//
+// The lock is an exclusive SQLite transaction on `.kedge/lock.db`, held from
+// before a command's first read of this state to after its last write.
+// SQLite takes it from the OS's file locks, which end with the process, so a
+// command killed with SIGKILL leaves nothing to take over (checked on Linux
+// while drafting §6.2). The lock's transaction writes nothing: what it would
+// write is lost with a crash, and a record must survive one, so records live
+// in `.kedge/state.db`, each committed on its own before the request it guards.
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { parseEnv } from "node:util";
+import { DeployRefused } from "./deploy";
+
+const dir = (cwd: string) => {
+  const d = join(cwd, ".kedge");
+  mkdirSync(d, { recursive: true });
+  return d;
+};
+
+/**
+ * Runs `work` holding the checkout's lock. A second command is refused at once
+ * (no wait), naming the one that holds it, so two never interleave their reads
+ * and rewrites of `.env.local` or a record.
+ */
+export async function withStoreLock<T>(cwd: string, command: string, work: () => Promise<T>): Promise<T> {
+  const d = dir(cwd);
+  const db = new DatabaseSync(join(d, "lock.db"), { timeout: 0 });
+  const holder = join(d, "lock.holder");
+  try {
+    try {
+      db.exec("BEGIN EXCLUSIVE");
+    } catch (e) {
+      if (!/database is locked/.test((e as Error).message)) throw e;
+      // Written by the holder after it took the lock: informative only, the lock is what decides.
+      const who = existsSync(holder) ? readFileSync(holder, "utf8").trim() : "another kedge command";
+      throw new DeployRefused(`${who} is using this store's local state; run this again when it has finished`);
+    }
+    writeFileSync(holder, `kedge ${command} (pid ${process.pid})\n`);
+    try {
+      return await work();
+    } finally {
+      db.exec("ROLLBACK");
+    }
+  } finally {
+    db.close();
+  }
+}
+
+/** A credential reference this checkout made (§6.2), bound to the store's identity and the key's kind. */
+export interface RefRecord {
+  ref: string;
+  store: string;
+  kind: "secret" | "publishable" | "storefront";
+  /** recorded: about to be sent; then the server's answer; saved: its key is in `.env.local`. */
+  state: "recorded" | "used" | "fenced" | "revoked" | "saved";
+  storefront_id: string | null;
+  key_id: string | null;
+  /** The `.env.local` name its key is saved under. */
+  env_name: string;
+  /** SHA-256 of the key it made, recorded before the key is written: binds the saved key to this ref. */
+  key_digest: string | null;
+}
+
+/** `.kedge/state.db`, mode 0600: records only a command holding the lock writes, each committed alone. */
+export function stateDb(cwd: string): DatabaseSync {
+  const file = join(dir(cwd), "state.db");
+  const db = new DatabaseSync(file);
+  chmodSync(file, 0o600);
+  db.exec(`CREATE TABLE IF NOT EXISTS credential_ref (
+    ref TEXT PRIMARY KEY, store TEXT NOT NULL, kind TEXT NOT NULL, state TEXT NOT NULL,
+    storefront_id TEXT, key_id TEXT, env_name TEXT NOT NULL, key_digest TEXT,
+    created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`);
+  return db;
+}
+
+/** Where a store's saved keys go (p0.10.1 §4): `kedge dev`'s apart from Cloudflare's, so neither blocks the other. */
+export const ENV_FILE = { production: ".env.local", local: ".env.development.local" } as const;
+
+/**
+ * Rewrites an env file, keeping every line it doesn't touch: `values` set
+ * (replaced in place, or added at the end) and `remove` dropped. A temporary
+ * file in the same directory, mode 0600, renamed over it, so a crash leaves
+ * the old file or the new one, never half of either.
+ */
+export function saveEnv(
+  cwd: string,
+  values: Record<string, string>,
+  name: string = ENV_FILE.production,
+  remove: readonly string[] = [],
+): void {
+  const file = join(cwd, name);
+  const lines = existsSync(file) ? readFileSync(file, "utf8").split("\n") : [];
+  const left = new Set(Object.keys(values));
+  const drop = new Set(remove);
+  const out = lines.flatMap((line) => {
+    const key = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)?.[1];
+    if (!key) return [line];
+    if (drop.has(key)) return [];
+    if (!(key in values)) return [line];
+    left.delete(key);
+    return [`${key}=${values[key]}`];
+  });
+  while (out.length && out.at(-1) === "") out.pop();
+  for (const key of left) out.push(`${key}=${values[key]}`);
+  const tmp = join(cwd, `${name}.${process.pid}.tmp`);
+  try {
+    writeFileSync(tmp, `${out.join("\n")}\n`, { mode: 0o600 });
+    renameSync(tmp, file);
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+}
+
+/** An env file's values (`.env.local` by default), as the credential resolver reads them. */
+export function readEnvLocal(cwd: string, name: string = ENV_FILE.production): Record<string, string> {
+  const file = join(cwd, name);
+  return existsSync(file) ? (parseEnv(readFileSync(file, "utf8")) as Record<string, string>) : {};
+}