@classytic/arc 2.31.0 → 2.33.0

package/dist/idempotency/index.mjs

@@ -1,12 +1,43 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { n as requireSingleHeaderValue } from "../headers-3zvE0rM3.mjs";
-import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-D1MP_gRG.mjs";
-import { t as createIdempotencyResult } from "../interface-DYzM0q-u.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { n as requireSingleHeaderValue } from "../headers-CveNO9gR.mjs";
+import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-B88p99Z2.mjs";
+import { t as createIdempotencyResult } from "../interface-DznJrm9R.mjs";
 import { and, eq, exists, gt, lt, or, startsWith } from "@classytic/repo-core/filter";
 import { createHash } from "node:crypto";
 import fp from "fastify-plugin";
 import { update } from "@classytic/repo-core/update";
 //#region src/idempotency/repository-idempotency-adapter.ts
+/**
+* The backing repository returned a document whose key does not match the
+* key that was asked for — which means the repository is NOT applying the
+* key filter. Concretely observed (2026-08-14, be-prod): a Mongoose schema
+* with no declared paths (`new Schema({}, { _id: false })`) under a global
+* `mongoose.set('strictQuery', true)` strips EVERY filter key as an
+* "unknown path", so `getOne({ _id: key })` becomes `getOne({})` — one
+* shared document then absorbs every idempotency key, and every request
+* replays the most recent cached response ACROSS KEYS AND ACROSS USERS
+* (a cancel response for order A was served as "success" for order B,
+* which was never actually canceled).
+*
+* That failure mode is silent by construction — every read "succeeds" with
+* a plausible document — so the adapter verifies the identity of every
+* document it gets back and THROWS this instead of trusting it. Returning
+* `undefined` (treat as miss) would be worse, not safer: the very next
+* `tryLock`/`set` on the same broken repository would corrupt the shared
+* document again.
+*
+* Fix on the host side: declare the key path on the schema (e.g.
+* `_id: String`) and/or set `strictQuery: false` in the SCHEMA options so
+* filters on it are never stripped — see `idempotencyPlugin`'s
+* `repository` option docs.
+*/
+var IdempotencyStoreMisconfiguredError = class extends Error {
+	code = "IDEMPOTENCY_STORE_MISCONFIGURED";
+	constructor(operation, expectedKey, actualKey) {
+		super(`idempotency repository store: ${operation} for key '${expectedKey}' returned a document keyed '${String(actualKey)}' — the repository is not applying the key filter (commonly: a pathless Mongoose schema under strictQuery:true strips the filter to {}). Declare the key path on the schema (e.g. _id: String) and set strictQuery: false in the schema options. Refusing to serve cross-key results.`);
+		this.name = "IdempotencyStoreMisconfiguredError";
+	}
+};
 function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 	const missing = [];
 	if (typeof repository.getOne !== "function") missing.push("getOne");
@@ -17,11 +48,23 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 	const idField = repository.idField ?? "_id";
 	const isDuplicateKeyError = createIsDuplicateKeyError(repository);
 	const safeGetOne = createSafeGetOne(repository);
