@veris-ai/daytona 0.2.1 → 0.3.0

package/dist/network.d.ts

@@ -3,21 +3,31 @@ export type EgressMode = 'strict' | 'open';
 /** A service whose `url` is an HTTP endpoint (vs a wire-protocol DSN). */
 export declare const isHttpUrl: (u: string) => boolean;
 /**
- * Vendor hostnames the twin answers for. These MUST be on the allowlist.
- *
- * That reads backwards until you follow the path: the sandbox's traffic goes to
- * Daytona's proxy, which drops anything not allowlisted and forwards the rest
- * to `outboundProxyUrl` — the Veris gateway. So a vendor host that is absent
- * never reaches the gateway and never reaches the twin; it is simply blocked.
- *
- * Allowing it is not a leak, because the allowlist is not what stands between
- * the sandbox and the real vendor — the gateway is. Verified: with every proxy
- * variable stripped, an allowlisted host is still intercepted rather than
- * dialled directly.
+ * Vendor hostnames the twin answers for — the ones the gateway intercepts on
+ * this sandbox's behalf. Informational: they are what a receipt is about, and
+ * they are deliberately NOT handed to Daytona as an allowlist (see buildNetwork).
  */
 export declare function vendorHosts(services: ServiceInfo[]): string[];
 /** Hosts the twin itself lives at — the proxy must reach these or nothing works. */
 export declare function twinHosts(services: ServiceInfo[]): string[];
+/**
+ * The twin hosts a sandbox genuinely cannot work without.
+ *
+ * A service with vendor routes needs nothing here: the code under test dials
+ * `api.stripe.com` and the gateway answers it from the twin. A service with NO
+ * routes has no vendor hostname to dial — yente is the one that measured it —
+ * so its own twin URL is the only way in, and that URL resolves to a host that
+ * was absent from every allowlist we built. Measured: the URL `services()`
+ * hands you is unreachable from inside the sandbox, so a routeless twin cannot
+ * be used at all.
+ *
+ * Narrow on purpose, and the narrowness is the point. Every http service of a
+ * twin shares ONE hostname (`…/s/<twin>/<service>`), and that hostname also
+ * serves `/veris/*` — including `/veris/reset`, which clears the log the
+ * receipt is read from. Allowing it is a real cost, so it is paid only when a
+ * service would otherwise be unreachable. See the note at the top of state.ts.
+ */
+export declare function directTwinHosts(services: ServiceInfo[]): string[];
 /**
  * Endpoints of non-HTTP data planes (e.g. the pg-gateway a postgres DSN
  * targets). Handed over rather than intercepted, so they need plain
@@ -36,39 +46,41 @@ export declare function dataPlaneHosts(services: ServiceInfo[]): string[];
  */
 export declare function dataPlaneEnv(services: ServiceInfo[]): Record<string, string>;
 export declare function isSafeEnvName(name: string): boolean;
-/**
- * Package registries and toolchain hosts, allowed by default.
- *
- * A coding sandbox that cannot `npm install` is not a coding sandbox, and
- * registries are not vendors under test, so they must stay reachable. Naming
- * them here keeps the list auditable rather than punching a wildcard.
- *
- * Override wholesale with `veris.allowRegistries: false` plus your own
- * `veris.allowOut`, for a sandbox that should reach nothing but its twin.
- */
-export declare const DEFAULT_REGISTRY_HOSTS: readonly string[];
 export interface BuildNetworkArgs {
-    services: ServiceInfo[];
     mode: EgressMode;
-    /** The Veris gateway's host, and the canary hostname it answers on. Without
-     *  these the sandbox cannot reach the gateway at all. */
-    gatewayHosts: string[];
-    /** Extra hostnames the caller wants reachable. */
-    allowOut?: string[];
-    /** Include DEFAULT_REGISTRY_HOSTS. Default true. */
-    allowRegistries?: boolean;
+    /** IPv4 addresses the Veris gateway listens on, from the egress credential
+     *  (or one DNS lookup of the proxy host on an older control plane). */
+    gatewayIps: string[];
 }
 /** The Daytona create params that decide what the sandbox may reach. */
 export interface NetworkParams {
-    networkBlockAll?: boolean;
-    domainAllowList?: string;
+    networkAllowList?: string;
+}
+/** What buildNetwork decided. */
+export interface NetworkPlan {
+    params: NetworkParams;
 }
 /**
- * Strict (the default) is deny-all-except: the vendor hosts the twin answers
- * for, the gateway itself, the twin's data planes, and package registries.
+ * Strict (the default) pins the sandbox to the gateway's addresses and nothing
+ * else: `networkAllowList` is one /32 per gateway IP. Every hostname the code
+ * under test dials — vendor, registry, anything — then travels as a CONNECT
+ * through the gateway, which answers vendor hostnames from the twin and passes
+ * public hosts through. A client that ignores the proxy variables cannot dial
+ * out at all (Daytona blocks it), so it fails closed rather than reaching the
+ * real vendor.
+ *
+ * Why an ADDRESS list and not the hostname list this used to build: measured
+ * on Daytona, a `domainAllowList` set beside `outboundProxyUrl` switches its
+ * egress proxy into TLS inspection. The client is shown a leaf signed by
+ * Daytona's own CA, Daytona opens a second TLS session to the gateway and
+ * rejects the Veris-signed leaf it gets back, and every vendor call ends as
+ * `502 could not reach upstream host` whatever the sandbox trusts.
+ * `networkAllowList` beside the same proxy URL leaves the tunnel untouched.
+ * Pinning to the gateway also retires Daytona's 20-domain cap: what may be
+ * reached is the gateway's decision, not a list assembled here.
  *
- * Open sets no allowlist at all. It exists for debugging and is never the
- * default: with no allowlist there is nothing forcing traffic at the gateway,
- * and the receipt cannot tell you what slipped past.
+ * Open sets no allowlist at all. Daytona still blocks anything that bypasses
+ * the proxy in this mode, so it is not a leak; it is the way to run against a
+ * control plane that has not published its gateway addresses.
  */
