@hatk/hatk 0.0.1-alpha.1 → 0.0.1-alpha.100

package/dist/oauth/server.js

@@ -1,13 +1,37 @@
 // packages/hatk/src/oauth/server.ts
 import { generateKeyPair, importPrivateKey, computeJwkThumbprint, signJwt, parseJwt, verifyEs256, importPublicKey, randomToken, sha256, base64UrlEncode, } from "./crypto.js";
 import { parseDpopProof, createDpopProof } from "./dpop.js";
+import { initSession } from "./session.js";
 import { resolveClient, validateRedirectUri, isLoopbackClient } from "./client.js";
-import { discoverAuthServer, resolveHandle } from "./discovery.js";
-import { getServerKey, storeServerKey, storeOAuthRequest, getOAuthRequest, deleteOAuthRequest, storeAuthCode, consumeAuthCode, storeSession, checkAndStoreDpopJti, cleanupExpiredOAuth, storeRefreshToken, getRefreshToken, revokeRefreshToken, } from "./db.js";
+import { negotiateScope } from "./service-describe.js";
+import { discoverAuthServer, resolveHandle, fetchProtectedResourceMetadata, fetchAuthServerMetadata, } from "./discovery.js";
+import { getServerKey, storeServerKey, storeOAuthRequest, getOAuthRequest, deleteOAuthRequest, storeAuthCode, consumeAuthCode, storeSession, deleteSession, checkAndStoreDpopJti, cleanupExpiredOAuth, storeRefreshToken, getRefreshToken, revokeRefreshToken, } from "./db.js";
 import { emit } from "../logger.js";
-import { querySQL } from "../db.js";
-import { fireOnLoginHook } from "./hooks.js";
+import { querySQL } from "../database/db.js";
+import { fireOnLoginHook } from "../hooks.js";
 const SERVER_KEY_KID = 'appview-oauth-key';
+const CLIENT_KEY_KID = 'pds-client-auth-key';
+const CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
+/**
+ * RFC 6749 §5.2 OAuth token-endpoint error.
+ *
+ * Surfaces as HTTP `status` (default 400) with body
+ * `{ error: code, error_description: description }` so OAuth clients can
+ * distinguish a permanently-rejected refresh token (`invalid_grant`) from
+ * a transient server failure and decide whether to log the user out.
+ */
+export class OAuthError extends Error {
+    code;
+    description;
+    status;
+    constructor(code, description, status = 400) {
+        super(description);
+        this.code = code;
+        this.description = description;
+        this.status = status;
+        this.name = 'OAuthError';
+    }
+}
 async function resolveHandleForDid(did) {
     const rows = (await querySQL('SELECT handle FROM _repos WHERE did = $1', [did]));
     return rows[0]?.handle || undefined;
@@ -34,10 +58,58 @@ function pdsClientId(issuer, config) {
     }
     return `${issuer}/oauth-client-metadata.json`;
 }
+/**
+ * The endpoints a remote auth server advertises, taken from its metadata rather
+ * than rebuilt from its issuer.
+ *
+ * RFC 8414 requires `authorization_endpoint` and `token_endpoint` and the
+ * atproto OAuth profile requires PAR on top of that, so an auth server is free
+ * to serve any of them from a path of its choosing. Concatenating `/oauth/...`
+ * onto the issuer only ever worked because bsky.social and the reference PDS
+ * happen to use those paths.
+ *
+ * PAR keeps its legacy fallback: it was already read from metadata, and the
+ * fallback is what deployments without it have been relying on.
+ */
+function authServerEndpoints(metadata, authServer) {
+    if (!metadata.authorization_endpoint) {
+        throw new Error(`Auth server ${authServer} advertises no authorization_endpoint`);
+    }
+    if (!metadata.token_endpoint) {
+        throw new Error(`Auth server ${authServer} advertises no token_endpoint`);
+    }
+    return {
+        authorizationEndpoint: metadata.authorization_endpoint,
+        tokenEndpoint: metadata.token_endpoint,
+        parEndpoint: metadata.pushed_authorization_request_endpoint || `${authServer}/oauth/par`,
+    };
+}
+/**
+ * Endpoint stored on a request or session row, falling back to the path this
+ * used to hardcode. The fallback is for rows written before those columns
+ * existed, not for fresh discovery — a login started after the upgrade always
+ * has the advertised endpoint.
+ */
+function storedEndpoint(stored, authServer, legacyPath) {
+    return stored || `${authServer}${legacyPath}`;
+}
+/**
+ * Append query parameters to an endpoint URL. RFC 6749 §3.1 lets an
+ * authorization endpoint carry its own query component, which a bare
+ * `${endpoint}?${params}` would corrupt.
+ */
+function withQuery(endpoint, params) {
+    const url = new URL(endpoint);
+    for (const [key, value] of params)
+        url.searchParams.set(key, value);
+    return url.toString();
+}
 let serverPrivateJwk;
 let serverPublicJwk;
 let serverPrivateKey;
 let serverJkt;
