coulomb/net-kingdom
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
net-kingdom/docs/user-engine-platform-expansion-contract.md
tegwick 29ae3e70c6
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 1s
Details
Activate expanded portal integration gate
2026-08-09 02:00:58 +02:00

2.8 KiB
Raw Blame History

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.