cose library

COSE signed transport for CrateStack Dart/Flutter clients (ADR 0006, cratestack#1026): seal a request and open a response with cratestack-cose, the one Rust implementation, reached through the same backends as the CBOR codec: flutter_rust_bridge natively and the cratestack-cbor-wasm build on the web. Nothing here implements COSE or any crypto in Dart.

Import it next to the codec; a codec-only app imports nothing new:

import 'package:cratestack_cbor/cose.dart';

final envelope = await ClientEnvelope.create(
  signer: Ed25519Signer.fromSeed(seed),
  serverKeys: [CoseServerKey.ed25519(serverPublicKey)],
  audience: 'payments',
);

Keystore keys. A key that must not enter the process (Android Keystore, Secure Enclave, WebCrypto) signs through a callback; see ExternalSigner:

final signer = ExternalSigner.esp256(
  publicKey: publicKey, // SEC1 point (either form) or SubjectPublicKeyInfo
  timeout: const Duration(seconds: 60),
  sign: (tbs) async {
    try {
      return SignOutcome.signature(await keystore.sign(tbs));
    } on UserDismissed {
      return const SignOutcome.cancelled();
    }
  },
);

Errors. Everything the Rust side refuses is a CoseException (a sealed class: CoseRejected, CoseMisuse, and the signer variants). Dart-side argument checks that cannot be right are ArgumentError, thrown by the constructors of the key and binding types before any bridge call, and ClientEnvelope.contractHeaderValue before the backend has started is a StateError.

This client is Required-only, like the Rust client: it seals every request and opens only responses to a sealed request.

Classes

CallBinding
The inputs a call's signature is bound to (ADR 0006 §4). The audience is the envelope's, not the call's.
CancelledOutcome
The prompt was dismissed; see SignOutcome.cancelled.
ClientEnvelope
Seals requests and opens responses for one service (ADR 0006).
CoseServerKey
A key the server's responses verify with, pinned at enrolment.
CoseSigner
Who signs a request. Sealed: HmacSigner and Ed25519Signer hold their key in memory (service credentials and tests); ExternalSigner never has the key, which stays in the Android Keystore, the Secure Enclave or WebCrypto, and only asks it to sign.
Ed25519Signer
Signs a COSE_Sign1 with the Ed25519 key of a 32-byte seed.
ExternalSigner
Signs a COSE_Sign1 (ESP256) with a P-256 key that never enters this process: one in the Android Keystore, the iOS Secure Enclave, WebCrypto, or any other store that can sign but not export (cratestack#1151).
FailedOutcome
The keystore failed; see SignOutcome.failed.
HmacSigner
Signs a COSE_Mac0 with a shared secret of at least 32 random bytes.
Opened
A response that verified.
SignedOutcome
The keystore signed; see SignOutcome.signature.
SignOutcome
What a keystore signing call ended with.
TimedOutOutcome
The keystore was too slow; see SignOutcome.timedOut.

Enums

CoseAlg
The four algorithms of ADR 0006 §2.
CoseMode
The message structure an envelope emits and accepts.

Typedefs

SignCallback = Future<SignOutcome> Function(Uint8List toBeSigned)
Signs the complete to-be-signed bytes with a keystore key: ECDSA over SHA-256 of exactly toBeSigned, never of a digest of it. Returns a SignOutcome; see ExternalSigner.

Exceptions / Errors

CoseException
Why sealing a request or opening a response failed.
CoseMisuse
The caller or its configuration is wrong: a key of the wrong length, an empty audience, a binding of the wrong shape.
CoseRejected
The message did not verify (the coarse 401): a tampered body, a wrong key, a response to another request, a stale or replayed message. Never says which.
CoseSignerCancelled
The person dismissed the keystore's prompt: an ExternalSigner whose callback returned SignOutcome.cancelled.
CoseSignerFailed
The keystore failed: the callback of an ExternalSigner returned SignOutcome.failed (the message is the callback's), or threw (the message names only the exception's type). A signature that is not a valid one by the key is CoseMisuse instead, because the callback did not fail.
CoseSignerTimedOut
The keystore did not answer in time: the callback of an ExternalSigner returned SignOutcome.timedOut, or exceeded ExternalSigner.timeout.