+let clientPublicJwk;
+let clientPrivateKey;
 let _plcUrl;
 let _relayUrl;
 export async function initOAuth(_config, plcUrl, relayUrl) {
@@ -57,6 +129,26 @@ export async function initOAuth(_config, plcUrl, relayUrl) {
     }
     serverPrivateKey = await importPrivateKey(serverPrivateJwk);
     serverJkt = await computeJwkThumbprint(serverPublicJwk);
+    // Client-authentication key, kept separate from the access-token signing key
+    // above. A PDS binds each session to the kid that authenticated it and
+    // refuses a later refresh signed by a different one, so this key can't be
+    // rotated without signing every user out — keeping it distinct means the
+    // access-token key stays rotatable.
+    const existingClientKey = await getServerKey(CLIENT_KEY_KID);
+    let clientPrivateJwk;
+    if (existingClientKey) {
+        clientPrivateJwk = JSON.parse(existingClientKey.privateKey);
+        clientPublicJwk = JSON.parse(existingClientKey.publicKey);
+    }
+    else {
+        const kp = await generateKeyPair();
+        clientPrivateJwk = kp.privateJwk;
+        clientPublicJwk = kp.publicJwk;
+        await storeServerKey(CLIENT_KEY_KID, JSON.stringify(clientPrivateJwk), JSON.stringify(clientPublicJwk));
+    }
+    clientPrivateKey = await importPrivateKey(clientPrivateJwk);
+    // Initialize SSR session cookie signing
+    initSession(serverPrivateJwk, _config.cookieName);
     // Periodic cleanup of expired OAuth data
     setInterval(() => cleanupExpiredOAuth().catch(() => { }), 60_000);
 }
@@ -103,22 +195,96 @@ export function getJwks() {
         ],
     };
 }
+/**
+ * Whether we authenticate to PDSes as a confidential client.
+ *
+ * A confidential client gets a 2-year session and 3-month refresh window
+ * instead of 2 weeks, and is exempt from the consent screen atproto forces on
+ * every authorization request from a public client. It requires a fetchable
+ * `jwks_uri`, so loopback deployments (local dev) stay public.
+ */
+export function isConfidentialClient(issuer) {
+    return !isLoopbackClient(issuer);
+}
+/** Public half of the client-authentication key, for the PDS to verify assertions. */
+export function getClientJwks() {
+    return {
+        keys: [
+            {
+                ...clientPublicJwk,
+                kid: CLIENT_KEY_KID,
+                use: 'sig',
+                alg: 'ES256',
+            },
+        ],
+    };
+}
+/**
+ * A JWT proving we are this client, per RFC 7523. The PDS checks `sub` against
+ * the client_id it resolved and `aud` against its own issuer, then verifies the
+ * signature against the key it fetched from `jwks_uri`.
+ */
+async function createClientAssertion(issuer, config, audience) {
+    const clientId = pdsClientId(issuer, config);
+    const now = Math.floor(Date.now() / 1000);
+    return signJwt({ typ: 'JWT', alg: 'ES256', kid: CLIENT_KEY_KID }, {
+        iss: clientId,
+        sub: clientId,
+        aud: audience,
+        jti: randomToken(),
+        iat: now,
+        exp: now + 60,
+    }, clientPrivateKey);
+}
+/**
+ * Add client authentication to a PAR or token request body. No-op for loopback
+ * deployments, which stay public clients.
+ */
+async function withClientAuth(params, issuer, config, audience) {
+    if (!isConfidentialClient(issuer))
+        return params;
+    return {
+        ...params,
+        client_assertion_type: CLIENT_ASSERTION_TYPE,
+        client_assertion: await createClientAssertion(issuer, config, audience),
+    };
+}
 export function getClientMetadata(issuer, config) {
     // Find the metadata client entry to get its scope
     const metadataClientId = `${issuer}/oauth-client-metadata.json`;
     const clientConfig = config.clients.find((c) => c.client_id === metadataClientId);
+    const confidential = isConfidentialClient(issuer);
     return {
         client_id: metadataClientId,
         client_name: clientConfig?.client_name || 'hatk',
         redirect_uris: [`${issuer}/oauth/callback`],
         grant_types: ['authorization_code', 'refresh_token'],
         response_types: ['code'],
-        token_endpoint_auth_method: 'none',
+        // atproto requires the signing alg alongside private_key_jwt, and requires
+        // its absence for a public client.
+        ...(confidential
+            ? {
+                token_endpoint_auth_method: 'private_key_jwt',
+                token_endpoint_auth_signing_alg: 'ES256',
+                jwks_uri: `${issuer}/oauth/client-jwks.json`,
+            }
+            : { token_endpoint_auth_method: 'none' }),
         dpop_bound_access_tokens: true,
         scope: clientConfig?.scope || 'atproto transition:generic',
     };
 }
 // --- PAR Endpoint ---
