@tribe-nest/forge 1.20.2 → 2.2.0

package/src/server/_tests/appUserPermissions.spec.ts

@@ -0,0 +1,197 @@
+// Unit tests for the app-user permission helpers — the CLIENT side of the
+// permission store (packages/forge/src/server/appUsers.ts + verifyAppUser's
+// `require` in appAuth.ts). The platform's own rules are tested against a real
+// database in apps/backend/src/routes/public/apps/_tests/appUserPermissions.spec.ts;
+// what CANNOT be tested there is this half, which decides which header a
+// credential becomes and whether a guard says yes.
+//
+// Both are security-relevant in a quiet way: a typo in the header name turns
+// every grant into a 401 (visible), and a wrong `require` turns every guard into
+// a yes (invisible). Hence the emphasis on the negative cases.
+//
+// Coverage:
+//  - credential → header mapping for all three principals
+//  - `Bearer ` normalization (bare token and full header value both work)
+//  - set vs add/remove body shapes
+//  - error surfacing: the platform's message reaches the caller, not "failed"
+//  - verifyAppUser: no token, bad response, permission held / not held / absent
+//  - verifyAppUser: `require` accepts one permission or any-of several
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { setAppUserPermissions, getAppUserPermissions } from "../appUsers";
+import { verifyAppUser } from "../appAuth";
+
+const cfg = { appId: "app-1", apiUrl: "https://api.test" };
+
+type Call = { url: string; init: RequestInit };
+let calls: Call[];
+
+/** Stub `fetch`, recording every call and answering with `body`. */
+function stubFetch(body: unknown, ok = true, status = 200) {
+  calls = [];
+  const fake = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+    calls.push({ url: String(url), init: init ?? {} });
+    return { ok, status, json: async () => body } as unknown as Response;
+  });
+  vi.stubGlobal("fetch", fake);
+  return fake;
+}
+
+const headers = (i = 0) => (calls[i].init.headers ?? {}) as Record<string, string>;
+const body = (i = 0) => JSON.parse(String(calls[i].init.body));
+
+const request = (auth?: string) =>
+  new Request("https://app.test/api/thing", { headers: auth ? { authorization: auth } : {} });
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("setAppUserPermissions — credentials", () => {
+  beforeEach(() => stubFetch({ permissions: ["a"] }));
+
+  it("sends a job token as the app-sync header, NOT as a bearer", async () => {
+    await setAppUserPermissions(cfg, { jobToken: "sync-token" }, "assoc-1", { add: ["a"] });
+    expect(headers()["x-app-sync-token"]).toBe("sync-token");
+    // A job token is not a bearer credential; sending it as one would be
+    // rejected by the platform with an auth error that reads like a bug.
+    expect(headers().authorization).toBeUndefined();
+  });
+
+  it("sends a platform token as a bearer", async () => {
+    await setAppUserPermissions(cfg, { platformToken: "tnp_abc" }, "assoc-1", { add: ["a"] });
+    expect(headers().authorization).toBe("Bearer tnp_abc");
+    expect(headers()["x-app-sync-token"]).toBeUndefined();
+  });
+
+  it("accepts an admin token either bare or as a whole Authorization header", async () => {
+    // The admin lane usually has the full header straight off the request, and
+    // double-prefixing it would produce "Bearer Bearer …".
+    await setAppUserPermissions(cfg, { adminToken: "Bearer jwt-value" }, "assoc-1", { add: ["a"] });
+    expect(headers().authorization).toBe("Bearer jwt-value");
+
+    await setAppUserPermissions(cfg, { adminToken: "jwt-value" }, "assoc-1", { add: ["a"] });
+    expect(headers(1).authorization).toBe("Bearer jwt-value");
+  });
+});
+
+describe("setAppUserPermissions — request shape", () => {
+  beforeEach(() => stubFetch({ permissions: ["kept"] }));
+
+  it("PUTs to the app's own user, url-encoding the association id", async () => {
+    await setAppUserPermissions(cfg, { jobToken: "t" }, "assoc/1", { add: ["a"] });
+    expect(calls[0].url).toBe("https://api.test/public/apps/app-1/users/assoc%2F1/permissions");
+    expect(calls[0].init.method).toBe("PUT");
+    expect(headers()["content-type"]).toBe("application/json");
+  });
+
+  it("sends `permissions` for a full set and `add`/`remove` for a patch", async () => {
+    await setAppUserPermissions(cfg, { jobToken: "t" }, "a1", { set: ["only", "these"] });
+    expect(body()).toEqual({ permissions: ["only", "these"] });
+
+    await setAppUserPermissions(cfg, { jobToken: "t" }, "a1", { add: ["x"], remove: ["y"] });
+    expect(body(1)).toEqual({ add: ["x"], remove: ["y"] });
+  });
+
+  it("returns the resulting list", async () => {
+    expect(await setAppUserPermissions(cfg, { jobToken: "t" }, "a1", { add: ["x"] })).toEqual(["kept"]);
+  });
+
+  it("GETs without a body", async () => {
+    expect(await getAppUserPermissions(cfg, { jobToken: "t" }, "a1")).toEqual(["kept"]);
+    expect(calls[0].init.method).toBe("GET");
+    expect(calls[0].init.body).toBeUndefined();
+  });
+});
+
+describe("setAppUserPermissions — failures", () => {
+  it("surfaces the platform's own message", async () => {
+    // The refusals say WHY and what to do instead ("an app user cannot change
+    // permissions…"). Flattening that to "request failed" would strand the
+    // developer who hit it.
+    stubFetch({ message: "An app user cannot change permissions — not even their own." }, false, 403);
+    await expect(setAppUserPermissions(cfg, { jobToken: "t" }, "a1", { add: ["x"] })).rejects.toThrow(
+      /app user cannot change permissions/,
+    );
+  });
+
+  it("still throws when the error body is not JSON", async () => {
+    calls = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: false, status: 500, json: async () => Promise.reject(new Error("nope")) })),
+    );
+    await expect(setAppUserPermissions(cfg, { jobToken: "t" }, "a1", { add: ["x"] })).rejects.toThrow(/500/);
+  });
+
+  it("treats a response with no permissions as an empty list, not undefined", async () => {
+    stubFetch({});
+    expect(await getAppUserPermissions(cfg, { jobToken: "t" }, "a1")).toEqual([]);
+  });
+});
+
+describe("verifyAppUser — require", () => {
+  const user = (permissions?: unknown) => ({
+    id: "acc-1",
+    associationId: "assoc-1",
+    email: "u@test",
+    firstName: null,
+    lastName: null,
+    status: "active",
+    appId: "app-1",
+    ...(permissions === undefined ? {} : { permissions }),
+  });
+
+  it("returns the user with permissions when no requirement is given", async () => {
+    stubFetch(user(["bookings.manage"]));
+    const result = await verifyAppUser(request("Bearer tok"), cfg);
+    expect(result).toMatchObject({ associationId: "assoc-1", permissions: ["bookings.manage"] });
+  });
+
+  it("passes when the user holds the required permission", async () => {
+    stubFetch(user(["bookings.manage", "reports.view"]));
+    expect(await verifyAppUser(request("Bearer tok"), cfg, { require: "bookings.manage" })).not.toBeNull();
+  });
+
+  it("REFUSES when the user is signed in but lacks it", async () => {
+    stubFetch(user(["reports.view"]));
+    expect(await verifyAppUser(request("Bearer tok"), cfg, { require: "bookings.manage" })).toBeNull();
+  });
+
+  it("treats an array requirement as ANY-of", async () => {
+    stubFetch(user(["reports.view"]));
+    expect(await verifyAppUser(request("Bearer tok"), cfg, { require: ["bookings.manage", "reports.view"] })).not.toBeNull();
+
+    stubFetch(user(["something.else"]));
+    expect(await verifyAppUser(request("Bearer tok"), cfg, { require: ["bookings.manage", "reports.view"] })).toBeNull();
+  });
+
+  it("holds nothing when the API sends no permissions (older backend)", async () => {
+    // A site on a newer Forge against an older API must degrade to "holds none"
+    // rather than throwing inside a guard — a crash there is a 500 on a route
+    // that should simply have said no.
+    stubFetch(user(undefined));
+    expect(await verifyAppUser(request("Bearer tok"), cfg)).toMatchObject({ permissions: [] });
+    expect(await verifyAppUser(request("Bearer tok"), cfg, { require: "anything" })).toBeNull();
+  });
+
+  it("returns null without a token, and never calls the platform", async () => {
+    const fetchMock = stubFetch(user([]));
+    expect(await verifyAppUser(request(), cfg, { require: "x" })).toBeNull();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("returns null when the platform rejects the token", async () => {
+    stubFetch({ message: "nope" }, false, 401);
+    expect(await verifyAppUser(request("Bearer bad"), cfg, { require: "x" })).toBeNull();
+  });
+
+  it("returns null when the platform is unreachable", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new Error("network down");
+      }),
+    );
+    // Fail CLOSED: an outage must not open a guarded route.
+    expect(await verifyAppUser(request("Bearer tok"), cfg, { require: "x" })).toBeNull();
+  });
+});

