@tribe-nest/forge 1.15.0 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "publishConfig": {
     "access": "public"
   },

package/src/server/appAuth.ts

@@ -0,0 +1,107 @@
+// Authenticate the CALLER of one of your app's OWN server routes (TanStack
+// server handlers, e.g. a "run this job now" or "save settings" endpoint).
+// SERVER-ONLY.
+//
+// Why this exists: `useAppAuth` / `useAppAdminGuard` are React hooks — they run
+// in the browser and CANNOT gate a server route. Without a server-side check, a
+// privileged route is either wide open or bolted shut behind a shared secret.
+// Neither is right. Instead: the client already holds the caller's token (the
+// app-user token, or the admin's TribeNest account token); forward it to your
+// server route in the `Authorization` header, and verify it HERE. The app Worker
+// is only a CLIENT — TribeNest is the sole authority on identity + access, so
+// these helpers forward the token to the platform and trust its answer.
+//
+// NEVER gate a privileged app route with a hardcoded/shared secret. Verify the
+// actual person making the request:
+//   - APP ADMIN  → `verifyAppAdmin`: the owner or a team member with a Work grant
+//     on the app (operator actions: trigger a sync, edit config, rebuild data).
+//   - APP USER   → `verifyAppUser`: an app-scoped account (`useAppAuth`); scope
+//     end-user actions to that user's own data.
+
+export interface AppAuthConfig {
+  /** The app id (VITE_APP_ID). `jobsConfig` from src/lib/jobs.ts satisfies this. */
+  appId: string;
+  /** The TribeNest public API base (VITE_API_URL). */
+  apiUrl: string;
+}
+
+export interface AppAdminIdentity {
+  isAdmin: true;
+  /** Highest permission the account holds on the app (view/comment/edit/manage). */
+  permission: string | null;
+  appName: string | null;
+}
+
+export interface AppUserIdentity {
+  id: string;
+  associationId: string;
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+  status: string;
+  appId: string | null;
+}
+
+// The bearer credential the client forwarded, or null. We pass it through as-is
+// (the platform verifies it) — never parse or trust its contents here.
+function bearer(request: Request): string | null {
+  const h = request.headers.get("authorization");
+  return h && /^Bearer\s+\S/i.test(h) ? h : null;
+}
+
+/**
+ * Verify the request comes from an APP ADMIN — the owner or a team member with a
+ * Work grant on the app. Forwards the caller's TribeNest account token to
+ * `GET /public/apps/:appId/admin-access`. Returns the admin identity, or `null`
+ * when there's no token / it's invalid / the account isn't an admin.
+ *
+ *     export const Route = createFileRoute("/api/tn-jobs/trigger")({
+ *       server: { handlers: { POST: async ({ request }) => {
+ *         const admin = await verifyAppAdmin(request, jobsConfig);
+ *         if (!admin) return new Response("forbidden", { status: 403 });
+ *         const { job, payload } = await request.json();
+ *         const { env } = await import("cloudflare:workers");
+ *         await enqueueAppJob(env, jobsConfig, job, payload);
+ *         return Response.json({ ok: true });
+ *       } } },
+ *     });
+ *
+ * The dashboard/admin UI calls this route with the admin's token in the
+ * `Authorization` header (the same token `usePublicAuth` holds) — so the button
+ * is authenticated as the person clicking it, no shared secret.
+ */
+export async function verifyAppAdmin(request: Request, cfg: AppAuthConfig): Promise<AppAdminIdentity | null> {
+  const auth = bearer(request);
+  if (!auth) return null;
+  try {
+    const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/admin-access`, {
+      headers: { authorization: auth },
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { isAdmin?: boolean; permission?: string | null; appName?: string | null };
+    return data.isAdmin ? { isAdmin: true, permission: data.permission ?? null, appName: data.appName ?? null } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verify the request comes from a logged-in APP USER (`useAppAuth` account).
+ * Forwards the app-user token to `GET /public/app-sessions/me`. Returns the
+ * 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.
+ */
+export async function verifyAppUser(request: Request, cfg: AppAuthConfig): Promise<AppUserIdentity | null> {
+  const auth = bearer(request);
+  if (!auth) return null;
+  try {
+    const res = await fetch(`${cfg.apiUrl}/public/app-sessions/me`, {
+      headers: { authorization: auth },
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as AppUserIdentity;
+  } catch {
+    return null;
+  }
+}

package/src/server/index.ts

@@ -15,6 +15,11 @@
 // App background-job runtime (no-config wrapper over the JobsDO). Server-only.
 export * from "./jobs";
 
+// Authenticate the caller of an app's own server routes (admin / app-user).
+// Server-only — the sanctioned alternative to gating a privileged route with a
+// shared secret. See appAuth.ts.
+export * from "./appAuth";
+
 import { emptyContentDocument, type ContentDocument } from "../content/types";
 import type {
   IEvent,