hammerkit 1.22.0 → 1.24.0

package/dist/secrets/command-secret-provider.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCommandSecretProvider = void 0;
+const child_process_1 = require("child_process");
+const abort_1 = require("../executer/abort");
+const STDERR_LIMIT = 500;
+// Runs the provider's command and takes its stdout, verbatim, as the value: a
+// key file needs its trailing newline. No shell, so a reference is one argument
+// and never syntax. The command sees PATH, the provider's own `env` and the
+// account's `env` and nothing else of this process: a personal login (`gcloud
+// auth login`, the 1Password app) is never picked up, and a missing credential
+// fails instead of falling back to one.
+function createCommandSecretProvider(binding) {
+    const { definition, account } = binding;
+    return {
+        async resolve(ref, environment) {
+            const [command, ...args] = definition.command.map((part) => expand(part, environment, `provider ${definition.name}`).replace(/\{\{ref\}\}/g, () => ref));
+            const env = {
+                ...minimalEnvironment(environment),
+                ...expandAll(definition.env, environment, `provider ${definition.name}`),
+                ...expandAll(account.env, environment, `account ${account.name}, provider ${definition.name}`),
+            };
+            return run(command, args, env, definition.timeoutMs, environment);
+        },
+    };
+}
+exports.createCommandSecretProvider = createCommandSecretProvider;
+function minimalEnvironment(environment) {
+    const names = process.platform === 'win32' ? ['PATH', 'Path', 'PATHEXT', 'SystemRoot'] : ['PATH'];
+    const result = {};
+    for (const name of names) {
+        const value = environment.processEnvs[name];
+        if (value !== undefined && value !== null) {
+            result[name] = value;
+        }
+    }
+    return result;
+}
+function expandAll(values, environment, owner) {
+    return Object.fromEntries(Object.entries(values).map(([key, value]) => [key, expand(value, environment, owner)]));
+}
+// `${NAME}` from the process environment; one that is not set stops the secret
+// before the command runs.
+function expand(value, environment, owner) {
+    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => {
+        const resolved = environment.processEnvs[name];
+        if (resolved === undefined || resolved === null || resolved === '') {
+            throw new Error(`${owner}: ${name} is not set`);
+        }
+        return resolved;
+    });
+}
+function run(command, args, env, timeoutMs, environment) {
+    return new Promise((resolve, reject) => {
+        const signal = environment.abortCtrl.signal;
+        if (signal.aborted) {
+            reject(new abort_1.AbortError());
+            return;
+        }
+        const child = (0, child_process_1.spawn)(command, args, { env, shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+        const stdout = [];
+        const stderr = [];
+        let failure = null;
+        const finish = (error, value) => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve(value ?? '');
+            }
+        };
+        const stop = (error) => {
+            failure = failure ?? error;
+            child.kill('SIGKILL');
+        };
+        const onAbort = () => stop(new abort_1.AbortError());
+        const timer = setTimeout(() => stop(new Error(`${command} did not finish within ${timeoutMs}ms`)), timeoutMs);
+        signal.addEventListener('abort', onAbort);
+        child.stdout.on('data', (chunk) => stdout.push(chunk));
+        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        child.on('error', (error) => {
+            finish(error.code === 'ENOENT' ? new Error(`${command} was not found on PATH`) : error);
+        });
+        child.on('close', (code) => {
+            if (failure) {
+                finish(failure);
+            }
+            else if (code !== 0) {
+                finish(new Error(`${command} exited with code ${code}${describeStderr(stderr, environment)}`));
+            }
+            else {
+                finish(null, Buffer.concat(stdout).toString('utf8'));
+            }
+        });
+    });
+}
+// What the CLI said, as the first lines of a failure; its own output may hold a
+// value it was asked for, so it is masked like all output.
+function describeStderr(chunks, environment) {
+    const text = environment.secrets.redact(Buffer.concat(chunks).toString('utf8').trim());
+    if (text.length === 0) {
+        return '';
+    }
+    return `: ${text.length > STDERR_LIMIT ? `${text.substring(0, STDERR_LIMIT)}…` : text}`;
+}
+//# sourceMappingURL=command-secret-provider.js.map

