@atproto/jwk 0.5.0 → 0.7.0-next.0

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@atproto/jwk",
-  "version": "0.5.0",
+  "version": "0.7.0-next.0",
+  "engines": {
+    "node": ">=22"
+  },
   "license": "MIT",
   "description": "A library for working with JSON Web Keys (JWKs) in TypeScript. This is meant to be extended by environment-specific libraries like @atproto/jwk-jose.",
   "keywords": [
@@ -16,9 +19,7 @@
     "url": "https://github.com/bluesky-social/atproto",
     "directory": "packages/oauth/jwk"
   },
-  "type": "commonjs",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -26,13 +27,13 @@
     }
   },
   "dependencies": {
-    "multiformats": "^9.9.0",
+    "multiformats": "^13.0.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "typescript": "^5.6.3"
+    "typescript": "^6.0.3"
   },
   "scripts": {
-    "build": "tsc --build tsconfig.json"
+    "build": "tsc --build tsconfig.build.json"
   }
 }

package/src/alg.ts

@@ -1,29 +1,29 @@
 import { JwkError } from './errors.js'
-import { Jwk } from './jwk.js'
+import { JwkBase, isEncKeyUsage, isSigKeyUsage } from './jwk.js'
 
 // Copy variable to prevent bundlers from automatically polyfilling "process" (e.g. parcel)
 const { process } = globalThis
 const IS_NODE_RUNTIME =
   typeof process !== 'undefined' && typeof process?.versions?.node === 'string'
 
