@hatk/hatk 0.0.1-alpha.84 → 0.0.1-alpha.86

package/dist/server.js

@@ -5,7 +5,7 @@ import { join, extname } from 'node:path';
 import { gzipSync } from 'node:zlib';
 import { queryRecords, getRecordByUri, searchRecords, getSchema, reshapeRow, setRepoStatus, getRepoStatus, getRepoRetryInfo, queryLabelsForUris, insertLabels, searchAccounts, listReposPaginated, getCollectionCounts, getRepoStatusCounts, getDatabaseSize, deleteLabels, getRecentRecords, listActiveRepoDids, removeRepo, getRepoHandle, getPreferences, putPreference, insertReport, queryReports, resolveReport, getOpenReportCount, } from "./database/db.js";
 import { executeFeed, listFeeds } from "./feeds.js";
-import { executeXrpc, InvalidRequestError, NotFoundError, registerCoreXrpcHandler, isLocalRelay } from "./xrpc.js";
+import { executeXrpc, InvalidRequestError, NotFoundError, registerCoreXrpcHandler, isLocalRelay, paramsFromSearch } from "./xrpc.js";
 import { pdsFor } from "./backfill.js";
 import { resolveRecords } from "./hydrate.js";
 import { handleOpengraphRequest, buildOgMeta } from "./opengraph.js";
@@ -18,8 +18,43 @@ import { getOAuthRequest, getSession } from "./oauth/db.js";
 import { pdsCreateRecord, pdsDeleteRecord, pdsPutRecord, pdsApplyWrites, pdsUploadBlob, ProxyError, ScopeMissingProxyError, } from "./pds-proxy.js";
 import { json, jsonError, cors, withCors, file, notFound } from "./response.js";
 import { collectionFromUri, isPrivateCollection } from "./private-collections.js";
+import { enterReadableSpaces } from "./spaces/visibility.js";
+import { readableSpacesFor } from "./spaces/viewer.js";
+import { parseSpaceBlobRequest, serveSpaceBlob } from "./spaces/blob.js";
+import { handleWriteNotice, NoticeError, parseWriteNotice, scheduleNoticeSync, spaceDidDocument, spaceServiceId, unwatchSpace, verifyNotice, } from "./spaces/index.js";
+import { parseSpaceRef } from "./spaces/uri.js";
 import { serve } from "./adapter.js";
 import { renderPage } from "./renderer.js";
