sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ R2/ S3Credentials.ts

import * as CoreBinding from "alchemy/Binding";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import { sanitizeKey } from "alchemy/RuntimeContext";
import * as Effect from "effect/Effect";
import { isWorker, type Worker, WorkerEnvironment } from "../Workers/Worker.ts";
import type { Bucket } from "./Bucket.ts";
import { bindS3Credentials, type BucketInput, resolveBucket } from "./S3CredentialsBinding.ts";

export { isS3Credentials } from "./S3CredentialsBinding.ts";

/** Which object operations the credentials' API token is granted. */
export type S3CredentialsAccess = "read" | "write" | "read-write";

export interface S3CredentialsOptions {
  /**
   * Object operations the credentials may perform. Deployed, this selects
   * the permission groups of the bucket-scoped API token they are derived
   * from (`Workers R2 Storage Bucket Item Read` and/or
   * `Workers R2 Storage Bucket Item Write`).
   */
  access: S3CredentialsAccess;
}

/**
 * S3 API credentials and endpoint for one R2 bucket, as delivered to the
 * Worker. Use them with any S3 client (`aws4fetch`, `@aws-sdk/client-s3`)
 * with path-style addressing: `{endpoint}/{bucketName}/{key}`.
 */
export interface S3CredentialsValue {
  /**
   * S3 endpoint, without the bucket: `https://{accountId}.r2.cloudflarestorage.com`
   * when deployed, `{worker url}/cdn-cgi/local/r2/s3` under `alchemy dev`.
   */
  endpoint: string;
  /** Bucket name — the path segment after the endpoint. */
  bucketName: string;
  /** SigV4 signing region. */
  region: "auto";
  accessKeyId: string;
  secretAccessKey: string;
}

/**
 * The value returned by {@link S3Credentials}: declarable on an async
 * Worker's `env` (where it arrives as a JSON string) and `yield*`-able in an
 * Effect-native Worker (where it resolves to a deferred accessor).
 */
export interface S3Credentials extends Effect.Effect<
  Effect.Effect<S3CredentialsValue, never, RuntimeContext>,
  never,
  WorkerEnvironment
> {
  readonly "~alchemy/Kind": "Cloudflare.R2.S3Credentials";
  readonly bucket: BucketInput;
  readonly access: S3CredentialsAccess;
}

/**
 * S3 API credentials for an R2 bucket that work unchanged in `alchemy dev`
 * and when deployed — for presigned URLs or any S3 client.
 *
 * The native R2 binding cannot presign or speak the S3 API: that requires S3
 * credentials and R2's S3 endpoint. `S3Credentials` provides both, resolved
 * per mode:
 *
 * - **Deployed** — Alchemy mints an account API token for the Worker whose
 *   policy is scoped to this bucket only, and derives S3 credentials from it
 *   (access key id = token id, secret = SHA-256 of the token value). The
 *   endpoint is
 *   `https://{accountId}.r2.cloudflarestorage.com` (`.eu.`/`.fedramp.` for
 *   jurisdictional buckets). The value is injected as a secret.
 * - **`alchemy dev`** — a locally-emulated bucket is served on the Worker's
 *   local S3 endpoint (`{worker url}/cdn-cgi/local/r2/s3`) with fixed local
 *   credentials. No token or cloud call is involved, and objects are shared
 *   with the Worker's native bindings of the bucket.
 *
 * The Effect-native presign bindings (`PresignGetObjectToken`,
 * `PresignPutObjectToken`) are built on it.
 *
 * ### Effect-native Workers
 * **Example:** Read the credentials at runtime
 * ```typescript
 * const credentials = yield* Cloudflare.R2.S3Credentials(Uploads, {
 *   access: "read-write",
 * });
 * // inside a handler:
 * const { endpoint, bucketName, accessKeyId, secretAccessKey } =
 *   yield* credentials;
 * ```
 *
 * ### Async Workers
 * **Example:** Presign an upload with aws4fetch
 * ```typescript
 * // alchemy.run.ts
 * export const Uploads = Cloudflare.R2.Bucket("Uploads");
 * export const Api = Cloudflare.Worker("Api", {
 *   main: "./src/worker.ts",
 *   env: {
 *     UPLOADS_S3: Cloudflare.R2.S3Credentials(Uploads, { access: "write" }),
 *   },
 * });
 * export type ApiEnv = Cloudflare.InferEnv<typeof Api>;
 *
 * // src/worker.ts
 * import { AwsClient } from "aws4fetch";
 * import type * as Cloudflare from "@alchemy.run/cloudflare";
 * import type { ApiEnv } from "../alchemy.run.ts";
 *
 * export default {
 *   async fetch(request: Request, env: ApiEnv) {
 *     // `UPLOADS_S3` is a JSON string (a secret when deployed)
 *     const s3: Cloudflare.R2.S3CredentialsValue = JSON.parse(env.UPLOADS_S3);
 *     const client = new AwsClient({ ...s3, service: "s3" });
 *     const url = new URL(`${s3.endpoint}/${encodeURIComponent(s3.bucketName)}/avatar.png`);
 *     url.searchParams.set("X-Amz-Expires", "900");
 *     const signed = await client.sign(url.toString(), {
 *       method: "PUT",
 *       aws: { signQuery: true },
 *     });
 *     return Response.json({ url: signed.url });
 *   },
 * };
 * ```
 *
 * @binding
 * @product R2
 * @category Storage & Databases
 */
