@framers/agentos-ext-account-sources 0.6.1 → 0.7.1

package/dist/sync/SourceRevocations.js

@@ -0,0 +1,794 @@
+/**
+ * @fileoverview Fenced purge and revocation recovery for account sources. One short transaction blocks the owner,
+ * moves the connection, records a purge marker and moves the grant's refresh token into a sealed revoke-only queue;
+ * the purge completes in a recoverable transaction of its own; an account-independent worker revokes queued tokens
+ * before a fixed deadline. A durable grant lease serializes refreshes across workers, and the grant an authorization
+ * exchange returns is either installed or queued for revocation, never lost.
+ * @module account-sources/sync/SourceRevocations
+ */
+import { randomUUID } from 'node:crypto';
+import { SealedTokenStore, OAuthGrantRefused, sealSecret, openSecret, } from '@framers/agentos/auth';
+import { SourceSyncFault } from './state.js';
+/** The key a connection's grant is kept under in the host's sealed-value rows, inside its `sourceGrantNamespace`. */
+export const SOURCE_GRANT_KEY = 'grant';
+/**
+ * The sealed-store namespace of one connection's grant, naming its tenant, owner and connection: a sealed grant
+ * copied to another connection's row does not open. Initial installation, refresh and the transfer to the revoke-only
+ * queue all use it with `SOURCE_GRANT_KEY`.
+ */
+export function sourceGrantNamespace(scope) {
+    return JSON.stringify(['AccountSourceGrant', scope.tenantId, scope.ownerId, scope.connectionId]);
+}
+const fields = (s) => [s.tenantId, s.ownerId, s.connectionId];
+const ownerFields = (s) => [s.tenantId, s.ownerId];
+const integer = (value) => Number.isSafeInteger(value) && value >= 0;
+const key = (value) => typeof value === 'string' && value.length > 0 && value.length <= 512;
+/** How long after it begins an exchange may install its grant; its queued token is held until then. */
+const EXCHANGE_MS = 60_000;
+/** Rolls back an installation the host refused or finished too late. */
+class ExchangeRefused extends Error {
+    constructor() { super('source_exchange_refused'); }
+}
+/** How pressing a notice is, when a stopped grant and a returned grant both have one. */
+const urgency = {
+    not_needed: 0, confirmed: 1, pending: 2, permission_removal_required: 3,
+};
+/** The notice of a connection's newest exchange: none while it is in flight or once it ended or installed. */
+function exchangeNotice(row) {
+    if (!row || row.outcome === 'installed' || row.outcome === 'ended')
+        return 'not_needed';
+    if (row.outcome === 'unconfirmed')
+        return 'permission_removal_required';
+    if (!row.queue_id)
+        return 'not_needed';
+    if (row.state === 'pending')
+        return row.outcome === 'open' && row.lease_token === row.id ? 'not_needed' : 'pending';
+    return row.state === 'confirmed' ? 'confirmed' : 'permission_removal_required';
+}
+function tables(prefix = 'agentos_source_revoke') {
+    if (!/^[a-z][a-z0-9_]{0,27}$/.test(prefix))
+        throw new Error('invalid_source_revocation_prefix');
+    return { prefix, blocks: `"${prefix}_blocks"`, intents: `"${prefix}_intents"`,
+        queue: `"${prefix}_queue"`, grants: `"${prefix}_grant_leases"`, exchanges: `"${prefix}_exchanges"` };
+}
+/**
+ * PostgreSQL DDL for the migration-owned lifecycle tables: the owner's block marker, the per-connection stop
+ * intent, the revoke-only queue and its due index, the grant lease, and the authorization exchanges with their two
+ * indexes. The service never runs them: the host's migration does. No table references an account table, so
+ * removing an account cannot erase an outstanding revocation, and the rows hold opaque ids, times, fixed states,
+ * attempt counts and sealed refresh tokens only.
+ *
+ * @param prefix - Table-name prefix: a lower-case letter, then at most 27 lower-case letters, digits or underscores.
+ * @returns The eight statements, in the order they must run.
+ * @throws {Error} `invalid_source_revocation_prefix` when the prefix does not have that form.
+ */
+export function sourceRevocationSchema(prefix = 'agentos_source_revoke') {
+    const t = tables(prefix);
+    return [
+        `CREATE TABLE IF NOT EXISTS ${t.blocks} (tenant_id TEXT NOT NULL,owner_id TEXT NOT NULL,
+      pending BOOLEAN NOT NULL DEFAULT FALSE,deleted BOOLEAN NOT NULL DEFAULT FALSE,
+      PRIMARY KEY(tenant_id,owner_id))`,
+        `CREATE TABLE IF NOT EXISTS ${t.intents} (tenant_id TEXT NOT NULL,owner_id TEXT NOT NULL,
+      connection_id TEXT NOT NULL,generation BIGINT NOT NULL,token TEXT NOT NULL,
+      reason TEXT NOT NULL CHECK(reason IN ('disconnect','account_deleted','grant_rejected','insufficient_scope')),
+      purged BOOLEAN NOT NULL,queue_id TEXT,acknowledged BOOLEAN NOT NULL DEFAULT FALSE,
+      PRIMARY KEY(tenant_id,owner_id,connection_id))`,
+        `CREATE TABLE IF NOT EXISTS ${t.queue} (id TEXT PRIMARY KEY,sealed TEXT,
+      state TEXT NOT NULL CHECK(state IN ('pending','confirmed','expired','unreadable')),
+      expires_at BIGINT NOT NULL,next_at BIGINT NOT NULL,attempts INTEGER NOT NULL DEFAULT 0,
+      lease_token TEXT,lease_until BIGINT,
+      CHECK((lease_token IS NULL)=(lease_until IS NULL)),
+      CHECK((state='pending')=(sealed IS NOT NULL)))`,
+        `CREATE INDEX IF NOT EXISTS "${prefix}_due" ON ${t.queue}(next_at,id) WHERE state='pending'`,
+        `CREATE TABLE IF NOT EXISTS ${t.grants} (tenant_id TEXT NOT NULL,owner_id TEXT NOT NULL,
+      connection_id TEXT NOT NULL,token TEXT NOT NULL,until BIGINT NOT NULL,
+      PRIMARY KEY(tenant_id,owner_id,connection_id))`,
+        `CREATE TABLE IF NOT EXISTS ${t.exchanges} (id TEXT PRIMARY KEY,tenant_id TEXT NOT NULL,owner_id TEXT NOT NULL,
+      connection_id TEXT NOT NULL,generation BIGINT NOT NULL,started_at BIGINT NOT NULL,ends_at BIGINT NOT NULL,
+      outcome TEXT NOT NULL CHECK(outcome IN ('open','installed','cleanup','unconfirmed','ended')),
+      queue_id TEXT,acknowledged BOOLEAN NOT NULL DEFAULT FALSE)`,
+        `CREATE INDEX IF NOT EXISTS "${prefix}_exchange_owner" ON ${t.exchanges}(tenant_id,owner_id,connection_id)`,
+        `CREATE INDEX IF NOT EXISTS "${prefix}_exchange_due" ON ${t.exchanges}(ends_at,id)
+      WHERE outcome='open' AND queue_id IS NULL`,
+    ];
+}
+/**
+ * Adapter-owned lifecycle recovery. No method logs or returns a queued credential.
+ *
+ * `disconnect`, `loseGrant` and `deleteOwner` commit the owner's fence, the connection's stop, a purge marker and the
+ * transfer of the grant's refresh token to the revoke-only queue in one transaction, before any provider call; the
+ * purge of sources and every result derived from them completes in a transaction of its own, which `recover`
+ * resumes after a failure. `revokeBatch` revokes queued tokens on its own schedule, independent of accounts, until
+ * each token's deadline, 23 hours and 59 minutes after it was queued. `withGrant` serializes refreshes across
+ * workers under a durable lease. The exchange methods record an authorization exchange before its request is sent
+ * and either install the grant it returns or queue it for revocation. Every check of `canConnect`, `permits` and
+ * `mayInstallExchange` belongs inside the owner fence of the host's transaction.
+ *
+ * @typeParam Prepared - The store's prepared value for one document.
+ */
+export class SourceRevocations {
+    db;
+    options;
+    t;
+    store;
+    clock;
+    /**
+     * @param db - A PostgreSQL adapter with transactions, on the database of the store's tables.
+     * @param options - The store, keys, sealed-value binding and revoker, with an optional prefix, clock and sink.
+     * @throws {Error} `source_revocation_requires_postgres` for another kind of adapter or one without transactions,
+     *   and `invalid_source_revocation_prefix` for a malformed prefix.
+     */
+    constructor(db, options) {
+        this.db = db;
+        this.options = options;
+        if (db.kind !== 'postgres' || !db.capabilities.has('transactions'))
+            throw new Error('source_revocation_requires_postgres');
+        this.t = tables(options.tablePrefix);
+        this.store = options.store;
+        this.clock = options.clock ?? Date.now;
+    }
+    now() {
+        const now = this.clock();
+        if (!integer(now) || now > 8_639_999_913_600_000)
+            throw new SourceSyncFault('invalid_response');
+        return now;
+    }
+    emit(state, n = 1) {
+        try {
+            this.options.events?.({ kind: 'source_revocation', state, n });
+        }
+        catch { /* No diagnostic can alter purge. */ }
+    }
+    async stored(work) {
+        try {
+            return await work();
+        }
+        catch (error) {
+            if (error instanceof SourceSyncFault)
+                throw error;
+            throw new SourceSyncFault('storage_unavailable');
+        }
+    }
+    grant(tx, scope) {
+        return new SealedTokenStore(this.options.values(tx, scope), this.options.keys, { namespace: sourceGrantNamespace(scope) });
+    }
+    context(id) { return JSON.stringify(['SourceRevocations', this.t.prefix, id]); }
+    /**
+     * Combine with fresh host account liveness in the sync store's active binding. False while a stop's purge is
+     * pending for the owner and, for good, once the owner was deleted; it does not authenticate an account.
+     */
+    async permits(tx, scope) {
+        const row = await tx.get(`SELECT pending,deleted FROM ${this.t.blocks}
+      WHERE tenant_id=$1 AND owner_id=$2`, ownerFields(scope));
+        return !row || (!row.pending && !row.deleted);
+    }
+    /**
+     * Check under the owner fence both at authorization start and grant installation. False when `permits` is, while a
+     * revocation of the owner's is pending or ended without confirmation and is not acknowledged, and while an exchange
+     * of the owner's is in flight or its returned grant awaits the same conditions.
+     */
+    async canConnect(tx, scope) {
+        if (!await this.permits(tx, scope))
+            return false;
+        return !await this.barrier(tx, scope, null);
+    }
+    /**
+     * Whether a stop's revocation or an exchange keeps the owner from a new grant, leaving out the exchange `except`.
+     * A revocation pending in the queue, or one that expired or could not be opened before the owner acknowledged the
+     * permission's removal, keeps it; so does an exchange in flight, one whose returned grant is in the queue under the
+     * same conditions, and one whose outcome is unconfirmed and not acknowledged.
+     */
+    async barrier(tx, scope, except) {
+        if (await tx.get(`SELECT 1 FROM ${this.t.intents} i LEFT JOIN ${this.t.queue} q ON q.id=i.queue_id
+      WHERE i.tenant_id=$1 AND i.owner_id=$2 AND i.queue_id IS NOT NULL
+      AND (q.state='pending' OR (COALESCE(q.state,'expired') IN ('expired','unreadable') AND i.acknowledged=FALSE)) LIMIT 1`, ownerFields(scope)))
+            return true;
+        return !!await tx.get(`SELECT 1 FROM ${this.t.exchanges} e LEFT JOIN ${this.t.queue} q ON q.id=e.queue_id
+      WHERE e.tenant_id=$1 AND e.owner_id=$2 AND ($3::text IS NULL OR e.id<>$3) AND (
+        (e.outcome='open' AND e.queue_id IS NULL)
+        OR (e.outcome IN ('open','cleanup') AND e.queue_id IS NOT NULL AND (q.state='pending'
+          OR (COALESCE(q.state,'expired') IN ('expired','unreadable') AND e.acknowledged=FALSE)))
+        OR (e.outcome='unconfirmed' AND e.acknowledged=FALSE)) LIMIT 1`, [...ownerFields(scope), except]);
+    }
+    /**
+     * The connection's notice for authenticated controls: whether its purge is pending, and the more pressing of the
+     * revocation of its last stopped grant and the cleanup of the grant its newest exchange returned.
+     */
+    async status(scope) {
+        return this.stored(async () => {
+            const row = await this.db.get(`SELECT i.purged,i.queue_id,q.state FROM ${this.t.intents} i LEFT JOIN ${this.t.queue} q ON q.id=i.queue_id
+          WHERE i.tenant_id=$1 AND i.owner_id=$2 AND i.connection_id=$3`, fields(scope));
+            const stopped = !row?.queue_id ? 'not_needed'
+                : row.state === 'pending' ? 'pending' : row.state === 'confirmed' ? 'confirmed' : 'permission_removal_required';
+            const returned = exchangeNotice(await this.db.get(`SELECT e.id,e.outcome,e.queue_id,q.state,
+        q.lease_token FROM ${this.t.exchanges} e LEFT JOIN ${this.t.queue} q ON q.id=e.queue_id
+        WHERE e.tenant_id=$1 AND e.owner_id=$2 AND e.connection_id=$3 ORDER BY e.started_at DESC,e.id DESC LIMIT 1`, fields(scope)));
+            return { localPending: row?.purged === false,
+                revocation: urgency[returned] > urgency[stopped] ? returned : stopped };
+        });
+    }
+    async block(tx, scope, deleted) {
+        await tx.run(`INSERT INTO ${this.t.blocks}(tenant_id,owner_id,pending,deleted) VALUES($1,$2,TRUE,$3)
+      ON CONFLICT(tenant_id,owner_id) DO UPDATE SET pending=TRUE,deleted=${this.t.blocks}.deleted OR excluded.deleted`, [...ownerFields(scope), deleted]);
+    }
+    async stage(tx, state, reason) {
+        const scope = state.scope;
+        await this.block(tx, scope, reason === 'account_deleted');
+        const previous = await tx.get(`SELECT * FROM ${this.t.intents}
+      WHERE tenant_id=$1 AND owner_id=$2 AND connection_id=$3 FOR UPDATE`, fields(scope));
+        let queueId = previous?.queue_id ?? null;
+        let acknowledged = previous?.acknowledged ?? false;
+        const bytes = this.options.values(tx, scope);
+        const raw = await bytes.get(SOURCE_GRANT_KEY);
+        if (raw !== null) {
+            if (previous?.queue_id && !await this.canReplaceQueue(tx, previous))
+                throw new SourceSyncFault('grant_rejected');
+            const id = randomUUID();
+            const now = this.now();
+            let sealed = null;
+            // The bytes read succeeded. Decode failure cannot delay deletion of an unusable grant.
+            try {
+                const grant = await new SealedTokenStore({ get: async () => raw, set: async () => { }, delete: async () => { } }, this.options.keys, { namespace: sourceGrantNamespace(scope) }).load(SOURCE_GRANT_KEY);
+                const token = grant?.refreshToken;
+                if (typeof token === 'string' && token.length > 0 && token.length <= 16_384) {
+                    sealed = sealSecret(token, this.options.keys.current.key, this.options.keys.current.id, this.context(id));
+                }
+            }
+            catch {
+                sealed = null;
+            }
+            await tx.run(`INSERT INTO ${this.t.queue}(id,sealed,state,expires_at,next_at)
+        VALUES($1,$2,$3,$4,$5)`, [id, sealed, sealed === null ? 'unreadable' : 'pending', now + 86_340_000, now]);
+            queueId = id;
+            acknowledged = false;
+        }
+        // Never invoke a flow's forget on the reusable live key after this commit.
+        await this.grant(tx, scope).clear(SOURCE_GRANT_KEY);
+        await tx.run(`DELETE FROM ${this.t.grants} WHERE tenant_id=$1 AND owner_id=$2 AND connection_id=$3`, fields(scope));
+        await tx.run(`INSERT INTO ${this.t.intents}(tenant_id,owner_id,connection_id,generation,token,reason,purged,queue_id,acknowledged)
+      VALUES($1,$2,$3,$4,$5,$6,FALSE,$7,$8) ON CONFLICT(tenant_id,owner_id,connection_id) DO UPDATE SET
+      generation=excluded.generation,token=excluded.token,reason=excluded.reason,purged=FALSE,
+      queue_id=excluded.queue_id,acknowledged=excluded.acknowledged`, [...fields(scope), state.generation, randomUUID(), reason, queueId, acknowledged]);
+    }
+    async canReplaceQueue(tx, intent) {
+        const queue = await tx.get(`SELECT state FROM ${this.t.queue} WHERE id=$1`, [intent.queue_id]);
+        return queue?.state === 'confirmed' || (queue?.state !== 'pending' && intent.acknowledged);
+    }
+    /**
+     * Disconnects the connection at the generation the authenticated request saw: fences it, queues its grant for
+     * revocation and clears the active grant in one transaction, then purges its sources and every result derived
+     * from them. No provider call happens here.
+     *
+     * @returns The connection's notice, or null when the generation has moved on, which changes nothing.
+     * @throws {SourceSyncFault} `storage_unavailable` when a step fails: the committed stop stays, and `recover`
+     *   completes its purge.
+     */
+    async disconnect(scope, generation) {
+        return this.stored(async () => {
+            if (!await this.store.stageStop(scope, { type: 'disconnect' }, (tx, state) => this.stage(tx, state, 'disconnect'), generation))
+                return null;
+            this.emit('fenced');
+            await this.recoverOwner(scope);
+            return this.status(scope);
+        });
+    }
+    /**
+     * The coordinator's handoff of a refused grant: with the run's exact current handle, the connection moves to
+     * `needs_reconnecting` and its grant is queued for revocation in one transaction, then purged as `disconnect` does.
+     *
+     * @returns Whether the handle was current and the grant was fenced; a stale handle changes nothing.
+     */
+    async loseGrant(handle, reason) {
+        return this.stored(async () => {
+            const scope = handle.lease.scope;
+            if (!await this.store.stageStop(scope, { type: 'grant_lost', reason }, (tx, state) => this.stage(tx, state, reason), handle))
+                return false;
+            this.emit('fenced');
+            await this.recoverOwner(scope);
+            return true;
+        });
+    }
+    /**
+     * Account deletion: blocks the owner for good and stops every connection of the owner, queueing each grant for
+     * revocation, in one transaction, also when the owner has no connection; then purges them. Call it before the host
+     * removes any source, credential or account row. Queued revocations outlive the account.
+     */
+    async deleteOwner(scope) {
+        await this.stored(async () => {
+            await this.store.stageOwnerStop(scope, async (tx, states) => {
+                await this.block(tx, scope, true);
+                for (const state of states)
+                    await this.stage(tx, state, 'account_deleted');
+                if (!states.length)
+                    await tx.run(`UPDATE ${this.t.blocks} SET pending=FALSE
+          WHERE tenant_id=$1 AND owner_id=$2`, ownerFields(scope));
+            });
+            this.emit('fenced');
+            await this.recoverOwner(scope);
+        });
+    }
+    /** Recover every pending intent for the owner. No grant or account row is required. */
+    async recover(scope) { await this.recoverOwner(scope); }
+    async recoverOwner(scope) {
+        await this.stored(async () => {
+            const intents = await this.db.all(`SELECT * FROM ${this.t.intents}
+        WHERE tenant_id=$1 AND owner_id=$2 AND purged=FALSE ORDER BY connection_id`, ownerFields(scope));
+            for (const intent of intents) {
+                const source = { tenantId: intent.tenant_id, ownerId: intent.owner_id, connectionId: intent.connection_id };
+                await this.store.recoverControl(source);
+                const completed = await this.store.completeStop(source, Number(intent.generation), async (tx) => {
+                    const changed = await tx.run(`UPDATE ${this.t.intents} SET purged=TRUE
+            WHERE tenant_id=$1 AND owner_id=$2 AND connection_id=$3 AND token=$4 AND purged=FALSE`, [...fields(source), intent.token]);
+                    if (changed.changes !== 1)
+                        return;
+                    await tx.run(`UPDATE ${this.t.blocks} SET pending=EXISTS(SELECT 1 FROM ${this.t.intents}
+            WHERE tenant_id=$1 AND owner_id=$2 AND purged=FALSE) WHERE tenant_id=$1 AND owner_id=$2`, ownerFields(source));
+                });
+                if (!completed)
+                    throw new SourceSyncFault('storage_unavailable');
+                this.emit('purged');
+                await this.store.recoverControl(source);
+            }
+        });
+    }
+    /**
+     * Owner-authenticated attestation; never describe it as provider confirmation. The account owner confirms having
+     * removed the permission at the provider for the connection's revocation that expired or could not be opened, and
+     * for its exchanges whose outcome is unconfirmed or whose returned grant's revocation ended the same way; a new
+     * grant may then begin. A pending or confirmed revocation is not acknowledged.
+     *
+     * @returns Whether anything was acknowledged.
+     */
+    async acknowledgeRemoval(scope) {
+        return this.stored(async () => {
+            let acknowledged = false;
+            await this.store.fence.blockOwner(scope, async (tx) => {
+                const intent = await tx.get(`SELECT * FROM ${this.t.intents}
+          WHERE tenant_id=$1 AND owner_id=$2 AND connection_id=$3 FOR UPDATE`, fields(scope));
+                if (intent?.purged && intent.queue_id) {
+                    const row = await tx.get(`SELECT * FROM ${this.t.queue} WHERE id=$1`, [intent.queue_id]);
+                    if (row?.state !== 'pending' && row?.state !== 'confirmed') {
+                        await tx.run(`UPDATE ${this.t.intents} SET acknowledged=TRUE
+              WHERE tenant_id=$1 AND owner_id=$2 AND connection_id=$3`, fields(scope));
+                        acknowledged = true;
+                    }
+                }
+                await this.lockOwner(tx, scope);
+                const exchanges = await tx.run(`UPDATE ${this.t.exchanges} e SET acknowledged=TRUE
+          WHERE e.tenant_id=$1 AND e.owner_id=$2 AND e.connection_id=$3 AND e.acknowledged=FALSE
+          AND (e.outcome='unconfirmed' OR (e.outcome IN ('open','cleanup') AND e.queue_id IS NOT NULL
+            AND NOT EXISTS(SELECT 1 FROM ${this.t.queue} q WHERE q.id=e.queue_id AND q.state IN ('pending','confirmed'))))`, fields(scope));
+                if ((exchanges.changes ?? 0) > 0)
+                    acknowledged = true;
+            });
+            await this.store.recoverControl(scope);
+            return acknowledged;
+        });
+    }
+    /**
+     * Runs one server-side grant operation, such as a refresh, under a durable 30-second grant lease, without holding a
+     * transaction over the network. `work` builds the provider flow on the sealed store it is given and must honor the
+     * signal, which aborts after 15 seconds or with `parent`. Every load and save through that store, and the final
+     * return, recheck the sync handle and the grant lease in a short transaction, so a disconnect or an expired lease
+     * makes a held token's save or return fail. The lease is never renewed; after it expires another worker may take
+     * a new one. Access tokens stay in memory.
+     *
+     * @returns What `work` answered.
+     * @throws {SourceSyncFault} `rate_limited` while another worker holds the lease, with its expiry as `retryAt`;
+     *   `grant_rejected` for a stale handle, a lost lease or a disconnect; `cancelled` when `parent` aborted first;
+     *   `storage_unavailable` for any other failure. A provider refusal (`OAuthGrantRefused`) passes through.
+     */
+    async withGrant(handle, work, parent) {
+        if (parent?.aborted)
+            throw new SourceSyncFault('cancelled');
+        const scope = handle.lease.scope;
+        const token = randomUUID();
+        const acquired = await this.stored(() => this.store.withCurrentHandle(handle, async (tx) => {
+            const row = await tx.get(`SELECT token,until FROM ${this.t.grants}
+        WHERE tenant_id=$1 AND owner_id=$2 AND connection_id=$3 FOR UPDATE`, fields(scope));
+            const now = this.now();
+            if (row && Number(row.until) > now)
+                throw new SourceSyncFault('rate_limited', Number(row.until));
+            await tx.run(`INSERT INTO ${this.t.grants}(tenant_id,owner_id,connection_id,token,until)
+        VALUES($1,$2,$3,$4,$5) ON CONFLICT(tenant_id,owner_id,connection_id)
+        DO UPDATE SET token=excluded.token,until=excluded.until`, [...fields(scope), token, now + 30_000]);
+            return true;
+        }));
+        if (acquired !== true)
+            throw new SourceSyncFault('grant_rejected');
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        parent?.addEventListener('abort', abort, { once: true });
+        if (parent?.aborted)
+            abort();
+        const timer = setTimeout(abort, 15_000);
+        const guarded = async (action) => {
+            if (controller.signal.aborted)
+                throw new SourceSyncFault(parent?.aborted ? 'cancelled' : 'network');
+            const result = await this.stored(() => this.store.withCurrentHandle(handle, async (tx) => {
+                const lease = await tx.get(`SELECT token,until FROM ${this.t.grants}
+          WHERE tenant_id=$1 AND owner_id=$2 AND connection_id=$3 FOR UPDATE`, fields(scope));
+                if (!lease || lease.token !== token || Number(lease.until) <= this.now())
+                    throw new SourceSyncFault('grant_rejected');
+                const value = await action(this.options.values(tx, scope));
+                if (controller.signal.aborted || Number(lease.until) <= this.now())
+                    throw new SourceSyncFault('grant_rejected');
+                return { value };
+            }));
+            if (!result)
+                throw new SourceSyncFault('grant_rejected');
+            return result.value;
+        };
+        const values = {
+            get: (key) => guarded((store) => store.get(key)),
+            set: (key, sealed) => guarded((store) => store.set(key, sealed)),
+            delete: (key) => guarded((store) => store.delete(key)),
+        };
+        try {
+            const result = await work(new SealedTokenStore(values, this.options.keys, { namespace: sourceGrantNamespace(scope) }), controller.signal);
+            await guarded(async () => true);
+            return result;
+        }
+        catch (error) {
+            if (error instanceof SourceSyncFault || error instanceof OAuthGrantRefused)
+                throw error;
+            throw new SourceSyncFault('storage_unavailable');
+        }
+        finally {
+            clearTimeout(timer);
+            parent?.removeEventListener('abort', abort);
+            await this.stored(async () => {
+                await this.db.run(`DELETE FROM ${this.t.grants}
+        WHERE tenant_id=$1 AND owner_id=$2 AND connection_id=$3 AND token=$4`, [...fields(scope), token]);
+            });
+        }
+    }
+    async expireQueue() {
+        const now = this.now();
+        const changed = await this.db.run(`UPDATE ${this.t.queue} SET sealed=NULL,state='expired',lease_token=NULL,lease_until=NULL
+      WHERE id IN (SELECT id FROM ${this.t.queue} WHERE state='pending' AND expires_at<=$1 ORDER BY expires_at,id LIMIT 1000)
+      AND state='pending' AND expires_at<=$1`, [now]);
+        return changed.changes ?? 0;
+    }
+    async claimRevoke() {
+        return this.db.transaction(async (tx) => {
+            const now = this.now();
+            const row = await tx.get(`SELECT * FROM ${this.t.queue} WHERE state='pending'
+        AND next_at<=$1 AND expires_at>$1 AND (lease_until IS NULL OR lease_until<=$1)
+        ORDER BY next_at,id LIMIT 1 FOR UPDATE SKIP LOCKED`, [now]);
+            if (!row)
+                return null;
+            const token = randomUUID();
+            const until = Math.min(now + 30_000, Number(row.expires_at));
+            await tx.run(`UPDATE ${this.t.queue} SET lease_token=$2,lease_until=$3,attempts=attempts+1 WHERE id=$1`, [row.id, token, until]);
+            return { ...row, lease_token: token, lease_until: until, attempts: row.attempts + 1 };
+        });
+    }
+    async settleRevoke(row, state) {
+        const now = this.now();
+        const delay = Math.min(900_000, 60_000 * 2 ** Math.min(4, row.attempts - 1));
+        const next = Math.min(Number(row.expires_at), now + delay);
+        const changed = state === 'pending'
+            ? await this.db.run(`UPDATE ${this.t.queue} SET next_at=$3,lease_token=NULL,lease_until=NULL
+          WHERE id=$1 AND lease_token=$2 AND state='pending' AND lease_until>$4 AND expires_at>$4`, [row.id, row.lease_token, next, now])
+            : await this.db.run(`UPDATE ${this.t.queue} SET sealed=NULL,state=$3,lease_token=NULL,lease_until=NULL
+          WHERE id=$1 AND lease_token=$2 AND state='pending' AND lease_until>$4 AND expires_at>$4`, [row.id, row.lease_token, state, now]);
+        return changed.changes === 1;
+    }
+    /**
+     * Schedule independently of accounts, source scopes and provider polling, at least every minute. Erases queued
+     * tokens whose deadline has passed and records exchanges whose deadline passed with no outcome as unconfirmed, then
+     * claims up to `limit` due tokens, one worker per token, and revokes each outside any transaction with the
+     * provider flow's `revoke`, 15 seconds at most. A success confirms it; a failure retries after 1, 2, 4, 8, then 15
+     * minutes, never past the deadline; a token that does not open is erased. A worker whose claim expired cannot
+     * settle a token another worker claimed since.
+     *
+     * @param limit - At most this many tokens, an integer from 1 to 100; 20 unless given.
+     * @param parent - Stops the batch: no request starts after it aborts.
+     * @throws {SourceSyncFault} `invalid_response` for another limit and `storage_unavailable` when the store fails.
+     */
+    async revokeBatch(limit = 20, parent) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+            throw new SourceSyncFault('invalid_response');
+        const out = { attempted: 0, confirmed: 0, deferred: 0, expired: 0, unreadable: 0 };
+        if (parent?.aborted)
+            return out;
+        return this.stored(async () => {
+            out.expired = await this.expireQueue() + await this.lapseExchanges();
+            if (out.expired)
+                this.emit('expired', out.expired);
+            for (let n = 0; n < limit && !parent?.aborted; n++) {
+                const row = await this.claimRevoke();
+                if (!row)
+                    break;
+                let bytes = null;
+                let token = '';
+                try {
+                    if (!row.sealed || Number(row.expires_at) <= this.now())
+                        throw new Error('expired_revocation');
+                    bytes = openSecret(row.sealed, [this.options.keys.current, ...(this.options.keys.previous ?? [])], this.context(row.id));
+                    token = Buffer.from(bytes).toString('utf8');
+                    if (!token.length || token.length > 16_384)
+                        throw new Error('invalid_revocation_material');
+                }
+                catch {
+                    if (await this.settleRevoke(row, 'unreadable')) {
+                        out.unreadable++;
+                        this.emit('unreadable');
+                    }
+                    bytes?.fill(0);
+                    token = '';
+                    continue;
+                }
+                const controller = new AbortController();
+                const abort = () => controller.abort();
+                parent?.addEventListener('abort', abort, { once: true });
+                if (parent?.aborted)
+                    abort();
+                const remaining = Math.min(15_000, Number(row.expires_at) - this.now(), Number(row.lease_until) - this.now());
+                const timer = setTimeout(abort, Math.max(1, remaining));
+                let completed = false;
+                try {
+                    if (remaining > 0 && !controller.signal.aborted) {
+                        out.attempted++;
+                        await this.options.revoker(controller.signal).revoke(token);
+                        completed = !controller.signal.aborted && Number(row.expires_at) > this.now();
+                    }
+                }
+                catch {
+                    completed = false;
+                }
+                finally {
+                    clearTimeout(timer);
+                    parent?.removeEventListener('abort', abort);
+                    bytes?.fill(0);
+                    token = '';
+                }
+                if (await this.settleRevoke(row, completed ? 'confirmed' : 'pending')) {
+                    if (completed) {
+                        out.confirmed++;
+                        this.emit('confirmed');
+                    }
+                    else {
+                        out.deferred++;
+                        this.emit('deferred');
+                    }
+                }
+            }
+            const expired = await this.expireQueue();
+            out.expired += expired;
+            if (expired)
+                this.emit('expired', expired);
+            return out;
+        });
+    }
+    /**
+     * Remove unreferenced terminal diagnostics, never usable credentials or restore markers: a day after their end,
+     * exchanges that installed, ended or were acknowledged, or whose returned grant's revocation was confirmed; then, a
+     * day after their deadline, terminal queue rows no stop or exchange refers to; at most 1,000 of each a call. A
+     * deleted owner's exchanges outlive the account only to settle their attempt, and the owner can never acknowledge:
+     * once the deletion is recorded, an exchange of the owner's that is not in flight and holds no pending revocation
+     * also goes a day after its end, including one recorded unconfirmed or whose returned grant's revocation expired or
+     * could not be opened. The owner's block marker stays.
+     *
+     * @returns How many rows were removed.
+     */
+    async compact() {
+        return this.stored(async () => {
+            const cutoff = this.now() - 86_400_000;
+            // A deleted owner's exchange goes once it is not in flight and holds no pending revocation.
+            const exchanges = await this.db.run(`DELETE FROM ${this.t.exchanges} WHERE id IN (
+        SELECT e.id FROM ${this.t.exchanges} e LEFT JOIN ${this.t.queue} q ON q.id=e.queue_id
+        WHERE e.ends_at<$1 AND (e.outcome IN ('installed','ended') OR e.acknowledged OR q.state='confirmed'
+          OR ((e.outcome<>'open' OR e.queue_id IS NOT NULL) AND q.state IS DISTINCT FROM 'pending'
+            AND EXISTS(SELECT 1 FROM ${this.t.blocks} b
+              WHERE b.tenant_id=e.tenant_id AND b.owner_id=e.owner_id AND b.deleted)))
+        ORDER BY e.ends_at,e.id LIMIT 1000)`, [cutoff]);
+            const changed = await this.db.run(`DELETE FROM ${this.t.queue} WHERE id IN (
+        SELECT q.id FROM ${this.t.queue} q WHERE q.state<>'pending' AND q.expires_at<$1
+        AND NOT EXISTS(SELECT 1 FROM ${this.t.intents} i WHERE i.queue_id=q.id)
+        AND NOT EXISTS(SELECT 1 FROM ${this.t.exchanges} e WHERE e.queue_id=q.id)
+        ORDER BY q.expires_at,q.id LIMIT 1000) AND state<>'pending'`, [cutoff]);
+            return (exchanges.changes ?? 0) + (changed.changes ?? 0);
+        });
+    }
+    /** Records exchanges whose deadline passed with no grant returned as unconfirmed: their outcome is unknown. */
+    async lapseExchanges() {
+        const now = this.now();
+        const changed = await this.db.run(`UPDATE ${this.t.exchanges} SET outcome='unconfirmed' WHERE id IN (
+      SELECT id FROM ${this.t.exchanges} WHERE outcome='open' AND queue_id IS NULL AND ends_at<=$1
+      ORDER BY ends_at,id LIMIT 1000) AND outcome='open' AND queue_id IS NULL AND ends_at<=$1`, [now]);
+        return changed.changes ?? 0;
+    }
+    /** Takes the owner's lifecycle row lock, creating the row unblocked when missing; exchange changes take it first. */
+    async lockOwner(tx, scope) {
+        await tx.run(`INSERT INTO ${this.t.blocks}(tenant_id,owner_id) VALUES($1,$2)
+      ON CONFLICT(tenant_id,owner_id) DO NOTHING`, ownerFields(scope));
+        await tx.get(`SELECT pending FROM ${this.t.blocks} WHERE tenant_id=$1 AND owner_id=$2 FOR UPDATE`, ownerFields(scope));
+    }
+    checkExchange(exchange) {
+        const scope = exchange?.scope;
+        if (!scope || !key(exchange.id) || !key(scope.tenantId) || !key(scope.ownerId) || !key(scope.connectionId)
+            || !integer(exchange.generation) || !integer(exchange.startedAt) || !integer(exchange.endsAt)) {
+            throw new SourceSyncFault('invalid_response');
+        }
+    }
+    /** The exchange's row under its lock, or null when no row matches every field of the exchange. */
+    async exchangeRow(tx, exchange) {
+        const row = await tx.get(`SELECT * FROM ${this.t.exchanges} WHERE id=$1 FOR UPDATE`, [exchange.id]);
+        return row && row.tenant_id === exchange.scope.tenantId && row.owner_id === exchange.scope.ownerId
+            && row.connection_id === exchange.scope.connectionId && Number(row.generation) === exchange.generation
+            && Number(row.started_at) === exchange.startedAt && Number(row.ends_at) === exchange.endsAt ? row : null;
+    }
+    /** What a settled exchange did with its grant, from its row and its queued token's state. */
+    async exchangeOutcome(tx, row) {
+        if (row.outcome === 'installed')
+            return { kind: 'installed' };
+        if (!row.queue_id)
+            return { kind: 'permission_removal_required' };
+        const queue = await tx.get(`SELECT state FROM ${this.t.queue} WHERE id=$1`, [row.queue_id]);
+        return queue?.state === 'pending' || queue?.state === 'confirmed' ? { kind: 'cleanup_pending' }
+            : { kind: 'permission_removal_required' };
+    }
+    /**
+     * Records an authorization exchange before its request is sent. Call it inside the host transaction that consumes
+     * the authenticated start, under the owner fence: it answers null, and the caller rolls that whole transaction
+     * back, unless the connection is `connecting` at `generation` and `canConnect` holds, so one exchange at a time is
+     * in flight for the owner and none while a revocation of the owner's is pending or unacknowledged. The exchange's
+     * marker holds opaque ids and times only, and the exchange ends 60 seconds after it begins: a grant returned later
+     * is not installed. Send the request only after the transaction commits.
+     *
+     * @param exchangeId - The host's opaque id for this attempt, 1 to 512 characters, never reused.
+     * @returns The exchange, or null.
+     * @throws {SourceSyncFault} `invalid_response` for a malformed scope, generation or id.
+     */
+    async beginExchange(tx, scope, generation, exchangeId) {
+        if (!key(exchangeId) || !integer(generation) || !key(scope?.tenantId) || !key(scope?.ownerId)
+            || !key(scope?.connectionId))
+            throw new SourceSyncFault('invalid_response');
+        return this.stored(async () => {
+            const state = await this.store.lockState(tx, scope);
+            if (!state || state.status !== 'connecting' || state.generation !== generation)
+                return null;
+            await this.lockOwner(tx, scope);
+            if (!await this.canConnect(tx, scope))
+                return null;
+            const startedAt = this.now();
+            const endsAt = startedAt + EXCHANGE_MS;
+            const inserted = await tx.run(`INSERT INTO ${this.t.exchanges}(id,tenant_id,owner_id,connection_id,generation,
+        started_at,ends_at,outcome) VALUES($1,$2,$3,$4,$5,$6,$7,'open') ON CONFLICT(id) DO NOTHING`, [exchangeId, ...fields(scope), generation, startedAt, endsAt]);
+            if (inserted.changes !== 1)
+                return null;
+            const exchange = { id: exchangeId, generation, startedAt, endsAt,
+                scope: { tenantId: scope.tenantId, ownerId: scope.ownerId, connectionId: scope.connectionId } };
+            return exchange;
+        });
+    }
+    /**
+     * Whether this exact exchange may install its grant now, read under the owner fence in the installing transaction:
+     * its marker is open and holds its sealed grant for installation, its deadline has not passed, the connection is
+     * still `connecting` at its generation with no grant installed, `permits` holds, and no other revocation or
+     * exchange keeps the owner from a new grant. It recognizes only the matching live attempt, never an older or newer
+     * one.
+     */
+    async mayInstallExchange(tx, exchange) {
+        this.checkExchange(exchange);
+        return this.stored(async () => {
+            const scope = exchange.scope;
+            const state = await this.store.lockState(tx, scope);
+            await this.lockOwner(tx, scope);
+            const row = await this.exchangeRow(tx, exchange);
+            if (!row || row.outcome !== 'open' || !row.queue_id || this.now() >= exchange.endsAt
+                || !state || state.status !== 'connecting' || state.generation !== exchange.generation)
+                return false;
+            const held = await tx.get(`SELECT * FROM ${this.t.queue} WHERE id=$1 FOR UPDATE`, [row.queue_id]);
+            if (!held || held.state !== 'pending' || held.lease_token !== exchange.id)
+                return false;
+            if (!await this.permits(tx, scope) || await this.barrier(tx, scope, exchange.id))
+                return false;
+            return await this.options.values(tx, scope).get(SOURCE_GRANT_KEY) === null;
+        });
+    }
+    /**
+     * Settles the grant an exchange returned. First the grant's refresh token is sealed into the revoke-only queue,
+     * held there until the exchange's end, so a crash cannot lose it. Then, when `mayInstallExchange` holds, `install`
+     * runs in the owner's transaction: it saves the grant under `sourceGrantNamespace` and `SOURCE_GRANT_KEY`, records
+     * the connection's ready state and finishes the host's start, and the same commit removes the held token. If the
+     * exchange may not install, `install` answers anything but true, throws or finishes after the deadline, the whole
+     * installation rolls back and the held token becomes due for revocation at once; if this process stops first, it
+     * becomes due at the exchange's end. A stale, cancelled or deleted exchange never runs `install`. An exchange that
+     * already ended or was recorded unconfirmed takes no token: its notice stands. A grant with no usable refresh token
+     * records the exchange unconfirmed.
+     *
+     * @returns What became of the grant.
+     * @throws {SourceSyncFault} `invalid_response` for a malformed exchange, `storage_unavailable` when the store fails.
+     */
+    async settleExchange(exchange, grant, install) {
+        this.checkExchange(exchange);
+        if (typeof install !== 'function')
+            throw new SourceSyncFault('invalid_response');
+        const refresh = grant?.refreshToken;
+        const token = typeof refresh === 'string' && refresh.length > 0 && refresh.length <= 16_384 ? refresh : null;
+        const removal = { kind: 'permission_removal_required' };
+        const settled = await this.stored(() => this.db.transaction(async (tx) => {
+            await this.lockOwner(tx, exchange.scope);
+            const row = await this.exchangeRow(tx, exchange);
+            if (!row)
+                return removal;
+            if (row.outcome !== 'open')
+                return this.exchangeOutcome(tx, row);
+            if (row.queue_id)
+                return null;
+            if (token === null) {
+                await tx.run(`UPDATE ${this.t.exchanges} SET outcome='unconfirmed' WHERE id=$1`, [row.id]);
+                return removal;
+            }
+            const now = this.now();
+            const id = randomUUID();
+            const until = Number(row.ends_at);
+            const hold = until > now;
+            const sealed = sealSecret(token, this.options.keys.current.key, this.options.keys.current.id, this.context(id));
+            await tx.run(`INSERT INTO ${this.t.queue}(id,sealed,state,expires_at,next_at,lease_token,lease_until)
+        VALUES($1,$2,'pending',$3,$4,$5,$6)`, [id, sealed, now + 86_340_000, hold ? until : now,
+                hold ? row.id : null, hold ? until : null]);
+            await tx.run(`UPDATE ${this.t.exchanges} SET queue_id=$2,outcome=$3 WHERE id=$1`, [row.id, id, hold ? 'open' : 'cleanup']);
+            return hold ? null : { kind: 'cleanup_pending' };
+        }));
+        if (settled)
+            return settled;
+        try {
+            const installed = await this.db.transaction(async (tx) => {
+                if (!await this.mayInstallExchange(tx, exchange))
+                    return false;
+                if (await install(tx, grant) !== true || this.now() >= exchange.endsAt)
+                    throw new ExchangeRefused();
+                const row = await this.exchangeRow(tx, exchange);
+                if (!row?.queue_id)
+                    throw new ExchangeRefused();
+                await tx.run(`DELETE FROM ${this.t.queue} WHERE id=$1 AND lease_token=$2`, [row.queue_id, row.id]);
+                await tx.run(`UPDATE ${this.t.exchanges} SET outcome='installed',queue_id=NULL WHERE id=$1`, [row.id]);
+                return true;
+            });
+            if (installed)
+                return { kind: 'installed' };
+        }
+        catch { /* A refused or failed installation rolled back whole; its held grant goes to revocation below. */ }
+        return this.stored(() => this.db.transaction(async (tx) => {
+            await this.lockOwner(tx, exchange.scope);
+            const row = await this.exchangeRow(tx, exchange);
+            if (!row)
+                return removal;
+            if (row.outcome === 'open' && row.queue_id) {
+                await tx.run(`UPDATE ${this.t.queue} SET next_at=$3,lease_token=NULL,lease_until=NULL
+          WHERE id=$1 AND state='pending' AND lease_token=$2`, [row.queue_id, row.id, this.now()]);
+                await tx.run(`UPDATE ${this.t.exchanges} SET outcome='cleanup' WHERE id=$1`, [row.id]);
+                row.outcome = 'cleanup';
+            }
+            return this.exchangeOutcome(tx, row);
+        }));
+    }
+    /**
+     * Records how an exchange ended when it returned no grant to settle: `not_dispatched` when its request never left
+     * the process, `revoked` when the provider flow revoked a grant it refused and the provider confirmed it, and
+     * `unconfirmed` for anything else after the request could have left, such as a timeout, an aborted connection, an
+     * unreadable answer or a revocation that was not confirmed. Only an open exchange holding no returned grant takes
+     * an ending, and a recorded outcome is never weakened. An unconfirmed exchange keeps new grants blocked until the
+     * account owner acknowledges the permission's removal.
+     *
+     * @throws {SourceSyncFault} `invalid_response` for a malformed exchange or another outcome.
+     */
+    async endExchange(exchange, outcome) {
+        this.checkExchange(exchange);
+        if (outcome !== 'not_dispatched' && outcome !== 'revoked' && outcome !== 'unconfirmed') {
+            throw new SourceSyncFault('invalid_response');
+        }
+        await this.stored(() => this.db.transaction(async (tx) => {
+            await this.lockOwner(tx, exchange.scope);
+            const row = await this.exchangeRow(tx, exchange);
+            if (!row || row.outcome !== 'open' || row.queue_id !== null)
+                return;
+            await tx.run(`UPDATE ${this.t.exchanges} SET outcome=$2 WHERE id=$1`, [row.id, outcome === 'unconfirmed' ? 'unconfirmed' : 'ended']);
+        }));
+    }
+}
+//# sourceMappingURL=SourceRevocations.js.map