@startup-api/cloudflare 0.0.1 → 0.1.0

package/README.md

@@ -67,6 +67,11 @@ Use this option if you want to deploy from your local machine.
 | `GOOGLE_CLIENT_SECRET` | No       | N/A       | Google OAuth2 Client Secret                                                   |
 | `TWITCH_CLIENT_ID`     | No       | N/A       | Twitch OAuth2 Client ID                                                       |
 | `TWITCH_CLIENT_SECRET` | No       | N/A       | Twitch OAuth2 Client Secret                                                   |
+| `PATREON_CLIENT_ID`    | No       | N/A       | Patreon OAuth2 Client ID                                                      |
+| `PATREON_CLIENT_SECRET`| No       | N/A       | Patreon OAuth2 Client Secret                                                  |
+| `PATREON_WEBHOOK_SECRET`| No      | N/A       | Secret for verifying Patreon webhook signatures                              |
+
+> Environment variables hold only credentials/secrets (OAuth client IDs and all secrets) plus the per‑deployment values `ORIGIN_URL`, `AUTH_ORIGIN`, `USERS_PATH`, `ADMIN_IDS`, and `ENVIRONMENT`. **All other configuration — OAuth scopes, Patreon campaign id, the access policy, entitlement freshness — is passed to the `createStartupAPI` factory** (see [Access policy & provider entitlements](#access-policy--provider-entitlements)).
 
 ### Setting up OAuth
 
@@ -88,6 +93,28 @@ Use this option if you want to deploy from your local machine.
 4. Select **Website** as the category
 5. Copy the **Client ID** and generate a **Client Secret** to add them to your Worker's environment variables
 
+#### Patreon
+
+1. Go to the [Patreon Developer Portal](https://www.patreon.com/portal/registration/register-clients)
+2. Click **Create Client** and fill in your app details
+3. Add your authorized redirect URI: `https://<your-worker-url>/users/auth/patreon/callback`
+4. Copy the **Client ID** and **Client Secret** and add them to your Worker's environment variables
+
+#### Requesting additional scopes
+
+Each provider requests the minimal scopes needed to sign a user in and read their basic profile. To request more (for example, to read a user's Patreon memberships), set the provider's `scopes` in the factory config (a string or array). The extra scopes are merged with the required base scopes:
+
+```ts
+import { createStartupAPI } from '@startup-api/cloudflare';
+
+const api = createStartupAPI({
+  providers: {
+    // Adds `identity.memberships` on top of the base `identity identity[email]`
+    patreon: { scopes: 'identity.memberships' },
+  },
+});
+```
+
 ### Example `wrangler.jsonc` snippet:
 
 ```json
@@ -105,6 +132,82 @@ Use this option if you want to deploy from your local machine.
 3. **Proxying:** All other requests are proxied to the configured `ORIGIN_URL`
 4. **Injection:** For `text/html` responses, the worker injects a `<script>` tag and a `<power-strip>` custom element before serving the content to the user
 
+## Access policy & provider entitlements
+
+StartupAPI can gate access to paths and forward the visitor's login/entitlement status to your origin so it can render gated UI. This is **provider-agnostic infrastructure**; only Patreon currently implements perk-level (benefit/tier) checks — Google and Twitch participate at the login levels only.
+
+### Path-based access policy
+
+Configure an ordered list of rules (first match wins) mapping a path pattern to a requirement, plus a `default` for unmatched paths. Requirement modes:
+
+- **`bypass`** — raw pass-through: no credential check, no identity resolution, no headers, no power-strip injection.
+- **`public`** — anyone; the session is resolved and identity/entitlement headers are forwarded when present.
+- **`authenticated`** — any logged-in user.
+- **`entitlement`** — a provider condition: Patreon `active_patron`, a specific `benefit` (perk) ID, or a `tier` ID.
+
+Patterns are exact (`/special`), prefix (`/app/*`), or `/` (homepage only). Each rule's `on_unauthorized` is `login` (redirect to sign in), `forbidden` (403), or `upgrade` (redirect to `upgrade_url`, e.g. a Patreon join page). When no policy is configured at all, every path is treated as `public` (backward compatible).
+
+The policy is passed to the factory as `accessPolicy` (see below). Example:
+
+```ts
+const accessPolicy = {
+  rules: [
+    { pattern: '/', requirement: { mode: 'public' } },
+    {
+      pattern: '/special',
+      requirement: { mode: 'entitlement', provider: 'patreon', condition: { type: 'benefit', benefit_id: '<BENEFIT_ID>' } },
+      on_unauthorized: 'upgrade',
+      upgrade_url: 'https://www.patreon.com/yourpage',
+    },
+  ],
+  default: { mode: 'entitlement', provider: 'patreon', condition: { type: 'active_patron' } },
+};
+```
+
+### Headers forwarded to the origin
+
+For non-`bypass` paths the worker forwards `X-StartupAPI-Authenticated`, `X-StartupAPI-Login-Provider`, a compact `X-StartupAPI-Entitlements` JSON, and (for Patreon) `X-StartupAPI-Patreon-Active` / `-Tiers` / `-Benefits` alongside the existing `X-StartupAPI-User-Id` / `-Account-Id`.
+
+### Keeping entitlements fresh
+
+Entitlements are fetched once at login. Each provider can additionally opt into freshness mechanisms in its factory config (all off by default — if none are enabled, entitlements are only checked at login):
+
+- **TTL** — lazily re-check on the request path when older than the TTL (`freshness.ttl: { ms }`, default 15 min), using the OAuth refresh token.
+- **Cron** — a scheduled re-sync of all of a provider's credentials (`freshness.cron: { schedule }`). The `scheduled()` handler is only present when at least one provider enables cron; you must also add a matching `triggers.crons` to your wrangler config.
+- **Webhook** (Patreon only) — set `freshness.webhook: true`, provide `PATREON_WEBHOOK_SECRET` (a secret, in env), and point a Patreon webhook at `<your-worker-url>/users/webhooks/patreon` (signature verified with HMAC-MD5).
+
+Set `providers.patreon.campaignId` to disambiguate when a user belongs to multiple campaigns.
+
+### Configuring via the factory
+
+Environment variables hold only credentials/secrets and the per-deployment values (`ORIGIN_URL`, `AUTH_ORIGIN`, `USERS_PATH`, `ADMIN_IDS`, `ENVIRONMENT`). Everything else — provider scopes, Patreon campaign id, the access policy, and entitlement freshness — is passed to `createStartupAPI(config)`. The plain re-export still works with defaults:
+
+```ts
+// Defaults — unchanged:
+export { default, UserDO, AccountDO, SystemDO, CredentialDO } from '@startup-api/cloudflare';
+```
+
+```ts
+// Custom configuration:
+import { createStartupAPI } from '@startup-api/cloudflare';
+
+const api = createStartupAPI({
+  providers: {
+    patreon: {
+      scopes: 'identity.memberships',
+      campaignId: '<CAMPAIGN_ID>',
+      freshness: { ttl: true, cron: { schedule: '0 */6 * * *' }, webhook: true },
+    },
+  },
+  accessPolicy: { rules: [/* ... */], default: { mode: 'public' } },
+});
+
+export default api.default; // includes scheduled() because cron is enabled
+export const { UserDO, AccountDO, SystemDO, CredentialDO } = api;
+```
+
+(Remember to add `triggers.crons` to your wrangler config when enabling cron.)
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startup-api/cloudflare",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"

package/public/users/power-strip.js

@@ -93,6 +93,8 @@ class PowerStrip extends HTMLElement {
               </svg>`;
     } else if (provider === 'twitch') {
       return `<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="11" fill="#9146FF" stroke="white" stroke-width="1"/><path d="M7 6H6v10h2v3l3-3h3l4-4V6H7zm9 6l-2 2h-3l-2 2v-2H8V7h8v5z" fill="white"/><path d="M14 8.5h1.5v2H14V8.5zm-3 0h1.5v2H11v-2z" fill="white"/></svg>`;
+    } else if (provider === 'patreon') {
+      return `<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="11" fill="#FF424D" stroke="white" stroke-width="1"/><circle cx="14" cy="11" r="3.5" fill="white"/><rect x="6.5" y="6.5" width="2" height="11" fill="white"/></svg>`;
     }
     return '';
   }
@@ -101,6 +103,7 @@ class PowerStrip extends HTMLElement {
     const returnUrl = encodeURIComponent(window.location.href);
     const googleLink = `${this.basePath}/auth/google?return_url=${returnUrl}`;
     const twitchLink = `${this.basePath}/auth/twitch?return_url=${returnUrl}`;
+    const patreonLink = `${this.basePath}/auth/patreon?return_url=${returnUrl}`;
     const logoutLink = `${this.basePath}/logout?return_url=${returnUrl}`;
 
     const providersStr = this.getAttribute('providers') || '';
@@ -128,6 +131,15 @@ class PowerStrip extends HTMLElement {
                     Continue with Twitch
                 </a>`;
     }
+    if (providers.includes('patreon')) {
+      authButtons += `
+                <a href="${patreonLink}" class="auth-btn patreon">
+                    <svg viewBox="0 0 24 24">
+                      <path d="M14.82 2.41c3.96 0 7.18 3.24 7.18 7.21 0 3.96-3.22 7.18-7.18 7.18-3.97 0-7.21-3.22-7.21-7.18 0-3.97 3.24-7.21 7.21-7.21M2 21.6h3.5V2.41H2V21.6z" fill="currentColor"/>
+                    </svg>
+                    Continue with Patreon
+                </a>`;
+    }
 
     let content = '';
     let accountSwitcher = '';
@@ -329,6 +341,7 @@ class PowerStrip extends HTMLElement {
 
         .provider-badge.google { color: #3c4043; }
         .provider-badge.twitch { color: #9146FF; }
+        .provider-badge.patreon { color: #FF424D; }
 
         .user-info {
             display: flex;
@@ -506,7 +519,17 @@ class PowerStrip extends HTMLElement {
             background-color: #7d2ee6;
             border-color: #7d2ee6;
         }
-        
+
+        .auth-btn.patreon {
+            background-color: #FF424D;
+            color: white;
+            border-color: #FF424D;
+        }
+        .auth-btn.patreon:hover {
+            background-color: #e63a44;
+            border-color: #e63a44;
+        }
+
         /* Account Switcher Styling */
         .account-list {
             display: flex;

package/public/users/profile.html

@@ -432,6 +432,10 @@
           return `<svg viewBox="0 0 24 24" width="24" height="24" style="color: #9146FF;">
                     <path d="M11.571 4.714h1.715v5.143H11.57zm4.715 0H18v5.143h-1.714zM6 0L1.714 4.286v15.428h5.143V24l4.286-4.286h3.428L22.286 12V0zm14.571 11.143l-3.428 3.428h-3.429l-3 3v-3H6.857V1.714h13.714z" fill="currentColor"/>
                   </svg>`;
+        } else if (provider === 'patreon') {
+          return `<svg viewBox="0 0 24 24" width="24" height="24" style="color: #FF424D;">
+                    <path d="M14.82 2.41c3.96 0 7.18 3.24 7.18 7.21 0 3.96-3.22 7.18-7.18 7.18-3.97 0-7.21-3.22-7.21-7.18 0-3.97 3.24-7.21 7.21-7.21M2 21.6h3.5V2.41H2V21.6z" fill="currentColor"/>
+                  </svg>`;
         }
         return '';
       }

package/src/StartupAPIEnv.ts

@@ -6,6 +6,9 @@ export type StartupAPIEnv = {
   GOOGLE_CLIENT_SECRET: string;
   TWITCH_CLIENT_ID: string;
   TWITCH_CLIENT_SECRET: string;
+  PATREON_CLIENT_ID: string;
+  PATREON_CLIENT_SECRET: string;
+  PATREON_WEBHOOK_SECRET?: string;
   ADMIN_IDS: string;
   SESSION_SECRET: string;
   ENVIRONMENT?: string;

package/src/auth/GoogleProvider.ts

@@ -1,11 +1,18 @@
 import type { StartupAPIEnv } from '../StartupAPIEnv';
+import type { ProviderOptions } from '../schemas/config';
 
 import { OAuthProvider, OAuthTokenResponse, UserProfile } from './OAuthProvider';
 
 export class GoogleProvider extends OAuthProvider {
-  static create(env: StartupAPIEnv, redirectBase: string): GoogleProvider | null {
+  static create(env: StartupAPIEnv, redirectBase: string, options?: ProviderOptions): GoogleProvider | null {
     if (!env.GOOGLE_CLIENT_ID || !env.GOOGLE_CLIENT_SECRET) return null;
-    return new GoogleProvider(env.GOOGLE_CLIENT_ID, env.GOOGLE_CLIENT_SECRET, redirectBase + '/google/callback', 'google');
+    return new GoogleProvider(
+      env.GOOGLE_CLIENT_ID,
+      env.GOOGLE_CLIENT_SECRET,
+      redirectBase + '/google/callback',
+      'google',
+      options?.scopes,
+    );
   }
 
   getAuthUrl(state: string): string {
@@ -13,7 +20,7 @@ export class GoogleProvider extends OAuthProvider {
       client_id: this.clientId,
       redirect_uri: this.redirectUri,
       response_type: 'code',
-      scope: 'openid email profile',
+      scope: this.buildScope(['openid', 'email', 'profile']),
       state: state,
       access_type: 'offline',
       prompt: 'consent',

package/src/auth/OAuthProvider.ts

@@ -15,17 +15,39 @@ export interface UserProfile {
   verified_email?: boolean;
 }
 
+import type { Entitlements } from '../entitlements/types';
+
 export abstract class OAuthProvider {
   protected clientId: string;
   protected clientSecret: string;
   protected redirectUri: string;
   public name: string;
+  protected additionalScopes: string[];
 
-  constructor(clientId: string, clientSecret: string, redirectUri: string, name: string) {
+  constructor(clientId: string, clientSecret: string, redirectUri: string, name: string, additionalScopes: string | string[] = []) {
     this.clientId = clientId.trim();
     this.clientSecret = clientSecret.trim();
     this.redirectUri = redirectUri.trim();
     this.name = name.trim();
+    // Accept a single scope string or a list; buildScope() trims and dedupes.
+    this.additionalScopes = Array.isArray(additionalScopes) ? additionalScopes : [additionalScopes];
+  }
+
+  /**
+   * Merge a provider's required base scopes with the configured additional scopes,
+   * preserving order and removing duplicates.
+   */
+  protected buildScope(defaultScopes: string[], separator = ' '): string {
+    const seen = new Set<string>();
+    const merged: string[] = [];
+    for (const scope of [...defaultScopes, ...this.additionalScopes]) {
+      const trimmed = scope.trim();
+      if (trimmed && !seen.has(trimmed)) {
+        seen.add(trimmed);
+        merged.push(trimmed);
+      }
+    }
+    return merged.join(separator);
   }
 
   isMatch(path: string, authBasePath: string): boolean {
@@ -41,6 +63,31 @@ export abstract class OAuthProvider {
   abstract getToken(code: string): Promise<OAuthTokenResponse>;
   abstract getUserProfile(token: string): Promise<UserProfile>;
 
+  /**
+   * Whether this provider produces entitlements (memberships / perks). Providers that gate access on
+   * provider-specific conditions (e.g. Patreon) override this to return true. Default: false.
+   */
+  supportsEntitlements(): boolean {
+    return false;
+  }
+
+  /**
+   * Fetch the user's current entitlements using a valid access token. Returns the provider-specific
+   * portion of the {@link Entitlements} shape (without `checked_at`/`source`, which the caller stamps).
+   * Default: null (provider has no entitlements).
+   */
+  async fetchEntitlements(_accessToken: string): Promise<Partial<Entitlements> | null> {
+    return null;
+  }
+
+  /**
+   * Exchange a refresh token for a fresh access token. Providers that issue refresh tokens override
+   * this. Default: null (no refresh support).
+   */
+  async refreshToken(_refreshToken: string): Promise<OAuthTokenResponse | null> {
+    return null;
+  }
+
   protected async fetchJson<T>(url: string, options?: RequestInit): Promise<T> {
     const response = await fetch(url, options);
     if (!response.ok) {

package/src/auth/PatreonProvider.ts

@@ -0,0 +1,124 @@
+import type { StartupAPIEnv } from '../StartupAPIEnv';
+import type { ProviderOptions } from '../schemas/config';
+
+import { OAuthProvider, OAuthTokenResponse, UserProfile } from './OAuthProvider';
+import type { Entitlements } from '../entitlements/types';
+import { parsePatreonIdentity } from '../entitlements/patreon';
+
+export class PatreonProvider extends OAuthProvider {
+  private campaignId?: string;
+
+  static create(env: StartupAPIEnv, redirectBase: string, options?: ProviderOptions): PatreonProvider | null {
+    if (!env.PATREON_CLIENT_ID || !env.PATREON_CLIENT_SECRET) return null;
+    const provider = new PatreonProvider(
+      env.PATREON_CLIENT_ID,
+      env.PATREON_CLIENT_SECRET,
+      redirectBase + '/patreon/callback',
+      'patreon',
+      options?.scopes,
+    );
+    provider.campaignId = options?.campaignId?.trim() || undefined;
+    return provider;
+  }
+
+  supportsEntitlements(): boolean {
+    return true;
+  }
+
+  getAuthUrl(state: string): string {
+    const params = new URLSearchParams({
+      client_id: this.clientId,
+      redirect_uri: this.redirectUri,
+      response_type: 'code',
+      scope: this.buildScope(['identity', 'identity[email]']),
+      state: state,
+    });
+    return `https://www.patreon.com/oauth2/authorize?${params.toString()}`;
+  }
+
+  getIcon(): string {
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+      <circle cx="12" cy="12" r="11" fill="#FF424D" stroke="white" stroke-width="1"/>
+      <circle cx="14" cy="11" r="3.5" fill="white"/>
+      <rect x="6.5" y="6.5" width="2" height="11" fill="white"/>
+    </svg>`;
+  }
+
+  async getToken(code: string): Promise<OAuthTokenResponse> {
+    const params = new URLSearchParams({
+      code,
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      redirect_uri: this.redirectUri,
+      grant_type: 'authorization_code',
+    });
+
+    return this.fetchJson<OAuthTokenResponse>('https://www.patreon.com/api/oauth2/token', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: params.toString(),
+    });
+  }
+
+  async getUserProfile(accessToken: string): Promise<UserProfile> {
+    const params = new URLSearchParams({
+      'fields[user]': 'email,full_name,image_url,is_email_verified',
+    });
+
+    const data = await this.fetchJson<{
+      data: {
+        id: string;
+        attributes: { email?: string; full_name?: string; image_url?: string; is_email_verified?: boolean };
+      };
+    }>(`https://www.patreon.com/api/oauth2/v2/identity?${params.toString()}`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+
+    const user = data.data;
+    return {
+      id: user.id,
+      email: user.attributes.email,
+      name: user.attributes.full_name,
+      picture: user.attributes.image_url,
+      verified_email: user.attributes.is_email_verified,
+    };
+  }
+
+  async refreshToken(refreshToken: string): Promise<OAuthTokenResponse> {
+    const params = new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+    });
+
+    return this.fetchJson<OAuthTokenResponse>('https://www.patreon.com/api/oauth2/token', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: params.toString(),
+    });
+  }
+
+  async fetchEntitlements(accessToken: string): Promise<Partial<Entitlements>> {
+    const params = new URLSearchParams({
+      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',
+    });
+
+    const data = await this.fetchJson<any>(`https://www.patreon.com/api/oauth2/v2/identity?${params.toString()}`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+
+    return { patreon: parsePatreonIdentity(data, this.campaignId) };
+  }
+}

