user-engine/history/2026-08-29-security-layer-scope-intent-assessment.md

Security layer model — scope vs intent vs implementation

Date: 2026-08-29 Repository: user-engine Audience: user-engine, gate-house, flex-auth, ops-warden Status: current-state review, not a decision record Sources:

• net-kingdom/SECURITY-COMPANION.md v0.2 (operative form; start here)
• net-kingdom/canon/standards/security-layer-model_v0.7.md (accepted statute)
• net-kingdom/canon/standards/user-engine-boundary-contract_v0.1.md
• INTENT.md and SCOPE.md as adapted this session
• intakes/intakes.md USER-IN-0001
• gate-house broadcast 2026-08-29 (accepted v0.7; nine undeclared repositories)
• working references: ops-warden/layer.yaml, ops-warden/pep-stance.yaml, kings-guard/layer.yaml
• implementation: src/user_engine/service.py, src/user_engine/adapters/flex_auth.py, src/user_engine/adapters/local.py, src/user_engine/domain/models.py, src/user_engine/runtime.py, src/user_engine/projections.py

The statute governs where the companion and the statute disagree. No disagreement was found that this review needed to work around.

---

1. Executive assessment

user-engine is already the product INTENT described before the layer model: a headless user-domain service with ports, a PostgreSQL store, a portal, and a live flex-auth caller. That slice is finished through USER-WP-0023.

The accepted layer model asks for something the product workplans never carried: an own-voice Engine/PIP declaration, a machine-readable conformance surface, and the PEP obligations that attach to any runtime that causes a protected side effect.

Until this session the repository carried only a gate-house review note on INTENT.md that named a layer and admitted the body was unadapted. That is not a declaration (companion §2, statute §11). USER-IN-0001 stayed open.

This review records the declaration, the SCOPE restatement, and the implementation gaps that must move. It does not contest Engine/PIP.

---

2. What we declare, and what we do not contest

Item	Position
Layer	Engine
Role	PIP
Catalog owns	users, accounts, memberships
Boundary contract	unchanged
One decision point	access-engine / flex-auth; we supply claims and enforce results
Contest the proposed layer?	No. Same inputs, same user-domain result. Not inference, not Tooling, not the PDP.

Finding, not a contest. Statute §4 catalogues user-engine as Engine/PIP and does not mark it PEP-shaped. Companion §5 and statute §6.4 say a PEP is any runtime that causes a protected side effect; being PEP-shaped does not change layer. user-engine's production mutations (account lifecycle, memberships, invitations, registration, hat selection, catalog and profile writes) are protected side effects gated on flex-auth. We are PEP-shaped in fact. §13.1 currently inventories ops-warden (published) and ops-mason (missing). user-engine is a third PEP-shaped consumer with no row. One row was already the finding; a silent third is worse.

Raised for gate-house to inventory. We do not ask to be recatalogued as Staff.

---

3. Intent vs scope after the adaptation

INTENT is now the layer declaration plus the previous product aspiration. SCOPE is the implemented product plus the layer obligations that are now in-scope because INTENT adopted them.

Area	INTENT	SCOPE after this session	Implementation
Engine / PIP declaration	Required, own voice, frontmatter	Declared; points at companion and statute	Frontmatter present. No layer.yaml.
Users, accounts, memberships	Own them	Own them	Shipped.
Claims, not decisions	Subject context is a PIP input	Explicit; local double excluded from production	Production asks flex-auth. Hats/facts not yet proven under §6.1. Local port can still decide.
PEP stance map	Published, tested equal to code, inventoried in §13.1	Named as remaining product scope	Fail-closed in FlexAuthHTTPAdapter; unpublished.
Allow lifetime	Every allow has a lifetime	Named as missing	AuthorizationDecision has effect, id, reason, obligations. No TTL or binding.
Evidence bound	No completeness claim; cadence for load-bearing	Named as partial	Local outbox is transactional with mutations. No classification, no cadence.
Tooling contacts	No OpenBao or key-cape admin client	Out of scope	Held. Env-injected secrets. Unused SecretProvider port.
Observation / actuation	Do not assume either exists	Out of scope	Not implemented. Correct.

SCOPE is not silently claiming INTENT's new layer obligations as done. The remaining holes are listed in SCOPE "Current Status" and mapped to USER-WP-0024.

---

4. Implementation assessment against the companion

Companion sections are the working checklist. Statute citations in parentheses.

4.1 Declare your layer (companion §2 / statute §11)

Before this session: undeclared. Gate-house prose in INTENT.md is explicitly not a declaration.

After this session: INTENT.md frontmatter layer: Engine, role: PIP, plus own-voice body. That is the form companion §2 asks for.

