Implement Knowledge City platform, organizer and DAV integration

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.
This commit is contained in:
Anya Tokugawa committed 2026-09-27 14:44:43 +09:00
1 parent 288e6e94ac
commit c1175d389f
699 files changed
+110197 -4117

No files matched your search

+642
View File
@@ -0,0 +1,642 @@
# 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
```