hpke 1.1.6 → 1.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/index.d.ts.map +1 -1
  2. package/index.js +692 -673
  3. package/index.ts +106 -87
  4. package/package.json +2 -2
package/index.ts CHANGED
@@ -105,6 +105,36 @@ class Mutex {
105
105
  }
106
106
  }
107
107
 
108
+ interface ContextState {
109
+ readonly suite: Triple
110
+ readonly mode: Mode
111
+ readonly key: Uint8Array
112
+ readonly base_nonce: Uint8Array
113
+ readonly exporter_secret: Uint8Array
114
+ readonly max_seq: number
115
+ seq: number
116
+ mutex?: Mutex
117
+ }
118
+
119
+ function createContextState(
120
+ suite: Triple,
121
+ mode: Mode,
122
+ key: Uint8Array,
123
+ base_nonce: Uint8Array,
124
+ exporter_secret: Uint8Array,
125
+ ): ContextState {
126
+ return {
127
+ suite,
128
+ mode,
129
+ key,
130
+ base_nonce,
131
+ exporter_secret,
132
+ max_seq: MaxSeq(suite.AEAD.Nn),
133
+ seq: 0,
134
+ mutex: undefined,
135
+ }
136
+ }
137
+
108
138
  /**
109
139
  * Context for encrypting multiple messages and exporting secrets on the sender side.
110
140
  *
@@ -125,14 +155,7 @@ class Mutex {
125
155
  * @group Core
126
156
  */
127
157
  class SenderContext {
128
- #suite: Triple
129
- #key: Uint8Array
130
- #base_nonce: Uint8Array
131
- #exporter_secret: Uint8Array
132
- #mode: Mode
133
- #seq: number = 0
134
- #max_seq: number
135
- #mutex?: Mutex
158
+ #state: ContextState
136
159
 
137
160
  constructor(
138
161
  suite: Triple,
@@ -141,12 +164,7 @@ class SenderContext {
141
164
  base_nonce: Uint8Array,
142
165
  exporter_secret: Uint8Array,
143
166
  ) {
144
- this.#suite = suite
145
- this.#mode = mode
146
- this.#key = key
147
- this.#base_nonce = base_nonce
148
- this.#exporter_secret = exporter_secret
149
- this.#max_seq = MaxSeq(suite.AEAD.Nn)
167
+ this.#state = createContextState(suite, mode, key, base_nonce, exporter_secret)
150
168
  }
151
169
 
152
170
  /**
@@ -155,7 +173,7 @@ class SenderContext {
155
173
  * @see {@link MODE_PSK}
156
174
  */
157
175
  get mode(): Mode {
158
- return this.#mode
176
+ return this.#state.mode
159
177
  }
160
178
 
161
179
  /**
@@ -165,7 +183,7 @@ class SenderContext {
165
183
  * and `2^53-1`.
166
184
  */
167
185
  get seq(): number {
168
- return this.#seq
186
+ return this.#state.seq
169
187
  }
170
188
 
171
189
  /**
@@ -198,21 +216,22 @@ class SenderContext {
198
216
  checkUint8Array(plaintext, 'plaintext')
199
217
  aad ??= new Uint8Array()
200
218
  checkUint8Array(aad, 'aad')
201
- if (this.#suite.AEAD.id === EXPORT_ONLY) {
219
+ const state = this.#state
220
+ if (state.suite.AEAD.id === EXPORT_ONLY) {
202
221
  throw new TypeError('Export-only AEAD cannot be used with Seal')
203
222
  }
204
223
 
205
- this.#mutex ??= new Mutex()
206
- const release = await this.#mutex.lock()
224
+ state.mutex ??= new Mutex()
225
+ const release = await state.mutex.lock()
207
226
  let ct: Uint8Array
208
227
  try {
209
- ct = await this.#suite.AEAD.Seal(
210
- this.#key,
211
- ComputeNonce(this.#base_nonce, this.#seq, this.#suite.AEAD.Nn),
228
+ ct = await state.suite.AEAD.Seal(
229
+ state.key,
230
+ ComputeNonce(state.base_nonce, state.seq, state.suite.AEAD.Nn),
212
231
  aad,
213
232
  plaintext,
214
233
  )
215
- this.#seq = IncrementSeq(this.#seq, this.#max_seq)
234
+ state.seq = IncrementSeq(state.seq, state.max_seq)
216
235
  return ct
217
236
  } finally {
218
237
  release()
@@ -243,7 +262,12 @@ class SenderContext {
243
262
  * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3)
244
263
  */
245
264
  async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
246
- return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
265
+ return await ContextExport(
266
+ this.#state.suite,
267
+ this.#state.exporter_secret,
268
+ exporterContext,
269
+ length,
270
+ )
247
271
  }
248
272
 
249
273
  /**
@@ -251,7 +275,7 @@ class SenderContext {
251
275
  * context.
252
276
  */
253
277
  get Nt(): number {
254
- return this.#suite.AEAD.Nt
278
+ return this.#state.suite.AEAD.Nt
255
279
  }
256
280
  }
