@pramen/server 0.0.12 → 0.0.13

package/dist/index.d.ts

@@ -3,8 +3,8 @@ 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";

package/dist/index.js

@@ -11,7 +11,7 @@ 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";

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,9 +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) {
@@ -33,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) {

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

@@ -56,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>;
@@ -66,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.12",
+  "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/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";

package/src/runtime/dispatch.ts

@@ -10,7 +10,7 @@
 
 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";
@@ -18,7 +18,7 @@ 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;
@@ -60,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) {

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

@@ -62,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.
@@ -74,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
@@ -88,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/