Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming. Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
6.6 KiB
Pages Wiki vNext Authentication / Authorization Draft
Goal
Separate:
Authentication
Identity
Capability
Delegation
Projection
into independent layers.
Avoid tightly coupling:
OIDC groups
filesystem ACLs
path hierarchy
to the knowledge topology.
Core Philosophy
Authentication != Authorization
Authentication answers:
Who are you?
Authorization answers:
What may you do?
These are intentionally separated.
High-Level Architecture
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:
{
"iss": "...",
"sub": "...",
"email": "...",
"groups": [...]
}
Important Principle
OIDC groups are NOT canonical authorization objects.
They are only:
external identity attributes
Layer 2: Principal
Responsibility
Canonical internal identity normalization.
Principal Model
principal_id
issuer
subject
display_name
email
Important Principle
The canonical identity inside Pages is:
principal_id
NOT:
OIDC group
email address
username
Layer 3: Capability Model
Responsibility
Represent authority within the knowledge topology.
Capability Philosophy
Capabilities are attached primarily to:
Zone
Spot
rather than individual Pages.
Why
Knowledge naturally clusters around semantic localities.
ACLs scale better when attached to locality.
Example
Spot(Auth API)
allow:
engineering-reader
api-editor
Pages inherit effective visibility from their locality.
Capability Model
principal
↓
membership
↓
role
↓
capability
Example
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
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:
access denied
Positive Grant Only
Avoid large explicit deny graphs.
Prefer:
grant omission
instead of:
explicit deny
Why
Explicit deny causes:
- precedence complexity
- inheritance conflicts
- ACL explosion
- runtime ambiguity
Recommended Model
allow-only locality policies
plus:
principal-side overlays
for exceptional cases.
Exceptional Restriction Handling
Instead of:
deny alice
prefer:
alice.status = suspended
or:
alice lacks capability
Principal States
Examples:
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:
authority artifact
delegated capability token
portable constrained access proof
Macaroon Role
Macaroons transport delegated authority.
Example
Canonical server-side capability:
Alice
└─ read Spot(Auth API)
Delegated macaroon:
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:
reduce authority
never expand it.
Runtime Validation
1. Verify macaroon signature
2. Verify caveats
3. Verify delegated capability validity
4. Apply runtime policy
Share Links
Example:
/s/abcdef
may internally represent:
anonymous delegated macaroon capability
Important Property
Share links may work without OIDC login.
This enables:
identity-less delegated access
Capability vs ACL
Traditional ACL
Object
└─ Subjects
Capability-Oriented Model
Principal
└─ Possessed Authorities
Real-World Analogy
Pages authorization behaves more like:
building access control
than filesystem ACLs.
Example
Zone = building
Spot = room
Capability = key
Macaroon = temporary visitor pass
Locality Unlock Model
Spot
requires capability:
auth-api:read
Principal
possesses:
auth-api:read
Runtime
Does principal possess required capability?
Capability Delegation
Example:
Alice delegates:
read-only access
to Spot(Auth API)
valid for 24 hours
This maps naturally to:
temporary visitor badge
Runtime Authorization Evaluation
Without Macaroon
principal session
↓
effective capability lookup
With Macaroon
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:
time
network
risk
device
lang
projection
Effective Capability Cache
Recommended for scalability.
Example:
principal_effective_capabilities
Important Principle
The source of truth is:
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:
semantic locality capability system
rather than:
filesystem ACL system