-export declare function buildNetwork(args: BuildNetworkArgs): NetworkParams;
+export declare function buildNetwork(args: BuildNetworkArgs): NetworkPlan;

package/dist/profile.d.ts

@@ -0,0 +1,70 @@
+export declare const DEFAULT_API_BASE = "https://svc.api.veris.ai";
+/** The profile file's shape, as the CLI writes it (internal/cfg/global.go). */
+export interface ProfileFile {
+    active_profile?: string;
+    profiles?: Record<string, {
+        api_base?: string;
+        api_key?: string;
+    } | null>;
+}
+/** Where a key and a control plane were finally found. */
+export interface VerisCredentials {
+    apiKey?: string;
+    apiBase: string;
+    /** Which layer answered for the key. `none` when nothing did. */
+    keySource: 'option' | 'env' | 'profile' | 'none';
+    /** Which layer answered for the base. `default` means nobody named one —
+     *  which matters to a caller deciding whether the base is a trusted source. */
+    baseSource: 'option' | 'env' | 'profile' | 'default';
+    /** The profile that was (or would have been) read, and whether it exists. */
+    profile: {
+        name: string;
+        path: string;
+        found: boolean;
+    };
+}
+export interface ResolveOpts {
+    /** A key given in code, which wins over everything. */
+    apiKey?: string;
+    /** A base given in code, which wins over everything. */
+    apiBase?: string;
+    /** The environment to read; defaults to process.env. */
+    env?: NodeJS.ProcessEnv;
+    /** The profile file's path; defaults to ~/.veris/twin.yaml. */
+    path?: string;
+    /** Reads the file, or returns undefined when it does not exist. Injected
+     *  so the resolution is testable without touching the home directory. */
+    readFile?: (path: string) => string | undefined;
+}
+/** ~/.veris/twin.yaml, resolved the way the CLI resolves it. */
+export declare function profilePath(home?: string): string;
+/**
+ * Parse the profile file. A missing file is not an error: a fresh machine has
+ * none, and the caller says what to do about that. A file that exists but
+ * does not parse IS an error naming the path, because silently treating it as
+ * empty would send the user to log in again over a stray tab — the CLI's own
+ * rule, kept so the two agree about the same file.
+ */
+export declare function parseProfileFile(text: string | undefined, path: string): ProfileFile | undefined;
+/** Which profile a command uses: VERIS_PROFILE → active_profile → default. */
+export declare function selectProfileName(env: NodeJS.ProcessEnv, file: ProfileFile | undefined): string;
+/**
+ * The key and control plane this process should use, and where each came
+ * from. Never throws for a missing key — that is a decision for the caller,
+ * which knows whether it needs one — but does throw for a file it cannot read.
+ */
+export declare function resolveVerisCredentials(opts?: ResolveOpts): VerisCredentials;
+/** "VERIS_API_KEY is not set, and …" — the two places a key was looked for. */
+export declare function missingKeyWhere(c: VerisCredentials): string;
+/** "Run `veris login` … or set VERIS_API_KEY" — where a key can come from. */
+export declare const KEY_SOURCES_HINT: string;
+/**
+ * What to say when no key was found anywhere: name every place one could
+ * have come from, so the fix is on the screen. `veris login` is first because
+ * it is the route that needs nothing typed into a shell.
+ */
+export declare function missingKeyMessage(c: VerisCredentials): string;
+/** resolveVerisCredentials, or a MissingCredentialsError that says where a key can come from. */
+export declare function requireVerisCredentials(opts?: ResolveOpts): VerisCredentials & {
+    apiKey: string;
+};

