@startup-api/cloudflare 0.3.1 → 0.4.0

package/README.md

@@ -12,36 +12,35 @@ This application uses the Cloudflare Developer Platform, including Workers and D
 
 ## Installation
 
-### Option 1: Cloudflare Workers GitHub Integration (Recommended)
+Start a new project with the **`npm create startup-api`** scaffolder. It generates a tiny Cloudflare Worker that pulls this framework in as the [`@startup-api/cloudflare`](https://www.npmjs.com/package/@startup-api/cloudflare) npm dependency — so you stay up to date with `npm update` instead of maintaining a fork of this repository.
 
-This is the easiest way to deploy and keep your worker up to date.
+```bash
+npm create startup-api my-app -- --origin https://your-app-origin.com
+cd my-app
+npm run dev      # local dev at http://localhost:8787
+npm run deploy   # deploy to Cloudflare
+```
 
-1. **Fork this repository** to your account
-2. Go to your [Cloudflare Dashboard's Workers & pages > Create Application](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create)
-3. Click **Continue with GitHub**
-4. Select your forked `startup-api-cloudflare` repository
-5. Pick the name for your site's worker (e.g. you might have multiple)
-6. Deploy the Worker
-7. In the **Settings** tab of your Worker, go to **Variables** and add the required `ORIGIN_URL` (see [Configuration](#configuration-details) below)
+Run `npm create startup-api` with no arguments to be prompted for the project name and origin URL interactively. Useful flags: `--no-install` (skip `npm install`) and `--yes` / `-y` (non-interactive — requires a `name` and `--origin`).
 
-### Option 2: Manual Installation (CLI)
+What you get:
 
-Use this option if you want to deploy from your local machine.
+- A minimal `src/index.ts` that re-exports the worker plus a `wrangler.jsonc` you control. The framework ships as the `@startup-api/cloudflare` dependency, so your project stays small.
+- A `.dev.vars` file with a random `SESSION_SECRET` for local development. For production, set your own with `npx wrangler secret put SESSION_SECRET`.
+- Framework updates are just `npm update @startup-api/cloudflare` — no fork to rebase.
 
-1. **Clone and Install**
-   ```bash
-   git clone https://github.com/StartupAPI/startup-api-cloudflare.git
-   cd startup-api-cloudflare
-   npm install
-   ```
-2. **Configure Environment Variables**
+Then set the required `ORIGIN_URL` and any OAuth credentials (see [Configuration](#configuration-details) below) and run `npm run deploy`. See [create-startup-api](https://github.com/StartupAPI/create-startup-api) for full details.
 
-   Update `wrangler.jsonc` or use dashboard **Settings** tab of your Worker, go to **Variables** and add the required `ORIGIN_URL` (see [Configuration](#configuration-details) below)
+### Automated deployments
 
-3. **Deploy**
-   ```bash
-   npm run deploy
-   ```
+`npm run deploy` deploys from your machine. To deploy automatically instead, push your scaffolded project to a GitHub repository and use either:
+
+- **Cloudflare Workers GitHub app** — connect the repo to Cloudflare's [Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/) Git integration and Cloudflare builds and deploys on every push, no CI config to maintain.
+- **A GitHub Actions workflow** — run [`cloudflare/wrangler-action`](https://github.com/cloudflare/wrangler-action) on push to deploy with Wrangler. Add a `CLOUDFLARE_API_TOKEN` (and `CLOUDFLARE_ACCOUNT_ID`) repository secret so the action can authenticate.
+
+Either way, set your production secrets (`SESSION_SECRET`, OAuth credentials) on the Worker in the Cloudflare dashboard or with `npx wrangler secret put` rather than committing them.
+
+> **Working on the framework itself?** See [CONTRIBUTING.md](./CONTRIBUTING.md) for cloning and running this repository locally.
 
 ## Configuration Details
 
@@ -58,18 +57,20 @@ Use this option if you want to deploy from your local machine.
 - **Using `wrangler.jsonc`:**
   Add the variables to the `"vars"` object in your configuration file. See [Cloudflare documentation](https://developers.cloudflare.com/workers/wrangler/configuration/#environment-variables) for more details.
 
-| Variable               | Required | Default   | Description                                                                   |
-| :--------------------- | :------- | :-------- | :---------------------------------------------------------------------------- |
-| `ORIGIN_URL`           | **Yes**  | N/A       | The base URL of your origin application (e.g., `https://your-app-origin.com`) |
-| `USERS_PATH`           | No       | `/users/` | The path used to serve internal assets like `power-strip.js`                  |
-| `AUTH_ORIGIN`          | No       | N/A       | Optional base URL for OAuth redirects (overrides request origin)              |
-| `GOOGLE_CLIENT_ID`     | No       | N/A       | Google OAuth2 Client ID                                                       |
-| `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                              |
+| Variable                 | Required | Default   | Description                                                                   |
+| :----------------------- | :------- | :-------- | :---------------------------------------------------------------------------- |
+| `ORIGIN_URL`             | **Yes**  | N/A       | The base URL of your origin application (e.g., `https://your-app-origin.com`) |
+| `USERS_PATH`             | No       | `/users/` | The path used to serve internal assets like `power-strip.js`                  |
+| `AUTH_ORIGIN`            | No       | N/A       | Optional base URL for OAuth redirects (overrides request origin)              |
+| `GOOGLE_CLIENT_ID`       | No       | N/A       | Google OAuth2 Client ID                                                       |
+| `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                               |
+
+> 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)).
 
@@ -100,6 +101,46 @@ Use this option if you want to deploy from your local machine.
 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:
@@ -144,7 +185,7 @@ By default the worker injects its own `<power-strip>` pinned to the top-right co
 ```
 
 - **`providers` is optional.** If you omit it, the worker fills in the active providers for you (e.g. `providers="google,twitch,patreon"`). Set it yourself to override which login buttons appear.
-- **Prefer an explicit closing tag.** `<power-strip></power-strip>` and `<power-strip/>` are both detected, but per the HTML spec `<power-strip/>` is *not* truly self-closing — the browser treats it as an open tag and nests the following content inside it. Use a closing tag (or place the element last in its container) to avoid surprises.
+- **Prefer an explicit closing tag.** `<power-strip></power-strip>` and `<power-strip/>` are both detected, but per the HTML spec `<power-strip/>` is _not_ truly self-closing — the browser treats it as an open tag and nests the following content inside it. Use a closing tag (or place the element last in its container) to avoid surprises.
 - **Script-only opt-out.** Use `<power-strip hidden>` to load `power-strip.js` (and its JS API) without rendering a visible strip.
 
 ## Access policy & provider entitlements
@@ -243,7 +284,12 @@ const api = createStartupAPI({
       freshness: { ttl: true, cron: { schedule: '0 */6 * * *' }, webhook: true },
     },
   },
-  accessPolicy: { rules: [/* ... */], default: { mode: 'public' } },
+  accessPolicy: {
+    rules: [
+      /* ... */
+    ],
+    default: { mode: 'public' },
+  },
 });
 
 export default api.default; // includes scheduled() because cron is enabled
@@ -254,7 +300,7 @@ export const { UserDO, AccountDO, SystemDO, CredentialDO } = api;
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to clone, run, test, and submit changes to the framework.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startup-api/cloudflare",
-  "version": "0.3.1",
+  "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