@aglyn/plugins-outreach 1.0.0-beta.143

package/src/lib/mailboxes/mailbox-credentials.js

@@ -0,0 +1,102 @@
+/**
+ * @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 { needsReseal, openSecret, sealSecret } from "@aglyn/shared-util-tools/secret-box";
+import { createHash } from "node:crypto";
+import { OUTREACH_COLLECTIONS } from "../model/outreach.types.js";
+/** The context a mailbox's refresh token is sealed under. */ export function refreshTokenSealContext(mailboxId) {
+    return `${OUTREACH_COLLECTIONS.mailboxCredentials}/${mailboxId}#refreshToken`;
+}
+/** Seals a refresh token for one mailbox under the keyring's current key. */ export function sealMailboxRefreshToken(refreshToken, mailboxId, keyring) {
+    return {
+        sealedRefreshToken: sealSecret(refreshToken, keyring.current, {
+            context: refreshTokenSealContext(mailboxId)
+        }),
+        tokenKeyId: keyring.current.id
+    };
+}
+/**
+ * Opens a stored credential's refresh token. Throws `SecretBoxError` when it
+ * cannot be opened — a missing or rotated-away key, or a tampered value.
+ */ export function openMailboxRefreshToken(credential, keyring) {
+    const opened = openSecret(credential.sealedRefreshToken, keyring, {
+        context: refreshTokenSealContext(credential.mailboxId)
+    });
+    return {
+        refreshToken: opened.plaintext,
+        needsReseal: needsReseal(opened, keyring)
+    };
+}
+/**
+ * The id a member's mailbox for one Google account has in one organization.
+ *
+ * Derived rather than random, so connecting the same account again updates
+ * the same mailbox instead of adding a second one, and two members — or two
+ * organizations — connecting one account never share an id. The credential
+ * collection is top-level, keyed by this id, so it must be unique across
+ * every organization, which is why the org is part of it.
+ */ export function outreachMailboxId(orgId, uid, providerAccountId) {
+    const hash = createHash('sha256').update(`${orgId}\n${uid}\ngoogle\n${providerAccountId}`).digest('base64url');
+    return `gm_${hash.slice(0, 24)}`;
+}
+export function mailboxCredentialsRef(firestore, mailboxId) {
+    return firestore.collection(OUTREACH_COLLECTIONS.mailboxCredentials).doc(mailboxId);
+}
+export function mailboxRef(firestore, orgId, mailboxId) {
+    return firestore.collection('orgs').doc(orgId).collection(OUTREACH_COLLECTIONS.mailboxes).doc(mailboxId);
+}
+/** A stored credential read defensively, or `null` when it is not one. */ export function readMailboxCredentials(data) {
+    var _record_id, _record_connectedByUid, _record_providerAccountId, _record_email, _record_tokenKeyId;
+    const record = data != null ? data : null;
+    if (!record || record.provider !== 'google' || typeof record.mailboxId !== 'string' || typeof record.orgId !== 'string' || typeof record.sealedRefreshToken !== 'string' || !record.sealedRefreshToken) {
+        return null;
+    }
+    return {
+        id: String((_record_id = record.id) != null ? _record_id : record.mailboxId),
+        orgId: record.orgId,
+        mailboxId: record.mailboxId,
+        provider: 'google',
+        connectedByUid: String((_record_connectedByUid = record.connectedByUid) != null ? _record_connectedByUid : ''),
+        providerAccountId: String((_record_providerAccountId = record.providerAccountId) != null ? _record_providerAccountId : ''),
+        email: String((_record_email = record.email) != null ? _record_email : ''),
+        scopes: Array.isArray(record.scopes) ? record.scopes.map(String) : [],
+        sealedRefreshToken: record.sealedRefreshToken,
+        tokenKeyId: String((_record_tokenKeyId = record.tokenKeyId) != null ? _record_tokenKeyId : ''),
+        createdAtMs: Number(record.createdAtMs) || 0,
+        updatedAtMs: Number(record.updatedAtMs) || 0
+    };
+}
+/**
+ * How many OTHER stored credentials hold a grant for the same Google account.
+ *
+ * Google's revocation ends the whole grant this client holds for an account,
+ * not one token, so revoking while another mailbox still uses the account —
+ * the same shared inbox connected by two members, or one account connected
+ * in two organizations — would silently break that mailbox. A disconnect or
+ * an erasure asks this first and leaves the grant alone while it is shared.
+ *
+ * An erasure names what it is ending anyway — a whole organization's
+ * credentials, or every one of a person's — and those are not counted.
+ */ export async function countOtherCredentialsForAccount(firestore, input) {
+    if (!input.providerAccountId) return 0;
+    const snapshot = await firestore.collection(OUTREACH_COLLECTIONS.mailboxCredentials).where('providerAccountId', '==', input.providerAccountId).limit(20).get();
+    return snapshot.docs.filter((doc)=>{
+        var _input_excludeMailboxIds;
+        if (doc.id === input.mailboxId || ((_input_excludeMailboxIds = input.excludeMailboxIds) == null ? void 0 : _input_excludeMailboxIds.has(doc.id))) return false;
+        return !input.excludeOrgId || doc.get('orgId') !== input.excludeOrgId;
+    }).length;
+}
+
+//# sourceMappingURL=mailbox-credentials.js.map