package/dist/secrets/prefetch-secrets.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prefetchSecrets = void 0;
+const plan_work_tasks_1 = require("../planner/utils/plan-work-tasks");
+const work_secret_1 = require("../planner/work-secret");
+const provider_values_1 = require("./provider-values");
+// Fetches the values a task id needs; a run drops the ones of the previous run
+// first (`newRun`), any other command reuses what the run already fetched. A task id is computed synchronously and holds the
+// digest of each `cache: true` secret, so those values must be in memory before
+// anything asks for an id. Secrets that don't affect the id are read when their
+// task starts, and a plan without provider secrets calls no provider.
+async function prefetchSecrets(workTree, environment, newRun = false) {
+    if (newRun) {
+        (0, provider_values_1.beginSecretRun)(environment);
+    }
+    const fetches = [];
+    for (const task of (0, plan_work_tasks_1.iterateWorkTasks)(workTree)) {
+        for (const secret of task.data.secrets) {
+            if (secret.cache && secret.source.type === 'provider') {
+                fetches.push((0, work_secret_1.resolveSecretValue)(secret, environment));
+            }
+        }
+    }
+    await Promise.all(fetches);
+}
+exports.prefetchSecrets = prefetchSecrets;
+//# sourceMappingURL=prefetch-secrets.js.map

package/dist/secrets/provider-values.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.peekProviderValue = exports.fetchProviderValue = exports.beginSecretRun = void 0;
+const secret_provider_1 = require("./secret-provider");
+// The values fetched in the current run, by provider, account and reference.
+// Concurrent requests share one fetch: a secret manager is rate limited (a
+// 1Password service account per token) and several tasks read the same value.
+// Held in memory only, never written anywhere, and dropped when the next run
+// begins so a rotated value is picked up by it.
+const runs = new WeakMap();
+function beginSecretRun(environment) {
+    runs.set(environment, new Map());
+}
+exports.beginSecretRun = beginSecretRun;
+function keyOf(binding, ref) {
+    return [binding.definition.name, binding.account.name, ref].join('\0');
+}
+function fetchProviderValue(binding, ref, environment) {
+    let values = runs.get(environment);
+    if (!values) {
+        values = new Map();
+        runs.set(environment, values);
+    }
+    const key = keyOf(binding, ref);
+    let fetched = values.get(key);
+    if (!fetched) {
+        environment.status
+            .context({ type: 'cli', name: 'hammerkit' })
+            .write('debug', `secret ${ref} via ${binding.definition.name}/${binding.account.name}`);
+        const entry = { promise: (0, secret_provider_1.createSecretProvider)(binding).resolve(ref, environment) };
+        entry.promise = entry.promise.then((value) => {
+            entry.value = value;
+            return value;
+        });
+        fetched = entry;
+        values.set(key, fetched);
+    }
+    return fetched.promise;
+}
+exports.fetchProviderValue = fetchProviderValue;
+// The value of a fetch that has finished in this run, for the sync part of
+// planning (a task id); undefined when it was not fetched, see prefetchSecrets.
+function peekProviderValue(binding, ref, environment) {
+    return runs.get(environment)?.get(keyOf(binding, ref))?.value;
+}
+exports.peekProviderValue = peekProviderValue;
+//# sourceMappingURL=provider-values.js.map

