@hatk/hatk 0.0.1-alpha.85 → 0.0.1-alpha.87

package/dist/spaces/store.js

@@ -0,0 +1,99 @@
+/**
+ * Sync state for permissioned spaces: which spaces this instance follows, and
+ * how far each writer's repo in them has been read.
+ *
+ * Deliberately separate from `_repos`, which is firehose and backfill
+ * bookkeeping keyed by DID alone. A writer's position is per space — the same
+ * account can hold a repo in several, at different revisions — so a DID is not
+ * a key here.
+ */
+import { querySQL, runSQL } from "../database/db.js";
+const toWatch = (row) => ({
+    space: row.space,
+    authority: row.authority,
+    spaceType: row.space_type,
+    readerDid: row.reader_did,
+    registeredUntil: row.registered_until,
+    lastError: row.last_error,
+});
+const WATCH_COLS = 'space, authority, space_type, reader_did, registered_until, last_error';
+export async function listSpaceWatches() {
+    const rows = (await querySQL(`SELECT ${WATCH_COLS} FROM _space_watch ORDER BY space`));
+    return rows.map(toWatch);
+}
+export async function getSpaceWatch(space) {
+    const rows = (await querySQL(`SELECT ${WATCH_COLS} FROM _space_watch WHERE space = $1`, [space]));
+    return rows[0] ? toWatch(rows[0]) : null;
+}
+/**
+ * Start following a space, or refresh what is known about one already followed.
+ *
+ * Never clears `reader_did` or `registered_until`: a second call to watch an
+ * existing space is a re-assertion of interest, not a reset of its progress.
+ */
+export async function putSpaceWatch(input) {
+    const existing = await getSpaceWatch(input.space);
+    if (existing) {
+        await runSQL(`UPDATE _space_watch SET authority = $1, space_type = $2, updated_at = $3 WHERE space = $4`, [
+            input.authority,
+            input.spaceType,
+            new Date().toISOString(),
+            input.space,
+        ]);
+        return;
+    }
+    await runSQL(`INSERT INTO _space_watch (space, authority, space_type, reader_did, registered_until, last_error, updated_at)
+     VALUES ($1, $2, $3, NULL, NULL, NULL, $4)`, [input.space, input.authority, input.spaceType, new Date().toISOString()]);
+}
+export async function updateSpaceWatch(space, patch) {
+    const sets = [];
+    const params = [];
+    let idx = 1;
+    if (patch.readerDid !== undefined) {
+        sets.push(`reader_did = $${idx++}`);
+        params.push(patch.readerDid);
+    }
+    if (patch.registeredUntil !== undefined) {
+        sets.push(`registered_until = $${idx++}`);
+        params.push(patch.registeredUntil);
+    }
+    if (patch.lastError !== undefined) {
+        sets.push(`last_error = $${idx++}`);
+        params.push(patch.lastError);
+    }
+    if (sets.length === 0)
+        return;
+    sets.push(`updated_at = $${idx++}`);
+    params.push(new Date().toISOString());
+    params.push(space);
+    await runSQL(`UPDATE _space_watch SET ${sets.join(', ')} WHERE space = $${idx}`, params);
+}
+export async function deleteSpaceWatch(space) {
+    await runSQL(`DELETE FROM _space_watch WHERE space = $1`, [space]);
+    await runSQL(`DELETE FROM _space_repos WHERE space = $1`, [space]);
+}
+export async function listSpaceRepos(space) {
+    const rows = (await querySQL(`SELECT space, did, pds, rev FROM _space_repos WHERE space = $1 ORDER BY did`, [
+        space,
+    ]));
+    return rows;
+}
+export async function getSpaceRepo(space, did) {
+    const rows = (await querySQL(`SELECT space, did, pds, rev FROM _space_repos WHERE space = $1 AND did = $2`, [
+        space,
+        did,
+    ]));
+    return rows[0] ?? null;
+}
+export async function putSpaceRepo(input) {
+    await runSQL(`INSERT OR REPLACE INTO _space_repos (space, did, pds, rev, synced_at) VALUES ($1, $2, $3, $4, $5)`, [
+        input.space,
+        input.did,
+        input.pds,
+        input.rev,
+        new Date().toISOString(),
+    ]);
+}
+export async function deleteSpaceRepo(space, did) {
+    await runSQL(`DELETE FROM _space_repos WHERE space = $1 AND did = $2`, [space, did]);
+}

