Skip to content

Implement canonical signed and encrypted mailbox envelopes #4628

Open

Description

@auser

Agent pickup triage

Category: needs reconciliation. This classifies the next task, not completion or a verified current-source pass.

Next bounded step: Reconcile merged #4694 against each acceptance item and its exact test evidence before changing canonical envelope code; identify any actual remaining gap rather than reimplementing it.

Handoff evidence: PR. PR states at triage: #4694 merged.

Read the linked handoff and coordinate any active owner before implementation. Preserve the original acceptance criteria below; this triage grants no spending, credentials, publication, host reconfiguration, or landing authority.


Parent: #4622

Depends on #4627.

Outcome

Implement one canonical, versioned mailbox envelope and capability-verification path for immutable pass-by-value messages. Authorization must be derived from verified capabilities and current execution state, never from sender-supplied routing fields alone.

Repository boundary and migration

  • Add the canonical DTOs under mvm-contract::protocol::mailbox; this becomes the sole source of wire truth for standalone MVM and mvmd consumers.
  • Define transport-neutral MailboxId, MessageId, DeliveryId, authorization-domain and workload/mailbox addresses, message kind (call, cast, reply), correlation/causation IDs, reply routing, deadlines, execution epochs, ordering scope/sequence, capabilities, envelopes, receipts, ACK/NACK outcomes, versions, and bounds.
  • Do not embed mvmd organization, fleet, node, instance, placement, or coordinator-RBAC types. mvmd may wrap the canonical address with those fields.
  • Do not put key generation, encryption/decryption I/O, storage, routing, or coordinator logic in mvm-contract; runtime implementations consume the DTOs.
  • Audit the existing mvmd-types::MailboxAddress, MailboxAssignment, EncryptedMailboxEnvelope, DeliveryLease, LeasedMessage, AckDelivery, and NackDelivery. Reuse validated semantics, but do not preserve accidental mvmd ownership or the incomplete V1 shape.
  • Replace the mvmd.mailbox.v1 cryptographic domain with an MVM-owned, versioned domain chosen by the ADR.

Scope

  • Canonical serialization and domain-separated signatures.
  • Recipient or mailbox-domain encryption with explicit algorithm and version identifiers.
  • Tenant, authorization domain, mailbox, sender, recipient, boot/session epoch, execution epoch, message ID, correlation ID, causation ID, sequence, issued-at, expiry, nonce, content type, payload length, capability reference, and encryption context.
  • Capability validation for send, receive, reply, monitor, and administer operations.
  • Destination-signed acceptance receipts distinguishing accepted, duplicate, expired, refused, full, and unavailable outcomes.
  • Bounded parsing before allocation and payload disclosure.

Acceptance criteria

  • Envelope and receipt types round-trip through the canonical wire codec without losing signed fields.
  • mvm-contract remains no_std + alloc compatible under its protocol feature and introduces no dependency from mvm to mvmd.
  • The canonical schema includes call/cast/reply, correlation, causation, reply routing, deadline, execution epoch, ordering, capability/policy reference, protocol/algorithm version, and destination acceptance receipt semantics.
  • Mutating any signed field or ciphertext causes verification to fail closed.
  • Wrong sender, recipient, tenant, mailbox, capability scope, execution epoch, expiry, nonce, or signature is rejected.
  • Replayed message IDs and stale epochs are detected without claiming global exactly-once processing.
  • Unknown protocol, algorithm, and content-type versions fail with typed errors and no payload logging.
  • Size and nesting limits are enforced before attacker-controlled allocation becomes unbounded.
  • Positive, tamper, wrong-key, replay, expiry, and boundary-size tests cover the public contract.
  • A checked compatibility fixture documents whether the current mvmd JSON envelope is migrated, temporarily decoded through a version adapter, or rejected as pre-production disposable data.
  • tinylabscom/mvmd#254 is updated to consume this contract and remove duplicate canonical DTO ownership from mvmd-types.

