hammerkit 1.27.0-next.21 → 1.27.0-next.23

package/build.schema.json

@@ -296,6 +296,9 @@
                     "type": "string",
                     "minLength": 1
                   },
+                  "publish": {
+                    "type": "boolean"
+                  },
                   "image": {
                     "type": "string"
                   },
@@ -308,6 +311,56 @@
                   "volumeSize": {
                     "type": "string",
                     "description": "size of its claim on Kubernetes, e.g. 10Gi"
+                  },
+                  "capAdd": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "enum": [
+                        "AUDIT_CONTROL",
+                        "AUDIT_READ",
+                        "AUDIT_WRITE",
+                        "BLOCK_SUSPEND",
+                        "BPF",
+                        "CHECKPOINT_RESTORE",
+                        "CHOWN",
+                        "DAC_OVERRIDE",
+                        "DAC_READ_SEARCH",
+                        "FOWNER",
+                        "FSETID",
+                        "IPC_LOCK",
+                        "IPC_OWNER",
+                        "KILL",
+                        "LEASE",
+                        "LINUX_IMMUTABLE",
+                        "MAC_ADMIN",
+                        "MAC_OVERRIDE",
+                        "MKNOD",
+                        "NET_ADMIN",
+                        "NET_BIND_SERVICE",
+                        "NET_BROADCAST",
+                        "NET_RAW",
+                        "PERFMON",
+                        "SETFCAP",
+                        "SETGID",
+                        "SETPCAP",
+                        "SETUID",
+                        "SYS_ADMIN",
+                        "SYS_BOOT",
+                        "SYS_CHROOT",
+                        "SYS_MODULE",
+                        "SYS_NICE",
+                        "SYS_PACCT",
+                        "SYS_PTRACE",
+                        "SYS_RAWIO",
+                        "SYS_RESOURCE",
+                        "SYS_TIME",
+                        "SYS_TTY_CONFIG",
+                        "SYSLOG",
+                        "WAKE_ALARM"
+                      ]
+                    },
+                    "description": "Linux capabilities added to the container, e.g. [SYS_ADMIN]"
                   }
                 },
                 "required": [
@@ -379,6 +432,9 @@
                   "runner": {
                     "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/runner"
                   },
+                  "publish": {
+                    "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/publish"
+                  },
                   "platform": {
                     "type": "object",
                     "properties": {
@@ -520,6 +576,9 @@
                   },
                   "args": {
                     "type": "boolean"
+                  },
+                  "publish": {
+                    "type": "boolean"
                   }
                 },
                 "required": [
@@ -576,6 +635,9 @@
                         "number"
                       ]
                     }
+                  },
+                  "publish": {
+                    "type": "boolean"
                   }
                 },
                 "required": [
@@ -606,6 +668,10 @@
                   "with": {
                     "$ref": "#/definitions/hammerkit/properties/envs",
                     "description": "Environment values for the current build task\nhttps://hammerkit.dev/docs/build-file/environment-variables"
+                  },
+                  "publish": {
+                    "type": "boolean",
+                    "description": "false: a server leaves out what this file declares"
                   }
                 },
                 "required": [
@@ -633,6 +699,10 @@
                   "with": {
                     "$ref": "#/definitions/hammerkit/properties/envs",
                     "description": "Environment values for the current build task\nhttps://hammerkit.dev/docs/build-file/environment-variables"
+                  },
+                  "publish": {
+                    "type": "boolean",
+                    "description": "false: a server leaves out what this file declares"
                   }
                 },
                 "required": [

package/dist/executer/docker-task.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dockerTask = exports.buildCreateOptions = void 0;
+exports.dockerTask = exports.getCapabilityHostConfig = exports.buildCreateOptions = void 0;
 const run_labels_1 = require("../docker/run-labels");
 const execute_docker_1 = require("./execute-docker");
 const abort_1 = require("./abort");
@@ -47,10 +47,30 @@ function buildCreateOptions(item, stateKey, network, environment, secrets, resou
             ...(0, item_network_1.getNetworkHostConfig)(network),
             AutoRemove: true,
             ...resources,
+            ...getCapabilityHostConfig(item, environment),
         },
     };
 }
 exports.buildCreateOptions = buildCreateOptions;
