@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,532 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.KEYED_FINGERPRINT_FORMAT = exports.SEALED_FORMAT = void 0;
4
+ exports.createSecrets = createSecrets;
5
+ const encoding_js_1 = require("./encoding.js");
6
+ const errors_js_1 = require("./errors.js");
7
+ const fingerprint_js_1 = require("./fingerprint.js");
8
+ const frame_js_1 = require("./frame.js");
9
+ const keyring_js_1 = require("./keyring.js");
10
+ /** Prefix and version of the sealed string format. */
11
+ exports.SEALED_FORMAT = "ls1";
12
+ /** Prefix and version of the keyed fingerprint format. */
13
+ exports.KEYED_FINGERPRINT_FORMAT = "lm1";
14
+ const DOMAIN = "loom-secrets";
15
+ const NONCE_BYTES = 12;
16
+ const TAG_BYTES = 16;
17
+ const MAC_BYTES = 32;
18
+ // 32 bytes in unpadded base64url.
19
+ const MAC_TEXT_LENGTH = 43;
20
+ const PURPOSE_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
21
+ const MAX_PURPOSE_LENGTH = 64;
22
+ const MAX_KEY_ID_DIGITS = 9;
23
+ // Characters, not bytes: room for a payload a little over 1.5 MiB.
24
+ const DEFAULT_MAX_LENGTH = 2_097_152;
25
+ const DEFAULT_SKEW_SECONDS = 60;
26
+ function parseSealed(sealed, maxLength) {
27
+ if (typeof sealed !== "string" || sealed.length > maxLength) {
28
+ return null;
29
+ }
30
+ const parts = sealed.split(".");
31
+ if (parts.length !== 4 || parts[0] !== exports.SEALED_FORMAT) {
32
+ return null;
33
+ }
34
+ const keyId = (0, keyring_js_1.parseSecretKeyId)(parts[1]);
35
+ const nonce = (0, encoding_js_1.fromBase64Url)(parts[2]);
36
+ const ciphertext = (0, encoding_js_1.fromBase64Url)(parts[3]);
37
+ if (keyId === null ||
38
+ nonce === null ||
39
+ nonce.length !== NONCE_BYTES ||
40
+ ciphertext === null ||
41
+ ciphertext.length < frame_js_1.FRAME_BLOCK_BYTES + TAG_BYTES ||
42
+ (ciphertext.length - TAG_BYTES) % frame_js_1.FRAME_BLOCK_BYTES !== 0) {
43
+ return null;
44
+ }
45
+ return { keyId, nonce, ciphertext };
46
+ }
47
+ function parseFingerprint(stored) {
48
+ // Bounded before splitting: the string may come from an untrusted row.
49
+ if (typeof stored !== "string" || stored.length > 64) {
50
+ return null;
51
+ }
52
+ const parts = stored.split(".");
53
+ if (parts.length !== 3 || parts[0] !== exports.KEYED_FINGERPRINT_FORMAT) {
54
+ return null;
55
+ }
56
+ const keyId = (0, keyring_js_1.parseSecretKeyId)(parts[1]);
57
+ const tag = parts[2].length === MAC_TEXT_LENGTH
58
+ ? (0, encoding_js_1.fromBase64Url)(parts[2])
59
+ : null;
60
+ if (keyId === null || tag === null || tag.length !== MAC_BYTES) {
61
+ return null;
62
+ }
63
+ return { keyId, tag };
64
+ }
65
+ /**
66
+ * Validates a binding and flattens it to sorted `key, value` pieces.
67
+ *
68
+ * Callers do this once, before any `await`, so that a binding object mutated
69
+ * while an operation is pending cannot change what is authenticated.
70
+ */
71
+ function bindingPieces(binding, unbound) {
72
+ const prototype = binding !== null && typeof binding === "object"
73
+ ? Object.getPrototypeOf(binding)
74
+ : undefined;
75
+ // A Map, Date or class instance has no own enumerable entries and would
76
+ // otherwise pass for an empty binding.
77
+ if (prototype !== Object.prototype && prototype !== null) {
78
+ throw new TypeError("A secret binding must be a plain object of strings.");
79
+ }
80
+ const keys = Object.keys(binding).sort();
81
+ if (keys.length === 0 && !unbound) {
82
+ throw new TypeError("A secret binding is required. Declare the purpose `unbound` to seal without one.");
83
+ }
84
+ return keys.flatMap((key) => {
85
+ if (key === "") {
86
+ throw new TypeError("A secret binding key must not be empty.");
87
+ }
88
+ return [
89
+ (0, encoding_js_1.assertWellFormed)(key, "A secret binding key"),
90
+ (0, encoding_js_1.assertWellFormed)(binding[key], `Secret binding "${key}"`),
91
+ ];
92
+ });
93
+ }
94
+ function positiveSeconds(value, what) {
95
+ if (!Number.isSafeInteger(value) || value <= 0) {
96
+ throw new RangeError(`${what} must be a positive whole number of seconds.`);
97
+ }
98
+ return value;
99
+ }
100
+ /**
101
+ * Creates the sealing and opening operations over a keyring.
102
+ *
103
+ * Each purpose encrypts with its own key, derived with HKDF from the keyring's
104
+ * key, so a value sealed for one purpose cannot be opened as another. The
105
+ * format version, key version, purpose and binding are all authenticated.
106
+ */
107
+ function createSecrets(options) {
108
+ const { keys } = options;
109
+ const now = options.now ?? Date.now;
110
+ const skewSeconds = options.skewSeconds ?? DEFAULT_SKEW_SECONDS;
111
+ if (!Number.isSafeInteger(skewSeconds) || skewSeconds < 0) {
112
+ throw new RangeError("skewSeconds must be a non-negative whole number.");
113
+ }
114
+ const subtle = globalThis.crypto.subtle;
115
+ const baseKeys = new Map();
116
+ // Copied and validated once, so later changes to the caller's array cannot
117
+ // loosen what was checked.
118
+ const expected = options.expectedKeys === undefined ? undefined : new Map((0, fingerprint_js_1.parseExpectedSecretKeys)(options.expectedKeys).map((entry) => [entry.id, entry]));
119
+ /** The raw key for a version, checked against the expected-key list. */
120
+ async function checkedKey(keyId) {
121
+ const entry = expected?.get(keyId);
122
+ if (expected && entry === undefined) {
123
+ // An undeclared variable may be a reused number or a stray paste.
124
+ if (await keys.key(keyId) === null) {
125
+ return null;
126
+ }
127
+ throw new errors_js_1.SecretsKeyError(`Key version ${keyId} is configured but not in the expected key list.`);
128
+ }
129
+ if (entry?.state === "retired") {
130
+ return null;
131
+ }
132
+ const raw = await keys.key(keyId);
133
+ if (raw === null) {
134
+ return null;
135
+ }
136
+ // A custom keyring is trusted for where a key comes from, not for its
137
+ // shape: a short key would seal and open without complaint.
138
+ if (!(raw instanceof Uint8Array) || raw.length !== keyring_js_1.SECRETS_KEY_BYTES) {
139
+ throw new errors_js_1.SecretsKeyError(`Key version ${keyId} must be exactly ${keyring_js_1.SECRETS_KEY_BYTES} bytes.`);
140
+ }
141
+ if (entry && await (0, fingerprint_js_1.secretKeyFingerprint)(raw) !== entry.fingerprint) {
142
+ throw new errors_js_1.SecretsKeyMismatchError(`Key version ${keyId} does not match its recorded fingerprint.`);
143
+ }
144
+ return raw;
145
+ }
146
+ /** HKDF input for a key version, imported once and kept non-extractable. */
147
+ function baseKey(keyId) {
148
+ let pending = baseKeys.get(keyId);
149
+ if (!pending) {
150
+ pending = checkedKey(keyId).then((raw) => raw === null
151
+ ? null
152
+ : subtle.importKey("raw", new Uint8Array(raw), "HKDF", false, [
153
+ "deriveKey",
154
+ ]));
155
+ baseKeys.set(keyId, pending);
156
+ // A failed or absent key is looked up again next time.
157
+ pending.then((key) => key === null && baseKeys.delete(keyId), () => baseKeys.delete(keyId));
158
+ }
159
+ return pending;
160
+ }
161
+ async function activeKeyId() {
162
+ const keyId = await keys.activeKeyId();
163
+ if (!(0, keyring_js_1.isSecretKeyId)(keyId)) {
164
+ throw new errors_js_1.SecretsKeyError("The keyring's active key version is not a valid key version.");
165
+ }
166
+ // With a list, only the key recorded as active may encrypt, so a pointer
167
+ // left on, or moved to, a decrypt-only key is caught before it is used.
168
+ if (expected && expected.get(keyId)?.state !== "active") {
169
+ throw new errors_js_1.SecretsKeyError(`Key version ${keyId} is the active pointer but is not the key recorded as active.`);
170
+ }
171
+ return keyId;
172
+ }
173
+ function report(event) {
174
+ try {
175
+ // A logging hook must not turn a failed open into a different error, or
176
+ // into an unhandled rejection that can end the process.
177
+ Promise.resolve(options.onFailure?.(event)).catch(() => { });
178
+ }
179
+ catch {
180
+ // Ignored for the same reason.
181
+ }
182
+ }
183
+ const secrets = {
184
+ async assertReady() {
185
+ const active = await activeKeyId();
186
+ const ids = expected
187
+ ? [...expected].filter(([, entry]) => entry.state !== "retired")
188
+ .map(([id]) => id)
189
+ : [active];
190
+ const checked = [];
191
+ for (const id of ids) {
192
+ const raw = await checkedKey(id);
193
+ if (raw === null) {
194
+ throw new errors_js_1.SecretsKeyError(`Key version ${id} is not configured.`);
195
+ }
196
+ checked.push({
197
+ id,
198
+ // Already compared with the recorded value when there is one.
199
+ fingerprint: expected?.get(id)?.fingerprint ??
200
+ await (0, fingerprint_js_1.secretKeyFingerprint)(raw),
201
+ });
202
+ }
203
+ return {
204
+ verified: expected !== undefined,
205
+ activeKeyId: active,
206
+ keys: checked,
207
+ };
208
+ },
209
+ purpose(name, purposeOptions = {}) {
210
+ if (typeof name !== "string" ||
211
+ name.length > MAX_PURPOSE_LENGTH ||
212
+ !PURPOSE_PATTERN.test(name)) {
213
+ throw new TypeError("A secret purpose is lowercase letters and digits separated by dots or dashes, at most 64 characters.");
214
+ }
215
+ const unbound = purposeOptions.unbound === true;
216
+ const purposeTtl = purposeOptions.ttlSeconds === undefined
217
+ ? undefined
218
+ : positiveSeconds(purposeOptions.ttlSeconds, "A purpose ttlSeconds");
219
+ const maxLength = purposeOptions.maxLength ?? DEFAULT_MAX_LENGTH;
220
+ if (!Number.isSafeInteger(maxLength) || maxLength <= 0) {
221
+ throw new RangeError("A purpose maxLength must be a positive integer.");
222
+ }
223
+ const cipherKeys = new Map();
224
+ /** This purpose's AES-256-GCM key under one key version. */
225
+ function cipherKey(keyId) {
226
+ let pending = cipherKeys.get(keyId);
227
+ if (!pending) {
228
+ pending = baseKey(keyId).then((base) => base === null ? null : subtle.deriveKey({
229
+ name: "HKDF",
230
+ hash: "SHA-256",
231
+ salt: new Uint8Array(0),
232
+ info: (0, encoding_js_1.pae)([DOMAIN, exports.SEALED_FORMAT, "key", name]),
233
+ }, base, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]));
234
+ cipherKeys.set(keyId, pending);
235
+ pending.then((key) => key === null && cipherKeys.delete(keyId), () => cipherKeys.delete(keyId));
236
+ }
237
+ return pending;
238
+ }
239
+ const macKeys = new Map();
240
+ /** This purpose's HMAC-SHA-256 key under one key version. */
241
+ function macKey(keyId) {
242
+ let pending = macKeys.get(keyId);
243
+ if (!pending) {
244
+ pending = baseKey(keyId).then((base) => base === null ? null : subtle.deriveKey({
245
+ name: "HKDF",
246
+ hash: "SHA-256",
247
+ salt: new Uint8Array(0),
248
+ // A different label from the encryption key, so the two keys
249
+ // are independent although they share a source.
250
+ info: (0, encoding_js_1.pae)([DOMAIN, exports.SEALED_FORMAT, "mac", name]),
251
+ }, base, { name: "HMAC", hash: "SHA-256", length: MAC_BYTES * 8 }, false, ["sign", "verify"]));
252
+ macKeys.set(keyId, pending);
253
+ pending.then((key) => key === null && macKeys.delete(keyId), () => macKeys.delete(keyId));
254
+ }
255
+ return pending;
256
+ }
257
+ function macInput(text, binding) {
258
+ return (0, encoding_js_1.pae)([
259
+ DOMAIN,
260
+ exports.SEALED_FORMAT,
261
+ "mac-input",
262
+ name,
263
+ (0, encoding_js_1.assertWellFormed)(text, "Fingerprint input"),
264
+ ...bindingPieces(binding, unbound),
265
+ ]);
266
+ }
267
+ function associatedData(keyId, pieces) {
268
+ return (0, encoding_js_1.pae)([
269
+ DOMAIN,
270
+ exports.SEALED_FORMAT,
271
+ "aad",
272
+ String(keyId),
273
+ name,
274
+ ...pieces,
275
+ ]);
276
+ }
277
+ async function encryptFrame(frame, pieces) {
278
+ const keyId = await activeKeyId();
279
+ const key = await cipherKey(keyId);
280
+ if (key === null) {
281
+ throw new errors_js_1.SecretsKeyError(`Active key version ${keyId} is not configured.`);
282
+ }
283
+ const nonce = globalThis.crypto.getRandomValues(new Uint8Array(NONCE_BYTES));
284
+ const ciphertext = await subtle.encrypt({
285
+ name: "AES-GCM",
286
+ iv: nonce,
287
+ additionalData: associatedData(keyId, pieces),
288
+ tagLength: TAG_BYTES * 8,
289
+ }, key, frame);
290
+ const sealed = `${exports.SEALED_FORMAT}.${keyId}.${(0, encoding_js_1.toBase64Url)(nonce)}.${(0, encoding_js_1.toBase64Url)(new Uint8Array(ciphertext))}`;
291
+ // Measured as if the key version had the most digits it can have, so
292
+ // that a value sealed today can still be resealed under any later key.
293
+ const worstCase = sealed.length - String(keyId).length +
294
+ MAX_KEY_ID_DIGITS;
295
+ if (worstCase > maxLength) {
296
+ throw new RangeError(`The sealed value would exceed this purpose's maxLength of ${maxLength}.`);
297
+ }
298
+ return sealed;
299
+ }
300
+ function expiryFor(sealOptions) {
301
+ const requested = sealOptions?.ttlSeconds === undefined
302
+ ? undefined
303
+ : positiveSeconds(sealOptions.ttlSeconds, "ttlSeconds");
304
+ if (requested !== undefined && purposeTtl !== undefined &&
305
+ requested > purposeTtl) {
306
+ throw new RangeError("ttlSeconds may shorten the purpose lifetime, not extend it.");
307
+ }
308
+ const ttl = requested ?? purposeTtl;
309
+ if (ttl === undefined) {
310
+ return undefined;
311
+ }
312
+ // Rounded up so a value never lives less than the lifetime asked for.
313
+ const expiresAt = Math.ceil(now() / 1000) + ttl;
314
+ if (!Number.isSafeInteger(expiresAt)) {
315
+ throw new RangeError("The clock did not return a usable time.");
316
+ }
317
+ return expiresAt;
318
+ }
319
+ async function sealPayload(kind, payload, binding, sealOptions) {
320
+ // Everything taken from the caller is read here, before the first
321
+ // await, so later mutation of their objects cannot change the result.
322
+ const pieces = bindingPieces(binding, unbound);
323
+ const frame = (0, frame_js_1.encodeFrame)({
324
+ kind,
325
+ payload: payload(),
326
+ expiresAt: expiryFor(sealOptions),
327
+ });
328
+ return await encryptFrame(frame, pieces);
329
+ }
330
+ /** Decrypts and checks a sealed string, returning the raw and parsed frame. */
331
+ async function openFrame(sealed, binding) {
332
+ // An invalid binding is a programming error, not an unreadable value.
333
+ const pieces = bindingPieces(binding, unbound);
334
+ const parsed = parseSealed(sealed, maxLength);
335
+ const fail = (reason) => {
336
+ report({ purpose: name, keyId: parsed?.keyId ?? null, reason });
337
+ throw new errors_js_1.SecretUnreadableError(reason);
338
+ };
339
+ if (parsed === null) {
340
+ return fail("malformed");
341
+ }
342
+ let key;
343
+ try {
344
+ key = await cipherKey(parsed.keyId);
345
+ }
346
+ catch (error) {
347
+ return fail(error instanceof errors_js_1.SecretsKeyMismatchError
348
+ ? "key-mismatch"
349
+ : "key-unavailable");
350
+ }
351
+ if (key === null) {
352
+ return fail("unknown-key");
353
+ }
354
+ let raw;
355
+ try {
356
+ raw = new Uint8Array(await subtle.decrypt({
357
+ name: "AES-GCM",
358
+ iv: parsed.nonce,
359
+ additionalData: associatedData(parsed.keyId, pieces),
360
+ tagLength: TAG_BYTES * 8,
361
+ }, key, parsed.ciphertext));
362
+ }
363
+ catch {
364
+ return fail("authentication");
365
+ }
366
+ const frame = (0, frame_js_1.decodeFrame)(raw);
367
+ if (frame === null) {
368
+ return fail("malformed");
369
+ }
370
+ if (frame.expiresAt === undefined) {
371
+ if (purposeTtl !== undefined) {
372
+ return fail("malformed");
373
+ }
374
+ }
375
+ else {
376
+ const nowSeconds = Math.floor(now() / 1000);
377
+ // Written so that a clock returning NaN fails closed.
378
+ if (!(nowSeconds < frame.expiresAt)) {
379
+ return fail("expired");
380
+ }
381
+ // Nothing this purpose seals can expire later than this, so a later
382
+ // expiry means a wrong clock when sealing, or a different purpose
383
+ // configuration. Either way it must not be honoured.
384
+ if (purposeTtl !== undefined &&
385
+ frame.expiresAt > nowSeconds + purposeTtl + skewSeconds) {
386
+ return fail("malformed");
387
+ }
388
+ }
389
+ return { parsed, raw, frame, pieces };
390
+ }
391
+ async function openPayload(kind, sealed, binding) {
392
+ const { parsed, frame } = await openFrame(sealed, binding);
393
+ if (frame.kind !== kind) {
394
+ report({ purpose: name, keyId: parsed.keyId, reason: "malformed" });
395
+ throw new errors_js_1.SecretUnreadableError("malformed");
396
+ }
397
+ return { parsed, payload: frame.payload };
398
+ }
399
+ function decodeText(parsed, payload) {
400
+ try {
401
+ return (0, encoding_js_1.decodeUtf8)(payload);
402
+ }
403
+ catch {
404
+ report({ purpose: name, keyId: parsed.keyId, reason: "malformed" });
405
+ throw new errors_js_1.SecretUnreadableError("malformed");
406
+ }
407
+ }
408
+ /** `null` for an unreadable value; programming errors still throw. */
409
+ async function orNull(opening) {
410
+ try {
411
+ return await opening;
412
+ }
413
+ catch (error) {
414
+ if (error instanceof errors_js_1.SecretUnreadableError) {
415
+ return null;
416
+ }
417
+ throw error;
418
+ }
419
+ }
420
+ const purpose = {
421
+ name,
422
+ seal(value, binding, sealOptions) {
423
+ return sealPayload("text", () => (0, encoding_js_1.encodeUtf8)(value, "A sealed value"), binding, sealOptions);
424
+ },
425
+ sealJson(value, binding, sealOptions) {
426
+ return sealPayload("json", () => {
427
+ const json = JSON.stringify(value);
428
+ if (json === undefined) {
429
+ throw new TypeError("The value cannot be represented as JSON.");
430
+ }
431
+ return (0, encoding_js_1.encodeUtf8)(json, "A sealed JSON value");
432
+ }, binding, sealOptions);
433
+ },
434
+ sealBytes(value, binding, sealOptions) {
435
+ return sealPayload("bytes", () => {
436
+ // `new Uint8Array(x)` accepts numbers, strings and other typed
437
+ // arrays and would silently seal something else.
438
+ if (!(value instanceof Uint8Array)) {
439
+ throw new TypeError("sealBytes needs a Uint8Array.");
440
+ }
441
+ return value;
442
+ }, binding, sealOptions);
443
+ },
444
+ async open(sealed, binding) {
445
+ const { parsed, payload } = await openPayload("text", sealed, binding);
446
+ return decodeText(parsed, payload);
447
+ },
448
+ async openJson(sealed, binding) {
449
+ const { parsed, payload } = await openPayload("json", sealed, binding);
450
+ const text = decodeText(parsed, payload);
451
+ try {
452
+ return JSON.parse(text);
453
+ }
454
+ catch {
455
+ // A SyntaxError message quotes its input, which is the plaintext.
456
+ report({ purpose: name, keyId: parsed.keyId, reason: "malformed" });
457
+ throw new errors_js_1.SecretUnreadableError("malformed");
458
+ }
459
+ },
460
+ async openBytes(sealed, binding) {
461
+ return (await openPayload("bytes", sealed, binding)).payload;
462
+ },
463
+ tryOpen(sealed, binding) {
464
+ return orNull(purpose.open(sealed, binding));
465
+ },
466
+ tryOpenJson(sealed, binding) {
467
+ return orNull(purpose.openJson(sealed, binding).then((value) => ({ value })));
468
+ },
469
+ tryOpenBytes(sealed, binding) {
470
+ return orNull(purpose.openBytes(sealed, binding));
471
+ },
472
+ keyId(sealed) {
473
+ return parseSealed(sealed, maxLength)?.keyId ?? null;
474
+ },
475
+ async needsReseal(sealed) {
476
+ const keyId = parseSealed(sealed, maxLength)?.keyId;
477
+ return keyId !== undefined && keyId !== await activeKeyId();
478
+ },
479
+ async reseal(sealed, binding) {
480
+ const { parsed, raw, pieces } = await openFrame(sealed, binding);
481
+ if (parsed.keyId === await activeKeyId()) {
482
+ return sealed;
483
+ }
484
+ // The decrypted frame is encrypted again as it is, so the payload
485
+ // kind and the original expiry are preserved rather than renewed.
486
+ return await encryptFrame(new Uint8Array(raw), pieces);
487
+ },
488
+ async mac(text, binding, macOptions) {
489
+ // Read from the caller before the first await, as in `seal`.
490
+ const input = macInput(text, binding);
491
+ const requested = macOptions?.keyId;
492
+ if (requested !== undefined && !(0, keyring_js_1.isSecretKeyId)(requested)) {
493
+ throw new TypeError("keyId must be a key version.");
494
+ }
495
+ const keyId = requested ?? await activeKeyId();
496
+ const key = await macKey(keyId);
497
+ if (key === null) {
498
+ throw new errors_js_1.SecretsKeyError(`Key version ${keyId} is not configured.`);
499
+ }
500
+ const tag = await subtle.sign("HMAC", key, input);
501
+ return `${exports.KEYED_FINGERPRINT_FORMAT}.${keyId}.${(0, encoding_js_1.toBase64Url)(new Uint8Array(tag))}`;
502
+ },
503
+ async macMatches(stored, text, binding) {
504
+ const input = macInput(text, binding);
505
+ const parsed = parseFingerprint(stored);
506
+ if (parsed === null) {
507
+ report({ purpose: name, keyId: null, reason: "malformed" });
508
+ return false;
509
+ }
510
+ const key = await macKey(parsed.keyId);
511
+ if (key === null) {
512
+ report({
513
+ purpose: name,
514
+ keyId: parsed.keyId,
515
+ reason: "unknown-key",
516
+ });
517
+ return false;
518
+ }
519
+ // `verify` compares the tags without an early exit.
520
+ return await subtle.verify("HMAC", key, parsed.tag, input);
521
+ },
522
+ async macNeedsRefresh(stored) {
523
+ const keyId = parseFingerprint(stored)?.keyId;
524
+ return keyId !== undefined && keyId !== await activeKeyId();
525
+ },
526
+ assertReady: () => secrets.assertReady(),
527
+ };
528
+ return purpose;
529
+ },
530
+ };
531
+ return secrets;
532
+ }