@classytic/arc 2.8.4 → 2.9.1

package/dist/EventTransport-CqZ8FyM_.d.mts

@@ -0,0 +1,293 @@
+//#region src/events/EventTransport.d.ts
+/**
+ * Event Transport Interface
+ *
+ * Defines contract for event delivery backends.
+ * Implement for durable transports (Redis, RabbitMQ, Kafka, etc.)
+ *
+ * @example
+ * // Redis Pub/Sub implementation
+ * class RedisEventTransport implements EventTransport {
+ *   async publish(event) {
+ *     await redis.publish(event.type, JSON.stringify(event));
+ *   }
+ *   async subscribe(pattern, handler) {
+ *     redis.psubscribe(pattern);
+ *     redis.on('pmessage', (p, channel, msg) => handler(JSON.parse(msg)));
+ *   }
+ * }
+ */
+/**
+ * Event metadata.
+ *
+ * Split out as a standalone interface so primitives / downstream packages can
+ * mirror it without re-declaring the DomainEvent wrapper. See events.ts in
+ * @classytic/primitives for the sibling shape.
+ */
+interface EventMeta {
+  /** Unique event ID (UUID v4 recommended) */
+  id: string;
+  /** Event timestamp */
+  timestamp: Date;
+  /**
+   * Schema version for this event type. Default: `1`.
+   *
+   * Use when the payload shape evolves so handlers can branch on version
+   * during migration windows (`if (event.meta.schemaVersion === 2) ...`).
+   * Bump ONLY when the payload contract changes in a breaking way.
+   */
+  schemaVersion?: number;
+  /**
+   * Correlation ID — stays stable across an entire causal chain so a single
+   * user action can be traced through every downstream event. Spans service
+   * boundaries. Generated at the edge (HTTP request, CLI invocation) and
+   * inherited by every child event.
+   */
+  correlationId?: string;
+  /**
+   * Causation ID — the `meta.id` of the direct parent event that caused
+   * this one. Forms a linked-list of cause-and-effect within a correlation.
+   *
+   * Distinct from correlationId: correlation groups, causation chains.
+   * Use {@link createChildEvent} to populate this automatically.
+   */
+  causationId?: string;
+  /**
+   * Partition key hint for ordered transports (Kafka, Kinesis, Redis Streams
+   * consumer groups). Events with the same partitionKey are guaranteed to be
+   * delivered in publish order by transports that honour it.
+   *
+   * Defaults to `resourceId` if unset. Transports that don't support ordering
+   * (in-memory, simple pub/sub) ignore this field.
+   */
+  partitionKey?: string;
+  /** Source resource (e.g. 'order', 'transaction') */
+  resource?: string;
+  /** Resource identifier */
+  resourceId?: string;
+  /** User who triggered the event */
+  userId?: string;
+  /** Organization context */
+  organizationId?: string;
+  /**
+   * Originating service or package (e.g. `'commerce'`, `'billing'`, `'arc-core'`).
+   *
+   * In a multi-service deployment, consumers route / log / alert by `source`
+   * without parsing `type` prefixes. Arc itself never populates this — hosts
+   * set it once per emitter (`app.events.publish('order.placed', p, { source: 'commerce' })`).
+   * Inherited by {@link createChildEvent} so downstream events carry the same
+   * source unless overridden.
+   */
+  source?: string;
+  /**
+   * Idempotency key — stable hint that this event represents a specific
+   * operation exactly once. Consumers dedupe with `if (processed.has(meta.idempotencyKey)) return`.
+   *
+   * Survives every transport (Memory / Pub-Sub / Streams / Kafka) because it's
+   * part of the event, not a transport-side option. Distinct from `meta.id`
+   * (which is fresh per emit — a retry would produce a new id).
+   *
+   * Typical sources: HTTP `Idempotency-Key` header, outbox `dedupeKey`, or
+   * `{aggregate.type}:{aggregate.id}:{action}`. Inherited by child events.
+   */
+  idempotencyKey?: string;
+  /**
+   * DDD aggregate marker — the aggregate that owns this event's invariant.
+   *
+   * Use when routing events by aggregate, doing event-sourcing replay, or
+   * enforcing consistency boundaries. Distinct from `resource` / `resourceId`
+   * (HTTP-origin entity) because an event emitted *by* one REST resource can
+   * *belong to* a different aggregate (e.g. `POST /orders/:id/ship` emits
+   * `shipment.dispatched` owned by a shipment aggregate).
+   *
+   * Downstream packages narrow `aggregate.type` to their own string union via
+   * interface extension:
+   *
+   * ```ts
+   * type CartAggregateType = 'cart' | 'cart-item';
+   * interface CartEventMeta extends EventMeta {
+   *   aggregate?: { type: CartAggregateType; id: string };
+   * }
+   * ```
+   *
+   * Not inherited by {@link createChildEvent} — child events typically belong
+   * to a different aggregate than their parent.
+   */
+  aggregate?: {
+    type: string;
+    id: string;
+  };
+}
+interface DomainEvent<T = unknown> {
+  /** Event type (e.g., 'product.created', 'order.shipped') */
+  type: string;
+  /** Event payload */
+  payload: T;
+  /** Event metadata */
+  meta: EventMeta;
+}
+type EventHandler<T = unknown> = (event: DomainEvent<T>) => void | Promise<void>;
+/**
+ * A permanently-failed event routed to a dead-letter sink after retries
+ * have been exhausted. Mirrors the shape a caller would log, alert on, or
+ * replay from once the upstream issue is fixed.
+ */
+interface DeadLetteredEvent<T = unknown> {
+  /** The original event */
+  event: DomainEvent<T>;
+  /** Serialised failure reason (message + optional machine code + stack) */
+  error: {
+    message: string;
+    code?: string;
+    stack?: string;
+  };
+  /** How many delivery attempts were made before giving up */
+  attempts: number;
+  /** First failure timestamp */
+  firstFailedAt: Date;
+  /** Last failure timestamp (immediately before dead-lettering) */
+  lastFailedAt: Date;
+  /** Optional handler / subscriber name that last failed (for debug) */
+  handlerName?: string;
+}
+/**
+ * Minimal logger interface for event transports.
+ * Compatible with `console`, `pino`, `fastify.log`, and any custom logger.
+ *
+ * @example
+ * ```typescript
+ * // Use Fastify's logger
+ * new MemoryEventTransport({ logger: fastify.log });
+ *
+ * // Use a custom logger
+ * new MemoryEventTransport({ logger: { warn: myWarn, error: myError } });
+ *
+ * // Default: console (no logger option needed)
+ * new MemoryEventTransport();
+ * ```
+ */
+interface EventLogger {
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+interface EventTransport {
+  /** Transport name for logging */
+  readonly name: string;
+  /**
+   * Publish an event to the transport
+   */
+  publish(event: DomainEvent): Promise<void>;
+  /**
+   * Publish a batch of events to the transport (optional, v2.8.1+).
+   *
+   * Transports that can efficiently batch (Kafka producer, Redis pipeline,
+   * RabbitMQ publisher confirms, SQS send-message-batch) should implement
+   * this. {@link import('./outbox.js').EventOutbox.relay} auto-detects and
+   * uses it for much higher throughput than per-event publishing.
+   *
+   * **Contract**: the returned `PublishManyResult` must describe the
+   * per-event outcome so the caller can acknowledge successes and fail the
+   * rest. Partial success is allowed — the transport reports it per event.
+   *
+   * If not implemented, `EventOutbox.relay` falls back to calling
+   * {@link publish} once per event.
+   *
+   * @param events - Events to publish (in order)
+   * @returns Per-event outcome map keyed by `event.meta.id`
+   */
+  publishMany?(events: readonly DomainEvent[]): Promise<PublishManyResult>;
+  /**
+   * Subscribe to events matching a pattern
+   * @param pattern - Event type pattern (e.g., 'product.*', '*')
+   * @param handler - Handler function
+   * @returns Unsubscribe function
+   */
+  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
+  /**
+   * Route a permanently-failed event to the transport's dead-letter sink
+   * (Kafka DLQ topic, SQS DLQ, Redis Stream `PEL` timeout handler, etc.).
+   *
+   * Called by {@link import('./outbox.js').EventOutbox} after exhausting
+   * retries. Transports that don't have a native DLQ can omit this —
+   * callers treat an absent `deadLetter` as "log and drop".
+   */
+  deadLetter?(dlq: DeadLetteredEvent): Promise<void>;
+  /**
+   * Close transport connections
+   */
+  close?(): Promise<void>;
+}
+/**
+ * Per-event outcome returned by {@link EventTransport.publishMany}.
+ *
+ * The key is `event.meta.id`; the value is `null` for success or an `Error`
+ * for per-event failure. Transports MUST include an entry for every event
+ * in the input batch.
+ */
+type PublishManyResult = ReadonlyMap<string, Error | null>;
+interface MemoryEventTransportOptions {
+  /** Logger for error/warning messages (default: console) */
+  logger?: EventLogger;
+}
+/**
+ * In-memory event transport (default)
+ * Events are delivered synchronously within the process.
+ * Not suitable for multi-instance deployments.
+ */
+declare class MemoryEventTransport implements EventTransport {
+  readonly name = "memory";
+  private handlers;
+  private logger;
+  constructor(options?: MemoryEventTransportOptions);
+  publish(event: DomainEvent): Promise<void>;
+  /**
+   * Reference `publishMany` implementation — delegates to `publish()` in order.
+   *
+   * Production transports (Kafka, Redis pipeline, SQS batch) should override
+   * this with a single batched network call. Memory transport has nothing to
+   * batch, so we just loop — the loop still returns a proper result map so
+   * `EventOutbox.relay` can exercise the batched code path in tests.
+   */
+  publishMany(events: readonly DomainEvent[]): Promise<PublishManyResult>;
+  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
+  close(): Promise<void>;
+}
+/**
+ * Create a domain event with auto-generated metadata.
+ *
+ * `id` and `timestamp` are filled in; everything else is caller-controlled.
+ * Set `schemaVersion` explicitly for any event type you plan to evolve.
+ */
+declare function createEvent<T>(type: string, payload: T, meta?: Partial<EventMeta>): DomainEvent<T>;
+/**
+ * Create a child event that chains causation from a parent event.
+ *
+ * Rules:
+ *  - `causationId` is set to the parent's `id` (direct cause)
+ *  - `correlationId` is inherited from the parent if set, else falls back
+ *    to the parent's `id` (root correlation)
+ *  - `userId` / `organizationId` are inherited when not overridden so the
+ *    whole chain stays scoped to the originating principal/tenant
+ *
+ * Caller-supplied `meta` wins over inherited fields — pass `{ userId: newActor }`
+ * to override when a subsystem acts on behalf of a different principal.
+ *
+ * @example
+ * ```typescript
+ * const orderPlaced = createEvent('order.placed', { orderId: 'o1' }, {
+ *   correlationId: req.id, userId: user.id,
+ * });
+ * await events.publish(orderPlaced);
+ *
+ * // Downstream handler emits a child event:
+ * const reserved = createChildEvent(orderPlaced, 'inventory.reserved', {
+ *   orderId: 'o1', skus: ['sku-1', 'sku-2'],
+ * });
+ * // reserved.meta.causationId   === orderPlaced.meta.id
+ * // reserved.meta.correlationId === orderPlaced.meta.correlationId
+ * // reserved.meta.userId        === user.id   (inherited)
+ * ```
+ */
+declare function createChildEvent<T>(parent: DomainEvent, type: string, payload: T, meta?: Partial<EventMeta>): DomainEvent<T>;
+//#endregion
+export { EventMeta as a, MemoryEventTransportOptions as c, createEvent as d, EventLogger as i, PublishManyResult as l, DomainEvent as n, EventTransport as o, EventHandler as r, MemoryEventTransport as s, DeadLetteredEvent as t, createChildEvent as u };

package/dist/adapters/index.d.mts

@@ -1,3 +1,3 @@
-import { a as RelationMetadata, c as ValidationResult, i as FieldMetadata, o as RepositoryLike, r as DataAdapter, s as SchemaMetadata, t as AdapterFactory } from "../interface-BVuMfeVv.mjs";
-import { a as PrismaQueryParserOptions, c as MongooseAdapterOptions, i as PrismaQueryParser, l as createMongooseAdapter, n as PrismaAdapterOptions, o as createPrismaAdapter, r as PrismaQueryOptions, s as MongooseAdapter, t as PrismaAdapter } from "../index-BgmMdpm8.mjs";
+import { a as RelationMetadata, c as ValidationResult, i as FieldMetadata, o as RepositoryLike, r as DataAdapter, s as SchemaMetadata, t as AdapterFactory } from "../interface-YrWsmKqE.mjs";
+import { a as PrismaQueryParserOptions, c as MongooseAdapterOptions, i as PrismaQueryParser, l as createMongooseAdapter, n as PrismaAdapterOptions, o as createPrismaAdapter, r as PrismaQueryOptions, s as MongooseAdapter, t as PrismaAdapter } from "../index-CtGKT0lf.mjs";
 export { AdapterFactory, DataAdapter, FieldMetadata, MongooseAdapter, MongooseAdapterOptions, PrismaAdapter, PrismaAdapterOptions, PrismaQueryOptions, PrismaQueryParser, PrismaQueryParserOptions, RelationMetadata, RepositoryLike, SchemaMetadata, ValidationResult, createMongooseAdapter, createPrismaAdapter };

package/dist/audit/index.d.mts

@@ -1,19 +1,108 @@
-import { a as AuditContext, c as AuditStore, i as AuditAction, l as AuditStoreOptions, n as MongoAuditStoreOptions, o as AuditEntry, r as MongoConnection, s as AuditQueryOptions, u as createAuditEntry } from "../mongodb-B8U2xaLj.mjs";
+import { o as RepositoryLike } from "../interface-YrWsmKqE.mjs";
+import { i as UserBase } from "../types-DZi1aYhm.mjs";
 import { FastifyPluginAsync } from "fastify";
 
+//#region src/audit/stores/interface.d.ts
+type AuditAction = "create" | "update" | "delete" | "restore" | "custom";
+interface AuditEntry {
+  /** Unique audit log ID */
+  id: string;
+  /** Resource name (e.g., 'product', 'user') */
+  resource: string;
+  /** Document/entity ID */
+  documentId: string;
+  /** Action performed */
+  action: AuditAction;
+  /** User who performed the action */
+  userId?: string;
+  /** Organization context */
+  organizationId?: string;
+  /** Previous state (for updates) */
+  before?: Record<string, unknown>;
+  /** New state (for creates/updates) */
+  after?: Record<string, unknown>;
+  /** Changed fields (for updates) */
+  changes?: string[];
+  /** Request ID for tracing */
+  requestId?: string;
+  /** IP address */
+  ipAddress?: string;
+  /** User agent */
+  userAgent?: string;
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+  /** When the action occurred */
+  timestamp: Date;
+}
+interface AuditContext {
+  user?: UserBase;
+  organizationId?: string;
+  requestId?: string;
+  ipAddress?: string;
+  userAgent?: string;
+  /** HTTP method + route pattern (e.g., 'PATCH /api/products/:id') */
+  endpoint?: string;
+  /** Request duration in milliseconds */
+  duration?: number;
+}
+interface AuditStoreOptions {
+  /** Store name for logging */
+  name: string;
+}
+/**
+ * Abstract audit store interface
+ */
+interface AuditStore {
+  /** Store name */
+  readonly name: string;
+  /** Log an audit entry */
+  log(entry: AuditEntry): Promise<void>;
+  /** Query audit logs (optional - not all stores support querying) */
+  query?(options: AuditQueryOptions): Promise<AuditEntry[]>;
+  /** Close/cleanup (optional) */
+  close?(): Promise<void>;
+}
+interface AuditQueryOptions {
+  resource?: string;
+  documentId?: string;
+  userId?: string;
+  organizationId?: string;
+  action?: AuditAction | AuditAction[];
+  from?: Date;
+  to?: Date;
+  limit?: number;
+  offset?: number;
+}
+/**
+ * Create audit entry from context
+ */
+declare function createAuditEntry(resource: string, documentId: string, action: AuditAction, context: AuditContext, data?: {
+  before?: Record<string, unknown>;
+  after?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}): AuditEntry;
+//#endregion
 //#region src/audit/auditPlugin.d.ts
 interface AuditPluginOptions {
   /** Enable audit logging (default: false) */
   enabled?: boolean;
-  /** Storage backends to use */
-  stores?: ("memory" | "mongodb")[];
-  /** MongoDB connection (required if using mongodb store) */
-  mongoConnection?: MongoConnection;
-  /** MongoDB collection name (default: 'audit_logs') */
-  mongoCollection?: string;
-  /** TTL in days for MongoDB (default: 90) */
-  ttlDays?: number;
-  /** Custom stores (advanced) */
+  /**
+   * Repository managing the audit collection. Arc consumes it **directly**
+   * — no wrapping, no aliases, no proxy classes. Pass any object that
+   * implements arc's `RepositoryLike` (mongokit's `Repository`, prismakit's
+   * repo, a custom implementation). Arc calls `repository.create(entry)` to
+   * log and `repository.findAll(filter, options)` to query.
+   *
+   * If neither `repository` nor `customStores` is provided, falls back to
+   * `MemoryAuditStore` (intended for dev / tests only).
+   */
+  repository?: RepositoryLike;
+  /**
+   * Custom audit stores — for backends that aren't repositories (Kafka, S3,
+   * OpenTelemetry exporter, etc.). Each must implement the `AuditStore`
+   * interface. `repository` and `customStores` compose: entries get logged
+   * to every store.
+   */
   customStores?: AuditStore[];
   /**
    * Automatically audit CRUD operations via the hook system (default: true when enabled).
@@ -101,4 +190,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, type MongoAuditStoreOptions, _default as auditPlugin, auditPlugin as auditPluginFn, createAuditEntry };
+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 };

package/dist/audit/index.mjs

@@ -1,5 +1,69 @@
-import { t as MongoAuditStore } from "../mongodb-B5O6xaW1.mjs";
 import fp from "fastify-plugin";
+//#region src/audit/repository-audit-adapter.ts
+function repositoryAsAuditStore(repository) {
+	return {
+		name: "repository",
+		async log(entry) {
+			const doc = {
+				_id: entry.id,
+				id: entry.id,
+				resource: entry.resource,
+				documentId: entry.documentId,
+				action: entry.action,
+				userId: entry.userId,
+				organizationId: entry.organizationId,
+				before: entry.before,
+				after: entry.after,
+				changes: entry.changes,
+				requestId: entry.requestId,
+				ipAddress: entry.ipAddress,
+				userAgent: entry.userAgent,
+				metadata: entry.metadata,
+				timestamp: entry.timestamp
+			};
+			await repository.create(doc);
+		},
+		async query(opts = {}) {
+			if (!repository.findAll) throw new Error("auditPlugin: repository.findAll is required for query(). mongokit ≥3.6 implements it; other kits should match.");
+			const filter = {};
+			if (opts.resource) filter.resource = opts.resource;
+			if (opts.documentId) filter.documentId = opts.documentId;
+			if (opts.userId) filter.userId = opts.userId;
+			if (opts.organizationId) filter.organizationId = opts.organizationId;
+			if (opts.action) {
+				const actions = Array.isArray(opts.action) ? opts.action : [opts.action];
+				filter.action = actions.length === 1 ? actions[0] : { $in: actions };
+			}
+			if (opts.from || opts.to) {
+				const range = {};
+				if (opts.from) range.$gte = opts.from;
+				if (opts.to) range.$lte = opts.to;
+				filter.timestamp = range;
+			}
+			return (await repository.findAll(filter, {
+				sort: { timestamp: -1 },
+				skip: opts.offset ?? 0,
+				limit: opts.limit ?? 100
+			})).map((d) => ({
+				id: String(d._id ?? d.id ?? ""),
+				resource: d.resource ?? "",
+				documentId: d.documentId ?? "",
+				action: d.action ?? "create",
+				userId: d.userId,
+				organizationId: d.organizationId,
+				before: d.before,
+				after: d.after,
+				changes: d.changes,
+				requestId: d.requestId,
+				ipAddress: d.ipAddress,
+				userAgent: d.userAgent,
+				metadata: d.metadata,
+				timestamp: d.timestamp ?? /* @__PURE__ */ new Date()
+			}));
+		}
+	};
+}
+//#endregion
 //#region src/audit/stores/interface.ts
 /**
 * Create audit entry from context
@@ -96,28 +160,17 @@ var MemoryAuditStore = class {
 //#endregion
 //#region src/audit/auditPlugin.ts
 const auditPlugin = async (fastify, opts = {}) => {
-	const { enabled = false, stores: storeTypes = ["memory"], mongoConnection, mongoCollection = "audit_logs", ttlDays = 90, customStores = [] } = opts;
+	const { enabled = false, repository, customStores = [] } = opts;
 	if (!enabled) {
 		fastify.decorate("audit", createNoopLogger());
 		fastify.decorateRequest("auditContext", void 0);
 		fastify.log?.debug?.("Audit plugin disabled");
 		return;
 	}
-	const stores = [...customStores];
-	for (const type of storeTypes) switch (type) {
-		case "memory":
-			stores.push(new MemoryAuditStore());
-			break;
-		case "mongodb":
-			if (!mongoConnection) throw new Error("Audit: mongoConnection required for mongodb store");
-			stores.push(new MongoAuditStore({
-				connection: mongoConnection,
-				collection: mongoCollection,
-				ttlDays
-			}));
-			break;
-	}
-	if (stores.length === 0) throw new Error("Audit: at least one store must be configured");
+	const stores = [];
+	if (repository) stores.push(repositoryAsAuditStore(repository));
+	stores.push(...customStores);
+	if (stores.length === 0) stores.push(new MemoryAuditStore());
 	async function logToStores(entry) {
 		await Promise.all(stores.map((store) => store.log(entry)));
 	}
@@ -232,7 +285,7 @@ const auditPlugin = async (fastify, opts = {}) => {
 			}, "Auto-audit hooks registered");
 		});
 	}
-	fastify.log?.debug?.({ stores: storeTypes }, "Audit plugin enabled");
+	fastify.log?.debug?.({ stores: stores.map((s) => s.name) }, "Audit plugin enabled");
 };
 /** Extract document ID from a result */
 function autoAuditExtractId(doc) {

package/dist/auth/index.d.mts

@@ -1,8 +1,8 @@
-import { b as AuthPluginOptions, y as AuthHelpers } from "../interface-BVuMfeVv.mjs";
-import { t as PermissionCheck } from "../types-CVC4HOKi.mjs";
+import { v as AuthHelpers, y as AuthPluginOptions } from "../interface-YrWsmKqE.mjs";
+import { t as PermissionCheck } from "../types-DZi1aYhm.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-Bapitwvd.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-D-oNWHz3.mjs";
-import { FastifyPluginAsync, FastifyReply as FastifyReply$1, FastifyRequest as FastifyRequest$1 } from "fastify";
+import { FastifyPluginAsync, FastifyReply as FastifyReply$1, FastifyRequest } from "fastify";
 
 //#region src/auth/authPlugin.d.ts
 declare module "fastify" {
@@ -17,6 +17,14 @@ declare module "fastify" {
     auth: AuthHelpers;
   }
 }
+/**
+ * Extract Bearer token from Authorization header.
+ *
+ * Exported for property-based test coverage — the contract is:
+ *  - header must start with exactly `"Bearer "` (case-sensitive, one space)
+ *  - everything after that prefix is returned verbatim (no trim, no parse)
+ *  - missing header → `null`; any other shape → `null`
+ */
 declare const authPlugin: FastifyPluginAsync<AuthPluginOptions>;
 declare const _default: FastifyPluginAsync<AuthPluginOptions>;
 //#endregion
@@ -90,9 +98,9 @@ interface BetterAuthAdapterResult {
   /** Fastify plugin that registers catch-all auth routes */
   plugin: FastifyPluginAsync;
   /** Authenticate preHandler -- validates session via Better Auth */
-  authenticate: (request: FastifyRequest$1, reply: FastifyReply$1) => Promise<void>;
+  authenticate: (request: FastifyRequest, reply: FastifyReply$1) => Promise<void>;
   /** Optional authenticate -- resolves session silently, continues as unauthenticated on failure */
-  optionalAuthenticate: (request: FastifyRequest$1, reply: FastifyReply$1) => Promise<void>;
+  optionalAuthenticate: (request: FastifyRequest, reply: FastifyReply$1) => Promise<void>;
   /** Permission helpers bound to this auth adapter (available when orgContext is enabled) */
   permissions: {
     requireOrgRole: (...roles: string[]) => PermissionCheck;
@@ -109,7 +117,7 @@ declare module "fastify" {
      * Validates session by calling Better Auth's session endpoint internally.
      * Set by the Better Auth adapter plugin.
      */
-    authenticate: (request: FastifyRequest$1, reply: FastifyReply$1) => Promise<void>;
+    authenticate: (request: FastifyRequest, reply: FastifyReply$1) => Promise<void>;
     /**
      * Optional authenticate middleware (Better Auth variant).
      * Tries to resolve session silently — populates request.user if valid,
@@ -117,7 +125,7 @@ declare module "fastify" {
      * Used on allowPublic() routes so downstream middleware can apply
      * org-scoped queries when a user IS authenticated.
      */
-    optionalAuthenticate: (request: FastifyRequest$1, reply: FastifyReply$1) => Promise<void>;
+    optionalAuthenticate: (request: FastifyRequest, reply: FastifyReply$1) => Promise<void>;
   }
 }
 /**

package/dist/auth/index.mjs

@@ -1,7 +1,7 @@
 import { n as normalizeRoles, t as getUserRoles } from "../types-ZUu_h0jp.mjs";
-import { t as ArcError } from "../errors-BF2bIOIS.mjs";
-import { h as requireTeamMembership, l as requireOrgMembership, u as requireOrgRole } from "../permissions-CH4cNwJi.mjs";
-import { n as extractBetterAuthOpenApi } from "../betterAuthOpenApi-C5lDyRH2.mjs";
+import { t as ArcError } from "../errors-CqWnSqM-.mjs";
+import { h as requireTeamMembership, l as requireOrgMembership, u as requireOrgRole } from "../permissions-oNZawnkR.mjs";
+import { n as extractBetterAuthOpenApi } from "../betterAuthOpenApi--rdY15Ld.mjs";
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/auth/authPlugin.ts
@@ -21,7 +21,12 @@ function parseExpiresIn(input, defaultValue) {
 	}[match[2]?.toLowerCase() ?? "s"] ?? 1);
 }
 /**
-* Extract Bearer token from Authorization header
+* Extract Bearer token from Authorization header.
+*
+* Exported for property-based test coverage — the contract is:
+*  - header must start with exactly `"Bearer "` (case-sensitive, one space)
+*  - everything after that prefix is returned verbatim (no trim, no parse)
+*  - missing header → `null`; any other shape → `null`
 */
 function extractBearerToken(request) {
 	const auth = request.headers.authorization;
@@ -29,7 +34,7 @@ function extractBearerToken(request) {
 	return auth.slice(7);
 }
 const authPlugin = async (fastify, opts = {}) => {
-	const { jwt: jwtConfig, authenticate: appAuthenticator, onFailure, userProperty = "user", exposeAuthErrors = false, tokenExtractor, isRevoked } = opts;
+	const { jwt: jwtConfig, authenticate: appAuthenticator, onFailure, userProperty = "user", exposeAuthErrors = false, tokenExtractor, isRevoked, strictTokenType = true } = opts;
 	/** Extract token from request — uses custom extractor if provided, else Bearer header */
 	const resolveToken = (request) => {
 		if (tokenExtractor) return tokenExtractor(request);
@@ -84,6 +89,7 @@ const authPlugin = async (fastify, opts = {}) => {
 				if (token) {
 					const decoded = jwtContext.verify(token);
 					if (decoded.type === "refresh") throw new Error("Refresh tokens cannot be used for authentication");
+					if (strictTokenType && decoded.type !== "access") throw new Error("Invalid token type: expected access token");
 					user = decoded;
 				}
 			} else throw new Error("No authenticator configured. Provide auth.authenticate function or auth.jwt.secret.");
@@ -146,6 +152,7 @@ const authPlugin = async (fastify, opts = {}) => {
 				if (token) {
 					const decoded = jwtContext.verify(token);
 					if (decoded.type === "refresh") return;
+					if (strictTokenType && decoded.type !== "access") return;
 					user = decoded;
 				}
 			}
@@ -677,7 +684,7 @@ function createBetterAuthAdapter(options) {
 		if (!fastify.hasDecorator("authenticate")) fastify.decorate("authenticate", authenticate);
 		if (!fastify.hasDecorator("optionalAuthenticate")) fastify.decorate("optionalAuthenticate", optionalAuthenticate);
 		if (!extractedOpenApi && openapiOpt !== false && auth.api && typeof auth.api === "object") {
-			const { extractBetterAuthOpenApi } = await import("../betterAuthOpenApi-C5lDyRH2.mjs").then((n) => n.t);
+			const { extractBetterAuthOpenApi } = await import("../betterAuthOpenApi--rdY15Ld.mjs").then((n) => n.t);
 			extractedOpenApi = extractBetterAuthOpenApi(auth.api, {
 				basePath,
 				userFields

package/dist/{betterAuthOpenApi-C5lDyRH2.mjs → betterAuthOpenApi--rdY15Ld.mjs}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
-import { a as toJsonSchema } from "./schemaConverter-OxfCshus.mjs";
+import { a as toJsonSchema } from "./schemaConverter-BxFDdtXu.mjs";
 //#region src/auth/betterAuthOpenApi.ts
 var betterAuthOpenApi_exports = /* @__PURE__ */ __exportAll({ extractBetterAuthOpenApi: () => extractBetterAuthOpenApi });
 /**