@intx/authz 0.1.2

package/src/evaluate.ts

@@ -0,0 +1,122 @@
+import type {
+  AuthzResult,
+  ConditionRegistry,
+  Effect,
+  GrantRule,
+  GrantStore,
+  MatchedGrant,
+} from "./types";
+import { matchPattern } from "./patterns";
+import { grantSpecificity } from "./specificity";
+import { evaluateConditions } from "./conditions";
+
+const EFFECT_PRIORITY: Record<Effect, number> = {
+  allow: 0,
+  ask: 1,
+  deny: 2,
+};
+
+export type EvalOptions = {
+  registry?: ConditionRegistry;
+  principalId?: string;
+  tenantId?: string;
+};
+
+/**
+ * Evaluate grants against a resource/action query.
+ *
+ * This is the core evaluation logic, separated from grant collection
+ * so it can be tested with synthetic grant lists.
+ *
+ * When a condition registry is provided, grants with non-null
+ * conditions are evaluated against it. Unknown condition keys
+ * cause an error. When no registry is provided, grants with
+ * non-null conditions are skipped (fail-closed).
+ */
+export async function evaluateGrants(
+  grants: GrantRule[],
+  resource: string,
+  action: string,
+  opts?: EvalOptions,
+): Promise<AuthzResult> {
+  const now = new Date();
+  const registry = opts?.registry;
+  const ctx = {
+    now,
+    resource,
+    action,
+    principalId: opts?.principalId ?? "",
+    tenantId: opts?.tenantId ?? "",
+  };
+
+  const matching: MatchedGrant[] = [];
+
+  for (const g of grants) {
+    if (g.expiresAt !== null && g.expiresAt < now) continue;
+    if (!matchPattern(g.resource, resource)) continue;
+    if (!matchPattern(g.action, action)) continue;
+
+    if (g.conditions && Object.keys(g.conditions).length > 0) {
+      if (!registry) continue;
+      if (!(await evaluateConditions(g.conditions, ctx, registry))) continue;
+    }
+
+    matching.push({
+      id: g.id,
+      resource: g.resource,
+      action: g.action,
+      effect: g.effect,
+      origin: g.origin,
+      specificity: grantSpecificity(g.resource, g.action),
+    });
+  }
+
+  if (matching.length === 0) {
+    return { effect: null, matchingGrants: [], resolvedBy: null };
+  }
+
+  // Sort ascending by specificity, then by effect priority.
+  // Last element wins -- which is the most specific, and at equal
+  // specificity the strongest effect (deny > ask > allow).
+  matching.sort((a, b) => {
+    const specDiff = a.specificity - b.specificity;
+    if (specDiff !== 0) return specDiff;
+    return (EFFECT_PRIORITY[a.effect] ?? 0) - (EFFECT_PRIORITY[b.effect] ?? 0);
+  });
+
+  const resolvedBy = matching[matching.length - 1];
+  if (!resolvedBy) {
+    return { effect: null, matchingGrants: [], resolvedBy: null };
+  }
+
+  return {
+    effect: resolvedBy.effect,
+    matchingGrants: matching,
+    resolvedBy,
+  };
+}
+
+/**
+ * Authorize a principal for a resource/action within a tenant.
+ *
+ * Collects all relevant grants via the provided store, matches them
+ * against the requested resource and action, and returns the resolved
+ * effect.
+ *
+ * Returns null when no grants match (fail-closed). The caller
+ * interprets the result in context: HTTP routes return 403, the
+ * agent runtime blocks the tool call.
+ */
+export async function authorize(
+  store: GrantStore,
+  principalId: string,
+  tenantId: string,
+  resource: string,
+  action: string,
+  registry?: ConditionRegistry,
+): Promise<AuthzResult> {
+  const grants = await store.collectGrants(principalId, tenantId);
+  const opts: EvalOptions = { principalId, tenantId };
+  if (registry) opts.registry = registry;
+  return evaluateGrants(grants, resource, action, opts);
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { authorize, evaluateGrants } from "./evaluate";
+export { matchPattern } from "./patterns";
+export { patternSpecificity, grantSpecificity } from "./specificity";
+export { evaluateConditions } from "./conditions";
+export { timeWindowEvaluator } from "./time-window";
+export { createInMemoryGrantStore } from "./memory-store";
+export type {
+  AuthzResult,
+  ConditionContext,
+  ConditionEvaluator,
+  ConditionRegistry,
+  Effect,
+  GrantRule,
+  GrantStore,
+  MatchedGrant,
+} from "./types";

package/src/memory-store.test.ts

@@ -0,0 +1,93 @@
+import { describe, test, expect } from "bun:test";
+
+import { createInMemoryGrantStore } from "./memory-store";
+import type { GrantRule } from "./types";
+
+function makeGrant(overrides: Partial<GrantRule> = {}): GrantRule {
+  return {
+    id: "grant-1",
+    resource: "tool:bash",
+    action: "invoke",
+    effect: "allow",
+    origin: "creator",
+    conditions: null,
+    expiresAt: null,
+    roleId: null,
+    principalId: "p-1",
+    ...overrides,
+  };
+}
+
+describe("createInMemoryGrantStore", () => {
+  test("returns grants matching the principalId", async () => {
+    const store = createInMemoryGrantStore([
+      makeGrant({ id: "g1", principalId: "p-1" }),
+      makeGrant({ id: "g2", principalId: "p-2" }),
+    ]);
+
+    const results = await store.collectGrants("p-1", "t-1");
+    expect(results.length).toBe(1);
+    const first = results[0];
+    if (first === undefined) throw new Error("expected a grant");
+    expect(first.id).toBe("g1");
+  });
+
+  test("returns empty array when no grants match", async () => {
+    const store = createInMemoryGrantStore([
+      makeGrant({ principalId: "p-other" }),
+    ]);
+
+    const results = await store.collectGrants("p-1", "t-1");
+    expect(results.length).toBe(0);
+  });
+
+  test("filters out expired grants", async () => {
+    const past = new Date(Date.now() - 60_000);
+    const store = createInMemoryGrantStore([
+      makeGrant({ id: "expired", principalId: "p-1", expiresAt: past }),
+      makeGrant({ id: "valid", principalId: "p-1" }),
+    ]);
+
+    const results = await store.collectGrants("p-1", "t-1");
+    expect(results.length).toBe(1);
+    const first = results[0];
+    if (first === undefined) throw new Error("expected a grant");
+    expect(first.id).toBe("valid");
+  });
+
+  test("includes grants with future expiry", async () => {
+    const future = new Date(Date.now() + 60_000);
+    const store = createInMemoryGrantStore([
+      makeGrant({ principalId: "p-1", expiresAt: future }),
+    ]);
+
+    const results = await store.collectGrants("p-1", "t-1");
+    expect(results.length).toBe(1);
+  });
+
+  test("tenantId does not affect filtering", async () => {
+    const store = createInMemoryGrantStore([makeGrant({ principalId: "p-1" })]);
+
+    const a = await store.collectGrants("p-1", "tenant-a");
+    const b = await store.collectGrants("p-1", "tenant-b");
+    expect(a.length).toBe(1);
+    expect(b.length).toBe(1);
+  });
+
+  test("returns multiple matching grants", async () => {
+    const store = createInMemoryGrantStore([
+      makeGrant({ id: "g1", principalId: "p-1", resource: "tool:bash" }),
+      makeGrant({ id: "g2", principalId: "p-1", resource: "tool:curl" }),
+      makeGrant({ id: "g3", principalId: "p-1", resource: "tool:node" }),
+    ]);
+
+    const results = await store.collectGrants("p-1", "t-1");
+    expect(results.length).toBe(3);
+  });
+
+  test("empty store returns empty array", async () => {
+    const store = createInMemoryGrantStore([]);
+    const results = await store.collectGrants("p-1", "t-1");
+    expect(results.length).toBe(0);
+  });
+});

package/src/memory-store.ts

@@ -0,0 +1,28 @@
+// In-memory grant store for testing and local demos.
+//
+// The caller provides a pre-scoped array of grants. The store filters by
+// principalId on each collectGrants call, matching the DB store's behavior.
+//
+// Limitations vs. the DB store:
+//   - tenantId is accepted by the interface but is a no-op here. The caller
+//     scopes grants to the correct tenant when constructing the store.
+//   - Role-based grants (principalId: null, roleId set) are not resolved.
+//     The DB store performs a principalRole join to find role memberships;
+//     this store has no role data. Grants with principalId: null are never
+//     returned. If you need role-based grants in tests, set principalId
+//     directly on each grant.
+
+import type { GrantRule, GrantStore } from "./types";
+
+export function createInMemoryGrantStore(grants: GrantRule[]): GrantStore {
+  return {
+    async collectGrants(principalId: string): Promise<GrantRule[]> {
+      const now = new Date();
+      return grants.filter((g) => {
+        if (g.principalId !== principalId) return false;
+        if (g.expiresAt !== null && g.expiresAt <= now) return false;
+        return true;
+      });
+    },
+  };
+}

package/src/patterns.test.ts

@@ -0,0 +1,89 @@
+import { describe, test, expect } from "bun:test";
+
+import { matchPattern } from "./patterns";
+
+describe("matchPattern", () => {
+  test("bare wildcard matches anything", () => {
+    expect(matchPattern("*", "agent:agt_abc")).toBe(true);
+    expect(matchPattern("*", "")).toBe(true);
+    expect(matchPattern("*", "anything")).toBe(true);
+  });
+
+  test("exact match", () => {
+    expect(matchPattern("agent:agt_abc", "agent:agt_abc")).toBe(true);
+    expect(matchPattern("agent:agt_abc", "agent:agt_xyz")).toBe(false);
+    expect(matchPattern("read", "read")).toBe(true);
+    expect(matchPattern("read", "write")).toBe(false);
+  });
+
+  test("type-level wildcard matches any identifier", () => {
+    expect(matchPattern("agent:*", "agent:agt_abc")).toBe(true);
+    expect(matchPattern("agent:*", "agent:agt_xyz")).toBe(true);
+    expect(matchPattern("agent:*", "wallet:wal_123")).toBe(false);
+  });
+
+  test("prefix wildcard", () => {
+    expect(matchPattern("wallet:wal_*", "wallet:wal_123")).toBe(true);
+    expect(matchPattern("wallet:wal_*", "wallet:xyz")).toBe(false);
+  });
+
+  test("no wildcard requires exact match", () => {
+    expect(matchPattern("agent:agt_abc", "agent:agt_abc")).toBe(true);
+    expect(matchPattern("documents", "documents:doc_1")).toBe(false);
+  });
+
+  test("wildcard at start", () => {
+    expect(matchPattern("*:read", "agent:read")).toBe(true);
+    expect(matchPattern("*:read", "wallet:read")).toBe(true);
+    expect(matchPattern("*:read", "agent:write")).toBe(false);
+  });
+
+  test("multiple wildcards", () => {
+    expect(matchPattern("*:*", "agent:agt_abc")).toBe(true);
+    expect(matchPattern("a*b*c", "abc")).toBe(true);
+    expect(matchPattern("a*b*c", "aXXbYYc")).toBe(true);
+    expect(matchPattern("a*b*c", "aXXbYY")).toBe(false);
+  });
+
+  test("pattern with no wildcards and different lengths", () => {
+    expect(matchPattern("ab", "abc")).toBe(false);
+    expect(matchPattern("abc", "ab")).toBe(false);
+  });
+
+  test("empty string pattern against empty string target", () => {
+    expect(matchPattern("", "")).toBe(true);
+  });
+
+  test("empty string pattern does not match non-empty target", () => {
+    expect(matchPattern("", "agent:agt_abc")).toBe(false);
+  });
+
+  test("consecutive wildcards behave like a single wildcard", () => {
+    expect(matchPattern("a**b", "aXb")).toBe(true);
+    expect(matchPattern("a**b", "ab")).toBe(true);
+    expect(matchPattern("***", "anything")).toBe(true);
+  });
+
+  test("nested colon resource patterns (api:stripe:*)", () => {
+    expect(matchPattern("api:stripe:*", "api:stripe:charges")).toBe(true);
+    expect(matchPattern("api:stripe:*", "api:stripe:refunds")).toBe(true);
+    expect(matchPattern("api:stripe:*", "api:plaid:accounts")).toBe(false);
+    expect(matchPattern("api:*", "api:stripe:charges")).toBe(true);
+  });
+
+  test("trailing wildcard matches zero characters", () => {
+    expect(matchPattern("abc*", "abc")).toBe(true);
+    expect(matchPattern("agent:*", "agent:")).toBe(true);
+  });
+
+  test("patterns are case-sensitive", () => {
+    expect(matchPattern("Agent:*", "agent:agt_abc")).toBe(false);
+    expect(matchPattern("agent:*", "Agent:agt_abc")).toBe(false);
+    expect(matchPattern("READ", "read")).toBe(false);
+  });
+
+  test("wildcard-only variants", () => {
+    expect(matchPattern("**", "anything")).toBe(true);
+    expect(matchPattern("**", "")).toBe(true);
+  });
+});

package/src/patterns.ts

@@ -0,0 +1,42 @@
+/**
+ * Match a target string against a glob pattern.
+ *
+ * Supports `*` as a wildcard that matches any sequence of characters.
+ * No other glob syntax is supported (no `?`, `**`, or character classes).
+ *
+ * Examples:
+ *   matchPattern("*", "agent:agt_abc")          => true
+ *   matchPattern("agent:*", "agent:agt_abc")    => true
+ *   matchPattern("agent:agt_abc", "agent:agt_abc") => true
+ *   matchPattern("agent:agt_abc", "agent:agt_xyz") => false
+ *   matchPattern("wallet:wal_*", "wallet:wal_123") => true
+ *   matchPattern("wallet:wal_*", "wallet:xyz")     => false
+ */
+export function matchPattern(pattern: string, target: string): boolean {
+  if (pattern === "*") return true;
+  if (pattern === target) return true;
+
+  if (!pattern.includes("*")) return false;
+
+  const parts = pattern.split("*");
+  let pos = 0;
+
+  for (let i = 0; i < parts.length; i++) {
+    const segment = parts[i] ?? "";
+    if (segment.length === 0) continue;
+
+    const idx = target.indexOf(segment, pos);
+    if (idx === -1) return false;
+
+    // First segment must anchor to the start
+    if (i === 0 && idx !== 0) return false;
+
+    pos = idx + segment.length;
+  }
+
+  // Last segment must anchor to the end
+  const lastSegment = parts[parts.length - 1] ?? "";
+  if (lastSegment.length > 0 && !target.endsWith(lastSegment)) return false;
+
+  return true;
+}

package/src/specificity.test.ts

@@ -0,0 +1,91 @@
+import { describe, test, expect } from "bun:test";
+
+import { patternSpecificity, grantSpecificity } from "./specificity";
+
+describe("patternSpecificity", () => {
+  test("bare wildcard has zero specificity", () => {
+    expect(patternSpecificity("*")).toBe(0);
+  });
+
+  test("type-level wildcard scores by literal length", () => {
+    // "agent:" has 6 literal chars
+    expect(patternSpecificity("agent:*")).toBe(6);
+  });
+
+  test("prefix wildcard scores by literal length", () => {
+    // "wallet:wal_" has 11 literal chars
+    expect(patternSpecificity("wallet:wal_*")).toBe(11);
+  });
+
+  test("exact match gets bonus of 1000", () => {
+    // "agent:agt_abc" has 13 chars + 1000 bonus
+    expect(patternSpecificity("agent:agt_abc")).toBe(1013);
+  });
+
+  test("more specific patterns score higher", () => {
+    const scores = [
+      patternSpecificity("*"),
+      patternSpecificity("agent:*"),
+      patternSpecificity("agent:agt_*"),
+      patternSpecificity("agent:agt_abc"),
+    ];
+
+    for (let i = 1; i < scores.length; i++) {
+      const prev = scores[i - 1] ?? 0;
+      expect(scores[i]).toBeGreaterThan(prev);
+    }
+  });
+
+  test("action patterns follow same rules", () => {
+    expect(patternSpecificity("*")).toBe(0);
+    expect(patternSpecificity("read")).toBe(1004); // 4 chars + 1000
+    expect(patternSpecificity("manage")).toBe(1006); // 6 chars + 1000
+  });
+});
+
+describe("grantSpecificity", () => {
+  test("combines resource and action specificity", () => {
+    expect(grantSpecificity("*", "*")).toBe(0);
+    expect(grantSpecificity("agent:*", "read")).toBe(6 + 1004);
+    expect(grantSpecificity("agent:agt_abc", "manage")).toBe(1013 + 1006);
+  });
+
+  test("more specific grant beats less specific", () => {
+    // Wildcard everything
+    const s1 = grantSpecificity("*", "*");
+    // Type-level wildcard with specific action
+    const s2 = grantSpecificity("agent:*", "read");
+    // Exact resource and action
+    const s3 = grantSpecificity("agent:agt_abc", "manage");
+
+    expect(s2).toBeGreaterThan(s1);
+    expect(s3).toBeGreaterThan(s2);
+  });
+});
+
+describe("patternSpecificity edge cases", () => {
+  test("empty string gets exact match bonus", () => {
+    // Empty string has no wildcard, so it gets the 1000 bonus + 0 literal chars
+    expect(patternSpecificity("")).toBe(1000);
+  });
+
+  test("multi-wildcard pattern scores only literal characters", () => {
+    // "*:*" has 1 literal char (':') and contains wildcards
+    expect(patternSpecificity("*:*")).toBe(1);
+  });
+
+  test("nested colon pattern scores all literal characters", () => {
+    // "api:stripe:*" has 11 literal chars ("api:stripe:") and contains a wildcard
+    expect(patternSpecificity("api:stripe:*")).toBe(11);
+    // "api:stripe:charges" has 18 chars and no wildcard -> 18 + 1000
+    expect(patternSpecificity("api:stripe:charges")).toBe(1018);
+  });
+
+  test("specificity is character-count based, not segment-aware", () => {
+    // Two patterns with same literal length but different structure
+    // score identically, proving specificity is purely character-based
+    const a = patternSpecificity("abcdef:*"); // 7 literal chars
+    const b = patternSpecificity("ab:cd:e*"); // 7 literal chars
+    expect(a).toBe(b);
+  });
+});

package/src/specificity.ts

@@ -0,0 +1,29 @@
+/**
+ * Compute a specificity score for a pattern.
+ *
+ * More specific patterns get higher scores:
+ *   "*"              => 0  (matches everything)
+ *   "agent:*"        => 6  (type-level wildcard, 6 literal chars)
+ *   "wallet:wal_*"   => 11 (prefix match, 11 literal chars)
+ *   "agent:agt_abc"  => 13 (exact match, 13 literal chars, no wildcards)
+ *
+ * The score is the count of non-wildcard characters, plus a bonus
+ * for patterns with no wildcards at all (exact matches).
+ */
+export function patternSpecificity(pattern: string): number {
+  if (pattern === "*") return 0;
+
+  const literalLength = pattern.replace(/\*/g, "").length;
+  const hasWildcard = pattern.includes("*");
+
+  // Exact matches get a bonus to ensure they always beat prefix globs
+  // of similar length
+  return hasWildcard ? literalLength : literalLength + 1000;
+}
+
+/**
+ * Combined specificity of a resource + action pair.
+ */
+export function grantSpecificity(resource: string, action: string): number {
+  return patternSpecificity(resource) + patternSpecificity(action);
+}