user-engine/SCOPE.md

# SCOPE

## One-Liner

Headless user-domain and identity-domain service for accounts, identity
links, memberships, catalogs, projections, audit, and events, with an
optional in-repo portal. It consumes NetKingdom IAM, authorization, tenant
authority, provisioning, and delivery; it does not own them.

## In Scope

- user and account records, and account lifecycle state;
- external identity links keyed by `(issuer, subject)`;
- actor, authenticated-subject, authorization-principal, and user-context
  mappings from verified IAM Profile claims;
- global, tenant, application, and membership profile values and
  preferences;
- tenant, application, team, and scope memberships;
- hats, realms, services, assets, access profiles, and active access
  context as user-domain facts;
- identity-context read models for domain consumers;
- canon interface cards, entity and relationship mappings, and explicit
  gap records;
- application registry for profile consumers;
- customization catalog registry, versioning, and validation;
- effective profile resolution and projections (self-service, admin,
  application runtime, audit, agent, claims-enrichment);
- local audit records and durable outbox events;
- local evidence references derived from audit and events;
- invitations, prepared accounts, entitlement claims, and onboarding
  journeys that user-engine owns;
- public registration *orchestration* (start, verify, resume, cancel,
  provider handoff) behind an explicit runtime flag;
- provider-neutral tenant lifecycle *calls* to the tenant authority
  (create, read, update, retire, reactivate, recover);
- optional CSRF-protected portal over the same APIs (self-service,
  onboarding, tenant admin, platform operator);
- standalone/local fixtures and a production PostgreSQL store;
- integration ports for claims, flex-auth decisions (including a rotating
  caller token), provisioning, registration verification, tenant
  management, outbox delivery, and runtime secrets.

## Out Of Scope

- login, OIDC/SAML token issuance, passwords, passkeys, sessions, and MFA
  lifecycle — `key-cape`, Keycloak, or `local-identity`;
- final authorization policy decisions and the protected-system registry —
  `flex-auth`;
- durable authorization grants beyond user-engine-owned memberships;
- tenant identifier authority, grouping reclassification, and capability
  role grants — `tenant-engine`;
- application-owned first-login profiles, unlink, and action step-up —
  consuming apps (e.g. coulomb-social) and KeyCape client policy;
- policy, control, access-review, exception, and organization
  source-of-truth ownership;
- runtime secret custody — OpenBao / Railiance;
- platform audit store and transactional SMTP — `audit-core` and
  `email-connect`;
- full SCIM server, enterprise directory replacement, or inbound
  SAML/OIDC federation (demand-triggered; Keycloak expanded mode is the
  published path);
- a generic extracted profile engine.

The in-repo portal is an optional surface, not a UI product. Password and
MFA screens stay on the identity provider.

## Boundary Rule

user-engine owns user-domain facts, identity-context mappings, and
projections. Adjacent systems provide authentication, IAM claims,
authorization decisions, tenant authority, policy/control definitions,
deployment, event transport, durable audit, secrets, organization records,
or additional UI — and they integrate through explicit adapters. They must
not become hidden sources of profile or identity-domain truth.

Governing published contracts:

- IAM Profile v0.3 — https://policy.coulomb.social/standards/iam-profile/v0.3/
- Tenancy Posture v0.1 — https://policy.coulomb.social/standards/tenancy-posture/v0.1/
- NetKingdom architecture — https://policy.coulomb.social/architecture/net-kingdom/v0.1/
- User-engine boundary contract (accepted, not yet published) —
  `~/net-kingdom/canon/standards/user-engine-boundary-contract_v0.1.md`

## Current Status

Workplans `USER-WP-0001` through `USER-WP-0023` are finished. There is no
active workplan. The isolated MVP, multi-tenancy, catalogs, canon
alignment, durable PostgreSQL store, self-service and admin portal,
public-registration orchestration, and flex-auth caller identity (live A2
on `flex-auth-user-engine`) are in the repo and, where applicable, on
Railiance.

Still operator-owned, not remaining product scope:

- public registration and outbox mail stay fail-closed until governed
  OpenBao verification/delivery tokens and the transactional SMTP lane
  are installed;
- the live tenant-lifecycle probe from a user-engine pod (GET / PATCH /
  retire / reactivate on a disposable tenant) is still owed;
- `policy.enabled` and tenant-engine caller `enforce` belong to flex-auth
  / tenant-engine.

## Against INTENT.md

INTENT is the stable aspiration. Against it, the repo now does the job it
set out to do.

| INTENT aim | Status |
| --- | --- |
| Headless user-domain service, provider- and PDP-agnostic | Met. Ports and adapters; production uses IAM Profile v0.3 and flex-auth. |
| Standalone now, multi-tenant / multi-app later | Met. Fixtures and in-memory conformance plus live PostgreSQL and Railiance. |
| Users, links, memberships, catalogs, projections, events | Met. |
| NetKingdom identity-domain integration layer | Met for the owned slice. Consumes KeyCape, flex-auth, tenant-engine, identity-provisioner, audit-core, email-connect. |
| Applications answer who / which scopes / what to project | Met via `/me`, identity context, catalogs, and projections. |
| Not an IdP, PDP, secret store, directory, or org authority | Held. |
| Optional UI, not UI-driven | Held, with a narrower reading: an optional portal now lives *in this repo* over the same APIs. INTENT's "not a UI application" still applies to product identity. |
| Canon-aligned mappings without taking IAM as SoT | Met (`USER-WP-0007`, interface card). Access-review, policy, and control remain references, not owned records. |
| Path from local setup to governed NetKingdom deploy | Met. |

Still aspirational, and deliberately not started here:

- inbound federation / SCIM / directory sync — new workplan only on tenant
  demand, targeting published Keycloak expanded mode;
- first-class access-review and governance records;
- a dedicated agent consumption product (projections exist);
- extracting a generic profile engine.

Those remain INTENT, not a hole in SCOPE.