sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Workers/ WorkerAccess.ts

import type * as cf from "@cloudflare/workers-types";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import type { Application, ApplicationProps } from "../Access/Application.ts";

/**
 * Protect this Worker with Cloudflare Access (`access` prop). Two forms:
 *
 * - a `Cloudflare.Access.Application` — enroll into a **shared**
 *   application (one policy set across several Workers). Note Access
 *   policies are application-wide: every Worker enrolled in the
 *   application is gated by the same policies.
 * - `{ policies, ... }` — a **dedicated** application owned by this
 *   Worker, created/updated/deleted with it. Access configuration
 *   (policies, session duration, IdPs) lives on applications, so
 *   per-Worker configuration means a per-Worker application — this form
 *   declares one for you, namespaced under the Worker (`<Worker>/Access`).
 *
 * Either way, enrolling pushes this Worker's `worker` destination (and a
 * `preview_worker` destination unless `previews: false`) onto the
 * application through its binding contract, so the application deploys
 * with — and converges on — the destinations of every enrolled Worker.
 * Removing the prop (or the Worker) un-enrolls it on the application's
 * next reconcile.
 */
export type WorkerAccessConfig = Application | WorkerAccessApplication;

/**
 * A dedicated Access application owned by this Worker — per-Worker
 * policies without declaring the application yourself.
 */
export interface WorkerAccessApplication {
  /**
   * Policies gating access to this Worker — inline bodies, reusable
   * `Cloudflare.Access.Policy` resources, or policy ids (see
   * `ApplicationProps["policies"]`).
   */
  policies: NonNullable<ApplicationProps["policies"]>;
  /** Display name for the application. Auto-generated when omitted. */
  name?: string;
  /** Session lifetime, e.g. `"24h"`. */
  sessionDuration?: string;
  /** Allowed identity-provider UUIDs. */
  allowedIdps?: string[];
  /** Skip the IdP picker when exactly one IdP is allowed. */
  autoRedirectToIdentity?: boolean;
  /** Show the application in the App Launcher dashboard. */
  appLauncherVisible?: boolean;
  /**
   * Also protect the Worker's version preview URLs.
   * @default true
   */
  previews?: boolean;
}

export class WorkerAccessIdentityError extends Data.TaggedError("WorkerAccessIdentityError")<{
  message: string;
  cause?: unknown;
}> {}

/**
 * The identity Cloudflare Access authenticated for the current request,
 * as resolved by `ctx.access.getIdentity()`. Field names follow the wire
 * format of Access's identity payload (snake_case); identity providers can
 * attach additional fields, captured by the index signature.
 */
export interface WorkerAccessIdentity {
  /** The user's email address, if the identity provider supplies one. */
  readonly email?: string;
  /** The user's display name. */
  readonly name?: string;
  /** The user's unique identifier. */
  readonly user_uuid?: string;
  /** The Cloudflare account id the Access organization belongs to. */
  readonly account_id?: string;
  /** Login timestamp (Unix epoch seconds). */
  readonly iat?: number;
  /** The user's IP address at authentication time. */
  readonly ip?: string;
  /** Authentication methods used (e.g. `"pwd"`). */
  readonly amr?: string[];
  /** Identity-provider information. */
  readonly idp?: { id: string; type: string };
  /** Where the user authenticated from. */
  readonly geo?: { country: string };
  /** Group memberships from the identity provider. */
  readonly groups?: Array<{ id: string; name: string; email?: string }>;
  /** Device posture check results, keyed by check id. */
  readonly devicePosture?: Record<string, unknown>;
  /** True when the user connected via Cloudflare WARP. */
  readonly is_warp?: boolean;
  /** True when the user is authenticated via Cloudflare Gateway. */
  readonly is_gateway?: boolean;
  /** Service-token client id, when authenticated via a service token. */
  readonly service_token_id?: string;
  /** True when the request authenticated with a service token. */
  readonly service_token_status?: boolean;
  readonly [key: string]: unknown;
}

/**
 * Effect-native view of the Cloudflare Access runtime API on the execution
 * context (`ctx.access`). Present only when the request was admitted by a
 * Cloudflare Access policy (see the `access` prop on `Cloudflare.Worker`),
 * or when simulated locally via the Worker's `dev.access` config.
 */
export interface WorkerExecutionContextAccess {
  /** The Access application audience (AUD) tag that admitted this request. */
  readonly aud: string;
  /**
   * Resolve the authenticated identity — email, name, groups, device
   * posture, etc. Resolves `undefined` when Access has no identity for the
   * request (e.g. some service-token flows).
   */
  getIdentity(): Effect.Effect<
    WorkerAccessIdentity | undefined,
    WorkerAccessIdentityError,
    RuntimeContext
  >;
}

/**
 * The shape workerd exposes on `ctx.access` (typed locally — this package's
 * workers-types predates it) and that the local dev simulation mirrors.
 */
interface RawAccessContext {
  readonly aud: string;
  getIdentity(): Promise<WorkerAccessIdentity | undefined>;
}

const makeAccessContext = (raw: RawAccessContext): WorkerExecutionContextAccess => ({
  aud: raw.aud,
  getIdentity: () =>
    Effect.tryPromise({
      try: () => raw.getIdentity(),
      catch: (cause) =>
        new WorkerAccessIdentityError({
          message:
            cause instanceof Error ? cause.message : "Unknown Access identity resolution error",
          cause,
        }),
    }),
});

/** The env key `dev.access` is lowered into by the local worker provider. */
export const DEV_ACCESS_ENV_KEY = "ALCHEMY_DEV_ACCESS";

/**
 * Resolve the current request's Access context: workerd's native
 * `ctx.access` when the request came through Cloudflare Access, the
 * `dev.access` simulation under `alchemy dev`, and `undefined` (an
 * unauthenticated request) otherwise. Backs the `access` member of the
 * per-event `WorkerExecutionContext`.
 */
export const resolveAccessContext = (
  ctx: cf.ExecutionContext,
  env: Record<string, unknown> | undefined,
): WorkerExecutionContextAccess | undefined => {
  // Deployed behind Access: workerd populates ctx.access natively.
  const native = (ctx as cf.ExecutionContext & { access?: RawAccessContext }).access;
  if (native !== undefined) {
    return makeAccessContext(native);
  }
  // Local dev: the Worker's `dev.access` config is lowered into an env
  // binding; absent config simulates an unauthenticated request.
  const dev = env?.[DEV_ACCESS_ENV_KEY] as
    | { aud?: string; identity?: WorkerAccessIdentity }
    | undefined;
  if (dev !== undefined) {
    return {
      aud: dev.aud ?? "dev",
      getIdentity: () => Effect.succeed(dev.identity),
    };
  }
  return undefined;
};