+/**
+ * The capabilities a task adds (`capAdd`). On a server they are only granted in the
+ * sandboxed runtime of `backend.capabilities`, never by the kernel of the docker host.
+ */
+function getCapabilityHostConfig(item, environment) {
+    const capAdd = item.data.capAdd;
+    if (capAdd.length === 0) {
+        return {};
+    }
+    if (!environment.hosted) {
+        return { CapAdd: capAdd };
+    }
+    const runtime = environment.hosted.capabilityRuntime;
+    if (!runtime) {
+        throw new Error(`${item.name}: adds the capabilities ${capAdd.join(', ')}, which this server grants in no sandboxed runtime`);
+    }
+    return { CapAdd: capAdd, Runtime: runtime };
+}
+exports.getCapabilityHostConfig = getCapabilityHostConfig;
 async function dockerTask(docker, item, environment, options) {
     item.status.write('info', `execute ${item.name} in container`);
     let network = null;

package/dist/kubernetes/job-placement.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getContainerSecurity = exports.getRunLabels = exports.getRunLabelValue = exports.RUN_LABEL = exports.getPodPlacement = exports.placeOnPool = exports.getNodeArch = exports.runInToolImage = exports.getLocalTaskPool = void 0;
+exports.getPodRuntimeClass = exports.getContainerSecurity = exports.getRunLabels = exports.getRunLabelValue = exports.RUN_LABEL = exports.getPodPlacement = exports.placeOnPool = exports.getNodeArch = exports.runInToolImage = exports.getLocalTaskPool = void 0;
 const crypto_1 = require("crypto");
 /**
  * The pool a local task runs on: the first that offers its platform. A pool says
@@ -34,6 +34,7 @@ function runInToolImage(task, server, platform) {
         user: null,
         mounts: [],
         volumeSize: null,
+        capAdd: [],
         pool: pool.name,
         arch: getNodeArch(pool),
     };
@@ -82,18 +83,41 @@ exports.getRunLabels = getRunLabels;
 /**
  * What a container of a run may do on a server, where it shares nodes with the pods of
  * other callers: no privilege escalation (setuid binaries such as sudo), no raw sockets
- * (spoofing on a bridge network) and the runtime's seccomp profile.
+ * (spoofing on a bridge network) and the runtime's seccomp profile. The capabilities a
+ * task adds (`capAdd`) come on top, in the sandbox of getPodRuntimeClass on a server.
  */
-function getContainerSecurity(kubernetes) {
-    return kubernetes.server
-        ? {
-            securityContext: {
-                allowPrivilegeEscalation: false,
-                capabilities: { drop: ['NET_RAW'] },
-                seccompProfile: { type: 'RuntimeDefault' },
-            },
-        }
-        : {};
+function getContainerSecurity(kubernetes, capAdd = []) {
+    const add = capAdd.length > 0 ? { add: [...capAdd] } : {};
+    if (!kubernetes.server) {
+        return capAdd.length > 0 ? { securityContext: { capabilities: add } } : {};
+    }
+    const drop = capAdd.includes('NET_RAW') ? {} : { drop: ['NET_RAW'] };
+    return {
+        securityContext: {
+            allowPrivilegeEscalation: false,
+            capabilities: { ...drop, ...add },
+            seccompProfile: { type: 'RuntimeDefault' },
+        },
+    };
 }
 exports.getContainerSecurity = getContainerSecurity;
+/**
+ * The RuntimeClass of the pod of a task that adds capabilities on a server: the sandbox the
+ * operator named (`backend.capabilities.runtimeClass`), so the capabilities hold in its own
+ * kernel and never in the node's. Elsewhere the cluster is the build file's own.
+ */
+function getPodRuntimeClass(task, kubernetes) {
+    if (task.capAdd.length === 0 || !kubernetes.server) {
+        return {};
+    }
+    const sandbox = kubernetes.server.capabilities;
+    if (!sandbox) {
+        throw new Error(`${task.name}: adds the capabilities ${task.capAdd.join(', ')}, which this server grants in no sandboxed runtime`);
+    }
+    if (sandbox.unavailable) {
+        throw new Error(`${task.name}: adds the capabilities ${task.capAdd.join(', ')}, but ${sandbox.unavailable}`);
+    }
+    return { runtimeClassName: sandbox.runtimeClass };
+}
+exports.getPodRuntimeClass = getPodRuntimeClass;
 //# sourceMappingURL=job-placement.js.map

package/dist/kubernetes/sandbox-runner.js

@@ -151,7 +151,9 @@ function canUseRunner(task, kubernetes, persistence) {
         persistence.mounts.some((mount) => (0, path_1.relative)(workspace.root, mount.mount.mountPath) === '') &&
         task.needs.length === 0 &&
         task.data.secrets.length === 0 &&
-        task.data.generates.length === 0);
+        task.data.generates.length === 0 &&
+        // its pod would need the sandboxed runtime of a Job
+        task.data.capAdd.length === 0);
 }
 exports.canUseRunner = canUseRunner;
 // What the runner is made of: the same key for the same pod

