Inbound federation (ADM_03)

Flow at a glance

Revoke propagation across instances takes ≤ 30 s via a per-user LRU cache window.

Endpoints

MedSuite accepts signed JWTs from registered partners for two flows:

Flow	Endpoint	When
SSO handoff	POST /sso/jwt	A partner-authenticated user lands in a MedSuite tenant session.
API bearer	Authorization: Bearer <partner-JWT> on /api/*	A partner service calls MedSuite APIs on behalf of a user, with scope intersection.

A third endpoint, POST /sso/revoke, lets the partner terminate the relationship — flipping the federated identity, disabling the linked MedSuite user, and watermarking the user's tokens as invalid.

Trust model

• Asymmetric only. Verifier accepts RS256/384/512, ES256/384/512, and EdDSA. HMAC is rejected at the algorithm layer so a master-DB breach cannot mint partner JWTs.
• Single-use jti. Every verified token has its jti written to security.federation_nonce keyed by (partner_id, jti). A replay fails with FEDERATION_NONCE_REPLAY.
• exp - iat ≤ 300s. Tokens with too-long lifetimes are rejected outright.
• Audience must match. The partner's audience is set in the trust-registry row; tokens with the wrong aud are rejected as FEDERATION_AUDIENCE_MISMATCH.

Three roles, three policies

Per (partner, tenant) link:

• Linking mode — how a partner subject becomes a MedSuite user: link_only (pre-link required), auto_link_by_email, or auto_provision.
• API access — allow_api_access toggles whether the partner can use purpose: 'api' JWTs as Bearer tokens at all. allowed_scopes intersects with the linked user's permission set on every API call.
• MFA trust — partner-wide mfa_trust_policy decides whether routes requiring step-up MFA accept a federated session (always_challenge | trust_for_window | full_trust).

What's where

Surface	Owner	What it does
/federation on the platform console	Platform admin	Trust registry — register partners, manage signing keys, link tenants. API paths keep the /platform/federation prefix.
/admin/federation	Tenant admin	Per-tenant policy — linking mode, allowed scopes, role mapping.
/admin/federation/activity	Tenant admin	Master-audit projection scoped to the caller's tenant.
tsx apps/rcm-core/src/scripts/register-federation-partner.ts	Operator	Bootstrap when the SPA isn't reachable.
tsx apps/rcm-core/src/scripts/revoke-federated-user.ts	Operator	Forced revoke.
tsx apps/rcm-core/src/scripts/rotate-federation-key.ts	Operator	Single-transaction key swap.