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.
- [ ] 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.