user-engine/SCOPE.md

SCOPE

Layer

Engine, role PIP — deterministic API for users, accounts, and memberships. Subject context is an input to the authorization decision and never a decision. Protected mutations are PEP-shaped: they consume access-engine (flex-auth) and do not substitute for it.

Declaration: INTENT.md frontmatter. Statute: net-kingdom/canon/standards/security-layer-model_v0.7.md (accepted). Working companion: net-kingdom/SECURITY-COMPANION.md. Boundary contract unchanged: net-kingdom/canon/standards/user-engine-boundary-contract_v0.1.md.

One-Liner

Headless user-domain and identity-domain Engine (PIP) for accounts, identity links, memberships, catalogs, projections, local audit, and events, with an optional in-repo portal. It consumes NetKingdom IAM, authorization, tenant authority, provisioning, and delivery; it does not own them and it does not decide 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 and claim templates;
• identity-context read models for domain consumers;
• PIP exports: subject, membership, and access-control facts for access-engine and other engines to consume as claims;
• 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 of the modeled concept;
• integration ports for claims, flex-auth decisions (including a rotating caller token), provisioning, registration verification, tenant management, outbox delivery, and runtime secrets;
• PEP enforcement of access-engine decisions on user-engine-owned mutations, including a published unreachable-engine stance.

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 / access-engine;
• caching or compiling an authorization decision, including from hats, access profiles, or memberships;
• 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; no OpenBao client here;
• a Keycloak or key-cape admin client;
• 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;
• observing production security events — kings-guard, and currently unstaffed;
• actuation: reduce authority, require step-up, isolate a workload — an Engine concept held at zero estate-wide.

The in-repo portal is an optional surface, not a UI product. Password and MFA screens stay on the identity provider. LocalAuthorizationCheckPort is a test and standalone double, not a production decision point.

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.

user-engine must not become a hidden source of authorization truth. Memberships, hats, and access-control facts are claims. access-engine renders the decision. When access-engine is unreachable, shipped behaviour is fail-closed for protected mutations; that stance still has to be published, tested equal to the code, and recorded as stance application rather than as a minted local decision id.

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
• NetKingdom Security Layer Model v0.7 (accepted) — ~/net-kingdom/canon/standards/security-layer-model_v0.7.md
• Working companion — ~/net-kingdom/SECURITY-COMPANION.md

Current Status

Workplans USER-WP-0001 through USER-WP-0023 are finished. 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.

USER-WP-0024 is the active workplan: layer declaration is in INTENT.md; machine-readable conformance, the published PEP stance map, decision lifetime, evidence cadence, and the access-control-fact claim contract are not yet shipped.

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.

Layer-model residue that is remaining product scope, tracked in USER-WP-0024 and assessed in history/2026-08-29-security-layer-scope-intent-assessment.md:

• no layer.yaml and no conformance check;
• unreachable-engine stance is fail-closed in FlexAuthHTTPAdapter but unpublished, untested against a map, and recorded as a locally minted decision_id;
• AuthorizationDecision carries no lifetime;
• denials have no declared emission cadence or heartbeat;
• LocalAuthorizationCheckPort defaults to allow and is a second decision point if a production runtime ever constructed it.

Against INTENT.md

INTENT is the stable aspiration. Against the pre-layer product aims, the repo still does the job it set out to do. Against the layer declaration now in INTENT, SCOPE is narrower than INTENT on conformance artifacts and PEP obligations.

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.
Engine / PIP declaration in own voice	Met in INTENT.md as of 2026-08-29. Closes the declaration half of USER-IN-0001.
Subject context is a claim, never a decision	Held in production path (FlexAuthHTTPAdapter). Not yet proven for hats/access-control facts under §6.1, and the local double can still decide.
PEP-shaped: no side effect without a decision or recorded stance	Partial. Production asks flex-auth and fail-closes on errors. Stance is unpublished; unavailable DENY mints a local decision_id.
Published unreachable-engine stance map, tested equal to shipped behaviour	Missing.
Every allow has a lifetime	Missing on AuthorizationDecision.
Evidence bound: no completeness claim; cadence for load-bearing events	Partial. Mutations enqueue audit+outbox in the same store transaction. Completeness is not claimed in code; docs do not classify load-bearing vs attributive or declare a cadence.
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.
No OpenBao / key-cape admin client	Held. SecretProvider is an unused port; runtime reads env.

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;
• observing production, or actuating containment — estate-wide zeros, not this repo's gaps to close.

Those remain INTENT, not a hole in SCOPE, except the layer-conformance rows above, which are now SCOPE because INTENT has adopted the accepted standard.