npm / @owf/cose
@owf/cose
What changed in @owf/cose 0.2 to 0.5, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-27.
24 breaking3 security10 new APIs and options1 behavior and defaults1 tooling5 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@owf/cose 0.53 changes
Breaking changes 2
The package publishes only ESM, removing the dual-package hazard that caused instanceof checks to fail in Metro/Hermes and similar single-module-system runtimes.
Token verification now rejects a token at its exp instant, including when the current time is exactly exp plus the skew.
Security 1
Reads x5chain from the protected header, or from the unprotected header when a protected x5t (SHA-256) matches its leaf; an unbound unprotected x5chain throws CoseX5ChainNotBoundError.
@owf/cose 0.425 changes
Breaking changes 13
Requires payload and header structure classes as a second argument so decoding validates and types the result against those structures.
Is now a CwtPayload rather than Uint8Array or null; detached payloads and invalid claims sets produce dedicated errors at fromToken.
The typ header is readable as Cwt.typ and reads protected headers only; keyId still falls back to unprotected headers.
Is no longer a Sign1Options or Mac0Options union; Cwt takes a CwtPayload as payload plus signatureOrTag, and signed bytes are payloadBytes.
externalAad is removed from CwtOptions; pass it to the call that uses it instead.
externalAad is removed from Mac0Options; pass it to the call that uses it instead.
The externalAad property is removed; pass externalAad to the call that uses it instead.
externalAad is removed from Sign1Options; pass it to the call that uses it instead.
Requires protected typ to be application/statuslist+cwt; absent typ is still defaulted, but a different typ is rejected.
Removed; use RegisteredCwtHeaderClaimKey.Typ instead.
Replaces getCustomClaim and infers the claim value type instead of taking it as a type argument.
Replaced by getClaim, which infers the claim value type.
Header buckets are expressed as typed subclasses with schemas from extendCoseHeaderClaims; each bucket validates only against its own schema.
Security 2
Reports in-place header value mutations that the header map cannot detect, so retained encoded bytes are not used after modification.
Provides the protected header type used to require StatusListCwt typ to be application/statuslist+cwt.
New APIs and options 6
Verifies a token's signature or tag, claims, and subclass verifications; supports both Sign1 and Mac0 verification.
Forwards the payload class's own option type, including options required by extended CWT payload types.
CWT payloads are expressed as subclasses with schemas from extendCwtPayloadClaims and typed accessors for registered RFC 8392 claims.
Checks required claims, expected iss/sub/aud, and token validity against now with a default skewSeconds of 30 seconds. CWT types can override it to apply their own rules.
Header buckets are expressed as typed subclasses with schemas from extendCoseHeaderClaims; protected headers use protectedHeadersSchema.
Adds keyLabels so validation errors can name numeric CBOR labels; a numeric TypeScript enum can be passed directly, and several can be merged with a spread.
Fixes and other changes 4
Remains available as a read-only getter over the separate signature and tag fields.
Describes fromEncodedStructure as returning the structure instance rather than something to re-wrap, preserving state such as retained bytes.
Pass externalAad to each sign or verify call that may use it instead of storing it on Sign1, Mac0, or Cwt structures; this fixes its use when provided.
Returns the original protected-header bstr after decoding, preserving the exact bytes used in signature or MAC verification; modified maps encode from the map as before.
@owf/cose 0.315 changes
Breaking changes 9
Mac0 and Sign1 replace algorithmName with algorithm, a COSE Algorithm identifier, and jwaAlgorithm, a JOSE Algorithm identifier.
Detached payload is no longer available on Sign1 and Mac0 classes; provide it directly to the method classes. It cannot be provided when an embedded payload is present.
The x509 context's getPublicKey return value is restricted to CoseKey.
kid is validated as a bstr when decoding protected and unprotected headers, rejecting malformed values such as { 4: undefined } in Sign1-derived structures.
Mac0Context's mac method is renamed to authenticate.
The mac0 and sign1 structures are no longer passed to the context; the already encoded data is provided instead.
The verification method now only allows CosKey.
The x509 context no longer allows an array of certificates.
The context method's alg parameter is renamed to optional algorithm, which is a COSE algorithm identifier.
New APIs and options 4
Sign1 and Mac0 verification methods receive algorithm as an optional parameter.
The cosekey algorithm can also be a MacAlgorithm.
Some support is added for obtaining the public and private key for ed25519.
Status list info objects are added for referenced status list tokens.
Behavior and default changes 1
ProtectedHeaders and UnprotectedHeaders use TypedMap-backed structures; headers keeps kid typed as a bstr while allowing access to other integer labels.
Fixes and other changes 1
For Mac0 and Sign1, alg is extracted only from protected headers, and failure to extract it no longer throws because the COSE spec does not require it.
@owf/cose 0.21 changes
Tooling 1
The package.json was aligned for export; the notes do not specify further details.