package/dist/planner/utils/append-work-task.js

@@ -92,10 +92,12 @@ function parseTask(cwd, task, environment, context) {
         return {
             ...baseWorkNode,
             type: 'container-task',
-            user: (0, get_container_user_1.getContainerUser)(),
+            // a capability holds for root only: a task that adds some runs as its image's user
+            user: task.schema.capAdd?.length ? null : (0, get_container_user_1.getContainerUser)(),
             image: (0, template_value_1.templateValue)(task.schema.image, envs),
             mounts: (0, parse_work_mounts_1.parseWorkMounts)(cwd, task.schema, envs),
             volumeSize: task.schema.volumeSize ?? null,
+            capAdd: task.schema.capAdd ?? [],
         };
     }
     else {

package/dist/planner/work-runtime-kubernetes.js

@@ -130,7 +130,8 @@ exports.describeFailedJob = describeFailedJob;
  * The containers of the Job of a command: the network gate first, nothing runs before the
  * item's policy holds, then the init containers that read its secrets, then the command. The
  * proxy's token (`network.secretEnv`) reaches the init containers through `secretSpec` only:
- * the command's container gets the proxy variables of a limited network without it.
+ * the command's container gets the proxy variables of a limited network without it. A task that
+ * adds capabilities gets them in the sandbox's RuntimeClass only.
  */
 function getTaskJobContainers(options) {
     const { task, cmd, envs, secrets, network, secretSpec, kubernetes } = options;
@@ -155,9 +156,10 @@ function getTaskJobContainers(options) {
                 name: options.container,
                 volumeMounts: [...options.mounts, ...secrets.mounts, ...secretSpec.mounts],
                 ...(0, container_resources_1.getKubernetesResources)(task.data.resources),
-                ...(0, job_placement_1.getContainerSecurity)(kubernetes),
+                ...(0, job_placement_1.getContainerSecurity)(kubernetes, task.data.capAdd),
             },
         ],
+        ...(0, job_placement_1.getPodRuntimeClass)({ name: task.name, capAdd: task.data.capAdd }, kubernetes),
     };
 }
 exports.getTaskJobContainers = getTaskJobContainers;

package/dist/remote/host-config.js

@@ -5,6 +5,7 @@ const path_1 = require("path");
 const zod_1 = require("zod");
 const yaml_1 = require("yaml");
 const get_cache_directory_1 = require("../optimizer/get-cache-directory");
+const build_file_secret_provider_schema_1 = require("../schema/build-file-secret-provider-schema");
 // Names with a meaning of their own in `run.on` / `--on`
 exports.RESERVED_SERVER_NAMES = ['local', 'auto'];
 const serverNamePattern = /^[a-z0-9][a-z0-9._-]*$/i;
