@startup-api/cloudflare 0.0.1 → 0.1.0

package/src/index.ts

@@ -1,190 +1,22 @@
-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 { getActiveProviders, parseCookies, getUserFromSession } 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 { Plan } from './billing/Plan';
-
-const DEFAULT_USERS_PATH = '/users/';
-
-export { UserDO, AccountDO, SystemDO, CredentialDO };
-
-import type { StartupAPIEnv } from './StartupAPIEnv';
-
-export default {
-  /**
-   * Main Worker fetch handler.
-   */
-  async fetch(request: Request, env: StartupAPIEnv): Promise<Response> {
-    if (!Plan.isInitialized()) {
-      initPlans();
-    }
-
-    // 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);
-      }
-    }
-
-    // Handle OAuth Routes
-    if (url.pathname.startsWith(usersPath + 'auth/')) {
-      return handleAuth(request, env, url, usersPath, cookieManager);
-    }
-
-    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) {
-      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);
-
-      const user = await getUserFromSession(request, env, cookieManager);
-      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);
-        }
-      }
-
-      const response = await fetch(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);
-  },
-} satisfies ExportedHandler<StartupAPIEnv>;
+import { createStartupAPI } from './createStartupAPI';
+
+/**
+ * Default StartupAPI instance, built from environment configuration only (no code config). This keeps
+ * the long-standing usage working unchanged:
+ *
+ *   export { default, UserDO, AccountDO, SystemDO, CredentialDO } from '@startup-api/cloudflare';
+ *
+ * To customize behavior (provider freshness, access policy, plans), import `createStartupAPI` and pass
+ * a config object instead of re-exporting the default.
+ */
+const instance = createStartupAPI();
+
+export const UserDO = instance.UserDO;
+export const AccountDO = instance.AccountDO;
+export const SystemDO = instance.SystemDO;
+export const CredentialDO = instance.CredentialDO;
+
+export { createStartupAPI };
+export type { StartupAPIConfig } from './schemas/config';
+
+export default instance.default;

package/src/policy/accessPolicy.ts

