@aglyn/plugins-marketplace 1.14.0 → 1.15.1

package/src/lib/server/connections/connection-store.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * A SITE'S DECLARED CONNECTION, AND ITS SEALED GRANT (AGL-4193).
+ *
+ * `hosts/{hostId}/pluginConnections/{listingId}__{connectionId}` — one per
+ * site, listing and declared connection. Copied in shape from accounting's
+ * ledger connection (`libs/plugins/accounting/.../connection-store.ts`), not
+ * imported: one plugin never imports another.
+ *
+ * The refresh and access tokens are sealed with `PLUGIN_CONNECTIONS_TOKEN_KEY`
+ * (secret box, AES-256-GCM), each bound to this document and its purpose as
+ * the seal's context, so a value copied onto another site's document refuses
+ * to open there. The rules refuse every client the whole collection; the
+ * console reads {@link toConnectionView}, which carries no token, through the
+ * status route.
+ *
+ * ## Rotation, and only one refresher
+ *
+ * Many providers hand back a new refresh token on a refresh and retire the
+ * old one soon after. Two processes refreshing the same grant at once — the
+ * picker and the scheduled sync — would each spend the old token, and one
+ * would store a token the provider has already replaced. So a refresh first
+ * takes a short LEASE on the document in a transaction; a second refresher
+ * that finds the lease held waits for the first's result instead. A provider
+ * that refuses the grant (`invalid_grant`, a 401) moves the connection to
+ * `reconnect_required`, which only the site owner connecting again clears.
+ */
+import { type SecretBoxKeyring } from '@aglyn/shared-util-tools/secret-box';
+import type { PluginConnectionDeclaration } from '@aglyn/aglyn/app-utils/plugin-connections';
+import { type PluginConnectionChoice, type PluginConnectionStatus, type PluginConnectionView } from '../../model/plugin-connections';
+import { type PluginConnectionClient, type PluginConnectionTokenSet } from './provider-http';
+/** The stored document. Server-only. */
+export interface PluginConnectionRecord {
+    /** Tells a connection from a pending connect's state record in the same collection. */
+    kind: 'connection';
+    hostId: string;
+    /** The workspace that owns the site, when it connected. */
+    orgId: string;
+    listingId: string;
+    connectionId: string;
+    provider: string;
+    status: PluginConnectionStatus;
+    /** `''` when the provider issued no refresh token. */
+    sealedRefreshToken: string;
+    sealedAccessToken: string;
+    accessExpiresAtMs: number;
+    refreshedAtMs: number;
+    refreshLeaseUntilMs: number;
+    scopes: string[];
+    /** What the owner chose, by resource id. */
+    choices: Record<string, PluginConnectionChoice>;
+    connectedAtMs: number;
+    connectedByUid: string;
+    lastSyncAtMs: number | null;
+    /** When the scheduled sync should next run this connection; `null` while it waits for choices. */
+    nextSyncAtMs: number | null;
+    lastError: string | null;
+    /** Scheduled syncs that failed in a row since the last one that ran; sets the backoff (AGL-4194). */
+    syncFailures?: number;
+    updatedAtMs: number;
+}
+export declare function connectionsCollection(firestore: FirebaseFirestore.Firestore, hostId: string): FirebaseFirestore.CollectionReference;
+export declare function connectionRef(firestore: FirebaseFirestore.Firestore, hostId: string, listingId: string, connectionId: string): FirebaseFirestore.DocumentReference;
+/** The record the connection's sync writes, beside it (AGL-4192, AGL-4194). Server-only, like the rest. */
+export declare function connectionRecordRef(firestore: FirebaseFirestore.Firestore, hostId: string, listingId: string, connectionId: string): FirebaseFirestore.DocumentReference;
+type TokenOwner = Pick<PluginConnectionRecord, 'hostId' | 'listingId' | 'connectionId'>;
+/** The seal's context: this document and this token's purpose. */
+export declare const tokenContext: (owner: TokenOwner, purpose: "refresh" | "access") => string;
+/** Seals a token set for a record; a missing refresh token keeps `previousRefresh` (already sealed). */
+export declare function sealTokens(keyring: SecretBoxKeyring, owner: TokenOwner, tokens: Pick<PluginConnectionTokenSet, 'accessToken' | 'refreshToken'>, previousRefresh?: string): Pick<PluginConnectionRecord, 'sealedRefreshToken' | 'sealedAccessToken'>;
+/** Opens one of a record's tokens; throws `SecretBoxError` for one that does not open. */
+export declare function openToken(keyring: SecretBoxKeyring, record: TokenOwner & Pick<PluginConnectionRecord, 'sealedRefreshToken' | 'sealedAccessToken'>, purpose: 'refresh' | 'access'): {
+    token: string;
+    reseal: boolean;
+};
+/** A stored document read defensively, or `null` for anything that is not a connection. */
+export declare function readConnection(data: Record<string, unknown> | undefined): PluginConnectionRecord | null;
+export declare function getConnection(firestore: FirebaseFirestore.Firestore, hostId: string, listingId: string, connectionId: string): Promise<PluginConnectionRecord | null>;
+/** Every connection a site holds (never the pending states). */
+export declare function listHostConnections(firestore: FirebaseFirestore.Firestore, hostId: string): Promise<PluginConnectionRecord[]>;
+/** Whether every resource the declaration lists has a choice. */
+export declare function connectionReady(record: Pick<PluginConnectionRecord, 'choices'>, declaration: Pick<PluginConnectionDeclaration, 'resources'> | null): boolean;
+/** What the console reads: no token, no lease, no uid. */
+export declare function toConnectionView(record: PluginConnectionRecord, declaration: Pick<PluginConnectionDeclaration, 'resources'> | null): PluginConnectionView;
+/**
+ * Builds the record for a freshly exchanged grant. Reconnecting keeps the
+ * earlier choices and sync history: the owner reconnecting after a revoked
+ * grant means the same account, and the choose route re-checks every choice
+ * against what the new grant reaches before it is used again.
+ */
+export declare function newConnectionRecord(input: {
+    keyring: SecretBoxKeyring;
+    hostId: string;
+    orgId: string;
+    listingId: string;
+    connection: PluginConnectionDeclaration;
+    tokens: PluginConnectionTokenSet;
+    uid: string;
+    nowMs: number;
+    previous: PluginConnectionRecord | null;
+}): PluginConnectionRecord;
+/** Refresh when the access token has less than this left. */
+export declare const ACCESS_REFRESH_MARGIN_MS: number;
+export interface PluginConnectionTokenDeps {
+    firestore: FirebaseFirestore.Firestore;
+    keyring: SecretBoxKeyring;
+    /** The declaration the record was made under (the site's pinned manifest). */
+    connection: PluginConnectionDeclaration;
+    /** The publisher's OAuth app, opened. */
+    client: PluginConnectionClient;
+    now: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Thrown when a grant can no longer be used and the site owner has to connect again. */
+export declare class PluginConnectionReconnectRequiredError extends Error {
+    constructor(message: string);
+}
+/** Whether a record's access token should be refreshed before use. */
+export declare function accessTokenStale(record: Pick<PluginConnectionRecord, 'sealedAccessToken' | 'accessExpiresAtMs'>, nowMs: number): boolean;
+/**
+ * A usable access token for a connected record: the stored one, or a fresh
+ * one under the lease when it is near expiry (or `force`, after a 401).
+ */
+export declare function connectionAccessToken(deps: PluginConnectionTokenDeps, record: PluginConnectionRecord, options?: {
+    force?: boolean;
+}): Promise<string>;
+/**
+ * Refreshes a grant under the lease and stores the rotated tokens. Answers
+ * the access token now in force — this refresh's, or a concurrent one's.
+ */
+export declare function refreshConnection(deps: PluginConnectionTokenDeps, record: PluginConnectionRecord): Promise<{
+    accessToken: string;
+    refreshed: boolean;
+}>;
+/**
+ * Records a sync that ran (for the scheduled sync): its time, the next run,
+ * and the status back to `connected` with no error. `update()`, never a
+ * merge: a connection disconnected while the sync ran must not come back as
+ * a stub.
+ */
+export declare function markConnectionSynced(firestore: FirebaseFirestore.Firestore, record: TokenOwner, input: {
+    nowMs: number;
+    nextSyncAtMs: number;
+}): Promise<void>;
+/**
+ * Records a failure (for the scheduled sync and the picker): `error` with the
+ * next try scheduled, or `reconnect_required`, which stops the schedule until
+ * the owner connects again. The message is the provider's sentence or ours,
+ * never a token.
+ */
+export declare function markConnectionError(firestore: FirebaseFirestore.Firestore, record: TokenOwner, input: {
+    nowMs: number;
+    message: string;
+    reconnect: boolean;
+    nextSyncAtMs?: number | null;
+    syncFailures?: number;
+}): Promise<void>;
+export {};

package/src/lib/server/connections/connection-store.js

@@ -0,0 +1,331 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * A SITE'S DECLARED CONNECTION, AND ITS SEALED GRANT (AGL-4193).
+ *
+ * `hosts/{hostId}/pluginConnections/{listingId}__{connectionId}` — one per
+ * site, listing and declared connection. Copied in shape from accounting's
+ * ledger connection (`libs/plugins/accounting/.../connection-store.ts`), not
+ * imported: one plugin never imports another.
+ *
+ * The refresh and access tokens are sealed with `PLUGIN_CONNECTIONS_TOKEN_KEY`
+ * (secret box, AES-256-GCM), each bound to this document and its purpose as
+ * the seal's context, so a value copied onto another site's document refuses
+ * to open there. The rules refuse every client the whole collection; the
+ * console reads {@link toConnectionView}, which carries no token, through the
+ * status route.
+ *
+ * ## Rotation, and only one refresher
+ *
+ * Many providers hand back a new refresh token on a refresh and retire the
+ * old one soon after. Two processes refreshing the same grant at once — the
+ * picker and the scheduled sync — would each spend the old token, and one
+ * would store a token the provider has already replaced. So a refresh first
+ * takes a short LEASE on the document in a transaction; a second refresher
+ * that finds the lease held waits for the first's result instead. A provider
+ * that refuses the grant (`invalid_grant`, a 401) moves the connection to
+ * `reconnect_required`, which only the site owner connecting again clears.
+ */ import { needsReseal, openSecret, sealSecret } from "@aglyn/shared-util-tools/secret-box";
+import { pluginConnectionDocId, pluginConnectionRecordDocId } from "../../model/plugin-connections.js";
+import { PluginConnectionProviderError, refreshPluginConnectionToken } from "./provider-http.js";
+export function connectionsCollection(firestore, hostId) {
+    // Spelled out, not `PLUGIN_CONNECTIONS_HOST_COLLECTION`: the repo's host
+    // collection guards find a site's collections by this literal shape.
+    return firestore.collection('hosts').doc(hostId).collection('pluginConnections');
+}
+export function connectionRef(firestore, hostId, listingId, connectionId) {
+    return connectionsCollection(firestore, hostId).doc(pluginConnectionDocId(listingId, connectionId));
+}
+/** The record the connection's sync writes, beside it (AGL-4192, AGL-4194). Server-only, like the rest. */ export function connectionRecordRef(firestore, hostId, listingId, connectionId) {
+    return connectionsCollection(firestore, hostId).doc(pluginConnectionRecordDocId(listingId, connectionId));
+}
+/** The seal's context: this document and this token's purpose. */ export const tokenContext = (owner, purpose)=>`plugin-connections:token:${owner.hostId}:${owner.listingId}:${owner.connectionId}:${purpose}`;
+/** Seals a token set for a record; a missing refresh token keeps `previousRefresh` (already sealed). */ export function sealTokens(keyring, owner, tokens, previousRefresh = '') {
+    return {
+        sealedRefreshToken: tokens.refreshToken ? sealSecret(tokens.refreshToken, keyring.current, {
+            context: tokenContext(owner, 'refresh')
+        }) : previousRefresh,
+        sealedAccessToken: sealSecret(tokens.accessToken, keyring.current, {
+            context: tokenContext(owner, 'access')
+        })
+    };
+}
+/** Opens one of a record's tokens; throws `SecretBoxError` for one that does not open. */ export function openToken(keyring, record, purpose) {
+    const sealed = purpose === 'refresh' ? record.sealedRefreshToken : record.sealedAccessToken;
+    const opened = openSecret(sealed, keyring, {
+        context: tokenContext(record, purpose)
+    });
+    return {
+        token: opened.plaintext,
+        reseal: needsReseal(opened, keyring)
+    };
+}
+const STATUSES = [
+    'connected',
+    'reconnect_required',
+    'error'
+];
+/** A stored document read defensively, or `null` for anything that is not a connection. */ export function readConnection(data) {
+    if (!data || data['kind'] !== 'connection' || typeof data['listingId'] !== 'string' || typeof data['connectionId'] !== 'string') {
+        return null;
+    }
+    const record = data;
+    const choices = {};
+    if (record.choices && typeof record.choices === 'object') {
+        for (const [key, value] of Object.entries(record.choices)){
+            var _value_label;
+            if (value && typeof value.id === 'string') choices[key] = {
+                id: value.id,
+                label: String((_value_label = value.label) != null ? _value_label : value.id)
+            };
+        }
+    }
+    return _extends({}, record, {
+        status: STATUSES.includes(record.status) ? record.status : 'error',
+        sealedRefreshToken: typeof record.sealedRefreshToken === 'string' ? record.sealedRefreshToken : '',
+        sealedAccessToken: typeof record.sealedAccessToken === 'string' ? record.sealedAccessToken : '',
+        accessExpiresAtMs: Number(record.accessExpiresAtMs) || 0,
+        refreshedAtMs: Number(record.refreshedAtMs) || 0,
+        refreshLeaseUntilMs: Number(record.refreshLeaseUntilMs) || 0,
+        scopes: Array.isArray(record.scopes) ? record.scopes.map(String) : [],
+        choices,
+        lastSyncAtMs: Number(record.lastSyncAtMs) || null,
+        nextSyncAtMs: Number(record.nextSyncAtMs) || null,
+        lastError: typeof record.lastError === 'string' ? record.lastError : null,
+        syncFailures: Math.max(0, Math.trunc(Number(record.syncFailures) || 0))
+    });
+}
+export async function getConnection(firestore, hostId, listingId, connectionId) {
+    const snapshot = await connectionRef(firestore, hostId, listingId, connectionId).get();
+    return snapshot.exists ? readConnection(snapshot.data()) : null;
+}
+/** Every connection a site holds (never the pending states). */ export async function listHostConnections(firestore, hostId) {
+    const snapshot = await connectionsCollection(firestore, hostId).where('kind', '==', 'connection').get();
+    return snapshot.docs.map((doc)=>readConnection(doc.data())).filter((record)=>Boolean(record));
+}
+/** Whether every resource the declaration lists has a choice. */ export function connectionReady(record, declaration) {
+    var _ref;
+    return ((_ref = declaration == null ? void 0 : declaration.resources) != null ? _ref : []).every((resource)=>Boolean(record.choices[resource.id]));
+}
+/** What the console reads: no token, no lease, no uid. */ export function toConnectionView(record, declaration) {
+    return {
+        listingId: record.listingId,
+        connectionId: record.connectionId,
+        provider: record.provider,
+        status: record.status,
+        choices: record.choices,
+        ready: connectionReady(record, declaration),
+        scopes: record.scopes,
+        connectedAtMs: record.connectedAtMs,
+        lastSyncAtMs: record.lastSyncAtMs,
+        lastError: record.lastError
+    };
+}
+/**
+ * Builds the record for a freshly exchanged grant. Reconnecting keeps the
+ * earlier choices and sync history: the owner reconnecting after a revoked
+ * grant means the same account, and the choose route re-checks every choice
+ * against what the new grant reaches before it is used again.
+ */ export function newConnectionRecord(input) {
+    var _ref, _ref1, _ref2;
+    var _input_previous, _input_previous1, _input_previous2;
+    const owner = {
+        hostId: input.hostId,
+        listingId: input.listingId,
+        connectionId: input.connection.id
+    };
+    const choices = (_ref = (_input_previous = input.previous) == null ? void 0 : _input_previous.choices) != null ? _ref : {};
+    const ready = connectionReady({
+        choices
+    }, input.connection);
+    return _extends({
+        kind: 'connection'
+    }, owner, {
+        orgId: input.orgId,
+        provider: input.connection.provider,
+        status: 'connected'
+    }, sealTokens(input.keyring, owner, input.tokens, (_ref1 = (_input_previous1 = input.previous) == null ? void 0 : _input_previous1.sealedRefreshToken) != null ? _ref1 : ''), {
+        accessExpiresAtMs: input.tokens.accessExpiresAtMs,
+        refreshedAtMs: input.nowMs,
+        refreshLeaseUntilMs: 0,
+        scopes: input.tokens.scopes,
+        choices,
+        connectedAtMs: input.nowMs,
+        connectedByUid: input.uid,
+        lastSyncAtMs: (_ref2 = (_input_previous2 = input.previous) == null ? void 0 : _input_previous2.lastSyncAtMs) != null ? _ref2 : null,
+        nextSyncAtMs: ready ? input.nowMs : null,
+        lastError: null,
+        updatedAtMs: input.nowMs
+    });
+}
+/** Refresh when the access token has less than this left. */ export const ACCESS_REFRESH_MARGIN_MS = 5 * 60 * 1000;
+const LEASE_MS = 30000;
+const LEASE_WAITS = 6;
+const LEASE_WAIT_MS = 1000;
+/** Thrown when a grant can no longer be used and the site owner has to connect again. */ export class PluginConnectionReconnectRequiredError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'PluginConnectionReconnectRequiredError';
+    }
+}
+/** Whether a record's access token should be refreshed before use. */ export function accessTokenStale(record, nowMs) {
+    return !record.sealedAccessToken || record.accessExpiresAtMs - ACCESS_REFRESH_MARGIN_MS <= nowMs;
+}
+/**
+ * A usable access token for a connected record: the stored one, or a fresh
+ * one under the lease when it is near expiry (or `force`, after a 401).
+ */ export async function connectionAccessToken(deps, record, options = {}) {
+    if (record.status === 'reconnect_required') {
+        var _record_lastError;
+        throw new PluginConnectionReconnectRequiredError((_record_lastError = record.lastError) != null ? _record_lastError : 'Connect again.');
+    }
+    if (!options.force && !accessTokenStale(record, deps.now())) {
+        return openToken(deps.keyring, record, 'access').token;
+    }
+    return (await refreshConnection(deps, record)).accessToken;
+}
+/**
+ * Refreshes a grant under the lease and stores the rotated tokens. Answers
+ * the access token now in force — this refresh's, or a concurrent one's.
+ */ export async function refreshConnection(deps, record) {
+    var _deps_sleep;
+    const ref = connectionRef(deps.firestore, record.hostId, record.listingId, record.connectionId);
+    const sleep = (_deps_sleep = deps.sleep) != null ? _deps_sleep : (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
+    const startedRefreshedAt = record.refreshedAtMs;
+    for(let wait = 0; wait <= LEASE_WAITS; wait += 1){
+        const claim = await deps.firestore.runTransaction(async (transaction)=>{
+            const snapshot = await transaction.get(ref);
+            const current = readConnection(snapshot.exists ? snapshot.data() : undefined);
+            if (!current || current.status === 'reconnect_required') return {
+                kind: 'gone',
+                current
+            };
+            // Someone else refreshed since we read: use theirs.
+            if (current.refreshedAtMs > startedRefreshedAt && !accessTokenStale(current, deps.now())) {
+                return {
+                    kind: 'fresh',
+                    current
+                };
+            }
+            if (current.refreshLeaseUntilMs > deps.now()) return {
+                kind: 'held',
+                current
+            };
+            transaction.update(ref, {
+                refreshLeaseUntilMs: deps.now() + LEASE_MS
+            });
+            return {
+                kind: 'ours',
+                current
+            };
+        });
+        if (claim.kind === 'gone') {
+            var _ref;
+            var _claim_current;
+            throw new PluginConnectionReconnectRequiredError((_ref = (_claim_current = claim.current) == null ? void 0 : _claim_current.lastError) != null ? _ref : 'Connect again.');
+        }
+        if (claim.kind === 'fresh') {
+            return {
+                accessToken: openToken(deps.keyring, claim.current, 'access').token,
+                refreshed: false
+            };
+        }
+        if (claim.kind === 'held') {
+            await sleep(LEASE_WAIT_MS);
+            continue;
+        }
+        const current = claim.current;
+        if (!current.sealedRefreshToken) {
+            // Nothing to refresh with: the provider never issued a refresh token.
+            const message = 'The connection has expired. Connect again.';
+            await ref.update({
+                status: 'reconnect_required',
+                lastError: message,
+                refreshLeaseUntilMs: 0,
+                nextSyncAtMs: null,
+                updatedAtMs: deps.now()
+            });
+            throw new PluginConnectionReconnectRequiredError(message);
+        }
+        let tokens;
+        try {
+            tokens = await refreshPluginConnectionToken(deps.connection, deps.client, openToken(deps.keyring, current, 'refresh').token);
+        } catch (error) {
+            if (error instanceof PluginConnectionProviderError && error.code === 'auth') {
+                const message = error.message || 'The provider refused the connection. Connect again.';
+                await ref.update({
+                    status: 'reconnect_required',
+                    lastError: message,
+                    refreshLeaseUntilMs: 0,
+                    nextSyncAtMs: null,
+                    updatedAtMs: deps.now()
+                });
+                throw new PluginConnectionReconnectRequiredError(message);
+            }
+            await ref.update({
+                refreshLeaseUntilMs: 0
+            });
+            throw error;
+        }
+        const nowMs = deps.now();
+        await ref.update(_extends({}, sealTokens(deps.keyring, current, tokens, current.sealedRefreshToken), {
+            accessExpiresAtMs: tokens.accessExpiresAtMs,
+            refreshedAtMs: nowMs,
+            refreshLeaseUntilMs: 0,
+            updatedAtMs: nowMs
+        }));
+        return {
+            accessToken: tokens.accessToken,
+            refreshed: true
+        };
+    }
+    throw new PluginConnectionProviderError('transient', 'Another refresh of this connection is still running.');
+}
+/**
+ * Records a sync that ran (for the scheduled sync): its time, the next run,
+ * and the status back to `connected` with no error. `update()`, never a
+ * merge: a connection disconnected while the sync ran must not come back as
+ * a stub.
+ */ export async function markConnectionSynced(firestore, record, input) {
+    await connectionRef(firestore, record.hostId, record.listingId, record.connectionId).update({
+        status: 'connected',
+        lastSyncAtMs: input.nowMs,
+        nextSyncAtMs: input.nextSyncAtMs,
+        lastError: null,
+        syncFailures: 0,
+        updatedAtMs: input.nowMs
+    });
+}
+/**
+ * Records a failure (for the scheduled sync and the picker): `error` with the
+ * next try scheduled, or `reconnect_required`, which stops the schedule until
+ * the owner connects again. The message is the provider's sentence or ours,
+ * never a token.
+ */ export async function markConnectionError(firestore, record, input) {
+    var _input_nextSyncAtMs;
+    await connectionRef(firestore, record.hostId, record.listingId, record.connectionId).update(_extends({
+        status: input.reconnect ? 'reconnect_required' : 'error',
+        lastError: input.message.slice(0, 300),
+        nextSyncAtMs: input.reconnect ? null : (_input_nextSyncAtMs = input.nextSyncAtMs) != null ? _input_nextSyncAtMs : null
+    }, input.syncFailures !== undefined ? {
+        syncFailures: input.syncFailures
+    } : {}, {
+        updatedAtMs: input.nowMs
+    }));
+}
+
+//# sourceMappingURL=connection-store.js.map

package/src/lib/server/connections/connection-store.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/plugins/marketplace/src/lib/server/connections/connection-store.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A SITE'S DECLARED CONNECTION, AND ITS SEALED GRANT (AGL-4193).\n *\n * `hosts/{hostId}/pluginConnections/{listingId}__{connectionId}` — one per\n * site, listing and declared connection. Copied in shape from accounting's\n * ledger connection (`libs/plugins/accounting/.../connection-store.ts`), not\n * imported: one plugin never imports another.\n *\n * The refresh and access tokens are sealed with `PLUGIN_CONNECTIONS_TOKEN_KEY`\n * (secret box, AES-256-GCM), each bound to this document and its purpose as\n * the seal's context, so a value copied onto another site's document refuses\n * to open there. The rules refuse every client the whole collection; the\n * console reads {@link toConnectionView}, which carries no token, through the\n * status route.\n *\n * ## Rotation, and only one refresher\n *\n * Many providers hand back a new refresh token on a refresh and retire the\n * old one soon after. Two processes refreshing the same grant at once — the\n * picker and the scheduled sync — would each spend the old token, and one\n * would store a token the provider has already replaced. So a refresh first\n * takes a short LEASE on the document in a transaction; a second refresher\n * that finds the lease held waits for the first's result instead. A provider\n * that refuses the grant (`invalid_grant`, a 401) moves the connection to\n * `reconnect_required`, which only the site owner connecting again clears.\n */\n\nimport { needsReseal, openSecret, sealSecret, type SecretBoxKeyring } from '@aglyn/shared-util-tools/secret-box'\nimport type { PluginConnectionDeclaration } from '@aglyn/aglyn/app-utils/plugin-connections'\nimport {\n  pluginConnectionDocId,\n  pluginConnectionRecordDocId,\n  type PluginConnectionChoice,\n  type PluginConnectionStatus,\n  type PluginConnectionView,\n} from '../../model/plugin-connections'\nimport {\n  PluginConnectionProviderError,\n  refreshPluginConnectionToken,\n  type PluginConnectionClient,\n  type PluginConnectionTokenSet,\n} from './provider-http'\n\n/** The stored document. Server-only. */\nexport interface PluginConnectionRecord {\n  /** Tells a connection from a pending connect's state record in the same collection. */\n  kind: 'connection'\n  hostId: string\n  /** The workspace that owns the site, when it connected. */\n  orgId: string\n  listingId: string\n  connectionId: string\n  provider: string\n  status: PluginConnectionStatus\n  /** `''` when the provider issued no refresh token. */\n  sealedRefreshToken: string\n  sealedAccessToken: string\n  accessExpiresAtMs: number\n  refreshedAtMs: number\n  refreshLeaseUntilMs: number\n  scopes: string[]\n  /** What the owner chose, by resource id. */\n  choices: Record<string, PluginConnectionChoice>\n  connectedAtMs: number\n  connectedByUid: string\n  lastSyncAtMs: number | null\n  /** When the scheduled sync should next run this connection; `null` while it waits for choices. */\n  nextSyncAtMs: number | null\n  lastError: string | null\n  /** Scheduled syncs that failed in a row since the last one that ran; sets the backoff (AGL-4194). */\n  syncFailures?: number\n  updatedAtMs: number\n}\n\nexport function connectionsCollection(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n): FirebaseFirestore.CollectionReference {\n  // Spelled out, not `PLUGIN_CONNECTIONS_HOST_COLLECTION`: the repo's host\n  // collection guards find a site's collections by this literal shape.\n  return firestore.collection('hosts').doc(hostId).collection('pluginConnections')\n}\n\nexport function connectionRef(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n  listingId: string,\n  connectionId: string,\n): FirebaseFirestore.DocumentReference {\n  return connectionsCollection(firestore, hostId).doc(pluginConnectionDocId(listingId, connectionId))\n}\n\n/** The record the connection's sync writes, beside it (AGL-4192, AGL-4194). Server-only, like the rest. */\nexport function connectionRecordRef(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n  listingId: string,\n  connectionId: string,\n): FirebaseFirestore.DocumentReference {\n  return connectionsCollection(firestore, hostId).doc(pluginConnectionRecordDocId(listingId, connectionId))\n}\n\ntype TokenOwner = Pick<PluginConnectionRecord, 'hostId' | 'listingId' | 'connectionId'>\n\n/** The seal's context: this document and this token's purpose. */\nexport const tokenContext = (owner: TokenOwner, purpose: 'refresh' | 'access') =>\n  `plugin-connections:token:${owner.hostId}:${owner.listingId}:${owner.connectionId}:${purpose}`\n\n/** Seals a token set for a record; a missing refresh token keeps `previousRefresh` (already sealed). */\nexport function sealTokens(\n  keyring: SecretBoxKeyring,\n  owner: TokenOwner,\n  tokens: Pick<PluginConnectionTokenSet, 'accessToken' | 'refreshToken'>,\n  previousRefresh = '',\n): Pick<PluginConnectionRecord, 'sealedRefreshToken' | 'sealedAccessToken'> {\n  return {\n    sealedRefreshToken: tokens.refreshToken\n      ? sealSecret(tokens.refreshToken, keyring.current, { context: tokenContext(owner, 'refresh') })\n      : previousRefresh,\n    sealedAccessToken: sealSecret(tokens.accessToken, keyring.current, { context: tokenContext(owner, 'access') }),\n  }\n}\n\n/** Opens one of a record's tokens; throws `SecretBoxError` for one that does not open. */\nexport function openToken(\n  keyring: SecretBoxKeyring,\n  record: TokenOwner & Pick<PluginConnectionRecord, 'sealedRefreshToken' | 'sealedAccessToken'>,\n  purpose: 'refresh' | 'access',\n): { token: string; reseal: boolean } {\n  const sealed = purpose === 'refresh' ? record.sealedRefreshToken : record.sealedAccessToken\n  const opened = openSecret(sealed, keyring, { context: tokenContext(record, purpose) })\n  return { token: opened.plaintext, reseal: needsReseal(opened, keyring) }\n}\n\nconst STATUSES: readonly PluginConnectionStatus[] = ['connected', 'reconnect_required', 'error']\n\n/** A stored document read defensively, or `null` for anything that is not a connection. */\nexport function readConnection(data: Record<string, unknown> | undefined): PluginConnectionRecord | null {\n  if (!data || data['kind'] !== 'connection' || typeof data['listingId'] !== 'string' || typeof data['connectionId'] !== 'string') {\n    return null\n  }\n  const record = data as unknown as PluginConnectionRecord\n  const choices: Record<string, PluginConnectionChoice> = {}\n  if (record.choices && typeof record.choices === 'object') {\n    for (const [key, value] of Object.entries(record.choices)) {\n      if (value && typeof value.id === 'string') choices[key] = { id: value.id, label: String(value.label ?? value.id) }\n    }\n  }\n  return {\n    ...record,\n    status: STATUSES.includes(record.status) ? record.status : 'error',\n    sealedRefreshToken: typeof record.sealedRefreshToken === 'string' ? record.sealedRefreshToken : '',\n    sealedAccessToken: typeof record.sealedAccessToken === 'string' ? record.sealedAccessToken : '',\n    accessExpiresAtMs: Number(record.accessExpiresAtMs) || 0,\n    refreshedAtMs: Number(record.refreshedAtMs) || 0,\n    refreshLeaseUntilMs: Number(record.refreshLeaseUntilMs) || 0,\n    scopes: Array.isArray(record.scopes) ? record.scopes.map(String) : [],\n    choices,\n    lastSyncAtMs: Number(record.lastSyncAtMs) || null,\n    nextSyncAtMs: Number(record.nextSyncAtMs) || null,\n    lastError: typeof record.lastError === 'string' ? record.lastError : null,\n    syncFailures: Math.max(0, Math.trunc(Number(record.syncFailures) || 0)),\n  }\n}\n\nexport async function getConnection(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n  listingId: string,\n  connectionId: string,\n): Promise<PluginConnectionRecord | null> {\n  const snapshot = await connectionRef(firestore, hostId, listingId, connectionId).get()\n  return snapshot.exists ? readConnection(snapshot.data()) : null\n}\n\n/** Every connection a site holds (never the pending states). */\nexport async function listHostConnections(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n): Promise<PluginConnectionRecord[]> {\n  const snapshot = await connectionsCollection(firestore, hostId).where('kind', '==', 'connection').get()\n  return snapshot.docs\n    .map((doc) => readConnection(doc.data()))\n    .filter((record): record is PluginConnectionRecord => Boolean(record))\n}\n\n/** Whether every resource the declaration lists has a choice. */\nexport function connectionReady(\n  record: Pick<PluginConnectionRecord, 'choices'>,\n  declaration: Pick<PluginConnectionDeclaration, 'resources'> | null,\n): boolean {\n  return (declaration?.resources ?? []).every((resource) => Boolean(record.choices[resource.id]))\n}\n\n/** What the console reads: no token, no lease, no uid. */\nexport function toConnectionView(\n  record: PluginConnectionRecord,\n  declaration: Pick<PluginConnectionDeclaration, 'resources'> | null,\n): PluginConnectionView {\n  return {\n    listingId: record.listingId,\n    connectionId: record.connectionId,\n    provider: record.provider,\n    status: record.status,\n    choices: record.choices,\n    ready: connectionReady(record, declaration),\n    scopes: record.scopes,\n    connectedAtMs: record.connectedAtMs,\n    lastSyncAtMs: record.lastSyncAtMs,\n    lastError: record.lastError,\n  }\n}\n\n/**\n * Builds the record for a freshly exchanged grant. Reconnecting keeps the\n * earlier choices and sync history: the owner reconnecting after a revoked\n * grant means the same account, and the choose route re-checks every choice\n * against what the new grant reaches before it is used again.\n */\nexport function newConnectionRecord(input: {\n  keyring: SecretBoxKeyring\n  hostId: string\n  orgId: string\n  listingId: string\n  connection: PluginConnectionDeclaration\n  tokens: PluginConnectionTokenSet\n  uid: string\n  nowMs: number\n  previous: PluginConnectionRecord | null\n}): PluginConnectionRecord {\n  const owner = { hostId: input.hostId, listingId: input.listingId, connectionId: input.connection.id }\n  const choices = input.previous?.choices ?? {}\n  const ready = connectionReady({ choices }, input.connection)\n  return {\n    kind: 'connection',\n    ...owner,\n    orgId: input.orgId,\n    provider: input.connection.provider,\n    status: 'connected',\n    // A provider that issues no new refresh token on a re-consent keeps the\n    // previous grant's, which it did not revoke.\n    ...sealTokens(input.keyring, owner, input.tokens, input.previous?.sealedRefreshToken ?? ''),\n    accessExpiresAtMs: input.tokens.accessExpiresAtMs,\n    refreshedAtMs: input.nowMs,\n    refreshLeaseUntilMs: 0,\n    scopes: input.tokens.scopes,\n    choices,\n    connectedAtMs: input.nowMs,\n    connectedByUid: input.uid,\n    lastSyncAtMs: input.previous?.lastSyncAtMs ?? null,\n    nextSyncAtMs: ready ? input.nowMs : null,\n    lastError: null,\n    updatedAtMs: input.nowMs,\n  }\n}\n\n/** Refresh when the access token has less than this left. */\nexport const ACCESS_REFRESH_MARGIN_MS = 5 * 60 * 1000\n\nconst LEASE_MS = 30_000\nconst LEASE_WAITS = 6\nconst LEASE_WAIT_MS = 1000\n\nexport interface PluginConnectionTokenDeps {\n  firestore: FirebaseFirestore.Firestore\n  keyring: SecretBoxKeyring\n  /** The declaration the record was made under (the site's pinned manifest). */\n  connection: PluginConnectionDeclaration\n  /** The publisher's OAuth app, opened. */\n  client: PluginConnectionClient\n  now: () => number\n  sleep?: (ms: number) => Promise<void>\n}\n\n/** Thrown when a grant can no longer be used and the site owner has to connect again. */\nexport class PluginConnectionReconnectRequiredError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = 'PluginConnectionReconnectRequiredError'\n  }\n}\n\n/** Whether a record's access token should be refreshed before use. */\nexport function accessTokenStale(record: Pick<PluginConnectionRecord, 'sealedAccessToken' | 'accessExpiresAtMs'>, nowMs: number): boolean {\n  return !record.sealedAccessToken || record.accessExpiresAtMs - ACCESS_REFRESH_MARGIN_MS <= nowMs\n}\n\n/**\n * A usable access token for a connected record: the stored one, or a fresh\n * one under the lease when it is near expiry (or `force`, after a 401).\n */\nexport async function connectionAccessToken(\n  deps: PluginConnectionTokenDeps,\n  record: PluginConnectionRecord,\n  options: { force?: boolean } = {},\n): Promise<string> {\n  if (record.status === 'reconnect_required') {\n    throw new PluginConnectionReconnectRequiredError(record.lastError ?? 'Connect again.')\n  }\n  if (!options.force && !accessTokenStale(record, deps.now())) {\n    return openToken(deps.keyring, record, 'access').token\n  }\n  return (await refreshConnection(deps, record)).accessToken\n}\n\n/**\n * Refreshes a grant under the lease and stores the rotated tokens. Answers\n * the access token now in force — this refresh's, or a concurrent one's.\n */\nexport async function refreshConnection(\n  deps: PluginConnectionTokenDeps,\n  record: PluginConnectionRecord,\n): Promise<{ accessToken: string; refreshed: boolean }> {\n  const ref = connectionRef(deps.firestore, record.hostId, record.listingId, record.connectionId)\n  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)))\n  const startedRefreshedAt = record.refreshedAtMs\n  for (let wait = 0; wait <= LEASE_WAITS; wait += 1) {\n    const claim = await deps.firestore.runTransaction(async (transaction) => {\n      const snapshot = await transaction.get(ref)\n      const current = readConnection(snapshot.exists ? snapshot.data() : undefined)\n      if (!current || current.status === 'reconnect_required') return { kind: 'gone' as const, current }\n      // Someone else refreshed since we read: use theirs.\n      if (current.refreshedAtMs > startedRefreshedAt && !accessTokenStale(current, deps.now())) {\n        return { kind: 'fresh' as const, current }\n      }\n      if (current.refreshLeaseUntilMs > deps.now()) return { kind: 'held' as const, current }\n      transaction.update(ref, { refreshLeaseUntilMs: deps.now() + LEASE_MS })\n      return { kind: 'ours' as const, current }\n    })\n    if (claim.kind === 'gone') {\n      throw new PluginConnectionReconnectRequiredError(claim.current?.lastError ?? 'Connect again.')\n    }\n    if (claim.kind === 'fresh') {\n      return { accessToken: openToken(deps.keyring, claim.current, 'access').token, refreshed: false }\n    }\n    if (claim.kind === 'held') {\n      await sleep(LEASE_WAIT_MS)\n      continue\n    }\n    const current = claim.current\n    if (!current.sealedRefreshToken) {\n      // Nothing to refresh with: the provider never issued a refresh token.\n      const message = 'The connection has expired. Connect again.'\n      await ref.update({ status: 'reconnect_required', lastError: message, refreshLeaseUntilMs: 0, nextSyncAtMs: null, updatedAtMs: deps.now() })\n      throw new PluginConnectionReconnectRequiredError(message)\n    }\n    let tokens: PluginConnectionTokenSet\n    try {\n      tokens = await refreshPluginConnectionToken(deps.connection, deps.client, openToken(deps.keyring, current, 'refresh').token)\n    } catch (error) {\n      if (error instanceof PluginConnectionProviderError && error.code === 'auth') {\n        const message = error.message || 'The provider refused the connection. Connect again.'\n        await ref.update({\n          status: 'reconnect_required',\n          lastError: message,\n          refreshLeaseUntilMs: 0,\n          nextSyncAtMs: null,\n          updatedAtMs: deps.now(),\n        })\n        throw new PluginConnectionReconnectRequiredError(message)\n      }\n      await ref.update({ refreshLeaseUntilMs: 0 })\n      throw error\n    }\n    const nowMs = deps.now()\n    await ref.update({\n      ...sealTokens(deps.keyring, current, tokens, current.sealedRefreshToken),\n      accessExpiresAtMs: tokens.accessExpiresAtMs,\n      refreshedAtMs: nowMs,\n      refreshLeaseUntilMs: 0,\n      updatedAtMs: nowMs,\n    })\n    return { accessToken: tokens.accessToken, refreshed: true }\n  }\n  throw new PluginConnectionProviderError('transient', 'Another refresh of this connection is still running.')\n}\n\n/**\n * Records a sync that ran (for the scheduled sync): its time, the next run,\n * and the status back to `connected` with no error. `update()`, never a\n * merge: a connection disconnected while the sync ran must not come back as\n * a stub.\n */\nexport async function markConnectionSynced(\n  firestore: FirebaseFirestore.Firestore,\n  record: TokenOwner,\n  input: { nowMs: number; nextSyncAtMs: number },\n): Promise<void> {\n  await connectionRef(firestore, record.hostId, record.listingId, record.connectionId).update({\n    status: 'connected',\n    lastSyncAtMs: input.nowMs,\n    nextSyncAtMs: input.nextSyncAtMs,\n    lastError: null,\n    syncFailures: 0,\n    updatedAtMs: input.nowMs,\n  })\n}\n\n/**\n * Records a failure (for the scheduled sync and the picker): `error` with the\n * next try scheduled, or `reconnect_required`, which stops the schedule until\n * the owner connects again. The message is the provider's sentence or ours,\n * never a token.\n */\nexport async function markConnectionError(\n  firestore: FirebaseFirestore.Firestore,\n  record: TokenOwner,\n  input: { nowMs: number; message: string; reconnect: boolean; nextSyncAtMs?: number | null; syncFailures?: number },\n): Promise<void> {\n  await connectionRef(firestore, record.hostId, record.listingId, record.connectionId).update({\n    status: input.reconnect ? 'reconnect_required' : 'error',\n    lastError: input.message.slice(0, 300),\n    nextSyncAtMs: input.reconnect ? null : (input.nextSyncAtMs ?? null),\n    ...(input.syncFailures !== undefined ? { syncFailures: input.syncFailures } : {}),\n    updatedAtMs: input.nowMs,\n  })\n}\n"],"names":["needsReseal","openSecret","sealSecret","pluginConnectionDocId","pluginConnectionRecordDocId","PluginConnectionProviderError","refreshPluginConnectionToken","connectionsCollection","firestore","hostId","collection","doc","connectionRef","listingId","connectionId","connectionRecordRef","tokenContext","owner","purpose","sealTokens","keyring","tokens","previousRefresh","sealedRefreshToken","refreshToken","current","context","sealedAccessToken","accessToken","openToken","record","sealed","opened","token","plaintext","reseal","STATUSES","readConnection","data","choices","key","value","Object","entries","id","label","String","status","includes","accessExpiresAtMs","Number","refreshedAtMs","refreshLeaseUntilMs","scopes","Array","isArray","map","lastSyncAtMs","nextSyncAtMs","lastError","syncFailures","Math","max","trunc","getConnection","snapshot","get","exists","listHostConnections","where","docs","filter","Boolean","connectionReady","declaration","resources","every","resource","toConnectionView","provider","ready","connectedAtMs","newConnectionRecord","input","connection","previous","kind","orgId","nowMs","connectedByUid","uid","updatedAtMs","ACCESS_REFRESH_MARGIN_MS","LEASE_MS","LEASE_WAITS","LEASE_WAIT_MS","PluginConnectionReconnectRequiredError","Error","message","name","accessTokenStale","connectionAccessToken","deps","options","force","now","refreshConnection","ref","sleep","ms","Promise","resolve","setTimeout","startedRefreshedAt","wait","claim","runTransaction","transaction","undefined","update","refreshed","client","error","code","markConnectionSynced","markConnectionError","reconnect","slice"],"mappings":"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"}

package/src/lib/server/connections/credentials-store.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type SecretBoxKeyring } from '@aglyn/shared-util-tools/secret-box';
+import type { PluginConnectionClient } from './provider-http';
+/**
+ * A LISTING'S OAUTH APP, SEALED (AGL-4193).
+ *
+ * `pluginConnectionCredentials/{listingId}__{connectionId}`: the client id
+ * and secret of the PUBLISHER's own OAuth app, which every site's connect for
+ * that listing authenticates with. Both are sealed with
+ * `PLUGIN_CONNECTIONS_TOKEN_KEY`, each bound to this document and its purpose
+ * as the seal's context, so a value copied into another listing's document
+ * refuses to open there.
+ *
+ * Write-only by design: no route reads either value back. A publisher sees
+ * "set" or "not set", and replaces the pair whole. `orgId` names the
+ * publishing workspace, so that workspace's erasure sweeps the document by
+ * field (`orgKeyedCollections`), and the Firestore rules refuse every client.
+ */
+export interface PluginConnectionCredentialsRecord {
+    /** The publishing workspace. */
+    orgId: string;
+    listingId: string;
+    connectionId: string;
+    sealedClientId: string;
+    sealedClientSecret: string;
+    updatedAtMs: number;
+    updatedBy: string;
+}
+export declare function credentialsRef(firestore: FirebaseFirestore.Firestore, listingId: string, connectionId: string): FirebaseFirestore.DocumentReference;
+/** The seal's context: this document and this value's purpose. */
+export declare const credentialsContext: (listingId: string, connectionId: string, purpose: "client-id" | "client-secret") => string;
+/** Builds the stored record for a pair the publisher typed. */
+export declare function sealCredentials(keyring: SecretBoxKeyring, input: {
+    orgId: string;
+    listingId: string;
+    connectionId: string;
+    clientId: string;
+    clientSecret: string;
+    uid: string;
+    nowMs: number;
+}): PluginConnectionCredentialsRecord;
+export declare function saveCredentials(firestore: FirebaseFirestore.Firestore, record: PluginConnectionCredentialsRecord): Promise<void>;
+export declare function clearCredentials(firestore: FirebaseFirestore.Firestore, listingId: string, connectionId: string): Promise<void>;
+/** Whether each named connection's credentials are set, and when: never the values. */
+export declare function credentialsStatus(firestore: FirebaseFirestore.Firestore, listingId: string, connectionIds: readonly string[]): Promise<Record<string, {
+    set: boolean;
+    updatedAtMs: number | null;
+}>>;
+/**
+ * The publisher's OAuth app for a listing's connection, opened, or `null`
+ * when it is not set. Throws `SecretBoxError` for a value that does not open
+ * (a key that was dropped from the ring, or a tampered document).
+ */
+export declare function openCredentials(firestore: FirebaseFirestore.Firestore, keyring: SecretBoxKeyring, listingId: string, connectionId: string): Promise<PluginConnectionClient | null>;
+/** Every credentials document a workspace's listings hold, for its erasure. */
+export declare function credentialsForOrg(firestore: FirebaseFirestore.Firestore, orgId: string): Promise<FirebaseFirestore.QueryDocumentSnapshot[]>;