package/dist/spaces/uri.d.ts

@@ -0,0 +1,60 @@
+/**
+ * AT-URIs for permissioned spaces (proposal 0016).
+ *
+ * A space is named by a three-segment ref, and a record inside one carries the
+ * writer, collection and rkey after it:
+ *
+ *   at://{authority}/space/{type}/{skey}                              — the space
+ *   at://{authority}/space/{type}/{skey}/{writer}/{collection}/{rkey} — a record in it
+ *
+ * Seven segments where an ordinary record URI has five, and `space` sitting
+ * where a collection would. Anything that reads a collection out of a URI by
+ * position has to know the difference or it reads back the literal 'space'.
+ *
+ * The authority is always a DID rather than a handle: a space's membership is
+ * keyed on DIDs, so a handle could not be resolved to a member.
+ */
+export interface SpaceRef {
+    /** The DID the space is anchored on, and the only party that issues credentials for it. */
+    authority: string;
+    /** The space type NSID, whose lexicon declares which collections the space holds. */
+    type: string;
+    skey: string;
+}
+export interface SpaceRecordRef extends SpaceRef {
+    /** The three-segment ref of the space this record lives in. */
+    space: string;
+    /** The account whose repo holds the record. Records stay with their writer. */
+    writer: string;
+    collection: string;
+    rkey: string;
+}
+export declare function spaceRefUri(ref: SpaceRef): string;
+/** Parse `at://{authority}/space/{type}/{skey}` — the space itself, not a record in it. */
+export declare function parseSpaceRef(uri: string): SpaceRef | null;
+/** Whether a URI names a space or anything inside one. */
+export declare function isSpaceUri(uri: string): boolean;
+/** `at://{authority}/space/{type}/{skey}` from its parts; `self` is the skey a singleton space uses. */
+export declare function spaceUri(authority: string, type: string, skey?: string): string;
+/** The record key: the last segment of either URI shape. */
+export declare function rkeyOf(uri: string): string;
+export declare function spaceRecordUri(space: string, writer: string, collection: string, rkey: string): string;
+export declare function parseSpaceRecordUri(uri: string): SpaceRecordRef | null;
+/** The space a record URI belongs to, or undefined for an ordinary repo URI. */
+export declare function spaceFromUri(uri: string): string | undefined;
+/**
+ * The collection a record URI names, whichever shape it is.
+ *
+ * The one place the two URI forms are reconciled; every positional read of a
+ * collection goes through here.
+ */
+export declare function collectionFromRecordUri(uri: string): string | undefined;
+/**
+ * The audience a delegation token for this space is addressed to.
+ *
+ * An authority that publishes no `#atproto_space_host` entry is still reached
+ * at its `#atproto_pds` endpoint — the fragment names the audience, not the
+ * address.
+ */
+export declare function spaceHostAud(authority: string): string;
+//# sourceMappingURL=uri.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"uri.d.ts","sourceRoot":"","sources":["../../src/spaces/uri.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,WAAW,QAAQ;IACvB,2FAA2F;IAC3F,SAAS,EAAE,MAAM,CAAA;IACjB,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,cAAe,SAAQ,QAAQ;IAC9C,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;IACb,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;CACb;AAOD,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEjD;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAM1D;AAED,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG/C;AAED,wGAAwG;AACxG,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,SAAS,GAAG,MAAM,CAE/E;AAED,4DAA4D;AAC5D,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtG;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CActE;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKvE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/spaces/uri.js

