alchemy 2.0.0-beta.47 → 2.0.0-beta.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "2.0.0-beta.47",
+  "version": "2.0.0-beta.49",
   "homepage": "https://alchemy.run",
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
@@ -291,15 +291,15 @@
     "@alchemy.run/node-utils": "0.0.4",
     "@aws-sdk/credential-providers": "^3.0.0",
     "@clack/prompts": "^0.11.0",
-    "@distilled.cloud/aws": "^0.22.2",
-    "@distilled.cloud/axiom": "^0.22.2",
-    "@distilled.cloud/cloudflare": "^0.22.2",
+    "@distilled.cloud/aws": "^0.22.4",
+    "@distilled.cloud/axiom": "^0.22.4",
+    "@distilled.cloud/cloudflare": "^0.22.4",
     "@distilled.cloud/cloudflare-rolldown-plugin": "0.10.1",
     "@distilled.cloud/cloudflare-runtime": "0.10.1",
     "@distilled.cloud/cloudflare-vite-plugin": "0.10.1",
-    "@distilled.cloud/core": "^0.22.2",
-    "@distilled.cloud/neon": "^0.22.2",
-    "@distilled.cloud/planetscale": "^0.22.2",
+    "@distilled.cloud/core": "^0.22.4",
+    "@distilled.cloud/neon": "^0.22.4",
+    "@distilled.cloud/planetscale": "^0.22.4",
     "@effect/vitest": ">=4.0.0-beta.74 || >=4.0.0",
     "@libsql/client": "^0.17.0",
     "@octokit/rest": "^22.0.1",

package/src/AdoptPolicy.ts

@@ -139,7 +139,7 @@ export const adopt: {
   ): <A, E, R2 = never>(
     effect: Effect.Effect<A, E, R2>,
   ) => Effect.Effect<A, E, R1 | R2>;
