@classytic/arc 2.6.3 → 2.7.3

package/dist/scope/index.d.mts

@@ -1,4 +1,5 @@
-import { _ as isMember, a as AUTHENTICATED_SCOPE, c as getOrgContext, d as getTeamId, f as getUserId, g as isElevated, h as isAuthenticated, i as elevationPlugin, l as getOrgId, m as hasOrgAccess, n as ElevationOptions, o as PUBLIC_SCOPE, p as getUserRoles, r as _default, s as RequestScope, t as ElevationEvent, u as getOrgRoles } from "../elevation-C_taLQrM.mjs";
+import { _ as isAuthenticated, a as getClientId, b as isOrgInScope, c as getOrgRoles, d as getScopeContextMap, f as getServiceScopes, g as hasOrgAccess, h as getUserRoles, i as getAncestorOrgIds, l as getRequestScope, m as getUserId, n as PUBLIC_SCOPE, o as getOrgContext, p as getTeamId, r as RequestScope, s as getOrgId, t as AUTHENTICATED_SCOPE, u as getScopeContext, v as isElevated, x as isService, y as isMember } from "../types--D3vvfdt.mjs";
+import { i as elevationPlugin, n as ElevationOptions, r as _default, t as ElevationEvent } from "../elevation-D7WK0RXq.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 
 //#region src/scope/rateLimitKey.d.ts
@@ -29,4 +30,4 @@ interface ResolveOrgFromHeaderOptions {
  */
 declare function resolveOrgFromHeader(options: ResolveOrgFromHeaderOptions): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
 //#endregion
-export { AUTHENTICATED_SCOPE, type ElevationEvent, type ElevationOptions, PUBLIC_SCOPE, type RateLimitKeyContext, type RequestScope, type ResolveOrgFromHeaderOptions, type TenantKeyGeneratorOptions, createTenantKeyGenerator, _default as elevationPlugin, elevationPlugin as elevationPluginFn, getOrgContext, getOrgId, getOrgRoles, getTeamId, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, resolveOrgFromHeader };
+export { AUTHENTICATED_SCOPE, type ElevationEvent, type ElevationOptions, PUBLIC_SCOPE, type RateLimitKeyContext, type RequestScope, type ResolveOrgFromHeaderOptions, type TenantKeyGeneratorOptions, createTenantKeyGenerator, _default as elevationPlugin, elevationPlugin as elevationPluginFn, getAncestorOrgIds, getClientId, getOrgContext, getOrgId, getOrgRoles, getRequestScope, getScopeContext, getScopeContextMap, getServiceScopes, getTeamId, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, isOrgInScope, isService, resolveOrgFromHeader };

package/dist/scope/index.mjs

@@ -1,6 +1,6 @@
-import { a as getOrgRoles, c as getUserRoles, d as isElevated, f as isMember, i as getOrgId, l as hasOrgAccess, n as PUBLIC_SCOPE, o as getTeamId, r as getOrgContext, s as getUserId, t as AUTHENTICATED_SCOPE, u as isAuthenticated } from "../types-BhtYdxZU.mjs";
+import { _ as isElevated, a as getOrgContext, b as isService, c as getRequestScope, d as getServiceScopes, f as getTeamId, g as isAuthenticated, h as hasOrgAccess, i as getClientId, l as getScopeContext, m as getUserRoles, n as PUBLIC_SCOPE, o as getOrgId, p as getUserId, r as getAncestorOrgIds, s as getOrgRoles, t as AUTHENTICATED_SCOPE, u as getScopeContextMap, v as isMember, y as isOrgInScope } from "../types-AOD8fxIw.mjs";
 import { n as normalizeRoles } from "../types-ZUu_h0jp.mjs";
-import { n as elevation_default, t as elevationPlugin } from "../elevation-BEdACOLB.mjs";
+import { n as elevation_default, t as elevationPlugin } from "../elevation-By_p2lnn.mjs";
 //#region src/scope/rateLimitKey.ts
 function createTenantKeyGenerator(opts) {
 	if (opts?.strategy) return opts.strategy;
@@ -8,6 +8,7 @@ function createTenantKeyGenerator(opts) {
 		const scope = ctx.scope;
 		if (!scope || scope.kind === "public") return ctx.ip;
 		if (scope.kind === "member") return scope.organizationId;
+		if (scope.kind === "service") return scope.organizationId;
 		if (scope.kind === "elevated") return scope.organizationId ?? scope.userId ?? ctx.ip;
 		return scope.userId ?? ctx.ip;
 	};
@@ -75,4 +76,4 @@ function resolveOrgFromHeader(options) {
 	};
 }
 //#endregion
-export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, createTenantKeyGenerator, elevation_default as elevationPlugin, elevationPlugin as elevationPluginFn, getOrgContext, getOrgId, getOrgRoles, getTeamId, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, resolveOrgFromHeader };
+export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, createTenantKeyGenerator, elevation_default as elevationPlugin, elevationPlugin as elevationPluginFn, getAncestorOrgIds, getClientId, getOrgContext, getOrgId, getOrgRoles, getRequestScope, getScopeContext, getScopeContextMap, getServiceScopes, getTeamId, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, isOrgInScope, isService, resolveOrgFromHeader };

