gemstack-ai 1.1.2 → 1.3.0

package/src/lib/safety-gates.js

@@ -0,0 +1,277 @@
+const { checkEnvironmentCommercialPolicy, resolveEnvironmentTier } = require('./provider-registry');
+
+/**
+ * Creates a normalized, structured gate decision object.
+ *
+ * @param {object} params
+ * @param {boolean} params.authorized
+ * @param {string} params.decision - 'ALLOW' | 'DENY'
+ * @param {string} params.reasonCode
+ * @param {string} params.message
+ * @param {object} [params.context={}]
+ * @returns {object} Structured gate decision
+ */
+function createGateDecision({ authorized, decision, reasonCode, message, context = {} }) {
+  // Strip any accidental credential fields from context
+  const cleanContext = {};
+  for (const [k, v] of Object.entries(context)) {
+    const lk = k.toLowerCase();
+    if (!lk.includes('key') && !lk.includes('secret') && !lk.includes('token') && !lk.includes('pass')) {
+      cleanContext[k] = v;
+    }
+  }
+
+  return {
+    authorized: Boolean(authorized),
+    decision: decision || (authorized ? 'ALLOW' : 'DENY'),
+    reasonCode,
+    reason_code: reasonCode, // backward/spec compatibility
+    message,
+    context: cleanContext
+  };
+}
+
+/**
+ * ProviderCapabilityGate: Validates provider registration, environment allowance,
+ * capability declaration, and adapter execution support.
+ *
+ * @param {object} request
+ * @param {string} request.provider_id
+ * @param {string} request.capability_id
+ * @param {string} [request.environment]
+ * @param {object} [request.adapter]
+ * @param {object} registry - ProviderRegistry instance
+ * @param {object} [options={}]
+ * @returns {object} Structured gate decision
+ */
+function evaluateProviderCapability(request, registry, options = {}) {
+  if (!request || typeof request !== 'object') {
+    return createGateDecision({
+      authorized: false,
+      decision: 'DENY',
+      reasonCode: 'UNKNOWN_PROVIDER_IDENTITY',
+      message: 'Capability evaluation request must be an object.',
+      context: {}
+    });
+  }
+
+  const providerId = (request.provider_id || '').toLowerCase().trim();
+  const capabilityId = request.capability_id;
+  const envTier = resolveEnvironmentTier({ environment: request.environment, ...options });
+
+  // 1. Is Provider Registered?
+  if (!providerId || !registry || !registry.hasProvider(providerId)) {
+    return createGateDecision({
+      authorized: false,
+      decision: 'DENY',
+      reasonCode: 'UNKNOWN_PROVIDER_IDENTITY',
+      message: 'Provider "' + (request.provider_id || '') + '" is not registered in provider registry.',
+      context: { provider_id: request.provider_id, capability_id: capabilityId, environment: envTier }
+    });
+  }
+
+  const provider = registry.getProvider(providerId);
+
+  // 2. Is Provider Permitted in Active Environment?
+  if (provider.type === 'COMMERCIAL') {
+    const envPolicy = checkEnvironmentCommercialPolicy(envTier, options);
+    if (!envPolicy.allowed) {
+      return createGateDecision({
+        authorized: false,
+        decision: 'DENY',
+        reasonCode: envPolicy.reasonCode,
+        message: envPolicy.message,
+        context: { provider_id: providerId, capability_id: capabilityId, environment: envTier }
+      });
+    }
+  }
+
+  // 3. Is Capability Declared for this Provider?
+  if (!capabilityId || !registry.hasCapability(providerId, capabilityId)) {
+    return createGateDecision({
+      authorized: false,
+      decision: 'DENY',
+      reasonCode: 'PROVIDER_CAPABILITY_UNDECLARED',
+      message: 'Capability "' + (capabilityId || '') + '" is not declared for provider "' + providerId + '".',
+      context: { provider_id: providerId, capability_id: capabilityId, environment: envTier }
+    });
+  }
+
+  // 4. Does Adapter Support Capability?
+  if (request.adapter) {
+    const hasAdapterSupport = typeof request.adapter.supportsCapability === 'function'
+      ? request.adapter.supportsCapability(capabilityId)
+      : (Array.isArray(request.adapter.supportedCapabilities) && request.adapter.supportedCapabilities.includes(capabilityId));
+
+    if (!hasAdapterSupport) {
+      return createGateDecision({
+        authorized: false,
+        decision: 'DENY',
+        reasonCode: 'PROVIDER_CAPABILITY_UNSUPPORTED',
+        message: 'Adapter for provider "' + providerId + '" does not implement capability "' + capabilityId + '".',
+        context: { provider_id: providerId, capability_id: capabilityId, environment: envTier }
+      });
+    }
+  }
+
+  // 5. Success
+  return createGateDecision({
+    authorized: true,
+    decision: 'ALLOW',
+    reasonCode: 'CAPABILITY_VERIFIED',
+    message: 'Provider "' + providerId + '" capability "' + capabilityId + '" verified successfully.',
+    context: { provider_id: providerId, capability_id: capabilityId, environment: envTier }
+  });
+}
+
+/**
+ * BillableActionGate: Evaluates spending authorization, cost state classification,
+ * budget limits, and fail-closed commercial defaults.
+ *
+ * @param {object} request
+ * @param {string} request.action_id
+ * @param {string} request.provider_id
+ * @param {string} request.capability_id
+ * @param {string} [request.environment]
+ * @param {number} [request.requested_units=1]
+ * @param {object} [request.authorization_token]
+ * @param {object} ledger - Loaded cost-ledger object or ProviderRegistry
+ * @param {object} [options={}]
+ * @param {string[]} [options.declaredActions] - Optional whitelist of declared actions in spec.md
+ * @returns {object} Structured gate decision
+ */
+function evaluateBillableAction(request, ledger, options = {}) {
+  if (!request || typeof request !== 'object') {
+    return createGateDecision({
+      authorized: false,
+      decision: 'DENY',
+      reasonCode: 'UNDECLARED_BILLABLE_ACTION',
+      message: 'Billable action request must be an object.',
+      context: {}
+    });
+  }
+
+  const actionId = request.action_id;
+  const providerId = (request.provider_id || '').toLowerCase().trim();
+  const capabilityId = request.capability_id;
+  const envTier = resolveEnvironmentTier({ environment: request.environment, ...options });
+  const requestedUnits = typeof request.requested_units === 'number' ? request.requested_units : 1;
+
+  // 1. Action Declaration Check (Must be explicitly declared)
+  if (!actionId || typeof actionId !== 'string' || !actionId.trim()) {
+    return createGateDecision({
+      authorized: false,
+      decision: 'DENY',
+      reasonCode: 'UNDECLARED_BILLABLE_ACTION',
+      message: 'Action ID is missing or invalid.',
+      context: { action_id: actionId, provider_id: providerId, environment: envTier }
+    });
+  }
+
+  if (options.declaredActions && Array.isArray(options.declaredActions)) {
+    if (!options.declaredActions.includes(actionId)) {
+      return createGateDecision({
+        authorized: false,
+        decision: 'DENY',
+        reasonCode: 'UNDECLARED_BILLABLE_ACTION',
+        message: 'Billable action "' + actionId + '" is not declared in specification or active plan.',
+        context: { action_id: actionId, provider_id: providerId, environment: envTier }
+      });
+    }
+  }
+
+  // Resolve Provider & Capability from Ledger
+  let providerEntry = null;
+  let capabilityEntry = null;
+
+  if (ledger && ledger.providers && ledger.providers[providerId]) {
+    providerEntry = ledger.providers[providerId];
+    if (providerEntry.capabilities && providerEntry.capabilities[capabilityId]) {
+      capabilityEntry = providerEntry.capabilities[capabilityId];
+    }
+  }
+
+  // 2. Cost State Resolution (Strict Fail-Closed)
+  const costState = capabilityEntry ? capabilityEntry.cost_state : (request.cost_state || 'UNKNOWN');
+
+  if (costState === 'UNKNOWN' || !['FREE', 'BILLABLE', 'POTENTIALLY_BILLABLE'].includes(costState)) {
+    return createGateDecision({
+      authorized: false,
+      decision: 'DENY',
+      reasonCode: 'UNKNOWN_COST_CLASSIFICATION',
+      message: 'Action "' + actionId + '" has UNKNOWN cost classification. Fail-closed: execution denied.',
+      context: { action_id: actionId, provider_id: providerId, capability_id: capabilityId, cost_state: 'UNKNOWN', environment: envTier }
+    });
+  }
+
+  // 3. Environment Check for Commercial / Billable
+  const isCommercial = providerEntry ? providerEntry.type === 'COMMERCIAL' : (costState !== 'FREE');
+  if (isCommercial) {
+    const envPolicy = checkEnvironmentCommercialPolicy(envTier, options);
+    if (!envPolicy.allowed) {
+      return createGateDecision({
+        authorized: false,
+        decision: 'DENY',
+        reasonCode: envPolicy.reasonCode,
+        message: envPolicy.message,
+        context: { action_id: actionId, provider_id: providerId, capability_id: capabilityId, cost_state: costState, environment: envTier }
+      });
+    }
+  }
+
+  // 4. FREE Actions (Permitted for Local / MOCK / Zero Cost)
+  if (costState === 'FREE') {
+    return createGateDecision({
+      authorized: true,
+      decision: 'ALLOW',
+      reasonCode: 'ACTION_AUTHORIZED_FREE',
+      message: 'Action "' + actionId + '" is FREE and authorized for execution.',
+      context: { action_id: actionId, provider_id: providerId, capability_id: capabilityId, cost_state: 'FREE', environment: envTier }
+    });
+  }
+
+  // 5. BILLABLE / POTENTIALLY_BILLABLE Actions -> Require Explicit Spending Token
+  const token = request.authorization_token;
+  const isTokenValid = token && (token.granted === true || token.granted_by || token.source === 'CLI_FLAG' || token.max_budget_units !== undefined);
+
+  if (!isTokenValid) {
+    return createGateDecision({
+      authorized: false,
+      decision: 'DENY',
+      reasonCode: 'BILLABLE_ACTION_UNAUTHORIZED',
+      message: 'Action "' + actionId + '" on provider "' + providerId + '" requires explicit spending authorization.',
+      context: { action_id: actionId, provider_id: providerId, capability_id: capabilityId, cost_state: costState, environment: envTier }
+    });
+  }
+
+  // 6. Budget & Unit Threshold Check
+  const estimatedUnitCost = (capabilityEntry && typeof capabilityEntry.estimated_unit_cost === 'number') ? capabilityEntry.estimated_unit_cost : 1;
+  const estimatedTotalCost = requestedUnits * estimatedUnitCost;
+
+  if (token && typeof token.max_budget_units === 'number') {
+    if (estimatedTotalCost > token.max_budget_units) {
+      return createGateDecision({
+        authorized: false,
+        decision: 'DENY',
+        reasonCode: 'BUDGET_THRESHOLD_EXCEEDED',
+        message: 'Action "' + actionId + '" estimated cost (' + estimatedTotalCost + ') exceeds authorized budget limit (' + token.max_budget_units + ').',
+        context: { action_id: actionId, provider_id: providerId, capability_id: capabilityId, cost_state: costState, environment: envTier, estimated_total_cost: estimatedTotalCost, max_budget_units: token.max_budget_units }
+      });
+    }
+  }
+
+  // 7. Full Authorization Pass
+  return createGateDecision({
+    authorized: true,
+    decision: 'ALLOW',
+    reasonCode: 'ACTION_AUTHORIZED',
+    message: 'Action "' + actionId + '" authorized for execution within budget.',
+    context: { action_id: actionId, provider_id: providerId, capability_id: capabilityId, cost_state: costState, environment: envTier, estimated_total_cost: estimatedTotalCost }
+  });
+}
+
+module.exports = {
+  createGateDecision,
+  evaluateProviderCapability,
+  evaluateBillableAction
+};

