canopycms 0.0.68-int.98 → 0.1.0

package/dist/worker/self-checks.js

@@ -0,0 +1,358 @@
+import fs from 'node:fs/promises';
+import net from 'node:net';
+import path from 'node:path';
+import { getErrorMessage, isNodeError } from '../utils/error.js';
+/** The instance metadata service's IPv4 address; the launch template sets no IPv6 endpoint. */
+const IMDS_HOST = '169.254.169.254';
+/** How long the IMDS connect may take before it counts as unreachable. */
+const IMDS_CONNECT_TIMEOUT_MS = 1_000;
+/** Connect failures that prove no route: no network, or no IPv4 sockets at all. */
+const NO_ROUTE_CODES = new Set(['ENETUNREACH', 'EAFNOSUPPORT']);
+/**
+ * The variables that hold a secret, or name one (ARNs, JSON fields), and belong to the gateway:
+ * CanopyCMS's GitHub and Clerk settings.
+ */
+const SECRET_ENV_PATTERN = /^(?:CANOPYCMS_GITHUB_TOKEN|CANOPYCMS_GITHUB_APP_|CLERK_SECRET_KEY)/;
+/**
+ * The conventional credential variables: GitHub tokens (`GITHUB_BOT_TOKEN` is canopycms's default
+ * `githubTokenEnvVar`) and the AWS SDK's static credentials. The worker's git reads none (its
+ * environment is git-manager.ts's allowlist), but code that becomes the worker reads its
+ * environment. Exact names, so a look-alike such as `GITHUB_TOKEN_PATH` passes.
+ * `CLERK_JWT_KEY` is not here: it is a public verification key.
+ */
+const AMBIENT_CREDENTIAL_ENV_NAMES = new Set([
+    'GH_TOKEN',
+    'GITHUB_TOKEN',
+    'GITHUB_BOT_TOKEN',
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    'AWS_SECURITY_TOKEN',
+]);
+/** The worker unit's checks, in the plan's order. */
+export async function workerSelfChecks(environment = {}) {
+    return [
+        await imdsUnreachable(environment),
+        await onlyLoopback(environment),
+        await procShowsOnlyOwnProcesses(environment),
+        await homeIsEmpty(environment),
+        noSecretsInEnv(environment),
+    ];
+}
+/** The gateway unit's checks. */
+export async function gatewaySelfChecks(environment = {}) {
+    return [
+        await efsUnreadable(environment),
+        await corePatternNotPiped(environment),
+        await coreLimitZero(environment),
+        ...(environment.listenFd === undefined ? [] : [await socketAccessIsOthers(environment)]),
+    ];
+}
+/** Throw one error naming every failed check, or return. */
+export function assertSelfChecks(results) {
+    const failed = results.filter((result) => !result.ok);
+    if (failed.length === 0)
+        return;
+    throw new Error(`Refusing to start: ${failed.map((result) => `${result.check}: ${result.detail}`).join('; ')}`);
+}
+/**
+ * A TCP connect to IMDS fails with no route (`ENETUNREACH`, or `EAFNOSUPPORT` under
+ * `RestrictAddressFamilies=AF_UNIX`) or times out. Any other outcome, a refusal included, means a
+ * route exists.
+ * @internal Exported for tests.
+ */
+export async function imdsUnreachable(environment = {}) {
+    const connect = environment.connect ?? tcpConnect;
+    const outcome = await connect(IMDS_HOST, 80, IMDS_CONNECT_TIMEOUT_MS);
+    if (outcome === 'timeout' || (outcome !== 'connected' && NO_ROUTE_CODES.has(outcome.code))) {
+        return {
+            check: 'imds',
+            ok: true,
+            detail: outcome === 'timeout' ? 'timed out' : outcome.code,
+        };
+    }
+    return {
+        check: 'imds',
+        ok: false,
+        detail: `the worker unit can reach the instance metadata service (${outcome === 'connected' ? 'connected' : outcome.code}), ` +
+            'so the process split protects nothing',
+    };
+}
+/**
+ * `/proc/self/net/dev` lists only `lo`: `PrivateNetwork=` took effect. Not `/sys/class/net`, which
+ * `PrivateNetwork=` does not remount, so it shows the host's interfaces even inside the cut.
+ * @internal Exported for tests.
+ */
+export async function onlyLoopback(environment = {}) {
+    const file = path.join(rootOf(environment), 'proc', 'self', 'net', 'dev');
+    let text;
+    try {
+        text = await fs.readFile(file, 'utf8');
+    }
+    catch (err) {
+        return {
+            check: 'network-namespace',
+            ok: false,
+            detail: `cannot read ${file}: ${getErrorMessage(err)}`,
+        };
+    }
+    const interfaces = text
+        .split('\n')
+        .slice(2)
+        .map((line) => line.split(':')[0]?.trim() ?? '')
+        .filter((name) => name !== '');
+    const ok = interfaces.length === 1 && interfaces[0] === 'lo';
+    return {
+        check: 'network-namespace',
+        ok,
+        detail: ok
+            ? 'only lo'
+            : `the worker unit sees network interfaces besides lo (${interfaces.join(', ')}): it is not in a private network namespace`,
+    };
+}
+/**
+ * Every process `/proc` lists is this uid's: `ProtectProc=invisible` took effect.
+ * @internal Exported for tests.
+ */
+export async function procShowsOnlyOwnProcesses(environment = {}) {
+    const proc = path.join(rootOf(environment), 'proc');
+    const uid = environment.uid ?? process.getuid?.();
+    if (uid === undefined) {
+        return { check: 'proc', ok: false, detail: 'this platform has no process uid to compare' };
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(proc);
+    }
+    catch (err) {
+        return { check: 'proc', ok: false, detail: `cannot list ${proc}: ${getErrorMessage(err)}` };
+    }
+    const others = [];
+    for (const entry of entries.filter((name) => /^\d+$/.test(name))) {
+        try {
+            const stat = await fs.stat(path.join(proc, entry));
+            if (stat.uid !== uid)
+                others.push(`${entry} (uid ${stat.uid})`);
+        }
+        catch (err) {
+            // A process that exited between the listing and the stat.
+            if (!(isNodeError(err) && err.code === 'ENOENT')) {
+                others.push(`${entry} (${getErrorMessage(err)})`);
+            }
+        }
+    }
+    const ok = others.length === 0;
+    return {
+        check: 'proc',
+        ok,
+        detail: ok
+            ? `only uid ${uid}`
+            : `the worker unit sees other users' processes: ${others.slice(0, 5).join(', ')}`,
+    };
+}
+/**
+ * `/home` is empty: `ProtectHome=tmpfs`'s always-observable effect. `/run/user`, which it also
+ * hides, is empty anyway whenever nobody is logged in.
+ * @internal Exported for tests.
+ */
+export async function homeIsEmpty(environment = {}) {
+    const home = path.join(rootOf(environment), 'home');
+    try {
+        const entries = await fs.readdir(home);
+        return {
+            check: 'home',
+            ok: entries.length === 0,
+            detail: entries.length === 0
+                ? 'empty'
+                : `the worker unit sees ${home}'s entries: ProtectHome=tmpfs did not apply`,
+        };
+    }
+    catch (err) {
+        return { check: 'home', ok: false, detail: `cannot list ${home}: ${getErrorMessage(err)}` };
+    }
+}
+/**
+ * No GitHub or Clerk secret, nor the ARN or JSON field naming one, is in the worker's environment:
+ * they belong to the gateway's env file. Nor is a conventional credential variable (a GitHub token,
+ * the AWS SDK's static credentials). Names only are reported.
+ * @internal Exported for tests.
+ */
+export function noSecretsInEnv(environment = {}) {
+    const env = environment.env ?? process.env;
+    const found = Object.keys(env)
+        .filter((key) => env[key] !== undefined &&
+        (SECRET_ENV_PATTERN.test(key) || AMBIENT_CREDENTIAL_ENV_NAMES.has(key)))
+        .sort();
+    const ok = found.length === 0;
+    return {
+        check: 'secrets-in-env',
+        ok,
+        detail: ok
+            ? 'none'
+            : `the worker unit's environment holds ${found.join(', ')}, which the worker must not hold`,
+    };
+}
+/**
+ * The gateway cannot list `/mnt/efs`: `InaccessiblePaths=/mnt/efs` took effect.
+ * @internal Exported for tests.
+ */
+export async function efsUnreadable(environment = {}) {
+    const efs = path.join(rootOf(environment), 'mnt', 'efs');
+    try {
+        await fs.readdir(efs);
+    }
+    catch (err) {
+        // Denied is the directive at work. Absent (a unit without `RequiresMountsFor=`, started before
+        // the mount) or any other failure proves nothing: a mount made later could still reach it.
+        const code = isNodeError(err) ? err.code : undefined;
+        const denied = code === 'EACCES' || code === 'EPERM';
+        return {
+            check: 'efs-unreadable',
+            ok: denied,
+            detail: denied
+                ? (code ?? '')
+                : `cannot tell that ${efs} is inaccessible: ${getErrorMessage(err)}`,
+        };
+    }
+    return {
+        check: 'efs-unreadable',
+        ok: false,
+        detail: `the GitHub gateway can read ${efs}, where the CMS Lambda writes`,
+    };
+}
+/**
+ * `kernel.core_pattern` does not begin with `|`: a piped pattern would hand a crashing gateway
+ * git's memory (the credential file's contents) to a helper.
+ * @internal Exported for tests.
+ */
+export async function corePatternNotPiped(environment = {}) {
+    const file = path.join(rootOf(environment), 'proc', 'sys', 'kernel', 'core_pattern');
+    try {
+        const pattern = (await fs.readFile(file, 'utf8')).trim();
+        const ok = !pattern.startsWith('|');
+        return {
+            check: 'core-pattern',
+            ok,
+            detail: ok ? pattern : `kernel.core_pattern pipes core dumps to a program (${pattern})`,
+        };
+    }
+    catch (err) {
+        return {
+            check: 'core-pattern',
+            ok: false,
+            detail: `cannot read ${file}: ${getErrorMessage(err)}`,
+        };
+    }
+}
+/**
+ * `/proc/self/limits` shows a zero core limit, soft and hard: `LimitCORE=0` took effect.
+ * @internal Exported for tests.
+ */
+export async function coreLimitZero(environment = {}) {
+    const file = path.join(rootOf(environment), 'proc', 'self', 'limits');
+    let text;
+    try {
+        text = await fs.readFile(file, 'utf8');
+    }
+    catch (err) {
+        return {
+            check: 'core-limit',
+            ok: false,
+            detail: `cannot read ${file}: ${getErrorMessage(err)}`,
+        };
+    }
+    const line = text.split('\n').find((row) => row.startsWith('Max core file size'));
+    const [soft, hard] = line?.slice('Max core file size'.length).trim().split(/\s+/) ?? [];
+    const ok = soft === '0' && hard === '0';
+    return {
+        check: 'core-limit',
+        ok,
+        detail: ok
+            ? 'zero'
+            : `the core file size limit is ${soft ?? '?'} (soft) and ${hard ?? '?'} (hard), not zero`,
+    };
+}
+/**
+ * The socket systemd passed is one only another user (and root) can connect to: its node is not
+ * this process's uid, and grants no group or other access. Whoever owns it is the worker, so a
+ * gateway running as that user (a unit without `User=canopy-github`) would hand the worker its
+ * own environment and memory. A socket's own descriptor reports the creating process (systemd,
+ * root), not the node's owner, so the node is found by the socket's inode in
+ * `/proc/self/net/unix`.
+ * @internal Exported for tests.
+ */
+export async function socketAccessIsOthers(environment = {}) {
+    const fail = (detail) => ({ check: 'socket-access', ok: false, detail });
+    const uid = environment.uid ?? process.getuid?.();
+    if (uid === undefined)
+        return fail('this platform has no process uid to compare');
+    const fd = environment.listenFd ?? 3;
+    const proc = path.join(rootOf(environment), 'proc', 'self');
+    let socketPath;
+    try {
+        const inode = (await fs.stat(path.join(proc, 'fd', String(fd)))).ino;
+        const table = await fs.readFile(path.join(proc, 'net', 'unix'), 'utf8');
+        // Num RefCount Protocol Flags Type St Inode Path; the path is absent for an unbound socket.
+        for (const line of table.split('\n').slice(1)) {
+            const fields = line.trim().split(/\s+/);
+            if (fields[6] === String(inode) && fields.length > 7)
+                socketPath = fields.slice(7).join(' ');
+        }
+    }
+    catch (err) {
+        return fail(`cannot find the socket on descriptor ${fd}: ${getErrorMessage(err)}`);
+    }
+    if (socketPath === undefined || !path.isAbsolute(socketPath)) {
+        return fail(`the socket on descriptor ${fd} is not bound to a path`);
+    }
+    let node;
+    try {
+        node = await fs.lstat(socketPath);
+    }
+    catch (err) {
+        return fail(`cannot read ${socketPath}: ${getErrorMessage(err)}`);
+    }
+    if (!node.isSocket())
+        return fail(`${socketPath} is not a socket`);
+    if (node.uid === uid) {
+        return fail(`the GitHub gateway runs as uid ${uid}, which owns its socket ${socketPath} and so is the ` +
+            "worker's user: give the gateway unit User=canopy-github");
+    }
+    if ((node.mode & 0o077) !== 0) {
+        return fail(`${socketPath} has mode ${(node.mode & 0o777).toString(8)}, so users besides its owner can ` +
+            'reach the gateway: give the socket unit SocketMode=0600');
+    }
+    return { check: 'socket-access', ok: true, detail: `${socketPath} is uid ${node.uid}'s alone` };
+}
+function rootOf(environment) {
+    return environment.root ?? '/';
+}
+/**
+ * One TCP connect, as the IMDS check makes it.
+ * @internal Exported for tests.
+ */
+export function tcpConnect(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        let socket;
+        try {
+            socket = net.connect({ host, port });
+        }
+        catch (err) {
+            resolve({ code: isNodeError(err) && err.code !== undefined ? err.code : 'ERROR' });
+            return;
+        }
+        const timer = setTimeout(() => {
+            socket.destroy();
+            resolve('timeout');
+        }, timeoutMs);
+        socket.once('connect', () => {
+            clearTimeout(timer);
+            socket.destroy();
+            resolve('connected');
+        });
+        socket.once('error', (err) => {
+            clearTimeout(timer);
+            resolve({ code: isNodeError(err) && err.code !== undefined ? err.code : 'ERROR' });
+        });
+    });
+}

