​

ADR 0006: COSE Envelope Modes and Key Management

​

Status

​

Date

​

Decisions

• the JSON file store writes a temporary file, fsyncs it, then renames it over the old one. Today it uses a plain std::fs::write, which is not crash-atomic.
• SQLite uses one transaction.
• Redis uses MULTI/EXEC or a Lua script.

• Nothing assumes a signature length. Buffers, size limits and the chain checkpoint parser size the signature from alg, never from a hard-coded 64 bytes.
• A hybrid is one alg value. A composite algorithm identifier (a classical and a post-quantum signature over the same Sig_structure, as in the IETF composite-signature work) goes in the existing alg header, and the composite key’s thumbprint prefix is the kid. The COSE structure, the AAD and the checkpoint payload do not change, so adding it is not a wire break.
• Resolution is by (kid, alg), as CoseVerifierResolver::resolve already specifies. One device can hold a classical key and a hybrid key side by side during migration.
• The AAD’s binding-version field (§4, currently 1) is the escape hatch if a future scheme needs a different binding.

• Algorithm identifiers (§3): -19 (Ed25519) and -9 (ESP256), the fully specified algorithms of RFC 9864, which deprecates -8 (EdDSA) and -7 (ES256). Both encode in one byte, so no size changes. Nothing has shipped with -8/-7, so verifiers accept only -19 and -9 (and the Mac0 ids).
• REST responses are bound to the resource, not only to the route shape (§4). The AAD gains path_params: the matched path parameter values in template order, as the router decoded them (empty for RPC, whose op id and body digest already bind it). With the template alone, a signed GET /accounts/1 response would verify as the answer to GET /accounts/2. That gap matters because Q1 signs every GET response.
• Crate placement (§11): cratestack-cose sits at L2 with an optional auth feature. Without the feature it depends on cratestack-core only, so clients and the wasm/napi builds stay free of cratestack-auth’s Redis, reqwest and rustls dependencies. With it, the crate owns everything auth-specific too: the ServiceSigningKey and DeviceKeyResolver adapters, the Redis nonce bridge, and the COSE enrolment code. cratestack_auth::{build,parse}_cose_enroll_response move there, which is a breaking change (no known in-repo consumers).
• P0 defaults:
  • The shared vectors cover both cti shapes: 16 random bytes (P0 nonce mode) and a 2-byte counter (the §3 measurements). cti is injectable on the seal side for that purpose.
  • Multi-replica nonce replay bridges cratestack-auth’s existing Redis nonce store, keyed by (kid, cti).
  • DeviceKeyResolver gains a required lookup-by-thumbprint method. This is breaking, so implementors get a compile error instead of every COSE device request failing silently.
  • A Mac0 kid is the RFC 9679 thumbprint prefix of the key. Deployers list their key ids so the thumbprints can be precomputed, and secrets shorter than 32 bytes are rejected.
  • Errors, per §10: every failed check is the same coarse 401; a backend outage (key resolver or nonce store) is a 500.
  • The schema SHA first hashed the raw .cstack text, so a comment-only schema edit would reject every signed client. cratestack#1065 replaced it with a canonical schema identity (§4, “Schema identity (#1065)”). That still refused every client on any schema edit, so binding version 2 replaced it in the AAD with the called op’s contract digest (§4, “Op contracts”).

