toride 0.0.1 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,309 @@
+import { P as Policy, T as TorideSchema, D as DefaultSchema, a as TorideOptions, A as ActorRef, R as ResourceRef, C as CheckOptions, E as ExplainResult, b as PermissionSnapshot, B as BatchCheckItem, c as TestCase, d as Resolvers } from './client-RqwW0K_-.js';
+export { e as ActorDeclaration, f as AttributeType, g as ClientResourceRef, h as ConditionExpression, i as ConditionOperator, j as ConditionValue, k as CycleError, l as DecisionEvent, m as DepthLimitError, n as DerivedRoleEntry, o as DerivedRoleTrace, p as EvaluatorFn, F as FieldAccessDef, G as GlobalRole, M as MatchedRule, Q as QueryEvent, q as ResolvedRolesDetail, r as ResourceBlock, s as ResourceResolver, t as Rule, S as SimpleConditions, u as TorideClient, V as ValidationError } from './client-RqwW0K_-.js';
+
+/**
+ * Parse and validate a YAML string into a typed Policy object.
+ * Uses the `yaml` package with pretty errors.
+ */
+declare function loadYaml(input: string): Promise<Policy>;
+/**
+ * Parse and validate a JSON string into a typed Policy object.
+ */
+declare function loadJson(input: string): Promise<Policy>;
+
+/**
+ * Merge two policies into one.
+ *
+ * - Actors: additive union of actor types and their attributes
+ * - Global roles: additive union (overlay wins on conflict)
+ * - Resources: additive union of resource types; overlapping resources merge
+ *   roles, permissions, relations, derived_roles, rules, and field_access
+ * - Grants: throws on conflicting grants (same role, different permission sets)
+ * - Rules: silently appended
+ * - Tests: dropped (not merged)
+ */
+declare function mergePolicies(base: Policy, overlay: Policy): Policy;
+
+/** A single validation diagnostic (error or warning). */
+interface ValidationDiagnostic {
+    readonly message: string;
+    readonly path: string;
+}
+/** Result from non-throwing validation. */
+interface ValidationResult {
+    readonly errors: ValidationDiagnostic[];
+}
+/** Result from strict validation (errors + warnings). */
+interface StrictValidationResult {
+    readonly errors: ValidationDiagnostic[];
+    readonly warnings: ValidationDiagnostic[];
+}
+/**
+ * Validate cross-references in a structurally valid policy.
+ * Collects ALL errors and throws ValidationError with all messages.
+ * Backward compatible: always throws on first error set.
+ */
+declare function validatePolicy(policy: Policy): void;
+/**
+ * Non-throwing validation: returns all errors as an array.
+ * Used by CLI and programmatic consumers that want to collect errors.
+ */
+declare function validatePolicyResult(policy: Policy): ValidationResult;
+/**
+ * Strict validation: returns errors + static analysis warnings.
+ * Errors are the same as validatePolicy().
+ * Warnings include unused roles, unreachable rules, redundant derivations.
+ */
+declare function validatePolicyStrict(policy: Policy): StrictValidationResult;
+
+interface FieldEqConstraint {
+    readonly type: "field_eq";
+    readonly field: string;
+    readonly value: unknown;
+}
+interface FieldNeqConstraint {
+    readonly type: "field_neq";
+    readonly field: string;
+    readonly value: unknown;
+}
+interface FieldGtConstraint {
+    readonly type: "field_gt";
+    readonly field: string;
+    readonly value: unknown;
+}
+interface FieldGteConstraint {
+    readonly type: "field_gte";
+    readonly field: string;
+    readonly value: unknown;
+}
+interface FieldLtConstraint {
+    readonly type: "field_lt";
+    readonly field: string;
+    readonly value: unknown;
+}
+interface FieldLteConstraint {
+    readonly type: "field_lte";
+    readonly field: string;
+    readonly value: unknown;
+}
+interface FieldInConstraint {
+    readonly type: "field_in";
+    readonly field: string;
+    readonly values: unknown[];
+}
+interface FieldNinConstraint {
+    readonly type: "field_nin";
+    readonly field: string;
+    readonly values: unknown[];
+}
+interface FieldExistsConstraint {
+    readonly type: "field_exists";
+    readonly field: string;
+    readonly exists: boolean;
+}
+interface FieldIncludesConstraint {
+    readonly type: "field_includes";
+    readonly field: string;
+    readonly value: unknown;
+}
+interface FieldContainsConstraint {
+    readonly type: "field_contains";
+    readonly field: string;
+    readonly value: string;
+}
+interface RelationConstraint {
+    readonly type: "relation";
+    readonly field: string;
+    readonly resourceType: string;
+    readonly constraint: Constraint;
+}
+interface HasRoleConstraint {
+    readonly type: "has_role";
+    readonly actorId: string;
+    readonly actorType: string;
+    readonly role: string;
+}
+interface UnknownConstraint {
+    readonly type: "unknown";
+    readonly name: string;
+}
+interface AndConstraint {
+    readonly type: "and";
+    readonly children: Constraint[];
+}
+interface OrConstraint {
+    readonly type: "or";
+    readonly children: Constraint[];
+}
+interface NotConstraint {
+    readonly type: "not";
+    readonly child: Constraint;
+}
+interface AlwaysConstraint {
+    readonly type: "always";
+}
+interface NeverConstraint {
+    readonly type: "never";
+}
+/** Full constraint discriminated union (AST node). */
+type Constraint = FieldEqConstraint | FieldNeqConstraint | FieldGtConstraint | FieldGteConstraint | FieldLtConstraint | FieldLteConstraint | FieldInConstraint | FieldNinConstraint | FieldExistsConstraint | FieldIncludesConstraint | FieldContainsConstraint | RelationConstraint | HasRoleConstraint | UnknownConstraint | AndConstraint | OrConstraint | NotConstraint | AlwaysConstraint | NeverConstraint;
+/** Leaf constraint subset for ConstraintAdapter.translate(). */
+type LeafConstraint = FieldEqConstraint | FieldNeqConstraint | FieldGtConstraint | FieldGteConstraint | FieldLtConstraint | FieldLteConstraint | FieldInConstraint | FieldNinConstraint | FieldExistsConstraint | FieldIncludesConstraint | FieldContainsConstraint;
+/** Result of partial evaluation. */
+type ConstraintResult = {
+    readonly unrestricted: true;
+} | {
+    readonly forbidden: true;
+} | {
+    readonly constraints: Constraint;
+};
+/** User-provided adapter for translating constraint ASTs to queries. */
+interface ConstraintAdapter<TQuery> {
+    translate(constraint: LeafConstraint): TQuery;
+    relation(field: string, resourceType: string, childQuery: TQuery): TQuery;
+    hasRole(actorId: string, actorType: string, role: string): TQuery;
+    unknown(name: string): TQuery;
+    and(queries: TQuery[]): TQuery;
+    or(queries: TQuery[]): TQuery;
+    not(query: TQuery): TQuery;
+}
+
+/**
+ * Main authorization engine.
+ * Creates a per-check cache, resolves direct roles, checks grants,
+ * and returns boolean with default-deny semantics.
+ */
+declare class Toride<S extends TorideSchema = DefaultSchema> {
+    private policy;
+    private readonly resolvers;
+    private readonly options;
+    constructor(options: TorideOptions<S>);
+    /**
+     * Check if an actor can perform an action on a resource.
+     * Default-deny: returns false if resource type is unknown or no grants match.
+     */
+    can<R extends S["resources"]>(actor: ActorRef<S>, action: S["permissionMap"][R], resource: ResourceRef<S, R>, options?: CheckOptions): Promise<boolean>;
+    /**
+     * T097: Atomic policy swap. In-flight checks capture the resource block
+     * at the start of evaluateInternal, so they complete with the old policy.
+     * JS single-threaded nature ensures the assignment is atomic.
+     */
+    setPolicy(policy: Policy): void;
+    /**
+     * T068: Return full ExplainResult with role derivation traces,
+     * granted permissions, matched rules, and human-readable final decision.
+     */
+    explain<R extends S["resources"]>(actor: ActorRef<S>, action: S["permissionMap"][R], resource: ResourceRef<S, R>, options?: CheckOptions): Promise<ExplainResult<S, R>>;
+    /**
+     * T069: Check all declared permissions for a resource and return permitted ones.
+     * Uses a shared cache across all per-action evaluations.
+     */
+    permittedActions<R extends S["resources"]>(actor: ActorRef<S>, resource: ResourceRef<S, R>, options?: CheckOptions): Promise<S["permissionMap"][R][]>;
+    /**
+     * T083: Generate a PermissionSnapshot for a list of resources.
+     * Calls permittedActions() for each resource and returns a map
+     * keyed by "Type:id" with arrays of permitted action strings.
+     * Suitable for serializing to the client via TorideClient.
+     */
+    snapshot(actor: ActorRef<S>, resources: ResourceRef<S>[], options?: CheckOptions): Promise<PermissionSnapshot>;
+    /**
+     * T095: Check if an actor can perform a field-level operation on a specific field.
+     * Restricted fields require the actor to have a role listed in field_access.
+     * Unlisted fields are unrestricted: any actor with the resource-level permission can access them.
+     */
+    canField<R extends S["resources"]>(actor: ActorRef<S>, operation: "read" | "update", resource: ResourceRef<S, R>, field: string, options?: CheckOptions): Promise<boolean>;
+    /**
+     * T095: Return the list of declared field_access field names the actor can access
+     * for the given operation. Only returns explicitly declared fields.
+     */
+    permittedFields<R extends S["resources"]>(actor: ActorRef<S>, operation: "read" | "update", resource: ResourceRef<S, R>, options?: CheckOptions): Promise<string[]>;
+    /**
+     * T070: Return flat deduplicated list of all resolved roles (direct + derived).
+     */
+    resolvedRoles<R extends S["resources"]>(actor: ActorRef<S>, resource: ResourceRef<S, R>, options?: CheckOptions): Promise<string[]>;
+    /**
+     * T071: Evaluate multiple checks for the same actor with a shared resolver cache.
+     * Returns boolean[] in the same order as the input checks.
+     */
+    canBatch(actor: ActorRef<S>, checks: BatchCheckItem<S>[], options?: CheckOptions): Promise<boolean[]>;
+    /**
+     * T064: Build constraint AST for partial evaluation / data filtering.
+     * Returns ConstraintResult with unrestricted/forbidden sentinels or constraint AST.
+     */
+    buildConstraints<R extends S["resources"]>(actor: ActorRef<S>, action: S["permissionMap"][R], resourceType: R, options?: CheckOptions): Promise<ConstraintResult>;
+    /**
+     * T064: Translate constraint AST using an adapter.
+     * Dispatches each constraint node to the adapter's methods.
+     */
+    translateConstraints<TQuery>(constraints: Constraint, adapter: ConstraintAdapter<TQuery>): TQuery;
+    /**
+     * T072: Fire onDecision audit callback via microtask (non-blocking).
+     * Errors are silently swallowed to prevent audit failures from affecting authorization.
+     */
+    private fireDecisionEvent;
+    /**
+     * T072: Fire onQuery audit callback via microtask (non-blocking).
+     * Errors are silently swallowed.
+     */
+    private fireQueryEvent;
+    /**
+     * Evaluate with full ExplainResult (shared code path for can(), explain(), and helpers).
+     * Accepts an optional pre-existing AttributeCache for shared-cache scenarios (canBatch, permittedActions).
+     */
+    private evaluateInternal;
+}
+/**
+ * Typed factory function for creating a Toride instance.
+ */
+declare function createToride<S extends TorideSchema = DefaultSchema>(options: TorideOptions<S>): Toride<S>;
+
+/**
+ * Constructs a Resolvers map from test case mock data.
+ * Uses "Type:id" format as keys in the TestCase.resolvers map.
+ * Each entry maps to an attribute object that the mock resolver returns.
+ *
+ * Example TestCase.resolvers:
+ *   { "Document:doc1": { status: "draft", owner_id: "u1" },
+ *     "Organization:org1": { plan: "enterprise" } }
+ *
+ * This produces a Resolvers map where each resource type has a resolver
+ * that looks up the attributes by "Type:id" key.
+ */
+declare function createMockResolver(testCase: TestCase): Resolvers;
+
+/** Result of parsing a separate .test.yaml file. */
+interface TestFileResult {
+    policyPath: string;
+    tests: TestCase[];
+}
+/**
+ * Extract inline tests from a loaded Policy object.
+ * Returns the policy (unchanged) and the test cases (or empty array if none).
+ */
+declare function parseInlineTests(policy: Policy): {
+    policy: Policy;
+    tests: TestCase[];
+};
+/**
+ * Parse a separate .test.yaml file content string.
+ * Returns the path to the policy file and the test cases.
+ */
+declare function parseTestFile(yamlContent: string): TestFileResult;
+
+/** Result of a single test case execution. */
+interface TestResult {
+    name: string;
+    passed: boolean;
+    expected: "allow" | "deny";
+    actual: "allow" | "deny";
+}
+/**
+ * Run a set of test cases against a policy.
+ * Creates a fresh engine per test case for isolation.
+ * Global roles are derived from actor attributes -- never mocked.
+ */
+declare function runTestCases(policy: Policy, tests: TestCase[]): Promise<TestResult[]>;
+
+declare const VERSION = "0.0.1";
+
+export { ActorRef, BatchCheckItem, CheckOptions, type Constraint, type ConstraintAdapter, type ConstraintResult, DefaultSchema, ExplainResult, type LeafConstraint, PermissionSnapshot, Policy, Resolvers, ResourceRef, type StrictValidationResult, TestCase, type TestFileResult, type TestResult, Toride, TorideOptions, TorideSchema, VERSION, type ValidationDiagnostic, type ValidationResult, createMockResolver, createToride, loadJson, loadYaml, mergePolicies, parseInlineTests, parseTestFile, runTestCases, validatePolicy, validatePolicyResult, validatePolicyStrict };