@@ -0,0 +1,97 @@
+/**
+ * AT-URIs for permissioned spaces (proposal 0016).
+ *
+ * A space is named by a three-segment ref, and a record inside one carries the
+ * writer, collection and rkey after it:
+ *
+ *   at://{authority}/space/{type}/{skey}                              — the space
+ *   at://{authority}/space/{type}/{skey}/{writer}/{collection}/{rkey} — a record in it
+ *
+ * Seven segments where an ordinary record URI has five, and `space` sitting
+ * where a collection would. Anything that reads a collection out of a URI by
+ * position has to know the difference or it reads back the literal 'space'.
+ *
+ * The authority is always a DID rather than a handle: a space's membership is
+ * keyed on DIDs, so a handle could not be resolved to a member.
+ */
+const SPACE_MARKER = 'space';
+const AT_PREFIX = 'at://';
+function segments(uri) {
+    if (!uri.startsWith(AT_PREFIX))
+        return null;
+    return uri.slice(AT_PREFIX.length).split('/');
+}
+export function spaceRefUri(ref) {
+    return `${AT_PREFIX}${ref.authority}/${SPACE_MARKER}/${ref.type}/${ref.skey}`;
+}
+/** Parse `at://{authority}/space/{type}/{skey}` — the space itself, not a record in it. */
+export function parseSpaceRef(uri) {
+    const parts = segments(uri);
+    if (!parts || parts.length !== 4)
+        return null;
+    const [authority, marker, type, skey] = parts;
+    if (marker !== SPACE_MARKER || !authority.startsWith('did:') || !type || !skey)
+        return null;
+    return { authority, type, skey };
+}
+/** Whether a URI names a space or anything inside one. */
+export function isSpaceUri(uri) {
+    const parts = segments(uri);
+    return parts != null && parts.length >= 4 && parts[1] === SPACE_MARKER && parts[0].startsWith('did:');
+}
+/** `at://{authority}/space/{type}/{skey}` from its parts; `self` is the skey a singleton space uses. */
+export function spaceUri(authority, type, skey = 'self') {
+    return `${AT_PREFIX}${authority}/${SPACE_MARKER}/${type}/${skey}`;
+}
+/** The record key: the last segment of either URI shape. */
+export function rkeyOf(uri) {
+    return uri.slice(uri.lastIndexOf('/') + 1);
+}
+export function spaceRecordUri(space, writer, collection, rkey) {
+    return `${space}/${writer}/${collection}/${rkey}`;
+}
+export function parseSpaceRecordUri(uri) {
+    const parts = segments(uri);
+    if (!parts || parts.length !== 7)
+        return null;
+    const [authority, marker, type, skey, writer, collection, rkey] = parts;
+    if (marker !== SPACE_MARKER || !authority.startsWith('did:') || !collection || !rkey)
+        return null;
+    return {
+        authority,
+        type,
+        skey,
+        writer,
+        collection,
+        rkey,
+        space: `${AT_PREFIX}${authority}/${SPACE_MARKER}/${type}/${skey}`,
+    };
+}
+/** The space a record URI belongs to, or undefined for an ordinary repo URI. */
+export function spaceFromUri(uri) {
+    return parseSpaceRecordUri(uri)?.space ?? undefined;
+}
+/**
+ * The collection a record URI names, whichever shape it is.
+ *
+ * The one place the two URI forms are reconciled; every positional read of a
+ * collection goes through here.
+ */
+export function collectionFromRecordUri(uri) {
+    const parts = segments(uri);
+    if (!parts)
+        return undefined;
+    if (parts.length === 7 && parts[1] === SPACE_MARKER)
+        return parts[5];
+    return parts.length >= 3 ? parts[1] : undefined;
+}
+/**
+ * The audience a delegation token for this space is addressed to.
+ *
+ * An authority that publishes no `#atproto_space_host` entry is still reached
+ * at its `#atproto_pds` endpoint — the fragment names the audience, not the
+ * address.
+ */
+export function spaceHostAud(authority) {
+    return `${authority}#atproto_space_host`;
+}