@@ -0,0 +1,99 @@
+import { AccessPolicySchema } from '../schemas/policy';
+import type { AccessPolicyConfig, AccessPolicyResolved, AccessRule, Requirement, UnauthorizedAction } from '../schemas/policy';
+import type { Entitlements } from '../entitlements/types';
+import { providerEntitlementCheckers, providerSupportsEntitlements } from './entitlementCheckers';
+
+/**
+ * Match a single path pattern against a request path.
+ * - `/`        → the homepage only
+ * - `/foo/*`   → `/foo` and anything under `/foo/`
+ * - `/foo`     → exact match
+ */
+export function matchPattern(pattern: string, path: string): boolean {
+  if (pattern === '/') return path === '/';
+  if (pattern.endsWith('/*')) {
+    const base = pattern.slice(0, -2);
+    return path === base || path.startsWith(base + '/');
+  }
+  return path === pattern;
+}
+
+export type PolicyDecision =
+  | { allow: true }
+  | { allow: false; reason: 'unauthenticated' | 'not_entitled'; action: UnauthorizedAction; upgrade_url?: string };
+
+function deny(reason: 'unauthenticated' | 'not_entitled', rule: AccessRule): PolicyDecision {
+  return { allow: false, reason, action: rule.on_unauthorized, upgrade_url: rule.upgrade_url };
+}
+
+/**
+ * Decide whether a request satisfies a resolved rule, given the auth state and resolved entitlements.
+ * `bypass`/`public` always allow; `authenticated` needs a logged-in user; `entitlement` dispatches the
+ * condition through the provider checker registry.
+ */
+export function evaluateAccess(rule: AccessRule, ctx: { authenticated: boolean; entitlements: Entitlements | null }): PolicyDecision {
+  const req = rule.requirement;
+  switch (req.mode) {
+    case 'bypass':
+    case 'public':
+      return { allow: true };
+    case 'authenticated':
+      return ctx.authenticated ? { allow: true } : deny('unauthenticated', rule);
+    case 'entitlement': {
+      if (!ctx.authenticated) return deny('unauthenticated', rule);
+      const checker = providerEntitlementCheckers[req.provider];
+      const ok = checker ? checker(req.condition, ctx.entitlements) : false;
+      return ok ? { allow: true } : deny('not_entitled', rule);
+    }
+  }
+}
+
+/**
+ * Static registry for the path-based access policy, initialized once at startup (mirrors the Plan
+ * registry pattern). The default rule (for unmatched paths) falls back to `authenticated`.
+ */
+export class AccessPolicy {
+  private static config: AccessPolicyResolved | null = null;
+
+  static init(config: AccessPolicyConfig | undefined): void {
+    const parsed = AccessPolicySchema.parse(config ?? {});
+
+    // Validate that every entitlement requirement targets a provider that supports entitlements.
+    const requirements: Requirement[] = [...parsed.rules.map((r) => r.requirement), ...(parsed.default ? [parsed.default] : [])];
+    for (const req of requirements) {
+      if (req.mode === 'entitlement' && !providerSupportsEntitlements(req.provider)) {
+        throw new Error(
+          `Access policy references an entitlement condition for provider '${req.provider}', which does not support entitlement conditions`,
+        );
+      }
+    }
+
+    AccessPolicy.config = parsed;
+  }
+
+  static isInitialized(): boolean {
+    return AccessPolicy.config !== null;
+  }
+
+  /** Reset state — intended for tests that re-init with different configs. */
+  static reset(): void {
+    AccessPolicy.config = null;
+  }
+
+  /** Resolve the rule that applies to a path: first matching rule, else the default. */
+  static evaluate(path: string): AccessRule {
+    const cfg = AccessPolicy.config;
+    if (!cfg) throw new Error('AccessPolicy not initialized');
+
+    for (const rule of cfg.rules) {
+      if (matchPattern(rule.pattern, path)) return rule;
+    }
+
+    return {
+      pattern: '*',
+      requirement: cfg.default ?? { mode: 'authenticated' },
+      on_unauthorized: cfg.default_on_unauthorized,
+      upgrade_url: cfg.default_upgrade_url,
+    };
+  }
+}

package/src/policy/entitlementCheckers.ts

@@ -0,0 +1,36 @@
+import type { Entitlements } from '../entitlements/types';
+import type { EntitlementCondition } from '../schemas/policy';
+
+/**
+ * Provider entitlement checker registry — the ONLY place provider-specific access logic lives.
+ *
+ * Each entry maps a provider name to a function that decides whether a given entitlement condition is
+ * satisfied by the user's resolved entitlements. The access policy engine dispatches through this map,
+ * so adding perk-level checks for a new provider is purely additive (register a checker + implement
+ * the provider's `fetchEntitlements`) with no engine changes.
+ *
+ * Only Patreon participates today; Google/Twitch register nothing and therefore cannot be the target
+ * of an entitlement requirement (the policy rejects that at init time).
+ */
+export type EntitlementChecker = (condition: EntitlementCondition, entitlements: Entitlements | null) => boolean;
+
+export const providerEntitlementCheckers: Record<string, EntitlementChecker> = {
+  patreon(condition, entitlements) {
+    const patreon = entitlements?.patreon;
+    if (!patreon) return false;
+    switch (condition.type) {
+      case 'active_patron':
+        return patreon.is_active_patron;
+      case 'benefit':
+        return patreon.entitled_benefit_ids.includes(condition.benefit_id);
+      case 'tier':
+        return patreon.entitled_tier_ids.includes(condition.tier_id);
+      default:
+        return false;
+    }
+  },
+};
+
+export function providerSupportsEntitlements(provider: string): boolean {
+  return Object.prototype.hasOwnProperty.call(providerEntitlementCheckers, provider);
+}

