Merge pull request #2 from vegtelenseg/1-consider-dropping-asyncconditions-config-field

feat: add runtime detection for async conditions, deprecate asyncConditions flag

Author: vegtelenseg

README.md

@@ -325,12 +325,11 @@ Conditions receive the full `EvaluationContext` — subject, action, resource, r
 
 ### Async Conditions
 
-For conditions that need database lookups or API calls:
+For conditions that need database lookups or API calls, use async functions and the `*Async` evaluation methods:
 
 ```typescript
 const engine = new AccessEngine<MySchema>({
   schema: {} as MySchema,
-  asyncConditions: true,
 });
 
 engine.addRule(
@@ -348,7 +347,7 @@ engine.addRule(
 const decision = await engine.evaluateAsync(user, "report:export", "report");
 ```
 
-When `asyncConditions` is enabled, use `evaluateAsync()`, `permittedAsync()`, and `explainAsync()` instead of their synchronous counterparts.
+Use `evaluateAsync()`, `permittedAsync()`, and `explainAsync()` when you have async conditions. If you accidentally call the synchronous `evaluate()` or `explain()` with async conditions, the engine throws a clear error guiding you to the async API.
 
 ### Wildcard Action Patterns
 
@@ -986,7 +985,7 @@ See [SECURITY.md](./SECURITY.md) for responsible disclosure instructions.
 | `defaultEffect` | `"deny"` (default) or `"allow"` |
 | `onDecision` | Listener called on every evaluation |
 | `onConditionError` | Called when a condition throws (fail-closed) |
-| `asyncConditions` | Enable async condition support |
+| `asyncConditions` | *(deprecated)* When true, sync methods throw immediately. Will be removed in v2. Async conditions are now detected automatically. |
 | `strictTenancy` | Throw if tenantId is omitted for tenant-scoped subjects |
 | `roleHierarchy` | A `RoleHierarchy` instance |
 | `cacheSize` | LRU cache capacity (0 = disabled) |

src/engine.test.ts

@@ -245,6 +245,39 @@ describe("Async conditions", () => {
       "evaluateAsync",
     );
   });
+
+  it("evaluateAsync works without asyncConditions flag", async () => {
+    const engine = new AccessEngine<TestSchema>({ schema });
+    engine.addRule(
+      allow<TestSchema>()
+        .id("async-no-flag")
+        .roles("member")
+        .actions("report:export")
+        .on("report")
+        .when(async (ctx) => ctx.subject.attributes?.["canExport"] === true)
+        .build(),
+    );
+    const user = makeUser("u9", [{ role: "member" }], { canExport: true });
+    const decision = await engine.evaluateAsync(user, "report:export", "report");
+    expect(decision.allowed).toBe(true);
+  });
+
+  it("throws clear error when evaluate() hits async condition without flag", () => {
+    const engine = new AccessEngine<TestSchema>({ schema });
+    engine.addRule(
+      allow<TestSchema>()
+        .id("async-condition")
+        .roles("member")
+        .actions("report:export")
+        .on("report")
+        .when(async () => true)
+        .build(),
+    );
+    const user = makeUser("u10", [{ role: "member" }]);
+    expect(() => engine.evaluate(user, "report:export", "report")).toThrow(
+      "Async condition encountered. Use evaluateAsync() instead.",
+    );
+  });
 });
 
 // ---------------------------------------------------------------------------

src/engine.ts