• The AAD binds the op’s contract digest, not the schema’s. Element 7 is contract_sha, the digest of the wire closure of the op being called. BINDING_VERSION is 2.
• An unbound Cratestack-Contract header selects the digest. It carries the first 8 bytes of the digest (unpadded base64url, 11 characters) and chooses which of the digests the server already accepts for the op to verify under. The signature covers all 32 bytes, so the header widens nothing.
• A digest the server does not accept is an unsigned 426 contract_unsupported, answered before any key is looked up. Without the header, the server tries the accepted digests newest first, at most a configured number (default 4).
• The response is sealed under the digest the request used.
• Version 2 verifiers refuse version 1, with no opt-in.
• A signed /rpc/batch binds the whole-contract digest for now, accepted only when it equals the server’s current one. Per-frame digests are a follow-up.
• The compatible-history lock (digests of older contracts a server still accepts, checked by a classifier) shipped in the change after binding version 2 (cratestack#1123, 2026-09-30): see §4, “The compatible-history lock”. Without a lock the accepted list per op has one member.

• The AAD binds the recipient (§4). A new audience element carries a configured logical service identifier, not the Host header, which gateways rewrite. Without it:
  • one signed request opens at any two services that share a schema and a route, each with its own nonce store;
  • in Mac0 mode, a service’s own outgoing request is a valid incoming request to itself.
• Signed responses to bodiless requests are fresh (§4). A GET has no body, so its request digest used to be SHA-256("") every time, and a year-old signed response still verified for a new GET of the same URL. The client now sends Cratestack-Nonce: 16 random bytes, base64url without padding, on every request it wants a verified response to, which in Required mode is all of them. For an unsigned request, request_digest = SHA-256(nonce ‖ payload). Each signed response is then bound to exactly one request, with no server state.
• Encode in place stays (§1), through an additive hook. CratestackCodec gains a provided encode_into and CratestackEnvelope a provided seal_value. The COSE envelope overrides seal_value to encode straight into its output buffer, so neither trait merged in cratestack#1066 breaks. HMAC and ES256 compute over the MAC/Sig structure incrementally. So does Ed25519, using the two-pass PureEdDSA streaming in ed25519-dalek’s MultipartSigner (maintainer, 2026-09-25). That is the same computation as the hazmat module’s streaming API, but dalek expands the key itself, which avoids the key-leak misuse hazmat warns about. No algorithm makes a contiguous to-be-signed copy. Streamed signatures are byte-identical to the standard sign for every vector and a range of payload sizes. The streamed verify is as strict as verify_strict: dalek’s streaming verify does not check that R decompresses, that R is not small-order, or that the public key is not weak, so cratestack adds those checks itself, and tests prove each one matters.
• A response binds the kind of request it answers (§4). The response AAD carries request_kind: 0 means the request was unsigned and its digest is SHA-256(nonce ‖ payload); 1 means it was signed and its digest is SHA-256(request COSE bytes). Without it, the two digest forms could collide: a signed request C re-presented as an unsigned twin with nonce C[..16] and body C[16..] produced a server response that verified as the answer to C. A response carries request_kind, request_digest and status together; a request carries none of them.
• An empty audience is misuse (a 500), because it silently gives up the protection. A service’s inbound audience must differ from the audience it uses when sending to peers: a shared name such as internal defeats reflection protection.
• Kept as specified: the replay store is keyed by (kid, cti). Two keys that share an 8-byte kid could interfere, but targeting that costs about 2⁶⁴ work and only causes a denial of service. The Mac0 KeyProvider adapter refuses an empty id list, a repeated id, and two ids that resolve to the same secret; it reads the keys once at load, so a rotation means a rebuild.
• Security hardening, found by the same review and implemented in #1005:
  • the verified principal is the thumbprint of the key that actually verified, and that key’s kid must match the header;
  • an HMAC key is bound to exactly one of alg 4 or 5, so a 256/256 deployment never accepts a 64-bit tag;
  • ESP256 signatures are low-S only, which keeps “one message, one encoding”;
  • the skew bound is validated when the envelope is built.

​

Context

​

What exists today

• It signs a different serialization than it sends. The MAC covers serde_json::to_vec(&body), while the envelope travels as CBOR. Verification works only because both sides re-serialize a serde_json::Value identically. Any value that JSON represents lossily (bytes, big integers, CBOR tags, float edge cases) breaks that silently. COSE removes the issue: the payload is a byte string, and the verifier checks the bytes it received.
• It spends bytes badly: 147 B per message, against 41 B for the COSE_Mac0 equivalent.

​

Codec parity today

​

Measurements

​

Goals and non-goals

• End-to-end integrity and origin authentication of payloads. They must survive TLS-terminating hops (CDNs, load balancers, operator and corporate proxies), storage in the offline SQLite store, and relay between devices.
• Low byte overhead, especially on the uplink and on streams.
• Streaming as a first-class case: incremental verification, detectable truncation, and resumption (P3).
• Offline-first: a mutation signed when it was created stays valid for upload days later, without opening a replay hole.
• Auth headers become optional for signed traffic. A verified COSE key identifies the caller, so writes do not also need Authorization: Signature (§12).
• No canonicalization anywhere. Verify the exact bytes that were sent.
• One Rust implementation shared by the Rust, JS (wasm/napi) and Flutter (FRB) clients.

• Confidentiality. TLS covers transit; COSE_Encrypt0 for data at rest can come later on the same structure.
• Multi-signer COSE_Sign, or COSE_Mac with recipients.
• Replacing TLS or the enrolment protocol.

​

Decision (proposed)

​

1. Layering: the codec stays simple, the envelope binds

typed value ──CborCodec──▶ payload bytes ──CoseEnvelope──▶ COSE_Sign1 / COSE_Mac0 / chain
                               ▲                              │
                               └──────── verified as-is ◀─────┘

/// Replaces the current sync, bytes-only trait (only `NoEnvelope` implements it today).
pub trait CratestackEnvelope: Clone + Send + Sync + 'static {
    fn media_type(&self, shape: BodyShape) -> &'static str;

    fn seal<'a>(&'a self, payload: Bytes, bind: &'a Binding<'a>)
        -> BoxFuture<'a, Result<Bytes, CratestackError>>;

    /// Verifies, runs replay checks, records the principal (kid → device/service)
    /// in ctx, and returns the payload slice (zero-copy into `body`).
    fn open<'a>(&'a self, body: Bytes, bind: &'a Binding<'a>, ctx: &'a mut CratestackContext)
        -> BoxFuture<'a, Result<Bytes, CratestackError>>;

    /// `None` = this envelope does not sign streams (plain cbor-seq passes through).
    fn stream_sealer(&self, bind: Binding<'static>) -> Option<Box<dyn StreamSealer>>;
    fn stream_opener(&self, bind: Binding<'static>) -> Option<Box<dyn StreamOpener>>;
}

/// Everything that goes into external_aad. Built by router/client, never sent (§4).
pub struct Binding<'a> {
    pub audience: &'a str,                 // configured logical service identifier (the recipient)
    pub method: &'a str,
    pub route: &'a str,                    // op_id for RPC; route template for REST
    pub path_params: &'a [&'a str],        // REST: matched values in template order; RPC: empty
    pub query: Option<&'a str>,            // canonical_query()
    pub contract_sha: &'a [u8; 32],        // the called op's contract digest (binding version 2)
    pub payload_media_type: &'a str,       // "application/cbor"
    pub response: Option<ResponseBinding>, // responses only; None on requests
}

