Bilateral Co-Sign

Both keys sign the same bytes

The co-signer flow starts at tool host B. B signs the statement’s DSSE PAE bytes, asks A for a signature over the same bytes, checks the response, and assembles the envelope.

sign_chio_bilateral_dsse_envelope_with_cosigner runs this flow when B holds its own key and knows A’s public key. Its BilateralCoSigningProtocol callback obtains A’s signature, and the helper validates the returned signature and the final envelope. sign_chio_bilateral_dsse_envelope takes both keypairs directly, for local construction and tests.

Across organizations, A’s signature comes from a remote co-signer at A’s door; while it is unreachable, the work stays pending and is never re-dispatched. The in-process reference co-signer checks the request’s origin id and B’s configured key and signature, then signs the supplied bytes. The unit of agreement is one pair of organizations and one statement, so authenticating it needs no federation-wide consensus round.

One statement travels in three encodings

1. Canonical statement bytes. The in-toto Statement with its receipt subject, strict predicate type, and invocation fields.
2. DSSE PAE bytes. The payload type and the canonical statement bytes, framed with explicit byte lengths. Both Ed25519 signatures cover this encoding.
3. Envelope payload. The statement bytes in base64 for transport, beside payloadType and exactly two signatures.

PAE is Pre-Authentication Encoding. Lengths count bytes and are written as decimal ASCII, as this source-test vector on a toy payload shows:

Type:     application/x
Payload:  hello
PAE:      DSSEv1 13 application/x 5 hello

A Chio envelope sets payloadType to application/vnd.in-toto+json. Its statement uses https://in-toto.io/Statement/v1 and the strict predicate type chio.bilateral-cosign-invocation.v1, and the decoded bytes must equal the statement’s canonical re-encoding.

Each keyid is the SHA-256 of the raw Ed25519 public-key bytes and must match the corresponding passport_key_fingerprint in the predicate. The verifier finds each signature by key id, so either array order passes. A duplicate key id, a missing signer, a third signature, or one key shared by A and B is refused.

The statement binds one receipt, one lease, and both verdicts

The strict context check ties the two signatures to records the receiver resolves. The statement names one subject, chio-receipt: plus the receipt id, whose SHA-256 matches the canonical receipt body. Its tool_name and tool_args_hash match that receipt, and the receipt’s own signature comes from the pinned key of tool host B.

Both policy verdicts must agree. The capability lease must resolve with a matching issuer and exact expiry, and a receipt-backed action class needs a resolvable governance receipt. The verifier reads the two recorded verdicts and reruns neither organization’s policy evaluation. Agreement to refuse is evidence too: a unanimous deny verifies, and admission runs its own allow check.

Read more in Invocation commitments and Verdicts.

Offline verification carries its own context

To verify offline, supply locally what the strict verifier reads: the receipt store, the lease and governance records, the pinned keys and ladder references, the action-class map, the evaluation time, and the revocation view. Two signatures and an isolated receipt satisfy only the envelope check.

Time and revocation are inputs. A later check can refuse an expired lease or ladder reference, and retained evidence of an agreement says nothing about whether the same action is authorized now. Both peers need a ladder manifest reference that is fresh at the chosen time.

cargo run --locked --features federation --bin bilateral