+	/**
+	* Every document read back MUST carry the key it was fetched by. A
+	* mismatch means the repository dropped the filter (see
+	* {@link IdempotencyStoreMisconfiguredError}) — fail loud, never serve
+	* or mutate a cross-key document.
+	*/
+	function assertKeyIdentity(operation, doc, expectedKey) {
+		const actual = doc[idField];
+		if (String(actual) !== expectedKey) throw new IdempotencyStoreMisconfiguredError(operation, expectedKey, actual);
+	}
 	return {
 		name: "repository",
 		async get(key) {
 			const doc = await safeGetOne(eq(idField, key));
-			if (!doc?.result) return void 0;
+			if (!doc) return void 0;
+			assertKeyIdentity("get", doc, key);
+			if (!doc.result) return void 0;
 			if (new Date(doc.expiresAt) < /* @__PURE__ */ new Date()) return void 0;
 			return {
 				key,
@@ -33,7 +76,7 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 			};
 		},
 		async set(key, result) {
-			await r.findOneAndUpdate(eq(idField, key), update({
+			const doc = await r.findOneAndUpdate(eq(idField, key), update({
 				set: {
 					result: {
 						statusCode: result.statusCode,
@@ -43,11 +86,13 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 					createdAt: result.createdAt,
 					expiresAt: result.expiresAt
 				},
+				setOnInsert: { [idField]: key },
 				unset: ["lock"]
 			}), {
 				upsert: true,
 				returnDocument: "after"
 			});
+			if (doc) assertKeyIdentity("set", doc, key);
 		},
 		async tryLock(key, requestId, ttlMs) {
 			const now = /* @__PURE__ */ new Date();
@@ -60,6 +105,7 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 						expiresAt: lockExpiresAt
 					} },
 					setOnInsert: {
+						[idField]: key,
 						createdAt: now,
 						expiresAt: docExpiresAt
 					}
@@ -67,6 +113,7 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 					upsert: true,
 					returnDocument: "after"
 				});
+				if (doc) assertKeyIdentity("tryLock", doc, key);
 				return doc !== null && doc !== void 0;
 			} catch (err) {
 				if (isDuplicateKeyError(err)) return false;
@@ -90,6 +137,7 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 		async findByPrefix(prefix) {
 			const doc = await safeGetOne(and(startsWith(idField, prefix, "sensitive"), exists("result", true), gt("expiresAt", /* @__PURE__ */ new Date())));
 			if (!doc?.result) return void 0;
+			if (!String(doc[idField] ?? "").startsWith(prefix)) throw new IdempotencyStoreMisconfiguredError("findByPrefix", prefix, doc[idField]);
 			return {
 				key: String(doc[idField] ?? prefix),
 				statusCode: doc.result.statusCode,
@@ -138,8 +186,10 @@ var MemoryIdempotencyStore = class {
 	}
 	async tryLock(key, requestId, ttlMs) {
 		const existing = this.locks.get(key);
-		if (existing) if (/* @__PURE__ */ new Date() > existing.expiresAt) this.locks.delete(key);
-		else return false;
+		if (existing) {
+			if (/* @__PURE__ */ new Date() > existing.expiresAt) this.locks.delete(key);
+			else return false;
+		}
 		this.locks.set(key, {
 			key,
 			requestId,
@@ -285,8 +335,42 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		"POST",
 		"PUT",
 		"PATCH"
-	], include, exclude, repository, store: explicitStore, retryAfterSeconds = 1, namespace } = opts;
+	], include, exclude, repository, store: explicitStore, retryAfterSeconds = 1, namespace, selfCheck = true } = opts;
 	const store = repository ? repositoryAsIdempotencyStore(repository, ttlMs) : explicitStore ?? new MemoryIdempotencyStore({ ttlMs });
+	/**
+	* Who owns the store's lifecycle — arc closes ONLY what arc built.
+	*
+	* A host-supplied `store` may outlive this app: two arc apps in one process
+	* (a documented topology) can share one, and `MemoryIdempotencyStore.close()`
+	* CLEARS its maps. Closing on the first app's shutdown therefore wiped the
+	* second app's live idempotency records — replayable requests silently
+	* became re-executable. A store handed in from outside is the host's to
+	* close. The same rule now applies to the events transport and the
+	* query-cache store, which had the identical defect.
+	*
+	* The `repository` path builds its own adapter here, so arc owns that
+	* wrapper — but the adapter has no `close`, and the underlying repository
+	* (host-owned) is never touched.
+	*/
+	const ownsStore = !explicitStore;
+	if (enabled && selfCheck) {
+		const probeSuffix = createHash("sha256").update(`${process.pid}:${Date.now()}:${Math.random()}`).digest("hex").slice(0, 12);
+		const probeKeyA = `__arc_idempotency_selfcheck__:${probeSuffix}:a`;
+		const probeKeyB = `__arc_idempotency_selfcheck__:${probeSuffix}:b`;
+		/** Correctness verdicts rethrow; everything else degrades to a warning. */
+		class SelfCheckViolation extends Error {}
+		try {
+			await store.set(probeKeyA, createIdempotencyResult(299, { probe: true }, {}, 6e4));
+			const own = await store.get(probeKeyA);
+			if (!own || own.statusCode !== 299) fastify.log?.warn?.({ probe: "own-key" }, "idempotencyPlugin self-check: probe entry did not read back under its own key. This is usually the store being unreachable at boot (connection not ready), not a misconfiguration — continuing, with the adapter's per-read key-identity checks as the runtime backstop. If keyed requests later fail with IDEMPOTENCY_STORE_MISCONFIGURED, the store's key filter is being stripped (see IdempotencyStoreMisconfiguredError).");
+			else if (await store.get(probeKeyB)) throw new SelfCheckViolation("idempotencyPlugin self-check: a probe read under key B returned key A's entry — the store is ignoring the key filter, which in production replays cached responses across keys and users (observed cause: a pathless Mongoose schema under strictQuery:true strips every filter to {}). Declare the key path on the schema (e.g. _id: String) and set strictQuery: false in the schema options.");
+		} catch (err) {
+			if (err instanceof SelfCheckViolation || err?.code === "IDEMPOTENCY_STORE_MISCONFIGURED") throw err;
+			fastify.log?.warn?.({ err }, "idempotencyPlugin self-check could not complete (store unreachable at boot?) — continuing. The adapter's per-read key-identity checks remain the runtime backstop.");
+		} finally {
+			await store.deleteByPrefix(`__arc_idempotency_selfcheck__:${probeSuffix}:`).catch(() => {});
+		}
+	}
 	if (!enabled) {
 		fastify.decorate("idempotency", {
 			invalidate: async () => {},
@@ -429,7 +513,7 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		await store.unlock(fullKey, request.id);
 	});
 	fastify.addHook("onClose", async () => {
-		await store.close?.();
+		if (ownsStore) await store.close?.();
 	});
 	fastify.log?.debug?.({
 		headerName,
@@ -442,4 +526,4 @@ var idempotencyPlugin_default = fp(idempotencyPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { MemoryIdempotencyStore, createIdempotencyResult, idempotencyPlugin_default as idempotencyPlugin, idempotencyPlugin as idempotencyPluginFn, repositoryAsIdempotencyStore };
+export { IdempotencyStoreMisconfiguredError, MemoryIdempotencyStore, createIdempotencyResult, idempotencyPlugin_default as idempotencyPlugin, idempotencyPlugin as idempotencyPluginFn, repositoryAsIdempotencyStore };

package/dist/idempotency/redis.mjs

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
 //#region src/idempotency/stores/redis.ts
 var RedisIdempotencyStore = class {
 	name = "redis";

package/dist/{index-CEJNZFtX.d.mts → index-B-DvUzsr.d.mts}

@@ -1,7 +1,7 @@
 
-import { r as CacheStore, t as CacheLogger } from "./interface-BOk3YnTz.mjs";
 import { i as RequestScope, n as Mandate } from "./types-ChuShpCP.mjs";
-import { i as PermissionContext, r as PermissionCheck, t as AuthorizationDecision } from "./types-B7XeLEgK.mjs";
+import { l as PermissionCheck, s as AuthorizationDecision, u as PermissionContext } from "./base-Csjc2oF-.mjs";
+import { r as CacheStore, t as CacheLogger } from "./interface-BOk3YnTz.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 //#region src/permissions/agent.d.ts
 /**
@@ -990,4 +990,83 @@ declare function fullPublic<TDoc = Record<string, unknown>>(overrides?: Permissi
  */
 declare function readOnly<TDoc = Record<string, unknown>>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
 //#endregion
-export { evaluatePermissionDecision as $, explainAccess as A, anyOf as B, requireGrant as C, collectPublicSurface as D, PermissionRequirement as E, createDynamicPermissionMatrix as F, requireOwnership as G, denyAll as H, createOrgPermissions as I, roles as J, requirePlatformRole as K, allOf as L, DynamicPermissionMatrix as M, DynamicPermissionMatrixConfig as N, describePermission as O, PermissionEventBus as P, applyAuthorizationDecision as Q, allow as R, modeSatisfies as S, AccessExplanation as T, not as U, deny as V, requireAuth as W, scopeOf as X, when as Y, PermissionCheckReturn as Z, createRoleHierarchy as _, permissionMatrix as a, requireMandate as at, GrantResolution as b, publicReadAdminWrite as c, requireOrgMembership as d, normalizeToDecision as et, requireOrgRole as f, RoleHierarchy as g, requireTeamMembership as h, ownerWithAdminBypass as i, requireDPoP as it, ConnectEventsOptions as j, describePermissionMap as k, readOnly as l, requireServiceScope as m, authenticated as n, RequireMandateOptions as nt, presets_d_exports as o, requireScopeContext as p, requireRoles as q, fullPublic as r, requireAgentScope as rt, publicRead as s, adminOnly as t, RequireAgentScopeOptions as tt, requireOrgInScope as u, GRANT_MODES as v, conjoinPolicyFilters as w, RequireGrantOptions as x, GrantMode as y, allowPublic as z };
+//#region src/permissions/matrix.d.ts
+type PermissionEntryType = "public" | "authenticated" | "roles" | "scoped";
+interface PermissionEntry {
+  type: PermissionEntryType;
+  roles: string[];
+  /**
+   * Present only for `scoped` — the caller-scope dimensions the gate requires
+   * (e.g. `{ branchRole: "head_office" }`), for the client to resolve against
+   * the viewer's active context.
+   */
+  scope?: Record<string, unknown>;
+}
+/**
+ * The slice of arc's `ResourceRegistry` this reads.
+ *
+ * Structural on purpose: coupling to the full registry type would drag the
+ * resource layer into the permissions layer, and this only ever reads names
+ * and gates.
+ */
+interface PermissionMatrixRegistry {
+  getAll(): ReadonlyArray<{
+    name: string;
+    permissions?: Record<string, unknown>;
+    actions?: ReadonlyArray<{
+      name: string;
+      permissions?: unknown;
+    }>;
+    aggregations?: ReadonlyArray<{
+      name: string;
+      permissions?: unknown;
+    }>;
+    /**
+     * Custom routes. Only those declaring `capability` are published — see the
+     * loop in `introspectRegistry` for why a route needs an explicit name.
+     */
+    customRoutes?: ReadonlyArray<{
+      method: string;
+      path: string;
+      capability?: string;
+      permissions?: unknown;
+    }>;
+  }>;
+}
+interface PermissionMatrixOptions {
+  /** The live registry. Omit and the matrix carries only curated modules. */
+  registry?: PermissionMatrixRegistry;
+  /**
+   * Curated, human-named groupings the client already organises around
+   * (`products`, `finance`, …). Overlaid FIRST — the live registry wins on an
+   * exact name collision, because the enforced gate beats an approximation.
+   */
+  curatedModules?: Record<string, unknown>;
+  /**
+   * Second curated layer, applied only where `curatedModules` has no entry —
+   * typically per-resource policies behind the domain groupings.
+   */
+  fallbackModules?: Record<string, unknown>;
+  /** Platform-level role names. */
+  platformRoles?: readonly string[];
+  /** Organization/branch-level role names. */
+  orgRoles?: readonly string[];
+}
+interface PermissionMatrix {
+  /** Every role name, both namespaces — so a role picker has one source. */
+  roles: string[];
+  roleGroups: {
+    platform: string[];
+    branch: string[];
+  };
+  modules: Record<string, Record<string, PermissionEntry>>;
+}
+/** Re-shape arc's typed requirement into the wire entry. */
+declare function introspectCheck(check: PermissionCheck): PermissionEntry;
+/** Introspect a permission module, flattening nested groups to `a.b`. */
+declare function introspectModule(mod: Record<string, unknown>): Record<string, PermissionEntry>;
+/** Every live resource's ACTUAL gates, keyed by arc resource name. */
+declare function introspectRegistry(registry: PermissionMatrixRegistry): Record<string, Record<string, PermissionEntry>>;
+declare function buildPermissionMatrix(options?: PermissionMatrixOptions): PermissionMatrix;
+//#endregion
+export { requireAuth as $, RequireGrantOptions as A, ConnectEventsOptions as B, requireServiceScope as C, GRANT_MODES as D, createRoleHierarchy as E, PermissionRequirement as F, createOrgPermissions as G, DynamicPermissionMatrixConfig as H, collectPublicSurface as I, allowPublic as J, allOf as K, describePermission as L, requireGrant as M, conjoinPolicyFilters as N, GrantMode as O, AccessExplanation as P, not as Q, describePermissionMap as R, requireScopeContext as S, RoleHierarchy as T, PermissionEventBus as U, DynamicPermissionMatrix as V, createDynamicPermissionMatrix as W, deny as X, anyOf as Y, denyAll as Z, publicReadAdminWrite as _, PermissionMatrixRegistry as a, scopeOf as at, requireOrgMembership as b, introspectModule as c, evaluatePermissionDecision as ct, authenticated as d, RequireMandateOptions as dt, requireOwnership as et, fullPublic as f, requireAgentScope as ft, publicRead as g, presets_d_exports as h, PermissionMatrixOptions as i, when as it, modeSatisfies as j, GrantResolution as k, introspectRegistry as l, normalizeToDecision as lt, permissionMatrix as m, requireMandate as mt, PermissionEntryType as n, requireRoles as nt, buildPermissionMatrix as o, PermissionCheckReturn as ot, ownerWithAdminBypass as p, requireDPoP as pt, allow as q, PermissionMatrix as r, roles as rt, introspectCheck as s, applyAuthorizationDecision as st, PermissionEntry as t, requirePlatformRole as tt, adminOnly as u, RequireAgentScopeOptions as ut, readOnly as v, requireTeamMembership as w, requireOrgRole as x, requireOrgInScope as y, explainAccess as z };