/// All three travel together: a half-built response binding does not compile.
pub struct ResponseBinding {
    pub request: RequestDigest,            // { kind: Unsigned (0) | Signed (1), digest: [u8; 32] }
    pub status: u16,
}

#[async_trait]
pub trait CoseSigner: Send + Sync + 'static {
    fn alg(&self) -> coset::iana::Algorithm;
    fn kid(&self) -> &[u8];                  // 8-byte thumbprint prefix, §3
    async fn sign(&self, to_be_signed: &[u8]) -> Result<Vec<u8>, CratestackError>;
}

#[async_trait]
pub trait CoseVerifierResolver: Send + Sync + 'static {
    /// May return several candidates on kid-prefix collision; the opener tries each.
    async fn resolve(&self, kid: &[u8], alg: coset::iana::Algorithm)
        -> Result<Vec<VerifyingKey>, CratestackError>;
}

​

2. Media types

​

3. Message layout

; Unary: COSE_Sign1 = tag 18, COSE_Mac0 = tag 17 (always tagged on the wire)
protected = {
  1 => int,                ; alg: -19 Ed25519 (default), -9 ESP256 (RFC 9864); Mac0: 4 = HMAC 256/64, 5 = HMAC 256/256
  4 => bstr .size 8,       ; kid: first 8 bytes of the RFC 9679 COSE Key Thumbprint
  ? 15 => {                ; CWT Claims (RFC 9597), requests only
    ? 6 => int,            ;   iat, seconds
    ? 7 => bstr,           ;   cti: device counter (1–4 bytes) or 16 random bytes, §5
  }
}
unprotected = {}           ; always empty: nothing unauthenticated on the wire
payload     = bstr .cbor Body

• kid = an 8-byte thumbprint prefix. It is derived from the key, so no kid strings are stored, and rotation is self-describing. The birthday bound is about 2³² keys, and the resolver returns several candidates on the rare collision.
• Algorithms by direction.
  • Device → server: Ed25519 (-19). Device keys are already Ed25519, and these messages must be provable later.
  • Server → client: Ed25519 by default, or ESP256 (-9) where the key lives in an HSM or as non-extractable WebCrypto (Q2).
  • Service → service inside one trust domain: Mac0 HMAC 256/256, or HMAC 256/64 on constrained links. A 64-bit tag is safe only because forgery requires online attempts, and those are rate limited.