-} = ((enabled: boolean | Effect.Effect<boolean, never, any>) =>
+} = ((enabled: boolean | Effect.Effect<boolean, never, any> = true) =>
   (eff: Effect.Effect<any, any, any>) =>
     eff.pipe(
       typeof enabled === "boolean"

package/src/Binding.ts

@@ -3,6 +3,7 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import { SingleShotGen } from "effect/Utils";
+import type { Input } from "./Input.ts";
 import * as Namespace from "./Namespace.ts";
 import { ALCHEMY_PHASE } from "./Phase.ts";
 import { tryFindProviderByType } from "./Provider.ts";
@@ -42,7 +43,10 @@ type BindParameters<
   Parameters extends any[],
   Req = never,
 > = Parameters extends [infer First, ...infer Rest]
-  ? [First | Effect.Effect<First, never, Req>, ...BindParameters<Rest, Req>]
+  ? [
+      Input<First> | Effect.Effect<First, never, Req>,
+      ...BindParameters<Rest, Req>,
+    ]
   : [];
 
 /**

package/src/Cli/commands/cloudflare.ts

@@ -1,3 +1,7 @@
+import * as cfAccounts from "@distilled.cloud/cloudflare/accounts";
+import { apiKeyCredentials } from "@distilled.cloud/cloudflare/Credentials";
+import * as user from "@distilled.cloud/cloudflare/user";
+import * as Config from "effect/Config";
 import * as ConfigProvider from "effect/ConfigProvider";
 import * as Console from "effect/Console";
 import * as Effect from "effect/Effect";
@@ -6,6 +10,7 @@ import * as Logger from "effect/Logger";
 import * as Option from "effect/Option";
 import * as Stream from "effect/Stream";
 import { Command, Flag } from "effect/unstable/cli";
+import * as HttpClient from "effect/unstable/http/HttpClient";
 
 import { AuthProviders } from "../../Auth/AuthProvider.ts";
 import { withProfileOverride } from "../../Auth/Profile.ts";
@@ -16,6 +21,7 @@ import * as CloudflareCredentials from "../../Cloudflare/Credentials.ts";
 import { CloudflareLogs } from "../../Cloudflare/Logs.ts";
 import { STATE_STORE_SCRIPT_NAME } from "../../Cloudflare/StateStore/Api.ts";
 import { bootstrap as bootstrapCloudflare } from "../../Cloudflare/StateStore/State.ts";
+import * as Clank from "../../Util/Clank.ts";
 import { loadConfigProvider } from "../../Util/ConfigProvider.ts";
 import { fileLogger } from "../../Util/FileLogger.ts";
 
@@ -110,6 +116,393 @@ const bootstrapCommand = Command.make(
   ),
 );
 
+/**
+ * A single resolved Cloudflare token policy in the shape expected by
+ * `POST /user/tokens`.
+ */
+type CreateTokenPolicy = {
+  effect: "allow";
+  permissionGroups: { id: string }[];
+  resources: Record<string, unknown>;
+};
+
+/**
+ * Curated set of permission groups granted by `create-token` when
+ * `--all-permissions` is NOT passed. Covers the services Alchemy commonly
+ * deploys (Workers + storage + zone/DNS) without handing out a god token.
+ * Names are matched against the account's live permission groups; any name
+ * not available for the account is silently skipped.
+ */
+const ALCHEMY_DEFAULT_PERMISSION_GROUP_NAMES: ReadonlySet<string> = new Set([
+  "Account Settings Read",
+  "Workers Scripts Read",
+  "Workers Scripts Write",
+  "Workers KV Storage Read",
+  "Workers KV Storage Write",
+  "Workers R2 Storage Read",
+  "Workers R2 Storage Write",
+  "Workers Routes Read",
+  "Workers Routes Write",
+  "Workers Tail Read",
+  "Workers Observability Read",
+  "Workers Observability Write",
+  "Workers AI Read",
+  "Workers AI Write",
+  "D1 Read",
+  "D1 Write",
+  "Queues Read",
+  "Queues Write",
+  "Hyperdrive Read",
+  "Hyperdrive Write",
+  "Pages Read",
+  "Pages Write",
+  "Vectorize Read",
+  "Vectorize Write",
+  "Pipelines Read",
+  "Pipelines Write",
+  "AI Gateway Read",
+  "AI Gateway Run",
+  "AI Gateway Write",
+  "Browser Rendering Read",
+  "Browser Rendering Write",
+  "Images Read",
+  "Images Write",
+  "Stream Read",
+  "Stream Write",
+  "Secrets Store Read",
+  "Secrets Store Write",
+  "DNS Read",
+  "DNS Write",
+  "Zone Read",
+  "Zone Settings Read",
+  "Zone Settings Write",
+  "SSL and Certificates Read",
+  "SSL and Certificates Write",
+]);
+
+/**
+ * Group permission groups by their Cloudflare scope and produce one policy
+ * per scope, wiring up the right resource selector for each:
+ *
+ * - `com.cloudflare.api.account` → scoped to the account ID
+ * - `com.cloudflare.api.account.zone` → all zones (`*`)
+ * - `com.cloudflare.edge.r2.bucket` → all buckets (`*`)
+ *
+ * Mirrors the upstream `alchemy` "god token" policy shape. Groups with an
+ * unrecognized scope are skipped, and empty policies are dropped.
+ */
+const buildTokenPolicies = (
+  accountId: string,
+  groups: readonly { id: string; scopes: readonly string[] }[],
+): CreateTokenPolicy[] => {
+  const buckets: Record<string, CreateTokenPolicy> = {
+    "com.cloudflare.api.account": {
+      effect: "allow",
+      permissionGroups: [],
+      resources: { [`com.cloudflare.api.account.${accountId}`]: "*" },
+    },
+    "com.cloudflare.api.account.zone": {
+      effect: "allow",
+      permissionGroups: [],
+      resources: { "com.cloudflare.api.account.zone.*": "*" },
+    },
+    "com.cloudflare.edge.r2.bucket": {
+      effect: "allow",
+      permissionGroups: [],
+      resources: { "com.cloudflare.edge.r2.bucket.*": "*" },
+    },
+  };
+  const seen = new Set<string>();
+  for (const group of groups) {
+    const bucket = buckets[group.scopes[0]!];
+    if (!bucket || seen.has(group.id)) continue;
+    seen.add(group.id);
+    bucket.permissionGroups.push({ id: group.id });
+  }
+  return Object.values(buckets).filter((p) => p.permissionGroups.length > 0);
+};
+
+/**
+ * Let the user pick which Cloudflare account the token is scoped to. Lists
+ * the accounts visible to the configured credentials and prompts a selection
+ * (defaulting the cursor to the profile's account). If there's exactly one
+ * account, it's used without prompting; if the API returns none, falls back
+ * to the profile's account.
+ */
+const selectAccountId = (defaultAccountId: string | undefined) =>
+  Effect.gen(function* () {
+    const list = yield* cfAccounts.listAccounts;
+    const response = yield* list({});
+    const accounts = response.result;
+
+    if (accounts.length === 0) {
+      if (defaultAccountId) return defaultAccountId;
+      return yield* Effect.die(
+        "No Cloudflare accounts found for these credentials.",
+      );
+    }
+    if (accounts.length === 1) {
+      const account = accounts[0]!;
+      yield* Clank.info(`Using account: ${account.name} (${account.id})`);
+      return account.id;
+    }
+    return yield* Clank.select({
+      message: "Select a Cloudflare account",
+      initialValue: defaultAccountId,
+      options: accounts.map((a) => ({
+        value: a.id,
+        label: a.name,
+        hint: a.id === defaultAccountId ? `${a.id} (current profile)` : a.id,
+      })),
+    });
+  });
+
+const allPermissionsFlag = Flag.boolean("all-permissions").pipe(
+  Flag.withDescription(
+    "Grant the token EVERY Cloudflare permission group (a 'god token'). " +
+      "Use with care — it has full access to your account.",
+  ),
+  Flag.withDefault(false),
+);
+
+const tokenNameFlag = Flag.string("name").pipe(
+  Flag.withDescription(
+    "Name for the API token. Defaults to 'alchemy' (or 'alchemy-all-permissions').",
+  ),
+  Flag.optional,
+  Flag.map(Option.getOrUndefined),
+);
+
+const tokenAccountIdFlag = Flag.string("account-id").pipe(
+  Flag.withDescription(
+    "Cloudflare account ID to scope the token to. Defaults to the profile's account.",
+  ),
+  Flag.optional,
+  Flag.map(Option.getOrUndefined),
+);
+
+/**
+ * `alchemy cloudflare create-token` — mint a Cloudflare API token
+ * (`POST /user/tokens`).
+ *
+ * This command is **standalone**: it does not use an Alchemy auth profile.
+ * Cloudflare only mints a token whose permissions the authenticating
+ * credential is allowed to grant — and OAuth/scoped tokens silently produce a
+ * token with zero permissions — so it always authenticates with the account's
+ * **Global API Key** (read from `CLOUDFLARE_API_KEY` / `CLOUDFLARE_EMAIL`,
+ * otherwise prompted). The key is used only to create the token and is never
+ * stored.
+ *
+ * With `--all-permissions` it builds a "superuser" token spanning every
+ * permission group (after a confirmation prompt). Otherwise it grants a
+ * curated set covering the services Alchemy commonly deploys.
+ */
+const createTokenCommand = Command.make(
+  "create-token",
+  {
+    envFile,
+    allPermissions: allPermissionsFlag,
+    name: tokenNameFlag,
+    accountId: tokenAccountIdFlag,
+  },
+  instrumentCommand(
+    "cloudflare.create-token",
+    (a: { allPermissions: boolean }) => ({
+      "alchemy.all_permissions": a.allPermissions,
+    }),
+  )(
+    Effect.fnUntraced(function* ({ envFile, allPermissions, name, accountId }) {
+      const configProvider = ConfigProvider.layer(
+        yield* loadConfigProvider(envFile),
+      );
+
+      yield* Effect.gen(function* () {
+        // The Global API Key is a dashboard-only secret — there is no API to
+        // fetch it — so read it from the environment or prompt for it. It is
+        // used only to create the token and is never stored.
+        const envApiKey = yield* Config.string("CLOUDFLARE_API_KEY").pipe(
+          Config.option,
+          Config.map(Option.getOrUndefined),
+        );
+        const apiKey =
+          envApiKey ??
+          (yield* Clank.password({
+            message:
+              "Paste your Global API Key (see bottom of https://dash.cloudflare.com/profile/api-tokens)",
+            validate: (v) => (v.trim().length === 0 ? "Required" : undefined),
+          }));
+
+        const envEmail = yield* Config.string("CLOUDFLARE_EMAIL").pipe(
+          Config.option,
+          Config.map(Option.getOrUndefined),
+        );
+        const email =
+          envEmail ??
+          (yield* Clank.text({
+            message: "Cloudflare account email",
+            validate: (v) => (v.trim().length === 0 ? "Required" : undefined),
+          }));
+
+        const credentials = Effect.succeed(
+          apiKeyCredentials({ apiKey, email }),
+        );
+        const withCreds = <A, E, R>(self: Effect.Effect<A, E, R>) =>
+          self.pipe(
+            Effect.provideService(
+              CloudflareCredentials.Credentials,
+              credentials,
+            ),
+          );
+
+        const resolvedAccountId =
+          accountId ?? (yield* withCreds(selectAccountId(undefined)));
+
+        const tokenName =
+          name ??
+          (yield* Clank.text({
+            message: "Token name",
+            placeholder: allPermissions ? "alchemy-superuser" : "alchemy",
+            validate: (v) =>
+              v.trim().length === 0 ? "Token name is required" : undefined,
+          }));
+
+        // Resolve permission groups live from Cloudflare instead of a static
+        // catalog. Cloudflare silently ignores permission-group IDs it doesn't
+        // recognize, so a stale local list yields a token with zero
+        // permissions. `/user/tokens/permission_groups` returns exactly the
+        // groups (and IDs) valid for this credential.
+        //
+        // We hit the endpoint with a raw GET rather than the typed distilled
+        // client: the client hard-codes the set of valid `scopes` literals,
+        // and Cloudflare keeps adding new ones (e.g. `com.cloudflare.edge.
+        // worker.script`), which makes the strict schema reject the whole
+        // response. Parsing leniently keeps us forward-compatible.
+        const http = yield* HttpClient.HttpClient;
+        const pgResponse = yield* http.get(
+          "https://api.cloudflare.com/client/v4/user/tokens/permission_groups",
+          {
+            headers: {
+              "X-Auth-Key": apiKey,
+              "X-Auth-Email": email,
+              Accept: "application/json",
+            },
+          },
+        );
+        const pgBody = (yield* pgResponse.json) as {
+          result?: { id?: string; name?: string; scopes?: string[] }[];
+        };
+        const liveGroups = (pgBody.result ?? []).flatMap((g) =>
+          g.id && g.scopes && g.scopes.length > 0
+            ? [{ id: g.id, name: g.name ?? "", scopes: g.scopes }]
+            : [],
+        );
+
+        const selected = allPermissions
+          ? liveGroups
+          : liveGroups.filter((g) =>
+              ALCHEMY_DEFAULT_PERMISSION_GROUP_NAMES.has(g.name),
+            );
+        const policies = buildTokenPolicies(resolvedAccountId, selected);
+
+        if (policies.length === 0) {
+          return yield* Effect.die(
+            "No permission groups resolved for this account; cannot create a token.",
+          );
+        }
+
+        if (allPermissions) {
+          yield* Clank.warn(
+            "This token will have FULL access to your Cloudflare account. " +
+              "Keep it secret — anyone with it can control your account.",
+          );
+          const ok = yield* Clank.confirm({
+            message: "Create a superuser token with all permissions?",
+            initialValue: false,
+          });
+          if (!ok) {
+            yield* Console.log("Cancelled.");
+            return;
+          }
+        }
+
+        const result = yield* withCreds(
+          user.createToken({ name: tokenName, policies }),
+        );
+
+        if (!result.value) {
+          return yield* Effect.die(
+            "Cloudflare did not return a token value. Try again.",
+          );
+        }
+
+        // Cloudflare echoes back the policies it actually accepted. It silently
+        // drops permission groups the authenticating user isn't allowed to
+        // grant — so a token can come back with zero permissions even though
+        // the request was well-formed. Count what was granted and warn loudly
+        // if it's empty (almost always an account-role problem, not a bug).
+        const granted = (result.policies ?? []).reduce(
+          (n, p) => n + (p.permissionGroups?.length ?? 0),
+          0,
+        );
+
+        // Verify the freshly minted token actually authenticates. The
+        // Cloudflare dashboard has a long-standing rendering bug where
+        // API-created tokens show a blank permission summary (and a disabled
+        // "View"), which makes a perfectly good token look empty. A live
+        // `/user/tokens/verify` is the source of truth.
+        const status = yield* http
+          .get("https://api.cloudflare.com/client/v4/user/tokens/verify", {
+            headers: {
+              Authorization: `Bearer ${result.value}`,
+              Accept: "application/json",
+            },
+          })
+          .pipe(
+            Effect.flatMap((r) => r.json),
+            Effect.map(
+              (b) => (b as { result?: { status?: string } }).result?.status,
+            ),
+            Effect.catch(() => Effect.succeed(undefined)),
+          );
+
+        yield* Console.log("");
+        yield* Console.log(
+          `Created Cloudflare API token "${result.name ?? tokenName}" (${result.id ?? "unknown id"}).`,
+        );
+        yield* Console.log(
+          `Granted ${granted} permission group(s) across ${result.policies?.length ?? 0} policy(ies)` +
+            (status ? `; token status: ${status}.` : "."),
+        );
+        yield* Console.log("");
+        yield* Console.log(result.value);
+        yield* Console.log("");
+        yield* Console.log(
+          "Store this value now — Cloudflare only shows it once. " +
+            "Use it as CLOUDFLARE_API_TOKEN.",
+        );
+
+        if (granted === 0) {
+          yield* Clank.warn(
+            "Cloudflare granted 0 permissions. A token can only carry permissions " +
+              "the authenticating user already holds, so this usually means the " +
+              "Global API Key's user is not a Super Administrator on the selected " +
+              "account. Check the user's role in the Cloudflare dashboard " +
+              "(Members) and retry with an owner/Super Administrator.",
+          );
+        } else {
+          // Token is good; preempt the "it looks empty" confusion.
+          yield* Clank.info(
+            "Heads up: the Cloudflare dashboard often renders API-created tokens " +
+              'with a blank permission summary (and a greyed-out "View") — this is ' +
+              "a known UI bug, not a broken token. The permissions above are applied. " +
+              'To see them in the dashboard, open the token and click "← Edit token".',
+          );
+        }
+      }).pipe(Effect.provide(configProvider));
+    }),
+  ),
+);
+
 const tailFlag = Flag.boolean("tail").pipe(
   Flag.withDescription(
     "Stream logs in real time via the Cloudflare tail websocket instead of fetching past entries.",
@@ -220,5 +613,5 @@ const stateCommand = Command.make("state", {}).pipe(
 );
 
 export const cloudflareCommand = Command.make("cloudflare", {}).pipe(
-  Command.withSubcommands([bootstrapCommand, stateCommand]),
+  Command.withSubcommands([bootstrapCommand, createTokenCommand, stateCommand]),
 );

package/src/Cloudflare/AiGateway/AiGateway.ts

@@ -448,7 +448,8 @@ export const AiGatewayProvider = () =>
         rateLimitingLimit: nullIfZero(gateway.rateLimitingLimit),
         rateLimitingTechnique: gateway.rateLimitingTechnique ?? "fixed",
         authentication: gateway.authentication ?? false,
-        dlp: gateway.dlp ?? undefined,
+        // Distilled widened generated string enums to open unions (`string & {}`).
+        dlp: (gateway.dlp ?? undefined) as AiGatewayDlp | undefined,
         isDefault: gateway.isDefault ?? false,
         logManagement: gateway.logManagement ?? 100_000,
         logManagementStrategy:

package/src/Cloudflare/ApiToken/AccountApiToken.ts

@@ -9,9 +9,11 @@ import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import type { Providers } from "../Providers.ts";
 import {
   buildConditionPayload,
+  collectPolicies,
   conditionFingerprint,
   policyFingerprint,
   resolvePolicies,
+  type ApiTokenBinding,
   type ApiTokenProps,
 } from "./Common.ts";
 
@@ -30,7 +32,7 @@ export type AccountApiToken = Resource<
     value: Redacted.Redacted<string>;
     accountId: string;
   },
-  never,
+  ApiTokenBinding,
   Providers
 >;
 
@@ -70,6 +72,44 @@ export type AccountApiToken = Resource<
  *   value: token.value,
  * });
  * ```
+ *
+ * @section Attaching Policies via Bindings
+ * @example Let a downstream capability contribute its own policies
+ * A token can be created with no `policies` of its own; the policies are
+ * supplied through its binding contract (see {@link ApiTokenBinding}). This is
+ * how capabilities like {@link CreateTunnel} provision a least-privilege token.
+ * ```typescript
+ * const token = yield* Cloudflare.AccountApiToken("scoped-token");
+ *
+ * yield* token.bind("MyCapability", {
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       permissionGroups: ["Cloudflare Tunnel Write"],
+ *       resources: { [`com.cloudflare.api.account.${accountId}`]: "*" },
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @section Exposing a Token to a Worker
+ * @example Read the token value at runtime
+ * Bind the token's outputs in the Worker's Init phase to get runtime
+ * accessors. Binding `token.value` injects it as a `secret_text` Worker
+ * binding; the returned accessor reads it back (as `Redacted`) at runtime.
+ * ```typescript
+ * // init
+ * const value = yield* token.value; // Accessor<Redacted<string>>
+ * const accountId = yield* token.accountId; // Accessor<string>
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     const apiToken = yield* value; // Redacted<string>
+ *     // ... call the Cloudflare API with `apiToken`
+ *     return HttpServerResponse.text("ok");
+ *   }),
+ * };
+ * ```
  */
 export const AccountApiToken = Resource<AccountApiToken>(
   "Cloudflare.AccountApiToken",
@@ -96,21 +136,25 @@ export const AccountApiTokenProvider = () =>
         tokenData: {
           id?: string | null;
           name?: string | null;
-          status?: "active" | "disabled" | "expired" | null;
+          // Distilled widened generated string enums to open unions (`string & {}`).
+          status?: string | null;
         },
         value: Redacted.Redacted<string>,
         accountId: string,
       ): AccountApiTokenAttributes => ({
         tokenId: tokenData.id ?? "",
         name: tokenData.name ?? "",
-        status: tokenData.status ?? "active",
+        status: (tokenData.status ?? "active") as
+          | "active"
+          | "disabled"
+          | "expired",
         value,
         accountId,
       });
 
       return {
         stables: ["tokenId", "accountId"],
-        diff: Effect.fn(function* ({ id, olds, news, output }) {
+        diff: Effect.fn(function* ({ id, olds, news = {}, output }) {
           if (!isResolved(news)) return undefined;
           const newAccountId = news.accountId ?? defaultAccountId;
           const oldAccountId =
@@ -123,7 +167,9 @@ export const AccountApiTokenProvider = () =>
           const oldPolicyFp = policyFingerprint(
             resolvePolicies(olds?.policies ?? []),
           );
-          const newPolicyFp = policyFingerprint(resolvePolicies(news.policies));
+          const newPolicyFp = policyFingerprint(
+            resolvePolicies(news.policies ?? []),
+          );
           const oldCondFp = conditionFingerprint(olds?.condition);
           const newCondFp = conditionFingerprint(news.condition);
           if (
@@ -136,10 +182,17 @@ export const AccountApiTokenProvider = () =>
             return { action: "update" } as const;
           }
         }),
-        reconcile: Effect.fn(function* ({ id, news, output }) {
+        reconcile: Effect.fn(function* ({ id, news = {}, output, bindings }) {
           const accountId = news.accountId ?? defaultAccountId;
           const name = yield* resolveName(id, news.name);
-          const policies = resolvePolicies(news.policies);
+          const collected = collectPolicies(news.policies, bindings);
+          if (collected.length === 0) {
+            return yield* Effect.die(
+              `Cloudflare requires at least one policy on token "${name}". ` +
+                "Pass `policies` or attach them via a binding.",
+            );
+          }
+          const policies = resolvePolicies(collected);
 
           // Observe — fetch current state if we already know the token id.
           // Cloudflare reports a deleted token as `InvalidRoute` or