alepha 0.19.3 → 0.19.5

package/src/captcha/providers/CaptchaProvider.ts

@@ -0,0 +1,17 @@
+/**
+ * Captcha verification provider interface.
+ *
+ * Verifies that a user-submitted captcha token is valid. Implementations
+ * call the relevant captcha service (Turnstile, reCAPTCHA, hCaptcha, etc.)
+ * to validate the token server-side.
+ */
+export abstract class CaptchaProvider {
+  /**
+   * Verify a captcha token.
+   *
+   * @param token - The captcha response token submitted by the client.
+   * @param ip - Optional client IP address for additional validation.
+   * @returns Whether the token is valid.
+   */
+  public abstract verify(token: string, ip?: string): Promise<boolean>;
+}

package/src/captcha/providers/MemoryCaptchaProvider.ts

@@ -0,0 +1,65 @@
+import { $logger } from "alepha/logger";
+import type { CaptchaProvider } from "./CaptchaProvider.ts";
+
+export interface CaptchaRecord {
+  token: string;
+  ip?: string;
+  verifiedAt: Date;
+}
+
+/**
+ * In-memory captcha provider for testing.
+ *
+ * Accepts all tokens by default. Use `reject()` to make verification fail,
+ * and `accept()` to restore. All verification attempts are recorded for assertions.
+ */
+export class MemoryCaptchaProvider implements CaptchaProvider {
+  protected readonly log = $logger();
+
+  /**
+   * All verification attempts.
+   */
+  public records: CaptchaRecord[] = [];
+
+  protected shouldAccept = true;
+
+  public async verify(token: string, ip?: string): Promise<boolean> {
+    this.log.debug("Verifying captcha in memory store", { token, ip });
+
+    this.records.push({
+      token,
+      ip,
+      verifiedAt: new Date(),
+    });
+
+    return this.shouldAccept;
+  }
+
+  /**
+   * Make all subsequent verifications fail.
+   */
+  public reject(): void {
+    this.shouldAccept = false;
+  }
+
+  /**
+   * Make all subsequent verifications pass (default behavior).
+   */
+  public accept(): void {
+    this.shouldAccept = true;
+  }
+
+  /**
+   * Whether a token was verified.
+   */
+  public wasVerified(token: string): boolean {
+    return this.records.some((r) => r.token === token);
+  }
+
+  /**
+   * Get the last verification attempt.
+   */
+  public get last(): CaptchaRecord | undefined {
+    return this.records[this.records.length - 1];
+  }
+}

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/core/templates/webAppRouterTs.ts

@@ -24,23 +24,8 @@ export const webAppRouterTs = (options: {
     imports.push(
       'import { AdminSessionRouter } from "@alepha/ui/admin-sessions";',
     );
-    imports.push('import { AdminAuditRouter } from "@alepha/ui/admin-audits";');
-    imports.push('import { AdminFileRouter } from "@alepha/ui/admin-files";');
-    imports.push(
-      'import { AdminParameterRouter } from "@alepha/ui/admin-parameters";',
-    );
-    imports.push('import { AdminJobRouter } from "@alepha/ui/admin-jobs";');
-    imports.push('import { AdminApiKeyRouter } from "@alepha/ui/admin-keys";');
-    imports.push(
-      'import { AdminNotificationRouter } from "@alepha/ui/admin-notifications";',
-    );
-    imports.push(
-      'import { AdminBillingRouter } from "@alepha/ui/admin-billing";',
-    );
     imports.push('import { $inject } from "alepha";');
-    imports.push(
-      'import { IconLayoutDashboard, IconLockPassword, IconCreditCard } from "@tabler/icons-react";',
-    );
+    imports.push('import { IconLayoutDashboard } from "@tabler/icons-react";');
   }
 
   // Page import
@@ -67,61 +52,23 @@ export const webAppRouterTs = (options: {
       classMembers.push(`  // ── Admin Domain Routers ──────────────────────────
   protected users = $inject(AdminUserRouter);
   protected sessions = $inject(AdminSessionRouter);
-  protected audits = $inject(AdminAuditRouter);
-  protected files = $inject(AdminFileRouter);
-  protected parameters = $inject(AdminParameterRouter);
-  protected jobs = $inject(AdminJobRouter);
-  protected apiKeys = $inject(AdminApiKeyRouter);
-  protected notifications = $inject(AdminNotificationRouter);
-  protected billing = $inject(AdminBillingRouter);
 
   // ── Admin Panel ─────────────────────────────────
   admin = $uiAdmin({
     pages: [
       this.users.adminUsers,
+      this.users.adminUserLayout,
       this.sessions.adminSessions,
-      this.audits.adminAudits,
-      this.files.adminFiles,
-      this.parameters.adminParameters,
-      this.jobs.adminJobs,
-      this.apiKeys.adminApiKeys,
-      this.notifications.adminNotifications,
-      this.billing.adminBilling,
     ],
     sidebarItems: [
-      {
-        label: "Security",
-        children: [
-          { label: "Identity", icon: IconLockPassword, children: [
-            this.users.adminUsers,
-            this.sessions.adminSessions,
-            this.apiKeys.adminApiKeys,
-          ]},
-          this.audits.adminAudits,
-        ],
-      },
-      {
-        label: "System",
-        children: [
-          this.files.adminFiles,
-          this.jobs.adminJobs,
-          this.notifications.adminNotifications,
-          this.parameters.adminParameters,
-        ],
-      },
-      {
-        label: "Commerce",
-        icon: IconCreditCard,
-        children: [
-          this.billing.adminBilling,
-        ],
-      },
+      this.users.adminUsers,
+      this.sessions.adminSessions,
     ],
   });
 
   // ── Admin Dashboard ─────────────────────────────
   adminDashboard = $page({
-    parent: this.admin.adminLayout,
+    parent: this.admin,
     path: "/",
     label: "Dashboard",
     icon: IconLayoutDashboard,

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";
 }