package/src/server/appAuth.ts

@@ -40,6 +40,15 @@ export interface AppUserIdentity {
   lastName: string | null;
   status: string;
   appId: string | null;
+  /**
+   * The permissions YOUR app has given this user. Your own vocabulary — the
+   * platform stores these strings and never interprets them.
+   *
+   * Read here, on the server, from the platform's answer about the caller's
+   * token. That is what makes them trustworthy: nothing the browser sends can
+   * change them, and a revoked permission is gone on the very next request.
+   */
+  permissions: string[];
 }
 
 // The bearer credential the client forwarded, or null. We pass it through as-is
@@ -91,8 +100,26 @@ export async function verifyAppAdmin(request: Request, cfg: AppAuthConfig): Prom
  * user, or `null` when unauthenticated. Use to scope an end-user server action
  * to that user (e.g. read/write only their own rows) — the returned
  * `associationId` is the owner id the platform enforces on `mine`-scoped data.
+ *
+ * Pass `require` to also demand one of YOUR app's permissions, so the check and
+ * the refusal are one line and can't drift apart:
+ *
+ *     const user = await verifyAppUser(request, cfg, { require: "bookings.manage" })
+ *     if (!user) return new Response("forbidden", { status: 403 })
+ *
+ * `require` returns null when the user is signed in but lacks the permission —
+ * same shape as "not signed in", because the route's answer is the same either
+ * way and distinguishing them tells a prober which permission to go hunting for.
+ * Read `user.permissions` yourself when you need the difference.
  */
