Stax Digital Garden

HBM-1003 - Capability-Gated Read Access and Token Scopes

2 min read

Living Document Notice Published 2026-09-12. The evolving architecture and revisions for this dispatch live in the Stax Digital Garden.

Capability-Gated Read Access and Token Scopes

Capability-Gated Read Access and Token Scopes: Monochromatic ice blue phosphor P7 vector CRT macro showing concentric capability-gated security sectors and pass-through token channels

Granting connected modules blanket read access to personal knowledge archives creates privacy hazards. A simple word-count widget or status bar icon does not require access to private journal entries, cryptographic secrets, or raw attachment binaries stored in the vault.

Harbormaster implements a capability-gated security model for the Knowledge Provider Protocol. Capabilities follow a deny-by-default architecture: each module requests specific, fine-grained access scopes during registration, which the local operator reviews through an out-of-band consent surface before tokens activate.

Capability Scopes and Permission Matrix

Harbormaster defines explicit capability scopes governing read-only introspection:

Scope IdentifierPermitted OperationsRestricted Surfaces
kpp.graph:readQuery note relationships and link countsFull note markdown text
kpp.notes:readRead published public note markdown bodiesPrivate frontmatter fields
kpp.events:streamSubscribe to graph update events via SSEDirect database modification
kpp.system:inspectInspect engine version and uptime telemetryAny knowledge vault content

Capabilities cannot be self-granted by client modules. When an unknown module requests capabilities, Harbormaster stages a pending consent request:

[ Connected Module ] ──> Requests [kpp.graph:read, kpp.notes:read]
                                  │
                                  ▼
                     [ Harbormaster Gateway ] ──> Stores Pending Grant
                                  │
                                  ▼ (Notification via CLI / Desktop)
                     [ Local Human Operator ]
                                  │
                                  ├─► harbormaster auth approve <grant_id>
                                  └─► harbormaster auth deny <grant_id>

Token Validation Engine

Tokens are validated in constant time, preventing timing attacks on token comparison:

import hmac
import secrets
from typing import Optional, Set
 
class CapabilityValidator:
    def __init__(self):
        self.active_grants = {}
 
    def register_approved_grant(self, client_id: str, scopes: Set[str]) -> str:
        token = secrets.token_urlsafe(32)
        self.active_grants[token] = {
            "client_id": client_id,
            "scopes": scopes
        }
        return token
 
    def validate_request(self, token: str, required_scope: str) -> bool:
        # Constant-time token lookup
        matching_grant = None
        for active_token, grant in self.active_grants.items():
            if hmac.compare_digest(active_token, token):
                matching_grant = grant
                break
 
        if not matching_grant:
            return False
 
        return required_scope in matching_grant["scopes"]

Command-Line Grant Inspection and Revocation

Operators manage capability grants directly from the local terminal:

# List all pending module registration requests
harbormaster auth pending
 
# Approve specific scoped grant for local status bar tool
harbormaster auth approve grnt_98a7cf --scopes=kpp.graph:read
 
# Instantly revoke token and disconnect module
harbormaster auth revoke grnt_98a7cf
  • Directus Target: harbormaster
  • Garden Source Reference: MOC - Harbormaster Protocol, MOC - Bosun PKM Tools
  • Garden Source Reference: [HBM-1003 - Capability-Gated Read Access and Token Scopes](HBM-1003 - Capability-Gated Read Access and Token Scopes)

Graph View