@dura-run/cli 0.3.2 → 0.4.0

package/README.md

@@ -45,12 +45,12 @@ All project-scoped commands pick up `projectId` from `dura.json` — you only ne
 
 ### `dura dev` runs your handlers in-process (GH #118)
 
-Until we wire isolated-vm into the local runner, `dura dev` loads your
-automation code via native `import(...)` in the CLI's Node process. That
-process has full access to your filesystem — including `~/.dura/config`
-(where the CLI stores your API key), `~/.ssh`, `~/.aws`, and environment
-variables. A malicious npm dependency anywhere in your handler's import
-graph could read those files and exfiltrate them on the first request.
+`dura dev` loads your automation code via native `import(...)` in the
+CLI's Node process. That process has full access to your filesystem —
+including `~/.dura/config` (where the CLI stores your API key), `~/.ssh`,
+`~/.aws`, and environment variables. A malicious npm dependency anywhere
+in your handler's import graph could read those files and exfiltrate
+them on the first request.
 
 To make this risk explicit, `dura dev` refuses to start whenever you
 have credentials stored locally unless you opt in per project:
@@ -77,9 +77,15 @@ Treat `dura dev` with the same trust you'd give `node -e ...` in a
 project that imports every one of your dependencies — audit your
 `package.json` (and lockfile) before trusting a new project.
 
-We're tracking a full isolated-vm migration for local dev in
-[GH #147](https://github.com/dura-run/dura-run/issues/147) — once
-that ships, the trust gate will be removed.
+The trust gate is the permanent mitigation. We evaluated a full
+isolated-vm migration for local dev in
+[GH #147](https://github.com/dura-run/dura-run/issues/147) and declined
+it: the threat window is narrow (malicious deps mostly fire at install
+or require-time, which sandboxing `dura dev` wouldn't help with), and
+the engineering cost is high relative to the mitigation. Production
+handlers run in a real V8 isolate via the executor service. See
+[docs/internal/architecture.md](../../docs/internal/architecture.md) for
+the threat-model decision.
 
 ## Documentation
 

package/dist/dura.js

@@ -2262,9 +2262,20 @@ function formatObject(data) {
 }
 
 // src/lib/config-store.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync
+} from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+function chmodPosix(path, mode) {
+  if (process.platform === "win32")
+    return;
+  chmodSync(path, mode);
+}
 function getConfigDir() {
   const explicitDir = process.env["DURA_CONFIG_DIR"];
   if (explicitDir)
@@ -2301,12 +2312,15 @@ function readConfig() {
 function writeConfig(config) {
   const dir = getConfigDir();
   if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
+    mkdirSync(dir, { recursive: true, mode: 448 });
   }
-  writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + `
+  chmodPosix(dir, 448);
+  const path = getConfigPath();
+  writeFileSync(path, JSON.stringify(config, null, 2) + `
 `, {
     mode: 384
   });
+  chmodPosix(path, 384);
 }
 function updateConfig(partial) {
   const current = readConfig();
@@ -3003,10 +3017,19 @@ var init_project_id = () => {};
 // src/commands/secrets.ts
 var exports_secrets = {};
 __export(exports_secrets, {
-  registerSecretsCommand: () => registerSecretsCommand
+  registerSecretsCommand: () => registerSecretsCommand,
+  escapeEnvValue: () => escapeEnvValue
 });
-import { writeFileSync as writeFileSync3 } from "node:fs";
+import {
+  writeFileSync as writeFileSync3,
+  existsSync as existsSync4,
+  readFileSync as readFileSync4,
+  appendFileSync
+} from "node:fs";
 import { join as join4 } from "node:path";
+function escapeEnvValue(v) {
+  return v.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n");
+}
 function resolveAuth(opts, output) {
   const projectId = resolveProjectId({ project: opts.project });
   if (!projectId) {
@@ -3066,28 +3089,65 @@ function registerSecretsCommand(program2) {
       reportApiError(output, err, "SECRET_REMOVE_FAILED");
     }
   });
-  secrets.command("pull").description("Write secrets to .env.local for local development").option("--project <id>", "Project ID (defaults to dura.json)").option("--api-url <url>", "API base URL").option("--token <token>", "Auth token").option("--dir <path>", "Directory to write .env.local to", ".").action(async (opts, cmd) => {
+  secrets.command("pull").description("Write secrets to .env.local for local development (file holds DECRYPTED plaintext secrets)").option("--project <id>", "Project ID (defaults to dura.json)").option("--confirm", "Overwrite an existing .env.local").option("--api-url <url>", "API base URL").option("--token <token>", "Auth token").option("--dir <path>", "Directory to write .env.local to", ".").action(async (opts, cmd) => {
     const output = getOutput(cmd);
+    const envPath = join4(opts.dir, ".env.local");
+    if (existsSync4(envPath) && !opts.confirm) {
+      output.error("FILE_EXISTS", `${envPath} already exists. Re-run with --confirm to overwrite.`);
+      return;
+    }
     const auth = resolveAuth(opts, output);
     if (!auth)
       return;
     const { client, projectId } = auth;
     try {
       const values = await client.get(`/api/v1/projects/${projectId}/secrets/pull`);
-      const lines = Object.entries(values).map(([k, v]) => `${k}="${v.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n")}"`);
-      const envPath = join4(opts.dir, ".env.local");
+      const lines = Object.entries(values).map(([k, v]) => `${k}="${escapeEnvValue(v)}"`);
       writeFileSync3(envPath, lines.join(`
 `) + `
 `, { mode: 384 });
+      let gitignore;
+      try {
+        gitignore = ensureGitignored(opts.dir) ? "added" : "present";
+      } catch {
+        gitignore = "failed";
+        output.warn(`Could not update ${join4(opts.dir, ".gitignore")} — add ".env.local" to it yourself; the file holds plaintext secrets.`);
+      }
       output.success({
         written: envPath,
-        count: Object.keys(values).length
+        count: Object.keys(values).length,
+        gitignore
       });
     } catch (err) {
       reportApiError(output, err, "SECRET_PULL_FAILED");
     }
   });
 }