package/src/lib/test-matrix.js

@@ -0,0 +1,187 @@
+const crypto = require('node:crypto');
+const { normalizeContent } = require('./hasher');
+
+const CANONICAL_LAYERS = ['UNIT', 'INTEGRATION', 'E2E', 'CLI'];
+const CANONICAL_GATES = ['REQUIRED', 'SUPPLEMENTAL'];
+const CANONICAL_ID_REGEX = /^TEST-[A-Z0-9]+-[A-Z0-9]+$/;
+const REQUIRED_FIELDS = ['id', 'category', 'layer', 'description', 'pass_criteria', 'gate'];
+
+/**
+ * Extracts the single column-0 gemstack-test-matrix block from markdown.
+ *
+ * @param {string} markdownContent
+ * @returns {{ matrix: Array<object>|null, isLegacy: boolean }}
+ */
+function extractTestMatrixBlock(markdownContent) {
+  const normalized = normalizeContent(markdownContent);
+  const lines = normalized.split('\n');
+  const fence = '```';
+  const header = '```gemstack-test-matrix';
+
+  const blocks = [];
+  let inBlock = false;
+  let blockLines = [];
+
+  for (const line of lines) {
+    if (!inBlock) {
+      if (line.trimEnd() === header) {
+        inBlock = true;
+        blockLines = [];
+      }
+    } else {
+      if (line.trimEnd() === fence) {
+        inBlock = false;
+        blocks.push(blockLines.join('\n'));
+      } else {
+        blockLines.push(line);
+      }
+    }
+  }
+
+  if (blocks.length === 0) {
+    return { matrix: null, isLegacy: true };
+  }
+
+  if (blocks.length > 1) {
+    const err = new Error(`Multiple gemstack-test-matrix blocks detected (${blocks.length}). Exactly one is permitted.`);
+    err.code = 'TEST_MATRIX_PARSE_ERROR';
+    throw err;
+  }
+
+  const jsonRaw = blocks[0].trim();
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonRaw);
+  } catch (parseErr) {
+    const err = new Error(`Failed to parse gemstack-test-matrix JSON: ${parseErr.message}`);
+    err.code = 'TEST_MATRIX_PARSE_ERROR';
+    throw err;
+  }
+
+  return { matrix: parsed, isLegacy: false };
+}
+
+/**
+ * Validates a canonical test matrix array.
+ *
+ * @param {any} matrix
+ * @returns {Array<object>} Sanitized array of canonical test objects
+ */
+function validateTestMatrix(matrix) {
+  if (!Array.isArray(matrix)) {
+    const err = new Error('gemstack-test-matrix must be a JSON array of test objects');
+    err.code = 'TEST_MATRIX_INVALID_SHAPE';
+    throw err;
+  }
+
+  const seenIds = new Set();
+  const validated = [];
+
+  for (let i = 0; i < matrix.length; i++) {
+    const item = matrix[i];
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      const err = new Error(`Item at index ${i} in gemstack-test-matrix must be a non-null object`);
+      err.code = 'TEST_MATRIX_INVALID_SHAPE';
+      throw err;
+    }
+
+    // Check unknown fields
+    const keys = Object.keys(item);
+    for (const k of keys) {
+      if (!REQUIRED_FIELDS.includes(k)) {
+        const err = new Error(`Item at index ${i} contains unknown field: "${k}"`);
+        err.code = 'TEST_MATRIX_INVALID_SHAPE';
+        throw err;
+      }
+    }
+
+    // Check required fields and empty values
+    for (const rf of REQUIRED_FIELDS) {
+      if (!(rf in item)) {
+        const err = new Error(`Item at index ${i} missing required field: "${rf}"`);
+        err.code = 'TEST_MATRIX_INVALID_SHAPE';
+        throw err;
+      }
+      if (typeof item[rf] !== 'string' || item[rf].trim().length === 0) {
+        const err = new Error(`Item at index ${i} field "${rf}" must be a non-empty string`);
+        err.code = 'TEST_MATRIX_INVALID_SHAPE';
+        throw err;
+      }
+    }
+
+    // Validate ID regex
+    if (!CANONICAL_ID_REGEX.test(item.id)) {
+      const err = new Error(`Item at index ${i} has invalid ID "${item.id}". Must match ^TEST-[A-Z0-9]+-[A-Z0-9]+$`);
+      err.code = 'TEST_MATRIX_INVALID_SHAPE';
+      throw err;
+    }
+
+    // Validate duplicate ID
+    if (seenIds.has(item.id)) {
+      const err = new Error(`Duplicate test ID detected in gemstack-test-matrix: "${item.id}"`);
+      err.code = 'TEST_MATRIX_DUPLICATE_ID';
+      throw err;
+    }
+    seenIds.add(item.id);
+
+    // Validate enum fields
+    if (!CANONICAL_LAYERS.includes(item.layer)) {
+      const err = new Error(`Item "${item.id}" has invalid layer "${item.layer}". Must be one of: ${CANONICAL_LAYERS.join(', ')}`);
+      err.code = 'TEST_MATRIX_INVALID_SHAPE';
+      throw err;
+    }
+
+    if (!CANONICAL_GATES.includes(item.gate)) {
+      const err = new Error(`Item "${item.id}" has invalid gate "${item.gate}". Must be one of: ${CANONICAL_GATES.join(', ')}`);
+      err.code = 'TEST_MATRIX_INVALID_SHAPE';
+      throw err;
+    }
+
+    validated.push({
+      id: item.id,
+      category: item.category,
+      layer: item.layer,
+      description: item.description,
+      pass_criteria: item.pass_criteria,
+      gate: item.gate
+    });
+  }
+
+  return validated;
+}
+
+/**
+ * Computes deterministic SHA-256 acceptanceSignature digest over canonical test matrix.
+ *
+ * @param {Array<object>} matrix
+ * @returns {string} 64-character lowercase hexadecimal digest
+ */
+function computeAcceptanceSignature(matrix) {
+  const validated = validateTestMatrix(matrix);
+
+  // Sort canonical records by id using deterministic code-unit ordering
+  const sorted = [...validated].sort((a, b) => (a.id < b.id ? -1 : (a.id > b.id ? 1 : 0)));
+
+  // Normalize each record with ASCII-sorted keys: category, description, gate, id, layer, pass_criteria
+  const normalizedRecords = sorted.map(rec => ({
+    category: rec.category,
+    description: rec.description,
+    gate: rec.gate,
+    id: rec.id,
+    layer: rec.layer,
+    pass_criteria: rec.pass_criteria
+  }));
+
+  const canonicalJson = JSON.stringify(normalizedRecords);
+  return crypto.createHash('sha256').update(canonicalJson, 'utf8').digest('hex');
+}
+
+module.exports = {
+  CANONICAL_LAYERS,
+  CANONICAL_GATES,
+  CANONICAL_ID_REGEX,
+  REQUIRED_FIELDS,
+  extractTestMatrixBlock,
+  validateTestMatrix,
+  computeAcceptanceSignature
+};