package/dist/provision.d.ts

@@ -0,0 +1,100 @@
+export interface ProvisionOptions {
+    /** The twin to attach to. Required: a provisioned box is only useful pointed
+     *  at a twin the caller already made. */
+    sandbox: string;
+    /** Daytona image or snapshot to create the sandbox from. Unset: Daytona's default. */
+    image?: string;
+    snapshot?: string;
+    /** KEY=VALUE pairs set as sandbox environment variables. */
+    env: Record<string, string>;
+}
+/**
+ * Idle minutes before Daytona stops the sandbox.
+ *
+ * Nothing deletes a provisioned box for the caller, so these two intervals are
+ * the only thing standing between an abandoned box and a bill. Daytona's own
+ * default is 15 minutes of no API activity; 30 is deliberately more generous,
+ * because a caller here is installing dependencies and running a suite between
+ * our calls and a box stopped underneath them is worse than half an hour of
+ * idle compute.
+ */
+export declare const AUTO_STOP_MINUTES = 30;
+/**
+ * Minutes after the sandbox stops before Daytona deletes it.
+ *
+ * Daytona disables auto-delete by default, so a stopped box keeps its disk (and
+ * its cost) forever. An hour is long enough to come back and look at a box that
+ * stopped while you were at lunch, short enough that forgetting one is cheap.
+ */
+export declare const AUTO_DELETE_MINUTES = 60;
+/**
+ * Wall-clock life of a provisioned sandbox, in minutes.
+ *
+ * The hard backstop under the two intervals above: it destroys the box whatever
+ * state it is in. Four hours fits a long install and a long suite with room to
+ * spare, and bounds a box that was never torn down. It does NOT move the twin's
+ * TTL — provision always attaches, and the twin's life was decided when whoever
+ * created it said so.
+ */
+export declare const PROVISION_TTL_MINUTES = 240;
+/** What `provision` prints on stdout. One object, nothing else there. */
+export interface ProvisionResult {
+    /** The Daytona sandbox id — what `veris-daytona teardown` takes. */
+    daytonaSandboxId: string;
+    /** The Veris twin's id. NOT the Daytona one; the receipt is read from this. */
+    verisSandboxId: string;
+    /** The Veris environment the twin belongs to. */
+    verisEnvironmentId: string;
+    /** Whether deleting the sandbox also deletes the twin. Always false here:
+     *  provision attaches to a twin the caller made, so the caller keeps it. */
+    ownsTwin: boolean;
+    /** An empty directory in the sandbox to put code in and run commands from. */
+    workDir: string;
+    /** The CA bundle inside the sandbox: the public roots plus the Veris CA. */
+    caBundlePath: string;
+    /** The CA trust variables. Export these on EVERY command — Daytona overwrites
+     *  the well-known ones inside the sandbox with its own CA file, which cannot
+     *  verify the gateway's certificates. */
+    trustEnv: Record<string, string>;
+    /** The same variables as one line of shell `export`s, to prefix a command
+     *  with when you have no env map to fill. */
+    trustPrelude: string;
+    /** Run this INSIDE the sandbox after installing dependencies, to append the
+     *  Veris CA to the CA bundles SDKs ship with them. */
+    patchBundledCasCommand: string;
+    /** How to get code into the box. Daytona's own CLI has no upload, copy or
+     *  sync command and its `ssh` takes no remote command, so a caller who does
+     *  not know this verb exists has no route in short of writing an SDK script. */
+    pushCommand: string;
+    /** How to run one command in the box with trustEnv already exported and its
+     *  output streaming. `daytona exec` can set no variables at all. */
+    execCommand: string;
+    /** The twin's service names — what `--require-service` would name. */
+    services: string[];
+    /** When Daytona destroys the sandbox regardless of state. */
+    expiresAt: string;
+    /** Idle minutes before Daytona stops the sandbox. */
+    autoStopMinutes: number;
+    /** Minutes after stopping before Daytona deletes it. */
+    autoDeleteMinutes: number;
+}
+export declare const PROVISION_USAGE = "usage: veris-daytona provision --sandbox <twin-id> [options]\n\nCreates a Daytona sandbox whose vendor API calls are answered by an existing\nVeris twin, and stops there: nothing is uploaded, nothing is run, nothing is\ndeleted. One JSON object is printed on stdout; progress goes to stderr.\n\n  --sandbox <twin-id>       the Veris twin to attach to (required)\n  --image <name>            Daytona image to run in (default: Daytona's default snapshot)\n  --snapshot <name>         Daytona snapshot to run in\n  --env KEY=VALUE           set as a sandbox environment variable (repeatable)\n\nneeds: DAYTONA_API_KEY, and a Veris key: VERIS_API_KEY, or the profile\n`veris login` saved in ~/.veris/twin.yaml (VERIS_PROFILE picks one; the\nenvironment variable wins when both exist). No VERIS_ENVIRONMENT_ID \u2014 the\nenvironment comes from the twin. A Daytona key without delete:sandboxes still\nprovisions, with a warning that teardown will be refused.\n\nthe JSON on stdout:\n  daytonaSandboxId        the Daytona sandbox id; `veris-daytona teardown` takes it\n  verisSandboxId          the Veris twin's id \u2014 NOT the Daytona one\n  verisEnvironmentId      the environment the twin belongs to\n  ownsTwin                false: the twin is yours, and teardown leaves it alone\n  workDir                 an empty directory to put code in and run commands from\n  caBundlePath            the CA bundle inside the sandbox (public roots + the Veris CA)\n  trustEnv                the CA variables, as a map \u2014 export them on EVERY command\n  trustPrelude            the same variables as one line of shell `export`s\n  patchBundledCasCommand  run it inside the sandbox after installing dependencies\n  pushCommand             how to get code in \u2014 the Daytona CLI cannot upload\n  execCommand             how to run one command in there, trustEnv already applied\n  services                the twin's service names\n  expiresAt               when Daytona destroys the sandbox whatever state it is in\n  autoStopMinutes         idle minutes before Daytona stops it\n  autoDeleteMinutes       minutes after stopping before Daytona deletes it\n\nGetting code in: the Daytona CLI has no upload, copy or sync command, its `ssh`\ntakes no remote command, and `--context` is a build context on `create` only \u2014\nso `veris-daytona push <daytonaSandboxId>` is the route. It tars the current\ndirectory into workDir. `veris-daytona exec <daytonaSandboxId> -- <command>`\nthen runs a command in there with trustEnv already exported and its output\nstreaming, neither of which `daytona exec` can do.\n\nData-plane variables (DATABASE_URL and the like) are already set inside the\nsandbox, so a command run in there inherits them.\n\nThe sandbox stops after 30 idle minutes, is deleted 60 minutes after\nit stops, and is destroyed at 240 minutes old whatever state it is in \u2014 nothing\nhere deletes it for you. The twin's own TTL is whatever created it.\n\nexit code: 0 when the sandbox is up and the canary answered; 2 otherwise.";
+/** Parse everything after `provision`. Pure; throws UsageError with a human message. */
+export declare function parseProvisionArgs(argv: readonly string[]): ProvisionOptions;
+/**
+ * The JSON object, from the handful of facts only a live create() knows.
+ *
+ * Everything else in it is derived here rather than in cli.ts, so the shape a
+ * caller parses is decided in one pure place and tested without an account.
+ */
+export declare function provisionResult(facts: {
+    daytonaSandboxId: string;
+    verisSandboxId: string;
+    verisEnvironmentId: string;
+    workDir: string;
+    trustEnv: Record<string, string>;
+    services: string[];
+    expiresAt: string;
+}): ProvisionResult;
+/** The one line of stdout. Indented, because a human reads this too. */
+export declare function provisionJson(result: ProvisionResult): string;

