@pramen/server 0.0.11 → 0.0.13

package/dist/durable-object.js

@@ -17,6 +17,7 @@
 import { DurableObject } from "cloudflare:workers";
 import { migrate } from "./runtime/migrate";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
+import { createMail } from "./runtime/mail";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { Db } from "./runtime/db";
 import { digest } from "./runtime/digest";
@@ -154,7 +155,15 @@ export class PramenDOBase extends DurableObject {
     taskCtx() {
         const identity = { roles: ["admin"] };
         const db = new Db(this.driver, { acl: this.acl, identity, system: true, schema: this.app.schema, partition: this.partition, suppressTriggers: true }, this.app.schema);
-        return { db, kv: this.kv, files: this.filesFor(this.tenant), env: this.envBag, identity, tasks: tasksFacade(this.driver) };
+        return {
+            db,
+            kv: this.kv,
+            files: this.filesFor(this.tenant),
+            env: this.envBag,
+            identity,
+            tasks: tasksFacade(this.driver),
+            mail: createMail(this.envBag, this.kv),
+        };
     }
     /** Restore (tenant, partition) on a cold wake (e.g. an alarm with no request) so the
      * task context is scoped correctly. No-op once loaded/persisted this instance. */

package/dist/index.d.ts

@@ -3,14 +3,16 @@ export type { TriggerDef, TriggerOp } from "./sdk/schema";
 export { isValidUuid } from "./sdk/uuid";
 export type { DefaultValue, FieldType, FieldDef, EntityFields, EntityDef, SchemaDef, RelationDef, RelationDefs, BelongsToDef, HasManyDef, } from "./sdk/schema";
 export { createApp } from "./sdk/app";
-export { query, mutation } from "./sdk/handlers";
-export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, Tasks, TaskHandler, AppTaskMap } from "./sdk/handlers";
+export { query, mutation, authorizeHandler } from "./sdk/handlers";
+export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap } from "./sdk/handlers";
 export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
 export type { Action, Identity, IdentityMarker, InputMarker, Policy, PolicyRule, PolicyRules, Role, Validator, WhereRule, ConditionalFields, FieldsFn, RelationAclRule, SetValue, ResolverFn, ResolverContext, ResolverDb, } from "./sdk/acl";
 export type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, JsonValue, ProjectedRow, RelationsOf, RelationsResult, WhereClause, WhereInput, WhereOps, } from "./sdk/infer";
 export type { FileRef, Files, SignUploadOpts, SignDownloadOpts, HeadResult } from "./sdk/files";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
+export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 export { sqliteDialect, postgresDialect, DoSqliteDriver, D1Driver } from "./runtime/driver";
 export type { Driver, Dialect, Row } from "./runtime/driver";

package/dist/index.js

@@ -11,10 +11,12 @@ export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, de
 export { isValidUuid } from "./sdk/uuid";
 // --- app + handlers ---
 export { createApp } from "./sdk/app";
-export { query, mutation } from "./sdk/handlers";
+export { query, mutation, authorizeHandler } from "./sdk/handlers";
 // --- ACL ---
 export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
+// --- mail (ctx.mail) ---
+export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 // --- errors ---
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 // --- substrate seam (advanced: bring your own SQL backend) ---

package/dist/runtime/dispatch.d.ts

@@ -4,7 +4,7 @@ import type { Driver } from "./driver";
 import type { Kv } from "./kv";
 import type { Files } from "../sdk/files";
 import type { SchemaDef } from "../sdk/schema";
