# Plan identity providers and connected mailboxes

Define OIDC, SMTP/Graph, OAuth grant and incoming mailbox boundaries before implementation.

Current baseline: **0.19.0**. Foundation supplies
[connected sending and reading contracts](/foundation/0.19.0/guides/connected-mail/). The [OIDC bridge](/foundation/0.19.0/guides/oidc-login/) supports code flow plus native-token/BFF
integration; product admission,
OAuth acquisition/consent/storage and incoming adapters remain separate work.
No real provider or mailbox configuration is performed.

## Current reusable implementation

Foundation supplies Argon2id through Infrastructure, strong-authentication/MFA
ceremonies, opaque browser/native sessions, transactional EF mappings, MailKit
submission and Scriban rendering. Product hosts supply the identity directory,
trusted authority/principal resolution, migrations and real authorization policy.

The legacy mail port retains one configured SMTP transport. Version 0.8.0 also
supplies connection-bound SMTP/Graph dispatch, Cc/Bcc and reply/thread metadata.
OAuth grant lifecycle, actual reading and attachments remain separate requirements.

## Foundation responsibilities

| Area | Reusable extension | Product-owned boundary |
| --- | --- | --- |
| OIDC | 0.9.0 bridge with maintained ASP.NET Core handler, Google/Apple/explicit Microsoft directory profiles and mandatory bounded intent/completion ports | User creation/linking, trusted directory, primary-proof/MFA mapping, native handoff and allowed deployments; common/organizations issuer policy remains separate |
| Password hashing | Evaluate EF-free Argon2id registration with an Infrastructure compatibility facade | Normalization, password policy, attempts, reset and account lifecycle |
| Mail connections | Provider-neutral references, capabilities, grant/token lifecycle and protected-store ports | Ownership, current authorization, credential persistence, consent and disconnect workflow |
| Sending | Retain SMTP and add a separately selected Microsoft Graph adapter | Sender admission, system versus customer connection selection, durable outbox/retry |
| Reading | Bounded folder/message/continuation/checkpoint contracts; later Graph/IMAP adapters | Durable ingestion, shared mail storage, app projections, leases, retention and privacy |

The confirmed first increment completes SMTP/Graph sending and common connection/
reading contracts. Incoming Graph/IMAP synchronization, attachments and webhook
workers remain a separate increment. New code reuses the existing MimeKit dependency
and .NET HTTP primitives; it introduces no Graph SDK or new OAuth library.

## Identity and mailbox authorization are separate

Signing in through Microsoft authenticates the product user. It does not grant
Graph Mail.Send or Mail.Read, select a mailbox, or authorize a background worker.
Use separate purpose-bound OAuth intents/grants for mailbox access. An ERP/product
session token must never be sent to Graph as a Graph access token. Logging out or
unlinking an identity and disconnecting a mailbox have different effects.

Provider profiles require controlled issuer, audience, signature, state, nonce,
callback and client binding. Google keys identity by stable subject, not email.
Apple requires a server-side signed client secret and specific form-post/first-login
handling. The maintained Apple code-flow profile uses form POST without PKCE; native
SDK exchange has a separate server challenge and explicit nonce convention.
Do not silently weaken a generic PKCE or nonce requirement.
Microsoft needs explicit account-type/tenant-aware issuer handling. Provider-specific
fixtures are not live-provider acceptance. Preserve signed proof versus descriptive
profile data, and never auto-link identities through a matching email address.

Service/shared versus user-owned connections and SMTP/Graph/IMAP are independent
dimensions. Distinguish delegated grants from organizational application access.
Products bind the external organization/mailbox to an authorized connection and
revalidate state/grants per operation. Do not turn a From address into permission
to send as any mailbox. Shared sending needs the applicable Exchange rights.
Exchange application RBAC scopes access, but unscoped Entra grants are additive.

Token and refresh storage needs purpose/connection binding, encryption, CAS/refresh
serialization and disconnect fencing. Products own the actual store and migrations.
No secret belongs in ToString, URLs, errors, traces or public DTOs. Client-supplied
IDs, folders or continuation URLs must not redirect credentials to arbitrary hosts.

## Submission and future synchronization

Keep old constructors/ports compatible or introduce an explicitly versioned richer
request. Declare capability/bounds for recipients, reply/thread headers and attachments.
Separate local operation IDs, RFC Message-ID and provider object/request IDs.
Graph sendMail's HTTP 202 has no response body and establishes acceptance only.
Do not manufacture a delivery receipt or provider ID. Timeouts can have UnknownOutcome;
blind retries and Message-ID do not establish exactly-once delivery. A transport
cannot commit atomically with a product database transaction.

For incoming Graph data, request mailbox-scoped immutable IDs and track folder delta,
continuations, deletions/moves and expired state. Some delegated shared-mailbox grants
cannot create change subscriptions. Treat notifications as wakeups; reconciliation,
subscription renewal and durable checkpoints remain explicit. IMAP keys need folder,
UIDVALIDITY and UID, not Internet Message-ID alone. Reading must not silently change
remote read/move/delete state. Persist ingestion receipts before advancing checkpoints.

Inbound HTML/MIME and attachments remain untrusted bounded data. Do not execute them,
fetch remote images or render raw markup. Shared ingestion and separate authorized app
projections avoid independent apps moving or importing the same remote message blindly.

## Required evidence

- Existing SMTP/session/MFA consumers stay green through independent packaged tests.
- Loopback SMTP, Graph HTTP and token endpoints verify actual request/response handling,
  send acceptance, 401/403/429/5xx, Retry-After, missing permissions and ambiguous outcomes.
- OIDC fixtures exercise valid/invalid signatures, issuer/audience/nonce/state, replay,
  client binding, callback modes and assurance without real provider configuration.
- Products prove PostgreSQL identity/token uniqueness, audit/outbox rollback, concurrent
  refresh/disconnect, reset/link races and recoverable revocation with live admission checks.
- Reading implementations separately prove cursor/UID reset, replay, concurrent ingestion,
  missed notifications, untrusted continuations, malformed MIME and bounded attachments.

## Primary references checked 2026-11-15

- [Google OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect).
- [Apple authentication](https://developer.apple.com/documentation/signinwithapple/authenticating-users-with-sign-in-with-apple)
  and [discovery](https://appleid.apple.com/.well-known/openid-configuration).
- [Microsoft identity claims](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference).
- [Graph sendMail](https://learn.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0)
  and [Exchange application RBAC](https://learn.microsoft.com/en-us/exchange/permissions-exo/application-rbac).
- [Immutable IDs](https://learn.microsoft.com/en-us/graph/outlook-immutable-id),
  [delta](https://learn.microsoft.com/en-us/graph/delta-query-messages) and
  [shared notification constraints](https://learn.microsoft.com/en-us/graph/outlook-change-notifications-overview).
