@frontmcp/skills 1.0.4 → 1.1.0-beta.1

package/catalog/frontmcp-authorities/references/claims-mapping.md

@@ -0,0 +1,266 @@
+---
+name: claims-mapping
+description: JWT claims mapping configuration per identity provider (Auth0, Keycloak, Okta, Cognito, Frontegg) for the authorities system
+---
+
+# JWT Claims Mapping
+
+The `claimsMapping` field in `@FrontMcp({ authorities: { claimsMapping } })` tells the authorities engine where to find roles, permissions, tenant ID, and user ID within the decoded JWT payload. Every identity provider structures its tokens differently, so this mapping is required for correct policy evaluation.
+
+## How Claims Mapping Works
+
+The engine receives `authInfo` on each request, which contains the decoded JWT claims. The `claimsMapping` fields are dot-paths resolved against these claims using `resolveDotPath()`. The resolver first tries a direct key lookup (for keys containing dots, such as Auth0 namespaced claims), then falls back to dot-separated path traversal.
+
+```typescript
+interface AuthoritiesClaimsMapping {
+  /** Dot-path to roles array in JWT claims */
+  roles?: string;
+  /** Dot-path to permissions array/string in JWT claims */
+  permissions?: string;
+  /** Dot-path to tenant/org ID in JWT claims */
+  tenantId?: string;
+  /** Dot-path to user ID in JWT claims (default: 'sub') */
+  userId?: string;
+  /** Extensible: additional custom claim mappings */
+  [key: string]: string | undefined;
+}
+```
+
+## Auth0
+
+Auth0 stores roles in a custom namespaced claim (you define the namespace) and permissions in a flat `permissions` array. The org ID (if using Auth0 Organizations) is in `org_id`.
+
+**Sample JWT payload:**
+
+```json
+{
+  "sub": "auth0|abc123",
+  "https://myapp.com/roles": ["admin", "editor"],
+  "permissions": ["users:read", "users:write", "content:publish"],
+  "org_id": "org_def456",
+  "aud": "https://api.myapp.com",
+  "iss": "https://myapp.auth0.com/"
+}
+```
+
+**Claims mapping:**
+
+```typescript
+// In @FrontMcp({ authorities: { ... } })
+authorities: {
+  claimsMapping: {
+    roles: 'https://myapp.com/roles',
+    permissions: 'permissions',
+    tenantId: 'org_id',
+  },
+}
+```
+
+**Notes:**
+
+- The roles claim namespace (`https://myapp.com/roles`) is configured in an Auth0 Action or Rule. It must be a fully qualified URL.
+- `resolveDotPath` handles the dotted namespace key via direct key lookup, so `https://myapp.com/roles` works correctly.
+- Permissions appear only if the API has RBAC enabled in Auth0 dashboard.
+
+## Keycloak
+
+Keycloak nests realm roles under `realm_access.roles` and client-specific roles under `resource_access.<client-id>.roles`. Permissions are typically modeled as client roles or fine-grained UMA permissions.
+
+**Sample JWT payload:**
+
+```json
+{
+  "sub": "f1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "realm_access": {
+    "roles": ["admin", "user", "offline_access"]
+  },
+  "resource_access": {
+    "my-client": {
+      "roles": ["content:write", "content:publish"]
+    },
+    "account": {
+      "roles": ["manage-account"]
+    }
+  },
+  "preferred_username": "jane.doe",
+  "azp": "my-client",
+  "iss": "https://keycloak.example.com/realms/myrealm"
+}
+```
+
+**Claims mapping:**
+
+```typescript
+// In @FrontMcp({ authorities: { ... } })
+authorities: {
+  claimsMapping: {
+    roles: 'realm_access.roles',
+    permissions: 'resource_access.my-client.roles',
+  },
+}
+```
+
+**Notes:**
+
+- Replace `my-client` with your actual Keycloak client ID.
+- Keycloak adds system roles like `offline_access` and `uma_authorization` to `realm_access.roles`. You may want to use `all` instead of `any` in RBAC policies to avoid matching on these.
+- For multi-tenant Keycloak setups, tenant ID is often a custom claim added via a protocol mapper.
+
+## Okta
+
+Okta uses `groups` for role-like claims and `scp` (or `scope`) for permission-like claims. Groups must be explicitly included in the token via an Authorization Server claim configuration.
+
+**Sample JWT payload:**
+
+```json
+{
+  "sub": "00u1a2b3c4d5e6f7g8h9",
+  "groups": ["Admin", "Engineering", "Everyone"],
+  "scp": ["openid", "profile", "users.read", "users.write"],
+  "cid": "0oa1b2c3d4e5f6g7h8",
+  "uid": "00u1a2b3c4d5e6f7g8h9",
+  "iss": "https://myorg.okta.com/oauth2/default"
+}
+```
+
+**Claims mapping:**
+
+```typescript
+// In @FrontMcp({ authorities: { ... } })
+authorities: {
+  claimsMapping: {
+    roles: 'groups',
+    permissions: 'scp',
+  },
+}
+```
+
+**Notes:**
+
+- Groups must be added as a claim to the authorization server. Go to Security > API > Authorization Servers > Claims > Add Claim with value type "Groups" and filter "Matches regex `.*`".
+- `scp` is an array of scope strings. If your Okta config uses `scope` (singular), adjust the path accordingly.
+- Okta does not have a built-in org/tenant claim. For multi-tenant, add a custom claim via a token hook.
+
+## Amazon Cognito
+
+Cognito uses `cognito:groups` for groups and `scope` (space-separated string) for OAuth scopes. Custom attributes use the `custom:` prefix.
+
+**Sample JWT payload:**
+
+```json
+{
+  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "cognito:groups": ["Admins", "PowerUsers"],
+  "scope": "openid profile aws.cognito.signin.user.admin",
+  "custom:tenantId": "tenant-abc",
+  "client_id": "1a2b3c4d5e6f7g8h9i0j",
+  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_AbCdEfG"
+}
+```
+
+**Claims mapping:**
+
+```typescript
+// In @FrontMcp({ authorities: { ... } })
+authorities: {
+  claimsMapping: {
+    roles: 'cognito:groups',
+    permissions: 'scope',
+    tenantId: 'custom:tenantId',
+  },
+}
+```
+
+**Notes:**
+
+- `scope` in Cognito is a space-separated string, not an array. The authorities engine handles this automatically via `toStringArray()`, which splits space-separated strings.
+- `cognito:groups` contains dots in the key name. `resolveDotPath` handles this via direct key lookup.
+- Custom attributes require the `custom:` prefix in both the claim path and the User Pool schema.
+
+## Frontegg
+
+Frontegg places roles and permissions as flat arrays at the top level. Tenant ID is in `tenantId`. The token also includes `tenantIds` (array of all tenant memberships) for multi-tenant scenarios.
+
+**Sample JWT payload:**
+
+```json
+{
+  "sub": "user-uuid-123",
+  "roles": ["Admin", "ReadOnly"],
+  "permissions": ["fe.users.read", "fe.users.write", "fe.tenant.admin"],
+  "tenantId": "tenant-uuid-456",
+  "tenantIds": ["tenant-uuid-456", "tenant-uuid-789"],
+  "email": "jane@example.com",
+  "iss": "https://app-abc.frontegg.com"
+}
+```
+
+**Claims mapping:**
+
+```typescript
+// In @FrontMcp({ authorities: { ... } })
+authorities: {
+  claimsMapping: {
+    roles: 'roles',
+    permissions: 'permissions',
+    tenantId: 'tenantId',
+  },
+}
+```
+
+**Notes:**
+
+- Frontegg tokens have the simplest structure since roles and permissions are flat top-level arrays.
+- The default fallback behavior (no `claimsMapping`) already looks for `roles` and `permissions` at the top level, so Frontegg often works without explicit mapping.
+- For cross-tenant operations, use `tenantIds` (array) instead of `tenantId` (single active tenant).
+
+## Custom IdP / claimsResolver
+
+If your JWT structure does not fit the dot-path model, use `claimsResolver` instead of `claimsMapping`. This gives full programmatic control over claim extraction.
+
+```typescript
+// In @FrontMcp({ authorities: { ... } })
+authorities: {
+  claimsResolver: (authInfo) => {
+    const claims = authInfo?.extra?.authorization?.claims ?? {};
+    const user = authInfo?.user ?? {};
+
+    // Custom extraction logic
+    const roles = (claims['x-custom-roles'] as string || '').split(',').filter(Boolean);
+    const permissions = Array.isArray(claims['x-permissions'])
+      ? claims['x-permissions']
+      : [];
+
+    return {
+      roles,
+      permissions,
+      claims: { ...claims, ...user },
+    };
+  },
+}
+```
+
+**When to use `claimsResolver`:**
+
+- The token has roles encoded as a comma-separated string or bitmask
+- Roles need to be derived from multiple claim fields
+- Permissions require runtime transformation (e.g., wildcard expansion)
+- The token structure is deeply nested or unconventional
+
+`claimsResolver` takes precedence over `claimsMapping` when both are provided.
+
+## Quick Reference Table
+
+| IdP      | Roles Path                | Permissions Path                 | Tenant Path       | Notes                             |
+| -------- | ------------------------- | -------------------------------- | ----------------- | --------------------------------- |
+| Auth0    | `https://myapp.com/roles` | `permissions`                    | `org_id`          | Namespace is developer-defined    |
+| Keycloak | `realm_access.roles`      | `resource_access.<client>.roles` | Custom claim      | Replace `<client>` with client ID |
+| Okta     | `groups`                  | `scp`                            | Custom claim      | Groups must be added as a claim   |
+| Cognito  | `cognito:groups`          | `scope`                          | `custom:tenantId` | `scope` is space-separated        |
+| Frontegg | `roles`                   | `permissions`                    | `tenantId`        | Works with default fallback       |
+
+## Reference
+
+- Type: `AuthoritiesClaimsMapping` in `libs/auth/src/authorities/authorities.profiles.ts`
+- Context builder: `AuthoritiesContextBuilder` in `libs/auth/src/authorities/authorities.context.ts`
+- Related: `references/authority-profiles.md`, `references/rbac-abac-rebac.md`