Activity

  1. added
    enhancementNew feature or request
    mailboxesSigned pass-by-value mailbox program
    mailbox-phase-1Mailbox foundations and protocol decisions
    on Oct 22, 2026
  2. reopened this on Oct 26, 2026
  3. auser commented on Nov 2, 2026

    @auser
    CollaboratorAuthor

    Independent read-only reconciliation at main 662176d74eda5351be5d5be689370d6527475a05 supports checking acceptance boxes 2–10 inclusive only.

    • #4694, merged as 0c233d22aef392371631a915a4180ec17d4467c7, supplies the canonical DTOs, no_std + alloc protocol surface, whole-object signatures and authenticated ciphertext, identity/capability/epoch/expiry/replay/version gates, bounded decoding, compatibility fixture, and public-contract outcome tests. The schema covers call/cast/reply, correlation, causation, reply routing, deadline, execution epoch, ordering, capability/policy references, protocol/algorithm versions, and destination acceptance receipts.
    • Signed-field, ciphertext, receipt, wrong-key, wrong-identity, scope, expiry, nonce, replay, stale-epoch, unknown-version, and boundary-size cases fail closed with typed errors that do not carry payload data. Replay detection is explicitly process-local and makes no global exactly-once claim.
    • #4885, merged as ed0109de500af41b6cf6921da0f547feb12f0e67, adds the within-size-cap deep-nesting regression, completing box 8’s nesting evidence.
    • The checked legacy mvmd JSON fixture is explicitly rejected as pre-production disposable data rather than silently migrated or reinterpreted.

    Source and outcome-test inspection only; no new tests were run. Boxes 1 and 11 were not assessed or changed and remain outside this reconciliation.

  4. auser commented on Nov 9, 2026

    @auser
    CollaboratorAuthor

    Current-source reconciliation of the two remaining boxes (mvm@63e751d428f2eb1c1f3effef43cc88a89dfb206b, mvmd@50d64da294a4eb2ca34885b64b90e1abada2f6b2)

    Box 1 verified and checked. The canonical MVM envelope codec is encode_envelope/decode_envelope: JCS encoding, size/version checks before decoding, and deny_unknown_fields DTOs. envelope_roundtrips_and_opens_without_losing_signed_fields encodes, decodes, checks exact envelope identity, verifies sender signature and capability, and opens the original bytes; destination_receipt_wire_roundtrip_and_signature_cover_outcome_and_identity JCS-encodes the signed receipt, decodes it, checks exact equality and verifies its signature, then shows outcome tampering fails. Executed cargo test -p mvm-core --test mailbox_crypto on the macOS host: 18 passed, 0 failed. No new codec or crypto was needed. This is a codec/receipt witness, not destination durable acceptance or an end-to-end delivery witness.

    Box 11 remains unchecked and #4628 remains open. Current MVMD still defines its own fleet MailboxAddress, EncryptedMailboxEnvelope, DeliveryLease and ACK/NACK DTOs (prototype DTO), signs with mvmd.mailbox.v1 and has encrypt/decrypt helpers in mvmd-core (legacy crypto), and its API sends/leases/ACKs those prototype types rather than the MVM canonical envelope (API). mvmd-mvm alone path-depends on mvm-contract as a detached optional adapter; the main MVMD mailbox path does not (adapter manifest). None of these prototype codepaths is evidence of canonical consumption. Exact next step is tinylabscom/mvmd#254: inventory rows/API clients, decide explicit bounded compatibility vs tested pre-production rejection, make the coordinator a canonical ciphertext/metadata consumer with separate fleet placement wrappers and no mailbox decryption keys, and validate cross-repo conformance. #4629's standalone service is a dependency for the complete MVMD integration, so do not close #4628 by changing a type alias or by checking the MVMD box prematurely.

    Validation not run: cargo test --workspace, clippy, gated Linux/build VM, live-vsock, or MVMD tests. No source changes, PR, push, shared-branch merge, or billable host.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestmailbox-phase-1Mailbox foundations and protocol decisionsmailboxesSigned pass-by-value mailbox program

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions