# 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.