Design an authorisation engine (RBAC + ABAC)

export type Effect = "allow" | "deny";

export interface Subject { id: string; tenantId: string; roles: readonly string[]; attrs: Readonly<Record<string, unknown>> }
export interface Resource { type: string; id: string; tenantId: string; attrs: Readonly<Record<string, unknown>> }
export interface Environment { now: Date; ip?: string; attrs: Readonly<Record<string, unknown>> }

export interface Request { subject: Subject; action: string; resource: Resource; env: Environment }

export interface Condition { evaluate(req: Request): boolean; describe(): string }

export interface Policy {
  id: string;
  effect: Effect;
  roles: readonly string[];          // any of; "*" = everyone
  actions: readonly string[];        // "lesson:read", "lesson:*"
  resourceTypes: readonly string[];  // "lesson", "*"
  conditions: readonly Condition[];  // all must hold
}

export interface Decision { effect: Effect; matched: readonly string[]; reason: string }

export interface AuthorizationEngine {
  isAllowed(req: Request): Decision;
}

export interface DecisionListener { onDecision(req: Request, d: Decision): void }

export class PolicyEngine implements AuthorizationEngine {
  private policies: readonly Policy[];
  constructor(policies: readonly Policy[], private readonly listeners: readonly DecisionListener[] = []) {
    this.policies = Object.freeze([...policies]);
  }

  /** Atomic replacement: callers holding the old engine keep a consistent snapshot. */
  withPolicies(policies: readonly Policy[]): PolicyEngine {
    return new PolicyEngine(policies, this.listeners);
  }

  isAllowed(req: Request): Decision {
    const d = this.evaluate(req);
    for (const l of this.listeners) l.onDecision(req, d);
    return d;
  }

  private evaluate(req: Request): Decision {
    if (req.subject.tenantId !== req.resource.tenantId) {
      return { effect: "deny", matched: [], reason: "cross-tenant access" };
    }
    const matched = this.policies.filter((p) => this.applies(p, req));
    const denies = matched.filter((p) => p.effect === "deny");
    if (denies.length) return { effect: "deny", matched: denies.map((p) => p.id), reason: "explicit deny" };
    const allows = matched.filter((p) => p.effect === "allow");
    if (allows.length) return { effect: "allow", matched: allows.map((p) => p.id), reason: "allowed by policy" };
    return { effect: "deny", matched: [], reason: "no matching policy" };
  }

  private applies(p: Policy, req: Request): boolean {
    return (
      matchesAny(p.roles, req.subject.roles) &&
      matchesPattern(p.actions, req.action) &&
      matchesPattern(p.resourceTypes, req.resource.type) &&
      p.conditions.every((c) => c.evaluate(req))
    );
  }
}

const matchesAny = (allowed: readonly string[], have: readonly string[]) =>
  allowed.includes("*") || have.some((r) => allowed.includes(r));

const matchesPattern = (patterns: readonly string[], value: string) =>
  patterns.some((pat) => pat === "*" || pat === value || (pat.endsWith(":*") && value.startsWith(pat.slice(0, -1))));

export class OwnerCondition implements Condition {
  evaluate(r: Request) { return r.resource.attrs["ownerId"] === r.subject.id; }
  describe() { return "resource.ownerId == subject.id"; }
}

export class TimeWindowCondition implements Condition {
  constructor(private readonly startHour: number, private readonly endHour: number) {}
  evaluate(r: Request) { const h = r.env.now.getUTCHours(); return h >= this.startHour && h < this.endHour; }
  describe() { return `utc hour in [${this.startHour}, ${this.endHour})`; }
}

export class AttrInCondition implements Condition {
  constructor(private readonly path: "subject" | "resource", private readonly key: string, private readonly values: readonly unknown[]) {}
  evaluate(r: Request) { return this.values.includes(r[this.path].attrs[this.key]); }
  describe() { return `${this.path}.${this.key} in [${this.values.join(", ")}]`; }
}

import { describe, it, expect } from "vitest";

const base = (over: Partial<Request> = {}): Request => ({
  subject: { id: "u1", tenantId: "t1", roles: ["learner"], attrs: {} },
  action: "lesson:read",
  resource: { type: "lesson", id: "l1", tenantId: "t1", attrs: { ownerId: "u9" } },
  env: { now: new Date("2026-11-13T10:00:00Z"), attrs: {} },
  ...over,
});

describe("PolicyEngine", () => {
  it("denies by default", () => {
    expect(new PolicyEngine([]).isAllowed(base()).effect).toBe("deny");
  });
  it("allows a role with a matching policy", () => {
    const e = new PolicyEngine([{ id: "p1", effect: "allow", roles: ["learner"], actions: ["lesson:read"], resourceTypes: ["lesson"], conditions: [] }]);
    expect(e.isAllowed(base()).effect).toBe("allow");
  });
  it("explicit deny overrides allow", () => {
    const e = new PolicyEngine([
      { id: "p1", effect: "allow", roles: ["*"], actions: ["*"], resourceTypes: ["*"], conditions: [] },
      { id: "d1", effect: "deny", roles: ["learner"], actions: ["lesson:*"], resourceTypes: ["lesson"], conditions: [] },
    ]);
    const d = e.isAllowed(base());
    expect(d.effect).toBe("deny");
    expect(d.matched).toEqual(["d1"]);
  });
  it("never crosses tenants, even with a wildcard allow", () => {
    const e = new PolicyEngine([{ id: "p1", effect: "allow", roles: ["*"], actions: ["*"], resourceTypes: ["*"], conditions: [] }]);
    const d = e.isAllowed(base({ resource: { type: "lesson", id: "l2", tenantId: "t2", attrs: {} } }));
    expect(d.effect).toBe("deny");
    expect(d.reason).toBe("cross-tenant access");
  });
  it("conditions gate the allow", () => {
    const e = new PolicyEngine([{ id: "own", effect: "allow", roles: ["learner"], actions: ["lesson:edit"], resourceTypes: ["lesson"], conditions: [new OwnerCondition()] }]);
    expect(e.isAllowed(base({ action: "lesson:edit" })).effect).toBe("deny");
    expect(e.isAllowed(base({ action: "lesson:edit", resource: { type: "lesson", id: "l1", tenantId: "t1", attrs: { ownerId: "u1" } } })).effect).toBe("allow");
  });
});