@startup-api/cloudflare 0.3.2 → 0.4.1

package/README.md

@@ -69,6 +69,9 @@ Either way, set your production secrets (`SESSION_SECRET`, OAuth credentials) on
 | `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                               |
+| `ATPROTO_ENABLED`        | No       | N/A       | Set truthy (`true`/`1`/`yes`/`on`) to enable AT Protocol (Atmosphere) login   |
+
+> AT Protocol (Atmosphere) login needs **no client secret** — it is a public OAuth client. Enable it either by setting `ATPROTO_ENABLED` truthy (a per-deployment switch) **or** through the `createStartupAPI` factory (see [AT Protocol / Atmosphere](#at-protocol--atmosphere-atproto) below). A factory `atproto: { enabled: false }` overrides the env flag, so a deployment can force it off.
 
 > 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)).
 
@@ -99,6 +102,51 @@ 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
 
+#### AT Protocol / Atmosphere (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 provider host hardcoded.
+
+Because it has no secrets, atproto is enabled in one of two ways:
+
+- **Env flag (no code):** set `ATPROTO_ENABLED` truthy (`true`/`1`/`yes`/`on`) — handy for toggling it per deployment (e.g. on in prod, off in preview) without touching code. This uses the default settings.
+- **Factory config (for customization):** include its config key in `createStartupAPI` — an empty object is enough, and the optional fields below let you set the client name, resolvers, or scopes.
+
+A factory `atproto: { enabled: false }` is an explicit opt-out that **overrides** the env flag, so a deployment can force the provider off.
+
+```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. Enable it — set `ATPROTO_ENABLED` truthy, or include `atproto: {}` in the factory `providers` config (no client id/secret needed either way). A factory `enabled: false` forces it off.
+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 **Login with your Atmosphere account**, 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.1",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
@@ -37,6 +37,7 @@
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.12.4",
     "@eslint/js": "^10.0.1",
+    "@types/he": "^1.2.3",
     "@vitest/coverage-istanbul": "^3.2.4",
     "@vitest/coverage-v8": "^3.2.4",
     "eslint": "^10.0.1",
@@ -47,6 +48,7 @@
     "wrangler": "^4.60.0"
   },
   "dependencies": {
+    "he": "^1.2.0",
     "prettier": "^3.8.1",
     "zod": "^3.25.76"
   }

package/public/users/power-strip.js

