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 Identifier	Permitted Operations	Restricted Surfaces
`kpp.graph:read`	Query note relationships and link counts	Full note markdown text
`kpp.notes:read`	Read published public note markdown bodies	Private frontmatter fields
`kpp.events:stream`	Subscribe to graph update events via SSE	Direct database modification
`kpp.system:inspect`	Inspect engine version and uptime telemetry	Any knowledge vault content

Operator Consent Lifecycle

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