package/dist/{sse-BF7GR7IB.mjs → sse-6W0hjVS_.mjs}

@@ -1,6 +1,6 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
-import { i as getOrgId, n as PUBLIC_SCOPE } from "./types-BhtYdxZU.mjs";
-import { t as arcLog } from "./logger-Dz3j1ItV.mjs";
+import { n as PUBLIC_SCOPE, o as getOrgId } from "./types-AOD8fxIw.mjs";
+import { t as arcLog } from "./logger-DLg8-Ueg.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/sse.ts
 var sse_exports = /* @__PURE__ */ __exportAll({

package/dist/testing/index.d.mts

@@ -1,5 +1,5 @@
-import { Ut as CrudRepository, Vt as ResourceDefinition, u as AnyRecord } from "../interface-DYH8AXGe.mjs";
-import { d as ResourceLike, r as CreateAppOptions } from "../types-By-5mIfn.mjs";
+import { Ut as CrudRepository, Vt as ResourceDefinition, u as AnyRecord } from "../interface-B91alUzq.mjs";
+import { d as ResourceLike, r as CreateAppOptions } from "../types-2FlNl0mL.mjs";
 import Fastify, { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Connection } from "mongoose";
 import { Mock } from "vitest";

package/dist/testing/index.mjs

@@ -1796,7 +1796,7 @@ function runEventTests(resourceName, displayName, events) {
 * ```
 */
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-D2w0LdYJ.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-D7e77m8C.mjs").then((n) => n.r);
 	const { useInMemoryDb = true, mongoUri: providedMongoUri, ...appOptions } = options;
 	const defaultAuth = {
 		type: "jwt",

package/dist/types/index.d.mts

@@ -1,4 +1,5 @@
-import { _ as isMember, a as AUTHENTICATED_SCOPE, d as getTeamId, g as isElevated, h as isAuthenticated, l as getOrgId, m as hasOrgAccess, n as ElevationOptions, o as PUBLIC_SCOPE, s as RequestScope, t as ElevationEvent, u as getOrgRoles } from "../elevation-C_taLQrM.mjs";
-import { $ as RateLimitConfig, A as FieldRule, B as JwtContext, C as CrudRouterOptions, Ct as getUserId, D as FastifyRequestExtras, E as EventsDecorator, F as InferDocType, Ft as IController, G as OpenApiSchemas, Gt as PaginatedResult, H as MiddlewareConfig, I as InferResourceDoc, It as IControllerResponse, J as PopulateOption, K as OwnershipCheck, Kt as PaginationParams, L as IntrospectionData, Lt as IRequestContext, M as HealthCheck, Mt as ControllerHandler, N as HealthOptions, Nt as ControllerLike, O as FastifyWithAuth, P as InferAdapterDoc, Pt as FastifyHandler, Q as QueryParserInterface, R as IntrospectionPluginOptions, Rt as RouteHandler, S as CrudRouteKey, St as envelope, T as EventDefinition, Tt as BaseControllerOptions, U as MiddlewareHandler, Ut as CrudRepository, V as LookupOption, W as ObjectId, Wt as InferDoc, X as PresetHook, Y as PresetFunction, Z as PresetResult, _ as Authenticator, _t as TypedResourceConfig, at as ResourceCacheConfig, b as ControllerQueryOptions, bt as ValidateOptions, ct as ResourceHooks, d as ApiResponse, dt as RouteHandlerMethod, et as RegistryEntry, f as ArcDecorator, ft as RouteSchemaOptions, g as AuthPluginOptions, gt as TypedRepository, h as AuthHelpers, ht as TypedController, it as RequestWithExtras, j as GracefulShutdownOptions, k as FastifyWithDecorators, l as AdditionalRoute, lt as ResourceMetadata, m as ArcRequest, mt as TokenPair, nt as RequestContext, ot as ResourceConfig, p as ArcInternalMetadata, pt as ServiceContext, q as ParsedQuery, qt as QueryOptions, rt as RequestIdOptions, st as ResourceHookContext, tt as RegistryStats, u as AnyRecord, ut as ResourcePermissions, v as AuthenticatorContext, vt as UserLike, w as CrudSchemas, x as CrudController, xt as ValidationResult, y as ConfigError, yt as UserOrganization, z as JWTPayload } from "../interface-DYH8AXGe.mjs";
-import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "../types-BNUccdcf.mjs";
+import { _ as isAuthenticated, c as getOrgRoles, g as hasOrgAccess, n as PUBLIC_SCOPE, p as getTeamId, r as RequestScope, s as getOrgId, t as AUTHENTICATED_SCOPE, v as isElevated, y as isMember } from "../types--D3vvfdt.mjs";
+import { $ as RateLimitConfig, A as FieldRule, B as JwtContext, C as CrudRouterOptions, Ct as getUserId, D as FastifyRequestExtras, E as EventsDecorator, F as InferDocType, Ft as IController, G as OpenApiSchemas, Gt as PaginatedResult, H as MiddlewareConfig, I as InferResourceDoc, It as IControllerResponse, J as PopulateOption, K as OwnershipCheck, Kt as PaginationParams, L as IntrospectionData, Lt as IRequestContext, M as HealthCheck, Mt as ControllerHandler, N as HealthOptions, Nt as ControllerLike, O as FastifyWithAuth, P as InferAdapterDoc, Pt as FastifyHandler, Q as QueryParserInterface, R as IntrospectionPluginOptions, Rt as RouteHandler, S as CrudRouteKey, St as envelope, T as EventDefinition, Tt as BaseControllerOptions, U as MiddlewareHandler, Ut as CrudRepository, V as LookupOption, W as ObjectId, Wt as InferDoc, X as PresetHook, Y as PresetFunction, Z as PresetResult, _ as Authenticator, _t as TypedResourceConfig, at as ResourceCacheConfig, b as ControllerQueryOptions, bt as ValidateOptions, ct as ResourceHooks, d as ApiResponse, dt as RouteHandlerMethod, et as RegistryEntry, f as ArcDecorator, ft as RouteSchemaOptions, g as AuthPluginOptions, gt as TypedRepository, h as AuthHelpers, ht as TypedController, it as RequestWithExtras, j as GracefulShutdownOptions, k as FastifyWithDecorators, l as AdditionalRoute, lt as ResourceMetadata, m as ArcRequest, mt as TokenPair, nt as RequestContext, ot as ResourceConfig, p as ArcInternalMetadata, pt as ServiceContext, q as ParsedQuery, qt as QueryOptions, rt as RequestIdOptions, st as ResourceHookContext, tt as RegistryStats, u as AnyRecord, ut as ResourcePermissions, v as AuthenticatorContext, vt as UserLike, w as CrudSchemas, x as CrudController, xt as ValidationResult, y as ConfigError, yt as UserOrganization, z as JWTPayload } from "../interface-B91alUzq.mjs";
+import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "../types-B4BNthET.mjs";
+import { n as ElevationOptions, t as ElevationEvent } from "../elevation-D7WK0RXq.mjs";
 export { AUTHENTICATED_SCOPE, AdditionalRoute, AnyRecord, ApiResponse, ArcDecorator, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRepository, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OpenApiSchemas, OwnershipCheck, PUBLIC_SCOPE, PaginatedResult, PaginationParams, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryOptions, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResourceCacheConfig, ResourceConfig, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteHandler, RouteHandlerMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult, envelope, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };

package/dist/types/index.mjs

@@ -1,4 +1,4 @@
-import { a as getOrgRoles, d as isElevated, f as isMember, i as getOrgId, l as hasOrgAccess, n as PUBLIC_SCOPE, o as getTeamId, t as AUTHENTICATED_SCOPE, u as isAuthenticated } from "../types-BhtYdxZU.mjs";
+import { _ as isElevated, f as getTeamId, g as isAuthenticated, h as hasOrgAccess, n as PUBLIC_SCOPE, o as getOrgId, s as getOrgRoles, t as AUTHENTICATED_SCOPE, v as isMember } from "../types-AOD8fxIw.mjs";
 //#region src/types/index.ts
 /**
 * Response envelope helper — wraps data in Arc's standard `{ success, data }` format.

package/dist/types--D3vvfdt.d.mts

@@ -0,0 +1,286 @@
+//#region src/scope/types.d.ts
+/**
+ * Request Scope — The One Standard
+ *
+ * Discriminated union representing the access context of every request.
+ * Replaces scattered orgScope/orgRoles/organizationId/bypassRoles.
+ *
+ * Set once by auth adapters, read everywhere by permissions/presets/guards.
+ *
+ * @example
+ * ```typescript
+ * // In a permission check
+ * const scope = request.scope;
+ * if (isElevated(scope)) return true;
+ * if (isMember(scope) && scope.orgRoles.includes('admin')) return true;
+ *
+ * // Get user identity from scope
+ * const userId = getUserId(scope);
+ * const globalRoles = getUserRoles(scope);
+ * ```
+ */
+/**
+ * Request scope — 5 kinds, no ambiguity.
+ *
+ * | Kind          | Meaning                                          |
+ * |---------------|--------------------------------------------------|
+ * | public        | No authentication                                |
+ * | authenticated | Logged-in user, no org context                   |
+ * | member        | User in an org with specific roles               |
+ * | service       | Machine-to-machine (API key, service account)    |
+ * | elevated      | Platform admin, explicit elevation               |
+ *
+ * **Identity fields by kind:**
+ * - `userId` / `userRoles` — available on `authenticated`, `member`, `elevated` (a real human)
+ * - `clientId` — available on `service` (a machine identity, NOT a user)
+ * - `organizationId` — required on `member` and `service`, optional on `elevated`
+ * - `orgRoles` — org-level roles, only on `member` (from membership records)
+ * - `scopes` — optional OAuth-style scope strings on `service` (e.g. `['jobs:write', 'memories:read']`)
+ *
+ * Use `getUserId(scope)` / `getClientId(scope)` / `getOrgId(scope)` instead of
+ * narrowing manually — helpers return `undefined` when the field isn't present.
+ */
+type RequestScope = {
+  kind: "public";
+} | {
+  kind: "authenticated";
+  userId?: string;
+  userRoles?: string[];
+} | {
+  kind: "member";
+  userId?: string;
+  userRoles: string[];
+  organizationId: string;
+  orgRoles: string[];
+  teamId?: string;
+  /**
+   * App-defined scope dimensions beyond org and team. Use this to carry
+   * branch / project / department / region / workspace identifiers that
+   * arc itself shouldn't take a position on.
+   *
+   * Read with `getScopeContext(scope, key)`. Filtered by
+   * `multiTenantPreset({ tenantFields: [...] })` and gated by
+   * `requireScopeContext(...)`. Populated by your auth function or
+   * adapter (e.g. from JWT claims, BA session fields, or request headers).
+   *
+   * Treat as immutable — `Readonly` enforces that at the type level.
+   */
+  context?: Readonly<Record<string, string>>;
+  /**
+   * Parent organizations the caller has access to, ordered closest-first
+   * (immediate parent → … → root). Used for explicit hierarchy checks
+   * via `isOrgInScope` and `requireOrgInScope` — there's no automatic
+   * inheritance, every check is opt-in.
+   *
+   * Arc takes no position on the source — your auth function loads the
+   * chain from your own org table during sign-in or middleware. Empty
+   * or absent = caller has no parent orgs (the common case).
+   */
+  ancestorOrgIds?: readonly string[];
+} | {
+  kind: "service";
+  clientId: string;
+  organizationId: string;
+  scopes?: readonly string[]; /** App-defined scope dimensions — see `member.context` for details. */
+  context?: Readonly<Record<string, string>>; /** Parent organizations — see `member.ancestorOrgIds` for details. */
+  ancestorOrgIds?: readonly string[];
+} | {
+  kind: "elevated";
+  userId?: string;
+  organizationId?: string;
+  elevatedBy: string; /** App-defined scope dimensions — see `member.context` for details. */
+  context?: Readonly<Record<string, string>>; /** Parent organizations — see `member.ancestorOrgIds` for details. */
+  ancestorOrgIds?: readonly string[];
+};
+/** Check if scope is `member` kind */
+declare function isMember(scope: RequestScope): scope is Extract<RequestScope, {
+  kind: "member";
+}>;
+/** Check if scope is `elevated` kind */
+declare function isElevated(scope: RequestScope): scope is Extract<RequestScope, {
+  kind: "elevated";
+}>;
+/** Check if scope is `service` kind (machine-to-machine auth) */
+declare function isService(scope: RequestScope): scope is Extract<RequestScope, {
+  kind: "service";
+}>;
+/** Check if scope has org access (member, service, or elevated) */
+declare function hasOrgAccess(scope: RequestScope): boolean;
+/** Check if request is authenticated (any kind except public) */
+declare function isAuthenticated(scope: RequestScope): boolean;
+/** Get organizationId from scope (member, service, or elevated — undefined otherwise) */
+declare function getOrgId(scope: RequestScope): string | undefined;
+/**
+ * Get stable client identity from a service scope.
+ *
+ * Returns the `clientId` for machine-to-machine auth (API keys, service accounts),
+ * or `undefined` for any other scope kind. Use this for audit logging, rate limiting,
+ * and anywhere you need to distinguish "this specific API client" from "this user".
+ *
+ * @example
+ * ```typescript
+ * const clientId = getClientId(request.scope);
+ * if (clientId) {
+ *   auditLog.record({ actor: clientId, action: 'create' });
+ * }
+ * ```
+ */
+declare function getClientId(scope: RequestScope): string | undefined;
+/**
+ * Get OAuth-style scope strings from a service scope (e.g. `['jobs:write']`).
+ * Returns an empty array for any non-service kind.
+ */
+declare function getServiceScopes(scope: RequestScope): readonly string[];
+/** Get org roles from scope (empty array if not a member) */
+declare function getOrgRoles(scope: RequestScope): string[];
+/** Get team ID from scope (only available on member kind) */
+declare function getTeamId(scope: RequestScope): string | undefined;
+/**
+ * Get an app-defined scope dimension by key (e.g. `branchId`, `projectId`).
+ *
+ * Returns the value when the scope is `member`/`service`/`elevated` AND has
+ * `context` set AND the key exists; `undefined` otherwise. Designed to be
+ * the single read path for any custom tenancy dimension your app cares about
+ * — branch, project, department, region, workspace, etc.
+ *
+ * Arc itself takes no position on what keys you use — that's your domain.
+ *
+ * @example
+ * ```typescript
+ * import { getScopeContext } from '@classytic/arc/scope';
+ *
+ * const branchId = getScopeContext(request.scope, 'branchId');
+ * if (!branchId) return reply.code(403).send({ error: 'Branch context required' });
+ * ```
+ */
+declare function getScopeContext(scope: RequestScope, key: string): string | undefined;
+/**
+ * Get the full scope context map (read-only). Returns `undefined` for scope
+ * kinds that don't carry context (`public`, `authenticated`).
+ */
+declare function getScopeContextMap(scope: RequestScope): Readonly<Record<string, string>> | undefined;
+/**
+ * Get the parent-organization chain for a scope (closest-first, root-last).
+ *
+ * Returns the `ancestorOrgIds` array when the scope is `member`/`service`/
+ * `elevated` and has it set; an empty array otherwise (including for kinds
+ * that can't carry org context).
+ *
+ * Arc takes no position on what the chain represents — your auth function
+ * loads it from your own data model. Common use cases: holding company →
+ * subsidiaries, MSP → managed tenants, white-label parent → child accounts.
+ *
+ * @example
+ * ```typescript
+ * import { getAncestorOrgIds } from '@classytic/arc/scope';
+ *
+ * const ancestors = getAncestorOrgIds(request.scope);
+ * if (ancestors.includes('acme-holding')) {
+ *   // caller has access to a path that includes Acme Holding
+ * }
+ * ```
+ */
+declare function getAncestorOrgIds(scope: RequestScope): readonly string[];
+/**
+ * Pure predicate: does this scope grant access to `targetOrgId`?
+ *
+ * Returns `true` if `targetOrgId` equals the scope's `organizationId` OR
+ * appears in `ancestorOrgIds`. Returns `false` otherwise — including for
+ * elevated scopes (this is a pure data query, not a permission check; the
+ * elevated bypass lives in `requireOrgInScope`, not here).
+ *
+ * Designed to be the building block for any custom hierarchy logic in your
+ * own permission checks. Use `requireOrgInScope` for the route-gating
+ * version that includes the elevated bypass.
+ *
+ * @example
+ * ```typescript
+ * import { isOrgInScope } from '@classytic/arc/scope';
+ *
+ * // Inside a custom permission check
+ * if (!isOrgInScope(request.scope, request.params.orgId)) {
+ *   return { granted: false, reason: 'Not in your org hierarchy' };
+ * }
+ * ```
+ */
+declare function isOrgInScope(scope: RequestScope, targetOrgId: string): boolean;
+/**
+ * Get userId from scope (available on authenticated, member, elevated).
+ *
+ * @example
+ * ```typescript
+ * import { getUserId } from '@classytic/arc/scope';
+ * const userId = getUserId(request.scope);
+ * ```
+ */
+declare function getUserId(scope: RequestScope): string | undefined;
+/**
+ * Get global user roles from scope (available on authenticated and member).
+ * These are user-level roles (e.g. superadmin, finance-admin) distinct from
+ * org-level roles (scope.orgRoles).
+ *
+ * @example
+ * ```typescript
+ * import { getUserRoles } from '@classytic/arc/scope';
+ * const globalRoles = getUserRoles(request.scope);
+ * ```
+ */
+declare function getUserRoles(scope: RequestScope): string[];
+/**
+ * Org context — canonical extraction from a Fastify request.
+ *
+ * Works regardless of auth type (JWT, Better Auth, custom) by reading
+ * `request.scope` and `request.user`. Eliminates the need for each resource
+ * to re-invent org extraction from headers/user/scope.
+ *
+ * @example
+ * ```typescript
+ * import { getOrgContext } from '@classytic/arc/scope';
+ *
+ * handler: async (request, reply) => {
+ *   const { userId, organizationId, roles, orgRoles } = getOrgContext(request);
+ * }
+ * ```
+ */
+declare function getOrgContext(request: {
+  scope?: RequestScope;
+  user?: Record<string, unknown> | null;
+  headers?: Record<string, string | string[] | undefined>;
+}): {
+  userId: string | undefined;
+  organizationId: string | undefined;
+  roles: string[];
+  orgRoles: string[];
+};
+/**
+ * Read `request.scope` safely from any object that *might* have one.
+ * Falls back to `PUBLIC_SCOPE` when the field is absent or undefined.
+ *
+ * This is the canonical way for permission checks, presets, and middleware
+ * to read scope — never access `request.scope` directly because it can be
+ * `undefined` on requests that haven't been touched by an auth adapter yet.
+ *
+ * Accepts a structural shape (`{ scope?: RequestScope }`) instead of the
+ * full Fastify request type so it can be called from any layer without
+ * dragging in the Fastify type. The actual runtime is identical.
+ *
+ * @example
+ * ```typescript
+ * import { getRequestScope } from '@classytic/arc/scope';
+ *
+ * function myCheck(ctx: PermissionContext) {
+ *   const scope = getRequestScope(ctx.request);
+ *   if (isElevated(scope)) return true;
+ *   // ...
+ * }
+ * ```
+ */
+declare function getRequestScope(request: {
+  scope?: RequestScope;
+}): RequestScope;
+/** Default public scope — used as initial decoration value */
+declare const PUBLIC_SCOPE: Readonly<RequestScope>;
+/** Default authenticated scope — used when user is logged in but no org */
+declare const AUTHENTICATED_SCOPE: Readonly<RequestScope>;
+//#endregion
+export { isAuthenticated as _, getClientId as a, isOrgInScope as b, getOrgRoles as c, getScopeContextMap as d, getServiceScopes as f, hasOrgAccess as g, getUserRoles as h, getAncestorOrgIds as i, getRequestScope as l, getUserId as m, PUBLIC_SCOPE as n, getOrgContext as o, getTeamId as p, RequestScope as r, getOrgId as s, AUTHENTICATED_SCOPE as t, getScopeContext as u, isElevated as v, isService as x, isMember as y };

package/dist/{types-By-5mIfn.d.mts → types-2FlNl0mL.d.mts}

@@ -1,12 +1,12 @@
-import { n as ElevationOptions } from "./elevation-C_taLQrM.mjs";
-import { _ as Authenticator } from "./interface-DYH8AXGe.mjs";
-import { t as ExternalOpenApiPaths } from "./externalPaths-DpO-s7r8.mjs";
-import { i as CacheStore } from "./interface-D_BWALyZ.mjs";
-import { r as QueryCachePluginOptions } from "./queryCachePlugin-DcmETvcB.mjs";
-import { i as EventTransport } from "./EventTransport-wc5hSLik.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-DW45v4V5.mjs";
-import { c as MetricsOptions, d as SSEOptions, m as CachingOptions, r as VersioningOptions, t as ErrorHandlerOptions } from "./errorHandler-Do4vVQ1f.mjs";
-import { r as IdempotencyStore } from "./interface-gr-7qo9j.mjs";
+import { _ as Authenticator } from "./interface-B91alUzq.mjs";
+import { n as ElevationOptions } from "./elevation-D7WK0RXq.mjs";
+import { t as ExternalOpenApiPaths } from "./externalPaths-iba7jD3d.mjs";
+import { i as CacheStore } from "./interface-CG7oRZjX.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-Ckl71mkc.mjs";
+import { i as EventTransport } from "./EventTransport-C4VheKeC.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-CdvUoUna.mjs";
+import { c as MetricsOptions, d as SSEOptions, m as CachingOptions, r as VersioningOptions, t as ErrorHandlerOptions } from "./errorHandler-pCpEtNd7.mjs";
+import { r as IdempotencyStore } from "./interface-CSbZdv_3.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 
 //#region src/factory/loadResources.d.ts
@@ -598,6 +598,41 @@ interface CreateAppOptions {
   ajv?: {
     keywords?: string[];
   };
+  /**
+   * Enable `reply.ok()`, `reply.fail()`, `reply.paginated()` response helpers.
+   *
+   * Default: `false` (opt-in).
+   *
+   * @example
+   * ```typescript
+   * const app = await createApp({ replyHelpers: true });
+   *
+   * // Then in any handler:
+   * return reply.ok({ name: 'MacBook' });          // → 200 { success: true, data: { ... } }
+   * return reply.ok(product, 201);                  // → 201 { success: true, data: { ... } }
+   * return reply.fail('Not found', 404);            // → 404 { success: false, error: '...' }
+   * return reply.fail(['err1', 'err2'], 422);       // → 422 { success: false, errors: [...] }
+   * return reply.paginated({ docs, total, page, limit });
+   * ```
+   */
+  replyHelpers?: boolean;
+  /**
+   * Auto-convert BigInt values to Number in all JSON responses.
+   *
+   * When `true`, Arc adds a `preSerialization` hook that converts BigInt values
+   * to Number before JSON serialization. Without this, `JSON.stringify` throws
+   * on BigInt values (e.g., from financial libraries like fin-io).
+   *
+   * Default: `false` (opt-in — most apps don't use BigInt).
+   *
+   * @example
+   * ```typescript
+   * const app = await createApp({
+   *   serializeBigInt: true,
+   * });
+   * ```
+   */
+  serializeBigInt?: boolean;
   /**
    * Resources to register automatically.
    * Each resource's `.toPlugin()` is called and registered for you.