@startup-api/cloudflare 0.3.1 → 0.4.0

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

package/src/auth/atproto/identity.ts

@@ -0,0 +1,178 @@
+/**
+ * AT Protocol identity resolution. Given a user-supplied handle or DID we walk the full discovery
+ * chain — with NO hardcoded Bluesky/PDS hosts — to find the authorization server that owns the
+ * identity:
+ *
+ *   handle ──▶ DID            (HTTPS `.well-known/atproto-did`, then DNS TXT `_atproto.<handle>` via DoH)
+ *   DID    ──▶ DID document   (did:plc via a PLC directory, did:web via the domain's `.well-known`)
+ *   DID doc──▶ PDS endpoint   (the `#atproto_pds` service)
+ *   PDS    ──▶ auth server    (`.well-known/oauth-protected-resource` → `.well-known/oauth-authorization-server`)
+ *
+ * The PLC directory and DNS-over-HTTPS resolver are generic, swappable infrastructure (overridable via
+ * env), not identity providers — every account hosts its own PDS and authorization server, which we
+ * discover dynamically here.
+ */
+
+const DID_PREFIX = /^did:(plc|web):/;
+
+export interface AuthServerMetadata {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  pushed_authorization_request_endpoint: string;
+  [key: string]: unknown;
+}
+
+export interface ResolvedIdentity {
+  did: string;
+  handle?: string;
+  pds: string;
+  authServer: AuthServerMetadata;
+}
+
+export interface ResolverOptions {
+  /** PLC directory base URL for resolving did:plc. Defaults to the canonical https://plc.directory. */
+  plcUrl?: string;
+  /** DNS-over-HTTPS endpoint (RFC 8484 JSON) for the `_atproto.<handle>` TXT fallback. */
+  dohUrl?: string;
+}
+
+const DEFAULT_PLC_URL = 'https://plc.directory';
+const DEFAULT_DOH_URL = 'https://cloudflare-dns.com/dns-query';
+
+async function fetchJson(url: string, init?: RequestInit): Promise<any> {
+  const res = await fetch(url, init);
+  if (!res.ok) throw new Error(`Request to ${url} failed: ${res.status} ${res.statusText}`);
+  return res.json();
+}
+
+/** Resolve a handle to a DID via the HTTPS well-known method, falling back to DNS TXT over DoH. */
+async function resolveHandleToDid(handle: string, options: ResolverOptions): Promise<string> {
+  // 1. HTTPS well-known (works for any host that serves it; no third-party dependency).
+  try {
+    const res = await fetch(`https://${handle}/.well-known/atproto-did`, { redirect: 'error' });
+    if (res.ok) {
+      const did = (await res.text()).trim();
+      if (DID_PREFIX.test(did)) return did;
+    }
+  } catch {
+    // Fall through to DNS-based resolution.
+  }
+
+  // 2. DNS TXT `_atproto.<handle>` via DNS-over-HTTPS.
+  try {
+    const dohUrl = new URL(options.dohUrl || DEFAULT_DOH_URL);
+    dohUrl.searchParams.set('name', `_atproto.${handle}`);
+    dohUrl.searchParams.set('type', 'TXT');
+    const data = await fetchJson(dohUrl.toString(), { headers: { accept: 'application/dns-json' } });
+    for (const answer of data.Answer ?? []) {
+      const txt = String(answer.data ?? '').replace(/^"|"$/g, '');
+      if (txt.startsWith('did=')) {
+        const did = txt.slice(4).trim();
+        if (DID_PREFIX.test(did)) return did;
+      }
+    }
+  } catch {
+    // Fall through to the error below.
+  }
+
+  throw new Error(`Could not resolve handle "${handle}" to a DID`);
+}
+
+/** Fetch and return the DID document for a did:plc or did:web identifier. */
+async function resolveDidDocument(did: string, options: ResolverOptions): Promise<any> {
+  if (did.startsWith('did:plc:')) {
+    const base = (options.plcUrl || DEFAULT_PLC_URL).replace(/\/$/, '');
+    return fetchJson(`${base}/${did}`);
+  }
+  if (did.startsWith('did:web:')) {
+    // did:web:example.com[:path...] → https://example.com[/path...]/did.json (or /.well-known/did.json).
+    const rest = did.slice('did:web:'.length);
+    const segments = rest.split(':').map((s) => decodeURIComponent(s));
+    const host = segments.shift();
+    if (!host) throw new Error(`Malformed did:web identifier: ${did}`);
+    const path = segments.length ? `/${segments.join('/')}/did.json` : '/.well-known/did.json';
+    return fetchJson(`https://${host}${path}`);
+  }
+  throw new Error(`Unsupported DID method: ${did}`);
+}
+
+/** Extract the PDS service endpoint from a DID document. */
+function getPdsEndpoint(didDoc: any): string {
+  const services: any[] = Array.isArray(didDoc?.service) ? didDoc.service : [];
+  const pds = services.find(
+    (s) => s?.id === '#atproto_pds' || (typeof s?.id === 'string' && s.id.endsWith('#atproto_pds')) || s?.type === 'AtprotoPersonalDataServer',
+  );
+  const endpoint = typeof pds?.serviceEndpoint === 'string' ? pds.serviceEndpoint : pds?.serviceEndpoint?.uri;
+  if (!endpoint) throw new Error('DID document does not advertise an atproto PDS endpoint');
+  return endpoint.replace(/\/$/, '');
+}
+
+/** Extract the primary handle (`at://<handle>`) from a DID document's alsoKnownAs, if present. */
+function getHandle(didDoc: any): string | undefined {
+  const aka: string[] = Array.isArray(didDoc?.alsoKnownAs) ? didDoc.alsoKnownAs : [];
+  const at = aka.find((a) => typeof a === 'string' && a.startsWith('at://'));
+  return at ? at.slice('at://'.length) : undefined;
+}
+
+/** Resolve a PDS to its authorization server metadata via the protected-resource indirection. */
+async function resolveAuthServer(pds: string): Promise<AuthServerMetadata> {
+  const protectedResource = await fetchJson(new URL('/.well-known/oauth-protected-resource', pds).toString());
+  const issuer: string | undefined = protectedResource?.authorization_servers?.[0];
+  if (!issuer) throw new Error(`PDS ${pds} does not declare an authorization server`);
+
+  const metadata = (await fetchJson(new URL('/.well-known/oauth-authorization-server', issuer).toString())) as AuthServerMetadata;
+  if (!metadata.authorization_endpoint || !metadata.token_endpoint || !metadata.pushed_authorization_request_endpoint) {
+    throw new Error(`Authorization server ${issuer} is missing required OAuth endpoints (PAR is mandatory for atproto)`);
+  }
+  return metadata;
+}
+
+/**
+ * Full identity → authorization-server resolution. Accepts a handle (optionally `@`-prefixed) or a DID.
+ */
+export async function resolveIdentity(input: string, options: ResolverOptions = {}): Promise<ResolvedIdentity> {
+  const cleaned = input.trim().replace(/^@/, '');
+  if (!cleaned) throw new Error('Empty atproto identifier');
+
+  const isDid = cleaned.startsWith('did:');
+  let handle: string | undefined = isDid ? undefined : cleaned;
+  const did = isDid ? cleaned : await resolveHandleToDid(cleaned, options);
+
+  const didDoc = await resolveDidDocument(did, options);
+  const pds = getPdsEndpoint(didDoc);
+  if (!handle) handle = getHandle(didDoc);
+
+  const authServer = await resolveAuthServer(pds);
+  return { did, handle, pds, authServer };
+}
+
+/**
+ * Fetch a public actor profile record from the user's PDS to populate display name and avatar. Best
+ * effort: getRecord is an unauthenticated read, and any failure falls back to the handle/DID.
+ */
+export async function fetchProfile(pds: string, did: string, handle?: string): Promise<{ name?: string; picture?: string }> {
+  try {
+    const url = new URL('/xrpc/com.atproto.repo.getRecord', pds);
+    url.searchParams.set('repo', did);
+    url.searchParams.set('collection', 'app.bsky.actor.profile');
+    url.searchParams.set('rkey', 'self');
+
+    const res = await fetch(url.toString());
+    if (!res.ok) return { name: handle };
+
+    const data = (await res.json()) as { value?: { displayName?: string; avatar?: { ref?: { $link?: string } } } };
+    const value = data.value ?? {};
+    let picture: string | undefined;
+    const cid = value.avatar?.ref?.$link;
+    if (cid) {
+      const blob = new URL('/xrpc/com.atproto.sync.getBlob', pds);
+      blob.searchParams.set('did', did);
+      blob.searchParams.set('cid', cid);
+      picture = blob.toString();
+    }
+    return { name: value.displayName || handle, picture };
+  } catch {
+    return { name: handle };
+  }
+}