@@ -1,3 +1,8 @@
+// Atmosphere (atproto) logo mark — the "union" glyph, drawn on a 0 0 32 32 viewBox.
+// Shared by the provider badge and the login button so the two never drift apart.
+const ATMOSPHERE_MARK_PATH =
+  'M16 0C18.1127 1.0372e-05 19.9555 1.15414 20.9332 2.8662C21.1045 3.16613 21.4647 3.31517 21.7979 3.22403C22.2761 3.09321 22.7795 3.02333 23.2992 3.02333C26.4347 3.02335 28.9765 5.56529 28.9765 8.70083C28.9765 9.22048 28.9066 9.72378 28.7758 10.2019C28.6846 10.5351 28.8337 10.8953 29.1336 11.0666C30.8458 12.0442 32 13.8872 32 16C32 16.0822 31.9981 16.1639 31.9946 16.2452C31.9946 16.2456 31.9944 16.246 31.9942 16.2463C31.9939 16.2465 31.9937 16.2469 31.9937 16.2473C31.8599 19.6701 29.2873 22.4 26.1329 22.4L25.9815 22.3979C24.3638 22.353 22.909 21.59 21.8719 20.3888C21.5701 20.0392 20.9949 20.0275 20.6799 20.3652C19.5117 21.6171 17.8474 22.4 16 22.4C12.4654 22.4 9.6 19.5346 9.6 16C9.6 12.4654 12.4654 9.6 16 9.6C17.4368 9.6 18.7629 10.0736 19.831 10.8731C20.0053 11.0036 20.2667 10.8843 20.2667 10.6667C20.2667 10.0776 20.7442 9.6 21.3333 9.6C21.9224 9.6 22.4 10.0776 22.4 10.6667V16C22.4158 18.5458 24.26 20.2666 26.1329 20.2667C27.9447 20.2667 29.7293 18.6564 29.8583 16.2467C29.8583 16.2466 29.8583 16.2464 29.8581 16.2463C29.858 16.2461 29.8579 16.2459 29.8579 16.2458C29.8591 16.2281 29.8597 16.2104 29.8606 16.1927C29.8634 16.1293 29.8654 16.0654 29.8658 16.001C29.8658 16.0006 29.866 16.0003 29.8663 16C29.8665 15.9997 29.8667 15.9994 29.8667 15.999C29.8663 14.5464 28.9914 13.2933 27.7308 12.7465L26.4045 12.1712C26.0876 12.0337 25.937 11.6696 26.0641 11.3484L26.5963 10.0042C26.7549 9.60324 26.8431 9.16479 26.8431 8.70083C26.8431 6.77399 25.3056 5.20644 23.3906 5.15792L23.2992 5.15667C22.8351 5.15667 22.3965 5.24487 21.9956 5.40354L20.6515 5.93568C20.3304 6.06282 19.9663 5.91222 19.8288 5.59538L19.2533 4.26917C18.7234 3.04774 17.5306 2.18836 16.1356 2.13583L16 2.13333C14.547 2.13333 13.2934 3.00824 12.7465 4.26896L12.1712 5.59529C12.0337 5.91217 11.6696 6.06282 11.3484 5.93568L10.0042 5.40354C9.62831 5.25477 9.21941 5.16798 8.7875 5.15771L8.70083 5.15667C6.74349 5.15667 5.15667 6.74349 5.15667 8.70083C5.15667 9.16475 5.24485 9.60323 5.40354 10.0042L5.93568 11.3484C6.06282 11.6696 5.91217 12.0337 5.59529 12.1712L4.26896 12.7465C3.00823 13.2934 2.13333 14.5469 2.13333 16C2.13333 17.4529 3.00832 18.7063 4.26917 19.2533L5.59538 19.8288C5.91222 19.9663 6.06282 20.3304 5.93568 20.6515L5.40354 21.9956C5.24487 22.3965 5.15667 22.835 5.15667 23.2992C5.15667 25.2565 6.74349 26.8433 8.70083 26.8433C9.1644 26.8433 9.60287 26.7551 10.0042 26.5963L11.3484 26.0641C11.6696 25.937 12.0337 26.0876 12.1712 26.4045L12.7465 27.7308C13.2934 28.9917 14.547 29.8667 16 29.8667C17.4529 29.8667 18.7063 28.9918 19.2533 27.7308L19.6555 26.8037C19.8871 26.2698 20.5083 26.0256 21.0415 26.2589C21.561 26.4862 21.8066 27.0847 21.5966 27.6115L21.2104 28.5798C20.3374 30.5922 18.3333 32 16 32C13.8872 32 12.0442 30.8458 11.0666 29.1336C10.8953 28.8337 10.5351 28.6846 10.2019 28.7758C9.72378 28.9067 9.22049 28.9767 8.70083 28.9767C5.56528 28.9767 3.02333 26.4347 3.02333 23.2992C3.02333 22.7795 3.09321 22.2761 3.22403 21.7979C3.31516 21.4647 3.16613 21.1045 2.86619 20.9332C1.15412 19.9555 0 18.1127 0 16C5.927e-07 13.8873 1.1541 12.0443 2.8662 11.0666C3.16613 10.8953 3.31517 10.5351 3.22403 10.2019C3.09323 9.72379 3.02333 9.22047 3.02333 8.70083C3.02333 5.56528 5.56528 3.02333 8.70083 3.02333C9.22047 3.02334 9.72379 3.09323 10.2019 3.22404C10.5351 3.31517 10.8953 3.16614 11.0666 2.86621C12.0443 1.15411 13.8873 0 16 0ZM16 11.7333C13.6436 11.7333 11.7333 13.6436 11.7333 16C11.7333 18.3564 13.6436 20.2667 16 20.2667C18.3564 20.2667 20.2667 18.3564 20.2667 16C20.2667 13.6436 18.3564 11.7333 16 11.7333Z';
+
 class PowerStrip extends HTMLElement {
   constructor() {
     super();
@@ -212,6 +217,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 32 32"><circle cx="16" cy="16" r="16" fill="#4a8ad4"/><g transform="translate(3.2 3.2) scale(0.8)"><path fill-rule="evenodd" clip-rule="evenodd" d="${ATMOSPHERE_MARK_PATH}" fill="white"/></g></svg>`;
     }
     return '';
   }
