@probelabs/visor 0.1.129 → 0.1.130

package/dist/enterprise/policy/opa-wasm-evaluator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) ProbeLabs. All rights reserved.
+ * Licensed under the Elastic License 2.0; you may not use this file except
+ * in compliance with the Elastic License 2.0.
+ */
+/**
+ * OPA WASM Evaluator - loads and evaluates OPA policies locally.
+ *
+ * Supports three input formats:
+ * 1. Pre-compiled `.wasm` bundle — loaded directly (fastest startup)
+ * 2. `.rego` files or directory — auto-compiled to WASM via `opa build` CLI
+ * 3. Directory with `policy.wasm` inside — loaded directly
+ *
+ * Compilation and caching of .rego files is delegated to {@link OpaCompiler}.
+ *
+ * Requires:
+ * - `@open-policy-agent/opa-wasm` npm package (optional dep)
+ * - `opa` CLI on PATH (only when auto-compiling .rego files)
+ */
+export declare class OpaWasmEvaluator {
+    private policy;
+    private dataDocument;
+    private compiler;
+    initialize(rulesPath: string | string[]): Promise<void>;
+    /**
+     * Load external data from a JSON file to use as the OPA data document.
+     * The loaded data will be passed to `policy.setData()` during evaluation,
+     * making it available in Rego via `data.<key>`.
+     */
+    loadData(dataPath: string): void;
+    evaluate(input: object): Promise<any>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=opa-wasm-evaluator.d.ts.map

package/dist/enterprise/policy/opa-wasm-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opa-wasm-evaluator.d.ts","sourceRoot":"","sources":["file:///home/runner/work/visor/visor/src/enterprise/policy/opa-wasm-evaluator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,YAAY,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAkC;IAE5C,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA6B7D;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IA2B1B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAcrC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAehC"}

package/dist/enterprise/policy/policy-input-builder.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Copyright (c) ProbeLabs. All rights reserved.
+ * Licensed under the Elastic License 2.0; you may not use this file except
+ * in compliance with the Elastic License 2.0.
+ */
+import type { PolicyConfig, StepPolicyOverride } from '../../policy/types';
+/**
+ * OPA input document shape (internal to enterprise code).
+ * This mirrors what OPA .rego rules expect — OSS code never sees this type.
+ */
+export interface OpaInput {
+    scope: string;
+    check?: {
+        id: string;
+        type: string;
+        group?: string;
+        tags?: string[];
+        criticality?: string;
+        sandbox?: string;
+        policy?: StepPolicyOverride;
+    };
+    tool?: {
+        serverName: string;
+        methodName: string;
+        transport?: string;
+    };
+    capability?: {
+        allowEdit?: boolean;
+        allowBash?: boolean;
+        allowedTools?: string[];
+        enableDelegate?: boolean;
+        sandbox?: string;
+    };
+    actor: {
+        authorAssociation?: string;
+        login?: string;
+        roles: string[];
+        isLocalMode: boolean;
+        slack?: {
+            userId?: string;
+            email?: string;
+            channelId?: string;
+            channelType?: 'channel' | 'dm' | 'group';
+        };
+    };
+    repository?: {
+        owner?: string;
+        name?: string;
+        branch?: string;
+        baseBranch?: string;
+        event?: string;
+        action?: string;
+    };
+    pullRequest?: {
+        number?: number;
+        labels?: string[];
+        draft?: boolean;
+        changedFiles?: number;
+    };
+}
+export interface ActorContext {
+    authorAssociation?: string;
+    login?: string;
+    isLocalMode: boolean;
+    slack?: {
+        userId?: string;
+        email?: string;
+        channelId?: string;
+        channelType?: 'channel' | 'dm' | 'group';
+    };
+}
+export interface RepositoryContext {
+    owner?: string;
+    name?: string;
+    branch?: string;
+    baseBranch?: string;
+    event?: string;
+    action?: string;
+}
+export interface PullRequestContext {
+    number?: number;
+    labels?: string[];
+    draft?: boolean;
+    changedFiles?: number;
+}
+export interface CheckContext {
+    id: string;
+    type: string;
+    group?: string;
+    tags?: string[];
+    criticality?: string;
+    sandbox?: string;
+    policy?: StepPolicyOverride;
+}
+/**
+ * Builds OPA-compatible input documents from engine context.
+ *
+ * Resolves actor roles from the `policy.roles` config section by matching
+ * the actor's authorAssociation and login against role definitions.
+ */
+export declare class PolicyInputBuilder {
+    private roles;
+    private actor;
+    private repository?;
+    private pullRequest?;
+    constructor(policyConfig: PolicyConfig, actor: ActorContext, repository?: RepositoryContext, pullRequest?: PullRequestContext);
+    /** Resolve which roles apply to the current actor. */
+    resolveRoles(): string[];
+    private buildActor;
+    forCheckExecution(check: CheckContext): OpaInput;
+    forToolInvocation(serverName: string, methodName: string, transport?: string): OpaInput;
+    forCapabilityResolve(checkId: string, capabilities: {
+        allowEdit?: boolean;
+        allowBash?: boolean;
+        allowedTools?: string[];
+        enableDelegate?: boolean;
+        sandbox?: string;
+    }): OpaInput;
+}
+//# sourceMappingURL=policy-input-builder.d.ts.map

package/dist/enterprise/policy/policy-input-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-input-builder.d.ts","sourceRoot":"","sources":["file:///home/runner/work/visor/visor/src/enterprise/policy/policy-input-builder.ts"],"names":[],"mappings":"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"}

package/dist/enterprise/scheduler/knex-store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) ProbeLabs. All rights reserved.
+ * Licensed under the Elastic License 2.0; you may not use this file except
+ * in compliance with the Elastic License 2.0.
+ */
+import type { Schedule, ScheduleLimits } from '../../scheduler/schedule-store';
+import type { ScheduleStoreBackend, ScheduleStoreStats, StorageConfig, HAConfig } from '../../scheduler/store/types';
+/**
+ * Enterprise Knex-backed store for PostgreSQL, MySQL, and MSSQL
+ */
+export declare class KnexStoreBackend implements ScheduleStoreBackend {
+    private knex;
+    private driver;
+    private connection;
+    constructor(driver: 'postgresql' | 'mysql' | 'mssql', storageConfig: StorageConfig, _haConfig?: HAConfig);
+    initialize(): Promise<void>;
+    private buildStandardConnection;
+    private buildMssqlConnection;
+    private resolveSslConfig;
+    private validateSslPath;
+    shutdown(): Promise<void>;
+    private migrateSchema;
+    private getKnex;
+    create(schedule: Omit<Schedule, 'id' | 'createdAt' | 'runCount' | 'failureCount' | 'status'>): Promise<Schedule>;
+    importSchedule(schedule: Schedule): Promise<void>;
+    get(id: string): Promise<Schedule | undefined>;
+    update(id: string, patch: Partial<Schedule>): Promise<Schedule | undefined>;
+    delete(id: string): Promise<boolean>;
+    getByCreator(creatorId: string): Promise<Schedule[]>;
+    getActiveSchedules(): Promise<Schedule[]>;
+    getDueSchedules(now?: number): Promise<Schedule[]>;
+    findByWorkflow(creatorId: string, workflowName: string): Promise<Schedule[]>;
+    getAll(): Promise<Schedule[]>;
+    getStats(): Promise<ScheduleStoreStats>;
+    validateLimits(creatorId: string, isRecurring: boolean, limits: ScheduleLimits): Promise<void>;
+    tryAcquireLock(lockId: string, nodeId: string, ttlSeconds: number): Promise<string | null>;
+    releaseLock(lockId: string, lockToken: string): Promise<void>;
+    renewLock(lockId: string, lockToken: string, ttlSeconds: number): Promise<boolean>;
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=knex-store.d.ts.map

package/dist/enterprise/scheduler/knex-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knex-store.d.ts","sourceRoot":"","sources":["file:///home/runner/work/visor/visor/src/enterprise/scheduler/knex-store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAC/E,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,QAAQ,EAET,MAAM,6BAA6B,CAAC;AA+FrC;;GAEG;AACH,qBAAa,gBAAiB,YAAW,oBAAoB;IAC3D,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,UAAU,CAAyB;gBAGzC,MAAM,EAAE,YAAY,GAAG,OAAO,GAAG,OAAO,EACxC,aAAa,EAAE,aAAa,EAC5B,SAAS,CAAC,EAAE,QAAQ;IAMhB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAkDjC,OAAO,CAAC,uBAAuB;IAW/B,OAAO,CAAC,oBAAoB;IAkB5B,OAAO,CAAC,gBAAgB;IA4BxB,OAAO,CAAC,eAAe;IAWjB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;YAOjB,aAAa;IA4C3B,OAAO,CAAC,OAAO;IAST,MAAM,CACV,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,QAAQ,CAAC,GACpF,OAAO,CAAC,QAAQ,CAAC;IAkBd,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAM9C,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAgB3E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYpC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAMpD,kBAAkB,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAMzC,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAsBlD,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAW5E,MAAM,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAM7B,QAAQ,IAAI,OAAO,CAAC,kBAAkB,CAAC;IA4BvC,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,IAAI,CAAC;IAqCV,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAmC1F,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7D,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAalF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/examples/README.md

@@ -134,6 +134,9 @@ Example configurations demonstrating various Visor features and use cases.
 - **`sandbox-multi-env.yaml`** - Multiple sandbox environments per check
 - **`sandbox-read-only.yaml`** - Read-only sandbox with network isolation
 
+### Enterprise Policy Examples (EE)
+- **`enterprise-policy/`** - OPA policy engine with role-based access control **(Enterprise Edition -- requires license, contact hello@probelabs.com)**
+
 ### Integration Examples
 - **`jira-simple-example.yaml`** - Simple JIRA integration
 - **`jira-single-issue-workflow.yaml`** - Single JIRA issue workflow
@@ -464,6 +467,26 @@ visor --config examples/workflows/quick-pr-check.yaml --input "pr_type=feature"
 visor --config examples/workflows/workflow-composition-example.yaml
 ```
 
+## Enterprise Policy Engine (EE)
+
+> **Enterprise Edition feature.** Requires a Visor EE license.
+> Contact **hello@probelabs.com** for licensing.
+
+Role-based access control for checks, MCP tools, and AI capabilities using OPA (Open Policy Agent) policies:
+
+```bash
+# Install EE build
+npm install @probelabs/visor@ee
+
+# Set license
+export VISOR_LICENSE="<your-jwt-token>"
+
+# Run with policy enforcement
+visor --config examples/enterprise-policy/visor.yaml
+```
+
+See [`examples/enterprise-policy/README.md`](enterprise-policy/README.md) for full documentation, configuration reference, and Rego policy examples.
+
 ## 📚 Further Reading
 
 - [Main README](../README.md) - Complete Visor documentation

package/dist/examples/enterprise-policy/README.md

@@ -0,0 +1,344 @@
+# OPA Policy Engine (Enterprise Edition)
+
+> **This is an Enterprise Edition feature.** A valid Visor EE license is required.
+> To get a license or learn more, contact **hello@probelabs.com**.
+
+The OPA (Open Policy Agent) policy engine gives you fine-grained, role-based access control over Visor checks, MCP tools, and AI capabilities. Policies are written in [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) and evaluated locally via WASM or against a remote OPA server.
+
+For the full documentation, see [docs/enterprise-policy.md](../../docs/enterprise-policy.md).
+
+## What it controls
+
+| Scope | What it does |
+|-------|-------------|
+| **Check execution** | Gate which checks can run based on the actor's role |
+| **MCP tool access** | Allow or block specific MCP methods per role |
+| **AI capabilities** | Restrict `allowBash`, `allowEdit`, and tool lists per role |
+
+## Prerequisites
+
+| Dependency | Purpose |
+|-----------|---------|
+| `@probelabs/visor@ee` | Visor Enterprise Edition build |
+| Valid EE license (JWT) | Activates the policy engine |
+| `opa` CLI | Compiles `.rego` files to WASM at startup (local mode) |
+| `@open-policy-agent/opa-wasm` | Evaluates WASM policies in-process (installed automatically with EE build) |
+
+### Installing the OPA CLI
+
+The OPA CLI is needed to compile `.rego` files into WebAssembly at startup.
+
+**macOS:**
+```bash
+brew install opa
+```
+
+**Linux:**
+```bash
+curl -L -o /usr/local/bin/opa \
+  https://openpolicyagent.org/downloads/latest/opa_linux_amd64_static
+chmod +x /usr/local/bin/opa
+```
+
+**Verify:**
+```bash
+opa version
+```
+
+> You can skip the OPA CLI if you pre-compile your `.rego` files into a `.wasm` bundle (see [Pre-compiling](#pre-compiling-wasm-bundles) below).
+
+## Quick start
+
+### 1. Install the EE build
+
+```bash
+npm install @probelabs/visor@ee
+```
+
+### 2. Set your license
+
+```bash
+# Option A: environment variable
+export VISOR_LICENSE="<your-jwt-token>"
+
+# Option B: file in project root
+echo "<your-jwt-token>" > .visor-license
+```
+
+### 3. Add the `policy:` block to your `.visor.yaml`
+
+```yaml
+version: "1.0"
+
+policy:
+  engine: local              # 'local' (WASM) or 'remote' (HTTP OPA server)
+  rules: ./policies/         # Path to .rego files (local mode)
+  fallback: deny             # 'allow' or 'deny' when evaluation fails
+  timeout: 5000              # Evaluation timeout in ms
+
+  roles:
+    admin:
+      author_association: [OWNER]
+      users: [cto-username]
+    developer:
+      author_association: [MEMBER, COLLABORATOR]
+    external:
+      author_association: [FIRST_TIME_CONTRIBUTOR, FIRST_TIMER, NONE]
+```
+
+### 4. Write Rego policies
+
+See the `policies/` directory in this example for ready-to-use policies:
+
+- **`check_execute.rego`** -- Controls which checks each role can run
+- **`tool_invoke.rego`** -- Blocks destructive MCP methods for non-admins
+- **`capability_resolve.rego`** -- Restricts AI capabilities (bash, file editing) by role
+
+### 5. Run
+
+```bash
+visor --config .visor.yaml
+```
+
+Checks that the actor's role is not authorized for will be skipped with reason `policy_denied`.
+
+## Files in this example
+
+```
+enterprise-policy/
+  visor.yaml                          # Example .visor.yaml with policy configuration
+  policies/
+    check_execute.rego                # Check execution gating
+    tool_invoke.rego                  # MCP tool access control
+    capability_resolve.rego           # AI capability restrictions
+```
+
+## Configuration reference
+
+### Top-level `policy:` block
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `engine` | `local` \| `remote` \| `disabled` | Evaluation backend |
+| `rules` | `string` \| `string[]` | Path to `.rego` files or `.wasm` bundle (local mode) |
+| `url` | `string` | OPA server URL (remote mode) |
+| `fallback` | `allow` \| `deny` \| `warn` | Default decision on evaluation failure |
+| `timeout` | `number` | Evaluation timeout in ms (default: 5000) |
+| `roles` | `map` | Role definitions (see below) |
+
+### Role definitions
+
+Roles map GitHub author associations, team slugs, or explicit usernames to named roles that your Rego policies reference.
+
+```yaml
+roles:
+  admin:
+    author_association: [OWNER]
+    users: [alice, bob]
+  developer:
+    author_association: [MEMBER, COLLABORATOR]
+  external:
+    author_association: [FIRST_TIME_CONTRIBUTOR, NONE]
+```
+
+### Per-step `policy:` override
+
+Individual steps can declare role requirements directly in YAML, without writing Rego:
+
+```yaml
+steps:
+  deploy-production:
+    type: command
+    exec: ./deploy.sh production
+    policy:
+      require: admin           # Only admin role can trigger this
+      deny: [external]         # Explicitly deny external contributors
+      rule: visor/deploy/prod  # Optional: custom OPA rule path
+```
+
+## Rego policy structure
+
+Policies live under `package visor.<scope>` and must export an `allowed` boolean:
+
+```rego
+package visor.check.execute
+
+default allowed = false
+
+allowed {
+  input.actor.roles[_] == "admin"
+}
+
+reason = "access denied" { not allowed }
+```
+
+### Available scopes
+
+| Package | Evaluated when |
+|---------|---------------|
+| `visor.check.execute` | Before each check runs |
+| `visor.tool.invoke` | Before each MCP tool call |
+| `visor.capability.resolve` | When assembling AI config |
+
+### Input document
+
+Your Rego policies receive an `input` document with these fields:
+
+```json
+{
+  "scope": "check.execute",
+  "check": {
+    "id": "deploy-production",
+    "type": "command",
+    "tags": ["deploy"],
+    "criticality": "external",
+    "policy": { "require": "admin" }
+  },
+  "actor": {
+    "login": "alice",
+    "authorAssociation": "MEMBER",
+    "roles": ["developer"],
+    "isLocalMode": false
+  },
+  "repository": {
+    "owner": "probelabs",
+    "name": "visor",
+    "branch": "feat/new-feature"
+  }
+}
+```
+
+## Writing Rego for Visor
+
+### Checking roles
+
+Use `input.actor.roles[_]` to check if the actor has a specific role:
+
+```rego
+allowed {
+  input.actor.roles[_] == "admin"
+}
+```
+
+### Handling per-step YAML requirements
+
+When a step declares `policy.require`, your Rego must handle both string and array values:
+
+```rego
+# String require (e.g., require: admin)
+allowed {
+  required := input.check.policy.require
+  is_string(required)
+  input.actor.roles[_] == required
+}
+
+# Array require (e.g., require: [developer, admin])
+allowed {
+  required := input.check.policy.require
+  is_array(required)
+  required[_] == input.actor.roles[_]
+}
+```
+
+### Local mode bypass
+
+When running locally (CLI), you may want to allow all checks:
+
+```rego
+allowed {
+  input.actor.isLocalMode == true
+}
+```
+
+### WASM-safe patterns
+
+OPA compiles Rego to WebAssembly for fast in-process evaluation. Some patterns are not WASM-safe:
+
+```rego
+# BAD: not safe for WASM compilation
+allowed = false {
+  not input.actor.roles[_] == "admin"
+}
+
+# GOOD: use a helper rule
+is_admin { input.actor.roles[_] == "admin" }
+allowed = false {
+  not is_admin
+}
+```
+
+### Testing your policies
+
+Use the OPA CLI to test policies before deploying:
+
+```bash
+# Evaluate with test input
+echo '{"actor":{"roles":["developer"],"isLocalMode":false},"check":{"id":"deploy-staging"}}' | \
+  opa eval -d policies/ -i /dev/stdin 'data.visor.check.execute.allowed'
+
+# Check for syntax errors
+opa check policies/
+
+# Run OPA unit tests (if you have _test.rego files)
+opa test policies/ -v
+```
+
+## Pre-compiling WASM bundles
+
+For faster startup (skip compilation at runtime), pre-compile your policies:
+
+```bash
+# Compile all .rego files into a WASM bundle
+opa build -t wasm -e visor -d policies/ -o bundle.tar.gz
+
+# Extract the WASM file
+tar -xzf bundle.tar.gz /policy.wasm
+
+# Reference the .wasm file in config
+# policy:
+#   rules: ./policy.wasm
+```
+
+> When compiling with `opa build`, always use `-e visor` as the entrypoint.
+
+## Remote OPA server
+
+To evaluate against a running OPA server instead of local WASM:
+
+```yaml
+policy:
+  engine: remote
+  url: http://opa:8181
+  fallback: deny
+  timeout: 3000
+```
+
+Visor sends POST requests to `${url}/v1/data/visor/<scope>` with `{ "input": ... }`.
+
+### Running an OPA server
+
+```bash
+# Local server with your policies
+opa run --server --addr :8181 ./policies/
+
+# Docker
+docker run -p 8181:8181 \
+  -v $(pwd)/policies:/policies \
+  openpolicyagent/opa:latest \
+  run --server --addr :8181 /policies/
+```
+
+## Without a license
+
+If no valid license is found, the policy engine is silently disabled and all checks run as normal (the OSS default). No error is raised.
+
+## Further reading
+
+- [Full enterprise policy documentation](../../docs/enterprise-policy.md) -- comprehensive guide with troubleshooting
+- [Author permissions (OSS)](../../docs/author-permissions.md) -- simpler, inline permission checks
+- [OPA documentation](https://www.openpolicyagent.org/docs/latest/) -- official OPA docs
+- [Rego playground](https://play.openpolicyagent.org/) -- interactive Rego editor and tester
+
+---
+
+**Questions? Need a license?** Contact **hello@probelabs.com**

package/dist/examples/enterprise-policy/policies/capability_resolve.rego

@@ -0,0 +1,29 @@
+# AI capability restriction policy (Visor Enterprise Edition)
+# Controls which AI capabilities (bash, file editing) are available per role.
+# Contact hello@probelabs.com for licensing.
+
+package visor.capability.resolve
+
+# Helper: actor has developer role
+is_developer { input.actor.roles[_] == "developer" }
+
+# Helper: actor has admin role
+is_admin { input.actor.roles[_] == "admin" }
+
+# Disable file editing for non-developers
+capabilities["allowEdit"] = false {
+  not is_developer
+  not is_admin
+}
+
+# Disable bash for external contributors
+capabilities["allowBash"] = false {
+  input.actor.roles[_] == "external"
+}
+
+reason = "edit capability restricted for non-developer/admin roles" {
+  capabilities["allowEdit"] == false
+}
+reason = "bash capability restricted for external contributors" {
+  capabilities["allowBash"] == false
+}