@verax-ai/body 0.3.0 → 0.4.0

package/dist/install.d.ts

@@ -0,0 +1,745 @@
+import { type SpawnSyncReturns } from "node:child_process";
+export declare const EX_ELEVATION = 77;
+export declare const ELEVATION_LINE = "verax install needs an elevated shell (Administrator / root)";
+/** The tarball Node under `/opt/verax-node`, plus the distribution `/usr/bin/node`. Neither is `env node`. */
+export declare function posixRootOwnedCommand(platform: "linux" | "darwin", command: string): string;
+/** Names the administrator-owned copy. A same-user elevated shell is not that copy. */
+export declare function unreadableSentence(dir: string, command?: string): string;
+export declare class SystemToolError extends Error {
+    readonly code = 78;
+    constructor(message: string);
+}
+/** Basename of a planned or resolved tool, without a Windows `.exe`. */
+export declare function systemToolName(argv0: string): string;
+/**
+ * Windows directory for system tools. An env value is accepted only when it is
+ * `X:\\Windows` and contains no `..`. A value that points elsewhere is refused
+ * before any process is started. `exec`, when passed, then applies the same
+ * administrator-only DACL check used for node.exe to System32 and each tool,
+ * ancestors included.
+ */
+export declare function windowsSystemRoot(env?: NodeJS.ProcessEnv, exec?: ToolExec): string;
+/** One install root, normalised. `..` is refused. The machine comparison is separate. */
+export declare function windowsInstallRoot(raw: string | undefined, fallback: string, label: string): string;
+/** ProgramData and Program Files as the machine records them, not as the shell sets them. */
+export type WindowsMachineRoots = {
+    programData: string;
+    programFiles: string;
+};
+export declare const WINDOWS_CANONICAL_ROOTS: WindowsMachineRoots;
+/**
+ * Use the machine roots. A shell value that differs is named and refused.
+ * An unset shell variable is not a redirect. The root and each ancestor must
+ * be a real directory, and the path on disk must be the path as given.
+ */
+export declare function adoptWindowsInstallRoots(env: NodeJS.ProcessEnv, machine?: WindowsMachineRoots): WindowsMachineRoots;
+/** HKLM ProgramFilesDir and ProfileList ProgramData, read without expansion. The drive is the drive of SystemRoot. */
+export declare function readWindowsMachineRoots(exec?: ToolExec): WindowsMachineRoots;
+/**
+ * Absolute path for a system tool. Windows uses System32 under SystemRoot.
+ * Linux walks fixed directories and never consults PATH.
+ * macOS uses the fixed table (dscl, launchctl, chown, chmod, id, stat, plutil, lsof).
+ * A missing Linux binary falls back to the first candidate so a plan can name
+ * the path; spawning still refuses when that file is absent.
+ */
+export declare function systemToolPath(tool: string, platform?: NodeJS.Platform): string;
+/** Absolute paths for every system tool on `platform`. */
+export declare function systemToolTable(platform?: NodeJS.Platform): Record<string, string>;
+export declare function requireSystemTool(tool: string, platform?: NodeJS.Platform): string;
+/** Stderr lines from a generated PowerShell script. A line with this prefix is a failed step even when the process exits 0. */
+export declare const PS_ERROR_MARK = "verax-ps-error:";
+/**
+ * Env for system-tool spawns. The caller's PATH is not copied.
+ * TEMP/TMP are set only to `tempDir`. The caller's TEMP is a user-writable
+ * AppData directory and must not receive install files.
+ * On Windows, PSModulePath is only the System32 Windows PowerShell 5.1 module
+ * directory. Without it, PowerShell 5.1 puts Documents\WindowsPowerShell\Modules
+ * first, and -NoProfile does not change that list.
+ */
+export declare function systemToolEnv(platform?: NodeJS.Platform, tempDir?: string): NodeJS.ProcessEnv;
+export declare function toolArgv(tool: string, args: readonly string[], platform?: NodeJS.Platform): string[];
+type ToolSpawn = (file: string, args: readonly string[], opts: {
+    encoding: "utf8";
+    windowsHide: true;
+    shell: false;
+    env: NodeJS.ProcessEnv;
+}) => Pick<SpawnSyncReturns<string>, "status" | "stdout" | "stderr">;
+export declare function nodeTrustMessage(nodePath: string): string;
+/** Account name printed when elevated code is writable by the invoking user. */
+export declare function codeTrustAccount(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): string;
+export declare function elevatedCodeMessage(dir: string, account: string, platform: InstallPlatform, detail?: string): string;
+/** Package directory of the running CLI, each `@verax-ai/*` it loads, and their `node_modules`. */
+export declare function veraxCodeDirectories(entryUrl?: string): string[];
+/**
+ * `probe` returns true when that directory can be changed by the invoking user.
+ * Without a probe the caller supplies `userWritable` from the same ACL or mode
+ * check used for node.exe, ancestors included.
+ */
+export declare function elevatedCodeRefusal(platform: InstallPlatform, dirs: readonly string[], opts: {
+    account: string;
+    probe?: (dir: string) => boolean;
+    userWritable?: (dir: string) => boolean | string;
+}): string | null;
+export type UserTokenSpawn = {
+    uid: number;
+    gid: number;
+    tokenDir: string;
+    tokenPath: string;
+    token: string;
+};
+/** Same checks as the uid child. Tests call this in place of spawn. */
+export declare function writeAgentTokenFile(tokenDir: string, tokenPath: string, token: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export type InstallPlatform = "win32" | "linux" | "darwin";
+export type PlanOpts = {
+    port?: number;
+    days?: number;
+    force?: boolean;
+    /**
+     * Test-only. Prefixes the fixed POSIX install roots. Not read from CLI argv.
+     * Win32 ignores it.
+     */
+    posixRoot?: string;
+    /**
+     * Machine ProgramData and Program Files. When omitted, the canonical paths
+     * are the machine values. A shell value that differs is refused.
+     */
+    windowsMachineRoots?: WindowsMachineRoots;
+    /** Trusted Node used to run npm and the service. It is not copied. */
+    execPath: string;
+    bodyVersion: string;
+    npmCli: string;
+    stateExists: boolean;
+    /** `%ProgramData%\\Verax` (or the Linux code/state parents) already exists. */
+    veraxRootExists?: boolean;
+    /** `install.json` written by a previous verax install. */
+    markerExists?: boolean;
+    /** Junction, symlink, or other reparse point. Named in the refusal. */
+    reparsePath?: string;
+    /** Injected `icacls` text for the Node tree. A user write ACE refuses. */
+    nodeIcacls?: string;
+    userSid?: string;
+    /** Linux: uid and mode of the Node file and each parent. Non-root or group/other-writable refuses. */
+    nodeModes?: {
+        uid: number;
+        mode: number;
+    }[];
+    /**
+     * uid and mode of each ancestor of the Linux and macOS install roots.
+     * When set, the plan does not lstat those directories. `null` means unreadable.
+     */
+    ancestorStat?: (dir: string) => {
+        uid: number;
+        mode: number;
+        symlink?: boolean;
+    } | null;
+    /** Release-test install from `npm pack` tarballs. Skips the registry and signature audit. */
+    fromTarballs?: string;
+    tarballFiles?: string[];
+    /** Injected icacls text for the tarball directory. A user write ACE refuses. */
+    tarballIcacls?: string;
+    /**
+     * One SDDL per path. A newline-joined blob is not one descriptor.
+     * `ancestor` is true only for the tarball directory.
+     */
+    tarballSddl?: {
+        path: string;
+        sddl: string;
+        ancestor: boolean;
+    }[];
+    /** Linux uid/mode of the tarball directory and each tarball. */
+    tarballModes?: {
+        uid: number;
+        mode: number;
+    }[];
+    /** sha256 of each tarball at trust-check time. npm installs the private-temp copies. */
+    tarballDigests?: {
+        file: string;
+        sha256: string;
+    }[];
+    linuxState?: {
+        exists: boolean;
+        symlink: boolean;
+        owner: string;
+    };
+    linuxCode?: {
+        exists: boolean;
+        symlink: boolean;
+        owner: string;
+    };
+    /** Windows `verax-svc`. Absent means the account is not there yet. */
+    winAccount?: {
+        exists: boolean;
+        createdByUs: boolean;
+    };
+    /** Linux login `verax`. Absent means the account is not there yet. `createdGroup` is the marker's claim that this install's useradd made the group. */
+    linuxAccount?: {
+        exists: boolean;
+        createdByUs: boolean;
+        createdGroup?: boolean;
+    };
+    /** Owner name of an existing `%ProgramData%\\Verax`. */
+    winRootOwner?: string;
+    /** icacls text of an existing `%ProgramData%\\Verax`. */
+    winRootAcl?: string;
+    /** `ProfileImagePath` for the invoking SID. A different `USERPROFILE` is refused. */
+    profileImagePath?: string;
+    /** Home from `getent` or `dscl`. `VERAX_INVOKING_HOME` must match it. */
+    invokingHome?: string;
+    /** macOS `_verax` uid/gid chosen from the free 200–400 range. */
+    darwinAccount?: {
+        uid: number;
+        gid: number;
+        createUser: boolean;
+        createGroup: boolean;
+        recordUser: boolean;
+        recordGroup: boolean;
+    };
+    darwinState?: {
+        exists: boolean;
+        symlink: boolean;
+    };
+    /** `/Library/Verax` before this install. */
+    darwinRoot?: {
+        exists: boolean;
+        symlink: boolean;
+    };
+    /** uid and gid of SUDO_USER, already checked against `id` and SUDO_UID/SUDO_GID. */
+    invokingIds?: {
+        uid: number;
+        gid: number;
+    };
+};
+export type PlanOp = {
+    op: "manifest";
+    dir: string;
+} | {
+    op: "mkdir";
+    path: string;
+    mode?: number;
+} | {
+    op: "argv";
+    argv: string[];
+    optional?: boolean;
+    rollbackDir?: string;
+    stdin?: string;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+} | {
+    op: "write";
+    path: string;
+    contents: string;
+    mode?: number;
+    exclusive?: boolean;
+} | {
+    op: "lock-root";
+    path: string;
+    create: boolean;
+} | {
+    op: "init";
+    stateDir: string;
+    port: number;
+    days: number;
+    force: boolean;
+    noOwnerGrant: boolean;
+} | {
+    op: "user-token";
+    tokenDir: string;
+    tokenPath: string;
+    uid: number;
+    gid: number;
+} | {
+    op: "place-token";
+    path: string;
+} | {
+    op: "remove";
+    path: string;
+} | {
+    op: "wait-healthz";
+    port: number;
+    timeoutMs: number;
+    nonce: string;
+} | {
+    op: "print";
+    text: string;
+} | {
+    op: "stage-tarballs";
+    files: {
+        source: string;
+        sha256: string;
+        dest: string;
+    }[];
+} | {
+    op: "private-temp";
+    path: string;
+    /** Win32 DACL after inheritance is removed. POSIX omits this. */
+    acl?: readonly string[];
+    inheritance?: "removed";
+    /** Win32 owner SID, starred for icacls (`*S-1-5-32-544`). */
+    owner?: string;
+    /** POSIX directory mode. Root creates it. */
+    mode?: number;
+};
+export type InstallPlan = {
+    ok: false;
+    code: number;
+    message: string;
+} | {
+    ok: true;
+    ops: PlanOp[];
+    codeDir: string;
+    stateDir: string;
+    tokenPath: string;
+};
+export type ExecResult = {
+    status: number | null;
+    stdout?: string;
+    stderr?: string;
+};
+export type ToolExec = (argv: string[], stdin?: string, env?: NodeJS.ProcessEnv, cwd?: string) => ExecResult;
+export type InstallIo = {
+    stdout: {
+        write(s: string): unknown;
+    };
+    stderr: {
+        write(s: string): unknown;
+    };
+};
+export type InstallHooks = {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    elevated?: () => boolean;
+    exec?: ToolExec;
+    stateExists?: (dir: string) => boolean;
+    layout?: {
+        execPath: string;
+        bodyVersion: string;
+        npmCli: string;
+    };
+    io?: InstallIo;
+    /**
+     * Test-only. Relocates `/opt/verax`, `/var/lib/verax`, `/etc/systemd/system`,
+     * `/Library/Verax`, `/Library/Application Support/Verax`, and
+     * `/Library/LaunchDaemons` under this directory. CLI argv cannot set it.
+     */
+    posixRoot?: string;
+    /** Test-only. Replaces `copyFileSync` while staging `--from-tarballs` copies. */
+    copyFile?: (source: string, dest: string) => void;
+    /** Test-only. Caps the post-start /healthz wait. CLI argv cannot set it. */
+    healthTimeoutMs?: number;
+    /**
+     * True when that code directory can be changed by the invoking user.
+     * Absent means the install reads the real ACL or mode.
+     */
+    codeProbe?: (dir: string) => boolean;
+    /**
+     * True when that path (the running Node, or an ancestor) can be changed by the invoking user.
+     * Absent, together with `codeProbe`, means a test is stubbing the code check and the Node
+     * binary is not lstat'd. Absent with no `codeProbe` means the real ACL or mode check.
+     */
+    execPathProbe?: (file: string) => boolean;
+    /** Defaults to `process.execArgv`. An elevated command refuses a preload flag here. */
+    execArgv?: readonly string[];
+    /**
+     * uid and mode for ancestors of the Linux and macOS install roots.
+     * When set, the plan does not lstat them. Absent means lstat.
+     */
+    ancestorStat?: (dir: string) => {
+        uid: number;
+        mode: number;
+        symlink?: boolean;
+    } | null;
+    /** Test-only stand-in for the uid/gid child that writes the POSIX agent token. */
+    spawnUserToken?: (spec: UserTokenSpawn) => ExecResult;
+    /**
+     * Machine ProgramData and Program Files. When omitted, install and uninstall
+     * read them from HKLM. A shell value that differs is refused.
+     */
+    windowsMachineRoots?: WindowsMachineRoots;
+};
+/** Prefix a fixed POSIX install path. Longest root wins. Unset root returns `fixed`. */
+export declare function relocatePosixPath(fixed: string, posixRoot?: string): string;
+export declare function stateDirFor(platform: NodeJS.Platform | InstallPlatform, env?: NodeJS.ProcessEnv, posixRoot?: string, machine?: WindowsMachineRoots): string;
+export declare function codeDirFor(platform: NodeJS.Platform | InstallPlatform, env?: NodeJS.ProcessEnv, posixRoot?: string, machine?: WindowsMachineRoots): string;
+export declare function windowsAgentTokenPath(env: NodeJS.ProcessEnv, userSid: string, machine?: WindowsMachineRoots): string;
+export declare function npmCliPath(execPath: string, platform: InstallPlatform): string;
+export declare function ancestry(file: string, platform: InstallPlatform): string[];
+export type SddlAce = {
+    /** `A` includes object and callback allows (`OA`, `XA`, `ZA`). `D` includes `OD` and `XD`. */
+    type: "A" | "D";
+    flags: Set<string>;
+    rights: string;
+    sid: string;
+    inheritOnly: boolean;
+};
+/** `icacls` account names are language-specific. Security reads use this SDDL string. */
+export declare function windowsSddlArgv(target: string): string[];
+/**
+ * UTF-8 JSON array for the batch reader's stdin. The command line never carries it:
+ * a real install tree is far past CreateProcess's 32,767 characters.
+ */
+export declare function windowsSddlBatchStdin(paths: readonly string[]): string;
+/**
+ * One PowerShell process reads every path. `paths` is not placed on this argv;
+ * the caller passes `windowsSddlBatchStdin(paths)` as stdin. Stdout is one JSON
+ * object: `{ "<path>": "<sddl>" | { "error": "<msg>" } }`.
+ * PowerShell 5.1 unwraps a one-element JSON array, so the script re-wraps with
+ * `| ForEach-Object { $_ }`.
+ */
+export declare function windowsSddlBatchArgv(paths: readonly string[]): string[];
+export type SddlHit = {
+    status: number;
+    text: string;
+};
+/** One process for every path. A failed process fails every path closed, with the tool text kept for the refusal. */
+export declare function readSddlBatch(exec: ToolExec, paths: readonly string[]): Map<string, SddlHit>;
+export declare function canonicalSid(token: string): string | null;
+/** Owner SID from an SDDL `O:` field. Null when the text is not SDDL. */
+export declare function sddlOwner(text: string): string | null;
+/**
+ * DACL ACEs. Inherit-only `(IO)` is flagged and does not apply to the object.
+ * `OA` / `XA` / `ZA` are stored as allow; `OD` / `XD` as deny. SACL types are dropped.
+ * Any other type fails closed (`null`); the refusal names it.
+ */
+export declare function parseSddlAces(text: string): SddlAce[] | null;
+/**
+ * One ACE rights field as a 32-bit mask. Hex is taken as written.
+ * Letter rights are SDDL codes, two characters at a time (`DC` is FILE_WRITE_DATA, not icacls delete-child).
+ * An unknown code fails closed and is named.
+ */
+export declare function sddlRightsMask(rights: string): {
+    mask: number;
+} | {
+    unknown: string;
+};
+/** First unknown SDDL right in a parsed DACL. Null when every rights field is known, the text is not SDDL, or an ACE type is unknown. */
+export declare function sddlUnknownRight(text: string): string | null;
+/**
+ * True when SDDL lets a principal other than Administrators, SYSTEM, or
+ * TrustedInstaller change this object. Text that is not SDDL is untrusted.
+ * `NO_ACCESS_CONTROL` is a NULL DACL and grants everyone full control.
+ * An empty DACL (`D:` or `D:P` with no ACEs) denies everyone.
+ * A DACL body that does not fully parse is untrusted.
+ * An ACE type outside allow, deny, and ignored SACL types is an untrusted ACL.
+ * The owner keeps implicit WRITE_DAC unless an OWNER RIGHTS ACE limits them.
+ * `ancestor: true` counts only replace / re-point rights. `(IO)` does not apply.
+ * `svcSid`, when set, is trusted the same way verifyServiceAcl trusts it.
+ */
+export declare function windowsUserCanWrite(text: string, opts?: {
+    path?: string;
+    userSid?: string;
+    ancestor?: boolean;
+    svcSid?: string;
+}): boolean;
+/** Symlink or junction resolved. A missing path stays as given so a later ACL or stat check can refuse it. */
+export declare function resolveTrustPath(file: string, platform: InstallPlatform): string;
+/**
+ * The target, then each parent. The target itself is judged as the object.
+ * When the target is a Windows executable (`node.exe`, a System32 tool, `process.execPath`),
+ * its immediate parent is also judged as the object: add-file and add-subdirectory count.
+ * Parents above that stay ancestors. A directory target is unchanged: only that
+ * directory is the object, and every parent stays an ancestor.
+ */
+export declare function trustTargets(file: string, platform: InstallPlatform): {
+    path: string;
+    ancestor: boolean;
+}[];
+/**
+ * Another user can rename or replace this entry.
+ * An ancestor with the sticky bit is kept: only its owner can rename a child (mode 1777, the way `/tmp` works).
+ * The entry itself stays refused when it is group- or other-writable, sticky bit or not.
+ * A symbolic link is refused either way.
+ */
+export declare function posixOthersCanReplace(st: {
+    uid: number;
+    mode: number;
+    symlink?: boolean;
+}, ancestor: boolean): boolean;
+/** POSIX half of the elevated code check. `read` supplies uid and mode so a test does not lstat the machine. */
+export declare function posixCodeDirectoryDetail(dir: string, platform: InstallPlatform, read: (file: string) => {
+    uid: number;
+    mode: number;
+    symlink?: boolean;
+} | null): string | false;
+/**
+ * Directory grant only. `(OI)(CI)` on a directory propagates to children.
+ * Never combine this with `/T`: `/inheritance:r /T` strips every child, and `(OI)(CI)`
+ * does not apply to a file, so each file is left with an empty DACL.
+ * `principal` is `verax-svc` in the plan; execute rewrites it to `*S-1-...`.
+ */
+export declare function windowsDirGrantArgs(dir: string, principal: string, rights: "F" | "RX"): string[];
+/** Children inherit the directory DACL. `/reset` carries no `(OI)` or `(CI)` grant. */
+export declare function windowsResetInheritArgs(dir: string): string[];
+/**
+ * One PowerShell snippet for the install script and the win32 test.
+ * Normalises holder tokens to sorted unique strings and compares with
+ * Compare-Object. Functions emit strings; they do not return collections,
+ * so a one-item result is not unrolled into a bare string.
+ * `$prev`, `$want`, and `$got` are the raw token lists. Sets `$prevSet`,
+ * `$wantSet`, and `$gotSet`. A mismatch prints previous/expected/after/added/missing
+ * and throws; added/missing are also printed when the sets match.
+ */
+export declare const LOGON_HOLDER_COMPARE: string;
+/**
+ * Secedit holder list as a set of upper-case SIDs.
+ * Split on commas, trim, drop one leading `*`, map a name through `nameToSid`,
+ * keep an unmapped name upper-cased, de-duplicate. A token that already matches
+ * `S-1-` is a SID and is not looked up. The install script's
+ * `Normalize-LogonHolders` is this function with NTAccount.Translate as the map.
+ */
+export declare function normalizeLogonHolders(csv: string, nameToSid: Readonly<Record<string, string>>): string[];
+/** Five stderr lines for a holder-set mismatch. `added` is after − expected. */
+export declare function logonHolderMismatchLines(previous: readonly string[], expected: readonly string[], after: readonly string[]): string[];
+/** Terminating errors exit 1. Native calls still need an explicit `$LASTEXITCODE` check. */
+export declare function powerShellScript(body: string): string;
+export declare function successText(platform: InstallPlatform, info: {
+    codeDir: string;
+    stateDir: string;
+    tokenPath: string;
+    port: number;
+}): string;
+export declare function planInstall(platform: InstallPlatform, env: NodeJS.ProcessEnv, opts: PlanOpts): InstallPlan;
+/**
+ * Fresh env for npm. Nothing is copied from the caller: no HOME, no npm_config_*, no NPM_CONFIG_*.
+ * HOME and the Windows profile dirs are the private temp, so ~/.npmrc is never read.
+ */
+export declare function npmSpawnEnv(platform: InstallPlatform, execPath: string, tempDir: string): NodeJS.ProcessEnv;
+/** `resolved` tarball URLs that are not the public npm registry. */
+export declare function registryLockProblems(lockText: string): string[];
+export declare function planUninstall(platform: InstallPlatform, env: NodeJS.ProcessEnv, opts: {
+    keepState: boolean;
+    removeWinAccount?: boolean;
+    removeDarwinUser?: boolean;
+    removeDarwinGroup?: boolean;
+    /** Linux `verax` login. Set only when the marker says `createdUser`. */
+    removeLinuxUser?: boolean;
+    /** Linux `verax` group. Set only when the marker says `createdGroup`. */
+    removeLinuxGroup?: boolean;
+    posixRoot?: string;
+    /** Invoking user SID. Windows removes `%ProgramData%\\Verax\\agent-token\\<sid>`. */
+    userSid?: string;
+    windowsMachineRoots?: WindowsMachineRoots;
+}): InstallPlan;
+export declare function foreignAclPrincipals(text: string, svcSid?: string): string[];
+export type ParsedAce = {
+    principal: string;
+    rights: "F" | "RX" | "other";
+    inheritOnly: boolean;
+};
+/** One SDDL allow/deny ACE. `(IO)` does not apply to the object. */
+export declare function parseIcaclsAce(line: string): ParsedAce | null;
+export declare function parseIcaclsAces(text: string): ParsedAce[];
+/**
+ * Code dir: service RX, Administrators F, SYSTEM F, nothing else.
+ * State dir: service F, Administrators F, SYSTEM F, nothing else.
+ */
+export declare function verifyServiceAcl(text: string, kind: "code" | "state", opts?: {
+    dir?: string;
+    svcSid?: string;
+    file?: string;
+}): {
+    ok: true;
+    aces: ParsedAce[];
+} | {
+    ok: false;
+    aces: ParsedAce[];
+    detail: string;
+};
+export declare function manifestMismatches(manifest: string, hashOf: (rel: string) => string | null): string[];
+export type BoundaryCheck = {
+    id: string;
+    level: "ok" | "fail";
+    detail: string;
+};
+export declare function installedBoundaryChecks(input: {
+    codeDir: string;
+    stateDir: string;
+    manifest: string | null;
+    hashOf: (rel: string) => string | null;
+    aclText?: string;
+    /** Windows icacls of the code directory. Same verifier as the state ACL, with svc RX. */
+    codeAclText?: string;
+    /** icacls of files inside the state or code tree. Inherited ACEs count. An empty DACL fails, naming the file. */
+    fileAcls?: {
+        path: string;
+        text: string;
+        kind: "code" | "state";
+    }[];
+    /** Service SID, so a read-back ACE named `*S-1-...` matches verax-svc. */
+    svcSid?: string;
+    mode?: number;
+    owner?: string;
+    /** Group name of the state directory. macOS expects `_verax`. */
+    ownerGroup?: string;
+    codeOwner?: string;
+    codeMode?: number;
+    /** Windows owner names for the state and code directories. */
+    winOwners?: {
+        state?: string;
+        code?: string;
+    };
+    /** icacls of `%ProgramData%\\Verax`. A Users or CREATOR OWNER write ACE fails. */
+    rootAclText?: string;
+    rootDir?: string;
+    markerPresent?: boolean;
+    /** `install.json` `source`. `tarballs` is release testing, not the registry. */
+    installSource?: string;
+    autostart: boolean;
+}): BoundaryCheck[];
+export declare function directoryAccess(dir: string): "ok" | "missing" | "unreadable";
+export declare function defaultElevated(platform?: NodeJS.Platform): boolean;
+export declare function defaultExec(argv: string[], stdin?: string, env?: NodeJS.ProcessEnv, cwd?: string): ExecResult;
+export declare function discoverLayout(execPath?: string, platform?: NodeJS.Platform): {
+    execPath: string;
+    bodyVersion: string;
+    npmCli: string;
+} | {
+    error: string;
+};
+/**
+ * Ancestors created along the way are 0755. Only `target` receives `mode`.
+ * An existing real directory is kept and receives `mode`. A symlink or a file is EEXIST:
+ * this run must not follow a link into a directory it did not create.
+ */
+/**
+ * Create one directory. By default an existing target is EEXIST: the installer relies on that to
+ * refuse a directory someone planted between its check and this call. `existingOk` (init --force)
+ * keeps an existing real directory that this process's user owns.
+ */
+export declare function mkdirLeaf(target: string, mode: number, opts?: {
+    existingOk?: boolean;
+}): void;
+/** True when the body answered /healthz with this install's nonce. A bare 200 is not the service. */
+export declare function healthzProvesService(body: string, nonce: string): boolean;
+/** Bind and release. False when something is already listening. */
+export declare function loopbackPortFree(port: number): Promise<boolean>;
+export declare function serviceHealthIsNonce(port: number, nonce: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * Enforcing only, and only before install creates anything.
+ * Permissive and Disabled are not a check. A missing getenforce still reads the kernel flag.
+ * Returns the refusal line, or null when the Node label may start a service.
+ */
+export declare function linuxSelinuxNodeRefusal(exec: (argv: string[]) => ExecResult, nodePath: string): string | null;
+/** Linux doctor line: the SELinux mode, and when enforcing the service domain. `init_t` is a warning. */
+export declare function linuxSelinuxCheck(exec?: (argv: string[]) => ExecResult): {
+    id: string;
+    level: "ok" | "warn";
+    detail: string;
+};
+/**
+ * Linux doctor line for the Node binary this process runs.
+ * Enforcing prints the type and warns when it is not `bin_t` or `usr_t`.
+ * Any other mode is not a check.
+ */
+export declare function linuxNodeLabelCheck(exec?: (argv: string[]) => ExecResult, nodePath?: string): {
+    id: string;
+    level: "ok" | "warn";
+    detail: string;
+} | null;
+/** Check-time sha256. Sharing violations (antivirus) retry like the later copy. */
+export declare function hashFileWithRetry(file: string, read: (file: string) => Buffer | string, io: {
+    stderr: {
+        write: (chunk: string) => void;
+    };
+}, pauseMs?: number): {
+    ok: true;
+    sha256: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Copy each trusted tarball into the private temp. Retry sharing violations. The copy's sha256 must match the trust-check hash. */
+export declare function stageTarballCopies(files: readonly {
+    source: string;
+    sha256: string;
+    dest: string;
+}[], copyFile: (source: string, dest: string) => void, io: {
+    stderr: {
+        write: (chunk: string) => void;
+    };
+}, pauseMs?: number): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Files whose DACL must match the directory grant. Missing files are skipped by the caller. */
+export declare function serviceAclFiles(root: string, kind: "code" | "state"): string[];
+/** Existing token parent: real directory the agent cannot steal, or a refusal sentence. */
+export declare function tokenParentRefusal(facts: {
+    dir: string;
+    symlink: boolean;
+    directory: boolean;
+    reparse: boolean;
+    platform: NodeJS.Platform;
+    uid: number;
+    invokingUid?: number;
+    ownerSid?: string;
+    invokingSid?: string;
+}): string | null;
+/**
+ * By-path chown and chmod. `ensureTokenParent` does not run these.
+ * It opens the directory and changes that descriptor.
+ */
+export declare function rootOwnedTokenParentArgv(dir: string, invokingUid: number, platform: NodeJS.Platform): string[][];
+/** One invoking SID and one owner lookup per path for this install or init run. */
+export declare function beginWinOwnerRun(): void;
+export declare function endWinOwnerRun(): void;
+/** Owner SID of an existing directory, and the SID of this process. */
+export declare function windowsDirectorySids(dir: string, exec?: (argv: string[]) => ExecResult): {
+    ownerSid: string | undefined;
+    invokingSid: string | undefined;
+};
+/**
+ * Create a missing token parent with recursive mkdir.
+ * An existing directory must be a real directory, not a symlink or reparse point,
+ * owned by the invoking user, Administrators, SYSTEM, or root. A root-owned
+ * POSIX directory is given to the invoking uid and mode 0700 through the
+ * directory descriptor, after the dev/ino is checked against the lstat.
+ * `beforeChange` runs after that lstat and the owner check, before the descriptor
+ * is opened. Tests use it to swap the directory.
+ */
+export declare function ensureTokenParent(dir: string, env?: NodeJS.ProcessEnv, exec?: ToolExec, beforeChange?: () => void): void;
+/** Owner + Administrators + SYSTEM. Throws when whoami or icacls fails. */
+/**
+ * Owner, Administrators and SYSTEM only. A directory that already holds files needs `directory`:
+ * the grants then carry `(OI)(CI)`, so its children inherit them. Without it `/inheritance:r`
+ * leaves every existing child with an empty DACL.
+ */
+export declare function restrictToOwnerWin32(target: string, spawn?: ToolSpawn, directory?: boolean): void;
+export declare function orderTarballs(files: readonly string[]): string[];
+/** The SID `whoami /user` names for this process. */
+export declare function windowsInvokingSid(exec?: (argv: string[]) => ExecResult): string | undefined;
+/**
+ * Code which already ran can hide itself: a preload can clear `NODE_OPTIONS` and
+ * `execArgv` before this function reads them. This catches only what is still set.
+ */
+export declare function elevatedPreloadRefusal(env: NodeJS.ProcessEnv, execArgv: readonly string[]): string | null;
+export type NodeTrustProbe = {
+    execPath?: string;
+    execPathProbe?: (file: string) => boolean;
+    execArgv?: readonly string[];
+};
+export declare function refuseWritableCode(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, exec: ToolExec, probe?: (dir: string) => boolean, node?: NodeTrustProbe): string | null;
+/** Elevated approve uses the process exec. Install and uninstall pass their own. */
+export declare function elevatedCommandCodeRefusal(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, probe?: (dir: string) => boolean, node?: NodeTrustProbe): string | null;
+/** Elevated approve opens a state directory only when the invoking user cannot change it. */
+export declare function elevatedStateDirRefusal(dir: string, platform: NodeJS.Platform, env: NodeJS.ProcessEnv, probe?: (dir: string) => boolean): string | null;
+export declare function markCliCodeCheckPassed(): void;
+export declare function clearCliCodeCheckPassed(): void;
+export declare function cliCodeCheckPassedAlready(): boolean;
+/**
+ * The ancestor rule the installer applies to ProgramData: a non-administrator
+ * who can replace or re-point an ancestor is a refusal. A path whose ACL
+ * cannot be read is a refusal too.
+ */
+export declare function windowsProgramDataRefusal(env: NodeJS.ProcessEnv, exec?: ToolExec, machine?: WindowsMachineRoots): string | null;
+export declare function runInstall(argv: readonly string[], hooks?: InstallHooks): Promise<number>;
+export declare function runUninstall(argv: readonly string[], hooks?: InstallHooks): Promise<number>;
+export declare function liveInstalledChecks(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, exec?: ToolExec): BoundaryCheck[];
+export declare function doctorStateTarget(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string | null;
+export {};