@kedge/cli 0.0.0-stage → 0.10.0

package/src/fork.ts

@@ -0,0 +1,67 @@
+// `kedge doctor --core-diff` (docs/proposals/p0.8-cli-agent-kit.md §8.3): how far
+// a fork's packages have drifted from a release, per package and file, the
+// way Magento's core:code:changes turns "how far have we drifted" into a number
+// before an upgrade (research/14 §1). It reports; only --strict fails on it.
+// Each package.json is left out: a fork's names its siblings by workspace:*,
+// a release's by version, and that difference isn't drift. Each package's
+// LICENSE is the root one, copied in only while packing, so it's compared
+// with the fork's root LICENSE.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileHash, type Manifest } from "./manifest";
+
+export interface PackageDiff {
+  package: string;
+  changed: string[];
+  added: string[];
+  removed: string[];
+}
+
+export function coreDiff(repo: string, manifest: Manifest): PackageDiff[] {
+  const out: PackageDiff[] = [];
+  for (const [name, files] of Object.entries(manifest.packages)) {
+    const dir = join(repo, "packages", name.replace(/^@kedge\//, ""));
+    const d: PackageDiff = { package: name, changed: [], added: [], removed: [] };
+    const tops = new Set(
+      Object.keys(files)
+        .map((f) => f.split("/")[0] as string)
+        .filter((t) => !t.endsWith(".json")),
+    );
+    for (const [f, want] of Object.entries(files)) {
+      if (f === "package.json") continue;
+      const p = f === "LICENSE" ? join(repo, "LICENSE") : join(dir, f);
+      if (!existsSync(p)) d.removed.push(f);
+      else if (fileHash(f, readFileSync(p)) !== want) d.changed.push(f);
+    }
+    const walk = (d0: string) => {
+      if (!existsSync(d0)) return;
+      for (const e of readdirSync(d0, { withFileTypes: true })) {
+        const p = join(d0, e.name);
+        if (e.isDirectory()) walk(p);
+        else {
+          const rel = relative(dir, p);
+          if (files[rel] === undefined && !(rel.startsWith("migrations/") && !rel.endsWith(".sql"))) d.added.push(rel);
+        }
+      }
+    };
+    for (const t of tops) walk(join(dir, t));
+    if (d.changed.length || d.added.length || d.removed.length) out.push(d);
+  }
+  return out;
+}
+
+export function formatCoreDiff(diffs: readonly PackageDiff[], version: string): string {
+  if (!diffs.length) return `the packages match Kedge ${version}`;
+  const lines = [`drift from Kedge ${version}:`];
+  for (const d of diffs) {
+    lines.push(`  ${d.package}: ${d.changed.length} changed, ${d.added.length} added, ${d.removed.length} removed`);
+    for (const f of d.changed) lines.push(`    ~ ${f}`);
+    for (const f of d.added) lines.push(`    + ${f}`);
+    for (const f of d.removed) lines.push(`    - ${f}`);
+  }
+  const files = diffs.reduce((n, d) => n + d.changed.length + d.added.length + d.removed.length, 0);
+  lines.push(
+    `  ${files} file${files === 1 ? "" : "s"} across ${diffs.length} package${diffs.length === 1 ? "" : "s"}: each is a merge at the next upgrade`,
+  );
+  return lines.join("\n");
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export {
+  CORE_TABLES,
+  errorSources,
+  type LintIssue,
+  lintSql,
+  type Owner,
+  PERMANENT_IDENTITIES,
+  statementTexts,
+  tokenize,
+} from "@kedge/core";
+export { ComposeError, type ComposeInput, type ComposeResult, compose, type Lock, type LockEntry } from "./compose";
+export { lintPlugin } from "./plugin-lint";

package/src/invariants.ts

@@ -0,0 +1,168 @@
+// INVARIANTS.md and invariants.json (docs/proposals/p0.8-cli-agent-kit.md §4.2):
+// core's catalog checked against the composed schema, then each plugin's own
+// constraints and RAISE codes with the codes they map to. `kedge generate`
+// writes both; doctor's `invariants` check reports the catalog's problems.
+import type { ErrorMapEntry } from "@kedge/core";
+import {
+  CATALOG_EXEMPT,
+  type CatalogEntry,
+  CORE_RAISE_CODES,
+  catalogPattern,
+  ENTITY_RAISE_CODES,
+  INVARIANT_CATALOG,
+} from "@kedge/db";
+import { byCodePoint } from "./order";
+import { raiseCodes, type Schema, type SchemaObject } from "./schema";
+
+/** The merchant's own, from `local/`: theirs to name and keep, never core's catalog's (codex code r19). */
+export const isLocal = (o: SchemaObject) => o.name.startsWith("local_") || o.table.startsWith("local_");
+
+/** Objects the catalog speaks for: core's triggers and named constraints. Plugins' are listed per plugin. */
+const claimable = (o: SchemaObject) =>
+  (o.type === "trigger" || o.type === "constraint") && !o.name.startsWith("plg_") && !isLocal(o);
+
+/** Every code core's own SQL raises, and what each becomes. */
+export const CORE_CODES: Readonly<Record<string, string>> = { ...CORE_RAISE_CODES, ...ENTITY_RAISE_CODES };
+
+export interface CatalogProblem {
+  message: string;
+}
+
+export function catalogProblems(
+  schema: Schema,
+  checks: ReadonlySet<string>,
+  catalog: readonly CatalogEntry[] = INVARIANT_CATALOG,
+  exempt: readonly { objects: readonly string[]; reason: string }[] = CATALOG_EXEMPT,
+): CatalogProblem[] {
+  const problems: CatalogProblem[] = [];
+  const objects = schema.objects.filter(claimable);
+  const claimed = new Set<string>();
+  const claim = (where: string, pattern: string) => {
+    const re = catalogPattern(pattern);
+    const hits = objects.filter((o) => re.test(o.name));
+    if (hits.length === 0 && !generated.has(pattern))
+      problems.push({ message: `${where} names "${pattern}", which matches no core trigger or constraint` });
+    for (const h of hits) claimed.add(h.name);
+  };
+  const ids = new Set<string>();
+  const generated = new Set(catalog.filter((e) => e.generated).flatMap((e) => e.objects));
+  for (const e of catalog) {
+    if (ids.has(e.id)) problems.push({ message: `${e.id} is listed twice` });
+    ids.add(e.id);
+    for (const p of e.objects) claim(e.id, p);
+    if (e.check && !checks.has(e.check))
+      problems.push({ message: `${e.id}'s check "${e.check}" isn't in @kedge/testing's INVARIANTS` });
+  }
+  for (const x of exempt) for (const p of x.objects) claim("an exemption", p);
+  const unclaimed = [...new Set(objects.filter((o) => !claimed.has(o.name)).map((o) => o.name))];
+  if (unclaimed.length)
+    problems.push({
+      message: `core objects no catalog entry claims: ${unclaimed.join(", ")} (add them to packages/db/src/invariant-catalog.ts)`,
+    });
+  return problems;
+}
+
+export interface RenderedEntry {
+  id: string;
+  title: string;
+  rule: string;
+  check: string | null;
+  objects: string[];
+  raises: { code: string; error: string }[];
+}
+
+export interface PluginInvariants {
+  plugin: string;
+  constraints: { name: string; table: string; error: string | null }[];
+  raises: { code: string; object: string; error: string | null }[];
+}
+
+export interface Invariants {
+  version: 1;
+  core: RenderedEntry[];
+  plugins: PluginInvariants[];
+}
+
+const coreError = (code: string) => {
+  const e = CORE_CODES[code];
+  return e === undefined ? "UNMAPPED" : e === "defect" ? "INTERNAL (a core defect)" : e;
+};
+
+/**
+ * The plugin a `kedge_<plugin>_*` object belongs to: core generates them around a plugin's own SQL (its
+ * acquire statements, its entities' triggers), so their codes are the plugin's or core's. Longest name
+ * first, so `kedge_gift_card_*` is gift_card's beside a plugin named gift. Doctor and the catalog share
+ * it: a code doctor accepts as mapped is the one INVARIANTS.md shows (codex code r31).
+ */
+export function generatedFor<P extends { name: string }>(name: string, plugins: readonly P[]): P | undefined {
+  return [...plugins].sort((a, b) => b.name.length - a.name.length).find((p) => name.startsWith(`kedge_${p.name}_`));
+}
+
+/** The catalog and every plugin's constraints, as invariants.json holds them. */
+export function invariantsOf(
+  schema: Schema,
+  plugins: readonly { name: string; errors: Readonly<Record<string, ErrorMapEntry>> }[],
+): Invariants {
+  const objects = schema.objects.filter(claimable);
+  const core = INVARIANT_CATALOG.map((e) => {
+    const res = e.objects.map(catalogPattern);
+    const hits = objects.filter((o) => res.some((r) => r.test(o.name)));
+    const raises = new Map<string, { code: string; error: string }>();
+    for (const o of hits) {
+      const owner = generatedFor(o.name, plugins);
+      for (const code of raiseCodes(o.sql)) {
+        const error = owner?.errors[code]?.code ?? coreError(code);
+        raises.set(`${code} ${error}`, { code, error });
+      }
+    }
+    return {
+      id: e.id,
+      title: e.title,
+      rule: e.rule,
+      check: e.check ?? null,
+      objects: [...new Set(hits.map((o) => o.name))],
+      raises: [...raises.values()].sort((a, b) => byCodePoint(a.code, b.code) || byCodePoint(a.error, b.error)),
+    };
+  });
+  const out: PluginInvariants[] = [];
+  for (const p of plugins) {
+    const prefix = `plg_${p.name}_`;
+    const mapped = (key: string) => p.errors[key]?.code ?? null;
+    const constraints = schema.objects
+      .filter((o) => o.type === "constraint" && o.table.startsWith(prefix))
+      .map((o) => ({ name: o.name, table: o.table, error: mapped(o.name) }));
+    const raises = schema.objects
+      .filter((o) => (o.type === "trigger" || o.type === "view") && o.name.startsWith(prefix))
+      .flatMap((o) => raiseCodes(o.sql).map((code) => ({ code, object: o.name, error: mapped(code) })));
+    if (constraints.length || raises.length) out.push({ plugin: p.name, constraints, raises });
+  }
+  return { version: 1, core, plugins: out };
+}
+
+export function invariantsMarkdown(inv: Invariants): string {
+  const lines = [
+    "# Invariants",
+    "",
+    "Generated by `kedge generate` from the composed migrations; never edit it. Each",
+    "rule is enforced by D1 itself, in the batch, so code that breaks it is refused",
+    "with the error shown. Follow the rule and you never meet the error.",
+    "",
+  ];
+  for (const e of inv.core) {
+    lines.push(`## ${e.id}: ${e.title}`, "", e.rule, "");
+    if (e.raises.length) lines.push(`- **Errors:** ${e.raises.map((r) => `\`${r.code}\` → ${r.error}`).join("; ")}`);
+    if (e.check) lines.push(`- **Checked after every test** by \`describeKedgeInvariants\` (\`${e.check}\`)`);
+    lines.push(`- **Enforced by:** ${e.objects.length} objects (\`invariants.json\` lists them)`, "");
+  }
+  if (inv.plugins.length) {
+    lines.push("## Plugins", "");
+    for (const p of inv.plugins) {
+      lines.push(`### ${p.plugin}`, "");
+      for (const c of p.constraints)
+        lines.push(`- constraint \`${c.name}\` on \`${c.table}\` → ${c.error ?? "UNMAPPED"}`);
+      for (const r of p.raises) lines.push(`- \`RAISE '${r.code}'\` in \`${r.object}\` → ${r.error ?? "UNMAPPED"}`);
+      lines.push("");
+    }
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/src/keys-save.ts

@@ -0,0 +1,298 @@
+// `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 { 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.
+  const env = readEnvLocal(d.cwd);
+  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(
+      `.env.local 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);
+    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;
+    }
+  });
+}
+
+/**
+ * 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,110 @@
+// 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;
+}
+
+/**
+ * Writes `values` into `.env.local`, keeping every other line: 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>): void {
+  const file = join(cwd, ".env.local");
+  const lines = existsSync(file) ? readFileSync(file, "utf8").split("\n") : [];
+  const left = new Set(Object.keys(values));
+  const out = lines.map((line) => {
+    const name = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)?.[1];
+    if (!name || !(name in values)) return line;
+    left.delete(name);
+    return `${name}=${values[name]}`;
+  });
+  while (out.length && out.at(-1) === "") out.pop();
+  for (const name of left) out.push(`${name}=${values[name]}`);
+  const tmp = join(cwd, `.env.local.${process.pid}.tmp`);
+  try {
+    writeFileSync(tmp, `${out.join("\n")}\n`, { mode: 0o600 });
+    renameSync(tmp, file);
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+}
+
+/** `.env.local`'s values, as the credential resolver reads them. */
+export function readEnvLocal(cwd: string): Record<string, string> {
+  const file = join(cwd, ".env.local");
+  return existsSync(file) ? (parseEnv(readFileSync(file, "utf8")) as Record<string, string>) : {};
+}