package/dist/push.d.ts

@@ -0,0 +1,11 @@
+export interface PushOptions {
+    /** The Daytona sandbox id — `provision`'s daytonaSandboxId. Not the twin's. */
+    sandboxId: string;
+    /** Git URL to clone into the sandbox. Unset: the current directory is uploaded. */
+    repo?: string;
+    /** Branch to clone. Only meaningful with --repo. */
+    ref?: string;
+}
+export declare const PUSH_USAGE: string;
+/** Parse everything after `push`. Pure; throws UsageError with a human message. */
+export declare function parsePushArgs(argv: readonly string[]): PushOptions;

package/dist/receipt.d.ts

@@ -1,19 +1,31 @@
 import type { ServiceInfo } from './control-plane';
 /** One intercepted request, from the twin's trace log. */
 export interface ReceiptRequest {
+    /** Row id. Monotonic per service, and what a later read resumes from. */
+    id: number;
     method: string;
     path: string;
     /** null = no response sent (fault hang). */
     status: number | null;
+    tier: string;
 }
 export interface ReceiptEntry {
-    /** Count of intercepted requests (real JSON parse, not a regex). */
+    /** Vendor-surface requests the twin received since the watermark. A floor,
+     *  not a count, when `capped` is set. */
     requests: number;
     /** The twin service's /veris/* control plane. */
     controlUrl: string;
     /** Typed request list, newest first. */
     entries: ReceiptRequest[];
-    /** Verbatim /veris/requests body. */
+    /** The read stopped before the log did, so `requests` is "at least this
+     *  many". Never silent: a count that is quietly a floor is exactly the bug
+     *  this replaced. */
+    capped: boolean;
+    /** Present when this is only a lower bound. */
+    incompleteReason?: string;
+    sinceId?: number;
+    untilId?: number;
+    /** The /veris/requests rows read, verbatim as served, merged across pages. */
     raw: unknown;
 }
 export type ReceiptLeak = 'udp-quic-possible' | 'ech-possible';
