@aglyn/plugins-outreach 1.0.0-beta.143

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

@@ -0,0 +1,41 @@
+/**
+ * @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 { SecretBoxError } from "@aglyn/shared-util-tools/secret-box";
+import { GmailTransportError } from "../transport/gmail-errors.js";
+import { revokeGoogleToken } from "../transport/google-oauth.js";
+import { countOtherCredentialsForAccount, openMailboxRefreshToken } from "./mailbox-credentials.js";
+/** Revokes one stored grant at Google, unless it is still shared. Never throws. */ export async function revokeMailboxGrant(firestore, credential, deps, options = {}) {
+    try {
+        const others = await countOtherCredentialsForAccount(firestore, {
+            providerAccountId: credential.providerAccountId,
+            mailboxId: credential.mailboxId,
+            excludeOrgId: options.excludeOrgId,
+            excludeMailboxIds: options.excludeMailboxIds
+        });
+        if (others > 0) return 'kept-for-other-mailbox';
+        const config = deps.readConfig();
+        if (!config.configured) return 'failed';
+        const { refreshToken } = openMailboxRefreshToken(credential, config.config.keyring);
+        return await revokeGoogleToken(refreshToken, deps.transport);
+    } catch (error) {
+        if (!(error instanceof GmailTransportError) && !(error instanceof SecretBoxError)) {
+            console.error('[outreach] revoking a mailbox grant failed', error);
+        }
+        return 'failed';
+    }
+}
+
+//# sourceMappingURL=mailbox-revoke.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/mailboxes/mailbox-revoke.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 { SecretBoxError } from '@aglyn/shared-util-tools/secret-box'\nimport { GmailTransportError } from '../transport/gmail-errors'\nimport { revokeGoogleToken } from '../transport/google-oauth'\nimport type { TransportDeps } from '../transport/http'\nimport type { OutreachMailboxDisconnectResponse } from './mailbox-api'\nimport {\n  countOtherCredentialsForAccount,\n  openMailboxRefreshToken,\n  type OutreachGoogleMailboxCredentials,\n} from './mailbox-credentials'\nimport type { OutreachGoogleConfigResult } from './outreach-config'\n\n/**\n * TELLING GOOGLE A STORED GRANT IS OVER (AGL-2978).\n *\n * A disconnect, a workspace erasure and an account erasure all end a\n * mailbox's grant the same way: open its sealed refresh token with this\n * deployment's key and revoke it at Google — unless another stored\n * credential still uses the same Google account, because Google's\n * revocation ends the whole grant this client holds for the account, and\n * revoking it would silently break that other mailbox.\n *\n * Never throws. A grant that cannot be revoked is still deleted by whoever\n * called this; the outcome says which happened.\n */\n\n/**\n * What became of a grant at Google: `revoked`, `already-invalid`,\n * `kept-for-other-mailbox` while another credential still uses the account,\n * or `failed` when Google could not be told — the token would not open, the\n * deployment is not configured, or Google did not answer.\n */\nexport type OutreachGrantRevocation = OutreachMailboxDisconnectResponse['revocation']\n\nexport interface OutreachRevokeDeps {\n  readConfig(): OutreachGoogleConfigResult\n  /** The network and retry policy the revocation call uses. */\n  transport: TransportDeps\n}\n\nexport interface RevokeMailboxGrantOptions {\n  /**\n   * Credentials of this organization do not count as another use of the\n   * account: the workspace erasure is ending all of them.\n   */\n  excludeOrgId?: string\n  /**\n   * These credentials do not count as another use of the account either:\n   * the account erasure is ending every one of the person's grants.\n   */\n  excludeMailboxIds?: ReadonlySet<string>\n}\n\n/** Revokes one stored grant at Google, unless it is still shared. Never throws. */\nexport async function revokeMailboxGrant(\n  firestore: FirebaseFirestore.Firestore,\n  credential: OutreachGoogleMailboxCredentials,\n  deps: OutreachRevokeDeps,\n  options: RevokeMailboxGrantOptions = {},\n): Promise<OutreachGrantRevocation> {\n  try {\n    const others = await countOtherCredentialsForAccount(firestore, {\n      providerAccountId: credential.providerAccountId,\n      mailboxId: credential.mailboxId,\n      excludeOrgId: options.excludeOrgId,\n      excludeMailboxIds: options.excludeMailboxIds,\n    })\n    if (others > 0) return 'kept-for-other-mailbox'\n    const config = deps.readConfig()\n    if (!config.configured) return 'failed'\n    const { refreshToken } = openMailboxRefreshToken(credential, config.config.keyring)\n    return await revokeGoogleToken(refreshToken, deps.transport)\n  } catch (error) {\n    if (!(error instanceof GmailTransportError) && !(error instanceof SecretBoxError)) {\n      console.error('[outreach] revoking a mailbox grant failed', error)\n    }\n    return 'failed'\n  }\n}\n"],"names":["SecretBoxError","GmailTransportError","revokeGoogleToken","countOtherCredentialsForAccount","openMailboxRefreshToken","revokeMailboxGrant","firestore","credential","deps","options","others","providerAccountId","mailboxId","excludeOrgId","excludeMailboxIds","config","readConfig","configured","refreshToken","keyring","transport","error","console"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,cAAc,QAAQ,sCAAqC;AACpE,SAASC,mBAAmB,QAAQ,+BAA2B;AAC/D,SAASC,iBAAiB,QAAQ,+BAA2B;AAG7D,SACEC,+BAA+B,EAC/BC,uBAAuB,QAElB,2BAAuB;AA4C9B,iFAAiF,GACjF,OAAO,eAAeC,mBACpBC,SAAsC,EACtCC,UAA4C,EAC5CC,IAAwB,EACxBC,UAAqC,CAAC,CAAC;IAEvC,IAAI;QACF,MAAMC,SAAS,MAAMP,gCAAgCG,WAAW;YAC9DK,mBAAmBJ,WAAWI,iBAAiB;YAC/CC,WAAWL,WAAWK,SAAS;YAC/BC,cAAcJ,QAAQI,YAAY;YAClCC,mBAAmBL,QAAQK,iBAAiB;QAC9C;QACA,IAAIJ,SAAS,GAAG,OAAO;QACvB,MAAMK,SAASP,KAAKQ,UAAU;QAC9B,IAAI,CAACD,OAAOE,UAAU,EAAE,OAAO;QAC/B,MAAM,EAAEC,YAAY,EAAE,GAAGd,wBAAwBG,YAAYQ,OAAOA,MAAM,CAACI,OAAO;QAClF,OAAO,MAAMjB,kBAAkBgB,cAAcV,KAAKY,SAAS;IAC7D,EAAE,OAAOC,OAAO;QACd,IAAI,CAAEA,CAAAA,iBAAiBpB,mBAAkB,KAAM,CAAEoB,CAAAA,iBAAiBrB,cAAa,GAAI;YACjFsB,QAAQD,KAAK,CAAC,8CAA8CA;QAC9D;QACA,OAAO;IACT;AACF"}

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

