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.
643 lines
6.6 KiB
Markdown
643 lines
6.6 KiB
Markdown
# 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
|
|
```
|