package/dist/secrets/secret-catalog.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectSecretCatalog = exports.emptySecretCatalog = void 0;
+const merge_environment_variables_1 = require("../environment/merge-environment-variables");
+const replace_env_variables_1 = require("../environment/replace-env-variables");
+const units_1 = require("../utils/units");
+const DEFAULT_TIMEOUT = '30s';
+function emptySecretCatalog() {
+    return { providers: {}, accounts: {} };
+}
+exports.emptySecretCatalog = emptySecretCatalog;
+const FULL_COMMIT = /^[0-9a-f]{40}$/i;
+// Providers and accounts are global names, like caches, collected from every
+// loaded build file. A name declared twice is an error rather than a silent
+// override: which definition runs with a service account's credential must not
+// depend on include order.
+function collectSecretCatalog(files, environment, context) {
+    const catalog = emptySecretCatalog();
+    for (const file of files) {
+        const providers = Object.entries(file.schema.secretProviders ?? {});
+        const accounts = Object.entries(file.schema.secretAccounts ?? {});
+        if (providers.length === 0 && accounts.length === 0) {
+            continue;
+        }
+        requirePinnedSource(file);
+        const envs = (0, replace_env_variables_1.buildEnvironmentVariables)((0, merge_environment_variables_1.mergeEnvironmentVariables)(file.schema.envs, null), environment, context).variables;
+        for (const [name, provider] of providers) {
+            if (catalog.providers[name]) {
+                throw new Error(`secret provider ${name} is declared in ${catalog.providers[name].declaredIn} and in ${file.fileName}`);
+            }
+            catalog.providers[name] = {
+                name,
+                type: 'command',
+                command: provider.command.map((part) => applyEnvs(part, envs)),
+                env: provider.env ?? {},
+                timeoutMs: (0, units_1.parseDuration)(provider.timeout ?? DEFAULT_TIMEOUT),
+                declaredIn: file.fileName,
+            };
+        }
+        for (const [name, account] of accounts) {
+            if (catalog.accounts[name]) {
+                throw new Error(`secret account ${name} is declared in ${catalog.accounts[name].declaredIn} and in ${file.fileName}`);
+            }
+            catalog.accounts[name] = {
+                name,
+                default: account.default ?? false,
+                providers: account.providers,
+                declaredIn: file.fileName,
+            };
+        }
+    }
+    const defaults = Object.values(catalog.accounts).filter((account) => account.default);
+    if (defaults.length > 1) {
+        throw new Error(`more than one default secret account: ${defaults.map((a) => a.name).join(', ')}`);
+    }
+    for (const account of Object.values(catalog.accounts)) {
+        for (const provider of Object.keys(account.providers)) {
+            if (!catalog.providers[provider]) {
+                throw new Error(`secret account ${account.name} (${account.declaredIn}) names provider ${provider}, which is not declared`);
+            }
+        }
+    }
+    return catalog;
+}
+exports.collectSecretCatalog = collectSecretCatalog;
+// A tag or branch can be moved, and a moved file runs with the credentials of a
+// service account: providers and accounts from a git include are pinned.
+function requirePinnedSource(file) {
+    if (file.remote && !FULL_COMMIT.test(file.remote.ref ?? '')) {
+        throw new Error(`${file.fileName} declares secret providers or accounts, so its git include ${file.remote.git} needs ref to be a full commit SHA`);
+    }
+}
+// `${NAME}` that the build file's own `envs` define; any other reference stays
+// for the host environment.
+function applyEnvs(value, envs) {
+    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (match, name) => name in envs && !envs[name].includes('$') ? envs[name] : match);
+}
+//# sourceMappingURL=secret-catalog.js.map

package/dist/secrets/secret-provider.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSecretProvider = exports.registerSecretProvider = void 0;
+const command_secret_provider_1 = require("./command-secret-provider");
+const factories = new Map();
+function registerSecretProvider(type, factory) {
+    factories.set(type, factory);
+}
+exports.registerSecretProvider = registerSecretProvider;
+function createSecretProvider(binding) {
+    const factory = factories.get(binding.definition.type);
+    if (!factory) {
+        throw new Error(`unknown secret provider type: ${binding.definition.type}`);
+    }
+    return factory(binding);
+}
+exports.createSecretProvider = createSecretProvider;
+registerSecretProvider('command', command_secret_provider_1.createCommandSecretProvider);
+//# sourceMappingURL=secret-provider.js.map

