@startup-api/cloudflare 0.0.1 → 0.2.0

package/src/auth/providers.ts

@@ -0,0 +1,39 @@
+import type { StartupAPIEnv } from '../StartupAPIEnv';
+import type { ProviderOptions } from '../schemas/config';
+import { OAuthProvider } from './OAuthProvider';
+import { GoogleProvider } from './GoogleProvider';
+import { TwitchProvider } from './TwitchProvider';
+import { PatreonProvider } from './PatreonProvider';
+
+export type ProviderConfigs = Record<string, ProviderOptions>;
+
+/**
+ * Compute the base URL that provider callback/redirect URIs are built from, e.g.
+ * `https://host/users/auth`. Mirrors the logic in handleAuth so all call sites agree.
+ */
+export function computeRedirectBase(env: StartupAPIEnv, origin: string, usersPath: string): string {
+  const baseUsersPath = usersPath.startsWith('/') ? usersPath : '/' + usersPath;
+  return new URL((baseUsersPath.endsWith('/') ? baseUsersPath : baseUsersPath + '/') + 'auth', origin).toString();
+}
+
+/**
+ * Build the list of active OAuth providers (those whose credentials are configured in env). Provider
+ * behavior (scopes, Patreon campaign) comes from the factory config passed as `providerConfigs`.
+ */
+export function createProviders(env: StartupAPIEnv, redirectBase: string, providerConfigs: ProviderConfigs = {}): OAuthProvider[] {
+  return [
+    GoogleProvider.create(env, redirectBase, providerConfigs.google),
+    TwitchProvider.create(env, redirectBase, providerConfigs.twitch),
+    PatreonProvider.create(env, redirectBase, providerConfigs.patreon),
+  ].filter((p): p is OAuthProvider => p !== null);
+}
+
+/** Get a single active provider by name, or undefined if not configured. */
+export function getProvider(
+  env: StartupAPIEnv,
+  redirectBase: string,
+  name: string,
+  providerConfigs: ProviderConfigs = {},
+): OAuthProvider | undefined {
+  return createProviders(env, redirectBase, providerConfigs).find((p) => p.name === name);
+}

package/src/createStartupAPI.ts

