@sealant/sdk 0.18.1 → 0.19.0

package/README.md

@@ -124,6 +124,86 @@ const workspace = await sealant.workspaces.create({
 rootless daemon at launch. The workspace receives `DOCKER_HOST`; Sealant never mounts the host
 Docker socket. GitHub credentials provide both `GH_TOKEN` and `GITHUB_TOKEN` to the workspace.
 
+## Workspace environment variables
+
+Ordinary (non-secret) configuration set on the workspace at creation and inherited by every process
+the platform starts inside it — the harness, later shells, exec'd commands, and their descendants:
+
+```ts
+const workspace = await sealant.workspaces.create({
+  repository: "github.com/acme/billing-service",
+  harness: codex(),
+  env: { APP_MODE: "review", FEATURE_FLAGS: "checkout,invoices" },
+});
+```
+
+The contract, stated plainly:
+
+- **Not for secrets.** Values are persisted verbatim in the durable workspace spec and are returned
+  by workspace-details APIs to authorized clients for the life of that record. Use `credentials` for
+  connected-account material. There is no partial support: secret-looking names — containing
+  `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD`, `CREDENTIAL`, or `APIKEY` (as a substring, so
+  `TOKENIZER_PATH` counts), ending in `_KEY`, or exactly `KEY` — are rejected at create, because the
+  workspace runtime's secret filter would silently drop them before any process could see them. A
+  loud rejection beats a variable that never arrives.
+- **Validated, client-side and server-side, with the same policy.** Names are
+  `[A-Za-z_][A-Za-z0-9_]*` (max 128 chars); values are any UTF-8 up to 4 KiB (empty and multiline
+  included, NUL excluded); at most 128 entries and 32 KiB total per workspace. Platform-owned names
+  (`SEALANT_*`, `HOME`, `PATH`, `TERM`, `DOCKER_HOST`, proxy variables, loader/shell/
+  runtime-injection controls like `LD_*`, `BASH_ENV`, `NODE_OPTIONS`, `PYTHONPATH`, and Git/SSH
+  config controls) are rejected. The policy is exported (`parseWorkspaceEnv`,
+  `findWorkspaceEnvReservedRule`, `formatWorkspaceEnvIssue`, `WORKSPACE_ENV_*` constants) so your
+  own settings surface can validate with the platform's exact rules.
+- **Fixed at creation.** A live workspace is never mutated; a platform-side restart reuses the
+  stored spec. Caller values can never override platform controls or injected connected-account
+  credentials.
+- **No nested-container injection.** Docker Compose or `docker run` inside the workspace can use the
+  values for interpolation, but child containers receive only what the Compose file or the command
+  explicitly passes (`environment`, `env_file`, `-e`). Docker runtime only.
+
+## Secret environment variables
+
+The half of a real `.env` that `env` deliberately refuses — API keys, database URLs with passwords —
+goes through the **transient secret channel**:
+
+```ts
+const workspace = await sealant.workspaces.create({
+  repository: "github.com/acme/billing-service",
+  harness: codex(),
+  env: { APP_MODE: "review" },
+  secretEnv: {
+    DATABASE_URL: "postgres://app:s3cret@db.internal/billing",
+    STRIPE_API_KEY: "sk_live_…",
+  },
+});
+```
+
+What the platform guarantees for `secretEnv`, and how it differs from `env`:
+
+- **Same grammar and size bounds** (`parseWorkspaceSecretEnv`, exported), and the same
+  platform-owned names are reserved — but secret-shaped names are exactly what belongs here.
+  Connected-account names (`GITHUB_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, `GH_TOKEN`) stay reserved:
+  attach those through `credentials`.
+- **Never persisted in the clear.** The map rides the create request beside the spec, is sealed with
+  the install's credential key on the build job, is decrypted by the worker just before launch, and
+  the sealed row is cleared once the launch settles. It is never in the blueprint, the attempt
+  snapshot, `WorkspaceDetails`, or any read API.
+- **Never in `docker run` argv or container env.** The worker stages a `0600` file the workspace
+  daemon reads once at boot and removes it the moment the workspace is ready. `docker inspect` shows
+  a file path, not values.
+- **Inherited by every process the platform starts in the workspace**, winning over `env` and
+  container env for the same name — the harness, later shells, exec'd commands, Services.
+- **Masked in captured output.** Every value seeds the daemon's redactor regardless of its name, so
+  a `DATABASE_URL` a process echoes is recorded as `***REDACTED***`, like a token.
+- **Fixed at creation.** A platform-side _restart_ of the workspace runs **without** secret env (the
+  sealed copy is gone by design); create a new workspace to re-supply it. Docker runtime only;
+  nested containers started by Compose or `docker run` inside the workspace still receive only what
+  you explicitly pass.
+
+Not covered, and worth saying plainly: a process that _deliberately_ writes a secret to a file in
+the repository or to a mount is producing ordinary workspace state, and the redactor masks captured
+I/O, not files.
+
 ## Dotfiles and shell
 
 Bring your own environment: a login shell and dotfiles applied before the workspace accepts work.

package/dist/effect/api-client.d.ts

@@ -1063,6 +1063,9 @@ declare const buildControlPlaneClient: (config: SealantInternalConfig) => Effect
                     readonly github?: string | undefined;
                 } | undefined;
                 readonly spec: unknown;
+                readonly secretEnv?: {
+                    readonly [x: string]: string;
+                } | undefined;
                 readonly ttlSeconds?: number | undefined;
             };
             readonly responseMode?: Mode;
@@ -2381,6 +2384,9 @@ declare const SealantApiClient_base: Context.ServiceClass<SealantApiClient, "@se
                     readonly github?: string | undefined;
                 } | undefined;
                 readonly spec: unknown;
+                readonly secretEnv?: {
+                    readonly [x: string]: string;
+                } | undefined;
                 readonly ttlSeconds?: number | undefined;
             };
             readonly responseMode?: Mode;

package/dist/effect/operations.d.ts

@@ -25,6 +25,9 @@ export declare const createWorkspaceOp: (payload: {
         readonly github?: string | undefined;
     } | undefined;
     readonly spec: unknown;
+    readonly secretEnv?: {
+        readonly [x: string]: string;
+    } | undefined;
     readonly ttlSeconds?: number | undefined;
 }, idempotencyKey?: string | undefined) => Effect.Effect<{
     readonly workspaceId: string;

package/dist/index.d.ts

@@ -18,3 +18,5 @@ export { Sealant } from "./client.js";
 export { claudeCode, codex, customHarness, opencode } from "./harness.js";
 export { SealantApiError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
 export type * from "./types.js";
+export { findWorkspaceEnvReservedRule, findWorkspaceSecretEnvReservedRule, formatWorkspaceEnvIssue, parseWorkspaceEnv, parseWorkspaceSecretEnv, WORKSPACE_ENV_MAX_ENTRIES, WORKSPACE_ENV_MAX_NAME_LENGTH, WORKSPACE_ENV_MAX_TOTAL_BYTES, WORKSPACE_ENV_MAX_VALUE_BYTES, WORKSPACE_ENV_NAME_PATTERN, WORKSPACE_ENV_SECRET_MARKERS, } from "@sealant/api-contracts/workspace-environment";
+export type { WorkspaceEnvIssue, WorkspaceEnvParseResult, WorkspaceEnvReservedRule, } from "@sealant/api-contracts/workspace-environment";

package/dist/index.js

@@ -17,3 +17,6 @@
 export { Sealant } from "./client.js";
 export { claudeCode, codex, customHarness, opencode } from "./harness.js";
 export { SealantApiError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
+// The workspace environment policy (`CreateOptions.env` validation) is public API: downstream
+// products validate at their own boundaries with the exact rules the platform enforces.
+export { findWorkspaceEnvReservedRule, findWorkspaceSecretEnvReservedRule, formatWorkspaceEnvIssue, parseWorkspaceEnv, parseWorkspaceSecretEnv, WORKSPACE_ENV_MAX_ENTRIES, WORKSPACE_ENV_MAX_NAME_LENGTH, WORKSPACE_ENV_MAX_TOTAL_BYTES, WORKSPACE_ENV_MAX_VALUE_BYTES, WORKSPACE_ENV_NAME_PATTERN, WORKSPACE_ENV_SECRET_MARKERS, } from "@sealant/api-contracts/workspace-environment";

package/dist/internal/blueprint.d.ts

@@ -26,6 +26,9 @@ export declare const buildCreateWorkspaceRequest: (options: CreateOptions, confi
             readonly github?: string | undefined;
         } | undefined;
         readonly spec: unknown;
+        readonly secretEnv?: {
+            readonly [x: string]: string;
+        } | undefined;
         readonly ttlSeconds?: number | undefined;
     };
 };

package/dist/internal/blueprint.js

@@ -11,6 +11,7 @@
  * plane resolves those account references server-side (never secret material over this path).
  */
 import { randomUUID } from "node:crypto";
+import { formatWorkspaceEnvIssue, parseWorkspaceEnv, parseWorkspaceSecretEnv, } from "@sealant/api-contracts/workspace-environment";
 import { SealantError } from "../errors.js";
 import { mapWorkspaceCredentials } from "./credentials.js";
 import { parseTtlSeconds } from "./duration.js";
@@ -85,6 +86,44 @@ export const buildCreateWorkspaceRequest = (options, config) => {
         };
     const dotfilesRepository = options.dotfiles?.repository;
     const dotfilesArchives = options.dotfiles?.archives ?? [];
+    // Client-side rejection with the exact policy the control plane re-applies on parse: same
+    // module, same messages, so a bad name fails here instead of as an opaque 400.
+    const envResult = options.env === undefined ? undefined : parseWorkspaceEnv(options.env);
+    if (envResult !== undefined && !envResult.ok) {
+        throw new SealantError(`workspaces.create \`env\` was rejected: ${envResult.issues
+            .map(formatWorkspaceEnvIssue)
+            .join("; ")}`, { code: "invalid_workspace_env" });
+    }
+    const userEnv = envResult === undefined ? undefined : envResult.env;
+    const secretEnvResult = options.secretEnv === undefined ? undefined : parseWorkspaceSecretEnv(options.secretEnv);
+    if (secretEnvResult !== undefined && !secretEnvResult.ok) {
+        throw new SealantError(`workspaces.create \`secretEnv\` was rejected: ${secretEnvResult.issues
+            .map(formatWorkspaceEnvIssue)
+            .join("; ")}`, { code: "invalid_workspace_secret_env" });
+    }
+    // Secrets ride the request TOP LEVEL, never the spec: the spec is the durable, API-visible
+    // blueprint; the transient channel is a separate field the control plane seals until launch.
+    const secretEnv = secretEnvResult === undefined || Object.keys(secretEnvResult.env).length === 0
+        ? undefined
+        : secretEnvResult.env;
+    // One `runtime` object for every runtime-scoped field: two conditional `runtime:` spreads in the
+    // spec literal would let the later one silently clobber the earlier.
+    const runtime = {
+        ...(dotfilesArchives.length === 0
+            ? {}
+            : {
+                dotfilesArchives: dotfilesArchives.map((archive) => ({
+                    data: archive.data,
+                    ...(archive.manager === undefined ? {} : { manager: archive.manager }),
+                    ...(archive.target === undefined ? {} : { target: archive.target }),
+                    ...(archive.bootstrap === undefined ? {} : { bootstrap: archive.bootstrap }),
+                    ...(archive.bootstrapCommand === undefined
+                        ? {}
+                        : { bootstrapCommand: archive.bootstrapCommand }),
+                })),
+            }),
+        ...(userEnv === undefined || Object.keys(userEnv).length === 0 ? {} : { userEnv }),
+    };
     const spec = {
         version: "1",
         sources: {
@@ -138,21 +177,7 @@ export const buildCreateWorkspaceRequest = (options, config) => {
                 ? {}
                 : { dotfilesBootstrapCommand: dotfilesRepository.bootstrapCommand }),
         },
-        ...(dotfilesArchives.length === 0
-            ? {}
-            : {
-                runtime: {
-                    dotfilesArchives: dotfilesArchives.map((archive) => ({
-                        data: archive.data,
-                        ...(archive.manager === undefined ? {} : { manager: archive.manager }),
-                        ...(archive.target === undefined ? {} : { target: archive.target }),
-                        ...(archive.bootstrap === undefined ? {} : { bootstrap: archive.bootstrap }),
-                        ...(archive.bootstrapCommand === undefined
-                            ? {}
-                            : { bootstrapCommand: archive.bootstrapCommand }),
-                    })),
-                },
-            }),
+        ...(Object.keys(runtime).length === 0 ? {} : { runtime }),
         target: {
             os: options.baseImage !== undefined
                 ? { family: "custom", mode: "require", baseImage: options.baseImage }
@@ -174,6 +199,7 @@ export const buildCreateWorkspaceRequest = (options, config) => {
             ...(options.name === undefined ? {} : { name: options.name }),
             ...(options.ttl === undefined ? {} : { ttlSeconds: parseTtlSeconds(options.ttl) }),
             spec,
+            ...(secretEnv === undefined ? {} : { secretEnv }),
         },
     };
 };

package/dist/types.d.ts

@@ -215,6 +215,36 @@ export interface CreateOptions {
     readonly shell?: "bash" | "zsh" | "fish";
     /** Dotfiles applied before the workspace accepts work (see `WorkspaceDotfilesOptions`). */
     readonly dotfiles?: WorkspaceDotfilesOptions;
+    /**
+     * Ordinary (non-secret) environment variables set on the workspace container and inherited by
+     * every process the platform starts inside it — the harness, later shells, exec'd commands, and
+     * their descendants. Validated client-side against the public policy re-exported from this
+     * package (`parseWorkspaceEnv`): names are `[A-Za-z_][A-Za-z0-9_]*`, platform-owned and
+     * secret-looking names are rejected loudly (the workspace runtime filters names containing
+     * `TOKEN`/`SECRET`/`PASSWORD`/`PASSWD`/`CREDENTIAL`/`APIKEY`, ending in `_KEY`, or exactly
+     * `KEY` — a value under such a name would silently never arrive). Not for secrets: values are
+     * persisted verbatim in the durable workspace spec and returned by workspace-details APIs; use
+     * `credentials` for connected-account material. The map is fixed at creation — a live workspace
+     * is never mutated, and a platform-side restart reuses the stored spec. Containers started
+     * INSIDE the workspace by Docker Compose or `docker run` receive only what the Compose file or
+     * command explicitly passes. Docker runtime only.
+     */
+    readonly env?: Readonly<Record<string, string>>;
+    /**
+     * SECRET environment variables for the workspace — API keys, database URLs with passwords,
+     * anything a dev server needs that must not be persisted or echoed. Same grammar and size
+     * bounds as `env`, validated client-side by `parseWorkspaceSecretEnv`; secret-shaped names are
+     * exactly what belongs here, while platform-owned names and connected-account names
+     * (`GITHUB_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`) stay reserved. Delivered through the transient
+     * secret channel: encrypted at rest on the build job until launch, handed to the workspace
+     * daemon as a boot file that is removed once the workspace is ready, never written to the
+     * blueprint, the attempt snapshot, `docker inspect`, or any read API — and every value is
+     * masked in captured process output. Inherited by every process the platform starts in the
+     * workspace, winning over `env` and container env for the same name. Fixed at creation; a
+     * platform-side RESTART of the workspace runs without secret env (create a new workspace
+     * instead). Docker runtime only.
+     */
+    readonly secretEnv?: Readonly<Record<string, string>>;
     /** Runtime-managed services that need more than installing an OS package. */
     readonly services?: WorkspaceServicesOptions;
     /** When true (default), resolve only once the workspace runtime is live. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/sdk",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "The fluent public SDK for Sealant — create a workspace, run a harness, replay the record.",
   "license": "Apache-2.0",
   "repository": {
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@sealant/api-contracts": "^0.18.1"
+    "@sealant/api-contracts": "^0.19.0"
   },
   "devDependencies": {
     "@effect/vitest": "4.0.0-beta.85",