@allus-fyi/company-data 0.0.3

package/dist/esm/webhooks.js

@@ -0,0 +1,329 @@
+/**
+ * Webhook receiver helpers.
+ *
+ * The lower-latency push alternative to polling the changes feed. The platform
+ * delivers each change event to the company's configured webhook URL with:
+ *
+ *   - `X-Allus-Webhook-Id`  — which webhook this is (selects the HMAC secret).
+ *   - `X-Allus-Signature`   — `HMAC-SHA256(rawBody, secret)` as lowercase hex.
+ *   - the body — the same slug-keyed {@link Change} shape as the pull feed,
+ *     JSON or XML. If the webhook has `encrypt_payload` on, the body is REPLACED
+ *     by a `{"_enc":1,...}` envelope encrypted to the company **account** key (and
+ *     the HMAC is then over that envelope — it is the final body that was sent).
+ *
+ * Webhook delivery auth is per-webhook and may be any of five methods (hmac,
+ * bearer, basic, custom header, or none); {@link verifyWebhook} dispatches on the
+ * single method configured in {@link Config} ({@link Config.webhookAuthMethod}).
+ *
+ * All secrets/keys come from {@link Config}. **These helpers take NO key or secret
+ * arguments** — only the raw body, the headers, the config, and (for value typing)
+ * the same decrypt/type closures the {@link Client} already holds.
+ *
+ * The account-key envelope is webhook-specific: the platform wraps it with
+ * OpenSSL's DEFAULT OAEP padding (MGF1-**SHA1**), NOT the SHA-256 wrapper used for
+ * person field values. So unwrapping the envelope uses an OAEP-SHA1 path here
+ * (Node's default `oaepHash`, pinned explicitly to `'sha1'` for clarity), while the
+ * inner field `value` (still a service-key wrapper) decrypts with the normal
+ * SHA-256 {@link decrypt}. HMAC is always computed over the raw bytes, never the
+ * parsed tree.
+ */
+import { createDecipheriv, createHmac, createPrivateKey, privateDecrypt, timingSafeEqual, constants as cryptoConstants, } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { GCM_IV_LEN, GCM_TAG_LEN } from './crypto.js';
+import { WebhookError } from './errors.js';
+import { Change } from './models.js';
+import { parseXml } from './xml.js';
+const HDR_WEBHOOK_ID = 'x-allus-webhook-id';
+const HDR_SIGNATURE = 'x-allus-signature';
+const ENC_MARKER = '_enc';
+// ── header helpers ─────────────────────────────────────────────────────────────
+/** Case-insensitive header lookup (frameworks normalize casing inconsistently). */
+function header(headers, name) {
+    if (!headers)
+        return null;
+    const target = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === target) {
+            if (Array.isArray(value))
+                return value.length > 0 ? String(value[0]) : null;
+            return value != null ? String(value) : null;
+        }
+    }
+    return null;
+}
+function asBytes(rawBody) {
+    if (Buffer.isBuffer(rawBody))
+        return rawBody;
+    if (rawBody instanceof Uint8Array)
+        return Buffer.from(rawBody);
+    if (typeof rawBody === 'string')
+        return Buffer.from(rawBody, 'utf8');
+    throw new WebhookError('webhook rawBody must be a Buffer, Uint8Array, or string');
+}
+// ── verify ─────────────────────────────────────────────────────────────────────
+/**
+ * Verify a webhook against the SINGLE configured auth method.
+ *
+ * Mirrors the platform's per-webhook delivery auth (one method per webhook):
+ *
+ *   - `hmac`   — recompute `HMAC-SHA256(rawBody, secret)` (secret selected by
+ *     `X-Allus-Webhook-Id`) and constant-time-compare to `X-Allus-Signature`.
+ *   - `bearer` — `Authorization` equals `Bearer <token>`.
+ *   - `basic`  — `Authorization` equals `Basic <base64(user:pass)>`.
+ *   - `header` — the configured custom header equals the configured value.
+ *   - `none`   — always `true` (explicit opt-out).
+ *
+ * All comparisons are constant-time. Returns `false` on a missing/mismatched
+ * credential, or when no method is configured — never throws for a bad credential
+ * (that is {@link handleWebhook}'s job). Which method is used is decided entirely
+ * by config ({@link Config.webhookAuthMethod}); config loading guarantees at most
+ * one is set. The HMAC is over the exact raw bytes.
+ */
+export function verifyWebhook(rawBody, headers, config) {
+    const method = config.webhookAuthMethod();
+    if (method === null)
+        return false;
+    if (method === 'none')
+        return true;
+    if (method === 'bearer') {
+        const got = header(headers, 'authorization');
+        if (got === null)
+            return false;
+        return constantTimeStringEqual(got, 'Bearer ' + (config.webhookBearerToken ?? ''));
+    }
+    if (method === 'basic') {
+        const got = header(headers, 'authorization');
+        if (got === null)
+            return false;
+        const basic = config.webhookBasic;
+        const creds = `${basic.username}:${basic.password}`;
+        const token = Buffer.from(creds, 'utf8').toString('base64');
+        return constantTimeStringEqual(got, 'Basic ' + token);
+    }
+    if (method === 'header') {
+        const hdr = config.webhookHeader;
+        const got = header(headers, hdr.name);
+        if (got === null)
+            return false;
+        return constantTimeStringEqual(got, hdr.value);
+    }
+    // method === 'hmac'
+    const body = asBytes(rawBody);
+    const signature = header(headers, HDR_SIGNATURE);
+    if (!signature)
+        return false;
+    const webhookId = header(headers, HDR_WEBHOOK_ID);
+    const secret = config.webhookSecret(webhookId);
+    if (!secret)
+        return false;
+    const expected = createHmac('sha256', secret).update(body).digest('hex');
+    return constantTimeStringEqual(expected, signature.trim().toLowerCase());
+}
+/** Constant-time compare two UTF-8 strings (length-safe). */
+function constantTimeStringEqual(a, b) {
+    // Compare fixed-length byte buffers; if lengths differ, compare against `a`
+    // itself so we never short-circuit on a length mismatch (timing-safe).
+    const ab = Buffer.from(a, 'utf8');
+    const bb = Buffer.from(b, 'utf8');
+    if (ab.length !== bb.length) {
+        // Still do a constant-time compare against a same-length buffer to avoid a
+        // length-based timing oracle, then return false.
+        timingSafeEqual(ab, ab);
+        return false;
+    }
+    return timingSafeEqual(ab, bb);
+}
+// ── parse ──────────────────────────────────────────────────────────────────────
+/**
+ * Parse a webhook body → a typed {@link Change}.
+ *
+ * Does NOT verify the signature (use {@link handleWebhook} for verify+parse).
+ * Handles JSON and XML bodies, and an `encrypt_payload` account-key envelope: if
+ * the (JSON) body is a `{"_enc":1,...}` wrapper, it is first unwrapped with the
+ * account private key (OAEP-SHA1) into the inner serialized payload, which is then
+ * parsed. The inner field `value` (a service-key wrapper) is decrypted by the same
+ * model factory the feed uses, so a webhook `Change` is byte-identical to a feed
+ * `Change`.
+ *
+ * `deps.accountKey` is an optional pre-loaded account private key (the
+ * {@link Client} loads it ONCE and reuses it, so an `encrypt_payload` webhook
+ * doesn't re-read the PEM + re-run PBKDF2 ~100k iters per request). When undefined,
+ * the key is loaded from config on demand — config-only key handling either way.
+ */
+export function parseWebhook(rawBody, headers, config, deps) {
+    // `headers` is part of the webhook contract (verify reads them; parse keeps the
+    // symmetric signature) but the body/envelope decode is header-independent — the
+    // encrypt_payload envelope is self-describing (`{"_enc":1,…}`).
+    void headers;
+    const body = asBytes(rawBody);
+    const payload = decodePayload(body, config, deps.accountKey);
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new WebhookError('webhook payload is not a JSON/XML object');
+    }
+    return Change.fromApi(payload, {
+        typeForSlug: deps.typeForSlug,
+        decryptValue: deps.decryptValue,
+        binaryFetch: deps.binaryFetch,
+    });
+}
+/**
+ * Verify + parse a webhook in one call.
+ *
+ * Throws {@link WebhookError} on a bad/unknown signature; otherwise returns the
+ * typed {@link Change}. The typical one-liner inside a webhook route. `deps.accountKey`
+ * (optional) is a pre-loaded account private key reused for the `encrypt_payload`
+ * envelope (see {@link parseWebhook}).
+ */
+export function handleWebhook(rawBody, headers, config, deps) {
+    if (!verifyWebhook(rawBody, headers, config)) {
+        throw new WebhookError('webhook signature verification failed');
+    }
+    return parseWebhook(rawBody, headers, config, deps);
+}
+// ── payload decoding (JSON / XML / encrypt_payload envelope) ────────────────────
+function decodePayload(body, config, accountKey) {
+    const text = body.toString('utf8').trim();
+    // An encrypt_payload envelope is always JSON ({"_enc":1,...}). Detect + unwrap it
+    // before anything else (the inner payload is then JSON or XML per format).
+    if (text.startsWith('{')) {
+        let obj;
+        try {
+            obj = JSON.parse(text);
+        }
+        catch (exc) {
+            throw new WebhookError(`webhook body is not valid JSON: ${exc.message}`);
+        }
+        if (obj !== null &&
+            typeof obj === 'object' &&
+            !Array.isArray(obj) &&
+            obj[ENC_MARKER] === 1 &&
+            ['k', 'iv', 'd'].every((f) => f in obj)) {
+            const inner = unwrapAccountEnvelope(obj, config, accountKey);
+            return decodeInner(inner);
+        }
+        return obj;
+    }
+    // Otherwise an XML body (the platform's <response> serialization).
+    if (text.startsWith('<')) {
+        try {
+            return parseXml(text);
+        }
+        catch (exc) {
+            throw new WebhookError(`webhook body is not valid XML: ${exc.message}`);
+        }
+    }
+    throw new WebhookError('webhook body is neither JSON nor XML');
+}
+function decodeInner(innerText) {
+    const stripped = innerText.trim();
+    if (stripped.startsWith('<')) {
+        try {
+            return parseXml(stripped);
+        }
+        catch (exc) {
+            throw new WebhookError(`decrypted webhook payload is not valid XML: ${exc.message}`);
+        }
+    }
+    try {
+        return JSON.parse(stripped);
+    }
+    catch (exc) {
+        throw new WebhookError(`decrypted webhook payload is not valid JSON: ${exc.message}`);
+    }
+}
+// ── account-key envelope unwrap (OAEP-SHA1 — webhook-specific) ───────────────────
+/**
+ * Load the account private key from config ONCE (or `null` if not configured).
+ *
+ * Reused by the {@link Client} so an `encrypt_payload` webhook never re-reads the
+ * PEM + re-runs PBKDF2 (~100k iters) per request — the account key is loaded a
+ * single time at client construction, exactly like the service key. Returns `null`
+ * when no `accountPrivateKey` is configured (the SDK only needs it for
+ * `encrypt_payload` webhooks). Throws {@link WebhookError} on a read / passphrase /
+ * PEM problem.
+ */
+export function loadAccountKey(config) {
+    if (!config.accountPrivateKey)
+        return null;
+    let pem;
+    try {
+        pem = readFileSync(config.accountPrivateKey);
+    }
+    catch (exc) {
+        throw new WebhookError(`could not read accountPrivateKey PEM: ${config.accountPrivateKey}: ${exc.message}`);
+    }
+    const passphrase = config.accountPassphrase ?? '';
+    try {
+        return createPrivateKey({ key: pem, passphrase });
+    }
+    catch (exc) {
+        throw new WebhookError(`could not load account private key: ${exc.message}`);
+    }
+}
+function unwrapAccountEnvelope(envelope, config, accountKey) {
+    const key = accountKey ?? loadAccountKey(config);
+    if (key === null || key === undefined) {
+        throw new WebhookError('received an encrypt_payload webhook but no accountPrivateKey is configured');
+    }
+    return decryptOaepSha1(envelope, key);
+}
+function b64(value, name) {
+    if (typeof value !== 'string') {
+        throw new WebhookError(`envelope field '${name}' must be a base64 string`);
+    }
+    const buf = Buffer.from(value, 'base64');
+    const normalized = value.replace(/\s+/g, '');
+    if (buf.toString('base64').replace(/=+$/, '') !== normalized.replace(/=+$/, '')) {
+        throw new WebhookError(`envelope field '${name}' is not valid base64`);
+    }
+    return buf;
+}
+/**
+ * RSA-OAEP(**SHA-1**, MGF1-SHA1) unwrap + AES-256-GCM decrypt → utf-8 string.
+ *
+ * Mirrors {@link decrypt} but pins SHA-1 for the OAEP/MGF1 hash to match the
+ * account-key envelope (the only place the platform uses SHA-1 OAEP). Node defaults
+ * `oaepHash` to SHA-1 already; we set it explicitly for clarity + to be robust to a
+ * future default change.
+ */
+function decryptOaepSha1(wrapper, privateKey) {
+    const encKey = b64(wrapper.k, 'k');
+    const iv = b64(wrapper.iv, 'iv');
+    const ciphertextWithTag = b64(wrapper.d, 'd');
+    if (iv.length !== GCM_IV_LEN) {
+        throw new WebhookError(`envelope iv must be ${GCM_IV_LEN} bytes, got ${iv.length}`);
+    }
+    if (ciphertextWithTag.length < GCM_TAG_LEN) {
+        throw new WebhookError('envelope ciphertext too short to contain a GCM tag');
+    }
+    let aesKey;
+    try {
+        aesKey = privateDecrypt({
+            key: privateKey,
+            padding: cryptoConstants.RSA_PKCS1_OAEP_PADDING,
+            oaepHash: 'sha1',
+        }, encKey);
+    }
+    catch (exc) {
+        throw new WebhookError(`account-key envelope RSA-OAEP unwrap failed (wrong account key?): ${exc.message}`);
+    }
+    if (aesKey.length !== 32) {
+        throw new WebhookError(`unwrapped envelope AES key must be 32 bytes, got ${aesKey.length}`);
+    }
+    const tag = ciphertextWithTag.subarray(ciphertextWithTag.length - GCM_TAG_LEN);
+    const ciphertext = ciphertextWithTag.subarray(0, ciphertextWithTag.length - GCM_TAG_LEN);
+    let plaintext;
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', aesKey, iv);
+        decipher.setAuthTag(tag);
+        plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    }
+    catch {
+        throw new WebhookError('account-key envelope AES-GCM tag mismatch');
+    }
+    const out = plaintext.toString('utf8');
+    if (!Buffer.from(out, 'utf8').equals(plaintext)) {
+        throw new WebhookError('decrypted account-key envelope is not valid UTF-8');
+    }
+    return out;
+}

