toride 0.0.1 → 0.2.0

package/dist/chunk-475CNU63.js

@@ -0,0 +1,37 @@
+// src/client.ts
+var CLIENT_VERSION = "0.0.1";
+var TorideClient = class {
+  permissions;
+  constructor(snapshot) {
+    this.permissions = /* @__PURE__ */ new Map();
+    for (const [key, actions] of Object.entries(snapshot)) {
+      this.permissions.set(key, new Set(actions));
+    }
+  }
+  /**
+   * Synchronous permission check.
+   * Returns true if the action is permitted for the resource, false otherwise.
+   * Unknown resources return false (default-deny).
+   */
+  can(action, resource) {
+    const key = `${resource.type}:${resource.id}`;
+    const actions = this.permissions.get(key);
+    if (!actions) return false;
+    return actions.has(action);
+  }
+  /**
+   * Return the list of permitted actions for a resource.
+   * Returns empty array for unknown resources.
+   */
+  permittedActions(resource) {
+    const key = `${resource.type}:${resource.id}`;
+    const actions = this.permissions.get(key);
+    if (!actions) return [];
+    return [...actions];
+  }
+};
+
+export {
+  CLIENT_VERSION,
+  TorideClient
+};

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/** Main CLI entry point. */
+declare function main(args?: string[]): Promise<number>;
+
+export { main };

