@gadicc/loom 1.35.2 → 1.36.0
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 +56 -0
- package/THIRD_PARTY_NOTICES.md +12 -9
- package/esm/src/cli/externalSkills.d.ts.map +1 -1
- package/esm/src/cli/externalSkills.js +25 -20
- package/esm/src/cli/mod.d.ts +72 -1
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +771 -36
- package/esm/src/cli/projectSkills.d.ts +10 -3
- package/esm/src/cli/projectSkills.d.ts.map +1 -1
- package/esm/src/cli/projectSkills.js +173 -49
- package/esm/src/cli/vercelBuildEnv.d.ts +28 -0
- package/esm/src/cli/vercelBuildEnv.d.ts.map +1 -1
- package/esm/src/cli/vercelBuildEnv.js +120 -30
- package/esm/src/mail/postal.d.ts.map +1 -1
- package/esm/src/mail/postal.js +2 -1
- package/esm/src/next/secrets/mod.d.ts +108 -0
- package/esm/src/next/secrets/mod.d.ts.map +1 -0
- package/esm/src/next/secrets/mod.js +176 -0
- package/esm/src/secrets/encoding.d.ts +32 -0
- package/esm/src/secrets/encoding.d.ts.map +1 -0
- package/esm/src/secrets/encoding.js +87 -0
- package/esm/src/secrets/errors.d.ts +45 -0
- package/esm/src/secrets/errors.d.ts.map +1 -0
- package/esm/src/secrets/errors.js +39 -0
- package/esm/src/secrets/fingerprint.d.ts +43 -0
- package/esm/src/secrets/fingerprint.d.ts.map +1 -0
- package/esm/src/secrets/fingerprint.js +87 -0
- package/esm/src/secrets/frame.d.ts +34 -0
- package/esm/src/secrets/frame.d.ts.map +1 -0
- package/esm/src/secrets/frame.js +86 -0
- package/esm/src/secrets/keyring.d.ts +62 -0
- package/esm/src/secrets/keyring.d.ts.map +1 -0
- package/esm/src/secrets/keyring.js +160 -0
- package/esm/src/secrets/legacy.d.ts +60 -0
- package/esm/src/secrets/legacy.d.ts.map +1 -0
- package/esm/src/secrets/legacy.js +147 -0
- package/esm/src/secrets/maintenance.d.ts +173 -0
- package/esm/src/secrets/maintenance.d.ts.map +1 -0
- package/esm/src/secrets/maintenance.js +315 -0
- package/esm/src/secrets/mod.d.ts +6 -0
- package/esm/src/secrets/mod.d.ts.map +1 -0
- package/esm/src/secrets/mod.js +5 -0
- package/esm/src/secrets/secrets.d.ts +192 -0
- package/esm/src/secrets/secrets.d.ts.map +1 -0
- package/esm/src/secrets/secrets.js +528 -0
- package/package.json +50 -2
- package/script/src/cli/externalSkills.d.ts.map +1 -1
- package/script/src/cli/externalSkills.js +25 -20
- package/script/src/cli/mod.d.ts +72 -1
- package/script/src/cli/mod.d.ts.map +1 -1
- package/script/src/cli/mod.js +772 -33
- package/script/src/cli/projectSkills.d.ts +10 -3
- package/script/src/cli/projectSkills.d.ts.map +1 -1
- package/script/src/cli/projectSkills.js +173 -49
- package/script/src/cli/vercelBuildEnv.d.ts +28 -0
- package/script/src/cli/vercelBuildEnv.d.ts.map +1 -1
- package/script/src/cli/vercelBuildEnv.js +121 -30
- package/script/src/mail/postal.d.ts.map +1 -1
- package/script/src/mail/postal.js +2 -1
- package/script/src/next/secrets/mod.d.ts +108 -0
- package/script/src/next/secrets/mod.d.ts.map +1 -0
- package/script/src/next/secrets/mod.js +218 -0
- package/script/src/secrets/encoding.d.ts +32 -0
- package/script/src/secrets/encoding.d.ts.map +1 -0
- package/script/src/secrets/encoding.js +95 -0
- package/script/src/secrets/errors.d.ts +45 -0
- package/script/src/secrets/errors.d.ts.map +1 -0
- package/script/src/secrets/errors.js +45 -0
- package/script/src/secrets/fingerprint.d.ts +43 -0
- package/script/src/secrets/fingerprint.d.ts.map +1 -0
- package/script/src/secrets/fingerprint.js +92 -0
- package/script/src/secrets/frame.d.ts +34 -0
- package/script/src/secrets/frame.d.ts.map +1 -0
- package/script/src/secrets/frame.js +91 -0
- package/script/src/secrets/keyring.d.ts +62 -0
- package/script/src/secrets/keyring.d.ts.map +1 -0
- package/script/src/secrets/keyring.js +202 -0
- package/script/src/secrets/legacy.d.ts +60 -0
- package/script/src/secrets/legacy.d.ts.map +1 -0
- package/script/src/secrets/legacy.js +186 -0
- package/script/src/secrets/maintenance.d.ts +173 -0
- package/script/src/secrets/maintenance.d.ts.map +1 -0
- package/script/src/secrets/maintenance.js +323 -0
- package/script/src/secrets/mod.d.ts +6 -0
- package/script/src/secrets/mod.d.ts.map +1 -0
- package/script/src/secrets/mod.js +24 -0
- package/script/src/secrets/secrets.d.ts +192 -0
- package/script/src/secrets/secrets.d.ts.map +1 -0
- package/script/src/secrets/secrets.js +532 -0
- package/skills/loom/SKILL.md +74 -222
- package/skills/loom/references/dependency-upgrades.md +26 -0
- package/skills/loom/references/local-development.md +157 -0
- package/skills/loom/references/release-safety.md +118 -0
- package/skills/loom/references/release-trusted-sources.md +55 -0
- package/skills/loom/references/tools-and-skills.md +83 -0
- package/skills/loom-api-keys/SKILL.md +1 -1
- package/skills/loom-auth/SKILL.md +7 -60
- package/skills/loom-auth/references/secrets-and-rotation.md +61 -0
- package/skills/loom-db/SKILL.md +4 -79
- package/skills/loom-files/SKILL.md +4 -2
- package/skills/loom-files/references/provider-configuration.md +142 -0
- package/skills/loom-jobs/SKILL.md +9 -8
- package/skills/loom-lingui/SKILL.md +5 -3
- package/skills/loom-secrets/SKILL.md +252 -0
- package/skills/loom-torvalds-review/SKILL.md +9 -6
- package/skills/loom-torvalds-review/references/context-profiles.md +2 -1
- package/skills/upgrade-deps/SKILL.md +15 -7
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.assertWellFormed = assertWellFormed;
|
|
4
|
+
exports.encodeUtf8 = encodeUtf8;
|
|
5
|
+
exports.decodeUtf8 = decodeUtf8;
|
|
6
|
+
exports.toBase64Url = toBase64Url;
|
|
7
|
+
exports.fromBase64Url = fromBase64Url;
|
|
8
|
+
exports.pae = pae;
|
|
9
|
+
const encoder = new TextEncoder();
|
|
10
|
+
// `ignoreBOM: true` keeps a leading U+FEFF in the output; the default strips it.
|
|
11
|
+
const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
|
|
12
|
+
const BASE64URL_PATTERN = /^[A-Za-z0-9_-]*$/;
|
|
13
|
+
// Stay well under engine argument limits when spreading into fromCharCode.
|
|
14
|
+
const BINARY_CHUNK = 0x8000;
|
|
15
|
+
/**
|
|
16
|
+
* Rejects strings that UTF-8 encoding would silently change.
|
|
17
|
+
*
|
|
18
|
+
* `TextEncoder` turns every lone surrogate into U+FFFD, so two different
|
|
19
|
+
* JavaScript strings could otherwise produce the same bytes and collide as
|
|
20
|
+
* bindings or fingerprint input.
|
|
21
|
+
*/
|
|
22
|
+
function assertWellFormed(value, what) {
|
|
23
|
+
if (typeof value !== "string") {
|
|
24
|
+
throw new TypeError(`${what} must be a string.`);
|
|
25
|
+
}
|
|
26
|
+
if (!value.isWellFormed()) {
|
|
27
|
+
throw new TypeError(`${what} must be well-formed Unicode.`);
|
|
28
|
+
}
|
|
29
|
+
return value;
|
|
30
|
+
}
|
|
31
|
+
/** UTF-8 bytes of a well-formed string. */
|
|
32
|
+
function encodeUtf8(value, what) {
|
|
33
|
+
return encoder.encode(assertWellFormed(value, what));
|
|
34
|
+
}
|
|
35
|
+
/** Strict UTF-8 decoding. Throws on malformed input; preserves a leading BOM. */
|
|
36
|
+
function decodeUtf8(bytes) {
|
|
37
|
+
return decoder.decode(bytes);
|
|
38
|
+
}
|
|
39
|
+
/** Unpadded base64url. */
|
|
40
|
+
function toBase64Url(bytes) {
|
|
41
|
+
let binary = "";
|
|
42
|
+
for (let offset = 0; offset < bytes.length; offset += BINARY_CHUNK) {
|
|
43
|
+
binary += String.fromCharCode(...bytes.subarray(offset, offset + BINARY_CHUNK));
|
|
44
|
+
}
|
|
45
|
+
return btoa(binary)
|
|
46
|
+
.replaceAll("+", "-")
|
|
47
|
+
.replaceAll("/", "_")
|
|
48
|
+
.replace(/=+$/, "");
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Decodes unpadded base64url, accepting only the canonical spelling.
|
|
52
|
+
*
|
|
53
|
+
* Decoders tolerate padding, the standard alphabet and non-zero trailing bits.
|
|
54
|
+
* Re-encoding and comparing leaves exactly one accepted string per byte
|
|
55
|
+
* sequence, so a stored ciphertext cannot be respelled.
|
|
56
|
+
*/
|
|
57
|
+
function fromBase64Url(text) {
|
|
58
|
+
if (!BASE64URL_PATTERN.test(text)) {
|
|
59
|
+
return null;
|
|
60
|
+
}
|
|
61
|
+
let binary;
|
|
62
|
+
try {
|
|
63
|
+
binary = atob(text.replaceAll("-", "+").replaceAll("_", "/"));
|
|
64
|
+
}
|
|
65
|
+
catch {
|
|
66
|
+
return null;
|
|
67
|
+
}
|
|
68
|
+
const bytes = new Uint8Array(binary.length);
|
|
69
|
+
for (let index = 0; index < binary.length; index += 1) {
|
|
70
|
+
bytes[index] = binary.charCodeAt(index);
|
|
71
|
+
}
|
|
72
|
+
return toBase64Url(bytes) === text ? bytes : null;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Pre-authentication encoding, as in PASETO: a little-endian 64-bit count of
|
|
76
|
+
* pieces, then each piece prefixed with its little-endian 64-bit byte length.
|
|
77
|
+
*
|
|
78
|
+
* Joining fields with a separator is ambiguous whenever a field can contain
|
|
79
|
+
* the separator. Length prefixes make the encoding injective, so no two
|
|
80
|
+
* different lists of pieces produce the same bytes.
|
|
81
|
+
*/
|
|
82
|
+
function pae(pieces) {
|
|
83
|
+
const encoded = pieces.map((piece) => piece instanceof Uint8Array ? piece : encodeUtf8(piece, "Encoded piece"));
|
|
84
|
+
const length = encoded.reduce((total, piece) => total + 8 + piece.length, 8);
|
|
85
|
+
const output = new Uint8Array(length);
|
|
86
|
+
const view = new DataView(output.buffer);
|
|
87
|
+
view.setBigUint64(0, BigInt(encoded.length), true);
|
|
88
|
+
let offset = 8;
|
|
89
|
+
for (const piece of encoded) {
|
|
90
|
+
view.setBigUint64(offset, BigInt(piece.length), true);
|
|
91
|
+
output.set(piece, offset + 8);
|
|
92
|
+
offset += 8 + piece.length;
|
|
93
|
+
}
|
|
94
|
+
return output;
|
|
95
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Why a sealed value could not be opened.
|
|
3
|
+
*
|
|
4
|
+
* For operator logs and metrics only. Forwarding it to an end user tells a
|
|
5
|
+
* caller who submits tokens which key ids exist and whether a guess reached
|
|
6
|
+
* the cipher.
|
|
7
|
+
*/
|
|
8
|
+
export type SecretFailureReason =
|
|
9
|
+
/** Not a string this module could have produced, or the wrong kind. */
|
|
10
|
+
"malformed"
|
|
11
|
+
/** The key version named in the string is not configured. */
|
|
12
|
+
| "unknown-key"
|
|
13
|
+
/** The key version is configured but its value cannot be used. */
|
|
14
|
+
| "key-unavailable"
|
|
15
|
+
/** The key's fingerprint is not the one recorded for that version. */
|
|
16
|
+
| "key-mismatch"
|
|
17
|
+
/** Wrong key, wrong purpose, wrong binding, or altered ciphertext. */
|
|
18
|
+
| "authentication"
|
|
19
|
+
/** The value carried an expiry that has passed. */
|
|
20
|
+
| "expired";
|
|
21
|
+
/**
|
|
22
|
+
* Thrown by `open` for every failure. The message is fixed so that nothing
|
|
23
|
+
* about the cause, the ciphertext or the binding can leak through it.
|
|
24
|
+
*/
|
|
25
|
+
export declare class SecretUnreadableError extends Error {
|
|
26
|
+
/** See {@link SecretFailureReason}. Not for end users. */
|
|
27
|
+
readonly reason: SecretFailureReason;
|
|
28
|
+
constructor(reason: SecretFailureReason);
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* A key is missing or unusable. The message names the variable or key version
|
|
32
|
+
* and the problem, never the value.
|
|
33
|
+
*/
|
|
34
|
+
export declare class SecretsKeyError extends Error {
|
|
35
|
+
constructor(message: string);
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* A configured key is not the key that was recorded for its version: its
|
|
39
|
+
* fingerprint differs. Usually a paste mistake, or a version number reused
|
|
40
|
+
* for a new key.
|
|
41
|
+
*/
|
|
42
|
+
export declare class SecretsKeyMismatchError extends SecretsKeyError {
|
|
43
|
+
constructor(message: string);
|
|
44
|
+
}
|
|
45
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/src/secrets/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB;AAC7B,uEAAuE;AACrE,WAAW;AACb,6DAA6D;GAC3D,aAAa;AACf,kEAAkE;GAChE,iBAAiB;AACnB,sEAAsE;GACpE,cAAc;AAChB,sEAAsE;GACpE,gBAAgB;AAClB,mDAAmD;GACjD,SAAS,CAAC;AAEd;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;gBAEzB,MAAM,EAAE,mBAAmB;CAKxC;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,eAAe;gBAC9C,OAAO,EAAE,MAAM;CAI5B"}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.SecretsKeyMismatchError = exports.SecretsKeyError = exports.SecretUnreadableError = void 0;
|
|
4
|
+
/**
|
|
5
|
+
* Thrown by `open` for every failure. The message is fixed so that nothing
|
|
6
|
+
* about the cause, the ciphertext or the binding can leak through it.
|
|
7
|
+
*/
|
|
8
|
+
class SecretUnreadableError extends Error {
|
|
9
|
+
constructor(reason) {
|
|
10
|
+
super("Secret could not be read.");
|
|
11
|
+
/** See {@link SecretFailureReason}. Not for end users. */
|
|
12
|
+
Object.defineProperty(this, "reason", {
|
|
13
|
+
enumerable: true,
|
|
14
|
+
configurable: true,
|
|
15
|
+
writable: true,
|
|
16
|
+
value: void 0
|
|
17
|
+
});
|
|
18
|
+
this.name = "SecretUnreadableError";
|
|
19
|
+
this.reason = reason;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
exports.SecretUnreadableError = SecretUnreadableError;
|
|
23
|
+
/**
|
|
24
|
+
* A key is missing or unusable. The message names the variable or key version
|
|
25
|
+
* and the problem, never the value.
|
|
26
|
+
*/
|
|
27
|
+
class SecretsKeyError extends Error {
|
|
28
|
+
constructor(message) {
|
|
29
|
+
super(message);
|
|
30
|
+
this.name = "SecretsKeyError";
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
exports.SecretsKeyError = SecretsKeyError;
|
|
34
|
+
/**
|
|
35
|
+
* A configured key is not the key that was recorded for its version: its
|
|
36
|
+
* fingerprint differs. Usually a paste mistake, or a version number reused
|
|
37
|
+
* for a new key.
|
|
38
|
+
*/
|
|
39
|
+
class SecretsKeyMismatchError extends SecretsKeyError {
|
|
40
|
+
constructor(message) {
|
|
41
|
+
super(message);
|
|
42
|
+
this.name = "SecretsKeyMismatchError";
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
exports.SecretsKeyMismatchError = SecretsKeyMismatchError;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/** What a key version is for, as recorded beside its fingerprint. */
|
|
2
|
+
export type SecretKeyState =
|
|
3
|
+
/** Encrypts new values and decrypts. Exactly one key is active. */
|
|
4
|
+
"active"
|
|
5
|
+
/** Decrypts only: an older key, or a new one not yet switched to. */
|
|
6
|
+
| "decrypt-only"
|
|
7
|
+
/** No longer needed. Its variable is expected to be gone. */
|
|
8
|
+
| "retired";
|
|
9
|
+
/**
|
|
10
|
+
* One key the app expects to find, with the fingerprint recorded when the key
|
|
11
|
+
* was generated. The list for an environment is committed with the app (in
|
|
12
|
+
* `loom.json`), so a deployed key that differs from the copy in the password
|
|
13
|
+
* manager is detected instead of trusted.
|
|
14
|
+
*/
|
|
15
|
+
export interface ExpectedSecretKey {
|
|
16
|
+
id: number;
|
|
17
|
+
/** 16 lowercase hex characters from {@link secretKeyFingerprint}. */
|
|
18
|
+
fingerprint: string;
|
|
19
|
+
state: SecretKeyState;
|
|
20
|
+
}
|
|
21
|
+
/** Whether a string has the shape of a key fingerprint. */
|
|
22
|
+
export declare function isSecretKeyFingerprint(value: unknown): value is string;
|
|
23
|
+
/**
|
|
24
|
+
* A short public identifier of a key: the first 8 bytes of an HKDF output that
|
|
25
|
+
* is used for nothing else.
|
|
26
|
+
*
|
|
27
|
+
* A write-only variable cannot be read back, so this is how an operator proves
|
|
28
|
+
* that the key in the deployment is the key in the password manager: compute
|
|
29
|
+
* it from the saved copy, and compare with what the running app reports. It is
|
|
30
|
+
* safe to commit and to log. It is not a key id and never appears in a sealed
|
|
31
|
+
* string.
|
|
32
|
+
*/
|
|
33
|
+
export declare function secretKeyFingerprint(key: Uint8Array): Promise<string>;
|
|
34
|
+
/**
|
|
35
|
+
* Validates an expected-key list, for example one read from `loom.json`, and
|
|
36
|
+
* returns a copy. Throws a `TypeError` naming the entry that is wrong.
|
|
37
|
+
*
|
|
38
|
+
* The list must have exactly one `active` key. No version and no fingerprint
|
|
39
|
+
* may appear twice: one fingerprint under two versions means one key was
|
|
40
|
+
* entered twice.
|
|
41
|
+
*/
|
|
42
|
+
export declare function parseExpectedSecretKeys(value: unknown): ExpectedSecretKey[];
|
|
43
|
+
//# sourceMappingURL=fingerprint.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../../src/src/secrets/fingerprint.ts"],"names":[],"mappings":"AAOA,qEAAqE;AACrE,MAAM,MAAM,cAAc;AACxB,mEAAmE;AACjE,QAAQ;AACV,qEAAqE;GACnE,cAAc;AAChB,6DAA6D;GAC3D,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,cAAc,CAAC;CACvB;AAED,2DAA2D;AAC3D,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEtE;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA0B3E;AAQD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,EAAE,CA6C3E"}
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.isSecretKeyFingerprint = isSecretKeyFingerprint;
|
|
4
|
+
exports.secretKeyFingerprint = secretKeyFingerprint;
|
|
5
|
+
exports.parseExpectedSecretKeys = parseExpectedSecretKeys;
|
|
6
|
+
const encoding_js_1 = require("./encoding.js");
|
|
7
|
+
const errors_js_1 = require("./errors.js");
|
|
8
|
+
const keyring_js_1 = require("./keyring.js");
|
|
9
|
+
const FINGERPRINT_BITS = 64;
|
|
10
|
+
const FINGERPRINT_PATTERN = /^[0-9a-f]{16}$/;
|
|
11
|
+
/** Whether a string has the shape of a key fingerprint. */
|
|
12
|
+
function isSecretKeyFingerprint(value) {
|
|
13
|
+
return typeof value === "string" && FINGERPRINT_PATTERN.test(value);
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* A short public identifier of a key: the first 8 bytes of an HKDF output that
|
|
17
|
+
* is used for nothing else.
|
|
18
|
+
*
|
|
19
|
+
* A write-only variable cannot be read back, so this is how an operator proves
|
|
20
|
+
* that the key in the deployment is the key in the password manager: compute
|
|
21
|
+
* it from the saved copy, and compare with what the running app reports. It is
|
|
22
|
+
* safe to commit and to log. It is not a key id and never appears in a sealed
|
|
23
|
+
* string.
|
|
24
|
+
*/
|
|
25
|
+
async function secretKeyFingerprint(key) {
|
|
26
|
+
if (!(key instanceof Uint8Array) || key.length !== keyring_js_1.SECRETS_KEY_BYTES) {
|
|
27
|
+
throw new errors_js_1.SecretsKeyError(`A key must be exactly ${keyring_js_1.SECRETS_KEY_BYTES} bytes to be fingerprinted.`);
|
|
28
|
+
}
|
|
29
|
+
const base = await globalThis.crypto.subtle.importKey("raw", new Uint8Array(key), "HKDF", false, ["deriveBits"]);
|
|
30
|
+
const bits = await globalThis.crypto.subtle.deriveBits({
|
|
31
|
+
name: "HKDF",
|
|
32
|
+
hash: "SHA-256",
|
|
33
|
+
salt: new Uint8Array(0),
|
|
34
|
+
info: (0, encoding_js_1.pae)(["loom-secrets", "ls1", "fingerprint"]),
|
|
35
|
+
}, base, FINGERPRINT_BITS);
|
|
36
|
+
return [...new Uint8Array(bits)]
|
|
37
|
+
.map((byte) => byte.toString(16).padStart(2, "0"))
|
|
38
|
+
.join("");
|
|
39
|
+
}
|
|
40
|
+
const KEY_STATES = [
|
|
41
|
+
"active",
|
|
42
|
+
"decrypt-only",
|
|
43
|
+
"retired",
|
|
44
|
+
];
|
|
45
|
+
/**
|
|
46
|
+
* Validates an expected-key list, for example one read from `loom.json`, and
|
|
47
|
+
* returns a copy. Throws a `TypeError` naming the entry that is wrong.
|
|
48
|
+
*
|
|
49
|
+
* The list must have exactly one `active` key. No version and no fingerprint
|
|
50
|
+
* may appear twice: one fingerprint under two versions means one key was
|
|
51
|
+
* entered twice.
|
|
52
|
+
*/
|
|
53
|
+
function parseExpectedSecretKeys(value) {
|
|
54
|
+
if (!Array.isArray(value)) {
|
|
55
|
+
throw new TypeError("The expected key list must be an array.");
|
|
56
|
+
}
|
|
57
|
+
const ids = new Set();
|
|
58
|
+
const fingerprints = new Set();
|
|
59
|
+
const keys = value.map((entry, index) => {
|
|
60
|
+
const candidate = entry;
|
|
61
|
+
const where = `Expected key ${index + 1}`;
|
|
62
|
+
if (candidate === null || typeof candidate !== "object") {
|
|
63
|
+
throw new TypeError(`${where} must be an object.`);
|
|
64
|
+
}
|
|
65
|
+
if (!(0, keyring_js_1.isSecretKeyId)(candidate.id)) {
|
|
66
|
+
throw new TypeError(`${where} needs a key version as its id.`);
|
|
67
|
+
}
|
|
68
|
+
if (!isSecretKeyFingerprint(candidate.fingerprint)) {
|
|
69
|
+
throw new TypeError(`${where} needs a fingerprint of 16 lowercase hex characters.`);
|
|
70
|
+
}
|
|
71
|
+
if (!KEY_STATES.includes(candidate.state)) {
|
|
72
|
+
throw new TypeError(`${where} needs a state of active, decrypt-only or retired.`);
|
|
73
|
+
}
|
|
74
|
+
if (ids.has(candidate.id)) {
|
|
75
|
+
throw new TypeError(`Key version ${candidate.id} is listed twice.`);
|
|
76
|
+
}
|
|
77
|
+
if (fingerprints.has(candidate.fingerprint)) {
|
|
78
|
+
throw new TypeError(`Key version ${candidate.id} has the same fingerprint as another version.`);
|
|
79
|
+
}
|
|
80
|
+
ids.add(candidate.id);
|
|
81
|
+
fingerprints.add(candidate.fingerprint);
|
|
82
|
+
return {
|
|
83
|
+
fingerprint: candidate.fingerprint,
|
|
84
|
+
id: candidate.id,
|
|
85
|
+
state: candidate.state,
|
|
86
|
+
};
|
|
87
|
+
});
|
|
88
|
+
if (keys.filter((key) => key.state === "active").length !== 1) {
|
|
89
|
+
throw new TypeError("Exactly one expected key must be active.");
|
|
90
|
+
}
|
|
91
|
+
return keys;
|
|
92
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/** What a sealed payload holds, recorded in the frame so `open` can check it. */
|
|
2
|
+
export type SecretPayloadKind = "text" | "bytes" | "json";
|
|
3
|
+
/** A parsed plaintext frame. */
|
|
4
|
+
export interface SecretFrame {
|
|
5
|
+
kind: SecretPayloadKind;
|
|
6
|
+
/** Seconds since the Unix epoch after which the value must not be used. */
|
|
7
|
+
expiresAt: number | undefined;
|
|
8
|
+
payload: Uint8Array<ArrayBuffer>;
|
|
9
|
+
}
|
|
10
|
+
/** Plaintext is padded to a multiple of this many bytes. */
|
|
11
|
+
export declare const FRAME_BLOCK_BYTES = 32;
|
|
12
|
+
/**
|
|
13
|
+
* Builds the plaintext that is encrypted:
|
|
14
|
+
*
|
|
15
|
+
* ```
|
|
16
|
+
* header ‖ [expiry] ‖ payload ‖ 0x80 ‖ 0x00… (to a multiple of 32 bytes)
|
|
17
|
+
* ```
|
|
18
|
+
*
|
|
19
|
+
* The header byte holds the payload kind in its low two bits and sets 0x80
|
|
20
|
+
* when an 8-byte big-endian expiry follows. Padding hides the exact length of
|
|
21
|
+
* short values such as passwords; it is removed only after the ciphertext has
|
|
22
|
+
* authenticated, so it cannot act as a padding oracle.
|
|
23
|
+
*/
|
|
24
|
+
export declare function encodeFrame(frame: {
|
|
25
|
+
kind: SecretPayloadKind;
|
|
26
|
+
expiresAt?: number | undefined;
|
|
27
|
+
payload: Uint8Array;
|
|
28
|
+
}): Uint8Array<ArrayBuffer>;
|
|
29
|
+
/**
|
|
30
|
+
* Parses an authenticated frame, or returns `null` when it is not one that
|
|
31
|
+
* {@link encodeFrame} could have produced.
|
|
32
|
+
*/
|
|
33
|
+
export declare function decodeFrame(bytes: Uint8Array): SecretFrame | null;
|
|
34
|
+
//# sourceMappingURL=frame.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../../src/src/secrets/frame.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1D,gCAAgC;AAChC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,iBAAiB,CAAC;IACxB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;CAClC;AAED,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAapC;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE;IACjC,IAAI,EAAE,iBAAiB,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,OAAO,EAAE,UAAU,CAAC;CACrB,GAAG,UAAU,CAAC,WAAW,CAAC,CAwB1B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CA4CjE"}
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.FRAME_BLOCK_BYTES = void 0;
|
|
4
|
+
exports.encodeFrame = encodeFrame;
|
|
5
|
+
exports.decodeFrame = decodeFrame;
|
|
6
|
+
/** Plaintext is padded to a multiple of this many bytes. */
|
|
7
|
+
exports.FRAME_BLOCK_BYTES = 32;
|
|
8
|
+
const KIND_CODES = {
|
|
9
|
+
text: 0,
|
|
10
|
+
bytes: 1,
|
|
11
|
+
json: 2,
|
|
12
|
+
};
|
|
13
|
+
const KINDS = ["text", "bytes", "json"];
|
|
14
|
+
const KIND_MASK = 0x03;
|
|
15
|
+
const EXPIRY_FLAG = 0x80;
|
|
16
|
+
const PADDING_MARKER = 0x80;
|
|
17
|
+
const EXPIRY_BYTES = 8;
|
|
18
|
+
/**
|
|
19
|
+
* Builds the plaintext that is encrypted:
|
|
20
|
+
*
|
|
21
|
+
* ```
|
|
22
|
+
* header ‖ [expiry] ‖ payload ‖ 0x80 ‖ 0x00… (to a multiple of 32 bytes)
|
|
23
|
+
* ```
|
|
24
|
+
*
|
|
25
|
+
* The header byte holds the payload kind in its low two bits and sets 0x80
|
|
26
|
+
* when an 8-byte big-endian expiry follows. Padding hides the exact length of
|
|
27
|
+
* short values such as passwords; it is removed only after the ciphertext has
|
|
28
|
+
* authenticated, so it cannot act as a padding oracle.
|
|
29
|
+
*/
|
|
30
|
+
function encodeFrame(frame) {
|
|
31
|
+
const hasExpiry = frame.expiresAt !== undefined;
|
|
32
|
+
if (hasExpiry &&
|
|
33
|
+
(!Number.isSafeInteger(frame.expiresAt) || frame.expiresAt < 0)) {
|
|
34
|
+
throw new RangeError("Expiry must be a non-negative whole second.");
|
|
35
|
+
}
|
|
36
|
+
const headerBytes = 1 + (hasExpiry ? EXPIRY_BYTES : 0);
|
|
37
|
+
const length = Math.ceil((headerBytes + frame.payload.length + 1) / exports.FRAME_BLOCK_BYTES) * exports.FRAME_BLOCK_BYTES;
|
|
38
|
+
const output = new Uint8Array(length);
|
|
39
|
+
output[0] = KIND_CODES[frame.kind] | (hasExpiry ? EXPIRY_FLAG : 0);
|
|
40
|
+
if (hasExpiry) {
|
|
41
|
+
new DataView(output.buffer).setBigUint64(1, BigInt(frame.expiresAt), false);
|
|
42
|
+
}
|
|
43
|
+
output.set(frame.payload, headerBytes);
|
|
44
|
+
output[headerBytes + frame.payload.length] = PADDING_MARKER;
|
|
45
|
+
return output;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Parses an authenticated frame, or returns `null` when it is not one that
|
|
49
|
+
* {@link encodeFrame} could have produced.
|
|
50
|
+
*/
|
|
51
|
+
function decodeFrame(bytes) {
|
|
52
|
+
if (bytes.length === 0 || bytes.length % exports.FRAME_BLOCK_BYTES !== 0) {
|
|
53
|
+
return null;
|
|
54
|
+
}
|
|
55
|
+
let markerIndex = bytes.length - 1;
|
|
56
|
+
while (markerIndex >= 0 && bytes[markerIndex] === 0) {
|
|
57
|
+
markerIndex -= 1;
|
|
58
|
+
}
|
|
59
|
+
if (markerIndex < 0 ||
|
|
60
|
+
bytes[markerIndex] !== PADDING_MARKER ||
|
|
61
|
+
bytes.length - markerIndex > exports.FRAME_BLOCK_BYTES) {
|
|
62
|
+
return null;
|
|
63
|
+
}
|
|
64
|
+
const header = bytes[0];
|
|
65
|
+
if ((header & ~(KIND_MASK | EXPIRY_FLAG)) !== 0) {
|
|
66
|
+
return null;
|
|
67
|
+
}
|
|
68
|
+
const kind = KINDS[header & KIND_MASK];
|
|
69
|
+
if (kind === undefined) {
|
|
70
|
+
return null;
|
|
71
|
+
}
|
|
72
|
+
const hasExpiry = (header & EXPIRY_FLAG) !== 0;
|
|
73
|
+
const headerBytes = 1 + (hasExpiry ? EXPIRY_BYTES : 0);
|
|
74
|
+
if (markerIndex < headerBytes) {
|
|
75
|
+
return null;
|
|
76
|
+
}
|
|
77
|
+
let expiresAt;
|
|
78
|
+
if (hasExpiry) {
|
|
79
|
+
const seconds = new DataView(bytes.buffer, bytes.byteOffset, bytes.length)
|
|
80
|
+
.getBigUint64(1, false);
|
|
81
|
+
if (seconds > BigInt(Number.MAX_SAFE_INTEGER)) {
|
|
82
|
+
return null;
|
|
83
|
+
}
|
|
84
|
+
expiresAt = Number(seconds);
|
|
85
|
+
}
|
|
86
|
+
return {
|
|
87
|
+
kind,
|
|
88
|
+
expiresAt,
|
|
89
|
+
payload: bytes.slice(headerBytes, markerIndex),
|
|
90
|
+
};
|
|
91
|
+
}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/** Every key is exactly this many random bytes. */
|
|
2
|
+
export declare const SECRETS_KEY_BYTES = 32;
|
|
3
|
+
export declare const DEFAULT_SECRETS_KEY_ENV_PREFIX = "LOOM_SECRETS_KEY_";
|
|
4
|
+
export declare const DEFAULT_SECRETS_ACTIVE_KEY_ENV = "LOOM_SECRETS_ACTIVE_KEY";
|
|
5
|
+
type SecretsEnv = Record<string, string | undefined>;
|
|
6
|
+
/**
|
|
7
|
+
* Where keys come from. Asynchronous so that a provider can later unwrap a key
|
|
8
|
+
* through a KMS without changing any stored ciphertext.
|
|
9
|
+
*/
|
|
10
|
+
export interface SecretKeyring {
|
|
11
|
+
/** The key version that encrypts. Throws {@link SecretsKeyError}. */
|
|
12
|
+
activeKeyId(): Promise<number>;
|
|
13
|
+
/**
|
|
14
|
+
* The raw key for a version, or `null` when that version is not configured.
|
|
15
|
+
* Throws {@link SecretsKeyError} when it is configured but unusable.
|
|
16
|
+
*/
|
|
17
|
+
key(id: number): Promise<Uint8Array | null>;
|
|
18
|
+
}
|
|
19
|
+
/** Options for {@link envKeyring}. */
|
|
20
|
+
export interface EnvKeyringOptions {
|
|
21
|
+
/** Defaults to `process.env`, read at call time and never at import. */
|
|
22
|
+
env?: SecretsEnv;
|
|
23
|
+
/** Variable name prefix; the key version is appended. */
|
|
24
|
+
keyPrefix?: string;
|
|
25
|
+
/** Variable that names the key version that encrypts. */
|
|
26
|
+
activeKeyName?: string;
|
|
27
|
+
}
|
|
28
|
+
/** Whether a number can be a key version: an integer from 1 to 999999999. */
|
|
29
|
+
export declare function isSecretKeyId(id: unknown): id is number;
|
|
30
|
+
/** Parses the decimal key version used in variable names and sealed strings. */
|
|
31
|
+
export declare function parseSecretKeyId(text: string): number | null;
|
|
32
|
+
/**
|
|
33
|
+
* Trims a configured key value and rejects what is certainly not a key: an
|
|
34
|
+
* empty value, or a placeholder a platform or build put in its place. Shared
|
|
35
|
+
* with the legacy reader so both name these cases the same way.
|
|
36
|
+
*/
|
|
37
|
+
export declare function trimKeyValue(value: string, name: string): string;
|
|
38
|
+
/**
|
|
39
|
+
* Decodes one configured key, accepting standard base64 or base64url.
|
|
40
|
+
*
|
|
41
|
+
* Surrounding whitespace is trimmed: a pasted trailing newline is the common
|
|
42
|
+
* mistake, and a write-only variable cannot be inspected to find it. Errors
|
|
43
|
+
* name the variable and the problem, never the value.
|
|
44
|
+
*/
|
|
45
|
+
export declare function decodeSecretKey(value: string, name: string): Uint8Array;
|
|
46
|
+
/**
|
|
47
|
+
* Reads keys from environment variables: one variable per key version
|
|
48
|
+
* (`LOOM_SECRETS_KEY_<n>`) and a required pointer
|
|
49
|
+
* (`LOOM_SECRETS_ACTIVE_KEY`) naming the version that encrypts.
|
|
50
|
+
*
|
|
51
|
+
* A version is always read by name. Nothing is enumerated and nothing is read
|
|
52
|
+
* until a key is needed, so a build that never seals or opens needs no key,
|
|
53
|
+
* and one unusable variable does not affect the others.
|
|
54
|
+
*/
|
|
55
|
+
export declare function envKeyring(options?: EnvKeyringOptions): SecretKeyring;
|
|
56
|
+
/**
|
|
57
|
+
* A fixed set of keys, for tests and for callers that load keys themselves.
|
|
58
|
+
* `activeKeyId` may be omitted only when exactly one key is given.
|
|
59
|
+
*/
|
|
60
|
+
export declare function staticKeyring(keys: Readonly<Record<number, Uint8Array>>, activeKeyId?: number): SecretKeyring;
|
|
61
|
+
export {};
|
|
62
|
+
//# sourceMappingURL=keyring.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"keyring.d.ts","sourceRoot":"","sources":["../../../src/src/secrets/keyring.ts"],"names":[],"mappings":"AAIA,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,8BAA8B,sBAAsB,CAAC;AAClE,eAAO,MAAM,8BAA8B,4BAA4B,CAAC;AAexE,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B;;;OAGG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;CAC7C;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,MAAM,CAGvD;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAiBhE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CA4BvE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,aAAa,CAkDzE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,EAC1C,WAAW,CAAC,EAAE,MAAM,GACnB,aAAa,CA8Bf"}
|