+function ensureGitignored(dir) {
+  const gitignorePath = join4(dir, ".gitignore");
+  const covers = new Set([
+    ".env.local",
+    "/.env.local",
+    ".env.local/",
+    ".env*",
+    ".env.*",
+    "*.local"
+  ]);
+  let existing = "";
+  if (existsSync4(gitignorePath)) {
+    existing = readFileSync4(gitignorePath, "utf-8");
+    const alreadyCovered = existing.split(`
+`).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#")).some((line) => covers.has(line));
+    if (alreadyCovered)
+      return false;
+  }
+  const prefix = existing.length > 0 && !existing.endsWith(`
+`) ? `
+` : "";
+  appendFileSync(gitignorePath, `${prefix}.env.local
+`);
+  return true;
+}
 var init_secrets = __esm(() => {
   init_src3();
   init_api_client();
@@ -3096,6 +3156,9 @@ var init_secrets = __esm(() => {
   init_project_id();
 });
 
+// ../shared/src/types/queue.ts
+var init_queue = () => {};
+
 // ../shared/src/constants/defaults.ts
 var DEFAULT_TIMEOUT_MS = 30000, DEFAULT_MEMORY_LIMIT_MB = 128;
 // ../shared/src/constants/billing.ts
@@ -7272,15 +7335,15 @@ var init_marketplace = __esm(() => {
     readme: exports_external.string().max(50000).optional()
   }).strict();
   installAdapterSchema = exports_external.object({
-    adapterId: exports_external.string().min(1, "Adapter ID is required"),
+    adapterId: exports_external.string().uuid("Adapter ID must be a valid UUID"),
     config: exports_external.record(exports_external.unknown()).optional()
   });
   searchAdaptersSchema = exports_external.object({
     query: exports_external.string().optional(),
     category: exports_external.string().optional(),
     status: exports_external.enum(["draft", "published", "deprecated"]).optional(),
-    limit: exports_external.number().int().positive().max(100).default(20),
-    offset: exports_external.number().int().nonnegative().default(0)
+    limit: exports_external.coerce.number().int().positive().max(100).default(20),
+    offset: exports_external.coerce.number().int().nonnegative().default(0)
   });
 });
 
@@ -7787,7 +7850,7 @@ function Queue(initial = []) {
   };
 }
 var queue_default;
