@neuroverseos/governance 0.4.3 → 0.5.1

package/dist/admin/index.js

@@ -0,0 +1,703 @@
+import {
+  MENTRA_INTENT_TAXONOMY
+} from "../chunk-GJ6LM4JZ.js";
+import {
+  evaluateGuard
+} from "../chunk-ZAF6JH23.js";
+import "../chunk-QLPTHTVB.js";
+import "../chunk-QWGCMQQD.js";
+
+// src/admin/simulator.ts
+function zonePolicyToVerdict(policy) {
+  switch (policy) {
+    case "allow":
+      return "allow";
+    case "block":
+      return "block";
+    case "confirm_each":
+      return "pause";
+  }
+}
+function intentMatchesPattern(intent, pattern) {
+  if (pattern.endsWith("*")) {
+    return intent.startsWith(pattern.slice(0, -1));
+  }
+  return intent === pattern;
+}
+function evaluateIntentAgainstZone(intentDef, zone) {
+  const rules = zone.rules;
+  const domain = intentDef.domain;
+  for (const custom of rules.customRules) {
+    if (intentMatchesPattern(intentDef.intent, custom.intentPattern)) {
+      return custom.action === "confirm" ? "pause" : custom.action;
+    }
+  }
+  if (domain === "camera") return zonePolicyToVerdict(rules.camera);
+  if (domain === "microphone") return zonePolicyToVerdict(rules.microphone);
+  if (domain === "ai_data" || domain === "ai_action") {
+    if (intentDef.intent.includes("auto_purchase") || intentDef.intent.includes("auto_respond")) {
+      return zonePolicyToVerdict(rules.aiActions);
+    }
+    if (intentDef.intent.includes("retain") || intentDef.intent.includes("share")) {
+      return zonePolicyToVerdict(rules.dataRetention);
+    }
+    return zonePolicyToVerdict(rules.aiDataSend);
+  }
+  if (domain === "location") return zonePolicyToVerdict(rules.locationSharing);
+  return "allow";
+}
+function evaluateIntentAgainstRole(intentDef, role) {
+  const def = role.definition;
+  for (const pattern of def.cannotDo) {
+    if (intentDef.intent.includes(pattern) || intentDef.description.toLowerCase().includes(pattern.toLowerCase()) || intentDef.domain === pattern) {
+      return "block";
+    }
+  }
+  if (def.requiresApproval) {
+    return "pause";
+  }
+  if (def.canDo.length > 0) {
+    const allowed = def.canDo.some(
+      (pattern) => intentDef.intent.includes(pattern) || intentDef.description.toLowerCase().includes(pattern.toLowerCase()) || intentDef.domain === pattern
+    );
+    if (!allowed) return "block";
+  }
+  return "allow";
+}
+function mergeVerdicts(...verdicts) {
+  if (verdicts.includes("block")) return "block";
+  if (verdicts.includes("pause")) return "pause";
+  if (verdicts.includes("modify")) return "modify";
+  return "allow";
+}
+function simulatePolicy(request, currentRoles, currentZones, platformWorld) {
+  const intentsToTest = request.intents ? MENTRA_INTENT_TAXONOMY.filter((i) => request.intents.includes(i.intent)) : MENTRA_INTENT_TAXONOMY;
+  const verdicts = [];
+  const conflicts = [];
+  for (const intentDef of intentsToTest) {
+    let currentVerdict;
+    if (request.type !== "full_matrix") {
+      const currentVerdictParts = [];
+      if (request.targetZoneId) {
+        const currentZone = currentZones.find((z) => z.id === request.targetZoneId);
+        if (currentZone) {
+          currentVerdictParts.push(evaluateIntentAgainstZone(intentDef, currentZone));
+        }
+      }
+      if (request.targetRoleId) {
+        const currentRole = currentRoles.find((r) => r.id === request.targetRoleId);
+        if (currentRole) {
+          currentVerdictParts.push(evaluateIntentAgainstRole(intentDef, currentRole));
+        }
+      }
+      currentVerdict = currentVerdictParts.length > 0 ? mergeVerdicts(...currentVerdictParts) : "allow";
+    }
+    const proposedParts = [];
+    if (request.proposed?.zone) {
+      proposedParts.push(evaluateIntentAgainstZone(intentDef, request.proposed.zone));
+    } else if (request.targetZoneId) {
+      const existingZone = currentZones.find((z) => z.id === request.targetZoneId);
+      if (existingZone) {
+        proposedParts.push(evaluateIntentAgainstZone(intentDef, existingZone));
+      }
+    }
+    if (request.proposed?.role) {
+      proposedParts.push(evaluateIntentAgainstRole(intentDef, request.proposed.role));
+    } else if (request.targetRoleId) {
+      const existingRole = currentRoles.find((r) => r.id === request.targetRoleId);
+      if (existingRole) {
+        proposedParts.push(evaluateIntentAgainstRole(intentDef, existingRole));
+      }
+    }
+    if (request.type === "full_matrix") {
+      for (const zone of currentZones) {
+        proposedParts.push(evaluateIntentAgainstZone(intentDef, zone));
+      }
+      for (const role of currentRoles) {
+        proposedParts.push(evaluateIntentAgainstRole(intentDef, role));
+      }
+    }
+    if (platformWorld) {
+      try {
+        const event = {
+          intent: intentDef.intent,
+          scope: intentDef.domain,
+          actionCategory: intentDef.action_category
+        };
+        const guardResult = evaluateGuard(event, platformWorld, {});
+        if (guardResult.status !== "ALLOW") {
+          proposedParts.push(
+            guardResult.status === "BLOCK" ? "block" : guardResult.status === "PAUSE" ? "pause" : guardResult.status === "MODIFY" ? "modify" : "allow"
+          );
+        }
+      } catch {
+      }
+    }
+    const proposedVerdict = proposedParts.length > 0 ? mergeVerdicts(...proposedParts) : "allow";
+    const changed = currentVerdict !== void 0 && currentVerdict !== proposedVerdict;
+    verdicts.push({
+      intent: intentDef.intent,
+      description: intentDef.description,
+      currentVerdict,
+      proposedVerdict,
+      changed,
+      reason: buildReason(intentDef, proposedVerdict, request)
+    });
+    if (changed && currentVerdict === "allow" && proposedVerdict === "block") {
+      conflicts.push({
+        description: `"${intentDef.description}" was allowed but would now be blocked`,
+        severity: intentDef.base_risk === "low" ? "warning" : "error",
+        intent: intentDef.intent,
+        suggestion: `Verify that blocking ${intentDef.intent} won't break apps that depend on it`
+      });
+    }
+  }
+  const summary = {
+    total: verdicts.length,
+    allowed: verdicts.filter((v) => v.proposedVerdict === "allow").length,
+    blocked: verdicts.filter((v) => v.proposedVerdict === "block").length,
+    paused: verdicts.filter((v) => v.proposedVerdict === "pause").length,
+    modified: verdicts.filter((v) => v.proposedVerdict === "modify").length
+  };
+  const diff = request.type !== "full_matrix" ? verdicts.filter((v) => v.changed).map((v) => ({
+    intent: v.intent,
+    from: v.currentVerdict,
+    to: v.proposedVerdict,
+    explanation: `${v.description}: ${v.currentVerdict} \u2192 ${v.proposedVerdict}`
+  })) : void 0;
+  return {
+    request,
+    timestamp: Date.now(),
+    verdicts,
+    summary,
+    conflicts,
+    diff
+  };
+}
+function simulateFullMatrix(roles, zones, platformWorld) {
+  const matrix = /* @__PURE__ */ new Map();
+  for (const role of roles) {
+    const roleResults = /* @__PURE__ */ new Map();
+    for (const zone of zones) {
+      const result = simulatePolicy(
+        {
+          type: "full_matrix",
+          proposed: { role, zone }
+        },
+        [],
+        [],
+        platformWorld
+      );
+      roleResults.set(zone.id, result.verdicts);
+    }
+    matrix.set(role.id, roleResults);
+  }
+  return matrix;
+}
+function buildReason(intentDef, verdict, request) {
+  if (verdict === "block") {
+    if (request.proposed?.zone) {
+      return `Blocked by zone "${request.proposed.zone.name}" policy`;
+    }
+    if (request.proposed?.role) {
+      return `Blocked by role "${request.proposed.role.name}" restrictions`;
+    }
+    return "Blocked by combined policy";
+  }
+  if (verdict === "pause") {
+    return "Requires user confirmation before proceeding";
+  }
+  if (verdict === "modify") {
+    return "Allowed with modifications";
+  }
+  return "Allowed by current policy";
+}
+
+// src/admin/manager.ts
+var AUTHORITY_RANK = {
+  viewer: 0,
+  operator: 1,
+  supervisor: 2,
+  manager: 3,
+  admin: 4
+};
+function hasAuthority(actorLevel, requiredLevel) {
+  return AUTHORITY_RANK[actorLevel] >= AUTHORITY_RANK[requiredLevel];
+}
+var GovernanceAdmin = class {
+  storage;
+  platformWorld;
+  constructor(storage, platformWorld) {
+    this.storage = storage;
+    this.platformWorld = platformWorld;
+  }
+  // ── Authority Check ───────────────────────────────────────────────────
+  async getActorAuthority(actorRoleId) {
+    const chain = await this.storage.getAuthorityChain();
+    const grant = chain.grants.find((g) => g.roleId === actorRoleId);
+    return grant?.authorityLevel ?? "viewer";
+  }
+  async checkAuthority(actorRoleId, requiredLevel, locationId) {
+    const chain = await this.storage.getAuthorityChain();
+    const grant = chain.grants.find((g) => g.roleId === actorRoleId);
+    if (!grant || !hasAuthority(grant.authorityLevel, requiredLevel)) {
+      throw new GovernanceAdminError(
+        `Insufficient authority. Requires ${requiredLevel}, role "${actorRoleId}" has ${grant?.authorityLevel ?? "viewer"}`,
+        "INSUFFICIENT_AUTHORITY"
+      );
+    }
+    if (locationId && grant.locationScope && grant.locationScope.length > 0) {
+      if (!grant.locationScope.includes(locationId)) {
+        throw new GovernanceAdminError(
+          `Role "${actorRoleId}" does not have authority over location "${locationId}"`,
+          "LOCATION_SCOPE_DENIED"
+        );
+      }
+    }
+  }
+  async audit(action, actorId, actorRole, targetType, targetId, summary, changes) {
+    await this.storage.appendAudit({
+      id: `audit_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      action,
+      actorId,
+      actorRole,
+      timestamp: Date.now(),
+      targetType,
+      targetId,
+      changes,
+      summary
+    });
+  }
+  // ── Roles ─────────────────────────────────────────────────────────────
+  async createRole(role, actorId, actorRoleId) {
+    await this.checkAuthority(actorRoleId, "manager");
+    const existing = await this.storage.getRole(role.id);
+    if (existing) {
+      throw new GovernanceAdminError(
+        `Role "${role.id}" already exists`,
+        "ROLE_EXISTS"
+      );
+    }
+    const now = Date.now();
+    const newRole = {
+      ...role,
+      createdBy: actorId,
+      createdAt: now,
+      updatedAt: now,
+      active: true
+    };
+    await this.storage.saveRole(newRole);
+    await this.audit(
+      "role_created",
+      actorId,
+      actorRoleId,
+      "role",
+      role.id,
+      `Created role "${role.name}"`,
+      { after: newRole }
+    );
+    return newRole;
+  }
+  async updateRole(roleId, updates, actorId, actorRoleId) {
+    await this.checkAuthority(actorRoleId, "manager");
+    const existing = await this.storage.getRole(roleId);
+    if (!existing) {
+      throw new GovernanceAdminError(`Role "${roleId}" not found`, "ROLE_NOT_FOUND");
+    }
+    const updated = {
+      ...existing,
+      ...updates,
+      id: roleId,
+      // prevent ID mutation
+      updatedAt: Date.now()
+    };
+    await this.storage.saveRole(updated);
+    await this.audit(
+      "role_updated",
+      actorId,
+      actorRoleId,
+      "role",
+      roleId,
+      `Updated role "${roleId}"`,
+      {
+        before: existing,
+        after: updated
+      }
+    );
+    return updated;
+  }
+  async deleteRole(roleId, actorId, actorRoleId) {
+    await this.checkAuthority(actorRoleId, "admin");
+    const existing = await this.storage.getRole(roleId);
+    if (!existing) {
+      throw new GovernanceAdminError(`Role "${roleId}" not found`, "ROLE_NOT_FOUND");
+    }
+    const assignments = await this.storage.getAssignmentsByRole(roleId);
+    if (assignments.length > 0) {
+      throw new GovernanceAdminError(
+        `Cannot delete role "${roleId}" \u2014 ${assignments.length} device(s) still assigned. Unassign them first.`,
+        "ROLE_IN_USE"
+      );
+    }
+    await this.storage.deleteRole(roleId);
+    await this.audit(
+      "role_deleted",
+      actorId,
+      actorRoleId,
+      "role",
+      roleId,
+      `Deleted role "${existing.name}"`,
+      { before: existing }
+    );
+  }
+  async listRoles() {
+    return this.storage.getRoles();
+  }
+  async getRole(roleId) {
+    return this.storage.getRole(roleId);
+  }
+  // ── Assignments ───────────────────────────────────────────────────────
+  async assignRole(assignment, actorId, actorRoleId) {
+    await this.checkAuthority(actorRoleId, "operator");
+    const role = await this.storage.getRole(assignment.roleId);
+    if (!role) {
+      throw new GovernanceAdminError(
+        `Role "${assignment.roleId}" not found`,
+        "ROLE_NOT_FOUND"
+      );
+    }
+    const full = {
+      ...assignment,
+      id: `assign_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      assignedAt: Date.now()
+    };
+    await this.storage.saveAssignment(full);
+    await this.audit(
+      "role_assigned",
+      actorId,
+      actorRoleId,
+      "assignment",
+      full.id,
+      `Assigned role "${assignment.roleId}" to device "${assignment.deviceId}"` + (assignment.employeeName ? ` (${assignment.employeeName})` : "")
+    );
+    return full;
+  }
+  async unassignRole(assignmentId, actorId, actorRoleId) {
+    await this.checkAuthority(actorRoleId, "operator");
+    await this.storage.deleteAssignment(assignmentId);
+    await this.audit(
+      "role_unassigned",
+      actorId,
+      actorRoleId,
+      "assignment",
+      assignmentId,
+      `Removed role assignment "${assignmentId}"`
+    );
+  }
+  async getDeviceRole(deviceId) {
+    const assignments = await this.storage.getAssignmentsByDevice(deviceId);
+    const now = Date.now();
+    const active = assignments.filter(
+      (a) => !a.expiresAt || a.expiresAt > now
+    );
+    return active.sort((a, b) => b.assignedAt - a.assignedAt)[0] ?? null;
+  }
+  async listAssignments() {
+    return this.storage.getAssignments();
+  }
+  // ── Zones ─────────────────────────────────────────────────────────────
+  async createZone(zone, actorId, actorRoleId) {
+    await this.checkAuthority(actorRoleId, "manager", zone.locationId);
+    const existing = await this.storage.getZone(zone.id);
+    if (existing) {
+      throw new GovernanceAdminError(
+        `Zone "${zone.id}" already exists`,
+        "ZONE_EXISTS"
+      );
+    }
+    const now = Date.now();
+    const newZone = {
+      ...zone,
+      createdBy: actorId,
+      createdAt: now,
+      updatedAt: now,
+      active: true
+    };
+    await this.storage.saveZone(newZone);
+    await this.audit(
+      "zone_created",
+      actorId,
+      actorRoleId,
+      "zone",
+      zone.id,
+      `Created zone "${zone.name}" at location "${zone.locationId}"`,
+      { after: newZone }
+    );
+    return newZone;
+  }
+  async updateZone(zoneId, updates, actorId, actorRoleId) {
+    const existing = await this.storage.getZone(zoneId);
+    if (!existing) {
+      throw new GovernanceAdminError(`Zone "${zoneId}" not found`, "ZONE_NOT_FOUND");
+    }
+    await this.checkAuthority(actorRoleId, "manager", existing.locationId);
+    const updated = {
+      ...existing,
+      ...updates,
+      id: zoneId,
+      updatedAt: Date.now()
+    };
+    await this.storage.saveZone(updated);
+    await this.audit(
+      "zone_updated",
+      actorId,
+      actorRoleId,
+      "zone",
+      zoneId,
+      `Updated zone "${zoneId}"`,
+      {
+        before: existing,
+        after: updated
+      }
+    );
+    return updated;
+  }
+  async deleteZone(zoneId, actorId, actorRoleId) {
+    const existing = await this.storage.getZone(zoneId);
+    if (!existing) {
+      throw new GovernanceAdminError(`Zone "${zoneId}" not found`, "ZONE_NOT_FOUND");
+    }
+    await this.checkAuthority(actorRoleId, "admin", existing.locationId);
+    await this.storage.deleteZone(zoneId);
+    await this.audit(
+      "zone_deleted",
+      actorId,
+      actorRoleId,
+      "zone",
+      zoneId,
+      `Deleted zone "${existing.name}"`,
+      { before: existing }
+    );
+  }
+  async listZones(locationId) {
+    if (locationId) {
+      return this.storage.getZonesByLocation(locationId);
+    }
+    return this.storage.getZones();
+  }
+  async getZone(zoneId) {
+    return this.storage.getZone(zoneId);
+  }
+  // ── Authority ─────────────────────────────────────────────────────────
+  async updateAuthority(chain, actorId, actorRoleId) {
+    await this.checkAuthority(actorRoleId, "admin");
+    const previous = await this.storage.getAuthorityChain();
+    const enforced = {
+      ...chain,
+      emergencyOverrideAlwaysAllowed: true
+    };
+    await this.storage.saveAuthorityChain(enforced);
+    await this.audit(
+      "authority_updated",
+      actorId,
+      actorRoleId,
+      "authority",
+      "chain",
+      "Updated authority chain",
+      {
+        before: previous,
+        after: enforced
+      }
+    );
+    return enforced;
+  }
+  async getAuthority() {
+    return this.storage.getAuthorityChain();
+  }
+  // ── Simulation ────────────────────────────────────────────────────────
+  async simulate(request, actorId, actorRoleId) {
+    const roles = await this.storage.getRoles();
+    const zones = await this.storage.getZones();
+    const result = simulatePolicy(
+      request,
+      roles,
+      zones,
+      this.platformWorld
+    );
+    await this.audit(
+      "simulation_run",
+      actorId,
+      actorRoleId,
+      "simulation",
+      request.type,
+      `Ran ${request.type} simulation: ${result.summary.total} intents evaluated, ${result.summary.blocked} blocked, ${result.conflicts.length} conflicts`
+    );
+    return result;
+  }
+  async simulateMatrix(actorId, actorRoleId) {
+    const roles = await this.storage.getRoles();
+    const zones = await this.storage.getZones();
+    const result = simulateFullMatrix(roles, zones, this.platformWorld);
+    await this.audit(
+      "simulation_run",
+      actorId,
+      actorRoleId,
+      "simulation",
+      "full_matrix",
+      `Ran full matrix simulation: ${roles.length} roles \xD7 ${zones.length} zones`
+    );
+    return result;
+  }
+  /**
+   * Simulate a proposed role change and return only what would break.
+   * The "measure twice" before deploying.
+   */
+  async simulateRoleChange(roleId, proposedDefinitionUpdates, actorId, actorRoleId) {
+    const existing = await this.storage.getRole(roleId);
+    if (!existing) {
+      throw new GovernanceAdminError(`Role "${roleId}" not found`, "ROLE_NOT_FOUND");
+    }
+    const proposedRole = {
+      ...existing,
+      definition: { ...existing.definition, ...proposedDefinitionUpdates }
+    };
+    return this.simulate(
+      {
+        type: "role_change",
+        proposed: { role: proposedRole },
+        targetRoleId: roleId
+      },
+      actorId,
+      actorRoleId
+    );
+  }
+  /**
+   * Simulate a proposed zone rule change and return impact.
+   */
+  async simulateZoneChange(zoneId, proposedRuleUpdates, targetRoleId, actorId, actorRoleId) {
+    const existing = await this.storage.getZone(zoneId);
+    if (!existing) {
+      throw new GovernanceAdminError(`Zone "${zoneId}" not found`, "ZONE_NOT_FOUND");
+    }
+    const proposedZone = {
+      ...existing,
+      rules: {
+        ...existing.rules,
+        ...proposedRuleUpdates,
+        customRules: proposedRuleUpdates.customRules ?? existing.rules.customRules
+      }
+    };
+    return this.simulate(
+      {
+        type: "zone_change",
+        proposed: { zone: proposedZone },
+        targetRoleId,
+        targetZoneId: zoneId
+      },
+      actorId,
+      actorRoleId
+    );
+  }
+  // ── Audit Log ─────────────────────────────────────────────────────────
+  async getAuditLog(options) {
+    return this.storage.getAuditLog(options);
+  }
+};
+var GovernanceAdminError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "GovernanceAdminError";
+    this.code = code;
+  }
+};
+
+// src/admin/storage.ts
+var InMemoryStorage = class {
+  roles = /* @__PURE__ */ new Map();
+  assignments = /* @__PURE__ */ new Map();
+  zones = /* @__PURE__ */ new Map();
+  authority = {
+    grants: [],
+    emergencyOverrideAlwaysAllowed: true
+  };
+  audit = [];
+  // ── Roles ───────────────────────────────────────────────────────────────
+  async getRoles() {
+    return Array.from(this.roles.values());
+  }
+  async getRole(id) {
+    return this.roles.get(id) ?? null;
+  }
+  async saveRole(role) {
+    this.roles.set(role.id, role);
+  }
+  async deleteRole(id) {
+    this.roles.delete(id);
+  }
+  // ── Assignments ─────────────────────────────────────────────────────────
+  async getAssignments() {
+    return Array.from(this.assignments.values());
+  }
+  async getAssignmentsByDevice(deviceId) {
+    return Array.from(this.assignments.values()).filter(
+      (a) => a.deviceId === deviceId
+    );
+  }
+  async getAssignmentsByRole(roleId) {
+    return Array.from(this.assignments.values()).filter(
+      (a) => a.roleId === roleId
+    );
+  }
+  async saveAssignment(assignment) {
+    this.assignments.set(assignment.id, assignment);
+  }
+  async deleteAssignment(id) {
+    this.assignments.delete(id);
+  }
+  // ── Zones ───────────────────────────────────────────────────────────────
+  async getZones() {
+    return Array.from(this.zones.values());
+  }
+  async getZone(id) {
+    return this.zones.get(id) ?? null;
+  }
+  async getZonesByLocation(locationId) {
+    return Array.from(this.zones.values()).filter(
+      (z) => z.locationId === locationId
+    );
+  }
+  async saveZone(zone) {
+    this.zones.set(zone.id, zone);
+  }
+  async deleteZone(id) {
+    this.zones.delete(id);
+  }
+  // ── Authority ───────────────────────────────────────────────────────────
+  async getAuthorityChain() {
+    return this.authority;
+  }
+  async saveAuthorityChain(chain) {
+    this.authority = chain;
+  }
+  // ── Audit ───────────────────────────────────────────────────────────────
+  async getAuditLog(options) {
+    let entries = this.audit;
+    if (options?.action) {
+      entries = entries.filter((e) => e.action === options.action);
+    }
+    const offset = options?.offset ?? 0;
+    const limit = options?.limit ?? 100;
+    return entries.slice(offset, offset + limit);
+  }
+  async appendAudit(entry) {
+    this.audit.push(entry);
+  }
+};
+export {
+  GovernanceAdmin,
+  GovernanceAdminError,
+  InMemoryStorage,
+  simulateFullMatrix,
+  simulatePolicy
+};