@@ -0,0 +1,119 @@
+/**
+ * @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 { PluginWebApiHandler } from '@aglyn/aglyn/server';
+import type { TransportDeps } from '../transport/http';
+import { type OutreachGateDeps } from './mailbox-gate';
+import { type OutreachGoogleConfigResult } from './outreach-config';
+/**
+ * THE MAILBOX ROUTES (AGL-2978): connect a rep's Google mailbox, keep its
+ * settings, pause it, test it, and disconnect it.
+ *
+ * ## The connect, end to end
+ *
+ * 1. `connect` (the member's session) mints a signed, single-use state bound
+ *    to the member and the organization, records its pending entry, and
+ *    answers Google's consent address — offline access, the consent prompt,
+ *    a PKCE challenge and an OpenID nonce, both derived from the state.
+ * 2. Google redirects the browser to `oauth/callback`. That request carries
+ *    no bearer token, so it DOES nothing: it verifies the state's signature,
+ *    finds the organization's console path, and redirects to the Mailboxes
+ *    page with the code in the URL FRAGMENT, where no server and no `Referer`
+ *    sees it. Its release gate was asked about the organization and the
+ *    member the state names (the route's declared subject).
+ * 3. The page takes the code out of the address bar and posts it to
+ *    `connect/complete` with the member's own session. That is where the
+ *    state is consumed, where it is refused if it was minted for anyone else,
+ *    and where the code is exchanged. So a consent screen someone else was
+ *    tricked into completing cannot connect THEIR mailbox to the member who
+ *    started it: the code arrives in the wrong browser, whose session is not
+ *    the state's member.
+ *
+ * ## Refusals, in order, on `connect/complete`
+ *
+ * A state that is invalid, minted for another member or organization,
+ * expired, already used or superseded; a code Google refuses; a grant with no
+ * refresh token; a grant missing `gmail.send` or `gmail.readonly` (the consent
+ * screen lets a person untick them); an ID token that is not about this
+ * exchange or whose address Google has not verified; a Gmail profile whose
+ * address is not the ID token's; and a member at their mailbox limit.
+ *
+ * A grant refused after the code exchange is dropped, not revoked. Google's
+ * revocation ends the whole grant this client holds for the account, and the
+ * same account may already be connected — by this member in another
+ * organization, or by a teammate — so revoking a token this route merely
+ * declines to keep could disconnect a mailbox that is working.
+ *
+ * ## Who may do what
+ *
+ * Every route but the callback climbs `outreachMemberGate`. The member who
+ * connected a mailbox manages it; an organization owner or admin may also
+ * change its settings, pause it and disconnect it — a departing rep's mailbox
+ * has to be stoppable by somebody. Only its own member can send a test from
+ * it, since the test lands in their inbox.
+ */
+export interface OutreachMailboxRouteDeps {
+    firestore(): FirebaseFirestore.Firestore;
+    gate: OutreachGateDeps;
+    readConfig(): OutreachGoogleConfigResult;
+    /** Whether the signing secret the OAuth state needs is configured. */
+    stateSigningConfigured(): boolean;
+    redirectUri(requestUrl: string): string | null;
+    now(): number;
+    /** The network and retry policy every Google call uses. */
+    transport: TransportDeps;
+    consumeRateLimit(key: string, options: {
+        limit: number;
+        windowMs: number;
+    }): Promise<{
+        allowed: boolean;
+    }>;
+    logOrgActivity(orgId: string, actor: {
+        uid: string;
+        email?: string | null;
+    }, action: string, target: {
+        type: typeof OUTREACH_MAILBOX_ACTIVITY_TARGET;
+        id: string;
+        name: string;
+    }): Promise<void>;
+    confirmAliasesByProvider(firestore: FirebaseFirestore.Firestore, input: {
+        orgId: string;
+        uid: string;
+        addresses: readonly string[];
+        nowMs: number;
+    }): Promise<{
+        ok: boolean;
+        confirmed?: string[];
+    }>;
+}
+export interface OutreachMailboxRoutes {
+    availability: PluginWebApiHandler;
+    connect: PluginWebApiHandler;
+    oauthCallback: PluginWebApiHandler;
+    connectComplete: PluginWebApiHandler;
+    settings: PluginWebApiHandler;
+    status: PluginWebApiHandler;
+    test: PluginWebApiHandler;
+    disconnect: PluginWebApiHandler;
+}
+/** Test sends one mailbox may make in an hour. */
+export declare const OUTREACH_TEST_SENDS_PER_HOUR = 5;
+/**
+ * The org activity target a mailbox's rows are filed under: Outreach's own
+ * namespaced resource, which the feed reads as "Mailbox".
+ */
+export declare const OUTREACH_MAILBOX_ACTIVITY_TARGET = "outreach:mailbox";
+export declare function createOutreachMailboxRoutes(deps: OutreachMailboxRouteDeps): OutreachMailboxRoutes;