package/dist/cli.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import {
+  PolicySchema,
+  ValidationError,
+  parseInlineTests,
+  parseTestFile,
+  runTestCases,
+  validatePolicyResult,
+  validatePolicyStrict
+} from "./chunk-24PMDTLE.js";
+
+// src/cli.ts
+import { readFileSync, readdirSync, statSync } from "fs";
+import { resolve, dirname, join } from "path";
+import * as YAML from "yaml";
+import * as v from "valibot";
+function loadPolicyFile(filePath) {
+  const absPath = resolve(filePath);
+  let content;
+  try {
+    content = readFileSync(absPath, "utf-8");
+  } catch {
+    throw new Error(`Cannot read file: ${absPath}`);
+  }
+  let raw;
+  if (absPath.endsWith(".json")) {
+    try {
+      raw = JSON.parse(content);
+    } catch (err) {
+      throw new ValidationError(
+        `JSON parse error: ${err instanceof Error ? err.message : String(err)}`,
+        ""
+      );
+    }
+  } else {
+    try {
+      raw = YAML.parse(content, { prettyErrors: true });
+    } catch (err) {
+      throw new ValidationError(
+        `YAML parse error: ${err instanceof Error ? err.message : String(err)}`,
+        ""
+      );
+    }
+  }
+  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
+    );
+  }
+  return result.output;
+}
+function expandGlob(pattern) {
+  const absPattern = resolve(pattern);
+  if (!pattern.includes("*")) {
+    return [absPattern];
+  }
+  const parts = absPattern.split("/");
+  const baseParts = [];
+  for (const part of parts) {
+    if (part.includes("*")) break;
+    baseParts.push(part);
+  }
+  const baseDir = baseParts.join("/") || "/";
+  const regexStr = absPattern.replace(/\./g, "\\.").replace(/\*\*/g, "___GLOBSTAR___").replace(/\*/g, "[^/]*").replace(/___GLOBSTAR___/g, ".*");
+  const regex = new RegExp(`^${regexStr}$`);
+  const results = [];
+  function walkDir(dir) {
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join(dir, entry);
+      try {
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          walkDir(fullPath);
+        } else if (regex.test(fullPath)) {
+          results.push(fullPath);
+        }
+      } catch {
+      }
+    }
+  }
+  walkDir(baseDir);
+  return results.sort();
+}
+async function runTestFile(filePath) {
+  const absPath = resolve(filePath);
+  const content = readFileSync(absPath, "utf-8");
+  if (absPath.endsWith(".test.yaml") || absPath.endsWith(".test.yml")) {
+    const testFile = parseTestFile(content);
+    const policyPath = resolve(dirname(absPath), testFile.policyPath);
+    const policy = loadPolicyFile(policyPath);
+    const results = await runTestCases(policy, testFile.tests);
+    return { results, file: absPath };
+  } else {
+    const policy = loadPolicyFile(absPath);
+    const { tests } = parseInlineTests(policy);
+    if (tests.length === 0) {
+      return { results: [], file: absPath };
+    }
+    const results = await runTestCases(policy, tests);
+    return { results, file: absPath };
+  }
+}
+async function main(args = process.argv.slice(2)) {
+  const command = args[0];
+  if (command !== "validate" && command !== "test") {
+    console.error(`Usage: toride <validate|test> [options] <file(s)>`);
+    return 1;
+  }
+  if (command === "test") {
+    return handleTestCommand(args.slice(1));
+  }
+  const isStrict = args.includes("--strict");
+  const fileArg = args.filter((a) => a !== "validate" && a !== "--strict")[0];
+  if (!fileArg) {
+    console.error("Error: No policy file specified");
+    console.error("Usage: toride validate [--strict] <policy-file>");
+    return 1;
+  }
+  let policy;
+  try {
+    policy = loadPolicyFile(fileArg);
+  } catch (err) {
+    if (err instanceof ValidationError) {
+      console.error(`Error: ${err.message}`);
+    } else if (err instanceof Error) {
+      console.error(`Error: ${err.message}`);
+    }
+    return 1;
+  }
+  if (isStrict) {
+    const result = validatePolicyStrict(policy);
+    for (const error of result.errors) {
+      console.error(`Error: ${error.message}`);
+    }
+    for (const warning of result.warnings) {
+      console.warn(`Warning: ${warning.message}`);
+    }
+    if (result.errors.length > 0) {
+      return 1;
+    }
+    if (result.errors.length === 0 && result.warnings.length === 0) {
+      console.log("Policy is valid.");
+    } else {
+      console.log("Policy is valid (with warnings).");
+    }
+    return 0;
+  } else {
+    const result = validatePolicyResult(policy);
+    for (const error of result.errors) {
+      console.error(`Error: ${error.message}`);
+    }
+    if (result.errors.length > 0) {
+      return 1;
+    }
+    console.log("Policy is valid.");
+    return 0;
+  }
+}
+async function handleTestCommand(args) {
+  const fileArgs = args.filter((a) => !a.startsWith("-"));
+  if (fileArgs.length === 0) {
+    console.error("Error: No test file(s) specified");
+    console.error("Usage: toride test <file-or-glob> [...]");
+    return 1;
+  }
+  const allFiles = [];
+  for (const arg of fileArgs) {
+    const expanded = expandGlob(arg);
+    if (expanded.length === 0) {
+      console.error(`Warning: No files matched pattern "${arg}"`);
+    }
+    allFiles.push(...expanded);
+  }
+  if (allFiles.length === 0) {
+    console.error("Error: No test files found");
+    return 1;
+  }
+  let totalPassed = 0;
+  let totalFailed = 0;
+  for (const file of allFiles) {
+    try {
+      const { results } = await runTestFile(file);
+      for (const result of results) {
+        if (result.passed) {
+          console.log(`  \u2713 ${result.name}`);
+          totalPassed++;
+        } else {
+          console.log(`  \u2717 ${result.name}`);
+          console.log(`    Expected: ${result.expected}`);
+          console.log(`    Got: ${result.actual}`);
+          totalFailed++;
+        }
+      }
+    } catch (err) {
+      console.error(`Error processing ${file}: ${err instanceof Error ? err.message : String(err)}`);
+      totalFailed++;
+    }
+  }
+  console.log("");
+  if (totalFailed === 0) {
+    console.log(`${totalPassed} tests passed`);
+    return 0;
+  } else {
+    console.log(`${totalPassed} passed, ${totalFailed} failed`);
+    return 1;
+  }
+}
+var isDirectExecution = typeof process !== "undefined" && process.argv[1] && (process.argv[1].endsWith("/cli.js") || process.argv[1].endsWith("/cli.mjs"));
+if (isDirectExecution) {
+  main().then((code) => process.exit(code));
+}
+export {
+  main
+};

