Labels and clearances

Label fields

A known label combines the policies of the information’s owners. A clearance uses the same fields to describe what a destination accepts.

kind

owners

readers

compartments

Choosing owners and readers

Start with who owns the information and which recipients each owner permits. Your pricing team may permit its agents to read a customer’s price sheet while Harbor Goods permits a smaller group to read its NDA; an analysis combining both keeps both policies, a distinction a single “confidential” tag would lose.

Choose identifiers with stable organizational meanings and bind their use through trusted configuration; a string such as larkfield-pricing authenticates no receiver by itself. Readers set too broadly permit unintended disclosure, and readers set too narrowly push routine internal work through an exception path, so review labels against who receives summaries and delegated results.

Flow relation

For every source owner, the destination keeps that owner and allows only readers the source already permits. Every source compartment is present at the destination. For Harbor Goods’ terms as the source, owner harbor-goods with readers harbor-goods and fixer and compartment harbor-goods-terms:

• Same owners, readers, and compartments: allowed, every obligation survives.
• A reader removed, owner kept: allowed, fewer principals receive the data.
• An owner or compartment added: allowed, the destination is more restrictive.
• A reader added to a source owner’s policy: refused, disclosure broadens.
• A source owner dropped: refused, that owner’s policy disappears.
• A source compartment dropped: refused, a required separation disappears.

    pub fn flows_to(&self, destination: &Self) -> bool {
        match (self, destination) {
            (_, Self::Top) => true,
            (Self::Top, Self::Known { .. }) => false,
            (
                Self::Known {
                    owners: source_owners,
                    compartments: source_compartments,
                },
                Self::Known {
                    owners: destination_owners,
                    compartments: destination_compartments,
                },
            ) => {
                source_compartments.is_subset(destination_compartments)
                    && source_owners.iter().all(|(owner, source_readers)| {
                        destination_owners
                            .get(owner)
                            .is_some_and(|destination_readers| {
                                destination_readers.is_subset(source_readers)
                            })
                    })
            }
        }
    }

Order and recipient authority

The order compares information restrictions. The destination obtains its clearance through the application’s trusted configuration, and the surrounding operation still passes capability and caller checks, so two compatible labels never make an arbitrary URL a trusted internal service. Adding a principal to a reader set issues it no capability: the data policy and the operation’s authority must agree, and a refused transfer is diagnosed against both.

Join

    pub fn join_restrictions(&self, other: &Self) -> Result<Self, LabelValidationError> {
        let (
            Self::Known {
                owners: left_owners,
                compartments: left_compartments,
            },
            Self::Known {
                owners: right_owners,
                compartments: right_compartments,
            },
        ) = (self, other)
        else {
            return Ok(Self::Top);
        };

        let mut owners = left_owners.clone();
        for (owner, right_readers) in right_owners {
            match owners.entry(owner.clone()) {
                Entry::Vacant(entry) => {
                    entry.insert(right_readers.clone());
                }
                Entry::Occupied(mut entry) => {
                    let readers = entry
                        .get()
                        .intersection(right_readers)
                        .cloned()
                        .collect::<BTreeSet<_>>();
                    entry.insert(readers);
                }
            }
        }
        let compartments = left_compartments
            .union(right_compartments)
            .cloned()
            .collect();
        Self::try_known(owners, compartments)
    }

Joining your pricing team’s terms with Harbor Goods’ NDA keeps both owners. For an owner in both labels, the join intersects the allowed readers, and it unions the compartments. Joining an unrestricted label adds nothing, so a public input cannot reset a restricted session.

The default protocol limits are 64 owners, 256 readers per owner, and 64 compartments. try_known_with_limits constructs a label under tighter bounds; join_restrictions validates its result against the defaults. The enclosing wire input is byte-bounded before deserialization, because bounded collection cardinality alone leaves an incoming message unbounded.

Combined reader sets

Harbor Goods’ price sheet permits the pricing team, your pricing lead, and Harbor Goods’ contact; Ostrander’s permits the pricing team, the pricing lead, and Ostrander’s contact. After both reads, a combined analysis keeps both policies and the remaining readers are the pricing team and the pricing lead, so neither customer’s contact can receive a result drawn from both. Harbor Goods’ own NDA stays a separate obligation beside your team’s set, which makes a clearance that carries only your team’s obligation insufficient, and dropping either the terms or the NDA compartment broadens disclosure.

Calculate the source with join_restrictions, then check the destination with authorize_egress, which also rejects a missing clearance and a Top clearance. Here first, second, and expected_common_readers are labels with the reader sets above; the reader-intersection program builds them and runs the assertions.

let combined = first.join_restrictions(&second)?;
assert_eq!(combined, expected_common_readers);
assert_eq!(authorize_egress(&combined, Some(&combined)), Ok(()));
assert_eq!(
    authorize_egress(&combined, Some(&first)),
    Err(EgressDenial::FlowViolation),
);

