unbound-cli 1.18.0 → 1.19.0

package/src/lib/pack-remote.js

@@ -0,0 +1,308 @@
+// Network layer for `unbound pack`: reference data, managed-row discovery and
+// the sequential executor for plan operations. Everything goes through the
+// existing /api/v1 endpoints; there is no pack endpoint on the server.
+
+const api = require('../api');
+const { PackError, TOOL_TYPES, GENERIC_KINDS } = require('./pack-schema');
+
+const TOOL_PATH = '/api/v1/command-policies/';
+const GENERIC_PATH = '/api/v1/policies/';
+const PAGE_SIZE = 200;
+
+// Every write declares itself as the code path. The server marks the row
+// `origin: CODE` (so the console only lets people switch it on or off) and lets
+// the write through its code-managed lock. Reads of managed rows filter on it.
+const CODE_ORIGIN = 'CODE';
+
+// One CLI invocation is one Node process, so a module-level cache is exactly
+// one command's lifetime.
+let _ref = null;
+
+async function loadReference({ mcp = false } = {}) {
+  if (!_ref) {
+    const formResp = await api.get('/api/v1/policies/form_data/');
+    const data = formResp.data || formResp;
+    let labels = [];
+    try {
+      const resp = await api.get('/api/v1/labels/');
+      labels = resp.labels || [];
+    } catch (err) {
+      // An older backend without labels: label names simply cannot resolve.
+      if (!(err && err.statusCode === 404)) throw err;
+    }
+    _ref = {
+      userGroups: data.user_groups || [],
+      guardrails: data.guardrails || [],
+      aiModels: data.ai_models || [],
+      toolTypes: data.tool_types || [],
+      labels,
+      mcpServers: null,
+    };
+  }
+  if (mcp && !_ref.mcpServers) {
+    try {
+      const resp = await api.get(`${TOOL_PATH}metadata/mcp-servers/`);
+      _ref.mcpServers = resp.mcp_servers || [];
+      _ref.mcpServersError = null;
+    } catch (err) {
+      // Without the catalogue an action type cannot expand to tools, so the
+      // tool set is skipped in the diff; the caller warns with this reason.
+      _ref.mcpServers = [];
+      _ref.mcpServersError = err && err.message ? err.message : String(err);
+    }
+  }
+  return _ref;
+}
+
+function resetReference() {
+  _ref = null;
+}
+
+async function fetchAllToolRows(extraQuery = {}) {
+  const rows = [];
+  let page = 1;
+  for (;;) {
+    const query = { ...extraQuery, page, page_size: PAGE_SIZE };
+    const data = await api.get(TOOL_PATH, { query });
+    rows.push(...(data.policies || []));
+    if (!data.total_pages || page >= data.total_pages) break;
+    page += 1;
+  }
+  return rows;
+}
+
+async function fetchAllGenericRows(extraQuery = {}) {
+  const data = await api.get(GENERIC_PATH, Object.keys(extraQuery).length ? { query: { ...extraQuery } } : undefined);
+  return data.policies || [];
+}
+
+function classify(rows, table) {
+  const supported = [];
+  const unsupported = [];
+  for (const row of rows) {
+    const ok = table === 'tool' ? TOOL_TYPES.includes(row.policy_type) : GENERIC_KINDS.includes(String(row.type || '').toLowerCase());
+    (ok ? supported : unsupported).push(row);
+  }
+  return { supported, unsupported };
+}
+
+/**
+ * A backend without the origin field ignores the filters and returns every
+ * policy, none carrying `origin`. Applying against it would create plain
+ * console policies that the next run cannot find, so stop before any write.
+ */
+function requireCodeIdentitySupport(rows) {
+  if (rows.length && rows.every((row) => row.origin === undefined)) {
+    throw new PackError('this Unbound backend does not store the code identity of policies; policy packs need a newer server release');
+  }
+}
+
+/**
+ * Live rows that belong to one pack: `origin: CODE` with `code_pack` equal to
+ * the pack name. Names play no part. Rows of a policy type the CLI does not
+ * manage are returned under `unsupported` and never written.
+ */
+async function fetchManaged(packName) {
+  const byPack = { code_pack: packName, origin: CODE_ORIGIN };
+  // Re-checked client-side so a server that ignores the filters cannot hand
+  // back console policies as managed rows.
+  const managed = (row) => row.origin === CODE_ORIGIN && row.code_pack === packName && !!row.code_slug;
+  const [toolRows, genericRows] = await Promise.all([
+    fetchAllToolRows(byPack),
+    fetchAllGenericRows(byPack),
+  ]);
+  requireCodeIdentitySupport([...toolRows, ...genericRows]);
+  const tool = classify(toolRows.filter(managed), 'tool');
+  const generic = classify(genericRows.filter(managed), 'generic');
+  return {
+    tool: tool.supported,
+    generic: generic.supported,
+    unsupported: [
+      ...tool.unsupported.map((row) => ({ table: 'tool', row })),
+      ...generic.unsupported.map((row) => ({ table: 'generic', row })),
+    ],
+  };
+}
+
+/**
+ * Every live policy name in the org, whatever its origin, so the plan can
+ * refuse a create or rename that the server would reject as a duplicate.
+ * Map name -> { table, id, code_pack, code_slug }.
+ */
+async function fetchAllNames() {
+  const [toolRows, genericRows] = await Promise.all([fetchAllToolRows(), fetchAllGenericRows()]);
+  const names = new Map();
+  const add = (row, table) => {
+    if (row && typeof row.name === 'string') names.set(row.name, { table, id: row.id, code_pack: row.code_pack || null, code_slug: row.code_slug || null });
+  };
+  toolRows.forEach((r) => add(r, 'tool'));
+  genericRows.forEach((r) => add(r, 'generic'));
+  return names;
+}
+
+/**
+ * Every policy in the org, grouped by `code_pack`. Rows that no pack manages
+ * (console-made, or without an identity) are returned as `unmanaged`.
+ */
+async function fetchAllGrouped() {
+  const [toolRows, genericRows] = await Promise.all([fetchAllToolRows(), fetchAllGenericRows()]);
+  requireCodeIdentitySupport([...toolRows, ...genericRows]);
+  const packs = new Map();
+  const unmanaged = [];
+  const add = (row, table) => {
+    const pack = row.origin === CODE_ORIGIN && row.code_slug ? row.code_pack : null;
+    if (!pack) { unmanaged.push({ table, row }); return; }
+    if (!packs.has(pack)) packs.set(pack, { tool: [], generic: [], unsupported: [] });
+    const bucket = packs.get(pack);
+    const { supported } = classify([row], table);
+    if (supported.length) bucket[table].push(row);
+    else bucket.unsupported.push({ table, row });
+  };
+  toolRows.forEach((r) => add(r, 'tool'));
+  genericRows.forEach((r) => add(r, 'generic'));
+  return { packs, unmanaged };
+}
+
+/**
+ * Rows (either table) whose name is exactly `name`, each tagged with whether
+ * this CLI version manages its type (`supported`).
+ */
+async function findByExactName(name) {
+  const [toolRows, genericRows] = await Promise.all([fetchAllToolRows({ search: name }), fetchAllGenericRows()]);
+  const tag = (row, table) => ({ table, row, supported: classify([row], table).supported.length === 1 });
+  return [
+    ...toolRows.filter((r) => r.name === name).map((row) => tag(row, 'tool')),
+    ...genericRows.filter((r) => r.name === name).map((row) => tag(row, 'generic')),
+  ];
+}
+
+function pathFor(table, id) {
+  const base = table === 'tool' ? TOOL_PATH : GENERIC_PATH;
+  return id === undefined ? base : `${base}${id}/`;
+}
+
+async function createRow(table, body) {
+  return api.post(pathFor(table), { body: { ...body, origin: CODE_ORIGIN } });
+}
+
+async function updateRow(table, id, body) {
+  return api.put(pathFor(table, id), { body: { ...body, origin: CODE_ORIGIN } });
+}
+
+async function deleteRow(table, id) {
+  return api.del(pathFor(table, id), { query: { origin: CODE_ORIGIN } });
+}
+
+/**
+ * Id of a freshly created row. The generic endpoint wraps in {policy}, the
+ * command-policies endpoint returns the row unwrapped today; both envelopes
+ * the rest of the CLI tolerates ({command_policy}, {policy}) are handled too.
+ */
+function createdId(table, response) {
+  if (!response || typeof response !== 'object') return null;
+  let row = response;
+  if (row.command_policy && typeof row.command_policy === 'object') row = row.command_policy;
+  else if (row.policy && typeof row.policy === 'object' && row.id === undefined) row = row.policy;
+  return row.id !== undefined && row.id !== null ? row.id : null;
+}
+
+/**
+ * Replace a policy that cannot be patched in place. The new policy is created
+ * first under a temporary name and identity, so a failed create leaves the old
+ * one (and its enforcement) untouched; the old row is deleted only after that
+ * succeeds, and the new row then takes the final name and identity.
+ */
+function tempSuffix() {
+  return `-replacing-${Date.now().toString(36)}`;
+}
+
+function tempName(finalName, suffix = tempSuffix()) {
+  return `${String(finalName).slice(0, 255 - suffix.length)}${suffix}`;
+}
+
+/** Still inside the pack (same code_pack), so a stranded row shows up as an orphan on the next apply. */
+function tempSlug(finalSlug, suffix = tempSuffix()) {
+  if (!finalSlug) return undefined;
+  return `${finalSlug.slice(0, 64 - suffix.length)}${suffix}`;
+}
+
+async function replaceRow(table, oldRow, body) {
+  const suffix = tempSuffix();
+  const tmpName = tempName(body.name, suffix);
+  const tmpSlug = tempSlug(body.code_slug, suffix);
+  const created = await createRow(table, { ...body, name: tmpName, ...(tmpSlug ? { code_slug: tmpSlug } : {}) });
+  const newId = createdId(table, created);
+  if (newId === null) {
+    throw new Error(`created "${tmpName}" but the server returned no id; rename it to "${body.name}" by hand`);
+  }
+  try {
+    await deleteRow(table, oldRow.id);
+  } catch (err) {
+    // Roll back: the old policy is still there, so remove the duplicate.
+    try {
+      await deleteRow(table, newId);
+    } catch (rollbackErr) {
+      throw new Error(`deleting the old policy failed (${err.message}) and the replacement "${tmpName}" could not be removed (${rollbackErr.message}); it will show as an orphan on the next apply`);
+    }
+    throw err;
+  }
+  try {
+    const final = { name: body.name };
+    if (body.code_slug) { final.code_pack = body.code_pack; final.code_slug = body.code_slug; }
+    await updateRow(table, newId, final);
+  } catch (err) {
+    throw new Error(`old policy deleted and the new one is live as "${tmpName}", but renaming it to "${body.name}" failed: ${err.message}. Re-run apply: it will create "${body.name}" and list "${tmpName}" as an orphan to prune`);
+  }
+}
+
+/**
+ * Execute plan operations in order. Never throws for a single failed op:
+ * every op gets a result {op, status: 'ok'|'failed'|'skipped', error}.
+ * `onResult` is called after each op so the caller can stream progress.
+ */
+async function writeOps(ops, { onResult } = {}) {
+  const results = [];
+  for (const op of ops) {
+    const result = { op, status: 'skipped', error: null };
+    try {
+      if (op.op === 'create') {
+        await createRow(op.table, op.body);
+        result.status = 'ok';
+      } else if (op.op === 'update') {
+        await updateRow(op.table, op.row.id, op.body);
+        result.status = 'ok';
+      } else if (op.op === 'replace') {
+        await replaceRow(op.table, op.row, op.body);
+        result.status = 'ok';
+      } else if (op.op === 'delete') {
+        await deleteRow(op.table, op.row.id);
+        result.status = 'ok';
+      }
+    } catch (err) {
+      result.status = 'failed';
+      result.error = err && err.message ? err.message : String(err);
+    }
+    results.push(result);
+    if (onResult) onResult(result);
+  }
+  return results;
+}
+
+module.exports = {
+  TOOL_PATH,
+  GENERIC_PATH,
+  loadReference,
+  resetReference,
+  fetchManaged,
+  fetchAllNames,
+  fetchAllGrouped,
+  findByExactName,
+  createRow,
+  updateRow,
+  deleteRow,
+  replaceRow,
+  tempName,
+  tempSlug,
+  createdId,
+  writeOps,
+};

