coulomb/shard-wiki
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a00a457f44ccd697d928f814f035a7cb3ca0bca2
shard-wiki/docs/requirements-user-engine-netkingdom.md
tegwick a00a457f44 Establish clean starting point: workplan, access model, INTENT amendments 
Add SHARD-WP-0001 workplan backed by the StateHub yawex-requirements
workstream (6 design tasks, all todo). Includes access-model blueprint,
NetKingdom integration requirements draft, and INTENT amendments for
open-by-default authorization delegated to external identity providers.
2026-06-08 12:23:54 +02:00

5.3 KiB
Raw Blame History

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

Status: draft for review · Date: 2026-06-08

Derived from access-model-blueprint.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.
Reference in New Issue View Git Blame Copy Permalink