-export function* jwkAlgorithms(jwk: Jwk): Generator<string> {
+export function* jwkAlgorithms(jwk: JwkBase): Generator<string, void, unknown> {
   // Ed25519, Ed448, and secp256k1 always have "alg"
-  // OKP always has "use"
-  if (jwk.alg) {
+
+  if (typeof jwk.alg === 'string') {
     yield jwk.alg
     return
   }
 
   switch (jwk.kty) {
     case 'EC': {
-      if (jwk.use === 'enc' || jwk.use === undefined) {
+      if (jwkSupportsEnc(jwk)) {
         yield 'ECDH-ES'
         yield 'ECDH-ES+A128KW'
         yield 'ECDH-ES+A192KW'
         yield 'ECDH-ES+A256KW'
       }
 
-      if (jwk.use === 'sig' || jwk.use === undefined) {
+      if (jwkSupportsSig(jwk)) {
         const crv = 'crv' in jwk ? jwk.crv : undefined
         switch (crv) {
           case 'P-256':
@@ -54,7 +54,7 @@ export function* jwkAlgorithms(jwk: Jwk): Generator<string> {
     }
 
     case 'RSA': {
-      if (jwk.use === 'enc' || jwk.use === undefined) {
+      if (jwkSupportsEnc(jwk)) {
         yield 'RSA-OAEP'
         yield 'RSA-OAEP-256'
         yield 'RSA-OAEP-384'
@@ -62,7 +62,7 @@ export function* jwkAlgorithms(jwk: Jwk): Generator<string> {
         if (IS_NODE_RUNTIME) yield 'RSA1_5'
       }
 
-      if (jwk.use === 'sig' || jwk.use === undefined) {
+      if (jwkSupportsSig(jwk)) {
         yield 'PS256'
         yield 'PS384'
         yield 'PS512'
@@ -75,7 +75,7 @@ export function* jwkAlgorithms(jwk: Jwk): Generator<string> {
     }
 
     case 'oct': {
-      if (jwk.use === 'enc' || jwk.use === undefined) {
+      if (jwkSupportsEnc(jwk)) {
         yield 'A128GCMKW'
         yield 'A192GCMKW'
         yield 'A256GCMKW'
@@ -84,7 +84,7 @@ export function* jwkAlgorithms(jwk: Jwk): Generator<string> {
         yield 'A256KW'
       }
 
-      if (jwk.use === 'sig' || jwk.use === undefined) {
+      if (jwkSupportsSig(jwk)) {
         yield 'HS256'
         yield 'HS384'
         yield 'HS512'
@@ -97,3 +97,15 @@ export function* jwkAlgorithms(jwk: Jwk): Generator<string> {
       throw new JwkError(`Unsupported kty "${jwk.kty}"`)
   }
 }
+
+function jwkSupportsEnc(jwk: JwkBase): boolean {
+  return (
+    jwk.key_ops?.some(isEncKeyUsage) ?? (jwk.use == null || jwk.use === 'enc')
+  )
+}
+
+function jwkSupportsSig(jwk: JwkBase): boolean {
+  return (
+    jwk.key_ops?.some(isSigKeyUsage) ?? (jwk.use == null || jwk.use === 'sig')
+  )
+}

package/src/jwk.ts

@@ -1,45 +1,96 @@
 import { z } from 'zod'
+import { isLastOccurrence } from './util.js'
 
-export const keyUsageSchema = z.enum([
+export const PUBLIC_KEY_USAGE = ['verify', 'encrypt', 'wrapKey'] as const
+export const publicKeyUsageSchema = z.enum(PUBLIC_KEY_USAGE)
+export type PublicKeyUsage = (typeof PUBLIC_KEY_USAGE)[number]
+export function isPublicKeyUsage(usage: unknown): usage is PublicKeyUsage {
+  return (PUBLIC_KEY_USAGE as readonly unknown[]).includes(usage)
+}
+
+/**
+ * Determines if the given key usage is consistent for "sig" (signature) public
+ * key use.
+ */
+export function isSigKeyUsage(v: KeyUsage) {
+  return v === 'verify'
+}
+
+/**
+ * Determines if the given key usage is consistent for "enc" (encryption) public
+ * key use.
+ *
+ * > When a key is used to wrap another key and a public key use
+ * > designation for the first key is desired, the "enc" (encryption)
+ * > key use value is used, since key wrapping is a kind of encryption.
+ * > The "enc" value is also to be used for public keys used for key
+ * > agreement operations.
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7517#section-4.2}
+ */
+export function isEncKeyUsage(v: KeyUsage) {
+  return v === 'encrypt' || v === 'wrapKey'
+}
+
+export const PRIVATE_KEY_USAGE = [
   'sign',
-  'verify',
-  'encrypt',
   'decrypt',
-  'wrapKey',
   'unwrapKey',
   'deriveKey',
   'deriveBits',
-])
+] as const
+export const privateKeyUsageSchema = z.enum(PRIVATE_KEY_USAGE)
+export type PrivateKeyUsage = (typeof PRIVATE_KEY_USAGE)[number]
+export function isPrivateKeyUsage(usage: unknown): usage is PrivateKeyUsage {
+  return (PRIVATE_KEY_USAGE as readonly unknown[]).includes(usage)
+}
 
-export type KeyUsage = z.infer<typeof keyUsageSchema>
+export const KEY_USAGE = [...PRIVATE_KEY_USAGE, ...PUBLIC_KEY_USAGE] as const
+export const keyUsageSchema = z.enum(KEY_USAGE)
+export type KeyUsage = (typeof KEY_USAGE)[number]
 
 /**
- * The "use" and "key_ops" JWK members SHOULD NOT be used together;
- * however, if both are used, the information they convey MUST be
- * consistent.  Applications should specify which of these members they
- * use, if either is to be used by the application.
- *
- * @todo Actually check that "use" and "key_ops" are consistent when both are present.
- * @see {@link https://datatracker.ietf.org/doc/html/rfc7517#section-4.3}
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7517#section-4 JSON Web Key (JWK) Format}
+ * @see {@link https://www.iana.org/assignments/jose/jose.xhtml#web-key-parameters IANA "JSON Web Key Parameters" registry}
  */
-export const jwkBaseSchema = z.object({
+const jwkBaseSchema = z.object({
   kty: z.string().min(1),
   alg: z.string().min(1).optional(),
   kid: z.string().min(1).optional(),
-  ext: z.boolean().optional(),
   use: z.enum(['sig', 'enc']).optional(),
-  key_ops: z.array(keyUsageSchema).optional(),
+  key_ops: z
+    .array(keyUsageSchema)
+    .min(1, { message: 'At least one key usage must be specified' })
+    // https://datatracker.ietf.org/doc/html/rfc7517#section-4.3
+    // > Duplicate key operation values MUST NOT be present in the array.
+    .refine((ops) => ops.every(isLastOccurrence), {
+      message: 'key_ops must not contain duplicates',
+    })
+    .optional(),
 
   x5c: z.array(z.string()).optional(), // X.509 Certificate Chain
   x5t: z.string().min(1).optional(), // X.509 Certificate SHA-1 Thumbprint
   'x5t#S256': z.string().min(1).optional(), // X.509 Certificate SHA-256 Thumbprint
   x5u: z.string().url().optional(), // X.509 URL
+
+  // https://www.w3.org/TR/webcrypto/
+  ext: z.boolean().optional(), // Extractable
+
+  // Federation Historical Keys Response
+  // https://openid.net/specs/openid-federation-1_0.html#name-federation-historical-keys-res
+  iat: z.number().int().optional(), // Issued At (timestamp)
+  exp: z.number().int().optional(), // Expiration Time (timestamp)
+  nbf: z.number().int().optional(), // Not Before (timestamp)
+  revoked: z //  properties of the revocation
+    .object({
+      revoked_at: z.number().int(),
+      reason: z.string().optional(),
+    })
+    .optional(),
 })
 
-/**
- * @todo: properly implement this
- */
-export const jwkRsaKeySchema = jwkBaseSchema.extend({
+export type JwkBase = z.infer<typeof jwkBaseSchema>
+
+const jwkRsaKeySchema = jwkBaseSchema.extend({
   kty: z.literal('RSA'),
   alg: z
     .enum(['RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512'])
@@ -62,12 +113,11 @@ export const jwkRsaKeySchema = jwkBaseSchema.extend({
         t: z.string().optional(),
       }),
     )
-    .nonempty()
-
+    .min(1)
     .optional(), // Other Primes Info
 })
 
-export const jwkEcKeySchema = jwkBaseSchema.extend({
+const jwkEcKeySchema = jwkBaseSchema.extend({
   kty: z.literal('EC'),
   alg: z.enum(['ES256', 'ES384', 'ES512']).optional(),
   crv: z.enum(['P-256', 'P-384', 'P-521']),
@@ -78,7 +128,7 @@ export const jwkEcKeySchema = jwkBaseSchema.extend({
   d: z.string().min(1).optional(), // ECC Private Key
 })
 
-export const jwkEcSecp256k1KeySchema = jwkBaseSchema.extend({
+const jwkEcSecp256k1KeySchema = jwkBaseSchema.extend({
   kty: z.literal('EC'),
   alg: z.enum(['ES256K']).optional(),
   crv: z.enum(['secp256k1']),
@@ -89,7 +139,7 @@ export const jwkEcSecp256k1KeySchema = jwkBaseSchema.extend({
   d: z.string().min(1).optional(), // ECC Private Key
 })
 
-export const jwkOkpKeySchema = jwkBaseSchema.extend({
+const jwkOkpKeySchema = jwkBaseSchema.extend({
   kty: z.literal('OKP'),
   alg: z.enum(['EdDSA']).optional(),
   crv: z.enum(['Ed25519', 'Ed448']),
@@ -98,54 +148,116 @@ export const jwkOkpKeySchema = jwkBaseSchema.extend({
   d: z.string().min(1).optional(), // ECC Private Key
 })
 
-export const jwkSymKeySchema = jwkBaseSchema.extend({
+const jwkSymKeySchema = jwkBaseSchema.extend({
   kty: z.literal('oct'), // Octet Sequence (used to represent symmetric keys)
   alg: z.enum(['HS256', 'HS384', 'HS512']).optional(),
 
   k: z.string(), // Key Value (base64url encoded)
 })
 
-export const jwkUnknownKeySchema = jwkBaseSchema.extend({
-  kty: z
-    .string()
-    .refine((v) => v !== 'RSA' && v !== 'EC' && v !== 'OKP' && v !== 'oct'),
-})
-
+/**
+ * Zod parser for known JWK types
+ */
 export const jwkSchema = z
   .union([
-    jwkUnknownKeySchema,
     jwkRsaKeySchema,
     jwkEcKeySchema,
     jwkEcSecp256k1KeySchema,
     jwkOkpKeySchema,
     jwkSymKeySchema,
   ])
+  // @TODO These rules should be applied to jwkBaseSchema, but Zod 3 doesn't
+  // support extending refined schemas. Move these to the base schema when we
+  // upgrade to Zod 4.
+  .refine(
+    // https://datatracker.ietf.org/doc/html/rfc7517#section-4.2
+    // > The "use" (public key use) parameter identifies the intended use of the
+    // > public key
+    (k): boolean => k.use == null || isPublicJwk(k),
+    {
+      message: '"use" can only be used with public keys',
+      path: ['use'],
+    },
+  )
+  .refine(
+    (k): boolean => !k.key_ops?.some(isPrivateKeyUsage) || isPrivateJwk(k),
+    {
+      message: 'private key usage not allowed for public keys',
+      path: ['key_ops'],
+    },
+  )
   .refine(
-    (k) =>
-      // https://datatracker.ietf.org/doc/html/rfc7517#section-4.3
-      // > The "use" parameter is employed to indicate whether a public key is
-      // > used for encrypting data or verifying the signature on data.
-      !k.use ||
-      !k.key_ops ||
-      k.key_ops.every(
-        k.use === 'sig' ? (o) => o === 'verify' : (o) => o === 'decrypt',
-      ),
+    // https://datatracker.ietf.org/doc/html/rfc7517#section-4.3
+    // > The "use" and "key_ops" JWK members SHOULD NOT be used together;
+    // > however, if both are used, the information they convey MUST be
+    // > consistent.
+    (k): boolean =>
+      k.use == null ||
+      k.key_ops == null ||
+      (k.use === 'sig' && k.key_ops.every(isSigKeyUsage)) ||
+      (k.use === 'enc' && k.key_ops.every(isEncKeyUsage)),
     {
-      message: 'use and key_ops must be consistent',
+      message: '"key_ops" must be consistent with "use"',
       path: ['key_ops'],
     },
   )
 
-export type Jwk = z.infer<typeof jwkSchema>
+export type Jwk = z.output<typeof jwkSchema>
 
-/** @deprecated use {@link jwkSchema} */
+/** @deprecated use {@link jwkSchema} instead */
 export const jwkValidator = jwkSchema
 
 export const jwkPubSchema = jwkSchema
-  .refine((k) => k.kid != null, 'kid is required')
-  .refine((k) => !('k' in k) && !('d' in k), 'private key not allowed')
+  .refine(hasKid, {
+    message: '"kid" is required',
+    path: ['kid'],
+  })
+  // @NOTE for legacy reasons, we don't impose the presence of either "use" or "key_ops"
+  .refine(isPublicJwk, {
+    message: 'private key not allowed',
+  })
+  .refine((k): boolean => !k.key_ops || k.key_ops.every(isPublicKeyUsage), {
+    message: '"key_ops" must not contain private key usage for public keys',
+    path: ['key_ops'],
+  })
+
+export type PublicJwk = z.output<typeof jwkPubSchema>
+
+export const jwkPrivateSchema = jwkSchema
+  // @NOTE we don't impose the presence of "kid"
+  .refine(isPrivateJwk, {
+    message: 'private key required',
+  })
+
+export type PrivateJwk = z.output<typeof jwkPrivateSchema>
+
+export function hasKid<J extends object>(
+  jwk: J,
+): jwk is J & { kid: NonNullable<unknown> } {
+  return 'kid' in jwk && jwk.kid != null
+}
+
+export function hasSharedSecretJwk<J extends object>(
+  jwk: J,
+): jwk is J & { k: NonNullable<unknown> } {
+  return 'k' in jwk && jwk.k != null
+}
+
+export function hasPrivateSecretJwk<J extends object>(
+  jwk: J,
+): jwk is J & { d: NonNullable<unknown> } {
+  return 'd' in jwk && jwk.d != null
+}
+
+export function isPrivateJwk<J extends object>(jwk: J) {
+  return hasPrivateSecretJwk(jwk) || hasSharedSecretJwk(jwk)
+}
 
-export const jwkPrivateSchema = jwkSchema.refine(
-  (k) => ('k' in k && k.k != null) || ('d' in k && k.d != null),
-  'private key required',
-)
+export function isPublicJwk<J extends object>(
+  jwk: J,
+): jwk is Extract<
+  Exclude<J, { k: NonNullable<unknown> }>,
+  { d?: NonNullable<unknown> }
+> & { d?: never } {
+  return !hasPrivateSecretJwk(jwk) && !hasSharedSecretJwk(jwk)
+}

package/src/jwks.ts

@@ -6,17 +6,34 @@ import { jwkPubSchema, jwkSchema } from './jwk.js'
  * collection of JSON Web Keys (JWKs), that can be both public and private.
  */
 export const jwksSchema = z.object({
-  keys: z.array(jwkSchema),
+  keys: z.array(z.unknown()).transform((input) => {
+    // > Implementations SHOULD ignore JWKs within a JWK Set that use "kty"
+    // > (key type) values that are not understood by them, that are missing
+    // > required members, or for which values are out of the supported
+    // > ranges.
+    return input
+      .map((item) => jwkSchema.safeParse(item))
+      .filter((res) => res.success)
+      .map((res) => res.data)
+  }),
 })
 
-export type Jwks = z.infer<typeof jwksSchema>
+export type Jwks = z.output<typeof jwksSchema>
 
 /**
- * Public JSON Web Key Set schema. All keys must be public keys, have a `kid`,
- * and `use` or `key_ops` defined.
+ * Public JSON Web Key Set schema.
  */
 export const jwksPubSchema = z.object({
-  keys: z.array(jwkPubSchema),
+  keys: z.array(z.unknown()).transform((input) => {
+    // > Implementations SHOULD ignore JWKs within a JWK Set that use "kty"
+    // > (key type) values that are not understood by them, that are missing
+    // > required members, or for which values are out of the supported
+    // > ranges.
+    return input
+      .map((item) => jwkPubSchema.safeParse(item))
+      .filter((res) => res.success)
+      .map((res) => res.data)
+  }),
 })
 
-export type JwksPub = z.infer<typeof jwksPubSchema>
+export type JwksPub = z.output<typeof jwksPubSchema>

package/src/key.ts

@@ -1,60 +1,92 @@
 import { jwkAlgorithms } from './alg.js'
-import { JwkError } from './errors.js'
-import { Jwk, jwkSchema } from './jwk.js'
+import {
+  Jwk,
+  KeyUsage,
+  PUBLIC_KEY_USAGE,
+  PrivateJwk,
+  PublicJwk,
+  PublicKeyUsage,
+  hasSharedSecretJwk,
+  isEncKeyUsage,
+  isPrivateJwk,
+  isPublicKeyUsage,
+  isSigKeyUsage,
+  jwkPubSchema,
+  jwkSchema,
+} from './jwk.js'
 import { VerifyOptions, VerifyResult } from './jwt-verify.js'
 import { JwtHeader, JwtPayload, SignedJwt } from './jwt.js'
 import { cachedGetter } from './util.js'
 
-const jwkSchemaReadonly = jwkSchema.readonly()
+export type KeyMatchOptions = {
+  usage?: KeyUsage
+  kid?: string | string[]
+  alg?: string | string[]
+}
 
-export abstract class Key<J extends Jwk = Jwk> {
-  constructor(protected readonly jwk: Readonly<J>) {
-    // @TODO "use" is actually only for public keys. We should allow missing
-    // "use" here and automatically add it to the exposed `publicJwk`
+export type ActivityCheckOptions = {
+  allowRevoked?: boolean
+  clockTolerance?: number
+  currentDate?: Date
+}
 
-    // A key should always be used either for signing or encryption.
-    if (!jwk.use) throw new JwkError('Missing "use" Parameter value')
-  }
+export abstract class Key<J extends Jwk = Jwk> {
+  constructor(readonly jwk: Readonly<J>) {}
 
+  @cachedGetter
   get isPrivate(): boolean {
-    const { jwk } = this
-    if ('d' in jwk && jwk.d !== undefined) return true
-    if ('k' in jwk && jwk.k !== undefined) return true
-    return false
+    return isPrivateJwk(this.jwk)
   }
 
+  @cachedGetter
   get isSymetric(): boolean {
-    const { jwk } = this
-    if ('k' in jwk && jwk.k !== undefined) return true
-    return false
+    return hasSharedSecretJwk(this.jwk)
   }
 
-  get privateJwk(): Readonly<J> | undefined {
-    return this.isPrivate ? this.jwk : undefined
+  get privateJwk(): Readonly<PrivateJwk> | undefined {
+    if (!this.isPrivate) return undefined
+
+    return this.jwk as Readonly<PrivateJwk>
   }
 
   @cachedGetter
-  get publicJwk():
-    | Readonly<Exclude<J, { kty: 'oct' }> & { d?: never }>
-    | undefined {
+  get publicJwk(): Readonly<PublicJwk> | undefined {
     if (this.isSymetric) return undefined
+    if (!this.isPrivate) return this.jwk as Readonly<PublicJwk>
 
-    return jwkSchemaReadonly.parse({
+    const validated = jwkPubSchema.safeParse({
       ...this.jwk,
       d: undefined,
       k: undefined,
-    }) as Exclude<J, { kty: 'oct' }> & { d?: never }
+      use: undefined,
+      key_ops: buildPublicKeyOps(this.keyOps) ?? PUBLIC_KEY_USAGE,
+    })
+
+    // One reason why the parsing might fail is if key_ops is empty. This check
+    // also allows to future proof the code (e.g if another type of private key
+    // is added that uses a different property than "d" or "k" to store its
+    // private value).
+    if (!validated.success) return undefined
+
+    return Object.freeze(validated.data)
   }
 
   @cachedGetter
   get bareJwk(): Readonly<Jwk> | undefined {
     if (this.isSymetric) return undefined
     const { kty, crv, e, n, x, y } = this.jwk as any
-    return jwkSchemaReadonly.parse({ crv, e, kty, n, x, y })
+    return Object.freeze(jwkSchema.parse({ crv, e, kty, n, x, y }))
+  }
+
+  /**
+   * @note Only defined on public keys
+   */
+  get use(): 'sig' | 'enc' | undefined {
+    return this.jwk.use
   }
 
-  get use() {
-    return this.jwk.use!
+  get keyOps(): readonly KeyUsage[] | undefined {
+    return this.jwk.key_ops
   }
 
   /**
@@ -84,6 +116,67 @@ export abstract class Key<J extends Jwk = Jwk> {
     return Object.freeze(Array.from(jwkAlgorithms(this.jwk)))
   }
 
+  get isRevoked() {
+    return this.jwk.revoked != null
+  }
+
+  isActive(options?: ActivityCheckOptions) {
+    if (!options?.allowRevoked && this.isRevoked) return false
+
+    const tolerance = options?.clockTolerance ?? 0
+    if (tolerance !== Infinity) {
+      const now = options?.currentDate?.getTime() ?? Date.now()
+      const { exp, nbf } = this.jwk
+
+      if (nbf != null && !(now >= nbf * 1e3 - tolerance)) return false
+      if (exp != null && !(now < exp * 1e3 + tolerance)) return false
+    }
+
+    return true
+  }
+
+  matches(opts: KeyMatchOptions): boolean {
+    if (opts.kid != null) {
+      const matchesKid = Array.isArray(opts.kid)
+        ? this.kid != null && opts.kid.includes(this.kid)
+        : this.kid === opts.kid
+      if (!matchesKid) return false
+    }
+
+    if (opts.alg != null) {
+      const matchesAlg = Array.isArray(opts.alg)
+        ? opts.alg.some((a) => this.algorithms.includes(a))
+        : this.algorithms.includes(opts.alg)
+      if (!matchesAlg) return false
+    }
+
+    if (opts.usage != null) {
+      const matchesOps =
+        this.keyOps == null ||
+        this.keyOps.includes(opts.usage) ||
+        // @NOTE Because this.jwk represents the private key (typically used for
+        // private operations), the public counterpart operations are allowed.
+        (opts.usage === 'verify' && this.keyOps.includes('sign')) ||
+        (opts.usage === 'encrypt' && this.keyOps.includes('decrypt')) ||
+        (opts.usage === 'wrapKey' && this.keyOps.includes('unwrapKey'))
+      if (!matchesOps) return false
+
+      const matchesUse =
+        this.use == null ||
+        (this.use === 'sig' && isSigKeyUsage(opts.usage)) ||
+        (this.use === 'enc' && isEncKeyUsage(opts.usage))
+      if (!matchesUse) return false
+
+      // @NOTE This is only relevant when "key_ops" and "use" are undefined.
+      // This line also ensures that when "opts.usage" is a private key usage
+      // (e.g. "sign"), the key is indeed a private key.
+      const matchesKeyType = this.isPrivate || isPublicKeyUsage(opts.usage)
+      if (!matchesKeyType) return false
+    }
+
+    return true
+  }
+
   /**
    * Create a signed JWT
    */
@@ -99,3 +192,20 @@ export abstract class Key<J extends Jwk = Jwk> {
     options?: VerifyOptions<C>,
   ): Promise<VerifyResult<C>>
 }
+
+function buildPublicKeyOps(
+  keyUsages?: readonly KeyUsage[],
+): PublicKeyUsage[] | undefined {
+  if (keyUsages == null) return undefined
+
+  // https://datatracker.ietf.org/doc/html/rfc7517#section-4.3
+  // > Duplicate key operation values MUST NOT be present in the array.
+  const publicOps = new Set(keyUsages.filter(isPublicKeyUsage))
+
+  // @NOTE Translating private key usage into public key usage
+  if (keyUsages.includes('sign')) publicOps.add('verify')
+  if (keyUsages.includes('decrypt')) publicOps.add('encrypt')
+  if (keyUsages.includes('unwrapKey')) publicOps.add('wrapKey')
+
+  return Array.from(publicOps)
+}