@@ -0,0 +1,322 @@
+import { handleAuth } from './auth/index';
+import { injectPowerStrip } from './PowerStrip';
+import { UserDO } from './storage/UserDO';
+import { AccountDO } from './storage/AccountDO';
+import { SystemDO } from './storage/SystemDO';
+import { CredentialDO } from './storage/CredentialDO';
+import { CookieManager } from './CookieManager';
+import { initPlans } from './billing/plansConfig';
+import { Plan } from './billing/Plan';
+import { getActiveProviders, parseCookies, getUserFromSession, isAdmin } from './handlers/utils';
+import { handleAdmin } from './handlers/admin';
+import {
+  handleMe,
+  handleUpdateProfile,
+  handleListCredentials,
+  handleDeleteCredential,
+  handleMeImage,
+  handleUserImage,
+} from './handlers/user';
+import { handleMyAccounts, handleSwitchAccount, handleAccountDetails, handleAccountImage, handleAccountMembers } from './handlers/account';
+import { handleLogout } from './handlers/auth';
+import { handleSSR } from './handlers/ssr';
+
+import type { StartupAPIEnv } from './StartupAPIEnv';
+import { StartupAPIConfigSchema } from './schemas/config';
+import type { StartupAPIConfig, ProviderOptions, ResolvedFreshness } from './schemas/config';
+import type { AccessPolicyConfig } from './schemas/policy';
+import { AccessPolicy, evaluateAccess } from './policy/accessPolicy';
+import type { PolicyDecision } from './policy/accessPolicy';
+import { loadEntitlements, entitlementHeaders } from './entitlements/service';
+import type { Entitlements } from './entitlements/types';
+import { computeRedirectBase, getProvider } from './auth/providers';
+import { runEntitlementResync } from './entitlements/cron';
+import { handlePatreonWebhook } from './webhooks/patreon';
+
+const DEFAULT_USERS_PATH = '/users/';
+const DEFAULT_CRON_SCHEDULE = '0 */6 * * *';
+const DEFAULT_ENTITLEMENT_TTL_MS = 15 * 60 * 1000;
+
+// The factory's request handler is a local `const fetch`, which would shadow the global fetch inside
+// its body. Use this alias to proxy to the origin via the *current* global fetch at call time (so test
+// spies on globalThis.fetch are honored).
+const originFetch = (...args: Parameters<typeof fetch>): Promise<Response> => globalThis.fetch(...args);
+
+function isCronEnabled(options: ProviderOptions): boolean {
+  const cron = options.freshness?.cron;
+  return cron === true || (typeof cron === 'object' && cron !== null);
+}
+
+/** Resolve a provider's freshness config into concrete flags/values. */
+function resolveFreshness(options: ProviderOptions | undefined): ResolvedFreshness {
+  const f = options?.freshness ?? {};
+  const ttlEnabled = f.ttl === true || (typeof f.ttl === 'object' && f.ttl !== null);
+  const ttlMs = typeof f.ttl === 'object' && f.ttl?.ms ? f.ttl.ms : DEFAULT_ENTITLEMENT_TTL_MS;
+  const cronEnabled = isCronEnabled(options ?? {});
+  const cronSchedule = typeof f.cron === 'object' && f.cron?.schedule ? f.cron.schedule : DEFAULT_CRON_SCHEDULE;
+  return {
+    ttl: { enabled: ttlEnabled, ms: ttlMs },
+    cron: { enabled: cronEnabled, schedule: cronSchedule },
+    webhook: { enabled: f.webhook === true },
+  };
+}
+
+/** Resolve the access policy from factory config, else a backward-compatible all-public default. */
+function resolveAccessPolicy(configPolicy: AccessPolicyConfig | undefined): AccessPolicyConfig {
+  // No policy configured → preserve legacy behavior: allow everything, still forward identity headers.
+  return configPolicy ?? { default: { mode: 'public' } };
+}
+
+/** Build a deny response (login redirect / 403 / upgrade redirect) for an unmet access requirement. */
+function denyResponse(
+  decision: Extract<PolicyDecision, { allow: false }>,
+  ctx: { usersPath: string; returnUrl: string; activeProviders: string[] },
+): Response {
+  if (decision.action === 'forbidden') {
+    return new Response('Forbidden', { status: 403 });
+  }
+  if (decision.action === 'upgrade' && decision.upgrade_url) {
+    return new Response(null, { status: 302, headers: { Location: decision.upgrade_url } });
+  }
+  // 'login' (default): send the user to authenticate, preserving where they were going.
+  const ret = encodeURIComponent(ctx.returnUrl);
+  const target =
+    ctx.activeProviders.length === 1 ? `${ctx.usersPath}auth/${ctx.activeProviders[0]}?return_url=${ret}` : `/?return_url=${ret}`;
+  return new Response(null, { status: 302, headers: { Location: target } });
+}
+
+/**
+ * Build a configured StartupAPI instance: the Worker handler ({ fetch, scheduled? }) plus the Durable
+ * Object classes for re-export. `scheduled` is attached ONLY when at least one provider enables cron.
+ *
+ * All config is optional and falls back to env-derived defaults, so `createStartupAPI()` behaves like
+ * the previous package (login-only entitlements, no scheduled handler, all-public access policy).
+ */
+export function createStartupAPI(config: StartupAPIConfig = {}) {
+  const parsed = StartupAPIConfigSchema.parse(config);
+  const providerConfigs = parsed.providers ?? {};
+  const cronProviders = Object.entries(providerConfigs)
+    .filter(([, options]) => isCronEnabled(options))
+    .map(([name]) => name);
+  const anyCron = cronProviders.length > 0;
+  const patreonWebhookEnabled = providerConfigs.patreon?.freshness?.webhook === true;
+
+  const fetch = async (request: Request, env: StartupAPIEnv, ctx: ExecutionContext): Promise<Response> => {
+    if (!Plan.isInitialized()) {
+      if (parsed.plans) Plan.init(parsed.plans as any);
+      else initPlans();
+    }
+    if (!AccessPolicy.isInitialized()) {
+      AccessPolicy.init(resolveAccessPolicy(parsed.accessPolicy));
+    }
+
+    // Prevent infinite loops when serving assets
+    if (request.headers.has('x-skip-worker')) {
+      return env.ASSETS.fetch(request);
+    }
+
+    if (!env.ORIGIN_URL || !env.SESSION_SECRET) {
+      return env.ASSETS.fetch(request);
+    }
+
+    const url = new URL(request.url);
+    const usersPath = env.USERS_PATH || DEFAULT_USERS_PATH;
+
+    const cookieManager = new CookieManager(env.SESSION_SECRET);
+
+    // SSR Routes
+    const usersPathNormalized = usersPath.endsWith('/') ? usersPath : usersPath + '/';
+    if (url.pathname.startsWith(usersPathNormalized)) {
+      const subPath = url.pathname.slice(usersPathNormalized.length);
+      const isProfile = subPath === 'profile.html' || subPath === 'profile';
+      const isAccounts = subPath === 'accounts.html' || subPath === 'accounts';
+
+      if (isProfile || isAccounts) {
+        return handleSSR(request, env, url, usersPath, cookieManager);
+      }
+    }
+
+    // Patreon webhook (only mounted when configured)
+    if (patreonWebhookEnabled && url.pathname === usersPath + 'webhooks/patreon') {
+      return handlePatreonWebhook(request, env, ctx, providerConfigs);
+    }
+
+    // Handle OAuth Routes
+    if (url.pathname.startsWith(usersPath + 'auth/')) {
+      return handleAuth(request, env, url, usersPath, cookieManager, providerConfigs);
+    }
+
+    if (url.pathname === usersPath + 'me/avatar') {
+      return handleMeImage(request, env, 'avatar', cookieManager);
+    }
+
+    // Handle API Routes
+    if (url.pathname.startsWith(usersPath + 'api/')) {
+      const apiPath = url.pathname.replace(usersPath + 'api/', '/');
+
+      if (apiPath === '/me') {
+        return handleMe(request, env, cookieManager);
+      }
+
+      if (apiPath === '/me/profile' && request.method === 'POST') {
+        return handleUpdateProfile(request, env, cookieManager);
+      }
+
+      if (apiPath === '/me/credentials') {
+        if (request.method === 'GET') {
+          return handleListCredentials(request, env, cookieManager);
+        } else if (request.method === 'DELETE') {
+          return handleDeleteCredential(request, env, cookieManager);
+        }
+      }
+
+      if (apiPath === '/stop-impersonation' && request.method === 'POST') {
+        const cookieHeader = request.headers.get('Cookie');
+        const cookies = parseCookies(cookieHeader || '');
+        const backupSessionEncrypted = cookies['backup_session_id'];
+
+        if (!backupSessionEncrypted) {
+          return new Response('No impersonation session found', { status: 400 });
+        }
+
+        const backupSession = await cookieManager.decrypt(backupSessionEncrypted);
+        if (!backupSession) {
+          return new Response('Invalid backup session', { status: 400 });
+        }
+
+        const headers = new Headers();
+        const newSessionIdEncrypted = await cookieManager.encrypt(backupSession);
+        headers.set('Set-Cookie', `session_id=${newSessionIdEncrypted}; Path=/; HttpOnly; Secure; SameSite=Lax`);
+        headers.append('Set-Cookie', `backup_session_id=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0`);
+
+        return Response.json({ success: true }, { headers });
+      }
+
+      if (apiPath === '/me/accounts') {
+        return handleMyAccounts(request, env, cookieManager);
+      }
+
+      if (apiPath === '/me/accounts/switch' && request.method === 'POST') {
+        return handleSwitchAccount(request, env, cookieManager);
+      }
+
+      if (apiPath.startsWith('/me/accounts/')) {
+        const parts = apiPath.split('/');
+        if (parts.length === 4) {
+          return handleAccountDetails(request, env, parts[3], cookieManager);
+        }
+        if (parts.length === 5 && parts[4] === 'avatar') {
+          return handleAccountImage(request, env, parts[3], 'avatar', cookieManager);
+        }
+        if (parts.length >= 5 && parts[4] === 'members') {
+          return handleAccountMembers(request, env, parts[3], parts.slice(5), cookieManager);
+        }
+      }
+
+      if (apiPath.startsWith('/users/')) {
+        const parts = apiPath.split('/');
+        if (parts.length === 4 && parts[3] === 'avatar') {
+          return handleUserImage(request, env, parts[2], 'avatar', cookieManager);
+        }
+      }
+    }
+
+    if (url.pathname === usersPath + 'logout') {
+      return handleLogout(request, env, url, usersPath, cookieManager);
+    }
+
+    // Admin Routes
+    if (url.pathname.startsWith(usersPath + 'admin/')) {
+      return handleAdmin(request, env, usersPath, cookieManager);
+    }
+
+    // Intercept requests to usersPath and serve them from the public/users directory.
+    if (url.pathname.startsWith(usersPath)) {
+      url.pathname = url.pathname.replace(usersPath, '/users/');
+      const newRequest = new Request(url.toString(), request);
+      newRequest.headers.set('x-skip-worker', 'true');
+      return env.ASSETS.fetch(newRequest);
+    }
+
+    if (env.ORIGIN_URL) {
+      // Evaluate the access policy BEFORE any identity work, so bypass paths are a raw proxy.
+      const rule = AccessPolicy.evaluate(url.pathname);
+      const requestOrigin = env.AUTH_ORIGIN && env.AUTH_ORIGIN !== '' ? env.AUTH_ORIGIN : url.origin;
+      const returnUrl = url.pathname + url.search;
+
+      const originUrl = new URL(env.ORIGIN_URL);
+      url.protocol = originUrl.protocol;
+      url.host = originUrl.host;
+      url.port = originUrl.port;
+
+      const newRequest = new Request(url.toString(), request);
+      newRequest.headers.set('Host', url.host);
+
+      if (rule.requirement.mode === 'bypass') {
+        // Pure pass-through: no identity resolution, no headers, no power-strip injection.
+        return originFetch(newRequest);
+      }
+
+      const user = await getUserFromSession(request, env, cookieManager);
+      const authenticated = !!user;
+      const userIsAdmin = user ? isAdmin(user, env) : false;
+      let entitlements: Entitlements | null = null;
+      let loginProvider: string | undefined;
+
+      if (user) {
+        newRequest.headers.set('X-StartupAPI-User-Id', user.id);
+        const userStub = env.USER.get(env.USER.idFromString(user.id));
+        const currentAccount = await userStub.getCurrentAccount();
+        if (currentAccount) {
+          newRequest.headers.set('X-StartupAPI-Account-Id', currentAccount.account_id);
+        }
+
+        loginProvider = user.credential?.provider;
+        const subjectId = user.credential?.subject_id;
+        if (loginProvider && subjectId) {
+          const provider = getProvider(env, computeRedirectBase(env, requestOrigin, usersPath), loginProvider, providerConfigs);
+          if (provider && provider.supportsEntitlements()) {
+            const fr = resolveFreshness(providerConfigs[loginProvider]);
+            entitlements = await loadEntitlements({
+              env,
+              provider,
+              userStub,
+              userId: user.id,
+              subjectId,
+              ttlEnabled: fr.ttl.enabled,
+              ttlMs: fr.ttl.ms,
+            });
+          }
+        }
+      }
+
+      // Forward login + entitlement info to the origin (skipped for bypass above).
+      for (const [key, value] of Object.entries(entitlementHeaders(authenticated, loginProvider, entitlements))) {
+        newRequest.headers.set(key, value);
+      }
+
+      // Enforce the requirement. Admins bypass the gate (identity/headers above still apply).
+      const decision = evaluateAccess(rule, { authenticated, entitlements, isAdmin: userIsAdmin });
+      if (!decision.allow) {
+        return denyResponse(decision, { usersPath, returnUrl, activeProviders: getActiveProviders(env) });
+      }
+
+      const response = await originFetch(newRequest);
+      const providers = getActiveProviders(env);
+      return injectPowerStrip(response, usersPath, providers);
+    }
+
+    // do not modify the request as it will loop through the same worker again
+    return env.ASSETS.fetch(request);
+  };
+
+  const handler: ExportedHandler<StartupAPIEnv> = { fetch };
+
+  if (anyCron) {
+    handler.scheduled = async (_event: ScheduledController, env: StartupAPIEnv, ctx: ExecutionContext): Promise<void> => {
+      ctx.waitUntil(runEntitlementResync(env, cronProviders, providerConfigs));
+    };
+  }
+
+  return { default: handler, fetch: handler.fetch!, scheduled: handler.scheduled, UserDO, AccountDO, SystemDO, CredentialDO };
+}

