hammerkit 1.23.0 → 1.25.0

package/dist/server/server-config.js

@@ -0,0 +1,394 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectPlatform = exports.getSecretCatalog = exports.readServerConfig = exports.getSourceAccounts = exports.serverConfigSchema = exports.sourceSchema = exports.entitlementSchema = exports.buildsLevelSchema = exports.accountLevelSchema = exports.accountSchema = exports.definitionName = exports.issuerSchema = exports.serverPlatformSchema = void 0;
+const zod_1 = require("zod");
+const yaml_1 = require("yaml");
+const log_1 = require("../log");
+const units_1 = require("../utils/units");
+const build_file_secret_provider_schema_1 = require("../schema/build-file-secret-provider-schema");
+const repo_1 = require("./repo");
+const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '::1'];
+exports.serverPlatformSchema = zod_1.z
+    .object({
+    os: zod_1.z.enum(['linux', 'macos', 'windows']),
+    arch: zod_1.z.enum(['amd64', 'arm64']),
+})
+    .strict();
+// The issuer is compared with the `iss` of a token as written, and its keys are
+// fetched from it, so it has to be https (http only for local testing).
+const issuerUrlSchema = zod_1.z.string().refine((value) => {
+    try {
+        const url = new URL(value);
+        return (url.protocol === 'https:' ||
+            (url.protocol === 'http:' && LOOPBACK_HOSTS.includes(url.hostname.replace(/^\[|\]$/g, ''))));
+    }
+    catch {
+        return false;
+    }
+}, 'issuer must be an https url (http only for localhost)');
+exports.issuerSchema = zod_1.z
+    .object({
+    issuer: issuerUrlSchema,
+    audience: zod_1.z.string().min(1),
+    // the claim listing the groups of the caller
+    groupsClaim: zod_1.z.string().min(1).default('groups'),
+    // the public OAuth client `remote login` signs in with (device authorization
+    // grant); without one this issuer can only be used with a token obtained
+    // elsewhere, such as a CI job's or an agent's own
+    clientId: zod_1.z.string().min(1).optional(),
+    // what the login asks for, such as `openid api://hammerkit/.default`
+    scope: zod_1.z.string().min(1).default('openid'),
+})
+    .strict();
+// What a published build file is called: the project, as a build file author names it.
+exports.definitionName = zod_1.z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9._-]{0,63}$/i, 'use letters, digits, ".", "_" and "-", starting with a letter or digit');
+const subjectSchema = zod_1.z.object({ iss: zod_1.z.string().min(1), sub: zod_1.z.string().min(1) }).strict();
+const groupSchema = zod_1.z.object({ iss: zod_1.z.string().min(1), name: zod_1.z.string().min(1) }).strict();
+const claimsSchema = zod_1.z.object({ iss: zod_1.z.string().min(1), match: zod_1.z.record(zod_1.z.string()) }).strict();
+// Who: the person or client (`subject`), everyone in a group of an issuer
+// (`group`), or any token of an issuer whose claims match (`claims`, for CI jobs:
+// repository, ref, environment). Only validated token claims are matched.
+const whoShape = {
+    subject: subjectSchema.optional(),
+    group: groupSchema.optional(),
+    claims: claimsSchema.optional(),
+};
+function checkWho(who, ctx) {
+    const named = [who.subject, who.group, who.claims].filter((w) => w !== undefined);
+    if (named.length !== 1) {
+        ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, message: 'name exactly one of subject, group or claims' });
+    }
+    if (who.claims && Object.keys(who.claims.match).length === 0) {
+        ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ['claims', 'match'], message: 'match at least one claim' });
+    }
+}
+// The service accounts a server knows. A run never names one: the accounts it
+// uses are the ones its secrets are read as, and an entitlement says who may use
+// or only request each.
+const accountNameSchema = zod_1.z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9_-]*$/, 'a name starts with a letter and holds letters, digits, - and _');
+exports.accountSchema = zod_1.z
+    .object({
+    description: zod_1.z.string().min(1).max(200).optional(),
+    // per secret provider, the environment that makes its command act as this
+    // account; the credentials are files and variables of the operator's machine
+    providers: build_file_secret_provider_schema_1.buildFileSecretAccountSchema.shape.providers.default({}),
+    // where the code of a run using this account may come from; both when left out
+    source: zod_1.z
+        .array(zod_1.z.enum(['upload', 'ref']))
+        .min(1)
+        .optional(),
+    // the refs (branches or tags, `release/*` for a level) a run using this account
+    // may be started from; a commit is not accepted then, it names no branch
+    refs: zod_1.z.array(zod_1.z.string().min(1).max(200)).min(1).optional(),
+})
+    .strict()
+    .superRefine((account, ctx) => {
+    if (account.refs && (account.source?.length !== 1 || account.source[0] !== 'ref')) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['refs'],
+            message: 'refs only restricts runs from a git ref, set source: [ref] too, an upload names no ref',
+        });
+    }
+});
+exports.accountLevelSchema = zod_1.z.enum(['use', 'request']);
+// What a caller may do with the build files: run what is published, propose new
+// versions that someone else approves, or publish. Each level includes the lower.
+exports.buildsLevelSchema = zod_1.z.enum(['run', 'propose', 'publish']);
+const repoPatternSchema = zod_1.z.string().refine(repo_1.isRepoPattern, 'expected host/path, such as github.com/corp/*');
+exports.entitlementSchema = zod_1.z
+    .object({
+    ...whoShape,
+    // `use`: runs on the account at once and approves the runs others request on it;
+    // `request`: runs wait until somebody who may `use` the account approves them
+    accounts: zod_1.z.record(accountNameSchema, exports.accountLevelSchema).default({}),
+    // the repositories (`host/path` patterns) the caller may run from a git ref
+    repos: zod_1.z.array(repoPatternSchema).default([]),
+    builds: exports.buildsLevelSchema.optional(),
+})
+    .strict()
+    .superRefine((entitlement, ctx) => {
+    checkWho(entitlement, ctx);
+    if (Object.keys(entitlement.accounts).length === 0 && entitlement.builds === undefined) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'name accounts to use or request, or a builds level',
+        });
+    }
+});
+// A repository the server can read: `github.com/corp/*` for an organisation,
+// `gitlab.corp.com/platform/**` for a group with its subgroups. The credential is a
+// secret of a provider, read as `account`, and handed to git for that fetch only.
+exports.sourceSchema = zod_1.z
+    .object({
+    match: repoPatternSchema,
+    secret: zod_1.z
+        .object({
+        from: zod_1.z.string().regex(/^[A-Za-z][A-Za-z0-9_-]*:.+$/, 'expected provider:reference'),
+        account: accountNameSchema,
+        // the user name of the basic authentication the token is sent with
+        username: zod_1.z.string().min(1).default('x-access-token'),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+const duration = zod_1.z.string().refine((value) => {
+    try {
+        return (0, units_1.parseDuration)(value) > 0;
+    }
+    catch {
+        return false;
+    }
+}, 'expected a duration like 30m, 1h or 1d');
+// The server config is written by an operator and reviewed like code, so a typo
+// is an error and not a silently ignored key.
+exports.serverConfigSchema = zod_1.z
+    .object({
+    listen: zod_1.z
+        .object({
+        host: zod_1.z.string().min(1).default('127.0.0.1'),
+        port: zod_1.z.number().int().min(0).max(65535).default(8480),
+    })
+        .strict()
+        .default({}),
+    // paths of a certificate and key
+    tls: zod_1.z
+        .object({ cert: zod_1.z.string().min(1), key: zod_1.z.string().min(1) })
+        .strict()
+        .optional(),
+    // plain http carries OAuth tokens, so it is only accepted on the loopback
+    // interface, or when a proxy in front terminates TLS and this says so
+    behindTlsProxy: zod_1.z.boolean().default(false),
+    // the OAuth issuers whose tokens the server accepts, and the audience those
+    // tokens have to carry
+    issuers: zod_1.z.array(exports.issuerSchema).min(1, 'at least one issuer is needed, OAuth is the only way to call the server'),
+    // the service accounts, and the commands that read secrets as them; a build file
+    // can not declare either, only name an account on its secrets
+    accounts: zod_1.z.record(accountNameSchema, exports.accountSchema).default({}),
+    secretProviders: build_file_secret_provider_schema_1.buildFileSecretProvidersSchema.default({}),
+    // who may use which service account and which build files; default deny
+    entitlements: zod_1.z.array(exports.entitlementSchema).default([]),
+    approvals: zod_1.z
+        .object({
+        // how long a run waits for its approval before it is rejected
+        timeout: duration.default('1h'),
+        // runs waiting at the same time, more are refused
+        maxWaiting: zod_1.z.number().int().min(1).default(100),
+        // after a version was rejected, who proposed it can not propose that build
+        // file again, and nobody that version, for this long
+        cooldown: duration.default('10m'),
+    })
+        .strict()
+        .default({}),
+    // the repositories a run may get its code from, as patterns of `host/path`, and
+    // the secret that reads them: a token in a secret provider, read as a service
+    // account of the operator. The caller names a repository and a ref in the request,
+    // never a url.
+    sources: zod_1.z.array(exports.sourceSchema).default([]),
+    // what tasks may run on: containers, and the local runtime that runs commands on
+    // this machine as the user of the server. Local tasks read the whole file system of that
+    // user, so they have to be allowed by name.
+    runtimes: zod_1.z
+        .array(zod_1.z.enum(['docker', 'local']))
+        .min(1)
+        .default(['docker']),
+    // where the server keeps what must survive a restart: the published build files
+    storage: zod_1.z
+        .object({ directory: zod_1.z.string().min(1).optional() })
+        .strict()
+        .default({}),
+    // limits of the run registry
+    runs: zod_1.z
+        .object({
+        // runs that execute at the same time, the others wait in queue
+        maxConcurrent: zod_1.z.number().int().min(1).default(4),
+        // finished runs that are kept for their state and logs
+        keep: zod_1.z.number().int().min(1).default(200),
+        // what one caller (issuer and subject) may have at a time, so a single
+        // caller can not take the whole machine; over it a request gets 429
+        limits: zod_1.z
+            .object({
+            // runs that wait for an approval
+            waiting: zod_1.z.number().int().min(1).default(10),
+            // runs that wait in the queue for a free place
+            queued: zod_1.z.number().int().min(1).default(20),
+            // runs that execute at the same time, the others wait in the queue
+            running: zod_1.z.number().int().min(1).default(2),
+        })
+            .strict()
+            .default({}),
+        // a run that executes longer is stopped and fails
+        maxDuration: duration.default('1h'),
+        // log output kept per run; the rest is cut off
+        maxLogBytes: zod_1.z
+            .number()
+            .int()
+            .min(1024)
+            .default(1024 * 1024),
+        // the environment of a run: the variables of the server process that tasks
+        // (and the git fetch) can see. Nothing else of the server's environment
+        // is passed on, so there is no list built in; an operator names what the
+        // tools of the host need, such as PATH and DOCKER_HOST.
+        env: zod_1.z
+            .object({
+            allow: zod_1.z.array(zod_1.z.string().regex(/^[A-Za-z_][A-Za-z0-9_()]*$/)).default([]),
+            // fixed values that are set in addition
+            set: zod_1.z.record(zod_1.z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), zod_1.z.string()).default({}),
+        })
+            .strict()
+            .default({}),
+    })
+        .strict()
+        .default({}),
+    backend: zod_1.z
+        .object({
+        type: zod_1.z.literal('host'),
+        // what this machine offers; detected when left out
+        platform: exports.serverPlatformSchema.optional(),
+    })
+        .strict()
+        .default({ type: 'host' }),
+})
+    .strict()
+    .superRefine((config, ctx) => {
+    const issuers = config.issuers.map((i) => i.issuer);
+    config.entitlements.forEach((entitlement, index) => {
+        const iss = (entitlement.subject ?? entitlement.group ?? entitlement.claims)?.iss;
+        if (iss && !issuers.includes(iss)) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                path: ['entitlements', index],
+                message: `issuer ${iss} is not one of the accepted issuers`,
+            });
+        }
+    });
+    for (const [name, account] of Object.entries(config.accounts)) {
+        for (const provider of Object.keys(account.providers)) {
+            if (!config.secretProviders[provider]) {
+                ctx.addIssue({
+                    code: zod_1.z.ZodIssueCode.custom,
+                    path: ['accounts', name, 'providers', provider],
+                    message: `secret provider ${provider} is not declared in secretProviders`,
+                });
+            }
+        }
+    }
+    config.entitlements.forEach((entitlement, index) => {
+        for (const account of Object.keys(entitlement.accounts)) {
+            if (!config.accounts[account]) {
+                const known = Object.keys(config.accounts);
+                ctx.addIssue({
+                    code: zod_1.z.ZodIssueCode.custom,
+                    path: ['entitlements', index, 'accounts', account],
+                    message: `unknown account ${account}, ${known.length > 0 ? `accounts: ${known.join(', ')}` : 'none is defined'}`,
+                });
+            }
+        }
+    });
+    config.sources.forEach((source, index) => {
+        if (!source.secret) {
+            return;
+        }
+        const { from, account } = source.secret;
+        const kind = from.substring(0, from.indexOf(':'));
+        const where = ['sources', index, 'secret'];
+        if (!config.accounts[account]) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                path: [...where, 'account'],
+                message: `unknown account ${account}`,
+            });
+        }
+        else if (!config.accounts[account].providers[kind]) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                path: [...where, 'from'],
+                message: `account ${account} has no credentials for the provider ${kind}`,
+            });
+        }
+        if (!config.secretProviders[kind]) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                path: [...where, 'from'],
+                message: `secret provider ${kind} is not declared in secretProviders`,
+            });
+        }
+    });
+    const readers = getSourceAccounts(config);
+    config.entitlements.forEach((entitlement, index) => {
+        for (const account of Object.keys(entitlement.accounts)) {
+            if (readers.includes(account)) {
+                ctx.addIssue({
+                    code: zod_1.z.ZodIssueCode.custom,
+                    path: ['entitlements', index, 'accounts', account],
+                    message: `the account ${account} reads the sources, no entitlement may name it`,
+                });
+            }
+        }
+    });
+    if (!config.tls && !config.behindTlsProxy && !LOOPBACK_HOSTS.includes(config.listen.host)) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['listen', 'host'],
+            message: `plain http on ${config.listen.host} would send tokens in the clear, set tls or behindTlsProxy: true`,
+        });
+    }
+});
+// The accounts that read repositories: no caller uses them and no build file names them.
+function getSourceAccounts(config) {
+    return [...new Set(config.sources.flatMap((source) => (source.secret ? [source.secret.account] : [])))];
+}
+exports.getSourceAccounts = getSourceAccounts;
+async function readServerConfig(environment, path) {
+    if (!(await environment.file.exists(path))) {
+        throw new Error(`unable to read ${path}: no such file`);
+    }
+    let raw;
+    try {
+        raw = (0, yaml_1.parse)(await environment.file.read(path));
+    }
+    catch (e) {
+        throw new Error(`unable to read ${path}: ${(0, log_1.getErrorMessage)(e)}`);
+    }
+    const result = exports.serverConfigSchema.safeParse(raw ?? {});
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const where = issue.path.length > 0 ? `${issue.path.join('.')}: ` : '';
+        throw new Error(`invalid ${path}: ${where}${issue.message}`);
+    }
+    return result.data;
+}
+exports.readServerConfig = readServerConfig;
+// The secret providers and accounts of the config as the engine reads them, so a
+// secret of a build file is read as an account of the operator.
+function getSecretCatalog(config) {
+    const providers = {};
+    for (const [name, provider] of Object.entries(config.secretProviders)) {
+        providers[name] = {
+            name,
+            type: 'command',
+            command: provider.command,
+            env: provider.env ?? {},
+            timeoutMs: (0, units_1.parseDuration)(provider.timeout ?? '30s'),
+            declaredIn: 'the server config',
+        };
+    }
+    const accounts = {};
+    for (const [name, account] of Object.entries(config.accounts)) {
+        accounts[name] = { name, default: false, providers: account.providers, declaredIn: 'the server config' };
+    }
+    return { providers, accounts, explicitAccounts: true };
+}
+exports.getSecretCatalog = getSecretCatalog;
+function detectPlatform() {
+    const os = { darwin: 'macos', win32: 'windows' }[process.platform] ?? 'linux';
+    const arch = process.arch === 'arm64' ? 'arm64' : 'amd64';
+    return { os, arch };
+}
+exports.detectPlatform = detectPlatform;
+//# sourceMappingURL=server-config.js.map