toride 0.1.0 → 0.2.0

package/dist/{chunk-QE4FJZEG.js → chunk-24PMDTLE.js}

@@ -54,6 +54,7 @@ var FieldAccessDefSchema = v.object({
 var ResourceBlockSchema = v.object({
   roles: v.array(v.string()),
   permissions: v.array(v.string()),
+  attributes: v.optional(v.record(v.string(), AttributeTypeSchema)),
   relations: v.optional(v.record(v.string(), v.string())),
   grants: v.optional(v.record(v.string(), v.array(v.string()))),
   derived_roles: v.optional(v.array(DerivedRoleEntrySchema)),
@@ -2031,8 +2032,11 @@ var Toride = class {
    * Default-deny: returns false if resource type is unknown or no grants match.
    */
   async can(actor, action, resource, options) {
-    const result = await this.evaluateInternal(actor, action, resource, options);
-    this.fireDecisionEvent(actor, action, resource, result);
+    const a = actor;
+    const r = resource;
+    const act = action;
+    const result = await this.evaluateInternal(a, act, r, options);
+    this.fireDecisionEvent(a, act, r, result);
     return result.allowed;
   }
   /**
@@ -2048,8 +2052,11 @@ var Toride = class {
    * granted permissions, matched rules, and human-readable final decision.
    */
   async explain(actor, action, resource, options) {
-    const result = await this.evaluateInternal(actor, action, resource, options);
-    this.fireDecisionEvent(actor, action, resource, result);
+    const a = actor;
+    const r = resource;
+    const act = action;
+    const result = await this.evaluateInternal(a, act, r, options);
+    this.fireDecisionEvent(a, act, r, result);
     return result;
   }
   /**
@@ -2057,7 +2064,9 @@ var Toride = class {
    * Uses a shared cache across all per-action evaluations.
    */
   async permittedActions(actor, resource, options) {
-    const resourceBlock = this.policy.resources[resource.type];
+    const a = actor;
+    const r = resource;
+    const resourceBlock = this.policy.resources[r.type];
     if (!resourceBlock) {
       return [];
     }
@@ -2065,9 +2074,9 @@ var Toride = class {
     const permitted = [];
     for (const action of resourceBlock.permissions) {
       const result = await this.evaluateInternal(
-        actor,
+        a,
         action,
-        resource,
+        r,
         options,
         sharedCache
       );
@@ -2084,7 +2093,12 @@ var Toride = class {
    * Suitable for serializing to the client via TorideClient.
    */
   async snapshot(actor, resources, options) {
-    return snapshot(this, actor, resources, options);
+    return snapshot(
+      this,
+      actor,
+      resources,
+      options
+    );
   }
   /**
    * T095: Check if an actor can perform a field-level operation on a specific field.
@@ -2092,33 +2106,52 @@ var Toride = class {
    * Unlisted fields are unrestricted: any actor with the resource-level permission can access them.
    */
   async canField(actor, operation, resource, field, options) {
-    const resourceBlock = this.policy.resources[resource.type];
+    const r = resource;
+    const resourceBlock = this.policy.resources[r.type];
     if (!resourceBlock) {
       return false;
     }
-    return canField(this, actor, operation, resource, field, resourceBlock.field_access, options);
+    return canField(
+      this,
+      actor,
+      operation,
+      r,
+      field,
+      resourceBlock.field_access,
+      options
+    );
   }
   /**
    * T095: Return the list of declared field_access field names the actor can access
    * for the given operation. Only returns explicitly declared fields.
    */
   async permittedFields(actor, operation, resource, options) {
-    const resourceBlock = this.policy.resources[resource.type];
+    const r = resource;
+    const resourceBlock = this.policy.resources[r.type];
     if (!resourceBlock) {
       return [];
     }
-    return permittedFields(this, actor, operation, resource, resourceBlock.field_access, options);
+    return permittedFields(
+      this,
+      actor,
+      operation,
+      r,
+      resourceBlock.field_access,
+      options
+    );
   }
   /**
    * T070: Return flat deduplicated list of all resolved roles (direct + derived).
    */
   async resolvedRoles(actor, resource, options) {
-    const resourceBlock = this.policy.resources[resource.type];
+    const a = actor;
+    const r = resource;
+    const resourceBlock = this.policy.resources[r.type];
     if (!resourceBlock) {
       return [];
     }
     const action = resourceBlock.permissions[0] ?? "__resolvedRoles__";
-    const result = await this.evaluateInternal(actor, action, resource, options);
+    const result = await this.evaluateInternal(a, action, r, options);
     const directRoles = result.resolvedRoles.direct;
     const derivedRoleNames = result.resolvedRoles.derived.map((d) => d.role);
     return [.../* @__PURE__ */ new Set([...directRoles, ...derivedRoleNames])];
@@ -2131,17 +2164,20 @@ var Toride = class {
     if (checks.length === 0) {
       return [];
     }
+    const a = actor;
     const sharedCache = new AttributeCache(this.resolvers);
     const results = [];
     for (const check of checks) {
+      const r = check.resource;
+      const act = check.action;
       const result = await this.evaluateInternal(
-        actor,
-        check.action,
-        check.resource,
+        a,
+        act,
+        r,
         options,
         sharedCache
       );
-      this.fireDecisionEvent(actor, check.action, check.resource, result);
+      this.fireDecisionEvent(a, act, r, result);
       results.push(result.allowed);
     }
     return results;
@@ -2151,11 +2187,14 @@ var Toride = class {
    * Returns ConstraintResult with unrestricted/forbidden sentinels or constraint AST.
    */
   async buildConstraints(actor, action, resourceType, options) {
+    const a = actor;
+    const act = action;
+    const rt = resourceType;
     const cache = new AttributeCache(this.resolvers);
     const constraintResult = await buildConstraints(
-      actor,
-      action,
-      resourceType,
+      a,
+      act,
+      rt,
       cache,
       this.policy,
       {
@@ -2164,7 +2203,7 @@ var Toride = class {
         customEvaluators: this.options.customEvaluators
       }
     );
-    this.fireQueryEvent(actor, action, resourceType, constraintResult);
+    this.fireQueryEvent(a, act, rt, constraintResult);
     return constraintResult;
   }
   /**

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.js

@@ -7,7 +7,7 @@ import {
   runTestCases,
   validatePolicyResult,
   validatePolicyStrict
-} from "./chunk-QE4FJZEG.js";
+} from "./chunk-24PMDTLE.js";
 
 // src/cli.ts
 import { readFileSync, readdirSync, statSync } from "fs";

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

@@ -1,33 +1 @@
-import { P as PermissionSnapshot } from './snapshot-CcCYeU0Q.js';
-
-declare const CLIENT_VERSION = "0.0.1";
-
-/** Minimal resource reference for client-side lookups. */
-interface ClientResourceRef {
-    readonly type: string;
-    readonly id: string;
-}
-/**
- * Client-side permission checker that provides instant synchronous checks
- * against a PermissionSnapshot received from the server.
- *
- * Default-deny: unknown resources or actions return false.
- * The snapshot is defensively copied to prevent external mutation.
- */
-declare class TorideClient {
-    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: string, resource: ClientResourceRef): boolean;
-    /**
-     * Return the list of permitted actions for a resource.
-     * Returns empty array for unknown resources.
-     */
-    permittedActions(resource: ClientResourceRef): string[];
-}
-
-export { CLIENT_VERSION, type ClientResourceRef, PermissionSnapshot, TorideClient };
+export { v as CLIENT_VERSION, g as ClientResourceRef, b as PermissionSnapshot, u as TorideClient } from './client-RqwW0K_-.js';

package/dist/client.js

@@ -1,35 +1,7 @@
-// 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];
-  }
-};
+import {
+  CLIENT_VERSION,
+  TorideClient
+} from "./chunk-475CNU63.js";
 export {
   CLIENT_VERSION,
   TorideClient

package/dist/index.d.ts

@@ -1,230 +1,5 @@
-import { P as PermissionSnapshot } from './snapshot-CcCYeU0Q.js';
-
-/** Represents an entity performing actions. */
-interface ActorRef {
-    readonly type: string;
-    readonly id: string;
-    readonly attributes: Record<string, unknown>;
-}
-/** Represents a protected entity being accessed. */
-interface ResourceRef {
-    readonly type: string;
-    readonly id: string;
-    /** Pre-fetched attributes. Inline values take precedence over resolver results. */
-    readonly attributes?: Record<string, unknown>;
-}
-/** Optional per-check configuration. */
-interface CheckOptions {
-    readonly env?: Record<string, unknown>;
-}
-/** A single item in a canBatch() call. */
-interface BatchCheckItem {
-    readonly action: string;
-    readonly resource: ResourceRef;
-}
-/**
- * Per-type resolver function.
- * Called when the engine needs attributes not available inline.
- * Called at most once per unique resource per evaluation (cached).
- */
-type ResourceResolver = (ref: ResourceRef) => Promise<Record<string, unknown>>;
-/**
- * Map of resource type names to their resolver functions.
- * Not all types need resolvers — types without resolvers use trivial resolution
- * (fields are undefined unless provided inline).
- */
-type Resolvers = Record<string, ResourceResolver>;
-/** Custom evaluator function signature. */
-type EvaluatorFn = (actor: ActorRef, resource: ResourceRef, env: Record<string, unknown>) => Promise<boolean>;
-/** Engine construction options. */
-interface TorideOptions {
-    readonly policy: Policy;
-    /** Per-type resolver map. Optional — engine works without resolvers if all data is inline. */
-    readonly resolvers?: Resolvers;
-    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[];
-    /** 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 {
-    readonly allowed: boolean;
-    readonly resolvedRoles: ResolvedRolesDetail;
-    readonly grantedPermissions: string[];
-    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");
-}
+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.
@@ -398,16 +173,16 @@ interface ConstraintAdapter<TQuery> {
  * Creates a per-check cache, resolves direct roles, checks grants,
  * and returns boolean with default-deny semantics.
  */
-declare class Toride {
+declare class Toride<S extends TorideSchema = DefaultSchema> {
     private policy;
     private readonly resolvers;
     private readonly options;
-    constructor(options: TorideOptions);
+    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(actor: ActorRef, action: string, resource: ResourceRef, options?: CheckOptions): Promise<boolean>;
+    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.
@@ -418,44 +193,44 @@ declare class Toride {
      * T068: Return full ExplainResult with role derivation traces,
      * granted permissions, matched rules, and human-readable final decision.
      */
-    explain(actor: ActorRef, action: string, resource: ResourceRef, options?: CheckOptions): Promise<ExplainResult>;
+    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(actor: ActorRef, resource: ResourceRef, options?: CheckOptions): Promise<string[]>;
+    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, resources: ResourceRef[], options?: CheckOptions): Promise<PermissionSnapshot>;
+    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(actor: ActorRef, operation: "read" | "update", resource: ResourceRef, field: string, options?: CheckOptions): Promise<boolean>;
+    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(actor: ActorRef, operation: "read" | "update", resource: ResourceRef, options?: CheckOptions): Promise<string[]>;
+    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(actor: ActorRef, resource: ResourceRef, options?: CheckOptions): Promise<string[]>;
+    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, checks: BatchCheckItem[], options?: CheckOptions): Promise<boolean[]>;
+    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(actor: ActorRef, action: string, resourceType: string, options?: CheckOptions): Promise<ConstraintResult>;
+    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.
@@ -480,7 +255,7 @@ declare class Toride {
 /**
  * Typed factory function for creating a Toride instance.
  */
-declare function createToride(options: TorideOptions): Toride;
+declare function createToride<S extends TorideSchema = DefaultSchema>(options: TorideOptions<S>): Toride<S>;
 
 /**
  * Constructs a Resolvers map from test case mock data.
@@ -531,4 +306,4 @@ declare function runTestCases(policy: Policy, tests: TestCase[]): Promise<TestRe
 
 declare const VERSION = "0.0.1";
 
-export { type ActorDeclaration, type ActorRef, type AttributeType, type BatchCheckItem, type CheckOptions, type ConditionExpression, type ConditionOperator, type ConditionValue, type Constraint, type ConstraintAdapter, type ConstraintResult, CycleError, type DecisionEvent, DepthLimitError, type DerivedRoleEntry, type DerivedRoleTrace, type EvaluatorFn, type ExplainResult, type FieldAccessDef, type GlobalRole, type LeafConstraint, type MatchedRule, PermissionSnapshot, type Policy, type QueryEvent, type ResolvedRolesDetail, type Resolvers, type ResourceBlock, type ResourceRef, type ResourceResolver, type Rule, type SimpleConditions, type StrictValidationResult, type TestCase, type TestFileResult, type TestResult, Toride, type TorideOptions, VERSION, type ValidationDiagnostic, ValidationError, type ValidationResult, createMockResolver, createToride, loadJson, loadYaml, mergePolicies, parseInlineTests, parseTestFile, runTestCases, validatePolicy, validatePolicyResult, validatePolicyStrict };
+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

@@ -12,7 +12,10 @@ import {
   validatePolicy,
   validatePolicyResult,
   validatePolicyStrict
-} from "./chunk-QE4FJZEG.js";
+} from "./chunk-24PMDTLE.js";
+import {
+  TorideClient
+} from "./chunk-475CNU63.js";
 
 // src/policy/parser.ts
 import * as YAML from "yaml";
@@ -226,6 +229,7 @@ export {
   CycleError,
   DepthLimitError,
   Toride,
+  TorideClient,
   VERSION,
   ValidationError,
   createMockResolver,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toride",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Relation-aware authorization engine for TypeScript",
   "type": "module",
   "exports": {
@@ -27,8 +27,8 @@
     ]
   },
   "dependencies": {
-    "yaml": "^2.3.0",
-    "valibot": "^1.2.0"
+    "valibot": "^1.2.0",
+    "yaml": "^2.3.0"
   },
   "keywords": [
     "authorization",
@@ -42,9 +42,13 @@
     "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/dist/snapshot-CcCYeU0Q.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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[]>;
-
-export type { PermissionSnapshot as P };