export const S3Credentials = (
  bucket: BucketInput,
  options: S3CredentialsOptions,
): S3Credentials => {
  const { access } = options;
  return Object.assign(
    Effect.gen(function* () {
      const host = yield* CoreBinding.Host;
      return yield* makeS3Credentials(
        isWorker(host) ? host : undefined,
        yield* WorkerEnvironment,
        yield* resolveBucket(bucket),
        access,
      );
    }),
    {
      "~alchemy/Kind": "Cloudflare.R2.S3Credentials" as const,
      bucket,
      access,
    },
  );
};

/**
 * Bind {@link S3Credentials} for `bucket` on `host` (deploy time) and return
 * the runtime accessor. `host` is only read at deploy time; it is
 * `undefined` inside the deployed Worker.
 *
 * NOT exported from `index.ts`.
 */
export const makeS3Credentials = (
  host: Worker | undefined,
  env: WorkerEnvironment["Service"],
  bucket: Bucket,
  access: S3CredentialsAccess,
) =>
  Effect.gen(function* () {
    const bindingName = sanitizeKey(
      `R2_S3_CREDENTIALS_${bucket.LogicalId}_${access}`,
    ).toUpperCase();
    if (!globalThis.__ALCHEMY_RUNTIME__) {
      if (host === undefined) {
        return yield* Effect.die(
          new Error(
            `Cloudflare.R2.S3Credentials(${bucket.LogicalId}) can only be bound to a Cloudflare Worker.`,
          ),
        );
      }
      // Deploy-time only; its requirements (CloudflareEnvironment, the
      // token provider) are ambient wherever a Worker is evaluated, so they
      // are erased like `Binding.Host`'s.
      // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- deploy-time only; requirements are ambient where the Worker is evaluated
      yield* bindS3Credentials(host, bindingName, bucket, access) as Effect.Effect<void>;
    }
    // Captured at init; read at exec phase, where it is populated.
    return Effect.suspend(() => {
      const raw = (env as Record<string, unknown>)[bindingName];
      return typeof raw === "string"
        ? Effect.succeed(JSON.parse(raw) as S3CredentialsValue)
        : Effect.die(
            new Error(
              `Cloudflare.R2.S3Credentials(${bucket.LogicalId}) is not bound to this Worker: missing "${bindingName}".`,
            ),
          );
    }) as Effect.Effect<S3CredentialsValue, never, RuntimeContext>;
  });