@strimz/shared-crypto 0.1.0 → 0.1.2

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.
package/src/aes-gcm.ts CHANGED
@@ -1,40 +1,29 @@
1
1
  /**
2
2
  * AES-256-GCM authenticated symmetric encryption via Web Crypto.
3
3
  *
4
- * Used by the webhook layer to encrypt signing secrets at rest in
5
- * Postgres. Sized at the smallest interface that does the job —
6
- * encrypt one short string at a time, decrypt one short string at a
7
- * time, with the encryption key supplied as a 32-byte hex string from
8
- * environment configuration.
4
+ * Encrypt one short string at a time, decrypt one short string at a
5
+ * time. The encryption key is supplied as a 32-byte hex string by the
6
+ * caller. Suitable for envelope-encrypting small secrets where the
7
+ * key is held outside the data store.
9
8
  *
10
- * Why Web Crypto over `node:crypto`: the rest of `@strimz/shared-crypto`
11
- * targets Node 22, Vercel Edge, and Cloudflare Workers uniformly.
12
- * Keeping this consistent so the package can be imported anywhere
13
- * without conditional branches.
9
+ * AES-GCM is authenticated, so the auth tag detects bit-flips and
10
+ * substitution attacks. A tampered ciphertext fails closed at decrypt
11
+ * time. The 12-byte nonce and 16-byte tag are the canonical layout
12
+ * exposed by Web Crypto.
14
13
  *
15
- * Why AES-256-GCM:
16
- * - Authenticated. The auth tag detects bit-flips or substitution
17
- * attacks; a tampered ciphertext fails closed at decrypt time.
18
- * - Standard. Available natively in Web Crypto with no third-party
19
- * dependency.
20
- * - 12-byte nonce + 16-byte tag is the canonical layout.
21
- *
22
- * Output format (string-safe so it goes into Postgres TEXT columns
23
- * without re-encoding):
14
+ * Output format is string-safe and suitable for any text column:
24
15
  *
25
16
  * v1:<nonce-hex>:<ciphertext-and-tag-hex>
26
17
  *
27
- * Web Crypto returns the auth tag concatenated to the ciphertext,
28
- * so the on-the-wire format keeps them together rather than splitting
18
+ * Web Crypto returns the auth tag concatenated to the ciphertext, so
19
+ * the on-the-wire format keeps them together rather than splitting
29
20
  * them out. The leading `v1:` lets future schemes coexist during
30
21
  * migration.
31
22
  *
32
- * What this is NOT:
33
- * - A KMS replacement. The key lives in env. Rotating it means
34
- * rotating every encrypted value (or supporting two keys for a
35
- * cutover window). Graduate to a hardware-backed envelope when
36
- * funded — the `KmsSigner` abstraction in the API is the parallel
37
- * pattern for sign keys.
23
+ * This is not a KMS replacement. The key lives in caller-controlled
24
+ * storage. Rotating it means rotating every encrypted value, or
25
+ * supporting two keys for a cutover window. For sign keys, use a
26
+ * hardware-backed signer pattern instead.
38
27
  */
39
28
 
40
29
  import { fromHex, toHex } from './encoding.js'
@@ -48,7 +37,7 @@ const VERSION_PREFIX = 'v1:'
48
37
  /**
49
38
  * Encrypt a plaintext string with the supplied 32-byte hex key.
50
39
  * Returns a versioned, colon-delimited ciphertext blob safe to store
51
- * in a Postgres TEXT column.
40
+ * in any text column.
52
41
  */
53
42
  export async function encryptAesGcm(plaintext: string, keyHex: string): Promise<string> {
54
43
  const key = await importKey(keyHex)
@@ -65,7 +54,7 @@ export async function encryptAesGcm(plaintext: string, keyHex: string): Promise<
65
54
 
66
55
  /**
67
56
  * Inverse of `encryptAesGcm`. Throws on any tampering or key mismatch
68
- * — there is no partial-decrypt path. The caller decides how to
57
+ * with no partial-decrypt path. The caller decides how to
69
58
  * surface the failure (log + fail closed for storage; reject the
70
59
  * request for hot-path use).
71
60
  */
@@ -95,7 +84,7 @@ export async function decryptAesGcm(blob: string, keyHex: string): Promise<strin
95
84
  }
96
85
 
97
86
  /**
98
- * Convenience helper for generating a fresh 32-byte hex key — used
87
+ * Convenience helper for generating a fresh 32-byte hex key. Used
99
88
  * by ops scripts that seed the env var. Returned as a hex string so
100
89
  * it can be pasted into a secrets vault without binary handling.
101
90
  */
@@ -104,7 +93,7 @@ export function generateAesGcmKey(): string {
104
93
  return toHex(bytes)
105
94
  }
106
95
 
107
- async function importKey(keyHex: string): Promise<CryptoKey> {
96
+ function importKey(keyHex: string): Promise<CryptoKey> {
108
97
  if (!/^[0-9a-fA-F]+$/u.test(keyHex)) {
109
98
  throw new Error('encryption key must be a hex-encoded string')
110
99
  }
package/src/api-key.ts CHANGED
@@ -22,13 +22,13 @@ import { sha256Hex } from './hash.js'
22
22
  import { randomBase64Url } from './random.js'
23
23
 
24
24
  export interface GeneratedApiKey {
25
- /** The full plaintext key — display once then discard. */
25
+ /** The full plaintext key. Display once then discard. */
26
26
  secret: string
27
27
  /** Stored as the index. */
28
28
  hash: string
29
29
  /** Stored for display / log redaction. */
30
30
  prefix: string
31
- /** Stored for display — "my key ending in ...abcd". */
31
+ /** Stored for display, e.g. "my key ending in ...abcd". */
32
32
  lastFour: string
33
33
  kind: ApiKeyKind
34
34
  mode: ApiKeyMode
@@ -49,7 +49,7 @@ export async function generateApiKey(kind: ApiKeyKind, mode: ApiKeyMode): Promis
49
49
  }
50
50
  }
51
51
 
52
- export async function hashApiKey(secret: string): Promise<string> {
52
+ export function hashApiKey(secret: string): Promise<string> {
53
53
  return sha256Hex(secret)
54
54
  }
55
55
 
package/src/encoding.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Byte encoders that work in every JavaScript runtime we target.
3
- * No Node `Buffer`, no dependency on the DOM — just Uint8Array, strings, and
3
+ * No Node `Buffer`, no dependency on the DOM. Only Uint8Array, strings, and
4
4
  * the two TextEncoder/TextDecoder classes available everywhere.
5
5
  */
6
6
 
package/src/random.ts CHANGED
@@ -27,7 +27,7 @@ export function uuid(): string {
27
27
  if (c && typeof c.randomUUID === 'function') {
28
28
  return c.randomUUID()
29
29
  }
30
- // Fallback — RFC 4122 v4 from getRandomValues
30
+ // Fallback. RFC 4122 v4 from getRandomValues.
31
31
  const bytes = randomBytes(16)
32
32
  bytes[6] = ((bytes[6] as number) & 0x0f) | 0x40
33
33
  bytes[8] = ((bytes[8] as number) & 0x3f) | 0x80