alepha 0.19.4 → 0.19.5

package/src/captcha/providers/TurnstileCaptchaProvider.ts

@@ -0,0 +1,125 @@
+import { $context, AlephaError, t } from "alepha";
+import { $logger } from "alepha/logger";
+import type { CaptchaProvider } from "./CaptchaProvider.ts";
+
+/**
+ * Cloudflare Turnstile captcha verification provider.
+ *
+ * Validates captcha tokens against the Cloudflare Turnstile siteverify API.
+ * Free, privacy-friendly, and supports invisible mode.
+ *
+ * ## Setup
+ *
+ * 1. Create a Turnstile widget at https://dash.cloudflare.com/?to=/:account/turnstile
+ * 2. Copy the **Site Key** (public, for the client) and **Secret Key** (private, for the server)
+ * 3. Set `TURNSTILE_SECRET_KEY` in your environment
+ *
+ * ## Client-side integration
+ *
+ * Add the Turnstile script and widget to your form:
+ *
+ * ```html
+ * <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
+ * <form>
+ *   <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
+ *   <button type="submit">Submit</button>
+ * </form>
+ * ```
+ *
+ * The widget injects a hidden `cf-turnstile-response` input into the form.
+ * Send this value as the `captchaToken` in your registration request.
+ *
+ * For explicit rendering (React, SPA):
+ *
+ * ```ts
+ * turnstile.render("#container", {
+ *   sitekey: "YOUR_SITE_KEY",
+ *   callback: (token) => setCaptchaToken(token),
+ * });
+ * ```
+ *
+ * ## Server-side usage
+ *
+ * Register the provider in your app:
+ *
+ * ```ts
+ * import { CaptchaProvider } from "alepha/captcha";
+ * import { TurnstileCaptchaProvider } from "alepha/captcha";
+ *
+ * alepha.with({ provide: CaptchaProvider, use: TurnstileCaptchaProvider });
+ * ```
+ *
+ * ## Test keys (for development)
+ *
+ * - Always passes: site `1x00000000000000000000AA`, secret `1x0000000000000000000000000000000AA`
+ * - Always blocks: site `2x00000000000000000000AB`, secret `2x0000000000000000000000000000000AB`
+ * - Forces interactive: site `3x00000000000000000000FF`
+ *
+ * ## Environment Variables
+ *
+ * - `TURNSTILE_SECRET_KEY`: The secret key from the Cloudflare Turnstile dashboard.
+ *
+ * @see https://developers.cloudflare.com/turnstile/get-started/server-side-validation/
+ */
+export class TurnstileCaptchaProvider implements CaptchaProvider {
+  protected readonly log = $logger();
+  protected readonly secretKey: string;
+
+  constructor() {
+    const { alepha } = $context();
+
+    const env = alepha.parseEnv(
+      t.object({
+        TURNSTILE_SECRET_KEY: t.text({
+          description:
+            "The secret key from the Cloudflare Turnstile dashboard.",
+        }),
+      }),
+    );
+
+    this.secretKey = env.TURNSTILE_SECRET_KEY;
+  }
+
+  public async verify(token: string, ip?: string): Promise<boolean> {
+    const body = new URLSearchParams();
+    body.set("secret", this.secretKey);
+    body.set("response", token);
+
+    if (ip) {
+      body.set("remoteip", ip);
+    }
+
+    try {
+      const res = await fetch(
+        "https://challenges.cloudflare.com/turnstile/v0/siteverify",
+        {
+          method: "POST",
+          body,
+        },
+      );
+
+      const data = (await res.json()) as TurnstileResponse;
+
+      if (!data.success) {
+        this.log.debug("Turnstile verification failed", {
+          errorCodes: data["error-codes"],
+        });
+      }
+
+      return data.success;
+    } catch (error) {
+      throw new AlephaError("Failed to verify Turnstile captcha token", {
+        cause: error,
+      });
+    }
+  }
+}
+
+interface TurnstileResponse {
+  success: boolean;
+  "error-codes"?: string[];
+  challenge_ts?: string;
+  hostname?: string;
+  action?: string;
+  cdata?: string;
+}

package/src/cli/core/atoms/buildOptions.ts

@@ -207,6 +207,63 @@ export const buildOptions = $atom({
       }),
     ),
 
