@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.
Files changed (107) 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/mail/postal.d.ts.map +1 -1
  15. package/esm/src/mail/postal.js +2 -1
  16. package/esm/src/next/secrets/mod.d.ts +108 -0
  17. package/esm/src/next/secrets/mod.d.ts.map +1 -0
  18. package/esm/src/next/secrets/mod.js +176 -0
  19. package/esm/src/secrets/encoding.d.ts +32 -0
  20. package/esm/src/secrets/encoding.d.ts.map +1 -0
  21. package/esm/src/secrets/encoding.js +87 -0
  22. package/esm/src/secrets/errors.d.ts +45 -0
  23. package/esm/src/secrets/errors.d.ts.map +1 -0
  24. package/esm/src/secrets/errors.js +39 -0
  25. package/esm/src/secrets/fingerprint.d.ts +43 -0
  26. package/esm/src/secrets/fingerprint.d.ts.map +1 -0
  27. package/esm/src/secrets/fingerprint.js +87 -0
  28. package/esm/src/secrets/frame.d.ts +34 -0
  29. package/esm/src/secrets/frame.d.ts.map +1 -0
  30. package/esm/src/secrets/frame.js +86 -0
  31. package/esm/src/secrets/keyring.d.ts +62 -0
  32. package/esm/src/secrets/keyring.d.ts.map +1 -0
  33. package/esm/src/secrets/keyring.js +160 -0
  34. package/esm/src/secrets/legacy.d.ts +60 -0
  35. package/esm/src/secrets/legacy.d.ts.map +1 -0
  36. package/esm/src/secrets/legacy.js +147 -0
  37. package/esm/src/secrets/maintenance.d.ts +173 -0
  38. package/esm/src/secrets/maintenance.d.ts.map +1 -0
  39. package/esm/src/secrets/maintenance.js +315 -0
  40. package/esm/src/secrets/mod.d.ts +6 -0
  41. package/esm/src/secrets/mod.d.ts.map +1 -0
  42. package/esm/src/secrets/mod.js +5 -0
  43. package/esm/src/secrets/secrets.d.ts +192 -0
  44. package/esm/src/secrets/secrets.d.ts.map +1 -0
  45. package/esm/src/secrets/secrets.js +528 -0
  46. package/package.json +50 -2
  47. package/script/src/cli/externalSkills.d.ts.map +1 -1
  48. package/script/src/cli/externalSkills.js +25 -20
  49. package/script/src/cli/mod.d.ts +72 -1
  50. package/script/src/cli/mod.d.ts.map +1 -1
  51. package/script/src/cli/mod.js +772 -33
  52. package/script/src/cli/projectSkills.d.ts +10 -3
  53. package/script/src/cli/projectSkills.d.ts.map +1 -1
  54. package/script/src/cli/projectSkills.js +173 -49
  55. package/script/src/cli/vercelBuildEnv.d.ts +28 -0
  56. package/script/src/cli/vercelBuildEnv.d.ts.map +1 -1
  57. package/script/src/cli/vercelBuildEnv.js +121 -30
  58. package/script/src/mail/postal.d.ts.map +1 -1
  59. package/script/src/mail/postal.js +2 -1
  60. package/script/src/next/secrets/mod.d.ts +108 -0
  61. package/script/src/next/secrets/mod.d.ts.map +1 -0
  62. package/script/src/next/secrets/mod.js +218 -0
  63. package/script/src/secrets/encoding.d.ts +32 -0
  64. package/script/src/secrets/encoding.d.ts.map +1 -0
  65. package/script/src/secrets/encoding.js +95 -0
  66. package/script/src/secrets/errors.d.ts +45 -0
  67. package/script/src/secrets/errors.d.ts.map +1 -0
  68. package/script/src/secrets/errors.js +45 -0
  69. package/script/src/secrets/fingerprint.d.ts +43 -0
  70. package/script/src/secrets/fingerprint.d.ts.map +1 -0
  71. package/script/src/secrets/fingerprint.js +92 -0
  72. package/script/src/secrets/frame.d.ts +34 -0
  73. package/script/src/secrets/frame.d.ts.map +1 -0
  74. package/script/src/secrets/frame.js +91 -0
  75. package/script/src/secrets/keyring.d.ts +62 -0
  76. package/script/src/secrets/keyring.d.ts.map +1 -0
  77. package/script/src/secrets/keyring.js +202 -0
  78. package/script/src/secrets/legacy.d.ts +60 -0
  79. package/script/src/secrets/legacy.d.ts.map +1 -0
  80. package/script/src/secrets/legacy.js +186 -0
  81. package/script/src/secrets/maintenance.d.ts +173 -0
  82. package/script/src/secrets/maintenance.d.ts.map +1 -0
  83. package/script/src/secrets/maintenance.js +323 -0
  84. package/script/src/secrets/mod.d.ts +6 -0
  85. package/script/src/secrets/mod.d.ts.map +1 -0
  86. package/script/src/secrets/mod.js +24 -0
  87. package/script/src/secrets/secrets.d.ts +192 -0
  88. package/script/src/secrets/secrets.d.ts.map +1 -0
  89. package/script/src/secrets/secrets.js +532 -0
  90. package/skills/loom/SKILL.md +74 -222
  91. package/skills/loom/references/dependency-upgrades.md +26 -0
  92. package/skills/loom/references/local-development.md +157 -0
  93. package/skills/loom/references/release-safety.md +118 -0
  94. package/skills/loom/references/release-trusted-sources.md +55 -0
  95. package/skills/loom/references/tools-and-skills.md +83 -0
  96. package/skills/loom-api-keys/SKILL.md +1 -1
  97. package/skills/loom-auth/SKILL.md +7 -60
  98. package/skills/loom-auth/references/secrets-and-rotation.md +61 -0
  99. package/skills/loom-db/SKILL.md +4 -79
  100. package/skills/loom-files/SKILL.md +4 -2
  101. package/skills/loom-files/references/provider-configuration.md +142 -0
  102. package/skills/loom-jobs/SKILL.md +9 -8
  103. package/skills/loom-lingui/SKILL.md +5 -3
  104. package/skills/loom-secrets/SKILL.md +252 -0
  105. package/skills/loom-torvalds-review/SKILL.md +9 -6
  106. package/skills/loom-torvalds-review/references/context-profiles.md +2 -1
  107. 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"}