@classytic/arc 1.1.0 → 2.1.2

package/dist/idempotency/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/idempotency/stores/interface.ts","../../src/idempotency/stores/memory.ts","../../src/idempotency/idempotencyPlugin.ts"],"sourcesContent":["/**\n * Idempotency Store Interface\n *\n * Defines the contract for idempotency key storage backends.\n * Implement this interface for custom stores (Redis, DynamoDB, etc.)\n */\n\nexport interface IdempotencyResult {\n  /** The idempotency key */\n  key: string;\n  /** HTTP status code of the cached response */\n  statusCode: number;\n  /** Response headers to replay */\n  headers: Record<string, string>;\n  /** Response body */\n  body: unknown;\n  /** When this entry was created */\n  createdAt: Date;\n  /** When this entry expires */\n  expiresAt: Date;\n}\n\nexport interface IdempotencyLock {\n  /** The idempotency key being locked */\n  key: string;\n  /** Request ID that holds the lock */\n  requestId: string;\n  /** When the lock was acquired */\n  lockedAt: Date;\n  /** When the lock expires (auto-release) */\n  expiresAt: Date;\n}\n\nexport interface IdempotencyStore {\n  /** Store name for logging */\n  readonly name: string;\n\n  /**\n   * Get a cached result for an idempotency key.\n   * Returns undefined if not found or expired.\n   */\n  get(key: string): Promise<IdempotencyResult | undefined>;\n\n  /**\n   * Store a result for an idempotency key.\n   * TTL is handled by the store implementation.\n   */\n  set(key: string, result: Omit<IdempotencyResult, 'key'>): Promise<void>;\n\n  /**\n   * Try to acquire a lock for processing a key.\n   * Returns true if lock acquired, false if already locked.\n   */\n  tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;\n\n  /** Release a lock after processing complete */\n  unlock(key: string, requestId: string): Promise<void>;\n\n  /** Check if a key is currently locked */\n  isLocked(key: string): Promise<boolean>;\n\n  /** Delete a cached result by exact key */\n  delete(key: string): Promise<void>;\n\n  /**\n   * Delete all cached results whose key starts with the given prefix.\n   * Used by invalidate() to clear entries by raw idempotency key\n   * regardless of fingerprint.\n   * Returns the number of entries deleted.\n   */\n  deleteByPrefix(prefix: string): Promise<number>;\n\n  /**\n   * Find the first cached result whose key starts with the given prefix.\n   * Used by has() to check if any entry exists for a raw idempotency key.\n   * Returns undefined if no matching entry found.\n   */\n  findByPrefix(prefix: string): Promise<IdempotencyResult | undefined>;\n\n  /** Close the store (cleanup connections) */\n  close?(): Promise<void>;\n}\n\n/**\n * Helper to create a result object\n */\nexport function createIdempotencyResult(\n  statusCode: number,\n  body: unknown,\n  headers: Record<string, string>,\n  ttlMs: number\n): Omit<IdempotencyResult, 'key'> {\n  const now = new Date();\n  return {\n    statusCode,\n    headers,\n    body,\n    createdAt: now,\n    expiresAt: new Date(now.getTime() + ttlMs),\n  };\n}\n","/**\n * In-Memory Idempotency Store\n *\n * Default store for development and small deployments.\n * NOT suitable for multi-instance deployments - use Redis or similar.\n *\n * Features:\n * - Automatic TTL expiration\n * - Lock support for concurrent request handling\n * - Periodic cleanup of expired entries\n * - Prefix-based operations for raw key invalidation\n */\n\nimport type { IdempotencyResult, IdempotencyStore, IdempotencyLock } from './interface.js';\n\nexport interface MemoryIdempotencyStoreOptions {\n  /** Default TTL in milliseconds (default: 86400000 = 24h) */\n  ttlMs?: number;\n  /** Cleanup interval in milliseconds (default: 60000 = 1 min) */\n  cleanupIntervalMs?: number;\n  /** Maximum entries before oldest are evicted (default: 10000) */\n  maxEntries?: number;\n}\n\nexport class MemoryIdempotencyStore implements IdempotencyStore {\n  readonly name = 'memory';\n  private results: Map<string, IdempotencyResult> = new Map();\n  private locks: Map<string, IdempotencyLock> = new Map();\n  private ttlMs: number;\n  private maxEntries: number;\n  private cleanupInterval: ReturnType<typeof setInterval> | null = null;\n\n  constructor(options: MemoryIdempotencyStoreOptions = {}) {\n    this.ttlMs = options.ttlMs ?? 86400000; // 24 hours\n    this.maxEntries = options.maxEntries ?? 10000;\n\n    // Start cleanup timer\n    const cleanupIntervalMs = options.cleanupIntervalMs ?? 60000;\n    this.cleanupInterval = setInterval(() => {\n      this.cleanup();\n    }, cleanupIntervalMs);\n\n    // Don't keep Node process alive just for cleanup\n    if (this.cleanupInterval.unref) {\n      this.cleanupInterval.unref();\n    }\n  }\n\n  async get(key: string): Promise<IdempotencyResult | undefined> {\n    const result = this.results.get(key);\n    if (!result) return undefined;\n\n    // Check expiration\n    if (new Date() > result.expiresAt) {\n      this.results.delete(key);\n      return undefined;\n    }\n\n    return result;\n  }\n\n  async set(key: string, result: Omit<IdempotencyResult, 'key'>): Promise<void> {\n    // Evict oldest if at capacity\n    if (this.results.size >= this.maxEntries) {\n      this.evictOldest();\n    }\n\n    this.results.set(key, { ...result, key });\n  }\n\n  async tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean> {\n    const existing = this.locks.get(key);\n\n    if (existing) {\n      // Check if lock expired\n      if (new Date() > existing.expiresAt) {\n        this.locks.delete(key);\n      } else {\n        // Lock held by someone else\n        return false;\n      }\n    }\n\n    // Acquire lock\n    this.locks.set(key, {\n      key,\n      requestId,\n      lockedAt: new Date(),\n      expiresAt: new Date(Date.now() + ttlMs),\n    });\n\n    return true;\n  }\n\n  async unlock(key: string, requestId: string): Promise<void> {\n    const lock = this.locks.get(key);\n    if (lock && lock.requestId === requestId) {\n      this.locks.delete(key);\n    }\n  }\n\n  async isLocked(key: string): Promise<boolean> {\n    const lock = this.locks.get(key);\n    if (!lock) return false;\n\n    // Check if expired\n    if (new Date() > lock.expiresAt) {\n      this.locks.delete(key);\n      return false;\n    }\n\n    return true;\n  }\n\n  async delete(key: string): Promise<void> {\n    this.results.delete(key);\n    this.locks.delete(key);\n  }\n\n  async deleteByPrefix(prefix: string): Promise<number> {\n    let count = 0;\n    for (const key of this.results.keys()) {\n      if (key.startsWith(prefix)) {\n        this.results.delete(key);\n        count++;\n      }\n    }\n    for (const key of this.locks.keys()) {\n      if (key.startsWith(prefix)) {\n        this.locks.delete(key);\n      }\n    }\n    return count;\n  }\n\n  async findByPrefix(prefix: string): Promise<IdempotencyResult | undefined> {\n    const now = new Date();\n    for (const [key, result] of this.results) {\n      if (key.startsWith(prefix)) {\n        if (now > result.expiresAt) {\n          this.results.delete(key);\n          continue;\n        }\n        return result;\n      }\n    }\n    return undefined;\n  }\n\n  async close(): Promise<void> {\n    if (this.cleanupInterval) {\n      clearInterval(this.cleanupInterval);\n      this.cleanupInterval = null;\n    }\n    this.results.clear();\n    this.locks.clear();\n  }\n\n  /** Get current stats (for debugging/monitoring) */\n  getStats(): { results: number; locks: number } {\n    return {\n      results: this.results.size,\n      locks: this.locks.size,\n    };\n  }\n\n  private cleanup(): void {\n    const now = new Date();\n\n    for (const [key, result] of this.results) {\n      if (now > result.expiresAt) {\n        this.results.delete(key);\n      }\n    }\n\n    for (const [key, lock] of this.locks) {\n      if (now > lock.expiresAt) {\n        this.locks.delete(key);\n      }\n    }\n  }\n\n  private evictOldest(): void {\n    const entries = Array.from(this.results.entries())\n      .sort((a, b) => a[1].createdAt.getTime() - b[1].createdAt.getTime());\n\n    const toRemove = Math.max(1, Math.floor(entries.length * 0.1));\n    for (let i = 0; i < toRemove; i++) {\n      const entry = entries[i];\n      if (entry) {\n        this.results.delete(entry[0]);\n      }\n    }\n  }\n}\n\nexport default MemoryIdempotencyStore;\n","/**\n * Idempotency Plugin\n *\n * Duplicate request protection for mutating operations.\n * Uses idempotency keys to ensure safe retries.\n *\n * ## Auth Safety\n *\n * The idempotency check runs as a **route-level middleware**\n * (`idempotency.middleware`) that must be wired AFTER authentication in the\n * preHandler chain. This ensures the fingerprint includes the real caller\n * identity, preventing cross-user replay attacks.\n *\n * Arc's `createCrudRouter` does this automatically for mutation routes.\n * For custom routes, wire it manually:\n *\n * ```typescript\n * fastify.post('/orders', {\n *   preHandler: [fastify.authenticate, fastify.idempotency.middleware],\n * }, handler);\n * ```\n *\n * @example\n * import { idempotencyPlugin } from '@classytic/arc/idempotency';\n *\n * await fastify.register(idempotencyPlugin, {\n *   enabled: true,\n *   headerName: 'idempotency-key',\n *   ttlMs: 86400000, // 24 hours\n * });\n *\n * // Client sends:\n * // POST /api/orders\n * // Idempotency-Key: order-123-abc\n *\n * // If same key sent again within TTL, returns cached response\n */\n\nimport fp from 'fastify-plugin';\nimport { createHash } from 'crypto';\nimport type { FastifyInstance, FastifyPluginAsync, FastifyRequest, FastifyReply } from 'fastify';\nimport type { IdempotencyStore } from './stores/interface.js';\nimport { createIdempotencyResult } from './stores/interface.js';\nimport { MemoryIdempotencyStore } from './stores/memory.js';\n\nexport interface IdempotencyPluginOptions {\n  /** Enable idempotency (default: false) */\n  enabled?: boolean;\n  /** Header name for idempotency key (default: 'idempotency-key') */\n  headerName?: string;\n  /** TTL for cached responses in ms (default: 86400000 = 24h) */\n  ttlMs?: number;\n  /** Lock timeout in ms (default: 30000 = 30s) */\n  lockTimeoutMs?: number;\n  /** HTTP methods to apply idempotency to (default: ['POST', 'PUT', 'PATCH']) */\n  methods?: string[];\n  /** URL patterns to include (regex). If set, only matching URLs use idempotency */\n  include?: RegExp[];\n  /** URL patterns to exclude (regex). Excluded patterns take precedence */\n  exclude?: RegExp[];\n  /** Custom store (default: MemoryIdempotencyStore) */\n  store?: IdempotencyStore;\n  /** Retry-After header value in seconds when request is in-flight (default: 1) */\n  retryAfterSeconds?: number;\n}\n\ndeclare module 'fastify' {\n  interface FastifyRequest {\n    /** The idempotency key for this request (if present) */\n    idempotencyKey?: string;\n    /** Whether this response was replayed from cache */\n    idempotencyReplayed?: boolean;\n    /** @internal Full key with fingerprint for store lookups */\n    _idempotencyFullKey?: string;\n  }\n\n  interface FastifyInstance {\n    /** Idempotency utilities */\n    idempotency: {\n      /** Manually invalidate an idempotency key */\n      invalidate: (key: string) => Promise<void>;\n      /** Check if a key has a cached response */\n      has: (key: string) => Promise<boolean>;\n      /**\n       * Route-level preHandler for idempotency check + lock.\n       * Wire AFTER authenticate in the preHandler chain so that\n       * `request.user` is populated before the fingerprint is computed.\n       *\n       * `createCrudRouter` injects this automatically for mutation routes.\n       * For custom routes, add it manually:\n       * ```typescript\n       * fastify.post('/orders', {\n       *   preHandler: [fastify.authenticate, fastify.idempotency.middleware],\n       * }, handler);\n       * ```\n       */\n      middleware: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;\n    };\n  }\n}\n\nconst HEADER_IDEMPOTENCY_REPLAYED = 'x-idempotency-replayed';\nconst HEADER_IDEMPOTENCY_KEY = 'x-idempotency-key';\n\nconst idempotencyPlugin: FastifyPluginAsync<IdempotencyPluginOptions> = async (\n  fastify: FastifyInstance,\n  opts: IdempotencyPluginOptions = {}\n) => {\n  const {\n    enabled = false,\n    headerName = 'idempotency-key',\n    ttlMs = 86400000, // 24 hours\n    lockTimeoutMs = 30000, // 30 seconds\n    methods = ['POST', 'PUT', 'PATCH'],\n    include,\n    exclude,\n    store = new MemoryIdempotencyStore({ ttlMs }),\n    retryAfterSeconds = 1,\n  } = opts;\n\n  // Skip if not enabled\n  if (!enabled) {\n    // Provide no-op utilities\n    fastify.decorate('idempotency', {\n      invalidate: async () => {},\n      has: async () => false,\n      middleware: async () => {},\n    });\n    fastify.decorateRequest('idempotencyKey', undefined);\n    fastify.decorateRequest('idempotencyReplayed', false);\n    fastify.log?.debug?.('Idempotency plugin disabled');\n    return;\n  }\n\n  const methodSet = new Set(methods.map((m) => m.toUpperCase()));\n\n  fastify.decorateRequest('idempotencyKey', undefined);\n  fastify.decorateRequest('idempotencyReplayed', false);\n\n  /**\n   * Check if this request should use idempotency\n   */\n  function shouldApplyIdempotency(request: FastifyRequest): boolean {\n    // Check method\n    if (!methodSet.has(request.method)) {\n      return false;\n    }\n\n    const url = request.url;\n\n    // Check exclusions first (take precedence)\n    if (exclude?.some((pattern) => pattern.test(url))) {\n      return false;\n    }\n\n    // Check inclusions (if specified, only matching URLs apply)\n    if (include && !include.some((pattern) => pattern.test(url))) {\n      return false;\n    }\n\n    return true;\n  }\n\n  /**\n   * Normalize body for consistent hashing (sort keys recursively)\n   */\n  function normalizeBody(obj: unknown): unknown {\n    if (obj === null || typeof obj !== 'object') {\n      return obj;\n    }\n\n    if (Array.isArray(obj)) {\n      return obj.map(normalizeBody);\n    }\n\n    // Sort object keys\n    const sorted: Record<string, unknown> = {};\n    const keys = Object.keys(obj).sort();\n    for (const key of keys) {\n      sorted[key] = normalizeBody((obj as Record<string, unknown>)[key]);\n    }\n    return sorted;\n  }\n\n  /**\n   * Generate a fingerprint for the request (for key generation).\n   * Includes caller identity so the same idempotency key from different\n   * users doesn't replay one user's response to another.\n   *\n   * IMPORTANT: This must be called AFTER auth has populated request.user,\n   * otherwise userId falls back to 'anon' and cross-user replay is possible.\n   */\n  function getRequestFingerprint(request: FastifyRequest): string {\n    // Combine method + URL + body hash + user identity for uniqueness\n    let bodyHash = 'nobody';\n\n    if (request.body && typeof request.body === 'object') {\n      // Normalize body (sort keys) for consistent hashing\n      const normalized = normalizeBody(request.body);\n      const bodyString = JSON.stringify(normalized);\n      bodyHash = createHash('sha256').update(bodyString).digest('hex').substring(0, 16);\n      // SECURITY: Only log hash, never log full body (can contain secrets)\n      if (request.log && request.log.debug) {\n        request.log.debug({ bodyHash }, 'Generated body hash');\n      }\n    }\n\n    // Scope to caller identity to prevent cross-user replay\n    const user = request.user as { id?: string; _id?: string } | undefined;\n    const userId = user?.id ?? user?._id ?? 'anon';\n\n    const fingerprint = `${request.method}:${request.url}:${bodyHash}:u=${userId}`;\n    return fingerprint;\n  }\n\n  // ---- Route-level middleware: check + lock (AFTER auth) ----\n  const idempotencyMiddleware = async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {\n    if (!shouldApplyIdempotency(request)) {\n      return;\n    }\n\n    // Get idempotency key from header\n    const keyHeader = request.headers[headerName.toLowerCase()];\n    const idempotencyKey = typeof keyHeader === 'string' ? keyHeader.trim() : undefined;\n\n    if (!idempotencyKey) {\n      // No key provided - proceed normally\n      return;\n    }\n\n    // Store key on request for later use\n    request.idempotencyKey = idempotencyKey;\n\n    // Create full key with request fingerprint (user is now populated by auth)\n    const fullKey = `${idempotencyKey}:${getRequestFingerprint(request)}`;\n\n    // Check for cached result\n    const cached = await store.get(fullKey);\n    if (cached) {\n      // Replay cached response\n      request.idempotencyReplayed = true;\n\n      // Set response headers\n      reply.header(HEADER_IDEMPOTENCY_REPLAYED, 'true');\n      reply.header(HEADER_IDEMPOTENCY_KEY, idempotencyKey);\n\n      // Replay original headers\n      for (const [key, value] of Object.entries(cached.headers)) {\n        if (!key.startsWith('x-idempotency')) {\n          reply.header(key, value);\n        }\n      }\n\n      reply.code(cached.statusCode).send(cached.body);\n      return;\n    }\n\n    // Try to acquire lock\n    const lockAcquired = await store.tryLock(fullKey, request.id, lockTimeoutMs);\n    if (!lockAcquired) {\n      // Another request is processing this key\n      reply\n        .code(409)\n        .header('Retry-After', retryAfterSeconds.toString())\n        .send({\n          error: 'Request with this idempotency key is already in progress',\n          code: 'IDEMPOTENCY_CONFLICT',\n          retryAfter: retryAfterSeconds,\n        });\n      return;\n    }\n\n    // Store full key for onSend hook\n    request._idempotencyFullKey = fullKey;\n  };\n\n  // Decorate with utilities + middleware\n  fastify.decorate('idempotency', {\n    invalidate: async (key: string) => {\n      // Delete all entries for this raw idempotency key regardless of fingerprint\n      await store.deleteByPrefix(`${key}:`);\n    },\n    has: async (key: string) => {\n      // Check if any entry exists for this raw idempotency key\n      const result = await store.findByPrefix(`${key}:`);\n      return !!result;\n    },\n    middleware: idempotencyMiddleware,\n  });\n\n  // Store response after successful request\n  fastify.addHook('onSend', async (request, reply, payload) => {\n    // Skip if this was a replayed response\n    if (request.idempotencyReplayed) {\n      return payload;\n    }\n\n    const fullKey = request._idempotencyFullKey;\n    if (!fullKey) {\n      return payload;\n    }\n\n    // Only cache successful responses (2xx)\n    const statusCode = reply.statusCode;\n    if (statusCode < 200 || statusCode >= 300) {\n      // Unlock without caching\n      await store.unlock(fullKey, request.id);\n      return payload;\n    }\n\n    // Extract headers to cache (exclude certain headers)\n    const headersToCache: Record<string, string> = {};\n    const excludeHeaders = new Set([\n      'content-length',\n      'transfer-encoding',\n      'connection',\n      'keep-alive',\n      'date',\n      'set-cookie',\n    ]);\n\n    const rawHeaders = reply.getHeaders();\n    for (const [key, value] of Object.entries(rawHeaders)) {\n      if (!excludeHeaders.has(key.toLowerCase()) && typeof value === 'string') {\n        headersToCache[key] = value;\n      }\n    }\n\n    // Parse body if it's a string\n    let body: unknown;\n    try {\n      body = typeof payload === 'string' ? JSON.parse(payload) : payload;\n    } catch {\n      body = payload;\n    }\n\n    // Store the result\n    const result = createIdempotencyResult(statusCode, body, headersToCache, ttlMs);\n    await store.set(fullKey, result);\n\n    // Unlock (result is now cached)\n    await store.unlock(fullKey, request.id);\n\n    // Add idempotency key header to response\n    reply.header(HEADER_IDEMPOTENCY_KEY, request.idempotencyKey);\n\n    return payload;\n  });\n\n  // Handle errors - ensure lock is released\n  fastify.addHook('onError', async (request) => {\n    const fullKey = request._idempotencyFullKey;\n    if (fullKey) {\n      await store.unlock(fullKey, request.id);\n    }\n  });\n\n  // Cleanup on close\n  fastify.addHook('onClose', async () => {\n    await store.close?.();\n  });\n\n  fastify.log?.debug?.({ headerName, ttlMs, methods }, 'Idempotency plugin enabled');\n};\n\nexport default fp(idempotencyPlugin, {\n  name: 'arc-idempotency',\n  fastify: '5.x',\n});\n\nexport { idempotencyPlugin };\n"],"mappings":"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"}

package/dist/idempotency/mongodb.d.mts

@@ -0,0 +1,2 @@
+import { n as MongoIdempotencyStoreOptions, t as MongoIdempotencyStore } from "../mongodb-JN-9JA7K.mjs";
+export { MongoIdempotencyStore, type MongoIdempotencyStoreOptions };

package/dist/idempotency/mongodb.mjs

@@ -0,0 +1,115 @@
+//#region src/idempotency/stores/mongodb.ts
+var MongoIdempotencyStore = class {
+	name = "mongodb";
+	connection;
+	collectionName;
+	ttlMs;
+	indexCreated = false;
+	constructor(options) {
+		this.connection = options.connection;
+		this.collectionName = options.collection ?? "arc_idempotency";
+		this.ttlMs = options.ttlMs ?? 864e5;
+		if (options.createIndex !== false) this.ensureIndex().catch((err) => {
+			console.warn("[MongoIdempotencyStore] Failed to create index:", err);
+		});
+	}
+	get collection() {
+		return this.connection.db.collection(this.collectionName);
+	}
+	async ensureIndex() {
+		if (this.indexCreated) return;
+		try {
+			await this.collection.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 });
+			this.indexCreated = true;
+		} catch {
+			this.indexCreated = true;
+		}
+	}
+	async get(key) {
+		const doc = await this.collection.findOne({ _id: key });
+		if (!doc || !doc.result) return void 0;
+		if (new Date(doc.expiresAt) < /* @__PURE__ */ new Date()) return;
+		return {
+			key,
+			statusCode: doc.result.statusCode,
+			headers: doc.result.headers,
+			body: doc.result.body,
+			createdAt: new Date(doc.createdAt),
+			expiresAt: new Date(doc.expiresAt)
+		};
+	}
+	async set(key, result) {
+		await this.collection.updateOne({ _id: key }, {
+			$set: {
+				result: {
+					statusCode: result.statusCode,
+					headers: result.headers,
+					body: result.body
+				},
+				createdAt: result.createdAt,
+				expiresAt: result.expiresAt
+			},
+			$unset: { lock: "" }
+		}, { upsert: true });
+	}
+	async tryLock(key, requestId, ttlMs) {
+		const now = /* @__PURE__ */ new Date();
+		const expiresAt = new Date(now.getTime() + ttlMs);
+		try {
+			const result = await this.collection.updateOne({
+				_id: key,
+				$or: [{ lock: { $exists: false } }, { "lock.expiresAt": { $lt: now } }]
+			}, {
+				$set: { lock: {
+					requestId,
+					expiresAt
+				} },
+				$setOnInsert: {
+					createdAt: now,
+					expiresAt: new Date(now.getTime() + this.ttlMs)
+				}
+			}, { upsert: true });
+			return result.matchedCount === 1 || result.modifiedCount === 1;
+		} catch {
+			return false;
+		}
+	}
+	async unlock(key, requestId) {
+		await this.collection.updateOne({
+			_id: key,
+			"lock.requestId": requestId
+		}, { $unset: { lock: "" } });
+	}
+	async isLocked(key) {
+		const doc = await this.collection.findOne({ _id: key });
+		if (!doc || !doc.lock) return false;
+		return new Date(doc.lock.expiresAt) > /* @__PURE__ */ new Date();
+	}
+	async delete(key) {
+		await this.collection.deleteOne({ _id: key });
+	}
+	async deleteByPrefix(prefix) {
+		return (await this.collection.deleteMany({ _id: { $regex: `^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}` } })).deletedCount;
+	}
+	async findByPrefix(prefix) {
+		const doc = await this.collection.findOne({
+			_id: { $regex: `^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}` },
+			result: { $exists: true },
+			expiresAt: { $gt: /* @__PURE__ */ new Date() }
+		});
+		if (!doc || !doc.result) return void 0;
+		return {
+			key: doc._id,
+			statusCode: doc.result.statusCode,
+			headers: doc.result.headers,
+			body: doc.result.body,
+			createdAt: new Date(doc.createdAt),
+			expiresAt: new Date(doc.expiresAt)
+		};
+	}
+	async close() {}
+};
+
+//#endregion
+export { MongoIdempotencyStore };
+//# sourceMappingURL=mongodb.mjs.map

