@hatk/hatk 0.0.1-alpha.9 → 0.0.1-alpha.92

package/dist/setup.d.ts

@@ -1,8 +1,35 @@
+import type { BulkInserter } from './database/ports.ts';
+/** Context passed to each setup script's handler function. */
 export interface SetupContext {
     db: {
         query: (sql: string, params?: any[]) => Promise<any[]>;
-        run: (sql: string, ...params: any[]) => Promise<void>;
+        run: (sql: string, params?: any[]) => Promise<void>;
+        runBatch: (operations: Array<{
+            sql: string;
+            params: any[];
+        }>) => Promise<void>;
+        createBulkInserter: (table: string, columns: string[], options?: {
+            onConflict?: 'ignore' | 'replace';
+            batchSize?: number;
+        }) => Promise<BulkInserter>;
     };
 }
+export type SetupHandler = (ctx: SetupContext) => Promise<void>;
+export declare function defineSetup(handler: SetupHandler): {
+    __type: "setup";
+    handler: SetupHandler;
+};
+/**
+ * Run all setup scripts in the given directory on server boot.
+ *
+ * Each script should export a default handler function (or `{ handler }`) that
+ * receives a {@link SetupContext} with database access. Scripts run in sorted
+ * filename order — prefix with numbers (e.g. `01-create-tables.ts`) to control
+ * execution order. Files starting with `_` are ignored.
+ *
+ * @param setupDir - Absolute path to the `setup/` directory
+ */
 export declare function initSetup(setupDir: string): Promise<void>;
+/** Run a single setup handler with a SetupContext. */
+export declare function runSetupHandler(name: string, handler: SetupHandler): Promise<void>;
 //# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE;QACF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;QACtD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KACtD,CAAA;CACF;AAiBD,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB/D"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE;QACF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;QACtD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QACnD,QAAQ,EAAE,CAAC,UAAU,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,GAAG,EAAE,CAAA;SAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QAC9E,kBAAkB,EAAE,CAClB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,CAAC,EAAE;YAAE,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;YAAC,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,KAChE,OAAO,CAAC,YAAY,CAAC,CAAA;KAC3B,CAAA;CACF;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE/D,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY;;;EAEhD;AAkBD;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB/D;AAED,sDAAsD;AACtD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxF"}

package/dist/setup.js

@@ -6,10 +6,38 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+/**
+ * Setup scripts that run once on server boot for initializing custom tables,
+ * views, or other database state.
+ *
+ * Place scripts in the `setup/` directory. Each module default-exports a handler
+ * function (or `{ handler }`) that receives a {@link SetupContext} with database
+ * access. Scripts run in sorted filename order — prefix with numbers to control
+ * execution order. Files starting with `_` are ignored.
+ *
+ * @example
+ * ```ts
+ * // setup/01-leaderboard.ts
+ * import type { SetupContext } from '@hatk/hatk/setup'
+ *
+ * export default async function (ctx: SetupContext) {
+ *   await ctx.db.run(`
+ *     CREATE TABLE IF NOT EXISTS leaderboard (
+ *       did TEXT PRIMARY KEY,
+ *       score INTEGER DEFAULT 0
+ *     )
+ *   `)
+ * }
+ * ```
+ */
 import { resolve, relative } from 'node:path';
 import { readdirSync, statSync } from 'node:fs';
 import { log } from "./logger.js";