@@ -43,6 +44,10 @@ exports.hostConfigSchema = zod_1.z
     servers: zod_1.z.record(exports.hostServerSchema).default({}),
     tokenCommands: zod_1.z.record(tokenCommandSchema).optional(),
     run: zod_1.z.object({ on: zod_1.z.string().optional() }).passthrough().default({}),
+    // how this machine reads secrets, beside what the build files declare (see
+    // collectSecretCatalog); a server reads only its own config
+    secretProviders: build_file_secret_provider_schema_1.buildFileSecretProvidersSchema.optional(),
+    secretAccounts: build_file_secret_provider_schema_1.buildFileSecretAccountsSchema.optional(),
 })
     .passthrough();
 // Names like "constructor" must not find inherited members.

package/dist/remote/remote-work-commands.js

@@ -17,6 +17,22 @@ const units_1 = require("../utils/units");
 const service_tools_1 = require("../harness/service-tools");
 const path_1 = require("path");
 const check_keys_1 = require("../optimizer/check-keys");
+function describeOutcome(planned) {
+    switch (planned.outcome) {
+        case 'published':
+            return 'publishing it would publish it';
+        case 'already published':
+            return planned.yanked ? 'it is published already, and yanked' : 'it is published already';
+        case 'proposed':
+            return planned.missing?.length
+                ? `publishing it would propose it, it names accounts you do not use: ${planned.missing
+                    .map(server_client_1.printable)
+                    .join(', ')}`
+                : 'publishing it would propose it, somebody who may publish approves it';
+        default:
+            return 'the server accepts it, publishing it needs builds: propose or publish';
+    }
+}
 const RUN_ID = /^run_[A-Za-z0-9_-]{16}$/;
 // how a check passed, one line
 function describePassed(passed) {
@@ -106,6 +122,7 @@ function describePlan(plan) {
         ...(entry.mounts.length > 0 ? [`    mounts: ${entry.mounts.map(server_client_1.printable).join(', ')}`] : []),
         ...(entry.ports.length > 0 ? [`    ports: ${entry.ports.map(server_client_1.printable).join(', ')}`] : []),
         ...(entry.generates.length > 0 ? [`    generates: ${entry.generates.map(server_client_1.printable).join(', ')}`] : []),
+        ...(entry.capAdd?.length ? [`    capAdd: ${entry.capAdd.map(server_client_1.printable).join(', ')}`] : []),
     ]);
 }
 exports.describePlan = describePlan;