package/dist/spaces/verify.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Verifying a signature made by somebody else's atproto signing key.
+ *
+ * Everything hatk signs, it signs with ES256, because it chose its own keys and
+ * WebCrypto implements that curve. Everything it has to *verify* here was
+ * signed by an account it does not control, and most `did:plc` accounts sign
+ * with secp256k1 — a curve WebCrypto does not implement at all. So the two
+ * curves atproto allows are handled explicitly, over @noble/curves.
+ *
+ * A key arrives as a multibase string in a DID document's verification method
+ * (`publicKeyMultibase` on a `Multikey`): base58btc, prefixed with a multicodec
+ * varint naming the curve, then the compressed point. The prefix is the only
+ * thing that says which curve it is, so it is read rather than guessed.
+ */
+export type AtprotoCurve = 'secp256k1' | 'p256';
+export declare class SignatureError extends Error {
+}
+/**
+ * Decode base58btc. Written out rather than pulled in: it is short, it is the
+ * only encoding needed, and a wrong answer here fails closed rather than
+ * silently accepting something.
+ */
+export declare function decodeBase58btc(input: string): Uint8Array;
+export interface PublicKey {
+    curve: AtprotoCurve;
+    /** The compressed point, 33 bytes. */
+    bytes: Uint8Array;
+}
+/** Read a `publicKeyMultibase` from a DID document's verification method. */
+export declare function parseMultibaseKey(multibase: string): PublicKey;
+/**
+ * Verify a raw `r || s` signature over `message`.
+ *
+ * Low-S is required — atproto mandates it and a malleable signature would let
+ * the same assertion be presented twice with different bytes — and is what
+ * @noble enforces by default.
+ */
+export declare function verifySignature(key: PublicKey, signature: Uint8Array, message: Uint8Array): boolean;
+//# sourceMappingURL=verify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/spaces/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,MAAM,CAAA;AAE/C,qBAAa,cAAe,SAAQ,KAAK;CAAG;AAE5C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAuBzD;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,YAAY,CAAA;IACnB,sCAAsC;IACtC,KAAK,EAAE,UAAU,CAAA;CAClB;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAO9D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAUnG"}

package/dist/spaces/verify.js