257
281
  export type { SenderContext }
@@ -276,14 +300,7 @@ export type { SenderContext }
276
300
  * @group Core
277
301
  */
278
302
  class RecipientContext {
279
- #suite: Triple
280
- #key: Uint8Array
281
- #base_nonce: Uint8Array
282
- #exporter_secret: Uint8Array
283
- #mode: Mode
284
- #seq: number = 0
285
- #max_seq: number
286
- #mutex?: Mutex
303
+ #state: ContextState
287
304
 
288
305
  constructor(
289
306
  suite: Triple,
@@ -292,12 +309,7 @@ class RecipientContext {
292
309
  base_nonce: Uint8Array,
293
310
  exporter_secret: Uint8Array,
294
311
  ) {
295
- this.#suite = suite
296
- this.#mode = mode
297
- this.#key = key
298
- this.#base_nonce = base_nonce
299
- this.#exporter_secret = exporter_secret
300
- this.#max_seq = MaxSeq(suite.AEAD.Nn)
312
+ this.#state = createContextState(suite, mode, key, base_nonce, exporter_secret)
301
313
  }
302
314
 
303
315
  /**
@@ -306,7 +318,7 @@ class RecipientContext {
306
318
  * @see {@link MODE_PSK}
307
319
  */
308
320
  get mode(): Mode {
309
- return this.#mode
321
+ return this.#state.mode
310
322
  }
311
323
 
312
324
  /**
@@ -316,7 +328,7 @@ class RecipientContext {
316
328
  * and `2^53-1`.
317
329
  */
318
330
  get seq(): number {
319
- return this.#seq
331
+ return this.#state.seq
320
332
  }
321
333
 
322
334
  /**
@@ -351,18 +363,19 @@ class RecipientContext {
351
363
  aad ??= new Uint8Array()
352
364
  checkUint8Array(aad, 'aad')
353
365
 
354
- if (this.#suite.AEAD.id === EXPORT_ONLY) {
366
+ const state = this.#state
367
+ if (state.suite.AEAD.id === EXPORT_ONLY) {
355
368
  throw new TypeError('Export-only AEAD cannot be used with Open')
356
369
  }
357
370
 
358
- this.#mutex ??= new Mutex()
359
- const release = await this.#mutex.lock()
371
+ state.mutex ??= new Mutex()
372
+ const release = await state.mutex.lock()
360
373
  try {
361
374
  let pt: Uint8Array
362
375
  try {
363
- pt = await this.#suite.AEAD.Open(
364
- this.#key,
365
- ComputeNonce(this.#base_nonce, this.#seq, this.#suite.AEAD.Nn),
376
+ pt = await state.suite.AEAD.Open(
377
+ state.key,
378
+ ComputeNonce(state.base_nonce, state.seq, state.suite.AEAD.Nn),
366
379
  aad,
367
380
  ciphertext,
368
381
  )
@@ -373,7 +386,7 @@ class RecipientContext {
373
386
 
374
387
  throw new OpenError('AEAD decryption failed', { cause })
375
388
  }
376
- this.#seq = IncrementSeq(this.#seq, this.#max_seq)
389
+ state.seq = IncrementSeq(state.seq, state.max_seq)
377
390
  return pt
378
391
  } finally {
379
392
  release()
@@ -404,7 +417,12 @@ class RecipientContext {
404
417
  * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3)
405
418
  */
406
419
  async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
407
- return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
420
+ return await ContextExport(
421
+ this.#state.suite,
422
+ this.#state.exporter_secret,
423
+ exporterContext,
424
+ length,
425
+ )
408
426
  }
409
427
  }
410
428
  export type { RecipientContext }