package/src/lib/mailboxes/mailbox-credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/mailboxes/mailbox-credentials.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\nimport {\n  needsReseal,\n  openSecret,\n  sealSecret,\n  type SecretBoxKeyring,\n} from '@aglyn/shared-util-tools/secret-box'\nimport { createHash } from 'node:crypto'\nimport {\n  OUTREACH_COLLECTIONS,\n  type OutreachMailboxCredentials,\n} from '../model/outreach.types'\n\n/**\n * A MAILBOX'S GRANT AT REST (AGL-2978): `outreachMailboxCredentials/{mailboxId}`.\n *\n * The refresh token is the only secret, and it is stored only sealed —\n * AES-256-GCM under `OUTREACH_TOKEN_KEY` through the shared secret box, bound\n * to this document by the seal's context, so a sealed token copied into\n * another mailbox's credential refuses to open there. Every other field is\n * bookkeeping a reader needs without the key: which account, which scopes,\n * which member, which key sealed it.\n *\n * Sealed fields carry `token` in their names. The personal-data export\n * redacts by field name first, and a neutral name would be judged by its\n * value's shape alone.\n */\n\n/** A connected Google mailbox's stored credential. */\nexport interface OutreachGoogleMailboxCredentials extends OutreachMailboxCredentials {\n  provider: 'google'\n  /** The member who connected the mailbox. */\n  connectedByUid: string\n  /** Google's stable account id (`sub`), so one account's grants can be found. */\n  providerAccountId: string\n  /** The account's address, as Google verified it. */\n  email: string\n  /** The scopes Google granted, as it listed them. */\n  scopes: string[]\n  /** The refresh token, sealed — see the module comment. */\n  sealedRefreshToken: string\n  /** The id of the key that sealed it, for rotation. */\n  tokenKeyId: string\n}\n\n/** The context a mailbox's refresh token is sealed under. */\nexport function refreshTokenSealContext(mailboxId: string): string {\n  return `${OUTREACH_COLLECTIONS.mailboxCredentials}/${mailboxId}#refreshToken`\n}\n\n/** Seals a refresh token for one mailbox under the keyring's current key. */\nexport function sealMailboxRefreshToken(\n  refreshToken: string,\n  mailboxId: string,\n  keyring: SecretBoxKeyring,\n): { sealedRefreshToken: string; tokenKeyId: string } {\n  return {\n    sealedRefreshToken: sealSecret(refreshToken, keyring.current, {\n      context: refreshTokenSealContext(mailboxId),\n    }),\n    tokenKeyId: keyring.current.id,\n  }\n}\n\n/**\n * Opens a stored credential's refresh token. Throws `SecretBoxError` when it\n * cannot be opened — a missing or rotated-away key, or a tampered value.\n */\nexport function openMailboxRefreshToken(\n  credential: Pick<OutreachGoogleMailboxCredentials, 'mailboxId' | 'sealedRefreshToken'>,\n  keyring: SecretBoxKeyring,\n): { refreshToken: string; needsReseal: boolean } {\n  const opened = openSecret(credential.sealedRefreshToken, keyring, {\n    context: refreshTokenSealContext(credential.mailboxId),\n  })\n  return { refreshToken: opened.plaintext, needsReseal: needsReseal(opened, keyring) }\n}\n\n/**\n * The id a member's mailbox for one Google account has in one organization.\n *\n * Derived rather than random, so connecting the same account again updates\n * the same mailbox instead of adding a second one, and two members — or two\n * organizations — connecting one account never share an id. The credential\n * collection is top-level, keyed by this id, so it must be unique across\n * every organization, which is why the org is part of it.\n */\nexport function outreachMailboxId(orgId: string, uid: string, providerAccountId: string): string {\n  const hash = createHash('sha256').update(`${orgId}\\n${uid}\\ngoogle\\n${providerAccountId}`).digest('base64url')\n  return `gm_${hash.slice(0, 24)}`\n}\n\nexport function mailboxCredentialsRef(firestore: FirebaseFirestore.Firestore, mailboxId: string) {\n  return firestore.collection(OUTREACH_COLLECTIONS.mailboxCredentials).doc(mailboxId)\n}\n\nexport function mailboxRef(firestore: FirebaseFirestore.Firestore, orgId: string, mailboxId: string) {\n  return firestore\n    .collection('orgs')\n    .doc(orgId)\n    .collection(OUTREACH_COLLECTIONS.mailboxes)\n    .doc(mailboxId)\n}\n\n/** A stored credential read defensively, or `null` when it is not one. */\nexport function readMailboxCredentials(data: unknown): OutreachGoogleMailboxCredentials | null {\n  const record = (data ?? null) as Partial<OutreachGoogleMailboxCredentials> | null\n  if (\n    !record ||\n    record.provider !== 'google' ||\n    typeof record.mailboxId !== 'string' ||\n    typeof record.orgId !== 'string' ||\n    typeof record.sealedRefreshToken !== 'string' ||\n    !record.sealedRefreshToken\n  ) {\n    return null\n  }\n  return {\n    id: String(record.id ?? record.mailboxId),\n    orgId: record.orgId,\n    mailboxId: record.mailboxId,\n    provider: 'google',\n    connectedByUid: String(record.connectedByUid ?? ''),\n    providerAccountId: String(record.providerAccountId ?? ''),\n    email: String(record.email ?? ''),\n    scopes: Array.isArray(record.scopes) ? record.scopes.map(String) : [],\n    sealedRefreshToken: record.sealedRefreshToken,\n    tokenKeyId: String(record.tokenKeyId ?? ''),\n    createdAtMs: Number(record.createdAtMs) || 0,\n    updatedAtMs: Number(record.updatedAtMs) || 0,\n  }\n}\n\n/**\n * How many OTHER stored credentials hold a grant for the same Google account.\n *\n * Google's revocation ends the whole grant this client holds for an account,\n * not one token, so revoking while another mailbox still uses the account —\n * the same shared inbox connected by two members, or one account connected\n * in two organizations — would silently break that mailbox. A disconnect or\n * an erasure asks this first and leaves the grant alone while it is shared.\n *\n * An erasure names what it is ending anyway — a whole organization's\n * credentials, or every one of a person's — and those are not counted.\n */\nexport async function countOtherCredentialsForAccount(\n  firestore: FirebaseFirestore.Firestore,\n  input: {\n    providerAccountId: string\n    mailboxId: string\n    excludeOrgId?: string\n    excludeMailboxIds?: ReadonlySet<string>\n  },\n): Promise<number> {\n  if (!input.providerAccountId) return 0\n  const snapshot = await firestore\n    .collection(OUTREACH_COLLECTIONS.mailboxCredentials)\n    .where('providerAccountId', '==', input.providerAccountId)\n    .limit(20)\n    .get()\n  return snapshot.docs.filter((doc) => {\n    if (doc.id === input.mailboxId || input.excludeMailboxIds?.has(doc.id)) return false\n    return !input.excludeOrgId || doc.get('orgId') !== input.excludeOrgId\n  }).length\n}\n"],"names":["needsReseal","openSecret","sealSecret","createHash","OUTREACH_COLLECTIONS","refreshTokenSealContext","mailboxId","mailboxCredentials","sealMailboxRefreshToken","refreshToken","keyring","sealedRefreshToken","current","context","tokenKeyId","id","openMailboxRefreshToken","credential","opened","plaintext","outreachMailboxId","orgId","uid","providerAccountId","hash","update","digest","slice","mailboxCredentialsRef","firestore","collection","doc","mailboxRef","mailboxes","readMailboxCredentials","data","record","provider","String","connectedByUid","email","scopes","Array","isArray","map","createdAtMs","Number","updatedAtMs","countOtherCredentialsForAccount","input","snapshot","where","limit","get","docs","filter","excludeMailboxIds","has","excludeOrgId","length"],"mappings":"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"}

