Complete identity seams and email login

docs/user-engine-enterprise-identity-extension-points.md

@@ -0,0 +1,87 @@
+# User-engine enterprise identity extension points
+
+## Purpose
+
+This document freezes the compatibility seams for later customer-owned
+directories and identity providers. It does not enable enterprise federation;
+`NK-WP-0011` remains demand-triggered.
+
+## Stable ownership boundaries
+
+| Concern | Authority |
+| --- | --- |
+| Authentication, MFA, federation protocol, upstream session | KeyCape or Keycloak |
+| Customer directory users and groups | Customer directory |
+| Platform user profile, tenant membership and lifecycle projection | user-engine |
+| Fine-grained authorization decision | flex-auth |
+| Credential and secret custody | NetKingdom/OpenBao |
+| Audit evidence | owning service plus platform audit sink |
+
+User-engine must consume verified IAM Profile claims and provider-neutral
+lifecycle events. It must not store enterprise passwords, MFA factors, SAML
+assertions, refresh tokens, or directory administrator credentials.
+
+## Adapter seams
+
+### OIDC and SAML federation
+
+KeyCape/Keycloak terminates OIDC or SAML and emits the same IAM Profile
+envelope used by local identities. Upstream issuer and subject remain
+traceable in a private provenance claim while downstream applications trust
+only the canonical platform issuer.
+
+### SCIM provisioning
+
+A future SCIM adapter translates customer create, update, suspend and delete
+events into idempotent user-engine lifecycle commands. It uses an immutable
+provider object identifier plus tenant identifier as its key. SCIM transport,
+bearer credentials and retry queues stay outside the user-engine domain.
+
+### JIT provisioning
+
+JIT may create a pending platform projection after a successfully verified
+login. It must not grant tenant-admin or platform authority solely from an
+unmapped upstream claim. Privileged mappings require a pre-approved mapping
+rule or an existing platform-side membership.
+
+### Directory group mapping
+
+Mappings are tenant-scoped, versioned and deny ambiguous multi-tenant
+envelopes. Raw customer group names are never interpreted as platform roles
+without an explicit mapping. Platform roles and `tenant:platform` remain
+reserved.
+
+## Conflict and freshness rules
+
+- Immutable provider subject identifiers win over mutable email addresses.
+- Email is a login/display alias, not the cross-system identity key.
+- Customer-owned attributes are refreshed from the customer source; platform
+  memberships and application preferences remain platform-owned.
+- Suspension or offboarding from an authoritative customer source fails
+  closed for new sessions and invalidates cached authorization projections.
+- Duplicate email or provider-subject collisions enter reconciliation; they
+  are never merged automatically.
+- Events carry provider version/time, correlation ID and idempotency key.
+  Older events cannot overwrite newer state.
+- A stale connector cannot silently reactivate a suspended identity.
+
+## Offboarding and failure behavior
+
+Customer offboarding first blocks authentication, then suspends the
+user-engine tenant account and emits revocation/audit events. Destructive
+profile deletion is delayed by retention policy. Provider outage preserves
+the last known projection but does not bypass authentication, MFA, suspension
+or freshness limits.
+
+## Demand triggers
+
+Enterprise implementation begins only when a named tenant supplies:
+
+- protocol and provider choice;
+- authoritative attribute/group contract;
+- lifecycle and offboarding SLA;
+- acceptable freshness window;
+- tenant-specific role mappings;
+- test tenant and rollback owner.
+
+Until then, local LLDAP plus KeyCape remains the managed identity path.