Module context_path 

Server-side re-export of the canonical context-path validators.

Hierarchical trust-context paths are the security foundation for folder/sub-folder contexts (docs/05-design-notes/hierarchical-contexts.md). A context identifier is its materialized path: slash-separated segments, e.g. acme/eng/team-a. The authorization gate (crate::auth’s has_context_access) 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 now

The pure construction/validation rules moved down into vta_sdk::context_path so clients can derive sub-context ids under the same rules the VTA enforces, without depending on this server-only crate (see issue #392). This module re-exports the pure helpers verbatim and wraps the two fallible constructors so they keep returning AppError for the server’s ?-ergonomics; the ValidationError message is preserved verbatim.

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.