@intx/authz 0.1.2

package/README.md

@@ -0,0 +1,49 @@
+# @intx/authz
+
+Grant evaluation engine. Given a principal, a tenant, a resource,
+and an action, `authorize` collects the relevant grants from a
+`GrantStore`, picks the most specific match, applies condition
+evaluators, and returns the resolved effect.
+
+Pattern matching uses colon-segmented patterns with `*` and `**`
+wildcards; specificity scoring picks the most specific matching
+grant; condition evaluators gate matches on runtime facts such as
+time windows. An in-memory grant store is included for tests and
+single-process deployments; `@intx/db` provides the database-backed
+implementation.
+
+Consumed by `@intx/hub-api` for HTTP request authorization and by
+`@intx/harness` for tool-call gating.
+
+```ts
+import { authorize, createInMemoryGrantStore } from "@intx/authz";
+
+const store = createInMemoryGrantStore([
+  {
+    id: "g1",
+    principalId: "user-1",
+    roleId: null,
+    effect: "allow",
+    origin: "system",
+    resource: "tenant:*:agent:*",
+    action: "read",
+    conditions: null,
+    expiresAt: null,
+  },
+]);
+
+const result = await authorize(
+  store,
+  "user-1",
+  "acme",
+  "tenant:acme:agent:abc",
+  "read",
+);
+
+if (result.effect !== "allow") throw new Error("forbidden");
+```
+
+`authorize` returns an `AuthzResult` whose `effect` is one of
+`allow`, `deny`, `ask`, or `null` when no grant matches. Callers
+translate `null` into a refusal (HTTP 403, tool-call block) because
+evaluation is fail-closed.

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@intx/authz",
+  "version": "0.1.2",
+  "license": "LGPL-2.1-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@intx/types": "0.0.0"
+  }
+}

package/src/conditions.test.ts

@@ -0,0 +1,158 @@
+import { describe, test, expect } from "bun:test";
+
+import { evaluateConditions } from "./conditions";
+import type { ConditionContext, ConditionRegistry } from "./types";
+
+function ctx(overrides?: Partial<ConditionContext>): ConditionContext {
+  return {
+    now: new Date("2025-06-15T14:30:00Z"),
+    resource: "agent:agt_abc",
+    action: "read",
+    principalId: "prn_1",
+    tenantId: "tnt_1",
+    ...overrides,
+  };
+}
+
+describe("evaluateConditions", () => {
+  test("null conditions are always met", async () => {
+    expect(await evaluateConditions(null, ctx())).toBe(true);
+  });
+
+  test("empty object conditions are always met", async () => {
+    expect(await evaluateConditions({}, ctx())).toBe(true);
+  });
+
+  test("unknown condition key throws an error", async () => {
+    expect(
+      evaluateConditions({ bogus_condition: true }, ctx(), {}),
+    ).rejects.toThrow('Unknown condition: "bogus_condition"');
+  });
+
+  test("single condition evaluated against registry", async () => {
+    const registry: ConditionRegistry = {
+      is_tuesday: () => true,
+    };
+
+    expect(
+      await evaluateConditions({ is_tuesday: null }, ctx(), registry),
+    ).toBe(true);
+  });
+
+  test("condition returning false rejects the grant", async () => {
+    const registry: ConditionRegistry = {
+      always_fail: () => false,
+    };
+
+    expect(
+      await evaluateConditions({ always_fail: null }, ctx(), registry),
+    ).toBe(false);
+  });
+
+  test("all conditions must pass (AND semantics)", async () => {
+    const registry: ConditionRegistry = {
+      cond_a: () => true,
+      cond_b: () => true,
+      cond_c: () => false,
+    };
+
+    expect(
+      await evaluateConditions(
+        { cond_a: null, cond_b: null, cond_c: null },
+        ctx(),
+        registry,
+      ),
+    ).toBe(false);
+  });
+
+  test("all conditions passing returns true", async () => {
+    const registry: ConditionRegistry = {
+      cond_a: () => true,
+      cond_b: () => true,
+    };
+
+    expect(
+      await evaluateConditions({ cond_a: null, cond_b: null }, ctx(), registry),
+    ).toBe(true);
+  });
+
+  test("evaluator receives the condition value", async () => {
+    let receivedValue: unknown;
+    const registry: ConditionRegistry = {
+      threshold: (value) => {
+        receivedValue = value;
+        return true;
+      },
+    };
+
+    await evaluateConditions({ threshold: 42 }, ctx(), registry);
+
+    expect(receivedValue).toBe(42);
+  });
+
+  test("evaluator receives the full context", async () => {
+    let receivedCtx: ConditionContext | undefined;
+    const registry: ConditionRegistry = {
+      spy: (_value, c) => {
+        receivedCtx = c;
+        return true;
+      },
+    };
+
+    const c = ctx({ principalId: "prn_spy", tenantId: "tnt_spy" });
+    await evaluateConditions({ spy: null }, c, registry);
+
+    expect(receivedCtx?.principalId).toBe("prn_spy");
+    expect(receivedCtx?.tenantId).toBe("tnt_spy");
+    expect(receivedCtx?.resource).toBe("agent:agt_abc");
+    expect(receivedCtx?.action).toBe("read");
+  });
+
+  test("async evaluators are supported", async () => {
+    const registry: ConditionRegistry = {
+      async_check: async () => {
+        await new Promise((r) => setTimeout(r, 1));
+        return true;
+      },
+    };
+
+    expect(
+      await evaluateConditions({ async_check: null }, ctx(), registry),
+    ).toBe(true);
+  });
+
+  test("async evaluator returning false rejects", async () => {
+    const registry: ConditionRegistry = {
+      async_fail: async () => {
+        await new Promise((r) => setTimeout(r, 1));
+        return false;
+      },
+    };
+
+    expect(
+      await evaluateConditions({ async_fail: null }, ctx(), registry),
+    ).toBe(false);
+  });
+
+  test("short-circuits on first failing condition", async () => {
+    let secondCalled = false;
+    const registry: ConditionRegistry = {
+      first: () => false,
+      second: () => {
+        secondCalled = true;
+        return true;
+      },
+    };
+
+    await evaluateConditions({ first: null, second: null }, ctx(), registry);
+
+    expect(secondCalled).toBe(false);
+  });
+
+  test("no registry provided with non-null conditions throws", async () => {
+    // No registry argument at all -- defaults to empty registry
+    expect(evaluateConditions({ some_condition: true }, ctx())).rejects.toThrow(
+      'Unknown condition: "some_condition"',
+    );
+  });
+});

package/src/conditions.ts

@@ -0,0 +1,36 @@
+import type { ConditionContext, ConditionRegistry } from "./types";
+
+/**
+ * Evaluate whether a grant's conditions are satisfied.
+ *
+ * Each key in the conditions object is looked up in the registry.
+ * All conditions must be met for the grant to apply. If any
+ * condition key has no registered evaluator, an error is thrown
+ * to surface misconfiguration immediately.
+ *
+ * Null or empty conditions are always met.
+ */
+export async function evaluateConditions(
+  conditions: Record<string, unknown> | null,
+  ctx: ConditionContext,
+  registry: ConditionRegistry = {},
+): Promise<boolean> {
+  if (!conditions) return true;
+
+  const keys = Object.keys(conditions);
+  if (keys.length === 0) return true;
+
+  for (const key of keys) {
+    const evaluator = registry[key];
+    if (!evaluator) {
+      throw new Error(
+        `Unknown condition: "${key}". Register an evaluator in the condition registry.`,
+      );
+    }
+
+    const result = await evaluator(conditions[key], ctx);
+    if (!result) return false;
+  }
+
+  return true;
+}