# ArchitectureBlueprint — shard-wiki access & history model Status: **draft for review** · Date: 2026-06-08 · Resolves pending decision "Scope of a minimal access model in shard-wiki core". Part of `spec/`. Background on specification document types: InfoTechPrimers on coulomb.social. This blueprint settles how shard-wiki handles access control and change history. It realizes the INTENT principles *Open by default, progressively governed*, *History as the safety net*, and *Authorization in core, authentication delegated*. --- ## 1. The core idea: one core, a ladder of modes shard-wiki ships **one** authorization core. What changes between deployments is how much of it is switched on. No re-architecture is needed to climb the ladder — only configuration and the presence (or absence) of an external identity provider. This mirrors the NetKingdom **capability-progression ladder** ("capability-driven, not scale-driven"): start lightweight, expand when the need appears. | Mode | Identity provider | Who can read/write | External deps | Analogue | |------|------------------|--------------------|---------------|----------| | **L0 — Open (c2)** | none (everyone is `anonymous`) | everyone reads + writes | **none** | Ward Cunningham's original c2 wiki | | **L1 — Attributed** | local/optional | open writes, but edits are attributed when an identity is presented | none | classic "sign your edits" wiki | | **L2 — Authenticated** | user-engine (OIDC via net-kingdom lightweight) | authenticated principals; simple read-all / write-authenticated | user-engine + net-kingdom (OIDC/PKCE) | small team wiki | | **L3 — Role/Group** | user-engine memberships | per-shard/per-namespace roles (reader/author/maintainer) | user-engine groups | departmental wiki | | **L4 — Multi-tenant enterprise** | user-engine + net-kingdom expanded (Keycloak/SAML) | per-tenant isolation, per-page ACL, SSO/MFA, audit | full IAM stack | enterprise-grade | **Invariant:** L0 must always be reachable with zero external dependencies. Access control is *additive*; removing the identity provider degrades gracefully back down the ladder, it never bricks the wiki. --- ## 2. Why history is the floor, not access control In L0 the wiki trusts every writer. The protection against accidental loss, vandalism, or mistakes is therefore **not** gatekeeping but **complete, recoverable history**: - Every write is a Git commit on the information space's coordination layer (per INTENT's Git-addressable coordination principle). - Any revision of any page is restorable; deletion is a commit, never destruction. - History exists identically in **all** modes — L4's access control *hardens* the wiki but the recoverability guarantee is the same one that makes L0 safe to run open. This is the inversion of yawex, which gated with htpasswd and kept only a single `page~` backup. We keep the openness, replace the gate with history, and make the gate optional. --- ## 3. Component model ``` ┌─────────────────────────────────────────────┐ │ shard-wiki │ request ───► │ ┌────────────┐ ┌──────────────────────┐ │ (principal?) │ │ Policy │ │ Authorization core │ │ │ │ Enforcement├──►│ (PDP): capability │ │ │ │ Point (PEP)│ │ decisions per │ │ │ └─────┬───────┘ │ page / shard / tenant│ │ │ │ └──────────┬───────────┘ │ │ ▼ │ │ │ ┌────────────┐ ┌──────▼───────────┐ │ │ │ Shard │ │ IdentityProvider │ │ │ │ adapters │ │ (interface) │ │ │ │ (+capability│ └──────┬───────────┘ │ │ │ profile) │ │ │ │ └─────┬───────┘ │ │ │ ▼ │ │ │ Git-backed coordination journal │ │ └──────────────────────────────────┼─────────────┘ │ (L2+ only) ┌────────────────────────▼───────────────────┐ │ user-engine (accounts, memberships, │ │ profiles, audit, events) │ │ backed by net-kingdom IAM │ │ (OIDC/PKCE lightweight · Keycloak/SAML exp) │ └─────────────────────────────────────────────┘ ``` **Owned by shard-wiki core:** - **Principal** — a resolved actor: `anonymous`, or an identity token + claims from the provider. Core never stores credentials. - **IdentityProvider interface** — a thin pluggable contract. The **null provider** (everyone = `anonymous`) is the L0 default and ships in-core. - **Authorization core (PDP)** — pure capability decisions: given (principal, action, target page/shard/tenant), return allow/deny. Actions: `read, write, patch, merge, administer`. Layered on each adapter's **capability profile** (a shard that can't write can't be written regardless of policy). - **Policy Enforcement Point (PEP)** — wraps every adapter operation; calls the PDP. - **Tenant boundary** — a *root entity* is the unit of multi-tenancy. Shards attach to a root; an L4 tenant maps to a root entity (or a set of them). - **Change history** — Git commits on the coordination journal; the recovery substrate. **Delegated to the identity provider (L2+):** - Authentication (who you are) — net-kingdom IAM (OIDC/PKCE → Keycloak/SAML). - Identity lifecycle, user directory, credentials, secrets — net-kingdom / user-engine. - Memberships, groups, profiles, org structure, audit sink — user-engine. --- ## 4. Request flow (L4, fully governed) 1. Caller presents an OIDC token (issued by net-kingdom IAM) to shard-wiki. 2. The configured **IdentityProvider** validates the token and resolves a **Principal** (subject + tenant + group/role claims), enriching via **user-engine** memberships. 3. The **PEP** intercepts the requested action on a target page/shard. 4. The **PDP** decides using: tenant isolation → shard role bindings → optional per-page ACL → adapter capability profile. 5. On allow, the adapter performs the op; the write lands as a **Git commit** and an **audit event** is emitted to user-engine. 6. On deny, the op is refused; nothing mutates. **The same code path at L0:** step 1 is skipped, the null provider returns `anonymous`, the PDP's open policy allows read+write, the write still lands as a Git commit. History is identical; only the gate differs. --- ## 5. Design rules - **Fail open only at L0, fail closed at L2+.** The mode is explicit configuration, never inferred from whether the provider happens to be reachable (a flaky IAM must not silently open an enterprise wiki). If an L2+ deployment loses its provider, it denies, it does not fall back to open. - **Authorization is pure and offline-capable.** Once a Principal is resolved, decisions need no network call — role/ACL data is carried on the Principal or cached, so a federated read of a projected page doesn't require a live IAM round-trip per page. - **Per-page ACL is opt-in (L4).** Default scoping is per-shard / per-namespace (L3). Per-page ACL is supported but off by default to avoid yawex's per-directory `AccessControl` sprawl. - **Provenance carries authorization context.** A federated page records not just its source shard and freshness but the authorization context under which it was read, so the union view never leaks content a principal couldn't see at source. --- ## 6. Open questions (carry into requirements) 1. Token format/claims contract with net-kingdom (OIDC scopes, tenant claim name). 2. user-engine membership/role query shape and caching/TTL. 3. Audit event schema shard-wiki emits to user-engine. 4. How tenant ↔ root-entity mapping is configured and discovered. 5. Whether L1 "attributed but open" is worth shipping or we jump L0 → L2. See `demand/260608-netkingdom-integration-requirements.md` for the concrete asks these imply.