# Pages Wiki vNext Authentication / Authorization Draft ## Goal Separate: ```text Authentication Identity Capability Delegation Projection ``` into independent layers. Avoid tightly coupling: ```text OIDC groups filesystem ACLs path hierarchy ``` to the knowledge topology. * * * # Core Philosophy ## Authentication != Authorization Authentication answers: ```text Who are you? ``` Authorization answers: ```text What may you do? ``` These are intentionally separated. * * * # High-Level Architecture ```text OIDC ↓ Principal ↓ Membership / Roles ↓ Capability Graph ↓ Macaroon Delegation ↓ Runtime Policy Evaluation ``` * * * # Layer 1: Authentication ## Responsibility Identity proof only. * * * # Recommended Mechanism OIDC / OpenID Connect. Examples: - Keycloak - Authentik - Azure AD - Google Workspace - GitHub OIDC * * * # OIDC Output Example claims: ```json { "iss": "...", "sub": "...", "email": "...", "groups": [...] } ``` * * * # Important Principle OIDC groups are NOT canonical authorization objects. They are only: ```text external identity attributes ``` * * * # Layer 2: Principal ## Responsibility Canonical internal identity normalization. * * * # Principal Model ```text principal_id issuer subject display_name email ``` * * * # Important Principle The canonical identity inside Pages is: ```text principal_id ``` NOT: ```text OIDC group email address username ``` * * * # Layer 3: Capability Model ## Responsibility Represent authority within the knowledge topology. * * * # Capability Philosophy Capabilities are attached primarily to: ```text Zone Spot ``` rather than individual Pages. * * * # Why Knowledge naturally clusters around semantic localities. ACLs scale better when attached to locality. * * * # Example ```text Spot(Auth API) allow: engineering-reader api-editor ``` Pages inherit effective visibility from their locality. * * * # Capability Model ```text principal ↓ membership ↓ role ↓ capability ``` * * * # Example ```text engineering-team ↓ api-editor ↓ write Spot(Auth API) ``` * * * # Important Principle Roles are internal semantic policy objects. They are NOT identical to OIDC groups. * * * # OIDC Mapping ```text OIDC group ↓ Pages membership ↓ Pages role ↓ Capability ``` * * * # Capability Target Types Capabilities may target: | Object Type | Meaning | | --- | --- | | Zone | Containment locality | | Spot | Semantic locality | | Page | Exceptional override only | | Binding | Projection-level visibility | * * * # Default Authorization Strategy ## Default Deny No capability means: ```text access denied ``` * * * # Positive Grant Only Avoid large explicit deny graphs. Prefer: ```text grant omission ``` instead of: ```text explicit deny ``` * * * # Why Explicit deny causes: - precedence complexity - inheritance conflicts - ACL explosion - runtime ambiguity * * * # Recommended Model ```text allow-only locality policies ``` plus: ```text principal-side overlays ``` for exceptional cases. * * * # Exceptional Restriction Handling Instead of: ```text deny alice ``` prefer: ```text alice.status = suspended ``` or: ```text alice lacks capability ``` * * * # Principal States Examples: ```text active readonly suspended quarantined audit-only ``` * * * # Layer 4: Macaroon ## Responsibility Portable delegated constrained capability. * * * # Important Principle Macaroon is NOT the canonical ACL database. Macaroon is: ```text authority artifact delegated capability token portable constrained access proof ``` * * * # Macaroon Role Macaroons transport delegated authority. * * * # Example Canonical server-side capability: ```text Alice └─ read Spot(Auth API) ``` Delegated macaroon: ```text read-only spot=auth-api expires<2026-02-01 office-network-only ``` * * * # Caveats Macaroon caveats attenuate authority. Examples: Caveat Meaning expires time restriction network source network restriction readonly capability narrowing path locality restriction lang projection restriction method operation restriction * * * # Important Property Macaroons can only: ```text reduce authority ``` never expand it. * * * # Runtime Validation ```text 1. Verify macaroon signature 2. Verify caveats 3. Verify delegated capability validity 4. Apply runtime policy ``` * * * # Share Links Example: ```text /s/abcdef ``` may internally represent: ```text anonymous delegated macaroon capability ``` * * * # Important Property Share links may work without OIDC login. This enables: ```text identity-less delegated access ``` * * * # Capability vs ACL ## Traditional ACL ```text Object └─ Subjects ``` * * * # Capability-Oriented Model ```text Principal └─ Possessed Authorities ``` * * * # Real-World Analogy Pages authorization behaves more like: ```text building access control ``` than filesystem ACLs. * * * # Example ```text Zone = building Spot = room Capability = key Macaroon = temporary visitor pass ``` * * * # Locality Unlock Model ## Spot ```text requires capability: auth-api:read ``` * * * # Principal ```text possesses: auth-api:read ``` * * * # Runtime ```text Does principal possess required capability? ``` * * * # Capability Delegation Example: ```text Alice delegates: read-only access to Spot(Auth API) valid for 24 hours ``` This maps naturally to: ```text temporary visitor badge ``` * * * # Runtime Authorization Evaluation ## Without Macaroon ```text principal session ↓ effective capability lookup ``` * * * # With Macaroon ```text verify macaroon ↓ apply caveats ↓ treat as delegated capability ``` * * * # Runtime Evaluation Components | Component | Responsibility | | --- | --- | | Principal | Identity | | Capability Graph | Canonical authority | | Macaroon | Delegated authority | | Runtime Policy | Dynamic constraints | | Effective Cache | Acceleration | * * * # Runtime Constraints Examples: ```text time network risk device lang projection ``` * * * # Effective Capability Cache Recommended for scalability. Example: ```text principal_effective_capabilities ``` * * * # Important Principle The source of truth is: ```text server-side capability graph ``` NOT macaroon tokens. * * * # Architectural Direction Layer Model Authentication OIDC Identity Principal Authorization Capability graph Delegation Macaroon Constraints Caveats Runtime Effective policy evaluation * * * # Conceptual Summary Pages Wiki authorization is evolving toward: ```text semantic locality capability system ``` rather than: ```text filesystem ACL system ```