@veris-ai/daytona 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# @veris-ai/daytona
+
+Run code in a [Daytona](https://daytona.io) sandbox where calls to
+`api.stripe.com` and the rest of your vendor stack are answered by **Veris
+twins** — stateful, contract-accurate fakes — with the code under test
+completely unmodified.
+
+No base-URL overrides, no injected config, no mocking library. Your code keeps
+its production hostnames, credentials and SDKs; the network layer does the rest.
+And every run ends with a **receipt** of what the vendor actually received.
+
+## Install
+
+```sh
+npm i @veris-ai/daytona @daytona/sdk
+```
+
+Both, because `@daytona/sdk` is a peer dependency — that is what keeps
+`err instanceof DaytonaNotFoundError` working across the package boundary.
+
+| variable | where from |
+|---|---|
+| `DAYTONA_API_KEY` | [app.daytona.io/dashboard/keys](https://app.daytona.io/dashboard/keys) |
+| `VERIS_API_KEY` | [studio.veris.ai](https://studio.veris.ai) |
+| `VERIS_ENVIRONMENT_ID` | a Veris environment — it decides which vendor services your twin gets |
+
+## Use
+
+Change one import. Everything else in your Daytona code stays as it was.
+
+```ts
+import { Daytona } from '@veris-ai/daytona'   // was '@daytona/sdk'
+
+const daytona = new Daytona({ apiKey: process.env.DAYTONA_API_KEY })
+const sbx = await daytona.create({ image: 'python:3.12-slim' })
+
+await sbx.process.executeCommand('pytest tests/integration')
+
+// The assertion the whole thing exists for: did the twin actually see it?
+await sbx.veris.assertTouched('stripe', { method: 'POST', path: '/v1/charges' })
+
+await sbx.delete()   // deletes the twin too
+```
+
+This package re-exports everything from `@daytona/sdk`, so it is the only import
+you need to change. No particular sandbox image is required.
+
+### Why `assertTouched` and not just a green suite
+
+A test suite that skipped its integration and one that exercised it look
+identical from inside the sandbox. So does a call your code believed it made.
+The receipt is the only thing that separates them, and `assertTouched` throws
+when it is empty.
+
+## `sbx.veris`
+
+| method | what it gives you |
+|---|---|
+| `receipt()` | every request the twin received, with the mode and integrity of the run |
+| `receipt(service)` | the same for one service |
+| `assertTouched(service, match?)` | throws unless the twin saw matching traffic |
+| `services()` | what the twin answers for, and where |
+| `getDataPlaneEnv()` | `{ DATABASE_URL: … }` for non-HTTP twin services |
+| `getTrustEnv()` | the CA variables injected into the sandbox |
+| `deliverTo(port \| url)` | point vendor webhooks back at your sandbox |
+
+`sbx.verisSandboxId` is the twin's id — not to be confused with `sbx.id`, which
+is Daytona's.
+
+## Options
+
+```ts
+await daytona.create({
+  image: 'node:22',
+  veris: {
+    egress: 'strict',          // default. 'open' sets no allowlist — debugging only
+    allowOut: ['internal.corp'],
+    allowRegistries: true,     // default. npm, PyPI, apt, crates…
+    installCa: true,           // default
+    ttlMinutes: 60,
+    attachSandboxId: 'sbx_…',  // reuse an existing twin; delete() will not remove it
+    disabled: false,           // true = a plain Daytona sandbox, no twin
+  },
+})
+```
+
+Coordinates can also come from `veris.apiKey` / `veris.environmentId` /
+`veris.apiBase` instead of the environment.
+
+## How it works
+
+Every sandbox is created with two Daytona parameters: a `domainAllowList` (the
+vendor hostnames the twin answers for, the gateway, the twin's data planes, and
+package registries — nothing else leaves) and an `outboundProxyUrl` pointing at
+the Veris gateway over HTTP CONNECT.
+
+Daytona chains them: sandbox traffic reaches Daytona's own proxy, which drops
+anything not allowlisted and forwards the rest to the gateway, which answers
+vendor hostnames from the twin. Nothing of ours runs inside the sandbox, which
+is why any image works.
+
+Before `create()` resolves, a canary probe dials a reserved hostname only the
+gateway answers, whose body carries the twin id. It proves in one request that
+egress is tunnelled, that the credential reached the right twin, and that trust
+is wired — and it cannot pass by accident, because outside the tunnel that host
+has no listener. It runs again on every `receipt()`, so a receipt is never
+reported from a sandbox whose egress cannot be vouched for.
+
+## Errors
+
+Every error is a `VerisError` with a `phase`, so a failure says which of the
+four systems involved refused:
+
+`credentials` · `twin-provision` · `credential-mint` · `sandbox-create` ·
+`ca-install` · `canary` · `receipt` · `attach`
+
+## Limitations
+
+- **Requires a Veris control plane that serves an HTTP CONNECT gateway.**
+  Daytona accepts only `http`/`https` outbound proxies, so a SOCKS-only gateway
+  cannot be used; `create()` then fails at `credential-mint` saying so.
+- **QUIC/HTTP3 and ECH are not intercepted.** The gateway relays TCP. Both are
+  reported in the receipt's `leaks` rather than silently omitted.
+
+## License
+
+Apache-2.0. Source: [veris-ai/veris-daytona](https://github.com/veris-ai/veris-daytona).

package/dist/control-plane.d.ts

@@ -0,0 +1,89 @@
+export interface RouteEntry {
+    /** A real vendor hostname the service answers for. */
+    host: string;
+    /** Path prefixes narrowing the claim when several services share the host. */
+    paths?: string[] | null;
+}
+export interface ServiceInfo {
+    name: string;
+    status: string;
+    /** What the code under test points at: gateway URL for http services, a DSN for e.g. postgres. */
+    url: string;
+    /** Where /veris/* lives — always an http URL. */
+    control_url: string;
+    env_hint?: string | null;
+    routes?: RouteEntry[] | null;
+}
+export interface TwinSandbox {
+    id: string;
+    environment_id: string;
+    status: 'provisioning' | 'ready' | 'failed' | 'degraded' | 'terminating' | string;
+    created_at?: string | null;
+    expires_at?: string | null;
+    services: ServiceInfo[];
+    failure_reason?: string | null;
+    metadata?: Record<string, string>;
+}
+/** Response of POST /v1/sandboxes/{sid}/egress-credential (gateway mode). */
+export interface EgressCredential {
+    /** SOCKS5 endpoint. What @veris-ai/e2b uses; Daytona cannot (it accepts only
+     *  http/https outbound proxies). */
+    socks_address: string;
+    /** HTTP CONNECT endpoint, host:port. Absent on a control plane that predates
+     *  the CONNECT listener — which is a hard error here, since Daytona has no
+     *  other way to reach the gateway. */
+    connect_address?: string;
+    /** The CONNECT endpoint as a complete proxy URL, credentials included.
+     *  Preferred over building one from connect_address: the gateway owns its own
+     *  auth format, and guessing it is how you end up sending the wrong password. */
+    http_proxy_url?: string;
+    username: string;
+    password: string;
+    ca_pem: string;
+    canary_host: string;
+    min_sdk?: string;
+    expires_at?: string;
+    /** Server-served CA trust env map; the SDK's vendored list is the fallback. */
+    trust_env?: Record<string, string>;
+}
+/** Mutable fields of a running twin. An OMITTED key is left alone; an explicit
+ *  null is a value (client_base_url: null unregisters). */
+export interface SandboxPatch {
+    ttl_minutes?: number;
+    client_base_url?: string | null;
+}
+export interface ControlPlaneOpts {
+    apiKey: string;
+    apiBase: string;
+    /** Sent as X-Veris-SDK on every request, so the server can version-gate. */
+    sdkVersion: string;
+}
+export declare class ControlPlane {
+    readonly apiBase: string;
+    private readonly headers;
+    constructor(opts: ControlPlaneOpts);
+    private request;
+    private json;
+    createTwin(environmentId: string, opts?: {
+        ttlMinutes?: number;
+        metadata?: Record<string, string>;
+    }): Promise<TwinSandbox>;
+    getTwin(sandboxId: string): Promise<TwinSandbox | null>;
+    /** Poll until the twin reports ready. "failed" is terminal per the API docs. */
+    waitReady(sandboxId: string, timeoutMs: number): Promise<TwinSandbox>;
+    services(sandboxId: string): Promise<ServiceInfo[]>;
+    deleteTwin(environmentId: string, sandboxId: string): Promise<boolean>;
+    /**
+     * Mint (or re-mint) the gateway egress credential for a twin. Returns null
+     * when the control plane does not offer gateway mode at all (404 — route
+     * absent), so `mode: 'auto'` can fall back; throws VerisGatewayNotOfferedError
+     * on an explicit version refusal (409 sdk_too_old).
+     */
+    mintEgressCredential(environmentId: string, sandboxId: string): Promise<EgressCredential | null>;
+    /** PATCH the twin resource. Omitted fields are untouched by the server. */
+    updateSandbox(environmentId: string, sandboxId: string, patch: SandboxPatch): Promise<void>;
+    /** Extend a twin's TTL so it stays in lockstep with an extended Daytona sandbox. */
+    extendTtl(environmentId: string, sandboxId: string, ttlMinutes: number): Promise<void>;
+    /** Create-time preflight: is the gateway infrastructure up, per the control plane? */
+    gatewayHealth(): Promise<void>;
+}

package/dist/daytona.d.ts

@@ -0,0 +1,92 @@
+import { Daytona as BaseDaytona } from '@daytona/sdk';
+import type { CreateSandboxFromImageParams, CreateSandboxFromSnapshotParams, DaytonaConfig, ListSandboxesQuery, Sandbox } from '@daytona/sdk';
+import type { VerisApi } from './veris-api';
+import type { EgressMode } from './network';
+import { CA_CERT_PATH } from './trust';
+export interface VerisOpts {
+    /** Veris API key. Falls back to process.env.VERIS_API_KEY. Required. */
+    apiKey?: string;
+    /** Veris environment the twin is deployed from. Falls back to process.env.VERIS_ENVIRONMENT_ID. */
+    environmentId?: string;
+    /** Control plane base. Falls back to process.env.VERIS_API_BASE, then 'https://svc.api.veris.ai'. */
+    apiBase?: string;
+    /** Attach to an EXISTING twin instead of provisioning one (advanced). delete() will NOT remove it. */
+    attachSandboxId?: string;
+    /** Twin TTL backstop, minutes. Default 60, kept in step with the sandbox's ttlMinutes. */
+    ttlMinutes?: number;
+    /** 'strict' (default): the sandbox reaches only its twin, its data planes,
+     *  the control plane and package registries. 'open': no allowlist at all —
+     *  debugging only, because a bypassing client then reaches the real vendor. */
+    egress?: EgressMode;
+    /** Extra hostnames to allow out. */
+    allowOut?: string[];
+    /** Allow package registries (npm, PyPI, apt, …). Default true: a coding
+     *  sandbox that cannot install dependencies is not usable. */
+    allowRegistries?: boolean;
+    /** Install the gateway CA into the sandbox trust store. Default true; without
+     *  it every HTTPS call to a vendor host fails certificate validation. */
+    installCa?: boolean;
+    /** Inject { [env_hint]: dsn } for non-HTTP twin services. Default true. */
+    dataPlaneEnv?: boolean;
+    /** Turn Veris off entirely for this create — a plain Daytona sandbox. */
+    disabled?: boolean;
+}
+export interface VerisDaytonaConfig extends DaytonaConfig {
+    veris?: VerisOpts;
+}
+/** A Daytona sandbox with the Veris surface attached. */
+export type VerisSandbox = Sandbox & {
+    /** Receipts, services, assertions. Everything Veris adds. */
+    veris: VerisApi;
+    /** The Veris twin's id. Not to be confused with `sandbox.id`, the Daytona one. */
+    verisSandboxId: string;
+};
+/** Is this sandbox one of ours? Narrows for callers who hold a bare Sandbox. */
+export declare function isVerisSandbox(sbx: Sandbox): sbx is VerisSandbox;
+export declare class Daytona extends BaseDaytona {
+    private readonly verisDefaults;
+    constructor(config?: VerisDaytonaConfig);
+    create(params?: CreateSandboxFromSnapshotParams & {
+        veris?: VerisOpts;
+    }, options?: {
+        timeout?: number;
+    }): Promise<Sandbox>;
+    create(params?: CreateSandboxFromImageParams & {
+        veris?: VerisOpts;
+    }, options?: {
+        onSnapshotCreateLogs?: (chunk: string) => void;
+        timeout?: number;
+    }): Promise<Sandbox>;
+    /**
+     * Rehydrate the Veris surface on an existing sandbox.
+     *
+     * Not an optimisation — a necessity. The OpenCode plugin reconnects to a
+     * sandbox with get() on every resumed session and deletes through get() too,
+     * so a get() that returned a bare Sandbox would mean no receipts after any
+     * restart and a leaked twin on every delete.
+     */
+    get(sandboxIdOrName: string): Promise<Sandbox>;
+    /** Same rehydration for the sandboxes a list() streams. */
+    list(query?: ListSandboxesQuery): AsyncIterableIterator<Sandbox>;
+    /**
+     * Attach the Veris surface to a sandbox whose labels say it has a twin.
+     * A sandbox without our labels is passed through untouched — callers can use
+     * this client for ordinary Daytona work.
+     */
+    private rehydrate;
+    private provisionTwin;
+    /**
+     * Hang the Veris surface off the instance, and wrap delete() so teardown is
+     * automatic.
+     *
+     * Wrapping rather than asking callers to remember is the point: the OpenCode
+     * plugin's existing `sandbox.delete()` then removes the twin too, with no
+     * change to the plugin at all. A twin outlives its sandbox otherwise, until
+     * its TTL reaps it — invisible until the bill arrives.
+     */
+    private attach;
+    /** super.create through the overload the params actually match. */
+    private baseCreate;
+}
+export default Daytona;
+export { CA_CERT_PATH };

package/dist/errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Every failure phase a Veris error can name. Bring-up spans four systems
+ * (control plane, Daytona API, the sandbox, the Veris gateway), so errors
+ * carry a structured phase rather than a wall of logs.
+ */
+export type VerisErrorPhase = 'credentials' | 'twin-provision' | 'gateway-preflight' | 'credential-mint' | 'sandbox-create' | 'ca-install' | 'canary' | 'receipt' | 'attach';
+/**
+ * Base class for every error this package throws. Deliberately NOT a subclass
+ * of any Daytona error: `e instanceof VerisError` cleanly separates Veris
+ * failures from Daytona failures in one catch.
+ */
+export declare class VerisError extends Error {
+    readonly phase?: VerisErrorPhase;
+    /** The Veris twin's sandbox id, when one exists yet. */
+    readonly verisSandboxId?: string;
+    /** Verbatim control-plane response body, when the failure came from an API call. */
+    readonly responseBody?: unknown;
+    constructor(message: string, opts?: {
+        phase?: VerisErrorPhase;
+        verisSandboxId?: string;
+        responseBody?: unknown;
+        cause?: unknown;
+    });
+}
+/** A required credential/coordinate is missing. Thrown before any network call, naming the exact variable. */
+export declare class MissingCredentialsError extends VerisError {
+}
+/** The Veris gateway infrastructure is down (control-plane health said so). */
+export declare class VerisGatewayUnreachableError extends VerisError {
+}
+/** The control plane does not offer gateway mode (endpoint absent, or this SDK version is below min_sdk). */
+export declare class VerisGatewayNotOfferedError extends VerisError {
+    /** Server-announced minimum SDK version, when the refusal carried one. */
+    readonly minSdk?: string;
+    constructor(message: string, opts?: ConstructorParameters<typeof VerisError>[1] & {
+        minSdk?: string;
+    });
+}
+/** The canary probe failed: egress is not (or no longer) reaching the twin. */
+export declare class ReceiptIntegrityError extends VerisError {
+}
+/** assertTouched(): the named service saw zero intercepted requests — green without the receipt. */
+export declare class VerisUntouchedError extends VerisError {
+    readonly service: string;
+    constructor(message: string, service: string, opts?: ConstructorParameters<typeof VerisError>[1]);
+}
+/** The Daytona sandbox is alive but its Veris twin is gone (TTL expiry, delete, reset). */
+export declare class TwinExpiredError extends VerisError {
+}
+/** The sandbox image cannot host the Veris layer — in practice, no
+ *  ca-certificates, so the gateway CA cannot be trusted. */
+export declare class SnapshotUnsupportedError extends VerisError {
+}
+/** An inherited Daytona operation that would break the one-sandbox-one-twin invariant (e.g. fork). */
+export declare class UnsupportedOperationError extends VerisError {
+}

package/dist/gateway.d.ts

@@ -0,0 +1,65 @@
+import type { Sandbox } from '@daytona/sdk';
+/** Single-quote a string for POSIX sh. */
+export declare function shellQuote(s: string): string;
+/**
+ * Build the proxy URL Daytona is handed.
+ *
+ * The username is the tenant demux key — the gateway reads the sandbox id out
+ * of it. There is no separate secret: the id IS the capability, exactly as the
+ * SOCKS path treats it, so the password is a placeholder the gateway ignores.
+ *
+ * RFC 3986 §3.2.1 notes that `user:password` in userinfo is deprecated. It is
+ * also the only form HTTP proxy clients accept for RFC 7617 Basic credentials,
+ * and it is what Daytona forwards, so it is what we emit.
+ *
+ * `encodeURIComponent` is exactly right for userinfo: everything it leaves raw
+ * is unreserved or a sub-delim, and it escapes both separators — `:` to %3A and
+ * `@` to %40 — so a username can never break out into the authority.
+ *
+ * The address is validated rather than interpolated: it arrives from the
+ * control plane, and an unchecked value here would land in a URL and then in
+ * every client's proxy configuration.
+ */
+export declare function gatewayProxyUrl(credential: {
+    http_proxy_url?: string;
+    connect_address?: string;
+    username: string;
+}): string;
+/**
+ * Make the gateway's CA trusted, without requiring anything of the image.
+ *
+ * Defensive rather than load-bearing on Daytona today, and the distinction is
+ * worth recording. Daytona's own proxy terminates TLS with a certificate signed
+ * by ITS CA — already trusted in the image — and re-originates to the gateway,
+ * so the client never validates our forged leaf. Verified: a vendor call
+ * succeeds with --cacert naming only Daytona's CA.
+ *
+ * We install ours regardless, because the day Daytona tunnels CONNECT
+ * end-to-end (the ordinary behaviour for an HTTP proxy) the gateway's leaf
+ * reaches the client directly and nothing works without it. One upload and one
+ * shell command against a total outage is a trade worth making.
+ *
+ * The obvious approach — drop the cert in /usr/local/share/ca-certificates and
+ * run update-ca-certificates — needs root AND that tool, and Daytona's default
+ * image has neither. So the artefact is a bundle we build ourselves at a
+ * world-writable path: the distribution's roots (when it has any) plus ours.
+ *
+ * Daytona overrides the best-known trust variables with its own CA, correctly
+ * for its proxy. The dozen it does not set still point at this bundle, which
+ * carries both CAs and every public root — so those tools verify rather than
+ * break.
+ *
+ * The system-store install still runs when it can, for anything that reads the
+ * store directly rather than honouring the variables. It is best-effort.
+ */
+export declare function installCa(sandbox: Sandbox, caPem: string): Promise<void>;
+/**
+ * The canary probe: one HTTPS request from inside the sandbox to a reserved
+ * hostname only the gateway answers, with the twin id in the body.
+ *
+ * Green proves three things in a single request — egress really is tunnelled
+ * through the gateway, the credential demuxed to the right twin, and the CA
+ * install worked. Dialled outside the tunnel the host has no listener, so this
+ * cannot pass by accident, which is what makes a receipt worth reading.
+ */
+export declare function probeCanary(sandbox: Sandbox, canaryHost: string, expectedTwinId: string): Promise<void>;