63 lines
2.8 KiB
Markdown
63 lines
2.8 KiB
Markdown
|
# 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.
|