Bootstrap repo: State Hub registration, agent docs, TEN-WP-0001/0002
statehub register + repo-seed template scaffold (CLAUDE.md, .claude/rules/,
registry/). INTENT.md and SCOPE.md rewritten from the generated stub to
match net-kingdom's ratified tenant-engine-boundary-contract_v0.1.md
(Purpose, Responsibility Boundary, Non-Goals). topic_slug corrected from
the auto-assigned custodian default to netkingdom, matching key-cape and
user-engine.
TEN-WP-0001 (bootstrap) complete: files reviewed/refined, stack decided
(Python 3.12 + FastAPI, matching qonto-assistant's convention), first real
workplan seeded.
TEN-WP-0002 drafted: service skeleton, domain model (tenant/grouping/
capability-role/plan-grant), storage layer, and the three boundary-contract
API surfaces (cache-read for key-cape, live-lookup for flex-auth with an
explicit fail-closed requirement, write API behind a WriteAuthorizer seam
since real flex-auth integration is a declared non-goal for this pass).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-23 21:56:07 +02:00
|
|
|
# SCOPE
|
|
|
|
|
|
|
|
|
|
> Lightweight boundary for agents and contributors. Full contract:
|
|
|
|
|
> `net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md`.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## One-liner
|
|
|
|
|
|
|
|
|
|
Canonical owner of tenant-as-an-entity facts for NetKingdom: existence,
|
|
|
|
|
onboarding grouping, capability roles, and plan/subscription assignment.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Core Idea
|
|
|
|
|
|
|
|
|
|
`tenant-engine` answers "what is this tenant, what can it do, and what plan
|
|
|
|
|
is it on" for two consumers: `key-cape` (cached, at token issuance) and
|
|
|
|
|
`flex-auth` (live, for high-stakes decisions). It never stores users,
|
|
|
|
|
issues tokens, or makes authorization decisions.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## In Scope
|
|
|
|
|
|
|
|
|
|
- Tenant records: identifier, onboarding grouping (ADR-0013).
|
|
|
|
|
- Capability role grants/revocations: `PLTF`/`IAM`/`VEN`/`CUS` (ADR-0014),
|
|
|
|
|
audited, mostly plan-linked.
|
|
|
|
|
- Plan/subscription assignment, referenced by `adaptive-pricing` plan id.
|
|
|
|
|
- Cache-read API for `key-cape` (token-issuance-time `tenant_roles` claim
|
|
|
|
|
source).
|
|
|
|
|
- Live-lookup API for `flex-auth` (high-stakes, `aal2`-class decisions).
|
|
|
|
|
- Write API for grant/revoke/plan mutations, authorization-gated by
|
|
|
|
|
`flex-auth`.
|
|
|
|
|
- Reserved, not yet implemented: guardrail/quota policy (spend limits,
|
|
|
|
|
entity/action counts).
|
|
|
|
|
|
|
|
|
|
## Out of Scope
|
|
|
|
|
|
|
|
|
|
- Identity, authentication, MFA, token issuance — `key-cape`/Keycloak.
|
|
|
|
|
- Authorization decisions — `flex-auth` is the PDP; `tenant-engine` is a
|
|
|
|
|
data source it queries, never the other way around.
|
|
|
|
|
- Users, profiles, memberships — `user-engine`. `tenant_id` is the only key
|
|
|
|
|
shared between the two services.
|
|
|
|
|
- Pricing-model / plan term definitions — `adaptive-pricing`.
|
|
|
|
|
- Payment processing — not yet identified as owned by any repo.
|
|
|
|
|
- Runtime secret custody — OpenBao / `secrets-engine`.
|
|
|
|
|
- Irreversible operational decisions without human approval.
|
|
|
|
|
|
|
|
|
|
## Current State
|
|
|
|
|
|
|
|
|
|
- Status: bootstrapping. No implementation yet — see
|
|
|
|
|
`workplans/TEN-WP-0001-statehub-bootstrap.md` and the first real
|
|
|
|
|
implementation workplan it seeds.
|
|
|
|
|
- Ownership contract (`tenant-engine-boundary-contract_v0.1.md`) and the two
|
|
|
|
|
governing ADRs (0013, 0014) are ratified in `net-kingdom` and predate this
|
|
|
|
|
repo's code, by design.
|
|
|
|
|
|
|
|
|
|
## Getting Oriented
|
|
|
|
|
|
|
|
|
|
- Start with: `INTENT.md`
|
|
|
|
|
- Ownership contract: `net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md`
|
|
|
|
|
- Claim/carrying mechanism: `net-kingdom/canon/standards/iam-profile_v0.3.md`
|
TEN-WP-0003: FlexAuthWriteAuthorizer -- gate writes through flex-auth
flex_auth.py: CheckRequest + FlexAuthCheckClient against flex-auth's real
POST /v1/check contract (schemas/check_request.schema.json,
decision_envelope.schema.json, read directly from the flex-auth repo, not
guessed). Fail-closed by construction: only effect=="allow" authorizes;
every other effect, non-200, malformed body, or transport failure resolves
to deny, nothing raises past is_allowed().
authz.FlexAuthWriteAuthorizer implements the existing WriteAuthorizer
Protocol. Action -> resource-type mapping coordinated with FLEX-WP-0008's
planned vocabulary (both repos reference the same table).
DefaultDenyWriteAuthorizer stays the fallback when no flex-auth URL is
configured.
config.py: Settings.from_env(), mirroring qonto-assistant's pattern.
docs/flex-auth-integration.md documents the contract, fail-closed rule,
and current real state (denies everything until FLEX-WP-0008 lands).
60 tests passing. Verified live twice over real HTTP between separate
processes (not just MockTransport): a deny-returning flex-auth double
produces 403 from POST /tenants, an allow-returning one produces 201.
Also registered (not implemented) the two workplans this depends on for a
complete picture: flex-auth/FLEX-WP-0008 (protected-system registration --
what makes allow reachable) and key-cape/KEY-WP-0005 (discovered key-cape
emits none of iam-profile_v0.3.md's core claims yet, not just missing
tenant_roles -- a bigger, security-sensitive gap flagged rather than
quietly worked around).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-23 22:54:44 +02:00
|
|
|
- flex-auth write-authorization integration: `docs/flex-auth-integration.md`
|
Bootstrap repo: State Hub registration, agent docs, TEN-WP-0001/0002
statehub register + repo-seed template scaffold (CLAUDE.md, .claude/rules/,
registry/). INTENT.md and SCOPE.md rewritten from the generated stub to
match net-kingdom's ratified tenant-engine-boundary-contract_v0.1.md
(Purpose, Responsibility Boundary, Non-Goals). topic_slug corrected from
the auto-assigned custodian default to netkingdom, matching key-cape and
user-engine.
TEN-WP-0001 (bootstrap) complete: files reviewed/refined, stack decided
(Python 3.12 + FastAPI, matching qonto-assistant's convention), first real
workplan seeded.
TEN-WP-0002 drafted: service skeleton, domain model (tenant/grouping/
capability-role/plan-grant), storage layer, and the three boundary-contract
API surfaces (cache-read for key-cape, live-lookup for flex-auth with an
explicit fail-closed requirement, write API behind a WriteAuthorizer seam
since real flex-auth integration is a declared non-goal for this pass).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-23 21:56:07 +02:00
|
|
|
- Agent instructions: `AGENTS.md`, `CLAUDE.md`
|
|
|
|
|
- Workplans: `workplans/`
|