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

package/dist/pds-proxy.js

@@ -0,0 +1,356 @@
+// Shared PDS proxy functions — used by both HTTP route handlers and XRPC handlers.
+import { getSession, getServerKey, deleteSession } from "./oauth/db.js";
+import { createDpopProof } from "./oauth/dpop.js";
+import { refreshPdsSession } from "./oauth/server.js";
+import { validateRecord } from '@bigmoves/lexicon';
+import { getLexiconArray } from "./database/schema.js";
+import { insertRecord, deleteRecord as dbDeleteRecord } from "./database/db.js";
+import { emit } from "./logger.js";
+import { runLabelRules } from "./labels.js";
+export class ProxyError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export class ScopeMissingProxyError extends ProxyError {
+    constructor() {
+        super(401, 'ScopeMissingError');
+    }
+}
+/** Shared retry logic: DPoP nonce handling + token refresh. */
+async function withDpopRetry(oauthConfig, session, doFetch) {
+    let accessToken = session.access_token;
+    let result = await doFetch(accessToken);
+    if (result.ok)
+        return result;
+    let nonce;
+    // Step 1: handle DPoP nonce requirement
+    if (isNonceChallenge(result)) {
+        nonce = result.headers.get('DPoP-Nonce') || undefined;
+        if (nonce) {
+            result = await doFetch(accessToken, nonce);
+            if (result.ok)
+                return result;
+        }
+    }
+    // Step 2: handle insufficient scope — clear session so user re-authenticates with updated scopes
+    if (result.body.error === 'ScopeMissingError') {
+        await deleteSession(session.did);
+        throw new ScopeMissingProxyError();
+    }
+    // Step 3: handle expired PDS token — refresh and retry
+    if (isTokenError(result.body.error)) {
+        const refreshed = await refreshPdsSession(oauthConfig, session);
+        if (refreshed) {
+            accessToken = refreshed.accessToken;
+            result = await doFetch(accessToken, nonce);
+            if (result.ok)
+                return result;
+            if (isNonceChallenge(result)) {
+                nonce = result.headers.get('DPoP-Nonce') || undefined;
+                if (nonce)
+                    result = await doFetch(accessToken, nonce);
+            }
+            // A token minted seconds ago cannot be expired, so a second refusal is
+            // about the grant rather than the token: the session was authorized
+            // before the app asked for the scope this call needs, and no number of
+            // refreshes will add it. Read as a scope problem it becomes the prompt to
+            // authorize again; read as expiry it was an opaque 500.
+            //
+            // Not every PDS names this case. The reference answers ScopeMissingError,
+            // handled above; pds.js answers InvalidToken for a scope its permissioned
+            // space endpoints refuse, which is indistinguishable from expiry until
+            // the refresh rules expiry out.
+            if (!result.ok && isTokenError(result.body.error)) {
+                await deleteSession(session.did);
+                throw new ScopeMissingProxyError();
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Is this refusal a DPoP nonce challenge — a request to retry, not a dead token?
+ *
+ * A nonce challenge is the one 401 that costs nothing to satisfy: the server
+ * hands back the nonce it wants in the same response. Miss it and the failure
+ * falls through to the token-error branch below, which refreshes, replays the
+ * identical proof, is refused identically, and drops the user's session — a
+ * re-authorization to fix a header.
+ *
+ * So it is read the way RFC 9449 §8 writes it, from
+ * `WWW-Authenticate: DPoP error="use_dpop_nonce"`, and only then from the body.
+ * The body is not always available to read: zds sends that header but an
+ * `InvalidToken` body, because its XRPC error handler overwrites the
+ * `UseDpopNonce` one on the way out.
+ *
+ * The `DPoP-Nonce` header alone is not the signal. A server may attach one to
+ * every 401 it sends, including 401s about a genuinely invalid token, and
+ * treating those as challenges would replay every dead token once for nothing.
+ */
+function isNonceChallenge(result) {
+    const error = result.body.error;
+    if (error === 'use_dpop_nonce' || error === 'UseDpopNonce')
+        return true;
+    return result.status === 401 && (result.headers.get('WWW-Authenticate') ?? '').includes('use_dpop_nonce');
+}
+/**
+ * The PDS returns 'InvalidToken' or 'ExpiredToken' (AT Proto PascalCase
+ * convention) while the OAuth spec uses 'invalid_token' (RFC 6750 snake_case).
+ */
+function isTokenError(error) {
+    return error === 'invalid_token' || error === 'InvalidToken' || error === 'ExpiredToken';
+}
+async function proxyToPds(oauthConfig, session, method, pdsUrl, body) {
+    const serverKey = await getServerKey('appview-oauth-key');
+    const privateJwk = JSON.parse(serverKey.privateKey);
+    const publicJwk = JSON.parse(serverKey.publicKey);
+    return withDpopRetry(oauthConfig, session, async (token, nonce) => {
+        const proof = await createDpopProof(privateJwk, publicJwk, method, pdsUrl, token, nonce);
+        // A GET carries no body, and sending a JSON content-type without one makes
+        // some servers try to parse it. Queries reach here through pdsXrpc.
+        const hasBody = method !== 'GET' && body !== undefined;
+        const res = await fetch(pdsUrl, {
+            method,
+            headers: {
+                ...(hasBody ? { 'Content-Type': 'application/json' } : {}),
+                Authorization: `DPoP ${token}`,
+                DPoP: proof,
+            },
+            body: hasBody ? JSON.stringify(body) : undefined,
+        });
+        const resBody = await res.json().catch(() => ({}));
+        return { ok: res.ok, status: res.status, body: resBody, headers: res.headers };
+    });
+}
+/** Proxy a raw binary request to the user's PDS with DPoP + nonce retry + token refresh. */
+async function proxyToPdsRaw(oauthConfig, session, pdsUrl, body, contentType) {
+    const serverKey = await getServerKey('appview-oauth-key');
+    const privateJwk = JSON.parse(serverKey.privateKey);
+    const publicJwk = JSON.parse(serverKey.publicKey);
+    return withDpopRetry(oauthConfig, session, async (token, nonce) => {
+        const proof = await createDpopProof(privateJwk, publicJwk, 'POST', pdsUrl, token, nonce);
+        const res = await fetch(pdsUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': contentType,
+                'Content-Length': String(body.length),
+                Authorization: `DPoP ${token}`,
+                DPoP: proof,
+            },
+            body: Buffer.from(body),
+        });
+        const resBody = await res.json().catch(() => ({}));
+        return { ok: res.ok, status: res.status, body: resBody, headers: res.headers };
+    });
+}
+/**
+ * Call any XRPC method on the user's PDS with their session.
+ *
+ * The escape hatch beside the typed record helpers above, for methods hatk has
+ * no opinion about — `com.atproto.space.*` and the rest of proposal 0016 being
+ * the case it was added for. Nothing is validated or indexed: the response is
+ * whatever the PDS sent, and it is the caller's job to know its shape.
+ *
+ * The session's granted scopes still apply. A method the user never authorized
+ * comes back as a 403 from the PDS, not from here.
+ */
+export async function pdsXrpc(oauthConfig, viewer, nsid, options = {}) {
+    const session = await getSession(viewer.did);
+    if (!session)
+        throw new ProxyError(401, 'No PDS session for user');
+    const method = options.method ?? 'GET';
+    const url = new URL(`${session.pds_endpoint}/xrpc/${nsid}`);
+    for (const [key, value] of Object.entries(options.params ?? {})) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                url.searchParams.append(key, String(v));
+        }
+        else {
+            url.searchParams.append(key, String(value));
+        }
+    }
+    const res = await proxyToPds(oauthConfig, session, method, url.toString(), options.body);
+    if (!res.ok) {
+        throw new ProxyError(res.status, String(res.body.error || `${nsid} failed`));
+    }
+    return res.body;
+}
+export async function pdsCreateRecord(oauthConfig, viewer, input) {
+    const validationError = validateRecord(getLexiconArray(), input.collection, input.record);
+    if (validationError) {
+        throw new ProxyError(400, `InvalidRecord: ${validationError.path ? validationError.path + ': ' : ''}${validationError.message}`);
+    }
+    const session = await getSession(viewer.did);
+    if (!session)
+        throw new ProxyError(401, 'No PDS session for user');
+    const pdsUrl = `${session.pds_endpoint}/xrpc/com.atproto.repo.createRecord`;
+    const pdsBody = {
+        repo: viewer.did,
+        collection: input.collection,
+        rkey: input.rkey,
+        record: input.record,
+    };
+    const pdsRes = await proxyToPds(oauthConfig, session, 'POST', pdsUrl, pdsBody);
+    if (!pdsRes.ok)
+        throw new ProxyError(pdsRes.status, String(pdsRes.body.error || 'PDS write failed'));
+    try {
+        await insertRecord(input.collection, String(pdsRes.body.uri), String(pdsRes.body.cid), viewer.did, input.record);
+        await runLabelRules({
+            uri: String(pdsRes.body.uri),
+            cid: String(pdsRes.body.cid),
+            did: viewer.did,
+            collection: input.collection,
+            value: input.record,
+        });
+    }
+    catch (err) {
+        emit('pds-proxy', 'local_index_error', {
+            op: 'createRecord',
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    return pdsRes.body;
+}
+export async function pdsDeleteRecord(oauthConfig, viewer, input) {
+    const session = await getSession(viewer.did);
+    if (!session)
+        throw new ProxyError(401, 'No PDS session for user');
+    const pdsUrl = `${session.pds_endpoint}/xrpc/com.atproto.repo.deleteRecord`;
+    const pdsBody = {
+        repo: viewer.did,
+        collection: input.collection,
+        rkey: input.rkey,
+    };
+    const pdsRes = await proxyToPds(oauthConfig, session, 'POST', pdsUrl, pdsBody);
+    if (!pdsRes.ok)
+        throw new ProxyError(pdsRes.status, String(pdsRes.body.error || 'PDS delete failed'));
+    try {
+        const uri = `at://${viewer.did}/${input.collection}/${input.rkey}`;
+        await dbDeleteRecord(input.collection, uri);
+    }
+    catch (err) {
+        emit('pds-proxy', 'local_index_error', {
+            op: 'deleteRecord',
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    return pdsRes.body;
+}
+export async function pdsPutRecord(oauthConfig, viewer, input) {
+    const validationError = validateRecord(getLexiconArray(), input.collection, input.record);
+    if (validationError) {
+        throw new ProxyError(400, `InvalidRecord: ${validationError.path ? validationError.path + ': ' : ''}${validationError.message}`);
+    }
+    const session = await getSession(viewer.did);
+    if (!session)
+        throw new ProxyError(401, 'No PDS session for user');
+    const pdsUrl = `${session.pds_endpoint}/xrpc/com.atproto.repo.putRecord`;
+    const pdsBody = {
+        repo: viewer.did,
+        collection: input.collection,
+        rkey: input.rkey,
+        record: input.record,
+    };
+    const pdsRes = await proxyToPds(oauthConfig, session, 'POST', pdsUrl, pdsBody);
+    if (!pdsRes.ok)
+        throw new ProxyError(pdsRes.status, String(pdsRes.body.error || 'PDS write failed'));
+    try {
+        await insertRecord(input.collection, String(pdsRes.body.uri), String(pdsRes.body.cid), viewer.did, input.record);
+        await runLabelRules({
+            uri: String(pdsRes.body.uri),
+            cid: String(pdsRes.body.cid),
+            did: viewer.did,
+            collection: input.collection,
+            value: input.record,
+        });
+    }
+    catch (err) {
+        emit('pds-proxy', 'local_index_error', { op: 'putRecord', error: err instanceof Error ? err.message : String(err) });
+    }
+    return pdsRes.body;
+}
+/** Map dev.hatk.applyWrites#* types to com.atproto.repo.applyWrites#* for PDS. */
+function toPdsWriteType($type) {
+    return $type.replace('dev.hatk.applyWrites#', 'com.atproto.repo.applyWrites#');
+}
+function isCreateOrUpdate($type) {
+    const mapped = toPdsWriteType($type);
+    return mapped === 'com.atproto.repo.applyWrites#create' || mapped === 'com.atproto.repo.applyWrites#update';
+}
+export async function pdsApplyWrites(oauthConfig, viewer, input) {
+    // Validate all create/update records before sending
+    for (const write of input.writes) {
+        if (isCreateOrUpdate(write.$type) && write.value) {
+            const validationError = validateRecord(getLexiconArray(), write.collection, write.value);
+            if (validationError) {
+                throw new ProxyError(400, `InvalidRecord: ${validationError.path ? validationError.path + ': ' : ''}${validationError.message}`);
+            }
+        }
+    }
+    const session = await getSession(viewer.did);
+    if (!session)
+        throw new ProxyError(401, 'No PDS session for user');
+    const pdsUrl = `${session.pds_endpoint}/xrpc/com.atproto.repo.applyWrites`;
+    const pdsBody = {
+        repo: viewer.did,
+        writes: input.writes.map((w) => ({ ...w, $type: toPdsWriteType(w.$type) })),
+    };
+    const pdsRes = await proxyToPds(oauthConfig, session, 'POST', pdsUrl, pdsBody);
+    if (!pdsRes.ok)
+        throw new ProxyError(pdsRes.status, String(pdsRes.body.error || 'PDS applyWrites failed'));
+    // Index results locally
+    const results = pdsRes.body.results ?? [];
+    for (let i = 0; i < input.writes.length; i++) {
+        const write = input.writes[i];
+        const result = results[i];
+        try {
+            const mapped = toPdsWriteType(write.$type);
+            if (mapped === 'com.atproto.repo.applyWrites#create' && result?.uri && result?.cid && write.value) {
+                await insertRecord(write.collection, result.uri, result.cid, viewer.did, write.value);
+                await runLabelRules({
+                    uri: result.uri,
+                    cid: result.cid,
+                    did: viewer.did,
+                    collection: write.collection,
+                    value: write.value,
+                });
+            }
+            else if (mapped === 'com.atproto.repo.applyWrites#update' && result?.uri && result?.cid && write.value) {
+                await insertRecord(write.collection, result.uri, result.cid, viewer.did, write.value);
+                await runLabelRules({
+                    uri: result.uri,
+                    cid: result.cid,
+                    did: viewer.did,
+                    collection: write.collection,
+                    value: write.value,
+                });
+            }
+            else if (mapped === 'com.atproto.repo.applyWrites#delete' && write.rkey) {
+                const uri = `at://${viewer.did}/${write.collection}/${write.rkey}`;
+                await dbDeleteRecord(write.collection, uri);
+            }
+        }
+        catch (err) {
+            emit('pds-proxy', 'local_index_error', {
+                op: 'applyWrites',
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return pdsRes.body;
+}
+export async function pdsUploadBlob(oauthConfig, viewer, body, contentType) {
+    const session = await getSession(viewer.did);
+    if (!session)
+        throw new ProxyError(401, 'No PDS session for user');
+    const pdsUrl = `${session.pds_endpoint}/xrpc/com.atproto.repo.uploadBlob`;
+    const pdsRes = await proxyToPdsRaw(oauthConfig, session, pdsUrl, body, contentType);
+    if (!pdsRes.ok)
+        throw new ProxyError(pdsRes.status, String(pdsRes.body.error || 'PDS upload failed'));
+    return pdsRes.body;
+}

package/dist/private-collections.d.ts

@@ -0,0 +1,13 @@
+export declare function setPrivateCollections(list: string[]): void;
+export declare function isPrivateCollection(nsid: string | null | undefined): boolean;
+/**
+ * The collection segment of a record AT-URI, in either shape.
+ *
+ * A repo record is `at://{did}/{collection}/{rkey}`; a space record is
+ * `at://{authority}/space/{type}/{skey}/{writer}/{collection}/{rkey}`, where
+ * the position a collection used to occupy holds the literal 'space'. Reading
+ * it positionally without that distinction reports every space record as
+ * belonging to a collection named 'space', which no guard would match.
+ */
+export declare function collectionFromUri(uri: string): string | undefined;
+//# sourceMappingURL=private-collections.d.ts.map

package/dist/private-collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-collections.d.ts","sourceRoot":"","sources":["../src/private-collections.ts"],"names":[],"mappings":"AAWA,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAE1D;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjE"}

package/dist/private-collections.js

@@ -0,0 +1,27 @@
+import { collectionFromRecordUri } from "./spaces/uri.js";
+/**
+ * Collections that are indexed and queryable in-process but must never be
+ * served by the built-in dev.hatk.* record endpoints.
+ *
+ * Held module-level, mirroring the schema registry, so the guard can be applied
+ * inside handlers without threading config through every signature.
+ */
+let privateCollections = new Set();
+export function setPrivateCollections(list) {
+    privateCollections = new Set(list);
+}
+export function isPrivateCollection(nsid) {
+    return nsid != null && privateCollections.has(nsid);
+}
+/**
+ * The collection segment of a record AT-URI, in either shape.
+ *
+ * A repo record is `at://{did}/{collection}/{rkey}`; a space record is
+ * `at://{authority}/space/{type}/{skey}/{writer}/{collection}/{rkey}`, where
+ * the position a collection used to occupy holds the literal 'space'. Reading
+ * it positionally without that distinction reports every space record as
+ * belonging to a collection named 'space', which no guard would match.
+ */
+export function collectionFromUri(uri) {
+    return collectionFromRecordUri(uri);
+}

package/dist/push.d.ts

@@ -0,0 +1,54 @@
+export interface ApnsConfig {
+    keyFile: string;
+    keyId: string;
+    teamId: string;
+    bundleId: string;
+    production?: boolean;
+}
+/**
+ * Firebase Cloud Messaging, for Android devices.
+ *
+ * `keyFile` is a Google service-account JSON with the Firebase Messaging role,
+ * resolved like the APNs key: relative to the config file. The project id is
+ * read from that file unless overridden here.
+ */
+export interface FcmConfig {
+    keyFile: string;
+    projectId?: string;
+}
+export interface PushConfig {
+    apns?: ApnsConfig;
+    fcm?: FcmConfig;
+}
+export interface PushPayload {
+    did: string;
+    title: string;
+    body: string;
+    data?: Record<string, string>;
+    collapseId?: string;
+    badge?: number;
+}
+export interface PushInterface {
+    send: (payload: PushPayload) => Promise<void>;
+}
+/**
+ * Initialize push with config. Must be called before send().
+ *
+ * Each transport is loaded on its own: a missing or malformed credential
+ * disables that platform and leaves the other one sending, rather than taking
+ * push down entirely.
+ */
+export declare function initPush(config: PushConfig, configDir: string): void;
+/** Check if push is configured and at least one transport is usable. */
+export declare function isPushEnabled(): boolean;
+/** Which platforms this process can actually deliver to, for startup logging. */
+export declare function enabledPushTransports(): string[];
+/** Build the push interface injected into hook contexts. */
+export declare function buildPushInterface(): PushInterface;
+/** Register a push token for a DID. Upserts on conflict. */
+export declare function registerToken(did: string, token: string, platform: string): Promise<void>;
+/** Remove a push token. */
+export declare function removeToken(token: string): Promise<void>;
+/** Unregister a specific token for a DID. */
+export declare function unregisterToken(did: string, token: string): Promise<void>;
+//# sourceMappingURL=push.d.ts.map

package/dist/push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.d.ts","sourceRoot":"","sources":["../src/push.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,GAAG,CAAC,EAAE,SAAS,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9C;AAsBD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CA4CpE;AAED,wEAAwE;AACxE,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAKhD;AAED,4DAA4D;AAC5D,wBAAgB,kBAAkB,IAAI,aAAa,CAElD;AAmSD,4DAA4D;AAC5D,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/F;AAED,2BAA2B;AAC3B,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAED,6CAA6C;AAC7C,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/E"}