cosenamespacenamespace coseCOSE keys and signatures (RFC 9052, RFC 9053) as WebAuthn uses them (commons 0014-webauthn FR-002): a credential's public key read from its CBOR COSE_Key, checked for one of the two algorithms commons accepts (ES256, -7: ECDSA on P-256 with SHA-256; EdDSA, -8: Ed25519), imported into Web Crypto, and a signature verified with it, an ECDSA signature turned from the DER Ecdsa-Sig-Value an authenticator gives into the raw r || s Web Crypto takes. A COSE_Key can also be made from a public JSON Web Key, which is how a test (or a migration from stored JWKs) writes one.
import { coseKeyFromJwk, parseCoseKey, verifyCose } from "./cose.ts";
const pair = await crypto.subtle.generateKey({ name: "Ed25519" }, true, ["sign", "verify"]);
const cose = coseKeyFromJwk(await crypto.subtle.exportKey("jwk", pair.publicKey));
const data = new TextEncoder().encode("signed");
const sig = new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, pair.privateKey, data));
if (cose.kind === "ok") {
const key = parseCoseKey(cose.value);
if (key.kind === "ok") await verifyCose(key.value, sig, data); // { kind: "ok", value: true }
}cosenamespacenamespace cosecose.ES256constno test imports itconst ES256: -7COSE's identifier of ES256: ECDSA on P-256 with SHA-256.
cose.EDDSAconstno test imports itconst EDDSA: -8COSE's identifier of EdDSA (here always Ed25519).
cose.ALGORITHMSconstno test imports itconst ALGORITHMS: readonly number[]The algorithms commons accepts, in order of preference.
cose.CoseKeytypeno test imports ittype CoseKey =
| { readonly kty: "EC2"; readonly alg: typeof ES256; readonly crv: "P-256"; readonly x: Uint8Array; readonly y: Uint8Array }
| { readonly kty: "OKP"; readonly alg: typeof EDDSA; readonly crv: "Ed25519"; readonly x: Uint8Array };A public key read from a COSE_Key: an EC2 key on P-256 for ES256, or an OKP key on Ed25519 for EdDSA.
cose.parseCoseKeyfunctionno test imports itfunction parseCoseKey(bytes: Uint8Array<ArrayBufferLike>): Result<CoseKey, string>A COSE_Key read from its CBOR: a map with kty (1), alg (3), crv (-1), x (-2) and, for EC2, y (-3); anything else refused.
cose.encodeCoseKeyfunctionno test imports itfunction encodeCoseKey(key: CoseKey): Uint8Array<ArrayBufferLike>The CBOR COSE_Key of a key (deterministic: its labels sorted).
cose.Jwktypeno test imports ittype Jwk = {
readonly alg?: string;
readonly crv?: string;
readonly d?: string;
readonly e?: string;
readonly ext?: boolean;
readonly key_ops?: string[];
readonly kty?: string;
readonly n?: string;
readonly use?: string;
readonly x?: string;
readonly y?: string;
};A JSON Web Key (RFC 7517) as the fields this module reads and writes, declared here so that no consumer needs the dom library for a type of it.
cose.coseKeyFromJwkfunctionno test imports itfunction coseKeyFromJwk(jwk: Jwk): Result<Uint8Array<ArrayBufferLike>, string>The COSE_Key of a public JSON Web Key: EC on P-256 (as ES256) or OKP on Ed25519 (as EdDSA); any other key refused.
cose.jwkOfCoseKeyfunctionno test imports itfunction jwkOfCoseKey(key: CoseKey): JwkThe public JSON Web Key of a COSE key.
cose.importCoseKeyfunctionno test imports itfunction importCoseKey(key: CoseKey): Promise<Result<CryptoKey, string>>The key imported into Web Crypto for verifying; a point not on its curve is refused.
cose.ecdsaDerToRawfunctionno test imports itfunction ecdsaDerToRaw(der: Uint8Array<ArrayBufferLike>, size?: number): Result<Uint8Array<ArrayBufferLike>, string>An ECDSA signature as DER (Ecdsa-Sig-Value ::= SEQUENCE { r INTEGER, s INTEGER }) turned into raw r || s of size bytes each.
cose.verifyCosefunctionno test imports itfunction verifyCose(key: CoseKey, signature: Uint8Array<ArrayBufferLike>, data: Uint8Array<ArrayBufferLike>): Promise<Result<boolean, string>>Whether signature is the key's signature of data (ES256: DER as WebAuthn gives it; EdDSA: 64 raw bytes); an unusable key or a malformed signature is an error.
ES256constconst ES256: -7COSE's identifier of ES256: ECDSA on P-256 with SHA-256.
EDDSAconstconst EDDSA: -8COSE's identifier of EdDSA (here always Ed25519).
ALGORITHMSconstno test imports itconst ALGORITHMS: readonly number[]The algorithms commons accepts, in order of preference.
CoseKeytypeno test imports ittype CoseKey =
| { readonly kty: "EC2"; readonly alg: typeof ES256; readonly crv: "P-256"; readonly x: Uint8Array; readonly y: Uint8Array }
| { readonly kty: "OKP"; readonly alg: typeof EDDSA; readonly crv: "Ed25519"; readonly x: Uint8Array };A public key read from a COSE_Key: an EC2 key on P-256 for ES256, or an OKP key on Ed25519 for EdDSA.
parseCoseKeyfunctionfunction parseCoseKey(bytes: Uint8Array<ArrayBufferLike>): Result<CoseKey, string>A COSE_Key read from its CBOR: a map with kty (1), alg (3), crv (-1), x (-2) and, for EC2, y (-3); anything else refused.
encodeCoseKeyfunctionfunction encodeCoseKey(key: CoseKey): Uint8Array<ArrayBufferLike>The CBOR COSE_Key of a key (deterministic: its labels sorted).
Jwktypeno test imports ittype Jwk = {
readonly alg?: string;
readonly crv?: string;
readonly d?: string;
readonly e?: string;
readonly ext?: boolean;
readonly key_ops?: string[];
readonly kty?: string;
readonly n?: string;
readonly use?: string;
readonly x?: string;
readonly y?: string;
};A JSON Web Key (RFC 7517) as the fields this module reads and writes, declared here so that no consumer needs the dom library for a type of it.
coseKeyFromJwkfunctionfunction coseKeyFromJwk(jwk: Jwk): Result<Uint8Array<ArrayBufferLike>, string>The COSE_Key of a public JSON Web Key: EC on P-256 (as ES256) or OKP on Ed25519 (as EdDSA); any other key refused.
jwkOfCoseKeyfunctionfunction jwkOfCoseKey(key: CoseKey): JwkThe public JSON Web Key of a COSE key.
importCoseKeyfunctionno test imports itfunction importCoseKey(key: CoseKey): Promise<Result<CryptoKey, string>>The key imported into Web Crypto for verifying; a point not on its curve is refused.
ecdsaDerToRawfunctionfunction ecdsaDerToRaw(der: Uint8Array<ArrayBufferLike>, size?: number): Result<Uint8Array<ArrayBufferLike>, string>An ECDSA signature as DER (Ecdsa-Sig-Value ::= SEQUENCE { r INTEGER, s INTEGER }) turned into raw r || s of size bytes each.
verifyCosefunctionfunction verifyCose(key: CoseKey, signature: Uint8Array<ArrayBufferLike>, data: Uint8Array<ArrayBufferLike>): Promise<Result<boolean, string>>Whether signature is the key's signature of data (ES256: DER as WebAuthn gives it; EdDSA: 64 raw bytes); an unusable key or a malformed signature is an error.