@classytic/arc 2.41.1 → 2.44.0

package/dist/audit/index.d.mts

@@ -1,6 +1,6 @@
 
-import { d as UserBase } from "../base-CxrV1LmG.mjs";
-import "../index-DHbyPo5j.mjs";
+import { d as UserBase } from "../base-CZyixEQR.mjs";
+import "../index-WH7xgvxS.mjs";
 import { FastifyPluginAsync } from "fastify";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
 //#region src/audit/stores/interface.d.ts
@@ -37,6 +37,8 @@ interface AuditEntry {
 }
 interface AuditContext {
   user?: UserBase;
+  /** The actor from the request's VALIDATED scope (user or service client). Wins over `user`. */
+  actorId?: string;
   organizationId?: string;
   requestId?: string;
   ipAddress?: string;
@@ -86,7 +88,7 @@ interface AuditQueryOptions {
 /**
  * Create audit entry from context
  */
-declare function createAuditEntry(resource: string, documentId: string, action: AuditAction, context: AuditContext, data?: {
+export declare function createAuditEntry(resource: string, documentId: string, action: AuditAction, context: AuditContext, data?: {
   before?: Record<string, unknown>;
   after?: Record<string, unknown>;
   metadata?: Record<string, unknown>;
@@ -191,8 +193,13 @@ declare module "fastify" {
     audit: AuditLogger;
   }
   interface FastifyRequest {
-    /** Audit context for current request */
+    /**
+     * Audit context for the current request. The actor and organization are read from
+     * the VALIDATED scope when this is read — never captured before auth ran.
+     */
     auditContext?: AuditContext;
+    /** Extra fields a handler attaches to the audit row arc writes for this request. */
+    auditMetadata?: Record<string, unknown>;
   }
 }
 interface AuditLogger {
@@ -206,6 +213,11 @@ interface AuditLogger {
   restore: (resource: string, documentId: string, data: Record<string, unknown>, context?: AuditContext) => Promise<void>;
   /** Log a custom action */
   custom: (resource: string, documentId: string, action: string, data?: Record<string, unknown>, context?: AuditContext) => Promise<void>;
+  /**
+   * A logger bound to one request: every entry's actor and organization come from that
+   * request's validated scope, so a caller can neither forget nor forge them.
+   */
+  forRequest: (request: AuditRequestLike) => RequestAuditLogger;
   /** Query audit logs (if stores support it) */
   query: (options: AuditQueryOptions) => Promise<AuditEntry[]>;
   /**
@@ -215,7 +227,33 @@ interface AuditLogger {
    */
   purge: (cutoff: Date) => Promise<number>;
 }
-declare const auditPlugin: FastifyPluginAsync<AuditPluginOptions>;
+/** {@link AuditLogger} writes with the context bound to one request. */
+interface RequestAuditLogger {
+  create: (resource: string, documentId: string, data: Record<string, unknown>) => Promise<void>;
+  update: (resource: string, documentId: string, before: Record<string, unknown>, after: Record<string, unknown>) => Promise<void>;
+  delete: (resource: string, documentId: string, data: Record<string, unknown>) => Promise<void>;
+  restore: (resource: string, documentId: string, data: Record<string, unknown>) => Promise<void>;
+  custom: (resource: string, documentId: string, action: string, data?: Record<string, unknown>) => Promise<void>;
+}
+/** What {@link auditContextOf} reads — a FastifyRequest, or arc's `IRequestContext`. */
+interface AuditRequestLike {
+  readonly scope?: unknown;
+  readonly user?: unknown;
+  readonly id?: string;
+  readonly ip?: string;
+  readonly headers?: Record<string, unknown>;
+  readonly method?: string;
+  readonly url?: string;
+  readonly routeOptions?: {
+    readonly url?: string;
+  };
+  readonly metadata?: unknown;
+}
+/**
+ * The audit context of a request, from its VALIDATED scope: the actor is the scope's user
+ * (or service client) and the organization is the scope's active organization.
+ */
+export declare function auditContextOf(request: AuditRequestLike): AuditContext;
 declare const _default: FastifyPluginAsync<AuditPluginOptions>;
 //#endregion
 //#region src/audit/repository-audit-adapter.d.ts
@@ -237,14 +275,14 @@ interface RepositoryAuditStoreOptions {
    */
   readonly sessionProvider?: () => unknown;
 }
-declare function repositoryAsAuditStore(repository: RepositoryLike, options?: RepositoryAuditStoreOptions): AuditStore;
+export declare function repositoryAsAuditStore(repository: RepositoryLike, options?: RepositoryAuditStoreOptions): AuditStore;
 //#endregion
 //#region src/audit/stores/memory.d.ts
 interface MemoryAuditStoreOptions {
   /** Maximum entries to keep (default: 1000) */
   maxEntries?: number;
 }
-declare class MemoryAuditStore implements AuditStore {
+export declare class MemoryAuditStore implements AuditStore {
   readonly name = "memory";
   private entries;
   private maxEntries;
@@ -259,4 +297,4 @@ declare class MemoryAuditStore implements AuditStore {
   clear(): void;
 }
 //#endregion
-export { type AuditAction, type AuditContext, type AuditEntry, type AuditLogger, type AuditPluginOptions, type AuditQueryOptions, type AuditStore, type AuditStoreOptions, MemoryAuditStore, type MemoryAuditStoreOptions, _default as auditPlugin, auditPlugin as auditPluginFn, createAuditEntry, repositoryAsAuditStore };
+export { type AuditAction, type AuditContext, type AuditEntry, type AuditLogger, type AuditPluginOptions, type AuditQueryOptions, type AuditRequestLike, type AuditStore, type AuditStoreOptions, type MemoryAuditStoreOptions, type RepositoryAuditStoreOptions, type RequestAuditLogger, _default as auditPlugin };

package/dist/audit/index.mjs

@@ -1,6 +1,7 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as transactionContext } from "../transactionContext-CPbdlnVw.mjs";
-import { n as declareRuntimeCapability } from "../runtimeCapabilities-CkhS6jn6.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { g as getUserId, i as getClientId } from "../types-fvO6Ovzx.mjs";
+import { t as transactionContext } from "../transactionContext-orvnGu4F.mjs";
+import { n as declareRuntimeCapability } from "../runtimeCapabilities-DIMKMV2G.mjs";
 import { and, anyOf, eq, gte, lt, lte } from "@classytic/repo-core/filter";
 import fp from "fastify-plugin";
 //#region src/audit/repository-audit-adapter.ts
@@ -86,7 +87,7 @@ function createAuditEntry(resource, documentId, action, context, data) {
 		resource,
 		documentId,
 		action,
-		userId: extractUserId(context.user),
+		userId: context.actorId ?? extractUserId(context.user),
 		organizationId: context.organizationId,
 		before: data?.before,
 		after: data?.after,
@@ -182,6 +183,7 @@ const auditPlugin = async (fastify, opts = {}) => {
 	if (!enabled) {
 		fastify.decorate("audit", createNoopLogger());
 		fastify.decorateRequest("auditContext", void 0);
+		fastify.decorateRequest("auditMetadata", void 0);
 		fastify.log?.debug?.("Audit plugin disabled");
 		return;
 	}
@@ -220,6 +222,16 @@ const auditPlugin = async (fastify, opts = {}) => {
 				...data
 			} }));
 		},
+		forRequest(request) {
+			const ctx = () => auditContextOf(request);
+			return {
+				create: (resource, documentId, data) => audit.create(resource, documentId, data, ctx()),
+				update: (resource, documentId, before, after) => audit.update(resource, documentId, before, after, ctx()),
+				delete: (resource, documentId, data) => audit.delete(resource, documentId, data, ctx()),
+				restore: (resource, documentId, data) => audit.restore(resource, documentId, data, ctx()),
+				custom: (resource, documentId, action, data) => audit.custom(resource, documentId, action, data, ctx())
+			};
+		},
 		async query(options) {
 			for (const store of stores) if (store.query) return store.query(options);
 			return [];
@@ -231,27 +243,10 @@ const auditPlugin = async (fastify, opts = {}) => {
 		}
 	};
 	fastify.decorate("audit", audit);
-	fastify.decorateRequest("auditContext", void 0);
-	fastify.addHook("onRequest", async (request) => {
-		const user = request.user;
-		request.context;
-		const scope = request.scope;
-		request.auditContext = {
-			user,
-			organizationId: scope?.kind === "member" ? scope.organizationId : scope?.kind === "elevated" ? scope.organizationId : void 0,
-			requestId: request.id,
-			ipAddress: request.ip,
-			userAgent: request.headers["user-agent"],
-			endpoint: void 0,
-			duration: void 0
-		};
-	});
-	fastify.addHook("onResponse", async (request, reply) => {
-		if (request.auditContext) {
-			request.auditContext.endpoint = `${request.method} ${request.routeOptions?.url ?? request.url}`;
-			request.auditContext.duration = Math.round(reply.elapsedTime);
-		}
-	});
+	fastify.decorateRequest("auditContext", { getter() {
+		return auditContextOf(this);
+	} });
+	fastify.decorateRequest("auditMetadata", void 0);
 	const retention = opts.retention;
 	let retentionTimer = null;
 	if (retention) {
@@ -307,8 +302,10 @@ const auditPlugin = async (fastify, opts = {}) => {
 				} else if (excludeResources.has(ctx.resource)) return;
 				const docId = autoAuditExtractId(ctx.result);
 				const scope = ctx.context?._scope;
+				const scopedActor = scope ? getUserId(scope) ?? getClientId(scope) : void 0;
 				const auditCtx = {
 					user: ctx.user,
+					...scopedActor ? { actorId: String(scopedActor) } : {},
 					organizationId: scope ? autoAuditGetOrgId(scope) : void 0
 				};
 				try {
@@ -331,6 +328,24 @@ const auditPlugin = async (fastify, opts = {}) => {
 	}
 	fastify.log?.debug?.({ stores: stores.map((s) => s.name) }, "Audit plugin enabled");
 };
+/**
+* The audit context of a request, from its VALIDATED scope: the actor is the scope's user
+* (or service client) and the organization is the scope's active organization.
+*/
+function auditContextOf(request) {
+	const scope = request.metadata?._scope ?? request.scope;
+	const actorId = scope ? getUserId(scope) ?? getClientId(scope) : void 0;
+	const userAgent = request.headers?.["user-agent"];
+	return {
+		user: request.user,
+		...actorId ? { actorId: String(actorId) } : {},
+		organizationId: scope ? autoAuditGetOrgId(scope) : void 0,
+		requestId: request.id,
+		ipAddress: request.ip,
+		userAgent: typeof userAgent === "string" ? userAgent : void 0,
+		endpoint: request.method && request.routeOptions?.url ? `${request.method} ${request.routeOptions.url}` : void 0
+	};
+}
 /** Extract document ID from a result */
 function autoAuditExtractId(doc) {
 	if (!doc || typeof doc !== "object") return "";
@@ -361,6 +376,13 @@ function createNoopLogger() {
 		delete: noop,
 		restore: noop,
 		custom: noop,
+		forRequest: () => ({
+			create: noop,
+			update: noop,
+			delete: noop,
+			restore: noop,
+			custom: noop
+		}),
 		query: async () => [],
 		purge: async () => 0,
 		_noop: true
@@ -372,4 +394,4 @@ var auditPlugin_default = fp(auditPlugin, {
 	dependencies: ["arc-core"]
 });
 //#endregion
-export { MemoryAuditStore, auditPlugin_default as auditPlugin, auditPlugin as auditPluginFn, createAuditEntry, repositoryAsAuditStore };
+export { MemoryAuditStore, auditContextOf, auditPlugin_default as auditPlugin, createAuditEntry, repositoryAsAuditStore };

package/dist/auth/audit.d.mts

@@ -9,13 +9,13 @@ import { FastifyInstance } from "fastify";
  * unknown events still flow through when matched, just with the BA-supplied
  * name verbatim. Use this list for autocomplete-friendly defaults.
  */
-type AuthEventName = "session.create" | "session.delete" | "session.update" | "user.create" | "user.update" | "user.delete" | "mfa.enroll" | "mfa.verify" | "mfa.failed" | "mfa.disable" | "password.reset.request" | "password.reset.complete" | "email.verify" | "org.create" | "org.delete" | "org.invite.create" | "org.invite.accept" | "org.invite.reject" | "org.member.add" | "org.member.remove" | "org.member.role.update" | "apikey.create" | "apikey.delete" | "apikey.failed" | "endpoint.before" | "endpoint.after" | "endpoint.error";
+export type AuthEventName = "session.create" | "session.delete" | "session.update" | "user.create" | "user.update" | "user.delete" | "mfa.enroll" | "mfa.verify" | "mfa.failed" | "mfa.disable" | "password.reset.request" | "password.reset.complete" | "email.verify" | "org.create" | "org.delete" | "org.invite.create" | "org.invite.accept" | "org.invite.reject" | "org.member.add" | "org.member.remove" | "org.member.role.update" | "apikey.create" | "apikey.delete" | "apikey.failed" | "endpoint.before" | "endpoint.after" | "endpoint.error";
 /**
  * Resolved auth event ready for audit. The bridge constructs this from
  * BA's hook context, then forwards to `app.audit.custom('auth', subjectId,
  * event.name, event.payload)`.
  */
-interface AuthEvent {
+export interface AuthEvent {
   /** Canonical name (see {@link AuthEventName}). */
   name: string;
   /**
@@ -34,7 +34,7 @@ interface AuthEvent {
 /**
  * Options for `wireBetterAuthAudit`.
  */
-interface WireBetterAuthAuditOptions {
+export interface WireBetterAuthAuditOptions {
   /**
    * Glob patterns selecting which events to audit. `*` matches a single
    * segment (`session.*` matches `session.create` but not `session.create.foo`),
@@ -72,7 +72,7 @@ interface WireBetterAuthAuditOptions {
  * Result of `wireBetterAuthAudit` — duck-typed BA `hooks` + `databaseHooks`
  * config plus an `attach(app)` method to connect the live audit logger.
  */
-interface BetterAuthAuditBridge {
+export interface BetterAuthAuditBridge {
   /**
    * Spread into `betterAuth({ hooks })`. BA's top-level `hooks.before` /
    * `hooks.after` slots take a single async function each (not an array).
@@ -157,7 +157,7 @@ interface BetterAuthAuditBridge {
  * Single BA hook entry — duck-typed to avoid pinning a BA major version.
  * The shape mirrors `better-auth`'s public `hooks.{before,after}` API.
  */
-interface BetterAuthHookEntry {
+export interface BetterAuthHookEntry {
   matcher: (ctx: BetterAuthHookContext) => boolean;
   /**
    * Returns a (possibly empty) object so BA's `runBeforeHooks` /
@@ -169,7 +169,7 @@ interface BetterAuthHookEntry {
   handler: (ctx: BetterAuthHookContext) => Promise<Record<string, unknown>> | Record<string, unknown>;
 }
 /** Subset of BA's hook context the bridge actually reads. */
-interface BetterAuthHookContext {
+export interface BetterAuthHookContext {
   path?: string;
   method?: string;
   body?: Record<string, unknown>;
@@ -198,6 +198,6 @@ interface SessionLike {
   userAgent?: string;
   impersonatedBy?: string;
 }
-declare function wireBetterAuthAudit(opts?: WireBetterAuthAuditOptions): BetterAuthAuditBridge;
+export declare function wireBetterAuthAudit(opts?: WireBetterAuthAuditOptions): BetterAuthAuditBridge;
 //#endregion
-export { AuthEvent, AuthEventName, BetterAuthAuditBridge, BetterAuthHookContext, BetterAuthHookEntry, WireBetterAuthAuditOptions, wireBetterAuthAudit };
+export {};

package/dist/auth/audit.mjs

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
 //#region src/auth/audit.ts
 function compileGlobs(patterns) {
 	if (patterns.length === 0) return () => false;

package/dist/auth/index.d.mts

@@ -1,6 +1,7 @@
 
-import { l as PermissionCheck } from "../base-CxrV1LmG.mjs";
-import { Ft as AuthPluginOptions, Pt as AuthHelpers } from "../index-DHbyPo5j.mjs";
+import { i as RequestScope } from "../types-Ddl9OjmE.mjs";
+import { l as PermissionCheck } from "../base-CZyixEQR.mjs";
+import { At as AuthHelpers, jt as AuthPluginOptions } from "../index-WH7xgvxS.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-CmGOxOtD.mjs";
 import { a as SessionManagerOptions, c as createSessionManager, i as SessionData, n as MemorySessionStoreOptions, o as SessionManagerResult, r as SessionCookieOptions, s as SessionStore, t as MemorySessionStore } from "../sessionManager-qimlKV0P.mjs";
 import { FastifyPluginAsync, FastifyReply as FastifyReply$1, FastifyRequest } from "fastify";
@@ -17,7 +18,6 @@ declare module "fastify" {
     auth: AuthHelpers;
   }
 }
-declare const authPlugin: FastifyPluginAsync<AuthPluginOptions>;
 declare const _default: FastifyPluginAsync<AuthPluginOptions>;
 //#endregion
 //#region src/auth/betterAuth.d.ts
@@ -50,6 +50,30 @@ interface BetterAuthAdapterOptions {
    * @default false
    */
   orgContext?: boolean;
+  /**
+   * Effective roles in the active organization — the seam for an organization HIERARCHY (roles held
+   * at a parent, e.g. a head office, apply in its child organizations). Called with the caller's own
+   * membership roles there (`null` when not a member); returns the roles the request carries, or
+   * `null` to leave it non-member. Requires `orgContext`.
+   */
+  resolveOrgRoles?: (input: {
+    userId: string;
+    organizationId: string;
+    memberRoles: readonly string[] | null;
+  }) => readonly string[] | null | Promise<readonly string[] | null>;
+  /**
+   * Where the caller's own membership roles come from. Default `'better-auth'`: arc asks Better
+   * Auth (`getActiveMember`, then `getActiveMemberRole`) and passes the answer to `resolveOrgRoles`
+   * as `memberRoles`.
+   *
+   * `'resolver'`: `resolveOrgRoles` reads membership itself, so arc skips Better Auth's lookup — one
+   * fewer membership read per authenticated request — and calls it with `memberRoles: null`. Choose
+   * it ONLY for a resolver that never reads `memberRoles`; one that extends them would lose them.
+   * Requires `resolveOrgRoles`.
+   *
+   * @default 'better-auth'
+   */
+  memberLookup?: "better-auth" | "resolver";
   /**
    * OpenAPI documentation for auth endpoints.
    * - `true` (default): auto-extract from auth.api if available
@@ -86,16 +110,20 @@ interface BetterAuthAdapterOptions {
    */
   exposeAuthErrors?: boolean;
   /**
-   * Per-route rate limit for the Better Auth catch-all (`/api/auth/*`),
-   * applied via `@fastify/rate-limit`'s route config (requires the
-   * limiter to be registered, which createApp does by default).
+   * Credentials other than a session, by `Authorization` scheme (RFC 7235) — a paired device, an
+   * API key. A request presenting a registered scheme is authenticated by its verifier ONLY: the
+   * scope it returns (usually `{ kind: 'service', … }`) is installed; `null` is a 401. Gate such
+   * routes with `requireServiceScope(...)`. `Bearer` is the session's and cannot be registered.
    *
-   * Credential endpoints deserve a tighter bucket than the global limit
-   * (brute-force / credential-stuffing surface), BUT the same catch-all
-   * also serves Better Auth's chatty `get-session` heartbeat — so arc
-   * ships NO default here; a forced strict limit (the classic "5/min on
-   * /login") would 429 every SPA that polls sessions. Pick a ceiling that
-   * covers your session-poll cadence, or key the bucket smarter:
+   * @example
+   * credentials: { Device: (value) => verifyDevice(value) }   // Authorization: Device <sn>:<token>
+   */
+  credentials?: Readonly<Record<string, CredentialVerifier>>;
+  /**
+   * Per-route `@fastify/rate-limit` config for the auth catch-all. No default:
+   * the same route serves the chatty `get-session` heartbeat, so a strict
+   * login-style limit would 429 every SPA that polls sessions. Pick a ceiling
+   * above your poll cadence, or exempt the heartbeat:
    *
    * @example
    * ```ts
@@ -173,7 +201,9 @@ declare module "fastify" {
  * fastify.get('/me', { preHandler: [authenticate] }, handler);
  * ```
  */
-declare function createBetterAuthAdapter(options: BetterAuthAdapterOptions): BetterAuthAdapterResult;
+/** Verifies one credential scheme's value; the scope to install, or `null` when it is not valid. */
+type CredentialVerifier = (credentials: string, request: FastifyRequest) => Promise<RequestScope | null>;
+export declare function createBetterAuthAdapter(options: BetterAuthAdapterOptions): BetterAuthAdapterResult;
 //#endregion
 //#region src/auth/betterAuthOpenApi.d.ts
 interface BetterAuthOpenApiOptions {
@@ -211,7 +241,7 @@ interface BetterAuthOpenApiOptions {
  * endpoints, converts their Zod schemas to JSON Schema via `z.toJSONSchema()`,
  * and returns a complete `ExternalOpenApiPaths` object ready for Arc's spec builder.
  */
-declare function extractBetterAuthOpenApi(authApi: Record<string, unknown>, options?: BetterAuthOpenApiOptions): ExternalOpenApiPaths;
+export declare function extractBetterAuthOpenApi(authApi: Record<string, unknown>, options?: BetterAuthOpenApiOptions): ExternalOpenApiPaths;
 //#endregion
 //#region src/auth/trustedOrigins.d.ts
 /**
@@ -288,6 +318,6 @@ interface MirrorTrustedOriginsOptions {
  *     array.
  *   - `[canonicalUrl]` when `corsOrigins` is `false` / `undefined`.
  */
-declare function mirrorTrustedOriginsFromCors(options: MirrorTrustedOriginsOptions): string[];
+export declare function mirrorTrustedOriginsFromCors(options: MirrorTrustedOriginsOptions): string[];
 //#endregion
-export { type AuthPluginOptions, type BetterAuthAdapterOptions, type BetterAuthAdapterResult, type BetterAuthHandler, type BetterAuthOpenApiOptions, type CorsOriginsConfig, MemorySessionStore, type MemorySessionStoreOptions, type MirrorTrustedOriginsOptions, type SessionCookieOptions, type SessionData, type SessionManagerOptions, type SessionManagerResult, type SessionStore, _default as authPlugin, authPlugin as authPluginFn, createBetterAuthAdapter, createSessionManager, extractBetterAuthOpenApi, mirrorTrustedOriginsFromCors };
+export { type AuthPluginOptions, type BetterAuthAdapterOptions, type BetterAuthAdapterResult, type BetterAuthHandler, type BetterAuthOpenApiOptions, type CorsOriginsConfig, type CredentialVerifier, MemorySessionStore, type MemorySessionStoreOptions, type MirrorTrustedOriginsOptions, type SessionCookieOptions, type SessionData, type SessionManagerOptions, type SessionManagerResult, type SessionStore, _default as authPlugin, createSessionManager };