package/dist/idempotency/mongodb.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongodb.mjs","names":[],"sources":["../../src/idempotency/stores/mongodb.ts"],"sourcesContent":["/**\n * MongoDB Idempotency Store\n *\n * Durable idempotency store using MongoDB.\n * Suitable for multi-instance deployments.\n *\n * @example\n * import mongoose from 'mongoose';\n * import { MongoIdempotencyStore } from '@classytic/arc/idempotency';\n *\n * await fastify.register(idempotencyPlugin, {\n *   store: new MongoIdempotencyStore({\n *     connection: mongoose.connection,\n *     collection: 'idempotency_keys',\n *   }),\n * });\n */\n\nimport type { IdempotencyStore, IdempotencyResult } from './interface.js';\n\nexport interface MongoConnection {\n  db: {\n    collection(name: string): MongoCollection;\n  };\n}\n\ninterface MongoCollection {\n  findOne(filter: object): Promise<IdempotencyDocument | null>;\n  insertOne(doc: object): Promise<{ acknowledged: boolean }>;\n  updateOne(filter: object, update: object, options?: object): Promise<{ acknowledged: boolean; matchedCount: number; modifiedCount: number }>;\n  deleteOne(filter: object): Promise<{ deletedCount: number }>;\n  deleteMany(filter: object): Promise<{ deletedCount: number }>;\n  createIndex(spec: object, options?: object): Promise<string>;\n}\n\ninterface IdempotencyDocument {\n  _id: string;\n  result?: {\n    statusCode: number;\n    headers: Record<string, string>;\n    body: unknown;\n  };\n  lock?: {\n    requestId: string;\n    expiresAt: Date;\n  };\n  createdAt: Date;\n  expiresAt: Date;\n}\n\nexport interface MongoIdempotencyStoreOptions {\n  /** Mongoose connection or MongoDB connection object */\n  connection: MongoConnection;\n  /** Collection name (default: 'arc_idempotency') */\n  collection?: string;\n  /** Create TTL index on startup (default: true) */\n  createIndex?: boolean;\n  /** Default TTL in ms (default: 86400000 = 24 hours) */\n  ttlMs?: number;\n}\n\nexport class MongoIdempotencyStore implements IdempotencyStore {\n  readonly name = 'mongodb';\n  private connection: MongoConnection;\n  private collectionName: string;\n  private ttlMs: number;\n  private indexCreated = false;\n\n  constructor(options: MongoIdempotencyStoreOptions) {\n    this.connection = options.connection;\n    this.collectionName = options.collection ?? 'arc_idempotency';\n    this.ttlMs = options.ttlMs ?? 86400000;\n\n    if (options.createIndex !== false) {\n      this.ensureIndex().catch((err) => {\n        console.warn('[MongoIdempotencyStore] Failed to create index:', err);\n      });\n    }\n  }\n\n  private get collection(): MongoCollection {\n    return this.connection.db.collection(this.collectionName);\n  }\n\n  private async ensureIndex(): Promise<void> {\n    if (this.indexCreated) return;\n    try {\n      // TTL index for automatic cleanup\n      await this.collection.createIndex(\n        { expiresAt: 1 },\n        { expireAfterSeconds: 0 }\n      );\n      this.indexCreated = true;\n    } catch {\n      // Index might already exist\n      this.indexCreated = true;\n    }\n  }\n\n  async get(key: string): Promise<IdempotencyResult | undefined> {\n    const doc = await this.collection.findOne({ _id: key });\n    if (!doc || !doc.result) return undefined;\n\n    // Check expiration\n    if (new Date(doc.expiresAt) < new Date()) {\n      return undefined;\n    }\n\n    return {\n      key,\n      statusCode: doc.result.statusCode,\n      headers: doc.result.headers,\n      body: doc.result.body,\n      createdAt: new Date(doc.createdAt),\n      expiresAt: new Date(doc.expiresAt),\n    };\n  }\n\n  async set(key: string, result: Omit<IdempotencyResult, 'key'>): Promise<void> {\n    await this.collection.updateOne(\n      { _id: key },\n      {\n        $set: {\n          result: {\n            statusCode: result.statusCode,\n            headers: result.headers,\n            body: result.body,\n          },\n          createdAt: result.createdAt,\n          expiresAt: result.expiresAt,\n        },\n        $unset: { lock: '' },\n      },\n      { upsert: true }\n    );\n  }\n\n  async tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean> {\n    const now = new Date();\n    const expiresAt = new Date(now.getTime() + ttlMs);\n\n    try {\n      // Atomic upsert: acquire lock only when no active lock exists.\n      // Uses a single updateOne with upsert to avoid TOCTOU races —\n      // matchedCount/upsertedCount tells us if WE acquired the lock\n      // (not just that MongoDB acknowledged the command).\n      const result = await this.collection.updateOne(\n        {\n          _id: key,\n          $or: [\n            { lock: { $exists: false } },\n            { 'lock.expiresAt': { $lt: now } },\n          ],\n        },\n        {\n          $set: {\n            lock: { requestId, expiresAt },\n          },\n          $setOnInsert: {\n            createdAt: now,\n            expiresAt: new Date(now.getTime() + this.ttlMs),\n          },\n        },\n        { upsert: true },\n      );\n\n      // matchedCount === 1: existing doc matched (lock was free/expired)\n      // modifiedCount can be 0 if the $set value is identical — use matchedCount\n      // upsertedCount === 1 (implied by acknowledged + matchedCount === 0):\n      //   new doc created with our lock\n      return result.matchedCount === 1 || result.modifiedCount === 1;\n    } catch {\n      // Duplicate key on upsert race or other error → someone else got the lock\n      return false;\n    }\n  }\n\n  async unlock(key: string, requestId: string): Promise<void> {\n    // Only unlock if we hold the lock\n    await this.collection.updateOne(\n      { _id: key, 'lock.requestId': requestId },\n      { $unset: { lock: '' } }\n    );\n  }\n\n  async isLocked(key: string): Promise<boolean> {\n    const doc = await this.collection.findOne({ _id: key });\n    if (!doc || !doc.lock) return false;\n    return new Date(doc.lock.expiresAt) > new Date();\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.collection.deleteOne({ _id: key });\n  }\n\n  async deleteByPrefix(prefix: string): Promise<number> {\n    const result = await this.collection.deleteMany({\n      _id: { $regex: `^${prefix.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}` },\n    });\n    return result.deletedCount;\n  }\n\n  async findByPrefix(prefix: string): Promise<IdempotencyResult | undefined> {\n    // Filter expired docs at the query level so MongoDB doesn't return a stale\n    // entry when a valid one exists further down the index.\n    const doc = await this.collection.findOne({\n      _id: { $regex: `^${prefix.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}` },\n      result: { $exists: true },\n      expiresAt: { $gt: new Date() },\n    });\n    if (!doc || !doc.result) return undefined;\n\n    return {\n      key: doc._id,\n      statusCode: doc.result.statusCode,\n      headers: doc.result.headers,\n      body: doc.result.body,\n      createdAt: new Date(doc.createdAt),\n      expiresAt: new Date(doc.expiresAt),\n    };\n  }\n\n  async close(): Promise<void> {\n    // Don't close the connection - it's passed in and may be shared\n  }\n}\n\nexport default MongoIdempotencyStore;\n"],"mappings":"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"}

package/dist/idempotency/redis.d.mts

@@ -0,0 +1,2 @@
+import { n as RedisIdempotencyStore, r as RedisIdempotencyStoreOptions, t as RedisClient } from "../redis-D-JAeLtm.mjs";
+export { type RedisClient, RedisIdempotencyStore, type RedisIdempotencyStoreOptions };

package/dist/idempotency/redis.mjs

@@ -0,0 +1,104 @@
+//#region src/idempotency/stores/redis.ts
+var RedisIdempotencyStore = class {
+	name = "redis";
+	client;
+	prefix;
+	lockPrefix;
+	ttlMs;
+	constructor(options) {
+		this.client = options.client;
+		this.prefix = options.prefix ?? "idem:";
+		this.lockPrefix = options.lockPrefix ?? "idem:lock:";
+		this.ttlMs = options.ttlMs ?? 864e5;
+	}
+	resultKey(key) {
+		return `${this.prefix}${key}`;
+	}
+	lockKey(key) {
+		return `${this.lockPrefix}${key}`;
+	}
+	async get(key) {
+		const data = await this.client.get(this.resultKey(key));
+		if (!data) return void 0;
+		try {
+			const result = JSON.parse(data);
+			if (new Date(result.expiresAt) < /* @__PURE__ */ new Date()) {
+				await this.delete(key);
+				return;
+			}
+			return {
+				...result,
+				createdAt: new Date(result.createdAt),
+				expiresAt: new Date(result.expiresAt)
+			};
+		} catch {
+			return;
+		}
+	}
+	async set(key, result) {
+		const data = {
+			key,
+			...result
+		};
+		const ttlSeconds = Math.ceil((new Date(result.expiresAt).getTime() - Date.now()) / 1e3);
+		if (ttlSeconds > 0) await this.client.set(this.resultKey(key), JSON.stringify(data), { EX: ttlSeconds });
+	}
+	async tryLock(key, requestId, ttlMs) {
+		const ttlSeconds = Math.ceil(ttlMs / 1e3);
+		return await this.client.set(this.lockKey(key), requestId, {
+			EX: ttlSeconds,
+			NX: true
+		}) === "OK";
+	}
+	async unlock(key, requestId) {
+		if (await this.client.get(this.lockKey(key)) === requestId) await this.client.del(this.lockKey(key));
+	}
+	async isLocked(key) {
+		return await this.client.exists(this.lockKey(key)) > 0;
+	}
+	async delete(key) {
+		await this.client.del([this.resultKey(key), this.lockKey(key)]);
+	}
+	async deleteByPrefix(prefix) {
+		const resultKeys = await this.scanByPrefix(this.resultKey(prefix));
+		const lockKeys = await this.scanByPrefix(this.lockKey(prefix));
+		const allKeys = [...resultKeys, ...lockKeys];
+		if (allKeys.length === 0) return 0;
+		return this.client.del(allKeys);
+	}
+	async findByPrefix(prefix) {
+		const keys = await this.scanByPrefix(this.resultKey(prefix));
+		for (const key of keys) {
+			const data = await this.client.get(key);
+			if (!data) continue;
+			try {
+				const result = JSON.parse(data);
+				if (new Date(result.expiresAt) < /* @__PURE__ */ new Date()) continue;
+				return {
+					...result,
+					createdAt: new Date(result.createdAt),
+					expiresAt: new Date(result.expiresAt)
+				};
+			} catch {
+				continue;
+			}
+		}
+	}
+	/** Scan Redis keys matching a prefix pattern. Falls back to empty if SCAN unavailable. */
+	async scanByPrefix(prefix) {
+		if (!this.client.scan) return [];
+		const keys = [];
+		let cursor = "0";
+		do {
+			const [nextCursor, batch] = await this.client.scan(cursor, "MATCH", `${prefix}*`, "COUNT", 100);
+			cursor = nextCursor;
+			keys.push(...batch);
+		} while (String(cursor) !== "0");
+		return keys;
+	}
+	async close() {}
+};
+
+//#endregion
+export { RedisIdempotencyStore };
+//# sourceMappingURL=redis.mjs.map

package/dist/idempotency/redis.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.mjs","names":[],"sources":["../../src/idempotency/stores/redis.ts"],"sourcesContent":["/**\n * Redis Idempotency Store\n *\n * Durable idempotency store using Redis.\n * Suitable for multi-instance deployments.\n *\n * @example\n * import { createClient } from 'redis';\n * import { RedisIdempotencyStore } from '@classytic/arc/idempotency';\n *\n * const redis = createClient({ url: process.env.REDIS_URL });\n * await redis.connect();\n *\n * await fastify.register(idempotencyPlugin, {\n *   store: new RedisIdempotencyStore({ client: redis }),\n * });\n */\n\nimport type { IdempotencyStore, IdempotencyResult } from './interface.js';\n\nexport interface RedisClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, options?: { EX?: number; NX?: boolean }): Promise<string | null>;\n  del(key: string | string[]): Promise<number>;\n  exists(key: string | string[]): Promise<number>;\n  /** SCAN command — compatible with node-redis and ioredis varargs signatures. */\n  scan?(cursor: string | number, ...args: (string | number)[]): Promise<[string | number, string[]]>;\n  quit?(): Promise<string>;\n  disconnect?(): Promise<void>;\n}\n\nexport interface RedisIdempotencyStoreOptions {\n  /** Redis client instance */\n  client: RedisClient;\n  /** Key prefix (default: 'idem:') */\n  prefix?: string;\n  /** Lock key prefix (default: 'idem:lock:') */\n  lockPrefix?: string;\n  /** Default TTL in ms (default: 86400000 = 24 hours) */\n  ttlMs?: number;\n}\n\nexport class RedisIdempotencyStore implements IdempotencyStore {\n  readonly name = 'redis';\n  private client: RedisClient;\n  private prefix: string;\n  private lockPrefix: string;\n  private ttlMs: number;\n\n  constructor(options: RedisIdempotencyStoreOptions) {\n    this.client = options.client;\n    this.prefix = options.prefix ?? 'idem:';\n    this.lockPrefix = options.lockPrefix ?? 'idem:lock:';\n    this.ttlMs = options.ttlMs ?? 86400000;\n  }\n\n  private resultKey(key: string): string {\n    return `${this.prefix}${key}`;\n  }\n\n  private lockKey(key: string): string {\n    return `${this.lockPrefix}${key}`;\n  }\n\n  async get(key: string): Promise<IdempotencyResult | undefined> {\n    const data = await this.client.get(this.resultKey(key));\n    if (!data) return undefined;\n\n    try {\n      const result = JSON.parse(data) as IdempotencyResult;\n      // Check if expired (Redis TTL should handle this, but double-check)\n      if (new Date(result.expiresAt) < new Date()) {\n        await this.delete(key);\n        return undefined;\n      }\n      return {\n        ...result,\n        createdAt: new Date(result.createdAt),\n        expiresAt: new Date(result.expiresAt),\n      };\n    } catch {\n      return undefined;\n    }\n  }\n\n  async set(key: string, result: Omit<IdempotencyResult, 'key'>): Promise<void> {\n    const data: IdempotencyResult = { key, ...result };\n    const ttlSeconds = Math.ceil(\n      (new Date(result.expiresAt).getTime() - Date.now()) / 1000\n    );\n\n    if (ttlSeconds > 0) {\n      await this.client.set(this.resultKey(key), JSON.stringify(data), {\n        EX: ttlSeconds,\n      });\n    }\n  }\n\n  async tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean> {\n    const ttlSeconds = Math.ceil(ttlMs / 1000);\n    const result = await this.client.set(\n      this.lockKey(key),\n      requestId,\n      { EX: ttlSeconds, NX: true }\n    );\n    return result === 'OK';\n  }\n\n  async unlock(key: string, requestId: string): Promise<void> {\n    // Only unlock if we hold the lock (check requestId)\n    const currentHolder = await this.client.get(this.lockKey(key));\n    if (currentHolder === requestId) {\n      await this.client.del(this.lockKey(key));\n    }\n  }\n\n  async isLocked(key: string): Promise<boolean> {\n    const exists = await this.client.exists(this.lockKey(key));\n    return exists > 0;\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.client.del([this.resultKey(key), this.lockKey(key)]);\n  }\n\n  async deleteByPrefix(prefix: string): Promise<number> {\n    const resultKeys = await this.scanByPrefix(this.resultKey(prefix));\n    const lockKeys = await this.scanByPrefix(this.lockKey(prefix));\n    const allKeys = [...resultKeys, ...lockKeys];\n    if (allKeys.length === 0) return 0;\n    return this.client.del(allKeys);\n  }\n\n  async findByPrefix(prefix: string): Promise<IdempotencyResult | undefined> {\n    const keys = await this.scanByPrefix(this.resultKey(prefix));\n    for (const key of keys) {\n      const data = await this.client.get(key);\n      if (!data) continue;\n      try {\n        const result = JSON.parse(data) as IdempotencyResult;\n        if (new Date(result.expiresAt) < new Date()) continue;\n        return {\n          ...result,\n          createdAt: new Date(result.createdAt),\n          expiresAt: new Date(result.expiresAt),\n        };\n      } catch {\n        continue;\n      }\n    }\n    return undefined;\n  }\n\n  /** Scan Redis keys matching a prefix pattern. Falls back to empty if SCAN unavailable. */\n  private async scanByPrefix(prefix: string): Promise<string[]> {\n    if (!this.client.scan) return [];\n    const keys: string[] = [];\n    let cursor: string | number = '0';\n    do {\n      const [nextCursor, batch] = await this.client.scan(\n        cursor, 'MATCH', `${prefix}*`, 'COUNT', 100,\n      );\n      cursor = nextCursor;\n      keys.push(...batch);\n    } while (String(cursor) !== '0');\n    return keys;\n  }\n\n  async close(): Promise<void> {\n    // Don't close the client - it's passed in and may be shared\n    // The caller is responsible for closing it\n  }\n}\n\nexport default RedisIdempotencyStore;\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -0,0 +1,261 @@
+import "./elevation-B_2dRLVP.mjs";
+import { D as CrudRepository, E as defineResource, F as OperationFilter, I as PipelineConfig, L as PipelineContext, M as Guard, N as Interceptor, P as NextFunction, R as PipelineStep, S as RouteHandler, T as ResourceDefinition, _ as ControllerLike, a as RepositoryLike, b as IControllerResponse, c as BaseController, i as RelationMetadata, j as QueryOptions, k as PaginatedResult, l as BaseControllerOptions, n as DataAdapter, o as SchemaMetadata, r as FieldMetadata, s as ValidationResult, x as IRequestContext, y as IController, z as Transform } from "./interface-Ch8HU9uM.mjs";
+import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, t as FieldPermission } from "./fields-DyaDVX4J.mjs";
+import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-aYB4V7uN.mjs";
+import { AdditionalRoute, AnyRecord, ApiResponse, ArcInternalMetadata, AuthPluginOptions, ConfigError, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, EventDefinition, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, MiddlewareConfig, MiddlewareHandler, OwnershipCheck, PresetFunction, PresetResult, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestWithExtras, ResourceConfig, ResourceMetadata, RouteHandlerMethod, RouteSchemaOptions, ServiceContext, TypedController, TypedRepository, TypedResourceConfig, UserOrganization, ValidateOptions, ValidationResult as ValidationResult$1 } from "./types/index.mjs";
+import { c as MongooseAdapterOptions, l as createMongooseAdapter, n as PrismaAdapterOptions, o as createPrismaAdapter, s as MongooseAdapter, t as PrismaAdapter } from "./prisma-Dg9GoVdj.mjs";
+import "./adapters/index.mjs";
+import { C as MutationOperation, S as MUTATION_OPERATIONS, T as SYSTEM_FIELDS, _ as HookOperation, a as getControllerScope, b as MAX_REGEX_LENGTH, c as CrudOperation, d as DEFAULT_MAX_LIMIT, f as DEFAULT_SORT, g as HOOK_PHASES, h as HOOK_OPERATIONS, l as DEFAULT_ID_FIELD, m as DEFAULT_UPDATE_METHOD, p as DEFAULT_TENANT_FIELD, s as CRUD_OPERATIONS, u as DEFAULT_LIMIT, v as HookPhase, w as RESERVED_QUERY_PARAMS, x as MAX_SEARCH_LENGTH, y as MAX_FILTER_DEPTH } from "./fastifyAdapter-BkrGrlFi.mjs";
+import "./core/index.mjs";
+import { a as NotFoundError, d as ValidationError, i as ForbiddenError, t as ArcError, u as UnauthorizedError } from "./errors-ChKiFz62.mjs";
+import { a as presets_d_exports, c as readOnly, i as ownerWithAdminBypass, n as authenticated, o as publicRead, r as fullPublic, s as publicReadAdminWrite, t as adminOnly } from "./presets-DzSMwlKj.mjs";
+import { DynamicPermissionMatrix, DynamicPermissionMatrixConfig, allOf, allowPublic, anyOf, createDynamicPermissionMatrix, createOrgPermissions, denyAll, requireAuth, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireTeamMembership, when } from "./permissions/index.mjs";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/core/validateResourceConfig.d.ts
+interface ConfigError$1 {
+  field: string;
+  message: string;
+  suggestion?: string;
+}
+interface ValidationResult$2 {
+  valid: boolean;
+  errors: ConfigError$1[];
+  warnings: ConfigError$1[];
+}
+interface ValidateOptions$1 {
+  /** Skip controller method validation (for testing) */
+  skipControllerCheck?: boolean;
+  /** Allow unknown preset names */
+  allowUnknownPresets?: boolean;
+  /** Custom valid permission keys beyond CRUD */
+  additionalPermissionKeys?: string[];
+}
+/**
+ * Validate a resource configuration
+ */
+declare function validateResourceConfig(config: ResourceConfig, options?: ValidateOptions$1): ValidationResult$2;
+/**
+ * Format validation errors for display
+ */
+declare function formatValidationErrors(resourceName: string, result: ValidationResult$2): string;
+/**
+ * Validate and throw if invalid
+ */
+declare function assertValidConfig(config: ResourceConfig, options?: ValidateOptions$1): void;
+//#endregion
+//#region src/pipeline/guard.d.ts
+interface GuardOptions {
+  operations?: OperationFilter;
+  handler: (ctx: PipelineContext) => boolean | Promise<boolean>;
+}
+/**
+ * Create a named guard.
+ *
+ * @param name - Guard name (for debugging/introspection)
+ * @param handlerOrOptions - Handler function or options object
+ */
+declare function guard(name: string, handlerOrOptions: ((ctx: PipelineContext) => boolean | Promise<boolean>) | GuardOptions): Guard;
+//#endregion
+//#region src/pipeline/transform.d.ts
+interface TransformOptions {
+  operations?: OperationFilter;
+  handler: (ctx: PipelineContext) => PipelineContext | void | Promise<PipelineContext | void>;
+}
+/**
+ * Create a named transform.
+ *
+ * @param name - Transform name (for debugging/introspection)
+ * @param handlerOrOptions - Handler function or options object
+ */
+declare function transform(name: string, handlerOrOptions: ((ctx: PipelineContext) => PipelineContext | void | Promise<PipelineContext | void>) | TransformOptions): Transform;
+//#endregion
+//#region src/pipeline/intercept.d.ts
+interface InterceptOptions {
+  operations?: OperationFilter;
+  handler: (ctx: PipelineContext, next: NextFunction) => Promise<IControllerResponse<unknown>>;
+}
+/**
+ * Create a named interceptor.
+ *
+ * @param name - Interceptor name (for debugging/introspection)
+ * @param handlerOrOptions - Handler function or options object
+ */
+declare function intercept(name: string, handlerOrOptions: ((ctx: PipelineContext, next: NextFunction) => Promise<IControllerResponse<unknown>>) | InterceptOptions): Interceptor;
+//#endregion
+//#region src/pipeline/pipe.d.ts
+/**
+ * Compose pipeline steps into an ordered array.
+ * Accepts guards, transforms, and interceptors in any order.
+ */
+declare function pipe(...steps: PipelineStep[]): PipelineStep[];
+//#endregion
+//#region src/middleware/middleware.d.ts
+interface NamedMiddleware {
+  /** Unique name for debugging/introspection */
+  readonly name: string;
+  /** Operations this middleware applies to (default: all) */
+  readonly operations?: Array<'list' | 'get' | 'create' | 'update' | 'delete' | string>;
+  /** Priority — lower numbers run first (default: 10) */
+  readonly priority: number;
+  /** Conditional execution — return true to run, false to skip */
+  readonly when?: (request: RequestWithExtras) => boolean | Promise<boolean>;
+  /** The middleware handler */
+  readonly handler: MiddlewareHandler;
+}
+interface MiddlewareOptions {
+  operations?: NamedMiddleware['operations'];
+  priority?: number;
+  when?: NamedMiddleware['when'];
+  handler: MiddlewareHandler;
+}
+/**
+ * Create a named middleware with priority and conditions.
+ */
+declare function middleware(name: string, options: MiddlewareOptions): NamedMiddleware;
+/**
+ * Sort named middlewares by priority (ascending — lower runs first).
+ * Returns a MiddlewareConfig map keyed by operation, ready to pass to `defineResource()`.
+ */
+declare function sortMiddlewares(middlewares: NamedMiddleware[]): MiddlewareConfig;
+//#endregion
+//#region src/context/requestContext.d.ts
+/**
+ * Shape of the request-scoped context store.
+ * Populated by Arc's onRequest hook in arcCorePlugin.
+ */
+interface RequestStore {
+  /** Unique request identifier */
+  requestId?: string;
+  /** Authenticated user (if any) */
+  user?: {
+    id?: string;
+    _id?: string;
+    roles?: string[];
+    [key: string]: unknown;
+  } | null;
+  /** Active organization ID (multi-tenant) */
+  organizationId?: string;
+  /** Active team ID (team-scoped resources) */
+  teamId?: string;
+  /** Current resource name (set by arcDecorator in CRUD routes) */
+  resourceName?: string;
+  /** Request start time (for timing) */
+  startTime: number;
+  /** Additional context — extensible by app */
+  [key: string]: unknown;
+}
+/**
+ * Request context API.
+ *
+ * - `get()` — returns current store or undefined if outside request scope
+ * - `run(store, fn)` — run a function with a specific store (used by Arc internals)
+ * - `getStore()` — alias for get() (matches Node.js API naming)
+ */
+declare const requestContext: {
+  /**
+   * Get the current request context.
+   * Returns undefined if called outside a request lifecycle.
+   */
+  get(): RequestStore | undefined;
+  /**
+   * Alias for get() — matches Node.js AsyncLocalStorage API naming.
+   */
+  getStore(): RequestStore | undefined;
+  /**
+   * Run a function within a specific request context.
+   * Used internally by Arc's onRequest hook.
+   */
+  run<T>(store: RequestStore, fn: () => T): T;
+  /**
+   * The underlying AsyncLocalStorage instance.
+   * Exposed for advanced use cases (testing, custom integrations).
+   */
+  storage: AsyncLocalStorage<RequestStore>;
+};
+//#endregion
+//#region src/logger/index.d.ts
+/**
+ * Arc Logger — Centralized debug & warning system
+ *
+ * Lightweight, zero-dependency logger for Arc framework internals.
+ * Inspired by the `debug` npm package — disabled by default, opt-in via
+ * environment variable or `createApp({ debug })` option.
+ *
+ * @example
+ * ```typescript
+ * // Enable via env var
+ * ARC_DEBUG=1 node server.js        // all modules
+ * ARC_DEBUG=scope,elevation node server.js // specific modules
+ *
+ * // Enable via createApp
+ * const app = await createApp({ debug: true });
+ * const app = await createApp({ debug: 'scope,elevation' });
+ *
+ * // Suppress warnings (not recommended)
+ * ARC_SUPPRESS_WARNINGS=1 node server.js
+ *
+ * // Framework internals use:
+ * import { arcLog } from '../logger/index.js';
+ * const log = arcLog('elevation');
+ * log.debug('Elevation applied', { userId });
+ * log.warn('Something unexpected');
+ * ```
+ */
+interface ArcLoggerOptions {
+  /**
+   * Enable debug output.
+   * - `true` or `'*'` — all modules
+   * - `string` — comma-separated module names (e.g., `'scope,elevation'`)
+   * - `false` — disabled (default)
+   */
+  debug?: boolean | string;
+  /**
+   * Custom log writer. Defaults to `console`.
+   * Useful for routing Arc logs into Fastify's pino logger or test fixtures.
+   */
+  writer?: ArcLogWriter;
+}
+interface ArcLogWriter {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+interface ArcLogger {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+/**
+ * Configure the Arc logger globally.
+ *
+ * Called automatically by `createApp({ debug })`, but can also be
+ * called manually for standalone usage outside of `createApp`.
+ */
+declare function configureArcLogger(options: ArcLoggerOptions): void;
+/**
+ * Create a module-scoped logger.
+ *
+ * Debug and info messages are gated by the `ARC_DEBUG` env var or
+ * `createApp({ debug })` option. Warnings always show (unless
+ * `ARC_SUPPRESS_WARNINGS=1`). Errors always show.
+ *
+ * @param module - Module name (e.g., 'scope', 'elevation', 'sse', 'preset')
+ * @returns Logger instance for that module
+ *
+ * @example
+ * ```typescript
+ * const log = arcLog('elevation');
+ * log.debug('Checking elevation header');
+ * log.warn('No authenticate decorator found');
+ * ```
+ */
+declare function arcLog(module: string): ArcLogger;
+//#endregion
+//#region src/index.d.ts
+declare const version: string;
+//#endregion
+export { type ValidationResult as AdapterValidationResult, type AdditionalRoute, type AnyRecord, type ApiResponse, ArcError, type ArcInternalMetadata, type ArcLogWriter, type ArcLogger, type ArcLoggerOptions, type AuthPluginOptions, BaseController, type BaseControllerOptions, CRUD_OPERATIONS, type ConfigError, type ControllerLike, type CrudController, CrudOperation, type CrudRepository, type CrudRouteKey, type CrudRouterOptions, type CrudSchemas, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, type DataAdapter, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type EventDefinition, type FastifyRequestExtras, type FastifyWithAuth, type FastifyWithDecorators, type FieldMetadata, type FieldPermission, type FieldPermissionMap, type FieldRule, ForbiddenError, type GracefulShutdownOptions, type Guard, HOOK_OPERATIONS, HOOK_PHASES, type HealthCheck, type HealthOptions, HookOperation, HookPhase, type IController, type IControllerResponse, type IRequestContext, type InferAdapterDoc, type InferDocType, type InferResourceDoc, type Interceptor, type IntrospectionData, type IntrospectionPluginOptions, type JWTPayload, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, type MiddlewareConfig, MongooseAdapter, type MongooseAdapterOptions, MutationOperation, type NamedMiddleware, NotFoundError, type OwnershipCheck, type PaginatedResult, type PermissionCheck, type PermissionContext, type PermissionResult, type PipelineConfig, type PipelineContext, type PipelineStep, type PresetFunction, type PresetResult, PrismaAdapter, type PrismaAdapterOptions, type QueryOptions, RESERVED_QUERY_PARAMS, type RateLimitConfig, type RegistryEntry, type RegistryStats, type RelationMetadata, type RepositoryLike, type RequestContext, type RequestIdOptions, type RequestStore, type RequestWithExtras, type ResourceConfig, ResourceDefinition, type ResourceMetadata, type RouteHandler, type RouteHandlerMethod, type RouteSchemaOptions, SYSTEM_FIELDS, type SchemaMetadata, type ServiceContext, type Transform, type TypedController, type TypedRepository, type TypedResourceConfig, UnauthorizedError, type UserBase, type UserOrganization, type ValidateOptions, ValidationError, type ValidationResult$1 as ValidationResult, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, arcLog, assertValidConfig, authenticated, configureArcLogger, createDynamicPermissionMatrix, createMongooseAdapter, createOrgPermissions, createPrismaAdapter, defineResource, denyAll, fields, formatValidationErrors, fullPublic, getControllerScope, guard, intercept, middleware, ownerWithAdminBypass, presets_d_exports as permissions, pipe, publicRead, publicReadAdminWrite, readOnly, requestContext, requireAuth, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireTeamMembership, sortMiddlewares, transform, validateResourceConfig, version, when };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/core/validateResourceConfig.ts","../src/pipeline/guard.ts","../src/pipeline/transform.ts","../src/pipeline/intercept.ts","../src/pipeline/pipe.ts","../src/middleware/middleware.ts","../src/context/requestContext.ts","../src/logger/index.ts","../src/index.ts"],"mappings":"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"}