@@ -2370,14 +2388,34 @@ interface HKDF extends KDF {
2370
2388
 
2371
2389
  type KDF_BASE = Pick<KDF, 'Expand' | 'Extract' | 'Derive' | 'stages'>
2372
2390
 
2373
- async function cacheValue<K extends object, V>(
2374
- cache: WeakMap<K, V>,
2375
- key: K,
2376
- init: () => Promise<V>,
2377
- ): Promise<V> {
2378
- const result = await init()
2379
- cache.set(key, result)
2380
- return result
2391
+ interface CryptoKeyCacheEntry {
2392
+ bytes: Uint8Array
2393
+ key: Promise<CryptoKey>
2394
+ }
2395
+
2396
+ async function getCachedCryptoKey(
2397
+ cache: WeakMap<Uint8Array, CryptoKeyCacheEntry>,
2398
+ keyBytes: Uint8Array,
2399
+ init: (bytes: Uint8Array) => Promise<CryptoKey>,
2400
+ ): Promise<CryptoKey> {
2401
+ const cached = cache.get(keyBytes)
2402
+ if (
2403
+ cached &&
2404
+ cached.bytes.byteLength === keyBytes.byteLength &&
2405
+ cached.bytes.every((byte, index) => byte === keyBytes[index])
2406
+ ) {
2407
+ return cached.key
2408
+ }
2409
+
2410
+ const bytes = slice(keyBytes)
2411
+ const entry = { bytes, key: init(bytes) }
2412
+ cache.set(keyBytes, entry)
2413
+ try {
2414
+ return await entry.key
2415
+ } catch (cause) {
2416
+ if (cache.get(keyBytes) === entry) cache.delete(keyBytes)
2417
+ throw cause
2418
+ }
2381
2419
  }
2382
2420
 
2383
2421
  function HKDF_SHARED(): KDF_BASE {
@@ -2388,12 +2426,7 @@ function HKDF_SHARED(): KDF_BASE {
2388
2426
  this.name,
2389
2427
  )
2390
2428
  }
2391
- const cache = new WeakMap<Uint8Array, Promise<CryptoKey>>()
2392
- function importPrk(this: HKDF, prk: Uint8Array): Promise<CryptoKey> {
2393
- const key = importKey.call(this, prk as BufferSource)
2394
- cache.set(prk, key)
2395
- return key
2396
- }
2429
+ const cache = new WeakMap<Uint8Array, CryptoKeyCacheEntry>()
2397
2430
  return {
2398
2431
  stages: 2,
2399
2432
  Derive: NotApplicable,
@@ -2414,7 +2447,9 @@ function HKDF_SHARED(): KDF_BASE {
2414
2447
  throw new Error('L must be <= 255*Nh')
2415
2448
  }
2416
2449
  const N = Math.ceil(L / this.Nh)
2417
- const key = await (cache.get(prk) ?? importPrk.call(this, prk))
2450
+ const key = await getCachedCryptoKey(cache, prk, (bytes) =>
2451
+ importKey.call(this, bytes as BufferSource),
2452
+ )
2418
2453
 
2419
2454
  const T = new Uint8Array(N * this.Nh)
2420
2455
  let T_prev = new Uint8Array()
@@ -2685,17 +2720,6 @@ async function getPublicKey(name: string, key: CryptoKey, usages: KeyUsage[]): P
2685
2720
  )
2686
2721
  }
2687
2722
 
2688
- /** This is a last resort check, Web Cryptography implementers should already be checking it */
2689
- function checkNotAllZeros(buffer: Uint8Array): void {
2690
- let or = 0
2691
- for (let i = 0; i < buffer.length; i++) {
2692
- or |= buffer[i]!
2693
- }
2694
- if (or === 0) {
2695
- throw new ValidationError('DH shared secret is an all-zero value')
2696
- }
2697
- }
2698
-
2699
2723
  type KEM_BASE<K extends Key = Key> = Pick<
2700
2724
  KEM<K>,
2701
2725
  | 'GenerateKeyPair'
@@ -2894,7 +2918,6 @@ function DHKEM_SHARED(): Required<
2894
2918
  this.name,
2895
2919
  ),
2896
2920
  )
2897
- checkNotAllZeros(dh)
2898
2921
 
2899
2922
  const enc = await this.SerializePublicKey(pkE)
2900
2923
  const pkRm = await this.SerializePublicKey(pkR)
@@ -2922,7 +2945,6 @@ function DHKEM_SHARED(): Required<
2922
2945
  this.name,
2923
2946
  ),
2924
2947
  )
2925
- checkNotAllZeros(dh)
2926
2948
 
2927
2949
  const pkRm = await this.SerializePublicKey(pkR)
2928
2950
  const kem_context = concat(enc, pkRm)
@@ -3631,11 +3653,11 @@ type AEAD_BASE = Pick<AEAD, 'Seal' | 'Open'>
3631
3653
 
