shard-wiki/demand/260608-netkingdom-integration-requirements.md

Requirements — what shard-wiki needs from user-engine & net-kingdom

Status: inbound demand — draft for review · Date: 2026-06-08

Located in demand/ — not yet promoted to spec/ or workplans.

Derived from spec/ArchitectureBlueprint.md. These are the integration contracts shard-wiki needs to climb from L0 (open, standalone) to L4 (multi-tenant enterprise) without changing its core. They are requirements on the NetKingdom domain repos, to be negotiated with their owners — not assumptions about their current implementation.

Reference deployment roles:

• net-kingdom — IAM/SSO backend. Issues and validates identities. OIDC/PKCE in lightweight mode (KeyCape: Authelia + LLDAP + privacyIDEA), Keycloak/SAML in expanded mode. Owns authentication, credentials, MFA, the NetKingdom IAM Profile.
• user-engine — headless user-domain service: accounts, memberships, profiles, catalogs, projections, audit, events. Owns the membership/role/tenant read model shard-wiki authorizes against.

shard-wiki authorizes; it never authenticates or stores identity. Everything below is a read or emit contract — shard-wiki must not need write access to identity data.

---

A. From net-kingdom (authentication / IAM)

1. Token issuance & validation (OIDC/PKCE). A standard OIDC relationship shard-wiki can register as a confidential or public client; ability to validate presented access/ID tokens (JWKS endpoint or introspection). Lightweight mode must work without Keycloak.
2. Stable subject identifier. A durable sub that does not change across renames/email changes, usable as the Principal key.
3. Tenant claim. A claim that identifies the tenant/organization a token is scoped to (claim name TBD), so shard-wiki can map token → tenant → root entity.
4. Group/role claims (optional fast path). If groups/roles can ride in the token, L3/L4 decisions need no extra round-trip. Otherwise shard-wiki resolves them via user-engine (B).
5. Expanded-mode parity. The same claim contract must hold when the backend is swapped to Keycloak/SAML, so climbing L3→L4 is a deployment change, not a shard-wiki change.
6. Logout / token revocation signal so shard-wiki can drop cached Principals.

B. From user-engine (membership / authorization read model)

1. Resolve principal → memberships. Given a sub (and tenant), return the principal's group/role memberships relevant to wiki access. Read-only, low-latency, cacheable with a stated TTL.
2. Tenant ↔ root-entity mapping. A way to resolve which tenant(s) a principal belongs to and how those map to shard-wiki root entities. Either user-engine owns this mapping or it exposes the primitives for shard-wiki to hold it as config.
3. Role vocabulary. An agreed, minimal role set that maps onto shard-wiki actions: reader → read, author → read+write+patch, maintainer → +merge+administer. Custom roles allowed but must declare which actions they grant.
4. Profile lookup for attribution. Given a sub, return display name / handle so edits and signatures are attributable (the L1 "sign your edits" need, generalized).
5. Stable, versioned read API. A versioned contract (REST/gRPC) for B1–B4 so shard-wiki isn't coupled to user-engine internals; INTENT requires stable adapter contracts.
6. Bulk/batch resolution. Resolving memberships for many principals (e.g. rendering a BackLinks/history view) must not be N+1; provide batch lookup.

C. Audit / events (shard-wiki → user-engine)

1. Audit event sink. shard-wiki emits access-relevant events (page read-denied, write, patch, merge, admin change) to user-engine's audit/event stream. Need the event schema and transport (user-engine already lists "audit" and "events" as owned concerns — align to that).
2. Non-blocking emission. Audit emission must be async/best-effort so an audit outage never blocks a wiki write (history in Git remains the source of truth regardless).

D. Cross-cutting / non-functional

1. Graceful degradation contract. A defined behavior when the provider is unreachable in L2+: shard-wiki fails closed (denies), and must be able to distinguish "provider down" from "principal unauthorized" for operability. (L0/L1 never depend on the provider.)
2. No secret custody in shard-wiki. Client secrets / keys are provisioned and rotated by net-kingdom; shard-wiki consumes them via the deployment's secret mechanism, never stores or commits them. (Consistent with INTENT non-goal on secret storage.)
3. Offline authorization. After Principal resolution, decisions must be computable without per-page network calls (carry claims on the Principal or cache memberships).
4. Capability-progression alignment. The integration should slot into NetKingdom's C0–C6 ladder so shard-wiki's L0–L4 modes correspond to recognizable NetKingdom capability levels rather than introducing a parallel scheme.

---

Next actions

• Send this as a capability request / interface negotiation to the netkingdom domain (user-engine + net-kingdom owners) via the state hub. — sent 2026-06-13, capability request 3136a9e2-0c1a-4b3f-8a02-ef47b27071fe (auto-routed to netkingdom), inbox message 46c60f17.
• Lock the token claim contract (A2–A4) and the membership read API (B1–B5) first — they gate everything L2+.
• Define shard-wiki's audit event schema (C1) against user-engine's existing audit model.
• Resolve blueprint open questions §6 once the above are answered.