@declaw/sdk 1.2.3 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to the Declaw TypeScript / JavaScript SDK are documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0]
+
+_2026-07 train: credential vault client + injection domain scoping._
+
+### Added
+
+- Credential vault client — the `Vault` API for managing secrets **by name**:
+  `Vault.createSecret()`, `listSecrets()`, `rotateSecret()`, `deleteSecret()`,
+  `updateScopes()`, and `listPresets()`. Secret values are write-only (never
+  returned after create). Attach secrets to a sandbox with
+  `vaultRefs: { ENV_VAR: "secret-name" }`; the value is injected at the egress
+  proxy and never enters the sandbox (#386, #399, #408, #456).
+- Opt-in domain scoping for full injection defense via the `domains` option.
+
 ## [1.2.3]
 
 _Restore the conservative default connection ceiling._

package/dist/index.cjs

@@ -68,6 +68,7 @@ __export(index_exports, {
   TemplateError: () => TemplateError,
   TimeoutError: () => TimeoutError,
   TransformDirection: () => TransformDirection,
+  Vault: () => Vault,
   VolumeFiles: () => VolumeFiles,
   VolumeLocks: () => VolumeLocks,
   Volumes: () => Volumes,
@@ -119,6 +120,9 @@ __export(index_exports, {
   parseSnapshotInfo: () => parseSnapshotInfo,
   parseTemplateBuildStatus: () => parseTemplateBuildStatus,
   parseToxicityConfig: () => parseToxicityConfig,
+  parseVaultPreset: () => parseVaultPreset,
+  parseVaultScope: () => parseVaultScope,
+  parseVaultSecret: () => parseVaultSecret,
   parseVolumeInfo: () => parseVolumeInfo,
   parseWriteInfo: () => parseWriteInfo,
   requiresTlsInterception: () => requiresTlsInterception,
@@ -126,6 +130,7 @@ __export(index_exports, {
   securityPolicyToJSON: () => securityPolicyToJSON,
   toxicityConfigToJSON: () => toxicityConfigToJSON,
   validateNetworkEntry: () => validateNetworkEntry,
+  vaultScopeToJSON: () => vaultScopeToJSON,
   volumeAttachmentToJSON: () => volumeAttachmentToJSON
 });
 module.exports = __toCommonJS(index_exports);
@@ -641,7 +646,7 @@ function createInjectionDefenseConfig(opts) {
     enabled: opts?.enabled ?? false,
     sensitivity: opts?.sensitivity ?? "medium" /* Medium */,
     action: opts?.action ?? "log_only" /* LogOnly */,
-    threshold: opts?.threshold ?? 0.8,
+    threshold: opts?.threshold ?? 0.95,
     domains: opts?.domains,
     judge: opts?.judge,
     injectionMode: opts?.injectionMode
@@ -668,7 +673,7 @@ function parseInjectionDefenseConfig(data) {
     enabled: data.enabled ?? false,
     sensitivity: data.sensitivity ?? "medium" /* Medium */,
     action: data.action ?? "log_only" /* LogOnly */,
-    threshold: data.threshold ?? 0.8,
+    threshold: data.threshold ?? 0.95,
     domains: data.domains,
     judge: data.judge ? { enabled: data.judge.enabled ?? false, always: data.judge.always, policy: data.judge.policy } : void 0,
     injectionMode: data.injection_mode ?? data.injectionMode
@@ -1046,14 +1051,14 @@ function fullInjectionDefensePolicy(opts) {
     injectionDefense: createInjectionDefenseConfig({
       enabled: true,
       action: opts?.action ?? "block",
-      threshold: opts?.threshold ?? 0.8,
+      threshold: opts?.threshold ?? 0.95,
       domains: opts?.domains,
       injectionMode: opts?.mode ?? "balanced",
       judge: { enabled: true, always: opts?.alwaysJudge ?? false, policy: opts?.agentPolicy ?? "" }
     }),
     customPolicy: createCustomPolicyConfig({
       enabled: true,
-      policyRef: "prompt-injection@v2",
+      policyRef: "prompt-injection@v3",
       defaultDeny: false
     })
   });
@@ -1094,7 +1099,7 @@ function securityPolicyToJSON(policy) {
     action: injDefConfig.action,
     threshold: injDefConfig.threshold
   };
-  if (injDefConfig.domains !== void 0) {
+  if (injDefConfig.domains !== void 0 && injDefConfig.domains.length > 0) {
     injDef.domains = injDefConfig.domains;
   }
   if (injDefConfig.injectionMode !== void 0) {
@@ -2206,6 +2211,311 @@ function volumeAttachmentToJSON(att) {
   return out;
 }
 
+// src/vault/models.ts
+function parseVaultScope(data) {
+  const scope = {
+    domainRegex: String(data.domain_regex ?? "")
+  };
+  if (data.injection_type !== void 0 && data.injection_type !== null) {
+    scope.injectionType = String(data.injection_type);
+  }
+  if (data.header_name !== void 0 && data.header_name !== null) {
+    scope.headerName = String(data.header_name);
+  }
+  if (data.value_prefix !== void 0 && data.value_prefix !== null) {
+    scope.valuePrefix = String(data.value_prefix);
+  }
+  if (data.basic_username !== void 0 && data.basic_username !== null) {
+    scope.basicUsername = String(data.basic_username);
+  }
+  if (data.extra_headers !== void 0 && data.extra_headers !== null) {
+    scope.extraHeaders = data.extra_headers;
+  }
+  if (data.query_params !== void 0 && data.query_params !== null) {
+    scope.queryParams = data.query_params;
+  }
+  return scope;
+}
+function parseVaultSecret(data) {
+  const secret = {
+    secretId: String(data.secret_id ?? ""),
+    name: String(data.name ?? ""),
+    createdAt: String(data.created_at ?? ""),
+    updatedAt: String(data.updated_at ?? "")
+  };
+  const rawScopes = data.scopes;
+  if (rawScopes && rawScopes.length > 0) {
+    secret.scopes = rawScopes.map(parseVaultScope);
+  }
+  if (data.rotated_at !== void 0 && data.rotated_at !== null) {
+    secret.rotatedAt = String(data.rotated_at);
+  }
+  if (data.rotation_interval_days !== void 0 && data.rotation_interval_days !== null) {
+    secret.rotationIntervalDays = Number(data.rotation_interval_days);
+  }
+  if (data.rotation_due !== void 0 && data.rotation_due !== null) {
+    secret.rotationDue = Boolean(data.rotation_due);
+  }
+  return secret;
+}
+function parseVaultPreset(data) {
+  const rawScopes = data.scopes ?? [];
+  const preset = {
+    key: String(data.key ?? ""),
+    name: String(data.name ?? ""),
+    category: String(data.category ?? ""),
+    keyHint: String(data.key_hint ?? ""),
+    scopes: rawScopes.map(parseVaultScope)
+  };
+  if (data.docs_url !== void 0 && data.docs_url !== null) {
+    preset.docsUrl = String(data.docs_url);
+  }
+  return preset;
+}
+function vaultScopeToJSON(scope) {
+  const out = {
+    domain_regex: scope.domainRegex
+  };
+  if (scope.injectionType !== void 0) {
+    out.injection_type = scope.injectionType;
+  }
+  if (scope.headerName !== void 0) {
+    out.header_name = scope.headerName;
+  }
+  if (scope.valuePrefix !== void 0) {
+    out.value_prefix = scope.valuePrefix;
+  }
+  if (scope.basicUsername !== void 0) {
+    out.basic_username = scope.basicUsername;
+  }
+  if (scope.extraHeaders !== void 0) {
+    out.extra_headers = scope.extraHeaders;
+  }
+  if (scope.queryParams !== void 0) {
+    out.query_params = scope.queryParams;
+  }
+  return out;
+}
+
+// src/vault/vault.ts
+var DEFAULT_TEAM_NAME = "default";
+var DEFAULT_ENV_NAME = "prod";
+var defaultTeamCache = /* @__PURE__ */ new Map();
+function cacheKey(config) {
+  return `${config.apiUrl}\0${config.apiKey}`;
+}
+async function resolveDefaultTeamId(config, create, timeout) {
+  const key = cacheKey(config);
+  const cached = defaultTeamCache.get(key);
+  if (cached !== void 0) return cached;
+  const client = getSharedClient(config);
+  const resp = await client.get("/teams", { timeout });
+  const rows = resp.teams ?? [];
+  let best = null;
+  for (const t of rows) {
+    if (t.name === DEFAULT_TEAM_NAME) {
+      if (best === null || t.created_at < best.created_at) {
+        best = t;
+      }
+    }
+  }
+  if (best !== null) {
+    defaultTeamCache.set(key, best.team_id);
+    return best.team_id;
+  }
+  if (!create) return null;
+  const created = await client.post("/teams", {
+    json: { name: DEFAULT_TEAM_NAME },
+    timeout
+  });
+  defaultTeamCache.set(key, created.team_id);
+  return created.team_id;
+}
+async function ensureDefaultEnv(config, teamId, timeout) {
+  const client = getSharedClient(config);
+  const resp = await client.get(
+    `/teams/${encodeURIComponent(teamId)}/environments`,
+    { timeout }
+  );
+  const rows = resp.environments ?? [];
+  if (rows.some((e) => e.name === DEFAULT_ENV_NAME)) return;
+  try {
+    await client.post(`/teams/${encodeURIComponent(teamId)}/environments`, {
+      json: { name: DEFAULT_ENV_NAME },
+      timeout
+    });
+  } catch {
+    const resp2 = await client.get(
+      `/teams/${encodeURIComponent(teamId)}/environments`,
+      { timeout }
+    );
+    const rows2 = resp2.environments ?? [];
+    if (rows2.some((e) => e.name === DEFAULT_ENV_NAME)) return;
+    throw new Error(`Failed to ensure default environment "${DEFAULT_ENV_NAME}" on team ${teamId}`);
+  }
+}
+async function expandVaultRefs(config, refs, timeout) {
+  if (Object.keys(refs).length === 0) return refs;
+  const needsTeam = Object.values(refs).some((v) => !v.startsWith("vault://"));
+  if (!needsTeam) return refs;
+  const teamId = await resolveDefaultTeamId(config, false, timeout);
+  if (teamId === null) {
+    throw new Error("vault_refs given but no vault secrets exist for this account");
+  }
+  const out = {};
+  for (const [envVar, ref] of Object.entries(refs)) {
+    out[envVar] = ref.startsWith("vault://") ? ref : `vault://${teamId}/${DEFAULT_ENV_NAME}/${ref}`;
+  }
+  return out;
+}
+function buildConfig(opts) {
+  return new ConnectionConfig({
+    apiKey: opts?.apiKey,
+    domain: opts?.domain,
+    apiUrl: opts?.apiUrl,
+    requestTimeout: opts?.requestTimeout
+  });
+}
+var Vault = class _Vault {
+  // -------------------------------------------------------------------------
+  // Secrets
+  // -------------------------------------------------------------------------
+  /**
+   * Store a secret's value (server-side, in OpenBao) plus its injection
+   * scopes, under the auto-provisioned default team + "prod" environment.
+   * Returns metadata only — the value is never echoed.
+   *
+   * POST /teams/{teamId}/vault/secrets
+   */
+  static async createSecret(input, opts) {
+    const config = buildConfig(opts);
+    const teamId = await resolveDefaultTeamId(config, true, opts?.requestTimeout);
+    if (teamId === null) throw new Error("Failed to resolve or create default team");
+    await ensureDefaultEnv(config, teamId, opts?.requestTimeout);
+    const body = {
+      environment: DEFAULT_ENV_NAME,
+      value: input.value
+    };
+    if (input.name) body.name = input.name;
+    if (input.provider) body.provider = input.provider;
+    if (input.scopes && input.scopes.length > 0) {
+      body.scopes = input.scopes.map(vaultScopeToJSON);
+    }
+    if (input.rotationIntervalDays && input.rotationIntervalDays > 0) {
+      body.rotation_interval_days = input.rotationIntervalDays;
+    }
+    const client = getSharedClient(config);
+    const resp = await client.post(
+      `/teams/${encodeURIComponent(teamId)}/vault/secrets`,
+      { json: body, timeout: opts?.requestTimeout }
+    );
+    return parseVaultSecret(resp);
+  }
+  /**
+   * List secret metadata for the default team. Returns an empty array if no
+   * default team has been provisioned yet.
+   *
+   * GET /teams/{teamId}/vault/secrets -> {secrets}
+   */
+  static async listSecrets(opts) {
+    const config = buildConfig(opts);
+    const teamId = await resolveDefaultTeamId(config, false, opts?.requestTimeout);
+    if (teamId === null) return [];
+    const client = getSharedClient(config);
+    const resp = await client.get(
+      `/teams/${encodeURIComponent(teamId)}/vault/secrets`,
+      { timeout: opts?.requestTimeout }
+    );
+    const rows = resp.secrets ?? [];
+    return rows.map(parseVaultSecret);
+  }
+  /**
+   * Replace a secret's value by name (server-side); scopes are unchanged.
+   *
+   * POST /teams/{teamId}/vault/secrets/{secretId}/rotate {value}
+   */
+  static async rotateSecret(name, value, opts) {
+    const config = buildConfig(opts);
+    const teamId = await resolveDefaultTeamId(config, false, opts?.requestTimeout);
+    if (teamId === null) throw new Error(`vault secret "${name}" not found`);
+    const secretId = await _Vault._resolveSecretId(config, teamId, name, opts?.requestTimeout);
+    const client = getSharedClient(config);
+    await client.post(
+      `/teams/${encodeURIComponent(teamId)}/vault/secrets/${encodeURIComponent(secretId)}/rotate`,
+      { json: { value }, timeout: opts?.requestTimeout }
+    );
+  }
+  /**
+   * Delete a secret by name — metadata and stored value.
+   *
+   * DELETE /teams/{teamId}/vault/secrets/{secretId}
+   */
+  static async deleteSecret(name, opts) {
+    const config = buildConfig(opts);
+    const teamId = await resolveDefaultTeamId(config, false, opts?.requestTimeout);
+    if (teamId === null) throw new Error(`vault secret "${name}" not found`);
+    const secretId = await _Vault._resolveSecretId(config, teamId, name, opts?.requestTimeout);
+    const client = getSharedClient(config);
+    await client.delete(
+      `/teams/${encodeURIComponent(teamId)}/vault/secrets/${encodeURIComponent(secretId)}`,
+      { timeout: opts?.requestTimeout }
+    );
+  }
+  /**
+   * Replace a secret's injection scopes by name; the value is unchanged. Use
+   * this to change a secret's destination(s) or injection format in place
+   * instead of delete + recreate. At least one scope is required.
+   *
+   * POST /teams/{teamId}/vault/secrets/{secretId}/scopes
+   */
+  static async updateScopes(name, scopes, opts) {
+    if (!scopes || scopes.length === 0) {
+      throw new Error("at least one scope is required");
+    }
+    const config = buildConfig(opts);
+    const teamId = await resolveDefaultTeamId(config, false, opts?.requestTimeout);
+    if (teamId === null) throw new Error(`vault secret "${name}" not found`);
+    const secretId = await _Vault._resolveSecretId(config, teamId, name, opts?.requestTimeout);
+    const client = getSharedClient(config);
+    await client.post(
+      `/teams/${encodeURIComponent(teamId)}/vault/secrets/${encodeURIComponent(secretId)}/scopes`,
+      { json: { scopes: scopes.map(vaultScopeToJSON) }, timeout: opts?.requestTimeout }
+    );
+  }
+  // -------------------------------------------------------------------------
+  // Presets
+  // -------------------------------------------------------------------------
+  /**
+   * List built-in provider preset catalog (templates only, no secret material).
+   *
+   * GET /vault/presets -> {presets}
+   */
+  static async listPresets(opts) {
+    const client = getSharedClient(buildConfig(opts));
+    const resp = await client.get("/vault/presets", {
+      timeout: opts?.requestTimeout
+    });
+    const rows = resp.presets ?? [];
+    return rows.map(parseVaultPreset);
+  }
+  // -------------------------------------------------------------------------
+  // Internal helpers
+  // -------------------------------------------------------------------------
+  /** Maps a secret name to its id within the given team. */
+  static async _resolveSecretId(config, teamId, name, timeout) {
+    const client = getSharedClient(config);
+    const resp = await client.get(
+      `/teams/${encodeURIComponent(teamId)}/vault/secrets`,
+      { timeout }
+    );
+    const rows = resp.secrets ?? [];
+    for (const s of rows) {
+      if (s.name === name) return String(s.secret_id ?? "");
+    }
+    throw new Error(`vault secret "${name}" not found`);
+  }
+};
+
 // src/sandbox/sandbox.ts
 var DEFAULT_TEMPLATE = "base";
 var DEFAULT_TIMEOUT = 300;
@@ -2351,6 +2661,9 @@ var Sandbox = class _Sandbox {
     if (opts?.envs) {
       body.envs = opts.envs;
     }
+    if (opts?.vaultRefs) {
+      body.vault_refs = await expandVaultRefs(config, opts.vaultRefs, opts.requestTimeout);
+    }
     if (opts?.network) {
       body.network = networkOptsToJSON(opts.network);
     } else if (opts?.allowInternetAccess === false) {
@@ -3254,7 +3567,16 @@ function assertValidVolumeId3(id) {
   }
 }
 var Volumes = class {
-  /** Create a volume by streaming a tarball (gzip tar.gz) to the server. */
+  /**
+   * Create a volume named `name`, optionally populated with `data`.
+   *
+   * `POST /volumes` is the canonical create endpoint. With `data` (a gzip tar.gz)
+   * the body is ingested into a new file-granular volume (or a legacy tarball
+   * blob if no file-granular backend is configured). Creating an empty volume
+   * (no `data`, or an empty buffer) requires a file-granular backend.
+   * `empty(name)` / `ingest(name, data)` remain available for explicit,
+   * backend-specific control.
+   */
   static async create(name, data, opts) {
     if (!name) {
       throw new InvalidArgumentError("volume name is required");
@@ -3266,6 +3588,13 @@ var Volumes = class {
       requestTimeout: opts?.requestTimeout
     });
     const client = getSharedClient(config);
+    if (data === void 0 || data.byteLength === 0) {
+      const resp2 = await client.post("/volumes", {
+        params: { name },
+        timeout: opts?.requestTimeout
+      });
+      return parseVolumeInfo(resp2);
+    }
     const body = data instanceof Uint8Array ? data : new Uint8Array(data);
     const resp = await client.post("/volumes", {
       params: { name },
@@ -3570,6 +3899,7 @@ var Governance = class {
   TemplateError,
   TimeoutError,
   TransformDirection,
+  Vault,
   VolumeFiles,
   VolumeLocks,
   Volumes,
@@ -3621,6 +3951,9 @@ var Governance = class {
   parseSnapshotInfo,
   parseTemplateBuildStatus,
   parseToxicityConfig,
+  parseVaultPreset,
+  parseVaultScope,
+  parseVaultSecret,
   parseVolumeInfo,
   parseWriteInfo,
   requiresTlsInterception,
@@ -3628,6 +3961,7 @@ var Governance = class {
   securityPolicyToJSON,
   toxicityConfigToJSON,
   validateNetworkEntry,
+  vaultScopeToJSON,
   volumeAttachmentToJSON
 });
 //# sourceMappingURL=index.cjs.map