@@ -29,8 +41,18 @@ export interface Receipt {
     /** Known blind spots of THIS receipt. */
     leaks: ReceiptLeak[];
 }
+export interface RawRow extends ReceiptRequest {
+    [key: string]: unknown;
+}
+/** Malformed reads are failures, never successful empty evidence. */
+export declare function rowsOf(body: unknown): RawRow[];
 export declare function parseRequestsBody(body: unknown): {
     count: number;
     entries: ReceiptRequest[];
+    total: number;
 };
-export declare function fetchReceiptEntry(svc: ServiceInfo): Promise<ReceiptEntry>;
+export declare function readPage(svc: ServiceInfo, query: URLSearchParams): Promise<RawRow[]>;
+export declare function fetchWatermark(svc: ServiceInfo): Promise<number>;
+/** Read a finite window. The newest-id snapshot also detects servers that
+ * silently cap pages below our requested limit. Never subtract row counts. */
+export declare function fetchReceiptEntry(svc: ServiceInfo, sinceId?: number): Promise<ReceiptEntry>;

package/dist/run-receipt.d.ts

@@ -0,0 +1,13 @@
+import type { ServiceInfo } from './control-plane';
+export interface ReceiptBaseline {
+    version: 1;
+    twinId: string;
+    sandboxId: string;
+    services: Record<string, {
+        controlUrl: string;
+        id: number;
+        marker: string;
+    }>;
+}
+export declare function captureBaseline(twinId: string, sandboxId: string, services: ServiceInfo[]): Promise<ReceiptBaseline>;
+export declare function validateBaseline(baseline: ReceiptBaseline, twinId: string, sandboxId: string, services: ServiceInfo[]): Promise<void>;

package/dist/run.d.ts

