coulomb/tenant-engine
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
tenant-engine/INTENT.md
tegwick 807f8db07c Note NetKingdom layering review in INTENT 
Records this repository's layer in the NetKingdom IT-security layer model
(Taxonomy / Tooling / Engines / Staff) and what should change in this INTENT
as a result. Links to the review that established the model:
gate-house/history/2026-08-28-security-layer-model-and-gate-house-recut.md

The note flags pending adaptation only; the body is unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 2564823@bnt-lap001
Assistant-Session: 2a7ed827-4928-4b9f-8613-9135c9cadfe9
2026-08-28 20:33:43 +02:00

7.3 KiB
Raw Blame History

repo updated
tenant-engine 2026-07-23

INTENT

NetKingdom layering review — 2026-08-28. This repository's role was reviewed against the NetKingdom IT-security layer model: Taxonomy → Tooling → Engines → Staff, layered by determinism and by the kind of artifact each layer produces. Findings and the argument behind them: gate-house/history/2026-08-28-security-layer-model-and-gate-house-recut.md. The model as currently stated is gate-house/INTENT.md § "Where Gate House Sits"; it is ruled to become a net-kingdom/canon/standards/ standard, not yet written.

The layer rule that binds every repository: Staff never touches tooling directly. It acts only through engine APIs.

This repository is Engine — deterministic API for a modeled concept. Add the layer label. The existing boundary contract (net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md) holds unchanged. Same clarification as user-engine: tenancy context is an input to the decision, not a decision.

This note records what should change. The body below is not yet adapted.

Purpose

tenant-engine exists to be the single, canonical source of truth for what a tenant is on the NetKingdom platform — its existence, its onboarding grouping, its capability roles, and its plan/subscription assignment — separate from who its users are (user-engine), who authenticates it (key-cape/Keycloak), who authorizes actions against it (flex-auth), and what it pays for a given plan (adaptive-pricing).

Full ownership boundary, formally: net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md.

Why This Exists

No service in the fleet currently owns tenant-as-an-entity facts as a queryable resource. user-engine's own boundary contract explicitly scopes it to consuming tenant identifiers and storing records scoped by a tenant — not owning the tenant record itself. The IAM Profile defines the shape of the tenant claim, not a live directory of which tenants exist, what they're allowed to do, or what plan they're on.

That gap became concrete during Binky Hedgehog GmbH's onboarding as the platform's first tenant outside tenant:coulomb (key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md): a tenant's capability roles (PLTF/IAM/VEN/CUS, non-exclusive — a tenant can hold several at once, and its roles can change independently of how it was onboarded) needed a real owner, a real carrying mechanism, and a real governance model (role grants are usually a consequence of a paid plan). See net-kingdom/docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md and ADR-0014-tenant-capability-roles-and-tenant-engine-ownership.md.

Primary Utility

tenant-engine provides:

  • Tenant records: existence, identifier, and onboarding grouping (trial/friendly/single/small/medium/large/enterprise/ consumer/family/community/association/agentic, per ADR-0013).
  • Capability role grants: PLTF/IAM/VEN/CUS, with an audited grant/revoke trail linking most grants to a plan-assignment change.
  • Plan/subscription assignment: which adaptive-pricing plan a tenant currently holds, referenced by id — never a duplicated copy of plan terms.
  • A cache-read API key-cape calls at token-issuance time to source the optional tenant_roles token claim (IAM Profile v0.3).
  • A live-lookup API flex-auth calls synchronously for privileged, high-stakes decisions — the case where a cached claim isn't trustworthy enough (a stale VEN grant surviving a plan cancellation is not an acceptable risk for money-movement or credential-vending actions).
  • Reserved, not yet implemented: guardrail/quota policy (spend limits, entity/action counts) — trial-grouped tenants default to a zero spend budget; design is future work.

Intended Users

  • key-cape / Keycloak, at token issuance time (cache-read API).
  • flex-auth, at authorization-decision time (live-lookup API, and the target of write-authorization for grant/revoke/plan mutations).
  • Operators and tenant administrators, indirectly, through whatever admin surface eventually consumes tenant-engine's APIs (not yet built).
  • adaptive-pricing, as the source tenant-engine references for plan definitions (not the other way around).

Strategic Role

tenant-engine sits beside user-engine, not inside it — a deliberate bounded-context split, not an oversight. user-engine's aggregate root is the person; tenant-engine's is the tenant. Consumers that only need a fast, security-critical tenant-role lookup (flex-auth on every privileged decision, key-cape on every token issuance) should never need to depend on user-engine's much larger surface (registration flows, factor models, family dataspace onboarding) to get it. This matches the fleet's existing convention of many small, single-purpose -engine/-core services rather than one large one.

Responsibility Boundary

tenant-engine owns tenant-as-an-entity facts. It never re-derives or duplicates facts another system already owns.

tenant-engine Owns

  • Tenant existence, identifier, and onboarding grouping.
  • Capability role grants and their audit trail.
  • Plan/subscription assignment (by reference, not by copying plan terms).
  • Reserved: guardrail/quota policy, once designed.

Other Systems Own

Concern Owner
OIDC discovery, login, token issuance key-cape, Keycloak
Tenant identifier format and role vocabulary NetKingdom (IAM Profile, ADR-0013, ADR-0014)
Users, profiles, memberships user-engine
Authorization decisions flex-auth
Pricing-model / plan definitions adaptive-pricing
Runtime secrets OpenBao / secrets-engine
Payment processing Not yet identified — tenant-engine records plan assignment, not payment execution

Non-Goals

  • Not an identity provider. Never issues, verifies, or refreshes tokens.
  • Not a policy decision point. Never makes an authorization decision itself — it answers queries flex-auth issues.
  • Not a billing processor. Records plan assignment, not payment execution.
  • Not a pricing-model engine. References adaptive-pricing plan ids.
  • Not the user/membership domain. Never stores user accounts or profiles.

Governing Principle

This repository should stay focused on the purpose above. Work that changes its authority, ownership boundaries, or operational promises should be captured in a workplan before implementation, and should stay consistent with net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md — if the two drift, the canon contract wins and this file should be corrected.

Related

  • docs/flex-auth-integration.md — how the write API's WriteAuthorizer seam is implemented against a real flex-auth
  • net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md — the formal ownership contract
  • net-kingdom/canon/standards/iam-profile_v0.3.md — the tenant_roles claim and carrying mechanism this service implements
  • net-kingdom/docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md
  • net-kingdom/docs/adr/ADR-0014-tenant-capability-roles-and-tenant-engine-ownership.md
  • key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md — the first tenant this service will record