Struct NarrowingMatrix 

pub struct NarrowingMatrix { /* private fields */ }

A 256-bit capability mask with cryptographic narrowing guarantees.

NarrowingMatrix enforces that delegated capability sets are strict subsets of their parent’s set. The check is O(1): eight 64-bit AND operations on modern hardware, regardless of how many named capabilities exist.

Each capability name maps deterministically to a bit position in the 256-bit field via Blake3. Two distinct capability names that collide on the same bit are both authorized by setting that bit — this is intentional and conservative: the narrowing guarantee (sub ⊆ parent) still holds.

Collision behaviour

Hash-based mapping distributes capabilities uniformly across 256 bits. With the birthday bound, collisions become likely when a single deployment uses more than ~100–150 distinct capability names. Collisions are not a security vulnerability — they produce false positives (capability A grants slot X, and so does capability B, so holding A also passes a check for B). For large deployments use CapabilityRegistry to assign explicit, collision-free bit positions.

Narrowing invariant

For any parent mask P and requested mask R:

R.is_subset_of(P) ↔ (P.mask & R.mask) == R.mask

This is the sole enforcement rule. No external registry, no network call, no configuration file is required at verification time.

Implementations

impl NarrowingMatrix

pub const EMPTY: Self

An empty mask: no capabilities authorized.

pub const FULL: Self

A full mask: all 256 bits set — used by root passports.

pub fn from_capabilities<S: AsRef<str>>(caps: &[S]) -> Self

Build a mask from a slice of capability name strings.

Each name is mapped to a bit position via Blake3. Order does not matter. Duplicate names are idempotent.

For deployments with more than ~100 distinct capability names, prefer CapabilityRegistry::build_mask to avoid hash-space collisions.

pub fn from_csv(csv: &str) -> Self

Parse a comma-separated capability string (e.g. "trade.equity,portfolio.read").

pub fn is_subset_of(&self, parent: &NarrowingMatrix) -> bool

Return true if self is a subset of parent.

This is the sole enforcement rule for narrowing. A sub-passport cannot carry capabilities that its parent does not have.

pub fn enforce_narrowing(&self, parent: &NarrowingMatrix) -> Result<(), A1Error>

Validate that self is a subset of parent, returning an error otherwise.

pub fn intersect(&self, other: &NarrowingMatrix) -> NarrowingMatrix

Produce the intersection of two masks (logical AND).

Useful for computing the maximum allowed sub-mask from a parent.

pub fn commitment(&self) -> [u8; 32]

A 32-byte Blake3 commitment over this mask, domain-separated.

Stored in the cert extension so that a tampered mask fails the extension commitment check inside DelegationCert::signable_bytes.

pub fn as_bytes(&self) -> &[u8; 32]

The raw 32-byte mask. Suitable for serialization and storage.

pub fn to_hex(&self) -> String

Hex representation of the mask.

pub fn from_hex(s: &str) -> Result<Self, A1Error>

Reconstruct from a 32-byte hex string.

pub fn is_empty(&self) -> bool

Return true if no capabilities are set.

pub fn capacity_count(&self) -> u32

Count how many bits are set (number of unique capability slots in use).

Trait Implementations

impl Clone for NarrowingMatrix

fn clone(&self) -> NarrowingMatrix

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NarrowingMatrix

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for NarrowingMatrix

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for NarrowingMatrix

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for NarrowingMatrix

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for NarrowingMatrix

fn eq(&self, other: &NarrowingMatrix) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for NarrowingMatrix

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for NarrowingMatrix

impl StructuralPartialEq for NarrowingMatrix