@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/README.md +68 -8
- package/dist/aes-gcm.cjs +1 -1
- package/dist/aes-gcm.cjs.map +1 -1
- package/dist/aes-gcm.d.cts +18 -29
- package/dist/aes-gcm.d.ts +18 -29
- package/dist/aes-gcm.js +1 -1
- package/dist/aes-gcm.js.map +1 -1
- package/dist/api-key.cjs +1 -1
- package/dist/api-key.cjs.map +1 -1
- package/dist/api-key.d.cts +2 -2
- package/dist/api-key.d.ts +2 -2
- package/dist/api-key.js +1 -1
- package/dist/api-key.js.map +1 -1
- package/dist/encoding.cjs.map +1 -1
- package/dist/encoding.d.cts +1 -1
- package/dist/encoding.d.ts +1 -1
- package/dist/encoding.js.map +1 -1
- package/dist/hash.cjs.map +1 -1
- package/dist/hash.js.map +1 -1
- package/dist/hmac.cjs.map +1 -1
- package/dist/hmac.js.map +1 -1
- package/dist/index.cjs +2 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/random.cjs.map +1 -1
- package/dist/random.js.map +1 -1
- package/dist/webhook.cjs.map +1 -1
- package/dist/webhook.js.map +1 -1
- package/package.json +5 -5
- package/src/aes-gcm.ts +19 -30
- package/src/api-key.ts +3 -3
- package/src/encoding.ts +1 -1
- package/src/random.ts +1 -1
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
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
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
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|