Skip to content

aead-value 0.6: rename FfiValue to Value, make it Clone and non_exhaustive, move transport's framing tags #371

Description

@coderdan

Background

vitaminc-aead-value is the value model behind vitaminc's encryption traits:
FfiValue is a value whose type is known only at runtime, as it arrives from
JavaScript, Go or Python. Each scalar seals as a one-byte type tag plus its
payload, inside the encrypted envelope. That tag table is frozen, because
stored ciphertexts depend on it. The transport module is a separate encoding
for handing a value tree across WebAssembly memory; it is never stored.

Problem

  1. The name misleads. FfiValue reads as "a type for FFI", but it is the
    value model for any vitaminc cipher. Reviewers have proposed moving the
    crate into Stack Encrypt on that basis.
  2. It can't be cloned. Stack Encrypt's plan engine clones a field's
    plaintext per operation, so it wraps FfiValue in its own dynamic::Value
    only to add Clone (packages/stack-encrypt/src/dynamic/value.rs).
  3. Adding a kind is a breaking change. FfiValue and ValueKind are
    exhaustive enums.
  4. Transport's framing tags block the tag table. ARRAY, OBJECT and
    PASSTHROUGH are 0x10, 0x11 and 0x12 (transport.rs:27-35), and
    transport reuses the scalar tag numbers for its leaves. So the next scalar
    tags can't use 0x10 to 0x12 without colliding.

Proposal

  1. Rename FfiValue to Value, keeping
    #[deprecated] pub type FfiValue = Value; for one release.
  2. Implement Clone as a deep copy that rebuilds every leaf into a fresh
    Protected, as Stack Encrypt's duplicate() does today. Document that a
    clone is under the same custody as its original.
  3. Mark Value and ValueKind #[non_exhaustive].
  4. Move ARRAY, OBJECT and PASSTHROUGH to 0xF0, 0xF1 and 0xF2, in
    Rust and in Go's vcffi together. Transport carries no compatibility
    commitment, and every user of it ships with its peer.

Breaking; part of 0.6.0. Decided in ADR-0002 (cipherstash/stack#1139).

Relationship to other work

Activity

  1. self-assigned this
    on Oct 9, 2026
  2. added a commit that references this issue on Oct 9, 2026
    f569e55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions