@startup-api/cloudflare 0.3.2 → 0.4.0

package/README.md

@@ -70,6 +70,8 @@ Either way, set your production secrets (`SESSION_SECRET`, OAuth credentials) on
 | `PATREON_CLIENT_SECRET`  | No       | N/A       | Patreon OAuth2 Client Secret                                                  |
 | `PATREON_WEBHOOK_SECRET` | No       | N/A       | Secret for verifying Patreon webhook signatures                               |
 
+> AT Protocol (Bluesky) login needs **no environment variables at all** — it is a public OAuth client with no secret, so it is configured entirely through the `createStartupAPI` factory (see [Bluesky / AT Protocol](#bluesky--at-protocol-atproto) below).
+
 > 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
@@ -99,6 +101,46 @@ Either way, set your production secrets (`SESSION_SECRET`, OAuth credentials) on
 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
 
+#### Bluesky / AT Protocol (atproto)
+
+atproto login is decentralized: there is **no central provider to register with and no client secret**. Instead the worker acts as a [public OAuth client](https://atproto.com/specs/oauth) identified by a client-metadata document it serves itself, and it discovers the right authorization server **per user** from their handle or DID — so it works with `bsky.social` and any self-hosted PDS alike, with no Bluesky host hardcoded.
+
+Because it has no secrets, atproto is configured **entirely through the `createStartupAPI` factory** (not env vars). Just like the env-credential providers are enabled by the presence of their credentials, atproto is enabled simply by **including its config key** — an empty object is enough:
+
+```ts
+import { createStartupAPI } from '@startup-api/cloudflare';
+
+const api = createStartupAPI({
+  providers: {
+    atproto: {}, // including the key enables it — no client id/secret needed
+    // All fields below are optional:
+    // atproto: {
+    //   clientName: 'My App',           // shown on the consent screen (default "StartupAPI")
+    //   plcUrl: 'https://plc.directory', // override the PLC directory for did:plc
+    //   dohUrl: 'https://cloudflare-dns.com/dns-query', // override the DoH resolver
+    //   scopes: 'transition:generic',    // extra scopes on top of the base `atproto`
+    //   enabled: false,                  // explicit opt-out (e.g. for dynamically-built config)
+    // },
+  },
+});
+
+export default api.default;
+export const { UserDO, AccountDO, SystemDO, CredentialDO } = api;
+```
+
+1. Include `atproto: {}` in the factory `providers` config (no client id/secret needed). Pass `enabled: false` to opt out explicitly.
+2. Deploy over **HTTPS** with a stable hostname. The worker automatically serves its client metadata at `https://<your-worker-url>/users/auth/atproto/client-metadata.json` (this URL is the OAuth `client_id`) and registers the redirect URI `https://<your-worker-url>/users/auth/atproto/callback`.
+3. That's it. When a visitor clicks **Continue with Bluesky**, they're asked for their handle (e.g. `alice.bsky.social`) or DID; the worker then resolves it through the full atproto discovery chain and redirects them to _their own_ server to sign in:
+
+   ```
+   handle ─▶ DID            (HTTPS .well-known/atproto-did, then DNS _atproto.<handle> via DoH)
+   DID    ─▶ DID document   (did:plc via the PLC directory, did:web via the domain)
+   DID doc─▶ PDS endpoint    (the #atproto_pds service)
+   PDS    ─▶ auth server     (.well-known/oauth-protected-resource → oauth-authorization-server)
+   ```
+
+The flow uses PKCE, DPoP-bound (sender-constrained) tokens, and Pushed Authorization Requests (PAR) as required by the atproto OAuth profile. The PLC directory and DNS-over-HTTPS resolver are generic infrastructure and can be overridden via the `plcUrl` / `dohUrl` factory options.
+
 #### 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:

package/package.json

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

package/public/users/power-strip.js

@@ -212,6 +212,8 @@ class PowerStrip extends HTMLElement {
       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>`;
+    } else if (provider === 'atproto') {
+      return `<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="11" fill="#0085FF" stroke="white" stroke-width="1"/><path d="M12 10.5C10.9 8.4 8.2 6.3 6.3 6c-1.5-.2-1.8.7-1.5 2 .2 1 1.5 5 2.3 6 .9 1.2 2 1.4 3 1.2-1.7.3-3.2 1-1.2 3 .9.9 1.6.3 2.1-.6.5-1 .8-2.1 1-2.6.2.5.5 1.6 1 2.6.5.9 1.2 1.5 2.1.6 2-2 .5-2.7-1.2-3 1 .2 2.1 0 3-1.2.8-1 2.1-5 2.3-6 .3-1.3 0-2.2-1.5-2-1.9.3-4.6 2.4-5.7 4.5z" fill="white"/></svg>`;
     }
     return '';
   }
@@ -221,6 +223,7 @@ class PowerStrip extends HTMLElement {
     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 atprotoLink = `${this.basePath}/auth/atproto?return_url=${returnUrl}`;
     const logoutLink = `${this.basePath}/logout?return_url=${returnUrl}`;
 
     const providersStr = this.getAttribute('providers') || '';
@@ -257,6 +260,15 @@ class PowerStrip extends HTMLElement {
                     Continue with Patreon
                 </a>`;
     }
+    if (providers.includes('atproto')) {
+      authButtons += `
+                <a href="${atprotoLink}" class="auth-btn atproto">
+                    <svg viewBox="0 0 24 24">
+                      <path d="M12 10.5C10.9 8.4 8.2 6.3 6.3 6c-1.5-.2-1.8.7-1.5 2 .2 1 1.5 5 2.3 6 .9 1.2 2 1.4 3 1.2-1.7.3-3.2 1-1.2 3 .9.9 1.6.3 2.1-.6.5-1 .8-2.1 1-2.6.2.5.5 1.6 1 2.6.5.9 1.2 1.5 2.1.6 2-2 .5-2.7-1.2-3 1 .2 2.1 0 3-1.2.8-1 2.1-5 2.3-6 .3-1.3 0-2.2-1.5-2-1.9.3-4.6 2.4-5.7 4.5z" fill="currentColor"/>
+                    </svg>
+                    Continue with Bluesky
+                </a>`;
+    }
 
     let content = '';
     let accountSwitcher = '';
@@ -585,6 +597,7 @@ class PowerStrip extends HTMLElement {
         .provider-badge.google { color: #3c4043; }
         .provider-badge.twitch { color: #9146FF; }
         .provider-badge.patreon { color: #FF424D; }
+        .provider-badge.atproto { color: #0085FF; }
 
         .user-info {
             display: flex;
@@ -773,6 +786,16 @@ class PowerStrip extends HTMLElement {
             border-color: #e63a44;
         }
 
+        .auth-btn.atproto {
+            background-color: #0085FF;
+            color: white;
+            border-color: #0085FF;
+        }
+        .auth-btn.atproto:hover {
+            background-color: #006fd6;
+            border-color: #006fd6;
+        }
+
         /* Account Switcher Styling */
         .account-list {
             display: flex;

package/public/users/profile.html

@@ -433,6 +433,10 @@
           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>`;
+        } else if (provider === 'atproto') {
+          return `<svg viewBox="0 0 24 24" width="24" height="24" style="color: #0085FF;">
+                    <path d="M12 10.5C10.9 8.4 8.2 6.3 6.3 6c-1.5-.2-1.8.7-1.5 2 .2 1 1.5 5 2.3 6 .9 1.2 2 1.4 3 1.2-1.7.3-3.2 1-1.2 3 .9.9 1.6.3 2.1-.6.5-1 .8-2.1 1-2.6.2.5.5 1.6 1 2.6.5.9 1.2 1.5 2.1.6 2-2 .5-2.7-1.2-3 1 .2 2.1 0 3-1.2.8-1 2.1-5 2.3-6 .3-1.3 0-2.2-1.5-2-1.9.3-4.6 2.4-5.7 4.5z" fill="currentColor"/>
+                  </svg>`;
         }
         return '';
       }

package/src/auth/AtprotoProvider.ts

@@ -0,0 +1,282 @@
+import type { StartupAPIEnv } from '../StartupAPIEnv';
+import type { ProviderOptions } from '../schemas/config';
+
+import { OAuthProvider, type AuthContext, type ExchangeResult, type OAuthTokenResponse, type UserProfile } from './OAuthProvider';
+import { dpopFetch, generateDpopKey, generatePkce, randomToken } from './atproto/crypto';
+import { fetchProfile, resolveIdentity, type ResolverOptions } from './atproto/identity';
+
+const FLOW_COOKIE = 'atproto_flow';
+// Transient flow state lives only for the duration of the redirect round-trip.
+const FLOW_TTL_SECONDS = 600;
+
+/**
+ * Encrypted, cookie-stored state that must survive the redirect from the authorization server back to
+ * our callback: the PKCE verifier, the DPoP private key, the latest DPoP nonce, and the dynamically
+ * discovered endpoints/identity for this specific user.
+ */
+interface AtprotoFlowState {
+  state: string;
+  verifier: string;
+  dpopKey: JsonWebKey;
+  dpopNonce?: string;
+  issuer: string;
+  tokenEndpoint: string;
+  pds: string;
+  did: string;
+  handle?: string;
+  returnUrl: string | null;
+}
+
+/**
+ * Whether the atproto provider is turned on. It has no client secret (public OAuth client), so — like
+ * the env-credential providers are enabled by the presence of their credentials — atproto is enabled
+ * simply by including its config key (`providers: { atproto: {} }`). Pass `enabled: false` to opt out
+ * explicitly (e.g. when the config is built dynamically).
+ */
+export function isAtprotoEnabled(options?: ProviderOptions): boolean {
+  return options !== undefined && options.enabled !== false;
+}
+
+/**
+ * AT Protocol (Bluesky and any atproto PDS) authentication.
+ *
+ * Unlike the classic OAuth2 providers, atproto requires PKCE, DPoP-bound tokens, Pushed Authorization
+ * Requests (PAR), and per-user dynamic endpoints discovered from the identity (handle → DID → PDS →
+ * authorization server). It is a "public" OAuth client identified by a hosted client-metadata document
+ * (served at `…/auth/atproto/client-metadata.json`) rather than a client id/secret.
+ */
+export class AtprotoProvider extends OAuthProvider {
+  /** The public client id, i.e. the URL of this client's metadata document. */
+  private clientMetadataUrl = '';
+  private clientUri = '';
+  private clientName = 'StartupAPI';
+  private resolverOptions: ResolverOptions = {};
+
+  static create(_env: StartupAPIEnv, redirectBase: string, options?: ProviderOptions): AtprotoProvider | null {
+    if (!isAtprotoEnabled(options)) return null;
+    const provider = new AtprotoProvider('', '', redirectBase + '/atproto/callback', 'atproto', options?.scopes);
+    provider.clientMetadataUrl = redirectBase + '/atproto/client-metadata.json';
+    provider.clientUri = new URL(redirectBase).origin;
+    provider.clientName = options?.clientName?.trim() || 'StartupAPI';
+    provider.resolverOptions = {
+      plcUrl: options?.plcUrl?.trim() || undefined,
+      dohUrl: options?.dohUrl?.trim() || undefined,
+    };
+    return provider;
+  }
+
+  getIcon(): string {
+    // AT Protocol / Bluesky butterfly mark.
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+      <circle cx="12" cy="12" r="11" fill="#0085FF" stroke="white" stroke-width="1"/>
+      <path d="M12 10.5C10.9 8.4 8.2 6.3 6.3 6c-1.5-.2-1.8.7-1.5 2 .2 1 1.5 5 2.3 6 .9 1.2 2 1.4 3 1.2-1.7.3-3.2 1-1.2 3 .9.9 1.6.3 2.1-.6.5-1 .8-2.1 1-2.6.2.5.5 1.6 1 2.6.5.9 1.2 1.5 2.1.6 2-2 .5-2.7-1.2-3 1 .2 2.1 0 3-1.2.8-1 2.1-5 2.3-6 .3-1.3 0-2.2-1.5-2-1.9.3-4.6 2.4-5.7 4.5z" fill="white"/>
+    </svg>`;
+  }
+
+  /** The OAuth client metadata document (public client, DPoP-bound tokens). */
+  getClientMetadata(): Record<string, unknown> {
+    return {
+      client_id: this.clientMetadataUrl,
+      client_name: this.clientName,
+      client_uri: this.clientUri,
+      redirect_uris: [this.redirectUri],
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+      scope: this.buildScope(['atproto']),
+      token_endpoint_auth_method: 'none',
+      application_type: 'web',
+      dpop_bound_access_tokens: true,
+    };
+  }
+
+  async handleExtraRoute(ctx: AuthContext): Promise<Response | null> {
+    if (ctx.url.pathname === `${ctx.authPath}/atproto/client-metadata.json`) {
+      return Response.json(this.getClientMetadata());
+    }
+    return null;
+  }
+
+  /**
+   * Authorization start. Requires an identifier (`?handle=`); without one we serve a small handle-entry
+   * form (the standard atproto UX) so we never hardcode any authorization server. With a handle we
+   * resolve the identity, run a DPoP-protected PAR, persist the flow state in an encrypted cookie, and
+   * redirect to the discovered authorization endpoint.
+   */
+  async authorize(ctx: AuthContext): Promise<Response> {
+    const identifier = ctx.url.searchParams.get('handle');
+    const returnUrl = ctx.url.searchParams.get('return_url');
+    if (!identifier || !identifier.trim()) {
+      return this.renderHandleForm(ctx, returnUrl);
+    }
+
+    const identity = await resolveIdentity(identifier, this.resolverOptions);
+    const { verifier, challenge } = await generatePkce();
+    const dpopKey = await generateDpopKey();
+    const state = randomToken(16);
+    const scope = this.buildScope(['atproto']);
+
+    // Pushed Authorization Request: hand the request parameters to the authorization server up front
+    // and receive an opaque request_uri to send the user to. DPoP is required.
+    const parBody = new URLSearchParams({
+      client_id: this.clientMetadataUrl,
+      redirect_uri: this.redirectUri,
+      response_type: 'code',
+      code_challenge: challenge,
+      code_challenge_method: 'S256',
+      state,
+      scope,
+      login_hint: identity.handle ?? identity.did,
+    });
+
+    const { res, nonce } = await dpopFetch(
+      identity.authServer.pushed_authorization_request_endpoint,
+      { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: parBody.toString() },
+      dpopKey,
+    );
+    if (!res.ok) {
+      throw new Error(`Pushed authorization request failed: ${res.status} ${await res.text()}`);
+    }
+    const par = (await res.json()) as { request_uri: string };
+
+    const flow: AtprotoFlowState = {
+      state,
+      verifier,
+      dpopKey,
+      dpopNonce: nonce,
+      issuer: identity.authServer.issuer,
+      tokenEndpoint: identity.authServer.token_endpoint,
+      pds: identity.pds,
+      did: identity.did,
+      handle: identity.handle,
+      returnUrl,
+    };
+    const encrypted = await ctx.cookieManager.encrypt(JSON.stringify(flow));
+
+    const authUrl = new URL(identity.authServer.authorization_endpoint);
+    authUrl.searchParams.set('client_id', this.clientMetadataUrl);
+    authUrl.searchParams.set('request_uri', par.request_uri);
+
+    const headers = new Headers();
+    headers.set('Location', authUrl.toString());
+    headers.append(
+      'Set-Cookie',
+      `${FLOW_COOKIE}=${encrypted}; Path=${ctx.authPath}/atproto; HttpOnly; Secure; SameSite=Lax; Max-Age=${FLOW_TTL_SECONDS}`,
+    );
+    return new Response(null, { status: 302, headers });
+  }
+
+  /**
+   * Callback. Recover the encrypted flow state, validate `state`/`iss`, run the DPoP-protected token
+   * exchange against the discovered token endpoint, then resolve a profile from the user's PDS.
+   */
+  async exchange(ctx: AuthContext): Promise<ExchangeResult> {
+    const errorParam = ctx.url.searchParams.get('error');
+    if (errorParam) {
+      throw new Error(`atproto authorization error: ${errorParam} ${ctx.url.searchParams.get('error_description') ?? ''}`.trim());
+    }
+
+    const code = ctx.url.searchParams.get('code');
+    if (!code) {
+      const err = new Error('Missing code') as Error & { status?: number };
+      err.status = 400;
+      throw err;
+    }
+
+    const encrypted = readCookie(ctx.request.headers.get('Cookie'), FLOW_COOKIE);
+    if (!encrypted) throw new Error('Missing atproto flow state (cookie expired or blocked)');
+    const decrypted = await ctx.cookieManager.decrypt(encrypted);
+    const flow = decrypted ? (JSON.parse(decrypted) as AtprotoFlowState) : null;
+    if (!flow) throw new Error('Invalid atproto flow state');
+
+    if (flow.state !== ctx.url.searchParams.get('state')) throw new Error('State mismatch');
+    const iss = ctx.url.searchParams.get('iss');
+    if (iss && iss !== flow.issuer) throw new Error('Issuer mismatch');
+
+    const body = new URLSearchParams({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: this.redirectUri,
+      client_id: this.clientMetadataUrl,
+      code_verifier: flow.verifier,
+    });
+
+    const { res } = await dpopFetch(
+      flow.tokenEndpoint,
+      { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: body.toString() },
+      flow.dpopKey,
+      flow.dpopNonce,
+    );
+    if (!res.ok) {
+      throw new Error(`Token request failed: ${res.status} ${await res.text()}`);
+    }
+
+    const tokenData = (await res.json()) as OAuthTokenResponse & { sub?: string };
+    const did = tokenData.sub || flow.did;
+    const { name, picture } = await fetchProfile(flow.pds, did, flow.handle);
+
+    const profile: UserProfile = { id: did, name: name || flow.handle || did, picture };
+    const token: OAuthTokenResponse = {
+      access_token: tokenData.access_token,
+      refresh_token: tokenData.refresh_token,
+      expires_in: tokenData.expires_in,
+      scope: tokenData.scope,
+      token_type: tokenData.token_type,
+    };
+
+    const clearCookie = `${FLOW_COOKIE}=; Path=${ctx.authPath}/atproto; HttpOnly; Secure; SameSite=Lax; Max-Age=0`;
+    return { token, profile, returnUrl: flow.returnUrl ?? null, setCookies: [clearCookie] };
+  }
+
+  /** Minimal handle-entry page shown when the user starts the flow without an identifier. */
+  private renderHandleForm(ctx: AuthContext, returnUrl: string | null): Response {
+    const action = `${ctx.authPath}/atproto`;
+    const returnField = returnUrl ? `<input type="hidden" name="return_url" value="${escapeHtml(returnUrl)}" />` : '';
+    const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Sign in with Bluesky / atproto</title>
+<style>
+  body { font-family: system-ui, sans-serif; background: #f5f7fb; margin: 0; display: flex; min-height: 100vh; align-items: center; justify-content: center; }
+  .card { background: #fff; padding: 2rem; border-radius: 12px; box-shadow: 0 8px 30px rgba(0,0,0,0.08); width: 320px; }
+  h1 { font-size: 1.15rem; margin: 0 0 1rem; }
+  label { display: block; font-size: 0.85rem; color: #444; margin-bottom: 0.35rem; }
+  input[type=text] { width: 100%; box-sizing: border-box; padding: 0.6rem 0.7rem; border: 1px solid #ccd2dd; border-radius: 8px; font-size: 0.95rem; }
+  button { margin-top: 1rem; width: 100%; padding: 0.65rem; border: 0; border-radius: 8px; background: #0085FF; color: #fff; font-size: 0.95rem; cursor: pointer; }
+  p { font-size: 0.8rem; color: #777; margin-top: 0.75rem; }
+</style>
+</head>
+<body>
+  <form class="card" method="GET" action="${escapeHtml(action)}">
+    <h1>Sign in with Bluesky / atproto</h1>
+    <label for="handle">Your handle or DID</label>
+    <input type="text" id="handle" name="handle" placeholder="alice.bsky.social" autocomplete="username" autofocus required />
+    ${returnField}
+    <button type="submit">Continue</button>
+    <p>Enter your atproto handle (e.g. alice.bsky.social) or DID. Your account's own server handles the login.</p>
+  </form>
+</body>
+</html>`;
+    return new Response(html, { status: 200, headers: { 'Content-Type': 'text/html; charset=utf-8' } });
+  }
+}
+
+/** Read a single cookie value from a Cookie header, or undefined. */
+function readCookie(header: string | null, name: string): string | undefined {
+  if (!header) return undefined;
+  for (const part of header.split(';')) {
+    const [key, ...rest] = part.split('=');
+    if (key.trim() === name) return rest.join('=').trim();
+  }
+  return undefined;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}

package/src/auth/OAuthProvider.ts

@@ -16,6 +16,50 @@ export interface UserProfile {
 }
 
 import type { Entitlements } from '../entitlements/types';
+import type { StartupAPIEnv } from '../StartupAPIEnv';
+import type { CookieManager } from '../CookieManager';
+
+/**
+ * Per-request context handed to a provider's flow hooks. Carries everything needed to run an
+ * authorization start or callback without the provider reaching back into the router.
+ */
+export interface AuthContext {
+  request: Request;
+  env: StartupAPIEnv;
+  url: URL;
+  /** Base URL provider redirect/callback URIs are built from, e.g. `https://host/users/auth`. */
+  redirectBase: string;
+  /** Pathname of `redirectBase`, e.g. `/users/auth`. */
+  authPath: string;
+  /** Configured users path, e.g. `/users/`. */
+  usersPath: string;
+  /** Effective origin (AUTH_ORIGIN override or request origin). */
+  origin: string;
+  cookieManager: CookieManager;
+}
+
+/**
+ * Result of a successful callback exchange: the token, the resolved user profile, where to send the
+ * user next, and any extra cookies to emit (e.g. clearing transient flow state).
+ */
+export interface ExchangeResult {
+  token: OAuthTokenResponse;
+  profile: UserProfile;
+  returnUrl: string | null;
+  setCookies?: string[];
+}
+
+/** Decode the base64url state param used by the standard flow back into its return_url. */
+function parseReturnUrl(stateBase64: string | null): string | null {
+  if (!stateBase64) return null;
+  try {
+    const base64 = stateBase64.replace(/-/g, '+').replace(/_/g, '/');
+    const stateJson = decodeURIComponent(escape(atob(base64)));
+    return JSON.parse(stateJson).return_url ?? null;
+  } catch {
+    return null;
+  }
+}
 
 export abstract class OAuthProvider {
   protected clientId: string;
@@ -58,10 +102,66 @@ export abstract class OAuthProvider {
     return path === `${authBasePath}/${this.name}/callback`;
   }
 
-  abstract getAuthUrl(state: string): string;
   abstract getIcon(): string;
-  abstract getToken(code: string): Promise<OAuthTokenResponse>;
-  abstract getUserProfile(token: string): Promise<UserProfile>;
+
+  /**
+   * Simple OAuth2 hooks used by the default {@link authorize}/{@link exchange}. Providers whose flow
+   * fits the classic "redirect → code → token → profile" shape implement these. Providers with a
+   * heavier flow (e.g. atproto's PKCE/DPoP/PAR) instead override {@link authorize}/{@link exchange}
+   * and may leave these as the throwing defaults.
+   */
+  getAuthUrl(_state: string): string {
+    throw new Error(`${this.name}: getAuthUrl is not implemented`);
+  }
+
+  async getToken(_code: string): Promise<OAuthTokenResponse> {
+    throw new Error(`${this.name}: getToken is not implemented`);
+  }
+
+  async getUserProfile(_token: string): Promise<UserProfile> {
+    throw new Error(`${this.name}: getUserProfile is not implemented`);
+  }
+
+  /**
+   * Begin the authorization flow. Default: build a base64url `state` (nonce + return_url) and redirect
+   * to {@link getAuthUrl}. Providers needing async setup, server-side flow state, or custom request
+   * shapes override this and return their own Response.
+   */
+  async authorize(ctx: AuthContext): Promise<Response> {
+    const returnUrl = ctx.url.searchParams.get('return_url');
+    const stateObj = { nonce: Math.random().toString(36).substring(2), return_url: returnUrl };
+    const state = btoa(unescape(encodeURIComponent(JSON.stringify(stateObj))))
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=+$/, '');
+    return Response.redirect(this.getAuthUrl(state), 302);
+  }
+
+  /**
+   * Exchange a callback for a token and resolved profile. Default: read `code`, recover the return_url
+   * from `state`, then {@link getToken} + {@link getUserProfile}. Providers override this for custom
+   * token exchanges (PKCE/DPoP, dynamic endpoints, etc.).
+   */
+  async exchange(ctx: AuthContext): Promise<ExchangeResult> {
+    const code = ctx.url.searchParams.get('code');
+    if (!code) {
+      const err = new Error('Missing code') as Error & { status?: number };
+      err.status = 400;
+      throw err;
+    }
+    const returnUrl = parseReturnUrl(ctx.url.searchParams.get('state'));
+    const token = await this.getToken(code);
+    const profile = await this.getUserProfile(token.access_token);
+    return { token, profile, returnUrl };
+  }
+
+  /**
+   * Serve any provider-specific auxiliary GET routes mounted under the auth base path (e.g. the atproto
+   * client-metadata document). Default: not a provider route → null, so the router moves on.
+   */
+  async handleExtraRoute(_ctx: AuthContext): Promise<Response | null> {
+    return null;
+  }
 
   /**
    * Whether this provider produces entitlements (memberships / perks). Providers that gate access on

package/src/auth/atproto/crypto.ts

@@ -0,0 +1,119 @@
+/**
+ * Cryptographic primitives for the AT Protocol OAuth flow: base64url helpers, PKCE, and DPoP
+ * (RFC 9449) proof generation. atproto OAuth requires PKCE and sender-constrained (DPoP-bound)
+ * tokens, so every request to the authorization/token endpoints carries a freshly signed ES256
+ * proof-of-possession JWT. All of this runs on the WebCrypto API available in Workers.
+ */
+
+/** Encode raw bytes as unpadded base64url. */
+export function base64urlEncode(input: ArrayBuffer | Uint8Array): string {
+  const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+  let str = '';
+  for (const b of bytes) str += String.fromCharCode(b);
+  return btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** Encode a UTF-8 string as unpadded base64url. */
+export function base64urlEncodeString(value: string): string {
+  return base64urlEncode(new TextEncoder().encode(value));
+}
+
+/** A random unpadded-base64url token of `byteLength` random bytes (used for state, jti, PKCE verifier). */
+export function randomToken(byteLength = 32): string {
+  return base64urlEncode(crypto.getRandomValues(new Uint8Array(byteLength)));
+}
+
+export interface Pkce {
+  verifier: string;
+  challenge: string;
+}
+
+/** Generate a PKCE verifier and its S256 challenge. */
+export async function generatePkce(): Promise<Pkce> {
+  const verifier = randomToken(32);
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+  return { verifier, challenge: base64urlEncode(digest) };
+}
+
+const ES256_PARAMS = { name: 'ECDSA', namedCurve: 'P-256' } as const;
+
+/**
+ * Generate an ephemeral ES256 (P-256) keypair for DPoP and return its private JWK. The private JWK is
+ * persisted in the (encrypted) flow state so the same key can be reused for the token request and any
+ * later refresh; the public half is embedded in each proof's header.
+ */
+export async function generateDpopKey(): Promise<JsonWebKey> {
+  const pair = (await crypto.subtle.generateKey(ES256_PARAMS, true, ['sign', 'verify'])) as CryptoKeyPair;
+  return (await crypto.subtle.exportKey('jwk', pair.privateKey)) as JsonWebKey;
+}
+
+/** The public portion of a DPoP JWK, as embedded in the proof header. */
+function publicJwk(jwk: JsonWebKey): JsonWebKey {
+  return { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y };
+}
+
+/**
+ * Build a DPoP proof JWT bound to the given HTTP method and URL (htu is normalized to origin+path, per
+ * RFC 9449). When the server has issued a nonce it must be echoed back in the proof.
+ */
+export async function createDpopProof(privateJwk: JsonWebKey, htm: string, htu: string, nonce?: string): Promise<string> {
+  const key = await crypto.subtle.importKey('jwk', privateJwk, ES256_PARAMS, false, ['sign']);
+  const target = new URL(htu);
+  const header = { typ: 'dpop+jwt', alg: 'ES256', jwk: publicJwk(privateJwk) };
+  const payload: Record<string, unknown> = {
+    jti: randomToken(16),
+    htm: htm.toUpperCase(),
+    htu: target.origin + target.pathname,
+    iat: Math.floor(Date.now() / 1000),
+  };
+  if (nonce) payload.nonce = nonce;
+
+  const signingInput = `${base64urlEncodeString(JSON.stringify(header))}.${base64urlEncodeString(JSON.stringify(payload))}`;
+  const signature = await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, key, new TextEncoder().encode(signingInput));
+  // WebCrypto ECDSA already returns the raw r||s signature that JOSE/ES256 expects.
+  return `${signingInput}.${base64urlEncode(signature)}`;
+}
+
+export interface DpopResult {
+  res: Response;
+  /** The most recent server-issued DPoP nonce, to be reused on the next request. */
+  nonce?: string;
+}
+
+/**
+ * POST to a DPoP-protected endpoint, transparently handling the `use_dpop_nonce` challenge: the first
+ * request is sent without (or with the cached) nonce; if the server demands a fresh nonce we retry once
+ * with it. Returns the final response and the latest nonce so the caller can chain requests (PAR →
+ * token) without re-fetching one.
+ */
+export async function dpopFetch(url: string, init: RequestInit, privateJwk: JsonWebKey, nonce?: string): Promise<DpopResult> {
+  let currentNonce = nonce;
+  const method = (init.method || 'POST').toUpperCase();
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const proof = await createDpopProof(privateJwk, method, url, currentNonce);
+    const headers = new Headers(init.headers);
+    headers.set('DPoP', proof);
+    const res = await fetch(url, { ...init, headers });
+    const serverNonce = res.headers.get('DPoP-Nonce') ?? undefined;
+
+    if ((res.status === 400 || res.status === 401) && serverNonce && attempt === 0) {
+      let needsNonce = false;
+      try {
+        const body = (await res.clone().json()) as { error?: string };
+        needsNonce = body?.error === 'use_dpop_nonce';
+      } catch {
+        // Non-JSON body; fall through and surface the original response.
+      }
+      if (needsNonce) {
+        currentNonce = serverNonce;
+        continue;
+      }
+    }
+
+    return { res, nonce: serverNonce ?? currentNonce };
+  }
+
+  // Unreachable: the loop either returns a response or retries exactly once then returns.
+  throw new Error('dpopFetch: exhausted retries');
+}