# What changed in @owf/cose

> 44 changes in @owf/cose 0.2 to 0.5 from its official release notes, upgrade guides and advisories: 24 breaking, 3 security, 10 new APIs and options. Each one cited. Sources checked 2026-10-27. HTML: https://unstale.sh/npm/@owf/cose/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## @owf/cose 0.5

### Breaking changes

- 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. (0.5.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#050)
- Token verification now rejects a token at its exp instant, including when the current time is exactly exp plus the skew. (0.5.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#050)

### Security

- 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. (0.5.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#050)

## @owf/cose 0.4

### Breaking changes

- Requires payload and header structure classes as a second argument so decoding validates and types the result against those structures. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- Is now a CwtPayload rather than Uint8Array or null; detached payloads and invalid claims sets produce dedicated errors at fromToken. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- The typ header is readable as Cwt.typ and reads protected headers only; keyId still falls back to unprotected headers. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- Is no longer a Sign1Options or Mac0Options union; Cwt takes a CwtPayload as payload plus signatureOrTag, and signed bytes are payloadBytes. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- externalAad is removed from CwtOptions; pass it to the call that uses it instead. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- externalAad is removed from Mac0Options; pass it to the call that uses it instead. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- The externalAad property is removed; pass externalAad to the call that uses it instead. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- externalAad is removed from Sign1Options; pass it to the call that uses it instead. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- Requires protected typ to be application/statuslist+cwt; absent typ is still defaulted, but a different typ is rejected. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- Removed; use RegisteredCwtHeaderClaimKey.Typ instead. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- Replaces getCustomClaim and infers the claim value type instead of taking it as a type argument. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- Replaced by getClaim, which infers the claim value type. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- Header buckets are expressed as typed subclasses with schemas from extendCoseHeaderClaims; each bucket validates only against its own schema. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)

### Security

- Reports in-place header value mutations that the header map cannot detect, so retained encoded bytes are not used after modification. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- Provides the protected header type used to require StatusListCwt typ to be application/statuslist+cwt. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)

### New APIs and options

- Verifies a token's signature or tag, claims, and subclass verifications; supports both Sign1 and Mac0 verification. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- Forwards the payload class's own option type, including options required by extended CWT payload types. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- CWT payloads are expressed as subclasses with schemas from extendCwtPayloadClaims and typed accessors for registered RFC 8392 claims. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- 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. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- Header buckets are expressed as typed subclasses with schemas from extendCoseHeaderClaims; protected headers use protectedHeadersSchema. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- 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. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)

### Fixes and other changes

- Remains available as a read-only getter over the separate signature and tag fields. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- Describes fromEncodedStructure as returning the structure instance rather than something to re-wrap, preserving state such as retained bytes. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- 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. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)
- 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. (0.4.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#040)

## @owf/cose 0.3

### Breaking changes

- Mac0 and Sign1 replace algorithmName with algorithm, a COSE Algorithm identifier, and jwaAlgorithm, a JOSE Algorithm identifier. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)
- 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. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)
- The x509 context's getPublicKey return value is restricted to CoseKey. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)
- kid is validated as a bstr when decoding protected and unprotected headers, rejecting malformed values such as { 4: undefined } in Sign1-derived structures. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)
- Mac0Context's mac method is renamed to authenticate. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)
- The mac0 and sign1 structures are no longer passed to the context; the already encoded data is provided instead. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)
- The verification method now only allows CosKey. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)
- The x509 context no longer allows an array of certificates. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)
- The context method's alg parameter is renamed to optional algorithm, which is a COSE algorithm identifier. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)

### New APIs and options

- Sign1 and Mac0 verification methods receive algorithm as an optional parameter. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)
- The cosekey algorithm can also be a MacAlgorithm. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)
- Some support is added for obtaining the public and private key for ed25519. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)
- Status list info objects are added for referenced status list tokens. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)

### Behavior and default changes

- ProtectedHeaders and UnprotectedHeaders use TypedMap-backed structures; headers keeps kid typed as a bstr while allowing access to other integer labels. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)

### Fixes and other changes

- 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. (0.3.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#030)

## @owf/cose 0.2

### Tooling

- The package.json was aligned for export; the notes do not specify further details. (0.2.0) — [release notes](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/4f0b8736a475d2b457d8c7d770df0e65187661d9/packages/cose/CHANGELOG.md#020)