@pylonsync/functions 0.3.385 → 0.4.1

package/dist/auth.d.ts

@@ -0,0 +1,4 @@
+import type { AuthInfo } from "./types";
+export type AuthClaims = Omit<AuthInfo, "elevate">;
+/** Normalize the Rust wire envelope into the public function auth shape. */
+export declare function normalizeAuthClaims(raw: Record<string, unknown>): AuthClaims;

package/dist/runtime.d.ts

@@ -16,14 +16,6 @@
  */
 import type { DbReader, DbWriter, Llm, Rooms } from "./types";
 export declare function buildDbReader(callId: string, ssrRead?: boolean): DbReader;
-/**
- * Query-function caller for SSR `serverData.fn(name, args)`. Sends the same
- * `run_fn` frame `ctx.runQuery` uses, on the render's call_id — the host's
- * render loop executes the query with the PAGE's auth context (anonymous on
- * public pages) and rejects anything that isn't a query. Legacy rpc() (no
- * op_id) is correct here: concurrent calls queue settle-chained on the one
- * call_id, matching how ctx.runQuery behaves inside a function.
- */
 export declare function buildSsrFnCaller(callId: string): (name: string, args?: Record<string, unknown>) => Promise<unknown>;
 export declare function buildDbWriter(callId: string): DbWriter;
 /**

package/dist/types.d.ts

@@ -40,6 +40,10 @@ export interface AuthInfo<R extends AuthRequirement = "optional"> {
     /** Active tenant id (selected organization) for multi-tenant apps.
      *  Null when the session hasn't selected one. */
     tenantId: string | null;
+    /** Exact role slugs for the active organization/session. Custom roles do
+     *  not imply `member` or `admin`; compare explicitly or use
+     *  `ctx.requireMember` for an authoritative membership lookup. */
+    roles: string[];
     /**
      * Promote the call's auth context after the handler has done its
      * own authentication check (HMAC signature verification on a
@@ -546,6 +550,38 @@ export type MemberRow = Record<string, unknown> & {
  * with the caller's identity.
  */
 export type RequireMember = (orgId: string, opts?: RequireMemberOptions) => Promise<MemberRow>;
+/**
+ * Signed file-download URLs. `GET /api/files/<id>` only serves a file to its
+ * owner (or an unscoped admin) — `signedUrl` is the supported way to
+ * authorize a cross-user read: the host mints a short-lived HMAC-signed
+ * path (`/api/files/<id>?sig=...&exp=...`) that the GET handler honors as
+ * an alternative to the owner check, anonymously fetchable (works in
+ * `<img src>` and download links).
+ *
+ * WHO gets a URL is the calling function's responsibility — wrap the mint
+ * in a membership-gated function so authorization stays app-policy-driven:
+ *
+ * ```ts
+ * export default query({
+ *   args: { eventId: v.id("Event"), fileId: v.string() },
+ *   async handler(ctx, args) {
+ *     const event = await ctx.db.get("Event", args.eventId);
+ *     await ctx.requireMember(event.orgId, { role: "organizer" });
+ *     return { url: await ctx.files.signedUrl(args.fileId) };
+ *   },
+ * });
+ * ```
+ */
+export interface Files {
+    /**
+     * Mint a signed download path for a file id. `ttlSecs` defaults to 300
+     * and is capped by the host (24h) — a signed URL is a bearer capability,
+     * so keep lifetimes short.
+     */
+    signedUrl(fileId: string, opts?: {
+        ttlSecs?: number;
+    }): Promise<string>;
+}
 /** Context for query handlers (read-only).
  *
  * NOTE: `ctx.llm` is NOT exposed here. Queries are reactive: a
@@ -569,6 +605,8 @@ export interface QueryCtx<R extends AuthRequirement = "optional"> {
     error(code: string, message: string): Error;
     /** Assert org membership (optionally a role) — see {@link RequireMember}. */
     requireMember: RequireMember;