@@ -0,0 +1,87 @@
+import type { Receipt } from './receipt';
+export interface RunOptions {
+    /** Git URL to clone into the sandbox. Unset: the current directory is uploaded. */
+    repo?: string;
+    /** Branch to clone. */
+    ref?: string;
+    /** Veris environment. Unset: VERIS_ENVIRONMENT_ID. */
+    environment?: string;
+    /** Attach to an existing twin instead of creating one. It is not deleted afterwards. */
+    sandbox?: string;
+    /** Daytona image or snapshot to create the sandbox from. Unset: Daytona's default. */
+    image?: string;
+    snapshot?: string;
+    /** Shell command run once before the main command (dependency install). */
+    setup?: string;
+    /** Services the receipt must show traffic for. Empty: any service will do. */
+    requireService: string[];
+    /** KEY=VALUE pairs exported to the setup and main commands. */
+    env: Record<string, string>;
+    /** Keep the sandbox and twin after the run, and print how to reach them. */
+    keep: boolean;
+    /** Seconds the main command may run. */
+    timeoutSeconds: number;
+    /** The command itself, everything after `--`. */
+    command: string;
+}
+export declare const DEFAULT_TIMEOUT_SECONDS = 1800;
+export declare const USAGE = "usage: veris-daytona run [options] -- <command>\n\nRuns <command> in a Daytona sandbox whose vendor API calls are answered by a\nVeris twin, then prints what the twin received.\n\n  --repo <url>              git URL to clone into the sandbox (default: upload the current directory)\n  --ref <branch>            branch to clone\n  --environment <id>        Veris environment (default: $VERIS_ENVIRONMENT_ID)\n  --sandbox <twin-id>       attach to an existing twin instead of creating one\n  --image <name>            Daytona image to run in (default: Daytona's default snapshot)\n  --snapshot <name>         Daytona snapshot to run in\n  --setup <cmd>             shell command run first, e.g. 'npm ci' or 'pip install -e .'\n  --require-service <name>  the receipt must show this service (repeatable; default: any)\n  --env KEY=VALUE           exported to the setup and main commands (repeatable)\n  --timeout <seconds>       how long <command> may run (default: 1800)\n  --keep                    leave the sandbox and twin running afterwards\n\nneeds: DAYTONA_API_KEY (with delete:sandboxes, or the sandbox outlives the run),\na Veris key \u2014 VERIS_API_KEY, or the profile `veris login` saved in\n~/.veris/twin.yaml (VERIS_PROFILE picks one) \u2014 and VERIS_ENVIRONMENT_ID (or\n--environment). GITHUB_TOKEN or GH_TOKEN is used for a private --repo.\n\nexit code: the command's; 1 if the twin received nothing (a pass without a receipt is not a pass).";
+export declare class UsageError extends Error {
+}
+/** Parse everything after `run`. Pure; throws UsageError with a human message. */
+export declare function parseRunArgs(argv: readonly string[]): RunOptions;
+/** Quote argv words back into one shell line, leaving plain words alone. */
+export declare function shellJoin(words: readonly string[]): string;
+export interface Verdict {
+    /** The process exit code the run should end with. */
+    exitCode: number;
+    /** One line per reason, for the human. Empty when everything held. */
+    problems: string[];
+}
+/**
+ * Decide the exit code from the command's own status and the receipt.
+ *
+ * A failing command fails the run, receipt or not. A passing command still
+ * fails the run when the twin saw nothing, or saw nothing for a service the
+ * caller required — that is the case the receipt exists to catch.
+ */
+export declare function verdict(commandExitCode: number, receipt: Receipt, requireService: readonly string[]): Verdict;
+/**
+ * The receipt as the human sees it.
+ *
+ * A count the read could not finish prints as "≥N", per service and in the
+ * total. The twin's log is read in pages, so a very long run can end at the
+ * page budget, and printing that floor as if it were the count would be a
+ * wrong number stated confidently — the one thing a receipt must never be.
+ */
+export declare function formatReceipt(receipt: Receipt, twinId: string): string;
+/**
+ * The directory under the sandbox's own home that every verb puts code in.
+ *
+ * One name shared by four verbs on purpose: `provision` prints it as workDir,
+ * `push` unpacks into it, `exec` runs in it by default, and `run` does all
+ * three. A caller chaining provision → push → exec never has to carry the path
+ * between the commands, and cannot get it wrong.
+ */
+export declare const WORK_SUBDIR = "veris-run";
+/** Directories never worth shipping: rebuilt inside the sandbox, or not source. */
+export declare const UPLOAD_EXCLUDES: readonly string[];
+/** Exit status coreutils `timeout` reports when it had to stop the command. */
+export declare const TIMED_OUT_EXIT = 124;
+/**
+ * The one shell line a session runs: cd, exports, then the command under
+ * coreutils `timeout` so a hung suite is stopped inside the sandbox. Images
+ * without `timeout` run the command bare; the client-side backstop still
+ * applies.
+ */
+export declare function commandLine(cwd: string, env: Record<string, string>, command: string, timeoutSeconds: number): string;
+export declare function shellQuote(s: string): string;
+/**
+ * The environment a command runs with. Daytona overwrites SSL_CERT_FILE,
+ * REQUESTS_CA_BUNDLE and CURL_CA_BUNDLE inside the sandbox with its own CA
+ * file, which cannot verify the gateway's leaf and cannot be amended (root
+ * owned, read-only mount). So the Veris trust variables are exported on every
+ * command, where they beat the session's inherited values. The caller's --env
+ * comes last and wins.
+ */
+export declare function commandEnv(trust: Record<string, string>, user: Record<string, string>): Record<string, string>;

package/dist/service-control.d.ts

@@ -0,0 +1,8 @@
+import type { ServiceInfo } from './control-plane';
+export type ControlResource = 'manual' | 'schema' | 'operations' | 'data' | 'requests';
+export interface ControlOptions {
+    method?: 'GET' | 'POST' | 'PATCH';
+    query?: Record<string, string>;
+    body?: unknown;
+}
+export declare function serviceControl(svc: ServiceInfo, resource: ControlResource, options?: ControlOptions): Promise<unknown>;

package/dist/teardown.d.ts