@@ -221,6 +228,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 +265,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 32 32">
+                      <path fill-rule="evenodd" clip-rule="evenodd" d="${ATMOSPHERE_MARK_PATH}" fill="currentColor"/>
+                    </svg>
+                    Login with your Atmosphere account
+                </a>`;
+    }
 
     let content = '';
     let accountSwitcher = '';
@@ -585,6 +602,7 @@ class PowerStrip extends HTMLElement {
         .provider-badge.google { color: #3c4043; }
         .provider-badge.twitch { color: #9146FF; }
         .provider-badge.patreon { color: #FF424D; }
+        .provider-badge.atproto { color: #4a8ad4; }
 
         .user-info {
             display: flex;
@@ -658,7 +676,7 @@ class PowerStrip extends HTMLElement {
           box-shadow: var(--ps-dialog-shadow);
           background: var(--ps-dialog-bg);
           color: var(--ps-dialog-text);
-          max-width: 20rem;
+          max-width: 25rem;
           width: 90%;
           overflow: hidden;
         }
@@ -723,7 +741,8 @@ class PowerStrip extends HTMLElement {
             justify-content: center;
             gap: 0.75rem;
             font-weight: 500;
-            font-size: 1rem;
+            font-size: 0.95rem;
+            white-space: nowrap;
             transition: all 0.2s ease;
             text-decoration: none;
             color: inherit;
@@ -742,6 +761,7 @@ class PowerStrip extends HTMLElement {
         .auth-btn svg {
             width: 1.5rem;
             height: 1.5rem;
+            flex-shrink: 0;
         }
 
         .auth-btn.google {
@@ -773,6 +793,16 @@ class PowerStrip extends HTMLElement {
             border-color: #e63a44;
         }
 
+        .auth-btn.atproto {
+            background-color: #4a8ad4;
+            color: white;
+            border-color: #4a8ad4;
+        }
+        .auth-btn.atproto:hover {
+            background-color: #3d77ba;
+            border-color: #3d77ba;
+        }
+
         /* 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/StartupAPIEnv.ts

@@ -12,4 +12,7 @@ export type StartupAPIEnv = {
   ADMIN_IDS: string;
   SESSION_SECRET: string;
   ENVIRONMENT?: string;
+  // atproto has no credentials; this per-deployment flag enables it without touching the factory
+  // config (truthy = "true"/"1"/"yes"/"on"). A factory `atproto: { enabled: false }` still overrides it.
+  ATPROTO_ENABLED?: string;
 } & Env;

package/src/auth/AtprotoProvider.ts

@@ -0,0 +1,327 @@
+import { escape as escapeHtml } from 'he';
+
+import { ATMOSPHERE_MARK_PATH } from './atmosphereMark';
+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;
+}
+
+/** A string env flag is truthy when it reads as "true"/"1"/"yes"/"on" (case-insensitive). */
+function isEnvFlagTruthy(value: string | undefined): boolean {
+  return value !== undefined && ['true', '1', 'yes', 'on'].includes(value.trim().toLowerCase());
+}
+
+/**
+ * Whether the atproto provider is turned on. It has no client secret (public OAuth client), so it is
+ * enabled either by:
+ *   - including its factory config key (`providers: { atproto: {} }`), or
+ *   - setting the `ATPROTO_ENABLED` env var truthy (a per-deployment switch needing no code change).
+ * A factory `atproto: { enabled: false }` is an explicit opt-out that overrides the env flag, so a
+ * deployment can force the provider off regardless of the environment.
+ */
+export function isAtprotoEnabled(options?: ProviderOptions, env?: Pick<StartupAPIEnv, 'ATPROTO_ENABLED'>): boolean {
+  if (options?.enabled === false) return false; // explicit factory opt-out always wins
+  if (options !== undefined) return true; // present in the factory config
+  return isEnvFlagTruthy(env?.ATPROTO_ENABLED); // otherwise honor the per-deployment env toggle
+}
+
+/**
+ * AT Protocol (Atmosphere) authentication — works with any atproto PDS.
+ *
+ * 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, env)) 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 {
+    // Atmosphere (atproto) "union" logo mark, white on the brand-blue badge.
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+      <circle cx="16" cy="16" r="16" fill="#4a8ad4"/>
+      <g transform="translate(3.2 3.2) scale(0.8)"><path fill-rule="evenodd" clip-rule="evenodd" d="${ATMOSPHERE_MARK_PATH}" fill="white"/></g>
+    </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);
+    }
+
+    try {
+      return await this.startAuthorization(ctx, identifier, returnUrl);
+    } catch (e) {
+      // The user supplied a handle and is still on our side of the redirect, so the most useful
+      // recovery is to re-render the entry form with the failure shown and their handle pre-filled,
+      // rather than a dead-end error page. (Callback-phase failures fall back to renderAuthError.)
+      const message = e instanceof Error ? e.message : String(e);
+      return this.renderHandleForm(ctx, returnUrl, { error: message, handle: identifier });
+    }
+  }
+
+  /** Resolve the identity, run the DPoP-protected PAR, and redirect to the discovered auth endpoint. */
+  private async startAuthorization(ctx: AuthContext, identifier: string, returnUrl: string | null): Promise<Response> {
+    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] };
+  }
+
+  /**
+   * Handle-entry page. Shown when the user starts the flow without an identifier, and re-shown when a
+   * supplied handle fails to authorize — in which case `options.error` renders an inline banner and
+   * `options.handle` pre-fills the input so the user can correct and retry without leaving the page.
+   */
+  private renderHandleForm(
+    ctx: AuthContext,
+    returnUrl: string | null,
+    options: { error?: string; handle?: string } = {},
+  ): Response {
+    const action = `${ctx.authPath}/atproto`;
+    const returnField = returnUrl ? `<input type="hidden" name="return_url" value="${escapeHtml(returnUrl)}" />` : '';
+    const errorBanner = options.error ? `<div class="error" role="alert">${escapeHtml(options.error)}</div>` : '';
+    const handleValue = options.handle ? ` value="${escapeHtml(options.handle)}"` : '';
+    const status = options.error ? 400 : 200;
+    const stylesheet = `${escapeHtml(ctx.usersPath)}style.css`;
+    const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Login with your Atmosphere account</title>
+<link rel="stylesheet" href="${stylesheet}" />
+<style>
+  body { margin: 0; padding: 1rem; box-sizing: border-box; min-height: 100vh; display: flex; align-items: center; justify-content: center; background: var(--bg); color: var(--text); }
+  .auth-card { background: var(--surface); border: 1px solid var(--border); padding: 2rem; border-radius: 12px; box-shadow: 0 8px 30px rgba(0,0,0,0.08); width: 23rem; max-width: 100%; box-sizing: border-box; }
+  .auth-card h1 { font-size: 1rem; margin: 0 0 1rem; color: var(--text); white-space: nowrap; }
+  .auth-card label { display: block; font-size: 0.85rem; color: var(--text-secondary); margin-bottom: 0.35rem; }
+  .auth-card input[type=text] { width: 100%; box-sizing: border-box; padding: 0.6rem 0.7rem; border: 1px solid var(--border); border-radius: 8px; font-size: 0.95rem; background: var(--surface); color: var(--text); }
+  .auth-card input[type=text]:focus { outline: none; border-color: #4a8ad4; }
+  .auth-card button { margin-top: 1rem; width: 100%; padding: 0.65rem; border: 0; border-radius: 8px; background: #4a8ad4; color: #fff; font-size: 0.95rem; cursor: pointer; }
+  .auth-card button:hover { background: #3d77ba; }
+  .auth-card p { font-size: 0.8rem; color: var(--text-muted); margin: 0.75rem 0 0; }
+  .auth-card .error { background: var(--danger-soft-bg); border: 1px solid var(--danger); color: var(--danger); border-radius: 8px; padding: 0.6rem 0.7rem; font-size: 0.82rem; margin-bottom: 1rem; word-break: break-word; }
+</style>
+</head>
+<body>
+  <form class="auth-card" method="GET" action="${escapeHtml(action)}">
+    <h1>Login with your Atmosphere account</h1>
+    ${errorBanner}
+    <label for="handle">Your handle or DID</label>
+    <input type="text" id="handle" name="handle" placeholder="alice.bsky.social"${handleValue} 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,
+      headers: {
+        'Content-Type': 'text/html; charset=utf-8',
+        // Same hardening as the auth error page: only same-origin styles/form, never framed, never cached
+        // (the re-rendered form reflects the user-supplied handle).
+        'Content-Security-Policy':
+          "default-src 'none'; style-src 'self' 'unsafe-inline'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'",
+        'X-Content-Type-Options': 'nosniff',
+        'Referrer-Policy': 'no-referrer',
+        'Cache-Control': 'no-store',
+      },
+    });
+  }
+}
+
+/** 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;
+}

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