@classytic/arc 2.9.1 → 2.10.3

package/dist/{index-C-xjcA6F.d.mts → index-ChIw3776.d.mts}

@@ -1,6 +1,6 @@
 import { r as RequestScope } from "./types-BD85MlEK.mjs";
-import { n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-DZi1aYhm.mjs";
-import { i as CacheStore, t as CacheLogger } from "./interface-DplgQO2e.mjs";
+import { c as PermissionCheck, l as PermissionContext, u as PermissionResult } from "./fields-Lo1VUDpt.mjs";
+import { r as CacheStore, t as CacheLogger } from "./interface-D218ikEo.mjs";
 import { FastifyRequest } from "fastify";
 
 //#region src/permissions/applyPermissionResult.d.ts
@@ -36,161 +36,9 @@ type RequestSink = FastifyRequest & {
  */
 declare function applyPermissionResult(result: PermissionResult, request: RequestSink): void;
 //#endregion
-//#region src/permissions/roleHierarchy.d.ts
-/**
- * Role Hierarchy — Composable RBAC Inheritance
- *
- * Expands roles based on an inheritance map. Apply at scope-building time
- * so that requireRoles() works with the already-expanded list.
- *
- * @example
- * ```typescript
- * import { createRoleHierarchy } from '@classytic/arc/permissions';
- *
- * const hierarchy = createRoleHierarchy({
- *   superadmin: ['admin'],
- *   admin: ['branch_manager'],
- *   branch_manager: ['member'],
- * });
- *
- * // When building scope:
- * const expandedRoles = hierarchy.expand(user.roles);
- * // ['superadmin'] → ['superadmin', 'admin', 'branch_manager', 'member']
- *
- * // Check inclusion:
- * hierarchy.includes(['admin'], 'branch_manager'); // true (admin inherits branch_manager)
- * hierarchy.includes(['member'], 'admin');          // false (child doesn't inherit parent)
- * ```
- */
-interface RoleHierarchy {
-  /** Expand roles to include all inherited (child) roles. Deduplicated. */
-  expand(roles: readonly string[]): string[];
-  /** Check if any of the user's roles (expanded) include the required role. */
-  includes(userRoles: readonly string[], requiredRole: string): boolean;
-}
-/**
- * Create a role hierarchy from a parent → children map.
- *
- * Each key is a parent role, each value is the array of roles it inherits.
- * Inheritance is transitive: if A → B and B → C, then A expands to [A, B, C].
- * Circular references are handled safely (visited set).
- */
-declare function createRoleHierarchy(map: Record<string, readonly string[]>): RoleHierarchy;
-declare namespace presets_d_exports {
-  export { adminOnly, authenticated, fullPublic, ownerWithAdminBypass, publicRead, publicReadAdminWrite, readOnly };
-}
-/**
- * ResourcePermissions shape — matches the type in types/index.ts
- */
-interface ResourcePermissions<TDoc = any> {
-  list?: PermissionCheck<TDoc>;
-  get?: PermissionCheck<TDoc>;
-  create?: PermissionCheck<TDoc>;
-  update?: PermissionCheck<TDoc>;
-  delete?: PermissionCheck<TDoc>;
-}
-type PermissionOverrides<TDoc = any> = Partial<ResourcePermissions<TDoc>>;
-/**
- * Public read, authenticated write.
- * list + get = allowPublic(), create + update + delete = requireAuth()
- */
-declare function publicRead<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-/**
- * Public read, admin write.
- * list + get = allowPublic(), create + update + delete = requireRoles(['admin'])
- */
-declare function publicReadAdminWrite<TDoc = any>(roles?: readonly string[], overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-/**
- * All operations require authentication.
- */
-declare function authenticated<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-/**
- * All operations require specific roles.
- * @param roles - Required roles (user needs at least one). Default: ['admin']
- */
-declare function adminOnly<TDoc = any>(roles?: readonly string[], overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-/**
- * Owner-scoped with admin bypass.
- * list = auth (scoped to owner), get = auth, create = auth,
- * update + delete = ownership check with admin bypass.
- *
- * @param ownerField - Field containing owner ID (default: 'userId')
- * @param bypassRoles - Roles that bypass ownership check (default: ['admin'])
- */
-declare function ownerWithAdminBypass<TDoc = any>(ownerField?: Extract<keyof TDoc, string> | string, bypassRoles?: readonly string[], overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-/**
- * Full public access — no auth required for any operation.
- * Use sparingly (dev/testing, truly public APIs).
- */
-declare function fullPublic<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-/**
- * Read-only: list + get authenticated, write operations denied.
- * Useful for computed/derived resources.
- */
-declare function readOnly<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-//#endregion
-//#region src/permissions/index.d.ts
-interface DynamicPermissionMatrixConfig {
-  /**
-   * Resolve role → resource → actions map dynamically (DB/API/config service).
-   * Called at permission-check time (or cache miss if cache enabled).
-   */
-  resolveRolePermissions: (ctx: PermissionContext) => Record<string, Record<string, readonly string[]>> | Promise<Record<string, Record<string, readonly string[]>>>;
-  /**
-   * Optional cache store adapter.
-   * Use MemoryCacheStore for single-instance apps or RedisCacheStore for distributed setups.
-   */
-  cacheStore?: CacheStore<Record<string, Record<string, readonly string[]>>>;
-  /** Optional logger for cache/runtime failures (default: console) */
-  logger?: CacheLogger;
-  /**
-   * Legacy convenience in-memory cache config.
-   * If `cacheStore` is not provided and ttlMs > 0, Arc creates an internal MemoryCacheStore.
-   */
-  cache?: {
-    /** Cache TTL in milliseconds */ttlMs: number; /** Optional custom cache key builder */
-    key?: (ctx: PermissionContext) => string | null | undefined; /** Hard entry cap for internal memory store (default: 1000) */
-    maxEntries?: number;
-  };
-}
-/** Minimal publish/subscribe interface for cross-node cache invalidation. */
-interface PermissionEventBus {
-  publish: <T>(type: string, payload: T) => Promise<void>;
-  subscribe: (pattern: string, handler: (event: {
-    payload: unknown;
-  }) => void | Promise<void>) => Promise<(() => void) | undefined>;
-}
-interface ConnectEventsOptions {
-  /** Called on remote invalidation for app-specific cleanup (e.g., resolver cache) */
-  onRemoteInvalidation?: (orgId: string) => void | Promise<void>;
-  /** Custom event type (default: 'arc.permissions.invalidated') */
-  eventType?: string;
-}
-interface DynamicPermissionMatrix {
-  can: (permissions: Record<string, readonly string[]>) => PermissionCheck;
-  canAction: (resource: string, action: string) => PermissionCheck;
-  requireRole: (...roles: string[]) => PermissionCheck;
-  requireMembership: () => PermissionCheck;
-  requireTeamMembership: () => PermissionCheck;
-  /** Invalidate cached permissions for a specific organization */
-  invalidateByOrg: (orgId: string) => Promise<void>;
-  clearCache: () => Promise<void>;
-  /**
-   * Connect to an event system for cross-node cache invalidation.
-   *
-   * Late-binding: call after the event plugin is registered (e.g., in onReady hook).
-   * Once connected, `invalidateByOrg()` auto-publishes an event, and incoming
-   * events from other nodes trigger local cache invalidation.
-   * Echo is suppressed via per-process nodeId matching.
-   */
-  connectEvents(events: PermissionEventBus, options?: ConnectEventsOptions): Promise<void>;
-  /** Disconnect from the event system. Safe to call even if never connected. */
-  disconnectEvents(): Promise<void>;
-  /** Whether events are currently connected. */
-  readonly eventsConnected: boolean;
-}
+//#region src/permissions/core.d.ts
 /**
- * Allow public access (no authentication required)
+ * Allow public access (no authentication required).
  *
  * @example
  * ```typescript
@@ -202,7 +50,7 @@ interface DynamicPermissionMatrix {
  */
 declare function allowPublic(): PermissionCheck;
 /**
- * Require authentication (any authenticated user)
+ * Require authentication (any authenticated user).
  *
  * @example
  * ```typescript
@@ -213,48 +61,23 @@ declare function allowPublic(): PermissionCheck;
  * ```
  */
 declare function requireAuth(): PermissionCheck;
-/**
- * Require specific roles
- *
- * @param roles - Required roles (user needs at least one)
- * @param options - Optional bypass roles
- *
- * @example
- * ```typescript
- * permissions: {
- *   create: requireRoles(['admin', 'editor']),
- *   delete: requireRoles(['admin']),
- * }
- *
- * // With bypass roles
- * permissions: {
- *   update: requireRoles(['owner'], { bypassRoles: ['admin', 'superadmin'] }),
- * }
- * ```
- */
 /**
  * Require one of the specified roles. Checks BOTH platform roles
  * (`user.role`) AND organization roles (`scope.orgRoles`) by default —
  * passing in either layer grants access. Elevated scope always passes.
  *
  * Accepts EITHER variadic strings OR a single readonly array — both forms
- * produce identical behavior. Use whichever reads better at the call site.
+ * produce identical behavior.
  *
  * @example
  * ```typescript
- * requireRoles('admin')                       // single role, variadic
- * requireRoles('admin', 'editor')             // multiple roles, variadic
- * requireRoles(['admin', 'editor'])           // array form
- * requireRoles(['admin'], { bypassRoles: ['superadmin'] })   // with options
- * requireRoles(['admin'], { includeOrgRoles: false })        // platform-only
+ * requireRoles('admin')
+ * requireRoles('admin', 'editor')
+ * requireRoles(['admin', 'editor'])
+ * requireRoles(['admin'], { bypassRoles: ['superadmin'] })
+ * requireRoles(['admin'], { includeOrgRoles: false })  // platform-only
  * ```
  *
- * **2.7.1 BREAKING CHANGE:** `includeOrgRoles` now defaults to `true`. The
- * old default (`false`, platform-only) was a footgun for the common case of
- * Better Auth's organization plugin where roles like 'admin' are assigned at
- * the org level. To restore the old behavior explicitly, pass
- * `{ includeOrgRoles: false }`.
- *
  * For org-only role checks, prefer `requireOrgRole('admin')`.
  */
 declare function requireRoles(role: string, ...rest: string[]): PermissionCheck;
@@ -262,45 +85,19 @@ declare function requireRoles(roles: readonly string[], options?: {
   bypassRoles?: readonly string[];
   /**
    * Also check org membership roles (`scope.orgRoles`) when in org context.
-   * Default: `true` (changed in 2.7.1).
-   *
-   * Set to `false` to restore the pre-2.7.1 behavior of checking only
-   * platform roles (`user.role`). For org-only role checks, prefer
-   * `requireOrgRole('admin')` instead.
+   * Default: `true`. Set to `false` to check only platform roles.
    */
   includeOrgRoles?: boolean;
 }): PermissionCheck;
 /**
- * **Alias of `requireRoles()`** — checks both platform roles AND org roles.
- *
- * Since 2.7.1, `requireRoles()` defaults to `includeOrgRoles: true`, which
- * means `roles('admin')` and `requireRoles('admin')` are now functionally
- * identical. This helper is preserved for backwards compatibility and for
- * call sites that prefer the shorter `roles()` name.
- *
- * **For new code, prefer `requireRoles()`** — it's the canonical name and
- * matches the rest of the `requireXxx()` family (`requireAuth`, `requireOwnership`,
- * `requireOrgRole`, etc.).
- *
- * For platform-only checks: `requireRoles(['admin'], { includeOrgRoles: false })`
- * For org-only checks: `requireOrgRole('admin')`
- *
- * @example
- * ```typescript
- * // These are identical:
- * roles('admin', 'editor')
- * requireRoles('admin', 'editor')
- * requireRoles(['admin', 'editor'])
- * ```
+ * Short-form alias of `requireRoles()`. Identical behavior — checks both
+ * platform roles AND org roles. Prefer `requireRoles` for new code; this
+ * exists for call sites that want a terser name.
  */
 declare function roles(...args: string[] | [readonly string[]]): PermissionCheck;
 /**
- * Require resource ownership
- *
- * Returns filters to scope queries to user's owned resources.
- *
- * @param ownerField - Field containing owner ID (default: 'userId')
- * @param options - Optional bypass roles
+ * Require resource ownership. Returns filters to scope queries to the
+ * caller's owned resources.
  *
  * @example
  * ```typescript
@@ -314,65 +111,62 @@ declare function requireOwnership<TDoc = Record<string, unknown>>(ownerField?: E
   bypassRoles?: readonly string[];
 }): PermissionCheck<TDoc>;
 /**
- * Combine multiple checks - ALL must pass (AND logic).
+ * Combine multiple checks — ALL must pass (AND logic).
  *
  * Each child runs against the **accumulated** state of previous children:
- *   - `filters` from earlier children are merged into the next child's
- *     `_policyFilters` (so e.g. `requireOwnership` sees row-level scoping)
- *   - `scope` from earlier children is installed on the request before the
- *     next child runs (so e.g. `requireOrgMembership` after `requireApiKey`
- *     sees the service scope from the API key check)
+ *   - `filters` from earlier children merge into the next child's `_policyFilters`
+ *   - `scope` from earlier children installs on the request before the next child runs
  *
- * The final returned `PermissionResult` carries both the merged `filters` AND
- * the merged `scope`, so the outer middleware's `applyPermissionResult` call
- * sees the same end-state.
+ * The final result carries both merged `filters` and merged `scope`.
  *
  * @example
  * ```typescript
- * // CRUD permissions composed across roles + ownership
- * permissions: {
- *   update: allOf(
- *     requireAuth(),
- *     requireRoles(['editor']),
- *     requireOwnership('createdBy')
- *   ),
- * }
- *
- * // Custom auth + org membership — first check installs the scope,
- * // second check reads it.
  * permissions: {
+ *   update: allOf(requireAuth(), requireRoles(['editor']), requireOwnership('createdBy')),
  *   list: allOf(requireApiKey(), requireOrgMembership()),
  * }
  * ```
  */
 declare function allOf(...checks: PermissionCheck[]): PermissionCheck;
 /**
- * Combine multiple checks - ANY must pass (OR logic)
+ * Combine multiple checks — ANY must pass (OR logic).
  *
  * @example
  * ```typescript
  * permissions: {
- *   update: anyOf(
- *     requireRoles(['admin']),
- *     requireOwnership('createdBy')
- *   ),
+ *   update: anyOf(requireRoles(['admin']), requireOwnership('createdBy')),
  * }
  * ```
  */
 declare function anyOf(...checks: PermissionCheck[]): PermissionCheck;
 /**
- * Deny all access
+ * Invert a permission check. Grants when the wrapped check denies, denies
+ * when the wrapped check grants. Useful for "block if X" patterns —
+ * e.g. `not(requireRoles(['guest']))` to deny guest access.
+ *
+ * NOTE: filters and scope from the wrapped check are intentionally
+ * discarded — an inverted check has no row-level meaning.
  *
  * @example
  * ```typescript
  * permissions: {
- *   delete: denyAll('Deletion not allowed'),
+ *   internalApi: not(requireRoles(['external'])),
+ *   adminUI: allOf(requireAuth(), not(requireRoles(['readonly']))),
  * }
  * ```
  */
+declare function not(check: PermissionCheck, reason?: string): PermissionCheck;
+/**
+ * Deny all access.
+ *
+ * @example
+ * ```typescript
+ * permissions: { delete: denyAll('Deletion not allowed') }
+ * ```
+ */
 declare function denyAll(reason?: string): PermissionCheck;
 /**
- * Dynamic permission based on context
+ * Dynamic permission based on a condition function.
  *
  * @example
  * ```typescript
@@ -382,54 +176,187 @@ declare function denyAll(reason?: string): PermissionCheck;
  * ```
  */
 declare function when<TDoc = Record<string, unknown>>(condition: (ctx: PermissionContext<TDoc>) => boolean | Promise<boolean>): PermissionCheck<TDoc>;
+//#endregion
+//#region src/permissions/dynamic.d.ts
+interface DynamicPermissionMatrixConfig {
+  /**
+   * Resolve role → resource → actions map dynamically (DB / API / config service).
+   * Called at permission-check time (or cache miss when cache enabled).
+   */
+  resolveRolePermissions: (ctx: PermissionContext) => Record<string, Record<string, readonly string[]>> | Promise<Record<string, Record<string, readonly string[]>>>;
+  /**
+   * Optional cache store adapter. Use MemoryCacheStore for single-instance
+   * apps, RedisCacheStore for distributed setups.
+   */
+  cacheStore?: CacheStore<Record<string, Record<string, readonly string[]>>>;
+  /** Optional logger for cache/runtime failures (default: console). */
+  logger?: CacheLogger;
+  /**
+   * Convenience in-memory cache config. If `cacheStore` is not provided
+   * and `ttlSeconds > 0`, Arc creates an internal MemoryCacheStore.
+   */
+  cache?: {
+    /** Cache TTL in seconds */ttlSeconds: number; /** Optional custom cache key builder */
+    key?: (ctx: PermissionContext) => string | null | undefined; /** Hard entry cap for internal memory store (default: 1000) */
+    maxEntries?: number;
+  };
+}
+/** Minimal publish/subscribe interface for cross-node cache invalidation. */
+interface PermissionEventBus {
+  publish: <T>(type: string, payload: T) => Promise<void>;
+  subscribe: (pattern: string, handler: (event: {
+    payload: unknown;
+  }) => void | Promise<void>) => Promise<(() => void) | undefined>;
+}
+interface ConnectEventsOptions {
+  /** Called on remote invalidation for app-specific cleanup (e.g. resolver cache). */
+  onRemoteInvalidation?: (orgId: string) => void | Promise<void>;
+  /** Custom event type (default: 'arc.permissions.invalidated'). */
+  eventType?: string;
+}
+interface DynamicPermissionMatrix {
+  can: (permissions: Record<string, readonly string[]>) => PermissionCheck;
+  canAction: (resource: string, action: string) => PermissionCheck;
+  requireRole: (...roles: string[]) => PermissionCheck;
+  requireMembership: () => PermissionCheck;
+  requireTeamMembership: () => PermissionCheck;
+  /** Invalidate cached permissions for a specific organization. */
+  invalidateByOrg: (orgId: string) => Promise<void>;
+  clearCache: () => Promise<void>;
+  /**
+   * Connect to an event system for cross-node cache invalidation.
+   *
+   * Late-binding: call after the event plugin is registered (e.g. in an
+   * `onReady` hook). Once connected, `invalidateByOrg()` auto-publishes an
+   * event, and incoming events from other nodes trigger local cache
+   * invalidation. Echo is suppressed via per-process nodeId matching.
+   */
+  connectEvents(events: PermissionEventBus, options?: ConnectEventsOptions): Promise<void>;
+  /** Disconnect from the event system. Safe to call even if never connected. */
+  disconnectEvents(): Promise<void>;
+  /** Whether events are currently connected. */
+  readonly eventsConnected: boolean;
+}
 /**
- * Require an org-bound caller. Grants access for any scope kind that
- * carries org context: `member` (human user with org membership), `service`
- * (API key bound to an org), or `elevated` (platform admin). Denies for
- * `public` and `authenticated` scopes (no org context).
+ * Create a static role × resource × action permission system. Compile-time
+ * matrix — use when role mappings are known at build time and don't change
+ * per-deployment.
  *
- * This is the canonical "is the caller acting inside an org" check, and the
- * usual partner for `multiTenantPreset` — if a route is multi-tenant
- * filtered, you almost always want this gate too.
+ * @example
+ * ```typescript
+ * const perms = createOrgPermissions({
+ *   statements: {
+ *     product: ['create', 'update', 'delete'],
+ *     order: ['create', 'approve'],
+ *   },
+ *   roles: {
+ *     owner: { product: ['create', 'update', 'delete'], order: ['create', 'approve'] },
+ *     admin: { product: ['create', 'update'], order: ['create'] },
+ *     member: { product: [], order: [] },
+ *   },
+ * });
  *
- * Reads `request.scope` set by auth adapters or by upstream permission
- * checks via `PermissionResult.scope` (e.g. a custom `requireApiKey()`).
+ * defineResource({
+ *   permissions: {
+ *     create: perms.can({ product: ['create'] }),
+ *     delete: perms.can({ product: ['delete'] }),
+ *   }
+ * });
+ * ```
+ */
+declare function createOrgPermissions(config: {
+  statements: Record<string, readonly string[]>;
+  roles: Record<string, Record<string, readonly string[]>>;
+}): {
+  can: (permissions: Record<string, string[]>) => PermissionCheck;
+  requireRole: (...roles: string[]) => PermissionCheck;
+  requireMembership: () => PermissionCheck;
+  requireTeamMembership: () => PermissionCheck;
+};
+/**
+ * Create a dynamic role-based permission matrix. Use when role/action
+ * mappings are managed outside code (admin UI, DB-stored ACLs, remote
+ * policy service).
+ *
+ * Supports:
+ * - Org role union (any assigned org role can grant)
+ * - Global bypass roles
+ * - Wildcard resource/action (`*`)
+ * - Optional in-memory or distributed cache
+ * - Cross-node invalidation via the event bus
+ */
+declare function createDynamicPermissionMatrix(config: DynamicPermissionMatrixConfig): DynamicPermissionMatrix;
+//#endregion
+//#region src/permissions/roleHierarchy.d.ts
+/**
+ * Role Hierarchy — Composable RBAC Inheritance
+ *
+ * Expands roles based on an inheritance map. Apply at scope-building time
+ * so that requireRoles() works with the already-expanded list.
  *
  * @example
  * ```typescript
- * permissions: {
- *   list: requireOrgMembership(),
- *   get: requireOrgMembership(),
+ * import { createRoleHierarchy } from '@classytic/arc/permissions';
  *
- *   // Composed with an OAuth-style scope check for API-key callers
- *   create: allOf(requireOrgMembership(), requireServiceScope('jobs:write')),
- * }
+ * const hierarchy = createRoleHierarchy({
+ *   superadmin: ['admin'],
+ *   admin: ['branch_manager'],
+ *   branch_manager: ['member'],
+ * });
+ *
+ * // When building scope:
+ * const expandedRoles = hierarchy.expand(user.roles);
+ * // ['superadmin'] → ['superadmin', 'admin', 'branch_manager', 'member']
+ *
+ * // Check inclusion:
+ * hierarchy.includes(['admin'], 'branch_manager'); // true (admin inherits branch_manager)
+ * hierarchy.includes(['member'], 'admin');          // false (child doesn't inherit parent)
  * ```
  */
-declare function requireOrgMembership<TDoc = Record<string, unknown>>(): PermissionCheck<TDoc>;
+interface RoleHierarchy {
+  /** Expand roles to include all inherited (child) roles. Deduplicated. */
+  expand(roles: readonly string[]): string[];
+  /** Check if any of the user's roles (expanded) include the required role. */
+  includes(userRoles: readonly string[], requiredRole: string): boolean;
+}
 /**
- * Require specific org-level roles.
- * Reads `request.scope.orgRoles` (set by auth adapters).
- * Elevated scope always passes (platform admin bypass).
+ * Create a role hierarchy from a parent → children map.
  *
- * **Service scopes (API keys) always fail this check** — services don't
- * carry user-style org roles, only OAuth-style `scopes` strings. For routes
- * that should accept BOTH human admins AND API keys, compose explicitly:
+ * Each key is a parent role, each value is the array of roles it inherits.
+ * Inheritance is transitive: if A → B and B → C, then A expands to [A, B, C].
+ * Circular references are handled safely (visited set).
+ */
+declare function createRoleHierarchy(map: Record<string, readonly string[]>): RoleHierarchy;
+//#endregion
+//#region src/permissions/scope.d.ts
+/**
+ * Require an org-bound caller. Grants for `member`, `service`, and
+ * `elevated` scopes (anything with org context). Denies `public` and
+ * `authenticated` (no org context).
  *
+ * Canonical "is the caller acting inside an org" check. Usual partner for
+ * `multiTenantPreset` — if a route filters by tenant, you almost always
+ * want this gate too.
+ *
+ * @example
  * ```typescript
  * permissions: {
- *   create: anyOf(
- *     requireOrgRole('admin'),                       // human path
- *     requireServiceScope('jobs:write'),             // machine path
- *   ),
+ *   list: requireOrgMembership(),
+ *   create: allOf(requireOrgMembership(), requireServiceScope('jobs:write')),
  * }
  * ```
+ */
+declare function requireOrgMembership<TDoc = Record<string, unknown>>(): PermissionCheck<TDoc>;
+/**
+ * Require specific org-level roles. Reads `request.scope.orgRoles`.
+ * Elevated scope always passes (platform admin bypass).
  *
- * This separation is intentional — implicit "API key bypasses role checks"
- * is the kind of footgun that ships data breaches. Services must opt into
- * specific scopes the same way OAuth clients do.
- *
- * @param roles - Required org roles (user needs at least one)
+ * **Service scopes (API keys) always fail this check** — services don't
+ * carry user-style org roles, only OAuth-style `scopes` strings. For
+ * routes that should accept BOTH human admins AND API keys, compose with
+ * `anyOf(requireOrgRole(...), requireServiceScope(...))`. The implicit
+ * "API key bypasses role check" path is intentionally NOT supported —
+ * it's the kind of footgun that ships data breaches.
  *
  * @example
  * ```typescript
@@ -442,89 +369,49 @@ declare function requireOrgMembership<TDoc = Record<string, unknown>>(): Permiss
 declare function requireOrgRole<TDoc = Record<string, unknown>>(...args: string[] | [readonly string[]]): PermissionCheck<TDoc>;
 /**
  * Require specific OAuth-style scope strings on a service (API key) identity.
- *
- * Reads `request.scope.scopes` — only populated when the scope kind is
- * `service`. Mirrors how OAuth 2.0 / Better Auth's apiKey plugin / API
- * gateways express machine permissions: a comma- or array-encoded list of
- * scope strings like `'jobs:read'`, `'jobs:write'`, `'memories:*'`.
+ * Reads `request.scope.scopes` (only present when `scope.kind === 'service'`).
  *
  * **Pass behavior:**
- * - `service` scope where `scopes` contains ANY of the required strings → grant
- * - `elevated` scope (platform admin) → grant
+ * - `service` scope where `scopes` contains ANY required string → grant
+ * - `elevated` scope → grant
  * - Anything else → deny with a clear reason
  *
- * Notably this does **not** grant for `member` scopes — humans go through
- * `requireOrgRole`. For routes that should accept both, compose with `anyOf`:
- *
- * ```typescript
- * permissions: {
- *   create: anyOf(
- *     requireOrgRole('admin'),
- *     requireServiceScope('jobs:write'),
- *   ),
- * }
- * ```
- *
- * @param scopes - Required scope strings (caller needs at least one)
+ * Does **not** grant for `member` scopes — humans go through `requireOrgRole`.
+ * For routes that should accept both, compose with `anyOf`.
  *
  * @example
  * ```typescript
- * // Variadic
  * requireServiceScope('jobs:write')
  * requireServiceScope('jobs:read', 'jobs:write')
- *
- * // Array
  * requireServiceScope(['jobs:read', 'jobs:write'])
  *
- * // Composed with org membership for org-scoped API keys
  * permissions: {
  *   list: allOf(requireOrgMembership(), requireServiceScope('jobs:read')),
- *   create: allOf(requireOrgMembership(), requireServiceScope('jobs:write')),
  * }
  * ```
  */
 declare function requireServiceScope<TDoc = Record<string, unknown>>(...args: string[] | [readonly string[]]): PermissionCheck<TDoc>;
 /**
- * Require app-defined scope context dimensions (branch, project, department,
- * region, workspace, etc.) on the current request.
- *
- * Reads `request.scope.context` (a `Readonly<Record<string, string>>` slot
- * available on `member`, `service`, and `elevated` scope kinds). Arc takes
- * no position on what dimensions you use — you set them, you check them.
+ * Require app-defined scope context dimensions (branch, project, region,
+ * workspace, …) on the request. Arc takes no position on what dimensions
+ * you use — your auth function populates `scope.context`, your routes
+ * gate on it.
  *
  * **Three call shapes:**
- *
  * ```typescript
- * // 1. Presence check — key must exist on scope.context
- * requireScopeContext('branchId')
- *
- * // 2. Value match — key must equal a specific string
- * requireScopeContext('branchId', 'eng-paris')
- *
- * // 3. Multi-key (object form, AND semantics) — every key must match
- * requireScopeContext({ branchId: 'eng-paris', projectId: 'p-123' })
- * requireScopeContext({ region: 'eu', branchId: undefined })  // 'undefined' = presence-only for that key
+ * requireScopeContext('branchId')                                 // presence only
+ * requireScopeContext('branchId', 'eng-paris')                    // value match
+ * requireScopeContext({ branchId: 'eng-paris', projectId: 'p-1' }) // multi-key (AND)
+ * requireScopeContext({ region: 'eu', branchId: undefined })      // mixed
  * ```
  *
- * **Pass behavior:**
- * - All required keys present (and matching values when specified) → grant
- * - `elevated` scope (platform admin) → grant unconditionally (cross-context bypass)
- * - Any required key missing or mismatched → deny with a clear reason
- * - Scope kind without context support (`public`, `authenticated`) → deny
- *
- * Pairs with `multiTenantPreset({ tenantFields: [...] })` for row-level
- * filtering on the same dimensions.
+ * **Pass behavior:** all required keys present (and matching when
+ * specified) → grant. `elevated` scope grants unconditionally.
  *
  * @example
  * ```typescript
  * permissions: {
- *   // Branch-scoped CRUD — caller must have branchId in their scope context
  *   list: allOf(requireOrgMembership(), requireScopeContext('branchId')),
- *
- *   // Project admin — caller must have BOTH project context AND admin role
- *   delete: allOf(requireOrgRole('admin'), requireScopeContext('projectId')),
- *
- *   // Region-locked endpoint
  *   euOnly: requireScopeContext('region', 'eu'),
  * }
  * ```
@@ -534,34 +421,20 @@ declare function requireScopeContext<TDoc = Record<string, unknown>>(keyOrMap: s
  * Require that the caller's scope grants access to a target organization
  * — either the current org or one of its ancestors (`scope.ancestorOrgIds`).
  *
- * Designed for parent-child organization hierarchies (holding company →
- * subsidiary → branch, MSP → managed tenants, white-label parent → child
- * accounts) where some routes need to accept "this org OR any org I have
- * access to via the chain". Arc takes no position on the source of the
- * chain — your auth function loads `ancestorOrgIds` from your own data
- * model. There's no automatic inheritance: every route opts in explicitly.
+ * For parent-child organization hierarchies (holding → subsidiary → branch,
+ * MSP → tenant, white-label parent → child). Auth function pre-loads
+ * `ancestorOrgIds`; routes opt in explicitly. No automatic inheritance.
  *
  * **Two call shapes:**
- *
  * ```typescript
- * // Static target — rare, used when one route only ever acts on one org
- * requireOrgInScope('acme-holding')
- *
- * // Dynamic target — extracted from request params/body/headers per call
- * requireOrgInScope((ctx) => ctx.request.params.orgId)
- * requireOrgInScope((ctx) => ctx.request.body?.organizationId)
+ * requireOrgInScope('acme-holding')                          // static
+ * requireOrgInScope((ctx) => ctx.request.params.orgId)       // dynamic
  * ```
  *
- * **Pass behavior:**
- * - Target equals `scope.organizationId` → grant
- * - Target appears in `scope.ancestorOrgIds` → grant
- * - `elevated` scope → grant unconditionally (cross-org admin bypass)
- * - Target is undefined (extractor returned nothing) → deny with reason
- * - Anything else → deny with target name in reason
+ * `elevated` scope grants unconditionally (cross-org bypass).
  *
  * @example
  * ```typescript
- * // /orgs/:orgId/jobs — caller can act on any org in their hierarchy chain
  * permissions: {
  *   list: requireOrgInScope((ctx) => ctx.request.params.orgId),
  *   create: allOf(
@@ -573,59 +446,9 @@ declare function requireScopeContext<TDoc = Record<string, unknown>>(keyOrMap: s
  */
 declare function requireOrgInScope<TDoc = Record<string, unknown>>(target: string | ((ctx: PermissionContext<TDoc>) => string | undefined)): PermissionCheck<TDoc>;
 /**
- * Create a scoped permission system for resource-action patterns.
- * Maps org roles to fine-grained permissions without external API calls.
- *
- * @example
- * ```typescript
- * const perms = createOrgPermissions({
- *   statements: {
- *     product: ['create', 'update', 'delete'],
- *     order: ['create', 'approve'],
- *   },
- *   roles: {
- *     owner: { product: ['create', 'update', 'delete'], order: ['create', 'approve'] },
- *     admin: { product: ['create', 'update'], order: ['create'] },
- *     member: { product: [], order: [] },
- *   },
- * });
- *
- * defineResource({
- *   permissions: {
- *     create: perms.can({ product: ['create'] }),
- *     delete: perms.can({ product: ['delete'] }),
- *   }
- * });
- * ```
- */
-declare function createOrgPermissions(config: {
-  statements: Record<string, readonly string[]>;
-  roles: Record<string, Record<string, readonly string[]>>;
-}): {
-  can: (permissions: Record<string, string[]>) => PermissionCheck;
-  requireRole: (...roles: string[]) => PermissionCheck;
-  requireMembership: () => PermissionCheck;
-  requireTeamMembership: () => PermissionCheck;
-};
-/**
- * Create a dynamic role-based permission matrix.
- *
- * Use this when role/action mappings are managed outside code
- * (e.g., admin UI matrix, DB-stored ACLs, remote policy service).
- *
- * Supports:
- * - org role union (any assigned org role can grant)
- * - global bypass roles
- * - wildcard resource/action (`*`)
- * - optional in-memory cache
- */
-declare function createDynamicPermissionMatrix(config: DynamicPermissionMatrixConfig): DynamicPermissionMatrix;
-/**
- * Require membership in the active team.
- * User must be authenticated, a member of the active org, AND have an active team.
- *
- * Better Auth teams are flat member groups (no team-level roles).
- * Reads `request.scope.teamId` set by the Better Auth adapter.
+ * Require membership in the active team. User must be authenticated, a
+ * member of the active org, AND have an active team. Better Auth teams
+ * are flat member groups (no team-level roles). Reads `request.scope.teamId`.
  *
  * @example
  * ```typescript
@@ -636,5 +459,57 @@ declare function createDynamicPermissionMatrix(config: DynamicPermissionMatrixCo
  * ```
  */
 declare function requireTeamMembership<TDoc = Record<string, unknown>>(): PermissionCheck<TDoc>;
+declare namespace presets_d_exports {
+  export { adminOnly, authenticated, fullPublic, ownerWithAdminBypass, publicRead, publicReadAdminWrite, readOnly };
+}
+/**
+ * ResourcePermissions shape — matches the type in types/index.ts
+ */
+interface ResourcePermissions<TDoc = any> {
+  list?: PermissionCheck<TDoc>;
+  get?: PermissionCheck<TDoc>;
+  create?: PermissionCheck<TDoc>;
+  update?: PermissionCheck<TDoc>;
+  delete?: PermissionCheck<TDoc>;
+}
+type PermissionOverrides<TDoc = any> = Partial<ResourcePermissions<TDoc>>;
+/**
+ * Public read, authenticated write.
+ * list + get = allowPublic(), create + update + delete = requireAuth()
+ */
+declare function publicRead<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
+/**
+ * Public read, admin write.
+ * list + get = allowPublic(), create + update + delete = requireRoles(['admin'])
+ */
+declare function publicReadAdminWrite<TDoc = any>(roles?: readonly string[], overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
+/**
+ * All operations require authentication.
+ */
+declare function authenticated<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
+/**
+ * All operations require specific roles.
+ * @param roles - Required roles (user needs at least one). Default: ['admin']
+ */
+declare function adminOnly<TDoc = any>(roles?: readonly string[], overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
+/**
+ * Owner-scoped with admin bypass.
+ * list = auth (scoped to owner), get = auth, create = auth,
+ * update + delete = ownership check with admin bypass.
+ *
+ * @param ownerField - Field containing owner ID (default: 'userId')
+ * @param bypassRoles - Roles that bypass ownership check (default: ['admin'])
+ */
+declare function ownerWithAdminBypass<TDoc = any>(ownerField?: Extract<keyof TDoc, string> | string, bypassRoles?: readonly string[], overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
+/**
+ * Full public access — no auth required for any operation.
+ * Use sparingly (dev/testing, truly public APIs).
+ */
+declare function fullPublic<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
+/**
+ * Read-only: list + get authenticated, write operations denied.
+ * Useful for computed/derived resources.
+ */
+declare function readOnly<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
 //#endregion
-export { RoleHierarchy as A, authenticated as C, publicRead as D, presets_d_exports as E, applyPermissionResult as M, normalizePermissionResult as N, publicReadAdminWrite as O, adminOnly as S, ownerWithAdminBypass as T, requireScopeContext as _, allOf as a, roles as b, createDynamicPermissionMatrix as c, requireAuth as d, requireOrgInScope as f, requireRoles as g, requireOwnership as h, PermissionEventBus as i, createRoleHierarchy as j, readOnly as k, createOrgPermissions as l, requireOrgRole as m, DynamicPermissionMatrix as n, allowPublic as o, requireOrgMembership as p, DynamicPermissionMatrixConfig as r, anyOf as s, ConnectEventsOptions as t, denyAll as u, requireServiceScope as v, fullPublic as w, when as x, requireTeamMembership as y };
+export { requireRoles as A, allOf as C, not as D, denyAll as E, when as M, applyPermissionResult as N, requireAuth as O, normalizePermissionResult as P, createOrgPermissions as S, anyOf as T, ConnectEventsOptions as _, presets_d_exports as a, PermissionEventBus as b, readOnly as c, requireOrgRole as d, requireScopeContext as f, createRoleHierarchy as g, RoleHierarchy as h, ownerWithAdminBypass as i, roles as j, requireOwnership as k, requireOrgInScope as l, requireTeamMembership as m, authenticated as n, publicRead as o, requireServiceScope as p, fullPublic as r, publicReadAdminWrite as s, adminOnly as t, requireOrgMembership as u, DynamicPermissionMatrix as v, allowPublic as w, createDynamicPermissionMatrix as x, DynamicPermissionMatrixConfig as y };