@@ -0,0 +1,52 @@
+import type { DaytonaKeyInfo } from './daytona-key';
+export interface TeardownOptions {
+    /** The Daytona sandbox id. Not the twin's. */
+    sandboxId: string;
+}
+export declare const TEARDOWN_USAGE = "usage: veris-daytona teardown <daytona-sandbox-id>\n\nDeletes the Daytona sandbox. The id is the one `veris-daytona provision`\nprinted as daytonaSandboxId \u2014 not the Veris twin's id.\n\nThe twin follows the rule it was created under: one this package created is\ndeleted with the sandbox, one it attached to (`provision`, or `run --sandbox`)\nis yours and is left running. Which of the two happened is printed.\n\nneeds: DAYTONA_API_KEY with the delete:sandboxes permission \u2014 a key made with\n\"write sandboxes\" alone is refused, and the refusal says when Daytona will stop\nand delete the box on its own. To reach a twin that must be deleted, a Veris\nkey too: VERIS_API_KEY, or the profile `veris login` saved.\n\nexit code: 0 when the sandbox is deleted; 1 when there is no such sandbox, or\nthe key may not delete one.";
+/** The facts a refused delete is described from. Intervals are the sandbox's own. */
+export interface RefusedTeardown {
+    /** The Daytona sandbox id. */
+    sandboxId: string;
+    twinId?: string;
+    /** Whether the wrapped delete removed the twin before Daytona refused the
+     *  sandbox — it deletes the twin first, so an owned twin is already gone. */
+    ownsTwin: boolean;
+    /** Daytona's `autoStopInterval`: idle minutes before it stops. 0 is off. */
+    autoStopMinutes?: number;
+    /** Daytona's `autoDeleteInterval`: minutes after stopping before it is
+     *  deleted. 0 is at once; negative or unset is never. */
+    autoDeleteMinutes?: number;
+    /** Daytona's `autoDestroyAt`, when a TTL was set. */
+    expiresAt?: string;
+    /** The key's record, when GET /api/api-keys/current answered. */
+    key?: DaytonaKeyInfo;
+}
+/**
+ * Was this Daytona's "you may not" — HTTP 403 — rather than any other failure?
+ * Read off the status the SDK stamps rather than a class, so the check holds
+ * across the SDK's own renamings (DaytonaAuthorizationError became
+ * DaytonaForbiddenError) and for an error that crossed a package boundary.
+ */
+export declare function isPermissionDenied(e: unknown): boolean;
+/**
+ * What Daytona will do to the box on its own, in one clause: "stops after 30
+ * idle minutes and is deleted 60 minutes after it stops, and is destroyed at
+ * <time> whatever state it is in". This is the substance of a refusal — the
+ * reader's real question is whether the box bills forever, and the answer is
+ * on the sandbox object.
+ */
+export declare function sandboxBrakes(r: Pick<RefusedTeardown, 'autoStopMinutes' | 'autoDeleteMinutes' | 'expiresAt'>): string;
+/**
+ * What `teardown` says when Daytona answered 403.
+ *
+ * The bare "FAILED Access denied" this replaces named neither the cause nor the
+ * consequence. The cause is a key without `delete:sandboxes` — the one
+ * permission DELETE /api/sandbox/<id> checks, and one a key made with "write
+ * sandboxes" alone does not have. The consequence is a box that is still there
+ * and still billing, so the message says exactly when Daytona will stop and
+ * delete it by itself, what happened to the twin, and how to delete it sooner.
+ */
+export declare function teardownRefusedMessage(r: RefusedTeardown): string;
+/** Parse everything after `teardown`. Pure; throws UsageError with a human message. */
+export declare function parseTeardownArgs(argv: readonly string[]): TeardownOptions;

package/dist/trust.d.ts

@@ -36,6 +36,106 @@ export declare const VERIS_BUNDLE = "/tmp/veris-ca-bundle.crt";
  * is the one file that works in both worlds.
  */
 export declare function vendoredTrustEnv(): Record<string, string>;
