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

package/dist/spaces/identity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Resolving the services a space is reached through.
+ *
+ * Two different endpoints matter, and they are usually but not always the same
+ * host:
+ *
+ *   the authority's space host — issues credentials, enumerates writers
+ *   each writer's own PDS       — holds that writer's records and blobs
+ *
+ * A space is the aggregation of one repo per writer, each on the writer's own
+ * server, so reading one means talking to every writer's host with a credential
+ * the authority signed. There is no single server that has all of it.
+ */
+import { type PublicKey } from './verify.ts';
+export declare function configureSpaceIdentity(url: string): void;
+/**
+ * Where to send credential and writer-set requests for a space.
+ *
+ * The authority may publish a dedicated `#atproto_space_host`; one that does
+ * not is still reached at its `#atproto_pds`, which is the case for every
+ * community host built on the reference implementation.
+ */
+export declare function spaceHostEndpoint(authority: string): Promise<string>;
+/** Where a writer's repo in a space lives: their own PDS, wherever that is. */
+export declare function repoEndpoint(did: string): Promise<string>;
+/** Drop cached DID documents. For tests, and for a host that has just moved. */
+export declare function clearSpaceIdentityCache(): void;
+/**
+ * An account's atproto signing key, as its DID document publishes it.
+ *
+ * Used to check that a write notice really came from the space authority it
+ * claims to. `#atproto` is the entry every atproto DID document carries;
+ * `#atproto_space` is the optional dedicated credential-signing key, preferred
+ * when an authority publishes one.
+ */
+export declare function atprotoSigningKey(did: string): Promise<PublicKey | null>;
+//# sourceMappingURL=identity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/spaces/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAS/D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAExD;AA2BD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK1E;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEzD;AAED,gFAAgF;AAChF,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAW9E"}

package/dist/spaces/identity.js