package/src/entitlements/cron.ts

@@ -0,0 +1,37 @@
+import type { StartupAPIEnv } from '../StartupAPIEnv';
+import { computeRedirectBase, getProvider } from '../auth/providers';
+import type { ProviderConfigs } from '../auth/providers';
+import { refreshEntitlements } from './service';
+
+/**
+ * Periodically re-sync entitlements for the given providers (those that enabled cron). Pages through
+ * each provider's CredentialDO with keyset pagination and refreshes every credential; per-credential
+ * failures are logged and skipped so one revoked token doesn't abort the batch.
+ *
+ * Scale note: all credentials for a provider live in a single Durable Object, so throughput is bounded
+ * by that one SQLite instance. Fine to thousands; very large bases would need work-splitting.
+ */
+export async function runEntitlementResync(env: StartupAPIEnv, providerNames: string[], providerConfigs: ProviderConfigs = {}): Promise<void> {
+  // redirectBase is irrelevant for refresh/fetch-entitlement calls (they use tokens + client creds),
+  // so a placeholder origin is fine here where there is no inbound request.
+  const redirectBase = computeRedirectBase(env, env.AUTH_ORIGIN || 'https://localhost', '/users/');
+
+  for (const name of providerNames) {
+    const provider = getProvider(env, redirectBase, name, providerConfigs);
+    if (!provider || !provider.supportsEntitlements()) continue;
+
+    const credStub = env.CREDENTIAL.get(env.CREDENTIAL.idFromName(name));
+    let cursor: string | null = null;
+    do {
+      const page: { rows: any[]; cursor: string | null } = await credStub.listAll(500, cursor ?? undefined);
+      for (const cred of page.rows) {
+        try {
+          await refreshEntitlements(env, provider, { ...cred, user_id: cred.user_id }, 'cron');
+        } catch (e) {
+          console.error(`[cron] entitlement resync failed for ${name}/${cred.subject_id}`, e);
+        }
+      }
+      cursor = page.cursor;
+    } while (cursor);
+  }
+}

