@gadicc/loom 1.35.3 → 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.
Files changed (103) hide show
  1. package/README.md +56 -0
  2. package/THIRD_PARTY_NOTICES.md +12 -9
  3. package/esm/src/cli/externalSkills.d.ts.map +1 -1
  4. package/esm/src/cli/externalSkills.js +25 -20
  5. package/esm/src/cli/mod.d.ts +72 -1
  6. package/esm/src/cli/mod.d.ts.map +1 -1
  7. package/esm/src/cli/mod.js +771 -36
  8. package/esm/src/cli/projectSkills.d.ts +10 -3
  9. package/esm/src/cli/projectSkills.d.ts.map +1 -1
  10. package/esm/src/cli/projectSkills.js +173 -49
  11. package/esm/src/cli/vercelBuildEnv.d.ts +28 -0
  12. package/esm/src/cli/vercelBuildEnv.d.ts.map +1 -1
  13. package/esm/src/cli/vercelBuildEnv.js +120 -30
  14. package/esm/src/next/secrets/mod.d.ts +108 -0
  15. package/esm/src/next/secrets/mod.d.ts.map +1 -0
  16. package/esm/src/next/secrets/mod.js +176 -0
  17. package/esm/src/secrets/encoding.d.ts +32 -0
  18. package/esm/src/secrets/encoding.d.ts.map +1 -0
  19. package/esm/src/secrets/encoding.js +87 -0
  20. package/esm/src/secrets/errors.d.ts +45 -0
  21. package/esm/src/secrets/errors.d.ts.map +1 -0
  22. package/esm/src/secrets/errors.js +39 -0
  23. package/esm/src/secrets/fingerprint.d.ts +43 -0
  24. package/esm/src/secrets/fingerprint.d.ts.map +1 -0
  25. package/esm/src/secrets/fingerprint.js +87 -0
  26. package/esm/src/secrets/frame.d.ts +34 -0
  27. package/esm/src/secrets/frame.d.ts.map +1 -0
  28. package/esm/src/secrets/frame.js +86 -0
  29. package/esm/src/secrets/keyring.d.ts +62 -0
  30. package/esm/src/secrets/keyring.d.ts.map +1 -0
  31. package/esm/src/secrets/keyring.js +160 -0
  32. package/esm/src/secrets/legacy.d.ts +60 -0
  33. package/esm/src/secrets/legacy.d.ts.map +1 -0
  34. package/esm/src/secrets/legacy.js +147 -0
  35. package/esm/src/secrets/maintenance.d.ts +173 -0
  36. package/esm/src/secrets/maintenance.d.ts.map +1 -0
  37. package/esm/src/secrets/maintenance.js +315 -0
  38. package/esm/src/secrets/mod.d.ts +6 -0
  39. package/esm/src/secrets/mod.d.ts.map +1 -0
  40. package/esm/src/secrets/mod.js +5 -0
  41. package/esm/src/secrets/secrets.d.ts +192 -0
  42. package/esm/src/secrets/secrets.d.ts.map +1 -0
  43. package/esm/src/secrets/secrets.js +528 -0
  44. package/package.json +50 -2
  45. package/script/src/cli/externalSkills.d.ts.map +1 -1
  46. package/script/src/cli/externalSkills.js +25 -20
  47. package/script/src/cli/mod.d.ts +72 -1
  48. package/script/src/cli/mod.d.ts.map +1 -1
  49. package/script/src/cli/mod.js +772 -33
  50. package/script/src/cli/projectSkills.d.ts +10 -3
  51. package/script/src/cli/projectSkills.d.ts.map +1 -1
  52. package/script/src/cli/projectSkills.js +173 -49
  53. package/script/src/cli/vercelBuildEnv.d.ts +28 -0
  54. package/script/src/cli/vercelBuildEnv.d.ts.map +1 -1
  55. package/script/src/cli/vercelBuildEnv.js +121 -30
  56. package/script/src/next/secrets/mod.d.ts +108 -0
  57. package/script/src/next/secrets/mod.d.ts.map +1 -0
  58. package/script/src/next/secrets/mod.js +218 -0
  59. package/script/src/secrets/encoding.d.ts +32 -0
  60. package/script/src/secrets/encoding.d.ts.map +1 -0
  61. package/script/src/secrets/encoding.js +95 -0
  62. package/script/src/secrets/errors.d.ts +45 -0
  63. package/script/src/secrets/errors.d.ts.map +1 -0
  64. package/script/src/secrets/errors.js +45 -0
  65. package/script/src/secrets/fingerprint.d.ts +43 -0
  66. package/script/src/secrets/fingerprint.d.ts.map +1 -0
  67. package/script/src/secrets/fingerprint.js +92 -0
  68. package/script/src/secrets/frame.d.ts +34 -0
  69. package/script/src/secrets/frame.d.ts.map +1 -0
  70. package/script/src/secrets/frame.js +91 -0
  71. package/script/src/secrets/keyring.d.ts +62 -0
  72. package/script/src/secrets/keyring.d.ts.map +1 -0
  73. package/script/src/secrets/keyring.js +202 -0
  74. package/script/src/secrets/legacy.d.ts +60 -0
  75. package/script/src/secrets/legacy.d.ts.map +1 -0
  76. package/script/src/secrets/legacy.js +186 -0
  77. package/script/src/secrets/maintenance.d.ts +173 -0
  78. package/script/src/secrets/maintenance.d.ts.map +1 -0
  79. package/script/src/secrets/maintenance.js +323 -0
  80. package/script/src/secrets/mod.d.ts +6 -0
  81. package/script/src/secrets/mod.d.ts.map +1 -0
  82. package/script/src/secrets/mod.js +24 -0
  83. package/script/src/secrets/secrets.d.ts +192 -0
  84. package/script/src/secrets/secrets.d.ts.map +1 -0
  85. package/script/src/secrets/secrets.js +532 -0
  86. package/skills/loom/SKILL.md +74 -222
  87. package/skills/loom/references/dependency-upgrades.md +26 -0
  88. package/skills/loom/references/local-development.md +157 -0
  89. package/skills/loom/references/release-safety.md +118 -0
  90. package/skills/loom/references/release-trusted-sources.md +55 -0
  91. package/skills/loom/references/tools-and-skills.md +83 -0
  92. package/skills/loom-api-keys/SKILL.md +1 -1
  93. package/skills/loom-auth/SKILL.md +7 -60
  94. package/skills/loom-auth/references/secrets-and-rotation.md +61 -0
  95. package/skills/loom-db/SKILL.md +4 -79
  96. package/skills/loom-files/SKILL.md +4 -2
  97. package/skills/loom-files/references/provider-configuration.md +142 -0
  98. package/skills/loom-jobs/SKILL.md +9 -8
  99. package/skills/loom-lingui/SKILL.md +5 -3
  100. package/skills/loom-secrets/SKILL.md +252 -0
  101. package/skills/loom-torvalds-review/SKILL.md +9 -6
  102. package/skills/loom-torvalds-review/references/context-profiles.md +2 -1
  103. package/skills/upgrade-deps/SKILL.md +15 -7