package/dist/worker/shared-repo-git.d.ts

@@ -0,0 +1,96 @@
+import { type SimpleGit, type SimpleGitOptions } from 'simple-git';
+export type SharedRepoKind = 'bare' | 'worktree';
+/**
+ * The pins alone, without the environment {@link sharedRepoGit} adds (an explicit `GIT_DIR`, no
+ * lazy fetches), which every worker git in a shared repository needs too.
+ * @internal Exported for tests.
+ */
+export declare function sharedRepoGitOptions(kind: SharedRepoKind): Pick<SimpleGitOptions, 'config' | 'unsafe'>;
+/**
+ * A worker git instance in the shared repository at `repoPath` (the bare repository itself, or a
+ * clone's working tree), with the pins applied. The repository is named outright, as
+ * {@link assertSharedRepoConfig} names it, so both read the same config: discovery would take a
+ * planted `remote.git/.git`, or a `.git` above a clone whose own was removed. A clone's working
+ * tree is named too, which also overrides `core.worktree`.
+ *
+ * `options` are the caller's own (`timeout`, `abort`), applied under the pins. The child env is
+ * `gitChildEnv`'s: every shared-repository operation is local.
+ */
+export declare function sharedRepoGit(repoPath: string, kind: SharedRepoKind, options?: Partial<SimpleGitOptions>): SimpleGit;
+/** simple-git options for the worker's private GitHub mirror. */
+export declare function mirrorGitOptions(): Pick<SimpleGitOptions, 'config' | 'unsafe'>;
+/** {@link mirrorGitOptions}'s pins, for a git the mirror runs without simple-git (worker/git-process.ts). */
+export declare function mirrorPins(): string[];
+/**
+ * The pins of a quarantine repository, where the GitHub gateway takes in a pushed bundle
+ * (worker/github-mirror.ts): the mirror's, without `core.alternateRefsCommand=true`. That pin
+ * guards an alternates file the Lambda can write; a quarantine's names the mirror and is written
+ * by the gateway. With it, the fetch's connectivity check could not stop at the mirror's heads and
+ * would walk the mirror's whole history for every push.
+ */
+export declare function quarantinePins(): string[];
+/**
+ * {@link sharedRepoGit}'s pins, environment and working directory, for a git run through
+ * worker/git-process.ts: one whose stdin or stdout is a stream.
+ */
+export declare function sharedRepoProcessOptions(repoPath: string, kind: SharedRepoKind): {
+    cwd: string;
+    env: Record<string, string>;
+    config: string[];
+};
+/**
+ * `--upload-pack` for a fetch FROM `remote.git` into a clone.
+ * @internal Exported for tests.
+ */
+export declare function pinnedUploadPack(): string;
+/**
+ * `--receive-pack` for a push INTO `remote.git`. Without it the push runs remote.git's own hooks
+ * as the worker. The `receive.deny*` pins keep a planted setting from blocking the forced update
+ * that publishes a rewritten history (worker/history-rewrite.ts).
+ */
+export declare function pinnedReceivePack(): string;
+/**
+ * Fetch `branch` from `remote.git` into the clone `git` runs in, through
+ * {@link pinnedUploadPack}. The result is in FETCH_HEAD only.
+ */
+export declare function fetchFromRemoteGit(git: SimpleGit, remoteGitPath: string, branch: string): Promise<void>;
+/** @internal Exported for tests. */
+export interface UnexpectedConfigKey {
+    key: string;
+    /** The file git read it from, absolute. */
+    file: string;
+}
+/** Every refusal to run git in a shared repository, so a caller can tell one from git's own errors. */
+export declare class SharedRepoRefusalError extends Error {
+    constructor(message: string);
+}
+/**
+ * A shared repository whose own config holds a key CanopyCMS never writes.
+ * @internal Exported for tests.
+ */
+export declare class UntrustedRepoConfigError extends SharedRepoRefusalError {
+    readonly repoPath: string;
+    readonly keys: readonly UnexpectedConfigKey[];
+    constructor(repoPath: string, keys: readonly UnexpectedConfigKey[]);
+}
+/**
+ * Refuse a shared repository whose own config (with its includes, and `config.worktree`) holds a
+ * key outside {@link ALLOWED_REPO_CONFIG_KEYS}, or a submodule with a repository in it. Throws
+ * {@link UntrustedRepoConfigError} for a key. A config git cannot read, or does not finish reading,
+ * is also refused, with git's own message for a bad line, which names the line but not its content.
+ *
+ * `repoPath` is the bare repository itself for `bare`, the working tree for `worktree`.
+ */
+export declare function assertSharedRepoConfig(repoPath: string, kind: SharedRepoKind, options?: {
+    timeoutMs?: number;
+}): Promise<void>;
+/**
+ * Refuse a rebase or fast-forward from `from` to `to` in `clone` that would bring in a submodule
+ * at a path where a repository already sits, as one planted ahead of it would.
+ */
+export declare function assertNoIncomingSubmodules(git: SimpleGit, clone: string, from: string, to: string): Promise<void>;
+/**
+ * Arguments for every worker `git status` in a clone. On the command line, unlike in config, the
+ * setting outranks a `.gitmodules` entry's own `ignore`.
+ */
+export declare const SHARED_REPO_STATUS_ARGS: readonly string[];