• Why not Mac0 for devices? It is cheaper (41 B against 98 B), but with a symmetric key the server could forge device messages, so non-repudiation is lost.

​

4. External AAD: binding without bytes on the wire

external_aad = bstr .cbor [
  2,                        ; binding version
  audience: tstr,           ; the recipient: a configured logical service id, never the Host header
  method: tstr,
  route: tstr,              ; RPC op_id (stable across prefix rewrites); REST route template
  path_params: [* tstr],    ; REST: matched path parameter values in template order; RPC: []
  query: tstr / null,       ; canonical_query()
  contract_sha: bstr .size 32, ; the called op's contract digest (see "Op contracts")
  payload_type: tstr,       ; "application/cbor"
  bound_headers: [          ; request headers with semantics, exactly as sent (UTF-8, untrimmed)
    idempotency_key: tstr / null,
    if_match: tstr / null,
  ],
  ? request_kind: uint,             ; responses: 0 = unsigned request, 1 = signed request
  ? request_digest: bstr .size 32,  ; responses: kind 1 → SHA-256 over the request's COSE bytes;
                                    ; kind 0 → SHA-256(Cratestack-Nonce ‖ payload)
  ? status: uint,                   ; responses
]

• A request binding has 9 elements and a response binding 12. bound_headers is always present: [null, null] when a request carries neither header, and a response repeats its request’s values.
• A request that carries either header twice, or a value that is not UTF-8, is refused with an unsigned 400 before anything is bound.
• An empty value binds as "", not null.
• It defeats an on-path party that strips Idempotency-Key from a re-sealed retry (the operation would run twice), or that strips or changes If-Match (a conditional update would become a blind one).
• Response headers (ETag, Retry-After) remain unauthenticated.

