@orygn/opa-mcp 0.0.0 → 0.1.1

package/dist/resources/index.js

@@ -0,0 +1,107 @@
+import { OpaCli } from '../lib/opa-cli.js';
+import { tryParseJson } from '../lib/tool-helpers.js';
+import { STYLE_GUIDE } from './style-guide.js';
+import { PATTERNS } from './patterns.js';
+function categorizeBuiltins(caps) {
+    const grouped = {};
+    for (const builtin of caps.builtins ?? []) {
+        if (!builtin.name)
+            continue;
+        const categoryList = builtin.categories ?? [];
+        if (categoryList.length === 0) {
+            grouped['uncategorized'] ??= [];
+            grouped['uncategorized'].push(builtin.name);
+            continue;
+        }
+        for (const category of categoryList) {
+            grouped[category] ??= [];
+            grouped[category].push(builtin.name);
+        }
+    }
+    for (const list of Object.values(grouped))
+        list.sort();
+    return grouped;
+}
+const SECURITY_SENSITIVE = new Set([
+    'http.send',
+    'opa.runtime',
+    'crypto.x509.parse_certificates',
+    'crypto.x509.parse_certificate_request',
+    'crypto.x509.parse_keypair',
+    'crypto.x509.parse_rsa_private_key',
+    'crypto.parse_private_keys',
+]);
+async function buildBuiltinsResource(opa) {
+    const result = await opa.capabilities({ current: true });
+    if (result.exitCode !== 0) {
+        return JSON.stringify({
+            error: 'opa capabilities --current failed',
+            stderr: result.stderr.trim(),
+        }, null, 2);
+    }
+    const caps = tryParseJson(result.stdout);
+    if (!caps) {
+        return JSON.stringify({ error: 'opa capabilities produced no parseable JSON' }, null, 2);
+    }
+    const grouped = categorizeBuiltins(caps);
+    const sensitive = (caps.builtins ?? [])
+        .map((b) => b.name)
+        .filter((n) => typeof n === 'string' && SECURITY_SENSITIVE.has(n))
+        .sort();
+    return JSON.stringify({
+        version_note: 'Derived at read time from `opa capabilities --current`. Reflects the OPA build linked into this MCP server, not necessarily the OPA the user has installed locally.',
+        builtin_count: caps.builtins?.length ?? 0,
+        categories: grouped,
+        future_keywords: caps.future_keywords ?? [],
+        features: caps.features ?? [],
+        wasm_abi_versions: caps.wasm_abi_versions ?? [],
+        security_sensitive_builtins: sensitive,
+        security_note: 'The functions in `security_sensitive_builtins` introduce side effects (HTTP fetches, crypto operations, runtime introspection). Use them sparingly in policy hot paths and confirm operator approval.',
+    }, null, 2);
+}
+export function registerResources(server, config) {
+    const opa = new OpaCli(config);
+    server.registerResource('opa-builtins', 'opa://builtins', {
+        title: 'OPA built-in functions',
+        description: 'The OPA built-in function catalog, categorized by namespace, with security-sensitive functions flagged. Derived at read time from `opa capabilities --current` so the list stays in sync with the actual OPA binary.',
+        mimeType: 'application/json',
+    }, async (uri) => {
+        const content = await buildBuiltinsResource(opa);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'application/json',
+                    text: content,
+                },
+            ],
+        };
+    });
+    server.registerResource('opa-style-guide', 'opa://style-guide', {
+        title: 'Rego style guide',
+        description: 'Condensed Rego style guide adapted from the Styra reference: rego.v1, package layout, naming, default-deny, comprehensions vs every, schema annotations.',
+        mimeType: 'text/markdown',
+    }, (uri) => Promise.resolve({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: STYLE_GUIDE,
+            },
+        ],
+    }));
+    server.registerResource('opa-patterns', 'opa://patterns', {
+        title: 'Rego pattern library',
+        description: 'Curated Rego patterns: RBAC, ABAC, Kubernetes admission, IaC gates, API authorization, rate limiting. Each pattern includes when to use it, a full working example, a test, and common pitfalls.',
+        mimeType: 'text/markdown',
+    }, (uri) => Promise.resolve({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: PATTERNS,
+            },
+        ],
+    }));
+}
+//# sourceMappingURL=index.js.map

package/dist/resources/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"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"}

package/dist/resources/patterns.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Curated Rego pattern library. Each pattern includes:
+ *   - When to use it
+ *   - A working example
+ *   - A test
+ *   - Common pitfalls
+ */
+export declare const PATTERNS = "# Rego pattern library\n\nCommon Rego patterns with working examples, tests, and pitfalls. Each\npattern is self-contained \u2014 copy, adapt, and ship.\n\n---\n\n## 1. Role-based access control (RBAC)\n\n**When to use:** the simplest authorization model. Every user has one\nor more roles; each role grants a set of actions on a set of\nresources. Sufficient for ~80% of internal applications.\n\n```rego\npackage rbac\n\nimport rego.v1\n\ndefault allow := false\n\n# Permissions table \u2014 extend as roles evolve.\npermissions := {\n    \"admin\": {\"read\", \"write\", \"delete\", \"manage_users\"},\n    \"editor\": {\"read\", \"write\"},\n    \"viewer\": {\"read\"},\n}\n\nallow if {\n    some role in input.user.roles\n    input.action in permissions[role]\n}\n\n# Why was it denied? \u2014 useful for audit logs.\ndeny_reasons contains reason if {\n    not allow\n    input.user\n    reason := sprintf(\n        \"user %q has roles %v, none grant %q\",\n        [input.user.id, input.user.roles, input.action],\n    )\n}\n\ndeny_reasons contains \"anonymous request\" if {\n    not allow\n    not input.user\n}\n```\n\n**Test:**\n\n```rego\npackage rbac_test\n\nimport rego.v1\nimport data.rbac\n\ntest_admin_can_delete if {\n    rbac.allow with input as {\n        \"user\": {\"id\": \"alice\", \"roles\": [\"admin\"]},\n        \"action\": \"delete\",\n    }\n}\n\ntest_viewer_cannot_delete if {\n    not rbac.allow with input as {\n        \"user\": {\"id\": \"bob\", \"roles\": [\"viewer\"]},\n        \"action\": \"delete\",\n    }\n}\n\ntest_anonymous_denied if {\n    not rbac.allow with input as {\"action\": \"read\"}\n    \"anonymous request\" in (rbac.deny_reasons with input as {\"action\": \"read\"})\n}\n```\n\n**Pitfalls:**\n- The `permissions` table grows unbounded. Move to data files\n  (`data.permissions`) once you have more than ~20 roles.\n- Roles overlap with groups in real auth systems; map at the boundary\n  rather than carrying both.\n\n---\n\n## 2. Attribute-based access control (ABAC)\n\n**When to use:** when \"who\" alone isn't enough \u2014 decisions also depend\non resource attributes (ownership, tenant, sensitivity) and context\n(time of day, source IP).\n\n```rego\npackage abac\n\nimport rego.v1\n\ndefault allow := false\n\n# A user can read any resource they own.\nallow if {\n    input.action == \"read\"\n    input.resource.owner_id == input.user.id\n}\n\n# A user can read shared resources at their organization.\nallow if {\n    input.action == \"read\"\n    input.resource.shared\n    input.resource.org_id == input.user.org_id\n}\n\n# Admins can do anything within their organization.\nallow if {\n    \"admin\" in input.user.roles\n    input.resource.org_id == input.user.org_id\n}\n\n# Don't show \"secret\" resources to anyone outside the owner's\n# organization, even admins.\nallow := false if {\n    input.resource.classification == \"secret\"\n    input.resource.org_id != input.user.org_id\n}\n```\n\n**Test:**\n\n```rego\npackage abac_test\n\nimport rego.v1\nimport data.abac\n\ntest_owner_reads_own if {\n    abac.allow with input as {\n        \"action\": \"read\",\n        \"user\": {\"id\": \"u1\", \"org_id\": \"o1\"},\n        \"resource\": {\"owner_id\": \"u1\", \"org_id\": \"o1\"},\n    }\n}\n\ntest_admin_blocked_from_secret_in_other_org if {\n    not abac.allow with input as {\n        \"action\": \"read\",\n        \"user\": {\"id\": \"u1\", \"org_id\": \"o1\", \"roles\": [\"admin\"]},\n        \"resource\": {\n            \"owner_id\": \"u2\",\n            \"org_id\": \"o2\",\n            \"classification\": \"secret\",\n        },\n    }\n}\n```\n\n**Pitfalls:**\n- Multiple `allow` rules combine with logical OR. Use explicit\n  `allow := false if ...` to *override* an allow.\n- Don't compute attributes inside the policy; compute them at the\n  boundary and pass via `input`.\n\n---\n\n## 3. Kubernetes admission control\n\n**When to use:** validate or mutate Kubernetes resources at admission\ntime. Run as a Gatekeeper, OPA-as-a-webhook, or Kyverno-equivalent\npolicy layer.\n\n```rego\npackage k8s.admission\n\nimport rego.v1\n\n# Reject pods without resource limits.\ndeny contains msg if {\n    input.request.kind.kind == \"Pod\"\n    container := input.request.object.spec.containers[_]\n    not container.resources.limits.memory\n    msg := sprintf(\n        \"Pod %q container %q is missing resources.limits.memory\",\n        [input.request.object.metadata.name, container.name],\n    )\n}\n\n# Reject privileged containers in production.\ndeny contains msg if {\n    input.request.kind.kind == \"Pod\"\n    input.request.namespace != \"kube-system\"\n    container := input.request.object.spec.containers[_]\n    container.securityContext.privileged == true\n    msg := sprintf(\n        \"privileged containers are not allowed: %q in %q\",\n        [container.name, input.request.object.metadata.name],\n    )\n}\n```\n\n**Pitfalls:**\n- Use `input.request.object` for the resource being admitted; the\n  envelope shape comes from Kubernetes, not your control.\n- For mutations, return a JSON Patch via the `patch` field. Test\n  patches with the actual admission webhook in dry-run mode before\n  enforcing.\n- Iteration order is undefined; never rely on `containers[0]` to mean\n  anything specific.\n\n---\n\n## 4. Infrastructure-as-Code gates (Terraform)\n\n**When to use:** validate Terraform plans before apply. Catch overly\npermissive IAM, public S3 buckets, missing encryption.\n\n```rego\npackage terraform\n\nimport rego.v1\n\n# Reject S3 buckets without server-side encryption.\ndeny contains msg if {\n    resource := input.resource_changes[_]\n    resource.type == \"aws_s3_bucket\"\n    after := resource.change.after\n    not after.server_side_encryption_configuration\n    msg := sprintf(\n        \"S3 bucket %q has no server-side encryption configured\",\n        [resource.address],\n    )\n}\n\n# Reject IAM policies with action \"*\" on resource \"*\".\ndeny contains msg if {\n    resource := input.resource_changes[_]\n    resource.type == \"aws_iam_policy\"\n    policy := json.unmarshal(resource.change.after.policy)\n    statement := policy.Statement[_]\n    statement.Effect == \"Allow\"\n    \"*\" in statement.Action\n    statement.Resource == \"*\"\n    msg := sprintf(\"IAM policy %q grants Allow * on *\", [resource.address])\n}\n```\n\n**Pitfalls:**\n- Terraform plan JSON is verbose and version-specific. Pin the\n  `terraform plan -json` schema you target.\n- `resource_changes[_].change.after` may be `null` for destroys \u2014\n  guard against it.\n- For wide-radius changes, use `opa exec --decision` against a plan\n  file in CI, not the live API.\n\n---\n\n## 5. API authorization (HTTP request gating)\n\n**When to use:** at the API gateway / reverse proxy layer, validate\neach request against the caller's identity and the requested\nendpoint.\n\n```rego\npackage api.authz\n\nimport rego.v1\n\ndefault allow := false\n\n# Public endpoints \u2014 no auth required.\npublic_endpoints := {\n    {\"method\": \"GET\", \"path\": [\"health\"]},\n    {\"method\": \"GET\", \"path\": [\"version\"]},\n}\n\nallow if some _ in public_endpoints; matches_endpoint(_)\n\n# Authenticated reads on resources the user has access to.\nallow if {\n    input.method == \"GET\"\n    input.user\n    user_can_read(input.user, input.path)\n}\n\n# Authenticated writes only with specific scopes.\nallow if {\n    input.method in {\"POST\", \"PUT\", \"PATCH\", \"DELETE\"}\n    input.user\n    \"write\" in input.user.scopes\n    user_can_write(input.user, input.path)\n}\n\nmatches_endpoint(spec) if {\n    spec.method == input.method\n    spec.path == input.path\n}\n\nuser_can_read(user, path) if {\n    path[0] == \"users\"\n    user.id == path[1]\n}\n\nuser_can_write(user, path) if {\n    path[0] == \"users\"\n    user.id == path[1]\n}\n```\n\n**Pitfalls:**\n- `input.path` is typically an array (`[\"users\", \"alice\"]`), not a\n  string. Build it consistently at the gateway.\n- Path-prefix matching is easy; full pattern matching is not. For\n  parameterized routes, decode at the gateway and pass structured\n  fields.\n\n---\n\n## 6. Rate limiting (with sliding window data)\n\n**When to use:** allow N requests per principal per window. Lightweight\nlimit enforcement; for high throughput, push to a dedicated rate\nlimiter.\n\n```rego\npackage rate\n\nimport rego.v1\n\n# Configuration: 100 requests per principal per 60-second window.\nlimit := 100\nwindow_seconds := 60\n\n# input.now is a unix timestamp in nanoseconds.\n# data.requests[principal] is an array of nanosecond timestamps.\n\ncurrent_window := requests if {\n    requests := [t | some t in data.requests[input.principal]; t > input.now - window_seconds * 1000000000]\n}\n\ncount := count(current_window)\n\nallow if count < limit\n\ndeny_reason := sprintf(\n    \"rate limit exceeded: %d requests in last %d seconds (limit %d)\",\n    [count, window_seconds, limit],\n) if not allow\n```\n\n**Pitfalls:**\n- `data.requests` grows unbounded unless the writer prunes outside the\n  window. Schedule prune on every write.\n- This pattern is *advisory* \u2014 under load, two concurrent decisions\n  can both see `count == limit - 1` and both allow. For strict\n  limits, use a Lua/Redis token bucket at the gateway and have OPA\n  validate the token, not count requests.\n\n---\n\n## Where these patterns came from\n\nEach is distilled from production policy code. The full Rego files,\ntests, and policy data fixtures live in this server's GitHub\nrepository under `tests/fixtures/policies/`.\n\nFor more patterns, see:\n\n- OPA Playground: https://play.openpolicyagent.org/\n- Awesome OPA: https://github.com/anderseknert/awesome-opa\n- Styra DAS pattern library: https://docs.styra.com/das/policies\n";
+//# sourceMappingURL=patterns.d.ts.map

package/dist/resources/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../src/resources/patterns.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,glTA8WpB,CAAC"}

package/dist/resources/patterns.js

@@ -0,0 +1,375 @@
+/**
+ * Curated Rego pattern library. Each pattern includes:
+ *   - When to use it
+ *   - A working example
+ *   - A test
+ *   - Common pitfalls
+ */
+export const PATTERNS = `# Rego pattern library
+
+Common Rego patterns with working examples, tests, and pitfalls. Each
+pattern is self-contained — copy, adapt, and ship.
+
+---
+
+## 1. Role-based access control (RBAC)
+
+**When to use:** the simplest authorization model. Every user has one
+or more roles; each role grants a set of actions on a set of
+resources. Sufficient for ~80% of internal applications.
+
+\`\`\`rego
+package rbac
+
+import rego.v1
+
+default allow := false
+
+# Permissions table — extend as roles evolve.
+permissions := {
+    "admin": {"read", "write", "delete", "manage_users"},
+    "editor": {"read", "write"},
+    "viewer": {"read"},
+}
+
+allow if {
+    some role in input.user.roles
+    input.action in permissions[role]
+}
+
+# Why was it denied? — useful for audit logs.
+deny_reasons contains reason if {
+    not allow
+    input.user
+    reason := sprintf(
+        "user %q has roles %v, none grant %q",
+        [input.user.id, input.user.roles, input.action],
+    )
+}
+
+deny_reasons contains "anonymous request" if {
+    not allow
+    not input.user
+}
+\`\`\`
+
+**Test:**
+
+\`\`\`rego
+package rbac_test
+
+import rego.v1
+import data.rbac
+
+test_admin_can_delete if {
+    rbac.allow with input as {
+        "user": {"id": "alice", "roles": ["admin"]},
+        "action": "delete",
+    }
+}
+
+test_viewer_cannot_delete if {
+    not rbac.allow with input as {
+        "user": {"id": "bob", "roles": ["viewer"]},
+        "action": "delete",
+    }
+}
+
+test_anonymous_denied if {
+    not rbac.allow with input as {"action": "read"}
+    "anonymous request" in (rbac.deny_reasons with input as {"action": "read"})
+}
+\`\`\`
+
+**Pitfalls:**
+- The \`permissions\` table grows unbounded. Move to data files
+  (\`data.permissions\`) once you have more than ~20 roles.
+- Roles overlap with groups in real auth systems; map at the boundary
+  rather than carrying both.
+
+---
+
+## 2. Attribute-based access control (ABAC)
+
+**When to use:** when "who" alone isn't enough — decisions also depend
+on resource attributes (ownership, tenant, sensitivity) and context
+(time of day, source IP).
+
+\`\`\`rego
+package abac
+
+import rego.v1
+
+default allow := false
+
+# A user can read any resource they own.
+allow if {
+    input.action == "read"
+    input.resource.owner_id == input.user.id
+}
+
+# A user can read shared resources at their organization.
+allow if {
+    input.action == "read"
+    input.resource.shared
+    input.resource.org_id == input.user.org_id
+}
+
+# Admins can do anything within their organization.
+allow if {
+    "admin" in input.user.roles
+    input.resource.org_id == input.user.org_id
+}
+
+# Don't show "secret" resources to anyone outside the owner's
+# organization, even admins.
+allow := false if {
+    input.resource.classification == "secret"
+    input.resource.org_id != input.user.org_id
+}
+\`\`\`
+
+**Test:**
+
+\`\`\`rego
+package abac_test
+
+import rego.v1
+import data.abac
+
+test_owner_reads_own if {
+    abac.allow with input as {
+        "action": "read",
+        "user": {"id": "u1", "org_id": "o1"},
+        "resource": {"owner_id": "u1", "org_id": "o1"},
+    }
+}
+
+test_admin_blocked_from_secret_in_other_org if {
+    not abac.allow with input as {
+        "action": "read",
+        "user": {"id": "u1", "org_id": "o1", "roles": ["admin"]},
+        "resource": {
+            "owner_id": "u2",
+            "org_id": "o2",
+            "classification": "secret",
+        },
+    }
+}
+\`\`\`
+
+**Pitfalls:**
+- Multiple \`allow\` rules combine with logical OR. Use explicit
+  \`allow := false if ...\` to *override* an allow.
+- Don't compute attributes inside the policy; compute them at the
+  boundary and pass via \`input\`.
+
+---
+
+## 3. Kubernetes admission control
+
+**When to use:** validate or mutate Kubernetes resources at admission
+time. Run as a Gatekeeper, OPA-as-a-webhook, or Kyverno-equivalent
+policy layer.
+
+\`\`\`rego
+package k8s.admission
+
+import rego.v1
+
+# Reject pods without resource limits.
+deny contains msg if {
+    input.request.kind.kind == "Pod"
+    container := input.request.object.spec.containers[_]
+    not container.resources.limits.memory
+    msg := sprintf(
+        "Pod %q container %q is missing resources.limits.memory",
+        [input.request.object.metadata.name, container.name],
+    )
+}
+
+# Reject privileged containers in production.
+deny contains msg if {
+    input.request.kind.kind == "Pod"
+    input.request.namespace != "kube-system"
+    container := input.request.object.spec.containers[_]
+    container.securityContext.privileged == true
+    msg := sprintf(
+        "privileged containers are not allowed: %q in %q",
+        [container.name, input.request.object.metadata.name],
+    )
+}
+\`\`\`
+
+**Pitfalls:**
+- Use \`input.request.object\` for the resource being admitted; the
+  envelope shape comes from Kubernetes, not your control.
+- For mutations, return a JSON Patch via the \`patch\` field. Test
+  patches with the actual admission webhook in dry-run mode before
+  enforcing.
+- Iteration order is undefined; never rely on \`containers[0]\` to mean
+  anything specific.
+
+---
+
+## 4. Infrastructure-as-Code gates (Terraform)
+
+**When to use:** validate Terraform plans before apply. Catch overly
+permissive IAM, public S3 buckets, missing encryption.
+
+\`\`\`rego
+package terraform
+
+import rego.v1
+
+# Reject S3 buckets without server-side encryption.
+deny contains msg if {
+    resource := input.resource_changes[_]
+    resource.type == "aws_s3_bucket"
+    after := resource.change.after
+    not after.server_side_encryption_configuration
+    msg := sprintf(
+        "S3 bucket %q has no server-side encryption configured",
+        [resource.address],
+    )
+}
+
+# Reject IAM policies with action "*" on resource "*".
+deny contains msg if {
+    resource := input.resource_changes[_]
+    resource.type == "aws_iam_policy"
+    policy := json.unmarshal(resource.change.after.policy)
+    statement := policy.Statement[_]
+    statement.Effect == "Allow"
+    "*" in statement.Action
+    statement.Resource == "*"
+    msg := sprintf("IAM policy %q grants Allow * on *", [resource.address])
+}
+\`\`\`
+
+**Pitfalls:**
+- Terraform plan JSON is verbose and version-specific. Pin the
+  \`terraform plan -json\` schema you target.
+- \`resource_changes[_].change.after\` may be \`null\` for destroys —
+  guard against it.
+- For wide-radius changes, use \`opa exec --decision\` against a plan
+  file in CI, not the live API.
+
+---
+
+## 5. API authorization (HTTP request gating)
+
+**When to use:** at the API gateway / reverse proxy layer, validate
+each request against the caller's identity and the requested
+endpoint.
+
+\`\`\`rego
+package api.authz
+
+import rego.v1
+
+default allow := false
+
+# Public endpoints — no auth required.
+public_endpoints := {
+    {"method": "GET", "path": ["health"]},
+    {"method": "GET", "path": ["version"]},
+}
+
+allow if some _ in public_endpoints; matches_endpoint(_)
+
+# Authenticated reads on resources the user has access to.
+allow if {
+    input.method == "GET"
+    input.user
+    user_can_read(input.user, input.path)
+}
+
+# Authenticated writes only with specific scopes.
+allow if {
+    input.method in {"POST", "PUT", "PATCH", "DELETE"}
+    input.user
+    "write" in input.user.scopes
+    user_can_write(input.user, input.path)
+}
+
+matches_endpoint(spec) if {
+    spec.method == input.method
+    spec.path == input.path
+}
+
+user_can_read(user, path) if {
+    path[0] == "users"
+    user.id == path[1]
+}
+
+user_can_write(user, path) if {
+    path[0] == "users"
+    user.id == path[1]
+}
+\`\`\`
+
+**Pitfalls:**
+- \`input.path\` is typically an array (\`["users", "alice"]\`), not a
+  string. Build it consistently at the gateway.
+- Path-prefix matching is easy; full pattern matching is not. For
+  parameterized routes, decode at the gateway and pass structured
+  fields.
+
+---
+
+## 6. Rate limiting (with sliding window data)
+
+**When to use:** allow N requests per principal per window. Lightweight
+limit enforcement; for high throughput, push to a dedicated rate
+limiter.
+
+\`\`\`rego
+package rate
+
+import rego.v1
+
+# Configuration: 100 requests per principal per 60-second window.
+limit := 100
+window_seconds := 60
+
+# input.now is a unix timestamp in nanoseconds.
+# data.requests[principal] is an array of nanosecond timestamps.
+
+current_window := requests if {
+    requests := [t | some t in data.requests[input.principal]; t > input.now - window_seconds * 1000000000]
+}
+
+count := count(current_window)
+
+allow if count < limit
+
+deny_reason := sprintf(
+    "rate limit exceeded: %d requests in last %d seconds (limit %d)",
+    [count, window_seconds, limit],
+) if not allow
+\`\`\`
+
+**Pitfalls:**
+- \`data.requests\` grows unbounded unless the writer prunes outside the
+  window. Schedule prune on every write.
+- This pattern is *advisory* — under load, two concurrent decisions
+  can both see \`count == limit - 1\` and both allow. For strict
+  limits, use a Lua/Redis token bucket at the gateway and have OPA
+  validate the token, not count requests.
+
+---
+
+## Where these patterns came from
+
+Each is distilled from production policy code. The full Rego files,
+tests, and policy data fixtures live in this server's GitHub
+repository under \`tests/fixtures/policies/\`.
+
+For more patterns, see:
+
+- OPA Playground: https://play.openpolicyagent.org/
+- Awesome OPA: https://github.com/anderseknert/awesome-opa
+- Styra DAS pattern library: https://docs.styra.com/das/policies
+`;
+//# sourceMappingURL=patterns.js.map

package/dist/resources/patterns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.js","sourceRoot":"","sources":["../../src/resources/patterns.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8WvB,CAAC"}

package/dist/resources/style-guide.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Curated Rego style guide. Adapted from the Styra reference plus the
+ * OPA team's own conventions, condensed for LLM consumption.
+ */
+export declare const STYLE_GUIDE = "# Rego style guide\n\nA condensed reference for writing idiomatic, maintainable Rego. Adapted\nfrom the Styra style guide and the OPA project's conventions.\n\n## Always import `rego.v1`\n\nEvery `.rego` file should start with the v1 import. It enables the\nmodern syntax (`if`, `contains`, `every`) and disables the older\nimplicit-membership operator that's a frequent source of bugs.\n\n```rego\npackage authz\n\nimport rego.v1\n```\n\nOPA 1.0 (released January 2025) treats this as the default, but\nincluding it explicitly makes intent clear and keeps the file portable\nto older OPA installations.\n\n## Package layout mirrors directory layout\n\nMatch `package foo.bar` with the file path `foo/bar/main.rego` (or\n`foo/bar/<anything>.rego`). Regal flags mismatches as\n`directory-package-mismatch`.\n\nFor a multi-file package, group by responsibility:\n\n```\nauthz/\n  main.rego          # principal decision (allow / deny)\n  rbac.rego          # role-based access checks\n  abac.rego          # attribute-based access checks\n  helpers.rego       # shared helpers, no decisions\n  main_test.rego     # tests for principal decisions\n  rbac_test.rego     # tests for rbac\n```\n\nTests live in `*_test.rego` siblings of the source they test, in the\nsame package or a `<package>_test` package.\n\n## Naming\n\n- Rule names: `snake_case`.\n- Boolean rules: read like predicates \u2014 `allow`, `is_admin`,\n  `should_log`. Avoid `is_not_blocked` (double negative).\n- Set/object rules: read like nouns \u2014 `grants`, `roles`, `reasons`.\n- Helper rules: `_` prefix is *not* a convention; just give them names\n  that explain what they return.\n\nNames that conflict with reserved words (`type`, `time`, `input`) won't\nparse. Names matching builtins (`http`, `json`) shadow them.\n\n## Default deny\n\nEvery principal decision should have a default fallback so the policy\nreturns a value even when no rule matches.\n\n```rego\ndefault allow := false\n\nallow if {\n    input.user.role == \"admin\"\n}\n```\n\nThe same applies to set-valued reasons:\n\n```rego\ndeny contains reason if {\n    not allow\n    reason := \"not authorized\"\n}\n```\n\n## Comprehensions vs `every`\n\nWhen you need a value derived from a collection, use a comprehension:\n\n```rego\nadmin_users := {u | some u in input.users; u.role == \"admin\"}\n```\n\nWhen you need to assert that a property holds for every element, use\n`every` (introduced in OPA 0.41):\n\n```rego\nallow if {\n    every claim in input.token.claims {\n        claim.verified == true\n    }\n}\n```\n\n`every` is clearer than the older `not <comprehension>` idiom and\nshort-circuits on the first failure.\n\n## Annotations\n\nPublic rules deserve a metadata block so consumers know what they do.\n\n```rego\n# METADATA\n# title: Authorization decision for HTTP requests\n# description: |\n#   Returns true when the requesting principal has a role with a\n#   permission entry for the requested action on the requested\n#   resource. Anonymous requests always deny.\n# entrypoint: true\nallow if {\n    some role in input.principal.roles\n    permission_grants[role][input.action]\n}\n```\n\nAnnotations show up in `opa inspect`, the registry, and editor\nhovers. They are also extracted by `rego_describe_policy`.\n\n## Schema annotations\n\nFor policies that are sensitive to input shape, attach a JSON Schema:\n\n```rego\n# METADATA\n# schemas:\n#   - input: schema.input\nallow if {\n    input.user.id != \"\"\n}\n```\n\nCombined with `opa check --schema`, this turns input-shape mismatches\ninto compile errors instead of runtime undefineds.\n\n## Anti-patterns\n\n- **`http.send` in the decision path.** Each call adds round-trip\n  latency. If you must, scope it to a small, cacheable read.\n- **Deep `with` chains.** `x with input as ... with data as ...` more\n  than two layers deep is a smell \u2014 the test is doing too much. Split.\n- **`print` and `trace`.** Useful in development; remove before\n  shipping. Regal flags both as `print-or-trace-call`.\n- **Mixing `if` and the legacy implicit form in the same file.** Pick\n  one. With `rego.v1` imported you cannot use the implicit form.\n\n## Tests\n\n`opa test` runs every rule whose name starts with `test_`. A test\neither evaluates to true (pass) or fails to evaluate (fail). The\ncommon shape:\n\n```rego\npackage authz_test\n\nimport rego.v1\nimport data.authz\n\ntest_admin_can_delete if {\n    authz.allow with input as {\n        \"user\": {\"role\": \"admin\"},\n        \"action\": \"delete\",\n    }\n}\n\ntest_viewer_cannot_delete if {\n    not authz.allow with input as {\n        \"user\": {\"role\": \"viewer\"},\n        \"action\": \"delete\",\n    }\n}\n```\n\nRun with `opa test -v ./...` for verbose output. Add `--coverage` to\nverify which lines were exercised.\n\n## References\n\n- Official Rego style guide: https://docs.styra.com/regal/rego-style-guide\n- OPA documentation: https://www.openpolicyagent.org/docs/latest/\n- Regal linter rules: https://docs.styra.com/regal/rules\n";
+//# sourceMappingURL=style-guide.d.ts.map

package/dist/resources/style-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"style-guide.d.ts","sourceRoot":"","sources":["../../src/resources/style-guide.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,WAAW,+6JAqLvB,CAAC"}