-import { querySQL, runSQL } from "./db.js";
+import { querySQL, runSQL, runBatch, createBulkInserterSQL } from "./database/db.js";
+export function defineSetup(handler) {
+    return { __type: 'setup', handler };
+}
+/** Recursively collect .ts/.js files in a directory, skipping files prefixed with `_`. */
 function walkDir(dir) {
     const results = [];
     try {
@@ -26,23 +54,42 @@ function walkDir(dir) {
     catch { }
     return results.sort();
 }
+/**
+ * Run all setup scripts in the given directory on server boot.
+ *
+ * Each script should export a default handler function (or `{ handler }`) that
+ * receives a {@link SetupContext} with database access. Scripts run in sorted
+ * filename order — prefix with numbers (e.g. `01-create-tables.ts`) to control
+ * execution order. Files starting with `_` are ignored.
+ *
+ * @param setupDir - Absolute path to the `setup/` directory
+ */
 export async function initSetup(setupDir) {
     const files = walkDir(setupDir);
     if (files.length === 0)
         return;
     for (const scriptPath of files) {
         const name = relative(setupDir, scriptPath).replace(/\.(ts|js)$/, '');
-        const mod = await import(__rewriteRelativeImportExtension(scriptPath));
+        const mod = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ `${scriptPath}?t=${Date.now()}`));
         const handler = mod.default?.handler || mod.default;
         if (typeof handler !== 'function') {
             console.warn(`[setup] ${name}: no handler function found, skipping`);
             continue;
         }
         const ctx = {
-            db: { query: querySQL, run: runSQL },
+            db: { query: querySQL, run: runSQL, runBatch, createBulkInserter: createBulkInserterSQL },
         };
         log(`[setup] running: ${name}`);
         await handler(ctx);
         log(`[setup] done: ${name}`);
     }
 }
+/** Run a single setup handler with a SetupContext. */
+export async function runSetupHandler(name, handler) {
+    const ctx = {
+        db: { query: querySQL, run: runSQL, runBatch, createBulkInserter: createBulkInserterSQL },
+    };
+    log(`[setup] running: ${name}`);
+    await handler(ctx);
+    log(`[setup] done: ${name}`);
+}

package/dist/spaces/blob.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Serving a blob that lives in a permissioned space.
+ *
+ * Every other image hatk hands out has a public URL — a CDN path, or the
+ * repo's own `com.atproto.sync.getBlob`. A space's blob has neither, by
+ * design: `com.atproto.space.getBlob` serves it only to a credential holder,
+ * and only for a space the blob is actually referenced from. Giving one a
+ * public URL would turn that URL into the capability the credential exists to
+ * replace.
+ *
+ * So the bytes come through here, fetched on the viewer's own behalf with the
+ * viewer's own credential, and go no further: `private, no-store` keeps them
+ * out of every shared cache between this server and that browser.
+ */
+import type { OAuthConfig } from '../config.ts';
+/**
+ * The URL this appview serves a space blob at, for whoever is asking.
+ *
+ * Built here rather than by the app, because the route is hatk's: a blob in a
+ * space has no public address by design, and this is the one address it does
+ * have — answered per viewer, with that viewer's credential, uncacheable.
+ */
+export declare function spaceBlobUrl(space: string, repo: string, cid: string): string;
+/**
+ * The CID a blob reference names, in whichever spelling the read used.
+ *
+ * A repo read gives the lexicon's `{ ref: { $link } }`; a space read comes
+ * back through a lex client that decodes the same field into a CID object
+ * whose `/` is the string. One blob, two spellings, and no caller should have
+ * to know which it got.
+ */
+export declare function blobCid(blob: unknown): string | undefined;
+export interface SpaceBlobRequest {
+    space: string;
+    /** The repo holding the blob — the writer's, not the authority's. */
+    repo: string;
+    cid: string;
+}
+export declare function parseSpaceBlobRequest(params: URLSearchParams): SpaceBlobRequest | null;
+/**
+ * Fetch a space blob as this viewer, or answer why not.
+ *
+ * A viewer who cannot read the space gets the same 404 as a blob that is not
+ * there. The distinction between "you may not" and "it does not exist" is
+ * itself information about a private space, and the space host draws the line
+ * the same way when it reports a non-member's repo as simply absent.
+ */
+export declare function serveSpaceBlob(oauth: OAuthConfig | null, viewer: {
+    did: string;
+} | null, request: SpaceBlobRequest): Promise<Response>;
+//# sourceMappingURL=blob.d.ts.map

package/dist/spaces/blob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob.d.ts","sourceRoot":"","sources":["../../src/spaces/blob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAe/C;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAMzD;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,CAOtF;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,WAAW,GAAG,IAAI,EACzB,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC9B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,QAAQ,CAAC,CAsCnB"}

package/dist/spaces/blob.js