-export async function verifyAppUser(request: Request, cfg: AppAuthConfig): Promise<AppUserIdentity | null> {
+export async function verifyAppUser(
+  request: Request,
+  cfg: AppAuthConfig,
+  opts?: {
+    /** A permission (or any one of several) the user must hold. */
+    require?: string | string[];
+  },
+): Promise<AppUserIdentity | null> {
   const auth = bearer(request);
   if (!auth) return null;
   try {
@@ -100,7 +127,15 @@ export async function verifyAppUser(request: Request, cfg: AppAuthConfig): Promi
       headers: { authorization: auth },
     });
     if (!res.ok) return null;
-    return (await res.json()) as AppUserIdentity;
+    const user = (await res.json()) as AppUserIdentity;
+    // Older API responses have no `permissions`; treat that as "holds none"
+    // rather than letting `undefined.includes` throw inside a guard.
+    user.permissions = Array.isArray(user.permissions) ? user.permissions : [];
+    if (opts?.require) {
+      const required = Array.isArray(opts.require) ? opts.require : [opts.require];
+      if (!required.some((p) => user.permissions.includes(p))) return null;
+    }
+    return user;
   } catch {
     return null;
   }

package/src/server/appUsers.ts

@@ -0,0 +1,133 @@
+// Permissions for YOUR app's own users. SERVER-ONLY.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// THE ONE RULE: NEVER SET PERMISSIONS FROM WHAT THE BROWSER ASKED FOR.
+//
+// A user's own token can't reach this API — the platform refuses it — so the
+// only way to get self-escalation is to replay a user's request on the app's own
+// credential. That is exactly what a route looks like when it's written without
+// thinking about it:
+//
+//   ❌ WRONG — any signed-in user can now make themselves an admin
+//   const { associationId, permissions } = await request.json()
+//   await setAppUserPermissions(cfg, { jobToken: ctx.token }, associationId, { set: permissions })
+//
+//   ✅ RIGHT — a person with admin rights on the app decided this
+//   const admin = await verifyAppAdmin(request, cfg)
+//   if (!admin) return new Response("forbidden", { status: 403 })
+//   const { associationId, permissions } = await request.json()
+//   await setAppUserPermissions(cfg, { adminToken: request.headers.get("authorization")! },
+//     associationId, { set: permissions })
+//
+//   ✅ ALSO RIGHT — your own code decided, with no user request involved
+//   await setAppUserPermissions(cfg, { jobToken: ctx.token }, buyer.associationId,
+//     { add: ["premium"] })
+//
+// The difference is not the credential. It is whether the DECISION came from
+// your app or from the caller.
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// The permission strings are your own — "bookings.manage", "premium", whatever
+// your code checks. TribeNest stores them against the user and hands them back
+// with their identity (`verifyAppUser`, `useAppAuth`). It never reads them, so
+// there is no catalog to register and nothing to keep in sync with your code.
+
+import type { AppAuthConfig } from "./appAuth";
+
+/**
+ * How this call proves it is allowed to change permissions. Three principals,
+ * and a user's own session token is not one of them.
+ */
+export type AppUserPermissionCredential =
+  /** Inside a job handler: `{ jobToken: ctx.token }`. The app acting as itself. */
+  | { jobToken: string }
+  /** From your own server, outside a job: `{ platformToken: env.TN_APP_TOKEN }`. */
+  | { platformToken: string }
+  /** A person's token, AFTER `verifyAppAdmin` said they're an admin of this app. */
+  | { adminToken: string };
+
+export type AppUserPermissionChange =
+  /** The complete list. What an admin screen sends. */
+  | { set: string[] }
+  /**
+   * A patch. What automation should send: granting `premium` must not silently
+   * drop something another path added between your read and your write.
+   */
+  | { add?: string[]; remove?: string[] };
+
+function authHeaders(credential: AppUserPermissionCredential): Record<string, string> {
+  if ("jobToken" in credential) return { "x-app-sync-token": credential.jobToken };
+  const raw = "platformToken" in credential ? credential.platformToken : credential.adminToken;
+  // Accept a bare token or a whole `Authorization` header value, since the admin
+  // lane usually has the latter straight off the incoming request.
+  return { authorization: /^Bearer\s/i.test(raw) ? raw : `Bearer ${raw}` };
+}
+
+async function permissionsRequest(
+  cfg: AppAuthConfig,
+  credential: AppUserPermissionCredential,
+  associationId: string,
+  init: RequestInit,
+): Promise<string[]> {
+  const res = await fetch(
+    `${cfg.apiUrl}/public/apps/${cfg.appId}/users/${encodeURIComponent(associationId)}/permissions`,
+    { ...init, headers: { "content-type": "application/json", ...authHeaders(credential), ...(init.headers ?? {}) } },
+  );
+  const body = (await res.json().catch(() => ({}))) as { permissions?: string[]; message?: string };
+  if (!res.ok) {
+    throw new Error(body.message ?? `Could not update app-user permissions (${res.status})`);
+  }
+  return body.permissions ?? [];
+}
+
+/**
+ * Set or patch what one of your app's users may do. Returns the resulting list.
+ *
+ * NEVER TAKE THE PERMISSIONS FROM THE REQUEST BODY UNLESS YOU VERIFIED AN ADMIN
+ * FIRST. A user's own token cannot reach this API, so the only way to build
+ * self-escalation is to replay their request on your app's credential — which is
+ * what the obvious version of the route does:
+ *
+ * WRONG (any signed-in user just promoted themselves):
+ *   const { associationId, permissions } = await request.json()
+ *   await setAppUserPermissions(cfg, { jobToken: ctx.token }, associationId, { set: permissions })
+ *
+ * RIGHT (a person with admin rights on the app decided):
+ *   const admin = await verifyAppAdmin(request, cfg)
+ *   if (!admin) return new Response("forbidden", { status: 403 })
+ *   await setAppUserPermissions(cfg, { adminToken: request.headers.get("authorization")! },
+ *     associationId, { set: permissions })
+ *
+ * RIGHT (your own logic decided, no user request involved):
+ *   await setAppUserPermissions(cfg, { jobToken: ctx.token }, buyer.associationId, { add: ["premium"] })
+ *
+ * Prefer `add`/`remove` over `set` in automation — the owner can grant from the
+ * dashboard too, and replacing the whole list would undo them. Idempotent, which
+ * matters because jobs and event deliveries retry.
+ */
+export async function setAppUserPermissions(
+  cfg: AppAuthConfig,
+  credential: AppUserPermissionCredential,
+  associationId: string,
+  change: AppUserPermissionChange,
+): Promise<string[]> {
+  return permissionsRequest(cfg, credential, associationId, {
+    method: "PUT",
+    body: JSON.stringify("set" in change ? { permissions: change.set } : { add: change.add, remove: change.remove }),
+  });
+}
+
+/**
+ * What one of your app's users currently holds.
+ *
+ * For your ADMIN surface — "who has what". To authorize the CURRENT caller, use
+ * `verifyAppUser(request, cfg, { require })` instead: it reads the permissions of
+ * whoever is actually making the request, rather than an id the request supplied.
+ */
+export async function getAppUserPermissions(
+  cfg: AppAuthConfig,
+  credential: AppUserPermissionCredential,
+  associationId: string,
+): Promise<string[]> {
+  return permissionsRequest(cfg, credential, associationId, { method: "GET" });
+}

