Activate expanded portal integration gate

docs/user-engine-platform-expansion-contract.md

@@ -0,0 +1,62 @@
+# user-engine platform expansion contract
+
+This contract activates `NK-WP-0024` without weakening the proven portal.
+The current production image continues to use its existing integration path
+until all three endpoints below are deployed and verified together.
+
+## Authorization
+
+user-engine is the protected system and calls flex-auth `POST /v1/check` for
+every domain mutation. Requests use the existing user-engine resource types
+and action names, including `user-engine:user`, `user-engine:membership`,
+`user-engine:invitation`, `user-engine:tenant`, and `user-engine:outbox`.
+
+Policy roles are:
+
+- self: actions whose authorization context has `self=true` and whose target
+  user matches the authenticated subject's user projection;
+- tenant-admin: tenant-scoped membership, invitation, account lifecycle, and
+  recovery actions within the actor's tenant only;
+- platform-admin: tenant creation, platform recovery, outbox delivery, and
+  dead-letter replay across the platform tenant;
+
+The HTTP adapter is fail closed. Unreachable, malformed, timed-out, or
+non-conforming flex-auth responses become a deny decision. The flex-auth
+decision ID is stored on the corresponding user-engine audit record.
+
+Required runtime setting: `USER_ENGINE_FLEX_AUTH_URL`.
+
+## Durable event and mail delivery
+
+The transactional outbox remains the source of delivery state. The worker
+endpoint sends a CloudEvents-like, redacted JSON envelope to the platform
+event receiver and supplies the outbox event ID as `Idempotency-Key`.
+Invitation-created and invitation-resent events are additionally delivered to
+the approved mail receiver using the same idempotency key. Mailbox ownership
+is evidence only and is never passed into an authorization decision as proof
+of authority.
+
+Required runtime settings:
+
+- `USER_ENGINE_EVENT_URL`
+- `USER_ENGINE_MAIL_URL` (optional until the approved receiver exists)
+- `USER_ENGINE_DELIVERY_TOKEN` from the OpenBao-backed runtime lane
+
+Delivery uses bounded attempts already persisted in the user-engine outbox.
+Failures retain a redacted reason, dead-letter at the configured threshold,
+and can be replayed through the platform-operator route.
+
+## Production activation gate
+
+Do not add these environment variables to the live Deployment until:
+
+1. flex-auth has a cluster-local Service and a validated user-engine policy;
+2. the event and mail receivers accept idempotent, authenticated delivery;
+3. their credentials are present under the approved OpenBao user-engine lane;
+4. NetworkPolicies allow only the named receivers;
+5. the deployed failure matrix proves deny/unavailability, receiver failure,
+   dead-letter/replay, invitation expiry/replay, provider outage recovery, and
+   cross-tenant denial.
+
+This gate prevents a partial rollout from making the portal unavailable or
+silently dropping notifications.