-import type { AppTaskMap, HandlerContext, HandlerKind, HandlerMap, Tasks } from "../sdk/handlers";
+import { type AppTaskMap, type HandlerContext, type HandlerKind, type HandlerMap, type Tasks } from "../sdk/handlers";
 export interface DispatchResult {
     readonly result: unknown;
     readonly kind: HandlerKind;

package/dist/runtime/dispatch.js

@@ -9,8 +9,10 @@
 // layer can match a mutation's writes against each subscription's reads.
 import { Db } from "./db";
 import { warmup } from "./acl";
-import { BadRequest } from "./errors";
+import { BadRequest, Forbidden } from "./errors";
 import { enqueueTask } from "./outbox";
+import { createMail } from "./mail";
+import { authorizeHandler } from "../sdk/handlers";
 /** The `ctx.tasks` facade over the outbox. `onEnqueue` lets the caller count enqueues
  * so it can wake the drainer. */
 export function tasksFacade(driver, onEnqueue) {
@@ -32,6 +34,11 @@ export async function dispatch(handlers, schema, driver, kv, files, env, acl, na
     const handler = handlers[name];
     if (!handler)
         throw new BadRequest(`unknown handler: ${name}`);
+    // Per-handler authorization, enforced before any work (input parse / handler body) —
+    // gates handlers that bypass the row-ACL by touching ctx.kv/ctx.env/ctx.mail directly.
+    if (handler.auth && !authorizeHandler(handler.auth, acl.identity)) {
+        throw new Forbidden(`not authorized to call '${name}'`);
+    }
     // Validate/parse the request input at the boundary, if the handler declares it.
     let parsed = input;
     if (handler.input) {
@@ -48,7 +55,15 @@ export async function dispatch(handlers, schema, driver, kv, files, env, acl, na
     const resolved = await warmup(acl.acl, acl.identity, systemDb);
     const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved, schema, partition: acl.partition }, schema);
     let enqueued = 0;
-    const ctx = { db, kv, files, env, identity: acl.identity, tasks: tasksFacade(driver, () => enqueued++) };
+    const ctx = {
+        db,
+        kv,
+        files,
+        env,
+        identity: acl.identity,
+        tasks: tasksFacade(driver, () => enqueued++),
+        mail: createMail(env, kv),
+    };
     const result = handler.kind === "query"
         ? await handler.run(ctx, parsed)
         : await driver.transaction(async () => handler.run(ctx, parsed));

package/dist/runtime/mail.d.ts

@@ -0,0 +1,80 @@
+import type { Kv } from "./kv";
+export interface MailAddress {
+    email: string;
+    name?: string;
+}
+export interface MailMessage {
+    to: string | string[];
+    /** Sender. Optional — defaults to MAIL_FROM (a verified address). */
+    from?: MailAddress;
+    subject: string;
+    text?: string;
+    html?: string;
+    replyTo?: string | MailAddress;
+}
+/** The transport seam. One per backend (Cloudflare Email Sending, a dev stash, …). */
+export interface MailAdapter {
+    /** Deliver a fully-resolved message (`from` already filled by the facade). */
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
+/** The `ctx.mail` facade: resolves the sender, validates, and delegates to the adapter. */
+export declare class Mail {
+    private readonly adapter;
+    private readonly defaultFrom?;
+    constructor(adapter: MailAdapter, defaultFrom?: MailAddress | undefined);
+    send(message: MailMessage): Promise<void>;
+}
+/** The Cloudflare `send_email` binding shape (workers binding form: `from` uses `email`). */
+export interface SendEmailBinding {
+    send(message: {
+        to: string | string[];
+        from: MailAddress;
+        subject: string;
+        text?: string;
+        html?: string;
+        replyTo?: string | MailAddress;
+    }): Promise<void>;
+}
+/** Cloudflare Email Sending — sends via the `send_email` binding (no API keys). The
+ * `from` domain must be onboarded (`wrangler email sending enable yourdomain.com`). */
+export declare class CloudflareEmailAdapter implements MailAdapter {
+    private readonly binding;
+    constructor(binding: SendEmailBinding);
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
+/** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
+ * (or a dashboard) can read the "inbox" instead of really sending. */
+export declare class KvMailAdapter implements MailAdapter {
+    private readonly kv;
+    constructor(kv: Kv);
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
+/** In-memory transport: captures sent messages (pure; for unit tests). */
+export declare class MemoryMailAdapter implements MailAdapter {
+    readonly sent: Array<MailMessage & {
+        from: MailAddress;
+    }>;
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
+/** Fail-closed transport: no real sender and no explicit dev-capture opt-in, so a
+ * `send` THROWS rather than silently capturing. Prevents a misconfigured production
+ * (no MAIL_FROM) from writing security emails — magic-link tokens, resets — into KV
+ * instead of delivering them. Mirrors how files fail closed without FILES_SECRET. */
+export declare class UnconfiguredMailAdapter implements MailAdapter {
+    send(): Promise<void>;
+}
+/** Build `ctx.mail` from the environment:
+ *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
+ *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
+ *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
+ *    stash security emails in KV). */
+export declare function createMail(env: Readonly<Record<string, unknown>>, kv?: Kv): Mail;

package/dist/runtime/mail.js

@@ -0,0 +1,102 @@
+// ctx.mail — transactional-ish email facade, the same shape as ctx.files: an adapter
+// seam (CloudflareEmailAdapter / KvMailAdapter / MemoryMailAdapter) behind a thin
+// `Mail` facade, chosen from the environment. Handlers send mail without touching the
+// `send_email` binding directly:
+//
+//   await ctx.mail.send({ to: "u@x.com", subject: "Welcome", text: "…" });
+//
+// On Cloudflare the transport is Cloudflare Email Sending (the `send_email`/`EMAIL`
+// binding, no API keys). With no verified sender configured (local/dev), mail is
+// captured instead of sent — to KV (so an e2e/dashboard can read the "inbox") or
+// in-memory — so handlers work unchanged off-platform.
+/** The `ctx.mail` facade: resolves the sender, validates, and delegates to the adapter. */
+export class Mail {
+    adapter;
+    defaultFrom;
+    constructor(adapter, defaultFrom) {
+        this.adapter = adapter;
+        this.defaultFrom = defaultFrom;
+    }
+    async send(message) {
+        const to = Array.isArray(message.to) ? message.to : [message.to];
+        if (to.length === 0 || to.some((a) => typeof a !== "string" || a.length === 0)) {
+            throw new Error("ctx.mail.send: `to` is required");
+        }
+        if (typeof message.subject !== "string" || message.subject.length === 0) {
+            throw new Error("ctx.mail.send: `subject` is required");
+        }
+        const from = message.from ?? this.defaultFrom;
+        if (!from)
+            throw new Error("ctx.mail.send: no sender — set the MAIL_FROM var or pass `from`");
+        await this.adapter.send({ ...message, from });
+    }
+}
+/** Cloudflare Email Sending — sends via the `send_email` binding (no API keys). The
+ * `from` domain must be onboarded (`wrangler email sending enable yourdomain.com`). */
+export class CloudflareEmailAdapter {
+    binding;
+    constructor(binding) {
+        this.binding = binding;
+    }
+    async send(message) {
+        await this.binding.send({
+            to: message.to,
+            from: message.from,
+            subject: message.subject,
+            text: message.text,
+            html: message.html,
+            replyTo: message.replyTo,
+        });
+    }
+}
+/** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
+ * (or a dashboard) can read the "inbox" instead of really sending. */
+export class KvMailAdapter {
+    kv;
+    constructor(kv) {
+        this.kv = kv;
+    }
+    async send(message) {
+        const to = Array.isArray(message.to) ? message.to : [message.to];
+        const value = JSON.stringify({ from: message.from, subject: message.subject, text: message.text, html: message.html });
+        for (const addr of to)
+            await this.kv.put(`mail:${addr}`, value, { expirationTtl: 900 });
+    }
+}
+/** In-memory transport: captures sent messages (pure; for unit tests). */
+export class MemoryMailAdapter {
+    sent = [];
+    async send(message) {
+        this.sent.push(message);
+    }
+}
+/** Fail-closed transport: no real sender and no explicit dev-capture opt-in, so a
+ * `send` THROWS rather than silently capturing. Prevents a misconfigured production
+ * (no MAIL_FROM) from writing security emails — magic-link tokens, resets — into KV
+ * instead of delivering them. Mirrors how files fail closed without FILES_SECRET. */
+export class UnconfiguredMailAdapter {
+    async send() {
+        throw new Error("ctx.mail: no transport configured — set MAIL_FROM (with the EMAIL binding) to send, " +
+            "or MAIL_CAPTURE=true to capture in dev.");
+    }
+}
+/** Build `ctx.mail` from the environment:
+ *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
+ *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
+ *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
+ *    stash security emails in KV). */
+export function createMail(env, kv) {
+    const binding = env.EMAIL;
+    const fromAddr = typeof env.MAIL_FROM === "string" && env.MAIL_FROM ? env.MAIL_FROM : undefined;
+    if (binding && fromAddr) {
+        const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
+        return new Mail(new CloudflareEmailAdapter(binding), { email: fromAddr, name });
+    }
+    if (env.MAIL_CAPTURE === "true") {
+        const devFrom = { email: "dev@pramen.local", name: "pramen (dev)" };
+        return new Mail(kv ? new KvMailAdapter(kv) : new MemoryMailAdapter(), devFrom);
+    }
+    // Sentinel `from` so the facade delegates to the adapter, which throws the clear error.
+    return new Mail(new UnconfiguredMailAdapter(), { email: "unconfigured@invalid" });
+}

package/dist/sdk/app.js

@@ -5,7 +5,7 @@
 //   const { query, mutation } = createApp(schema);
 //   const listNotes = query((ctx) => ctx.db.find({ from: "notes" })); // typed!
 export function createApp(schema) {
-    const query = (run, opts) => ({ kind: "query", run: run, input: opts?.input, partition: opts?.partition });
-    const mutation = (run, opts) => ({ kind: "mutation", run: run, input: opts?.input, partition: opts?.partition });
+    const query = (run, opts) => ({ kind: "query", run: run, input: opts?.input, partition: opts?.partition, auth: opts?.auth });
+    const mutation = (run, opts) => ({ kind: "mutation", run: run, input: opts?.input, partition: opts?.partition, auth: opts?.auth });
     return { schema, query, mutation };
 }

package/dist/sdk/handlers.d.ts

@@ -1,5 +1,6 @@
 import type { Db } from "../runtime/db";
 import type { Kv } from "../runtime/kv";
+import type { Mail } from "../runtime/mail";
 import type { Identity } from "./acl";
 import type { Files } from "./files";
 import type { SchemaDef } from "./schema";
@@ -12,6 +13,11 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
     /** Per-tenant file storage: mint signed upload/download urls, head/delete blobs.
      * Bytes flow through the Worker /files/* route, never through the DO. */
     readonly files: Files;
+    /** Send email: `ctx.mail.send({ to, subject, text/html })`. On Cloudflare this is
+     * Cloudflare Email Sending (the `send_email` binding); off-platform / unconfigured it
+     * captures instead of sending. Prefer enqueuing the send as a task (see `ctx.tasks`)
+     * so it runs off the single-writer write path. */
+    readonly mail: Mail;
     /** The Worker/DO environment — bindings (KV, R2, DB, …) plus vars and secrets
      * (AUTH_SECRET, plus anything in wrangler.jsonc / .dev.vars / `wrangler secret`).
      * Use it to call external services from handlers — Cloudflare bindings (e.g. the
@@ -50,6 +56,17 @@ export type TaskHandler = (ctx: HandlerContext, payload: unknown, meta: TaskMeta
 /** Map of `kind` → handler. Set as `app.tasks`; drained by the DO alarm / a Cron. */
 export type AppTaskMap = Record<string, TaskHandler>;
 export type HandlerKind = "query" | "mutation";
+/** Authorization required to CALL a handler, enforced BEFORE its body runs. This is
+ * distinct from the row-level ACL (which gates `ctx.db`): use it to gate handlers that
+ * touch `ctx.kv`/`ctx.env`/`ctx.mail`/`ctx.tasks` directly — those bypass the ACL, so an
+ * un-gated such handler is callable by anyone (incl. anonymous) on an open tenant. Forms:
+ *   - `"authenticated"` — any non-anonymous caller (identity != null)
+ *   - `string[]`        — the caller must hold one of these roles
+ *   - `(identity) => boolean` — a custom predicate
+ * Absent ⇒ open (the prior behavior; a `ctx.db` handler is still ACL-gated). */
+export type HandlerAuth = "authenticated" | readonly string[] | ((identity: Identity | null) => boolean);
+/** Evaluate a handler's `auth` requirement against the caller's identity. */
+export declare function authorizeHandler(auth: HandlerAuth, identity: Identity | null): boolean;
 export interface Handler<I = unknown, O = unknown> {
     readonly kind: HandlerKind;
     readonly run: (ctx: HandlerContext<any>, input: I) => O | Promise<O>;
@@ -60,11 +77,15 @@ export interface Handler<I = unknown, O = unknown> {
      * routes the request to the matching partition-DO before dispatch. Absent ⇒ the
      * default partition (routed to the bare tenant key). */
     readonly partition?: string;
+    /** Optional call-authorization, enforced before the handler runs (see HandlerAuth). */
+    readonly auth?: HandlerAuth;
 }
 export interface HandlerOpts<I> {
     input?: (raw: unknown) => I;
     /** DO partition this handler runs in. Absent ⇒ the default partition. */
     partition?: string;
+    /** Authorization to CALL this handler (see HandlerAuth) — gate non-`ctx.db` handlers. */
+    auth?: HandlerAuth;
 }
 export declare function query<I = unknown, O = unknown>(run: (ctx: HandlerContext, input: I) => O | Promise<O>, opts?: HandlerOpts<I>): Handler<I, O>;
 export declare function mutation<I = unknown, O = unknown>(run: (ctx: HandlerContext, input: I) => O | Promise<O>, opts?: HandlerOpts<I>): Handler<I, O>;

package/dist/sdk/handlers.js

@@ -1,11 +1,23 @@
 // Handler factories — `query()` and `mutation()`. A query reads; a mutation is
 // wrapped in BEGIN/COMMIT by the dispatcher and
 // rolls back on throw (see runtime/dispatch.ts).
+/** Evaluate a handler's `auth` requirement against the caller's identity. */
+export function authorizeHandler(auth, identity) {
+    if (auth === "authenticated")
+        return identity != null;
+    if (typeof auth === "function")
+        return auth(identity);
+    if (!identity)
+        return false; // a role list can never be satisfied by an anonymous caller
+    const roles = Array.isArray(identity.roles) ? identity.roles : [];
+    const held = identity.role ? [identity.role, ...roles] : roles;
+    return auth.some((r) => held.includes(r));
+}
 // Standalone (schema-agnostic) handler factories. Prefer createApp(schema) for a
 // typed ctx.db; these remain for untyped/ad-hoc use.
 export function query(run, opts) {
-    return { kind: "query", run, input: opts?.input, partition: opts?.partition };
+    return { kind: "query", run, input: opts?.input, partition: opts?.partition, auth: opts?.auth };
 }
 export function mutation(run, opts) {
-    return { kind: "mutation", run, input: opts?.input, partition: opts?.partition };
+    return { kind: "mutation", run, input: opts?.input, partition: opts?.partition, auth: opts?.auth };
 }

package/dist/worker.js

@@ -6,6 +6,7 @@
 import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity } from "./auth";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
+import { createMail } from "./runtime/mail";
 import { migrate } from "./runtime/migrate";
 import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
@@ -110,7 +111,8 @@ export function makeWorker(app) {
         const identity = { roles: ["admin"] };
         const files = createFiles({ tenant: "main", secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
         const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
-        return { db, kv: new Kv(env.KV), files, env: env, identity, tasks: tasksFacade(driver) };
+        const kv = new Kv(env.KV);
+        return { db, kv, files, env: env, identity, tasks: tasksFacade(driver), mail: createMail(env, kv) };
     };
     /** Drain the D1 outbox in the Worker (no DO/alarm on this path) — called by the
      * /admin/tasks/drain route with `x-pramen-store: d1`, and by `scheduled()` (Cron). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "pramen server runtime — schema, ACL, ORM, live queries, files, and the createPramen(app) factory for Cloudflare Workers + Durable Objects.",
   "license": "MIT",
   "repository": {

package/src/durable-object.ts

@@ -18,6 +18,7 @@
 import { DurableObject } from "cloudflare:workers";
 import { migrate } from "./runtime/migrate";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
+import { createMail } from "./runtime/mail";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { Db } from "./runtime/db";
 import { digest } from "./runtime/digest";
@@ -205,7 +206,15 @@ export class PramenDOBase extends DurableObject<DoEnv> {
       { acl: this.acl, identity, system: true, schema: this.app.schema, partition: this.partition, suppressTriggers: true },
       this.app.schema,
     );
-    return { db, kv: this.kv, files: this.filesFor(this.tenant), env: this.envBag, identity, tasks: tasksFacade(this.driver) };
+    return {
+      db,
+      kv: this.kv,
+      files: this.filesFor(this.tenant),
+      env: this.envBag,
+      identity,
+      tasks: tasksFacade(this.driver),
+      mail: createMail(this.envBag, this.kv),
+    };
   }
 
   /** Restore (tenant, partition) on a cold wake (e.g. an alarm with no request) so the

package/src/index.ts

@@ -26,8 +26,8 @@ export type {
 
 // --- app + handlers ---
 export { createApp } from "./sdk/app";
-export { query, mutation } from "./sdk/handlers";
-export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, Tasks, TaskHandler, AppTaskMap } from "./sdk/handlers";
+export { query, mutation, authorizeHandler } from "./sdk/handlers";
+export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap } from "./sdk/handlers";
 
 // --- ACL ---
 export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
@@ -72,6 +72,10 @@ export type { FileRef, Files, SignUploadOpts, SignDownloadOpts, HeadResult } fro
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
 
+// --- mail (ctx.mail) ---
+export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
+
 // --- errors ---
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 

package/src/runtime/dispatch.ts

@@ -10,14 +10,15 @@
 
 import { Db } from "./db";
 import { warmup, type AclContext } from "./acl";
-import { BadRequest } from "./errors";
+import { BadRequest, Forbidden } from "./errors";
 import { enqueueTask, type TaskMap } from "./outbox";
+import { createMail } from "./mail";
 import type { Driver } from "./driver";
 import type { Kv } from "./kv";
 import type { Files } from "../sdk/files";
 import type { ResolverDb } from "../sdk/acl";
 import type { SchemaDef } from "../sdk/schema";
-import type { AppTaskMap, HandlerContext, HandlerKind, HandlerMap, Tasks } from "../sdk/handlers";
+import { authorizeHandler, type AppTaskMap, type HandlerContext, type HandlerKind, type HandlerMap, type Tasks } from "../sdk/handlers";
 
 export interface DispatchResult {
   readonly result: unknown;
@@ -59,6 +60,12 @@ export async function dispatch(
   const handler = handlers[name];
   if (!handler) throw new BadRequest(`unknown handler: ${name}`);
 
+  // Per-handler authorization, enforced before any work (input parse / handler body) —
+  // gates handlers that bypass the row-ACL by touching ctx.kv/ctx.env/ctx.mail directly.
+  if (handler.auth && !authorizeHandler(handler.auth, acl.identity)) {
+    throw new Forbidden(`not authorized to call '${name}'`);
+  }
+
   // Validate/parse the request input at the boundary, if the handler declares it.
   let parsed = input;
   if (handler.input) {
@@ -76,7 +83,15 @@ export async function dispatch(
 
   const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved, schema, partition: acl.partition }, schema);
   let enqueued = 0;
-  const ctx: HandlerContext = { db, kv, files, env, identity: acl.identity, tasks: tasksFacade(driver, () => enqueued++) };
+  const ctx: HandlerContext = {
+    db,
+    kv,
+    files,
+    env,
+    identity: acl.identity,
+    tasks: tasksFacade(driver, () => enqueued++),
+    mail: createMail(env, kv),
+  };
 
   const result =
     handler.kind === "query"

package/src/runtime/mail.ts

@@ -0,0 +1,136 @@
+// ctx.mail — transactional-ish email facade, the same shape as ctx.files: an adapter
+// seam (CloudflareEmailAdapter / KvMailAdapter / MemoryMailAdapter) behind a thin
+// `Mail` facade, chosen from the environment. Handlers send mail without touching the
+// `send_email` binding directly:
+//
+//   await ctx.mail.send({ to: "u@x.com", subject: "Welcome", text: "…" });
+//
+// On Cloudflare the transport is Cloudflare Email Sending (the `send_email`/`EMAIL`
+// binding, no API keys). With no verified sender configured (local/dev), mail is
+// captured instead of sent — to KV (so an e2e/dashboard can read the "inbox") or
+// in-memory — so handlers work unchanged off-platform.
+
+import type { Kv } from "./kv";
+
+export interface MailAddress {
+  email: string;
+  name?: string;
+}
+
+export interface MailMessage {
+  to: string | string[];
+  /** Sender. Optional — defaults to MAIL_FROM (a verified address). */
+  from?: MailAddress;
+  subject: string;
+  text?: string;
+  html?: string;
+  replyTo?: string | MailAddress;
+}
+
+/** The transport seam. One per backend (Cloudflare Email Sending, a dev stash, …). */
+export interface MailAdapter {
+  /** Deliver a fully-resolved message (`from` already filled by the facade). */
+  send(message: MailMessage & { from: MailAddress }): Promise<void>;
+}
+
+/** The `ctx.mail` facade: resolves the sender, validates, and delegates to the adapter. */
+export class Mail {
+  constructor(
+    private readonly adapter: MailAdapter,
+    private readonly defaultFrom?: MailAddress,
+  ) {}
+
+  async send(message: MailMessage): Promise<void> {
+    const to = Array.isArray(message.to) ? message.to : [message.to];
+    if (to.length === 0 || to.some((a) => typeof a !== "string" || a.length === 0)) {
+      throw new Error("ctx.mail.send: `to` is required");
+    }
+    if (typeof message.subject !== "string" || message.subject.length === 0) {
+      throw new Error("ctx.mail.send: `subject` is required");
+    }
+    const from = message.from ?? this.defaultFrom;
+    if (!from) throw new Error("ctx.mail.send: no sender — set the MAIL_FROM var or pass `from`");
+    await this.adapter.send({ ...message, from });
+  }
+}
+
+/** The Cloudflare `send_email` binding shape (workers binding form: `from` uses `email`). */
+export interface SendEmailBinding {
+  send(message: {
+    to: string | string[];
+    from: MailAddress;
+    subject: string;
+    text?: string;
+    html?: string;
+    replyTo?: string | MailAddress;
+  }): Promise<void>;
+}
+
+/** Cloudflare Email Sending — sends via the `send_email` binding (no API keys). The
+ * `from` domain must be onboarded (`wrangler email sending enable yourdomain.com`). */
+export class CloudflareEmailAdapter implements MailAdapter {
+  constructor(private readonly binding: SendEmailBinding) {}
+  async send(message: MailMessage & { from: MailAddress }): Promise<void> {
+    await this.binding.send({
+      to: message.to,
+      from: message.from,
+      subject: message.subject,
+      text: message.text,
+      html: message.html,
+      replyTo: message.replyTo,
+    });
+  }
+}
+
+/** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
+ * (or a dashboard) can read the "inbox" instead of really sending. */
+export class KvMailAdapter implements MailAdapter {
+  constructor(private readonly kv: Kv) {}
+  async send(message: MailMessage & { from: MailAddress }): Promise<void> {
+    const to = Array.isArray(message.to) ? message.to : [message.to];
+    const value = JSON.stringify({ from: message.from, subject: message.subject, text: message.text, html: message.html });
+    for (const addr of to) await this.kv.put(`mail:${addr}`, value, { expirationTtl: 900 });
+  }
+}
+
+/** In-memory transport: captures sent messages (pure; for unit tests). */
+export class MemoryMailAdapter implements MailAdapter {
+  readonly sent: Array<MailMessage & { from: MailAddress }> = [];
+  async send(message: MailMessage & { from: MailAddress }): Promise<void> {
+    this.sent.push(message);
+  }
+}
+
+/** Fail-closed transport: no real sender and no explicit dev-capture opt-in, so a
+ * `send` THROWS rather than silently capturing. Prevents a misconfigured production
+ * (no MAIL_FROM) from writing security emails — magic-link tokens, resets — into KV
+ * instead of delivering them. Mirrors how files fail closed without FILES_SECRET. */
+export class UnconfiguredMailAdapter implements MailAdapter {
+  async send(): Promise<void> {
+    throw new Error(
+      "ctx.mail: no transport configured — set MAIL_FROM (with the EMAIL binding) to send, " +
+        "or MAIL_CAPTURE=true to capture in dev.",
+    );
+  }
+}
+
+/** Build `ctx.mail` from the environment:
+ *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
+ *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
+ *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
+ *    stash security emails in KV). */
+export function createMail(env: Readonly<Record<string, unknown>>, kv?: Kv): Mail {
+  const binding = env.EMAIL as SendEmailBinding | undefined;
+  const fromAddr = typeof env.MAIL_FROM === "string" && env.MAIL_FROM ? env.MAIL_FROM : undefined;
+  if (binding && fromAddr) {
+    const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
+    return new Mail(new CloudflareEmailAdapter(binding), { email: fromAddr, name });
+  }
+  if (env.MAIL_CAPTURE === "true") {
+    const devFrom: MailAddress = { email: "dev@pramen.local", name: "pramen (dev)" };
+    return new Mail(kv ? new KvMailAdapter(kv) : new MemoryMailAdapter(), devFrom);
+  }
+  // Sentinel `from` so the facade delegates to the adapter, which throws the clear error.
+  return new Mail(new UnconfiguredMailAdapter(), { email: "unconfigured@invalid" });
+}

package/src/sdk/app.ts

@@ -14,12 +14,12 @@ export function createApp<S extends SchemaDef>(schema: S) {
   const query = <I = unknown, O = unknown>(
     run: (ctx: Ctx, input: I) => O | Promise<O>,
     opts?: HandlerOpts<I>,
-  ): Handler<I, O> => ({ kind: "query", run: run as Handler<I, O>["run"], input: opts?.input, partition: opts?.partition });
+  ): Handler<I, O> => ({ kind: "query", run: run as Handler<I, O>["run"], input: opts?.input, partition: opts?.partition, auth: opts?.auth });
 
   const mutation = <I = unknown, O = unknown>(
     run: (ctx: Ctx, input: I) => O | Promise<O>,
     opts?: HandlerOpts<I>,
-  ): Handler<I, O> => ({ kind: "mutation", run: run as Handler<I, O>["run"], input: opts?.input, partition: opts?.partition });
+  ): Handler<I, O> => ({ kind: "mutation", run: run as Handler<I, O>["run"], input: opts?.input, partition: opts?.partition, auth: opts?.auth });
 
   return { schema, query, mutation };
 }

package/src/sdk/handlers.ts

@@ -4,6 +4,7 @@
 
 import type { Db } from "../runtime/db";
 import type { Kv } from "../runtime/kv";
+import type { Mail } from "../runtime/mail";
 import type { Identity } from "./acl";
 import type { Files } from "./files";
 import type { SchemaDef } from "./schema";
@@ -17,6 +18,11 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
   /** Per-tenant file storage: mint signed upload/download urls, head/delete blobs.
    * Bytes flow through the Worker /files/* route, never through the DO. */
   readonly files: Files;
+  /** Send email: `ctx.mail.send({ to, subject, text/html })`. On Cloudflare this is
+   * Cloudflare Email Sending (the `send_email` binding); off-platform / unconfigured it
+   * captures instead of sending. Prefer enqueuing the send as a task (see `ctx.tasks`)
+   * so it runs off the single-writer write path. */
+  readonly mail: Mail;
   /** The Worker/DO environment — bindings (KV, R2, DB, …) plus vars and secrets
    * (AUTH_SECRET, plus anything in wrangler.jsonc / .dev.vars / `wrangler secret`).
    * Use it to call external services from handlers — Cloudflare bindings (e.g. the
@@ -56,6 +62,26 @@ export type AppTaskMap = Record<string, TaskHandler>;
 
 export type HandlerKind = "query" | "mutation";
 
+/** Authorization required to CALL a handler, enforced BEFORE its body runs. This is
+ * distinct from the row-level ACL (which gates `ctx.db`): use it to gate handlers that
+ * touch `ctx.kv`/`ctx.env`/`ctx.mail`/`ctx.tasks` directly — those bypass the ACL, so an
+ * un-gated such handler is callable by anyone (incl. anonymous) on an open tenant. Forms:
+ *   - `"authenticated"` — any non-anonymous caller (identity != null)
+ *   - `string[]`        — the caller must hold one of these roles
+ *   - `(identity) => boolean` — a custom predicate
+ * Absent ⇒ open (the prior behavior; a `ctx.db` handler is still ACL-gated). */
+export type HandlerAuth = "authenticated" | readonly string[] | ((identity: Identity | null) => boolean);
+
+/** Evaluate a handler's `auth` requirement against the caller's identity. */
+export function authorizeHandler(auth: HandlerAuth, identity: Identity | null): boolean {
+  if (auth === "authenticated") return identity != null;
+  if (typeof auth === "function") return auth(identity);
+  if (!identity) return false; // a role list can never be satisfied by an anonymous caller
+  const roles = Array.isArray(identity.roles) ? identity.roles : [];
+  const held = identity.role ? [identity.role, ...roles] : roles;
+  return auth.some((r) => held.includes(r));
+}
+
 export interface Handler<I = unknown, O = unknown> {
   readonly kind: HandlerKind;
   // Stored handlers are schema-agnostic; createApp() binds the typed surface.
@@ -68,12 +94,16 @@ export interface Handler<I = unknown, O = unknown> {
    * routes the request to the matching partition-DO before dispatch. Absent ⇒ the
    * default partition (routed to the bare tenant key). */
   readonly partition?: string;
+  /** Optional call-authorization, enforced before the handler runs (see HandlerAuth). */
+  readonly auth?: HandlerAuth;
 }
 
 export interface HandlerOpts<I> {
   input?: (raw: unknown) => I;
   /** DO partition this handler runs in. Absent ⇒ the default partition. */
   partition?: string;
+  /** Authorization to CALL this handler (see HandlerAuth) — gate non-`ctx.db` handlers. */
+  auth?: HandlerAuth;
 }
 
 // Standalone (schema-agnostic) handler factories. Prefer createApp(schema) for a
@@ -82,14 +112,14 @@ export function query<I = unknown, O = unknown>(
   run: (ctx: HandlerContext, input: I) => O | Promise<O>,
   opts?: HandlerOpts<I>,
 ): Handler<I, O> {
-  return { kind: "query", run, input: opts?.input, partition: opts?.partition };
+  return { kind: "query", run, input: opts?.input, partition: opts?.partition, auth: opts?.auth };
 }
 
 export function mutation<I = unknown, O = unknown>(
   run: (ctx: HandlerContext, input: I) => O | Promise<O>,
   opts?: HandlerOpts<I>,
 ): Handler<I, O> {
-  return { kind: "mutation", run, input: opts?.input, partition: opts?.partition };
+  return { kind: "mutation", run, input: opts?.input, partition: opts?.partition, auth: opts?.auth };
 }
 
 // Registry of handlers keyed by RPC name. Uses `any` for the per-handler input/

package/src/worker.ts

@@ -7,6 +7,7 @@
 import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity, type VerifyStrategy } from "./auth";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
+import { createMail } from "./runtime/mail";
 import { migrate } from "./runtime/migrate";
 import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
@@ -149,7 +150,8 @@ export function makeWorker(app: PramenApp) {
     const identity: Identity = { roles: ["admin"] };
     const files = createFiles({ tenant: "main", secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
     const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
-    return { db, kv: new Kv(env.KV), files, env: env as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver) };
+    const kv = new Kv(env.KV);
+    return { db, kv, files, env: env as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver), mail: createMail(env as unknown as Record<string, unknown>, kv) };
   };
 
   /** Drain the D1 outbox in the Worker (no DO/alarm on this path) — called by the