package/src/lib/pack-schema.js

@@ -0,0 +1,328 @@
+// PolicyPack file format: parsing, validation and defaults merging.
+//
+// One file is one pack. A pack is a versioned, org-owned bundle of one or more
+// policies. Every policy in the pack is materialised on the server as an
+// ordinary Cost / Security / Model policy (/api/v1/policies/) or Tool policy
+// (/api/v1/command-policies/) whose name is `<pack>/<id>`. That prefix is the
+// only tag that separates code-managed rows from console-made ones, so
+// everything in this module is pure: no network, no ids, just names.
+//
+// Validation is strict on purpose. A typo must never silently become an
+// unmanaged field, so unknown keys fail at every level. `config` is the one
+// exception: it is passed to the server verbatim and never inspected here.
+
+const path = require('path');
+const YAML = require('yaml');
+
+const API_VERSION = 'unbound.security/v1';
+const KIND = 'PolicyPack';
+
+const POLICY_KINDS = ['tool', 'security', 'model', 'cost'];
+const GENERIC_KINDS = ['security', 'model', 'cost'];
+const TOOL_TYPES = ['TERMINAL_COMMAND', 'MCP_TOOL'];
+const TOOL_ACTIONS = ['AUDIT', 'BLOCK', 'WARN', 'REQUIRE_SLACK_APPROVAL'];
+const GUARDRAIL_ACTIONS = ['BLOCK', 'REDACT', 'ROUTE', 'AUDIT'];
+const MCP_ACTION_TYPES = ['read', 'write', 'destructive'];
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+const PACK_KEYS = ['apiVersion', 'kind', 'metadata', 'defaults', 'policies'];
+const METADATA_KEYS = ['name', 'version', 'description', 'owner', 'labels'];
+const DEFAULTS_KEYS = ['enabled', 'scope', 'labels'];
+const SCOPE_KEYS = ['userGroups', 'toolTypes'];
+const COMMON_KEYS = ['id', 'name', 'kind', 'enabled', 'scope', 'config'];
+// description exists on tool policies only; the generic policy API has no such field.
+const TOOL_ONLY_KEYS = ['type', 'action', 'description', 'customMessage', 'commandFamily', 'mcp'];
+const GENERIC_ONLY_KEYS = ['priority', 'labels'];
+const SECURITY_ONLY_KEYS = ['guardrails'];
+const MODEL_ONLY_KEYS = ['models'];
+const MCP_KEYS = ['server', 'tool', 'tools', 'actionType'];
+const GUARDRAIL_KEYS = ['name', 'action', 'threshold', 'entities', 'routeModel', 'enabled'];
+const MODELS_KEYS = ['allowAll', 'allowed', 'excluded'];
+
+class PackError extends Error {
+  constructor(message, { file } = {}) {
+    super(file ? `${file}: ${message}` : message);
+    this.name = 'PackError';
+    this.exitCode = 2;
+    this.file = file;
+  }
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((s) => typeof s === 'string' && s.trim() !== '');
+}
+
+/**
+ * Parse pack text. JSON when the filename ends in .json, YAML otherwise.
+ * YAML is a superset of JSON, so a .yaml file holding JSON also parses.
+ */
+function parsePackText(text, filename = 'pack') {
+  const ext = path.extname(filename).toLowerCase();
+  try {
+    if (ext === '.json') return JSON.parse(text);
+    // Single-document YAML only. A multi-document stream is rejected so one
+    // file stays one pack.
+    const docs = YAML.parseAllDocuments(text, { prettyErrors: true });
+    if (docs.length !== 1) {
+      throw new Error(`expected exactly one YAML document, found ${docs.length}`);
+    }
+    const doc = docs[0];
+    if (doc.errors && doc.errors.length) throw doc.errors[0];
+    return doc.toJS();
+  } catch (err) {
+    throw new PackError(`could not parse: ${err.message}`, { file: filename });
+  }
+}
+
+function rejectUnknownKeys(obj, allowed, where, file) {
+  const unknown = Object.keys(obj).filter((k) => !allowed.includes(k));
+  if (unknown.length) {
+    throw new PackError(
+      `${where}: unknown key${unknown.length > 1 ? 's' : ''} ${unknown.map((k) => `"${k}"`).join(', ')}. Allowed: ${allowed.join(', ')}`,
+      { file }
+    );
+  }
+}
+
+function validateScope(scope, where, file, { allowToolTypes }) {
+  if (scope === undefined) return undefined;
+  if (!isPlainObject(scope)) throw new PackError(`${where}.scope must be an object`, { file });
+  rejectUnknownKeys(scope, SCOPE_KEYS, `${where}.scope`, file);
+  if (scope.userGroups !== undefined && !isStringArray(scope.userGroups)) {
+    throw new PackError(`${where}.scope.userGroups must be a list of user group names`, { file });
+  }
+  if (scope.toolTypes !== undefined) {
+    if (!allowToolTypes) throw new PackError(`${where}.scope.toolTypes applies to security, model and cost policies only`, { file });
+    if (!isStringArray(scope.toolTypes)) throw new PackError(`${where}.scope.toolTypes must be a list of tool type names`, { file });
+  }
+  return scope;
+}
+
+function validateMetadata(metadata, file) {
+  if (!isPlainObject(metadata)) throw new PackError('metadata must be an object', { file });
+  rejectUnknownKeys(metadata, METADATA_KEYS, 'metadata', file);
+  const { name, version, description, owner, labels } = metadata;
+  if (typeof name !== 'string' || !SLUG_RE.test(name)) {
+    throw new PackError('metadata.name is required and must match [a-z0-9][a-z0-9-]{0,63}', { file });
+  }
+  if (typeof version !== 'string' || version.trim() === '') {
+    throw new PackError('metadata.version is required (a string such as "1.0.0")', { file });
+  }
+  if (description !== undefined && typeof description !== 'string') throw new PackError('metadata.description must be a string', { file });
+  if (owner !== undefined && typeof owner !== 'string') throw new PackError('metadata.owner must be a string', { file });
+  if (labels !== undefined) {
+    if (!isPlainObject(labels) || !Object.values(labels).every((v) => typeof v === 'string')) {
+      throw new PackError('metadata.labels must be an object of string values', { file });
+    }
+  }
+  return { name, version: version.trim(), description, owner, labels };
+}
+
+function validateDefaults(defaults, file) {
+  if (defaults === undefined) return {};
+  if (!isPlainObject(defaults)) throw new PackError('defaults must be an object', { file });
+  rejectUnknownKeys(defaults, DEFAULTS_KEYS, 'defaults', file);
+  if (defaults.enabled !== undefined && typeof defaults.enabled !== 'boolean') throw new PackError('defaults.enabled must be true or false', { file });
+  if (defaults.labels !== undefined && !isStringArray(defaults.labels)) throw new PackError('defaults.labels must be a list of label names', { file });
+  validateScope(defaults.scope, 'defaults', file, { allowToolTypes: true });
+  return defaults;
+}
+
+/** Shallow merge of defaults into a policy; scope merges per sub-key. */
+function mergeDefaults(policy, defaults) {
+  const out = { ...policy };
+  if (out.enabled === undefined && defaults.enabled !== undefined) out.enabled = defaults.enabled;
+  if (out.labels === undefined && defaults.labels !== undefined && GENERIC_KINDS.includes(out.kind)) out.labels = [...defaults.labels];
+  if (defaults.scope) {
+    const scope = { ...(out.scope || {}) };
+    if (scope.userGroups === undefined && defaults.scope.userGroups !== undefined) scope.userGroups = [...defaults.scope.userGroups];
+    if (scope.toolTypes === undefined && defaults.scope.toolTypes !== undefined && GENERIC_KINDS.includes(out.kind)) scope.toolTypes = [...defaults.scope.toolTypes];
+    if (Object.keys(scope).length) out.scope = scope;
+  }
+  return out;
+}
+
+function validateMcp(mcp, where, file) {
+  if (!isPlainObject(mcp)) throw new PackError(`${where}.mcp is required for MCP_TOOL policies and must be an object`, { file });
+  rejectUnknownKeys(mcp, MCP_KEYS, `${where}.mcp`, file);
+  if (typeof mcp.server !== 'string' || mcp.server.trim() === '') throw new PackError(`${where}.mcp.server is required`, { file });
+  const selectors = ['tool', 'tools', 'actionType'].filter((k) => mcp[k] !== undefined);
+  if (selectors.length !== 1) {
+    throw new PackError(`${where}.mcp needs exactly one of tool, tools or actionType (found ${selectors.length ? selectors.join(', ') : 'none'})`, { file });
+  }
+  if (mcp.tool !== undefined && (typeof mcp.tool !== 'string' || mcp.tool.trim() === '')) throw new PackError(`${where}.mcp.tool must be a tool name`, { file });
+  if (mcp.tools !== undefined && (!isStringArray(mcp.tools) || mcp.tools.length === 0)) throw new PackError(`${where}.mcp.tools must be a non-empty list of tool names`, { file });
+  if (mcp.actionType !== undefined && !MCP_ACTION_TYPES.includes(mcp.actionType)) {
+    throw new PackError(`${where}.mcp.actionType must be one of: ${MCP_ACTION_TYPES.join(', ')}`, { file });
+  }
+  return mcp;
+}
+
+function validateToolPolicy(p, where, file) {
+  rejectUnknownKeys(p, [...COMMON_KEYS, ...TOOL_ONLY_KEYS], where, file);
+  if (!TOOL_TYPES.includes(p.type)) throw new PackError(`${where}.type must be one of: ${TOOL_TYPES.join(', ')}`, { file });
+  if (!TOOL_ACTIONS.includes(p.action)) throw new PackError(`${where}.action must be one of: ${TOOL_ACTIONS.join(', ')}`, { file });
+  if (p.customMessage !== undefined && typeof p.customMessage !== 'string') throw new PackError(`${where}.customMessage must be a string`, { file });
+  // The server accepts an empty message, and export must be able to round-trip
+  // such a policy, so the key has to be present but may be an empty string.
+  if ((p.action === 'BLOCK' || p.action === 'WARN') && typeof p.customMessage !== 'string') {
+    throw new PackError(`${where}.customMessage is required when action is BLOCK or WARN (an empty string is allowed)`, { file });
+  }
+  if (p.config !== undefined && !isPlainObject(p.config)) throw new PackError(`${where}.config must be an object`, { file });
+  if (p.type === 'TERMINAL_COMMAND') {
+    if (typeof p.commandFamily !== 'string' || p.commandFamily.trim() === '') throw new PackError(`${where}.commandFamily is required for TERMINAL_COMMAND policies`, { file });
+    if (!p.config || Object.keys(p.config).length === 0) throw new PackError(`${where}.config is required for TERMINAL_COMMAND policies (field -> pattern)`, { file });
+    if (p.mcp !== undefined) throw new PackError(`${where}.mcp applies to MCP_TOOL policies only`, { file });
+  } else {
+    if (p.commandFamily !== undefined) throw new PackError(`${where}.commandFamily applies to TERMINAL_COMMAND policies only`, { file });
+    validateMcp(p.mcp, where, file);
+  }
+}
+
+function validateGuardrails(guardrails, where, file) {
+  if (!Array.isArray(guardrails) || guardrails.length === 0) throw new PackError(`${where}.guardrails must be a non-empty list`, { file });
+  guardrails.forEach((g, i) => {
+    const gw = `${where}.guardrails[${i}]`;
+    if (!isPlainObject(g)) throw new PackError(`${gw} must be an object`, { file });
+    rejectUnknownKeys(g, GUARDRAIL_KEYS, gw, file);
+    if (typeof g.name !== 'string' || g.name.trim() === '') throw new PackError(`${gw}.name is required`, { file });
+    if (!GUARDRAIL_ACTIONS.includes(g.action)) throw new PackError(`${gw}.action must be one of: ${GUARDRAIL_ACTIONS.join(', ')}`, { file });
+    if (g.threshold !== undefined && !(Number.isInteger(g.threshold) && g.threshold >= 1 && g.threshold <= 100)) {
+      throw new PackError(`${gw}.threshold must be an integer from 1 to 100`, { file });
+    }
+    if (g.entities !== undefined && !isStringArray(g.entities)) throw new PackError(`${gw}.entities must be a list of entity names`, { file });
+    if (g.routeModel !== undefined && typeof g.routeModel !== 'string') throw new PackError(`${gw}.routeModel must be a model name`, { file });
+    if (g.enabled !== undefined && typeof g.enabled !== 'boolean') throw new PackError(`${gw}.enabled must be true or false`, { file });
+    if (g.action === 'ROUTE' && !g.routeModel) throw new PackError(`${gw}.routeModel is required when action is ROUTE`, { file });
+  });
+}
+
+function validateModels(models, where, file) {
+  if (!isPlainObject(models)) throw new PackError(`${where}.models must be an object`, { file });
+  rejectUnknownKeys(models, MODELS_KEYS, `${where}.models`, file);
+  if (models.allowAll !== undefined && typeof models.allowAll !== 'boolean') throw new PackError(`${where}.models.allowAll must be true or false`, { file });
+  if (models.allowed !== undefined && !isStringArray(models.allowed)) throw new PackError(`${where}.models.allowed must be a list of model names`, { file });
+  if (models.excluded !== undefined && !isStringArray(models.excluded)) throw new PackError(`${where}.models.excluded must be a list of model names`, { file });
+  if (models.allowed && models.allowed.length && (models.allowAll || models.excluded)) {
+    throw new PackError(`${where}.models.allowed cannot be combined with allowAll or excluded`, { file });
+  }
+  if (!models.allowAll && !(models.allowed && models.allowed.length) && !(models.excluded && models.excluded.length)) {
+    throw new PackError(`${where}.models needs allowAll: true, an allowed list, or an excluded list`, { file });
+  }
+}
+
+function validateGenericPolicy(p, where, file) {
+  const allowed = [...COMMON_KEYS, ...GENERIC_ONLY_KEYS];
+  if (p.kind === 'security') allowed.push(...SECURITY_ONLY_KEYS);
+  if (p.kind === 'model') allowed.push(...MODEL_ONLY_KEYS);
+  rejectUnknownKeys(p, allowed, where, file);
+  if (p.priority !== undefined && !Number.isInteger(p.priority)) throw new PackError(`${where}.priority must be an integer`, { file });
+  if (p.labels !== undefined && !isStringArray(p.labels)) throw new PackError(`${where}.labels must be a list of label names`, { file });
+  if (p.config !== undefined && !isPlainObject(p.config)) throw new PackError(`${where}.config must be an object`, { file });
+
+  if (p.kind === 'security') {
+    if (p.guardrails !== undefined) {
+      validateGuardrails(p.guardrails, where, file);
+      if (p.config && p.config.guardrails !== undefined) throw new PackError(`${where}: use either guardrails or config.guardrails, not both`, { file });
+    } else if (!p.config || Object.keys(p.config).length === 0) {
+      throw new PackError(`${where}: a security policy needs guardrails or a config`, { file });
+    }
+  } else if (p.kind === 'model') {
+    if (p.models !== undefined) {
+      validateModels(p.models, where, file);
+      if (p.config && ['support_all_models', 'allowed_model_ids', 'excluded_model_ids'].some((k) => k in p.config)) {
+        throw new PackError(`${where}: use either models or config.*_model_ids, not both`, { file });
+      }
+    } else if (!p.config || Object.keys(p.config).length === 0) {
+      throw new PackError(`${where}: a model policy needs models or a config`, { file });
+    }
+  } else if (p.kind === 'cost') {
+    if (!p.config || Object.keys(p.config).length === 0) throw new PackError(`${where}: a cost policy needs a config (for example monthly_budget)`, { file });
+  }
+}
+
+/**
+ * Validate a parsed pack document. Returns a normalised pack:
+ * { name, version, description, owner, labels, policies: [policy] } where
+ * each policy has defaults merged, `serverName` = its `name` or its `id`, and
+ * `enabled` resolved (default true).
+ */
+function validatePack(doc, file) {
+  if (!isPlainObject(doc)) throw new PackError('the document must be an object', { file });
+  rejectUnknownKeys(doc, PACK_KEYS, 'top level', file);
+  if (doc.apiVersion !== API_VERSION) throw new PackError(`apiVersion must be "${API_VERSION}"`, { file });
+  if (doc.kind !== KIND) throw new PackError(`kind must be "${KIND}"`, { file });
+
+  const metadata = validateMetadata(doc.metadata, file);
+  const defaults = validateDefaults(doc.defaults, file);
+
+  if (!Array.isArray(doc.policies) || doc.policies.length === 0) throw new PackError('policies must be a non-empty list', { file });
+
+  const seen = new Set();
+  const seenNames = new Set();
+  const policies = doc.policies.map((raw, i) => {
+    const where = `policies[${i}]`;
+    if (!isPlainObject(raw)) throw new PackError(`${where} must be an object`, { file });
+    if (typeof raw.id !== 'string' || !SLUG_RE.test(raw.id)) throw new PackError(`${where}.id is required and must match [a-z0-9][a-z0-9-]{0,63}`, { file });
+    if (seen.has(raw.id)) throw new PackError(`${where}.id "${raw.id}" is used twice in this pack`, { file });
+    seen.add(raw.id);
+    if (raw.name !== undefined && (typeof raw.name !== 'string' || !raw.name.trim() || raw.name.length > 255)) {
+      throw new PackError(`${where}.name must be a non-empty string of at most 255 characters`, { file });
+    }
+    const serverName = raw.name !== undefined ? raw.name.trim() : raw.id;
+    if (seenNames.has(serverName)) throw new PackError(`${where}: the name "${serverName}" is used twice in this pack`, { file });
+    seenNames.add(serverName);
+    if (!POLICY_KINDS.includes(raw.kind)) throw new PackError(`${where}.kind must be one of: ${POLICY_KINDS.join(', ')}`, { file });
+    if (raw.enabled !== undefined && typeof raw.enabled !== 'boolean') throw new PackError(`${where}.enabled must be true or false`, { file });
+    if (raw.description !== undefined && typeof raw.description !== 'string') throw new PackError(`${where}.description must be a string`, { file });
+
+    const label = `${where} (${raw.id})`;
+    if (raw.kind === 'tool') validateToolPolicy(raw, label, file);
+    else validateGenericPolicy(raw, label, file);
+    validateScope(raw.scope, label, file, { allowToolTypes: raw.kind !== 'tool' });
+
+    const merged = mergeDefaults(raw, defaults);
+    return {
+      ...merged,
+      enabled: merged.enabled === undefined ? true : merged.enabled,
+      // The policy's display name on the server: free text, defaults to the id.
+      // Identity is carried separately as code_pack + code_slug.
+      serverName,
+    };
+  });
+
+  return { ...metadata, policies };
+}
+
+/** Turn a free-form console policy name into a pack policy id. */
+function slugify(name) {
+  const slug = String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64)
+    .replace(/-+$/g, '');
+  return SLUG_RE.test(slug) ? slug : null;
+}
+
+module.exports = {
+  API_VERSION,
+  KIND,
+  POLICY_KINDS,
+  GENERIC_KINDS,
+  TOOL_TYPES,
+  TOOL_ACTIONS,
+  GUARDRAIL_ACTIONS,
+  MCP_ACTION_TYPES,
+  SLUG_RE,
+  PackError,
+  parsePackText,
+  validatePack,
+  mergeDefaults,
+  slugify,
+};

package/test/pack-confirm.test.js

@@ -0,0 +1,27 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { PassThrough } = require('node:stream');
+
+const { confirm } = require('../src/commands/pack')._internals;
+
+test('confirm fails closed when stdin is not a TTY', () => {
+  const stdin = new PassThrough();
+  stdin.isTTY = false;
+  assert.throws(() => confirm('Delete 2 policies?', { stdin }), /pass --yes/);
+});
+
+test('confirm resolves false when stdin closes without an answer', async () => {
+  const stdin = new PassThrough();
+  stdin.isTTY = true;
+  const p = confirm('Delete?', { stdin });
+  stdin.end();
+  assert.equal(await p, false);
+});
+
+test('confirm resolves true on y', async () => {
+  const stdin = new PassThrough();
+  stdin.isTTY = true;
+  const p = confirm('Delete?', { stdin });
+  stdin.write('y\n');
+  assert.equal(await p, true);
+});