email-connect/docs/caller-policy-draft-2026-10-08.md

User-engine caller policy draft — 2026-10-08

This is the historical draft review. The compatible rollout preparation below updates its scope and resolves the source compatibility gap; activation remains open.

This file proposes the only caller that exists today. It is not mounted, EMAIL_CONNECT_CALLERS_FILE is not set, and no token file was created. EMAIL-WP-0008-T03 stays waiting until the bindings, quotas and token custody are approved.

Source: config/callers.user-engine.draft.json.

What the live caller does

user-engine sends invitation mail to /v1/send with source user-engine and templates family_member.invited or family_invitation.resent. It reads /v1/status and /v1/delivery-status. Registration uses /v1/registration-verifications, consume and cancel. The live registration allow-list is tenant tenant:coulomb and client coulomb-social (USER_ENGINE_REGISTRATION_TENANTS / USER_ENGINE_REGISTRATION_CLIENTS in net-kingdom/sso-mfa/k8s/user-engine/runtime.yaml). Mail and verification share the current user-engine-delivery mail-token. Suppression is not a user-engine operation and is omitted.

Proposed limits

rate_per_minute 10 matches the live registration limit of 10 requests per 60 seconds. Burst 5 and an 8 KiB payload cap are below the receiver ceilings (6000/minute, 600 burst, 128 KiB). They are proposals, not an approved quota. adopt_legacy_verifications is proposed so this original caller can still consume verification rows written before caller ids existed.

Gap that blocks activation

Current invitation envelopes carry tenant and do not carry client_id. Scoped send accepts a binding only when both fields are present and admitted, or when both are absent and legacy_invitation_binding is set. A tenant without a client id is denied. Family invitations also use tenants other than tenant:coulomb. This draft therefore does not claim to carry current invitation traffic. Activation needs a user-engine change that sends an admitted tenant/client pair, or a separate reviewed contract change.

The token path in the draft does not exist. Selecting this file on the running receiver would fail startup before serving traffic. Do not copy the shared ingest token into that path as part of this draft.

Compatible rollout preparation — 2026-10-09

User selected the proposed limits and requested glob or regex support. The draft now admits exact tenant:coulomb/coulomb-social plus the proposed case-sensitive tenant:-family and tenant:family- globs with literal client coulomb-social. Only * and ? glob operators are supported; all patterns and actual identifiers are bounded to 128 characters, with at most 128 total exact/pattern pairs. These family naming patterns are proposals rather than a complete tenant inventory. They apply to verification creation and handle consumption/cancellation as well as invitation sends. Suppression remains excluded.

User-engine source accepts opt-in USER_ENGINE_MAIL_CLIENT_BINDINGS, a JSON list matching config/mail-client-bindings.user-engine.draft.json. It resolves one literal client for the actual tenant; missing or ambiguous matches refuse before any HTTP delivery. Only the mail transport gains client_id: audit envelopes and stored outbox payloads retain their original shape. Default unset configuration retains current live behavior. The reviewed patch is retained in deploy/caller-rollout/user-engine-mail-bindings.patch.

adopt_legacy_invitations explicitly reserves original invitation ids for this user-engine caller. A matching old fingerprint can tolerate the added transport client_id, preserving accepted evidence and terminal unknown/permanent outcomes. Other immutable changes still refuse; admission checks precede legacy matching. New events bind the full payload. Other callers cannot opt into this adoption.

The immutable ConfigMap and strategic deployment patch in deploy/caller-rollout pass server dry-run; packaged-evidence-2026-10-09.json binds the local candidate image to the exact caller module under UID10001 and disabled networking. Before activation, deliver a caller-specific token to the separately admitted Secret email-connect-caller-user-engine (key token) and corresponding user-engine custody lane. Do not copy the legacy shared ingest token into that projection. Publish/admit the new receiver image, retain the current ledger/recovery receipt, fence outbox dispatch during coordinated token/policy transition, and set both the receiver policy and user-engine binding configuration. Pending outbox tenants must match the admitted scope before traffic resumes; narrow or add explicit bindings when their names do not match these proposed globs.

The live receiver remains eb3e7b68 in single-caller mode. Capture and rehearsal must be repinned together only when a new receiver image is actually deployed. Policy narrowing/removal preserves ledger evidence but can deny existing links; review rollback with the compatible image and both caller credentials before releasing traffic. Source preparation does not issue a token or select this policy.