@@ -0,0 +1,111 @@
+/**
+ * Serving a blob that lives in a permissioned space.
+ *
+ * Every other image hatk hands out has a public URL — a CDN path, or the
+ * repo's own `com.atproto.sync.getBlob`. A space's blob has neither, by
+ * design: `com.atproto.space.getBlob` serves it only to a credential holder,
+ * and only for a space the blob is actually referenced from. Giving one a
+ * public URL would turn that URL into the capability the credential exists to
+ * replace.
+ *
+ * So the bytes come through here, fetched on the viewer's own behalf with the
+ * viewer's own credential, and go no further: `private, no-store` keeps them
+ * out of every shared cache between this server and that browser.
+ */
+import { emit } from "../logger.js";
+import { repoEndpoint } from "./identity.js";
+import { parseSpaceRef } from "./uri.js";
+import { viewerCredential } from "./viewer.js";
+/**
+ * What we are willing to hand back, whatever the repo claims it is.
+ *
+ * The record naming this blob was written by an account hatk does not control,
+ * and so was its mime type. Echoing that unchecked would let a writer choose
+ * what a browser executes in this origin.
+ */
+const SERVABLE = new Set(['image/jpeg', 'image/png', 'image/webp', 'image/avif', 'image/gif']);
+/**
+ * The URL this appview serves a space blob at, for whoever is asking.
+ *
+ * Built here rather than by the app, because the route is hatk's: a blob in a
+ * space has no public address by design, and this is the one address it does
+ * have — answered per viewer, with that viewer's credential, uncacheable.
+ */
+export function spaceBlobUrl(space, repo, cid) {
+    const params = new URLSearchParams({ space, repo, cid });
+    return `/space-blob?${params}`;
+}
+/**
+ * The CID a blob reference names, in whichever spelling the read used.
+ *
+ * A repo read gives the lexicon's `{ ref: { $link } }`; a space read comes
+ * back through a lex client that decodes the same field into a CID object
+ * whose `/` is the string. One blob, two spellings, and no caller should have
+ * to know which it got.
+ */
+export function blobCid(blob) {
+    const ref = blob?.ref;
+    if (!ref || typeof ref !== 'object')
+        return undefined;
+    if (typeof ref.$link === 'string')
+        return ref.$link;
+    if (typeof ref['/'] === 'string')
+        return ref['/'];
+    return undefined;
+}
+export function parseSpaceBlobRequest(params) {
+    const space = params.get('space');
+    const repo = params.get('repo') ?? params.get('did');
+    const cid = params.get('cid');
+    if (!space || !repo || !cid)
+        return null;
+    if (!parseSpaceRef(space) || !repo.startsWith('did:'))
+        return null;
+    return { space, repo, cid };
+}
+/**
+ * Fetch a space blob as this viewer, or answer why not.
+ *
+ * A viewer who cannot read the space gets the same 404 as a blob that is not
+ * there. The distinction between "you may not" and "it does not exist" is
+ * itself information about a private space, and the space host draws the line
+ * the same way when it reports a non-member's repo as simply absent.
+ */
+export async function serveSpaceBlob(oauth, viewer, request) {
+    if (!viewer)
+        return new Response('Unauthorized', { status: 401 });
+    const credential = await viewerCredential(oauth, viewer, request.space);
+    if (!credential)
+        return new Response('Not found', { status: 404 });
+    let upstream;
+    try {
+        const url = new URL(`${await repoEndpoint(request.repo)}/xrpc/com.atproto.space.getBlob`);
+        url.searchParams.set('space', request.space);
+        // `repo`, not `did`: a space read names the repo holding the record the
+        // same way everywhere. A server hosting one account falls back to it,
+        // which is what makes `did` ever appear to work.
+        url.searchParams.set('repo', request.repo);
+        url.searchParams.set('cid', request.cid);
+        upstream = await credential.fetch(url);
+    }
+    catch (err) {
+        emit('spaces', 'blob_error', { space: request.space, repo: request.repo, error: err.message });
+        return new Response('Blob unavailable', { status: 502 });
+    }
+    if (!upstream.ok)
+        return new Response('Not found', { status: upstream.status === 401 ? 404 : upstream.status });
+    const claimed = (upstream.headers.get('content-type') ?? '').split(';')[0].trim();
+    const contentType = SERVABLE.has(claimed) ? claimed : 'application/octet-stream';
+    return new Response(upstream.body, {
+        status: 200,
+        headers: {
+            'content-type': contentType,
+            // Not a public cache: this response is one viewer's, and the next
+            // request for the same URL may be somebody with no right to it.
+            'cache-control': 'private, no-store',
+            'content-disposition': 'inline',
+            'content-security-policy': "default-src 'none'; sandbox",
+            'x-content-type-options': 'nosniff',
+        },
+    });
+}