@@ -32,6 +32,19 @@ function escapeRegexMeta(s: string): string {
   return s.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
 }
 
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    typeof (value as PromiseLike<unknown>).then === "function"
+  );
+}
+
+const ASYNC_CONDITION_EVALUATE_MSG =
+  "Async condition encountered. Use evaluateAsync() instead.";
+const ASYNC_CONDITION_EXPLAIN_MSG =
+  "Async condition encountered. Use explainAsync() instead.";
+
 function compileActionPatterns(actions: string[] | "*"): RegExp[] | null {
   if (actions === "*") return null;
   const patterns: RegExp[] = [];
@@ -362,13 +375,22 @@ export class AccessEngine<S extends SchemaDefinition> {
         for (let i = 0; i < rule.conditions.length; i++) {
           try {
             const result = rule.conditions[i]!(ctx);
+            if (isThenable(result)) {
+              throw new Error(ASYNC_CONDITION_EXPLAIN_MSG);
+            }
             if (result !== true) {
               conditionResults.push({ index: i, passed: false });
               allConditionsPassed = false;
             } else {
               conditionResults.push({ index: i, passed: true });
             }
           } catch (err) {
+            if (
+              err instanceof Error &&
+              err.message === ASYNC_CONDITION_EXPLAIN_MSG
+            ) {
+              throw err;
+            }
             conditionResults.push({
               index: i,
               passed: false,
@@ -552,8 +574,18 @@ export class AccessEngine<S extends SchemaDefinition> {
     if (!rule.conditions) return true;
     for (let i = 0; i < rule.conditions.length; i++) {
       try {
-        if (rule.conditions[i]!(ctx) !== true) return false;
+        const result = rule.conditions[i]!(ctx);
+        if (isThenable(result)) {
+          throw new Error(ASYNC_CONDITION_EVALUATE_MSG);
+        }
+        if (result !== true) return false;
       } catch (err) {
+        if (
+          err instanceof Error &&
+          err.message === ASYNC_CONDITION_EVALUATE_MSG
+        ) {
+          throw err;
+        }
         this.emitConditionError(rule.id, i, err);
         return false;
       }

src/security-and-dx.test.ts

@@ -450,10 +450,27 @@ describe("DX: engine.explain()", () => {
     const user = makeUser("u1", [{ role: "admin" }]);
     expect(() => engine.explain(user, "invoice:read", "invoice")).toThrow("explainAsync");
   });
+
+  it("throws clear error when explain() hits async condition without flag", () => {
+    const engine = new AccessEngine<TestSchema>({ schema });
+    engine.addRule(
+      allow<TestSchema>()
+        .id("async-explain")
+        .roles("member")
+        .actions("report:export")
+        .on("report")
+        .when(async () => true)
+        .build(),
+    );
+    const user = makeUser("u1", [{ role: "member" }]);
+    expect(() => engine.explain(user, "report:export", "report")).toThrow(
+      "Async condition encountered. Use explainAsync() instead.",
+    );
+  });
 });
 
 describe("DX: explainAsync()", () => {
-  it("works with async conditions", async () => {
+  it("works with async conditions (with asyncConditions flag)", async () => {
     const engine = new AccessEngine<TestSchema>({ schema, asyncConditions: true });
     engine.addRule(
       allow<TestSchema>()
@@ -471,6 +488,22 @@ describe("DX: explainAsync()", () => {
     expect(result.allowed).toBe(true);
     expect(result.evaluatedRules[0]!.conditionResults[0]!.passed).toBe(true);
   });
+
+  it("works with async conditions without asyncConditions flag", async () => {
+    const engine = new AccessEngine<TestSchema>({ schema });
+    engine.addRule(
+      allow<TestSchema>()
+        .id("async-no-flag")
+        .roles("member")
+        .actions("report:export")
+        .on("report")
+        .when(async (ctx) => ctx.subject.attributes?.["canExport"] === true)
+        .build(),
+    );
+    const user = makeUser("u1", [{ role: "member" }], { canExport: true });
+    const result = await engine.explainAsync(user, "report:export", "report");
+    expect(result.allowed).toBe(true);
+  });
 });
 
 describe("DX: toAuditEntry()", () => {

src/types.ts

@@ -206,9 +206,14 @@ export interface EngineOptions<S extends SchemaDefinition> {
   onDecision?: DecisionListener<S>;
   onConditionError?: ConditionErrorHandler;
   /**
-   * When true, async conditions are awaited.
-   * When false (default), only synchronous conditions are supported
-   * and evaluate is guaranteed synchronous.
+   * When true, sync methods (evaluate, explain, permitted) throw immediately
+   * to force use of evaluateAsync, explainAsync, permittedAsync.
+   * When false (default), async conditions are detected at runtime and throw
+   * with a clear error pointing to the async API.
+   *
+   * @deprecated This option is deprecated and will be removed in v2. Async
+   * conditions are now detected automatically. Use evaluateAsync(),
+   * explainAsync(), or permittedAsync() when you have async conditions.
    */
   asyncConditions?: boolean;
   /**