@hatk/hatk 0.0.1-alpha.60 → 0.0.1-alpha.62

package/dist/backfill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backfill.d.ts","sourceRoot":"","sources":["../src/backfill.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAIjD,6CAA6C;AAC7C,UAAU,YAAY;IACpB,wFAAwF;IACxF,MAAM,EAAE,MAAM,CAAA;IACd,8FAA8F;IAC9F,MAAM,EAAE,MAAM,CAAA;IACd,yEAAyE;IACzE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,wDAAwD;IACxD,MAAM,EAAE,cAAc,CAAA;CACvB;AAoGD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkK/G;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAkIrE"}
+{"version":3,"file":"backfill.d.ts","sourceRoot":"","sources":["../src/backfill.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAIjD,6CAA6C;AAC7C,UAAU,YAAY;IACpB,wFAAwF;IACxF,MAAM,EAAE,MAAM,CAAA;IACd,8FAA8F;IAC9F,MAAM,EAAE,MAAM,CAAA;IACd,yEAAyE;IACzE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,wDAAwD;IACxD,MAAM,EAAE,cAAc,CAAA;CACvB;AA+FD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkK/G;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAkIrE"}

package/dist/backfill.js

@@ -5,14 +5,14 @@ import { setRepoStatus, getRepoStatus, getRepoRev, getRepoRetryInfo, listRetryEl
 import { emit, timer } from "./logger.js";
 import { validateRecord } from '@bigmoves/lexicon';
 import { getLexiconArray } from "./database/schema.js";
-/** In-memory cache of DID → PDS resolution results to avoid redundant lookups. */
-const pdsCache = new Map();
 let plcUrl;
 /**
  * Resolves a DID to its PDS endpoint and handle by fetching the DID document.
  *
  * Supports both `did:web` (fetches `/.well-known/did.json`) and `did:plc`
- * (fetches from the PLC directory). Results are cached for the lifetime of the process.
+ * (fetches from the PLC directory). Always fetches fresh — DID docs change
+ * (handle renames, PDS migrations) and a stale cache silently rewrites stale
+ * handles back into `_repos` on every backfill.
  *
  * @example
  * ```ts
@@ -22,9 +22,6 @@ let plcUrl;
  * ```
  */
 async function resolvePds(did) {
-    const cached = pdsCache.get(did);
-    if (cached)
-        return cached;
     let didDoc;
     if (did.startsWith('did:web:')) {
         const domain = did.slice('did:web:'.length);
@@ -42,12 +39,10 @@ async function resolvePds(did) {
     const pds = didDoc.service?.find((s) => s.id === '#atproto_pds')?.serviceEndpoint;
     if (!pds)
         throw new Error(`No PDS endpoint in DID document for ${did}`);
-    // Extract handle from alsoKnownAs (format: "at://handle")
+    // First at:// entry in alsoKnownAs is the canonical handle (per @atproto/identity convention)
     const aka = didDoc.alsoKnownAs?.find((u) => u.startsWith('at://'));
     const handle = aka ? aka.slice('at://'.length) : null;
-    const result = { pds, handle };
-    pdsCache.set(did, result);
-    return result;
+    return { pds, handle };
 }
 /**
  * Paginates through all active repos on a relay/PDS using `com.atproto.sync.listRepos`.

package/dist/dev-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev-entry.d.ts","sourceRoot":"","sources":["../src/dev-entry.ts"],"names":[],"mappings":"AA6GA,eAAO,MAAM,OAAO,yCAKlB,CAAA;AAEF,yEAAyE;AACzE,wBAAsB,YAAY,kBAEjC;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"dev-entry.d.ts","sourceRoot":"","sources":["../src/dev-entry.ts"],"names":[],"mappings":"AA8GA,eAAO,MAAM,OAAO,yCAKlB,CAAA;AAEF,yEAAyE;AACzE,wBAAsB,YAAY,kBAEjC;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/dev-entry.js

@@ -73,6 +73,7 @@ const collectionSet = new Set(collections);
 const cursor = await getCursor('relay');
 startIndexer({
     relayUrl: config.relay,
+    plcUrl: config.plc,
     collections: collectionSet,
     signalCollections: config.backfill.signalCollections ? new Set(config.backfill.signalCollections) : undefined,
     pinnedRepos: config.backfill.repos ? new Set(config.backfill.repos) : undefined,

package/dist/indexer.d.ts

@@ -12,6 +12,7 @@ export declare function triggerAutoBackfill(did: string, attempt?: number): Prom
 /** Configuration for the firehose indexer. */
 interface IndexerOpts {
     relayUrl: string;
+    plcUrl: string;
     collections: Set<string>;
     signalCollections?: Set<string>;
     pinnedRepos?: Set<string>;

package/dist/indexer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../src/indexer.ts"],"names":[],"mappings":"AAmKA;;;;;;;GAOG;AACH,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxD;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CA4EjF;AAED,8CAA8C;AAC9C,UAAU,WAAW;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAyBD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAmDxE"}
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../src/indexer.ts"],"names":[],"mappings":"AAoKA;;;;;;;GAOG;AACH,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxD;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CA4EjF;AAED,8CAA8C;AAC9C,UAAU,WAAW;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAyBD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAoDxE"}

package/dist/indexer.js

@@ -29,6 +29,7 @@ let indexerSignalCollections;
 let indexerPinnedRepos = null;
 let indexerFetchTimeout;
 let indexerMaxRetries;
+let indexerPlcUrl;
 let maxConcurrentBackfills = 3;
 /**
  * Flush the write buffer — insert all buffered records, update the relay cursor,
@@ -259,6 +260,7 @@ export async function startIndexer(opts) {
     indexerPinnedRepos = opts.pinnedRepos || null;
     indexerFetchTimeout = fetchTimeout;
     indexerMaxRetries = opts.maxRetries;
+    indexerPlcUrl = opts.plcUrl;
     maxConcurrentBackfills = opts.parallelism ?? 3;
     // Pre-populate repo status cache from DB so non-signal updates
     // (e.g. profile changes) are processed for already-tracked DIDs
@@ -287,8 +289,8 @@ export async function startIndexer(opts) {
             const bytes = new Uint8Array(event.data);
             processMessage(bytes, collections);
         }
-        catch {
-            // Skip unparseable firehose messages silently
+        catch (err) {
+            emit('indexer', 'decode_error', { error: err instanceof Error ? err.message : String(err) });
         }
     });
     ws.addEventListener('open', () => log('[indexer] Connected to relay'));
@@ -298,6 +300,60 @@ export async function startIndexer(opts) {
     });
     return ws;
 }
+/**
+ * Handle a `#identity` firehose event for a DID. The `handle` field on the
+ * event is optional per the lexicon, and some emitters omit it (signalling
+ * "re-resolve"). When absent, we re-resolve from the PLC directory so handle
+ * renames propagate even when the relay payload is sparse.
+ *
+ * Only updates DIDs we already track (present in repoStatusCache) to avoid
+ * writing rows for the entire network.
+ */
+async function handleIdentityEvent(did, payloadHandle) {
+    if (!repoStatusCache.has(did))
+        return;
+    let handle = payloadHandle;
+    const payloadHadHandle = handle !== undefined;
+    if (!handle) {
+        try {
+            // Bound the PLC fetch so a slow plc.directory can't pile up unbounded
+            // promises during an identity-event burst (fire-and-forget caller).
+            const res = await fetch(`${indexerPlcUrl}/${did}`, {
+                signal: AbortSignal.timeout(indexerFetchTimeout * 1000),
+            });
+            if (res.ok) {
+                const doc = (await res.json());
+                // First at:// entry is the canonical handle (per @atproto/identity convention)
+                const aka = doc.alsoKnownAs?.find((u) => u.startsWith('at://'));
+                handle = aka ? aka.slice('at://'.length) : undefined;
+            }
+            else {
+                emit('indexer', 'identity_resolve_error', { did, status: res.status });
+            }
+        }
+        catch (err) {
+            emit('indexer', 'identity_resolve_error', {
+                did,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (!handle) {
+        emit('indexer', 'identity_no_handle', { did, payload_had_handle: payloadHadHandle });
+        return;
+    }
+    try {
+        await updateRepoHandle(did, handle);
+        emit('indexer', 'identity_handle_update', { did, handle, payload_had_handle: payloadHadHandle });
+    }
+    catch (err) {
+        emit('indexer', 'identity_update_error', {
+            did,
+            handle,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
 /**
  * Process a single firehose message. Decodes the CBOR header/body, filters
  * for relevant collections, validates records against lexicons, and routes
@@ -306,13 +362,13 @@ export async function startIndexer(opts) {
 function processMessage(bytes, collections) {
     const header = cborDecode(bytes, 0);
     const body = cborDecode(bytes, header.offset);
-    // Handle identity events (handle changes)
+    // Handle identity events (handle changes). Fire-and-forget — keeps
+    // processMessage synchronous so the WS event loop drains without backpressure.
     if (header.value.t === '#identity') {
-        const did = body.value.did;
-        const handle = body.value.handle;
-        if (did && handle && repoStatusCache.has(did)) {
-            updateRepoHandle(did, handle).catch(() => { });
-        }
+        const did = typeof body.value.did === 'string' ? body.value.did : undefined;
+        const handle = typeof body.value.handle === 'string' ? body.value.handle : undefined;
+        if (did)
+            handleIdentityEvent(did, handle);
         return;
     }
     if (header.value.op !== 1 || header.value.t !== '#commit')

package/dist/main.js

@@ -200,6 +200,7 @@ log(`  Feeds: ${listFeeds()
 const cursor = await getCursor('relay');
 startIndexer({
     relayUrl: config.relay,
+    plcUrl: config.plc,
     collections: collectionSet,
     signalCollections: config.backfill.signalCollections ? new Set(config.backfill.signalCollections) : undefined,
     pinnedRepos: config.backfill.repos ? new Set(config.backfill.repos) : undefined,

package/dist/oauth/server.d.ts

@@ -1,4 +1,18 @@
 import type { OAuthConfig } from '../config.ts';
+/**
+ * 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 declare class OAuthError extends Error {
+    readonly code: 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'unauthorized_client' | 'unsupported_grant_type' | 'invalid_scope';
+    readonly description: string;
+    readonly status: number;
+    constructor(code: 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'unauthorized_client' | 'unsupported_grant_type' | 'invalid_scope', description: string, status?: number);
+}
 export declare function initOAuth(_config: OAuthConfig, plcUrl: string, relayUrl: string): Promise<void>;
 export declare function getAuthServerMetadata(issuer: string, config: OAuthConfig): {
     issuer: string;

package/dist/oauth/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/oauth/server.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AA4E/C,wBAAsB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBrG;AAID,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;;;;;;;;;;;;;;;;;;;EAqBxE;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;;;;;EAO/E;AAED,wBAAgB,OAAO;;;;;;;;;;;;;;;;;;;;;;EAWtB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;;;;;;;;;EAcpE;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAwKtD;AAID,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,GAAG,MAAM,CAShF;AAID;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1C,OAAO,CAAC,MAAM,CAAC,CA6HjB;AAID,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CA2HrG;AAID,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,GAAG,CAAC,CAUd;AA0JD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChH,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAsEpF;AAID,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA0BjC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/oauth/server.ts"],"names":[],"mappings":"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"}

package/dist/oauth/server.js

@@ -9,6 +9,26 @@ import { emit } from "../logger.js";
 import { querySQL } from "../database/db.js";
 import { fireOnLoginHook } from "../hooks.js";
 const SERVER_KEY_KID = 'appview-oauth-key';
+/**
+ * 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;
@@ -530,14 +550,14 @@ export async function handleCallback(config, code, state, iss) {
 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);
@@ -610,20 +630,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;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAyDA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AA2B9C;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAgM3F;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,EAAE,WAAW,GAAG,IAAI,CAAA;IACzB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACxF,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAC5D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACtB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA+zB5F;AAGD,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE,EACrB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,KAAK,EAAE,WAAW,GAAG,IAAI,EACzB,MAAM,GAAE,MAAM,EAAO,EACrB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC5D,QAAQ,CAAC,EAAE,MAAM,IAAI,GACpB,OAAO,WAAW,EAAE,MAAM,CAG5B"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AA0DA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AA2B9C;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAgM3F;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,EAAE,WAAW,GAAG,IAAI,CAAA;IACzB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACxF,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAC5D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACtB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA00B5F;AAGD,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE,EACrB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,KAAK,EAAE,WAAW,GAAG,IAAI,EACzB,MAAM,GAAE,MAAM,EAAO,EACrB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC5D,QAAQ,CAAC,EAAE,MAAM,IAAI,GACpB,OAAO,WAAW,EAAE,MAAM,CAG5B"}

package/dist/server.js

@@ -9,7 +9,7 @@ import { handleOpengraphRequest, buildOgMeta } from "./opengraph.js";
 import { getLabelDefinitions, rescanLabels } from "./labels.js";
 import { triggerAutoBackfill } from "./indexer.js";
 import { emit, timer } from "./logger.js";
-import { getAuthServerMetadata, getProtectedResourceMetadata, getJwks, getClientMetadata, handlePar, buildAuthorizeRedirect, handleCallback, serverLogin, handleToken, authenticate, } from "./oauth/server.js";
+import { getAuthServerMetadata, getProtectedResourceMetadata, getJwks, getClientMetadata, handlePar, buildAuthorizeRedirect, handleCallback, serverLogin, handleToken, authenticate, OAuthError, } from "./oauth/server.js";
 import { createSessionCookie, sessionCookieHeader, clearSessionCookieHeader, parseSessionCookie, } from "./oauth/session.js";
 import { getOAuthRequest } from "./oauth/db.js";
 import { pdsCreateRecord, pdsDeleteRecord, pdsPutRecord, pdsApplyWrites, pdsUploadBlob, ProxyError, ScopeMissingProxyError, } from "./pds-proxy.js";
@@ -849,10 +849,19 @@ export function createHandler(config) {
                     body = JSON.parse(rawBody);
                 }
                 const dpopHeader = request.headers.get('dpop');
-                if (!dpopHeader)
-                    return withCors(jsonError(400, 'DPoP header required', acceptEncoding));
-                const result = await handleToken(oauth, body, dpopHeader, `${requestOrigin}/oauth/token`);
-                return withCors(json(result, 200, acceptEncoding));
+                if (!dpopHeader) {
+                    return withCors(json({ error: 'invalid_request', error_description: 'DPoP header required' }, 400, acceptEncoding));
+                }
+                try {
+                    const result = await handleToken(oauth, body, dpopHeader, `${requestOrigin}/oauth/token`);
+                    return withCors(json(result, 200, acceptEncoding));
+                }
+                catch (err) {
+                    if (err instanceof OAuthError) {
+                        return withCors(json({ error: err.code, error_description: err.description }, err.status, acceptEncoding));
+                    }
+                    throw err;
+                }
             }
             // POST /xrpc/dev.hatk.createRecord — proxy write to user's PDS
             if (url.pathname === coreXrpc('createRecord') && request.method === 'POST' && oauth) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatk/hatk",
-  "version": "0.0.1-alpha.60",
+  "version": "0.0.1-alpha.62",
   "license": "MIT",
   "bin": {
     "hatk": "dist/cli.js"