+    /**
+     * PWA (Progressive Web App) configuration.
+     *
+     * Generates a web app manifest and enables installability.
+     * Requires a client-side bundle (React).
+     */
+    pwa: t.optional(
+      t.object({
+        /**
+         * Full application name displayed on the splash screen
+         * and in the OS app switcher.
+         */
+        name: t.string(),
+
+        /**
+         * Short name displayed on the home screen icon.
+         * Falls back to `name` if omitted.
+         */
+        shortName: t.optional(t.string()),
+
+        /**
+         * Theme color used for the browser toolbar and OS chrome.
+         *
+         * @default "#ffffff"
+         */
+        themeColor: t.optional(t.string()),
+
+        /**
+         * Background color for the splash screen.
+         *
+         * @default "#ffffff"
+         */
+        backgroundColor: t.optional(t.string()),
+
+        /**
+         * Display mode for the installed PWA.
+         *
+         * - `standalone` - Looks like a native app (default)
+         * - `fullscreen` - Uses entire screen (games, immersive)
+         * - `minimal-ui` - Like standalone with minimal browser UI
+         * - `browser` - Standard browser tab
+         *
+         * @default "standalone"
+         */
+        display: t.optional(
+          t.enum(["standalone", "fullscreen", "minimal-ui", "browser"]),
+        ),
+
+        /**
+         * Enable offline support via service worker.
+         *
+         * TODO: Not yet implemented.
+         */
+        offline: t.optional(t.boolean()),
+      }),
+    ),
+
     /**
      * Sitemap generation configuration.
      */

package/src/cli/core/commands/build.ts

@@ -17,6 +17,7 @@ import { BuildCloudflareTask } from "../tasks/BuildCloudflareTask.ts";
 import { BuildCompressTask } from "../tasks/BuildCompressTask.ts";
 import { BuildDockerTask } from "../tasks/BuildDockerTask.ts";
 import { BuildPrerenderTask } from "../tasks/BuildPrerenderTask.ts";
+import { BuildPwaTask } from "../tasks/BuildPwaTask.ts";
 import { BuildServerTask } from "../tasks/BuildServerTask.ts";
 import { BuildSitemapTask } from "../tasks/BuildSitemapTask.ts";
 import { BuildStaticTask } from "../tasks/BuildStaticTask.ts";