package/src/lib/mailboxes/mailbox-erasure.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @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 { PluginOrgEraser } from '@aglyn/aglyn/plugin-manager/plugin-org-erasure';
+import type { PluginUserEraser } from '@aglyn/aglyn/plugin-manager/plugin-user-erasure';
+import { type OutreachRevokeDeps } from './mailbox-revoke';
+/**
+ * OUTREACH'S SHARE OF AN ERASURE (AGL-2978).
+ *
+ * The workspace erasure deletes every stored Outreach grant on its own —
+ * `outreachMailboxCredentials` by its `orgId` field, and the mailboxes and
+ * pending connects with the organization's tree — in any process, whether
+ * or not this plugin is loaded. Deleting the platform's copy leaves the
+ * grant alive at Google, though: listed in the rep's account as an app with
+ * access to their mail until they remove it by hand. So Outreach registers a
+ * workspace eraser (`plugin-org-erasure`) that revokes each grant first,
+ * while the stored credential still exists to revoke it with. It deletes
+ * nothing itself; the erasure's own sweep does that right after.
+ *
+ * An ACCOUNT erasure (`plugin-user-erasure`, AGL-3106) reaches none of it on
+ * its own: a person's mailbox lives under the organization and their grant
+ * in a top-level collection, and the erasure removes the person, not the
+ * organizations they belonged to. So the account eraser below revokes every
+ * grant the person connected and deletes it, with their mailboxes and their
+ * pending connects — their Gmail address and a token that sends as them are
+ * about the person, and must not outlive them.
+ *
+ * Both erasers are registered from the console-only declarations entry:
+ * revoking opens a sealed token with `OUTREACH_TOKEN_KEY`, which only the
+ * console holds.
+ */
+export interface OutreachErasureDeps extends OutreachRevokeDeps {
+    firestore(): FirebaseFirestore.Firestore;
+}
+/** The platform's own dependencies. Specs build their own. */
+export declare function defaultOutreachErasureDeps(): OutreachErasureDeps;
+/**
+ * The workspace eraser: revoke, at Google, every grant the organization
+ * holds. A grant another organization still uses for the same Google
+ * account is kept (`kept`), because revoking it would cut that
+ * organization's mailbox off too. A plan counts the grants and touches
+ * nothing, so its revocation figures are `null` — not measured, not zero.
+ */
+export declare function createOutreachOrgEraser(deps: OutreachErasureDeps): PluginOrgEraser;
+/**
+ * The account eraser (AGL-3106): every mailbox the person connected, in the
+ * organizations they belonged to and in any they had already left, revoked
+ * at Google and deleted with its stored grant; and their pending connects.
+ *
+ * A grant is kept at Google when a TEAMMATE still uses the same Google
+ * account — a shared inbox two members connected — because revoking it would
+ * cut the teammate's mailbox off; the erased person's own copy is deleted
+ * either way. Every other copy the person holds is being erased too, so it
+ * does not count as a use.
+ */
+export declare function createOutreachUserEraser(deps: OutreachErasureDeps): PluginUserEraser;

package/src/lib/mailboxes/mailbox-erasure.js

@@ -0,0 +1,148 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { firebaseAdmin } from "@aglyn/tenant-data-admin/server/firebase-admin";
+import { OUTREACH_COLLECTIONS } from "../model/outreach.types.js";
+import { mailboxCredentialsRef, mailboxRef, readMailboxCredentials } from "./mailbox-credentials.js";
+import { revokeMailboxGrant } from "./mailbox-revoke.js";
+import { outreachOAuthStateRef } from "./oauth-state.js";
+import { readOutreachGoogleConfig } from "./outreach-config.js";
+/** The platform's own dependencies. Specs build their own. */ export function defaultOutreachErasureDeps() {
+    return {
+        firestore: ()=>firebaseAdmin.app().firestore(),
+        readConfig: readOutreachGoogleConfig,
+        transport: {}
+    };
+}
+const emptyTally = ()=>({
+        revoked: 0,
+        alreadyInvalid: 0,
+        kept: 0,
+        failed: 0
+    });
+function count(tally, outcome) {
+    if (outcome === 'revoked') tally.revoked += 1;
+    else if (outcome === 'already-invalid') tally.alreadyInvalid += 1;
+    else if (outcome === 'kept-for-other-mailbox') tally.kept += 1;
+    else tally.failed += 1;
+}
+/** Firestore refuses a batch of more than 500 writes. */ const BATCH_LIMIT = 450;
+/** Deletes every reference, in batches under Firestore's limit. */ async function deleteAll(firestore, refs) {
+    for(let start = 0; start < refs.length; start += BATCH_LIMIT){
+        const batch = firestore.batch();
+        for (const ref of refs.slice(start, start + BATCH_LIMIT))batch.delete(ref);
+        await batch.commit();
+    }
+}
+/**
+ * The workspace eraser: revoke, at Google, every grant the organization
+ * holds. A grant another organization still uses for the same Google
+ * account is kept (`kept`), because revoking it would cut that
+ * organization's mailbox off too. A plan counts the grants and touches
+ * nothing, so its revocation figures are `null` — not measured, not zero.
+ */ export function createOutreachOrgEraser(deps) {
+    return async ({ orgId, dryRun })=>{
+        const firestore = deps.firestore();
+        const rows = await firestore.collection(OUTREACH_COLLECTIONS.mailboxCredentials).where('orgId', '==', orgId).get();
+        if (dryRun) {
+            return {
+                grants: rows.size,
+                revoked: null,
+                alreadyInvalid: null,
+                kept: null,
+                failed: null
+            };
+        }
+        const tally = emptyTally();
+        for (const doc of rows.docs){
+            const credential = readMailboxCredentials(doc.data());
+            count(tally, credential ? await revokeMailboxGrant(firestore, credential, deps, {
+                excludeOrgId: orgId
+            }) : 'failed');
+        }
+        return _extends({
+            grants: rows.size
+        }, tally);
+    };
+}
+/**
+ * The account eraser (AGL-3106): every mailbox the person connected, in the
+ * organizations they belonged to and in any they had already left, revoked
+ * at Google and deleted with its stored grant; and their pending connects.
+ *
+ * A grant is kept at Google when a TEAMMATE still uses the same Google
+ * account — a shared inbox two members connected — because revoking it would
+ * cut the teammate's mailbox off; the erased person's own copy is deleted
+ * either way. Every other copy the person holds is being erased too, so it
+ * does not count as a use.
+ */ export function createOutreachUserEraser(deps) {
+    return async ({ uid, orgIds })=>{
+        const firestore = deps.firestore();
+        // By the person, across every organization — including one they have
+        // already left, which `orgIds` no longer names.
+        const credentials = await firestore.collection(OUTREACH_COLLECTIONS.mailboxCredentials).where('connectedByUid', '==', uid).get();
+        const mailboxes = new Map();
+        const stored = [];
+        for (const doc of credentials.docs){
+            var _ref, _doc_get;
+            const credential = readMailboxCredentials(doc.data());
+            const orgId = (_ref = credential == null ? void 0 : credential.orgId) != null ? _ref : String((_doc_get = doc.get('orgId')) != null ? _doc_get : '');
+            if (credential) stored.push(credential);
+            if (orgId) mailboxes.set(`${orgId}/${doc.id}`, {
+                orgId,
+                mailboxId: doc.id
+            });
+        }
+        // A mailbox whose grant is already gone still names the person's
+        // address; find those under each organization the person was in.
+        for (const orgId of orgIds){
+            const connected = await firestore.collection('orgs').doc(orgId).collection(OUTREACH_COLLECTIONS.mailboxes).where('connectedByUid', '==', uid).get();
+            for (const doc of connected.docs)mailboxes.set(`${orgId}/${doc.id}`, {
+                orgId,
+                mailboxId: doc.id
+            });
+        }
+        const theirs = new Set(credentials.docs.map((doc)=>doc.id));
+        const tally = emptyTally();
+        for (const credential of stored){
+            count(tally, await revokeMailboxGrant(firestore, credential, deps, {
+                excludeMailboxIds: theirs
+            }));
+        }
+        tally.failed += credentials.size - stored.length;
+        const orgsWithPending = new Set([
+            ...orgIds,
+            ...[
+                ...mailboxes.values()
+            ].map((entry)=>entry.orgId)
+        ]);
+        await deleteAll(firestore, [
+            ...credentials.docs.map((doc)=>mailboxCredentialsRef(firestore, doc.id)),
+            ...[
+                ...mailboxes.values()
+            ].map(({ orgId, mailboxId })=>mailboxRef(firestore, orgId, mailboxId)),
+            ...[
+                ...orgsWithPending
+            ].map((orgId)=>outreachOAuthStateRef(firestore, orgId, uid))
+        ]);
+        return _extends({
+            mailboxes: mailboxes.size,
+            grants: credentials.size
+        }, tally);
+    };
+}
+
+//# sourceMappingURL=mailbox-erasure.js.map