• Version 1 bound schema_sha, the whole-schema identity below. Every change before its freeze was part of it: path_params, audience, the nonce-based unsigned digest, and cratestack#1065’s schema identity. It froze with 0.15.0, the first release in which generated routers and clients put the envelope on the wire (cratestack#1006, #1007). (Decision 2026-09-26, taken when v0.13.0 was cut: tying the freeze to the crate’s first release would have forced a new version for #1065 with no peer to be compatible with.)
• Version 2 (cratestack#1123, 2026-09-30, 0.15.2) replaces element 7 with contract_sha, the called op’s contract digest. Every other element keeps its position, so the array lengths (9 and 12) are unchanged, and the version number is the domain separation: the same 32 bytes under 1 and 2 never produce the same AAD.
• From 0.15.0 on, any change to the element list or to how an element is derived bumps the version. Verifiers reject versions they do not accept, and a version 2 verifier accepts only 2: accepting version 1 would cost a second trial verification on every failure (the version is not on the wire) and keep a downgrade path alive for peers that, one day after 0.15.0, almost certainly had not shipped. Version 1 peers must be upgraded together with their servers.

• cross-endpoint replay: a body signed for payment.create fails on payment.refund;
• response swapping: a response is bound to its request and its status code;
• wire-shape drift, per op: a client whose wire shape for an op differs from the server’s fails closed for that op, and only that op;
• cross-service replay and reflection: the audience names the recipient;
• header stripping: bound_headers covers Idempotency-Key and If-Match;
• stale responses: an unsigned request’s digest includes the client’s Cratestack-Nonce, so a signed response answers exactly one request;
• digest-form confusion: request_kind keeps a response to an unsigned request from verifying as the response to a signed one.

• Excluded: source spans, /// docs, and the whitespace of attribute text outside string literals, including """ SQL bodies (@default( false ) is @default(false)). Comments never reach the parser’s output. The contents of "...", '...' and """...""" literals stay verbatim, because @@sql("...") bodies and regexes carry meaning in their whitespace. Still digest-changing, by design (fail-loud): reordering attributes, a trailing comma in [...], and - 1 versus -1.
• Sorted by name: top-level declarations (models, types, enums, mixins, procedures, views, queries) and the fields of models, types, mixins and views, so moving a declaration is not a contract change. When the positional P3 codec (§9) lands, whatever assigns its ids (declared in the schema or kept in a lockfile) must enter the identity, or the domain tag must move to /v2; field order is sorted away today, so ids cannot ride on it.
• Declared order kept: enum variants, attribute lists and procedure arguments. No codec encodes a variant by its index (enums travel by name), but the first variant is the type’s Default and Postgres orders an enum by declaration, so the order is part of the contract.
• Built by hand, versioned by tag. The canonical form is written node by node rather than by serialising the IR, so a new IR field enters the digest by a deliberate edit and never through a #[serde(default)]. A golden digest test pins it; the /v1 tag makes any later change to the form a new identity on purpose.
• Cost (why version 2 exists): the whole IR is hashed, not only the wire surface, so a server-only edit (a policy, an @@index, a view’s SQL) also changed the digest, and every client built before the edit was refused with an unsigned 401 indistinguishable from a revoked key. Mobile clients cannot be force-updated, so under Required each schema deploy would lock out every installed app.

• In the digest: the op’s transport, key and kind, its input and output roots (a procedure’s arguments and return type; for a model op the verb and the model), and the closure: every model, type, enum and view reachable from the roots through field types, generic arguments, relations and @computed(params:), each in its wire projection (@server_only fields removed, since they are on no wire). The key is the RPC op_id, or "<METHOD> <route template>" on REST, so @api_version is in it.
• Out of it (DROPPED_ATTRIBUTES, each entry reviewed against the generators that read it, with a test that pins the readers): @@allow, @@deny, procedure @allow/@deny/@authorize, @@index, @@sql bodies, @@audit, @@retain, @@internal (it decides whether an op exists, which is the key), @@unique, @@soft_delete, @@subscribe/@@emit, @no_idempotency, @no_rate_limit, @isolation, @pii, @sensitive, @db_enforce, field @unique, view @from, procedure @deprecated, and the value validators (@length, @regex, @email, @range, …). The datasource, config blocks, extension blocks, the auth block, the schema-level MCP config, queries, unreachable declarations, every other op, docs and spans are out entirely.
• Fail-loud: an attribute not on the reviewed list stays in, including attributes added later, so a new one moves digests until someone reviews it onto the list.
• Derivation. SHA-256(b"cratestack/op-contract/v1\0" ‖ canonical JSON), written node by node with every IR node destructured exhaustively, like the schema identity. If the derivation rules change, the tag moves to op-contract/v2. A second digest, client_contract_digest = SHA-256(b"cratestack/client-contract/v1\0" ‖ canonical JSON of the sorted [key, hex(op digest)] table), is the build identity of the whole client-facing contract, and what a signed /rpc/batch binds.
• Not caught, as before: a semantic change with no shape change (an Int switching from major to minor units). A later @contract_revision(n) attribute could force a break on purpose.

• Header present and naming an accepted digest: one verification.
• Header present and naming none: an unsigned 426 with RpcErrorBody { code: "contract_unsupported" } (REST CONTRACT_UNSUPPORTED), before any key lookup.
• Header absent (a hand-built client): the op’s accepted digests are tried newest first, capped (default 4). A nonce is recorded only after a message verifies, so a failed trial burns nothing, and the COSE envelope parses the message and resolves its key once (open_request_any), so a forged message costs one parse, one key resolution and at most the cap in verifications.
• The response is sealed under the digest the request opened under.
• A signed /rpc/batch has one AAD and many ops: until frames carry their own digests it binds the whole-contract digest, accepted only when equal to the server’s.
• The accepted list per op is [current], plus the older digests of a committed lock that a conservative classifier judges wire-compatible (next paragraph).

​

5. Freshness and replay, offline-aware

• No time limit on validity: a request signed days ago is accepted if its counter is new.
• Out-of-order delivery within the window is tolerated, which covers parallel batch uploads.
• Server state is O(1) per device.
• iat is still signed, for audit and for an optional per-op policy such as @signed(max_age: "30d").
• The device persists the counter in the same write as the queued mutation. A reused counter reads as a replay (Q4). Reinstalling the app re-enrols with a fresh key.
• Multi-replica servers keep the per-kid window in Redis or PG with compare-and-set, using the backends the idempotency and rate-limit stores already use.

​

6. Streams: chain mode

h₀ = SHA-256(external_aad)                      ; binds the chain to this request, 0 bytes sent
hᵢ = SHA-256(hᵢ₋₁ ‖ itemᵢ_bytes)

checkpoint = #6.48901(COSE_Sign1)               ; payload:
  [ seq: uint, h_seq: bstr .size 32, ? resume: bstr, ? end: true / RpcErrorBody ]

• Cadence: every 64 items, 32 KiB or 2 s, whichever comes first (Q3). Ops can override with @stream(checkpoint: 16|64|256).
• The terminal checkpoint is mandatory. It carries end: true, or the RpcErrorBody on failure. In signed mode it replaces the unsigned Tag(48900, …) sentinel, so a forged error is detectable too.
• Truncation is detectable. A body that ends without a terminal checkpoint is Incomplete. Today a stream cut short by a middlebox that closes cleanly looks like a short, successful stream.
• Reordering, dropping or injecting items breaks h at the next checkpoint.
• Detection: RPC_STREAM_ERROR_TAG gets a sibling RPC_STREAM_CHECKPOINT_TAG = 48901. The Rust CborSeqChunkDecoder and the TS scanner (packages/cratestack-ts-types/src/cbor-seq.ts) classify the leading tag. The tag wrapper keeps a checkpoint distinct from a legitimate item that is itself a COSE_Sign1.

• Verified buffers items until their checkpoint verifies. Added latency is at most one checkpoint interval, and memory is at most N items.
• Optimistic releases items at once and raises a tamper error at the checkpoint. This fits the offline store: a SQLite transaction per checkpoint window, committed when it verifies and rolled back when it doesn’t.

​

7. Uploads: signing the offline queue

1. When a mutation is created offline, the Rust runtime wraps it as a COSE_Sign1 RpcRequest frame with cti = next counter and persists those exact bytes. The queue is tamper-evident at rest, and iat records the device clock at creation.
2. On connectivity, the client flushes with POST /rpc/batch and Content-Type: application/vnd.cratestack.cose-seq+cbor-seq. Each frame is independently signed.
3. The server verifies each frame on its own. Results return as a chain-signed cbor-seq keyed by cti, so a partial failure fails only its frames.
4. After a dropped connection the client resends the unacknowledged frames. Anything already applied hits the §5 idempotency path.

​

8. Key distribution

• Server signing keys are published as a COSE_KeySet at /.well-known/cratestack/cose-keys, next to the existing jwks_router. The client pins at enrolment: the enrolment response is already a COSE_Sign1 (cose_enroll.rs) and gains the response-signing key thumbprint(s).
• Device keys use the existing DeviceKeyResolver, indexed additionally by thumbprint prefix.
• Rotation: the keyset holds old and new keys, and the kid selects between them.

​

9. Schema-bound integer keys (separate codec, P3)

​

10. Errors and threat model

• Verification failures return 401 with RpcErrorBody{code: "unauthenticated"} and a coarse reason. The response must never reveal which check failed. A backend failure (the key resolver or the nonce store is unreachable) is a 500, logged server-side: it says nothing about the message, and operators can tell an outage from an attack.
• One refusal is unsigned and not a 401: 426 contract_unsupported (binding version 2). It answers a Cratestack-Contract selector that names no digest accepted for the op, before any key lookup, so it reveals only that this op’s wire shape is no longer served: public information, since the digests ship in every client binary. It is not one of the checks this section forbids telling apart (signature, key, freshness, replay, audience, AAD). Being unsigned it is a hint, never proof: the client surfaces EnvelopeError::ContractUnsupported { op } and must not treat the server’s contract as known. The client reads the body only for its code, so a proxy’s own 426 stays Unsigned. It deliberately carries no Upgrade header: RFC 9110 §15.5.22 asks for one, but Upgrade is connection-specific (§7.8), forbidden on HTTP/2 (RFC 9113 §8.2.2) and stripped by proxies, and no protocol token names an op contract; 426 is kept because every other 4xx already means something else here (409 idempotency and transactions, 410 heuristically cacheable, 412 conditional headers, 400 the malformed selector).
• Error responses are signed too, or a hop could inject fake errors.
• A client in Required mode rejects unsigned or wrongly signed responses. It never falls back to plain.
• Why sign over TLS at all: TLS ends at the first terminating hop. Signed data stays verifiable at rest and when relayed between devices. Financial audit needs non-repudiation. Signed responses can be cached by untrusted edges.
• Existing mechanisms:
  • HmacEnvelope becomes Mac0 mode: deprecated for one minor release, then removed.
  • Authorization: Signature stays for bodiless requests (GET). For writes in signed mode, COSE subsumes it (method and route are in the AAD) and saves about 300 B of headers.
  • The 48900 sentinel is unchanged in unsigned mode.
  • The idempotency stream bypass still applies to signed streams.

​

11. One implementation, every client

• cratestack-client-rust (native, plus the Flutter runtime via FRB), which lifts the “not implemented” guard;
• cratestack-cbor-wasm and -napi, which gain seal, open and a chunk-fed StreamOpener. The React Native story in cratestack#893 plans a Rust-backed codec on device and inherits this.

​

12. Placement relative to the existing layers

• The envelope must run before rate limiting and idempotency. Both layers derive their caller key from the Authorization header by default: they hash it, fall back to the ConnectInfo peer, and refuse with 412 when neither exists (cratestack-axum/src/{ratelimit/key_fn.rs,idempotency/}). A COSE-only client sends no Authorization header, so it would be bucketed by IP address or refused. The envelope’s open therefore runs first and inserts the verified kid as a VerifiedPrincipal request extension. Rate limiting already treats that as a non-caller-mintable princ: bucket that needs no cardinality budget (cratestack#871), which closes the “unverified header mints buckets” class for signed traffic. The idempotency principal fingerprint needs the same hook. This is P0, not a later phase: without it, the P0 wiring breaks existing throttling and replay behaviour for COSE clients.
• The (kid, cti) idempotency key belongs in the L3 OpExecutor (ADR 0015). Its input is not an HTTP request, which is exactly the property that motivated building L3. Idempotency admission (slice 1) and rate-limit admission (slice 2, cratestack#877) already decide there. The in-process path from ADR 0018 then gets the same replay semantics without a second implementation.

​

Consequences

• One signing mechanism replaces HmacEnvelope and, for writes, Authorization: Signature, at a quarter to a third of their byte cost.
• Signed streams cost single-digit percent over unsigned, and truncation becomes detectable, which it is not today.
• Offline mutations stay valid for upload indefinitely without a replay hole.

• Breaking change to CratestackEnvelope, and to RuntimeEnvelopeConfig consumers once the placeholder becomes real.
• New server state per device key (the window), with compare-and-set on multi-replica deployments.
• Clients that bypass the Rust runtime cannot use signed mode.

​

Alternatives considered

• COSE as a CratestackCodec implementation. Rejected (§1): no key, no request context, no async, and it would touch every codec bound in the workspace.
• Per-item signing as the stream default. Rejected on the measurements: ×4.25 after compression. It remains available per op.
• Timestamp skew plus a nonce store for device keys. Rejected for devices (§5): it cannot accept an offline mutation older than the skew window. It stays the mode for service keys.
• Mac0 for device traffic. Rejected (§3): a symmetric key lets the server forge device messages.

​

Phasing

​

Test plan (acceptance)

• Vectors: identical bytes from Rust native, wasm and napi for the same key and payload. Deterministic Ed25519 makes this exact.
• Tampering: flip one bit in each of the payload, the protected header, the AAD route, the AAD contract digest and the request digest → reject. A request bound under another op’s digest (neg-contract-cross-op) and one signed over a version 1 AAD (neg-binding-v1) → reject. Assert on encoded bytes, not decoded values.
• Contract lock: a locked, compatible older digest opens and its response seals under it; an incompatible lock entry is a compile error naming the op and reason. Candidates that differ in anything but the contract digest, and an empty candidate list, are refused before any key lookup.
• Streams: truncate before the terminal checkpoint → Incomplete. Reorder, drop or insert an item → reject at the next checkpoint. A forged error item → reject. A legitimate COSE_Sign1 item → not treated as a checkpoint.
• Replay: resend the same bytes → idempotent response, handler not re-run. Counter below the window → reject. Out of order within the window → accept. Counter reuse → reject.
• Offline: mutation signed at T, uploaded at T+72 h → accepted in window mode, rejected in nonce mode.
• Layer placement (§12): a COSE-only request with no Authorization header and no ConnectInfo → not refused with 412, and charged to its princ: bucket.
• Fuzzing: CborSeqChunkDecoder over arbitrary bytes containing tags 18, 48900 and 48901.