Files
Anya Tokugawa c1175d389f 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.
2026-09-27 14:44:43 +09:00

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