alchemy 2.0.0-beta.46 → 2.0.0-beta.48

package/src/Cloudflare/StateStore/State.ts

@@ -57,124 +57,130 @@ export const state = () =>
       const profileName = yield* ALCHEMY_PROFILE;
       const localStage = `${profileName}_${scriptName}`;
       const credStore = yield* CredentialsStore;
-      if (yield* hasLocalStack(localStage)) {
-        // if there's still a local stack, then we need to finish the bootstrap
-        // TODO(sam): what if the local stack was
-        return yield* deployWithLocalState({
-          scriptName,
-          profileName,
-          isCI,
-          force: false,
-        });
-      }
-
-      const ensureLatest = ({
-        url,
-        authToken,
-      }: {
-        url: string;
-        authToken: string;
-      }) =>
-        Effect.gen(function* () {
-          const { matches, expected, observed } =
-            yield* checkStateStoreVersion(url);
-
-          if (observed === undefined) {
-            const shouldDeploy = yield* Clank.confirm({
-              message: `Cloudflare State Store '${scriptName}' is not available. Do you want to deploy it?`,
-            });
-            if (shouldDeploy) {
-              return yield* bootstrap({
-                workerName: scriptName,
-                profile: profileName,
-              });
-            } else {
-              return yield* Effect.die(new Clank.PromptCancelled());
-            }
-          }
+      const context = yield* Effect.context<Effect.Services<typeof init>>();
+
+      const init = Effect.gen(function* () {
+        if (yield* hasLocalStack(localStage)) {
+          // if there's still a local stack, then we need to finish the bootstrap
+          // TODO(sam): what if the local stack was
+          return yield* deployWithLocalState({
+            scriptName,
+            profileName,
+            isCI,
+            force: false,
+          });
+        }
 
-          const httpState = yield* ensureAccess({ url, authToken });
-          if (matches) {
-            return httpState;
-          } else if (isCI) {
-            return yield* Effect.die(
-              new AuthError({
-                message: `Cloudflare State store not found. Run 'alchemy bootstrap cloudflare --profile <your-ci-profile>' to deploy it first.`,
-              }),
-            );
-          } else {
-            const shouldDeploy = yield* Clank.confirm({
-              message:
-                `Cloudflare State Store '${scriptName}' is out of date ` +
-                `(expected v${expected}, observed v${observed ?? "unknown"})`,
-            });
-            if (shouldDeploy) {
-              const stateStoreOptions = yield* deployStateStore({
-                stage: scriptName,
-                state: httpState,
-                force: false,
+        const ensureLatest = ({
+          url,
+          authToken,
+        }: {
+          url: string;
+          authToken: string;
+        }) =>
+          Effect.gen(function* () {
+            const { matches, expected, observed } =
+              yield* checkStateStoreVersion(url);
+
+            if (observed === undefined) {
+              const shouldDeploy = yield* Clank.confirm({
+                message: `Cloudflare State Store '${scriptName}' is not available. Do you want to deploy it?`,
               });
-              return yield* makeCloudflareStateStore(stateStoreOptions);
-            } else {
-              return yield* Effect.die(new Clank.PromptCancelled());
+              if (shouldDeploy) {
+                return yield* bootstrap({
+                  workerName: scriptName,
+                  profile: profileName,
+                });
+              } else {
+                return yield* Effect.die(new Clank.PromptCancelled());
+              }
             }
-          }
-        });
 
-      const ensureAccess = (credentials: HttpStateStoreCredentials) =>
-        Effect.gen(function* () {
-          const isAuth = yield* checkHttpStateStoreAuth(credentials);
-          if (!isAuth) {
-            // our token is wrong, force a refresh
-            yield* Clank.info(
-              `Cloudflare State store authentication failed, refreshing credentials...`,
-            );
-            const credentials = yield* loginWithCloudflare(profileName, true);
-            if (!(yield* checkHttpStateStoreAuth(credentials))) {
+            const httpState = yield* ensureAccess({ url, authToken });
+            if (matches) {
+              return httpState;
+            } else if (isCI) {
               return yield* Effect.die(
                 new AuthError({
-                  message: `Cloudflare State store authentication failed, after refreshing credentials.`,
+                  message: `Cloudflare State store not found. Run 'alchemy bootstrap cloudflare --profile <your-ci-profile>' to deploy it first.`,
                 }),
               );
+            } else {
+              const shouldDeploy = yield* Clank.confirm({
+                message:
+                  `Cloudflare State Store '${scriptName}' is out of date ` +
+                  `(expected v${expected}, observed v${observed ?? "unknown"})`,
+              });
+              if (shouldDeploy) {
+                const stateStoreOptions = yield* deployStateStore({
+                  stage: scriptName,
+                  state: httpState,
+                  force: false,
+                });
+                return yield* makeCloudflareStateStore(stateStoreOptions);
+              } else {
+                return yield* Effect.die(new Clank.PromptCancelled());
+              }
+            }
+          });
+
+        const ensureAccess = (credentials: HttpStateStoreCredentials) =>
+          Effect.gen(function* () {
+            const isAuth = yield* checkHttpStateStoreAuth(credentials);
+            if (!isAuth) {
+              // our token is wrong, force a refresh
+              yield* Clank.info(
+                `Cloudflare State store authentication failed, refreshing credentials...`,
+              );
+              const credentials = yield* loginWithCloudflare(profileName, true);
+              if (!(yield* checkHttpStateStoreAuth(credentials))) {
+                return yield* Effect.die(
+                  new AuthError({
+                    message: `Cloudflare State store authentication failed, after refreshing credentials.`,
+                  }),
+                );
+              }
+              return yield* makeCloudflareStateStore(credentials);
             }
             return yield* makeCloudflareStateStore(credentials);
-          }
-          return yield* makeCloudflareStateStore(credentials);
-        });
+          });
 
-      const credentials = yield* credStore.read<HttpStateStoreCredentials>(
-        profileName,
-        CREDENTIALS_FILE,
-      );
-      if (credentials) {
-        return yield* ensureLatest(credentials);
-      }
-      const workerExists = yield* isStateStoreAvailable(scriptName);
-      if (workerExists) {
-        return yield* ensureLatest(
-          yield* loginWithCloudflare(profileName, false),
-        );
-      } else if (isCI) {
-        // TODO(sam): do we want to support bootstrapping the state store from CI?
-        // for now - just die here
-        return yield* Effect.die(
-          new AuthError({
-            message: `Cloudflare State store not found. Run 'alchemy bootstrap cloudflare --profile <your-ci-profile>' to deploy it first.`,
-          }),
-        );
-      } else {
-        return yield* Clank.confirm({
-          message:
-            "Cloudflare State Store not found. Do you want to deploy it?",
-        }).pipe(
-          Effect.flatMap((shouldDeploy) =>
-            shouldDeploy
-              ? bootstrap()
-              : Effect.die(new Clank.PromptCancelled()),
-          ),
+        const credentials = yield* credStore.read<HttpStateStoreCredentials>(
+          profileName,
+          CREDENTIALS_FILE,
         );
-      }
-    }).pipe(recordStateStoreInit, Effect.orDie),
+        if (credentials) {
+          return yield* ensureLatest(credentials);
+        }
+        const workerExists = yield* isStateStoreAvailable(scriptName);
+        if (workerExists) {
+          return yield* ensureLatest(
+            yield* loginWithCloudflare(profileName, false),
+          );
+        } else if (isCI) {
+          // TODO(sam): do we want to support bootstrapping the state store from CI?
+          // for now - just die here
+          return yield* Effect.die(
+            new AuthError({
+              message: `Cloudflare State store not found. Run 'alchemy bootstrap cloudflare --profile <your-ci-profile>' to deploy it first.`,
+            }),
+          );
+        } else {
+          return yield* Clank.confirm({
+            message:
+              "Cloudflare State Store not found. Do you want to deploy it?",
+          }).pipe(
+            Effect.flatMap((shouldDeploy) =>
+              shouldDeploy
+                ? bootstrap()
+                : Effect.die(new Clank.PromptCancelled()),
+            ),
+          );
+        }
+      }).pipe(recordStateStoreInit, Effect.orDie);
+
+      return yield* Effect.cached(init.pipe(Effect.provideContext(context)));
+    }),
   ).pipe(
     Layer.provideMerge(Credentials.fromAuthProvider()),
     Layer.provideMerge(CloudflareEnvironment.fromProfile()),
@@ -311,7 +317,7 @@ const deployStateStore = ({
   Effect.gen(function* () {
     yield* annotateAccountHash();
     // deploy it with local state (which we will then hoist into the Cloudflare state store)
-    const stateLayer = Layer.succeed(State, state);
+    const stateLayer = Layer.succeed(State, Effect.succeed(state));
     const { url, authToken } = yield* deploy({
       // use the script name as the stage name (so the user can have multiple state stores)
       stage,

package/src/Cloudflare/Tunnel/Tunnel.ts

@@ -120,6 +120,33 @@ export type Tunnel = Resource<
  *   ],
  * });
  * ```
+ *
+ * @section Managing Tunnels at Runtime
+ * The `Tunnel` resource manages a single, statically-declared tunnel as part of
+ * a stack. To create, read, update, or delete tunnels *on the fly* from inside
+ * a deployed Worker, bind one of the runtime tunnel clients instead. Each
+ * provisions a least-privilege {@link AccountApiToken} and injects it into the
+ * Worker:
+ *
+ * - {@link TunnelRead} — read-only (`get`, `list`, `getToken`,
+ *   `getConfiguration`); scoped to `Cloudflare Tunnel Read`.
+ * - {@link TunnelWrite} — mutating (`create`, `update`, `delete`,
+ *   `putConfiguration`); scoped to `Cloudflare Tunnel Write`.
+ * - {@link TunnelReadWrite} — the full CRUD surface; scoped to both.
+ *
+ * @example Create a tunnel on demand from a Worker
+ * ```typescript
+ * // init
+ * const tunnels = yield* Cloudflare.TunnelReadWrite.bind();
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     const tunnel = yield* tunnels.create({ name: "on-demand-tunnel" });
+ *     const token = yield* tunnels.getToken(tunnel.id!);
+ *     return HttpServerResponse.json({ id: tunnel.id, token });
+ *   }),
+ * };
+ * ```
  */
 export const Tunnel = Resource<Tunnel>("Cloudflare.Tunnel");
 

package/src/Cloudflare/Tunnel/TunnelBinding.ts

@@ -0,0 +1,114 @@
+import {
+  Credentials,
+  fromApiToken,
+} from "@distilled.cloud/cloudflare/Credentials";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import type { HttpClient } from "effect/unstable/http/HttpClient";
+import type * as Binding from "../../Binding.ts";
+import { RuntimeContext } from "../../RuntimeContext.ts";
+import { AccountApiToken } from "../ApiToken/AccountApiToken.ts";
+import type { ApiTokenPermissionGroupRef } from "../ApiToken/Common.ts";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import { Worker } from "../Workers/Worker.ts";
+
+/**
+ * Runtime accessors for a tunnel binding's token, obtained by binding the
+ * {@link AccountApiToken}'s outputs in the Worker's Init phase. Each accessor
+ * reads the value back from the Worker's environment at runtime.
+ */
+export interface TunnelToken {
+  /** The token's plaintext value (injected as a `secret_text` binding). */
+  value: Effect.Effect<Redacted.Redacted<string>>;
+  /** The account id the token is scoped to. */
+  accountId: Effect.Effect<string>;
+}
+
+/**
+ * Bind an {@link AccountApiToken}'s outputs into the Worker so they can be read
+ * at runtime: `token.value` is injected as a `secret_text` binding and
+ * `token.accountId` as `plain_text`. Returns the {@link TunnelToken} accessors.
+ */
+export const bindTunnelToken = (token: AccountApiToken) =>
+  Effect.gen(function* () {
+    const value = yield* token.value;
+    const accountId = yield* token.accountId;
+    return { value, accountId } satisfies TunnelToken;
+  });
+
+/**
+ * Resolve credentials from a bound token and provide them (plus the
+ * fetch-based HTTP client) to a raw SDK operation.
+ */
+export const authorizeWith =
+  (token: TunnelToken) =>
+  <A, E>(
+    eff: Effect.Effect<A, E, Credentials | HttpClient>,
+  ): Effect.Effect<A, E, RuntimeContext> =>
+    token.value.pipe(
+      Effect.flatMap((value) =>
+        eff.pipe(
+          Effect.provide(
+            fromApiToken({ apiToken: Redacted.value(value) }).pipe(
+              Layer.provideMerge(FetchHttpClient.layer),
+            ),
+          ),
+        ),
+      ),
+    );
+
+/**
+ * Shared runtime body for a tunnel binding: create a scoped token, attach the
+ * (narrow) policy, bind the token's outputs into the Worker, then build the
+ * client. Pass the result to `Layer.effect(<Binding>, ...)`.
+ */
+export const makeTunnelClient = <C>(
+  Policy: Binding.Policy<
+    any,
+    any,
+    (token: AccountApiToken) => Effect.Effect<void>
+  >,
+  makeClient: (token: TunnelToken) => C,
+) =>
+  Effect.gen(function* () {
+    const Token = yield* AccountApiToken;
+    const attach = yield* Policy;
+
+    return Effect.fn(function* () {
+      const ctx = yield* Worker;
+      const token = yield* Token(`${ctx.LogicalId}Token`);
+      yield* attach(token);
+      return makeClient(yield* bindTunnelToken(token));
+    });
+  });
+
+/**
+ * Build the deploy-time policy layer for a tunnel binding: attach an allow
+ * policy with the given permission groups to the binding's token.
+ */
+export const makeTunnelPolicyLive = <Self, Id extends string>(
+  Policy: Binding.Policy<
+    Self,
+    Id,
+    (token: AccountApiToken) => Effect.Effect<void>
+  >,
+  sid: string,
+  permissionGroups: ApiTokenPermissionGroupRef[],
+) =>
+  Policy.layer.effect(
+    Effect.gen(function* () {
+      const { accountId } = yield* CloudflareEnvironment;
+      return (_host, token) =>
+        token.bind(sid, {
+          policies: [
+            {
+              effect: "allow",
+              permissionGroups,
+              resources: { [`com.cloudflare.api.account.${accountId}`]: "*" },
+            },
+          ],
+        });
+    }),
+  );

package/src/Cloudflare/Tunnel/TunnelRead.ts

@@ -0,0 +1,168 @@
+import type {
+  GetTunnelCloudflaredConfigurationError,
+  GetTunnelCloudflaredConfigurationResponse,
+  GetTunnelCloudflaredError,
+  GetTunnelCloudflaredResponse,
+  GetTunnelCloudflaredTokenError,
+  GetTunnelCloudflaredTokenResponse,
+  ListTunnelCloudflaredsError,
+  ListTunnelCloudflaredsRequest,
+  ListTunnelCloudflaredsResponse,
+} from "@distilled.cloud/cloudflare/zero-trust";
+import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Binding from "../../Binding.ts";
+import type { RuntimeContext } from "../../RuntimeContext.ts";
+import type { AccountApiToken } from "../ApiToken/AccountApiToken.ts";
+import type { Worker } from "../Workers/Worker.ts";
+import {
+  authorizeWith,
+  makeTunnelClient,
+  makeTunnelPolicyLive,
+  type TunnelToken,
+} from "./TunnelBinding.ts";
+
+/** List-tunnels request, minus the account id (supplied by the binding). */
+export type ListTunnelsRequest = Omit<
+  ListTunnelCloudflaredsRequest,
+  "accountId"
+>;
+
+/**
+ * Read-only tunnel operations. Backed by the `Cloudflare Tunnel Read`
+ * permission group.
+ */
+export interface TunnelReadClient {
+  /** Fetch a single tunnel by id. */
+  get(
+    tunnelId: string,
+  ): Effect.Effect<
+    GetTunnelCloudflaredResponse,
+    GetTunnelCloudflaredError,
+    RuntimeContext
+  >;
+  /** List tunnels in the account. */
+  list(
+    request?: ListTunnelsRequest,
+  ): Effect.Effect<
+    ListTunnelCloudflaredsResponse,
+    ListTunnelCloudflaredsError,
+    RuntimeContext
+  >;
+  /** Fetch the connector token used to run the tunnel. */
+  getToken(
+    tunnelId: string,
+  ): Effect.Effect<
+    GetTunnelCloudflaredTokenResponse,
+    GetTunnelCloudflaredTokenError,
+    RuntimeContext
+  >;
+  /** Read the remotely-managed configuration (ingress rules) for a tunnel. */
+  getConfiguration(
+    tunnelId: string,
+  ): Effect.Effect<
+    GetTunnelCloudflaredConfigurationResponse,
+    GetTunnelCloudflaredConfigurationError,
+    RuntimeContext
+  >;
+}
+
+/** Build the read-only client over a bound token. */
+export const readClient = (token: TunnelToken): TunnelReadClient => {
+  const authorize = authorizeWith(token);
+  return {
+    get: Effect.fn("Cloudflare.Tunnel.get")(function* (tunnelId) {
+      const accountId = yield* token.accountId;
+      return yield* authorize(
+        zeroTrust.getTunnelCloudflared({ accountId, tunnelId }),
+      );
+    }),
+    list: Effect.fn("Cloudflare.Tunnel.list")(function* (request) {
+      const accountId = yield* token.accountId;
+      return yield* authorize(
+        zeroTrust.listTunnelCloudflareds({ accountId, ...request }),
+      );
+    }),
+    getToken: Effect.fn("Cloudflare.Tunnel.getToken")(function* (tunnelId) {
+      const accountId = yield* token.accountId;
+      return yield* authorize(
+        zeroTrust.getTunnelCloudflaredToken({ accountId, tunnelId }),
+      );
+    }),
+    getConfiguration: Effect.fn("Cloudflare.Tunnel.getConfiguration")(
+      function* (tunnelId) {
+        const accountId = yield* token.accountId;
+        return yield* authorize(
+          zeroTrust.getTunnelCloudflaredConfiguration({ accountId, tunnelId }),
+        );
+      },
+    ),
+  };
+};
+
+/**
+ * Binding that lets a Worker read Cloudflare Tunnels at runtime.
+ *
+ * Creates a scoped {@link AccountApiToken} with only the `Cloudflare Tunnel
+ * Read` permission and binds its outputs into the Worker (the token value as a
+ * `secret_text` binding) so runtime code can authenticate.
+ *
+ * @binding
+ *
+ * @section Reading tunnels at runtime
+ * @example Bind the read client
+ * Bind once in the Init phase; every method is available on the returned client.
+ * ```typescript
+ * const tunnels = yield* Cloudflare.TunnelRead.bind();
+ * ```
+ *
+ * @example List tunnels
+ * ```typescript
+ * const { result } = yield* tunnels.list({ isDeleted: false });
+ * ```
+ *
+ * @example Fetch a tunnel and its connector token
+ * `getToken` returns the plaintext token used to run `cloudflared`.
+ * ```typescript
+ * const tunnel = yield* tunnels.get(tunnelId);
+ * const token = yield* tunnels.getToken(tunnelId);
+ * ```
+ *
+ * @example Read the ingress configuration
+ * ```typescript
+ * const { config } = yield* tunnels.getConfiguration(tunnelId);
+ * ```
+ *
+ * @section Runtime Layer
+ * Provide {@link TunnelReadLive} in the Worker's runtime layer.
+ * ```typescript
+ * Effect.provide(Cloudflare.TunnelReadLive)
+ * ```
+ */
+export class TunnelRead extends Binding.Service<
+  TunnelRead,
+  () => Effect.Effect<TunnelReadClient, never, Worker>
+>()("Cloudflare.TunnelRead") {}
+
+/**
+ * Deploy-time policy for {@link TunnelRead}. Attaches the `Cloudflare Tunnel
+ * Read` permission to the token via its binding contract.
+ */
+export class TunnelReadPolicy extends Binding.Policy<
+  TunnelReadPolicy,
+  (token: AccountApiToken) => Effect.Effect<void>
+>()("Cloudflare.TunnelRead") {}
+
+/** Runtime layer for {@link TunnelRead}. */
+export const TunnelReadLive = Layer.effect(
+  TunnelRead,
+  makeTunnelClient(TunnelReadPolicy, readClient),
+);
+
+/** Live deploy-time policy layer for {@link TunnelReadPolicy}. */
+export const TunnelReadPolicyLive = makeTunnelPolicyLive(
+  TunnelReadPolicy,
+  "Cloudflare.TunnelRead",
+  ["Cloudflare Tunnel Read"],
+);

package/src/Cloudflare/Tunnel/TunnelReadWrite.ts

@@ -0,0 +1,88 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Binding from "../../Binding.ts";
+import type { AccountApiToken } from "../ApiToken/AccountApiToken.ts";
+import type { Worker } from "../Workers/Worker.ts";
+import {
+  makeTunnelClient,
+  makeTunnelPolicyLive,
+  type TunnelToken,
+} from "./TunnelBinding.ts";
+import { readClient, type TunnelReadClient } from "./TunnelRead.ts";
+import { writeClient, type TunnelWriteClient } from "./TunnelWrite.ts";
+
+/** Combined read + write tunnel operations. */
+export interface TunnelReadWriteClient
+  extends TunnelReadClient, TunnelWriteClient {}
+
+/** Build the combined read + write client over a bound token. */
+export const readWriteClient = (token: TunnelToken): TunnelReadWriteClient => ({
+  ...readClient(token),
+  ...writeClient(token),
+});
+
+/**
+ * Binding that lets a Worker perform the full Cloudflare Tunnel CRUD surface at
+ * runtime.
+ *
+ * Creates a scoped {@link AccountApiToken} with both the `Cloudflare Tunnel
+ * Read` and `Cloudflare Tunnel Write` permissions and binds its outputs into
+ * the Worker (the token value as a `secret_text` binding) so runtime code can
+ * authenticate.
+ *
+ * @binding
+ *
+ * @section Managing tunnels at runtime
+ * @example Create, configure, and delete a tunnel from a request handler
+ * ```typescript
+ * // init
+ * const tunnels = yield* Cloudflare.TunnelReadWrite.bind();
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     const tunnel = yield* tunnels.create({ name: "on-demand-tunnel" });
+ *     yield* tunnels.putConfiguration(tunnel.id!, {
+ *       ingress: [
+ *         { hostname: "app.example.com", service: "http://localhost:3000" },
+ *         { service: "http_status:404" },
+ *       ],
+ *     });
+ *     const token = yield* tunnels.getToken(tunnel.id!);
+ *     return HttpServerResponse.json({ id: tunnel.id, token });
+ *   }),
+ * };
+ * ```
+ *
+ * @section Runtime Layer
+ * Provide {@link TunnelReadWriteLive} in the Worker's runtime layer.
+ * ```typescript
+ * Effect.provide(Cloudflare.TunnelReadWriteLive)
+ * ```
+ */
+export class TunnelReadWrite extends Binding.Service<
+  TunnelReadWrite,
+  () => Effect.Effect<TunnelReadWriteClient, never, Worker>
+>()("Cloudflare.TunnelReadWrite") {}
+
+/**
+ * Deploy-time policy for {@link TunnelReadWrite}. Attaches both the `Cloudflare
+ * Tunnel Read` and `Cloudflare Tunnel Write` permissions to the token via its
+ * binding contract.
+ */
+export class TunnelReadWritePolicy extends Binding.Policy<
+  TunnelReadWritePolicy,
+  (token: AccountApiToken) => Effect.Effect<void>
+>()("Cloudflare.TunnelReadWrite") {}
+
+/** Runtime layer for {@link TunnelReadWrite}. */
+export const TunnelReadWriteLive = Layer.effect(
+  TunnelReadWrite,
+  makeTunnelClient(TunnelReadWritePolicy, readWriteClient),
+);
+
+/** Live deploy-time policy layer for {@link TunnelReadWritePolicy}. */
+export const TunnelReadWritePolicyLive = makeTunnelPolicyLive(
+  TunnelReadWritePolicy,
+  "Cloudflare.TunnelReadWrite",
+  ["Cloudflare Tunnel Read", "Cloudflare Tunnel Write"],
+);