package/src/lib/mailboxes/mailbox-erasure.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/mailboxes/mailbox-erasure.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\nimport type {\n  PluginOrgEraser,\n  PluginOrgErasureReport,\n} from '@aglyn/aglyn/plugin-manager/plugin-org-erasure'\nimport type {\n  PluginUserEraser,\n  PluginUserErasureReport,\n} from '@aglyn/aglyn/plugin-manager/plugin-user-erasure'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { OUTREACH_COLLECTIONS } from '../model/outreach.types'\nimport {\n  mailboxCredentialsRef,\n  mailboxRef,\n  readMailboxCredentials,\n  type OutreachGoogleMailboxCredentials,\n} from './mailbox-credentials'\nimport {\n  revokeMailboxGrant,\n  type OutreachGrantRevocation,\n  type OutreachRevokeDeps,\n} from './mailbox-revoke'\nimport { outreachOAuthStateRef } from './oauth-state'\nimport { readOutreachGoogleConfig } from './outreach-config'\n\n/**\n * OUTREACH'S SHARE OF AN ERASURE (AGL-2978).\n *\n * The workspace erasure deletes every stored Outreach grant on its own —\n * `outreachMailboxCredentials` by its `orgId` field, and the mailboxes and\n * pending connects with the organization's tree — in any process, whether\n * or not this plugin is loaded. Deleting the platform's copy leaves the\n * grant alive at Google, though: listed in the rep's account as an app with\n * access to their mail until they remove it by hand. So Outreach registers a\n * workspace eraser (`plugin-org-erasure`) that revokes each grant first,\n * while the stored credential still exists to revoke it with. It deletes\n * nothing itself; the erasure's own sweep does that right after.\n *\n * An ACCOUNT erasure (`plugin-user-erasure`, AGL-3106) reaches none of it on\n * its own: a person's mailbox lives under the organization and their grant\n * in a top-level collection, and the erasure removes the person, not the\n * organizations they belonged to. So the account eraser below revokes every\n * grant the person connected and deletes it, with their mailboxes and their\n * pending connects — their Gmail address and a token that sends as them are\n * about the person, and must not outlive them.\n *\n * Both erasers are registered from the console-only declarations entry:\n * revoking opens a sealed token with `OUTREACH_TOKEN_KEY`, which only the\n * console holds.\n */\n\nexport interface OutreachErasureDeps extends OutreachRevokeDeps {\n  firestore(): FirebaseFirestore.Firestore\n}\n\n/** The platform's own dependencies. Specs build their own. */\nexport function defaultOutreachErasureDeps(): OutreachErasureDeps {\n  return {\n    firestore: () => firebaseAdmin.app().firestore(),\n    readConfig: readOutreachGoogleConfig,\n    transport: {},\n  }\n}\n\n/** How many grants came to each end, for an erasure's audit record. */\ninterface RevocationTally {\n  revoked: number\n  alreadyInvalid: number\n  kept: number\n  failed: number\n}\n\nconst emptyTally = (): RevocationTally => ({ revoked: 0, alreadyInvalid: 0, kept: 0, failed: 0 })\n\nfunction count(tally: RevocationTally, outcome: OutreachGrantRevocation): void {\n  if (outcome === 'revoked') tally.revoked += 1\n  else if (outcome === 'already-invalid') tally.alreadyInvalid += 1\n  else if (outcome === 'kept-for-other-mailbox') tally.kept += 1\n  else tally.failed += 1\n}\n\n/** Firestore refuses a batch of more than 500 writes. */\nconst BATCH_LIMIT = 450\n\n/** Deletes every reference, in batches under Firestore's limit. */\nasync function deleteAll(\n  firestore: FirebaseFirestore.Firestore,\n  refs: readonly FirebaseFirestore.DocumentReference[],\n): Promise<void> {\n  for (let start = 0; start < refs.length; start += BATCH_LIMIT) {\n    const batch = firestore.batch()\n    for (const ref of refs.slice(start, start + BATCH_LIMIT)) batch.delete(ref)\n    await batch.commit()\n  }\n}\n\n/**\n * The workspace eraser: revoke, at Google, every grant the organization\n * holds. A grant another organization still uses for the same Google\n * account is kept (`kept`), because revoking it would cut that\n * organization's mailbox off too. A plan counts the grants and touches\n * nothing, so its revocation figures are `null` — not measured, not zero.\n */\nexport function createOutreachOrgEraser(deps: OutreachErasureDeps): PluginOrgEraser {\n  return async ({ orgId, dryRun }): Promise<PluginOrgErasureReport> => {\n    const firestore = deps.firestore()\n    const rows = await firestore\n      .collection(OUTREACH_COLLECTIONS.mailboxCredentials)\n      .where('orgId', '==', orgId)\n      .get()\n    if (dryRun) {\n      return { grants: rows.size, revoked: null, alreadyInvalid: null, kept: null, failed: null }\n    }\n    const tally = emptyTally()\n    for (const doc of rows.docs) {\n      const credential = readMailboxCredentials(doc.data())\n      count(\n        tally,\n        credential\n          ? await revokeMailboxGrant(firestore, credential, deps, { excludeOrgId: orgId })\n          : 'failed',\n      )\n    }\n    return { grants: rows.size, ...tally }\n  }\n}\n\n/**\n * The account eraser (AGL-3106): every mailbox the person connected, in the\n * organizations they belonged to and in any they had already left, revoked\n * at Google and deleted with its stored grant; and their pending connects.\n *\n * A grant is kept at Google when a TEAMMATE still uses the same Google\n * account — a shared inbox two members connected — because revoking it would\n * cut the teammate's mailbox off; the erased person's own copy is deleted\n * either way. Every other copy the person holds is being erased too, so it\n * does not count as a use.\n */\nexport function createOutreachUserEraser(deps: OutreachErasureDeps): PluginUserEraser {\n  return async ({ uid, orgIds }): Promise<PluginUserErasureReport> => {\n    const firestore = deps.firestore()\n    // By the person, across every organization — including one they have\n    // already left, which `orgIds` no longer names.\n    const credentials = await firestore\n      .collection(OUTREACH_COLLECTIONS.mailboxCredentials)\n      .where('connectedByUid', '==', uid)\n      .get()\n    const mailboxes = new Map<string, { orgId: string; mailboxId: string }>()\n    const stored: OutreachGoogleMailboxCredentials[] = []\n    for (const doc of credentials.docs) {\n      const credential = readMailboxCredentials(doc.data())\n      const orgId = credential?.orgId ?? String(doc.get('orgId') ?? '')\n      if (credential) stored.push(credential)\n      if (orgId) mailboxes.set(`${orgId}/${doc.id}`, { orgId, mailboxId: doc.id })\n    }\n    // A mailbox whose grant is already gone still names the person's\n    // address; find those under each organization the person was in.\n    for (const orgId of orgIds) {\n      const connected = await firestore\n        .collection('orgs')\n        .doc(orgId)\n        .collection(OUTREACH_COLLECTIONS.mailboxes)\n        .where('connectedByUid', '==', uid)\n        .get()\n      for (const doc of connected.docs) mailboxes.set(`${orgId}/${doc.id}`, { orgId, mailboxId: doc.id })\n    }\n\n    const theirs = new Set(credentials.docs.map((doc) => doc.id))\n    const tally = emptyTally()\n    for (const credential of stored) {\n      count(tally, await revokeMailboxGrant(firestore, credential, deps, { excludeMailboxIds: theirs }))\n    }\n    tally.failed += credentials.size - stored.length\n\n    const orgsWithPending = new Set([...orgIds, ...[...mailboxes.values()].map((entry) => entry.orgId)])\n    await deleteAll(firestore, [\n      ...credentials.docs.map((doc) => mailboxCredentialsRef(firestore, doc.id)),\n      ...[...mailboxes.values()].map(({ orgId, mailboxId }) => mailboxRef(firestore, orgId, mailboxId)),\n      ...[...orgsWithPending].map((orgId) => outreachOAuthStateRef(firestore, orgId, uid)),\n    ])\n\n    return {\n      mailboxes: mailboxes.size,\n      grants: credentials.size,\n      ...tally,\n    }\n  }\n}\n"],"names":["firebaseAdmin","OUTREACH_COLLECTIONS","mailboxCredentialsRef","mailboxRef","readMailboxCredentials","revokeMailboxGrant","outreachOAuthStateRef","readOutreachGoogleConfig","defaultOutreachErasureDeps","firestore","app","readConfig","transport","emptyTally","revoked","alreadyInvalid","kept","failed","count","tally","outcome","BATCH_LIMIT","deleteAll","refs","start","length","batch","ref","slice","delete","commit","createOutreachOrgEraser","deps","orgId","dryRun","rows","collection","mailboxCredentials","where","get","grants","size","doc","docs","credential","data","excludeOrgId","createOutreachUserEraser","uid","orgIds","credentials","mailboxes","Map","stored","String","push","set","id","mailboxId","connected","theirs","Set","map","excludeMailboxIds","orgsWithPending","values","entry"],"mappings":"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"}

package/src/lib/mailboxes/mailbox-gate.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @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 { DecodedIdToken } from 'firebase-admin/auth';
+import type { OutreachApiRefusalReason } from './mailbox-api';
+/**
+ * THE GATE EVERY AUTHENTICATED MAILBOX ROUTE CLIMBS (AGL-2978).
+ *
+ * The console dispatcher has already refused a request while
+ * `release_outreach` is off for the organization it names, an unverified
+ * account's token, a lockdown with no org in scope, and a caller over the
+ * console rate limit. What it cannot know is anything about the member, so
+ * each rung below is this plugin's:
+ *
+ *   401  no bearer token, or one the verifier refused
+ *   403  the account's address is unverified (an impersonation session is exempt)
+ *   400  the request did not name an organization
+ *   403  not a member of it, a site collaborator without org-wide reach, or
+ *        without `outreach.use`
+ *   403  the organization does not hold the `outreach` entitlement
+ *   423  lockdown, now with the organization and the account in scope
+ *
+ * `resolveOrgPermissions` is always given the concrete org id. Called without
+ * one it resolves a caller with no org at all as that future org's owner,
+ * which is right for a fresh signup and wrong for every question asked here.
+ */
+export interface OutreachGateDeps {
+    verifyIdToken(idToken: string): Promise<DecodedIdToken>;
+    resolveOrgPermissions(uid: string, context: {
+        orgId: string;
+    }): Promise<{
+        orgId: string | null;
+        /** `null` when the account is not on the organization's roster. */
+        role: string | null;
+        isOwner: boolean;
+        orgWide: boolean;
+        permissions: Partial<Record<string, boolean | undefined>>;
+    }>;
+    readOrg(orgId: string): Promise<Record<string, unknown> | null>;
+    lockdownRefusal(options: {
+        request: Request;
+        staff: boolean;
+        uid: string;
+        org: Record<string, unknown>;
+    }): Promise<Response | null>;
+}
+export interface OutreachGateContext {
+    uid: string;
+    /** The account's sign-in address, lower-cased, when the token carries one. */
+    email: string | null;
+    /** The account's name, when the token carries one. */
+    name: string | null;
+    staff: boolean;
+    orgId: string;
+    org: Record<string, unknown>;
+    /** An owner or admin of the organization, who may manage every mailbox. */
+    isOrgAdmin: boolean;
+}
+/** A refusal in the one shape every mailbox route answers with. */
+export declare function refusal(status: number, reason: OutreachApiRefusalReason, error: string): Response;
+export declare function readOrgId(value: unknown): string | null;
+export declare function outreachMemberGate(request: Request, rawOrgId: unknown, deps: OutreachGateDeps): Promise<Response | OutreachGateContext>;

package/src/lib/mailboxes/mailbox-gate.js

@@ -0,0 +1,98 @@
+/**
+ * @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 { checkEntitlement } from "@aglyn/aglyn/server";
+import { isEmailVerified, isImpersonationSession } from "@aglyn/tenant-data-admin/server/firebase-admin";
+import { invalidIdTokenResponse } from "@aglyn/tenant-data-admin/server/id-token-refusal";
+import { OUTREACH_USE_PERMISSION } from "../constants/bundle-common.js";
+/** A refusal in the one shape every mailbox route answers with. */ export function refusal(status, reason, error) {
+    return Response.json({
+        error,
+        reason
+    }, {
+        status,
+        headers: {
+            'Cache-Control': 'no-store'
+        }
+    });
+}
+/** An organization id as a request may name one: a plain document id. */ const ORG_ID = /^[A-Za-z0-9_-]{1,128}$/;
+export function readOrgId(value) {
+    const orgId = typeof value === 'string' ? value.trim() : '';
+    return ORG_ID.test(orgId) ? orgId : null;
+}
+function bearer(request) {
+    var _request_headers_get;
+    const authorization = (_request_headers_get = request.headers.get('authorization')) != null ? _request_headers_get : '';
+    return authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : null;
+}
+export async function outreachMemberGate(request, rawOrgId, deps) {
+    var _ref;
+    const token = bearer(request);
+    if (!token) return refusal(401, 'unauthenticated', 'Sign in to manage your connected mailboxes.');
+    let decoded;
+    try {
+        decoded = await deps.verifyIdToken(token);
+    } catch (error) {
+        // A refused credential is the caller's; an Auth outage is ours and
+        // propagates, so it answers 500 instead of "sign in again".
+        if (invalidIdTokenResponse(error)) {
+            return refusal(401, 'unauthenticated', 'Your sign-in could not be confirmed. Sign in again.');
+        }
+        throw error;
+    }
+    if (!isEmailVerified(decoded) && !isImpersonationSession(decoded)) {
+        return refusal(403, 'email-unverified', 'Verify your email address before connecting a mailbox.');
+    }
+    const orgId = readOrgId(rawOrgId);
+    if (!orgId) return refusal(400, 'org-required', 'Open an organization before managing its mailboxes.');
+    const membership = await deps.resolveOrgPermissions(decoded.uid, {
+        orgId
+    });
+    // A targeted org the account is not on answers with that org's id and no
+    // role — as does a lookup that failed closed — so the role is the test.
+    if (!membership.role || membership.orgId !== orgId) {
+        return refusal(403, 'not-a-member', 'You are not a member of that organization.');
+    }
+    if (!membership.orgWide) {
+        return refusal(403, 'not-org-wide', 'Sequences covers the whole organization, and your access is to particular sites.');
+    }
+    if (membership.permissions[OUTREACH_USE_PERMISSION] !== true) {
+        return refusal(403, 'permission', 'Your role does not include Use Sequences.');
+    }
+    const org = (_ref = await deps.readOrg(orgId)) != null ? _ref : {};
+    if (!checkEntitlement(org, 'outreach')) {
+        return refusal(403, 'entitlement', "Sequences isn't available to this workspace yet.");
+    }
+    const staff = decoded['staff'] === true;
+    const locked = await deps.lockdownRefusal({
+        request,
+        staff,
+        uid: decoded.uid,
+        org
+    });
+    if (locked) return locked;
+    return {
+        uid: decoded.uid,
+        email: typeof decoded.email === 'string' ? decoded.email.trim().toLowerCase() : null,
+        name: typeof decoded['name'] === 'string' ? String(decoded['name']) : null,
+        staff,
+        orgId,
+        org,
+        isOrgAdmin: membership.isOwner
+    };
+}
+
+//# sourceMappingURL=mailbox-gate.js.map

package/src/lib/mailboxes/mailbox-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/mailboxes/mailbox-gate.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\nimport { checkEntitlement } from '@aglyn/aglyn/server'\nimport {\n  isEmailVerified,\n  isImpersonationSession,\n} from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { invalidIdTokenResponse } from '@aglyn/tenant-data-admin/server/id-token-refusal'\nimport type { DecodedIdToken } from 'firebase-admin/auth'\nimport { OUTREACH_USE_PERMISSION } from '../constants/bundle-common'\nimport type { OutreachApiRefusalReason } from './mailbox-api'\n\n/**\n * THE GATE EVERY AUTHENTICATED MAILBOX ROUTE CLIMBS (AGL-2978).\n *\n * The console dispatcher has already refused a request while\n * `release_outreach` is off for the organization it names, an unverified\n * account's token, a lockdown with no org in scope, and a caller over the\n * console rate limit. What it cannot know is anything about the member, so\n * each rung below is this plugin's:\n *\n *   401  no bearer token, or one the verifier refused\n *   403  the account's address is unverified (an impersonation session is exempt)\n *   400  the request did not name an organization\n *   403  not a member of it, a site collaborator without org-wide reach, or\n *        without `outreach.use`\n *   403  the organization does not hold the `outreach` entitlement\n *   423  lockdown, now with the organization and the account in scope\n *\n * `resolveOrgPermissions` is always given the concrete org id. Called without\n * one it resolves a caller with no org at all as that future org's owner,\n * which is right for a fresh signup and wrong for every question asked here.\n */\n\nexport interface OutreachGateDeps {\n  verifyIdToken(idToken: string): Promise<DecodedIdToken>\n  resolveOrgPermissions(\n    uid: string,\n    context: { orgId: string },\n  ): Promise<{\n    orgId: string | null\n    /** `null` when the account is not on the organization's roster. */\n    role: string | null\n    isOwner: boolean\n    orgWide: boolean\n    permissions: Partial<Record<string, boolean | undefined>>\n  }>\n  readOrg(orgId: string): Promise<Record<string, unknown> | null>\n  lockdownRefusal(options: {\n    request: Request\n    staff: boolean\n    uid: string\n    org: Record<string, unknown>\n  }): Promise<Response | null>\n}\n\nexport interface OutreachGateContext {\n  uid: string\n  /** The account's sign-in address, lower-cased, when the token carries one. */\n  email: string | null\n  /** The account's name, when the token carries one. */\n  name: string | null\n  staff: boolean\n  orgId: string\n  org: Record<string, unknown>\n  /** An owner or admin of the organization, who may manage every mailbox. */\n  isOrgAdmin: boolean\n}\n\n/** A refusal in the one shape every mailbox route answers with. */\nexport function refusal(status: number, reason: OutreachApiRefusalReason, error: string): Response {\n  return Response.json({ error, reason }, { status, headers: { 'Cache-Control': 'no-store' } })\n}\n\n/** An organization id as a request may name one: a plain document id. */\nconst ORG_ID = /^[A-Za-z0-9_-]{1,128}$/\n\nexport function readOrgId(value: unknown): string | null {\n  const orgId = typeof value === 'string' ? value.trim() : ''\n  return ORG_ID.test(orgId) ? orgId : null\n}\n\nfunction bearer(request: Request): string | null {\n  const authorization = request.headers.get('authorization') ?? ''\n  return authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : null\n}\n\nexport async function outreachMemberGate(\n  request: Request,\n  rawOrgId: unknown,\n  deps: OutreachGateDeps,\n): Promise<Response | OutreachGateContext> {\n  const token = bearer(request)\n  if (!token) return refusal(401, 'unauthenticated', 'Sign in to manage your connected mailboxes.')\n  let decoded: DecodedIdToken\n  try {\n    decoded = await deps.verifyIdToken(token)\n  } catch (error) {\n    // A refused credential is the caller's; an Auth outage is ours and\n    // propagates, so it answers 500 instead of \"sign in again\".\n    if (invalidIdTokenResponse(error)) {\n      return refusal(401, 'unauthenticated', 'Your sign-in could not be confirmed. Sign in again.')\n    }\n    throw error\n  }\n  if (!isEmailVerified(decoded) && !isImpersonationSession(decoded)) {\n    return refusal(403, 'email-unverified', 'Verify your email address before connecting a mailbox.')\n  }\n\n  const orgId = readOrgId(rawOrgId)\n  if (!orgId) return refusal(400, 'org-required', 'Open an organization before managing its mailboxes.')\n\n  const membership = await deps.resolveOrgPermissions(decoded.uid, { orgId })\n  // A targeted org the account is not on answers with that org's id and no\n  // role — as does a lookup that failed closed — so the role is the test.\n  if (!membership.role || membership.orgId !== orgId) {\n    return refusal(403, 'not-a-member', 'You are not a member of that organization.')\n  }\n  if (!membership.orgWide) {\n    return refusal(403, 'not-org-wide', 'Sequences covers the whole organization, and your access is to particular sites.')\n  }\n  if (membership.permissions[OUTREACH_USE_PERMISSION] !== true) {\n    return refusal(403, 'permission', 'Your role does not include Use Sequences.')\n  }\n\n  const org = (await deps.readOrg(orgId)) ?? {}\n  if (!checkEntitlement(org, 'outreach')) {\n    return refusal(403, 'entitlement', \"Sequences isn't available to this workspace yet.\")\n  }\n  const staff = decoded['staff'] === true\n  const locked = await deps.lockdownRefusal({ request, staff, uid: decoded.uid, org })\n  if (locked) return locked\n\n  return {\n    uid: decoded.uid,\n    email: typeof decoded.email === 'string' ? decoded.email.trim().toLowerCase() : null,\n    name: typeof decoded['name'] === 'string' ? String(decoded['name']) : null,\n    staff,\n    orgId,\n    org,\n    isOrgAdmin: membership.isOwner,\n  }\n}\n"],"names":["checkEntitlement","isEmailVerified","isImpersonationSession","invalidIdTokenResponse","OUTREACH_USE_PERMISSION","refusal","status","reason","error","Response","json","headers","ORG_ID","readOrgId","value","orgId","trim","test","bearer","request","authorization","get","startsWith","slice","length","outreachMemberGate","rawOrgId","deps","token","decoded","verifyIdToken","membership","resolveOrgPermissions","uid","role","orgWide","permissions","org","readOrg","staff","locked","lockdownRefusal","email","toLowerCase","name","String","isOrgAdmin","isOwner"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gBAAgB,QAAQ,sBAAqB;AACtD,SACEC,eAAe,EACfC,sBAAsB,QACjB,iDAAgD;AACvD,SAASC,sBAAsB,QAAQ,mDAAkD;AAEzF,SAASC,uBAAuB,QAAQ,gCAA4B;AA4DpE,iEAAiE,GACjE,OAAO,SAASC,QAAQC,MAAc,EAAEC,MAAgC,EAAEC,KAAa;IACrF,OAAOC,SAASC,IAAI,CAAC;QAAEF;QAAOD;IAAO,GAAG;QAAED;QAAQK,SAAS;YAAE,iBAAiB;QAAW;IAAE;AAC7F;AAEA,uEAAuE,GACvE,MAAMC,SAAS;AAEf,OAAO,SAASC,UAAUC,KAAc;IACtC,MAAMC,QAAQ,OAAOD,UAAU,WAAWA,MAAME,IAAI,KAAK;IACzD,OAAOJ,OAAOK,IAAI,CAACF,SAASA,QAAQ;AACtC;AAEA,SAASG,OAAOC,OAAgB;QACRA;IAAtB,MAAMC,iBAAgBD,uBAAAA,QAAQR,OAAO,CAACU,GAAG,CAAC,4BAApBF,uBAAwC;IAC9D,OAAOC,cAAcE,UAAU,CAAC,aAAaF,cAAcG,KAAK,CAAC,UAAUC,MAAM,IAAI;AACvF;AAEA,OAAO,eAAeC,mBACpBN,OAAgB,EAChBO,QAAiB,EACjBC,IAAsB;QAmCT;IAjCb,MAAMC,QAAQV,OAAOC;IACrB,IAAI,CAACS,OAAO,OAAOvB,QAAQ,KAAK,mBAAmB;IACnD,IAAIwB;IACJ,IAAI;QACFA,UAAU,MAAMF,KAAKG,aAAa,CAACF;IACrC,EAAE,OAAOpB,OAAO;QACd,mEAAmE;QACnE,4DAA4D;QAC5D,IAAIL,uBAAuBK,QAAQ;YACjC,OAAOH,QAAQ,KAAK,mBAAmB;QACzC;QACA,MAAMG;IACR;IACA,IAAI,CAACP,gBAAgB4B,YAAY,CAAC3B,uBAAuB2B,UAAU;QACjE,OAAOxB,QAAQ,KAAK,oBAAoB;IAC1C;IAEA,MAAMU,QAAQF,UAAUa;IACxB,IAAI,CAACX,OAAO,OAAOV,QAAQ,KAAK,gBAAgB;IAEhD,MAAM0B,aAAa,MAAMJ,KAAKK,qBAAqB,CAACH,QAAQI,GAAG,EAAE;QAAElB;IAAM;IACzE,yEAAyE;IACzE,wEAAwE;IACxE,IAAI,CAACgB,WAAWG,IAAI,IAAIH,WAAWhB,KAAK,KAAKA,OAAO;QAClD,OAAOV,QAAQ,KAAK,gBAAgB;IACtC;IACA,IAAI,CAAC0B,WAAWI,OAAO,EAAE;QACvB,OAAO9B,QAAQ,KAAK,gBAAgB;IACtC;IACA,IAAI0B,WAAWK,WAAW,CAAChC,wBAAwB,KAAK,MAAM;QAC5D,OAAOC,QAAQ,KAAK,cAAc;IACpC;IAEA,MAAMgC,OAAO,OAAA,MAAMV,KAAKW,OAAO,CAACvB,kBAAnB,OAA8B,CAAC;IAC5C,IAAI,CAACf,iBAAiBqC,KAAK,aAAa;QACtC,OAAOhC,QAAQ,KAAK,eAAe;IACrC;IACA,MAAMkC,QAAQV,OAAO,CAAC,QAAQ,KAAK;IACnC,MAAMW,SAAS,MAAMb,KAAKc,eAAe,CAAC;QAAEtB;QAASoB;QAAON,KAAKJ,QAAQI,GAAG;QAAEI;IAAI;IAClF,IAAIG,QAAQ,OAAOA;IAEnB,OAAO;QACLP,KAAKJ,QAAQI,GAAG;QAChBS,OAAO,OAAOb,QAAQa,KAAK,KAAK,WAAWb,QAAQa,KAAK,CAAC1B,IAAI,GAAG2B,WAAW,KAAK;QAChFC,MAAM,OAAOf,OAAO,CAAC,OAAO,KAAK,WAAWgB,OAAOhB,OAAO,CAAC,OAAO,IAAI;QACtEU;QACAxB;QACAsB;QACAS,YAAYf,WAAWgB,OAAO;IAChC;AACF"}

package/src/lib/mailboxes/mailbox-revoke.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @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 { TransportDeps } from '../transport/http';
+import type { OutreachMailboxDisconnectResponse } from './mailbox-api';
+import { type OutreachGoogleMailboxCredentials } from './mailbox-credentials';
+import type { OutreachGoogleConfigResult } from './outreach-config';
+/**
+ * TELLING GOOGLE A STORED GRANT IS OVER (AGL-2978).
+ *
+ * A disconnect, a workspace erasure and an account erasure all end a
+ * mailbox's grant the same way: open its sealed refresh token with this
+ * deployment's key and revoke it at Google — unless another stored
+ * credential still uses the same Google account, because Google's
+ * revocation ends the whole grant this client holds for the account, and
+ * revoking it would silently break that other mailbox.
+ *
+ * Never throws. A grant that cannot be revoked is still deleted by whoever
+ * called this; the outcome says which happened.
+ */
+/**
+ * What became of a grant at Google: `revoked`, `already-invalid`,
+ * `kept-for-other-mailbox` while another credential still uses the account,
+ * or `failed` when Google could not be told — the token would not open, the
+ * deployment is not configured, or Google did not answer.
+ */
+export type OutreachGrantRevocation = OutreachMailboxDisconnectResponse['revocation'];
+export interface OutreachRevokeDeps {
+    readConfig(): OutreachGoogleConfigResult;
+    /** The network and retry policy the revocation call uses. */
+    transport: TransportDeps;
+}
+export interface RevokeMailboxGrantOptions {
+    /**
+     * Credentials of this organization do not count as another use of the
+     * account: the workspace erasure is ending all of them.
+     */
+    excludeOrgId?: string;
+    /**
+     * These credentials do not count as another use of the account either:
+     * the account erasure is ending every one of the person's grants.
+     */
+    excludeMailboxIds?: ReadonlySet<string>;
+}
+/** Revokes one stored grant at Google, unless it is still shared. Never throws. */
+export declare function revokeMailboxGrant(firestore: FirebaseFirestore.Firestore, credential: OutreachGoogleMailboxCredentials, deps: OutreachRevokeDeps, options?: RevokeMailboxGrantOptions): Promise<OutreachGrantRevocation>;