package/dist/server/approvals-api.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleApprovals = void 0;
+const zod_1 = require("zod");
+const http_1 = require("./http");
+const oauth_1 = require("./oauth");
+const policy_1 = require("./policy");
+const runs_1 = require("./runs");
+const decisionSchema = zod_1.z.object({ reason: zod_1.z.string().max(500).optional() }).strict();
+// What an approver is shown of a run: everything that decides whether to let it
+// go ahead, and who asked.
+function toApprovalView(run) {
+    return {
+        id: run.id,
+        state: run.state,
+        requestedBy: run.owner,
+        createdAt: run.createdAt,
+        definition: run.definition,
+        tasks: run.tasks,
+        account: run.account,
+        source: run.source,
+        options: run.options,
+        approval: run.approval,
+    };
+}
+/**
+ * The runs waiting for an approval, which an admin of the service account they
+ * use gives:
+ *
+ *   GET  /v1/approvals                  the runs the caller may approve
+ *   GET  /v1/approvals/<id>             one of them
+ *   POST /v1/approvals/<id>/approve     let it run (body: optional {reason})
+ *   POST /v1/approvals/<id>/reject      end it
+ *
+ * What the caller may not approve does not exist for them; their own run is the
+ * exception, they are told why it is not theirs to decide.
+ */
+async function handleApprovals(config, registry, log, principal, req, res, url) {
+    const match = /^\/v1\/approvals(?:\/([^/]+)(?:\/(approve|reject))?)?$/.exec(url.pathname);
+    if (!match) {
+        return false;
+    }
+    const [, id, action] = match;
+    const grant = (0, policy_1.getGrant)(config.entitlements, principal);
+    const canDecide = (account) => (0, policy_1.isAdmin)(grant, account);
+    if (!id) {
+        if (req.method !== 'GET') {
+            (0, http_1.send)(res, 405, { error: 'method not allowed' }, { allow: 'GET' });
+            return true;
+        }
+        const open = registry
+            .waiting()
+            .filter((run) => !(run.owner.iss === principal.iss && run.owner.sub === principal.sub) && canDecide(run.account));
+        (0, http_1.send)(res, 200, { approvals: open.map(toApprovalView) });
+        return true;
+    }
+    if (!runs_1.RUN_ID_PATTERN.test(id)) {
+        (0, http_1.send)(res, 404, { error: 'not found' });
+        return true;
+    }
+    if (!action) {
+        if (req.method !== 'GET') {
+            (0, http_1.send)(res, 405, { error: 'method not allowed' }, { allow: 'GET' });
+            return true;
+        }
+        const run = registry.getForApproval(id, canDecide);
+        run ? (0, http_1.send)(res, 200, toApprovalView(run)) : (0, http_1.send)(res, 404, { error: 'not found' });
+        return true;
+    }
+    if (req.method !== 'POST') {
+        (0, http_1.send)(res, 405, { error: 'method not allowed' }, { allow: 'POST' });
+        return true;
+    }
+    const body = decisionSchema.safeParse(req.headers['content-type'] ? await (0, http_1.readJson)(req) : {});
+    if (!body.success) {
+        const issue = body.error.issues[0];
+        (0, http_1.send)(res, 400, { error: `${issue.path.join('.') || 'request'}: ${issue.message}` });
+        return true;
+    }
+    const outcome = action === 'approve' ? 'approved' : 'rejected';
+    const result = registry.decide(principal, id, outcome, canDecide, body.data.reason);
+    log(`${action} run=${id} iss=${principal.iss} sub=${principal.sub} result=${result.status}${body.data.reason ? ` reason=${(0, oauth_1.quote)(body.data.reason)}` : ''}`);
+    switch (result.status) {
+        case 'ok':
+            (0, http_1.send)(res, 200, toApprovalView(result.run));
+            break;
+        case 'own-run':
+            (0, http_1.send)(res, 403, { error: 'a run is approved by somebody else than who asked for it' });
+            break;
+        case 'not-waiting':
+            (0, http_1.send)(res, 409, { error: `the run is ${result.state}, it does not wait for an approval` });
+            break;
+        default:
+            (0, http_1.send)(res, 404, { error: 'not found' });
+    }
+    return true;
+}
+exports.handleApprovals = handleApprovals;
+//# sourceMappingURL=approvals-api.js.map