+    /** Signed file-download URLs — see {@link Files}. */
+    files: Files;
 }
 /** Context for mutation handlers (read + write, transactional). */
 export interface MutationCtx<R extends AuthRequirement = "optional"> {
@@ -584,6 +622,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
     rooms: Rooms;
     /** Per-user OAuth connection registry. */
     connections: Connections;
+    /** Signed file-download URLs — see {@link Files}. */
+    files: Files;
     /** Create a typed error that triggers rollback. */
     error(code: string, message: string): Error;
     /** Assert org membership (optionally a role) — see {@link RequireMember}. */
@@ -604,6 +644,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     connections: Connections;
     /** Environment variables / secrets. */
     env: Record<string, string>;
+    /** Signed file-download URLs — see {@link Files}. */
+    files: Files;
     /** Run a registered query within its own read transaction. */
     runQuery<T = unknown>(fnName: string, args: Record<string, unknown>): Promise<T>;
     /** Run a registered mutation within its own write transaction. */

package/package.json

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

package/src/auth.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { normalizeAuthClaims } from "./auth";
+
+describe("function auth normalization", () => {
+  test("preserves custom roles from the Rust wire envelope", () => {
+    expect(
+      normalizeAuthClaims({
+        user_id: "u1",
+        is_admin: false,
+        tenant_id: "org_1",
+        roles: ["reviewer"],
+      }),
+    ).toEqual({
+      userId: "u1",
+      isAdmin: false,
+      tenantId: "org_1",
+      roles: ["reviewer"],
+    });
+  });
+
+  test("defaults missing roles to an empty array and drops non-strings", () => {
+    expect(normalizeAuthClaims({}).roles).toEqual([]);
+    expect(normalizeAuthClaims({ roles: ["billing", 42, null] }).roles).toEqual([
+      "billing",
+    ]);
+  });
+});

package/src/auth.ts

@@ -0,0 +1,19 @@
+import type { AuthInfo } from "./types";
+
+export type AuthClaims = Omit<AuthInfo, "elevate">;
+
+/** Normalize the Rust wire envelope into the public function auth shape. */
+export function normalizeAuthClaims(
+  raw: Record<string, unknown>,
+): AuthClaims {
+  return {
+    userId:
+      ((raw.userId ?? raw.user_id) as string | null | undefined) ?? null,
+    isAdmin: Boolean(raw.isAdmin ?? raw.is_admin),
+    tenantId:
+      ((raw.tenantId ?? raw.tenant_id) as string | null | undefined) ?? null,
+    roles: Array.isArray(raw.roles)
+      ? raw.roles.filter((role): role is string => typeof role === "string")
+      : [],
+  };
+}

package/src/member.test.ts

@@ -65,6 +65,20 @@ describe("ctx.requireMember", () => {
     ).toBe("FORBIDDEN");
   });
 