package/src/schemas/config.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { AccessPolicySchema } from './policy';
+
+/**
+ * Zod schema + types for the StartupAPI configuration factory (see src/createStartupAPI.ts).
+ *
+ * Only non-secret behavior lives here — provider enablement, per-provider freshness toggles, access
+ * policy and plans. Credentials/secrets stay in env. Every field is optional and falls back to
+ * env-derived defaults, so `createStartupAPI()` with no config behaves like the previous package.
+ */
+
+const TtlFreshnessSchema = z.union([z.boolean(), z.object({ ms: z.number().positive().optional() })]);
+const CronFreshnessSchema = z.union([z.boolean(), z.object({ schedule: z.string().optional() })]);
+
+export const ProviderFreshnessSchema = z.object({
+  /** Lazily re-check entitlements on the request hot path when older than the TTL. Off by default. */
+  ttl: TtlFreshnessSchema.optional(),
+  /** Periodically re-sync entitlements via a scheduled() handler. Off by default. */
+  cron: CronFreshnessSchema.optional(),
+  /** Update entitlements from provider webhooks (Patreon only). Off by default. */
+  webhook: z.boolean().optional(),
+});
+
+export const ProviderOptionsSchema = z.object({
+  /** Force-enable/disable the provider. Default: enabled iff its credentials are present in env. */
+  enabled: z.boolean().optional(),
+  /** Extra OAuth scopes to request, on top of the provider's required base scopes. */
+  scopes: z.union([z.string(), z.array(z.string())]).optional(),
+  /** Patreon only: restrict entitlements to a single campaign id. */
+  campaignId: z.string().optional(),
+  freshness: ProviderFreshnessSchema.optional(),
+});
+
+export const StartupAPIConfigSchema = z.object({
+  providers: z.record(z.string(), ProviderOptionsSchema).optional(),
+  accessPolicy: AccessPolicySchema.optional(),
+  // Plans are validated by the billing layer; accept an array passthrough here.
+  plans: z.array(z.any()).optional(),
+});
+
+export type ProviderFreshness = z.infer<typeof ProviderFreshnessSchema>;
+export type ProviderOptions = z.infer<typeof ProviderOptionsSchema>;
+export type StartupAPIConfig = z.input<typeof StartupAPIConfigSchema>;
+
+/** Normalized per-provider freshness after resolving boolean/object forms and env fallbacks. */
+export interface ResolvedFreshness {
+  ttl: { enabled: boolean; ms: number };
+  cron: { enabled: boolean; schedule: string };
+  webhook: { enabled: boolean };
+}

package/src/schemas/entitlement.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+/**
+ * Zod schemas for the provider-agnostic entitlement model (see src/entitlements/types.ts).
+ * Used to validate entitlement blobs on read/write from storage.
+ */
+
+export const PatreonEntitlementSchema = z.object({
+  patron_status: z.enum(['active_patron', 'declined_patron', 'former_patron']).nullable(),
+  is_active_patron: z.boolean(),
+  entitled_tier_ids: z.array(z.string()),
+  entitled_benefit_ids: z.array(z.string()),
+  pledge_amount_cents: z.number().nullable(),
+});
+
+export const EntitlementsSchema = z.object({
+  provider: z.string(),
+  checked_at: z.number(),
+  source: z.enum(['oauth', 'webhook', 'cron']),
+  patreon: PatreonEntitlementSchema.optional(),
+});
+
+export type EntitlementsInput = z.input<typeof EntitlementsSchema>;
+export type EntitlementsOutput = z.output<typeof EntitlementsSchema>;

