@tribe-nest/forge 1.14.0 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "1.14.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,

package/src/server/jobs.ts

@@ -21,8 +21,17 @@ interface AppJobsStub {
 export interface JobSchedule {
   /** Stable job name — also the key in your job map + the `scheduleId` in the token. */
   name: string;
-  /** How often to run, in milliseconds (e.g. 60_000 = every minute). */
-  intervalMs: number;
+  /**
+   * Fixed interval in milliseconds (e.g. 60_000 = every minute). Provide this OR
+   * `cron`, not both. Best for "every N minutes/hours"; the first run lands one
+   * interval after the deploy.
+   */
+  intervalMs?: number;
+   // A 5-field UTC cron expression: minute hour day-of-month month day-of-week.
+   // e.g. "0 3 * * *" = daily at 03:00 UTC; "0 0,6,12,18 * * *" = every 6 hours;
+   // "0 9 * * 1-5" = 09:00 UTC on weekdays. Provide this OR `intervalMs`. Use
+   // cron when a run must land at a specific wall-clock time; evaluation is UTC.
+  cron?: string;
 }
 
 /** Context passed to a job handler — carries the platform token so the handler
@@ -48,7 +57,11 @@ const stub = (env: AppJobsEnv, appId: string): AppJobsStub => env.JOBS.get(env.J
 // A stable fingerprint of the desired schedule set, so the DO skips reconcile
 // when nothing changed (sorted by name → order-independent).
 function scheduleHash(schedules: JobSchedule[]): string {
-  return JSON.stringify([...schedules].sort((a, b) => a.name.localeCompare(b.name)).map((s) => [s.name, s.intervalMs]));
+  return JSON.stringify(
+    [...schedules]
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map((s) => [s.name, s.intervalMs ?? null, s.cron ?? null]),
+  );
 }
 
 /**
@@ -73,9 +86,9 @@ export async function enqueueAppJob(
 }
 
 /**
- * Handle the DO's alarm callback (`POST /_jobs/run`). Verifies the platform
+ * Handle the DO's alarm callback (`POST /api/tn-jobs/run`). Verifies the platform
  * token, looks up the named handler in your job map, and runs it with the app's
- * `env` (so `env.SHOPIFY_TOKEN` etc. are available). Wire your `/_jobs/run` route
+ * `env` (so `env.SHOPIFY_TOKEN` etc. are available). Wire your `/api/tn-jobs/run` route
  * to this.
  */
 export async function handleAppJobRun(
@@ -115,8 +128,18 @@ export async function handleAppJobRun(
 /**
  * Persist APP-OWNED rows into one of the app's collections from a job handler —
  * the sanctioned server-side write path (do NOT invent an endpoint). Authenticated
- * by the run's token (from `JobContext`). `replace: true` = full refresh (archive
- * the existing app-owned rows first), so a re-sync doesn't accumulate duplicates.
+ * by the run's token (from `JobContext`).
+ *
+ * IMPORTANT — this ALWAYS INSERTS (there is no upsert-by-key). A stable title does
+ * NOT make re-runs idempotent (slugs auto-dedupe to -2/-3…), so re-running WILL
+ * duplicate rows. For idempotency use `replace: true` (archives every existing
+ * app-owned row in the collection, then inserts) AND re-pull the FULL dataset each
+ * run. NEVER combine `replace: true` with an incremental window (e.g.
+ * updated_at_min / last-7-days) — it archives the rows outside the window too and
+ * you lose history. (True incremental upsert-by-key is not supported yet.)
+ *
+ * Handlers receive `(payload, env, ctx)` — pass `ctx` here; `cfg` is your own
+ * config built from `import.meta.env`.
  *
  *     jobs = {
  *       "sync-shopify": async (_p, env, ctx) => {