+  test("custom roles are exact-match and inherit no built-in role", async () => {
+    const reviewer = { id: "m1", role: "reviewer" };
+    const requireMember = makeRequireMember("u1", spyRead([reviewer]).read);
+
+    expect(
+      await codeOf(() =>
+        requireMember("org_1", { role: ["owner", "admin", "member"] }),
+      ),
+    ).toBe("FORBIDDEN");
+    expect(await requireMember("org_1", { role: ["reviewer"] })).toEqual(
+      reviewer,
+    );
+  });
+
   test("role gate: passes when the member's role IS allowed (string or array)", async () => {
     const owner = { id: "m1", role: "owner" };
     expect(

package/src/runtime.ts

@@ -21,6 +21,7 @@ import type {
   EmailAttachment,
   EmailOptions,
   EmailSender,
+  Files,
   Stream,
   Scheduler,
   Llm,
@@ -35,6 +36,7 @@ import type {
   FnDefinition,
   AuthInfo,
 } from "./types";
+import { normalizeAuthClaims } from "./auth";
 import { makeRequireMember } from "./member";
 import { isDevMode } from "./ssr-runtime";
 import { validateArgs } from "./validators";
@@ -517,6 +519,19 @@ export function buildDbReader(callId: string, ssrRead = false): DbReader {
  * op_id) is correct here: concurrent calls queue settle-chained on the one
  * call_id, matching how ctx.runQuery behaves inside a function.
  */
+/** `ctx.files` — signed download URLs, minted host-side. */
+function buildFiles(callId: string): Files {
+  return {
+    async signedUrl(fileId, opts) {
+      return rpc(callId, {
+        type: "sign_file_url",
+        file_id: fileId,
+        ttl_secs: opts?.ttlSecs,
+      }) as Promise<string>;
+    },
+  };
+}
+
 export function buildSsrFnCaller(
   callId: string,
 ): (name: string, args?: Record<string, unknown>) => Promise<unknown> {
@@ -990,6 +1005,7 @@ function buildActionCtx(
       (err as any).code = code;
       return err;
     },
+    files: buildFiles(callId),
     // Actions have no ctx.db; read membership via the built-in internal query.
     requireMember: makeRequireMember(auth.userId, (entity, filter) =>
       rpc(callId, {
@@ -1082,11 +1098,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
   // already got camelCase don't regress.
   const rawAuth = msg.auth as unknown as Record<string, unknown>;
   const auth: AuthInfo = {
-    userId: ((rawAuth.userId ?? rawAuth.user_id) as string | null | undefined) ?? null,
-    isAdmin: Boolean(rawAuth.isAdmin ?? rawAuth.is_admin),
-    tenantId:
-      ((rawAuth.tenantId ?? rawAuth.tenant_id) as string | null | undefined) ??
-      null,
+    ...normalizeAuthClaims(rawAuth),
     // `elevate` round-trips through the host runtime which mutates
     // the per-call caller_is_admin flag — that's what subsequent
     // scheduler.runAfter() reads. We also mutate the local
@@ -1136,6 +1148,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
         requireMember: makeRequireMember(auth.userId, (entity, filter) =>
           reader.query(entity, { ...filter, $limit: 1 }),
         ),
+        files: buildFiles(msg.call_id),
       };
       break;
     }
@@ -1158,6 +1171,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
         requireMember: makeRequireMember(auth.userId, (entity, filter) =>
           writer.query(entity, { ...filter, $limit: 1 }),
         ),
+        files: buildFiles(msg.call_id),
       };
       break;
     }

package/src/types.ts

@@ -47,6 +47,10 @@ export interface AuthInfo<R extends AuthRequirement = "optional"> {
   /** Active tenant id (selected organization) for multi-tenant apps.
    *  Null when the session hasn't selected one. */
   tenantId: string | null;
+  /** Exact role slugs for the active organization/session. Custom roles do
+   *  not imply `member` or `admin`; compare explicitly or use
+   *  `ctx.requireMember` for an authoritative membership lookup. */
+  roles: string[];
   /**
    * Promote the call's auth context after the handler has done its
    * own authentication check (HMAC signature verification on a
@@ -640,6 +644,37 @@ export type RequireMember = (
   opts?: RequireMemberOptions,
 ) => Promise<MemberRow>;
 
+/**
+ * Signed file-download URLs. `GET /api/files/<id>` only serves a file to its
+ * owner (or an unscoped admin) — `signedUrl` is the supported way to
+ * authorize a cross-user read: the host mints a short-lived HMAC-signed
+ * path (`/api/files/<id>?sig=...&exp=...`) that the GET handler honors as
+ * an alternative to the owner check, anonymously fetchable (works in
+ * `<img src>` and download links).
+ *
+ * WHO gets a URL is the calling function's responsibility — wrap the mint
+ * in a membership-gated function so authorization stays app-policy-driven:
+ *
+ * ```ts
+ * export default query({
+ *   args: { eventId: v.id("Event"), fileId: v.string() },
+ *   async handler(ctx, args) {
+ *     const event = await ctx.db.get("Event", args.eventId);
+ *     await ctx.requireMember(event.orgId, { role: "organizer" });
+ *     return { url: await ctx.files.signedUrl(args.fileId) };
+ *   },
+ * });
+ * ```
+ */
+export interface Files {
+  /**
+   * Mint a signed download path for a file id. `ttlSecs` defaults to 300
+   * and is capped by the host (24h) — a signed URL is a bearer capability,
+   * so keep lifetimes short.
+   */
+  signedUrl(fileId: string, opts?: { ttlSecs?: number }): Promise<string>;
+}
+
 /** Context for query handlers (read-only).
  *
  * NOTE: `ctx.llm` is NOT exposed here. Queries are reactive: a
@@ -663,6 +698,8 @@ export interface QueryCtx<R extends AuthRequirement = "optional"> {
   error(code: string, message: string): Error;
   /** Assert org membership (optionally a role) — see {@link RequireMember}. */
   requireMember: RequireMember;
+  /** Signed file-download URLs — see {@link Files}. */
+  files: Files;
 }
 
 /** Context for mutation handlers (read + write, transactional). */
@@ -679,6 +716,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
   rooms: Rooms;
   /** Per-user OAuth connection registry. */
   connections: Connections;
+  /** Signed file-download URLs — see {@link Files}. */
+  files: Files;
   /** Create a typed error that triggers rollback. */
   error(code: string, message: string): Error;
   /** Assert org membership (optionally a role) — see {@link RequireMember}. */
@@ -700,6 +739,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   connections: Connections;
   /** Environment variables / secrets. */
   env: Record<string, string>;
+  /** Signed file-download URLs — see {@link Files}. */
+  files: Files;
   /** Run a registered query within its own read transaction. */
   runQuery<T = unknown>(
     fnName: string,