@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.
- package/README.md +66 -0
- package/THIRD_PARTY_NOTICES.md +12 -9
- package/esm/src/cli/externalSkills.d.ts.map +1 -1
- package/esm/src/cli/externalSkills.js +25 -20
- package/esm/src/cli/mod.d.ts +117 -1
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +1368 -44
- package/esm/src/cli/projectSkills.d.ts +10 -3
- package/esm/src/cli/projectSkills.d.ts.map +1 -1
- package/esm/src/cli/projectSkills.js +173 -49
- package/esm/src/cli/vercelBuildEnv.d.ts +28 -0
- package/esm/src/cli/vercelBuildEnv.d.ts.map +1 -1
- package/esm/src/cli/vercelBuildEnv.js +120 -30
- package/esm/src/next/secrets/mod.d.ts +108 -0
- package/esm/src/next/secrets/mod.d.ts.map +1 -0
- package/esm/src/next/secrets/mod.js +176 -0
- package/esm/src/secrets/encoding.d.ts +32 -0
- package/esm/src/secrets/encoding.d.ts.map +1 -0
- package/esm/src/secrets/encoding.js +87 -0
- package/esm/src/secrets/errors.d.ts +45 -0
- package/esm/src/secrets/errors.d.ts.map +1 -0
- package/esm/src/secrets/errors.js +39 -0
- package/esm/src/secrets/fingerprint.d.ts +43 -0
- package/esm/src/secrets/fingerprint.d.ts.map +1 -0
- package/esm/src/secrets/fingerprint.js +87 -0
- package/esm/src/secrets/frame.d.ts +34 -0
- package/esm/src/secrets/frame.d.ts.map +1 -0
- package/esm/src/secrets/frame.js +86 -0
- package/esm/src/secrets/keyring.d.ts +62 -0
- package/esm/src/secrets/keyring.d.ts.map +1 -0
- package/esm/src/secrets/keyring.js +160 -0
- package/esm/src/secrets/legacy.d.ts +60 -0
- package/esm/src/secrets/legacy.d.ts.map +1 -0
- package/esm/src/secrets/legacy.js +147 -0
- package/esm/src/secrets/maintenance.d.ts +173 -0
- package/esm/src/secrets/maintenance.d.ts.map +1 -0
- package/esm/src/secrets/maintenance.js +315 -0
- package/esm/src/secrets/mod.d.ts +6 -0
- package/esm/src/secrets/mod.d.ts.map +1 -0
- package/esm/src/secrets/mod.js +5 -0
- package/esm/src/secrets/secrets.d.ts +192 -0
- package/esm/src/secrets/secrets.d.ts.map +1 -0
- package/esm/src/secrets/secrets.js +528 -0
- package/package.json +50 -2
- package/script/src/cli/externalSkills.d.ts.map +1 -1
- package/script/src/cli/externalSkills.js +25 -20
- package/script/src/cli/mod.d.ts +117 -1
- package/script/src/cli/mod.d.ts.map +1 -1
- package/script/src/cli/mod.js +1372 -41
- package/script/src/cli/projectSkills.d.ts +10 -3
- package/script/src/cli/projectSkills.d.ts.map +1 -1
- package/script/src/cli/projectSkills.js +173 -49
- package/script/src/cli/vercelBuildEnv.d.ts +28 -0
- package/script/src/cli/vercelBuildEnv.d.ts.map +1 -1
- package/script/src/cli/vercelBuildEnv.js +121 -30
- package/script/src/next/secrets/mod.d.ts +108 -0
- package/script/src/next/secrets/mod.d.ts.map +1 -0
- package/script/src/next/secrets/mod.js +218 -0
- package/script/src/secrets/encoding.d.ts +32 -0
- package/script/src/secrets/encoding.d.ts.map +1 -0
- package/script/src/secrets/encoding.js +95 -0
- package/script/src/secrets/errors.d.ts +45 -0
- package/script/src/secrets/errors.d.ts.map +1 -0
- package/script/src/secrets/errors.js +45 -0
- package/script/src/secrets/fingerprint.d.ts +43 -0
- package/script/src/secrets/fingerprint.d.ts.map +1 -0
- package/script/src/secrets/fingerprint.js +92 -0
- package/script/src/secrets/frame.d.ts +34 -0
- package/script/src/secrets/frame.d.ts.map +1 -0
- package/script/src/secrets/frame.js +91 -0
- package/script/src/secrets/keyring.d.ts +62 -0
- package/script/src/secrets/keyring.d.ts.map +1 -0
- package/script/src/secrets/keyring.js +202 -0
- package/script/src/secrets/legacy.d.ts +60 -0
- package/script/src/secrets/legacy.d.ts.map +1 -0
- package/script/src/secrets/legacy.js +186 -0
- package/script/src/secrets/maintenance.d.ts +173 -0
- package/script/src/secrets/maintenance.d.ts.map +1 -0
- package/script/src/secrets/maintenance.js +323 -0
- package/script/src/secrets/mod.d.ts +6 -0
- package/script/src/secrets/mod.d.ts.map +1 -0
- package/script/src/secrets/mod.js +24 -0
- package/script/src/secrets/secrets.d.ts +192 -0
- package/script/src/secrets/secrets.d.ts.map +1 -0
- package/script/src/secrets/secrets.js +532 -0
- package/skills/loom/SKILL.md +79 -222
- package/skills/loom/references/dependency-upgrades.md +26 -0
- package/skills/loom/references/local-development.md +157 -0
- package/skills/loom/references/release-safety.md +118 -0
- package/skills/loom/references/release-trusted-sources.md +55 -0
- package/skills/loom/references/tools-and-skills.md +83 -0
- package/skills/loom-api-keys/SKILL.md +1 -1
- package/skills/loom-auth/SKILL.md +7 -60
- package/skills/loom-auth/references/secrets-and-rotation.md +61 -0
- package/skills/loom-db/SKILL.md +4 -79
- package/skills/loom-files/SKILL.md +4 -2
- package/skills/loom-files/references/provider-configuration.md +150 -0
- package/skills/loom-jobs/SKILL.md +9 -8
- package/skills/loom-lingui/SKILL.md +5 -3
- package/skills/loom-secrets/SKILL.md +266 -0
- package/skills/loom-torvalds-review/SKILL.md +9 -6
- package/skills/loom-torvalds-review/references/context-profiles.md +2 -1
- package/skills/upgrade-deps/SKILL.md +15 -7
|
@@ -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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"}
|