@hatk/hatk 0.0.1-alpha.11 → 0.0.1-alpha.111

package/dist/spaces/credential.js

@@ -0,0 +1,220 @@
+/**
+ * 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 the exchange   (10 min)
+ *
+ * — 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: each request signs the credential together with the
+ * DID it is addressed to, so a host handed one to serve its own repo cannot
+ * replay it against any other account. See signature.ts.
+ *
+ * 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 { pdsXrpc } from "../pds-proxy.js";
+import { emit } from "../logger.js";
+import { spaceHostEndpoint } from "./identity.js";
+import { generateSpaceSigKey, spaceSigHeaders } from "./signature.js";
+import { parseSpaceRef } from "./uri.js";
+/**
+ * Re-mint this long before the credential's own expiry rather than racing it.
+ * Credentials live ten minutes, so this keeps nine of them.
+ */
+const RENEW_LEAD_MS = 60 * 1000;
+export class SpaceCredentialError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+/** A refusal about who is asking, rather than about the space or the network. */
+export function isNotAuthorized(err) {
+    return err instanceof SpaceCredentialError && (err.code === 'UserNotAuthorized' || err.code === 'NotAuthorized');
+}
+export function isSpaceGone(err) {
+    return err instanceof SpaceCredentialError && (err.code === 'SpaceDeleted' || err.code === 'SpaceNotFound');
+}
+function expiryOf(jwt) {
+    try {
+        const payload = JSON.parse(Buffer.from(jwt.split('.')[1], 'base64url').toString());
+        return typeof payload.exp === 'number' ? payload.exp * 1000 : Date.now() + 60 * 60 * 1000;
+    }
+    catch {
+        // An unreadable expiry is not a reason to refuse a credential the authority
+        // just issued; treat it as short-lived and re-mint sooner.
+        return Date.now() + 10 * 60 * 1000;
+    }
+}
+/**
+ * Exchange a delegation token for a credential at the authority, binding it to
+ * `key` by signing the token with it.
+ */
+async function exchange(authorityHost, space, delegationToken, key) {
+    const url = `${authorityHost}/xrpc/com.atproto.space.getSpaceCredential`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            ...(await spaceSigHeaders(key, `Bearer ${delegationToken}`)),
+        },
+        body: JSON.stringify({ space }),
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || !body.credential) {
+        throw new SpaceCredentialError(res.status, body.error ?? (res.status >= 500 ? 'UpstreamFailure' : 'InvalidRequest'), body.message ?? `getSpaceCredential refused (${res.status})`);
+    }
+    return body.credential;
+}
+/** Mint a credential for `space` using `readerDid`'s stored session. */
+export async function mintSpaceCredential(oauthConfig, space, readerDid) {
+    const ref = parseSpaceRef(space);
+    if (!ref)
+        throw new SpaceCredentialError(400, 'InvalidRequest', `Not a space ref: ${space}`);
+    // The reader's own PDS signs this, under the whole-space read grant their
+    // session carries. A session without that scope is refused here, before the
+    // authority is ever contacted.
+    let token;
+    try {
+        const out = await pdsXrpc(oauthConfig, { did: readerDid }, 'com.atproto.space.getDelegationToken', {
+            params: { space },
+        });
+        if (typeof out.token !== 'string')
+            throw new Error('PDS returned no delegation token');
+        token = out.token;
+    }
+    catch (err) {
+        throw new SpaceCredentialError(err?.status ?? 502, 'DelegationFailed', err?.message ?? 'delegation failed');
+    }
+    // A key per credential, held only as long as the credential is.
+    const key = await generateSpaceSigKey();
+    const authorityHost = await spaceHostEndpoint(ref.authority);
+    const credential = await exchange(authorityHost, space, token, key);
+    // Signatures depend only on the credential and the audience, so each is made
+    // once and reused for as long as the credential lives.
+    const signed = new Map();
+    const credentialFetch = async (input, init) => {
+        const url = typeof input === 'string' ? input : input.toString();
+        const audience = new URL(url).searchParams.get('repo') ?? ref.authority;
+        let sig = signed.get(audience);
+        if (!sig) {
+            sig = spaceSigHeaders(key, `Atproto-Space ${credential}`, audience);
+            signed.set(audience, sig);
+        }
+        const headers = new Headers(init?.headers);
+        for (const [name, value] of Object.entries(await sig))
+            headers.set(name, value);
+        return fetch(url, { ...init, headers });
+    };
+    return { space, readerDid, expiresAt: expiryOf(credential), fetch: credentialFetch };
+}
+// --- Cache ---
+const cache = new Map();
+function fresh(cred) {
+    return !!cred && cred.expiresAt - RENEW_LEAD_MS > Date.now();
+}
+/**
+ * A credential for `space`, minted with whichever candidate session works.
+ *
+ * Candidates are tried in order and the first that succeeds is cached. A
+ * refusal about the reader — they were ejected, or never belonged — moves on to
+ * the next candidate; a refusal about the space itself stops the whole attempt,
+ * since no other reader would fare better.
+ */
+export async function getSpaceCredential(oauthConfig, space, candidates, opts = {}) {
+    if (!opts.refresh) {
+        const cached = cache.get(space);
+        if (fresh(cached))
+            return cached;
+    }
+    let lastError;
+    for (const readerDid of candidates) {
+        try {
+            const credential = await mintSpaceCredential(oauthConfig, space, readerDid);
+            cache.set(space, credential);
+            return credential;
+        }
+        catch (err) {
+            if (isSpaceGone(err))
+                throw err;
+            lastError = err;
+            emit('spaces', 'credential_refused', {
+                space,
+                reader_did: readerDid,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    cache.delete(space);
+    throw lastError ?? new SpaceCredentialError(403, 'NoReader', `No session on this instance can read ${space}`);
+}
+export function forgetSpaceCredential(space) {
+    cache.delete(space);
+}
+// --- Per reader ---
+/**
+ * Credentials minted as one particular reader, for reads made on their behalf.
+ *
+ * Kept apart from the cache above, which holds whichever session works for a
+ * space and is right for indexing it. A read made for a viewer has to be made
+ * as that viewer: the authority's answer is the authorization.
+ */
+const readerCache = new Map();
+/** Pairs held at once. Past this the least recently used goes. */
+const MAX_READER_CREDENTIALS = 5000;
+/**
+ * `readerDid`'s own credential for `space`, minted with their stored session.
+ *
+ * Throws a {@link SpaceCredentialError} when they may not read it, carrying the
+ * authority's status and code, and caches only successes — a refusal is asked
+ * again next time rather than remembered. `refresh` mints anew, for a read the
+ * host refused despite a credential that had not expired by our clock.
+ */
+export async function readerSpaceCredential(oauthConfig, readerDid, space, opts = {}) {
+    const key = `${readerDid} ${space}`;
+    const cached = readerCache.get(key);
+    readerCache.delete(key);
+    if (!opts.refresh && fresh(cached)) {
+        readerCache.set(key, cached);
+        return cached;
+    }
+    const credential = await mintSpaceCredential(oauthConfig, space, readerDid);
+    readerCache.set(key, credential);
+    while (readerCache.size > MAX_READER_CREDENTIALS) {
+        const oldest = readerCache.keys().next();
+        if (oldest.done)
+            break;
+        readerCache.delete(oldest.value);
+    }
+    return credential;
+}
+/**
+ * Drop `readerDid`'s cached credential for `space`, after something that may
+ * have changed their standing in it — leaving it, say. The next read mints anew.
+ */
+export function forgetReaderSpaceCredential(readerDid, space) {
+    readerCache.delete(`${readerDid} ${space}`);
+}
+/** For tests: drop every cached credential. */
+export function resetSpaceCredentials() {
+    cache.clear();
+    readerCache.clear();
+}

package/dist/spaces/engine.d.ts

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

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

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