Skip to content

stack-encrypt refactor: add explicit owned whole-value blob encryption #1484

Closed

Description

@coderdan

Background

Stack Encrypt (packages/stack-encrypt) is the Rust engine that every CipherStash language SDK runs on. Its scalar API encrypts one value of a supported kind, such as text, a number, or a timestamp. It refuses a struct or a Vec, on purpose.

Sometimes a program needs to store a whole composite value, such as a settings struct, as one ciphertext, with no search terms. The Stack Encrypt API plan, merged in pull request #1365, calls this an opaque blob. Go already stores opaque values.

Problem

A developer who needs this today might serialise the value themselves. That gives no versioning, and no protection of the plaintext. A blanket fallback for every Serialize type would make that easy to do by accident.

Proposal

Add an explicit OpaqueBlob<T> adapter.

  • Choose a codec that the library defines, and document it. Document the authenticated type marker and version, the supported types, schema changes, and decode errors.
  • Encode a whole composite as one opaque Ciphertext. Keep it separate from collection batching and from structural trees.
  • Authenticate before decoding. Protect the source value, the encoder's growing buffers, decoded intermediates, and partial failures.
  • Document the timing and length that a blob reveals. Arbitrary Serde types do not serialise in constant time, so do not imply that they do.
  • Store and reload a blob through a fresh cipher. Add fixed test vectors, malformed input tests, and cross-language exchange.
  • Return ordinary owned results. Specify any opt-in result adapter that wipes on drop. Zeroize alone does not wipe on drop, so do not imply that it does.

Follows #1470. Coordinate the secure buffer with #1468, and the lifecycle evidence with #1480. Reuse Vitamin C's storage and codec contracts and Go's existing opaque values. Do not invent a second wire format.

Pull request #1503 does this work and closes this issue.

Plans: the Stack Encrypt API plan and the conformance roadmap.

Activity

  1. self-assigned this
    on Nov 1, 2026
  2. added 2 commits that reference this issue on Nov 8, 2026
    3e3a6f3
    c0d3cbd
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

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions