Upgrade certified.one to epds v0.9

.agents/skills/epds-login/references/client-metadata.md

@@ -113,10 +113,9 @@ key generation and serving details.
 | `dpop_bound_access_tokens`        | Yes         | Always `true`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `client_uri`                      | No          | Your app's homepage URL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `logo_uri`                        | No          | URL to your app logo (shown on login page)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `email_template_uri`              | No          | URL to a custom OTP email HTML template                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `email_subject_template`          | No          | Custom email subject line with `{{code}}` placeholder                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `email_template_uri`              | No          | URL to a custom OTP email HTML template. Trusted clients only. Must use HTTPS; HTTP is permitted only when `EPDS_ALLOW_PRIVATE_IPS=true` enables `allowHttp` for local development. Keep that setting disabled for internet-facing deployments.                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `email_subject_template`          | No          | Custom email subject line with `{{code}}` placeholder. Trusted clients only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `brand_color`                     | No          | Hex colour for buttons and input focus rings (default: `#1A130F`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `background_color`                | No          | Hex colour for the login page background (default: `#F2EBE4`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `epds_handle_mode`                | No          | ePDS extension. Handle picker variant for new users: `"picker"`, `"random"`, or `"picker-with-random"` (default). See [tutorial](../../../../docs/tutorial.md#optional-control-the-handle-picker).                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `epds_skip_consent_on_signup`     | No          | ePDS extension. When `true`, skip the consent screen on initial sign-up. Only honoured when the PDS has `PDS_SIGNUP_ALLOW_CONSENT_SKIP=true` AND the client is in `PDS_OAUTH_TRUSTED_CLIENTS`.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `epds_handle_login_url`           | No          | ePDS extension. Absolute http(s) URL on your client's origin. When set, the auth-service login page renders an "Or sign in with ATProto/Bluesky" button; submitting a handle redirects the browser to this URL with `?handle=<value>` appended. See [tutorial](../../../../docs/tutorial.md#optional-offer-atprotobluesky-handle-sign-in).                                                                                                                                                                                                                                                                                                         |
@@ -134,18 +133,20 @@ for the route list and example URLs.
 
 ## Custom email templates
 
-If you provide `email_template_uri`, the auth service fetches that URL and
-uses it as the OTP email body instead of the default Certified template.
+Custom email HTML and subject fields are honored only when the client is in
+`PDS_OAUTH_TRUSTED_CLIENTS`. When trusted metadata provides
+`email_template_uri`, auth-service fetches that HTML and uses it for the HTML
+part of the OTP email. The server retains control of the plain-text part.
 
 Your template must be an HTML file. Supported placeholders:
 
-| Placeholder                           | Description                               |
-| ------------------------------------- | ----------------------------------------- |
-| `{{code}}`                            | The 8-digit OTP code — **required**       |
-| `{{app_name}}`                        | Value of `client_name` from your metadata |
-| `{{logo_uri}}`                        | Value of `logo_uri` from your metadata    |
-| `{{#is_new_user}}...{{/is_new_user}}` | Block shown only on first sign-up         |
-| `{{^is_new_user}}...{{/is_new_user}}` | Block shown only on subsequent sign-ins   |
+| Placeholder                           | Description                                       |
+| ------------------------------------- | ------------------------------------------------- |
+| `{{code}}`                            | Configured 4–12-character OTP code — **required** |
+| `{{app_name}}`                        | Value of `client_name` from your metadata         |
+| `{{logo_uri}}`                        | Value of `logo_uri` from your metadata            |
+| `{{#is_new_user}}...{{/is_new_user}}` | Block shown only on first sign-up                 |
+| `{{^is_new_user}}...{{/is_new_user}}` | Block shown only on subsequent sign-ins           |
 
 Minimal template example:
 
@@ -281,6 +282,12 @@ allow-list.
 
 ## Local development
 
-During local development you can use `http://localhost` client IDs. The
-`client_id` must still be a reachable URL — ePDS fetches it at runtime.
-Use a local server or `ngrok` to expose your metadata endpoint.
+A remote ePDS must be able to fetch a discoverable client metadata URL and any
+remote `jwks_uri`. It cannot reach a server bound only to your localhost. Every
+ordinary web client, including a public client, must use an HTTPS tunnel or
+deployed HTTPS development URL.
+
+AT Protocol loopback clients are the only exception. They use a separate
+metadata encoding and public-client rules. Do not assume an ordinary
+`http://localhost/.../client-metadata.json` URL will be fetched successfully by
+a remote ePDS.

.agents/skills/epds-login/references/dpop-pkce.md

@@ -1,185 +1,14 @@
-# PKCE and DPoP Helper Implementations
+# PKCE and DPoP
 
-> **Flow 2 does not need these helpers.** If your app uses
-> `@atproto/oauth-client-node` (recommended for any flow that does not pass
-> a raw email as `login_hint`), the library handles PKCE, DPoP, and nonce
-> retry internally. These helpers are only needed for **Flow 1** (hand-rolled
-> PAR/DPoP with email `login_hint`).
-
-Copy these into your project. They have no dependencies beyond Node's built-in
-`node:crypto` module.
+`NodeOAuthClient` handles PKCE, DPoP, and the associated OAuth state, including
+for email-first login:
 
 ```typescript
-import * as crypto from 'node:crypto'
-
-// ---------------------------------------------------------------------------
-// PKCE helpers
-// ---------------------------------------------------------------------------
-
-/** Generate a random code verifier for PKCE. Store this in your session. */
-export function generateCodeVerifier(): string {
-  return crypto.randomBytes(32).toString('base64url')
-}
-
-/** Derive the code challenge to send to the auth server. */
-export function generateCodeChallenge(verifier: string): string {
-  return crypto.createHash('sha256').update(verifier).digest('base64url')
-}
-
-/** Generate a random state value. Store this in your session. */
-export function generateState(): string {
-  return crypto.randomBytes(16).toString('base64url')
-}
-
-// ---------------------------------------------------------------------------
-// DPoP helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Generate a fresh DPoP key pair.
- *
- * Call this once per login attempt. Store `privateJwk` in your session cookie
- * so the callback handler can restore the key pair for token exchange.
- * Never reuse a key pair across different login flows.
- */
-export function generateDpopKeyPair() {
-  const { publicKey, privateKey } = crypto.generateKeyPairSync('ec', {
-    namedCurve: 'P-256',
-  })
-  return {
-    privateKey,
-    publicJwk: publicKey.export({ format: 'jwk' }),
-    privateJwk: privateKey.export({ format: 'jwk' }),
-  }
-}
-
-/**
- * Restore a DPoP key pair from a serialized private JWK.
- *
- * Use this in the callback handler to recover the key pair from the session
- * cookie that was set during the login handler.
- */
-export function restoreDpopKeyPair(privateJwk: crypto.JsonWebKey) {
-  const privateKey = crypto.createPrivateKey({ key: privateJwk, format: 'jwk' })
-  const publicKey = crypto.createPublicKey(privateKey)
-  return {
-    privateKey,
-    publicJwk: publicKey.export({ format: 'jwk' }),
-  }
-}
-
-/**
- * Create a DPoP proof JWT for a single HTTP request.
- *
- * Create a new proof for every request — they are single-use by design.
- *
- * @param opts.nonce - Include when the server returned a `dpop-nonce` header.
- * @param opts.accessToken - Include when making API calls with an access token.
- */
-export function createDpopProof(opts: {
-  privateKey: crypto.KeyObject
-  jwk: object
-  method: string
-  url: string
-  nonce?: string
-  accessToken?: string
-}): string {
-  const header = { alg: 'ES256', typ: 'dpop+jwt', jwk: opts.jwk }
-
-  const payload: Record<string, unknown> = {
-    jti: crypto.randomUUID(),
-    htm: opts.method,
-    htu: opts.url,
-    iat: Math.floor(Date.now() / 1000),
-  }
-  if (opts.nonce) payload.nonce = opts.nonce
-  if (opts.accessToken) {
-    payload.ath = crypto
-      .createHash('sha256')
-      .update(opts.accessToken)
-      .digest('base64url')
-  }
-
-  const headerB64 = Buffer.from(JSON.stringify(header)).toString('base64url')
-  const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url')
-  const signingInput = `${headerB64}.${payloadB64}`
-  const sig = crypto.sign('sha256', Buffer.from(signingInput), opts.privateKey)
-  return `${signingInput}.${derToRaw(sig).toString('base64url')}`
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Convert a DER-encoded ECDSA signature to raw r||s format.
- * Required because Node's crypto.sign() outputs DER, but JWTs expect raw.
- */
-function derToRaw(der: Buffer): Buffer {
-  // DER: 0x30 [total-len] 0x02 [r-len] [r] 0x02 [s-len] [s]
-  let offset = 2
-  if (der[1]! > 0x80) offset += der[1]! - 0x80 // long-form length
-
-  offset++ // skip 0x02 tag
-  const rLen = der[offset++]!
-  let r = der.subarray(offset, offset + rLen)
-  offset += rLen
-
-  offset++ // skip 0x02 tag
-  const sLen = der[offset++]!
-  let s = der.subarray(offset, offset + sLen)
-
-  // DER may pad with a leading zero byte to indicate positive — strip it
-  if (r.length > 32) r = r.subarray(r.length - 32)
-  if (s.length > 32) s = s.subarray(s.length - 32)
-
-  const raw = Buffer.alloc(64)
-  r.copy(raw, 32 - r.length)
-  s.copy(raw, 64 - s.length)
-  return raw
-}
+const url = await client.authorize(epdsUrl)
+url.searchParams.set('login_hint', email)
 ```
 
-## Nonce retry pattern (Flow 1 only)
-
-ePDS always rejects the first DPoP proof with a `400` and a `dpop-nonce`
-header. This is standard behaviour. For Flow 1 (hand-rolled), wrap every
-PAR and token request in this retry loop. Flow 2 does not need this —
-`NodeOAuthClient` handles nonce retry internally.
+The SDK handles PKCE, DPoP key generation and proof signing, nonce retry, PAR,
+token exchange, client assertions, and persisted OAuth state.
 
-```typescript
-async function fetchWithDpopRetry(
-  url: string,
-  body: URLSearchParams,
-  privateKey: crypto.KeyObject,
-  publicJwk: object,
-): Promise<Response> {
-  const makeProof = (nonce?: string) =>
-    createDpopProof({ privateKey, jwk: publicJwk, method: 'POST', url, nonce })
-
-  let res = await fetch(url, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/x-www-form-urlencoded',
-      DPoP: makeProof(),
-    },
-    body: body.toString(),
-  })
-
-  if (!res.ok) {
-    const nonce = res.headers.get('dpop-nonce')
-    if (nonce && res.status === 400) {
-      res = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/x-www-form-urlencoded',
-          DPoP: makeProof(nonce),
-        },
-        body: body.toString(),
-      })
-    }
-  }
-
-  return res
-}
-```
+See [`../SKILL.md`](../SKILL.md) for maintained integration guidance.