package/dist/index.js

@@ -0,0 +1,246 @@
+import {
+  CycleError,
+  DepthLimitError,
+  PolicySchema,
+  Toride,
+  ValidationError,
+  createMockResolver,
+  createToride,
+  parseInlineTests,
+  parseTestFile,
+  runTestCases,
+  validatePolicy,
+  validatePolicyResult,
+  validatePolicyStrict
+} from "./chunk-24PMDTLE.js";
+import {
+  TorideClient
+} from "./chunk-475CNU63.js";
+
+// src/policy/parser.ts
+import * as YAML from "yaml";
+import * as v from "valibot";
+function detectOldRelationSyntax(raw) {
+  if (typeof raw !== "object" || raw === null) return;
+  const obj = raw;
+  const resources = obj.resources;
+  if (typeof resources !== "object" || resources === null) return;
+  for (const [resName, resDef] of Object.entries(
+    resources
+  )) {
+    if (typeof resDef !== "object" || resDef === null) continue;
+    const relations = resDef.relations;
+    if (typeof relations !== "object" || relations === null) continue;
+    for (const [relName, relDef] of Object.entries(
+      relations
+    )) {
+      if (typeof relDef === "object" && relDef !== null) {
+        const relObj = relDef;
+        if ("resource" in relObj) {
+          const targetType = String(relObj.resource ?? relName);
+          throw new ValidationError(
+            `Relation "${relName}" on resource "${resName}" uses the old object syntax ({ resource: ..., cardinality: ... }). Relations must now be a plain type name. Change to: ${relName}: ${targetType}`,
+            `resources.${resName}.relations.${relName}`
+          );
+        }
+      }
+    }
+  }
+}
+function parsePolicy(raw) {
+  detectOldRelationSyntax(raw);
+  const result = v.safeParse(PolicySchema, raw);
+  if (!result.success) {
+    const issue = result.issues[0];
+    const path = issue?.path?.map((p) => String(p.key)).join(".") ?? "";
+    throw new ValidationError(
+      `Policy validation failed: ${issue?.message ?? "unknown error"}${path ? ` at ${path}` : ""}`,
+      path
+    );
+  }
+  const policy = result.output;
+  validatePolicy(policy);
+  return policy;
+}
+async function loadYaml(input) {
+  let raw;
+  try {
+    raw = YAML.parse(input, { prettyErrors: true });
+  } catch (err) {
+    throw new ValidationError(
+      `YAML parse error: ${err instanceof Error ? err.message : String(err)}`,
+      ""
+    );
+  }
+  return parsePolicy(raw);
+}
+async function loadJson(input) {
+  let raw;
+  try {
+    raw = JSON.parse(input);
+  } catch (err) {
+    throw new ValidationError(
+      `JSON parse error: ${err instanceof Error ? err.message : String(err)}`,
+      ""
+    );
+  }
+  return parsePolicy(raw);
+}
+
+// src/policy/merger.ts
+var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function assertNoDangerousKeys(obj, context) {
+  for (const key of Object.keys(obj)) {
+    if (DANGEROUS_KEYS.has(key)) {
+      throw new Error(`Dangerous key "${key}" detected in ${context}`);
+    }
+  }
+}
+function mergePolicies(base, overlay) {
+  const actors = mergeActors(base.actors, overlay.actors);
+  const global_roles = mergeGlobalRoles(base.global_roles, overlay.global_roles);
+  const resources = mergeResources(base.resources, overlay.resources);
+  const result = {
+    version: "1",
+    actors,
+    resources
+  };
+  if (global_roles && Object.keys(global_roles).length > 0) {
+    result.global_roles = global_roles;
+  }
+  return result;
+}
+function mergeActors(base, overlay) {
+  assertNoDangerousKeys(base, "base actors");
+  assertNoDangerousKeys(overlay, "overlay actors");
+  const result = { ...base };
+  for (const [name, actor] of Object.entries(overlay)) {
+    if (result[name]) {
+      result[name] = {
+        attributes: { ...result[name].attributes, ...actor.attributes }
+      };
+    } else {
+      result[name] = actor;
+    }
+  }
+  return result;
+}
+function mergeGlobalRoles(base, overlay) {
+  if (!base && !overlay) return void 0;
+  if (base) assertNoDangerousKeys(base, "base global_roles");
+  if (overlay) assertNoDangerousKeys(overlay, "overlay global_roles");
+  return { ...base ?? {}, ...overlay ?? {} };
+}
+function mergeResources(base, overlay) {
+  assertNoDangerousKeys(base, "base resources");
+  assertNoDangerousKeys(overlay, "overlay resources");
+  const result = {};
+  for (const [name, block] of Object.entries(base)) {
+    result[name] = block;
+  }
+  for (const [name, overlayBlock] of Object.entries(overlay)) {
+    if (result[name]) {
+      result[name] = mergeResourceBlock(name, result[name], overlayBlock);
+    } else {
+      result[name] = overlayBlock;
+    }
+  }
+  return result;
+}
+function mergeResourceBlock(resourceName, base, overlay) {
+  const roles = unionArrays(base.roles, overlay.roles);
+  const permissions = unionArrays(base.permissions, overlay.permissions);
+  const grants = mergeGrants(resourceName, base.grants, overlay.grants);
+  const relations = mergeRelations(base.relations, overlay.relations);
+  const derived_roles = appendArrays(base.derived_roles, overlay.derived_roles);
+  const rules = appendArrays(base.rules, overlay.rules);
+  const field_access = mergeFieldAccess(base.field_access, overlay.field_access);
+  const result = {
+    roles,
+    permissions,
+    ...grants && Object.keys(grants).length > 0 ? { grants } : {},
+    ...relations && Object.keys(relations).length > 0 ? { relations } : {},
+    ...derived_roles && derived_roles.length > 0 ? { derived_roles } : {},
+    ...rules && rules.length > 0 ? { rules } : {},
+    ...field_access && Object.keys(field_access).length > 0 ? { field_access } : {}
+  };
+  return result;
+}
+function unionArrays(a, b) {
+  return [.../* @__PURE__ */ new Set([...a, ...b])];
+}
+function appendArrays(a, b) {
+  if (!a && !b) return void 0;
+  return [...a ?? [], ...b ?? []];
+}
+function mergeGrants(resourceName, base, overlay) {
+  if (!base && !overlay) return void 0;
+  if (!base) return overlay;
+  if (!overlay) return base;
+  assertNoDangerousKeys(base, "base grants");
+  assertNoDangerousKeys(overlay, "overlay grants");
+  const result = { ...base };
+  for (const [role, perms] of Object.entries(overlay)) {
+    if (result[role]) {
+      const existingSet = new Set(result[role]);
+      const newSet = new Set(perms);
+      if (existingSet.size !== newSet.size || ![...existingSet].every((p) => newSet.has(p))) {
+        throw new Error(
+          `Grant conflict on resource "${resourceName}": role "${role}" has different permission sets. Base: [${result[role].join(", ")}], Overlay: [${perms.join(", ")}]`
+        );
+      }
+    } else {
+      result[role] = perms;
+    }
+  }
+  return result;
+}
+function mergeRelations(base, overlay) {
+  if (!base && !overlay) return void 0;
+  if (base) assertNoDangerousKeys(base, "base relations");
+  if (overlay) assertNoDangerousKeys(overlay, "overlay relations");
+  return { ...base ?? {}, ...overlay ?? {} };
+}
+function mergeFieldAccess(base, overlay) {
+  if (!base && !overlay) return void 0;
+  if (!base) return overlay;
+  if (!overlay) return base;
+  assertNoDangerousKeys(base, "base field_access");
+  assertNoDangerousKeys(overlay, "overlay field_access");
+  const result = { ...base };
+  for (const [field, def] of Object.entries(overlay)) {
+    if (result[field]) {
+      const mergedRead = unionArrays(result[field].read ?? [], def.read ?? []);
+      const mergedUpdate = unionArrays(result[field].update ?? [], def.update ?? []);
+      const merged = {};
+      if (mergedRead.length > 0) merged.read = mergedRead;
+      if (mergedUpdate.length > 0) merged.update = mergedUpdate;
+      result[field] = merged;
+    } else {
+      result[field] = def;
+    }
+  }
+  return result;
+}
+
+// src/index.ts
+var VERSION = "0.0.1";
+export {
+  CycleError,
+  DepthLimitError,
+  Toride,
+  TorideClient,
+  VERSION,
+  ValidationError,
+  createMockResolver,
+  createToride,
+  loadJson,
+  loadYaml,
+  mergePolicies,
+  parseInlineTests,
+  parseTestFile,
+  runTestCases,
+  validatePolicy,
+  validatePolicyResult,
+  validatePolicyStrict
+};

package/package.json

@@ -1,12 +1,55 @@
 {
   "name": "toride",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Relation-aware authorization engine for TypeScript",
-  "main": "index.js",
-  "keywords": ["authorization", "rbac", "rebac", "abac", "permissions"],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "toride": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "nx": {
+    "tags": [
+      "type:core"
+    ]
+  },
+  "dependencies": {
+    "valibot": "^1.2.0",
+    "yaml": "^2.3.0"
+  },
+  "keywords": [
+    "authorization",
+    "rbac",
+    "rebac",
+    "abac",
+    "permissions"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/toride-auth/toride"
+  },
+  "devDependencies": {
+    "tsd": "^0.33.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typetest": "tsd --files 'src/__typetests__/*.test-d.ts'",
+    "lint": "tsc --noEmit",
+    "bench": "vitest bench"
   }
-}
+}

package/index.js

@@ -1 +0,0 @@
-// Coming soon