package/dist/server/definitions-api.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleDefinitions = void 0;
+const bundle_1 = require("../remote/bundle");
+const definitions_1 = require("./definitions");
+const http_1 = require("./http");
+const policy_1 = require("./policy");
+const proposals_1 = require("./proposals");
+const server_config_1 = require("./server-config");
+// A bundle is JSON text with escapes, so the body may be somewhat larger than the files.
+const MAX_PUBLISH_BYTES = bundle_1.MAX_BUNDLE_BYTES * 2;
+/**
+ * The published build files:
+ *
+ *   PUT  /v1/definitions/<name>                 publish a bundle, or propose it when the
+ *                                               caller may only propose (answers 202)
+ *   GET  /v1/definitions                        the names, with their latest version
+ *   GET  /v1/definitions/<name>                 the versions of one
+ *   GET  /v1/definitions/<name>/<hash|latest>   one version
+ *   GET  /v1/definitions/<name>/<hash|latest>/files   the files of one version
+ */
+async function handleDefinitions(config, store, proposals, log, principal, req, res, url) {
+    const match = /^\/v1\/definitions(?:\/([^/]+)(?:\/([^/]+)(\/files)?)?)?$/.exec(url.pathname);
+    if (!match) {
+        return false;
+    }
+    const [, name, version, files] = match;
+    const grant = (0, policy_1.getGrant)(config.entitlements, principal);
+    if (name !== undefined && !server_config_1.definitionName.safeParse(name).success) {
+        (0, http_1.send)(res, 404, { error: 'not found' });
+        return true;
+    }
+    if (name !== undefined && version === undefined && req.method === 'PUT') {
+        await publish(config, store, proposals, log, principal, name, req, res);
+        return true;
+    }
+    if (req.method !== 'GET') {
+        (0, http_1.send)(res, 405, { error: 'method not allowed' }, { allow: name !== undefined && !version ? 'GET, PUT' : 'GET' });
+        return true;
+    }
+    // what the caller may not see does not exist for them
+    if (!(0, policy_1.maySeeDefinitions)(grant)) {
+        (0, http_1.send)(res, 404, { error: 'not found' });
+        return true;
+    }
+    if (name === undefined) {
+        (0, http_1.send)(res, 200, {
+            definitions: store.names().map((n) => ({ name: n, latest: store.find(n, 'latest')?.hash })),
+        });
+        return true;
+    }
+    if (version === undefined) {
+        const versions = store.list(name);
+        versions.length > 0
+            ? (0, http_1.send)(res, 200, { name, latest: versions[0].hash, versions })
+            : (0, http_1.send)(res, 404, { error: 'not found' });
+        return true;
+    }
+    const found = version === 'latest' || bundle_1.HASH_PATTERN.test(version) ? store.find(name, version) : undefined;
+    if (!found) {
+        (0, http_1.send)(res, 404, { error: 'not found' });
+        return true;
+    }
+    if (files) {
+        const bundle = await store.files(found);
+        bundle ? (0, http_1.send)(res, 200, bundle) : (0, http_1.send)(res, 404, { error: 'not found' });
+    }
+    else {
+        (0, http_1.send)(res, 200, found);
+    }
+    return true;
+}
+exports.handleDefinitions = handleDefinitions;
+async function publish(config, store, proposals, log, principal, name, req, res) {
+    const grant = (0, policy_1.getGrant)(config.entitlements, principal);
+    const direct = (0, policy_1.mayPublish)(grant, name);
+    if (!direct && !(0, policy_1.mayPropose)(grant, name)) {
+        log(`refuse publish iss=${principal.iss} sub=${principal.sub}: build file ${name} is not granted`);
+        (0, http_1.send)(res, 403, { error: `you may not publish ${name}` });
+        return;
+    }
+    const parsed = bundle_1.bundleSchema.safeParse(await (0, http_1.readJson)(req, MAX_PUBLISH_BYTES));
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        (0, http_1.send)(res, 400, { error: `${issue.path.join('.') || 'request'}: ${issue.message}` });
+        return;
+    }
+    try {
+        if (!direct) {
+            // a version can't run before it is approved, but it has to load, as it would
+            // have when published, so the approver is not asked about a broken one
+            const { version, existing } = await store.prepare(name, parsed.data, principal);
+            if (existing) {
+                (0, http_1.send)(res, 200, { ...existing, created: false });
+                return;
+            }
+            const { proposal, created } = proposals.propose(version, parsed.data, principal);
+            log(`propose ${name} ${proposal.hash} iss=${principal.iss} sub=${principal.sub} created=${created} tasks=${proposal.tasks.length}`);
+            (0, http_1.send)(res, created ? 202 : 200, { ...proposal, created });
+            return;
+        }
+        const { version, created } = await store.publish(name, parsed.data, principal);
+        log(`publish ${name} ${version.hash} iss=${principal.iss} sub=${principal.sub} created=${created} tasks=${version.tasks.length}`);
+        (0, http_1.send)(res, created ? 201 : 200, { ...version, created });
+    }
+    catch (e) {
+        if (e instanceof definitions_1.DefinitionError) {
+            log(`refuse publish iss=${principal.iss} sub=${principal.sub}: ${name} does not load`);
+            (0, http_1.send)(res, 400, { error: `the build file does not load: ${e.message}` });
+            return;
+        }
+        if (e instanceof proposals_1.ProposalError) {
+            (0, http_1.send)(res, 503, { error: e.message });
+            return;
+        }
+        throw e;
+    }
+}
+//# sourceMappingURL=definitions-api.js.map