-var init_queue = __esm(() => {
+var init_queue2 = __esm(() => {
   queue_default = Queue;
 });
 
@@ -8565,7 +8628,7 @@ var init_connection = __esm(() => {
   init_types2();
   init_errors2();
   init_result();
-  init_queue();
+  init_queue2();
   init_query();
   init_bytes();
   connection_default = Connection;
@@ -9245,7 +9308,7 @@ var init_src = __esm(() => {
   init_types2();
   init_connection();
   init_query();
-  init_queue();
+  init_queue2();
   init_errors2();
   init_large();
   Object.assign(Postgres, {
@@ -12789,7 +12852,8 @@ var init_deployments = __esm(() => {
     index("deployments_project_idx").on(table3.projectId),
     index("deployments_project_status_idx").on(table3.projectId, table3.status),
     index("deployments_environment_idx").on(table3.environmentId),
-    index("deployments_project_created_idx").on(table3.projectId, desc(table3.createdAt))
+    index("deployments_project_created_idx").on(table3.projectId, desc(table3.createdAt)),
+    uniqueIndex("deployments_one_active_per_project").on(table3.projectId).where(sql`${table3.status} = 'active'`)
   ]);
 });
 
@@ -12894,6 +12958,32 @@ var init_metrics = __esm(() => {
   ]);
 });
 
+// ../shared/src/db/schema/spans.ts
+var spans;
+var init_spans = __esm(() => {
+  init_pg_core();
+  init_execution_records();
+  init_projects();
+  spans = pgTable("spans", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    executionId: uuid("execution_id").notNull().references(() => executionRecords.id, { onDelete: "cascade" }),
+    projectId: uuid("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }),
+    traceId: text("trace_id").notNull(),
+    spanId: text("span_id").notNull(),
+    parentSpanId: text("parent_span_id"),
+    name: text("name").notNull(),
+    kind: text("kind").notNull(),
+    startedAt: timestamp("started_at", { withTimezone: true }).notNull(),
+    endedAt: timestamp("ended_at", { withTimezone: true }).notNull(),
+    attributes: jsonb("attributes").$type(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
+  }, (table3) => [
+    index("spans_execution_idx").on(table3.executionId),
+    index("spans_project_idx").on(table3.projectId),
+    index("spans_trace_idx").on(table3.traceId)
+  ]);
+});
+
 // ../shared/src/db/schema/artifacts.ts
 var artifacts;
 var init_artifacts = __esm(() => {
@@ -13091,6 +13181,7 @@ var init_credit_ledger = __esm(() => {
   }, (table3) => [
     index("credit_ledger_org_created_idx").on(table3.organizationId, table3.createdAt),
     uniqueIndex("credit_ledger_execution_debit_dedup").on(sql`((metadata->>'executionId'))`).where(sql`entry_type IN ('execution_debit', 'overage_debit') AND metadata ? 'executionId'`),
+    uniqueIndex("credit_ledger_execution_refund_dedup").on(sql`((metadata->>'executionId'))`).where(sql`entry_type = 'execution_refund' AND metadata ? 'executionId'`),
     uniqueIndex("credit_ledger_included_grant_dedup").on(table3.organizationId, sql`((metadata->>'billingCycle'))`, sql`((metadata->>'plan'))`).where(sql`entry_type = 'included_grant' AND metadata ? 'billingCycle' AND metadata ? 'plan'`)
   ]);
 });
@@ -13412,12 +13503,14 @@ var init_workflows = __esm(() => {
   ]);
   stepRuns = pgTable("step_runs", {
     id: uuid("id").defaultRandom().primaryKey(),
-    workflowRunId: uuid("workflow_run_id").notNull().references(() => workflowRuns.id),
+    workflowRunId: uuid("workflow_run_id").notNull().references(() => workflowRuns.id, { onDelete: "cascade" }),
     stepName: text("step_name").notNull(),
     status: text("status").notNull().default("pending"),
     input: jsonb("input"),
     output: jsonb("output"),
-    executionId: uuid("execution_id").references(() => executionRecords.id),
+    executionId: uuid("execution_id").references(() => executionRecords.id, {
+      onDelete: "set null"
+    }),
     attempt: integer("attempt").notNull().default(1),
     startedAt: timestamp("started_at", { withTimezone: true }),
     completedAt: timestamp("completed_at", { withTimezone: true }),
@@ -13430,7 +13523,7 @@ var init_workflows = __esm(() => {
   ]);
   approvalRequests = pgTable("approval_requests", {
     id: uuid("id").defaultRandom().primaryKey(),
-    stepRunId: uuid("step_run_id").notNull().references(() => stepRuns.id),
+    stepRunId: uuid("step_run_id").notNull().references(() => stepRuns.id, { onDelete: "cascade" }),
     approvers: jsonb("approvers").$type().notNull(),
     message: text("message"),
     status: text("status").notNull().default("pending"),
@@ -13732,6 +13825,27 @@ var init_admin_audit_log = __esm(() => {
   ]);
 });
 
+// ../shared/src/db/schema/custom-domains.ts
+var customDomains;
+var init_custom_domains = __esm(() => {
+  init_pg_core();
+  init_projects();
+  customDomains = pgTable("custom_domains", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    projectId: uuid("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }),
+    domain: text("domain").notNull(),
+    status: text("status").notNull(),
+    txtRecord: text("txt_record").notNull(),
+    verifiedAt: timestamp("verified_at", { withTimezone: true }),
+    tlsProvisionedAt: timestamp("tls_provisioned_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
+  }, (table3) => [
+    uniqueIndex("custom_domains_domain_idx").on(table3.domain),
+    index("custom_domains_project_idx").on(table3.projectId)
+  ]);
+});
+
 // ../shared/src/db/schema/index.ts
 var init_schema2 = __esm(() => {
   init_users();
@@ -13744,6 +13858,7 @@ var init_schema2 = __esm(() => {
   init_execution_records();
   init_log_entries();
   init_metrics();
+  init_spans();
   init_artifacts();
   init_secrets2();
   init_api_keys();
@@ -13768,6 +13883,7 @@ var init_schema2 = __esm(() => {
   init_auth();
   init_admin_sessions();
   init_admin_audit_log();
+  init_custom_domains();
 });
 
 // ../shared/src/db/index.ts
@@ -13800,6 +13916,7 @@ function parseHttpBody(body, _headers) {
 
 // ../shared/src/index.ts
 var init_src2 = __esm(() => {
+  init_queue();
   init_billing();
   init_limits();
   init_native_deps();
@@ -13813,16 +13930,16 @@ var init_src2 = __esm(() => {
 });
 
 // src/lib/manifest.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join5 } from "node:path";
 function readManifest(dir) {
   const path = join5(dir, "dura.json");
-  if (!existsSync4(path)) {
+  if (!existsSync5(path)) {
     throw new ManifestError(`No dura.json found in ${dir}`);
   }
   let raw;
   try {
-    raw = JSON.parse(readFileSync4(path, "utf-8"));
+    raw = JSON.parse(readFileSync5(path, "utf-8"));
   } catch {
     throw new ManifestError("dura.json is not valid JSON");
   }
@@ -13834,10 +13951,10 @@ function readManifest(dir) {
 }
 function readRawManifest(dir) {
   const path = join5(dir, "dura.json");
-  if (!existsSync4(path)) {
+  if (!existsSync5(path)) {
     throw new ManifestError(`No dura.json found in ${dir}`);
   }
-  return JSON.parse(readFileSync4(path, "utf-8"));
+  return JSON.parse(readFileSync5(path, "utf-8"));
 }
 function writeRawManifest(dir, data) {
   const path = join5(dir, "dura.json");
@@ -14019,11 +14136,67 @@ function generateDeploymentManifest(_projectDir, manifest) {
 }
 var init_manifest_generator = () => {};
 
+// src/lib/parity-check.ts
+import { builtinModules } from "node:module";
+import * as esbuild from "esbuild";
+function isNodeBuiltinSpecifier(specifier) {
+  if (specifier.startsWith("node:"))
+    return true;
+  return BARE_BUILTIN_SET.has(specifier);
+}
+async function analyzeNodeBuiltinImports(entryPath) {
+  const externalList = [
+    "node:*",
+    ...builtinModules,
+    ...builtinModules.map((m) => `node:${m}`)
+  ];
+  let result;
+  try {
+    result = await esbuild.build({
+      entryPoints: [entryPath],
+      bundle: true,
+      metafile: true,
+      write: false,
+      platform: "neutral",
+      format: "esm",
+      logLevel: "silent",
+      external: externalList
+    });
+  } catch {
+    return [];
+  }
+  const seen = new Set;
+  const hits = [];
+  for (const [importerPath, info] of Object.entries(result.metafile.inputs)) {
+    for (const imp of info.imports) {
+      if (!imp.external)
+        continue;
+      if (!isNodeBuiltinSpecifier(imp.path))
+        continue;
+      const key = `${imp.path}\x00${importerPath}`;
+      if (seen.has(key))
+        continue;
+      seen.add(key);
+      hits.push({ specifier: imp.path, importer: importerPath });
+    }
+  }
+  hits.sort((a, b2) => {
+    if (a.specifier !== b2.specifier)
+      return a.specifier < b2.specifier ? -1 : 1;
+    return a.importer < b2.importer ? -1 : a.importer > b2.importer ? 1 : 0;
+  });
+  return hits;
+}
+var BARE_BUILTIN_SET;
+var init_parity_check = __esm(() => {
+  BARE_BUILTIN_SET = new Set(builtinModules);
+});
+
 // src/lib/bundler.ts
 import { join as join6, resolve as resolve2 } from "node:path";
 import {
-  existsSync as existsSync5,
-  readFileSync as readFileSync5,
+  existsSync as existsSync6,
+  readFileSync as readFileSync6,
   writeFileSync as writeFileSync5,
   mkdirSync as mkdirSync3,
   readdirSync,
@@ -14031,7 +14204,7 @@ import {
 } from "node:fs";
 import { createGzip } from "node:zlib";
 import { Readable } from "node:stream";
-import * as esbuild from "esbuild";
+import * as esbuild2 from "esbuild";
 async function createBundle(projectDir, options) {
   const maxSize = options?.maxBundleSize ?? MAX_BUNDLE_SIZE_BYTES;
   let duraManifest;
@@ -14044,13 +14217,14 @@ async function createBundle(projectDir, options) {
     };
   }
   const buildDir = join6(projectDir, ".dura", "build");
-  if (existsSync5(buildDir)) {
+  if (existsSync6(buildDir)) {
     rmSync(buildDir, { recursive: true });
   }
   mkdirSync3(buildDir, { recursive: true });
+  const parityWarnings = [];
   for (const auto of duraManifest.automations) {
     const entryPath = resolve2(projectDir, auto.entrypoint);
-    if (!existsSync5(entryPath)) {
+    if (!existsSync6(entryPath)) {
       rmSync(buildDir, { recursive: true });
       return {
         success: false,
@@ -14059,8 +14233,8 @@ async function createBundle(projectDir, options) {
     }
     const outFile = join6(buildDir, `${auto.name}.js`);
     try {
-      const source = readFileSync5(entryPath, "utf-8");
-      const xformed = await esbuild.transform(source, {
+      const source = readFileSync6(entryPath, "utf-8");
+      const xformed = await esbuild2.transform(source, {
         loader: "ts",
         target: "es2022",
         sourcemap: false
@@ -14073,6 +14247,12 @@ async function createBundle(projectDir, options) {
         error: `Failed to bundle ${auto.name}: ${err instanceof Error ? err.message : String(err)}`
       };
     }
+    try {
+      const hits = await analyzeNodeBuiltinImports(entryPath);
+      if (hits.length > 0) {
+        parityWarnings.push({ automation: auto.name, hits });
+      }
+    } catch {}
   }
   const deployManifest = generateDeploymentManifest(projectDir, duraManifest);
   writeFileSync5(join6(buildDir, "manifest.json"), JSON.stringify(deployManifest, null, 2));
@@ -14089,7 +14269,8 @@ async function createBundle(projectDir, options) {
     success: true,
     archiveBuffer,
     manifest: deployManifest,
-    sizeBytes: archiveBuffer.length
+    sizeBytes: archiveBuffer.length,
+    parityWarnings
   };
 }
 async function createTarGz(dir) {
@@ -14123,7 +14304,7 @@ function collectFiles(dir, base) {
       const relativePath = fullPath.slice(base.length + 1);
       result.push({
         name: relativePath,
-        content: new Uint8Array(readFileSync5(fullPath))
+        content: new Uint8Array(readFileSync6(fullPath))
       });
     } else if (entry.isDirectory()) {
       result.push(...collectFiles(fullPath, base));
@@ -14181,6 +14362,7 @@ var init_bundler = __esm(() => {
   init_src2();
   init_manifest2();
   init_manifest_generator();
+  init_parity_check();
 });
 
 // src/commands/deploy.ts
@@ -14220,6 +14402,18 @@ function registerDeployCommand(program2) {
       return;
     }
     output.info(`Bundle created: ${bundle.sizeBytes} bytes`);
+    if (bundle.parityWarnings && bundle.parityWarnings.length > 0) {
+      for (const w of bundle.parityWarnings) {
+        const lines = [
+          `"${w.automation}" imports Node built-ins that are not available in the dura.run runtime:`,
+          ...w.hits.map((h) => `  ${h.specifier.padEnd(22)} (imported by ${h.importer})`),
+          `Your handler may fail when invoked in production.`,
+          `See https://dura.run/docs/runtime for the available runtime surface.`
+        ];
+        output.warn(lines.join(`
+`));
+      }
+    }
     output.info("Deploying...");
     try {
       const result = await client.deployBundle(projectId, bundle.archiveBuffer, bundle.manifest);
@@ -14239,7 +14433,8 @@ function registerDeployCommand(program2) {
         activatedAt: result.deployment.activatedAt,
         bundleSize: bundle.sizeBytes,
         automations: bundle.manifest.automations.length,
-        urls: result.urls ?? []
+        urls: result.urls ?? [],
+        parityWarnings: bundle.parityWarnings ?? []
       });
       if (result.urls && result.urls.length > 0) {
         output.info(`
@@ -14337,12 +14532,13 @@ __export(exports_logs, {
   parseFilters: () => parseFilters,
   parseDuration: () => parseDuration,
   formatLogEntry: () => formatLogEntry,
+  fetchWsTicket: () => fetchWsTicket,
   createFollowClient: () => createFollowClient,
   buildWsUrl: () => buildWsUrl
 });
-function buildWsUrl(apiUrl, projectId, filters, token = "") {
+function buildWsUrl(apiUrl, projectId, filters, ticket = "") {
   const wsBase = apiUrl.replace(/^http:\/\//, "ws://").replace(/^https:\/\//, "wss://");
-  const params = new URLSearchParams({ token, projectId });
+  const params = new URLSearchParams({ ticket, projectId });
   if (filters.level)
     params.set("level", filters.level);
   if (filters.executionId)
@@ -14351,6 +14547,10 @@ function buildWsUrl(apiUrl, projectId, filters, token = "") {
     params.set("automationName", filters.automationName);
   return `${wsBase}/api/v1/ws?${params.toString()}`;
 }
+async function fetchWsTicket(client) {
+  const res = await client.post("/api/v1/logs/ws-ticket");
+  return res.ticket;
+}
 function formatLogEntry(entry) {
   const fieldsStr = entry.fields && Object.keys(entry.fields).length > 0 ? " " + JSON.stringify(entry.fields) : "";
   return `${entry.timestamp} [${entry.level.toUpperCase()}] ${entry.message}${fieldsStr}`;
@@ -14452,7 +14652,14 @@ function registerLogsCommand(program2) {
       }
       if (executionId)
         filters.executionId = executionId;
-      const wsUrl = buildWsUrl(apiUrl, projectId, filters, token);
+      let ticket;
+      try {
+        ticket = await fetchWsTicket(client);
+      } catch (err) {
+        reportApiError(output, err, "WS_TICKET_FAILED");
+        return;
+      }
+      const wsUrl = buildWsUrl(apiUrl, projectId, filters, ticket);
       if (!output.isJson()) {
         output.info(`Connecting to live log stream for project ${projectId}…`);
       }
@@ -14733,9 +14940,20 @@ var init_schedule = __esm(() => {
 });
 
 // src/lib/dev-trust.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync4, writeFileSync as writeFileSync6 } from "node:fs";
+import { chmodSync as chmodSync2, existsSync as existsSync7, mkdirSync as mkdirSync4, writeFileSync as writeFileSync6 } from "node:fs";
 import { dirname, join as join7 } from "node:path";
+function chmodPosix2(path, mode) {
+  if (process.platform === "win32")
+    return;
+  chmodSync2(path, mode);
+}
 function hasStoredCredentials() {
+  const envToken = process.env["DURA_TOKEN"];
+  if (typeof envToken === "string" && envToken.length > 0)
+    return true;
+  const envApiKey = process.env["DURA_API_KEY"];
+  if (typeof envApiKey === "string" && envApiKey.length > 0)
+    return true;
   try {
     const cfg = readConfig();
     const apiKey = typeof cfg.apiKey === "string" ? cfg.apiKey : "";
@@ -14746,14 +14964,15 @@ function hasStoredCredentials() {
   }
 }
 function hasProjectTrustMarker(projectDir) {
-  return existsSync6(join7(projectDir, TRUST_MARKER_RELATIVE_PATH));
+  return existsSync7(join7(projectDir, TRUST_MARKER_RELATIVE_PATH));
 }
 function grantProjectTrust(projectDir) {
   const markerPath = join7(projectDir, TRUST_MARKER_RELATIVE_PATH);
   const dir = dirname(markerPath);
-  if (!existsSync6(dir)) {
-    mkdirSync4(dir, { recursive: true });
+  if (!existsSync7(dir)) {
+    mkdirSync4(dir, { recursive: true, mode: 448 });
   }
+  chmodPosix2(dir, 448);
   const note = [
     "# dura dev trust marker",
     "#",
@@ -14765,6 +14984,7 @@ function grantProjectTrust(projectDir) {
   ].join(`
 `);
   writeFileSync6(markerPath, note, { mode: 384 });
+  chmodPosix2(markerPath, 384);
 }
 function isEnvTruthy(val) {
   if (!val)
@@ -14816,9 +15036,10 @@ function renderTrustRefusal() {
   return [
     `${bold}${yellow}dura dev refuses to start.${reset2}`,
     "",
-    "Your local machine has stored dura credentials, and `dura dev` currently",
-    "loads your handler code with full filesystem access. Until we ship an",
-    "isolated-vm sandbox for local dev, you must explicitly accept this risk.",
+    "Your local machine has stored dura credentials, and `dura dev` loads",
+    "your handler code with full filesystem access. Production isolation",
+    "lives in @dura/executor; dura dev intentionally does not sandbox (see",
+    "#147). You must explicitly accept this risk to start the dev server.",
     "",
     "To proceed, pick ONE of:",
     "",
@@ -15366,7 +15587,7 @@ __export(exports_file_watcher, {
   resolveAffectedAutomation: () => resolveAffectedAutomation,
   createFileWatcher: () => createFileWatcher
 });
-import { watch, existsSync as existsSync7 } from "node:fs";
+import { watch, existsSync as existsSync8 } from "node:fs";
 import { join as join8 } from "node:path";
 function resolveAffectedAutomation(manifest, changedPath) {
   const normalized = changedPath.replace(/\\/g, "/");
@@ -15403,7 +15624,7 @@ function createFileWatcher(options) {
       watching = true;
       for (const dir of watchDirs) {
         const fullDir = join8(projectDir, dir);
-        if (!existsSync7(fullDir))
+        if (!existsSync8(fullDir))
           continue;
         try {
           const fsWatcher = watch(fullDir, { recursive: true }, (_eventType, filename) => {
@@ -15454,7 +15675,10 @@ function parseEnvFile(content) {
     }
     const key = line3.slice(0, eqIndex).trim();
     let value = line3.slice(eqIndex + 1).trim();
-    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1).replace(/\\(.)/g, (_, c) => c === "n" ? `
+` : c);
+    } else if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
       value = value.slice(1, -1);
     }
     if (key.length > 0) {
@@ -15515,12 +15739,12 @@ function registerDevCommand(program2) {
       }
       throw err;
     }
-    const { existsSync: existsSync8, readFileSync: readFileSync6 } = await import("node:fs");
+    const { existsSync: existsSync9, readFileSync: readFileSync7 } = await import("node:fs");
     const { join: join9 } = await import("node:path");
     const envPath = join9(projectDir, ".env.local");
     let secrets2 = {};
-    if (existsSync8(envPath)) {
-      const content = readFileSync6(envPath, "utf-8");
+    if (existsSync9(envPath)) {
+      const content = readFileSync7(envPath, "utf-8");
       secrets2 = parseEnvFile(content);
       output.info(`Loaded ${Object.keys(secrets2).length} secret(s) from .env.local`);
     }
@@ -15871,9 +16095,9 @@ var init_comparator = __esm(() => {
 
 // src/snapshot/file-manager.ts
 import {
-  existsSync as existsSync8,
+  existsSync as existsSync9,
   mkdirSync as mkdirSync5,
-  readFileSync as readFileSync6,
+  readFileSync as readFileSync7,
   writeFileSync as writeFileSync7,
   readdirSync as readdirSync2,
   unlinkSync
@@ -15895,16 +16119,16 @@ class SnapshotFileManager {
     return join9(this.snapshotsDir, automationNameToFileName(automationName));
   }
   ensureDir() {
-    if (!existsSync8(this.snapshotsDir)) {
+    if (!existsSync9(this.snapshotsDir)) {
       mkdirSync5(this.snapshotsDir, { recursive: true });
     }
   }
   read(automationName) {
     const path = this.filePath(automationName);
-    if (!existsSync8(path))
+    if (!existsSync9(path))
       return null;
     try {
-      const raw = readFileSync6(path, "utf-8");
+      const raw = readFileSync7(path, "utf-8");
       return JSON.parse(raw);
     } catch {
       return null;
@@ -15934,14 +16158,14 @@ class SnapshotFileManager {
     });
   }
   listAutomationNames() {
-    if (!existsSync8(this.snapshotsDir))
+    if (!existsSync9(this.snapshotsDir))
       return [];
     const files = readdirSync2(this.snapshotsDir).filter((f) => f.endsWith(".snap.json"));
     const names = [];
     for (const file of files) {
       const path = join9(this.snapshotsDir, file);
       try {
-        const raw = readFileSync6(path, "utf-8");
+        const raw = readFileSync7(path, "utf-8");
         const parsed = JSON.parse(raw);
         if (parsed.automationName) {
           names.push(parsed.automationName);
@@ -15952,7 +16176,7 @@ class SnapshotFileManager {
   }
   delete(automationName) {
     const path = this.filePath(automationName);
-    if (existsSync8(path)) {
+    if (existsSync9(path)) {
       unlinkSync(path);
     }
   }
@@ -15961,7 +16185,7 @@ var SNAPSHOTS_DIR = "__snapshots__";
 var init_file_manager = () => {};
 
 // src/snapshot/config-reader.ts
-import { existsSync as existsSync9, readFileSync as readFileSync7 } from "node:fs";
+import { existsSync as existsSync10, readFileSync as readFileSync8 } from "node:fs";
 import { join as join10 } from "node:path";
 function readSnapshotConfig(projectDir) {
   const durajsonPath = join10(projectDir, "dura.json");
@@ -15969,17 +16193,17 @@ function readSnapshotConfig(projectDir) {
   let fromDuraJson = {};
   let fromTestJson = {};
   let mocks;
-  if (existsSync9(durajsonPath)) {
+  if (existsSync10(durajsonPath)) {
     try {
-      const raw = JSON.parse(readFileSync7(durajsonPath, "utf-8"));
+      const raw = JSON.parse(readFileSync8(durajsonPath, "utf-8"));
       if (raw["snapshots"] && typeof raw["snapshots"] === "object" && !Array.isArray(raw["snapshots"])) {
         fromDuraJson = raw["snapshots"];
       }
     } catch {}
   }
-  if (existsSync9(testjsonPath)) {
+  if (existsSync10(testjsonPath)) {
     try {
-      const raw = JSON.parse(readFileSync7(testjsonPath, "utf-8"));
+      const raw = JSON.parse(readFileSync8(testjsonPath, "utf-8"));
       if (raw["snapshots"] && typeof raw["snapshots"] === "object" && !Array.isArray(raw["snapshots"])) {
         fromTestJson = raw["snapshots"];
       }
@@ -16729,7 +16953,7 @@ __export(exports_events, {
   resolvePayload: () => resolvePayload,
   registerEventsCommand: () => registerEventsCommand
 });
-import { readFileSync as readFileSync8 } from "node:fs";
+import { readFileSync as readFileSync9 } from "node:fs";
 function resolvePayload(opts) {
   if (opts.payload !== undefined && opts.payloadFile !== undefined) {
     throw new Error("Use either --payload or --payload-file, not both");
@@ -16737,7 +16961,7 @@ function resolvePayload(opts) {
   if (opts.payload === undefined && opts.payloadFile === undefined) {
     throw new Error("--payload or --payload-file is required");
   }
-  const raw = opts.payload !== undefined ? opts.payload : readFileSync8(opts.payloadFile, "utf-8");
+  const raw = opts.payload !== undefined ? opts.payload : readFileSync9(opts.payloadFile, "utf-8");
   try {
     return JSON.parse(raw);
   } catch (err) {
@@ -17023,8 +17247,8 @@ __export(exports_export, {
   collectExportFiles: () => collectExportFiles
 });
 import {
-  existsSync as existsSync10,
-  readFileSync as readFileSync9,
+  existsSync as existsSync11,
+  readFileSync as readFileSync10,
   readdirSync as readdirSync3,
   statSync,
   writeFileSync as writeFileSync8
@@ -17044,7 +17268,7 @@ function collectExportFiles(baseDir, currentDir) {
       }
     } else if (stat.isFile()) {
       if (!EXCLUDED_FILES.has(item)) {
-        const content = readFileSync9(fullPath, "utf-8");
+        const content = readFileSync10(fullPath, "utf-8");
         entries.push({ relativePath: relPath, content });
       }
     }
@@ -17069,13 +17293,13 @@ function registerExportCommand(program2) {
     const output = getOutput(cmd);
     const projectDir = resolve4(opts.dir ?? ".");
     const manifestPath = join11(projectDir, "dura.json");
-    if (!existsSync10(manifestPath)) {
+    if (!existsSync11(manifestPath)) {
       output.error("EXPORT_NO_MANIFEST", "No dura.json found in project directory", "Run this command from a dura project directory or use --dir");
       return;
     }
     let projectName;
     try {
-      const manifestContent = readFileSync9(manifestPath, "utf-8");
+      const manifestContent = readFileSync10(manifestPath, "utf-8");
       const manifest = JSON.parse(manifestContent);
       projectName = manifest.name ?? "unnamed-project";
     } catch {
@@ -17942,17 +18166,18 @@ var init_diagnose = __esm(() => {
 // src/commands/create.ts
 var exports_create = {};
 __export(exports_create, {
+  writeGeneratedFiles: () => writeGeneratedFiles,
   registerCreateCommand: () => registerCreateCommand,
   registerAddCommand: () => registerAddCommand
 });
 import {
-  existsSync as existsSync11,
+  existsSync as existsSync12,
   mkdirSync as mkdirSync6,
   writeFileSync as writeFileSync9,
-  readFileSync as readFileSync10,
+  readFileSync as readFileSync11,
   readdirSync as readdirSync4
 } from "node:fs";
-import { join as join12, resolve as resolve5, dirname as dirname2 } from "node:path";
+import { join as join12, resolve as resolve5, dirname as dirname2, isAbsolute as isAbsolute2, sep } from "node:path";
 function slugifyDescription(description) {
   return description.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 30).replace(/-+$/, "");
 }
@@ -17960,13 +18185,13 @@ function getExistingRoutes(projectDir) {
   const routesDir = join12(projectDir, "routes");
   const jobsDir = join12(projectDir, "jobs");
   const routes = [];
-  if (existsSync11(routesDir)) {
+  if (existsSync12(routesDir)) {
     try {
       const files = readdirSync4(routesDir);
       routes.push(...files.map((f) => `routes/${f}`));
     } catch {}
   }
-  if (existsSync11(jobsDir)) {
+  if (existsSync12(jobsDir)) {
     try {
       const files = readdirSync4(jobsDir);
       routes.push(...files.map((f) => `jobs/${f}`));
@@ -17975,13 +18200,26 @@ function getExistingRoutes(projectDir) {
   return routes;
 }
 function writeGeneratedFiles(projectDir, files) {
-  for (const file of files) {
-    const filePath = join12(projectDir, file.path);
-    const dir = dirname2(filePath);
-    if (!existsSync11(dir)) {
+  const root = resolve5(projectDir);
+  const resolved = files.map((file) => {
+    if (isAbsolute2(file.path)) {
+      throw new Error(`Refusing to write generated file with absolute path "${file.path}" — paths must be relative to the project directory.`);
+    }
+    if (file.path.split(/[\\/]/).includes("..")) {
+      throw new Error(`Refusing to write generated file "${file.path}" — path traversal ("..") is not allowed.`);
+    }
+    const abs = resolve5(root, file.path);
+    if (abs !== root && !abs.startsWith(root + sep)) {
+      throw new Error(`Refusing to write generated file "${file.path}" — resolved path "${abs}" is outside the project directory.`);
+    }
+    return { abs, content: file.content };
+  });
+  for (const { abs, content } of resolved) {
+    const dir = dirname2(abs);
+    if (!existsSync12(dir)) {
       mkdirSync6(dir, { recursive: true });
     }
-    writeFileSync9(filePath, file.content, "utf-8");
+    writeFileSync9(abs, content, "utf-8");
   }
 }
 async function confirm(question) {
@@ -18011,7 +18249,7 @@ function registerCreateCommand(program2) {
     const projectName = opts.name || slugifyDescription(description);
     const parentDir = opts.dir ? resolve5(opts.dir) : process.cwd();
     const projectDir = join12(parentDir, projectName);
-    if (existsSync11(projectDir)) {
+    if (existsSync12(projectDir)) {
       output.error("DIRECTORY_EXISTS", `Directory "${projectName}" already exists`, "Choose a different name with --name or remove the existing directory");
       return;
     }
@@ -18038,7 +18276,12 @@ function registerCreateCommand(program2) {
     }
     mkdirSync6(join12(projectDir, "routes"), { recursive: true });
     mkdirSync6(join12(projectDir, "jobs"), { recursive: true });
-    writeGeneratedFiles(projectDir, generateResult.files);
+    try {
+      writeGeneratedFiles(projectDir, generateResult.files);
+    } catch (err) {
+      output.error("UNSAFE_GENERATED_PATH", err instanceof Error ? err.message : "Unsafe generated file path", "The AI response contained a file path outside the project directory and was rejected.");
+      return;
+    }
     output.info(`Files written to ${projectDir}`);
     if (opts.deploy !== false) {
       output.info("Deploying...");
@@ -18069,14 +18312,14 @@ function registerAddCommand(program2) {
     }
     const projectDir = opts.dir ? resolve5(opts.dir) : process.cwd();
     const duraJsonPath = join12(projectDir, "dura.json");
-    if (!existsSync11(duraJsonPath)) {
+    if (!existsSync12(duraJsonPath)) {
       output.error("NOT_A_DURA_PROJECT", "No dura.json found in the current directory", "Run this command from a dura project directory or use --dir");
       return;
     }
     const existingRoutes = getExistingRoutes(projectDir);
     let projectConfig = {};
     try {
-      projectConfig = JSON.parse(readFileSync10(duraJsonPath, "utf-8"));
+      projectConfig = JSON.parse(readFileSync11(duraJsonPath, "utf-8"));
     } catch {}
     const apiUrl = getApiUrl();
     const client = new ApiClient(apiUrl, token);
@@ -18105,7 +18348,12 @@ function registerAddCommand(program2) {
         return;
       }
     }
-    writeGeneratedFiles(projectDir, generateResult.files);
+    try {
+      writeGeneratedFiles(projectDir, generateResult.files);
+    } catch (err) {
+      output.error("UNSAFE_GENERATED_PATH", err instanceof Error ? err.message : "Unsafe generated file path", "The AI response contained a file path outside the project directory and was rejected.");
+      return;
+    }
     output.info(`Files written to ${projectDir}`);
     if (opts.deploy !== false) {
       output.info("Run `dura deploy --project " + projectId + " --dir " + projectDir + "` to deploy");
@@ -19170,7 +19418,7 @@ var init_heal = __esm(() => {
 });
 
 // src/lib/skill-installer.ts
-import { existsSync as existsSync12, mkdirSync as mkdirSync7, readFileSync as readFileSync11, writeFileSync as writeFileSync10 } from "node:fs";
+import { existsSync as existsSync13, mkdirSync as mkdirSync7, readFileSync as readFileSync12, writeFileSync as writeFileSync10 } from "node:fs";
 import { join as join13, dirname as dirname3 } from "node:path";
 import { homedir as homedir2 } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -19186,14 +19434,14 @@ function getLocalSkillsDir(projectDir) {
 }
 function installSkills(targetDir) {
   const sourceDir = getSkillSourceDir();
-  if (!existsSync12(targetDir)) {
+  if (!existsSync13(targetDir)) {
     mkdirSync7(targetDir, { recursive: true });
   }
   const installedFiles = [];
   for (const file of SKILL_FILES) {
     const sourcePath = join13(sourceDir, file);
     const targetPath = join13(targetDir, file);
-    const content = readFileSync11(sourcePath, "utf-8");
+    const content = readFileSync12(sourcePath, "utf-8");
     writeFileSync10(targetPath, content, "utf-8");
     installedFiles.push(targetPath);
   }
@@ -19218,7 +19466,7 @@ var exports_init = {};
 __export(exports_init, {
   registerInitCommand: () => registerInitCommand
 });
-import { existsSync as existsSync13, mkdirSync as mkdirSync8, writeFileSync as writeFileSync11 } from "node:fs";
+import { existsSync as existsSync14, mkdirSync as mkdirSync8, writeFileSync as writeFileSync11 } from "node:fs";
 import { join as join14, resolve as resolve6, basename } from "node:path";
 function registerInitCommand(program2) {
   program2.command("init").description("Initialize a dura project in the current directory and install AI agent skills").option("--dir <path>", "Project directory (defaults to current dir)").option("--name <name>", "Project name (defaults to directory name)").option("--global", "Install AI agent skills globally (~/.claude/skills/dura/)").option("--local", "Install AI agent skills locally (.claude/skills/dura/)").option("--skip-skills", "Skip AI agent skill installation").action(async (opts, cmd) => {
@@ -19232,24 +19480,24 @@ function registerInitCommand(program2) {
     mkdirSync8(join14(projectDir, "routes"), { recursive: true });
     mkdirSync8(join14(projectDir, "jobs"), { recursive: true });
     const manifestPath = join14(projectDir, "dura.json");
-    const alreadyInitialized = existsSync13(manifestPath);
+    const alreadyInitialized = existsSync14(manifestPath);
     if (!alreadyInitialized) {
       writeFileSync11(manifestPath, duraJsonTemplate(projectName));
     } else {
       output.info(`dura.json already exists in ${projectDir} — leaving it in place.`);
     }
     const helloPath = join14(projectDir, "routes", "hello.ts");
-    if (existsSync13(helloPath)) {
+    if (existsSync14(helloPath)) {
       output.warn("routes/hello.ts already exists — skipping");
     } else {
       writeFileSync11(helloPath, HELLO_TEMPLATE);
     }
     const gitignorePath = join14(projectDir, ".gitignore");
-    if (!existsSync13(gitignorePath)) {
+    if (!existsSync14(gitignorePath)) {
       writeFileSync11(gitignorePath, GITIGNORE_CONTENT2);
     }
     const pkgPath = join14(projectDir, "package.json");
-    if (!existsSync13(pkgPath)) {
+    if (!existsSync14(pkgPath)) {
       writeFileSync11(pkgPath, packageJsonTemplate(projectName));
     }
     if (alreadyInitialized) {
@@ -19469,29 +19717,36 @@ async function registerAllCommands(program2) {
   const { registerHealCommand: registerHealCommand2 } = await Promise.resolve().then(() => (init_heal(), exports_heal));
   const { registerInitCommand: registerInitCommand2 } = await Promise.resolve().then(() => (init_init(), exports_init));
   const { registerProjectsCommand: registerProjectsCommand2 } = await Promise.resolve().then(() => (init_projects2(), exports_projects));
+  program2.commandsGroup("Auth & setup:");
   registerLoginCommand2(program2);
   registerLogoutCommand2(program2);
   registerConfigCommand2(program2);
+  program2.commandsGroup("Projects:");
   registerNewCommand2(program2);
   registerInitCommand2(program2);
   registerCreateCommand2(program2);
   registerAddCommand2(program2);
   registerProjectsCommand2(program2);
+  program2.commandsGroup("Templates:");
   registerTemplateCommand2(program2);
+  program2.commandsGroup("Config:");
   registerSecretsCommand2(program2);
   registerDomainsCommand2(program2);
   registerEndpointKeysCommand2(program2);
   registerEnvCommand2(program2);
+  program2.commandsGroup("Deploy lifecycle:");
   registerDeployCommand2(program2);
   registerRollbackCommand2(program2);
   registerDeploymentsCommand2(program2);
   registerPromoteCommand2(program2);
   registerCanaryCommand2(program2);
+  program2.commandsGroup("Run & develop:");
   registerDevCommand2(program2);
   registerTestCommand2(program2);
   registerRunCommand2(program2);
   registerScheduleCommand2(program2);
   registerEventsCommand2(program2);
+  program2.commandsGroup("Observe & debug:");
   registerStatusCommand2(program2);
   registerLogsCommand2(program2);
   registerUsageCommand2(program2);
@@ -19499,6 +19754,7 @@ async function registerAllCommands(program2) {
   registerReplayCommand2(program2);
   registerReplaysCommand2(program2);
   registerDiagnoseCommand2(program2);
+  program2.commandsGroup("Workflows & ops:");
   registerWorkflowsCommand2(program2);
   registerWorkflowCommand2(program2);
   registerApprovalsCommand2(program2);
@@ -19506,14 +19762,16 @@ async function registerAllCommands(program2) {
   registerRejectCommand2(program2);
   registerHealCommand2(program2);
   registerReportsCommand2(program2);
+  program2.commandsGroup("Integrations & storage:");
   registerWebhookCommand2(program2);
   registerMarketplaceCommand2(program2);
   registerKvCommand2(program2);
+  program2.commandsGroup("Export & introspection:");
   registerExportCommand2(program2);
   registerOpenApiCommand2(program2);
   return program2;
 }
-var CLI_VERSION = "0.3.2";
+var CLI_VERSION = "0.4.0";
 var init_src3 = __esm(() => {
   init_esm();
   if (import.meta.url === `file://${realpathSync(process.argv[1] ?? "").replace(/\\/g, "/")}`) {
@@ -19530,4 +19788,4 @@ export {
   CLI_VERSION
 };
 
-//# debugId=BE2D824A7368E16F64756E2164756E21
+//# debugId=BACD50D24CC529CE64756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dura-run/cli",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "CLI for the dura.run managed automation platform",
   "license": "Apache-2.0",
   "type": "module",

package/skills/dura-develop.md

@@ -2,6 +2,36 @@
 
 > This skill teaches an AI agent how to scaffold projects, write automation handlers, use SDK globals, and run locally with `dura dev`.
 
+## Runtime constraints
+
+Handlers run in a V8 isolate on dura.run. **No Node built-ins, no filesystem, no child processes, no native addons.** If you reach for `node:fs`, `Buffer`, `child_process`, or `require('some-native-lib')`, the deploy will warn and the handler will fail at runtime.
+
+**What IS available:**
+
+- Standard JavaScript globals (`Date`, `Math`, `JSON`, `Promise`, `Uint8Array`, etc.)
+- `crypto.randomUUID()` and `crypto.getRandomValues(typedArray)` (WebCrypto-spec random)
+- `crypto.subtle.*` — full WebCrypto: `digest`, `sign`/`verify`, `encrypt`/`decrypt`, `generateKey`, `importKey`/`exportKey`, `deriveKey`/`deriveBits`, `wrapKey`/`unwrapKey`
+- `TextEncoder` and `TextDecoder` (UTF-8 only)
+- The fetch API (via `dura.fetch`)
+- The `dura.*` SDK surface: `fetch`, `log`, `env`, `kv`, `trigger`, `triggerAndWait`
+
+**Note on `crypto.subtle`:** it is bridged to the host runtime, so each call blocks the isolate while it runs. `await`ing a few signs/hashes per request is fine, but `Promise.all([...subtle calls])` executes serially, not concurrently — don't rely on parallelism for throughput, and avoid bulk hashing in tight loops.
+
+**Use these replacements for common Node-isms:**
+
+| Don't use             | Use instead                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| `node:fs`             | `dura.kv` or the artifact APIs                                                             |
+| `node:crypto` for IDs | `crypto.randomUUID()`                                                                      |
+| `node:crypto` for random bytes | `crypto.getRandomValues(new Uint8Array(n))`                                       |
+| `node:crypto` for hashing/signing | `crypto.subtle.digest` / `crypto.subtle.sign` / `crypto.subtle.verify` (WebCrypto)         |
+| `Buffer`              | `Uint8Array` with `TextEncoder` / `TextDecoder`                                            |
+| `node:child_process`  | Not supported — there is no process boundary to use                                        |
+| `node:http` / `https` | `dura.fetch`                                                                               |
+| `process.env.X`       | `dura.env.get("X")`                                                                        |
+
+If `dura deploy` warns about Node built-ins in your bundle, swap to the equivalent above before shipping.
+
 ## Scaffolding a New Project
 
 ### `dura new <name>` — Create a New Project