package/dist/client-RqwW0K_-.d.ts

@@ -0,0 +1,368 @@
+/**
+ * Shape constraint for Toride's type parameter.
+ * Each property is a union or mapped type that codegen fills with literals.
+ */
+interface TorideSchema {
+    /** Union of all resource type names (e.g., "Document" | "Organization") */
+    resources: string;
+    /** Global union of all action/permission names across all resources */
+    actions: string;
+    /** Union of all actor type names (e.g., "User" | "ServiceAccount") */
+    actorTypes: string;
+    /** Per-resource permission unions: { Document: "read" | "write"; ... } */
+    permissionMap: {
+        [R in string]: string;
+    };
+    /** Per-resource role unions: { Document: "admin" | "editor"; ... } */
+    roleMap: {
+        [R in string]: string;
+    };
+    /** Per-resource attribute shapes: { Document: { status: string; ownerId: string }; ... } */
+    resourceAttributeMap: {
+        [R in string]: Record<string, unknown>;
+    };
+    /** Per-actor attribute shapes: { User: { email: string; is_admin: boolean }; ... } */
+    actorAttributeMap: {
+        [A in string]: Record<string, unknown>;
+    };
+    /** Per-resource relation maps: { Document: { org: "Organization" }; ... } */
+    relationMap: {
+        [R in string]: Record<string, string>;
+    };
+}
+/**
+ * Default schema where everything is string / Record<string, unknown>.
+ * Used when Toride is instantiated without a type parameter.
+ * Provides full backward compatibility with the current untyped API.
+ */
+interface DefaultSchema extends TorideSchema {
+    resources: string;
+    actions: string;
+    actorTypes: string;
+    permissionMap: Record<string, string>;
+    roleMap: Record<string, string>;
+    resourceAttributeMap: Record<string, Record<string, unknown>>;
+    actorAttributeMap: Record<string, Record<string, unknown>>;
+    relationMap: Record<string, Record<string, string>>;
+}
+/**
+ * Represents an entity performing actions.
+ * Generic discriminated union over actor types in S.
+ * When S = DefaultSchema, collapses to the original untyped shape.
+ */
+type ActorRef<S extends TorideSchema = DefaultSchema> = {
+    [A in S["actorTypes"]]: {
+        readonly type: A;
+        readonly id: string;
+        readonly attributes: S["actorAttributeMap"][A];
+    };
+}[S["actorTypes"]];
+/**
+ * Represents a protected entity being accessed.
+ * Generic over schema S and resource type R.
+ * When S = DefaultSchema, collapses to the original untyped shape.
+ */
+type ResourceRef<S extends TorideSchema = DefaultSchema, R extends S["resources"] = S["resources"]> = {
+    readonly type: R;
+    readonly id: string;
+    /** Pre-fetched attributes. Inline values take precedence over resolver results. */
+    readonly attributes?: S["resourceAttributeMap"][R];
+};
+/** Optional per-check configuration. */
+interface CheckOptions {
+    readonly env?: Record<string, unknown>;
+}
+/** A single item in a canBatch() call. Action narrowed to global actions union. */
+interface BatchCheckItem<S extends TorideSchema = DefaultSchema> {
+    readonly action: S["actions"];
+    readonly resource: ResourceRef<S>;
+}
+/**
+ * Per-type resolver function.
+ * Called when the engine needs attributes not available inline.
+ * Called at most once per unique resource per evaluation (cached).
+ *
+ * Registering a resolver is **optional** per resource type. When no resolver is
+ * registered, inline {@link ResourceRef.attributes} are used as the sole data
+ * source — this is referred to as "default resolver" behavior (analogous to
+ * GraphQL's default field resolver, which returns `parent[fieldName]`).
+ *
+ * A resolver is only needed when attributes must be fetched from an external
+ * source (e.g., a database). When both inline attributes and a resolver are
+ * present, inline attributes take precedence field-by-field over resolver
+ * results.
+ */
+type ResourceResolver<S extends TorideSchema = DefaultSchema, R extends S["resources"] = S["resources"]> = (ref: ResourceRef<S, R>) => Promise<Record<string, unknown>>;
+/**
+ * Map of resource type names to their resolver functions.
+ *
+ * Not all types need resolvers. Types without a registered resolver use
+ * **default resolver** behavior (also called "trivial resolution"): the engine
+ * reads attribute values directly from the inline {@link ResourceRef.attributes}
+ * passed at the call site. Fields not present inline resolve to `undefined`,
+ * causing conditions that reference them to fail (default-deny).
+ *
+ * This mirrors GraphQL's default field resolver pattern, where an unresolved
+ * field simply returns `parent[fieldName]` — here, inline attributes play the
+ * role of the `parent` object.
+ */
+type Resolvers<S extends TorideSchema = DefaultSchema> = {
+    [R in S["resources"]]?: ResourceResolver<S, R>;
+};
+/** Custom evaluator function signature. */
+type EvaluatorFn = (actor: ActorRef, resource: ResourceRef, env: Record<string, unknown>) => Promise<boolean>;
+/** Engine construction options. */
+interface TorideOptions<S extends TorideSchema = DefaultSchema> {
+    readonly policy: Policy;
+    /**
+     * Per-type resolver map.
+     *
+     * Optional — the engine works without any resolvers when all required data is
+     * provided inline via {@link ResourceRef.attributes}. This "default resolver"
+     * mode is the simplest way to use toride and requires no async data fetching.
+     *
+     * When both inline attributes and a resolver are present for the same resource
+     * type, **inline attributes take precedence** over resolver results on a
+     * field-by-field basis.
+     *
+     * @example
+     * ```ts
+     * // Inline-only mode — no resolvers needed
+     * const toride = new Toride({ policy });
+     *
+     * const allowed = await toride.can(actor, "read", {
+     *   type: "Document",
+     *   id: "doc-1",
+     *   attributes: { status: "published", ownerId: "user-42" },
+     * });
+     * ```
+     */
+    readonly resolvers?: Resolvers<S>;
+    readonly maxConditionDepth?: number;
+    readonly maxDerivedRoleDepth?: number;
+    readonly customEvaluators?: Record<string, EvaluatorFn>;
+    readonly onDecision?: (event: DecisionEvent) => void;
+    readonly onQuery?: (event: QueryEvent) => void;
+}
+/** Attribute type for actor declarations. */
+type AttributeType = "string" | "number" | "boolean";
+/** Actor type declaration with attribute schema. */
+interface ActorDeclaration {
+    readonly attributes: Record<string, AttributeType>;
+}
+/** Global role definition derived from actor attributes. */
+interface GlobalRole {
+    readonly actor_type: string;
+    readonly when: ConditionExpression;
+}
+/**
+ * Derived role entry. Exactly one derivation pattern per entry.
+ * Patterns:
+ *   1. from_global_role
+ *   2. from_role + on_relation
+ *   3. from_relation
+ *   4. actor_type + when (conditional)
+ *   5. when only
+ */
+interface DerivedRoleEntry {
+    readonly role: string;
+    readonly from_global_role?: string;
+    readonly from_role?: string;
+    readonly on_relation?: string;
+    readonly from_relation?: string;
+    readonly actor_type?: string;
+    readonly when?: ConditionExpression;
+}
+/** Conditional rule (permit or forbid). */
+interface Rule {
+    readonly effect: "permit" | "forbid";
+    readonly roles?: string[];
+    readonly permissions: string[];
+    readonly when: ConditionExpression;
+}
+/** Field-level access control definition. */
+interface FieldAccessDef {
+    readonly read?: string[];
+    readonly update?: string[];
+}
+/** Resource block definition. */
+interface ResourceBlock {
+    readonly roles: string[];
+    readonly permissions: string[];
+    /** Optional typed attribute declarations for this resource type. */
+    readonly attributes?: Record<string, AttributeType>;
+    /** Relations map field names to target resource type names (simplified). */
+    readonly relations?: Record<string, string>;
+    readonly grants?: Record<string, string[]>;
+    readonly derived_roles?: DerivedRoleEntry[];
+    readonly rules?: Rule[];
+    readonly field_access?: Record<string, FieldAccessDef>;
+}
+/** Operator-based condition value. */
+type ConditionOperator = {
+    readonly eq: unknown;
+} | {
+    readonly neq: unknown;
+} | {
+    readonly gt: unknown;
+} | {
+    readonly gte: unknown;
+} | {
+    readonly lt: unknown;
+} | {
+    readonly lte: unknown;
+} | {
+    readonly in: unknown[] | string;
+} | {
+    readonly includes: unknown;
+} | {
+    readonly exists: boolean;
+} | {
+    readonly startsWith: string;
+} | {
+    readonly endsWith: string;
+} | {
+    readonly contains: string;
+} | {
+    readonly custom: string;
+};
+/**
+ * Condition value: either a primitive (equality shorthand),
+ * a cross-reference string ($actor.x, $resource.x, $env.x),
+ * or an operator object.
+ */
+type ConditionValue = string | number | boolean | ConditionOperator;
+/** Simple conditions: all key-value pairs ANDed together. */
+type SimpleConditions = Record<string, ConditionValue>;
+/**
+ * Recursive condition expression.
+ * Either simple conditions (Record<string, ConditionValue>),
+ * or a logical combinator ({ any: ... } or { all: ... }).
+ */
+type ConditionExpression = SimpleConditions | {
+    readonly any: ConditionExpression[];
+} | {
+    readonly all: ConditionExpression[];
+};
+/** Test case for declarative YAML tests. */
+interface TestCase {
+    readonly name: string;
+    readonly actor: ActorRef;
+    /** Mock resolver data: keyed by "Type:id", values are attribute objects. */
+    readonly resolvers?: Record<string, Record<string, unknown>>;
+    readonly action: string;
+    readonly resource: ResourceRef;
+    readonly expected: "allow" | "deny";
+}
+/** Top-level policy object. */
+interface Policy {
+    readonly version: "1";
+    readonly actors: Record<string, ActorDeclaration>;
+    readonly global_roles?: Record<string, GlobalRole>;
+    readonly resources: Record<string, ResourceBlock>;
+    readonly tests?: TestCase[];
+}
+/** Trace for a derived role showing derivation path. */
+interface DerivedRoleTrace {
+    readonly role: string;
+    readonly via: string;
+}
+/** Resolved roles detail with direct and derived breakdown. */
+interface ResolvedRolesDetail {
+    readonly direct: string[];
+    readonly derived: DerivedRoleTrace[];
+}
+/** A matched rule with evaluation context. */
+interface MatchedRule {
+    readonly effect: "permit" | "forbid";
+    readonly matched: boolean;
+    readonly rule: Rule;
+    readonly resolvedValues: Record<string, unknown>;
+}
+/** Full decision trace from explain(). */
+interface ExplainResult<S extends TorideSchema = DefaultSchema, R extends S["resources"] = S["resources"]> {
+    readonly allowed: boolean;
+    readonly resolvedRoles: ResolvedRolesDetail;
+    readonly grantedPermissions: S["permissionMap"][R][];
+    readonly matchedRules: MatchedRule[];
+    readonly finalDecision: string;
+}
+/** Audit event for authorization checks. */
+interface DecisionEvent {
+    readonly actor: ActorRef;
+    readonly action: string;
+    readonly resource: ResourceRef;
+    readonly allowed: boolean;
+    readonly resolvedRoles: string[];
+    readonly matchedRules: {
+        effect: string;
+        matched: boolean;
+    }[];
+    readonly timestamp: Date;
+}
+/** Audit event for constraint queries. */
+interface QueryEvent {
+    readonly actor: ActorRef;
+    readonly action: string;
+    readonly resourceType: string;
+    readonly resultType: "unrestricted" | "forbidden" | "constrained";
+    readonly timestamp: Date;
+}
+/** Thrown when policy validation fails. */
+declare class ValidationError extends Error {
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/** Thrown when a cycle is detected in relation traversal. */
+declare class CycleError extends Error {
+    readonly path: string[];
+    constructor(message: string, path: string[]);
+}
+/** Thrown when depth limit is exceeded. */
+declare class DepthLimitError extends Error {
+    readonly limit: number;
+    readonly limitType: "condition" | "derivation";
+    constructor(message: string, limit: number, limitType: "condition" | "derivation");
+}
+
+/**
+ * A serializable map of permissions keyed by "Type:id".
+ * Values are arrays of permitted action strings.
+ * Suitable for JSON transport to client-side TorideClient.
+ */
+type PermissionSnapshot = Record<string, string[]>;
+
+declare const CLIENT_VERSION = "0.0.1";
+
+/** Minimal resource reference for client-side lookups. Generic over S for type narrowing. */
+interface ClientResourceRef<S extends TorideSchema = DefaultSchema> {
+    readonly type: S["resources"];
+    readonly id: string;
+}
+/**
+ * Client-side permission checker that provides instant synchronous checks
+ * against a PermissionSnapshot received from the server.
+ *
+ * Generic over TorideSchema so that action names and resource types
+ * are validated at compile time when a concrete schema is provided.
+ *
+ * Default-deny: unknown resources or actions return false.
+ * The snapshot is defensively copied to prevent external mutation.
+ */
+declare class TorideClient<S extends TorideSchema = DefaultSchema> {
+    private readonly permissions;
+    constructor(snapshot: PermissionSnapshot);
+    /**
+     * Synchronous permission check.
+     * Returns true if the action is permitted for the resource, false otherwise.
+     * Unknown resources return false (default-deny).
+     */
+    can(action: S["actions"], resource: ClientResourceRef<S>): boolean;
+    /**
+     * Return the list of permitted actions for a resource.
+     * Returns empty array for unknown resources.
+     */
+    permittedActions(resource: ClientResourceRef<S>): S["actions"][];
+}
+
+export { type ActorRef as A, type BatchCheckItem as B, type CheckOptions as C, type DefaultSchema as D, type ExplainResult as E, type FieldAccessDef as F, type GlobalRole as G, type MatchedRule as M, type Policy as P, type QueryEvent as Q, type ResourceRef as R, type SimpleConditions as S, type TorideSchema as T, ValidationError as V, type TorideOptions as a, type PermissionSnapshot as b, type TestCase as c, type Resolvers as d, type ActorDeclaration as e, type AttributeType as f, type ClientResourceRef as g, type ConditionExpression as h, type ConditionOperator as i, type ConditionValue as j, CycleError as k, type DecisionEvent as l, DepthLimitError as m, type DerivedRoleEntry as n, type DerivedRoleTrace as o, type EvaluatorFn as p, type ResolvedRolesDetail as q, type ResourceBlock as r, type ResourceResolver as s, type Rule as t, TorideClient as u, CLIENT_VERSION as v };

package/dist/client.d.ts

@@ -0,0 +1 @@
+export { v as CLIENT_VERSION, g as ClientResourceRef, b as PermissionSnapshot, u as TorideClient } from './client-RqwW0K_-.js';

package/dist/client.js

@@ -0,0 +1,8 @@
+import {
+  CLIENT_VERSION,
+  TorideClient
+} from "./chunk-475CNU63.js";
+export {
+  CLIENT_VERSION,
+  TorideClient
+};