+/**
+ * The same variables as one POSIX `export` prelude, to prefix a command with.
+ *
+ * The map above is the right shape when you control the process's environment.
+ * A caller that does not — anything handing a command to a shell whose env it
+ * did not build — has nowhere to put a map, and the command inherits Daytona's
+ * overwritten SSL_CERT_FILE / REQUESTS_CA_BUNDLE / CURL_CA_BUNDLE /
+ * NODE_EXTRA_CA_CERTS instead. Measured with the inherited value: `uv sync`
+ * dies with "invalid peer certificate: UnknownIssuer". Prefixing this makes
+ * the command's own shell put the Veris bundle back:
+ *
+ *   sandbox.process.executeCommand(`${trustPrelude()} ${yourCommand}`)
+ *
+ * Values are single-quoted, so the string stays one safe command line whatever
+ * the control plane served.
+ */
+export declare function trustPrelude(env?: Record<string, string>): string;
+/**
+ * CA bundles that SDKs ship INSIDE the code under test, as slash-anchored path
+ * suffixes.
+ *
+ * No trust variable reaches these. stripe-python passes
+ * `verify=stripe.ca_bundle_path` explicitly, so all eighteen variables above
+ * are irrelevant to it and the first Stripe call dies with "Could not verify
+ * Stripe's SSL certificate" — the gateway's forged leaf is signed by a CA that
+ * file has never heard of. Appending our CA to the file keeps the SDK on the
+ * code path that ships; the bundle merely holds one more root.
+ *
+ * The table is the veris CLI's (internal/bundlescan), for the reason it gives
+ * there: matched as a path SUFFIX because site-packages prefixes vary per
+ * image and the tail does not, and deliberately with no bare `cacert.pem`
+ * rule, because that filename also names test fixtures and client-auth
+ * material that must not quietly gain a root.
+ */
+export declare const BUNDLED_CA_FILES: readonly {
+    sdk: string;
+    suffix: string;
+}[];
+/** Where the patch script is written inside the sandbox, so anything that can
+ *  run a shell command — a test harness, an agent, a person over ssh — can
+ *  re-run it after installing dependencies without holding this SDK. */
+export declare const BUNDLED_CA_PATCH_SCRIPT = "/tmp/veris-patch-bundled-cas.sh";
+/**
+ * What the script prints per patched file, so the caller can report what
+ * happened rather than infer it from an exit code.
+ *
+ * A sentence rather than a machine marker, because both routes to this script
+ * are read by a person. `provision` tells a caller to run `sh
+ * /tmp/veris-patch-bundled-cas.sh` themselves, and whatever the script prints
+ * is what they see — a bare `__VERIS_PATCHED__ /path` reads as debug output
+ * that escaped. `patchBundledCas()` parses the paths back off this same
+ * constant, and cli.ts prints the same sentence for the SDK route, so the
+ * prose a human reads and the list a program gets cannot drift apart.
+ */
+export declare const BUNDLED_CA_PATCHED_MARKER = "the Veris CA was appended to ";
+/**
+ * The script that finds those bundles and appends the Veris CA to each.
+ *
+ * Meant to run AFTER dependencies are installed, and to be re-run: the bundles
+ * do not exist at create time, and an agent installs more of them mid-session,
+ * so there is no create-time moment that covers either. Idempotent by
+ * construction — a file already carrying our certificate is skipped, matched
+ * on a line of its base64 body rather than on the BEGIN line every certificate
+ * shares.
+ *
+ * Appending in place, where the CLI over-mounts a patched copy: a Daytona
+ * sandbox offers no bind mounts and the container is disposable, so editing
+ * the file is the equivalent move. Unwritable files are skipped rather than
+ * sudo'd — a root-owned bundle in the system Python is rarely the one the
+ * application's virtualenv reads, and silently rewriting system trust is a
+ * larger act than this warrants.
+ */
+export declare function bundledCaPatchScript(): string;
+/**
+ * Node is the one runtime the trust variables above cannot reach.
+ *
+ * Daytona overwrites NODE_EXTRA_CA_CERTS and SSL_CERT_FILE inside the sandbox
+ * with its own CA file — right for clients that go through its proxy, which
+ * terminates TLS with that CA. Node is not such a client: it ignores
+ * HTTPS_PROXY, is forwarded to the gateway end to end, and the leaf it
+ * validates is signed by the Veris CA, which Daytona's file lacks. Seen live:
+ * plain `node` failed against a vendor host with UNABLE_TO_VERIFY_LEAF_SIGNATURE.
+ */
+/**
+ * Node's trust flag. NODE_EXTRA_CA_CERTS is Daytona's, and Node's baked-in
+ * Mozilla roots know neither CA — so switch Node to OpenSSL's store:
+ * --use-openssl-ca loads SSL_CERT_FILE (Daytona's file) AND the system
+ * certificate directory, where CA_INSTALL_CMD puts our CA and the distribution
+ * keeps the public roots. Injected as NODE_OPTIONS, which Daytona leaves alone.
+ *
+ * Verified live on Daytona's default image (uid 1001, passwordless sudo,
+ * update-ca-certificates present): 200 from plain `node` with the flag and
+ * our CA in /etc/ssl/certs; UNABLE_TO_VERIFY_LEAF_SIGNATURE without the flag.
+ * So this leans on the store install succeeding. There is no second route:
+ * Daytona's CA file is on a read-only mount, so appending our CA to it — the
+ * obvious alternative — fails for root too.
+ */
+export declare const NODE_TRUST_FLAG = "--use-openssl-ca";
+/** NODE_OPTIONS with the trust flag appended to whatever the caller set. */
+export declare function nodeOptionsWithTrust(existing?: string): string;
 /**
  * The store-based install, for stacks that read a trust store rather than an
  * env var — a Java client honours no CA variable at all. Rebuilds the system