package/catalog/frontmcp-authorities/references/custom-evaluators.md

@@ -0,0 +1,420 @@
+---
+name: custom-evaluators
+description: Creating and registering custom authority evaluators for domain-specific authorization logic beyond RBAC, ABAC, and ReBAC
+---
+
+# Custom Evaluators
+
+When the built-in RBAC, ABAC, and ReBAC models do not cover your authorization requirements, you can create custom evaluators. Custom evaluators are registered via the `authorities.evaluators` config in `@FrontMcp()` and invoked via the `custom.*` field in policies.
+
+## AuthoritiesEvaluator Interface
+
+Every custom evaluator must implement the `AuthoritiesEvaluator` interface from `@frontmcp/auth`.
+
+```typescript
+import type { AuthoritiesEvaluator, AuthoritiesEvaluationContext, AuthoritiesResult } from '@frontmcp/auth';
+
+interface AuthoritiesEvaluator {
+  /** Evaluator name (must match the key under `custom.*` in policies) */
+  name: string;
+  /** Evaluate the policy against the context */
+  evaluate(policy: unknown, ctx: AuthoritiesEvaluationContext): Promise<AuthoritiesResult>;
+}
+```
+
+The `policy` parameter is whatever value is passed under the evaluator's key in the `custom` field. The `ctx` parameter provides the full evaluation context including user info, input, environment, and the relationship resolver.
+
+The return value must be an `AuthoritiesResult`:
+
+```typescript
+interface AuthoritiesResult {
+  /** Whether access was granted */
+  granted: boolean;
+  /** Human-readable reason for denial */
+  deniedBy?: string;
+  /** List of policy types that were evaluated (for audit) */
+  evaluatedPolicies: string[];
+  /** Optional detailed message */
+  message?: string;
+}
+```
+
+## Registering Custom Evaluators
+
+Custom evaluators are registered in the `evaluators` field of the `authorities` config. The key must match the evaluator's `name` and the key used in `custom.*` policies.
+
+```typescript
+import { FrontMcp } from '@frontmcp/sdk';
+import { ipAllowListEvaluator } from './evaluators/ip-allow-list';
+import { featureFlagEvaluator } from './evaluators/feature-flag';
+import { timeWindowEvaluator } from './evaluators/time-window';
+
+@FrontMcp({
+  name: 'my-server',
+  authorities: {
+    claimsMapping: { roles: 'roles', permissions: 'permissions' },
+    profiles: { admin: { roles: { any: ['admin'] } } },
+    evaluators: {
+      ipAllowList: ipAllowListEvaluator,
+      featureFlag: featureFlagEvaluator,
+      timeWindow: timeWindowEvaluator,
+    },
+  },
+})
+export class MyServer {}
+```
+
+## Async Guards: DB/Redis Lookups
+
+Custom evaluators are **fully async** — use them for database queries, Redis checks, feature flags, or any I/O-bound authorization logic.
+
+### Redis Set Membership
+
+```typescript
+const tenantAllowlistGuard: AuthoritiesEvaluator = {
+  name: 'tenantAllowlist',
+  evaluate: async (policy, ctx) => {
+    const { redisKey } = policy as { redisKey: string };
+    const tenantId = ctx.input['tenantId'] as string;
+    const isAllowed = await redis.sismember(redisKey, tenantId);
+    return {
+      granted: isAllowed,
+      deniedBy: isAllowed ? undefined : `tenant '${tenantId}' not in allowlist`,
+      denial: isAllowed ? undefined : { kind: 'custom', path: 'custom.tenantAllowlist' },
+      evaluatedPolicies: ['custom.tenantAllowlist'],
+    };
+  },
+};
+```
+
+### Database Query
+
+```typescript
+const activeSubscriptionGuard: AuthoritiesEvaluator = {
+  name: 'activeSubscription',
+  evaluate: async (_policy, ctx) => {
+    const row = await db.query('SELECT active FROM subscriptions WHERE user_id = $1', [ctx.user.sub]);
+    const active = row?.active === true;
+    return {
+      granted: active,
+      deniedBy: active ? undefined : 'no active subscription',
+      denial: active ? undefined : { kind: 'custom', path: 'custom.activeSubscription' },
+      evaluatedPolicies: ['custom.activeSubscription'],
+    };
+  },
+};
+```
+
+### Feature Flag
+
+```typescript
+const featureFlagGuard: AuthoritiesEvaluator = {
+  name: 'featureFlag',
+  evaluate: async (policy, ctx) => {
+    const { flag } = policy as { flag: string };
+    const enabled = await featureFlagService.isEnabled(flag, { userId: ctx.user.sub });
+    return {
+      granted: enabled,
+      deniedBy: enabled ? undefined : `feature '${flag}' not enabled`,
+      denial: enabled ? undefined : { kind: 'custom', path: `custom.featureFlag.${flag}` },
+      evaluatedPolicies: [`custom.featureFlag`],
+    };
+  },
+};
+```
+
+### When to Use Custom Evaluators vs Hooks
+
+| Approach                                 | When to Use                                                                          |
+| ---------------------------------------- | ------------------------------------------------------------------------------------ |
+| **Custom evaluator**                     | Reusable async check across many tools — register once, reference via `custom` field |
+| **`Will('checkEntryAuthorities')` hook** | One-off async check for a specific plugin/app, not tied to a specific tool           |
+| **Static `authorities` policy**          | Roles, permissions, attributes — no I/O needed                                       |
+
+## Using Custom Evaluators in Policies
+
+Reference custom evaluators via the `custom` field on any `AuthoritiesPolicyMetadata`. The key under `custom` must match the registered evaluator name.
+
+```typescript
+@Tool({
+  name: 'admin_panel',
+  authorities: {
+    roles: { any: ['admin'] },
+    custom: {
+      ipAllowList: { cidr: ['10.0.0.0/8', '172.16.0.0/12'] },
+    },
+  },
+})
+export default class AdminPanelTool extends ToolContext { ... }
+```
+
+The engine evaluates `custom` evaluators alongside RBAC, ABAC, and ReBAC. They follow the same `operator` semantics (default `'AND'`), so in the example above the user must have the `admin` role AND pass the IP allowlist check.
+
+## Example: IP Allowlist Evaluator
+
+Restricts access to requests from specific CIDR ranges.
+
+```typescript
+// evaluators/ip-allow-list.ts
+import type { AuthoritiesEvaluator, AuthoritiesEvaluationContext, AuthoritiesResult } from '@frontmcp/auth';
+
+interface IpAllowListPolicy {
+  cidr: string[];
+}
+
+function isInCidr(ip: string, cidr: string): boolean {
+  // Simplified -- use a library like 'ip-cidr' in production
+  const [subnet, bits] = cidr.split('/');
+  if (!bits) return ip === subnet;
+  // ... full CIDR matching logic
+  return false;
+}
+
+export const ipAllowListEvaluator: AuthoritiesEvaluator = {
+  name: 'ipAllowList',
+  async evaluate(policy: unknown, ctx: AuthoritiesEvaluationContext): Promise<AuthoritiesResult> {
+    const { cidr } = policy as IpAllowListPolicy;
+    const remoteIp = ctx.env['remoteIp'] as string | undefined;
+
+    if (!remoteIp) {
+      return {
+        granted: false,
+        deniedBy: 'custom.ipAllowList: remoteIp not available in env',
+        evaluatedPolicies: ['custom.ipAllowList'],
+      };
+    }
+
+    const allowed = cidr.some((c) => isInCidr(remoteIp, c));
+
+    return {
+      granted: allowed,
+      deniedBy: allowed ? undefined : `custom.ipAllowList: ${remoteIp} not in allowed CIDR ranges`,
+      evaluatedPolicies: ['custom.ipAllowList'],
+    };
+  },
+};
+```
+
+**Usage:**
+
+```typescript
+@Tool({
+  name: 'internal_admin',
+  authorities: {
+    custom: {
+      ipAllowList: { cidr: ['10.0.0.0/8', '192.168.0.0/16'] },
+    },
+  },
+})
+export default class InternalAdminTool extends ToolContext { ... }
+```
+
+## Example: Feature Flag Evaluator
+
+Gates access behind a feature flag service.
+
+```typescript
+// evaluators/feature-flag.ts
+import type { AuthoritiesEvaluator, AuthoritiesEvaluationContext, AuthoritiesResult } from '@frontmcp/auth';
+
+interface FeatureFlagPolicy {
+  flag: string;
+  /** If true, the flag must be disabled for access (inverse gate) */
+  inverse?: boolean;
+}
+
+// Assume a global feature flag client is available
+declare const featureFlags: { isEnabled(flag: string, userId: string): Promise<boolean> };
+
+export const featureFlagEvaluator: AuthoritiesEvaluator = {
+  name: 'featureFlag',
+  async evaluate(policy: unknown, ctx: AuthoritiesEvaluationContext): Promise<AuthoritiesResult> {
+    const { flag, inverse } = policy as FeatureFlagPolicy;
+    const enabled = await featureFlags.isEnabled(flag, ctx.user.sub);
+    const granted = inverse ? !enabled : enabled;
+
+    return {
+      granted,
+      deniedBy: granted
+        ? undefined
+        : `custom.featureFlag: '${flag}' is ${enabled ? 'enabled' : 'disabled'} (inverse=${!!inverse})`,
+      evaluatedPolicies: ['custom.featureFlag'],
+    };
+  },
+};
+```
+
+**Usage:**
+
+```typescript
+@Tool({
+  name: 'beta_feature',
+  authorities: {
+    custom: {
+      featureFlag: { flag: 'beta-tools-v2' },
+    },
+  },
+})
+export default class BetaFeatureTool extends ToolContext { ... }
+```
+
+## Example: Time Window Evaluator
+
+Restricts access to specific time windows (e.g., business hours only).
+
+```typescript
+// evaluators/time-window.ts
+import type { AuthoritiesEvaluator, AuthoritiesEvaluationContext, AuthoritiesResult } from '@frontmcp/auth';
+
+interface TimeWindowPolicy {
+  /** Allowed days (0=Sunday, 6=Saturday) */
+  days: number[];
+  /** Start hour (0-23, inclusive) */
+  startHour: number;
+  /** End hour (0-23, exclusive) */
+  endHour: number;
+  /** IANA timezone (default: UTC) */
+  timezone?: string;
+}
+
+export const timeWindowEvaluator: AuthoritiesEvaluator = {
+  name: 'timeWindow',
+  async evaluate(policy: unknown, ctx: AuthoritiesEvaluationContext): Promise<AuthoritiesResult> {
+    const { days, startHour, endHour, timezone } = policy as TimeWindowPolicy;
+    const now = new Date();
+    const formatter = new Intl.DateTimeFormat('en-US', {
+      timeZone: timezone ?? 'UTC',
+      hour: 'numeric',
+      hour12: false,
+      weekday: 'short',
+    });
+
+    const parts = formatter.formatToParts(now);
+    const hour = parseInt(parts.find((p) => p.type === 'hour')?.value ?? '0', 10);
+    // Get day of week in the configured timezone (not local system timezone)
+    const dayName = new Intl.DateTimeFormat('en-US', { timeZone: timezone ?? 'UTC', weekday: 'long' }).format(now);
+    const dayIndex = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'].indexOf(dayName);
+
+    const dayAllowed = days.includes(dayIndex);
+    const hourAllowed = hour >= startHour && hour < endHour;
+    const granted = dayAllowed && hourAllowed;
+
+    return {
+      granted,
+      deniedBy: granted ? undefined : `custom.timeWindow: current time outside allowed window`,
+      evaluatedPolicies: ['custom.timeWindow'],
+    };
+  },
+};
+```
+
+**Usage:**
+
+```typescript
+@Tool({
+  name: 'payroll_sync',
+  authorities: {
+    roles: { any: ['finance'] },
+    custom: {
+      timeWindow: {
+        days: [1, 2, 3, 4, 5],  // Monday through Friday
+        startHour: 9,
+        endHour: 17,
+        timezone: 'America/New_York',
+      },
+    },
+  },
+})
+export default class PayrollSyncTool extends ToolContext { ... }
+```
+
+## Example: Rate Limit Evaluator
+
+Denies access when a per-user rate limit is exceeded.
+
+```typescript
+// evaluators/rate-limit.ts
+import type { AuthoritiesEvaluator, AuthoritiesEvaluationContext, AuthoritiesResult } from '@frontmcp/auth';
+
+interface RateLimitPolicy {
+  /** Maximum calls allowed */
+  max: number;
+  /** Time window in seconds */
+  windowSeconds: number;
+}
+
+// In-memory counter (use Redis in production)
+const counters = new Map<string, { count: number; resetAt: number }>();
+
+export const rateLimitEvaluator: AuthoritiesEvaluator = {
+  name: 'rateLimit',
+  async evaluate(policy: unknown, ctx: AuthoritiesEvaluationContext): Promise<AuthoritiesResult> {
+    const { max, windowSeconds } = policy as RateLimitPolicy;
+    const key = `${ctx.user.sub}`;
+    const now = Date.now();
+
+    let entry = counters.get(key);
+    if (!entry || now > entry.resetAt) {
+      entry = { count: 0, resetAt: now + windowSeconds * 1000 };
+      counters.set(key, entry);
+    }
+
+    entry.count++;
+
+    if (entry.count > max) {
+      return {
+        granted: false,
+        deniedBy: `custom.rateLimit: ${entry.count}/${max} calls in window`,
+        evaluatedPolicies: ['custom.rateLimit'],
+      };
+    }
+
+    return {
+      granted: true,
+      evaluatedPolicies: ['custom.rateLimit'],
+    };
+  },
+};
+```
+
+## Combining Custom Evaluators with Built-in Models
+
+Custom evaluators participate in the same combinator system as RBAC, ABAC, and ReBAC.
+
+```typescript
+// Admin from allowed IP during business hours
+authorities: {
+  allOf: [
+    { roles: { any: ['admin'] } },
+    { custom: { ipAllowList: { cidr: ['10.0.0.0/8'] } } },
+    { custom: { timeWindow: { days: [1, 2, 3, 4, 5], startHour: 9, endHour: 17 } } },
+  ],
+}
+
+// Feature flag OR admin bypass
+authorities: {
+  anyOf: [
+    { roles: { any: ['admin'] } },
+    { custom: { featureFlag: { flag: 'new-dashboard' } } },
+  ],
+}
+```
+
+## Best Practices
+
+| Practice                                | Description                                                                         |
+| --------------------------------------- | ----------------------------------------------------------------------------------- |
+| Always return `evaluatedPolicies`       | Include `custom.<name>` in the array for audit trail                                |
+| Provide descriptive `deniedBy`          | Include the evaluator name, the failing condition, and relevant values              |
+| Keep evaluators stateless when possible | Use external stores (Redis, database) for state; avoid in-memory maps in production |
+| Type the policy parameter               | Cast `policy as YourPolicyType` at the top of `evaluate()`                          |
+| Handle missing context gracefully       | Return denial with a clear message if expected env/input values are absent          |
+| Test evaluators in isolation            | Each evaluator is a plain object; test `evaluate()` directly with mock contexts     |
+| Name evaluators with camelCase          | The name must match both the registered key and the `custom.*` policy key           |
+
+## Reference
+
+- Type: `AuthoritiesEvaluator` in `libs/auth/src/authorities/authorities.types.ts`
+- Registry: `AuthoritiesEvaluatorRegistry` in `libs/auth/src/authorities/authorities.registry.ts`
+- Engine dispatch: `evaluateCustom()` in `libs/auth/src/authorities/authorities.engine.ts`
+- Related: `references/authority-profiles.md`, `references/rbac-abac-rebac.md`