Still missing: a machine-readable declaration file equivalent to ops-warden/layer.yaml. Statute §11 allows frontmatter or an equivalent file; the working references use a file because that is what a conformance script can fail a commit against. user-engine has no checker, so a new OpenBao import would not fail the build. Necessity: add layer.yaml and a check adapted from kings-guard (Engine, not Staff; expect no Tooling client, record non-Tooling clients).

4.2 Rules that bind everyone (companion §3 / statute §6, §8, §9.7)

Rule	Shipped behaviour	Gap
One decision point	Production FlexAuthHTTPAdapter POSTs /v1/check. Service _authorize denies on non-allow.	LocalAuthorizationCheckPort is a local PDP (default ALLOW, reason "local"). Runtime assembly uses flex-auth only, but nothing prevents a production constructor from passing the local port.
Compiled data still deciding	Access-control facts and hats are documented as claim templates (docs/hats-realms-services-assets-access-profiles.md). Projections cache profile material only (projections.py).	No test that a consumer cannot treat AccessControlFact or an active hat as an allow. Tenant capability roles are forwarded, not evaluated — held, documented in the architecture blueprint.
Doctrine as a claim	We do not apply zone stance or maturity ourselves.	None for doctrine we author — we author none.
Adaptive systems only tighten	We do not raise authority on missing evidence.	Held. Do not plan around actuation; it is at zero.
Staff never touches Tooling	We are Engine; §5 does not bind this shape the same way. PostgreSQL is the modeled-concept store, not a §4 Tooling row.	Record PostgreSQL, State Hub, and env-injected secrets as non-Tooling / own-store in layer.yaml so the check is total.
Every allow has a lifetime	Not modelled.	AuthorizationDecision must carry a lifetime (TTL or session/obligation binding). Replay of a stored verdict outside that lifetime is a second decision point. Today we do not cache verdicts, which is the safe subset, but we also cannot state a deadline (statute §9.7.2: a PEP MUST state one).

4.3 If you touch Tooling (companion §4 / statute §5)

Catalogued Tooling is key-cape and OpenBao.

Contact	Present?	Shape
OpenBao HTTP/CLI	No	Blocked-clean on a secrets-engine signing/read surface. Runtime secrets come from the environment / projected files (runtime.py).
key-cape admin / LDAP	No	Consumes verified IAM Profile claims (OIDC/JWKS). That is Engine input, not a Staff Tooling client.
PostgreSQL	Yes — own store	Modeled-concept persistence for a PIP. Not §4 Tooling. List it in the declaration so the check is total.
State Hub	Agents writing progress, not the service	Not catalogued. List as non-Tooling. Carve-out sunsets; we do not become a second state plane.

No §5.1/§5.2/§5.3 Staff contact exists. Conformance state for Tooling contact is conforming (Engine with no catalogued Tooling client), provided we declare the own-store and non-Tooling clients rather than leave them silent.

SecretProvider in ports.py has no implementation. Leave it as a port. Do not add an OpenBao adapter to close it.

4.4 If you cause side effects (companion §5 / statute §6.4)

user-engine is PEP-shaped. Four obligations:

1. No side effect without a decision record, or a recorded stance. Mutations go through _authorize then _record_mutation inside store.transaction(). On flex-auth transport/parse failure, FlexAuthHTTPAdapter returns DENY with reason "authorization service unavailable" and a locally minted decision_id (AuthorizationDecision.decision_id default factory). _authorize then writes that id onto the deny audit record. That is a fake decision id, not a recorded stance application. Statute v0.7 obligation 1 is explicit: where the engine is unreachable, record the application of the stance in place of the decision. decision_id must be absent unless a decision was rendered.

2. Do not replay a verdict outside its binding and lifetime. No verdict cache exists in the flex-auth adapter. Good. Negative caching is not used. Keep it that way unless a cache is declared with lifetime. The mechanical replay test (canonical request digest

   • lifetime) is not implemented because we do not replay; still need a lifetime on the decision we hold for the mutation.

3. Publish the unreachable-engine stance map. Shipped behaviour is fail-closed for every call — no per-zone map, no published file, no test that file equals code. runtime.py comment says "Production authorization and delivery are fail-closed HTTP boundaries." That is a comment, which statute §6.4 forbids as the form of a stance. Reference shape: ops-warden/pep-stance.yaml. user-engine's map can be simpler (one protected-system, fail-closed total, including unknown) but it must be total, published, and tested.

4. Stay reconstructable, bounded by evidence (below). Deny audits are written outside the mutation transaction, which is correct (there is no mutation). They currently look like engine decisions.

4.5 Evidence (companion §6 / statute §9.6)