@@ -136,8 +153,24 @@ function registerWorkCommands(remote, context) {
         .command('publish [server]')
         .description('publish the build file and the files it includes to a server, runs refer to it by its hash')
         .addOption(new commander_1.Option('--annotation <key=value>', 'say more about where it comes from, or leave one out with key=; path, repo, commit, machine and user are filled in').argParser(collectOption))
+        .addOption(new commander_1.Option('--dry-run', "check it against the server's policy and say what publishing would do, without publishing; builds: run is enough"))
         .action(guarded('Remote publish was not successful', async (name, options) => {
         const bundle = await (0, collect_bundle_1.collectBundle)(buildFile, environment);
+        if (options.dryRun) {
+            const { name: serverName, server, token } = await connect(name);
+            const answer = await (0, server_client_1.callServer)(server, token, 'POST', '/v1/definitions/plan', bundle).catch((e) => {
+                throw e instanceof server_client_1.ServerError && e.status === 404
+                    ? new Error(`${serverName} can't check a build file without publishing it, it needs hammerkit 1.27`)
+                    : e;
+            });
+            const planned = answer.body;
+            const files = Object.keys(bundle.files).length;
+            environment.stdout.write(`checked with the policy of ${serverName}: ${(0, server_client_1.printable)(planned.hash)} (${files} ${files === 1 ? 'file' : 'files'}), nothing was published\n`);
+            const names = [...(planned.tasks ?? []), ...(planned.services ?? [])];
+            environment.stdout.write(`tasks and services: ${names.map(server_client_1.printable).join(', ') || 'none'}\n`);
+            environment.stdout.write(`${describeOutcome(planned)}\n`);
+            return;
+        }
         const annotations = (0, annotations_1.applyAnnotations)(await (0, annotations_1.collectAnnotations)(buildFile, Object.keys(bundle.files)), options.annotation ?? []);
         const { name: serverName, server, token } = await connect(name);
         const answer = await (0, server_client_1.callServer)(server, token, 'POST', '/v1/definitions', {

package/dist/schema/build-file-base-task-schema.js

@@ -49,5 +49,8 @@ exports.buildFileBaseTaskSchema = (0, zod_1.object)({
     // Name of the server (see `hammerkit remote`) the task has to run on; defaults
     // to the build file's `runner`. Never a local fallback when it is unknown.
     runner: runner_schema_1.runnerSchema.optional(),
+    // false: a server leaves it out of a published version, for a task only this machine
+    // runs (a dev watcher, a task that mounts the docker socket)
+    publish: (0, zod_1.boolean)().optional(),
 });
 //# sourceMappingURL=build-file-base-task-schema.js.map

package/dist/schema/build-file-container-service-schema.js

@@ -47,6 +47,8 @@ exports.buildFileContainerServiceSchema = (0, zod_1.object)({
     network: network_schema_1.networkSchema.optional(),
     // whether its `cmd` takes the arguments after `--` of `up`: false refuses them
     args: (0, zod_1.boolean)().optional(),
+    // false: a server leaves it out of a published version
+    publish: (0, zod_1.boolean)().optional(),
 })
     .strict()
     .describe('container service');

package/dist/schema/build-file-container-task-schema.js

@@ -4,12 +4,16 @@ exports.buildFileContainerTaskSchema = void 0;
 const build_file_base_task_schema_1 = require("./build-file-base-task-schema");
 const zod_1 = require("zod");
 const size_schema_1 = require("./size-schema");
+const capabilities_schema_1 = require("./capabilities-schema");
 exports.buildFileContainerTaskSchema = build_file_base_task_schema_1.buildFileBaseTaskSchema
     .extend({
     image: (0, zod_1.string)(),
     mounts: (0, zod_1.array)((0, zod_1.string)()).optional(),
     // on Kubernetes, the size of the claim that holds its sources, mounts and outputs
     volumeSize: size_schema_1.sizeSchema.describe('size of its claim on Kubernetes, e.g. 10Gi').optional(),
+    // Linux capabilities added to the container, such as SYS_ADMIN for a daemonless image
+    // build. A server allows them only in a sandboxed runtime (`backend.capabilities`).
+    capAdd: capabilities_schema_1.capabilitiesSchema.describe('Linux capabilities added to the container, e.g. [SYS_ADMIN]').optional(),
 })
     .strict()
     .describe('container task');

package/dist/schema/build-file-include-schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isGitSource = exports.buildFileIncludeSchema = exports.buildFileLocalSourceSchema = exports.buildFileGitSourceSchema = void 0;
+exports.isPublished = exports.isGitSource = exports.buildFileIncludeSchema = exports.buildFileLocalSourceSchema = exports.buildFileGitSourceSchema = void 0;
 const zod_1 = require("zod");
 const envs_schema_1 = require("./envs-schema");
 // A repo URL or ref starting with `-` would be read by git as an option
@@ -21,17 +21,25 @@ exports.buildFileGitSourceSchema = (0, zod_1.object)({
     path: (0, zod_1.string)().optional().describe('Build file or directory within the repository'),
     // overrides for the top-level `envs` the included file declares as its inputs
     with: envs_schema_1.envsSchema.optional(),
+    publish: (0, zod_1.boolean)().optional().describe('false: a server leaves out what this file declares'),
 }).strict();
-// A local path with values for the inputs of the file it names, like `with` of a git
-// source. A value may pass on an `envs` value of the including file as `${NAME}`.
+// A local path, with values for the inputs of the file it names like `with` of a git
+// source (a value may pass on an `envs` value of the including file as `${NAME}`), and
+// whether a server publishes what it declares.
 exports.buildFileLocalSourceSchema = (0, zod_1.object)({
     path: (0, zod_1.string)().min(1).describe('Build file or directory, relative to the including file'),
     with: envs_schema_1.envsSchema.optional(),
+    publish: (0, zod_1.boolean)().optional().describe('false: a server leaves out what this file declares'),
 }).strict();
-// A string is a local path; an object is a local path with inputs, or a git source (ADR-0004).
+// A string is a local path; an object is a local path with options, or a git source (ADR-0004).
 exports.buildFileIncludeSchema = (0, zod_1.union)([(0, zod_1.string)(), exports.buildFileLocalSourceSchema, exports.buildFileGitSourceSchema]);
 function isGitSource(include) {
     return typeof include !== 'string' && 'git' in include;
 }
 exports.isGitSource = isGitSource;
+// `publish: false`: what the file declares is left out of a version a server publishes
+function isPublished(include) {
+    return typeof include === 'string' || include.publish !== false;
+}
+exports.isPublished = isPublished;
 //# sourceMappingURL=build-file-include-schema.js.map

package/dist/schema/build-file-kubernetes-service-schema.js

@@ -13,5 +13,7 @@ exports.buildFileKubernetesServiceSchema = (0, zod_1.object)({
     selector: build_file_kubernetes_service_selector_schema_1.buildFileKubernetesServiceSelectorSchema,
     labels: labels_schema_1.labelsSchema.optional(),
     ports: (0, zod_1.array)((0, zod_1.union)([(0, zod_1.string)(), (0, zod_1.number)()])),
+    // false: a server leaves it out of a published version
+    publish: (0, zod_1.boolean)().optional(),
 }).strict();
 //# sourceMappingURL=build-file-kubernetes-service-schema.js.map

package/dist/schema/capabilities-schema.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capabilitiesSchema = exports.LINUX_CAPABILITIES = void 0;
+const zod_1 = require("zod");
+// The Linux capabilities, without the CAP_ prefix (capabilities(7))
+exports.LINUX_CAPABILITIES = [
+    'AUDIT_CONTROL',
+    'AUDIT_READ',
+    'AUDIT_WRITE',
+    'BLOCK_SUSPEND',
+    'BPF',
+    'CHECKPOINT_RESTORE',
+    'CHOWN',
+    'DAC_OVERRIDE',
+    'DAC_READ_SEARCH',
+    'FOWNER',
+    'FSETID',
+    'IPC_LOCK',
+    'IPC_OWNER',
+    'KILL',
+    'LEASE',
+    'LINUX_IMMUTABLE',
+    'MAC_ADMIN',
+    'MAC_OVERRIDE',
+    'MKNOD',
+    'NET_ADMIN',
+    'NET_BIND_SERVICE',
+    'NET_BROADCAST',
+    'NET_RAW',
+    'PERFMON',
+    'SETFCAP',
+    'SETGID',
+    'SETPCAP',
+    'SETUID',
+    'SYS_ADMIN',
+    'SYS_BOOT',
+    'SYS_CHROOT',
+    'SYS_MODULE',
+    'SYS_NICE',
+    'SYS_PACCT',
+    'SYS_PTRACE',
+    'SYS_RAWIO',
+    'SYS_RESOURCE',
+    'SYS_TIME',
+    'SYS_TTY_CONFIG',
+    'SYSLOG',
+    'WAKE_ALARM',
+];
+// Capabilities a container gets on top of its runtime's default set, by name such as
+// SYS_ADMIN. `ALL` is not one: a task names what it needs.
+exports.capabilitiesSchema = (0, zod_1.array)((0, zod_1.enum)(exports.LINUX_CAPABILITIES, {
+    errorMap: (issue, ctx) => issue.code === 'invalid_enum_value'
+        ? { message: `unknown capability ${JSON.stringify(issue.received)}, expected a name such as SYS_ADMIN` }
+        : { message: ctx.defaultError },
+})).refine((names) => new Set(names).size === names.length, 'a capability is listed twice');
+//# sourceMappingURL=capabilities-schema.js.map