@@ -0,0 +1,87 @@
+/**
+ * Verifying a signature made by somebody else's atproto signing key.
+ *
+ * Everything hatk signs, it signs with ES256, because it chose its own keys and
+ * WebCrypto implements that curve. Everything it has to *verify* here was
+ * signed by an account it does not control, and most `did:plc` accounts sign
+ * with secp256k1 — a curve WebCrypto does not implement at all. So the two
+ * curves atproto allows are handled explicitly, over @noble/curves.
+ *
+ * A key arrives as a multibase string in a DID document's verification method
+ * (`publicKeyMultibase` on a `Multikey`): base58btc, prefixed with a multicodec
+ * varint naming the curve, then the compressed point. The prefix is the only
+ * thing that says which curve it is, so it is read rather than guessed.
+ */
+import { p256 } from '@noble/curves/nist.js';
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+/** Multicodec varints for the two curves atproto allows. */
+const SECP256K1_PREFIX = [0xe7, 0x01];
+const P256_PREFIX = [0x80, 0x24];
+export class SignatureError extends Error {
+}
+/**
+ * Decode base58btc. Written out rather than pulled in: it is short, it is the
+ * only encoding needed, and a wrong answer here fails closed rather than
+ * silently accepting something.
+ */
+export function decodeBase58btc(input) {
+    if (input.length === 0)
+        return new Uint8Array(0);
+    const bytes = [0];
+    for (const char of input) {
+        const value = BASE58_ALPHABET.indexOf(char);
+        if (value < 0)
+            throw new SignatureError(`Not base58btc: ${char}`);
+        let carry = value;
+        for (let i = 0; i < bytes.length; i++) {
+            carry += bytes[i] * 58;
+            bytes[i] = carry & 0xff;
+            carry >>= 8;
+        }
+        while (carry > 0) {
+            bytes.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    // Every leading '1' is a leading zero byte that the arithmetic above drops.
+    for (const char of input) {
+        if (char !== '1')
+            break;
+        bytes.push(0);
+    }
+    return new Uint8Array(bytes.reverse());
+}
+/** Read a `publicKeyMultibase` from a DID document's verification method. */
+export function parseMultibaseKey(multibase) {
+    if (!multibase.startsWith('z'))
+        throw new SignatureError('Key is not base58btc multibase');
+    const decoded = decodeBase58btc(multibase.slice(1));
+    const starts = (prefix) => prefix.every((b, i) => decoded[i] === b);
+    if (starts(SECP256K1_PREFIX))
+        return { curve: 'secp256k1', bytes: decoded.slice(SECP256K1_PREFIX.length) };
+    if (starts(P256_PREFIX))
+        return { curve: 'p256', bytes: decoded.slice(P256_PREFIX.length) };
+    throw new SignatureError('Key is neither secp256k1 nor p256');
+}
+/**
+ * Verify a raw `r || s` signature over `message`.
+ *
+ * Low-S is required — atproto mandates it and a malleable signature would let
+ * the same assertion be presented twice with different bytes — and is what
+ * @noble enforces by default.
+ */
+export function verifySignature(key, signature, message) {
+    if (signature.length !== 64)
+        return false;
+    const digest = sha256(message);
+    try {
+        const curve = key.curve === 'secp256k1' ? secp256k1 : p256;
+        return curve.verify(signature, digest, key.bytes);
+    }
+    catch {
+        // A malformed point or scalar is a failed verification, not a crash.
+        return false;
+    }
+}

package/dist/spaces/viewer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Which spaces a given viewer may be shown.
+ *
+ * The question has exactly one authoritative answer, and hatk is not the one
+ * holding it: a space's authority decides who may read it, at the moment it
+ * mints a credential, from records and rules that live on the community's own
+ * host. Re-deriving that here — reading the access and membership records out
+ * of the index and evaluating them — would be a second implementation of
+ * somebody else's authorization, drifting from it in exactly the cases that
+ * matter. Ejected members keep their content readable in the alpha; an invites
+ * space is write-for-anyone and read-for-owner; a host may change its rules
+ * without telling us.
+ *
+ * So the check is the real thing: ask the authority to mint a credential as
+ * this viewer, and take the answer. It succeeds precisely when the viewer may
+ * read the space, because that is the same call their own browser would make.
+ *
+ * What that costs is a round trip per space, so the answer is cached — which
+ * means revocation lags by up to the cache's lifetime. Worth stating plainly:
+ * somebody ejected from a community may still be served that community's rows
+ * for a few minutes. The alternative is two round trips on every request, and
+ * the space host itself already lets a minted credential outlive a revocation
+ * by up to two hours.
+ */
+import type { OAuthConfig } from '../config.ts';
+import { type SpaceCredential } from './credential.ts';
+/**
+ * The spaces this viewer may be shown, as the scope for a request.
+ *
+ * Empty for a signed-out visitor, always: obtaining a credential begins with a
+ * delegation token from the reader's own PDS, so there is no anonymous read
+ * path into a space at all. `readableBy: ["public"]` means any authenticated
+ * reader, never anyone.
+ */
+export declare function readableSpacesFor(oauth: OAuthConfig | null, viewer: {
+    did: string;
+} | null): Promise<string[]>;
+/**
+ * This viewer's own credential for a space, or null if they may not read it.
+ *
+ * For the reads that cannot go through the index — a blob, which has no public
+ * URL by design and must be fetched from the repo that holds it with the same
+ * credential as the record naming it.
+ */
+export declare function viewerCredential(oauth: OAuthConfig | null, viewer: {
+    did: string;
+} | null, space: string): Promise<SpaceCredential | null>;
+/** Drop a viewer's cached answer — after they sign out, or to stop honouring it early. */
+export declare function forgetViewerSpaces(viewerDid: string): void;
+export declare function resetViewerSpaces(): void;
+//# sourceMappingURL=viewer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"viewer.d.ts","sourceRoot":"","sources":["../../src/spaces/viewer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C,OAAO,EAAoC,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAsGxF;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,EAAE,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIpH;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,WAAW,GAAG,IAAI,EACzB,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC9B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAkBjC;AAED,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE1D;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC"}

package/dist/spaces/viewer.js

@@ -0,0 +1,167 @@
+/**
+ * Which spaces a given viewer may be shown.
+ *
+ * The question has exactly one authoritative answer, and hatk is not the one
+ * holding it: a space's authority decides who may read it, at the moment it
+ * mints a credential, from records and rules that live on the community's own
+ * host. Re-deriving that here — reading the access and membership records out
+ * of the index and evaluating them — would be a second implementation of
+ * somebody else's authorization, drifting from it in exactly the cases that
+ * matter. Ejected members keep their content readable in the alpha; an invites
+ * space is write-for-anyone and read-for-owner; a host may change its rules
+ * without telling us.
+ *
+ * So the check is the real thing: ask the authority to mint a credential as
+ * this viewer, and take the answer. It succeeds precisely when the viewer may
+ * read the space, because that is the same call their own browser would make.
+ *
+ * What that costs is a round trip per space, so the answer is cached — which
+ * means revocation lags by up to the cache's lifetime. Worth stating plainly:
+ * somebody ejected from a community may still be served that community's rows
+ * for a few minutes. The alternative is two round trips on every request, and
+ * the space host itself already lets a minted credential outlive a revocation
+ * by up to two hours.
+ */
+import { emit } from "../logger.js";
+import { mintSpaceCredential, isSpaceGone } from "./credential.js";
+import { listSpaceWatches } from "./store.js";
+/** How long a viewer's readable set is trusted before it is checked again. */
+const TTL_MS = 5 * 60 * 1000;
+/** Enough for a community's worth of spaces without opening a socket per space. */
+const CONCURRENCY = 6;
+/**
+ * Viewers held at once. Past this the oldest entry goes — a cache that grows
+ * with every account that has ever signed in is a leak, and the cost of a miss
+ * is one round trip.
+ */
+const MAX_VIEWERS = 1000;
+const cache = new Map();
+/**
+ * Resolutions in flight, one per viewer. A page fires several requests at
+ * once and every one of them misses the same cold cache; without this each
+ * would mint its own credential per space, and a member landing on the home
+ * page cost six times what it needed to.
+ */
+const inFlight = new Map();
+function entryFor(viewerDid) {
+    const entry = cache.get(viewerDid);
+    if (!entry)
+        return undefined;
+    if (entry.expiresAt <= Date.now()) {
+        cache.delete(viewerDid);
+        return undefined;
+    }
+    // Re-inserted so iteration order is least-recently-used first.
+    cache.delete(viewerDid);
+    cache.set(viewerDid, entry);
+    return entry;
+}
+function store(viewerDid, credentials) {
+    const entry = { expiresAt: Date.now() + TTL_MS, credentials };
+    cache.set(viewerDid, entry);
+    while (cache.size > MAX_VIEWERS) {
+        const oldest = cache.keys().next();
+        if (oldest.done)
+            break;
+        cache.delete(oldest.value);
+    }
+    return entry;
+}
+async function inBatches(items, size, fn) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size) {
+        out.push(...(await Promise.all(items.slice(i, i + size).map(fn))));
+    }
+    return out;
+}
+function resolve(oauth, viewerDid) {
+    const pending = inFlight.get(viewerDid);
+    if (pending)
+        return pending;
+    const task = resolveNow(oauth, viewerDid).finally(() => {
+        if (inFlight.get(viewerDid) === task)
+            inFlight.delete(viewerDid);
+    });
+    inFlight.set(viewerDid, task);
+    return task;
+}
+async function resolveNow(oauth, viewerDid) {
+    const watches = await listSpaceWatches();
+    const credentials = new Map();
+    if (watches.length === 0)
+        return store(viewerDid, credentials);
+    const elapsed = Date.now();
+    await inBatches(watches, CONCURRENCY, async (watch) => {
+        try {
+            credentials.set(watch.space, await mintSpaceCredential(oauth, watch.space, viewerDid));
+        }
+        catch (err) {
+            // Every refusal is a no, and a refusal is the ordinary shape of "not a
+            // member" rather than a fault worth reporting. A space that has been
+            // deleted is a no for everybody and the sweep will stop following it.
+            credentials.set(watch.space, null);
+            if (isSpaceGone(err))
+                return;
+        }
+    });
+    const readable = [...credentials].filter(([, c]) => c !== null).length;
+    emit('spaces', 'viewer_resolved', {
+        viewer_did: viewerDid,
+        checked: watches.length,
+        readable,
+        duration_ms: Date.now() - elapsed,
+    });
+    return store(viewerDid, credentials);
+}
+/**
+ * The spaces this viewer may be shown, as the scope for a request.
+ *
+ * Empty for a signed-out visitor, always: obtaining a credential begins with a
+ * delegation token from the reader's own PDS, so there is no anonymous read
+ * path into a space at all. `readableBy: ["public"]` means any authenticated
+ * reader, never anyone.
+ */
+export async function readableSpacesFor(oauth, viewer) {
+    if (!oauth || !viewer)
+        return [];
+    const entry = entryFor(viewer.did) ?? (await resolve(oauth, viewer.did));
+    return [...entry.credentials].filter(([, c]) => c !== null).map(([space]) => space);
+}
+/**
+ * This viewer's own credential for a space, or null if they may not read it.
+ *
+ * For the reads that cannot go through the index — a blob, which has no public
+ * URL by design and must be fetched from the repo that holds it with the same
+ * credential as the record naming it.
+ */
+export async function viewerCredential(oauth, viewer, space) {
+    if (!oauth || !viewer)
+        return null;
+    const entry = entryFor(viewer.did) ?? (await resolve(oauth, viewer.did));
+    const cached = entry.credentials.get(space);
+    if (cached !== undefined) {
+        // A credential can expire inside the entry's own lifetime; the answer to
+        // "may they read it" outlives the token that proved it.
+        if (cached === null)
+            return null;
+        if (cached.expiresAt > Date.now())
+            return cached;
+    }
+    try {
+        const credential = await mintSpaceCredential(oauth, space, viewer.did);
+        entry.credentials.set(space, credential);
+        return credential;
+    }
+    catch {
+        entry.credentials.set(space, null);
+        return null;
+    }
+}
+/** Drop a viewer's cached answer — after they sign out, or to stop honouring it early. */
+export function forgetViewerSpaces(viewerDid) {
+    cache.delete(viewerDid);
+}
+export function resetViewerSpaces() {
+    cache.clear();
+    inFlight.clear();
+}

