Organization-managed Outlook mailboxes — implementation plan

Approved 2026-09-10; in progress, uncommitted and unverified. Implement the canonical design. The cutover plan remains historical; its dead scheduler grants stay removed.

Ownership and integration order

Workers run in parallel against the observed core DTO, not invented function names. Core authority is the shared boundary; web derives actor/org from session, MCP/native from authenticated context. The user's explicit Devin/Fable route supersedes the prior Astra-only preference; the existing lane plan/dual-review waiver remains recorded, not a claim that reviews passed. No merge/deploy authorization.

1. Core identity, storage and OAuth

• Use packages/connectors-core/src/managed-mailbox.ts as the observed DTO seam: metadata/effective rights, read | read_send, internal-only token response and signed managed purpose. Public exports must follow package entrypoints; consumers must not duplicate DTOs.
• Implement schema/RLS in packages/db/src/schema/managed_mailbox.ts and its index; generate via bun db:generate; update packages/db/scripts/provision-roles.ts. Prove org FK/member integrity and service-only encrypted credential access with an isolated database, never the shared dev DB.
• Reuse packages/connector-auth/src/authorize.ts, pkce-state-store.ts, token.ts and tokens/refresh.ts plus existing envelope helpers. Integrate service routes under apps/connectors-api/src/routes/; route names beyond observed code are implementation decisions, not delivered APIs.
• Implement current-membership/admin checks, same-identity reconnect, nonce/PKCE validation and generation-fenced callback/refresh writes. Exercise disconnect/reconnect and grant/member revocation races before exposing token use.

2. Web administration

Add the admin Mailboxes surface within apps/web/app/(settings)/ and existing settings navigation/API patterns. Reuse apps/web/lib/connections/outlook-oauth.ts; extend apps/web/app/api/connectors/outlook/callback/route.ts to dispatch verified signed purpose on the same registered URL while preserving personal OAuth. Do not resurrect /delegation or account classification. Show multiple accounts, safe connection/error states, existing-member read/read+send grants, revoke/reconnect/disconnect; never serialize credential DTOs to the browser.

3. Native and MCP capability

Integrate discovery and selectors in packages/agent-runtime/src/tools/ (existing list-recent-mail.ts, search-mail.ts, read-email-thread.ts, read-email-attachment.ts, mail-send.ts, draft-email.ts, send-newsletter.ts) and apps/mcp-server/src/tools.ts / src/tools/. Cover registrations, schemas, capability admission and execution on both surfaces. Reuse the core authority boundary, not a second grant system.

For attachment-to-Drive, preserve destination ownership in apps/connectors-api/src/lib/personal-drive.ts and src/routes/personal-drive.ts; only source selection changes. Preserve personal defaults, explicit immediate sends, disconnected-feeder knowledge gates and scheduler removal.

Acceptance — check only after attached evidence

• Admin connects two distinct Microsoft accounts without North-user creation; nonadmin administration is denied; personal OAuth still works on the same callback.
• Admin discovery returns all organization mailboxes; nonadmin discovery returns assigned only, with effective rights and no credentials or other members' grants, on native and MCP.
• Read grants permit reads but reject send/draft/newsletter; read+send permits those operations. Revoke, downgrade and member removal deny subsequent affected use; admin implicit rights remain organization-scoped.
• Every listed mail operation preserves omitted-selector personal behavior and rejects explicit unknown/cross-org/unassigned/disconnected/reauth mailbox IDs without fallback, even when personal credentials exist.
• Selected-source message/thread/attachment resolution cannot read another mailbox; attachment-to-own-Drive uses caller destination authority and stays in North Drafts.
• Forged/expired/replayed state, wrong actor/org/redirect/generation and different-identity reconnect fail; personal/managed callback dispatch cannot cross purposes.
• Disconnect or superseding reconnect fences in-flight refresh/callback persistence; revoked grants/member removal cannot be bypassed with cached authority. No stale token write restores access.
• Isolated DB evidence proves RLS, org foreign keys, current-member checks, duplicate identity handling and ordinary-role denial of credential ciphertext; generated migration/provision succeeds.
• Real Mailboxes surface verification covers add, grant, revoke, reconnect/disconnect and denied/error states on synthetic accounts; record any unavailable runtime capability rather than claiming visual proof.
• Later user-manual acceptance connects the existing Tips & Tricks Microsoft account then Careers, uses both under one North principal and confirms original user/history/ownership are untouched.

Verification and evidence boundary

Implementers attach exact commands, results and isolation limits for affected package tests, root bun run lint / bun run typecheck, Next build and native/MCP behavior smokes. Use fresh DB fixtures and synthetic provider behavior; no live sends, Drive writes, account changes or shared services to claim verification. UI checks follow the repository ui-test workflow when a suitable authorized surface exists; do not start a dev server in this lane.

Documentation verification separately parses HTML, checks pair/status/index links, preserves unrelated pages byte-for-byte and runs bun --no-env-file test docs/superpowers/convert-docs-to-html.test.ts (three existing tests). It is not feature verification. Set this pair with bun docs/superpowers/status.ts set managed-outlook-mailboxes in-progress; regenerate STATUS/index without retaining unrelated theme normalization.

User-reported PR #415 / cutover head 2a20299b11 has historical green Actions only. No new-capability gates, live acceptance, completed review or release are claimed. Keep acceptance unchecked until evidence exists; status remains in progress. No automatic Tips & Tricks migration/deletion, no scheduler/ingestion/subscriptions/shared discovery or application-wide Exchange permissions.