@@ -0,0 +1,88 @@
+/**
+ * Resolving the services a space is reached through.
+ *
+ * Two different endpoints matter, and they are usually but not always the same
+ * host:
+ *
+ *   the authority's space host — issues credentials, enumerates writers
+ *   each writer's own PDS       — holds that writer's records and blobs
+ *
+ * A space is the aggregation of one repo per writer, each on the writer's own
+ * server, so reading one means talking to every writer's host with a credential
+ * the authority signed. There is no single server that has all of it.
+ */
+import { pdsFor } from "../backfill.js";
+import { parseMultibaseKey } from "./verify.js";
+let plcUrl = 'https://plc.directory';
+export function configureSpaceIdentity(url) {
+    plcUrl = url;
+}
+const docCache = new Map();
+function fetchDidDoc(did) {
+    const cached = docCache.get(did);
+    if (cached)
+        return cached;
+    const pending = (async () => {
+        try {
+            const url = did.startsWith('did:web:')
+                ? `https://${decodeURIComponent(did.slice('did:web:'.length)).replace(/:/g, '/')}/.well-known/did.json`
+                : `${plcUrl}/${did}`;
+            const res = await fetch(url);
+            if (!res.ok)
+                return null;
+            return (await res.json());
+        }
+        catch {
+            return null;
+        }
+    })();
+    docCache.set(did, pending);
+    return pending;
+}
+function serviceEndpoint(doc, id) {
+    return doc?.service?.find((s) => s.id === id || s.id?.endsWith(id))?.serviceEndpoint;
+}
+/**
+ * Where to send credential and writer-set requests for a space.
+ *
+ * The authority may publish a dedicated `#atproto_space_host`; one that does
+ * not is still reached at its `#atproto_pds`, which is the case for every
+ * community host built on the reference implementation.
+ */
+export async function spaceHostEndpoint(authority) {
+    const doc = await fetchDidDoc(authority);
+    const endpoint = serviceEndpoint(doc, '#atproto_space_host') ?? serviceEndpoint(doc, '#atproto_pds');
+    if (!endpoint)
+        throw new Error(`No space host or PDS endpoint in DID document for ${authority}`);
+    return endpoint;
+}
+/** Where a writer's repo in a space lives: their own PDS, wherever that is. */
+export function repoEndpoint(did) {
+    return pdsFor(did);
+}
+/** Drop cached DID documents. For tests, and for a host that has just moved. */
+export function clearSpaceIdentityCache() {
+    docCache.clear();
+}
+/**
+ * An account's atproto signing key, as its DID document publishes it.
+ *
+ * Used to check that a write notice really came from the space authority it
+ * claims to. `#atproto` is the entry every atproto DID document carries;
+ * `#atproto_space` is the optional dedicated credential-signing key, preferred
+ * when an authority publishes one.
+ */
+export async function atprotoSigningKey(did) {
+    const doc = await fetchDidDoc(did);
+    const methods = doc?.verificationMethod ?? [];
+    const named = (id) => methods.find((m) => m.id === id || m.id?.endsWith(id));
+    const method = named('#atproto_space') ?? named('#atproto');
+    if (!method?.publicKeyMultibase)
+        return null;
+    try {
+        return parseMultibaseKey(method.publicKeyMultibase);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/spaces/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Permissioned-space indexing, as a whole.
+ *
+ * Off unless `spaces` is configured. With it off nothing in here runs, no
+ * space row can be written, and the read gate serves none — which is the state
+ * every deployment that predates this is in.
+ */
+import type { OAuthConfig, SpacesConfig } from '../config.ts';
+import { unwatchSpace, watchSpace } from './engine.ts';
+export { collectionsForSpaceType, reconcileAll, reconcileSpace, syncSpaceRepo, unwatchSpace, watchSpace, } from './engine.ts';
+export { getSpaceCredential, mintSpaceCredential, isNotAuthorized, isSpaceGone } from './credential.ts';
+export { listSpaceRepos, listSpaceWatches, type SpaceWatch } from './store.ts';
+export { isSpaceReadable, readableSpaces, withReadableSpaces } from './visibility.ts';
+export { UngatedSpaceQueryError, spaceBackedCollections } from './guard.ts';
+export { forgetViewerSpaces, readableSpacesFor, viewerCredential } from './viewer.ts';
+/**
+ * A DPoP proof signed by this instance's own key, for an app that has to hold
+ * a DPoP-bound token itself — a community host minting one for a member to act
+ * as the community, say. The key is the one hatk already presents to PDSes.
+ */
+export declare function serverDpopProof(method: string, url: string, accessToken?: string, nonce?: string): Promise<string>;
+export { handleWriteNotice } from './engine.ts';
+export { clearPendingNotices, NoticeError, parseWriteNotice, scheduleNoticeSync, verifyNotice, type WriteNotice, } from './notify.ts';
+export * from './uri.ts';
+export { blobCid, spaceBlobUrl } from './blob.ts';
+export { records, requireSpace, spaceRecords } from './records.ts';
+export declare function spaceServiceId(): string | null;
+/**
+ * The DID document an authority resolves to find where to deliver notices.
+ *
+ * It publishes a service entry and nothing else. A syncer signs nothing — it
+ * verifies inbound notices and presents credentials bound to an ephemeral key
+ * — so there is no verification method to publish and no key here to steal.
+ */
+export declare function spaceDidDocument(did: string, endpoint: string, fragment: string): Record<string, unknown>;
+export interface StartSpacesOptions {
+    spaces: SpacesConfig;
+    oauth: OAuthConfig | null;
+    plc: string;
+    /** Every collection hatk has a table for. */
+    collections: Set<string>;
+}
+/**
+ * Configure the engine and start the reconcile sweep.
+ *
+ * Returns without starting anything if the instance has no OAuth: reading a
+ * space begins with a delegation token from a member's own PDS, so an instance
+ * that holds no sessions has no way to obtain one and would sweep forever
+ * finding nothing.
+ */
+export declare function startSpaces(opts: StartSpacesOptions): void;
+export declare function stopSpaces(): void;
+/** Re-exported so an app's on-login hook can start following a space it just learned about. */
+export { watchSpace as followSpace, unwatchSpace as unfollowSpace };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/spaces/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAG7D,OAAO,EAA+D,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAOnH,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AACvG,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAA;AAC9E,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACrF,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAC3E,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAErF;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAIjB;AACD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,KAAK,WAAW,GACjB,MAAM,aAAa,CAAA;AACpB,cAAc,UAAU,CAAA;AACxB,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACjD,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAWlE,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAE9C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzG;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAA;IACpB,KAAK,EAAE,WAAW,GAAG,IAAI,CAAA;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,6CAA6C;IAC7C,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAqD1D;AAED,wBAAgB,UAAU,IAAI,IAAI,CAMjC;AAED,+FAA+F;AAC/F,OAAO,EAAE,UAAU,IAAI,WAAW,EAAE,YAAY,IAAI,aAAa,EAAE,CAAA"}

package/dist/spaces/index.js

@@ -0,0 +1,133 @@
+/**
+ * Permissioned-space indexing, as a whole.
+ *
+ * Off unless `spaces` is configured. With it off nothing in here runs, no
+ * space row can be written, and the read gate serves none — which is the state
+ * every deployment that predates this is in.
+ */
+import { emit } from "../logger.js";
+import { log } from "../logger.js";
+import { collectionsForSpaceType, configureSpaceEngine, reconcileAll, unwatchSpace, watchSpace } from "./engine.js";
+import { setSpaceBackedCollections } from "./guard.js";
+import { configureSpaceIdentity } from "./identity.js";
+import { clearPendingNotices } from "./notify.js";
+import { getServerKey } from "../oauth/db.js";
+import { createDpopProof } from "../oauth/dpop.js";
+export { collectionsForSpaceType, reconcileAll, reconcileSpace, syncSpaceRepo, unwatchSpace, watchSpace, } from "./engine.js";
+export { getSpaceCredential, mintSpaceCredential, isNotAuthorized, isSpaceGone } from "./credential.js";
+export { listSpaceRepos, listSpaceWatches } from "./store.js";
+export { isSpaceReadable, readableSpaces, withReadableSpaces } from "./visibility.js";
+export { UngatedSpaceQueryError, spaceBackedCollections } from "./guard.js";
+export { forgetViewerSpaces, readableSpacesFor, viewerCredential } from "./viewer.js";
+/**
+ * A DPoP proof signed by this instance's own key, for an app that has to hold
+ * a DPoP-bound token itself — a community host minting one for a member to act
+ * as the community, say. The key is the one hatk already presents to PDSes.
+ */
+export async function serverDpopProof(method, url, accessToken, nonce) {
+    const key = await getServerKey('appview-oauth-key');
+    if (!key)
+        throw new Error('No server key: is OAuth configured?');
+    return createDpopProof(JSON.parse(key.privateKey), JSON.parse(key.publicKey), method, url, accessToken, nonce);
+}
+export { handleWriteNotice } from "./engine.js";
+export { clearPendingNotices, NoticeError, parseWriteNotice, scheduleNoticeSync, verifyNotice, } from "./notify.js";
+export * from "./uri.js";
+export { blobCid, spaceBlobUrl } from "./blob.js";
+export { records, requireSpace, spaceRecords } from "./records.js";
+let sweepTimer = null;
+/**
+ * What a notice must be addressed to for this instance to act on it, and what
+ * every registration names. Null when no service DID is configured, which is
+ * also what makes the inbound routes refuse everything.
+ */
+let serviceId = null;
+export function spaceServiceId() {
+    return serviceId;
+}
+/**
+ * The DID document an authority resolves to find where to deliver notices.
+ *
+ * It publishes a service entry and nothing else. A syncer signs nothing — it
+ * verifies inbound notices and presents credentials bound to an ephemeral key
+ * — so there is no verification method to publish and no key here to steal.
+ */
+export function spaceDidDocument(did, endpoint, fragment) {
+    return {
+        '@context': ['https://www.w3.org/ns/did/v1'],
+        id: did,
+        service: [
+            {
+                id: `#${fragment}`,
+                type: 'AtprotoSpaceService',
+                serviceEndpoint: endpoint,
+            },
+        ],
+    };
+}
+/**
+ * Configure the engine and start the reconcile sweep.
+ *
+ * Returns without starting anything if the instance has no OAuth: reading a
+ * space begins with a delegation token from a member's own PDS, so an instance
+ * that holds no sessions has no way to obtain one and would sweep forever
+ * finding nothing.
+ */
+export function startSpaces(opts) {
+    const { spaces, oauth, plc, collections } = opts;
+    if (!oauth) {
+        log("[spaces] configured but OAuth is not — a space is read with a member's delegation, so nothing to do");
+        return;
+    }
+    if (spaces.types.length === 0) {
+        log('[spaces] configured with no space types — nothing to index');
+        return;
+    }
+    configureSpaceIdentity(plc);
+    serviceId = spaces.serviceDid ? `${spaces.serviceDid}#${spaces.serviceFragment ?? 'atproto_space_syncer'}` : null;
+    configureSpaceEngine({
+        oauth,
+        types: new Set(spaces.types),
+        collections,
+        ...(serviceId ? { serviceId } : {}),
+    });
+    // The tables a space row can land in, so raw SQL over one of them without
+    // the gate is refused by name rather than quietly served to everyone.
+    const backed = new Set(spaces.types.flatMap((type) => collectionsForSpaceType(type)));
+    setSpaceBackedCollections(backed);
+    if (backed.size > 0) {
+        log(`[spaces] raw SQL over ${[...backed].join(', ')} must carry ctx.spaceFilter`);
+    }
+    const intervalMs = Math.max(30, spaces.reconcileInterval ?? 300) * 1000;
+    const sweep = async () => {
+        for (const space of spaces.watch ?? []) {
+            try {
+                await watchSpace(space);
+            }
+            catch (err) {
+                emit('spaces', 'watch_failed', {
+                    space,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        await reconcileAll();
+    };
+    // Deferred rather than run inline: the server is already listening by the
+    // time this is called, and a first sweep that has to reach several hosts
+    // should not sit in front of the first request.
+    setTimeout(() => void sweep().catch(() => { }), 1000).unref();
+    sweepTimer = setInterval(() => void sweep().catch(() => { }), intervalMs);
+    sweepTimer.unref();
+    log(`[spaces] indexing ${spaces.types.join(', ')} — reconciling every ${intervalMs / 1000}s`);
+}
+export function stopSpaces() {
+    if (sweepTimer)
+        clearInterval(sweepTimer);
+    sweepTimer = null;
+    serviceId = null;
+    setSpaceBackedCollections([]);
+    clearPendingNotices();
+}
+/** Re-exported so an app's on-login hook can start following a space it just learned about. */
+export { watchSpace as followSpace, unwatchSpace as unfollowSpace };

package/dist/spaces/notify.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Receiving write notices from a space authority.
+ *
+ * A space's writes never reach a firehose, so an authority tells its
+ * subscribers directly: register once, and every write into the space arrives
+ * as a `notifyWrite` carrying the repo and the revision it reached — and no
+ * records. The notice says something moved; reading it is still the syncer's
+ * job, with its own credential.
+ *
+ * This only makes sync prompt, never correct. Delivery is best-effort by
+ * design: the reference host forwards each notice once from an in-memory queue
+ * and logs the failure, so a missed one is recovered by the reconcile sweep or
+ * by the next write. Nothing here may be load-bearing.
+ *
+ * ## Why this needs its own verifier
+ *
+ * A forwarded notice does not look like the one a PDS sends its own authority.
+ * At origin, a writer's host signs with `iss` = the writer and `aud` = the bare
+ * authority DID. Forwarded onward, the authority re-signs with `iss` = itself
+ * and `aud` = the registered service identifier *including its fragment*. The
+ * reference PDS's own inbound handler rejects exactly that shape — it requires
+ * `iss` to equal the claimed writer and `aud` to equal the bare authority — so
+ * a receiver cannot borrow it and has to check the forwarded shape itself.
+ */
+export declare class NoticeError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Check a service-auth JWT that claims to come from `expectedIss`.
+ *
+ * The audience must match this instance's own service identifier exactly,
+ * fragment included: a token addressed to somebody else is not ours to act on
+ * however valid its signature. The method is checked for the same reason — a
+ * token minted for one call must not be replayable against another.
+ */
+export declare function verifyNotice(authorization: string | null, expected: {
+    iss: string;
+    aud: string;
+    lxm: string;
+}): Promise<void>;
+export interface WriteNotice {
+    space: string;
+    repo: string;
+    rev: string;
+}
+export declare function parseWriteNotice(body: unknown): WriteNotice | null;
+export declare function scheduleNoticeSync(key: string, run: () => Promise<void>, delay?: number): void;
+/** Drop every pending sync. For shutdown, and for tests. */
+export declare function clearPendingNotices(): void;
+//# sourceMappingURL=notify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../src/spaces/notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAUH,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM;CAIlB;AAcD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,QAAQ,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAMlE;AAcD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,SAAc,GAAG,IAAI,CASnG;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C"}

package/dist/spaces/notify.js

@@ -0,0 +1,121 @@
+/**
+ * Receiving write notices from a space authority.
+ *
+ * A space's writes never reach a firehose, so an authority tells its
+ * subscribers directly: register once, and every write into the space arrives
+ * as a `notifyWrite` carrying the repo and the revision it reached — and no
+ * records. The notice says something moved; reading it is still the syncer's
+ * job, with its own credential.
+ *
+ * This only makes sync prompt, never correct. Delivery is best-effort by
+ * design: the reference host forwards each notice once from an in-memory queue
+ * and logs the failure, so a missed one is recovered by the reconcile sweep or
+ * by the next write. Nothing here may be load-bearing.
+ *
+ * ## Why this needs its own verifier
+ *
+ * A forwarded notice does not look like the one a PDS sends its own authority.
+ * At origin, a writer's host signs with `iss` = the writer and `aud` = the bare
+ * authority DID. Forwarded onward, the authority re-signs with `iss` = itself
+ * and `aud` = the registered service identifier *including its fragment*. The
+ * reference PDS's own inbound handler rejects exactly that shape — it requires
+ * `iss` to equal the claimed writer and `aud` to equal the bare authority — so
+ * a receiver cannot borrow it and has to check the forwarded shape itself.
+ */
+import { emit } from "../logger.js";
+import { atprotoSigningKey } from "./identity.js";
+import { parseSpaceRef } from "./uri.js";
+import { verifySignature } from "./verify.js";
+/** Clock skew tolerated on a notice's expiry. The reference signs them for 60s. */
+const SKEW_SEC = 60;
+export class NoticeError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+function base64UrlToBytes(value) {
+    const padded = value.replace(/-/g, '+').replace(/_/g, '/');
+    return new Uint8Array(Buffer.from(padded, 'base64'));
+}
+/**
+ * Check a service-auth JWT that claims to come from `expectedIss`.
+ *
+ * The audience must match this instance's own service identifier exactly,
+ * fragment included: a token addressed to somebody else is not ours to act on
+ * however valid its signature. The method is checked for the same reason — a
+ * token minted for one call must not be replayable against another.
+ */
+export async function verifyNotice(authorization, expected) {
+    const token = authorization?.match(/^Bearer (.+)$/)?.[1];
+    if (!token)
+        throw new NoticeError(401, 'Missing service auth');
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        throw new NoticeError(401, 'Malformed service auth');
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    }
+    catch {
+        throw new NoticeError(401, 'Malformed service auth');
+    }
+    // The issuer is checked against the space named in the body rather than
+    // trusted from the token, so a valid token from one authority cannot be used
+    // to speak about another authority's space.
+    if (payload.iss?.split('#')[0] !== expected.iss) {
+        throw new NoticeError(403, 'Notice issuer is not the space authority');
+    }
+    if (payload.aud !== expected.aud)
+        throw new NoticeError(403, 'Notice is addressed elsewhere');
+    if (payload.lxm !== expected.lxm)
+        throw new NoticeError(403, 'Notice is for a different method');
+    if (typeof payload.exp !== 'number' || payload.exp + SKEW_SEC < Date.now() / 1000) {
+        throw new NoticeError(401, 'Notice has expired');
+    }
+    const key = await atprotoSigningKey(expected.iss);
+    if (!key)
+        throw new NoticeError(502, `Could not resolve a signing key for ${expected.iss}`);
+    const message = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
+    if (!verifySignature(key, base64UrlToBytes(parts[2]), message)) {
+        throw new NoticeError(403, 'Notice signature does not verify');
+    }
+}
+export function parseWriteNotice(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const { space, repo, rev } = body;
+    if (typeof space !== 'string' || typeof repo !== 'string' || typeof rev !== 'string')
+        return null;
+    if (!parseSpaceRef(space) || !repo.startsWith('did:'))
+        return null;
+    return { space, repo, rev };
+}
+/**
+ * Collapse a burst of notices for the same repo into one sync.
+ *
+ * A member writing a gallery produces a notice per record, and syncing per
+ * notice would read the same repo a dozen times over a few seconds. A short
+ * trailing delay turns that into one read, which is also what keeps a flood —
+ * forged or otherwise — from costing more than one sync per interval.
+ */
+const DEBOUNCE_MS = 750;
+const pending = new Map();
+export function scheduleNoticeSync(key, run, delay = DEBOUNCE_MS) {
+    const existing = pending.get(key);
+    if (existing)
+        clearTimeout(existing);
+    const timer = setTimeout(() => {
+        pending.delete(key);
+        void run().catch((err) => emit('spaces', 'notice_sync_failed', { key, error: err?.message ?? String(err) }));
+    }, delay);
+    timer.unref?.();
+    pending.set(key, timer);
+}
+/** Drop every pending sync. For shutdown, and for tests. */
+export function clearPendingNotices() {
+    for (const timer of pending.values())
+        clearTimeout(timer);
+    pending.clear();
+}

package/dist/spaces/records.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The reads an app over permissioned spaces needs and should not have to write.
+ *
+ * Each of these is two things done in the right order — a select that carries
+ * the space gate, then resolution into properly shaped rows — and an app that
+ * writes them itself has to know both. Getting the first wrong serves a private
+ * space to whoever asks. So they are the framework's.
+ */
+import { getRecordsByUris, reshapeRow } from '../database/db.ts';
+import type { Row } from '../lex-types.ts';
+/**
+ * Every record of one collection in one space the viewer may read, oldest
+ * first.
+ *
+ * A space outside the viewer's scope matches no rows, so the result is empty
+ * rather than refused; `requireSpace` is the explicit refusal for a page that
+ * should say "members only" instead of showing nothing.
+ */
+export declare function spaceRecords<R = unknown>(collection: string, space: string): Promise<Row<R>[]>;
+/**
+ * Every record of one collection where `field` is one of `values`, oldest
+ * first — the many-rows counterpart of `ctx.lookup`, which keeps one per key.
+ *
+ * Gated like every other read: a space row appears only inside a scope that
+ * names its space, and a public row always.
+ */
+export declare function records<R = unknown>(collection: string, field: string, values: string[]): Promise<Row<R>[]>;
+/**
+ * Refuse the way the space itself would.
+ *
+ * A viewer the space's authority does not admit gets `NotAuthorized`, which
+ * is the ordinary shape of "not a member" — the same answer their own browser
+ * would have had from a refused credential.
+ */
+export declare function requireSpace(space: string): void;
+export { getRecordsByUris, reshapeRow };
+//# sourceMappingURL=records.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/spaces/records.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAa,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE3E,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AAK1C;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAQpG;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAejH;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEhD;AAGD,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAA"}

package/dist/spaces/records.js

@@ -0,0 +1,63 @@
+/**
+ * The reads an app over permissioned spaces needs and should not have to write.
+ *
+ * Each of these is two things done in the right order — a select that carries
+ * the space gate, then resolution into properly shaped rows — and an app that
+ * writes them itself has to know both. Getting the first wrong serves a private
+ * space to whoever asks. So they are the framework's.
+ */
+import { getRecordsByUris, getSchema, reshapeRow } from "../database/db.js";
+import { resolveRecords } from "../hydrate.js";
+import { InvalidRequestError } from "../xrpc.js";
+import { spaceFilterSql, isSpaceReadable } from "./visibility.js";
+import { guardedQuerySQL } from "./guard.js";
+/**
+ * Every record of one collection in one space the viewer may read, oldest
+ * first.
+ *
+ * A space outside the viewer's scope matches no rows, so the result is empty
+ * rather than refused; `requireSpace` is the explicit refusal for a page that
+ * should say "members only" instead of showing nothing.
+ */
+export async function spaceRecords(collection, space) {
+    if (!getSchema(collection))
+        return [];
+    const gate = spaceFilterSql('t', 2);
+    const rows = (await guardedQuerySQL(`SELECT t.uri FROM "${collection}" t WHERE t.space = $1 AND ${gate.sql} ORDER BY t.indexed_at ASC`, [space, ...gate.params]));
+    return resolveRecords(rows.map((r) => r.uri));
+}
+/**
+ * Every record of one collection where `field` is one of `values`, oldest
+ * first — the many-rows counterpart of `ctx.lookup`, which keeps one per key.
+ *
+ * Gated like every other read: a space row appears only inside a scope that
+ * names its space, and a public row always.
+ */
+export async function records(collection, field, values) {
+    const schema = getSchema(collection);
+    if (!schema || values.length === 0)
+        return [];
+    const known = new Set(schema.columns.map((c) => c.name));
+    known.add('did');
+    // The field goes into SQL by name; a name the schema does not know is
+    // either a typo or an attempt, and both are refused the same way.
+    if (!known.has(field))
+        throw new InvalidRequestError(`Unknown field ${field} on ${collection}`);
+    const placeholders = values.map((_, i) => `$${i + 1}`).join(',');
+    const gate = spaceFilterSql('t', values.length + 1);
+    const rows = (await guardedQuerySQL(`SELECT t.uri FROM "${collection}" t WHERE t.${field} IN (${placeholders}) AND ${gate.sql} ORDER BY t.indexed_at ASC`, [...values, ...gate.params]));
+    return resolveRecords(rows.map((r) => r.uri));
+}
+/**
+ * Refuse the way the space itself would.
+ *
+ * A viewer the space's authority does not admit gets `NotAuthorized`, which
+ * is the ordinary shape of "not a member" — the same answer their own browser
+ * would have had from a refused credential.
+ */
+export function requireSpace(space) {
+    if (!isSpaceReadable(space))
+        throw new InvalidRequestError('Not a member of this space', 'NotAuthorized');
+}
+// Re-exported so a handler can shape a row the way a read shaped it.
+export { getRecordsByUris, reshapeRow };

package/dist/spaces/store.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+export interface SpaceWatch {
+    space: string;
+    authority: string;
+    spaceType: string;
+    /** The account whose session last minted a credential for this space, if any. */
+    readerDid: string | null;
+    /** Expiry of the current `registerNotify` registration, ISO 8601. */
+    registeredUntil: string | null;
+    lastError: string | null;
+}
+export interface SpaceRepo {
+    space: string;
+    did: string;
+    /** The PDS holding this writer's repo — their own, not the authority's. */
+    pds: string | null;
+    /** The revision this writer's repo had been read to. */
+    rev: string | null;
+}
+export declare function listSpaceWatches(): Promise<SpaceWatch[]>;
+export declare function getSpaceWatch(space: string): Promise<SpaceWatch | 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 declare function putSpaceWatch(input: {
+    space: string;
+    authority: string;
+    spaceType: string;
+}): Promise<void>;
+export declare function updateSpaceWatch(space: string, patch: {
+    readerDid?: string | null;
+    registeredUntil?: string | null;
+    lastError?: string | null;
+}): Promise<void>;
+export declare function deleteSpaceWatch(space: string): Promise<void>;
+export declare function listSpaceRepos(space: string): Promise<SpaceRepo[]>;
+export declare function getSpaceRepo(space: string, did: string): Promise<SpaceRepo | null>;
+export declare function putSpaceRepo(input: SpaceRepo): Promise<void>;
+export declare function deleteSpaceRepo(space: string, did: string): Promise<void>;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/spaces/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,iFAAiF;IACjF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,qEAAqE;IACrE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,2EAA2E;IAC3E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,wDAAwD;IACxD,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CACnB;AA6BD,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAG9D;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAG7E;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBjH;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC/F,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGnE;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAKxE;AAED,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAMxF;AAED,wBAAsB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAQlE;AAED,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/E"}