knowa_patch_format library

The on-the-wire format for a signed Knowa patch.

Shared by the signing tool and the on-device loader so that both agree, byte for byte, on what is signed.

Layout

  offset  size  field
       0     5  magic "KNOWA"
       5     1  format version (currently 1)
       6     4  metadata length, big-endian uint32
      10     N  metadata, UTF-8 JSON
    10+N    64  Ed25519 signature
 74+N..     *   payload (compiled patch)

The signature covers metadata bytes || payload bytes, so metadata cannot be swapped between payloads or edited without invalidating it.

The metadata bytes are stored verbatim and verified as stored, never re-encoded from the parsed object: JSON key order and whitespace are not canonical.

Classes

PatchEnvelope
A parsed patch container.
PatchMetadata
Describes what a patch is and what it targets.
RevocationBody
What a revocation says.
RevocationRecord
A parsed revocation record.

Constants

knownPlatforms → const List<String>
The platforms a patch can be signed for, named as Flutter's TargetPlatform values in lower case.
patchFormatVersion → const int
Changes only for incompatible layout changes. The loader refuses versions it does not recognise.
patchMagic → const List<int>
Identifies a Knowa patch container.
publicKeyLength → const int
Ed25519 public keys are always 32 bytes.
revocationFormatVersion → const int
Changes only for incompatible layout changes.
revocationMagic → const List<int>
Identifies a Knowa revocation record.
signatureLength → const int
Ed25519 signatures are always 64 bytes.

Functions

buildSignedBytes(Uint8List metadataBytes, Uint8List payload) → Uint8List
The exact bytes an Ed25519 signature is computed over.
decodePatch(Uint8List bytes) → PatchEnvelope
Parses a container. Throws PatchFormatException on anything malformed.
decodeRevocation(Uint8List bytes) → RevocationRecord
Parses a revocation record. Throws PatchFormatException on anything malformed, which callers treat as "no revocation".
encodePatch({required PatchMetadata metadata, required Uint8List payload, required List<int> signer(Uint8List signedBytes)}) → Uint8List
Builds a container.
encodeRevocation({required RevocationBody body, required List<int> signer(Uint8List bodyBytes)}) → Uint8List
Builds a revocation record.
keyFingerprint(List<int> publicKeyBytes) → String
A short, stable identifier for an Ed25519 public key.
sha256OfPayload(List<int> payload) → String

Exceptions / Errors

PatchFormatException
Raised for any malformed container. Callers treat this as "no patch".