@@ -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"}
@@ -0,0 +1,202 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.DEFAULT_SECRETS_ACTIVE_KEY_ENV = exports.DEFAULT_SECRETS_KEY_ENV_PREFIX = exports.SECRETS_KEY_BYTES = void 0;
37
+ exports.isSecretKeyId = isSecretKeyId;
38
+ exports.parseSecretKeyId = parseSecretKeyId;
39
+ exports.trimKeyValue = trimKeyValue;
40
+ exports.decodeSecretKey = decodeSecretKey;
41
+ exports.envKeyring = envKeyring;
42
+ exports.staticKeyring = staticKeyring;
43
+ const dntShim = __importStar(require("../../_dnt.shims.js"));
44
+ const encoding_js_1 = require("./encoding.js");
45
+ const errors_js_1 = require("./errors.js");
46
+ /** Every key is exactly this many random bytes. */
47
+ exports.SECRETS_KEY_BYTES = 32;
48
+ exports.DEFAULT_SECRETS_KEY_ENV_PREFIX = "LOOM_SECRETS_KEY_";
49
+ exports.DEFAULT_SECRETS_ACTIVE_KEY_ENV = "LOOM_SECRETS_ACTIVE_KEY";
50
+ const KEY_ID_PATTERN = /^[1-9][0-9]{0,8}$/;
51
+ const ASCII_WHITESPACE_ENDS = /^[ \t\n\v\f\r]+|[ \t\n\v\f\r]+$/g;
52
+ // What platforms substitute for a value they will not reveal. Matched exactly:
53
+ // anything else that is not a key already fails the base64 check below.
54
+ const REDACTION_PLACEHOLDERS = new Set([
55
+ "[redacted]",
56
+ "[sensitive]",
57
+ "vercel sensitive value",
58
+ ]);
59
+ // Written by `loom` release tooling in place of an unreadable Secret during a
60
+ // local production build (see src/cli/vercelBuildEnv.ts).
61
+ const BUILD_PLACEHOLDER_PREFIX = "loom-build-only-";
62
+ /** Whether a number can be a key version: an integer from 1 to 999999999. */
63
+ function isSecretKeyId(id) {
64
+ return typeof id === "number" && Number.isInteger(id) &&
65
+ KEY_ID_PATTERN.test(String(id));
66
+ }
67
+ /** Parses the decimal key version used in variable names and sealed strings. */
68
+ function parseSecretKeyId(text) {
69
+ return KEY_ID_PATTERN.test(text) ? Number(text) : null;
70
+ }
71
+ /**
72
+ * Trims a configured key value and rejects what is certainly not a key: an
73
+ * empty value, or a placeholder a platform or build put in its place. Shared
74
+ * with the legacy reader so both name these cases the same way.
75
+ */
76
+ function trimKeyValue(value, name) {
77
+ const trimmed = value.replace(ASCII_WHITESPACE_ENDS, "");
78
+ if (trimmed === "") {
79
+ throw new errors_js_1.SecretsKeyError(`${name} is empty.`);
80
+ }
81
+ const lowered = trimmed.toLowerCase();
82
+ if (REDACTION_PLACEHOLDERS.has(lowered)) {
83
+ throw new errors_js_1.SecretsKeyError(`${name} is a redaction placeholder; the real value is not available to this process.`);
84
+ }
85
+ if (lowered.startsWith(BUILD_PLACEHOLDER_PREFIX)) {
86
+ throw new errors_js_1.SecretsKeyError(`${name} is a build-only placeholder; secrets cannot be used during this build.`);
87
+ }
88
+ return trimmed;
89
+ }
90
+ /**
91
+ * Decodes one configured key, accepting standard base64 or base64url.
92
+ *
93
+ * Surrounding whitespace is trimmed: a pasted trailing newline is the common
94
+ * mistake, and a write-only variable cannot be inspected to find it. Errors
95
+ * name the variable and the problem, never the value.
96
+ */
97
+ function decodeSecretKey(value, name) {
98
+ const trimmed = trimKeyValue(value, name);
99
+ const invalid = new errors_js_1.SecretsKeyError(`${name} must be base64 or base64url of ${exports.SECRETS_KEY_BYTES} random bytes.`);
100
+ const unpadded = trimmed.replace(/=+$/, "");
101
+ const padding = trimmed.length - unpadded.length;
102
+ const usesStandard = /[+/]/.test(unpadded);
103
+ if (usesStandard && /[-_]/.test(unpadded)) {
104
+ throw invalid;
105
+ }
106
+ // Padding is optional, but when present it must be the right amount.
107
+ if (padding !== 0 && padding !== (4 - (unpadded.length % 4)) % 4) {
108
+ throw invalid;
109
+ }
110
+ const bytes = (0, encoding_js_1.fromBase64Url)(unpadded.replaceAll("+", "-").replaceAll("/", "_"));
111
+ if (!bytes) {
112
+ throw invalid;
113
+ }
114
+ if (bytes.length !== exports.SECRETS_KEY_BYTES) {
115
+ throw new errors_js_1.SecretsKeyError(`${name} must decode to exactly ${exports.SECRETS_KEY_BYTES} bytes; received ${bytes.length}.`);
116
+ }
117
+ return bytes;
118
+ }
119
+ function processEnv() {
120
+ return dntShim.dntGlobalThis.process?.env ?? {};
121
+ }
122
+ /**
123
+ * Reads keys from environment variables: one variable per key version
124
+ * (`LOOM_SECRETS_KEY_<n>`) and a required pointer
125
+ * (`LOOM_SECRETS_ACTIVE_KEY`) naming the version that encrypts.
126
+ *
127
+ * A version is always read by name. Nothing is enumerated and nothing is read
128
+ * until a key is needed, so a build that never seals or opens needs no key,
129
+ * and one unusable variable does not affect the others.
130
+ */
131
+ function envKeyring(options = {}) {
132
+ const keyPrefix = options.keyPrefix ?? exports.DEFAULT_SECRETS_KEY_ENV_PREFIX;
133
+ const activeKeyName = options.activeKeyName ??
134
+ exports.DEFAULT_SECRETS_ACTIVE_KEY_ENV;
135
+ const env = () => options.env ?? processEnv();
136
+ // Reading the environment can itself throw, for example under Deno without
137
+ // permission for that variable. Either way the caller gets a rejection.
138
+ function read(name) {
139
+ try {
140
+ return env()[name];
141
+ }
142
+ catch {
143
+ throw new errors_js_1.SecretsKeyError(`${name} could not be read from the environment.`);
144
+ }
145
+ }
146
+ return {
147
+ activeKeyId() {
148
+ try {
149
+ const raw = read(activeKeyName);
150
+ const id = raw === undefined
151
+ ? null
152
+ : parseSecretKeyId(raw.replace(ASCII_WHITESPACE_ENDS, ""));
153
+ if (id === null) {
154
+ throw new errors_js_1.SecretsKeyError(`${activeKeyName} must name the key version that encrypts, for example 1.`);
155
+ }
156
+ return Promise.resolve(id);
157
+ }
158
+ catch (error) {
159
+ return Promise.reject(error);
160
+ }
161
+ },
162
+ key(id) {
163
+ if (!isSecretKeyId(id)) {
164
+ return Promise.resolve(null);
165
+ }
166
+ const name = `${keyPrefix}${id}`;
167
+ try {
168
+ const raw = read(name);
169
+ return Promise.resolve(raw === undefined ? null : decodeSecretKey(raw, name));
170
+ }
171
+ catch (error) {
172
+ return Promise.reject(error);
173
+ }
174
+ },
175
+ };
176
+ }
177
+ /**
178
+ * A fixed set of keys, for tests and for callers that load keys themselves.
179
+ * `activeKeyId` may be omitted only when exactly one key is given.
180
+ */
181
+ function staticKeyring(keys, activeKeyId) {
182
+ const ids = Object.keys(keys).map(Number);
183
+ const active = activeKeyId ?? (ids.length === 1 ? ids[0] : undefined);
184
+ return {
185
+ activeKeyId() {
186
+ if (active === undefined || !isSecretKeyId(active) || !keys[active]) {
187
+ return Promise.reject(new errors_js_1.SecretsKeyError("staticKeyring needs an active key version that is one of its keys."));
188
+ }
189
+ return Promise.resolve(active);
190
+ },
191
+ key(id) {
192
+ const key = isSecretKeyId(id) ? keys[id] : undefined;
193
+ if (!key) {
194
+ return Promise.resolve(null);
195
+ }
196
+ if (key.length !== exports.SECRETS_KEY_BYTES) {
197
+ return Promise.reject(new errors_js_1.SecretsKeyError(`Key version ${id} must be exactly ${exports.SECRETS_KEY_BYTES} bytes; received ${key.length}.`));
198
+ }
199
+ return Promise.resolve(new Uint8Array(key));
200
+ },
201
+ };
202
+ }