@gadicc/loom 1.35.3 → 1.37.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 +66 -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 +117 -1
  6. package/esm/src/cli/mod.d.ts.map +1 -1
  7. package/esm/src/cli/mod.js +1368 -44
  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 +117 -1
  48. package/script/src/cli/mod.d.ts.map +1 -1
  49. package/script/src/cli/mod.js +1372 -41
  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 +79 -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 +150 -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 +266 -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,147 @@
1
+ import "../../_dnt.polyfills.js";
2
+ import * as dntShim from "../../_dnt.shims.js";
3
+ import { SecretsKeyError, SecretUnreadableError, } from "./errors.js";
4
+ import { trimKeyValue } from "./keyring.js";
5
+ export { SecretsKeyError, SecretUnreadableError, } from "./errors.js";
6
+ const DEFAULT_LEGACY_KEY_ENV_PREFIX = "CRYPTO_KEY_";
7
+ const LEGACY_KEY_BYTES = new Set([16, 24, 32]);
8
+ const CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
9
+ const TAG_BYTES = 16;
10
+ // Decoded exactly as the code that wrote these values has always read them:
11
+ // a leading byte-order mark is dropped and an invalid byte becomes U+FFFD.
12
+ // Strictness would add nothing, because the bytes are already authenticated,
13
+ // and it could reject a row that reads today.
14
+ const decoder = new TextDecoder();
15
+ function fromBase64(text) {
16
+ if (typeof text !== "string") {
17
+ return null;
18
+ }
19
+ let binary;
20
+ try {
21
+ // `atob` is as forgiving as the reader these rows were written for.
22
+ binary = atob(text);
23
+ }
24
+ catch {
25
+ return null;
26
+ }
27
+ const bytes = new Uint8Array(binary.length);
28
+ for (let index = 0; index < binary.length; index += 1) {
29
+ bytes[index] = binary.charCodeAt(index);
30
+ }
31
+ return bytes;
32
+ }
33
+ function decodeLegacyKey(value, name) {
34
+ const trimmed = trimKeyValue(value, name);
35
+ const bytes = CANONICAL_BASE64.test(trimmed) ? fromBase64(trimmed) : null;
36
+ if (bytes === null) {
37
+ throw new SecretsKeyError(`${name} must be canonical base64.`);
38
+ }
39
+ if (!LEGACY_KEY_BYTES.has(bytes.length)) {
40
+ throw new SecretsKeyError(`${name} must decode to a 16-, 24- or 32-byte AES key; received ${bytes.length} bytes.`);
41
+ }
42
+ return bytes;
43
+ }
44
+ function processEnv() {
45
+ return dntShim.dntGlobalThis.process?.env ?? {};
46
+ }
47
+ /**
48
+ * Opens values in porty3's original format, so that rows written before the
49
+ * move to sealed strings stay readable for as long as they exist.
50
+ *
51
+ * There is deliberately no way to write this format here. It has no key
52
+ * version of its own, no associated data and therefore no binding: a value
53
+ * opens wherever it is placed. New data belongs in a sealed string.
54
+ *
55
+ * Each key is read by name and decoded the first time it is needed, so an
56
+ * unusable `CRYPTO_KEY_1` does not stop version 0 from working.
57
+ */
58
+ export function createLegacyPartsReader(options = {}) {
59
+ const keyPrefix = options.keyPrefix ?? DEFAULT_LEGACY_KEY_ENV_PREFIX;
60
+ const subtle = globalThis.crypto.subtle;
61
+ const keys = new Map();
62
+ function key(version) {
63
+ let pending = keys.get(version);
64
+ if (!pending) {
65
+ pending = (async () => {
66
+ const name = `${keyPrefix}${version}`;
67
+ let raw;
68
+ try {
69
+ raw = (options.env ?? processEnv())[name];
70
+ }
71
+ catch {
72
+ throw new SecretsKeyError(`${name} could not be read from the environment.`);
73
+ }
74
+ return raw === undefined ? null : await subtle.importKey("raw", decodeLegacyKey(raw, name), "AES-GCM", false, ["decrypt"]);
75
+ })();
76
+ keys.set(version, pending);
77
+ pending.then((imported) => imported === null && keys.delete(version), () => keys.delete(version));
78
+ }
79
+ return pending;
80
+ }
81
+ function fail(keyVersion, reason) {
82
+ try {
83
+ Promise.resolve(options.onFailure?.({ keyVersion, reason }))
84
+ .catch(() => { });
85
+ }
86
+ catch {
87
+ // A logging hook must not change the outcome.
88
+ }
89
+ throw new SecretUnreadableError(reason);
90
+ }
91
+ const reader = {
92
+ async open(parts) {
93
+ // Copied out before the first await, so the caller's object cannot
94
+ // change underneath the read.
95
+ const keyVersion = parts?.keyVersion ?? 0;
96
+ const ciphertext = fromBase64(parts?.value);
97
+ const iv = fromBase64(parts?.iv);
98
+ if (!Number.isSafeInteger(keyVersion) || keyVersion < 0 ||
99
+ ciphertext === null || ciphertext.length < TAG_BYTES ||
100
+ iv === null || iv.length === 0) {
101
+ return fail(null, "malformed");
102
+ }
103
+ let imported;
104
+ try {
105
+ imported = await key(keyVersion);
106
+ }
107
+ catch {
108
+ return fail(keyVersion, "key-unavailable");
109
+ }
110
+ if (imported === null) {
111
+ return fail(keyVersion, "unknown-key");
112
+ }
113
+ let plaintext;
114
+ try {
115
+ plaintext = await subtle.decrypt({ name: "AES-GCM", iv }, imported, ciphertext);
116
+ }
117
+ catch (error) {
118
+ // Web Crypto reports a failed tag as OperationError. Anything else is
119
+ // a parameter the runtime will not take, such as an IV length.
120
+ return fail(keyVersion, error?.name === "OperationError"
121
+ ? "authentication"
122
+ : "malformed");
123
+ }
124
+ return decoder.decode(plaintext);
125
+ },
126
+ async tryOpen(parts) {
127
+ try {
128
+ return await reader.open(parts);
129
+ }
130
+ catch (error) {
131
+ if (error instanceof SecretUnreadableError) {
132
+ return null;
133
+ }
134
+ throw error;
135
+ }
136
+ },
137
+ async assertKey(keyVersion = 0) {
138
+ if (!Number.isSafeInteger(keyVersion) || keyVersion < 0) {
139
+ throw new TypeError("A legacy key version is a non-negative integer.");
140
+ }
141
+ if (await key(keyVersion) === null) {
142
+ throw new SecretsKeyError(`${keyPrefix}${keyVersion} is not configured.`);
143
+ }
144
+ },
145
+ };
146
+ return reader;
147
+ }
@@ -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":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEjE,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,EAAE,aAAa,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,EAAE;IAChC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,CAAC;IACvB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IAC7C;;;;;OAKG;IACH,IAAI,CACF,EAAE,EAAE,EAAE,EACN,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAChC;;;;OAIG;IACH,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7E;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAE7E,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,sBAAsB,CAAC;CAChC;AAED,gDAAgD;AAChD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,IAAI,EAAE,OAAO,CAAC;IACd,yCAAyC;IACzC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,oDAAoD;AACpD,MAAM,WAAW,wBAAwB;IACvC,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,sBAAsB,EAAE,GAAG,SAAS,CAAC;IACzD,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,UAAU,WAAW;IACnB,gDAAgD;IAChD,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qEAAqE;AACrE,MAAM,WAAW,oBACf,SAAQ,sBAAsB,EAAE,WAAW;IAC3C,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,oDAAoD;AACpD,MAAM,WAAW,0BACf,SAAQ,sBAAsB,EAAE,WAAW;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yCAAyC;AACzC,MAAM,WAAW,oBACf,SAAQ,sBAAsB,EAAE,WAAW;IAC3C,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAC;IAChB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,iDAAiD;AACjD,MAAM,WAAW,4BAA6B,SAAQ,wBAAwB;IAC5E,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC3C;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAC;gBAGlD,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,KAAK,EAAE,OAAO;CAcjB;AAMD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EACtC,SAAS,EAAE,SAAS,cAAc,CAAC,EAAE,CAAC,EAAE,GACvC,SAAS,cAAc,CAAC,EAAE,CAAC,EAAE,CAmB/B;AAkKD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EACtC,EAAE,EAAE,EAAE,EACN,SAAS,EAAE,SAAS,cAAc,CAAC,EAAE,CAAC,EAAE,EACxC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAsBjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EACtC,EAAE,EAAE,EAAE,EACN,SAAS,EAAE,SAAS,cAAc,CAAC,EAAE,CAAC,EAAE,EACxC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAqBvC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CAAC,EAAE,EAC5C,EAAE,EAAE,EAAE,EACN,SAAS,EAAE,SAAS,cAAc,CAAC,EAAE,CAAC,EAAE,EACxC,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CA8DjC"}
@@ -0,0 +1,315 @@
1
+ import "../../_dnt.polyfills.js";
2
+ /**
3
+ * A maintenance run stopped on something other than an unreadable row, such
4
+ * as a lost database connection. Rows already handled stay handled; running
5
+ * again is safe. The original error is `cause`.
6
+ */
7
+ export class SecretMaintenanceError extends Error {
8
+ constructor(location, rowId, results, cause) {
9
+ // The cause's own message is left out: a driver may quote parameters.
10
+ super(`Secret maintenance stopped in "${location}"${rowId === null ? "" : ` at row ${rowId}`}.`, { cause });
11
+ /** The location being processed. */
12
+ Object.defineProperty(this, "location", {
13
+ enumerable: true,
14
+ configurable: true,
15
+ writable: true,
16
+ value: void 0
17
+ });
18
+ /** The row being processed, when one was. */
19
+ Object.defineProperty(this, "rowId", {
20
+ enumerable: true,
21
+ configurable: true,
22
+ writable: true,
23
+ value: void 0
24
+ });
25
+ /** Results for the locations finished before this one. */
26
+ Object.defineProperty(this, "results", {
27
+ enumerable: true,
28
+ configurable: true,
29
+ writable: true,
30
+ value: void 0
31
+ });
32
+ this.name = "SecretMaintenanceError";
33
+ this.location = location;
34
+ this.rowId = rowId;
35
+ this.results = results;
36
+ }
37
+ }
38
+ const DEFAULT_BATCH_SIZE = 100;
39
+ const DEFAULT_MAX_FAILURES = 1000;
40
+ const KINDS = ["text", "json", "bytes"];
41
+ /**
42
+ * Declares an app's secret locations, rejecting duplicate names so that a
43
+ * report line or a saved cursor always means one place.
44
+ */
45
+ export function defineSecretLocations(locations) {
46
+ const names = new Set();
47
+ for (const location of locations) {
48
+ if (typeof location.name !== "string" || location.name === "") {
49
+ throw new TypeError("A secret location needs a name.");
50
+ }
51
+ if (names.has(location.name)) {
52
+ throw new TypeError(`Secret location "${location.name}" is declared twice.`);
53
+ }
54
+ if (location.kind !== undefined && !KINDS.includes(location.kind)) {
55
+ throw new TypeError(`Secret location "${location.name}" has an unknown kind.`);
56
+ }
57
+ names.add(location.name);
58
+ }
59
+ return [...locations];
60
+ }
61
+ function positiveInteger(value, fallback, what) {
62
+ const resolved = value ?? fallback;
63
+ if (!Number.isSafeInteger(resolved) || resolved <= 0) {
64
+ throw new RangeError(`${what} must be a positive integer.`);
65
+ }
66
+ return resolved;
67
+ }
68
+ /** Collects failures up to a limit while counting all of them. */
69
+ function failureList(max) {
70
+ const list = [];
71
+ return {
72
+ failures: list,
73
+ failureCount: 0,
74
+ add(id, reason) {
75
+ this.failureCount += 1;
76
+ if (list.length < max) {
77
+ list.push({ id, reason });
78
+ }
79
+ },
80
+ };
81
+ }
82
+ /**
83
+ * Turns an error from sealing or opening one row into a row failure. Anything
84
+ * else is not about that row's secret and is rethrown to stop the run.
85
+ */
86
+ function rowFailureReason(error) {
87
+ const candidate = error;
88
+ // Matched by shape, not `instanceof`: the app and this module may have
89
+ // loaded different copies of the error class (ESM and CommonJS builds).
90
+ if (candidate?.name === "SecretUnreadableError" &&
91
+ typeof candidate.reason === "string") {
92
+ return candidate.reason;
93
+ }
94
+ if (error instanceof TypeError) {
95
+ return "invalid-binding";
96
+ }
97
+ throw error;
98
+ }
99
+ /** Runs one operation over every location, with paging and error context. */
100
+ async function eachLocation(db, declared, options, start) {
101
+ const locations = defineSecretLocations(declared);
102
+ const batchSize = positiveInteger(options.batchSize, DEFAULT_BATCH_SIZE, "batchSize");
103
+ const maxRows = options.maxRows === undefined
104
+ ? Infinity
105
+ : positiveInteger(options.maxRows, 1, "maxRows");
106
+ const maxFailures = positiveInteger(options.maxFailures, DEFAULT_MAX_FAILURES, "maxFailures");
107
+ const results = [];
108
+ for (const location of locations) {
109
+ const operation = start(location, maxFailures);
110
+ const earlier = options.previous?.find((progress) => progress.name === location.name);
111
+ if (earlier?.done) {
112
+ results.push(operation.finish({
113
+ name: location.name,
114
+ rows: 0,
115
+ done: true,
116
+ cursor: null,
117
+ }));
118
+ continue;
119
+ }
120
+ let cursor = earlier?.cursor ?? null;
121
+ let rows = 0;
122
+ let done = false;
123
+ let rowId = null;
124
+ let previousPage = new Set();
125
+ try {
126
+ while (rows < maxRows) {
127
+ rowId = null;
128
+ const page = await location.read(db, cursor, Math.min(batchSize, maxRows - rows));
129
+ if (page.length === 0) {
130
+ done = true;
131
+ break;
132
+ }
133
+ const thisPage = new Set();
134
+ for (const row of page) {
135
+ if (typeof row?.id !== "string" || row.id === "") {
136
+ throw new TypeError("A row was returned without a string id.");
137
+ }
138
+ // A read that ignores its cursor would otherwise never finish. No
139
+ // order is imposed on ids: a database may sort them differently
140
+ // from JavaScript, and only lack of progress is an error.
141
+ if (previousPage.has(row.id) || thisPage.has(row.id)) {
142
+ throw new Error("The same row was returned twice.");
143
+ }
144
+ thisPage.add(row.id);
145
+ rowId = row.id;
146
+ await operation.visit(row);
147
+ cursor = row.id;
148
+ rows += 1;
149
+ }
150
+ previousPage = thisPage;
151
+ }
152
+ }
153
+ catch (error) {
154
+ throw new SecretMaintenanceError(location.name, rowId, results, error);
155
+ }
156
+ results.push(operation.finish({
157
+ name: location.name,
158
+ rows,
159
+ done,
160
+ cursor: done ? null : cursor,
161
+ }));
162
+ }
163
+ return results;
164
+ }
165
+ /** Opens a row strictly and returns a comparable form of its plaintext. */
166
+ async function openComparable(location, sealed, binding) {
167
+ const { purpose } = location;
168
+ switch (location.kind ?? "text") {
169
+ case "json":
170
+ return JSON.stringify(await purpose.openJson(sealed, binding));
171
+ case "bytes":
172
+ return (await purpose.openBytes(sealed, binding)).join(",");
173
+ default:
174
+ return await purpose.open(sealed, binding);
175
+ }
176
+ }
177
+ /**
178
+ * Counts rows per key version by parsing each string. It decrypts nothing, so
179
+ * it needs no key and can run anywhere the database can be read. A clean
180
+ * report says where rows stand, not that they open: use
181
+ * {@link verifySecretLocations} for that.
182
+ */
183
+ export function reportSecretLocations(db, locations, options = {}) {
184
+ return eachLocation(db, locations, options, (location, maxFailures) => {
185
+ const byKeyId = {};
186
+ const malformed = failureList(maxFailures);
187
+ return {
188
+ visit(row) {
189
+ const keyId = location.purpose.keyId(row.sealed);
190
+ if (keyId === null) {
191
+ malformed.add(row.id, "malformed");
192
+ }
193
+ else {
194
+ byKeyId[keyId] = (byKeyId[keyId] ?? 0) + 1;
195
+ }
196
+ return Promise.resolve();
197
+ },
198
+ finish: (progress) => ({
199
+ ...progress,
200
+ byKeyId,
201
+ failures: malformed.failures,
202
+ failureCount: malformed.failureCount,
203
+ }),
204
+ };
205
+ });
206
+ }
207
+ /**
208
+ * Opens every declared row with no fallback of any kind, and reports each row
209
+ * that does not open by id and reason. Run it inside the deployed app: that is
210
+ * the only place the keys exist. It never outputs a value.
211
+ *
212
+ * A value whose lifetime has passed is reported as `expired` on every run. It
213
+ * can never be resealed, so the app must delete such rows before the key they
214
+ * are under can be retired.
215
+ */
216
+ export function verifySecretLocations(db, locations, options = {}) {
217
+ return eachLocation(db, locations, options, (location, maxFailures) => {
218
+ let opened = 0;
219
+ const failed = failureList(maxFailures);
220
+ return {
221
+ async visit(row) {
222
+ try {
223
+ await openComparable(location, row.sealed, row.binding);
224
+ opened += 1;
225
+ }
226
+ catch (error) {
227
+ failed.add(row.id, rowFailureReason(error));
228
+ }
229
+ },
230
+ finish: (progress) => ({
231
+ ...progress,
232
+ opened,
233
+ failures: failed.failures,
234
+ failureCount: failed.failureCount,
235
+ }),
236
+ };
237
+ });
238
+ }
239
+ /**
240
+ * Moves rows that are under an older key to the active key.
241
+ *
242
+ * Before anything else it runs `assertReady()` for the keys each location's
243
+ * purpose will actually use. A real run also requires that an expected-key
244
+ * list was applied, so rows are never moved onto a key that has not been shown
245
+ * to match its recorded fingerprint: moving every row onto a mistyped
246
+ * write-only key, and later retiring the old one, would lose them all.
247
+ *
248
+ * For each row it reseals, opens the new string and compares it with the old
249
+ * plaintext, and only then swaps it in with the location's compare-and-swap. A
250
+ * row someone else changed in the meantime is counted and left alone. It is
251
+ * safe to run again, and to stop and continue by passing the results back as
252
+ * `previous`.
253
+ */
254
+ export async function resealSecretLocations(db, locations, options = {}) {
255
+ const dryRun = options.dryRun !== false;
256
+ for (const location of defineSecretLocations(locations)) {
257
+ const readiness = await location.purpose.assertReady();
258
+ if (!dryRun && !readiness.verified && !options.allowUnverifiedKeys) {
259
+ throw new Error(`Secret location "${location.name}" has no expected-key list, so its active key is unverified. Refusing to reseal.`);
260
+ }
261
+ }
262
+ return eachLocation(db, locations, options, (location, maxFailures) => {
263
+ const counts = { current: 0, resealed: 0, changed: 0 };
264
+ const changedIds = [];
265
+ const failed = failureList(maxFailures);
266
+ return {
267
+ async visit(row) {
268
+ let next;
269
+ try {
270
+ if (location.purpose.keyId(row.sealed) === null) {
271
+ failed.add(row.id, "malformed");
272
+ return;
273
+ }
274
+ if (!await location.purpose.needsReseal(row.sealed)) {
275
+ counts.current += 1;
276
+ return;
277
+ }
278
+ next = await location.purpose.reseal(row.sealed, row.binding);
279
+ const [before, after] = await Promise.all([
280
+ openComparable(location, row.sealed, row.binding),
281
+ openComparable(location, next, row.binding),
282
+ ]);
283
+ if (before !== after) {
284
+ // Unreachable unless the purpose or the runtime is broken; a row
285
+ // must never be replaced by something that reads differently.
286
+ failed.add(row.id, "malformed");
287
+ return;
288
+ }
289
+ }
290
+ catch (error) {
291
+ failed.add(row.id, rowFailureReason(error));
292
+ return;
293
+ }
294
+ // Outside the try: a failed write is not an unreadable row.
295
+ if (dryRun || await location.write(db, row.id, row.sealed, next)) {
296
+ counts.resealed += 1;
297
+ }
298
+ else {
299
+ counts.changed += 1;
300
+ if (changedIds.length < maxFailures) {
301
+ changedIds.push(row.id);
302
+ }
303
+ }
304
+ },
305
+ finish: (progress) => ({
306
+ ...progress,
307
+ dryRun,
308
+ ...counts,
309
+ changedIds,
310
+ failures: failed.failures,
311
+ failureCount: failed.failureCount,
312
+ }),
313
+ };
314
+ });
315
+ }
@@ -0,0 +1,6 @@
1
+ import "../../_dnt.polyfills.js";
2
+ export { type SecretFailureReason, SecretsKeyError, SecretsKeyMismatchError, SecretUnreadableError, } from "./errors.js";
3
+ export { type ExpectedSecretKey, isSecretKeyFingerprint, parseExpectedSecretKeys, secretKeyFingerprint, type SecretKeyState, } from "./fingerprint.js";
4
+ export { decodeSecretKey, DEFAULT_SECRETS_ACTIVE_KEY_ENV, DEFAULT_SECRETS_KEY_ENV_PREFIX, envKeyring, type EnvKeyringOptions, isSecretKeyId, type SecretKeyring, SECRETS_KEY_BYTES, staticKeyring, } from "./keyring.js";
5
+ export { createSecrets, type CreateSecretsOptions, KEYED_FINGERPRINT_FORMAT, type MacOptions, SEALED_FORMAT, type SealOptions, type SecretBinding, type SecretFailureEvent, type SecretPurpose, type SecretPurposeOptions, type Secrets, type SecretsReadiness, } from "./secrets.js";
6
+ //# sourceMappingURL=mod.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/src/secrets/mod.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,mBAAmB,EACxB,eAAe,EACf,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,iBAAiB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,eAAe,EACf,8BAA8B,EAC9B,8BAA8B,EAC9B,UAAU,EACV,KAAK,iBAAiB,EACtB,aAAa,EACb,KAAK,aAAa,EAClB,iBAAiB,EACjB,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,KAAK,UAAU,EACf,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,OAAO,EACZ,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC"}
@@ -0,0 +1,5 @@
1
+ import "../../_dnt.polyfills.js";
2
+ export { SecretsKeyError, SecretsKeyMismatchError, SecretUnreadableError, } from "./errors.js";
3
+ export { isSecretKeyFingerprint, parseExpectedSecretKeys, secretKeyFingerprint, } from "./fingerprint.js";
4
+ export { decodeSecretKey, DEFAULT_SECRETS_ACTIVE_KEY_ENV, DEFAULT_SECRETS_KEY_ENV_PREFIX, envKeyring, isSecretKeyId, SECRETS_KEY_BYTES, staticKeyring, } from "./keyring.js";
5
+ export { createSecrets, KEYED_FINGERPRINT_FORMAT, SEALED_FORMAT, } from "./secrets.js";