@classytic/arc 2.6.3 → 2.7.1

package/dist/types-AOD8fxIw.mjs

@@ -0,0 +1,229 @@
+//#region src/scope/types.ts
+/** Check if scope is `member` kind */
+function isMember(scope) {
+	return scope.kind === "member";
+}
+/** Check if scope is `elevated` kind */
+function isElevated(scope) {
+	return scope.kind === "elevated";
+}
+/** Check if scope is `service` kind (machine-to-machine auth) */
+function isService(scope) {
+	return scope.kind === "service";
+}
+/** Check if scope has org access (member, service, or elevated) */
+function hasOrgAccess(scope) {
+	return scope.kind === "member" || scope.kind === "service" || scope.kind === "elevated";
+}
+/** Check if request is authenticated (any kind except public) */
+function isAuthenticated(scope) {
+	return scope.kind !== "public";
+}
+/** Get organizationId from scope (member, service, or elevated — undefined otherwise) */
+function getOrgId(scope) {
+	if (scope.kind === "member") return scope.organizationId;
+	if (scope.kind === "service") return scope.organizationId;
+	if (scope.kind === "elevated") return scope.organizationId;
+}
+/**
+* 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' });
+* }
+* ```
+*/
+function getClientId(scope) {
+	if (scope.kind === "service") return scope.clientId;
+}
+/**
+* Get OAuth-style scope strings from a service scope (e.g. `['jobs:write']`).
+* Returns an empty array for any non-service kind.
+*/
+function getServiceScopes(scope) {
+	if (scope.kind === "service") return scope.scopes ?? [];
+	return [];
+}
+/** Get org roles from scope (empty array if not a member) */
+function getOrgRoles(scope) {
+	if (scope.kind === "member") return scope.orgRoles;
+	return [];
+}
+/** Get team ID from scope (only available on member kind) */
+function getTeamId(scope) {
+	if (scope.kind === "member") return scope.teamId;
+}
+/**
+* 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' });
+* ```
+*/
+function getScopeContext(scope, key) {
+	if (scope.kind === "member" || scope.kind === "service" || scope.kind === "elevated") return scope.context?.[key];
+}
+/**
+* Get the full scope context map (read-only). Returns `undefined` for scope
+* kinds that don't carry context (`public`, `authenticated`).
+*/
+function getScopeContextMap(scope) {
+	if (scope.kind === "member" || scope.kind === "service" || scope.kind === "elevated") return scope.context;
+}
+/**
+* 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
+* }
+* ```
+*/
+function getAncestorOrgIds(scope) {
+	if (scope.kind === "member" || scope.kind === "service" || scope.kind === "elevated") return scope.ancestorOrgIds ?? [];
+	return [];
+}
+/**
+* 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' };
+* }
+* ```
+*/
+function isOrgInScope(scope, targetOrgId) {
+	if (targetOrgId === void 0 || targetOrgId === null) return false;
+	if (scope.kind !== "member" && scope.kind !== "service" && scope.kind !== "elevated") return false;
+	if (scope.organizationId === targetOrgId) return true;
+	return (scope.ancestorOrgIds ?? []).includes(targetOrgId);
+}
+/**
+* Get userId from scope (available on authenticated, member, elevated).
+*
+* @example
+* ```typescript
+* import { getUserId } from '@classytic/arc/scope';
+* const userId = getUserId(request.scope);
+* ```
+*/
+function getUserId(scope) {
+	if (scope.kind === "public") return void 0;
+	return scope.userId;
+}
+/**
+* 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);
+* ```
+*/
+function getUserRoles(scope) {
+	if (scope.kind === "authenticated") return scope.userRoles ?? [];
+	if (scope.kind === "member") return scope.userRoles;
+	return [];
+}
+/**
+* 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);
+* }
+* ```
+*/
+function getOrgContext(request) {
+	const scope = request.scope ?? { kind: "public" };
+	return {
+		userId: getUserId(scope) ?? request.user?.id ?? request.user?._id,
+		organizationId: getOrgId(scope) ?? request.user?.organizationId ?? request.headers?.["x-organization-id"],
+		roles: getUserRoles(scope),
+		orgRoles: getOrgRoles(scope)
+	};
+}
+/**
+* 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;
+*   // ...
+* }
+* ```
+*/
+function getRequestScope(request) {
+	return request.scope ?? PUBLIC_SCOPE;
+}
+/** Default public scope — used as initial decoration value */
+const PUBLIC_SCOPE = Object.freeze({ kind: "public" });
+/** Default authenticated scope — used when user is logged in but no org */
+const AUTHENTICATED_SCOPE = Object.freeze({ kind: "authenticated" });
+//#endregion
+export { isElevated as _, getOrgContext as a, isService as b, getRequestScope as c, getServiceScopes as d, getTeamId as f, isAuthenticated as g, hasOrgAccess as h, getClientId as i, getScopeContext as l, getUserRoles as m, PUBLIC_SCOPE as n, getOrgId as o, getUserId as p, getAncestorOrgIds as r, getOrgRoles as s, AUTHENTICATED_SCOPE as t, getScopeContextMap as u, isMember as v, isOrgInScope as y };

package/dist/types-CNEbix8T.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-B4_TDdPe.d.mts → types-ClmkMDK1.d.mts}

@@ -1,4 +1,4 @@
-import { Vt as ResourceDefinition } from "./interface-DYH8AXGe.mjs";
+import { Vt as ResourceDefinition } from "./interface-Dwzqt4mn.mjs";
 import { z } from "zod";
 
 //#region src/integrations/mcp/types.d.ts

package/dist/{types-By-5mIfn.d.mts → types-D0qf0Mf4.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-Dwzqt4mn.mjs";
+import { n as ElevationOptions } from "./elevation-Dm-HTBCt.mjs";
+import { t as ExternalOpenApiPaths } from "./externalPaths-Dg7OLsKo.mjs";
+import { i as CacheStore } from "./interface-CnluRL4_.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-Bw8XyJpX.mjs";
+import { i as EventTransport } from "./EventTransport-CUpRK_Lg.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-BgLxJkIB.mjs";
+import { c as MetricsOptions, d as SSEOptions, m as CachingOptions, r as VersioningOptions, t as ErrorHandlerOptions } from "./errorHandler-COa51ho_.mjs";
+import { r as IdempotencyStore } from "./interface-B9rHWPxD.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 
 //#region src/factory/loadResources.d.ts