feat: add JWK key_ops support, fix .algorithms() op returns

BREAKING CHANGE: key.algorithms(op) un+wrapKey was split into correct
wrapKey/unwrapKey/deriveKey returns

BREAKING CHANGE: keystore.all and keystore.get `operation` option was
removed, `key_ops: string[]` supersedes it

Author: panva

README.md

@@ -81,7 +81,6 @@ Won't implement:
   - no crypto, no use
 
 Not Planned / PR | Use-Case | Discussion Welcome:
-- ◯ automatically adding `kid` reference to JWS / JWE Headers
 - ◯ `x5c`, `x5t`, `x5t#S256`, `x5u` etc `JWK.Key` fields
 
 </details>

docs/README.md

@@ -29,6 +29,7 @@ I can continue maintaining it and adding new features carefree. You may also don
   - [key.alg](#keyalg)
   - [key.use](#keyuse)
   - [key.kid](#keykid)
+  - [key.key_ops](#keykey_ops)
   - [key.thumbprint](#keythumbprint)
   - [key.type](#keytype)
   - [key.public](#keypublic)
@@ -116,6 +117,16 @@ defined in [RFC7638][spec-thumbprint].
 
 ---
 
+#### `key.key_ops`
+
+Returns the key's JWK Key Operations Parameter if set. If set the key can only be used for the
+specified operations. Supported values are 'sign', 'verify', 'encrypt', 'decrypt', 'wrapKey',
+'unwrapKey' and 'deriveKey'.
+
+- `string[]`
+
+---
+
 #### `key.thumbprint`
 
 Returns the key's JWK Key thumbprint calculated using the method defined in [RFC7638][spec-thumbprint].
@@ -415,11 +426,15 @@ Securely generates a new RSA, EC, OKP or oct key.
 - `crvOrSize`: `<number>` &vert; `<string>` key's bit size or in case of OKP and EC keys the curve
   **Default:** 2048 for RSA, 'P-256' for EC, 'Ed25519' for OKP and 256 for oct.
 - `options`: `<Object>`
-  - `alg`: `<string>` option identifies the algorithm intended for use with the key.
+  - `alg`: `<string>` Key Algorithm Parameter. It identifies the algorithm intended for use with the
+    key.
   - `kid`: `<string>` Key ID Parameter. When not provided is computed using the method defined in
-    [RFC7638][spec-thumbprint]
-  - `use`: `<string>` option indicates whether the key is to be used for encrypting & decrypting
-    data or signing & verifying data. Must be 'sig' or 'enc'.
+    [RFC7638][spec-thumbprint].
+  - `use`: `<string>` Public Key Use Parameter. Indicates whether the key is to be used for
+    encrypting & decrypting data or signing & verifying data. Must be 'sig' or 'enc'.
+  - `key_ops`: `string[]` Key Operations Parameter. If set, the key can only be used for the
+    specified operations. Supported values are 'sign', 'verify', 'encrypt', 'decrypt', 'wrapKey',
+    'unwrapKey' and 'deriveKey'.
 - `private`: `<boolean>` **Default** 'true'. Is the resulting key private or public (when
   asymmetrical)
 - Returns: `Promise<JWK.RSAKey>` &vert; `Promise<JWK.ECKey>` &vert; `Promise<JWK.OKPKey>` &vert; `Promise<JWK.OctKey>`
@@ -454,11 +469,15 @@ Synchronous version of `JWK.generate()`
 - `crvOrSize`: `<number>` &vert; `<string>` key's bit size or in case of OKP and EC keys the curve.
   **Default:** 2048 for RSA, 'P-256' for EC, 'Ed25519' for OKP and 256 for oct.
 - `options`: `<Object>`
-  - `alg`: `<string>` option identifies the algorithm intended for use with the key.
-  - `use`: `<string>` option indicates whether the key is to be used for encrypting & decrypting
-    data or signing & verifying data. Must be 'sig' or 'enc'.
+  - `alg`: `<string>` Key Algorithm Parameter. It identifies the algorithm intended for use with the
+    key.
   - `kid`: `<string>` Key ID Parameter. When not provided is computed using the method defined in
-    [RFC7638][spec-thumbprint]
+    [RFC7638][spec-thumbprint].
+  - `use`: `<string>` Public Key Use Parameter. Indicates whether the key is to be used for
+    encrypting & decrypting data or signing & verifying data. Must be 'sig' or 'enc'.
+  - `key_ops`: `string[]` Key Operations Parameter. If set, the key can only be used for the
+    specified operations. Supported values are 'sign', 'verify', 'encrypt', 'decrypt', 'wrapKey',
+    'unwrapKey' and 'deriveKey'.
 - `private`: `<boolean>` **Default** 'true'. Is the resulting key private or public (when
   asymmetrical)
 - Returns: `<JWK.RSAKey>` &vert; `<JWK.ECKey>` &vert; `<JWK.OKPKey>` &vert; `<JWK.OctKey>`
@@ -551,10 +570,12 @@ specified by the parameters are first.
 - `parameters`: `<Object>`
   - `kty`: `<string>` Key Type to filter for.
   - `alg`: `<string>` Key supported algorithm to filter for.
-  - `use`: `<string>` Key use to filter for.
   - `kid`: `<string>` Key ID to filter for.
-  - `operation`: `<string>` Further specify the operation a given alg must be valid for. Must be one
-    of 'encrypt', 'decrypt', 'sign', 'verify', 'wrapKey', 'unwrapKey'
+  - `use`: `<string>` Filter keys with the specified use defined. Keys missing "use" parameter will
+    be matched but rank lower then ones with an exact match.
+  - `key_ops`: `string[]` Filter keys with specified key_ops defined (if key_ops is defined on the
+    key). Keys missing "key_ops" parameter will be matched but rank lower then ones with matching
+    entries.
 - Returns: `<Key[]>` Array of key instances or an empty array when none are matching the parameters.
 
 ---
@@ -567,10 +588,12 @@ parameters is returned.
 - `parameters`: `<Object>`
   - `kty`: `<string>` Key Type to filter for.
   - `alg`: `<string>` Key supported algorithm to filter for.
-  - `use`: `<string>` Key use to filter for.
   - `kid`: `<string>` Key ID to filter for.
-  - `operation`: `<string>` Further specify the operation a given alg must be valid for. Must be one
-    of 'encrypt', 'decrypt', 'sign', 'verify', 'wrapKey', 'unwrapKey'
+  - `use`: `<string>` Filter keys with the specified use defined. Keys missing "use" parameter will
+    be matched but rank lower then ones with an exact match.
+  - `key_ops`: `string[]` Filter keys with specified key_ops defined (if key_ops is defined on the
+    key). Keys missing "key_ops" parameter will be matched but rank lower then ones with matching
+    entries.
 - Returns: `<JWK.RSAKey>` &vert; `<JWK.ECKey>` &vert; `<JWK.OKPKey>` &vert; `<JWK.OctKey>` &vert; `<undefined>`
 
 ---
@@ -1206,6 +1229,7 @@ Verifies the provided JWE in either serialization with a given `<JWK.Key>` or `<
 - [Class: &lt;JWEDecryptionFailed&gt;](#class-jwedecryptionfailed)
 - [Class: &lt;JWEInvalid&gt;](#class-jweinvalid)
 - [Class: &lt;JWKImportFailed&gt;](#class-jwkimportfailed)
+- [Class: &lt;JWKKeyInvalid&gt;](#class-jwkkeyinvalid)
 - [Class: &lt;JWKKeySupport&gt;](#class-jwkkeysupport)
 - [Class: &lt;JWKSNoMatchingKey&gt;](#class-jwksnomatchingkey)
 - [Class: &lt;JWSInvalid&gt;](#class-jwsinvalid)
@@ -1311,6 +1335,16 @@ if (err.code === 'ERR_JWK_IMPORT_FAILED') {
 }
 ```
 
+#### Class: `JWKKeyInvalid`
+
+Thrown when key's parameters are invalid, e.g. key_ops and use values are inconsistent.
+
+```js
+if (err.code === 'ERR_JWK_INVALID') {
+  // ...
+}
+```
+
 #### Class: `JWKKeySupport`
 
 Thrown when a key does not support the request algorithm.

lib/errors.js

@@ -6,6 +6,7 @@ const CODES = {
   JWEDecryptionFailed: 'ERR_JWE_DECRYPTION_FAILED',
   JWEInvalid: 'ERR_JWE_INVALID',
   JWKImportFailed: 'ERR_JWK_IMPORT_FAILED',
+  JWKInvalid: 'ERR_JWK_INVALID',
   JWKKeySupport: 'ERR_JWK_KEY_SUPPORT',
   JWKSNoMatchingKey: 'ERR_JWKS_NO_MATCHING_KEY',
   JWSInvalid: 'ERR_JWS_INVALID',
@@ -63,6 +64,7 @@ module.exports.JWEDecryptionFailed = class JWEDecryptionFailed extends JOSEError
 module.exports.JWEInvalid = class JWEInvalid extends JOSEError {}
 
 module.exports.JWKImportFailed = class JWKImportFailed extends JOSEError {}
+module.exports.JWKInvalid = class JWKInvalid extends JOSEError {}
 module.exports.JWKKeySupport = class JWKKeySupport extends JOSEError {}
 
 module.exports.JWKSNoMatchingKey = class JWKSNoMatchingKey extends JOSEError {}

lib/help/consts.js

@@ -0,0 +1,31 @@
+module.exports.KEYOBJECT = Symbol('KEYOBJECT')
+module.exports.PRIVATE_MEMBERS = Symbol('PRIVATE_MEMBERS')
+module.exports.PUBLIC_MEMBERS = Symbol('PUBLIC_MEMBERS')
+module.exports.THUMBPRINT_MATERIAL = Symbol('THUMBPRINT_MATERIAL')
+module.exports.JWK_MEMBERS = Symbol('JWK_MEMBERS')
+module.exports.KEY_MANAGEMENT_ENCRYPT = Symbol('KEY_MANAGEMENT_ENCRYPT')
+module.exports.KEY_MANAGEMENT_DECRYPT = Symbol('KEY_MANAGEMENT_DECRYPT')
+
+const USES_MAPPING = {
+  sig: new Set(['sign', 'verify']),
+  enc: new Set(['encrypt', 'decrypt', 'wrapKey', 'unwrapKey', 'deriveKey'])
+}
+const OPS = new Set([...USES_MAPPING.sig, ...USES_MAPPING.enc])
+const USES = new Set(Object.keys(USES_MAPPING))
+
+module.exports.USES_MAPPING = USES_MAPPING
+module.exports.OPS = OPS
+module.exports.USES = USES
+
+module.exports.OKP_CURVES = new Set(['Ed25519', 'Ed448', 'X25519', 'X448'])
+module.exports.EC_CURVES = new Set(['P-256', 'P-384', 'P-521'])
+module.exports.ECDH_ALGS = ['ECDH-ES', 'ECDH-ES+A128KW', 'ECDH-ES+A192KW', 'ECDH-ES+A256KW']
+
+module.exports.KEYLENGTHS = {
+  'A128CBC-HS256': 256,
+  'A192CBC-HS384': 384,
+  'A256CBC-HS512': 512,
+  'A128GCM': 128,
+  'A192GCM': 192,
+  'A256GCM': 256
+}

lib/help/key_lengths.js

@@ -3,9 +3,7 @@ const { createPublicKey } = require('crypto')
 const base64url = require('./base64url')
 const errors = require('../errors')
 const asn1 = require('./asn1')
-
-const EC_CURVES = new Set(['P-256', 'P-384', 'P-521'])
-const OKP_CURVES = new Set(['Ed25519', 'Ed448', 'X25519', 'X448'])
+const { OKP_CURVES, EC_CURVES } = require('./consts')
 
 const oidHexToCurve = new Map([
   ['06082a8648ce3d030107', 'P-256'],

lib/help/key_utils.js

@@ -3,15 +3,16 @@
 import { KeyObject, PrivateKeyInput, PublicKeyInput } from 'crypto'
 
 type use = 'sig' | 'enc'
+type keyOperation = 'sign' | 'verify' | 'encrypt' | 'decrypt' | 'wrapKey' | 'unwrapKey' | 'deriveKey'
 interface KeyParameters {
     alg?: string
     use?: use
     kid?: string
+    key_ops?: keyOperation[]
 }
 type ECCurve = 'P-256' | 'P-384' | 'P-521'
 type OKPCurve = 'Ed25519' | 'Ed448' | 'X25519' | 'X448'
 type keyType = 'RSA' | 'EC' | 'OKP' | 'oct'
-type keyOperation = 'encrypt' | 'decrypt' | 'sign' | 'verify' | 'wrapKey' | 'unwrapKey'
 type asymmetricKeyObjectTypes = 'private' | 'public'
 type keyObjectTypes = asymmetricKeyObjectTypes | 'secret'
 
@@ -31,6 +32,7 @@ export namespace JWK {
         secret: boolean
         alg?: string
         use?: use
+        key_ops?: keyOperation[]
         kid: string
         thumbprint: string
 
@@ -144,7 +146,6 @@ export namespace JWK {
 export namespace JWKS {
     interface KeyQuery extends KeyParameters {
         kty: keyType
-        operation: keyOperation
     }
 
     class KeyStore {
@@ -341,6 +342,7 @@ export namespace errors {
     export class JWEInvalid extends JOSEError {}
 
     export class JWKImportFailed extends JOSEError {}
+    export class JWKInvalid extends JOSEError {}
     export class JWKKeySupport extends JOSEError {}
 
     export class JWKSNoMatchingKey extends JOSEError {}

lib/help/symbols.js

@@ -3,7 +3,7 @@ const { createCipheriv, createDecipheriv } = require('crypto')
 
 const uint64be = require('../help/uint64be')
 const timingSafeEqual = require('../help/timing_safe_equal')
-const { KEYOBJECT } = require('../help/symbols')
+const { KEYOBJECT } = require('../help/consts')
 const { JWEInvalid, JWEDecryptionFailed } = require('../errors')
 
 const checkInput = function (size, iv, tag) {

lib/index.d.ts

@@ -1,7 +1,7 @@
 const { strict: assert } = require('assert')
 const { createCipheriv, createDecipheriv } = require('crypto')
 
-const { KEYOBJECT } = require('../help/symbols')
+const { KEYOBJECT } = require('../help/consts')
 const { JWEInvalid, JWEDecryptionFailed } = require('../errors')
 
 const checkInput = function (size, iv, tag) {