@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,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
+ }
@@ -0,0 +1,60 @@
1
+ import "../../_dnt.polyfills.js";
2
+ import { type SecretFailureReason } from "./errors.js";
3
+ export { type SecretFailureReason, SecretsKeyError, SecretUnreadableError, } from "./errors.js";
4
+ type LegacyEnv = Record<string, string | undefined>;
5
+ /**
6
+ * A value in the format porty3 wrote before Loom's sealed strings: AES-GCM
7
+ * ciphertext and IV as standard base64, with no associated data.
8
+ */
9
+ export interface LegacySecretParts {
10
+ /** Base64 ciphertext with the 16-byte authentication tag appended. */
11
+ value: string;
12
+ /** Base64 initialisation vector. Existing rows use 16 bytes. */
13
+ iv: string;
14
+ /** Which `CRYPTO_KEY_<n>` encrypted it. Rows that predate the field are 0. */
15
+ keyVersion?: number;
16
+ }
17
+ /** The reasons a legacy value can fail for; it has no expiry or fingerprint. */
18
+ export type LegacyFailureReason = Extract<SecretFailureReason, "malformed" | "unknown-key" | "key-unavailable" | "authentication">;
19
+ /** Reported to `onFailure` for every legacy value that could not be opened. */
20
+ export interface LegacyFailureEvent {
21
+ /** `null` when the parts themselves were malformed. */
22
+ keyVersion: number | null;
23
+ reason: LegacyFailureReason;
24
+ }
25
+ /** Options for {@link createLegacyPartsReader}. */
26
+ export interface LegacyPartsReaderOptions {
27
+ /** Defaults to `process.env`, read when a key is first needed. */
28
+ env?: LegacyEnv;
29
+ /** Variable name prefix; the key version is appended. */
30
+ keyPrefix?: string;
31
+ /** Receives no plaintext or ciphertext. Whatever it throws is ignored. */
32
+ onFailure?: (event: LegacyFailureEvent) => unknown;
33
+ }
34
+ /** Read-only access to values in the legacy format. */
35
+ export interface LegacyPartsReader {
36
+ /** Throws {@link SecretUnreadableError} on any failure. */
37
+ open(parts: LegacySecretParts): Promise<string>;
38
+ /** Like `open`, but `null` when the value cannot be read. */
39
+ tryOpen(parts: LegacySecretParts): Promise<string | null>;
40
+ /**
41
+ * Checks that a key version is configured and usable, without opening
42
+ * anything. Throws {@link SecretsKeyError} naming the variable and the
43
+ * problem. `open` reports the same problem only as `key-unavailable`, so
44
+ * this is how an operator finds out why. Defaults to version 0.
45
+ */
46
+ assertKey(keyVersion?: number): Promise<void>;
47
+ }
48
+ /**
49
+ * Opens values in porty3's original format, so that rows written before the
50
+ * move to sealed strings stay readable for as long as they exist.
51
+ *
52
+ * There is deliberately no way to write this format here. It has no key
53
+ * version of its own, no associated data and therefore no binding: a value
54
+ * opens wherever it is placed. New data belongs in a sealed string.
55
+ *
56
+ * Each key is read by name and decoded the first time it is needed, so an
57
+ * unusable `CRYPTO_KEY_1` does not stop version 0 from working.
58
+ */
59
+ export declare function createLegacyPartsReader(options?: LegacyPartsReaderOptions): LegacyPartsReader;
60
+ //# sourceMappingURL=legacy.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"legacy.d.ts","sourceRoot":"","sources":["../../../src/src/secrets/legacy.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AAEjC,OAAO,EACL,KAAK,mBAAmB,EAGzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,KAAK,mBAAmB,EACxB,eAAe,EACf,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAarB,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,GAAG,OAAO,CACvC,mBAAmB,EACnB,WAAW,GAAG,aAAa,GAAG,iBAAiB,GAAG,gBAAgB,CACnE,CAAC;AAEF,+EAA+E;AAC/E,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CACpD;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,6DAA6D;IAC7D,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1D;;;;;OAKG;IACH,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAsCD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,wBAA6B,GACrC,iBAAiB,CAkHnB"}
@@ -0,0 +1,186 @@
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.SecretUnreadableError = exports.SecretsKeyError = void 0;
37
+ exports.createLegacyPartsReader = createLegacyPartsReader;
38
+ require("../../_dnt.polyfills.js");
39
+ const dntShim = __importStar(require("../../_dnt.shims.js"));
40
+ const errors_js_1 = require("./errors.js");
41
+ const keyring_js_1 = require("./keyring.js");
42
+ var errors_js_2 = require("./errors.js");
43
+ Object.defineProperty(exports, "SecretsKeyError", { enumerable: true, get: function () { return errors_js_2.SecretsKeyError; } });
44
+ Object.defineProperty(exports, "SecretUnreadableError", { enumerable: true, get: function () { return errors_js_2.SecretUnreadableError; } });
45
+ const DEFAULT_LEGACY_KEY_ENV_PREFIX = "CRYPTO_KEY_";
46
+ const LEGACY_KEY_BYTES = new Set([16, 24, 32]);
47
+ const CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
48
+ const TAG_BYTES = 16;
49
+ // Decoded exactly as the code that wrote these values has always read them:
50
+ // a leading byte-order mark is dropped and an invalid byte becomes U+FFFD.
51
+ // Strictness would add nothing, because the bytes are already authenticated,
52
+ // and it could reject a row that reads today.
53
+ const decoder = new TextDecoder();
54
+ function fromBase64(text) {
55
+ if (typeof text !== "string") {
56
+ return null;
57
+ }
58
+ let binary;
59
+ try {
60
+ // `atob` is as forgiving as the reader these rows were written for.
61
+ binary = atob(text);
62
+ }
63
+ catch {
64
+ return null;
65
+ }
66
+ const bytes = new Uint8Array(binary.length);
67
+ for (let index = 0; index < binary.length; index += 1) {
68
+ bytes[index] = binary.charCodeAt(index);
69
+ }
70
+ return bytes;
71
+ }
72
+ function decodeLegacyKey(value, name) {
73
+ const trimmed = (0, keyring_js_1.trimKeyValue)(value, name);
74
+ const bytes = CANONICAL_BASE64.test(trimmed) ? fromBase64(trimmed) : null;
75
+ if (bytes === null) {
76
+ throw new errors_js_1.SecretsKeyError(`${name} must be canonical base64.`);
77
+ }
78
+ if (!LEGACY_KEY_BYTES.has(bytes.length)) {
79
+ throw new errors_js_1.SecretsKeyError(`${name} must decode to a 16-, 24- or 32-byte AES key; received ${bytes.length} bytes.`);
80
+ }
81
+ return bytes;
82
+ }
83
+ function processEnv() {
84
+ return dntShim.dntGlobalThis.process?.env ?? {};
85
+ }
86
+ /**
87
+ * Opens values in porty3's original format, so that rows written before the
88
+ * move to sealed strings stay readable for as long as they exist.
89
+ *
90
+ * There is deliberately no way to write this format here. It has no key
91
+ * version of its own, no associated data and therefore no binding: a value
92
+ * opens wherever it is placed. New data belongs in a sealed string.
93
+ *
94
+ * Each key is read by name and decoded the first time it is needed, so an
95
+ * unusable `CRYPTO_KEY_1` does not stop version 0 from working.
96
+ */
97
+ function createLegacyPartsReader(options = {}) {
98
+ const keyPrefix = options.keyPrefix ?? DEFAULT_LEGACY_KEY_ENV_PREFIX;
99
+ const subtle = globalThis.crypto.subtle;
100
+ const keys = new Map();
101
+ function key(version) {
102
+ let pending = keys.get(version);
103
+ if (!pending) {
104
+ pending = (async () => {
105
+ const name = `${keyPrefix}${version}`;
106
+ let raw;
107
+ try {
108
+ raw = (options.env ?? processEnv())[name];
109
+ }
110
+ catch {
111
+ throw new errors_js_1.SecretsKeyError(`${name} could not be read from the environment.`);
112
+ }
113
+ return raw === undefined ? null : await subtle.importKey("raw", decodeLegacyKey(raw, name), "AES-GCM", false, ["decrypt"]);
114
+ })();
115
+ keys.set(version, pending);
116
+ pending.then((imported) => imported === null && keys.delete(version), () => keys.delete(version));
117
+ }
118
+ return pending;
119
+ }
120
+ function fail(keyVersion, reason) {
121
+ try {
122
+ Promise.resolve(options.onFailure?.({ keyVersion, reason }))
123
+ .catch(() => { });
124
+ }
125
+ catch {
126
+ // A logging hook must not change the outcome.
127
+ }
128
+ throw new errors_js_1.SecretUnreadableError(reason);
129
+ }
130
+ const reader = {
131
+ async open(parts) {
132
+ // Copied out before the first await, so the caller's object cannot
133
+ // change underneath the read.
134
+ const keyVersion = parts?.keyVersion ?? 0;
135
+ const ciphertext = fromBase64(parts?.value);
136
+ const iv = fromBase64(parts?.iv);
137
+ if (!Number.isSafeInteger(keyVersion) || keyVersion < 0 ||
138
+ ciphertext === null || ciphertext.length < TAG_BYTES ||
139
+ iv === null || iv.length === 0) {
140
+ return fail(null, "malformed");
141
+ }
142
+ let imported;
143
+ try {
144
+ imported = await key(keyVersion);
145
+ }
146
+ catch {
147
+ return fail(keyVersion, "key-unavailable");
148
+ }
149
+ if (imported === null) {
150
+ return fail(keyVersion, "unknown-key");
151
+ }
152
+ let plaintext;
153
+ try {
154
+ plaintext = await subtle.decrypt({ name: "AES-GCM", iv }, imported, ciphertext);
155
+ }
156
+ catch (error) {
157
+ // Web Crypto reports a failed tag as OperationError. Anything else is
158
+ // a parameter the runtime will not take, such as an IV length.
159
+ return fail(keyVersion, error?.name === "OperationError"
160
+ ? "authentication"
161
+ : "malformed");
162
+ }
163
+ return decoder.decode(plaintext);
164
+ },
165
+ async tryOpen(parts) {
166
+ try {
167
+ return await reader.open(parts);
168
+ }
169
+ catch (error) {
170
+ if (error instanceof errors_js_1.SecretUnreadableError) {
171
+ return null;
172
+ }
173
+ throw error;
174
+ }
175
+ },
176
+ async assertKey(keyVersion = 0) {
177
+ if (!Number.isSafeInteger(keyVersion) || keyVersion < 0) {
178
+ throw new TypeError("A legacy key version is a non-negative integer.");
179
+ }
180
+ if (await key(keyVersion) === null) {
181
+ throw new errors_js_1.SecretsKeyError(`${keyPrefix}${keyVersion} is not configured.`);
182
+ }
183
+ },
184
+ };
185
+ return reader;
186
+ }
@@ -0,0 +1,173 @@
1
+ import "../../_dnt.polyfills.js";
2
+ import type { SecretFailureReason } from "./errors.js";
3
+ import type { SecretBinding, SecretPurpose } from "./secrets.js";
4
+ /** One stored sealed string, as a location reads it. */
5
+ export interface SecretLocationRow {
6
+ /** Stable row identifier. Reported on failure; never a secret. */
7
+ id: string;
8
+ sealed: string;
9
+ /**
10
+ * The binding the app's own reader would supply for this row. Build it with
11
+ * the same function the reader uses: a second derivation can disagree with
12
+ * the first, and then a clean result here says nothing about the app.
13
+ */
14
+ binding: SecretBinding;
15
+ }
16
+ /**
17
+ * A place where an app stores sealed strings. Loom cannot find ciphertext by
18
+ * itself, so every column that holds it is declared, and what is not declared
19
+ * is not reported, verified or resealed.
20
+ */
21
+ export interface SecretLocation<Db> {
22
+ /** For reports, for example `temple_forums.api_key_encrypted`. */
23
+ name: string;
24
+ purpose: SecretPurpose;
25
+ /** What the rows hold. Defaults to `text`. */
26
+ kind?: "text" | "json" | "bytes" | undefined;
27
+ /**
28
+ * The next rows after `cursor` (`null` for the first page), at most `limit`
29
+ * of them, in any order that is stable between calls and in which every row
30
+ * comes after the previous page's last row. Rows that hold no sealed string
31
+ * are left out. Each row needs a non-empty string `id`.
32
+ */
33
+ read(db: Db, cursor: string | null, limit: number): Promise<SecretLocationRow[]>;
34
+ /**
35
+ * Replaces `expected` with `next` only if the row still holds `expected`,
36
+ * as one `UPDATE … WHERE` statement, and reports whether it did. It must
37
+ * never insert: a row deleted in the meantime stays deleted.
38
+ */
39
+ write(db: Db, id: string, expected: string, next: string): Promise<boolean>;
40
+ }
41
+ /**
42
+ * Why a row was not handled. `invalid-binding` means the location produced a
43
+ * binding that is not an object of strings, usually from a nullable column.
44
+ */
45
+ export type SecretRowFailureReason = SecretFailureReason | "invalid-binding";
46
+ /** A row that could not be handled, identified without revealing anything. */
47
+ export interface SecretLocationFailure {
48
+ id: string;
49
+ reason: SecretRowFailureReason;
50
+ }
51
+ /** How far an operation got in one location. */
52
+ export interface SecretLocationProgress {
53
+ name: string;
54
+ /** Rows looked at in this run. */
55
+ rows: number;
56
+ /** Whether the location was read to its end. */
57
+ done: boolean;
58
+ /** Where to continue when not `done`. */
59
+ cursor: string | null;
60
+ }
61
+ /** Options shared by the maintenance operations. */
62
+ export interface SecretMaintenanceOptions {
63
+ /** Rows read per page. Defaults to 100. */
64
+ batchSize?: number | undefined;
65
+ /**
66
+ * Stop after this many rows per location, for runtimes with a time limit.
67
+ * Pass the results back as `previous` to continue.
68
+ */
69
+ maxRows?: number | undefined;
70
+ /**
71
+ * Results of an earlier, unfinished run of the same operation. Locations
72
+ * that were `done` are skipped; the others continue from their cursor.
73
+ */
74
+ previous?: readonly SecretLocationProgress[] | undefined;
75
+ /** Failures listed per location; the count is always complete. Default 1000. */
76
+ maxFailures?: number | undefined;
77
+ }
78
+ interface FailureList {
79
+ /** The first `maxFailures` rows that failed. */
80
+ failures: SecretLocationFailure[];
81
+ /** How many rows failed, including any not listed. */
82
+ failureCount: number;
83
+ }
84
+ /** Counts per key version for one location. Nothing is decrypted. */
85
+ export interface SecretLocationReport extends SecretLocationProgress, FailureList {
86
+ /** Rows per key version, keyed by the version number. */
87
+ byKeyId: Record<string, number>;
88
+ }
89
+ /** Outcome of opening every row of one location. */
90
+ export interface SecretLocationVerification extends SecretLocationProgress, FailureList {
91
+ opened: number;
92
+ }
93
+ /** Outcome of resealing one location. */
94
+ export interface SecretLocationReseal extends SecretLocationProgress, FailureList {
95
+ /** Whether this was a rehearsal that wrote nothing. */
96
+ dryRun: boolean;
97
+ /** Already under the active key. These rows are not opened. */
98
+ current: number;
99
+ /** Moved to the active key, or would be in a dry run. */
100
+ resealed: number;
101
+ /**
102
+ * Changed or deleted by someone else between the read and the write, and
103
+ * left alone. They are still under their old key unless that write moved
104
+ * them: run again.
105
+ */
106
+ changed: number;
107
+ /** The first `maxFailures` of those rows. */
108
+ changedIds: string[];
109
+ }
110
+ /** Options for {@link resealSecretLocations}. */
111
+ export interface ResealSecretLocationsOptions extends SecretMaintenanceOptions {
112
+ /** Defaults to `true`: nothing is written unless this is `false`. */
113
+ dryRun?: boolean | undefined;
114
+ /**
115
+ * Write even though no expected-key list was applied, so nothing shows that
116
+ * the active key is the one the operator saved. For development databases.
117
+ */
118
+ allowUnverifiedKeys?: boolean | undefined;
119
+ }
120
+ /**
121
+ * A maintenance run stopped on something other than an unreadable row, such
122
+ * as a lost database connection. Rows already handled stay handled; running
123
+ * again is safe. The original error is `cause`.
124
+ */
125
+ export declare class SecretMaintenanceError extends Error {
126
+ /** The location being processed. */
127
+ readonly location: string;
128
+ /** The row being processed, when one was. */
129
+ readonly rowId: string | null;
130
+ /** Results for the locations finished before this one. */
131
+ readonly results: readonly SecretLocationProgress[];
132
+ constructor(location: string, rowId: string | null, results: readonly SecretLocationProgress[], cause: unknown);
133
+ }
134
+ /**
135
+ * Declares an app's secret locations, rejecting duplicate names so that a
136
+ * report line or a saved cursor always means one place.
137
+ */
138
+ export declare function defineSecretLocations<Db>(locations: readonly SecretLocation<Db>[]): readonly SecretLocation<Db>[];
139
+ /**
140
+ * Counts rows per key version by parsing each string. It decrypts nothing, so
141
+ * it needs no key and can run anywhere the database can be read. A clean
142
+ * report says where rows stand, not that they open: use
143
+ * {@link verifySecretLocations} for that.
144
+ */
145
+ export declare function reportSecretLocations<Db>(db: Db, locations: readonly SecretLocation<Db>[], options?: SecretMaintenanceOptions): Promise<SecretLocationReport[]>;
146
+ /**
147
+ * Opens every declared row with no fallback of any kind, and reports each row
148
+ * that does not open by id and reason. Run it inside the deployed app: that is
149
+ * the only place the keys exist. It never outputs a value.
150
+ *
151
+ * A value whose lifetime has passed is reported as `expired` on every run. It
152
+ * can never be resealed, so the app must delete such rows before the key they
153
+ * are under can be retired.
154
+ */
155
+ export declare function verifySecretLocations<Db>(db: Db, locations: readonly SecretLocation<Db>[], options?: SecretMaintenanceOptions): Promise<SecretLocationVerification[]>;
156
+ /**
157
+ * Moves rows that are under an older key to the active key.
158
+ *
159
+ * Before anything else it runs `assertReady()` for the keys each location's
160
+ * purpose will actually use. A real run also requires that an expected-key
161
+ * list was applied, so rows are never moved onto a key that has not been shown
162
+ * to match its recorded fingerprint: moving every row onto a mistyped
163
+ * write-only key, and later retiring the old one, would lose them all.
164
+ *
165
+ * For each row it reseals, opens the new string and compares it with the old
166
+ * plaintext, and only then swaps it in with the location's compare-and-swap. A
167
+ * row someone else changed in the meantime is counted and left alone. It is
168
+ * safe to run again, and to stop and continue by passing the results back as
169
+ * `previous`.
170
+ */
171
+ export declare function resealSecretLocations<Db>(db: Db, locations: readonly SecretLocation<Db>[], options?: ResealSecretLocationsOptions): Promise<SecretLocationReseal[]>;
172
+ export {};
173
+ //# sourceMappingURL=maintenance.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../../src/src/secrets/maintenance.ts"],"names":[],"mappings":"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"}