package/dist/spaces/visibility.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Which permissioned spaces the read in flight is allowed to serve.
+ *
+ * Space records are not public data. A space's authority decides who may read
+ * it, and it decides that one caller at a time — so a row indexed out of a
+ * space carries an audience, and serving it to a request that has not proven
+ * it belongs to that audience discloses private data no matter how the query
+ * was written.
+ *
+ * hatk has no other per-row visibility concept. The takedown join is
+ * viewer-independent and `privateCollections` is all-or-nothing, so neither
+ * could carry this. The rule here is instead:
+ *
+ *   a row with `space IS NULL` is public repo data and always readable;
+ *   a row with a space is readable only inside a scope that names that space.
+ *
+ * The default is an empty scope, which serves no space rows at all. That is
+ * deliberate: a read path nobody remembered to scope fails closed and shows a
+ * member nothing, rather than failing open and showing a stranger everything.
+ * Every query over a record table applies `spaceFilterSql`; the scope is
+ * established per request by whoever established the viewer.
+ */
+/**
+ * Run `fn` with exactly these spaces readable.
+ *
+ * Replaces rather than extends any enclosing scope: widening what a nested read
+ * may see is never what a caller means, and a scope that only ever narrows is
+ * one that can be reasoned about locally.
+ */
+export declare function withReadableSpaces<T>(spaces: Iterable<string>, fn: () => T): T;
+/**
+ * Set the readable spaces for the rest of the current async context.
+ *
+ * `withReadableSpaces` wants a callback, and a request handler is a long body
+ * rather than something to wrap — restructuring it around a closure to hold a
+ * scope would be the tail wagging the dog. A server handler already runs in its
+ * own async context per request, which is the case `enterWith` exists for.
+ */
+export declare function enterReadableSpaces(spaces: Iterable<string>): void;
+/** The spaces this read may serve. Empty outside any scope. */
+export declare function readableSpaces(): ReadonlySet<string>;
+/** Whether a space would be served to the read in flight. */
+export declare function isSpaceReadable(space: string | null | undefined): boolean;
+/**
+ * The space gate as a SQL predicate, for a table aliased `alias` (pass '' for
+ * an unaliased table).
+ *
+ * `startIdx` is the next free `$N` placeholder; the returned `nextIdx` is the
+ * next one after this predicate's own. With nothing readable the predicate
+ * binds no parameters at all, which is the shape almost every request takes.
+ */
+export declare function spaceFilterSql(alias: string, startIdx: number): {
+    sql: string;
+    params: string[];
+    nextIdx: number;
+};
+//# sourceMappingURL=visibility.d.ts.map