#[path = "../receipt.rs"]
mod receipt;
use base64::{engine::general_purpose::STANDARD, Engine};
use chio_core_types::{crypto::Keypair, receipt::body::ChioReceipt};
use chio_federation::bilateral_dsse::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let buyer = Keypair::generate();
    let vendor = Keypair::generate();
    let receipt = ChioReceipt::sign(receipt::receipt_body(&vendor), &vendor)?;
    // Construct one strict invocation statement, then send the same PAE bytes
    // to each operator's signing boundary. Keys stay with their owners.
    let buyer_id = Keyid::from_public_key(&buyer.public_key());
    let vendor_id = Keyid::from_public_key(&vendor.public_key());
    let identity = |kernel: &str, fingerprint: Keyid| KernelIdentity {
        kernel_id: kernel.into(),
        passport_key_fingerprint: fingerprint,
        alg: "ed25519".into(),
    };
    let allow = |policy: &str| PolicyVerdict {
        verdict: "allow".into(),
        policy_id: policy.into(),
        policy_version: "1".into(),
        rationale_code: None,
    };
    let extensions = BilateralPredicateExtensions {
        capability_lease_ref: Some(CapabilityLeaseRef {
            lease_id: "analysis-read-lease".into(),
            issuer: "buyer".into(),
            expires_at_unix_ms: swarm_authority_examples::now_ms() + 60000,
            scope_digest: None,
        }),
        policy_evaluation_summary: Some(PolicyEvaluationSummary {
            server_a_verdict: allow("buyer-read-policy"),
            server_b_verdict: allow("vendor-read-policy"),
            joint_disposition: Some("allow".into()),
        }),
        consistency_model: Some("single-kernel".into()),
        ..Default::default()
    };
    let predicate = build_chio_bilateral_invocation_predicate(
        &receipt,
        identity("buyer", buyer_id.clone()),
        identity("vendor", vendor_id.clone()),
        "read_refund_case",
        swarm_authority_examples::now_ms(),
        extensions,
    )?;
    let statement = build_chio_bilateral_invocation_statement(&receipt, predicate)?;
    let payload = statement.canonical_bytes()?;
    let message = pae(PAYLOAD_TYPE_IN_TOTO, &payload);
    let mut envelope = DsseEnvelope {
        payload_type: PAYLOAD_TYPE_IN_TOTO.into(),
        payload: STANDARD.encode(&payload),
        signatures: vec![
            DsseSignature {
                keyid: buyer_id.0,
                sig: STANDARD.encode(buyer.sign(&message).to_bytes()),
            },
            DsseSignature {
                keyid: vendor_id.0,
                sig: STANDARD.encode(vendor.sign(&message).to_bytes()),
            },
        ],
    };
    verify_chio_bilateral_dsse_envelope(&envelope, &buyer.public_key(), &vendor.public_key())?;
    println!("strict invocation: both operator signatures verified");
    let (mut changed, _) = envelope.decode_statement()?;
    changed.predicate.tool_name = "write_refund_case".into();
    envelope.payload = STANDARD.encode(changed.canonical_bytes()?);
    println!(
        "changed payload: {}",
        verify_chio_bilateral_dsse_envelope(&envelope, &buyer.public_key(), &vendor.public_key())
            .expect_err("signatures must bind the payload")
    );
    Ok(())
}

use chio_core_types::{
    crypto::{sha256_hex, Keypair},
    receipt::{
        body::ChioReceiptBody,
        decision::{Decision, ToolCallAction},
        kinds::TrustLevel,
    },
};
pub fn receipt_body(kp: &Keypair) -> ChioReceiptBody {
    ChioReceiptBody {
        id: "rcpt-chio-bbs".to_string(),
        timestamp: swarm_authority_examples::now_ms() / 1000,
        capability_id: "cap-chio-receipt".to_string(),
        tool_server: "vendor-a.files".to_string(),
        tool_name: "read_refund_case".to_string(),
        action: ToolCallAction::from_parameters(serde_json::json!({
            "path": "/cases/refund-250.json"
        }))
        .expect("fixture action is valid"),
        decision: Some(Decision::Allow),
        receipt_kind: Default::default(),
        boundary_class: Default::default(),
        observation_outcome: None,
        tool_origin: Default::default(),
        redaction_mode: Default::default(),
        actor_chain: Vec::new(),
        content_hash: sha256_hex(b"{\"refund_minor\":25000}"),
        policy_hash: sha256_hex(b"chio-policy"),
        evidence: Vec::new(),
        metadata: Some(serde_json::json!({"workflow_id": "wf-chio-refund-001"})),
        trust_level: TrustLevel::Mediated,
        tenant_id: Some("buyer-tenant".to_string()),
        kernel_key: kp.public_key(),
        bbs_projection_version: None,
    }
}

strict invocation: both operator signatures verified
changed payload: origin (Org A) signature failed verification

The downloadable project creates one strict invocation statement, collects two signatures over its PAE bytes, and verifies them with the buyer and vendor public keys. After it alters the payload, the origin’s signature fails verification.

Read more in Verifier entry points.

Threshold authority travels beside the two signatures

An action whose ladder class requires co_sign: n_of_m adds a FROST authorization. The envelope keeps its two passport signatures, and the aggregate is a separate artifact, verified against its roster and epoch, then passed to verify_chio_bilateral_invocation_with_frost as VerifiedFrostAuthorization.

• The predicate names a treaty_binding_ref, its consistency_model is quorum-required, and its consistency_anchor is frost-quorum.
• The authorization’s action class matches the treaty action class, and its scope id matches the treaty id.
• Its resource id matches invocation_id, and it is current at the pinned time.
• A FROST authorization supplied with an ordinary bilateral mode is refused.

The binding compares those identifiers and the time. Recomputing the action digest from the tool arguments, claiming the current resource version and fence, and keeping the effect single-use with an idempotency key, restored state included, belong to the authorization and effect path.

Read more in FROST Quorum, which covers the roster, signing ceremony, slot lifecycle, and rotation.

Next: put a quorum behind the action