alepha 0.23.0 → 0.24.0

package/src/crypto/providers/SecretProvider.ts

@@ -1,10 +1,10 @@
-import { $env, $hook, $inject, Alepha, t } from "alepha";
+import { $env, $hook, $inject, Alepha, AlephaError, z } from "alepha";
 import { $logger } from "alepha/logger";
 
 export const DEFAULT_SECRET_KEY_VALUE = "change-me-in-production";
 
-export const alephaSecretEnvSchema = t.object({
-  APP_SECRET: t.text({
+export const alephaSecretEnvSchema = z.object({
+  APP_SECRET: z.text({
     default: DEFAULT_SECRET_KEY_VALUE,
     description:
       "The secret key used for signing JWTs, encrypting cookies, and other security features.",
@@ -23,14 +23,20 @@ export class SecretProvider {
   protected readonly configure = $hook({
     on: "configure",
     handler: async () => {
-      // It's not ideal from a security pov but it's the best for convenience,
-      // it can be changed to a hard error in a future release.
-      if (
-        this.secretKey === DEFAULT_SECRET_KEY_VALUE &&
-        this.alepha.isProduction()
-      ) {
+      if (this.secretKey === DEFAULT_SECRET_KEY_VALUE) {
+        // In production the default secret is a full token-forgery bypass:
+        // JWTs would be signed with a public, well-known constant. Fail closed.
+        if (this.alepha.isProduction()) {
+          throw new AlephaError(
+            "APP_SECRET is unset in production (using the built-in default). " +
+              "Set a strong, unique APP_SECRET environment variable — the default " +
+              "is public and lets anyone forge authentication tokens.",
+          );
+        }
+        // Outside production, keep the convenience default but make the risk loud.
         this.log.warn(
-          "Using default secret key. Please set a secure APP_SECRET environment variable.",
+          "Using the default APP_SECRET. This is fine for local development but " +
+            "MUST be set to a strong, unique value before deploying to production.",
         );
       }
     },

package/src/datetime/primitives/$throttle.ts

@@ -20,7 +20,12 @@ export interface ThrottleOptions {
  * Middleware that rate-controls handler execution using a token bucket.
  *
  * Excess calls are **delayed** until capacity is available — never rejected.
- * Process-local (not distributed). Use `$rateLimit` for distributed rate limiting.
+ * Process-local (not distributed) — it cannot rate-limit across instances.
+ *
+ * **Limitation**: the token refill is time-based and re-checked only when a
+ * waiter wakes, so a burst of *concurrent* calls can wake in the same window
+ * and briefly exceed `rate`. Treat it as traffic smoothing, not a hard cap —
+ * do not rely on it to enforce a strict quota.
  *
  * **Use case**: protect an external API from your own traffic.
  *

package/src/email/brevo/providers/BrevoEmailProvider.ts

@@ -1,4 +1,4 @@
-import { $env, t } from "alepha";
+import { $env, z } from "alepha";
 import {
   EmailError,
   type EmailProvider,
@@ -9,11 +9,11 @@ import { $logger } from "alepha/logger";
 /**
  * Environment variables for Brevo configuration.
  */
-const envSchema = t.object({
-  BREVO_API_KEY: t.text({
+const envSchema = z.object({
+  BREVO_API_KEY: z.text({
     description: "Brevo API key for transactional email",
   }),
-  EMAIL_FROM: t.text({
+  EMAIL_FROM: z.text({
     description: "Default sender email address",
   }),
 });

package/src/email/cloudflare/providers/CloudflareEmailProvider.ts

@@ -1,4 +1,4 @@
-import { $env, $hook, $inject, Alepha, AlephaError, t } from "alepha";
+import { $env, $hook, $inject, Alepha, AlephaError, z } from "alepha";
 import {
   EmailError,
   type EmailProvider,
@@ -23,13 +23,13 @@ export const SEND_EMAIL_DEFAULT_BINDING = "SEND_EMAIL";
  * set it. `send()` re-checks at call time and throws a clear error if
  * it's missing then.
  */
-const envSchema = t.object({
-  EMAIL_FROM: t.optional(
-    t.text({
+const envSchema = z.object({
+  EMAIL_FROM: z
+    .text({
       description:
         "Default sender (a verified sender address). Accepts a bare address or an RFC 5322 display-name form, e.g. `Lore <noreply@lore.alepha.dev>`.",
-    }),
-  ),
+    })
+    .optional(),
 });
 
 /**

package/src/email/core/index.ts

@@ -30,14 +30,19 @@ declare module "alepha" {
 }
 
 /**
- * Email delivery with template support.
+ * Email delivery over pluggable providers.
  *
  * **Features:**
- * - Send emails with templates
+ * - `$email` declares a named send channel; the name is surfaced to the
+ *   `email:sending` / `email:sent` hooks (as their `template` field) for
+ *   auditing and interception
  * - Multiple recipients
  * - Local file provider for development
  * - Memory provider for testing
  *
+ * There is **no template rendering**: `send()` takes an already-rendered
+ * `subject` and `body` — bring your own templating if you need it.
+ *
  * For SMTP support, use `AlephaEmailSmtp` from `alepha/email/smtp`.
  * For Brevo support, use `AlephaEmailBrevo` from `alepha/email/brevo`.
  *

package/src/email/core/primitives/$email.ts

@@ -26,10 +26,14 @@ export interface EmailPrimitiveOptions {
 /**
  * Email primitive for sending emails through various providers.
  *
+ * The primitive's `name` identifies the channel in the `email:sending` /
+ * `email:sent` hooks; it does not select a template — `send()` expects an
+ * already-rendered `subject` and `body`.
+ *
  * Usage:
  * ```typescript
  * class MyService {
- *   private readonly welcomeEmail = $email({ name: "welcome" });
+ *   protected readonly welcomeEmail = $email({ name: "welcome" });
  *
  *   async sendWelcome(userEmail: string, userName: string) {
  *     await this.welcomeEmail.send({

package/src/email/core/providers/LocalEmailProvider.ts

@@ -1,4 +1,4 @@
-import { $atom, $hook, $inject, $state, type Static, t } from "alepha";
+import { $atom, $hook, $inject, $state, type Static, z } from "alepha";
 import { $logger } from "alepha/logger";
 import { FileSystemProvider } from "alepha/system";
 import { EmailError } from "../errors/EmailError.ts";
@@ -11,10 +11,10 @@ import type { EmailProvider, EmailSendOptions } from "./EmailProvider.ts";
  */
 export const localEmailOptions = $atom({
   name: "alepha.email.local.options",
-  schema: t.object({
-    directory: t.string({
-      description: "Directory path where email files will be stored",
-    }),
+  schema: z.object({
+    directory: z
+      .string()
+      .describe("Directory path where email files will be stored"),
   }),
   default: {
     directory: "node_modules/.alepha/emails",

package/src/email/smtp/providers/NodemailerEmailProvider.ts

@@ -1,4 +1,4 @@
-import { $atom, $env, $hook, $state, type Static, t } from "alepha";
+import { $atom, $env, $hook, $state, type Static, z } from "alepha";
 import {
   EmailError,
   type EmailProvider,
@@ -13,35 +13,32 @@ import nodemailer from "nodemailer";
 /**
  * Environment variables for nodemailer configuration
  */
-const envSchema = t.object({
-  EMAIL_HOST: t.optional(
-    t.text({
+const envSchema = z.object({
+  EMAIL_HOST: z
+    .text({
       description: "SMTP server host",
-    }),
-  ),
-  EMAIL_PORT: t.number({
-    default: 587,
-    description: "SMTP server port",
-  }),
-  EMAIL_USER: t.optional(
-    t.text({
+    })
+    .optional(),
+  EMAIL_PORT: z.number().describe("SMTP server port").default(587),
+  EMAIL_USER: z
+    .text({
       description: "SMTP authentication username",
-    }),
-  ),
-  EMAIL_PASS: t.optional(
-    t.text({
+    })
+    .optional(),
+  EMAIL_PASS: z
+    .text({
       description: "SMTP authentication password",
-    }),
-  ),
-  EMAIL_FROM: t.optional(
-    t.text({
+    })
+    .optional(),
+  EMAIL_FROM: z
+    .text({
       description: "Default from email address",
-    }),
-  ),
-  EMAIL_SECURE: t.boolean({
-    default: false,
-    description: "Use secure connection (TLS)",
-  }),
+    })
+    .optional(),
+  EMAIL_SECURE: z
+    .boolean()
+    .describe("Use secure connection (TLS)")
+    .default(false),
 });
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -51,32 +48,24 @@ const envSchema = t.object({
  */
 export const nodemailerEmailOptions = $atom({
   name: "alepha.email.nodemailer.options",
-  schema: t.object({
-    pool: t.optional(
-      t.boolean({
-        description: "Enable connection pooling",
-      }),
-    ),
-    maxConnections: t.optional(
-      t.number({
-        description: "Maximum number of connections in pool",
-      }),
-    ),
-    maxMessages: t.optional(
-      t.number({
-        description: "Maximum messages per connection",
-      }),
-    ),
-    rateDelta: t.optional(
-      t.number({
-        description: "Time in milliseconds between message sends",
-      }),
-    ),
-    rateLimit: t.optional(
-      t.number({
-        description: "Maximum number of messages per rateDelta",
-      }),
-    ),
+  schema: z.object({
+    pool: z.boolean().describe("Enable connection pooling").optional(),
+    maxConnections: z
+      .number()
+      .describe("Maximum number of connections in pool")
+      .optional(),
+    maxMessages: z
+      .number()
+      .describe("Maximum messages per connection")
+      .optional(),
+    rateDelta: z
+      .number()
+      .describe("Time in milliseconds between message sends")
+      .optional(),
+    rateLimit: z
+      .number()
+      .describe("Maximum number of messages per rateDelta")
+      .optional(),
   }),
   default: {},
 });