@pylonsync/functions 0.3.158 → 0.3.162

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.158",
+  "version": "0.3.162",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/define.ts

@@ -2,6 +2,23 @@
  * Function definition constructors.
  *
  * These are the primary API for defining server-side functions.
+ *
+ * Each constructor (query / mutation / action) has two overloads:
+ *
+ *   1. `auth` omitted, or `auth: "user" | "admin"` →  the framework
+ *      enforces a real signed-in user, so the handler's
+ *      `ctx.auth.userId` is narrowed from `string | null` to
+ *      `string`. The redundant `if (!ctx.auth.userId) throw …`
+ *      check disappears from app code.
+ *
+ *   2. `auth: "public" | "guest"` →  the function is reachable by
+ *      anonymous callers, so `ctx.auth.userId` stays `string | null`
+ *      and the handler must check it manually if relevant.
+ *
+ * The framework gate happens BEFORE the handler runs (in Rust,
+ * inside the router). A handler can't accidentally leak data by
+ * forgetting an auth check — when `auth: "user"` is in effect,
+ * an anonymous request never reaches the handler at all.
  */
 
 import type {
@@ -10,37 +27,80 @@ import type {
   MutationCtx,
   ActionCtx,
   Validator,
+  AuthMode,
 } from "./types";
 
-interface QueryDef<TArgs, TReturn> {
+/** Default auth mode applied when a definition omits `auth`. */
+const DEFAULT_AUTH: AuthMode = "user";
+
+interface CommonDef {
   args?: Record<string, Validator>;
-  handler: (ctx: QueryCtx, args: TArgs) => Promise<TReturn>;
   /**
-   * When true, the function is callable only via `ctx.runQuery()`
-   * from another function — never via the public `/api/fn/<name>`
-   * HTTP endpoint. The router refuses external calls with
-   * `404 FN_NOT_FOUND` so probing can't even confirm the name exists.
+   * When true, the function is callable only via `ctx.runQuery()` /
+   * `ctx.runMutation()` / `ctx.runAction()` from another function
+   * — never via the public `/api/fn/<name>` HTTP endpoint. The
+   * router refuses external calls with `404 FN_NOT_FOUND` so
+   * probing can't even confirm the name exists.
    *
-   * Use for queries that are meant as helpers for trusted action /
-   * mutation flows but would be unsafe if any caller could invoke
-   * them directly (e.g. they trust args without re-checking caller
-   * authority).
+   * Use for helper functions that are safe inside trusted
+   * wrappers but unsafe if any caller could invoke them directly
+   * (e.g. they trust args without re-checking caller authority).
+   *
+   * Internal functions inherit the wrapping handler's auth — the
+   * `auth` field has no effect when `internal: true`. The router
+   * isn't reachable anyway, and the caller has already passed its
+   * own gate.
    */
   internal?: boolean;
 }
 
-interface MutationDef<TArgs, TReturn> {
-  args?: Record<string, Validator>;
-  handler: (ctx: MutationCtx, args: TArgs) => Promise<TReturn>;
-  /** See QueryDef.internal — applies the same way to mutations. */
-  internal?: boolean;
+interface QueryDefRequired<TArgs, TReturn> extends CommonDef {
+  /** Defaults to `"user"`. See [`AuthMode`] for the full surface. */
+  auth?: "user" | "admin";
+  handler: (
+    ctx: QueryCtx<"required">,
+    args: TArgs,
+  ) => Promise<TReturn>;
 }
 
-interface ActionDef<TArgs, TReturn> {
-  args?: Record<string, Validator>;
-  handler: (ctx: ActionCtx, args: TArgs) => Promise<TReturn>;
-  /** See QueryDef.internal — applies the same way to actions. */
-  internal?: boolean;
+interface QueryDefOptional<TArgs, TReturn> extends CommonDef {
+  auth: "public" | "guest";
+  handler: (
+    ctx: QueryCtx<"optional">,
+    args: TArgs,
+  ) => Promise<TReturn>;
+}
+
+interface MutationDefRequired<TArgs, TReturn> extends CommonDef {
+  auth?: "user" | "admin";
+  handler: (
+    ctx: MutationCtx<"required">,
+    args: TArgs,
+  ) => Promise<TReturn>;
+}
+
+interface MutationDefOptional<TArgs, TReturn> extends CommonDef {
+  auth: "public" | "guest";
+  handler: (
+    ctx: MutationCtx<"optional">,
+    args: TArgs,
+  ) => Promise<TReturn>;
+}
+
+interface ActionDefRequired<TArgs, TReturn> extends CommonDef {
+  auth?: "user" | "admin";
+  handler: (
+    ctx: ActionCtx<"required">,
+    args: TArgs,
+  ) => Promise<TReturn>;
+}
+
+interface ActionDefOptional<TArgs, TReturn> extends CommonDef {
+  auth: "public" | "guest";
+  handler: (
+    ctx: ActionCtx<"optional">,
+    args: TArgs,
+  ) => Promise<TReturn>;
 }
 
 /**
@@ -52,24 +112,46 @@ interface ActionDef<TArgs, TReturn> {
  * @example
  * ```typescript
  * export default query({
+ *   // auth: "user" is the default — ctx.auth.userId is `string`,
+ *   // not `string | null`, inside the handler.
  *   args: { auctionId: v.string() },
  *   async handler(ctx, args) {
  *     return ctx.db.query("Lot", {
  *       auctionId: args.auctionId,
- *       $order: { closesAt: "asc" },
+ *       authorId: ctx.auth.userId,
  *     });
  *   },
  * });
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Explicitly public — landing-page count, never auth-shaped.
+ * export default query({
+ *   auth: "public",
+ *   async handler(ctx) {
+ *     return ctx.db.query("PublicPost", { published: true });
+ *   },
+ * });
+ * ```
  */
 export function query<TArgs = Record<string, unknown>, TReturn = unknown>(
-  def: QueryDef<TArgs, TReturn>
+  def: QueryDefRequired<TArgs, TReturn>,
+): FnDefinition<TArgs, TReturn>;
+export function query<TArgs = Record<string, unknown>, TReturn = unknown>(
+  def: QueryDefOptional<TArgs, TReturn>,
+): FnDefinition<TArgs, TReturn>;
+export function query<TArgs, TReturn>(
+  def:
+    | QueryDefRequired<TArgs, TReturn>
+    | QueryDefOptional<TArgs, TReturn>,
 ): FnDefinition<TArgs, TReturn> {
   return {
     type: "query",
     args: def.args,
-    handler: def.handler,
+    handler: def.handler as FnDefinition<TArgs, TReturn>["handler"],
     internal: def.internal,
+    auth: def.auth ?? DEFAULT_AUTH,
   };
 }
 
@@ -88,22 +170,37 @@ export function query<TArgs = Record<string, unknown>, TReturn = unknown>(
  * export default mutation({
  *   args: { lotId: v.string(), amount: v.number() },
  *   async handler(ctx, args) {
+ *     // ctx.auth.userId is `string` (not nullable) — the runtime
+ *     // already enforced `auth: "user"` (default) before reaching here.
  *     const lot = await ctx.db.get("Lot", args.lotId);
  *     if (!lot) throw ctx.error("NOT_FOUND", "Lot not found");
- *     await ctx.db.insert("Bid", { lotId: args.lotId, amount: args.amount });
+ *     await ctx.db.insert("Bid", {
+ *       lotId: args.lotId,
+ *       amount: args.amount,
+ *       bidderId: ctx.auth.userId,
+ *     });
  *     return { accepted: true };
  *   },
  * });
  * ```
  */
 export function mutation<TArgs = Record<string, unknown>, TReturn = unknown>(
-  def: MutationDef<TArgs, TReturn>
+  def: MutationDefRequired<TArgs, TReturn>,
+): FnDefinition<TArgs, TReturn>;
+export function mutation<TArgs = Record<string, unknown>, TReturn = unknown>(
+  def: MutationDefOptional<TArgs, TReturn>,
+): FnDefinition<TArgs, TReturn>;
+export function mutation<TArgs, TReturn>(
+  def:
+    | MutationDefRequired<TArgs, TReturn>
+    | MutationDefOptional<TArgs, TReturn>,
 ): FnDefinition<TArgs, TReturn> {
   return {
     type: "mutation",
     args: def.args,
-    handler: def.handler,
+    handler: def.handler as FnDefinition<TArgs, TReturn>["handler"],
     internal: def.internal,
+    auth: def.auth ?? DEFAULT_AUTH,
   };
 }
 
@@ -116,6 +213,13 @@ export function mutation<TArgs = Record<string, unknown>, TReturn = unknown>(
  *
  * Actions are NOT automatically retried because they may have side effects.
  *
+ * **Important:** policies don't gate actions — `auth: "user"` (the
+ * default) is the only thing protecting an action from anonymous calls.
+ * An action that charges Stripe, hits a private API, or reads a
+ * secret will respond happily to anonymous POSTs unless this gate
+ * fires. Pick `auth: "public"` explicitly only when the endpoint is
+ * meant to be open (a webhook receiver, a public form submit, …).
+ *
  * @example
  * ```typescript
  * export default action({
@@ -127,14 +231,39 @@ export function mutation<TArgs = Record<string, unknown>, TReturn = unknown>(
  *   },
  * });
  * ```
+ *
+ * @example
+ * ```typescript
+ * // GitHub webhook receiver — public because GitHub doesn't sign
+ * // in, the handler verifies the signature itself, then optionally
+ * // elevates.
+ * export default action({
+ *   auth: "public",
+ *   async handler(ctx) {
+ *     const ok = verifyGithubSignature(secret, ctx.request!.rawBody, sig);
+ *     if (!ok) throw ctx.error("INVALID_SIGNATURE", "bad sig");
+ *     await ctx.auth.elevate({ admin: true, reason: "github webhook hmac" });
+ *     // …
+ *   },
+ * });
+ * ```
  */
 export function action<TArgs = Record<string, unknown>, TReturn = unknown>(
-  def: ActionDef<TArgs, TReturn>
+  def: ActionDefRequired<TArgs, TReturn>,
+): FnDefinition<TArgs, TReturn>;
+export function action<TArgs = Record<string, unknown>, TReturn = unknown>(
+  def: ActionDefOptional<TArgs, TReturn>,
+): FnDefinition<TArgs, TReturn>;
+export function action<TArgs, TReturn>(
+  def:
+    | ActionDefRequired<TArgs, TReturn>
+    | ActionDefOptional<TArgs, TReturn>,
 ): FnDefinition<TArgs, TReturn> {
   return {
     type: "action",
     args: def.args,
-    handler: def.handler,
+    handler: def.handler as FnDefinition<TArgs, TReturn>["handler"],
     internal: def.internal,
+    auth: def.auth ?? DEFAULT_AUTH,
   };
 }

package/src/index.ts

@@ -31,5 +31,7 @@ export type {
   Stream,
   Scheduler,
   AuthInfo,
+  AuthMode,
+  AuthRequirement,
   FnDefinition,
 } from "./types";

package/src/runtime.ts

@@ -287,15 +287,32 @@ function rpc(callId: string, msg: Record<string, unknown>): Promise<unknown> {
 // Context builders
 // ---------------------------------------------------------------------------
 
-function buildDbReader(callId: string): DbReader {
+function buildDbReader(callId: string, unsafeOp = false): DbReader {
   // All DB ops use rpcDb so Promise.all over ctx.db reads can run in
   // parallel without colliding on the outer call_id key.
-  return {
+  //
+  // `unsafeOp` flag: when true, the emitted DbOp messages carry
+  // `unsafe_op: true` so the Rust side knows to skip the
+  // caller-aware policy gate (in Phase 2 — see
+  // pylon-functions/protocol.rs). Plain ctx.db.* leaves the flag
+  // off (the safe default); ctx.db.unsafe.* sets it.
+  const reader: DbReader = {
     async get(entity, id) {
-      return (await rpcDb(callId, { type: "db", op: "get", entity, id })) as any;
+      return (await rpcDb(callId, {
+        type: "db",
+        op: "get",
+        entity,
+        id,
+        unsafe_op: unsafeOp,
+      })) as any;
     },
     async list(entity) {
-      return (await rpcDb(callId, { type: "db", op: "list", entity })) as any;
+      return (await rpcDb(callId, {
+        type: "db",
+        op: "list",
+        entity,
+        unsafe_op: unsafeOp,
+      })) as any;
     },
     async lookup(entity, field, value) {
       return (await rpcDb(callId, {
@@ -304,6 +321,7 @@ function buildDbReader(callId: string): DbReader {
         entity,
         field,
         value,
+        unsafe_op: unsafeOp,
       })) as any;
     },
     async query(entity, filter) {
@@ -312,6 +330,7 @@ function buildDbReader(callId: string): DbReader {
         op: "query",
         entity,
         data: filter,
+        unsafe_op: unsafeOp,
       })) as any;
     },
     async queryGraph(query) {
@@ -320,6 +339,7 @@ function buildDbReader(callId: string): DbReader {
         op: "query_graph",
         entity: "",
         data: query,
+        unsafe_op: unsafeOp,
       })) as any;
     },
     async paginate(entity, opts) {
@@ -332,6 +352,7 @@ function buildDbReader(callId: string): DbReader {
         entity,
         after: opts.cursor ?? undefined,
         limit: numItems,
+        unsafe_op: unsafeOp,
       })) as any;
     },
     async search(entity, query) {
@@ -340,21 +361,34 @@ function buildDbReader(callId: string): DbReader {
         op: "search",
         entity,
         data: query,
+        unsafe_op: unsafeOp,
       })) as any;
     },
   };
+  if (!unsafeOp) {
+    (reader as DbReader & { unsafe: DbReader }).unsafe = buildDbReader(
+      callId,
+      true,
+    );
+  }
+  return reader;
 }
 
-function buildDbWriter(callId: string): DbWriter {
-  const reader = buildDbReader(callId);
-  return {
-    ...reader,
+function buildDbWriter(callId: string, unsafeOp = false): DbWriter {
+  // Drop the reader's `unsafe` shortcut before spreading — the
+  // writer needs its own (which we attach below). Without this
+  // strip, `writer.unsafe` would be a DbReader and the type
+  // narrows incorrectly.
+  const { unsafe: _ignored, ...readerOps } = buildDbReader(callId, unsafeOp);
+  const writer: DbWriter = {
+    ...readerOps,
     async insert(entity, data) {
       const r = (await rpcDb(callId, {
         type: "db",
         op: "insert",
         entity,
         data,
+        unsafe_op: unsafeOp,
       })) as { id: string };
       return r.id;
     },
@@ -365,6 +399,7 @@ function buildDbWriter(callId: string): DbWriter {
         entity,
         id,
         data,
+        unsafe_op: unsafeOp,
       })) as { updated: boolean };
       return r.updated;
     },
@@ -374,6 +409,7 @@ function buildDbWriter(callId: string): DbWriter {
         op: "delete",
         entity,
         id,
+        unsafe_op: unsafeOp,
       })) as { deleted: boolean };
       return r.deleted;
     },
@@ -385,6 +421,7 @@ function buildDbWriter(callId: string): DbWriter {
         id,
         relation,
         target_id: targetId,
+        unsafe_op: unsafeOp,
       })) as { linked: boolean };
       return r.linked;
     },
@@ -395,6 +432,7 @@ function buildDbWriter(callId: string): DbWriter {
         entity,
         id,
         relation,
+        unsafe_op: unsafeOp,
       })) as { unlinked: boolean };
       return r.unlinked;
     },
@@ -406,9 +444,27 @@ function buildDbWriter(callId: string): DbWriter {
         type: "db",
         op: "advisory_lock",
         entity: key,
+        unsafe_op: unsafeOp,
       });
     },
   };
+  // Top-level `ctx.db` is the safe path. `ctx.db.unsafe` is the
+  // escape hatch — same surface, every emitted op carries
+  // `unsafe_op: true` so the future caller-aware policy gate
+  // (PYLON_STRICT_FN_POLICIES) skips enforcement. Use sparingly,
+  // with a justifying comment, ideally in code that runs only
+  // from server-internal callers (webhooks, cron sweeps, admin
+  // tools).
+  //
+  // Self-reference would create an infinite loop on JSON
+  // serialization; only assign on the writer's `.unsafe` once.
+  if (!unsafeOp) {
+    (writer as DbWriter & { unsafe: DbWriter }).unsafe = buildDbWriter(
+      callId,
+      true,
+    );
+  }
+  return writer;
 }
 
 function buildStream(callId: string): Stream {
@@ -758,6 +814,11 @@ async function main() {
     // requests for internal fns; the Bun runtime here doesn't gate
     // (nested calls go through the same dispatcher).
     internal: def.internal === true,
+    // Declarative auth gate, enforced by the Rust router before the
+    // handler is invoked. Defaults to "user" when the TS def omits
+    // it — secure by default. See `packages/functions/src/define.ts`
+    // for the developer-facing AuthMode docs.
+    auth: def.auth ?? "user",
   }));
   send({ type: "ready", functions });
 

package/src/types.ts

@@ -6,8 +6,43 @@
 // Auth
 // ---------------------------------------------------------------------------
 
-export interface AuthInfo {
-  userId: string | null;
+/**
+ * Declarative auth requirement for a function. The framework
+ * enforces this BEFORE the handler runs — if the caller doesn't
+ * meet the bar, the request rejects with a typed error and the
+ * handler is never invoked.
+ *
+ * Functions default to `"user"` (signed-in required) when this
+ * field is omitted. That's the secure-by-default position: a
+ * forgotten `if (!ctx.auth.userId)` check never leaks data,
+ * because the runtime made the check before the handler ran.
+ *
+ * Modes:
+ * - `"public"` — anyone, including unauthenticated callers. Use
+ *   for healthchecks, landing-page form submits, intentionally-open
+ *   webhooks. Must be explicit; never the default.
+ * - `"guest"` — anonymous-with-stable-id sessions count, plus
+ *   any authenticated user. Use for cart-style pre-login state.
+ * - `"user"` — a real signed-in user (default). Guest sessions
+ *   are rejected. Inside the handler, `ctx.auth.userId` is
+ *   narrowed from `string | null` to `string` so the redundant
+ *   null check can be dropped.
+ * - `"admin"` — `ctx.auth.isAdmin === true`. Use for ops
+ *   endpoints exposed via `/api/fn/...`.
+ */
+export type AuthMode = "public" | "guest" | "user" | "admin";
+
+/**
+ * `userId` shape narrows based on the function's declared auth
+ * requirement. `auth: "user"` and `auth: "admin"` both guarantee
+ * a real signed-in user, so the handler sees a non-null string.
+ * `auth: "public"` and `auth: "guest"` allow anonymous callers,
+ * so the handler must keep checking.
+ */
+export type AuthRequirement = "required" | "optional";
+
+export interface AuthInfo<R extends AuthRequirement = "optional"> {
+  userId: R extends "required" ? string : string | null;
   isAdmin: boolean;
   /** Active tenant id (selected organization) for multi-tenant apps.
    *  Null when the session hasn't selected one. */
@@ -49,6 +84,26 @@ export interface AuthInfo {
 // ---------------------------------------------------------------------------
 
 export interface DbReader {
+  /**
+   * Escape hatch: same surface as `ctx.db` but operations bypass
+   * the framework's caller-aware policy gate (gated by
+   * `PYLON_STRICT_FN_POLICIES=1`, Phase 2). Use sparingly, only
+   * in code that runs from a trusted server-internal context —
+   * webhook receivers (after signature verification), scheduled
+   * cron sweeps, admin tooling. The plain `ctx.db.*` reads
+   * already work for the caller's-own-data case; `ctx.db.unsafe`
+   * is the answer when you genuinely need cross-tenant or
+   * cross-user reads.
+   *
+   * Every call should carry a justifying comment per codebase
+   * convention. A future `pylon lint` rule will flag bare
+   * `ctx.db.unsafe.*` without a comment immediately above.
+   *
+   * Optional on the type because old Pylon runtimes don't ship
+   * it; new code that targets v0.3.161+ can rely on the field.
+   */
+  unsafe?: DbReader;
+
   /** Get a single row by ID. Returns null if not found. */
   get(entity: string, id: string): Promise<Record<string, unknown> | null>;
 
@@ -141,6 +196,13 @@ export interface SearchResult<T = Record<string, unknown>> {
 // ---------------------------------------------------------------------------
 
 export interface DbWriter extends DbReader {
+  /**
+   * Escape hatch — same shape as [`DbReader.unsafe`] but with the
+   * write surface (insert/update/delete/link/unlink/advisoryLock).
+   * Overrides the inherited read-only `unsafe` from DbReader.
+   */
+  unsafe?: DbWriter;
+
   /** Insert a new row. Returns the generated ID. */
   insert(entity: string, data: Record<string, unknown>): Promise<string>;
 
@@ -248,17 +310,17 @@ export interface EmailSender {
 // ---------------------------------------------------------------------------
 
 /** Context for query handlers (read-only). */
-export interface QueryCtx {
+export interface QueryCtx<R extends AuthRequirement = "optional"> {
   db: DbReader;
-  auth: AuthInfo;
+  auth: AuthInfo<R>;
   /** Environment variables / secrets. */
   env: Record<string, string>;
 }
 
 /** Context for mutation handlers (read + write, transactional). */
-export interface MutationCtx {
+export interface MutationCtx<R extends AuthRequirement = "optional"> {
   db: DbWriter;
-  auth: AuthInfo;
+  auth: AuthInfo<R>;
   stream: Stream;
   scheduler: Scheduler;
   /** Environment variables / secrets. */
@@ -268,8 +330,8 @@ export interface MutationCtx {
 }
 
 /** Context for action handlers (external I/O, non-transactional). */
-export interface ActionCtx {
-  auth: AuthInfo;
+export interface ActionCtx<R extends AuthRequirement = "optional"> {
+  auth: AuthInfo<R>;
   stream: Stream;
   scheduler: Scheduler;
   /** Send transactional email via the runtime's configured provider. */
@@ -336,6 +398,12 @@ export interface FnDefinition<TArgs = unknown, TReturn = unknown> {
    * for execution.
    */
   internal?: boolean;
+  /**
+   * Auth requirement enforced by the runtime before the handler is
+   * invoked. Defaults to `"user"` — every function is signed-in only
+   * unless explicitly opted out via `auth: "public"`. See [`AuthMode`].
+   */
+  auth?: AuthMode;
 }
 
 // ---------------------------------------------------------------------------