package/dist/esm/xml.js

@@ -0,0 +1,252 @@
+/**
+ * Minimal, XXE-safe XML parser for the platform's wire serialization.
+ *
+ * The company-data API can serve XML (`Accept: application/xml` / `format: "xml"`).
+ * The platform serializer renders:
+ *
+ *   - a `<response>` document root;
+ *   - a list (int keys) as repeated `<item>` children — so an element whose
+ *     every child is `<item>` becomes an array;
+ *   - an associative array as named child tags — an object;
+ *   - scalars as element text (booleans were written as `"true"`/`"false"`).
+ *
+ * **XXE-safe by construction.** This is a hand-written recursive-descent parser
+ * (NOT a general XML library). It supports ONLY elements, text, comments, the XML
+ * declaration, CDATA, and the five built-in entities. It does NOT process a DOCTYPE
+ * / DTD, does NOT define or expand custom/general entities, and never resolves
+ * external entities or system identifiers — the classic XXE / billion-laughs
+ * vectors cannot occur because the machinery for them is simply absent. A DOCTYPE,
+ * a processing instruction other than the XML decl, or an unknown `&entity;`
+ * reference is rejected — entity expansion and external entity resolution don't
+ * exist here at all. HMAC verification is always computed over the raw bytes,
+ * never the parsed tree.
+ *
+ * This is intentionally small — JSON is the default wire format; XML is the opt-in
+ * alternative — and it only needs to invert the company-data payloads (dicts of
+ * lists of dicts of scalars).
+ */
+export class XmlParseError extends Error {
+}
+// The ONLY entities recognized — the five XML built-ins. No custom/general/external
+// entity is ever defined or expanded (XXE-safe).
+const BUILTIN_ENTITIES = {
+    lt: '<',
+    gt: '>',
+    amp: '&',
+    quot: '"',
+    apos: "'",
+};
+function decodeEntities(s) {
+    return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (_m, body) => {
+        if (body[0] === '#') {
+            const isHex = body[1] === 'x' || body[1] === 'X';
+            const codeStr = isHex ? body.slice(2) : body.slice(1);
+            const code = parseInt(codeStr, isHex ? 16 : 10);
+            if (Number.isNaN(code) || code < 0 || code > 0x10ffff) {
+                throw new XmlParseError(`invalid numeric character reference &${body};`);
+            }
+            return String.fromCodePoint(code);
+        }
+        const replacement = BUILTIN_ENTITIES[body];
+        if (replacement === undefined) {
+            // A non-builtin entity reference — reject rather than expand. This is the
+            // XXE / entity-expansion guard: we never define or look up custom entities.
+            throw new XmlParseError(`unsupported XML entity &${body}; (custom/external entities are disabled)`);
+        }
+        return replacement;
+    });
+}
+class Parser {
+    constructor(text) {
+        this.i = 0;
+        this.s = text;
+    }
+    parse() {
+        this.skipProlog();
+        const root = this.parseElement();
+        this.skipMisc();
+        if (this.i < this.s.length) {
+            throw new XmlParseError('trailing content after the document root element');
+        }
+        return root;
+    }
+    skipWhitespace() {
+        while (this.i < this.s.length && /\s/.test(this.s[this.i]))
+            this.i++;
+    }
+    // Skip the XML declaration, comments, and whitespace BEFORE the root element.
+    // A DOCTYPE is explicitly rejected (no DTD processing — XXE-safe).
+    skipProlog() {
+        for (;;) {
+            this.skipWhitespace();
+            if (this.s.startsWith('<?xml', this.i)) {
+                this.skipUntil('?>');
+                continue;
+            }
+            if (this.s.startsWith('<!--', this.i)) {
+                this.skipUntil('-->');
+                continue;
+            }
+            if (this.s.startsWith('<!DOCTYPE', this.i) || this.s.startsWith('<!doctype', this.i)) {
+                throw new XmlParseError('DOCTYPE / DTD is not allowed (XXE-safe parser)');
+            }
+            if (this.s.startsWith('<?', this.i)) {
+                throw new XmlParseError('processing instructions are not allowed');
+            }
+            return;
+        }
+    }
+    // Skip comments + whitespace AFTER the root element (epilogue).
+    skipMisc() {
+        for (;;) {
+            this.skipWhitespace();
+            if (this.s.startsWith('<!--', this.i)) {
+                this.skipUntil('-->');
+                continue;
+            }
+            return;
+        }
+    }
+    skipUntil(marker) {
+        const idx = this.s.indexOf(marker, this.i);
+        if (idx === -1)
+            throw new XmlParseError(`unterminated '${marker}'`);
+        this.i = idx + marker.length;
+    }
+    parseName() {
+        const start = this.i;
+        // XML name chars (a permissive but safe subset): letters, digits, _, -, ., :
+        while (this.i < this.s.length && /[A-Za-z0-9_\-.:]/.test(this.s[this.i]))
+            this.i++;
+        if (this.i === start)
+            throw new XmlParseError(`expected an element name at offset ${this.i}`);
+        return this.s.slice(start, this.i);
+    }
+    // Skip attributes within a start tag (the platform serializer emits none, but be
+    // tolerant). Attribute VALUES are read but never define entities.
+    skipAttributes() {
+        for (;;) {
+            this.skipWhitespace();
+            const c = this.s[this.i];
+            if (c === '>' || c === '/' || c === undefined)
+                return;
+            // name
+            this.parseName();
+            this.skipWhitespace();
+            if (this.s[this.i] !== '=')
+                throw new XmlParseError('malformed attribute (expected =)');
+            this.i++; // '='
+            this.skipWhitespace();
+            const quote = this.s[this.i];
+            if (quote !== '"' && quote !== "'")
+                throw new XmlParseError('attribute value must be quoted');
+            this.i++;
+            const end = this.s.indexOf(quote, this.i);
+            if (end === -1)
+                throw new XmlParseError('unterminated attribute value');
+            this.i = end + 1;
+        }
+    }
+    parseElement() {
+        if (this.s[this.i] !== '<')
+            throw new XmlParseError(`expected '<' at offset ${this.i}`);
+        this.i++; // '<'
+        const tag = this.parseName();
+        this.skipAttributes();
+        if (this.s.startsWith('/>', this.i)) {
+            this.i += 2; // self-closing
+            return { tag, children: [], text: '' };
+        }
+        if (this.s[this.i] !== '>')
+            throw new XmlParseError(`malformed start tag <${tag}>`);
+        this.i++; // '>'
+        const node = { tag, children: [], text: '' };
+        const textParts = [];
+        for (;;) {
+            if (this.i >= this.s.length)
+                throw new XmlParseError(`unterminated element <${tag}>`);
+            if (this.s.startsWith('</', this.i)) {
+                this.i += 2;
+                const closeName = this.parseName();
+                this.skipWhitespace();
+                if (this.s[this.i] !== '>')
+                    throw new XmlParseError(`malformed end tag </${closeName}>`);
+                this.i++; // '>'
+                if (closeName !== tag) {
+                    throw new XmlParseError(`mismatched end tag: </${closeName}> closing <${tag}>`);
+                }
+                break;
+            }
+            if (this.s.startsWith('<!--', this.i)) {
+                this.skipUntil('-->');
+                continue;
+            }
+            if (this.s.startsWith('<![CDATA[', this.i)) {
+                const end = this.s.indexOf(']]>', this.i + 9);
+                if (end === -1)
+                    throw new XmlParseError('unterminated CDATA section');
+                textParts.push(this.s.slice(this.i + 9, end)); // raw — no entity decode in CDATA
+                this.i = end + 3;
+                continue;
+            }
+            if (this.s.startsWith('<!DOCTYPE', this.i) || this.s.startsWith('<!doctype', this.i)) {
+                throw new XmlParseError('DOCTYPE / DTD is not allowed (XXE-safe parser)');
+            }
+            if (this.s.startsWith('<?', this.i)) {
+                throw new XmlParseError('processing instructions are not allowed');
+            }
+            if (this.s[this.i] === '<') {
+                node.children.push(this.parseElement());
+                continue;
+            }
+            // Text run up to the next '<'.
+            const lt = this.s.indexOf('<', this.i);
+            const end = lt === -1 ? this.s.length : lt;
+            textParts.push(decodeEntities(this.s.slice(this.i, end)));
+            this.i = end;
+        }
+        node.text = textParts.join('');
+        return node;
+    }
+}
+function nodeToValue(node) {
+    if (node.children.length === 0) {
+        // A leaf node: its text. Callers coerce types from the known schema; we keep
+        // the raw string (booleans came over as "true"/"false").
+        return node.text;
+    }
+    // All children are <item> → an array (PHP int-keyed list).
+    if (node.children.every((c) => c.tag === 'item')) {
+        return node.children.map(nodeToValue);
+    }
+    // Otherwise an object: named tags → keys. Repeated tags collapse to a list.
+    const result = {};
+    for (const child of node.children) {
+        const value = nodeToValue(child);
+        if (child.tag in result) {
+            const existing = result[child.tag];
+            if (Array.isArray(existing)) {
+                existing.push(value);
+            }
+            else {
+                result[child.tag] = [existing, value];
+            }
+        }
+        else {
+            result[child.tag] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Parse the platform's XML serialization back into JS data (XXE-safe).
+ *
+ * Mirrors the platform serializer (see the module doc). Returns the document root
+ * element's value (a `<response>` element → an object). Throws {@link XmlParseError}
+ * on malformed XML, a DOCTYPE/DTD, a processing instruction, or any non-builtin
+ * entity reference.
+ */
+export function parseXml(text) {
+    const root = new Parser(text).parse();
+    return nodeToValue(root);
+}

package/dist/types/buffer.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Durable plain-file buffer for the crash-safe changes pump.
+ *
+ * The changes feed is a server-side **drain-on-fetch queue**: a fetch returns up to
+ * N events and deletes those rows in the same transaction — the API keeps no copy.
+ * So a drained batch MUST be persisted locally BEFORE any delivery, or a consumer
+ * crash mid-batch loses events the API already deleted. This module is that
+ * persistence: a zero-dependency, plain-file buffer under `cacheDir`.
+ *
+ * Layout:
+ *
+ *     <cacheDir>/pending/<seq>_<change_id>.json      # one un-acked event, oldest-first
+ *     <cacheDir>/deadletter/<seq>_<change_id>.json   # events that exhausted retries
+ *
+ *   - The stored event is the **raw hardened API event object** — its `value` /
+ *     `value_url` is **CIPHERTEXT**, never the decrypted plaintext. No PII is ever
+ *     written to disk ("ciphertext at rest").
+ *   - `<seq>` is a zero-padded, monotonically increasing sequence number persisted
+ *     in `<cacheDir>/.seq`. Because {@link FileBuffer.append} is called in drain
+ *     order (oldest-first), sorting filenames lexicographically yields oldest-first
+ *     — a stable order even if event `at` timestamps are missing or equal.
+ *   - Writes are **crash-safe**: each file is written to a temp name, fsync'd,
+ *     atomically renamed into place, and the containing directory is fsync'd — so a
+ *     crash never leaves a half-written pending file.
+ *   - `ack(id)` deletes the pending file; `deadLetter(id, error, attempts)` moves it
+ *     to `deadletter/` with the error + attempt count appended. Neither re-fetches
+ *     from the API (it already deleted the row) — the buffer is the only home.
+ *
+ * All operations are SYNCHRONOUS (Node `fs` + `fsyncSync`) so the fsync discipline
+ * is exact. The pump calls them between awaits.
+ */
+/** A buffered event (the raw hardened API object; ciphertext value intact). */
+export type BufferedEvent = Record<string, unknown>;
+/** A dead-letter record: the stored event + flattened error/attempts/id. */
+export interface DeadLetterRecord extends BufferedEvent {
+    error: string | null;
+    attempts: number | null;
+}
+/**
+ * A durable, ordered, ciphertext-at-rest event buffer under `cacheDir`.
+ *
+ * Re-instantiating a `FileBuffer` on the same `cacheDir` recovers whatever is on
+ * disk — that recovery is exactly the pump's replay-on-restart.
+ */
+export declare class FileBuffer {
+    private readonly pendingDir;
+    private readonly deadletterDir;
+    private readonly seqPath;
+    constructor(cacheDir: string);
+    private nextSeq;
+    private readSeq;
+    private writeSeq;
+    private maxOnDiskSeq;
+    /**
+     * Persist a drained batch (oldest-first), each in its own fsync'd file.
+     *
+     * Each event is stored verbatim (ciphertext value intact). Returns the list of
+     * pending filenames written. This is the backup the API no longer holds — it
+     * MUST complete before the pump delivers anything.
+     */
+    append(events: BufferedEvent[]): string[];
+    /** All un-acked events, oldest-first (by the sortable filename). */
+    pending(): BufferedEvent[];
+    private pendingFiles;
+    private readEvent;
+    private findPendingFile;
+    /** Delete the pending file for `changeId` (the per-item ack). Idempotent. */
+    ack(changeId: unknown): boolean;
+    /**
+     * Move a poison event from pending → deadletter with error + attempts.
+     *
+     * Crash safety: the new dead-letter copy is written BEFORE the pending copy is
+     * unlinked — never lose. A crash between the two leaves the event in BOTH dirs,
+     * which is harmless: replay re-delivers it (the id-dedup handler absorbs the
+     * duplicate). Do NOT "fix" this by deleting-first.
+     *
+     * The event keeps its ciphertext value; the failure context is appended under a
+     * reserved key so it is never silently dropped.
+     */
+    deadLetter(changeId: unknown, error: string, attempts: number): boolean;
+    private deadletterFiles;
+    /**
+     * All dead-lettered events, oldest-first.
+     *
+     * Each item is the stored (ciphertext) event with a flattened `error` and
+     * `attempts` lifted out of the reserved `_deadletter` block, plus the event's own
+     * `id` for convenience.
+     */
+    deadLetters(): DeadLetterRecord[];
+    private findDeadletterFile;
+    /**
+     * Rewrite a dead-letter record IN PLACE with a refreshed error + attempts.
+     *
+     * Used by a still-failing re-drive (`retryDeadLetters`): the record stays in
+     * `deadletter/` and its failure context is updated atomically (temp file inside
+     * `deadletter/` → fsync → rename over the same path). It is NEVER routed back
+     * through `pending/`, so a crash anywhere in this method leaves the record either
+     * as the old dead-letter or the new one — it can never resurrect as a live
+     * pending event. Idempotent (returns false if the record is gone).
+     * Preserves the file's seq prefix so its oldest-first ordering is unchanged.
+     *
+     * The stored attempt count is monotonic across separate re-drive runs — a later
+     * run with a smaller `maxRetries` must never lower the recorded total — so we
+     * clamp to `max(existing, new)`.
+     */
+    updateDeadLetter(changeId: unknown, error: string, attempts: number): boolean;
+    /** Delete a dead-letter record (after a successful re-drive). Idempotent. */
+    removeDeadLetter(changeId: unknown): boolean;
+}