3632
3654
  function AEAD_SHARED(P_MAX: number): AEAD_BASE {
3633
3655
  // Cache the WebCrypto CryptoKey derived from a given key-bytes Uint8Array.
3634
- // Across the lifetime of a SenderContext/RecipientContext, `this.#key` is a
3656
+ // Across the lifetime of a SenderContext/RecipientContext, the key is a
3635
3657
  // stable Uint8Array, so crypto.subtle.importKey() would otherwise be called
3636
3658
  // on every Seal/Open. The WeakMap ensures the cache entry is reclaimed once
3637
3659
  // the underlying Uint8Array is unreachable.
3638
- const cache = new WeakMap<Uint8Array, CryptoKey>()
3660
+ const cache = new WeakMap<Uint8Array, CryptoKeyCacheEntry>()
3639
3661
  async function importKey(this: WebCryptoAEAD, key: Uint8Array): Promise<CryptoKey> {
3640
3662
  return await subtle(
3641
3663
  (c) =>
@@ -3651,8 +3673,7 @@ function AEAD_SHARED(P_MAX: number): AEAD_BASE {
3651
3673
  if (pt.byteLength > P_MAX) {
3652
3674
  throw new RangeError('"pt" exceeds P_MAX')
3653
3675
  }
3654
- const cryptoKey =
3655
- cache.get(key) ?? (await cacheValue(cache, key, () => importKey.call(this, key)))
3676
+ const cryptoKey = await getCachedCryptoKey(cache, key, (bytes) => importKey.call(this, bytes))
3656
3677
  return new Uint8Array(
3657
3678
  await subtle(
3658
3679
  (c) =>
@@ -3670,8 +3691,7 @@ function AEAD_SHARED(P_MAX: number): AEAD_BASE {
3670
3691
  )
3671
3692
  },
3672
3693
  async Open(this: WebCryptoAEAD, key, nonce, aad, ct) {
3673
- const cryptoKey =
3674
- cache.get(key) ?? (await cacheValue(cache, key, () => importKey.call(this, key)))
3694
+ const cryptoKey = await getCachedCryptoKey(cache, key, (bytes) => importKey.call(this, bytes))
3675
3695
  return new Uint8Array(
3676
3696
  await subtle(
3677
3697
  (c) =>
@@ -3976,7 +3996,6 @@ async function prepareEncapsG(
3976
3996
  kem.name,
3977
3997
  ),
3978
3998
  )
3979
- checkNotAllZeros(ss_T)
3980
3999
 
3981
4000
  return [ss_PQ, ss_T, ct_PQ, ct_T]
3982
4001
  }
@@ -4008,7 +4027,6 @@ async function prepareDecapsG(
4008
4027
  kem.name,
4009
4028
  ),
4010
4029
  )
4011
- checkNotAllZeros(ss_T)
4012
4030
 
4013
4031
  return [ss_PQ, ss_T]
4014
4032
  }
@@ -4110,7 +4128,8 @@ function COMPOSITE_HYBRID_KEM_SHARED(): KEM_BASE<HybridKey> {
4110
4128
  return key.getSeed(priv)
4111
4129
  },
4112
4130
  async DeserializePrivateKey(this: CompositeHybridKEM, key, extractable) {
4113
- const { ek_PQ, ek_T, dk_PQ, dk_T } = await expandDecapsKeyG(this, key)
4131
+ const seed = slice(key)
4132
+ const { ek_PQ, ek_T, dk_PQ, dk_T } = await expandDecapsKeyG(this, seed)
4114
4133
  const publicKey = new HybridKey(priv, this.algorithm, 'public', true, ek_PQ, ek_T)
4115
4134
  const privateKey = new HybridKey(
4116
4135
  priv,
@@ -4119,7 +4138,7 @@ function COMPOSITE_HYBRID_KEM_SHARED(): KEM_BASE<HybridKey> {
4119
4138
  extractable,
4120
4139
  dk_PQ,
4121
4140
  dk_T,
4122
- slice(key),
4141
+ seed,
4123
4142
  publicKey,
4124
4143
  )
4125
4144
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hpke",
3
- "version": "1.1.6",
3
+ "version": "1.1.7",
4
4
  "description": "Hybrid Public Key Encryption (HPKE) for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes",
5
5
  "keywords": [
6
6
  "browser",
@@ -45,7 +45,7 @@
45
45
  "check:packaging": "publint run . --strict && node tools/attw-check.js . && publint run examples/noble-suite --strict && node tools/attw-check.js examples/noble-suite",
46
46
  "docs": "npx typedoc",
47
47
  "format": "prettier --log-level silent --cache --write '**/*.{ts,js,mjs,cjs,json,yml}' '**/README.md'",
48
- "test": "node --test --no-warnings test/*.ts test/noble-version.js",
48
+ "test": "node --test --no-warnings test/*.ts test/build.js test/noble-version.js",
49
49
  "test:browsers": "node test/browser.mjs",
50
50
  "test:bun": "bun test ./test/*.ts",
51
51
  "test:deno": "deno test --no-check --allow-read test/*.ts",