package/src/entitlements/patreon.ts

@@ -0,0 +1,85 @@
+import type { PatreonEntitlement } from './types';
+
+/**
+ * Parse a Patreon v2 `identity` response (JSON:API) into our flat {@link PatreonEntitlement}.
+ *
+ * The relevant request is:
+ *   GET /api/oauth2/v2/identity
+ *     ?include=memberships,memberships.currently_entitled_tiers,memberships.currently_entitled_tiers.benefits
+ *     &fields[member]=patron_status,currently_entitled_amount_cents
+ *     &fields[tier]=title&fields[benefit]=title
+ *
+ * The response carries the user in `data`, with `data.relationships.memberships.data` listing member
+ * refs, and the full member/tier/benefit objects in the top-level `included` array. We resolve refs
+ * through `included`, walking member → currently_entitled_tiers → benefits.
+ *
+ * When `campaignId` is provided, only the membership for that campaign is considered (a user may be a
+ * patron of several campaigns through the same Patreon account); otherwise all memberships aggregate.
+ */
+export function parsePatreonIdentity(json: any, campaignId?: string): PatreonEntitlement {
+  const empty: PatreonEntitlement = {
+    patron_status: null,
+    is_active_patron: false,
+    entitled_tier_ids: [],
+    entitled_benefit_ids: [],
+    pledge_amount_cents: null,
+  };
+
+  if (!json || typeof json !== 'object' || !json.data) return empty;
+
+  // Index every included resource by `${type}:${id}` for O(1) ref resolution.
+  const included = new Map<string, any>();
+  for (const item of Array.isArray(json.included) ? json.included : []) {
+    if (item && item.type && item.id != null) {
+      included.set(`${item.type}:${item.id}`, item);
+    }
+  }
+  const resolve = (ref: any) => (ref && ref.type && ref.id != null ? included.get(`${ref.type}:${ref.id}`) : undefined);
+
+  const membershipRefs: any[] = json.data?.relationships?.memberships?.data ?? [];
+
+  const tierIds = new Set<string>();
+  const benefitIds = new Set<string>();
+  let patronStatus: PatreonEntitlement['patron_status'] = null;
+  let pledgeAmount: number | null = null;
+
+  for (const memberRef of membershipRefs) {
+    const member = resolve(memberRef);
+    if (!member) continue;
+
+    // Filter to a specific campaign when configured.
+    if (campaignId) {
+      const memberCampaignId = member.relationships?.campaign?.data?.id;
+      if (memberCampaignId && String(memberCampaignId) !== String(campaignId)) continue;
+    }
+
+    const status = member.attributes?.patron_status ?? null;
+    // Prefer an active membership's status/amount; otherwise keep the first non-null seen.
+    if (status === 'active_patron' || patronStatus === null) {
+      patronStatus = status;
+    }
+    const amount = member.attributes?.currently_entitled_amount_cents;
+    if (typeof amount === 'number' && (pledgeAmount === null || status === 'active_patron')) {
+      pledgeAmount = amount;
+    }
+
+    const tierRefs: any[] = member.relationships?.currently_entitled_tiers?.data ?? [];
+    for (const tierRef of tierRefs) {
+      if (tierRef?.id == null) continue;
+      tierIds.add(String(tierRef.id));
+      const tier = resolve(tierRef);
+      const benefitRefs: any[] = tier?.relationships?.benefits?.data ?? [];
+      for (const benefitRef of benefitRefs) {
+        if (benefitRef?.id != null) benefitIds.add(String(benefitRef.id));
+      }
+    }
+  }
+
+  return {
+    patron_status: patronStatus,
+    is_active_patron: patronStatus === 'active_patron',
+    entitled_tier_ids: [...tierIds],
+    entitled_benefit_ids: [...benefitIds],
+    pledge_amount_cents: pledgeAmount,
+  };
+}

