hammerkit 1.23.0 → 1.24.0

package/dist/schema/runner-schema.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runnerSchema = void 0;
+const zod_1 = require("zod");
+const host_config_1 = require("../remote/host-config");
+// A server registered with `hammerkit remote add`; resolved on the machine that
+// runs the build, so the build file carries no URL.
+exports.runnerSchema = (0, zod_1.string)()
+    .min(1)
+    .refine((name) => !host_config_1.RESERVED_SERVER_NAMES.includes(name), {
+    message: 'local and auto are no servers, leave runner out to run where --on or the host config says',
+});
+//# sourceMappingURL=runner-schema.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

package/dist/server/definitions.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefinitionStore = exports.inspectBundle = exports.DefinitionError = void 0;
+const promises_1 = require("fs/promises");
+const os_1 = require("os");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const yaml_1 = require("yaml");
+const get_file_context_1 = require("../file/get-file-context");
+const resolve_git_source_1 = require("../includes/resolve-git-source");
+const schema_parser_1 = require("../schema/schema-parser");
+const reference_parser_1 = require("../schema/reference-parser");
+const work_scope_parser_1 = require("../schema/work-scope-parser");
+const work_task_1 = require("../planner/work-task");
+const bundle_1 = require("../remote/bundle");
+const log_1 = require("../log");
+class DefinitionError extends Error {
+}
+exports.DefinitionError = DefinitionError;
+// 40 (sha-1) or 64 (sha-256) hex digits
+const COMMIT_PATTERN = /^[0-9a-f]{40}([0-9a-f]{24})?$/i;
+// A hash alone can only name what is inside the bundle, so everything a build
+// file pulls in from elsewhere has to be pinned: a git include needs a commit
+// and a remote that is not a path on the server.
+function findLooseIncludes(bundle) {
+    const problems = [];
+    for (const [path, content] of Object.entries(bundle.files)) {
+        if (!/\.ya?ml$/i.test(path)) {
+            continue;
+        }
+        let document;
+        try {
+            document = (0, yaml_1.parse)(content);
+        }
+        catch {
+            continue; // a file that isn't valid yaml is reported when the bundle is parsed
+        }
+        for (const block of ['includes', 'references']) {
+            for (const [name, include] of Object.entries(document?.[block] ?? {})) {
+                const source = include;
+                if (!source || typeof source !== 'object' || source.git === undefined) {
+                    continue;
+                }
+                if (typeof source.git !== 'string' || !/^(https:\/\/|ssh:\/\/|git@[\w.-]+:)/.test(source.git)) {
+                    problems.push(`${path}: ${block}.${name}: git has to be an https:// or ssh:// address`);
+                }
+                if (typeof source.ref !== 'string' || !COMMIT_PATTERN.test(source.ref)) {
+                    problems.push(`${path}: ${block}.${name}: pin ref to a commit, a branch or tag can move`);
+                }
+            }
+        }
+    }
+    return problems;
+}
+// What a build file may read while it is inspected: its own files. The rest of
+// the server is not its business (a missing file is "not there", not an error).
+function confined(files, root) {
+    const check = (path) => {
+        if (!(0, resolve_git_source_1.isWithin)(root, (0, path_1.resolve)(root, path))) {
+            throw new DefinitionError(`${path} is outside of the bundle`);
+        }
+    };
+    const guarded = (fn) => (path) => {
+        check(path);
+        return fn.call(files, path);
+    };
+    return {
+        ...files,
+        read: guarded(files.read),
+        readStream: guarded(files.readStream),
+        listFiles: guarded(files.listFiles),
+        stats: guarded(files.stats),
+        exists: async (path) => (0, resolve_git_source_1.isWithin)(root, (0, path_1.resolve)(root, path)) && files.exists(path),
+        watch: files.watch,
+    };
+}
+// A path of a task, written relative to the root of the bundle with forward
+// slashes. A leading `!` (an exclusion) is kept. Nothing is returned for a path
+// outside of the bundle.
+function insideBundle(root, cwd, path) {
+    const negated = path.startsWith('!');
+    const absolute = (0, path_1.resolve)(cwd, negated ? path.slice(1) : path);
+    const inside = (0, path_1.relative)(root, absolute);
+    if (inside === '..' || inside.startsWith(`..${path_1.sep}`) || (0, path_1.isAbsolute)(inside)) {
+        return [];
+    }
+    const portable = inside.split(path_1.sep).join(path_1.posix.sep);
+    // a pattern keeps its glob characters, `resolve` only normalizes separators
+    return [`${negated ? '!' : ''}${portable === '' ? '.' : portable}`];
+}
+// Writes the bundle into a directory of its own and reads it the way a run
+// would, so a build file that doesn't parse is refused when it is published, not
+// when somebody wants to run it.
+async function inspectBundle(bundle, environment) {
+    const problems = findLooseIncludes(bundle);
+    if (problems.length > 0) {
+        throw new DefinitionError(problems.join('\n'));
+    }
+    const directory = await (0, promises_1.mkdtemp)((0, path_1.join)((0, os_1.tmpdir)(), 'hammerkit-definition-'));
+    try {
+        for (const [path, content] of Object.entries(bundle.files)) {
+            await (0, promises_1.mkdir)((0, path_1.dirname)((0, path_1.join)(directory, path)), { recursive: true });
+            await (0, promises_1.writeFile)((0, path_1.join)(directory, path), content);
+        }
+        const inspected = {
+            ...environment,
+            cwd: directory,
+            file: confined((0, get_file_context_1.getFileContext)(directory), directory),
+        };
+        try {
+            const { ctx, scope } = await (0, schema_parser_1.createParseContext)((0, path_1.join)(directory, bundle.entry), inspected);
+            const context = await (0, reference_parser_1.parseReferences)(ctx, scope, inspected);
+            const workTree = (0, work_scope_parser_1.getWorkContext)(context, { environmentName: null }, inspected);
+            const inputs = {};
+            for (const item of Object.values(workTree.tasks)) {
+                inputs[item.name] = {
+                    // the sources a task inherits from its dependencies belong to those
+                    src: item.data.src
+                        .filter((source) => source.inherited === null)
+                        .flatMap((source) => insideBundle(directory, item.data.cwd, source.source)),
+                    mounts: (0, work_task_1.isContainerWorkTask)(item.data)
+                        ? item.data.mounts.flatMap((mount) => insideBundle(directory, item.data.cwd, mount.localPath))
+                        : [],
+                    deps: item.deps.map((dep) => dep.name).sort(),
+                    needs: item.needs.map((need) => need.name).sort(),
+                };
+            }
+            return {
+                tasks: Object.keys(context.tasks).sort(),
+                services: Object.keys(context.services).sort(),
+                inputs: Object.fromEntries(Object.entries(inputs).sort(([a], [b]) => (a < b ? -1 : 1))),
+            };
+        }
+        catch (e) {
+            throw new DefinitionError((0, log_1.getErrorMessage)(e).split(directory).join('.'));
+        }
+    }
+    finally {
+        await (0, promises_1.rm)(directory, { recursive: true, force: true });
+    }
+}
+exports.inspectBundle = inspectBundle;
+// The published build files: immutable versions, each named by its hash. They
+// are kept in files, so a restart doesn't forget what runs were started from.
+class DefinitionStore {
+    constructor(directory, environment, now = Date.now) {
+        this.directory = directory;
+        this.environment = environment;
+        this.now = now;
+        this.versions = new Map();
+    }
+    async load() {
+        let names = [];
+        try {
+            names = await (0, promises_1.readdir)(this.directory);
+        }
+        catch {
+            return; // nothing was published yet
+        }
+        for (const name of names) {
+            for (const file of await (0, promises_1.readdir)((0, path_1.join)(this.directory, name))) {
+                if (!file.endsWith('.json')) {
+                    continue;
+                }
+                const stored = JSON.parse(await (0, promises_1.readFile)((0, path_1.join)(this.directory, name, file), 'utf8'));
+                this.add(stored.version);
+            }
+        }
+    }
+    names() {
+        return [...this.versions.keys()].sort();
+    }
+    // newest first
+    list(name) {
+        return this.has(name) ? [...this.versions.get(name)] : [];
+    }
+    // a hash, or `latest` for the version published last
+    find(name, hash) {
+        const versions = this.list(name);
+        return hash === 'latest' ? versions[0] : versions.find((v) => v.hash === hash);
+    }
+    async files(version) {
+        try {
+            return JSON.parse(await (0, promises_1.readFile)(this.file(version.name, version.hash), 'utf8')).bundle;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // Reads a bundle the way a run would and says what it would be as a version;
+    // `existing` is the published version with the same hash, if there is one.
+    async prepare(name, bundle, publisher) {
+        const hash = (0, bundle_1.hashBundle)(bundle);
+        const existing = this.find(name, hash);
+        if (existing) {
+            return { version: existing, existing };
+        }
+        const { tasks, services, inputs } = await inspectBundle(bundle, this.environment);
+        return {
+            version: {
+                name,
+                hash,
+                entry: bundle.entry,
+                publishedAt: new Date(this.now()).toISOString(),
+                publishedBy: { iss: publisher.iss, sub: publisher.sub },
+                tasks,
+                services,
+                inputs,
+            },
+        };
+    }
+    // Publishing what already is there changes nothing and says so.
+    async publish(name, bundle, publisher, approvedBy) {
+        const prepared = await this.prepare(name, bundle, publisher);
+        if (prepared.existing) {
+            return { version: prepared.existing, created: false };
+        }
+        const version = {
+            ...prepared.version,
+            publishedAt: new Date(this.now()).toISOString(),
+            ...(approvedBy ? { approvedBy: { iss: approvedBy.iss, sub: approvedBy.sub } } : {}),
+        };
+        const file = this.file(name, version.hash);
+        await (0, promises_1.mkdir)((0, path_1.dirname)(file), { recursive: true });
+        const temporary = `${file}.${(0, crypto_1.randomBytes)(8).toString('hex')}.tmp`;
+        await (0, promises_1.writeFile)(temporary, JSON.stringify({ version, bundle }), { flag: 'wx' });
+        await (0, promises_1.rename)(temporary, file);
+        this.add(version);
+        return { version, created: true };
+    }
+    has(name) {
+        return this.versions.has(name);
+    }
+    add(version) {
+        const versions = this.versions.get(version.name) ?? [];
+        versions.unshift(version);
+        versions.sort((a, b) => b.publishedAt.localeCompare(a.publishedAt));
+        this.versions.set(version.name, versions);
+    }
+    file(name, hash) {
+        if (!bundle_1.HASH_PATTERN.test(hash)) {
+            throw new DefinitionError('invalid hash');
+        }
+        return (0, path_1.join)(this.directory, name, `${hash.slice('sha256:'.length)}.json`);
+    }
+}
+exports.DefinitionStore = DefinitionStore;
+//# sourceMappingURL=definitions.js.map

package/dist/server/discovery.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISCOVERY_PATH = exports.SERVER_PROTOCOL = void 0;
+// What a client needs to know about a server before it signs in. Kept apart from
+// the server so the client does not load the http server and token code.
+// Bumped when a client could no longer talk to an older or newer server.
+exports.SERVER_PROTOCOL = 1;
+exports.DISCOVERY_PATH = '/.well-known/hammerkit';
+//# sourceMappingURL=discovery.js.map