package/src/schemas/policy.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+
+/**
+ * Zod schemas for the path-based access policy (see src/policy/accessPolicy.ts).
+ *
+ * A policy is an ordered list of rules mapping a URL path pattern to an access requirement, plus a
+ * default requirement for unmatched paths. The requirement modes are provider-agnostic except for
+ * `entitlement`, whose `condition` is provider-scoped and validated against the provider entitlement
+ * checker registry at policy-init time.
+ */
+
+/**
+ * Provider entitlement conditions. Currently only Patreon implements these; the engine rejects an
+ * entitlement requirement whose provider has no registered checker.
+ */
+export const EntitlementConditionSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('active_patron') }),
+  z.object({ type: z.literal('benefit'), benefit_id: z.string() }),
+  z.object({ type: z.literal('tier'), tier_id: z.string() }),
+]);
+
+export const RequirementSchema = z.discriminatedUnion('mode', [
+  // Raw pass-through: no credential check, no identity resolution, no headers, no injection.
+  z.object({ mode: z.literal('bypass') }),
+  // Anyone; resolve session if present and forward identity/entitlement headers.
+  z.object({ mode: z.literal('public') }),
+  // Any logged-in user.
+  z.object({ mode: z.literal('authenticated') }),
+  // Provider-specific entitlement (e.g. Patreon active patron / benefit / tier).
+  z.object({
+    mode: z.literal('entitlement'),
+    provider: z.string(),
+    condition: EntitlementConditionSchema,
+  }),
+]);
+
+export const UnauthorizedActionSchema = z.enum(['login', 'forbidden', 'upgrade']);
+
+export const RuleSchema = z.object({
+  /** Path pattern: exact (`/special`), prefix (`/special/*`), or `/` for the homepage only. */
+  pattern: z.string(),
+  requirement: RequirementSchema,
+  /** What to do when the requirement is not met. Defaults to 'login'. */
+  on_unauthorized: UnauthorizedActionSchema.default('login'),
+  /** Redirect target for the 'upgrade' action (e.g. a Patreon join page). */
+  upgrade_url: z.string().optional(),
+});
+
+export const AccessPolicySchema = z.object({
+  rules: z.array(RuleSchema).default([]),
+  /** Requirement applied to paths that match no rule. Defaults to 'authenticated' when omitted. */
+  default: RequirementSchema.optional(),
+  default_on_unauthorized: UnauthorizedActionSchema.default('login'),
+  default_upgrade_url: z.string().optional(),
+});
+
+export type EntitlementCondition = z.infer<typeof EntitlementConditionSchema>;
+export type Requirement = z.infer<typeof RequirementSchema>;
+export type UnauthorizedAction = z.infer<typeof UnauthorizedActionSchema>;
+export type AccessRule = z.infer<typeof RuleSchema>;
+export type AccessPolicyConfig = z.input<typeof AccessPolicySchema>;
+export type AccessPolicyResolved = z.output<typeof AccessPolicySchema>;

package/src/storage/CredentialDO.ts

@@ -2,6 +2,7 @@ import { DurableObject } from 'cloudflare:workers';
 import { StartupAPIEnv } from '../StartupAPIEnv';
 import { OAuthCredentialSchema } from '../schemas/credential';
 import type { OAuthCredential, OAuthCredentialOutput } from '../schemas/credential';