+/**
+ * Parse a client-supplied `limit`, or null if it is not a usable one.
+ *
+ * `parseInt` alone lets `limit=abc` through as NaN and `limit=-5` through as a
+ * negative bound, both of which reach the database driver: the first as a
+ * datatype error, the second as "no limit at all" on SQLite. Neither is a
+ * server fault, so the caller turns a null into a 400.
+ */
+function parseLimit(raw, fallback) {
+    if (raw === null || raw === '')
+        return fallback;
+    if (!/^\d+$/.test(raw))
+        return null;
+    const value = Number(raw);
+    return value >= 1 ? value : null;
+}
+/** Whether `sort` names a column queryRecords can order this collection by. */
+function isSortableField(collection, sort) {
+    if (sort === 'indexed_at')
+        return true;
+    const schema = getSchema(collection);
+    return !!schema?.columns.some((c) => c.originalName === sort || c.name === sort);
+}
+/** Narrow a client-supplied `order` to the two values that may reach ORDER BY. */
+function parseOrder(raw) {
+    if (!raw)
+        return undefined;
+    const lowered = raw.toLowerCase();
+    return lowered === 'asc' || lowered === 'desc' ? lowered : null;
+}
 function scopeMissingResponse(acceptEncoding, handle) {
     const res = withCors(json({ error: 'ScopeMissingError', ...(handle ? { handle } : {}) }, 401, acceptEncoding));
     res.headers.append('Set-Cookie', clearSessionCookieHeader());
@@ -45,7 +80,11 @@ export function registerCoreHandlers(collections, oauth) {
         if (!getSchema(collection))
             throw new NotFoundError(`Unknown collection: ${collection}`);
         const sort = params.sort || undefined;
-        const order = (params.order || undefined);
+        if (sort && !isSortableField(collection, sort))
+            throw new InvalidRequestError(`Invalid sort field: ${sort}`);
+        const order = parseOrder(params.order);
+        if (order === null)
+            throw new InvalidRequestError(`Invalid order: ${params.order}`);
         const reserved = new Set(['collection', 'limit', 'cursor', 'sort', 'order']);
         const filters = {};
         for (const [key, value] of Object.entries(params)) {
@@ -219,7 +258,11 @@ export function registerCoreHandlers(collections, oauth) {
                 subjectDid = match[1];
             }
             else if (body.subject.did) {
-                subjectUri = `at://${body.subject.did}`;
+                // The bare DID, not `at://<did>`: resolving this report labels
+                // `subjectUri`, and an account label is keyed by DID alone. Ozone
+                // writes it that way and every appview reads it that way, so the
+                // `at://` form would apply a label nothing ever looks up.
+                subjectUri = body.subject.did;
                 subjectDid = body.subject.did;
             }
             else {
@@ -348,6 +391,19 @@ export function createHandler(config) {
             }
             catch { }
         }
+        // Which permissioned spaces this request may be shown, established once and
+        // read by every query below. A signed-out visitor gets none — there is no
+        // anonymous read path into a space — and so does an instance that indexes
+        // none, which is every deployment that has not configured `spaces`.
+        try {
+            enterReadableSpaces(await readableSpacesFor(oauth, viewer));
+        }
+        catch (err) {
+            // Failing to establish the scope must not widen it: the default is to
+            // serve no space row, and that is what an unresolved viewer gets.
+            enterReadableSpaces([]);
+            emit('spaces', 'viewer_resolve_error', { error: err.message });
+        }
         try {
             // GET /xrpc/dev.hatk.getRecords?collection=<nsid>&limit=N&cursor=C&<field>=<value>
             if (url.pathname === coreXrpc('getRecords')) {
@@ -358,11 +414,23 @@ export function createHandler(config) {
                     return withCors(jsonError(404, `Unknown collection: ${collection}`, acceptEncoding));
                 if (!getSchema(collection))
                     return withCors(jsonError(404, `Unknown collection: ${collection}`, acceptEncoding));
-                const limit = parseInt(url.searchParams.get('limit') || '20');
+                // Every one of these is attacker-controlled, and queryRecords trusts
+                // what it is handed: `sort` and `order` reach the ORDER BY clause and a
+                // non-numeric `limit` reaches the driver. Rejecting them here keeps a
+                // bad query string a 400 instead of a 500 (or worse).
+                const limit = parseLimit(url.searchParams.get('limit'), 20);
+                if (limit === null)
+                    return withCors(jsonError(400, 'Invalid limit parameter', acceptEncoding));
                 const cursor = url.searchParams.get('cursor') || undefined;
                 const sort = url.searchParams.get('sort') || undefined;
-                const order = (url.searchParams.get('order') || undefined);
-                // Collect field filters (everything except reserved params)
+                const order = parseOrder(url.searchParams.get('order'));
+                if (order === null)
+                    return withCors(jsonError(400, `Invalid order: ${url.searchParams.get('order')}`, acceptEncoding));
+                if (sort && !isSortableField(collection, sort))
+                    return withCors(jsonError(400, `Invalid sort field: ${sort}`, acceptEncoding));
+                // Collect field filters (everything except reserved params). An
+                // unknown field is ignored rather than rejected — queryRecords does
+                // the same, and clients rely on passing through extra params.
                 const reserved = new Set(['collection', 'limit', 'cursor', 'sort', 'order']);
                 const filters = {};
                 for (const [key, value] of url.searchParams) {
@@ -403,10 +471,7 @@ export function createHandler(config) {
                     return withCors(jsonError(400, 'Missing feed parameter', acceptEncoding));
                 const limit = parseInt(url.searchParams.get('limit') || '30');
                 const cursor = url.searchParams.get('cursor') || undefined;
-                const params = {};
-                for (const [key, value] of url.searchParams) {
-                    params[key] = value;
-                }
+                const params = paramsFromSearch(url.searchParams);
                 const result = await executeFeed(feedName, params, cursor, limit, viewer);
                 if (!result)
                     return withCors(jsonError(404, `Unknown feed: ${feedName}`, acceptEncoding));
@@ -816,6 +881,12 @@ export function createHandler(config) {
                 }, 200, acceptEncoding));
             }
             // --- OAuth Endpoints ---
+            // GET /.well-known/did.json — this instance's own DID document, so a space
+            // authority can resolve where to deliver notices. Published only when a
+            // service DID is configured; it carries a service entry and no key.
+            if (url.pathname === '/.well-known/did.json' && config.spaces?.serviceDid) {
+                return withCors(json(spaceDidDocument(config.spaces.serviceDid, config.spaces.publicUrl ?? requestOrigin, config.spaces.serviceFragment ?? 'atproto_space_syncer'), 200, acceptEncoding));
+            }
             // OAuth well-known endpoints
             if (url.pathname === '/.well-known/oauth-authorization-server' && oauth) {
                 return withCors(json(getAuthServerMetadata(oauth.issuer, oauth), 200, acceptEncoding));
@@ -920,7 +991,24 @@ export function createHandler(config) {
                     }
                     if (!code)
                         return withCors(jsonError(400, 'Missing code', acceptEncoding));
-                    const result = await handleCallback(oauth, code, state, iss);
+                    let result;
+                    try {
+                        result = await handleCallback(oauth, code, state, iss);
+                    }
+                    catch (err) {
+                        // Same convention as the token endpoint below: an error that names
+                        // its own status keeps it, anything else is a genuine failure and
+                        // falls through to the 500.
+                        if (err instanceof OAuthError)
+                            return withCors(json({ error: err.code, error_description: err.description }, err.status, acceptEncoding));
+                        // A callback matching no pending authorization request is a stale
+                        // redirect, not a server fault — the request expired while a login
+                        // tab sat open, or the user came back to a login they already
+                        // finished. Answer like the other client errors on this route.
+                        if (err instanceof Error && err.message === 'No matching authorization request found')
+                            return withCors(jsonError(400, err.message, acceptEncoding));
+                        throw err;
+                    }
                     const isSecure = requestOrigin.startsWith('https');
                     const handle = (await getRepoHandle(result.did)) ?? result.did;
                     const session = { did: result.did, handle };
@@ -1151,14 +1239,68 @@ export function createHandler(config) {
                     return withCors(file(png, 'image/png', 'public, max-age=300'));
             }
             // GET/POST /xrpc/{nsid} — custom XRPC handlers (matched by full NSID from folder structure)
+            // POST /xrpc/com.atproto.space.notifyWrite — a space authority telling us
+            // one of its repos moved. Carries no records: it says look again, and the
+            // read that follows uses our own credential like any other.
+            //
+            // Best-effort by protocol, so this answers before syncing and never lets
+            // a sync failure become the authority's problem. A missed notice is
+            // recovered by the reconcile sweep.
+            if (url.pathname === '/xrpc/com.atproto.space.notifyWrite' && request.method === 'POST') {
+                const serviceId = spaceServiceId();
+                if (!serviceId)
+                    return withCors(jsonError(404, 'This instance receives no space notices', acceptEncoding));
+                const notice = parseWriteNotice(await request.json().catch(() => null));
+                if (!notice)
+                    return withCors(jsonError(400, 'Expected space, repo and rev', acceptEncoding));
+                try {
+                    await verifyNotice(request.headers.get('authorization'), {
+                        iss: parseSpaceRef(notice.space).authority,
+                        aud: serviceId,
+                        lxm: 'com.atproto.space.notifyWrite',
+                    });
+                }
+                catch (err) {
+                    if (err instanceof NoticeError)
+                        return withCors(jsonError(err.status, err.message, acceptEncoding));
+                    throw err;
+                }
+                // Debounced per repo: one member writing a gallery sends a notice per
+                // record, and each is an invitation to read the same repo again.
+                scheduleNoticeSync(`${notice.space}|${notice.repo}`, () => handleWriteNotice(notice).then(() => { }));
+                return withCors(json({}, 200, acceptEncoding));
+            }
+            // POST /xrpc/com.atproto.space.notifySpaceDeleted — the authority saying a
+            // space is gone and every copy of it should go too.
+            if (url.pathname === '/xrpc/com.atproto.space.notifySpaceDeleted' && request.method === 'POST') {
+                const serviceId = spaceServiceId();
+                if (!serviceId)
+                    return withCors(jsonError(404, 'This instance receives no space notices', acceptEncoding));
+                const body = (await request.json().catch(() => null));
+                const space = typeof body?.space === 'string' ? body.space : null;
+                const ref = space ? parseSpaceRef(space) : null;
+                if (!space || !ref)
+                    return withCors(jsonError(400, 'Expected a space', acceptEncoding));
+                try {
+                    await verifyNotice(request.headers.get('authorization'), {
+                        iss: ref.authority,
+                        aud: serviceId,
+                        lxm: 'com.atproto.space.notifySpaceDeleted',
+                    });
+                }
+                catch (err) {
+                    if (err instanceof NoticeError)
+                        return withCors(jsonError(err.status, err.message, acceptEncoding));
+                    throw err;
+                }
+                await unwatchSpace(space);
+                return withCors(json({}, 200, acceptEncoding));
+            }
             if (url.pathname.startsWith('/xrpc/')) {
                 const method = url.pathname.slice('/xrpc/'.length);
                 const limit = parseInt(url.searchParams.get('limit') || '20');
                 const cursor = url.searchParams.get('cursor') || undefined;
-                const params = {};
-                for (const [key, value] of url.searchParams) {
-                    params[key] = value;
-                }
+                const params = paramsFromSearch(url.searchParams);
                 // Parse request body for POST (procedures)
                 let input;
                 if (request.method === 'POST') {
@@ -1189,6 +1331,16 @@ export function createHandler(config) {
                     throw err;
                 }
             }
+            // GET /space-blob?space=&repo=&cid= — a blob inside a permissioned space,
+            // fetched with the viewer's own credential. Unlike /blob/ below it is not
+            // dev-only and not cacheable: a space blob has no public URL by design,
+            // and this response belongs to one viewer.
+            if (url.pathname === '/space-blob') {
+                const parsed = parseSpaceBlobRequest(url.searchParams);
+                if (!parsed)
+                    return withCors(jsonError(400, 'Expected space, repo and cid', acceptEncoding));
+                return withCors(await serveSpaceBlob(oauth, viewer, parsed));
+            }
             // GET /blob/:did/:cid — dev-only image proxy (see blobUrl in xrpc.ts).
             // A PDS serves getBlob as an attachment with nosniff, which a browser
             // refuses to render in <img>; re-serving it from here drops that and

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"}