sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ ApiToken/ UserApiToken.ts

import * as user from "@distilled.cloud/cloudflare/user";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  buildConditionPayload,
  collectPolicies,
  conditionFingerprint,
  policyFingerprint,
  resolvePolicies,
  type ApiTokenBinding,
  type Props,
} from "./Common.ts";
import { uniqueTokens } from "./internal.ts";

export type UserApiToken = Resource<
  "Cloudflare.ApiToken.UserApiToken",
  Props,
  {
    tokenId: string;
    name: string;
    status: "active" | "disabled" | "expired";
    /**
     * The plaintext token value. Cloudflare returns this only once, on
     * creation, so we persist it here for downstream consumers.
     */
    value: Redacted.Redacted<string>;
  },
  ApiTokenBinding,
  Providers
>;

/**
 * A Cloudflare user-owned API token (`POST /user/tokens`).
 *
 * User-owned tokens are tied to the authenticated user's identity. They can
 * be created by any authenticated user (including OAuth-derived sessions
 * from `alchemy profile edit`) without needing the account-level
 * `API Tokens > Write` permission, but they are also revoked if the user
 * leaves the account.
 *
 * For CI tokens, prefer {@link AccountApiToken} so the token survives
 * personnel changes.
 *
 * Policy `resources` are passed through verbatim — no `accountId` rewriting
 * is performed because user tokens aren't bound to a single account.
 * ### Creating a Token
 * **Example:** A token bound to the authenticated user
 * ```typescript
 * const token = yield* Cloudflare.ApiToken.UserApiToken("personal-token", {
 *   name: "my-personal-token",
 *   policies: [
 *     {
 *       effect: "allow",
 *       permissionGroups: ["Workers Scripts Read"],
 *       resources: { [`com.cloudflare.api.account.${accountId}`]: "*" },
 *     },
 *   ],
 * });
 * ```
 *
 * ### 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}).
 * ```typescript
 * const token = yield* Cloudflare.ApiToken.UserApiToken("scoped-token");
 *
 * yield* token.bind("MyCapability", {
 *   policies: [
 *     {
 *       effect: "allow",
 *       permissionGroups: ["Workers Scripts Read"],
 *       resources: { [`com.cloudflare.api.account.${accountId}`]: "*" },
 *     },
 *   ],
 * });
 * ```
 *
 * ### Exposing a Token to a Worker
 * **Example:** Read the token value at runtime
 * Bind the token's value output in the Worker's Init phase to get a runtime
 * accessor. Binding it injects 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>>
 *
 * return {
 *   fetch: Effect.gen(function* () {
 *     const apiToken = yield* value; // Redacted<string>
 *     // ... call the Cloudflare API with `apiToken`
 *     return HttpServerResponse.text("ok");
 *   }),
 * };
 * ```
 *
 * @resource
 * @product API Tokens
 * @category Account & Identity
 */
export const UserApiToken = Resource<UserApiToken>("Cloudflare.ApiToken.UserApiToken", {
  aliases: ["Cloudflare.UserApiToken"],
});

type UserApiTokenAttributes = UserApiToken["Attributes"];

export const UserApiTokenProvider = () =>
  Provider.succeed(UserApiToken, {
    stables: ["tokenId"],
    diff: Effect.fn(function* ({ id, olds, news = {}, output }) {
      if (!isResolved(news)) return undefined;
      const oldName = output?.name ?? (yield* resolveName(id, olds?.name));
      const newName = yield* resolveName(id, news.name);
      const oldPolicyFp = policyFingerprint(resolvePolicies(olds?.policies ?? []));
      const newPolicyFp = policyFingerprint(resolvePolicies(news.policies ?? []));
      const oldCondFp = conditionFingerprint(olds?.condition);
      const newCondFp = conditionFingerprint(news.condition);
      if (
        oldName !== newName ||
        oldPolicyFp !== newPolicyFp ||
        oldCondFp !== newCondFp ||
        (olds?.expiresOn ?? undefined) !== (news.expiresOn ?? undefined) ||
        (olds?.notBefore ?? undefined) !== (news.notBefore ?? undefined)
      ) {
        return { action: "update" } as const;
      }
    }),
    reconcile: Effect.fn(function* ({ id, news = {}, output, bindings }) {
      const name = yield* resolveName(id, news.name);
      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 know the token id;
      // Cloudflare reports a deleted token as `TokenNotFound`, which
      // we treat as "create from scratch".
      const observed = output?.tokenId
        ? yield* user.getToken({ tokenId: output.tokenId }).pipe(
            Effect.map((token) => token),
            Effect.catchTag("TokenNotFound", () => Effect.undefined),
          )
        : undefined;

      // Ensure — create if missing. Cloudflare returns the plaintext
      // token value exactly once on create, so we must persist it.
      // No idempotency token is available; we accept a duplicate over
      // losing the secret value.
      if (observed === undefined) {
        const result = yield* user.createToken({
          name,
          policies,
          condition: buildConditionPayload(news.condition),
          expiresOn: news.expiresOn,
          notBefore: news.notBefore,
        });
        if (!result.value) {
          return yield* Effect.die(`Cloudflare did not return a value for token "${name}".`);
        }
        return buildAttributes(result, Redacted.make(result.value));
      }

      // Sync — the update API replaces all mutable fields. Cloudflare
      // does not return the plaintext value on update, so preserve
      // the one captured at creation.
      const result = yield* user.updateToken({
        tokenId: output!.tokenId,
        name,
        policies,
        condition: buildConditionPayload(news.condition),
        expiresOn: news.expiresOn,
        notBefore: news.notBefore,
      });
      return buildAttributes(result, output!.value);
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* user
        .deleteToken({ tokenId: output.tokenId })
        .pipe(Effect.catchTag("TokenNotFound", () => Effect.void));
    }),
    read: Effect.fn(function* ({ output }) {
      if (!output?.tokenId) return undefined;
      return yield* user.getToken({ tokenId: output.tokenId }).pipe(
        Effect.map((token) => buildAttributes(token, output.value)),
        Effect.catchTag("TokenNotFound", () => Effect.undefined),
      );
    }),
    // User-scoped: enumerate every token owned by the authenticated user via
    // `GET /user/tokens` (no account scope). The list API never returns the
    // plaintext token value — it is only emitted once at creation — so we
    // hydrate the read shape with an empty Redacted value, matching what
    // `read` produces when the secret was never captured.
    list: () =>
      // Offset-paginated over a name-sorted list: concurrent creates/deletes
      // between page fetches duplicate or skip tokens. Use the API's maximum
      // page size (1000) for a single-snapshot read and de-duplicate by id.
      user.listTokens.pages({ perPage: 1000 }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          uniqueTokens(Array.from(chunk).flatMap((page) => page.result ?? [])).map((token) =>
            buildAttributes(token, Redacted.make("")),
          ),
        ),
        // User-scoped tokens require user-level auth; an account-scoped token
        // (e.g. a CI profile) gets `Unauthorized` here — nothing to enumerate.
        Effect.catchTag("Unauthorized", () => Effect.succeed([])),
      ),
  });

const resolveName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    return name ?? (yield* createPhysicalName({ id }));
  });
const buildAttributes = (
  tokenData: {
    id?: string | null;
    name?: string | null;
    // Distilled widened generated string enums to open unions (`string & {}`).
    status?: string | null;
  },
  value: Redacted.Redacted<string>,
): UserApiTokenAttributes => ({
  tokenId: tokenData.id ?? "",
  name: tokenData.name ?? "",
  status: (tokenData.status ?? "active") as "active" | "disabled" | "expired",
  value,
});