Kind	What we have	Classification
Successful user-domain mutation	append_audit + append_outbox inside the same store.transaction() as the save	Accidental omission of the local record is prevented. Drain to audit-core is after commit (local outbox pattern).
Authorization denial	append_audit in _authorize, not transactional with a mutation	Load-bearing if any control treats absence of a deny as "it was allowed". Today nothing else branches on that record — attributive in practice, load-bearing in intent (denials are the class the statute names).
Membership removal / account disable	Mutation path with outbox	Load-bearing for access-review and for PIP consumers who cache facts.

What we may not claim, and currently do not claim in code:

• the audit record proves it happened;
• there is no record, so it did not happen.

Docs (docs/evidence-gap-examples.md) talk about missing external review references, not about this bound. Completeness of the local trail is easy to over-claim in portal copy and operability docs. Necessity: classify events, declare attributive vs load-bearing, declare a cadence or heartbeat for denials and revocations (rate monitoring will not work at this volume), and never describe the trail as complete.

No production observation exists to cite (companion §10). This review does not.

4.6 Agents (companion §7 / statute §3.4)

The service is an Engine. Agents working the repository are Staff principals. Credential routing is already inlined in AGENTS.md via warden route. No standing user-engine credential is vended to agents. No change to runtime is required; INTENT now states the four agent rules so a future convenience (a long-lived portal token in an agent session, treating tool availability as permission) fails the declaration.

4.7 Conformance state (companion §8 / statute §11)

Question	State
Tooling contact	Conforming — none to catalogued Tooling, once listed
Capability we refuse to take locally (secrets-engine API, actuation, observation)	Blocked-clean — not worse than conforming
PEP stance unpublished; fake decision ids	Undeclared violation of §6.4 until the map and recording ship
Layer declaration	In progress — own-voice frontmatter done; machine-readable file and checker not done

Blocked-clean on actuation and observation is the correct posture. Do not open a kings-guard or OpenBao client to look more complete.

4.8 Railiance workloads (companion §9)

rapp-user-engine is the managed package. Decisions come from flex-auth; credentials from the platform after deploy-time injection; evidence toward audit-core via the outbox. Axis-to-layer mapping is unsettled (statute §20.3); this review does not invent one.

4.9 Estate zeros (companion §10)

Do not cite "observed in operation." Do not plan automatic containment, step-up, or isolation as user-engine work.

---

5. Necessities for the current implementation

Ranked by whether the accepted standard is already violated in shipped behaviour, versus missing declaration machinery.

Must change (shipped behaviour vs v0.7)

1. Stop minting a local decision_id on engine-unavailable DENY. Record stance application (zone or equivalent scope, failure mode, outcome). decision_id present only when flex-auth rendered one.
2. Publish pep-stance.yaml (or equivalent) named from the layer declaration. Total, no implicit default. Test: published map equals FlexAuthHTTPAdapter behaviour. Ask gate-house to add the row to §13.1.
3. Give AuthorizationDecision a lifetime and refuse to treat an allow with no end as a standing grant. Even without a verdict cache, the PEP must state one deadline.

Must add (declaration and checkability)

4. layer.yaml plus a conformance script/test adapted from kings-guard: Engine/PIP, empty tooling_contacts, listed non-Tooling clients (Postgres own-store, State Hub, env secrets, flex-auth Engine API, key-cape OIDC as claim input).
5. Confine LocalAuthorizationCheckPort to tests and explicitly standalone fixtures. Production create_application() already uses flex-auth; make construction of a default-allow adapter in the runtime path fail.

Should add (evidence and PIP contract)

6. Classify local audit/outbox events as load-bearing or attributive. Declare a heartbeat or reconciliation for denials and membership/account revocations. Fix docs language so the trail is never "complete."
7. Prove hats / AccessControlFact are claims. A test that selecting a hat or exporting facts never returns an allow/deny, and a consumer contract sentence in the hats doc and the boundary-facing docs: compiling those facts into a local decision is §6.1.

Do not do

• Do not add an OpenBao or key-cape admin client.
• Do not cache flex-auth allows.
• Do not observe production or build containment.
• Do not treat USER-IN-0001 as closed by the old gate-house note; it closes when this repository's own files declare, which they now do for INTENT, with implementation follow-through on USER-WP-0024.

---

6. Mapping to work

Necessity	Workplan task
Own-voice INTENT + SCOPE + this review	USER-WP-0024-T01 (done this session)
layer.yaml + conformance check	USER-WP-0024-T02
PEP stance map, stance recording, lifetime, local-port confinement	USER-WP-0024-T03
Evidence classification and cadence	USER-WP-0024-T04
Access-control facts as claims	USER-WP-0024-T05
Intake close and §13.1 registration request	USER-WP-0024-T06

---

7. Adoption note for gate-house

user-engine answers USER-IN-0001: Engine, role PIP, in our own voice, in INTENT.md. We do not contest the proposed layer. We raise that we are PEP-shaped for our own mutations and are absent from statute §13.1. Findings against the accepted text remain welcome; this review is one.