Join by hand

Take two documents owned by larkfield-pricing: the first permits larkfield-pricing, fixer, and reviewer, the second larkfield-pricing and fixer. A workflow that learns both satisfies both, so the readers are larkfield-pricing and fixer. A document owned by harbor-goods adds a separate owner entry beside your team’s policy, and different compartments are both required.

These assertions use labels from the pricing lab and make no network request. The surrounding function returns a compatible error type, and first and second are validated InformationLabel values. A failed join refuses to construct the combined label; substituting bottom() would discard the obligations the join exists to keep.

let joined = first.join_restrictions(&second)?;
assert!(first.flows_to(&joined));
assert!(second.flows_to(&joined));
assert_eq!(
    joined.join_restrictions(&InformationLabel::bottom())?,
    joined,
);

Bottom and Top

InformationLabel::bottom() is known unrestricted data, for a source the application’s classification policy establishes as public. InformationLabel::Top is restrictive uncertainty, including history that verified evidence cannot reconstruct.

The lattice relation and the operational egress decision are separate APIs. The relation allows flow into Top; authorize_egress rejects Top as a destination clearance, so a catch-all unknown label never becomes an export permission.

Constructing a label

Harbor Goods permits itself and the fixer to receive its contract terms, and its destination keeps that owner and compartment. The program accepts the original policy and a narrower reader set, then refuses an outside buyer, basalt, as an extra reader, a missing compartment, and a public destination. Run it in the security-research project.

use chio_security_types::{Compartment, InformationLabel, PrincipalId};
use std::collections::{BTreeMap, BTreeSet};

fn harbor_goods(readers: &[&str], compartments: &[&str]) -> InformationLabel {
    InformationLabel::try_known(
        BTreeMap::from([(
            PrincipalId::new("harbor-goods").unwrap(),
            readers.iter().map(|name| PrincipalId::new(*name).unwrap()).collect(),
        )]),
        compartments.iter().map(|name| Compartment::new(*name).unwrap()).collect(),
    ).unwrap()
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let source = harbor_goods(&["harbor-goods", "fixer"], &["harbor-goods-terms"]);
    let narrower = harbor_goods(&["harbor-goods"], &["harbor-goods-terms"]);
    let broader = harbor_goods(&["harbor-goods", "fixer", "basalt"], &["harbor-goods-terms"]);
    let missing_compartment = harbor_goods(&["harbor-goods", "fixer"], &[]);
    assert!(source.flows_to(&source));
    assert!(source.flows_to(&narrower));
    assert!(!source.flows_to(&broader));
    assert!(!source.flows_to(&missing_compartment));
    assert!(!source.flows_to(&InformationLabel::bottom()));
    assert_eq!(source.join_restrictions(&narrower)?, narrower);
    assert_eq!(source.join_restrictions(&InformationLabel::bottom())?, source);
    let owner = PrincipalId::new("harbor-goods")?;
    assert!(InformationLabel::try_known(
        BTreeMap::from([(owner, BTreeSet::from([PrincipalId::new("fixer")?]))]),
        BTreeSet::new(),
    ).is_err());
    println!("ALLOW same or narrower reader set: Harbor Goods obligation retained");
    println!("REFUSE Basalt as a reader, a missing compartment and public clearance");
    println!("JOIN same owner: readers intersect; public input adds no permission");
    println!("REFUSE malformed label: owner must belong to its own reader set");
    Ok(())
}

cargo run --locked --quiet --example construct_label

ALLOW same or narrower reader set: Harbor Goods obligation retained
REFUSE Basalt as a reader, a missing compartment and public clearance
JOIN same owner: readers intersect; public input adds no permission
REFUSE malformed label: owner must belong to its own reader set

The destination with fewer readers is more restrictive and compatible. Adding the outside buyer broadens disclosure, and removing the compartment loses an obligation even when the reader names match. The constructor check is separate: a known label whose owner is missing from its own readers fails to construct. Recipient authentication and the tool’s authority belong to the host.

Diagnosing a refused transfer

1. Owners. For each source owner, find the matching destination owner. An absent owner is the reason for the refusal.
2. Readers. For each owner, compare the destination’s readers with the source’s. One extra destination reader widens disclosure.
3. Compartments. Check that every source compartment exists at the destination.
4. Operational checks. If the order holds and egress still refuses, check whether the resolved source is Top, the clearance is absent, or the destination is Top. authorize_egress names each as its own EgressDenial.

A serving host keeps the EgressDenial out of the caller’s refusal; control egress shows where each host records it. Repair classification and policy at their trusted source, and leave the payload’s caller metadata alone.

Collection bounds matter as a workflow reads more sources. When a join exceeds the default limits, join_restrictions returns an error; the flow engine refuses an admission join as a state overflow and raises an output join to Top. Either way the application stops or redesigns the task’s information boundary, since truncating the owner set would discard the obligations the join keeps.