@kedge/cli 0.9.0 → 0.10.0

package/src/cf.ts

@@ -10,8 +10,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseEnv } from "node:util";
+import { jsoncToJson } from "./worker-config";
 
 export type Row = Record<string, unknown>;
 
@@ -28,8 +30,8 @@ export interface WorkerSettings {
 
 /** A call whose answer never came: the caller records it as an unknown outcome (§3.1). */
 export class UnknownOutcome extends Error {
-  constructor(what: string) {
-    super(`${what}: no answer from Cloudflare; its outcome is unknown`);
+  constructor(what: string, from = "Cloudflare") {
+    super(`${what}: no answer from ${from}; its outcome is unknown`);
     this.name = "UnknownOutcome";
   }
 }
@@ -70,7 +72,10 @@ export class CloudflareError extends Error {
 export interface Cloudflare {
   readonly account: string;
   findD1(name: string): Promise<string | null>;
-  createD1(name: string): Promise<string>;
+  /** Creates a database in `jurisdiction` (none when null): set only at creation, never after (p0.10 §7). */
+  createD1(name: string, jurisdiction?: Jurisdiction | null): Promise<string>;
+  /** The database's jurisdiction, as Cloudflare records it; `none` when it has none. */
+  d1Jurisdiction(id: string): Promise<JurisdictionChoice>;
   deleteD1(id: string): Promise<void>;
   queryD1(id: string, sql: string, params?: readonly unknown[]): Promise<Row[]>;
   bookmark(id: string): Promise<string>;
@@ -100,14 +105,36 @@ export interface Cloudflare {
   applyMigrations(input: { config: string; database: string }): Promise<void>;
   /** One SQL file as one transaction (`wrangler d1 execute --file`): the CLI's audited batches (p0.5 §3.4). */
   executeD1File(input: { database: string; databaseId: string; sql: string }): Promise<void>;
-  /** The account's workers.dev subdomain. */
+  /** The account's workers.dev subdomain; none is the person's choice to make (`NeedsPerson`). */
   workersSubdomain(): Promise<string>;
+  /** One list of each resource type a store uses: null where it answered, else the refusing status (0: no answer). */
+  readable(): Promise<Record<ResourceKind, number | null>>;
   /** The account's Logpush jobs, or null when the token can't read them. */
   logpushJobs(): Promise<{ dataset: string; enabled: boolean; fields: string[] | null }[] | null>;
   /** `wrangler versions secret put|delete`: a new version with one secret changed, not deployed. */
   versionSecret(worker: string, name: string, value: string | null, message: string): Promise<string>;
 }
 
+export type ResourceKind = "Workers" | "D1" | "Queues";
+
+/**
+ * Where a store's data lives (p0.10 §7): D1 and Durable Object storage
+ * restricted to one jurisdiction, or `none`, which is a choice too. The values
+ * are Cloudflare's for both
+ * (https://developers.cloudflare.com/d1/configuration/data-location/,
+ * https://developers.cloudflare.com/durable-objects/reference/data-location/).
+ */
+export const JURISDICTIONS = ["eu", "us", "fedramp"] as const;
+export type Jurisdiction = (typeof JURISDICTIONS)[number];
+export type JurisdictionChoice = Jurisdiction | "none";
+
+export const isJurisdictionChoice = (v: string): v is JurisdictionChoice =>
+  v === "none" || (JURISDICTIONS as readonly string[]).includes(v);
+
+/** What the person is asked before a store's first resource exists. */
+export const CHOOSE_JURISDICTION =
+  "choose where this store's data lives: eu, us, fedramp or none (it can't change later), then run this again with --jurisdiction <choice>";
+
 export interface UploadInput {
   /** A generated Wrangler config, every path in it absolute. */
   config: string;
@@ -117,6 +144,196 @@ export interface UploadInput {
 
 const API = "https://api.cloudflare.com/client/v4";
 
+/**
+ * What only a person can do next (p0.10 §5): the command stops with exit 3 and
+ * this one sentence, which an agent passes on as written.
+ */
+export class NeedsPerson extends Error {
+  constructor(readonly handoff: string) {
+    super(handoff);
+  }
+}
+
+/**
+ * Where every Cloudflare call goes: `CLOUDFLARE_API_BASE_URL` when set, as
+ * Wrangler's own calls do, else Cloudflare (p0.10 §4). salve's broker sets it
+ * with a token valid only there, so sending that token to Cloudflare itself
+ * would leak it and fail.
+ */
+export function cloudflareBase(env: NodeJS.ProcessEnv): string {
+  const raw = env.CLOUDFLARE_API_BASE_URL?.trim();
+  if (!raw) return API;
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    throw new Error(`CLOUDFLARE_API_BASE_URL isn't a URL: ${raw}`);
+  }
+  const local = u.hostname === "localhost" || u.hostname === "127.0.0.1";
+  if (u.protocol !== "https:" && !(local && u.protocol === "http:"))
+    throw new Error(`CLOUDFLARE_API_BASE_URL must be https: ${raw}`);
+  return u.href.replace(/\/+$/, "");
+}
+
+/**
+ * An account without a workers.dev subdomain has nowhere to serve a store, and
+ * Kedge never registers one (p0.10 §4): it names every Worker on the account,
+ * so it's the account owner's choice, made where Wrangler sends people to make it
+ * (wrangler-dist/cli.js:165132, 4.152.0).
+ */
+export function noSubdomain(account: string): NeedsPerson {
+  return new NeedsPerson(
+    `this Cloudflare account has no workers.dev subdomain yet: choose one at https://dash.cloudflare.com/${account}/workers/subdomain, then run this again`,
+  );
+}
+
+/**
+ * What every command that can create a store resource checks before its first
+ * Cloudflare write (p0.10 §4), so a missing subdomain stops it with nothing
+ * made rather than after the database and Worker exist. Credentials have
+ * resolved by the time a `Cloudflare` exists. A store with no `<store>-ops`
+ * yet needs its jurisdiction chosen (§7); one that has it must not be given
+ * another. `ops` is that database's name; `preview apply` from a plan names
+ * its store only once the plan is read, and `openOps` checks the same there.
+ */
+export async function preflight(cf: Cloudflare, ops?: string, choice?: string): Promise<void> {
+  if (choice !== undefined && !isJurisdictionChoice(choice))
+    throw new NeedsPerson(
+      `--jurisdiction takes ${JURISDICTIONS.join(", ")} or none, not "${choice}": ${CHOOSE_JURISDICTION}`,
+    );
+  await cf.workersSubdomain();
+  if (ops === undefined) return;
+  const id = await cf.findD1(ops);
+  if (!id && choice === undefined) throw new NeedsPerson(CHOOSE_JURISDICTION);
+  if (id && choice !== undefined) {
+    const actual = await cf.d1Jurisdiction(id);
+    if (actual !== choice)
+      throw new NeedsPerson(
+        `this store's data lives in jurisdiction ${actual}, fixed when it was first deployed: run this again without --jurisdiction, or with --jurisdiction ${actual}`,
+      );
+  }
+}
+
+/** The resolved credentials: where they came from, the account, and a token fresh enough to send. */
+export interface CloudflareAuth {
+  source: "environment" | ".env.local" | "wrangler login";
+  account: string;
+  token: () => string;
+}
+
+/**
+ * The three sources, in order (p0.10 §4): the environment (salve, CI), the
+ * store's `.env.local`, then a `wrangler login` session read through Wrangler's
+ * own `wrangler auth token --json`, never from its files. A login's token is
+ * asked for again before every call: Wrangler refreshes an OAuth token only once
+ * it has expired, and says nothing of how long it has left, so a cached one
+ * could lapse in the middle of a cutover (codex code r1).
+ */
+export async function resolveCloudflare(
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+  fetchImpl: typeof fetch = fetch,
+  wranglerEntry: string = wranglerBin(),
+): Promise<CloudflareAuth> {
+  if (env.CLOUDFLARE_API_TOKEN) {
+    const token = env.CLOUDFLARE_API_TOKEN;
+    if (!env.CLOUDFLARE_ACCOUNT_ID) throw new NeedsPerson("set CLOUDFLARE_ACCOUNT_ID beside CLOUDFLARE_API_TOKEN");
+    sameAccount(env.CLOUDFLARE_ACCOUNT_ID, configIn(cwd));
+    return { source: "environment", account: env.CLOUDFLARE_ACCOUNT_ID, token: () => token };
+  }
+  const file = join(cwd, ".env.local");
+  const local = existsSync(file) ? parseEnv(readFileSync(file, "utf8")) : {};
+  if (local.CLOUDFLARE_API_TOKEN) {
+    const token = local.CLOUDFLARE_API_TOKEN;
+    const account = env.CLOUDFLARE_ACCOUNT_ID ?? local.CLOUDFLARE_ACCOUNT_ID;
+    if (!account) throw new NeedsPerson("add CLOUDFLARE_ACCOUNT_ID to .env.local beside CLOUDFLARE_API_TOKEN");
+    sameAccount(account, configIn(cwd));
+    return { source: ".env.local", account, token: () => token };
+  }
+  const token = () => {
+    const t = wranglerLoginToken(env, wranglerEntry);
+    if (!t)
+      throw new NeedsPerson(
+        "add CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID to .env.local, or run `wrangler login`, then run this again",
+      );
+    return t;
+  };
+  // Asked once here too, so a missing login is the handoff now, never a failed call later (codex code r1).
+  const first = token();
+  const account =
+    env.CLOUDFLARE_ACCOUNT_ID ?? local.CLOUDFLARE_ACCOUNT_ID ?? (await onlyAccount(env, first, fetchImpl));
+  sameAccount(account, configIn(cwd));
+  return { source: "wrangler login", account, token };
+}
+
+/** The store's Wrangler config file, if it has one. */
+function configIn(cwd: string): string | null {
+  for (const f of ["wrangler.jsonc", "wrangler.json"]) if (existsSync(join(cwd, f))) return join(cwd, f);
+  return null;
+}
+
+/**
+ * A Wrangler config's `account_id` wins over `CLOUDFLARE_ACCOUNT_ID` in every
+ * Wrangler run (`getActiveAccountId`, wrangler-dist/cli.js:133664, 4.152.0),
+ * so a config naming another account than the credentials resolved would send
+ * Wrangler's writes there while Kedge's own calls go here (codex code r8).
+ * Which account is the store's is the person's to say.
+ */
+export function sameAccount(account: string, configFile: string | null): void {
+  if (!configFile || !existsSync(configFile)) return;
+  const named = (JSON.parse(jsoncToJson(readFileSync(configFile, "utf8"))) as { account_id?: unknown }).account_id;
+  if (typeof named === "string" && named !== "" && named !== account)
+    throw new NeedsPerson(
+      `${basename(configFile)} names Cloudflare account ${named}, but the credentials are for ${account}: remove its account_id, or use credentials for ${named}, then run this again`,
+    );
+}
+
+const LEGACY_CREDENTIALS = new Set([
+  "CLOUDFLARE_API_TOKEN",
+  "CLOUDFLARE_API_KEY",
+  "CLOUDFLARE_EMAIL",
+  "CF_API_TOKEN",
+  "CF_API_KEY",
+  "CF_EMAIL",
+]);
+
+/** The login's token from Wrangler itself, in the person's own environment; null when there's none. */
+function wranglerLoginToken(env: NodeJS.ProcessEnv, wranglerEntry: string): string | null {
+  // A directory of our own, so Wrangler reads no store's `.env`; HOME stays the person's, where the login is.
+  const dir = mkdtempSync(join(tmpdir(), "kedge-auth-"));
+  try {
+    // Every credential Wrangler would take from the environment goes, its legacy aliases too, so
+    // what answers is the login and nothing else (codex code r5).
+    const rest = Object.fromEntries(Object.entries(env).filter(([k]) => !LEGACY_CREDENTIALS.has(k)));
+    const r = spawnSync(process.execPath, [wranglerEntry, "auth", "token", "--json"], {
+      cwd: dir,
+      encoding: "utf8",
+      env: { ...rest, WRANGLER_SEND_METRICS: "false" },
+    });
+    if (r.status !== 0) return null;
+    const j = JSON.parse(r.stdout) as { type?: unknown; token?: unknown };
+    return j.type === "oauth" && typeof j.token === "string" && j.token ? j.token : null;
+  } catch {
+    return null;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** The one account a token can reach; more than one is the person's choice. */
+async function onlyAccount(env: NodeJS.ProcessEnv, token: string, fetchImpl: typeof fetch): Promise<string> {
+  const res = await fetchImpl(`${cloudflareBase(env)}/memberships?per_page=50`, {
+    headers: { authorization: `Bearer ${token}` },
+  });
+  const data = (await res.json().catch(() => ({}))) as { result?: { account?: { id?: string; name?: string } }[] };
+  const accounts = (data.result ?? []).map((m) => m.account).filter((a): a is { id: string; name?: string } => !!a?.id);
+  if (accounts.length === 1) return (accounts[0] as { id: string }).id;
+  if (accounts.length === 0) throw new CloudflareError("the login's accounts", res.status, []);
+  throw new NeedsPerson(
+    `this login reaches ${accounts.length} Cloudflare accounts: set CLOUDFLARE_ACCOUNT_ID in .env.local to one of ${accounts.map((a) => `${a.id} (${a.name ?? "?"})`).join(", ")}`,
+  );
+}
+
 type Envelope<T> = {
   success?: boolean;
   result?: T;
@@ -130,24 +347,45 @@ export function wranglerBin(): string {
   return join(dirname(require.resolve("wrangler/package.json")), "bin", "wrangler.js");
 }
 
+/** A store's Cloudflare, from whichever source resolves (p0.10 §4). */
+export async function cloudflareFor(
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+  fetchImpl: typeof fetch = fetch,
+  wranglerEntry: string = wranglerBin(),
+): Promise<Cloudflare> {
+  return restCloudflare(env, fetchImpl, wranglerEntry, await resolveCloudflare(env, cwd, fetchImpl, wranglerEntry));
+}
+
 export function restCloudflare(
   env: NodeJS.ProcessEnv,
   fetchImpl: typeof fetch = fetch,
   /** The Wrangler entry to run; tests give a stand-in. */
   wranglerEntry: string = wranglerBin(),
+  /** Resolved credentials; without them, the environment's two variables. */
+  auth?: CloudflareAuth,
 ): Cloudflare {
-  const token = env.CLOUDFLARE_API_TOKEN;
-  const account = env.CLOUDFLARE_ACCOUNT_ID;
-  if (!token || !account) throw new Error("set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID");
-  const base = `${API}/accounts/${account}`;
+  const resolved =
+    auth ??
+    (() => {
+      const t = env.CLOUDFLARE_API_TOKEN;
+      const a = env.CLOUDFLARE_ACCOUNT_ID;
+      if (!t || !a) throw new Error("set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID");
+      return { source: "environment" as const, account: a, token: () => t };
+    })();
+  const account = resolved.account;
+  const apiBase = cloudflareBase(env);
+  const base = `${apiBase}/accounts/${account}`;
 
   async function call<T>(what: string, method: string, path: string, body?: unknown, ok404 = false): Promise<T | null> {
+    // Before the network's catch: a credential that's gone is a handoff, not an unknown outcome.
+    const bearer = resolved.token();
     let res: Response;
     try {
       res = await fetchImpl(`${base}${path}`, {
         method,
         headers: {
-          authorization: `Bearer ${token}`,
+          authorization: `Bearer ${bearer}`,
           ...(body === undefined ? {} : { "content-type": "application/json" }),
         },
         ...(body === undefined ? {} : { body: JSON.stringify(body) }),
@@ -196,7 +434,9 @@ export function restCloudflare(
   ): { out: string; outputs: Row[] } {
     // A fresh directory of our own: Wrangler loads `.env` from its working
     // directory and honours CLOUDFLARE_API_BASE_URL, so neither the store's
-    // files nor the caller's environment may reach it (§5.3).
+    // files nor the caller's environment may reach it (§5.3). The base URL
+    // Kedge resolved is passed on explicitly: salve's broker token is valid
+    // only there (p0.10 §4).
     const dir = mkdtempSync(join(tmpdir(), "kedge-wrangler-"));
     const envFile = join(dir, "empty.env");
     const output = join(dir, "output.ndjson");
@@ -209,8 +449,9 @@ export function restCloudflare(
         env: {
           PATH: env.PATH ?? "",
           HOME: dir,
-          CLOUDFLARE_API_TOKEN: token as string,
-          CLOUDFLARE_ACCOUNT_ID: account as string,
+          CLOUDFLARE_API_TOKEN: resolved.token(),
+          CLOUDFLARE_ACCOUNT_ID: account,
+          ...(apiBase === API ? {} : { CLOUDFLARE_API_BASE_URL: apiBase }),
           WRANGLER_SEND_METRICS: "false",
           WRANGLER_OUTPUT_FILE_PATH: output,
           CI: "1",
@@ -247,8 +488,12 @@ export function restCloudflare(
       );
       return r.find((d) => d.name === name)?.uuid ?? null;
     },
-    async createD1(name) {
-      const r = await call<{ uuid: string }>(`create D1 ${name}`, "POST", "/d1/database", { name });
+    async createD1(name, jurisdiction) {
+      // `jurisdiction` in the create body, the only time it can be set (D1 data location, cited above).
+      const r = await call<{ uuid: string }>(`create D1 ${name}`, "POST", "/d1/database", {
+        name,
+        ...(jurisdiction ? { jurisdiction } : {}),
+      });
       if (!r?.uuid) throw new UnknownOutcome(`create D1 ${name}`);
       return r.uuid;
     },
@@ -418,10 +663,43 @@ export function restCloudflare(
       }
     },
     async workersSubdomain() {
-      const r = await get<{ subdomain: string }>("workers.dev subdomain", "/workers/subdomain");
-      if (!r?.subdomain) throw new CloudflareError("no workers.dev subdomain", 200, []);
+      let r: { subdomain: string } | null;
+      try {
+        r = await get<{ subdomain: string }>("workers.dev subdomain", "/workers/subdomain");
+      } catch (e) {
+        // 10007 is Cloudflare's "no subdomain", as Wrangler reads it (wrangler-dist/cli.js:164937, 4.152.0).
+        if (e instanceof CloudflareError && e.codes.includes(10007)) throw noSubdomain(account);
+        throw e;
+      }
+      if (!r?.subdomain) throw noSubdomain(account);
       return r.subdomain;
     },
+    async d1Jurisdiction(id) {
+      // The database's own record (https://developers.cloudflare.com/api/resources/d1/subresources/database/methods/get/);
+      // absent is none.
+      const r = await get<{ jurisdiction?: string | null }>(`D1 ${id}`, `/d1/database/${id}`);
+      const j = r?.jurisdiction ?? "none";
+      if (!isJurisdictionChoice(j)) throw new CloudflareError(`D1 ${id} answered jurisdiction "${j}"`, 200, []);
+      return j;
+    },
+    async readable() {
+      const out: Record<ResourceKind, number | null> = { Workers: null, D1: null, Queues: null };
+      const paths: [ResourceKind, string][] = [
+        ["Workers", "/workers/scripts"],
+        ["D1", "/d1/database"],
+        ["Queues", "/queues"],
+      ];
+      for (const [kind, path] of paths) {
+        try {
+          await get(`list ${kind}`, path);
+        } catch (e) {
+          if (e instanceof CloudflareError) out[kind] = e.status;
+          else if (e instanceof UnknownOutcome) out[kind] = 0;
+          else throw e;
+        }
+      }
+      return out;
+    },
     async logpushJobs() {
       try {
         const r = await get<{ dataset: string; enabled: boolean; output_options?: { field_names?: string[] } }[]>(

package/src/check.ts

@@ -5,6 +5,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { childStdio } from "./output";
 
 export interface CheckInput {
   cwd: string;
@@ -21,7 +22,7 @@ const runBin = (bin: string, args: string[], cwd: string): number => {
     console.error(`${bin} isn't installed in this store: run pnpm install`);
     return 1;
   }
-  return spawnSync(path, args, { cwd, stdio: "inherit" }).status ?? 1;
+  return spawnSync(path, args, { cwd, stdio: childStdio() }).status ?? 1;
 };
 
 export async function check(input: CheckInput): Promise<number> {

package/src/cli-session.ts

@@ -0,0 +1,57 @@
+// A CLI session for one command (docs/proposals/p0.10-agent-path.md §6.2):
+// whoever holds the store's Cloudflare credentials writes the row, one audited
+// `system:cli` batch, to the target's own database and no other, and the
+// command sends the token to that target alone. The token lives in this
+// process's memory only: never printed, logged or saved. The row is deleted
+// when the command ends; one a crash leaves expires within ten minutes.
+import { type CliBatch, cliSessionEndSql, cliSessionSql } from "@kedge/db";
+import { type Cloudflare, UnknownOutcome } from "./cf";
+import { DeployRefused } from "./deploy";
+import type { StoreTarget } from "./target";
+
+/** What an older Worker's or database's refusal of a CLI session means for the person running it. */
+export const OLDER_KEDGE = "this store runs a Kedge older than this CLI, without CLI sessions: deploy first";
+
+export interface SessionDeps {
+  cloudflare: () => Promise<Cloudflare>;
+  /** `wrangler d1 execute --local` in the store's directory: `kedge dev`'s database. */
+  executeLocal: (b: CliBatch) => number;
+  now?: () => number;
+}
+
+async function write(target: StoreTarget, b: CliBatch, d: SessionDeps): Promise<void> {
+  if (target.kind === "local") {
+    if (d.executeLocal(b) !== 0) throw new DeployRefused("writing the CLI session to kedge dev's database failed");
+    return;
+  }
+  const cf = await d.cloudflare();
+  try {
+    await cf.executeD1File({ database: target.database.name, databaseId: target.database.id as string, sql: b.sql });
+  } catch (e) {
+    // A database from before P0.10 has no table to hold it.
+    if (e instanceof UnknownOutcome && /no such table: cli_session/.test(e.message))
+      throw new DeployRefused(OLDER_KEDGE);
+    throw e;
+  }
+}
+
+/** Runs `work` with a session holding `grants` on `target`, ending it after, whatever happened. */
+export async function withCliSession<T>(
+  target: StoreTarget,
+  grants: readonly string[],
+  d: SessionDeps,
+  work: (auth: Record<string, string>) => Promise<T>,
+): Promise<T> {
+  const now = d.now ?? Date.now;
+  const s = await cliSessionSql(grants, now());
+  await write(target, s, d);
+  try {
+    return await work({ authorization: `Bearer ${s.token}` });
+  } finally {
+    // Ending is housekeeping: a row left behind is useless without the token, and expires anyway.
+    await write(target, cliSessionEndSql(s.id, now()), d).catch(() => undefined);
+  }
+}
+
+/** Whether a request's credential was a CLI session, so a 401 can be read as an older Worker. */
+export const isCliSession = (auth: Record<string, string>) => auth.authorization?.startsWith("Bearer kcs_") === true;