+import { EntitlementsSchema } from '../schemas/entitlement';
 
 /**
  * A Durable Object representing all OAuth credentials for a specific provider.
@@ -28,6 +29,23 @@ export class CredentialDO extends DurableObject {
       );
       CREATE INDEX IF NOT EXISTS idx_user_id ON credentials(user_id);
     `);
+
+    // Entitlement columns were added after the initial schema. SQLite has no
+    // "ADD COLUMN IF NOT EXISTS", so guard each ALTER and ignore the duplicate-column error.
+    for (const column of ['entitlements TEXT', 'entitlements_checked_at INTEGER']) {
+      try {
+        this.sql.exec(`ALTER TABLE credentials ADD COLUMN ${column}`);
+      } catch (_e) {
+        // Column already exists.
+      }
+    }
+  }
+
+  /** Parse the JSON columns (profile_data, entitlements) of a credential row in place. */
+  private hydrate(row: any): any {
+    row.profile_data = row.profile_data ? JSON.parse(row.profile_data) : null;
+    row.entitlements = row.entitlements ? JSON.parse(row.entitlements) : null;
+    return row;
   }
 
   async get(subjectId: string): Promise<any | null> {
@@ -35,20 +53,48 @@ export class CredentialDO extends DurableObject {
     const row = result.next().value as any;
     if (!row) return null;
 
-    row.profile_data = JSON.parse(row.profile_data);
-    return row;
+    return this.hydrate(row);
   }
 
   async list(userId: string): Promise<any[]> {
     const result = this.sql.exec('SELECT * FROM credentials WHERE user_id = ?', userId);
     const credentials = [];
     for (const row of result) {
-      (row as any).profile_data = JSON.parse((row as any).profile_data);
-      credentials.push(row);
+      credentials.push(this.hydrate(row as any));
     }
     return credentials;
   }
 
+  /**
+   * Enumerate all credentials for this provider using keyset pagination on the subject_id PK.
+   * Used by the scheduled cron re-sync. Returns the next cursor (last subject_id) or null when done.
+   */
+  async listAll(limit = 500, after?: string): Promise<{ rows: any[]; cursor: string | null }> {
+    const result = after
+      ? this.sql.exec('SELECT * FROM credentials WHERE subject_id > ? ORDER BY subject_id LIMIT ?', after, limit)
+      : this.sql.exec('SELECT * FROM credentials ORDER BY subject_id LIMIT ?', limit);
+
+    const rows: any[] = [];
+    for (const row of result) {
+      rows.push(this.hydrate(row as any));
+    }
+    const cursor = rows.length === limit ? (rows[rows.length - 1].subject_id as string) : null;
+    return { rows, cursor };
+  }
+
+  /** Persist the entitlements blob for a credential (source of truth). */
+  async putEntitlements(subjectId: string, entitlements: Record<string, any>): Promise<{ success: boolean }> {
+    const validated = EntitlementsSchema.parse(entitlements);
+    this.sql.exec(
+      'UPDATE credentials SET entitlements = ?, entitlements_checked_at = ?, updated_at = ? WHERE subject_id = ?',
+      JSON.stringify(validated),
+      validated.checked_at,
+      Date.now(),
+      subjectId,
+    );
+    return { success: true };
+  }
+
   async put(data: OAuthCredential): Promise<{ success: boolean }> {
     console.log('[auth] Parsing Cred', data);
 

package/src/storage/UserDO.ts

@@ -51,6 +51,14 @@ export class UserDO extends DurableObject {
         subject_id TEXT NOT NULL,
         PRIMARY KEY (provider, subject_id)
       );
+
+      CREATE TABLE IF NOT EXISTS entitlements_cache (
+        provider TEXT NOT NULL,
+        subject_id TEXT NOT NULL,
+        data TEXT,
+        checked_at INTEGER,
+        PRIMARY KEY (provider, subject_id)
+      );
     `);
 
     // Ensure the single row exists
@@ -186,6 +194,34 @@ export class UserDO extends DurableObject {
     return { success: true };
   }
 
+  /**
+   * Read the denormalized entitlements cache for a (provider, subject_id). This is the per-request
+   * hot-path read: the proxy already opens this UserDO each request, so no extra DO hop is needed.
+   * Returns null when there is no cached entry.
+   */
+  async getEntitlements(provider: string, subject_id: string): Promise<{ data: any; checked_at: number } | null> {
+    const result = this.sql.exec(
+      'SELECT data, checked_at FROM entitlements_cache WHERE provider = ? AND subject_id = ?',
+      provider,
+      subject_id,
+    );
+    const row = result.next().value as any;
+    if (!row) return null;
+    return { data: row.data ? JSON.parse(row.data) : null, checked_at: row.checked_at };
+  }
+
+  /** Write-through update of the entitlements cache after a refresh (login / TTL / cron / webhook). */
+  async setEntitlements(provider: string, subject_id: string, data: Record<string, any>, checked_at: number): Promise<{ success: boolean }> {
+    this.sql.exec(
+      'INSERT OR REPLACE INTO entitlements_cache (provider, subject_id, data, checked_at) VALUES (?, ?, ?, ?)',
+      provider,
+      subject_id,
+      JSON.stringify(data),
+      checked_at,
+    );
+    return { success: true };
+  }
+
   async listCredentials(): Promise<any[]> {
     const credentialsMapping = this.sql.exec('SELECT DISTINCT provider FROM user_credentials');
     const credentials = [];