package/dist/spaces/credential.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Getting into a space to read it.
+ *
+ * hatk is not a member of anything. It has no DID that any community has
+ * admitted, and asking every authority to admit an indexer would make indexing
+ * a per-community act of trust before a single record could be read.
+ *
+ * So it reads as somebody who is already inside: a viewer whose OAuth session
+ * it already holds, whose PDS will mint a delegation token for the space, and
+ * whom the authority already lets in. The exchange is the same one the
+ * community's own web app makes from the browser —
+ *
+ *   the reader's PDS signs a delegation token   (60s, single-use, addressed to
+ *                                                the authority's space host)
+ *   the authority checks it, checks the reader against the space's policy, and
+ *   returns a credential bound to the key that signed our DPoP proof   (2h)
+ *
+ * — and the credential is then presented to every writer's host in the space.
+ * It carries no audience, which is why it must be bound to a key rather than
+ * held as a bearer token: a host handed a bearer credential to serve its own
+ * repo could replay it against every other host in the space.
+ *
+ * The consequence to be honest about: a space is only readable while somebody
+ * who can read it has a live session here. That is the same bound the data has
+ * anyway — nobody outside the space's audience was ever entitled to this — but
+ * it does mean indexing lapses when the last member logs out.
+ */
+import type { OAuthConfig } from '../config.ts';
+export declare class SpaceCredentialError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/** A refusal about who is asking, rather than about the space or the network. */
+export declare function isNotAuthorized(err: unknown): boolean;
+export declare function isSpaceGone(err: unknown): boolean;
+export interface SpaceCredential {
+    /** The space this credential reads, and the only one it is accepted for. */
+    space: string;
+    /** The account whose delegation bought it. */
+    readerDid: string;
+    expiresAt: number;
+    /** A fetch that presents the credential with a fresh DPoP proof per request. */
+    fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+}
+/** Mint a credential for `space` using `readerDid`'s stored session. */
+export declare function mintSpaceCredential(oauthConfig: OAuthConfig, space: string, readerDid: string): Promise<SpaceCredential>;
+/**
+ * A credential for `space`, minted with whichever candidate session works.
+ *
+ * Candidates are tried in order and the first that succeeds is cached. A
+ * refusal about the reader — they were ejected, or never belonged — moves on to
+ * the next candidate; a refusal about the space itself stops the whole attempt,
+ * since no other reader would fare better.
+ */
+export declare function getSpaceCredential(oauthConfig: OAuthConfig, space: string, candidates: string[], opts?: {
+    refresh?: boolean;
+}): Promise<SpaceCredential>;
+export declare function forgetSpaceCredential(space: string): void;
+/** For tests: drop every cached credential and the process binding key. */
+export declare function resetSpaceCredentials(): void;
+//# sourceMappingURL=credential.d.ts.map

package/dist/spaces/credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.d.ts","sourceRoot":"","sources":["../../src/spaces/credential.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAsB/C,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;gBADZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM;CAIlB;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAErD;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEjD;AAED,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAA;IACb,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,gFAAgF;IAChF,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CACtE;AAiDD,wEAAwE;AACxE,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,CAAC,CAiC1B;AAUD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAAE,EACpB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,CAwB1B;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C"}

package/dist/spaces/credential.js

