@anarchitects/auth-angular 0.4.0 → 0.5.0

package/types/anarchitects-auth-angular-util.d.ts

@@ -1,17 +1,15 @@
-import * as _casl_ability from '@casl/ability';
-import { MongoAbility } from '@casl/ability';
 import { Action, Subject, PolicyRule } from '@anarchitects/auth-ts/models';
+import { MongoAbility } from '@casl/ability';
 
-type AbilitySubject = Subject | (Record<string, unknown> & {
-    __caslSubjectType__?: Subject;
-});
-type AppAbility = MongoAbility<[
-    Action,
-    AbilitySubject
-], {
-    conditions: Record<string, unknown>;
-}>;
-declare const createAppAbility: (rules: PolicyRule[]) => MongoAbility<_casl_ability.AbilityTuple, Record<string, unknown>>;
+type AbilitySubject = Subject | object;
+type AbilityResource = Record<string, unknown>;
+type AppAbility = MongoAbility<[Action, AbilitySubject]>;
+declare const createAppAbility: (rules: PolicyRule[]) => AppAbility;
+declare const asAppAbilitySubject: <TResource extends AbilityResource>(subjectName: Subject, resource: TResource) => TResource & {
+    __caslSubjectType__: Subject;
+};
+declare const canAccessResource: <TResource extends AbilityResource>(ability: AppAbility | undefined, action: Action, subjectName: Subject, resource: TResource) => boolean;
+declare const canAccessResourceField: <TResource extends AbilityResource>(ability: AppAbility | undefined, action: Action, subjectName: Subject, field: string, resource: TResource) => boolean;
 
-export { createAppAbility };
+export { asAppAbilitySubject, canAccessResource, canAccessResourceField, createAppAbility };
 export type { AppAbility };

package/util/README.md

@@ -5,12 +5,28 @@ Utility layer for Angular auth. Re-exported via `@anarchitects/auth-angular/util
 ## Exports
 
 - `createAppAbility(rules: PolicyRule[])`: wraps `createMongoAbility` and returns the typed `AppAbility` used throughout the auth domain.
+- `canAccessResource(...)`: checks a concrete resource instance against the current ability.
+- `canAccessResourceField(...)`: checks whether a specific field-level action is allowed for a concrete resource.
 - `AppAbility`: CASL ability type configured for `Action`/`Subject` pairs defined in `@anarchitects/auth-ts/models`.
 
+## When To Use These Helpers
+
+Use this layer for concrete resource decisions, not coarse route metadata:
+
+- `createAppAbility(rules)` builds the frontend CASL ability from validated RBAC rules
+- `canAccessResource(...)` answers instance-level questions such as "may this user edit this post?"
+- `canAccessResourceField(...)` answers field-sensitive UI questions such as inline title editing
+
+If you only need coarse route-attempt semantics, use `policyGuard` and `RoutePolicy` instead of calling CASL directly here.
+
 ## Usage
 
 ```ts
-import { createAppAbility } from '@anarchitects/auth-angular/util';
+import {
+  canAccessResource,
+  canAccessResourceField,
+  createAppAbility,
+} from '@anarchitects/auth-angular/util';
 import type { PolicyRule } from '@anarchitects/auth-ts/models';
 
 const rules: PolicyRule[] = [
@@ -23,6 +39,16 @@ const ability = createAppAbility(rules);
 if (ability.can('manage', 'Project')) {
   // guarded feature logic
 }
+
+const post = { id: 'post-1', authorId: 'user-1', title: 'Draft' };
+
+if (canAccessResource(ability, 'update', 'Post', post)) {
+  // show edit button
+}
+
+if (canAccessResourceField(ability, 'update', 'Post', 'title', post)) {
+  // allow inline title editing
+}
 ```
 
-For stateful orchestration examples, see `auth.store` in the state layer where the ability factory is integrated with the auth API responses.
+Use these helpers for frontend instance-level decisions such as edit buttons, row actions, and resolved edit routes. Coarse route gating still belongs to `policyGuard`, and the backend must still enforce the final instance-level decision.