package/src/server/index.ts

@@ -20,6 +20,11 @@ export * from "./jobs";
 // shared secret. See appAuth.ts.
 export * from "./appAuth";
 
+// Permissions your app gives its OWN users — your vocabulary, stored by the
+// platform and never interpreted by it. Server-only, and read the rule at the
+// top of appUsers.ts before wiring a route to it.
+export * from "./appUsers";
+
 import { emptyContentDocument, type ContentDocument } from "../content/types";
 import type {
   IEvent,
@@ -263,3 +268,15 @@ export function toPlainText(html?: string, max = 200): string | undefined {
   if (!text) return undefined;
   return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
 }
+
+// Platform access + events (docs/app-platform-access-initiative.md). SERVER ONLY —
+// the client carries the app's platform credential.
+export {
+  createPlatformClient,
+  verifyPlatformEvent,
+  PlatformError,
+  type PlatformClient,
+  type PlatformConfig,
+  type PlatformAction,
+  type PlatformEvent,
+} from "./platform";

package/src/server/jobs.ts

@@ -91,9 +91,30 @@ export interface JobSchedule {
 export interface JobContext {
   /** The app-sync token this run was invoked with (forward it to writes). */
   token: string;
+  /**
+   * Milliseconds left before the platform stops waiting for this run.
+   *
+   * CHECK THIS IN ANY LOOP THAT DOES REAL WORK. A run that overruns is cut off
+   * mid-flight: the platform never learns the outcome, so it will NOT be retried
+   * automatically (retrying might redo work you already committed) and it lands in
+   * `deadLetters` for the owner to decide about. Commit what you have and stop
+   * while there is still time — see `partial` below.
+   */
+  remainingMs: () => number;
 }
 
-export type JobHandler = (payload: unknown, env: unknown, ctx: JobContext) => Promise<void> | void;
+/**
+ * What a handler can report back.
+ *
+ * Return nothing for "done". Return `{ partial: true }` when you committed some
+ * work and stopped deliberately — because you were running out of time, or the
+ * upstream paged. That is NOT a failure: it will not be retried, and it shows as
+ * `partial` rather than as an error on the owner's dashboard. Enqueue the next
+ * slice yourself; the cursor lives with you, not with us.
+ */
+export type JobResult = void | { partial: true; message?: string };
+
+export type JobHandler = (payload: unknown, env: unknown, ctx: JobContext) => Promise<JobResult> | JobResult;
 
 export interface AppJobsConfig {
   /** The app id (VITE_APP_ID). */
@@ -134,7 +155,16 @@ export async function reconcileAppJobs(env: AppJobsEnv, cfg: AppJobsConfig, sche
   await stub(env, cfg.appId).reconcile(cfg.script ?? "", cfg.appId, schedules, scheduleHash(schedules));
 }
 
-/** Enqueue a durable one-time job (survives redeploys, retried on failure). */
+/**
+ * Enqueue a durable one-time job (survives redeploys, retried on failure).
+ *
+ * `delayMs` means NOT BEFORE — it is a floor, not a schedule. Queued jobs run one
+ * after another, so once several are due they are dispatched back to back and any
+ * stagger you gave them is gone: fan out ten with `delayMs: i * 4000` and, if each
+ * takes a minute, they run a minute apart, not four seconds. Do NOT use it to pace
+ * against a third party's rate limit — handle that inside the handler, or chain the
+ * work by enqueueing the next slice when one finishes.
+ */
 export async function enqueueAppJob(
   env: AppJobsEnv,
   cfg: AppJobsConfig,
@@ -191,13 +221,27 @@ export async function handleAppJobRun(
   }
   if (!valid) return new Response("unauthorized", { status: 401 });
 
-  const body = (await request.json().catch(() => ({}))) as { job?: string; payload?: unknown };
+  const body = (await request.json().catch(() => ({}))) as {
+    job?: string;
+    payload?: unknown;
+    deadlineAt?: number;
+  };
   const handler = body.job ? jobs[body.job] : undefined;
   if (!handler) return new Response("unknown job", { status: 404 });
   try {
     // Pass the verified token so the handler can write app-owned data back
-    // (writeAppCollection) without re-minting anything.
-    await handler(body.payload ?? null, env, { token });
+    // (writeAppCollection) without re-minting anything, plus how long it has —
+    // so a long job can commit and stop instead of being cut off mid-write.
+    const deadlineAt = typeof body.deadlineAt === "number" ? body.deadlineAt : undefined;
+    const result = await handler(body.payload ?? null, env, {
+      token,
+      remainingMs: () => (deadlineAt ? Math.max(0, deadlineAt - Date.now()) : Number.POSITIVE_INFINITY),
+    });
+    if (result && typeof result === "object" && result.partial) {
+      // Reported to the platform as its own outcome so a correctly-behaving
+      // resumable job doesn't read as an error.
+      return new Response(result.message ?? "partial", { headers: { "x-tn-job-status": "partial" } });
+    }
     return new Response("ok");
   } catch (err) {
     // Non-2xx → the DO retries (one-time) / re-fires next interval (recurring).
@@ -245,7 +289,11 @@ export async function writeAppCollection(
   opts?: {
     /** Archive every existing row first. Only for a COMPLETE dataset — see above. */
     replace?: boolean;
-    /** Field(s) identifying a row, so existing rows are updated instead of duplicated. */
+    /**
+     * Field(s) identifying a row, so existing rows are updated instead of
+     * duplicated. Mark the key field FILTERABLE on the collection — matching is
+     * then an indexed lookup; otherwise it still works but scans.
+     */
     upsertKey?: string | string[];
   },
 ): Promise<{ created: number; updated: number; archived: number }> {
@@ -322,3 +370,90 @@ export async function aggregateAppCollection(
   if (!res.ok) throw new Error(`aggregateAppCollection ${slug} failed: ${res.status} ${await res.text().catch(() => "")}`);
   return res.json();
 }
+
+/**
+ * Upload a file and get back a hosted URL, in two steps.
+ *
+ * The two steps are not a formality. The bytes go to a STAGING key that does not
+ * survive: `finalizeAppUpload` moves the file to its real home, and anything
+ * never finalized is deleted within the hour. So the URL you can actually use is
+ * the one finalize returns — a staged URL will stop working, and the upload will
+ * not be counted against the profile's storage.
+ *
+ *   const up = await createAppUpload(ctx, cfg, "cover.png", bytes.byteLength)
+ *   await fetch(up.uploadUrl, { method: "PUT", headers: up.requiredHeaders, body: bytes })
+ *   const media = await finalizeAppUpload(ctx, cfg, up.uploadId)   // media.url is yours
+ *
+ * `size` is a hint so an over-quota upload fails before the transfer rather than
+ * after it; the size recorded is whatever storage reports once the bytes land.
+ * The file name decides the type, and script-capable types (html, svg) are
+ * refused.
+ */
+export async function createAppUpload(
+  ctx: JobContext,
+  cfg: AppJobsConfig,
+  fileName: string,
+  size?: number,
+): Promise<{
+  uploadId: string;
+  uploadUrl: string;
+  requiredHeaders: Record<string, string>;
+  method: "PUT";
+  expiresAt: string;
+}> {
+  const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/uploads`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
+    body: JSON.stringify({ fileName, size }),
+  });
+  if (!res.ok) throw new Error(`createAppUpload failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}
+
+/**
+ * Complete an upload started with {@link createAppUpload} and get the media row.
+ *
+ * Safe to retry — finalizing twice returns the same media rather than storing the
+ * file twice. Takes no size: the platform reads it back from storage.
+ */
+export async function finalizeAppUpload(
+  ctx: JobContext,
+  cfg: AppJobsConfig,
+  uploadId: string,
+): Promise<{ id: string; url: string; size: string; type: string; name: string }> {
+  const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/uploads/${uploadId}/finalize`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
+    body: "{}",
+  });
+  if (!res.ok) throw new Error(`finalizeAppUpload failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}
+
+/**
+ * Send an email as this app.
+ *
+ * The From resolves to the app's own sending identity when the owner configured
+ * one, otherwise the profile's — so mail is attributed to the creator, not to
+ * TribeNest, without the app holding any mail credentials.
+ *
+ *   await sendAppEmail(ctx, cfg, { to: user.email, subject: "Booked", html })
+ *
+ * Bounded on purpose: at most 50 recipients per call, and a daily per-app
+ * recipient budget, because the send is charged to the owner's allocation. For a
+ * campaign, use the platform's messaging tools instead — they handle consent and
+ * unsubscribes, which this deliberately does not.
+ */
+export async function sendAppEmail(
+  ctx: JobContext,
+  cfg: AppJobsConfig,
+  msg: { to: string | string[]; subject: string; html: string; replyTo?: string },
+): Promise<{ sent: number }> {
+  const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/emails`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
+    body: JSON.stringify(msg),
+  });
+  if (!res.ok) throw new Error(`sendAppEmail failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}