@@ -0,0 +1,184 @@
+/**
+ * Getting into a space to read it.
+ *
+ * hatk is not a member of anything. It has no DID that any community has
+ * admitted, and asking every authority to admit an indexer would make indexing
+ * a per-community act of trust before a single record could be read.
+ *
+ * So it reads as somebody who is already inside: a viewer whose OAuth session
+ * it already holds, whose PDS will mint a delegation token for the space, and
+ * whom the authority already lets in. The exchange is the same one the
+ * community's own web app makes from the browser —
+ *
+ *   the reader's PDS signs a delegation token   (60s, single-use, addressed to
+ *                                                the authority's space host)
+ *   the authority checks it, checks the reader against the space's policy, and
+ *   returns a credential bound to the key that signed our DPoP proof   (2h)
+ *
+ * — and the credential is then presented to every writer's host in the space.
+ * It carries no audience, which is why it must be bound to a key rather than
+ * held as a bearer token: a host handed a bearer credential to serve its own
+ * repo could replay it against every other host in the space.
+ *
+ * The consequence to be honest about: a space is only readable while somebody
+ * who can read it has a live session here. That is the same bound the data has
+ * anyway — nobody outside the space's audience was ever entitled to this — but
+ * it does mean indexing lapses when the last member logs out.
+ */
+import { computeJwkThumbprint, generateKeyPair } from "../oauth/crypto.js";
+import { createDpopProof } from "../oauth/dpop.js";
+import { pdsXrpc } from "../pds-proxy.js";
+import { emit } from "../logger.js";
+import { spaceHostEndpoint } from "./identity.js";
+import { parseSpaceRef } from "./uri.js";
+/** Re-mint this long before the credential's own expiry rather than racing it. */
+const RENEW_LEAD_MS = 5 * 60 * 1000;
+/**
+ * The key credentials are bound to, generated once per process and never
+ * persisted. It is registered nowhere, so a restart costs one round trip to
+ * mint fresh credentials and nothing else.
+ */
+let bindingKey = null;
+function getBindingKey() {
+    bindingKey ??= generateKeyPair();
+    return bindingKey;
+}
+export class SpaceCredentialError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+/** A refusal about who is asking, rather than about the space or the network. */
+export function isNotAuthorized(err) {
+    return err instanceof SpaceCredentialError && (err.code === 'UserNotAuthorized' || err.code === 'NotAuthorized');
+}
+export function isSpaceGone(err) {
+    return err instanceof SpaceCredentialError && (err.code === 'SpaceDeleted' || err.code === 'SpaceNotFound');
+}
+function expiryOf(jwt) {
+    try {
+        const payload = JSON.parse(Buffer.from(jwt.split('.')[1], 'base64url').toString());
+        return typeof payload.exp === 'number' ? payload.exp * 1000 : Date.now() + 60 * 60 * 1000;
+    }
+    catch {
+        // An unreadable expiry is not a reason to refuse a credential the authority
+        // just issued; treat it as short-lived and re-mint sooner.
+        return Date.now() + 10 * 60 * 1000;
+    }
+}
+/**
+ * Exchange a delegation token for a credential at the authority.
+ *
+ * The proof sent here carries no `ath`: a delegation token is an authorization
+ * grant rather than an access token, so there is nothing to hash yet, and a
+ * server that checks will refuse a proof that includes one. `dpopJkt` is sent
+ * alongside because implementations differ on which they read — the reference
+ * reads the proof, others read the field — and they agree here by construction.
+ */
+async function exchange(authorityHost, space, delegationToken) {
+    const { privateJwk, publicJwk } = await getBindingKey();
+    const url = `${authorityHost}/xrpc/com.atproto.space.getSpaceCredential`;
+    const proof = await createDpopProof(privateJwk, publicJwk, 'POST', url);
+    const dpopJkt = await computeJwkThumbprint(publicJwk);
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            Authorization: `Bearer ${delegationToken}`,
+            DPoP: proof,
+        },
+        body: JSON.stringify({ space, dpopJkt }),
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || !body.credential) {
+        throw new SpaceCredentialError(res.status, body.error ?? (res.status >= 500 ? 'UpstreamFailure' : 'InvalidRequest'), body.message ?? `getSpaceCredential refused (${res.status})`);
+    }
+    return body.credential;
+}
+/** Mint a credential for `space` using `readerDid`'s stored session. */
+export async function mintSpaceCredential(oauthConfig, space, readerDid) {
+    const ref = parseSpaceRef(space);
+    if (!ref)
+        throw new SpaceCredentialError(400, 'InvalidRequest', `Not a space ref: ${space}`);
+    // The reader's own PDS signs this, under the whole-space read grant their
+    // session carries. A session without that scope is refused here, before the
+    // authority is ever contacted.
+    let token;
+    try {
+        const out = await pdsXrpc(oauthConfig, { did: readerDid }, 'com.atproto.space.getDelegationToken', {
+            params: { space },
+        });
+        if (typeof out.token !== 'string')
+            throw new Error('PDS returned no delegation token');
+        token = out.token;
+    }
+    catch (err) {
+        throw new SpaceCredentialError(err?.status ?? 502, 'DelegationFailed', err?.message ?? 'delegation failed');
+    }
+    const authorityHost = await spaceHostEndpoint(ref.authority);
+    const credential = await exchange(authorityHost, space, token);
+    const { privateJwk, publicJwk } = await getBindingKey();
+    const credentialFetch = async (input, init) => {
+        const url = typeof input === 'string' ? input : input.toString();
+        const method = (init?.method ?? 'GET').toUpperCase();
+        const proof = await createDpopProof(privateJwk, publicJwk, method, url, credential);
+        const headers = new Headers(init?.headers);
+        headers.set('Authorization', `DPoP ${credential}`);
+        headers.set('DPoP', proof);
+        return fetch(url, { ...init, method, headers });
+    };
+    return { space, readerDid, expiresAt: expiryOf(credential), fetch: credentialFetch };
+}
+// --- Cache ---
+const cache = new Map();
+function fresh(cred) {
+    return !!cred && cred.expiresAt - RENEW_LEAD_MS > Date.now();
+}
+/**
+ * A credential for `space`, minted with whichever candidate session works.
+ *
+ * Candidates are tried in order and the first that succeeds is cached. A
+ * refusal about the reader — they were ejected, or never belonged — moves on to
+ * the next candidate; a refusal about the space itself stops the whole attempt,
+ * since no other reader would fare better.
+ */
+export async function getSpaceCredential(oauthConfig, space, candidates, opts = {}) {
+    if (!opts.refresh) {
+        const cached = cache.get(space);
+        if (fresh(cached))
+            return cached;
+    }
+    let lastError;
+    for (const readerDid of candidates) {
+        try {
+            const credential = await mintSpaceCredential(oauthConfig, space, readerDid);
+            cache.set(space, credential);
+            return credential;
+        }
+        catch (err) {
+            if (isSpaceGone(err))
+                throw err;
+            lastError = err;
+            emit('spaces', 'credential_refused', {
+                space,
+                reader_did: readerDid,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    cache.delete(space);
+    throw lastError ?? new SpaceCredentialError(403, 'NoReader', `No session on this instance can read ${space}`);
+}
+export function forgetSpaceCredential(space) {
+    cache.delete(space);
+}
+/** For tests: drop every cached credential and the process binding key. */
+export function resetSpaceCredentials() {
+    cache.clear();
+    bindingKey = null;
+}

package/dist/spaces/engine.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Keeping the index level with a permissioned space.
+ *
+ * A space never reaches a firehose. There is no stream to tail and no relay
+ * that has seen it, so the only way to know a space has moved is to ask the
+ * authority who has written into it and then ask each of those writers' hosts
+ * what changed. Two loops do that:
+ *
+ *   reconcile   the authority's `listRepos` gives the writer set with each
+ *               writer's current rev. Anything whose rev has moved is synced;
+ *               anything the authority no longer names is dropped.
+ *   sync        one writer's repo, forward from the rev we last read, through
+ *               `listRepoOps` — or wholesale through `listRecords` when there
+ *               is no rev to start from, or when the op log has been compacted
+ *               past it.
+ *
+ * Write notices exist too and are far cheaper, but they are best-effort by
+ * design: the reference host forwards them once from an in-memory queue and
+ * logs the failure. So reconcile is the thing that makes sync correct, and a
+ * notice only makes it prompt.
+ *
+ * What is deliberately not done here is verification. The alpha signs a commit
+ * over the repo's LtHash state, and a syncer can check it. hatk does not check
+ * the equivalent on the firehose path either — it reads records out of relayed
+ * CAR blocks and trusts them — so checking here would claim a guarantee the
+ * rest of the index does not make. Adding it means depending on `@atproto/space`
+ * for LtHash and the commit verifier, and is worth doing to both paths at once
+ * rather than to this one alone.
+ */
+import type { OAuthConfig } from '../config.ts';
+import { type SpaceCredential } from './credential.ts';
+import { type SpaceWatch } from './store.ts';
+export interface SpaceEngineOptions {
+    oauth: OAuthConfig;
+    /** Space type NSIDs this instance will follow. Anything else is refused. */
+    types: Set<string>;
+    /** Collections hatk indexes at all; a space collection outside this is skipped. */
+    collections: Set<string>;
+    /**
+     * This instance's service identifier — `did:web:...#atproto_space_syncer`.
+     * Absent when the instance receives no notices, in which case the sweep is
+     * the only thing that notices a write.
+     */
+    serviceId?: string;
+}
+export declare function configureSpaceEngine(opts: SpaceEngineOptions): void;
+/**
+ * The collections a space of this type holds, narrowed to the ones hatk has a
+ * table for.
+ *
+ * A space type's lexicon declares its collections, which is what makes a space
+ * readable without the app being told what is in it — but a space may name
+ * collections this instance does not index, and those are simply not its
+ * business.
+ */
+export declare function collectionsForSpaceType(spaceType: string): string[];
+/** Bring one writer's repo in a space up to date, however that has to happen. */
+export declare function syncSpaceRepo(watch: SpaceWatch, writer: string, credential: SpaceCredential): Promise<void>;
+/**
+ * Compare the authority's writer set against what the index holds, and close
+ * the difference.
+ *
+ * The writer set is what the authority has been told, not what is true: a
+ * repo's own host is the source of truth, and after a community migrates hosts
+ * the set is empty until each writer writes again. So a writer the authority
+ * stops naming has their rows dropped, but the rev comparison is only ever a
+ * reason to read — never a reason to believe a repo has not moved.
+ */
+export declare function reconcileSpace(watch: SpaceWatch): Promise<void>;
+/** Follow a space from now on, and read it once. */
+export declare function watchSpace(space: string): Promise<SpaceWatch>;
+/** Stop following a space and drop everything indexed from it. */
+export declare function unwatchSpace(space: string): Promise<void>;
+/**
+ * Act on a write notice: read the one repo it names.
+ *
+ * Only for a space already followed. A notice about anything else is not an
+ * instruction to start following it — that decision belongs to config or to the
+ * app, never to whoever can reach this endpoint.
+ *
+ * The notice's `rev` is deliberately not trusted as the new position: it is
+ * read from the repo's own host, which is the source of truth, by the ordinary
+ * sync path. The notice only says "look again".
+ */
+export declare function handleWriteNotice(notice: {
+    space: string;
+    repo: string;
+}): Promise<boolean>;
+/**
+ * Reconcile every followed space.
+ *
+ * Failures are per space and recorded rather than thrown: one community's host
+ * being unreachable is not a reason to stop reading the others, and a space
+ * whose last reader logged out should go quiet rather than take the sweep down.
+ */
+export declare function reconcileAll(): Promise<void>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/spaces/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/spaces/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAQ/C,OAAO,EAA0D,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAE9G,OAAO,EAUL,KAAK,UAAU,EAChB,MAAM,YAAY,CAAA;AAMnB,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,WAAW,CAAA;IAClB,4EAA4E;IAC5E,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAClB,mFAAmF;IACnF,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAaD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAEnE;AAOD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAQnE;AAoUD,iFAAiF;AACjF,wBAAsB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBjH;AAkED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCrE;AAID,oDAAoD;AACpD,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAUnE;AAED,kEAAkE;AAClE,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAKjG;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAclD"}