package/src/entitlements/service.ts

@@ -0,0 +1,98 @@
+import type { StartupAPIEnv } from '../StartupAPIEnv';
+import type { OAuthProvider } from '../auth/OAuthProvider';
+import type { Entitlements, EntitlementSource } from './types';
+import { getValidAccessToken } from './tokenManager';
+import type { StoredCredential } from './tokenManager';
+
+/**
+ * Fetch fresh entitlements for a credential and persist them to both the source of truth
+ * (CredentialDO) and the hot-path cache (UserDO). Returns null when the provider has no entitlements,
+ * the token can't be refreshed, or the provider call fails. Shared by login, lazy TTL, cron, webhook.
+ */
+export async function refreshEntitlements(
+  env: StartupAPIEnv,
+  provider: OAuthProvider,
+  credential: StoredCredential,
+  source: EntitlementSource,
+): Promise<Entitlements | null> {
+  if (!provider.supportsEntitlements()) return null;
+
+  const token = await getValidAccessToken(env, provider, credential);
+  if (!token) return null;
+
+  const partial = await provider.fetchEntitlements(token);
+  if (!partial) return null;
+
+  const entitlements: Entitlements = {
+    provider: provider.name,
+    checked_at: Date.now(),
+    source,
+    ...partial,
+  };
+
+  // Source of truth + write-through hot-path cache.
+  const credStub = env.CREDENTIAL.get(env.CREDENTIAL.idFromName(provider.name));
+  await credStub.putEntitlements(credential.subject_id, entitlements as unknown as Record<string, any>);
+  const userStub = env.USER.get(env.USER.idFromString(credential.user_id));
+  await userStub.setEntitlements(provider.name, credential.subject_id, entitlements as unknown as Record<string, any>, entitlements.checked_at);
+
+  return entitlements;
+}
+
+/**
+ * Resolve the entitlements that apply to the current request. Reads the UserDO hot-path cache first;
+ * if the entry is missing or (when TTL is enabled) older than `ttlMs`, refreshes from the provider and
+ * falls back to the cached value on failure. Returns null when the provider produces no entitlements.
+ */
+export async function loadEntitlements(opts: {
+  env: StartupAPIEnv;
+  provider: OAuthProvider;
+  // DurableObjectStub for the current user's UserDO (already opened by the proxy).
+  userStub: { getEntitlements: (provider: string, subjectId: string) => Promise<{ data: any; checked_at: number } | null> };
+  userId: string;
+  subjectId: string;
+  ttlEnabled: boolean;
+  ttlMs: number;
+}): Promise<Entitlements | null> {
+  const { env, provider, userStub, userId, subjectId, ttlEnabled, ttlMs } = opts;
+  if (!provider.supportsEntitlements()) return null;
+
+  const cached = await userStub.getEntitlements(provider.name, subjectId);
+  const isFresh = cached && (!ttlEnabled || Date.now() - cached.checked_at < ttlMs);
+  if (isFresh) return cached!.data as Entitlements;
+
+  // Missing or stale → refresh (lazy TTL). Fall back to the cached value if the refresh fails.
+  try {
+    const credStub = env.CREDENTIAL.get(env.CREDENTIAL.idFromName(provider.name));
+    const cred = await credStub.get(subjectId);
+    if (!cred) return (cached?.data as Entitlements) ?? null;
+    const refreshed = await refreshEntitlements(env, provider, { ...cred, user_id: cred.user_id ?? userId }, 'oauth');
+    return refreshed ?? ((cached?.data as Entitlements) ?? null);
+  } catch (e) {
+    console.error('[entitlements] loadEntitlements refresh failed', e);
+    return (cached?.data as Entitlements) ?? null;
+  }
+}
+
+/**
+ * Build the entitlement-related headers forwarded to the origin app. Always includes the
+ * authenticated flag; adds the login provider and a compact JSON entitlement summary when present,
+ * plus provider-namespaced convenience headers for Patreon.
+ */
+export function entitlementHeaders(authenticated: boolean, provider?: string, entitlements?: Entitlements | null): Record<string, string> {
+  const headers: Record<string, string> = { 'X-StartupAPI-Authenticated': String(authenticated) };
+  if (provider) headers['X-StartupAPI-Login-Provider'] = provider;
+  if (entitlements) {
+    headers['X-StartupAPI-Entitlements'] = JSON.stringify(entitlements);
+    if (entitlements.patreon) {
+      headers['X-StartupAPI-Patreon-Active'] = String(entitlements.patreon.is_active_patron);
+      if (entitlements.patreon.entitled_tier_ids.length) {
+        headers['X-StartupAPI-Patreon-Tiers'] = entitlements.patreon.entitled_tier_ids.join(',');
+      }
+      if (entitlements.patreon.entitled_benefit_ids.length) {
+        headers['X-StartupAPI-Patreon-Benefits'] = entitlements.patreon.entitled_benefit_ids.join(',');
+      }
+    }
+  }
+  return headers;
+}