+/**
+ * Handle a Pushed Authorization Request (PAR).
+ *
+ * Supports account creation via `prompt=create`. When set, `login_hint`
+ * is treated as a PDS hostname (e.g. "selfhosted.social" or "localhost:2583")
+ * rather than a handle or DID. The auth server is discovered from the PDS's
+ * protected resource metadata, and `prompt=create` is forwarded to the PDS
+ * PAR so it shows the signup page.
+ *
+ * For normal login, `login_hint` is a handle or DID as usual.
+ */
 export async function handlePar(config, body, dpopHeader, requestUrl) {
     // Validate client DPoP proof
     const dpop = await parseDpopProof(dpopHeader, 'POST', requestUrl);
@@ -143,36 +309,81 @@ export async function handlePar(config, body, dpopHeader, requestUrl) {
         throw new Error('code_challenge is required');
     if (body.code_challenge_method && body.code_challenge_method !== 'S256')
         throw new Error('Only S256 supported');
-    // Resolve DID from login_hint
+    // Resolve DID and PDS from login_hint
+    const prompt = body.prompt;
     let did = body.login_hint;
-    if (did && !did.startsWith('did:')) {
-        did = await resolveHandle(did, _relayUrl);
-    }
-    // Discover user's PDS auth server
     let pdsRequestUri;
     let pdsAuthServer;
+    let pdsAuthorizationEndpoint;
+    let pdsTokenEndpoint;
     let pdsCodeVerifier;
     let pdsState;
-    if (did) {
+    let pdsScope;
+    let pdsEndpoint;
+    if (prompt === 'create' && body.login_hint) {
+        // Account creation: login_hint is a PDS URL, discover auth server from it directly
+        let pdsUrl;
+        if (body.login_hint.startsWith('http')) {
+            pdsUrl = body.login_hint;
+        }
+        else if (body.login_hint.match(/^localhost[:/]/)) {
+            pdsUrl = `http://${body.login_hint}`;
+        }
+        else {
+            pdsUrl = `https://${body.login_hint}`;
+        }
+        pdsEndpoint = pdsUrl;
+        const protectedResource = await fetchProtectedResourceMetadata(pdsUrl);
+        pdsAuthServer = protectedResource.authorization_servers[0];
+        if (!pdsAuthServer)
+            throw new Error(`No auth server for PDS ${pdsUrl}`);
+        did = undefined; // no DID yet for account creation
+    }
+    else if (did && !did.startsWith('did:')) {
+        try {
+            did = await resolveHandle(did, _relayUrl);
+        }
+        catch {
+            throw new Error('Handle not found');
+        }
+    }
+    // Discover user's PDS auth server (for login flow with a resolved DID)
+    if (did && !pdsAuthServer) {
         const discovery = await discoverAuthServer(did, _plcUrl);
         pdsAuthServer = discovery.authServerEndpoint;
+        pdsEndpoint = discovery.pdsEndpoint;
+    }
+    if (pdsAuthServer) {
+        const authServerMetadata = await fetchAuthServerMetadata(pdsAuthServer);
+        const endpoints = authServerEndpoints(authServerMetadata, pdsAuthServer);
+        // Held for the authorize redirect and the token exchange, which run on
+        // later requests with only this row to go on.
+        pdsAuthorizationEndpoint = endpoints.authorizationEndpoint;
+        pdsTokenEndpoint = endpoints.tokenEndpoint;
         // Create PKCE for our PAR to the PDS
         pdsCodeVerifier = randomToken();
         const pdsCodeChallenge = base64UrlEncode(await sha256(pdsCodeVerifier));
         pdsState = randomToken(); // unique state to correlate callback
         // PAR to the PDS
-        const parEndpoint = discovery.authServerMetadata.pushed_authorization_request_endpoint || `${pdsAuthServer}/oauth/par`;
+        const parEndpoint = endpoints.parEndpoint;
         const serverDpopProof = await createDpopProof(serverPrivateJwk, serverPublicJwk, 'POST', parEndpoint);
-        const pdsParBody = new URLSearchParams({
+        pdsScope = await negotiateScope(config, body.scope || 'atproto transition:generic', pdsEndpoint, isLoopbackClient(config.issuer));
+        const pdsParParams = {
             client_id: pdsClientId(config.issuer, config),
             redirect_uri: pdsRedirectUri(config.issuer),
             response_type: 'code',
             code_challenge: pdsCodeChallenge,
             code_challenge_method: 'S256',
-            scope: body.scope || 'atproto transition:generic',
-            login_hint: body.login_hint || did,
+            scope: pdsScope,
             state: pdsState,
-        });
+        };
+        if (prompt === 'create') {
+            pdsParParams.prompt = 'create';
+        }
+        if (did) {
+            pdsParParams.login_hint = body.login_hint || did;
+        }
+        const pdsParBody = new URLSearchParams(await withClientAuth(pdsParParams, config.issuer, config, authServerMetadata.issuer || pdsAuthServer));
         const pdsParRes = await fetch(parEndpoint, {
             method: 'POST',
             headers: { 'Content-Type': 'application/x-www-form-urlencoded', DPoP: serverDpopProof },
@@ -234,10 +445,14 @@ export async function handlePar(config, body, dpopHeader, requestUrl) {
         dpopJkt: dpop.jkt,
         pdsRequestUri,
         pdsAuthServer,
+        pdsAuthorizationEndpoint,
+        pdsTokenEndpoint,
+        pdsEndpoint,
         pdsCodeVerifier,
         pdsState,
         did,
         loginHint: body.login_hint,
+        pdsScope,
         expiresAt,
     });
     return { request_uri: requestUri, expires_in: 600 };
@@ -251,12 +466,136 @@ export function buildAuthorizeRedirect(config, request) {
         request_uri: request.pds_request_uri,
         client_id: pdsClientId(config.issuer, config),
     });
-    return `${request.pds_auth_server}/oauth/authorize?${params}`;
+    return withQuery(storedEndpoint(request.pds_authorization_endpoint, request.pds_auth_server, '/oauth/authorize'), params);
+}
+// --- Server-initiated login (no DPoP required from browser) ---
+/**
+ * Initiate a server-side OAuth login or account creation flow.
+ *
+ * For account creation, pass `{ prompt: 'create', pds: 'selfhosted.social' }`.
+ * The `pds` is a bare hostname; the auth server is discovered from its
+ * protected resource metadata.
+ */
+export async function serverLogin(config, handle, options) {
+    let did;
+    let pdsAuthServer;
+    let pdsEndpoint;
+    if (options?.prompt === 'create' && options?.pds) {
+        // Account creation: discover auth server from PDS hostname
+        const pdsUrl = options.pds.startsWith('http')
+            ? options.pds
+            : options.pds.match(/^localhost[:/]/)
+                ? `http://${options.pds}`
+                : `https://${options.pds}`;
+        pdsEndpoint = pdsUrl;
+        const protectedResource = await fetchProtectedResourceMetadata(pdsUrl);
+        pdsAuthServer = protectedResource.authorization_servers[0];
+        if (!pdsAuthServer)
+            throw new Error(`No auth server for PDS ${pdsUrl}`);
+    }
+    else {
+        // Normal login: resolve handle to DID
+        did = handle;
+        if (!did.startsWith('did:')) {
+            did = await resolveHandle(handle, _relayUrl);
+        }
+        const discovery = await discoverAuthServer(did, _plcUrl);
+        pdsAuthServer = discovery.authServerEndpoint;
+        pdsEndpoint = discovery.pdsEndpoint;
+    }
+    const authServerMetadata = await fetchAuthServerMetadata(pdsAuthServer);
+    const endpoints = authServerEndpoints(authServerMetadata, pdsAuthServer);
+    // Create PKCE for PAR to PDS
+    const pdsCodeVerifier = randomToken();
+    const pdsCodeChallenge = base64UrlEncode(await sha256(pdsCodeVerifier));
+    const pdsState = randomToken();
+    // PAR to the PDS
+    const parEndpoint = endpoints.parEndpoint;
+    const serverDpopProof = await createDpopProof(serverPrivateJwk, serverPublicJwk, 'POST', parEndpoint);
+    const scope = await negotiateScope(config, config.scopes?.join(' ') || 'atproto transition:generic', pdsEndpoint, isLoopbackClient(config.issuer));
+    const pdsParParams = {
+        client_id: pdsClientId(config.issuer, config),
+        redirect_uri: pdsRedirectUri(config.issuer),
+        response_type: 'code',
+        code_challenge: pdsCodeChallenge,
+        code_challenge_method: 'S256',
+        scope,
+        state: pdsState,
+    };
+    if (options?.prompt === 'create') {
+        pdsParParams.prompt = 'create';
+    }
+    if (did) {
+        pdsParParams.login_hint = handle;
+    }
+    const pdsParBody = new URLSearchParams(await withClientAuth(pdsParParams, config.issuer, config, authServerMetadata.issuer || pdsAuthServer));
+    let pdsRequestUri;
+    const pdsParRes = await fetch(parEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded', DPoP: serverDpopProof },
+        body: pdsParBody.toString(),
+    });
+    if (!pdsParRes.ok) {
+        const errBody = await pdsParRes.json().catch(() => ({}));
+        if (errBody.error === 'use_dpop_nonce') {
+            const nonce = pdsParRes.headers.get('DPoP-Nonce');
+            if (nonce) {
+                const retryProof = await createDpopProof(serverPrivateJwk, serverPublicJwk, 'POST', parEndpoint, undefined, nonce);
+                const retryRes = await fetch(parEndpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/x-www-form-urlencoded', DPoP: retryProof },
+                    body: pdsParBody.toString(),
+                });
+                if (!retryRes.ok) {
+                    const retryErr = await retryRes.json().catch(() => ({}));
+                    throw new Error(`PDS PAR failed: ${retryRes.status} ${retryErr.error_description || retryErr.error || ''}`);
+                }
+                const retryData = await retryRes.json();
+                pdsRequestUri = retryData.request_uri;
+            }
+        }
+        else {
+            throw new Error(`PDS PAR failed: ${pdsParRes.status} ${errBody.error_description || errBody.error || ''}`);
+        }
+    }
+    else {
+        const pdsParData = await pdsParRes.json();
+        pdsRequestUri = pdsParData.request_uri;
+    }
+    // Store the request so the callback can find it
+    const requestUri = `urn:ietf:params:oauth:request_uri:${randomToken()}`;
+    const expiresAt = Math.floor(Date.now() / 1000) + 600;
+    await storeOAuthRequest(requestUri, {
+        clientId: pdsClientId(config.issuer, config),
+        redirectUri: '/',
+        scope,
+        state: pdsState,
+        codeChallenge: '',
+        codeChallengeMethod: 'S256',
+        dpopJkt: serverJkt,
+        pdsRequestUri,
+        pdsAuthServer,
+        pdsAuthorizationEndpoint: endpoints.authorizationEndpoint,
+        pdsTokenEndpoint: endpoints.tokenEndpoint,
+        pdsEndpoint,
+        pdsCodeVerifier,
+        pdsState,
+        did,
+        loginHint: handle,
+        pdsScope: scope,
+        expiresAt,
+    });
+    // Build redirect URL to PDS
+    const params = new URLSearchParams({
+        request_uri: pdsRequestUri,
+        client_id: pdsClientId(config.issuer, config),
+    });
+    return withQuery(endpoints.authorizationEndpoint, params);
 }
 // --- OAuth Callback (PDS redirects here) ---
 export async function handleCallback(config, code, state, iss) {
     // Find the matching OAuth request by pds_state (unique per PAR)
-    const { querySQL } = await import("../db.js");
+    const { querySQL } = await import("../database/db.js");
     let request = null;
     if (state) {
         const rows = await querySQL(`SELECT * FROM _oauth_requests WHERE pds_state = $1 AND expires_at > $2`, [
@@ -273,15 +612,15 @@ export async function handleCallback(config, code, state, iss) {
     if (!request)
         throw new Error('No matching authorization request found');
     // Exchange code at PDS token endpoint
-    const tokenEndpoint = `${request.pds_auth_server}/oauth/token`;
+    const tokenEndpoint = storedEndpoint(request.pds_token_endpoint, request.pds_auth_server, '/oauth/token');
     const serverDpopProof = await createDpopProof(serverPrivateJwk, serverPublicJwk, 'POST', tokenEndpoint);
-    const tokenBody = new URLSearchParams({
+    const tokenBody = new URLSearchParams(await withClientAuth({
         grant_type: 'authorization_code',
         code,
         redirect_uri: pdsRedirectUri(config.issuer),
         client_id: pdsClientId(config.issuer, config),
         code_verifier: request.pds_code_verifier,
-    });
+    }, config.issuer, config, request.pds_auth_server));
     let tokenRes = await fetch(tokenEndpoint, {
         method: 'POST',
         headers: { 'Content-Type': 'application/x-www-form-urlencoded', DPoP: serverDpopProof },
@@ -329,42 +668,78 @@ export async function handleCallback(config, code, state, iss) {
     const did = tokenData.sub;
     if (!did)
         throw new Error('PDS token response missing sub (DID)');
-    // Store PDS session server-side
+    // Store PDS session server-side — pds_endpoint is the actual data PDS
+    // (e.g. leccinum.us-west.host.bsky.network), pds_auth_server is the OAuth server (bsky.social)
     await storeSession(did, {
-        pdsEndpoint: request.pds_auth_server.replace('/oauth', ''),
+        pdsEndpoint: request.pds_endpoint,
+        pdsAuthServer: request.pds_auth_server,
+        pdsTokenEndpoint: tokenEndpoint,
         accessToken: tokenData.access_token,
         refreshToken: tokenData.refresh_token,
         dpopJkt: serverJkt,
         tokenExpiresAt: tokenData.expires_in ? Math.floor(Date.now() / 1000) + tokenData.expires_in : undefined,
+        requestedScope: request.pds_scope ?? undefined,
+        grantedScope: typeof tokenData.scope === 'string' ? tokenData.scope : undefined,
     });
-    await fireOnLoginHook(did);
+    await fireOnLoginHook(did, config);
     // Generate authorization code for the client
     const clientCode = randomToken();
     await storeAuthCode(clientCode, request.request_uri);
     // Update the request with the DID (in case it wasn't set during PAR)
     if (!request.did && did) {
-        const { runSQL } = await import("../db.js");
-        await runSQL('UPDATE _oauth_requests SET did = $1 WHERE request_uri = $2', did, request.request_uri);
+        const { runSQL } = await import("../database/db.js");
+        await runSQL('UPDATE _oauth_requests SET did = $1 WHERE request_uri = $2', [did, request.request_uri]);
     }
     // Build redirect back to client
     const params = new URLSearchParams({ code: clientCode, iss: config.issuer });
     if (request.state)
         params.set('state', request.state);
     const clientRedirectUri = `${request.redirect_uri}?${params}`;
-    return { requestUri: request.request_uri, clientRedirectUri, clientState: request.state };
+    return { requestUri: request.request_uri, clientRedirectUri, clientState: request.state, did };
+}
+/**
+ * Handle an error redirect from the PDS (user denied, request expired, etc).
+ *
+ * The PDS reports failures by redirecting to our callback with `error` and no
+ * `code`. Discard the pending request and return a URL that hands the error
+ * back to the app, so the browser lands somewhere renderable instead of on a
+ * raw error response.
+ */
+export async function handleCallbackError(config, error, errorDescription, state) {
+    let request = null;
+    if (state) {
+        const rows = await querySQL(`SELECT * FROM _oauth_requests WHERE pds_state = $1`, [state]);
+        request = rows.length > 0 ? rows[0] : null;
+    }
+    if (request)
+        await deleteOAuthRequest(request.request_uri);
+    emit('oauth', 'pds_callback_error', { error, error_description: errorDescription, matched: !!request });
+    const params = new URLSearchParams({ error });
+    if (errorDescription)
+        params.set('error_description', errorDescription);
+    // Server-initiated logins store redirect_uri as '/' — send the browser home
+    // with the error attached. Same for an unmatched state (expired or replayed).
+    if (!request || request.redirect_uri === '/')
+        return `/?${params}`;
+    // Client flow: echo the client's state and our issuer so the SPA's callback
+    // handler recognises the redirect as its own rather than re-entering here.
+    if (request.state)
+        params.set('state', request.state);
+    params.set('iss', config.issuer);
+    return `${request.redirect_uri}?${params}`;
 }
 // --- Token Endpoint ---
 export async function handleToken(config, body, dpopHeader, requestUrl) {
     const grantType = body.grant_type;
     if (!grantType)
-        throw new Error('grant_type is required');
+        throw new OAuthError('invalid_request', 'grant_type is required');
     if (grantType === 'authorization_code') {
         return handleAuthorizationCodeGrant(config, body, dpopHeader, requestUrl);
     }
     else if (grantType === 'refresh_token') {
         return handleRefreshTokenGrant(config, body, dpopHeader, requestUrl);
     }
-    throw new Error(`Unsupported grant_type: ${grantType}`);
+    throw new OAuthError('unsupported_grant_type', `Unsupported grant_type: ${grantType}`);
 }
 async function handleAuthorizationCodeGrant(config, body, dpopHeader, requestUrl) {
     const dpop = await parseDpopProof(dpopHeader, 'POST', requestUrl);
@@ -437,20 +812,21 @@ async function handleRefreshTokenGrant(config, body, dpopHeader, requestUrl) {
     const dpop = await parseDpopProof(dpopHeader, 'POST', requestUrl);
     const fresh = await checkAndStoreDpopJti(dpop.jti, dpop.iat + 300);
     if (!fresh)
-        throw new Error('DPoP jti replay detected');
+        throw new OAuthError('invalid_request', 'DPoP jti replay detected');
     const { refresh_token, client_id } = body;
     if (!refresh_token || !client_id)
-        throw new Error('Missing required parameters');
-    // Look up and validate refresh token
+        throw new OAuthError('invalid_request', 'Missing required parameters');
+    // Look up and validate refresh token. Per RFC 6749 §5.2, all of these are
+    // `invalid_grant` — the client must treat them as terminal and re-authenticate.
     const stored = await getRefreshToken(refresh_token);
     if (!stored)
-        throw new Error('Invalid refresh token');
+        throw new OAuthError('invalid_grant', 'Invalid refresh token');
     if (stored.revoked)
-        throw new Error('Refresh token revoked');
+        throw new OAuthError('invalid_grant', 'Refresh token revoked');
     if (stored.expires_at && stored.expires_at < Math.floor(Date.now() / 1000))
-        throw new Error('Refresh token expired');
+        throw new OAuthError('invalid_grant', 'Refresh token expired');
     if (stored.client_id !== client_id)
-        throw new Error('client_id mismatch');
+        throw new OAuthError('invalid_grant', 'client_id mismatch');
     // Revoke old refresh token (rotation)
     await revokeRefreshToken(refresh_token);
     const did = stored.did;
@@ -488,18 +864,101 @@ async function handleRefreshTokenGrant(config, body, dpopHeader, requestUrl) {
         handle,
     };
 }
+// --- Sessions obtained outside the redirect flow ---
+/** A refusal from the endpoint {@link obtainSession} called, or an answer it cannot use. */
+export class ObtainSessionError extends Error {
+    error;
+    status;
+    constructor(
+    /** The endpoint's error code, e.g. an XRPC error name. */
+    error, message, status) {
+        super(message);
+        this.error = error;
+        this.status = status;
+    }
+}
+/**
+ * Obtain a session for another account straight from its authorization server,
+ * outside the redirect flow: a group host creating an account for this app and
+ * handing it a session, say.
+ *
+ * `body` is POSTed as JSON to `url` as this app's OAuth client, the way the
+ * token endpoint is called: `client_id` and, for a confidential client, a client
+ * assertion addressed to the endpoint's origin, are added to it, and the request
+ * carries a DPoP proof from the app's key, answering a nonce challenge once.
+ * `headers` are sent too, for whatever else the endpoint wants to know (service
+ * auth from the viewer, typically).
+ *
+ * The response must hold an OAuth token response, at `session` or as the whole
+ * body. That session is stored for its `sub` exactly as a login's is, bound to
+ * the same DPoP key, so refresh and the PDS helpers work for that DID from here
+ * on. It is only accepted if the account's own authorization server is the one
+ * that answered: an endpoint cannot hand over a session for an account it does
+ * not serve.
+ */
+export async function obtainSession(config, url, body, opts = {}) {
+    const origin = new URL(url).origin;
+    const payload = {
+        ...body,
+        ...(await withClientAuth({ client_id: pdsClientId(config.issuer, config) }, config.issuer, config, origin)),
+    };
+    const send = async (nonce) => fetch(url, {
+        method: 'POST',
+        headers: {
+            ...opts.headers,
+            'Content-Type': 'application/json',
+            DPoP: await createDpopProof(serverPrivateJwk, serverPublicJwk, 'POST', url, undefined, nonce),
+        },
+        body: JSON.stringify(payload),
+    });
+    let res = await send();
+    let out = (await res.json().catch(() => ({})));
+    const nonce = res.headers.get('DPoP-Nonce');
+    if (!res.ok && out.error === 'use_dpop_nonce' && nonce) {
+        res = await send(nonce);
+        out = (await res.json().catch(() => ({})));
+    }
+    if (!res.ok) {
+        throw new ObtainSessionError(typeof out.error === 'string' ? out.error : 'UpstreamFailure', String(out.message ?? out.error_description ?? `${url} failed (${res.status})`), res.status);
+    }
+    const token = (typeof out.session === 'object' && out.session ? out.session : out);
+    const did = token.sub;
+    if (typeof did !== 'string' || typeof token.access_token !== 'string') {
+        throw new ObtainSessionError('NoSession', `${url} returned no session`, 502);
+    }
+    const { pdsEndpoint, authServerEndpoint, authServerMetadata } = await discoverAuthServer(did, _plcUrl);
+    if (new URL(authServerEndpoint).origin !== origin) {
+        throw new ObtainSessionError('WrongAuthServer', `${origin} is not the authorization server for ${did}`, 502);
+    }
+    await storeSession(did, {
+        pdsEndpoint,
+        pdsAuthServer: authServerEndpoint,
+        pdsTokenEndpoint: authServerMetadata.token_endpoint,
+        accessToken: token.access_token,
+        refreshToken: typeof token.refresh_token === 'string' ? token.refresh_token : undefined,
+        dpopJkt: serverJkt,
+        tokenExpiresAt: typeof token.expires_in === 'number' ? Math.floor(Date.now() / 1000) + token.expires_in : undefined,
+        requestedScope: typeof body.scope === 'string' ? body.scope : undefined,
+        grantedScope: typeof token.scope === 'string' ? token.scope : undefined,
+    });
+    emit('oauth', 'session_obtained', { did, from: origin });
+    return { did, response: out };
+}
 // --- PDS Session Refresh ---
 export async function refreshPdsSession(config, session) {
     if (!session.refresh_token)
         return null;
-    const tokenEndpoint = `${session.pds_endpoint}/oauth/token`;
+    // Prefer the endpoint the auth server advertised when this session was
+    // authorized. Sessions predating that column fall back to the auth server
+    // (or, older still, the PDS) with the path this used to hardcode.
+    const tokenEndpoint = storedEndpoint(session.pds_token_endpoint, session.pds_auth_server || session.pds_endpoint, '/oauth/token');
     const clientId = pdsClientId(config.issuer, config);
     const dpopProof = await createDpopProof(serverPrivateJwk, serverPublicJwk, 'POST', tokenEndpoint);
-    const body = new URLSearchParams({
+    const body = new URLSearchParams(await withClientAuth({
         grant_type: 'refresh_token',
         refresh_token: session.refresh_token,
         client_id: clientId,
-    });
+    }, config.issuer, config, session.pds_auth_server || session.pds_endpoint));
     let tokenRes = await fetch(tokenEndpoint, {
         method: 'POST',
         headers: { 'Content-Type': 'application/x-www-form-urlencoded', DPoP: dpopProof },
@@ -526,16 +985,22 @@ export async function refreshPdsSession(config, session) {
             did: session.did,
             pds_endpoint: session.pds_endpoint,
         });
+        await deleteSession(session.did);
         return null;
     }
     const tokenData = await tokenRes.json();
     // Update stored session
     await storeSession(session.did, {
         pdsEndpoint: session.pds_endpoint,
+        pdsAuthServer: session.pds_auth_server,
+        pdsTokenEndpoint: session.pds_token_endpoint,
         accessToken: tokenData.access_token,
         refreshToken: tokenData.refresh_token || session.refresh_token,
         dpopJkt: session.dpop_jkt,
         tokenExpiresAt: tokenData.expires_in ? Math.floor(Date.now() / 1000) + tokenData.expires_in : undefined,
+        // A refresh renews the grant, it does not renegotiate it.
+        requestedScope: session.requested_scope ?? undefined,
+        grantedScope: typeof tokenData.scope === 'string' ? tokenData.scope : (session.granted_scope ?? undefined),
     });
     return {
         accessToken: tokenData.access_token,