Module context_path 

Hierarchical trust-context paths — the security foundation for folder/sub-folder contexts.

A context identifier is its materialized path: slash-separated segments, e.g. acme/eng/team-a. The server’s authorization gate decides “admin of a parent → access to descendants” with is_ancestor_or_self — a pure, store-free segment comparison over data already in the verified JWT.

Why this lives in the SDK

Path construction (child_path) and validation (validate_context_path) are the canonical rules for what a context path may contain. A client that derives a sub-context id (e.g. a community’s <top>/<slug>) must apply the same rules so it only ever sends paths the VTA will accept. Keeping them here lets clients share the one source of truth instead of mirroring it and drifting on security-relevant logic. The server re-exports these through vti_common::context_path.

The one footgun, handled

A raw str::starts_with is wrong: acme would “contain” acme-evil. Ancestry here is segment-aware, and / is the only separator — it cannot appear inside a segment (each segment is a validate_identifier value), so there is no .. / slash-injection / empty-segment aliasing.

Constants

MAX_CONTEXT_DEPTH

Maximum nesting depth (number of path segments). Bounds derivation depth and keeps ancestry checks cheap; deep trees are an anti-pattern, not a need.

SEPARATOR

The path separator. A context identifier is segments joined by this; it never appears inside a segment.

Functions

child_path

Build a child path under parent by appending a single segment. The segment must be one valid identifier — it cannot itself contain a separator (else it would silently add several levels) — and the resulting path must validate (depth included).

depth

The depth (segment count) of a path. A top-level context is depth 1.

is_ancestor_or_self

Whether ancestor is descendant itself or an ancestor of it — the test the ACL gate uses for “admin of a parent context covers the subtree”.

parent_path

The parent path (one segment shorter), or None for a top-level (single segment) path.

validate_context_path

Validate a context path: non-empty, ≤ MAX_CONTEXT_DEPTH segments, every segment a valid identifier, and no empty / leading / trailing / doubled separators.