package/src/entitlements/tokenManager.ts

@@ -0,0 +1,67 @@
+import type { StartupAPIEnv } from '../StartupAPIEnv';
+import type { OAuthProvider } from '../auth/OAuthProvider';
+
+/** Refresh the access token this many ms before its actual expiry, to avoid edge-of-expiry failures. */
+const EXPIRY_SKEW_MS = 60_000;
+
+export interface StoredCredential {
+  subject_id: string;
+  user_id: string;
+  access_token?: string | null;
+  refresh_token?: string | null;
+  expires_at?: number | null;
+  scope?: string | null;
+  profile_data?: Record<string, any> | null;
+  created_at?: number | null;
+}
+
+/**
+ * Return a valid access token for a stored credential, refreshing it via the provider's refresh token
+ * when it has expired (or is about to). On a successful refresh the new token set is persisted back to
+ * the provider's CredentialDO. Returns null when there is no usable token and refresh is impossible or
+ * fails (e.g. a revoked refresh token) — callers should treat that as "entitlements unavailable" rather
+ * than crash the request.
+ *
+ * This is the single chokepoint shared by lazy TTL refresh (hot path) and the cron re-sync.
+ */
+export async function getValidAccessToken(
+  env: StartupAPIEnv,
+  provider: OAuthProvider,
+  credential: StoredCredential,
+): Promise<string | null> {
+  const notExpired = !credential.expires_at || Date.now() < credential.expires_at - EXPIRY_SKEW_MS;
+  if (credential.access_token && notExpired) {
+    return credential.access_token;
+  }
+
+  if (!credential.refresh_token) {
+    // No way to refresh; fall back to the existing token (may be stale) or give up.
+    return credential.access_token ?? null;
+  }
+
+  try {
+    const refreshed = await provider.refreshToken(credential.refresh_token);
+    if (!refreshed || !refreshed.access_token) {
+      return credential.access_token ?? null;
+    }
+
+    const expiresAt = refreshed.expires_in ? Date.now() + refreshed.expires_in * 1000 : undefined;
+
+    const stub = env.CREDENTIAL.get(env.CREDENTIAL.idFromName(provider.name));
+    await stub.put({
+      subject_id: credential.subject_id,
+      user_id: credential.user_id,
+      access_token: refreshed.access_token,
+      refresh_token: refreshed.refresh_token ?? credential.refresh_token,
+      expires_at: expiresAt,
+      scope: refreshed.scope ?? credential.scope ?? undefined,
+      profile_data: credential.profile_data ?? undefined,
+      created_at: credential.created_at ?? undefined,
+    });
+
+    return refreshed.access_token;
+  } catch (e) {
+    console.error(`[entitlements] Token refresh failed for ${provider.name}`, e);
+    return null;
+  }
+}