package/src/auth/TwitchProvider.ts

@@ -1,11 +1,18 @@
 import type { StartupAPIEnv } from '../StartupAPIEnv';
+import type { ProviderOptions } from '../schemas/config';
 
 import { OAuthProvider, OAuthTokenResponse, UserProfile } from './OAuthProvider';
 
 export class TwitchProvider extends OAuthProvider {
-  static create(env: StartupAPIEnv, redirectBase: string): TwitchProvider | null {
+  static create(env: StartupAPIEnv, redirectBase: string, options?: ProviderOptions): TwitchProvider | null {
     if (!env.TWITCH_CLIENT_ID || !env.TWITCH_CLIENT_SECRET) return null;
-    return new TwitchProvider(env.TWITCH_CLIENT_ID, env.TWITCH_CLIENT_SECRET, redirectBase + '/twitch/callback', 'twitch');
+    return new TwitchProvider(
+      env.TWITCH_CLIENT_ID,
+      env.TWITCH_CLIENT_SECRET,
+      redirectBase + '/twitch/callback',
+      'twitch',
+      options?.scopes,
+    );
   }
 
   getAuthUrl(state: string): string {
@@ -13,7 +20,7 @@ export class TwitchProvider extends OAuthProvider {
       client_id: this.clientId,
       redirect_uri: this.redirectUri,
       response_type: 'code',
-      scope: 'user:read:email',
+      scope: this.buildScope(['user:read:email']),
       state: state,
     });
     return `https://id.twitch.tv/oauth2/authorize?${params.toString()}`;

package/src/auth/index.ts

@@ -1,9 +1,9 @@
 import type { StartupAPIEnv } from '../StartupAPIEnv';
 
-import { GoogleProvider } from './GoogleProvider';
-import { TwitchProvider } from './TwitchProvider';
-import { OAuthProvider } from './OAuthProvider';
 import { CookieManager } from '../CookieManager';
+import { refreshEntitlements } from '../entitlements/service';
+import { computeRedirectBase, createProviders } from './providers';
+import type { ProviderConfigs } from './providers';
 
 export async function handleAuth(
   request: Request,
@@ -11,21 +11,19 @@ export async function handleAuth(
   url: URL,
   usersPath: string,
   cookieManager: CookieManager,
+  providerConfigs: ProviderConfigs = {},
 ): Promise<Response> {
   const path = url.pathname;
   const origin = env.AUTH_ORIGIN && env.AUTH_ORIGIN !== '' ? env.AUTH_ORIGIN : url.origin;
 
   // Standardize redirectBase
-  const baseUsersPath = usersPath.startsWith('/') ? usersPath : '/' + usersPath;
-  const redirectBase = new URL((baseUsersPath.endsWith('/') ? baseUsersPath : baseUsersPath + '/') + 'auth', origin).toString();
+  const redirectBase = computeRedirectBase(env, origin, usersPath);
 
   // For internal matching, we still need authPath
   const authPath = new URL(redirectBase).pathname;
 
-  // Instantiate providers
-  const providers: (OAuthProvider | null)[] = [GoogleProvider.create(env, redirectBase), TwitchProvider.create(env, redirectBase)];
-
-  const activeProviders = providers.filter((p): p is OAuthProvider => p !== null);
+  // Instantiate active providers
+  const activeProviders = createProviders(env, redirectBase, providerConfigs);
 
   // Handle Auth Start
   for (const provider of activeProviders) {
@@ -156,6 +154,30 @@ export async function handleAuth(
         // Register credential mapping in UserDO
         await userStub.addCredential(provider.name, profile.id);
 
+        // Login-time entitlement fetch: providers that support entitlements (e.g. Patreon) get an
+        // initial entitlement snapshot now, so gating works even when no freshness mechanism is
+        // configured. Best-effort — never block or fail login on an entitlement error.
+        if (provider.supportsEntitlements()) {
+          try {
+            await refreshEntitlements(
+              env,
+              provider,
+              {
+                subject_id: profile.id,
+                user_id: userIdStr,
+                access_token: token.access_token,
+                refresh_token: token.refresh_token,
+                expires_at: token.expires_in ? Date.now() + token.expires_in * 1000 : undefined,
+                scope: typeof token.scope === 'string' ? token.scope : undefined,
+                profile_data: profile,
+              },
+              'oauth',
+            );
+          } catch (e) {
+            console.error('[auth] Login-time entitlement fetch failed', e);
+          }
+        }
+
         // Register User in SystemDO index (Only for new users)
         if (isNewUser) {
           await userStub.updateProfile(profile);

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);
+}