@@ -43,6 +44,7 @@ export class BuildCommand {
     $inject(BuildServerTask),
     $inject(BuildAssetsTask),
     $inject(BuildSitemapTask),
+    $inject(BuildPwaTask),
     $inject(BuildPrerenderTask),
     $inject(BuildVercelTask),
     $inject(BuildCloudflareTask),

package/src/cli/core/providers/ViteDevServerProvider.ts

@@ -594,7 +594,7 @@ if (import.meta.hot) {
 </script>`);
 
     if (style) {
-      tags.push(`<link rel="stylesheet" href="/${style}">`);
+      tags.push(`<script type="module">import "/${style}";</script>`);
     }
     if (browser) {
       tags.push(`<script type="module" src="/${browser}"></script>`);

package/src/cli/core/services/ViteUtils.ts

@@ -359,16 +359,19 @@ export class ViteUtils {
   // HTML template
   // ---------------------------------------------------------------------------------------------------------------
 
-  public generateIndexHtml(entry: AppEntry): string {
+  public generateIndexHtml(entry: AppEntry, opts?: { pwa?: boolean }): string {
     const style = entry.style;
     const browser = entry.browser ?? entry.server;
+    const manifestLink = opts?.pwa
+      ? '\n<link rel="manifest" href="/manifest.webmanifest" />'
+      : "";
     return `
 <!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="UTF-8" />
 <title>App</title>
-<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>${manifestLink}
 ${style ? `<link rel="stylesheet" href="/${style}" />` : ""}
 </head>
 <body>

package/src/cli/core/tasks/BuildClientTask.ts

@@ -29,7 +29,9 @@ export class BuildClientTask extends BuildTask {
     const isCI = this.alepha.isCI();
 
     // Write index.html template for Vite to consume
-    const template = this.viteUtils.generateIndexHtml(ctx.entry);
+    const template = this.viteUtils.generateIndexHtml(ctx.entry, {
+      pwa: !!ctx.options.pwa,
+    });
     await this.fs.mkdir(this.fs.join(ctx.root, "node_modules/.alepha"));
     const indexHtmlPath = this.fs.join(
       ctx.root,

package/src/cli/core/tasks/BuildCloudflareTask.ts

@@ -141,11 +141,13 @@ export class BuildCloudflareTask extends BuildTask {
 
     const [dbName, id] = url.replace("d1://", "").replace("d1:", "").split(":");
     const binding = BuildCloudflareTask.D1_BINDING;
+    const jurisdiction = process.env.CLOUDFLARE_JURISDICTION;
     wrangler.d1_databases = wrangler.d1_databases || [];
     wrangler.d1_databases.push({
       binding,
       database_name: dbName,
       database_id: id,
+      ...(jurisdiction ? { jurisdiction } : {}),
     });
     wrangler.vars ??= {};
     wrangler.vars.DATABASE_URL = `d1://${binding}`;
@@ -177,10 +179,12 @@ export class BuildCloudflareTask extends BuildTask {
       return;
     }
 
+    const jurisdiction = process.env.CLOUDFLARE_JURISDICTION;
     wrangler.r2_buckets = wrangler.r2_buckets || [];
     wrangler.r2_buckets.push({
       binding: bucketName,
       bucket_name: bucketName,
+      ...(jurisdiction ? { jurisdiction } : {}),
     });
     wrangler.vars ??= {};
     wrangler.vars.R2_BUCKET_NAME = bucketName;

package/src/cli/core/tasks/BuildPwaTask.ts

@@ -0,0 +1,81 @@
+import { $inject } from "alepha";
+import { FileSystemProvider } from "alepha/system";
+import { BuildTask, type BuildTaskContext } from "./BuildTask.ts";
+
+/**
+ * Generate PWA web app manifest.
+ *
+ * Produces a `manifest.webmanifest` in the public output directory
+ * from the `pwa` section of build options. Detects icons from `public/`.
+ */
+export class BuildPwaTask extends BuildTask {
+  protected readonly fs = $inject(FileSystemProvider);
+
+  async run(ctx: BuildTaskContext): Promise<void> {
+    const pwa = ctx.options.pwa;
+    if (!pwa || !ctx.hasClient) {
+      return;
+    }
+
+    const distDir = ctx.options.output?.dist ?? "dist";
+    const publicDir = ctx.options.output?.public ?? "public";
+    const outputDir = this.fs.join(ctx.root, distDir, publicDir);
+
+    await ctx.run({
+      name: "generate pwa manifest",
+      handler: async () => {
+        const icons = await this.detectIcons(outputDir);
+
+        const manifest: Record<string, unknown> = {
+          name: pwa.name,
+          short_name: pwa.shortName ?? pwa.name,
+          start_url: "/",
+          display: pwa.display ?? "standalone",
+          theme_color: pwa.themeColor ?? "#ffffff",
+          background_color: pwa.backgroundColor ?? "#ffffff",
+        };
+
+        if (icons.length > 0) {
+          manifest.icons = icons;
+        }
+
+        const output = this.fs.join(outputDir, "manifest.webmanifest");
+        await this.fs.writeFile(output, JSON.stringify(manifest, null, 2));
+      },
+    });
+  }
+
+  /**
+   * Detect icon files in the public output directory.
+   *
+   * Looks for common icon filenames and generates
+   * manifest icon entries with appropriate sizes and types.
+   */
+  protected async detectIcons(
+    publicDir: string,
+  ): Promise<Array<{ src: string; sizes: string; type: string }>> {
+    const icons: Array<{ src: string; sizes: string; type: string }> = [];
+
+    const candidates: Array<{
+      file: string;
+      sizes: string;
+      type: string;
+    }> = [
+      { file: "icon-192.png", sizes: "192x192", type: "image/png" },
+      { file: "icon-512.png", sizes: "512x512", type: "image/png" },
+      { file: "icon.svg", sizes: "any", type: "image/svg+xml" },
+    ];
+
+    for (const candidate of candidates) {
+      if (await this.fs.exists(this.fs.join(publicDir, candidate.file))) {
+        icons.push({
+          src: `/${candidate.file}`,
+          sizes: candidate.sizes,
+          type: candidate.type,
+        });
+      }
+    }
+
+    return icons;
+  }
+}

package/src/cli/platform/adapters/CloudflareAdapter.ts

@@ -48,6 +48,17 @@ export class CloudflareAdapter extends PlatformAdapter {
     return !!dbUrl?.startsWith("postgres:");
   }
 
+  /**
+   * Propagate the environment's data-jurisdiction setting to the API client.
+   *
+   * Must be invoked at the top of every entry point (authenticate, build,
+   * deploy, secrets, provision, migrate, inspect, teardown) because
+   * CloudflareApi is a singleton reused across env invocations.
+   */
+  protected configureApi(ctx: PlatformContext): void {
+    this.api.setJurisdiction(ctx.envConfig.jurisdiction);
+  }
+
   protected async runShell(
     command: string,
     options: Parameters<ShellProvider["run"]>[1] = {},
@@ -70,6 +81,7 @@ export class CloudflareAdapter extends PlatformAdapter {
   // -------------------------------------------------------------------------
 
   async authenticate(ctx: PlatformContext, run: RunnerMethod): Promise<void> {
+    this.configureApi(ctx);
     await run({
       name: "authenticate",
       handler: async () => {
@@ -112,6 +124,7 @@ export class CloudflareAdapter extends PlatformAdapter {
   // -------------------------------------------------------------------------
 
   async build(ctx: AppContext, run: RunnerMethod): Promise<void> {
+    this.configureApi(ctx);
     const appDir = ctx.app.path
       ? this.fs.join(ctx.root, ctx.app.path)
       : ctx.root;
@@ -159,6 +172,10 @@ export class CloudflareAdapter extends PlatformAdapter {
       env.CLOUDFLARE_DOMAIN = ctx.envConfig.domain;
     }
 
+    if (ctx.envConfig.jurisdiction) {
+      env.CLOUDFLARE_JURISDICTION = ctx.envConfig.jurisdiction;
+    }
+
     await run({
       name: "alepha build -t cloudflare",
       handler: async () => {
@@ -178,6 +195,7 @@ export class CloudflareAdapter extends PlatformAdapter {
     ctx: AppContext,
     run: RunnerMethod,
   ): Promise<string | undefined> {
+    this.configureApi(ctx);
     const workerName = ctx.naming.worker(
       ctx.apps.length > 1 ? ctx.app.name : undefined,
     );
@@ -212,6 +230,7 @@ export class CloudflareAdapter extends PlatformAdapter {
     "DATABASE_URL",
     "R2_BUCKET_NAME",
     "CLOUDFLARE_DOMAIN",
+    "CLOUDFLARE_JURISDICTION",
     "HYPERDRIVE_ID",
     "POSTGRES_SCHEMA",
     "NODE_ENV",
@@ -221,6 +240,7 @@ export class CloudflareAdapter extends PlatformAdapter {
     ctx: PlatformContext,
     run: RunnerMethod,
   ): Promise<void> {
+    this.configureApi(ctx);
     const envVars = await this.envUtils.parseEnv(ctx.root, [`.env.${ctx.env}`]);
 
     // Filter out binding/build vars, VITE_* vars, and empty values
@@ -265,6 +285,7 @@ export class CloudflareAdapter extends PlatformAdapter {
     ctx: PlatformContext,
     run: RunnerMethod,
   ): Promise<void> {
+    this.configureApi(ctx);
     const needsDB = ctx.apps.some((a) => a.resources.hasDatabase);
     const needsBucket = ctx.apps.some((a) => a.resources.hasBucket);
     const postgres = needsDB && (await this.isPostgres(ctx));
@@ -345,6 +366,7 @@ export class CloudflareAdapter extends PlatformAdapter {
     ctx: PlatformContext,
     run: RunnerMethod,
   ): Promise<void> {
+    this.configureApi(ctx);
     const needsDB = ctx.apps.some((a) => a.resources.hasDatabase);
     if (!needsDB) {
       return;
@@ -431,6 +453,7 @@ export class CloudflareAdapter extends PlatformAdapter {
     ctx: PlatformContext,
     run: RunnerMethod,
   ): Promise<PlatformState> {
+    this.configureApi(ctx);
     const state: PlatformState = {
       workers: [],
       databases: [],
@@ -610,6 +633,7 @@ export class CloudflareAdapter extends PlatformAdapter {
   // -------------------------------------------------------------------------
 
   async teardown(ctx: PlatformContext, run: RunnerMethod): Promise<void> {
+    this.configureApi(ctx);
     // 1. Remove queue consumers (must happen before worker or queue deletion)
     for (const app of ctx.apps) {
       if (app.resources.hasQueue) {

package/src/cli/platform/atoms/platformOptions.ts

@@ -53,11 +53,27 @@ export const platformOptions = $atom({
        * Named environments with their adapter and configuration.
        */
       environments: t.record(
-        t.text(),
+        t.text({
+          description:
+            "Environment name (e.g. 'production', 'staging', 'preview'). Used in resource naming and selected via --env.",
+        }),
         t.object({
           adapter: t.enum(["cloudflare", "vercel"]),
+          /**
+           * Custom domain for the deployed worker (e.g. "api.example.com").
+           *
+           * On Cloudflare this is attached as a custom-domain route.
+           * Omit to use the adapter's default `*.workers.dev` / preview URL.
+           */
           domain: t.optional(t.text()),
-          domains: t.optional(t.record(t.text(), t.text())),
+          /**
+           * Cloudflare data jurisdiction for R2 buckets and D1 databases.
+           * - "eu": data stays within the EU
+           * - "fedramp": FedRAMP-authorized regions
+           *
+           * Omit for the default (global) jurisdiction.
+           */
+          jurisdiction: t.optional(t.enum(["eu", "fedramp"])),
         }),
       ),
     }),
@@ -75,6 +91,6 @@ export type PlatformOptions = Static<typeof platformOptions.schema>;
 export interface EnvironmentConfig {
   adapter: "cloudflare" | "vercel";
   domain?: string;
-  domains?: Record<string, string>;
   vars?: Record<string, string>;
+  jurisdiction?: "eu" | "fedramp";
 }

package/src/cli/platform/hooks/PlatformHook.ts

@@ -0,0 +1,51 @@
+import type { RunnerMethod } from "alepha/command";
+import type { PlatformContext } from "../adapters/PlatformAdapter.ts";
+
+/**
+ * Context passed to platform hooks.
+ *
+ * Extends PlatformContext with the fully-qualified base URL of the
+ * deployed app (derived from `envConfig.domain` or the adapter's deploy
+ * URL) and the active RunnerMethod.
+ */
+export interface PlatformHookContext extends PlatformContext {
+  /**
+   * Fully-qualified base URL of the deployed app, e.g. "https://foo.com".
+   */
+  baseUrl: string;
+  run: RunnerMethod;
+}
+
+/**
+ * Third-party provisioning hook for `alepha platform up` / `down`.
+ *
+ * Plugins can extend this to register resources in external services
+ * (Stripe webhooks, Sentry projects, Resend domains, etc.) tied to a
+ * deployment. Hooks are discovered via `alepha.services(PlatformHook)`,
+ * so adding a plugin to `services: [...]` in `alepha.config.ts` is all
+ * it takes to wire one in.
+ *
+ * Lifecycle:
+ * - `register` runs after `deploy` and before `adapter.secrets()` so
+ *   any secret a hook writes to `.env.<env>` is picked up in the same
+ *   `up` cycle.
+ * - `unregister` runs on `down` before `adapter.teardown()`.
+ *
+ * Implementations MUST be idempotent: `register` is called on every `up`.
+ */
+export abstract class PlatformHook {
+  /**
+   * Stable identifier. Used for log output.
+   */
+  abstract readonly name: string;
+
+  /**
+   * Create or update external resources. Must tolerate pre-existing state.
+   */
+  abstract register(ctx: PlatformHookContext): Promise<void>;
+
+  /**
+   * Remove external resources. Must tolerate missing state.
+   */
+  abstract unregister(ctx: PlatformHookContext): Promise<void>;
+}

package/src/cli/platform/index.ts

@@ -101,6 +101,7 @@ export * from "./adapters/VercelAdapter.ts";
 export * from "./atoms/platformOptions.ts";
 export * from "./commands/platform.ts";
 export * from "./commands/SecretsCommand.ts";
+export * from "./hooks/PlatformHook.ts";
 export * from "./providers/GitHubSecretStore.ts";
 export * from "./providers/MemorySecretStore.ts";
 export * from "./providers/PlatformCacheProvider.ts";

package/src/cli/platform/services/CloudflareApi.ts

@@ -67,6 +67,19 @@ export class CloudflareApi {
 
   protected token?: string;
   protected accountId?: string;
+  protected jurisdiction?: "eu" | "fedramp";
+
+  /**
+   * Set the Cloudflare data jurisdiction for R2 and D1 resources.
+   *
+   * R2 buckets and D1 databases created under a jurisdiction live in a
+   * separate namespace — every R2 API call (list/create/delete) must include
+   * the `cf-r2-jurisdiction` header, and D1 create must include the field
+   * in the request body. Omit / pass `undefined` for the default (global).
+   */
+  public setJurisdiction(jurisdiction?: "eu" | "fedramp"): void {
+    this.jurisdiction = jurisdiction;
+  }
 
   // -------------------------------------------------------------------------
   // Auth
@@ -127,7 +140,11 @@ export class CloudflareApi {
       `/accounts/${accountId}/d1/database`,
       {
         method: "POST",
-        body: { name, primary_location_hint: location },
+        body: {
+          name,
+          primary_location_hint: location,
+          ...(this.jurisdiction ? { jurisdiction: this.jurisdiction } : {}),
+        },
         bodySchema: createD1BodySchema,
         schema: cloudflareD1Schema,
       },
@@ -392,6 +409,10 @@ export class CloudflareApi {
       Authorization: `Bearer ${token}`,
     };
 
+    if (this.jurisdiction && /\/r2\//.test(path)) {
+      headers["cf-r2-jurisdiction"] = this.jurisdiction;
+    }
+
     const init: RequestInit = { method, headers };
 
     if (body) {