@classytic/arc 2.22.0 → 2.23.0

package/dist/realtime-I8OrfnMR.mjs

@@ -0,0 +1,375 @@
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
+import { arcLog } from "./logger/index.mjs";
+import { c as getOrgId } from "./types-bHblZ9YN.mjs";
+import { t as simpleEqualityMatcher } from "./simpleEqualityMatcher-Cg05HPsn.mjs";
+import { i as applyFieldReadPermissions, n as evaluateAndApplyPermission } from "./applyPermissionResult-Tw4iXtlf.mjs";
+import { t as getUserRoles } from "./types-XTApa8b6.mjs";
+import { a as promoteStreamTokenToHeader } from "./streaming-BQcW6_Kq.mjs";
+import { t as openSseStream } from "./sseStream-BQ7Qaynp.mjs";
+import fp from "fastify-plugin";
+//#region src/plugins/realtime.ts
+var realtime_exports = /* @__PURE__ */ __exportAll({
+	buildChangeFrame: () => buildChangeFrame,
+	connectionDeadlineMs: () => connectionDeadlineMs,
+	default: () => realtime_default,
+	realtimePlugin: () => realtimePlugin,
+	resolveDelivery: () => resolveDelivery,
+	resolveRowMatcher: () => resolveRowMatcher
+});
+const log = arcLog("realtime");
+const CHANGE_OPERATIONS = [
+	"created",
+	"updated",
+	"deleted"
+];
+/**
+* SSE `retry:` reconnection hint (ms). Deliberate: the feed has no replay,
+* so a reconnecting client refetches the list anyway — a short retry keeps
+* the gap small without hammering the server.
+*/
+const DEFAULT_RETRY_MS = 3e3;
+/**
+* Cap on resources per multiplexed connection. Generous for real
+* dashboards (Supabase caps channels-per-client similarly); prevents a
+* single socket from fanning out unbounded subscription work.
+*/
+const MAX_MULTIPLEX_RESOURCES = 20;
+/** Node's `setTimeout` ceiling (~24.8 days); larger delays fire immediately. */
+const MAX_TIMER_MS = 2147483647;
+/**
+* Milliseconds from `now` until the feed should force-close to bound
+* permission staleness — `min(auth-token exp, maxConnectionMs)`. Returns
+* `undefined` when neither bound applies (no `exp` claim, no cap → the feed
+* lives until client disconnect), `0` when already expired, else the
+* (setTimeout-ceiling-clamped) delay. Pure; exported for tests.
+*/
+function connectionDeadlineMs(user, maxConnectionMs, now = Date.now()) {
+	let deadline;
+	const exp = user?.exp;
+	if (typeof exp === "number" && Number.isFinite(exp)) deadline = exp * 1e3 - now;
+	if (maxConnectionMs !== void 0 && maxConnectionMs > 0) deadline = deadline === void 0 ? maxConnectionMs : Math.min(deadline, maxConnectionMs);
+	if (deadline === void 0) return void 0;
+	if (deadline <= 0) return 0;
+	return Math.min(deadline, MAX_TIMER_MS);
+}
+/**
+* Are these filters flat equality (every value a scalar, no `$` operators)?
+* That is the shape `simpleEqualityMatcher` is safe for — anything richer
+* needs the adapter's own matcher.
+*/
+function isFlatEquality(filters) {
+	for (const [key, value] of Object.entries(filters)) {
+		if (key.startsWith("$")) return false;
+		if (value !== null && typeof value === "object" && !(value instanceof Date)) return false;
+	}
+	return true;
+}
+/**
+* Decide how (or whether) this subscription's row filters can be enforced
+* in process: adapter matcher when supplied, `simpleEqualityMatcher` for
+* flat-equality shapes, UNENFORCEABLE (fail-closed → 501) for
+* operator-shaped filters with no adapter matcher. No filters → nothing
+* to enforce.
+*/
+function resolveRowMatcher(filters, adapter) {
+	const hasFilters = !!filters && Object.keys(filters).length > 0;
+	if (adapter?.matchesFilter) {
+		const matcher = adapter.matchesFilter.bind(adapter);
+		if (hasFilters && filters) try {
+			matcher({}, filters);
+		} catch {
+			return { enforceable: false };
+		}
+		return {
+			enforceable: true,
+			matcher
+		};
+	}
+	if (!hasFilters) return { enforceable: true };
+	if (isFlatEquality(filters)) return {
+		enforceable: true,
+		matcher: simpleEqualityMatcher
+	};
+	return { enforceable: false };
+}
+/**
+* Decide this event's fate for one subscriber. Pure — the whole
+* authorization + membership-transition story lives here:
+*
+*   1. tenant guard: org-carrying events only reach matching-org subscribers
+*      (a cross-org record was never visible → drop, never a leave).
+*   2. row filters (connect-time snapshot):
+*      - matches (or no filters)                     → deliver.
+*      - no match + operation is `updated`           → LEAVE (membership
+*        transition out; the record may have been in the subscriber's view).
+*      - no match + operation is `created`/`deleted` → drop (never entered
+*        the view — a created record that doesn't match was never shown; a
+*        deleted record that doesn't match was already filtered out).
+*
+* The ENTER transition (a record updated so it now DOES match) needs no
+* special signal: the matching `updated` frame carries the full record, so
+* the client adds it if absent.
+*/
+function resolveDelivery(event, policy, operation) {
+	if (policy.tenantScoped) {
+		const eventOrgId = event.meta?.organizationId;
+		if (eventOrgId && eventOrgId !== policy.subscriberOrgId) return { kind: "drop" };
+	}
+	const doc = event.payload?.data;
+	if (!(!!policy.filters && Object.keys(policy.filters).length > 0)) return {
+		kind: "deliver",
+		doc
+	};
+	if (!!doc && typeof doc === "object" && !!policy.matcher?.(doc, policy.filters)) return {
+		kind: "deliver",
+		doc
+	};
+	return operation === "updated" ? { kind: "leave" } : { kind: "drop" };
+}
+/**
+* Build the wire frame for one delivered change. Envelope note: this is
+* deliberately DOCUMENT-CHANGE-shaped (`data` = the masked document),
+* unlike the sse plugin's raw event mirror (`payload` = whatever was
+* published) — the two streams serve different consumers and the
+* divergence is intentional, not drift.
+*/
+function buildChangeFrame(event, resourceName, data) {
+	return JSON.stringify({
+		type: event.type,
+		resource: resourceName,
+		id: event.meta?.resourceId,
+		data,
+		meta: {
+			timestamp: event.meta?.timestamp,
+			correlationId: event.meta?.correlationId
+		}
+	});
+}
+const realtimePlugin = async (fastify, opts = {}) => {
+	const { path = "/realtime/:resource", heartbeat = 3e4, resources: allowlist, operations = CHANGE_OPERATIONS, tokenQueryParam = "token", maxConnectionMs } = opts;
+	if (!fastify.hasDecorator("events")) {
+		log.warn("Events plugin (arc-events) not registered. Realtime plugin will not function. Register eventPlugin before realtimePlugin.");
+		return;
+	}
+	if (!path.includes(":resource")) throw new Error(`[arc-realtime] path must contain ':resource' (got '${path}')`);
+	const activeConnections = /* @__PURE__ */ new Set();
+	const isProtected = (entry) => {
+		const listCheck = entry.permissions?.list;
+		return typeof listCheck === "function" && listCheck._isPublic !== true;
+	};
+	/**
+	* Run auth once for a set of requested resources: `authenticate` when ANY
+	* is protected (401 on missing/invalid token), `optionalAuthenticate`
+	* otherwise so tokens still parse. Returns false when a reply was sent.
+	*/
+	const runAuth = async (request, reply, entries) => {
+		const needsAuth = entries.some(isProtected);
+		if (tokenQueryParam) promoteStreamTokenToHeader(request, tokenQueryParam);
+		const authenticate = needsAuth ? fastify.authenticate : fastify.optionalAuthenticate;
+		if (needsAuth && typeof authenticate !== "function") {
+			await reply.code(401).send({
+				code: "arc.unauthorized",
+				message: "Authentication required",
+				status: 401
+			});
+			return false;
+		}
+		if (typeof authenticate === "function") {
+			await authenticate(request, reply);
+			if (reply.sent) return false;
+		}
+		return true;
+	};
+	/**
+	* Authorize ONE resource for this connection: run its list permission,
+	* snapshot its row filters IN ISOLATION (evaluateAndApplyPermission
+	* accumulates onto request._policyFilters — on a multiplexed connection
+	* resource B must never inherit resource A's filters, so the field is
+	* saved/reset/restored around each evaluation), and resolve the row
+	* matcher fail-closed. Sends the denial/501 reply itself; returns null
+	* when the caller should stop.
+	*/
+	const authorizeResource = async (resourceName, entry, request, reply) => {
+		const holder = request;
+		const saved = holder._policyFilters;
+		holder._policyFilters = void 0;
+		try {
+			const listCheck = entry.permissions?.list;
+			if (typeof listCheck === "function") {
+				if (!await evaluateAndApplyPermission(listCheck, {
+					user: request.user ?? null,
+					request,
+					resource: resourceName,
+					action: "list"
+				}, request, reply)) return null;
+			}
+			const filters = holder._policyFilters;
+			const resolution = resolveRowMatcher(filters, fastify.arc?.registry?.getAdapter(resourceName));
+			if (!resolution.enforceable) {
+				await reply.code(501).send({
+					code: "arc.realtime.unfilterable",
+					message: `The '${resourceName}' list permission returned operator-shaped row filters, which this feed cannot enforce in-process. Supply \`matchesFilter\` on the resource's DataAdapter to enable realtime for filter-scoped subscribers.`,
+					status: 501
+				});
+				return null;
+			}
+			const scope = request.scope;
+			return {
+				name: resourceName,
+				policy: {
+					tenantScoped: entry.tenantField !== false,
+					subscriberOrgId: scope ? getOrgId(scope) : void 0,
+					filters,
+					matcher: resolution.matcher
+				},
+				fields: entry.fields
+			};
+		} finally {
+			holder._policyFilters = saved;
+		}
+	};
+	/** Open the stream and wire every authorized subscription onto it. */
+	const sharedFrames = /* @__PURE__ */ new WeakMap();
+	const streamSubscriptions = async (request, reply, subscriptions) => {
+		const userRoles = getUserRoles(request.user ?? {});
+		const stream = openSseStream(request, reply, {
+			heartbeatMs: heartbeat,
+			retryMs: DEFAULT_RETRY_MS
+		});
+		stream.onCleanup(() => activeConnections.delete(stream.close));
+		activeConnections.add(stream.close);
+		const closeAt = connectionDeadlineMs(request.user, maxConnectionMs);
+		if (closeAt !== void 0) {
+			if (closeAt <= 0) {
+				stream.close();
+				return;
+			}
+			const timer = setTimeout(stream.close, closeAt);
+			timer.unref?.();
+			stream.onCleanup(() => clearTimeout(timer));
+		}
+		for (const sub of subscriptions) {
+			const deliver = (event, operation) => {
+				const decision = resolveDelivery(event, sub.policy, operation);
+				if (decision.kind === "drop") return;
+				if (decision.kind === "leave") {
+					stream.write(`${sub.name}.left`, JSON.stringify({
+						type: `${sub.name}.left`,
+						resource: sub.name,
+						id: event.meta?.resourceId
+					}), event.meta?.id);
+					return;
+				}
+				const { doc } = decision;
+				const needsMask = !!sub.fields && !!doc && typeof doc === "object";
+				let frame;
+				if (needsMask) {
+					const masked = applyFieldReadPermissions(doc, sub.fields, userRoles);
+					frame = buildChangeFrame(event, sub.name, masked);
+				} else {
+					const cached = sharedFrames.get(event);
+					frame = cached ?? buildChangeFrame(event, sub.name, doc);
+					if (!cached) sharedFrames.set(event, frame);
+				}
+				stream.write(event.type, frame, event.meta?.id);
+			};
+			for (const operation of operations) {
+				const unsub = await fastify.events.subscribe(`${sub.name}.${operation}`, (event) => deliver(event, operation));
+				stream.onCleanup(unsub);
+			}
+		}
+		stream.write("ready", JSON.stringify({
+			resources: subscriptions.map((s) => s.name),
+			operations: [...operations]
+		}));
+	};
+	const lookupEntry = (name) => {
+		if (allowlist && !allowlist.includes(name)) return void 0;
+		return fastify.arc?.registry?.get(name);
+	};
+	const notFound = (reply, name) => reply.code(404).send({
+		code: "arc.not_found",
+		message: `Resource '${name}' has no realtime feed`,
+		status: 404
+	});
+	fastify.route({
+		method: "GET",
+		url: path,
+		schema: {
+			tags: ["Events"],
+			summary: "Realtime resource change feed",
+			description: "SSE stream of created/updated/deleted events for one resource, gated by its list permission — row filters and field-level read permissions apply per event.",
+			response: { 200: {
+				type: "string",
+				description: "text/event-stream"
+			} }
+		},
+		handler: async (request, reply) => {
+			const resourceName = request.params.resource;
+			const entry = lookupEntry(resourceName);
+			if (!entry) return notFound(reply, resourceName);
+			if (!await runAuth(request, reply, [entry])) return;
+			const sub = await authorizeResource(resourceName, entry, request, reply);
+			if (!sub) return;
+			await streamSubscriptions(request, reply, [sub]);
+		}
+	});
+	const multiplexPath = path.replace(/\/:resource$/, "");
+	fastify.route({
+		method: "GET",
+		url: multiplexPath,
+		schema: {
+			tags: ["Events"],
+			summary: "Realtime multi-resource change feed",
+			description: "Multiplexed SSE stream for several resources over one connection (?resources=a,b,c). Every resource is gated by its own list permission; any denial rejects the subscription.",
+			querystring: {
+				type: "object",
+				properties: { resources: { type: "string" } },
+				required: ["resources"]
+			},
+			response: { 200: {
+				type: "string",
+				description: "text/event-stream"
+			} }
+		},
+		handler: async (request, reply) => {
+			const raw = request.query.resources;
+			const names = [...new Set(raw.split(",").map((s) => s.trim()).filter(Boolean))];
+			if (names.length === 0 || names.length > MAX_MULTIPLEX_RESOURCES) return reply.code(400).send({
+				code: "arc.bad_request",
+				message: `resources must name 1–${MAX_MULTIPLEX_RESOURCES} registered resources`,
+				status: 400
+			});
+			const entries = [];
+			for (const name of names) {
+				const entry = lookupEntry(name);
+				if (!entry) return notFound(reply, name);
+				entries.push(entry);
+			}
+			if (!await runAuth(request, reply, entries)) return;
+			const subscriptions = [];
+			for (let i = 0; i < names.length; i++) {
+				const sub = await authorizeResource(names[i], entries[i], request, reply);
+				if (!sub) return;
+				subscriptions.push(sub);
+			}
+			await streamSubscriptions(request, reply, subscriptions);
+		}
+	});
+	fastify.addHook("onClose", async () => {
+		for (const close of activeConnections) close();
+		activeConnections.clear();
+	});
+	log.debug("Plugin registered", {
+		path,
+		operations,
+		allowlist
+	});
+};
+var realtime_default = fp(realtimePlugin, {
+	name: "arc-realtime",
+	fastify: "5.x",
+	dependencies: ["arc-events"]
+});
+//#endregion
+export { realtime_default as n, realtime_exports as r, realtimePlugin as t };

package/dist/{registerRoute-xHc42fwB.mjs → registerRoute-CWO6mdYe.mjs}

@@ -1,6 +1,6 @@
 import { f as createError } from "./errors-DkO8Nk6-.mjs";
 import { n as requestContext } from "./requestContext-BZKOr13H.mjs";
-import { N as evaluateAndApplyPermission } from "./permissions-BJMuKMl7.mjs";
+import { n as evaluateAndApplyPermission } from "./applyPermissionResult-Tw4iXtlf.mjs";
 //#region src/core/middlewares/arcDecorator.ts
 /**
 * Build the `arcDecorator` preHandler for a resource.

package/dist/registry/index.d.mts

@@ -1,5 +1,5 @@
-import { K as ResolvedTenantPurge, R as RegisterOptions, V as ResourceDefinition, X as CrudRouteKey, k as IntrospectionPluginOptions, p as RegistryEntry, z as ResourceRegistry } from "../index-DbtgCOCj.mjs";
-import "../fastify-augmentation-9_fuetB4.mjs";
+import { K as ResolvedTenantPurge, R as RegisterOptions, V as ResourceDefinition, X as CrudRouteKey, k as IntrospectionPluginOptions, p as RegistryEntry, z as ResourceRegistry } from "../index-BBsvQt7U.mjs";
+import "../fastify-augmentation-g_f9omSc.mjs";
 import { FastifyPluginAsync } from "fastify";
 import { TenantPurgeProgress, TenantPurgeStrategy } from "@classytic/repo-core/repository";
 //#region src/registry/assertNoTenantData.d.ts

package/dist/registry/index.mjs

@@ -1,3 +1,3 @@
 import { a as cascadeDeleteForOrganization, c as assertNoTenantData, i as introspectionPlugin_default, n as buildResourceManifestFromRegistry, o as getCascadingResources, r as introspectionPlugin, s as getCascadingResourcesWithMetadata, t as buildResourceManifest } from "../registry-vcOCtPij.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-7RnrEWNP.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-y9Hnypus.mjs";
 export { ResourceRegistry, assertNoTenantData, buildResourceManifest, buildResourceManifestFromRegistry, cascadeDeleteForOrganization, getCascadingResources, getCascadingResourcesWithMetadata, introspectionPlugin_default as introspectionPlugin, introspectionPlugin as introspectionPluginFn };

package/dist/{schemaConverter-Ds5reSGs.mjs → schemaConverter-DJvodiHj.mjs}

@@ -100,7 +100,10 @@ function toJsonSchema(input, target = DEFAULT_FASTIFY_TARGET, mode = "warn") {
 	if (isZodSchema(input)) {
 		if (!_toJSONSchema) return unconvertible(mode, "A Zod schema was passed but zod v4 is not installed (or not yet loaded). Install zod >=4 — arc converts via zod's native z.toJSONSchema().");
 		try {
-			const converted = _toJSONSchema(input, { target });
+			const converted = _toJSONSchema(input, {
+				target,
+				unrepresentable: mode === "throw" ? "throw" : "any"
+			});
 			if ("$schema" in converted) delete converted.$schema;
 			return converted;
 		} catch (cause) {

package/dist/{schemaIR-B-6SPe7g.mjs → schemaIR-Ca7ySNPx.mjs}

@@ -1,4 +1,4 @@
-import { o as toJsonSchema } from "./schemaConverter-Ds5reSGs.mjs";
+import { o as toJsonSchema } from "./schemaConverter-DJvodiHj.mjs";
 //#region src/core/schemaIR.ts
 /**
 * Schema IR — one canonical representation, two adapters.

package/dist/scope/index.mjs

@@ -1,5 +1,5 @@
 import { C as isService, D as requireUserId, E as requireTeamId, S as isOrgInScope, T as requireOrgId, _ as getUserRoles, a as getDPoPJkt, b as isElevated, c as getOrgId, d as getScopeContext, f as getScopeContextMap, g as getUserId, h as getTenantFromRequest, i as getClientId, l as getOrgRoles, m as getTeamId, n as PUBLIC_SCOPE, o as getMandate, p as getServiceScopes, r as getAncestorOrgIds, s as getOrgContext, t as AUTHENTICATED_SCOPE, u as getRequestScope, v as hasOrgAccess, w as requireClientId, x as isMember, y as isAuthenticated } from "../types-bHblZ9YN.mjs";
 import { n as elevation_default, t as elevationPlugin } from "../elevation-COpYKt2h.mjs";
 import { t as createTenantKeyGenerator } from "../rateLimitKey-BoWRH3e7.mjs";
-import { t as resolveOrgFromHeader } from "../scope-k15RXfcq.mjs";
+import { t as resolveOrgFromHeader } from "../scope-LONQ3mfZ.mjs";
 export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, createTenantKeyGenerator, elevation_default as elevationPlugin, elevationPlugin as elevationPluginFn, getAncestorOrgIds, getClientId, getDPoPJkt, getMandate, getOrgContext, getOrgId, getOrgRoles, getRequestScope, getScopeContext, getScopeContextMap, getServiceScopes, getTeamId, getTenantFromRequest, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, isOrgInScope, isService, requireClientId, requireOrgId, requireTeamId, requireUserId, resolveOrgFromHeader };

package/dist/scope-LONQ3mfZ.mjs

@@ -0,0 +1,37 @@
+import { a as OrgAccessDeniedError, l as UnauthorizedError, u as ValidationError } from "./errors-DkO8Nk6-.mjs";
+import { t as getUserRoles } from "./types-XTApa8b6.mjs";
+//#region src/scope/resolveOrgFromHeader.ts
+/**
+* Create a preHandler hook that resolves org scope from a header.
+* Must run AFTER authentication so `request.user` is populated.
+* If the header is present and user is a member, sets `request.scope` to `member`.
+* If the header is absent, scope stays as-is (typically `authenticated`).
+*/
+function resolveOrgFromHeader(options) {
+	const { header = "x-organization-id", resolveMembership } = options;
+	return async (request, _reply) => {
+		const raw = request.headers[header.toLowerCase()];
+		if (Array.isArray(raw)) throw new ValidationError(`Duplicate '${header}' header`);
+		const orgId = raw;
+		if (!orgId) return;
+		const scope = request.scope;
+		if (!scope || scope.kind === "public") throw new UnauthorizedError("Authentication required for organization access");
+		if (scope.kind === "elevated") return;
+		const user = request.user;
+		if (!user) throw new UnauthorizedError("Authentication required for organization access");
+		const userId = String(user.id ?? user._id ?? "");
+		if (!userId) throw new UnauthorizedError("User identity required for organization access");
+		const membership = await resolveMembership(userId, orgId);
+		if (!membership) throw new OrgAccessDeniedError("Not a member of this organization");
+		const carriedRoles = "userRoles" in scope && Array.isArray(scope.userRoles) ? scope.userRoles : void 0;
+		request.scope = {
+			kind: "member",
+			userId: userId || void 0,
+			userRoles: carriedRoles?.length ? carriedRoles : getUserRoles(user),
+			organizationId: orgId,
+			orgRoles: membership.roles
+		};
+	};
+}
+//#endregion
+export { resolveOrgFromHeader as t };

package/dist/simpleEqualityMatcher-Cg05HPsn.mjs

@@ -0,0 +1,68 @@
+//#region src/utils/simpleEqualityMatcher.ts
+/**
+* `simpleEqualityMatcher` — a minimal, dialect-agnostic flat-key equality
+* matcher for `DataAdapter.matchesFilter` / `BaseController({ matchesFilter })`.
+*
+* **What it does:** for each `[key, expected]` in the filter, compares
+* `item[key]` to `expected` via string coercion (so Mongo `ObjectId` values
+* match their string representation) and returns `true` only if every
+* filter entry matches. Array item values are matched implicitly (contains).
+*
+* **What it does NOT do:**
+* - No `$eq` / `$ne` / `$in` / `$nin` / `$gt` / `$lt` / `$regex` / `$exists`
+* - No `$and` / `$or`
+* - No dot-path traversal (`"owner.id"`)
+* - No schema-specific coercion
+*
+* **Why it exists:** 95%+ of arc's `_policyFilters` are produced by built-in
+* permission helpers and are shaped like `{ ownerId: "u1" }` or
+* `{ organizationId: "org_x" }` — flat equality. For that common shape,
+* this helper is a safe, tested, 15-line defense-in-depth matcher that
+* hosts using minimal repos (no `getOne(compoundFilter)` DB path) can opt
+* into without arc shipping a full Mongo-syntax engine.
+*
+* **When to use:**
+* - Your adapter/repo doesn't natively filter on `getOne(compoundFilter)`
+* - Your `_policyFilters` are flat equality (from arc's built-in permission helpers)
+* - You want defense-in-depth on `validateItemAccess` / `fetchDetailed`'s `getById` fallback
+*
+* **When NOT to use:**
+* - Your `_policyFilters` use operators (`$in`, `$ne`, etc.) — supply a
+*   native matcher (mongokit's repo does the filter at the DB layer; for
+*   custom repos, wrap the kit's own predicate engine).
+* - You're a mongokit / sqlitekit / Prisma user — the DB-level filter
+*   applied by `getOne(compoundFilter)` already covers this.
+*
+* @example
+* ```ts
+* import { simpleEqualityMatcher } from '@classytic/arc/utils';
+*
+* // On a custom adapter
+* const adapter: DataAdapter = {
+*   repository,
+*   type: 'custom',
+*   name: 'in-memory',
+*   matchesFilter: simpleEqualityMatcher,
+* };
+*
+* // Or directly on BaseController for ad-hoc controllers
+* new BaseController(repo, { matchesFilter: simpleEqualityMatcher });
+* ```
+*/
+function simpleEqualityMatcher(item, filters) {
+	if (!item || typeof item !== "object") return false;
+	const obj = item;
+	for (const [key, expected] of Object.entries(filters)) {
+		if (expected && typeof expected === "object" && !Array.isArray(expected) && Object.getPrototypeOf(expected) === Object.prototype && Object.keys(expected).some((k) => k.startsWith("$"))) return false;
+		const actual = obj[key];
+		if (Array.isArray(actual)) {
+			const expectedStr = String(expected);
+			if (!actual.some((v) => String(v) === expectedStr)) return false;
+			continue;
+		}
+		if (String(actual) !== String(expected)) return false;
+	}
+	return true;
+}
+//#endregion
+export { simpleEqualityMatcher as t };

package/dist/{sse-CfUjwjDk.mjs → sse-0u4P4-OI.mjs}

@@ -1,7 +1,8 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { c as getOrgId, n as PUBLIC_SCOPE } from "./types-bHblZ9YN.mjs";
-import { a as promoteStreamTokenToHeader, n as forwardedStreamHeaders } from "./streaming-BQcW6_Kq.mjs";
+import { a as promoteStreamTokenToHeader } from "./streaming-BQcW6_Kq.mjs";
+import { t as openSseStream } from "./sseStream-BQ7Qaynp.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/sse.ts
 var sse_exports = /* @__PURE__ */ __exportAll({
@@ -29,16 +30,8 @@ const ssePlugin = async (fastify, opts = {}) => {
 			} }
 		},
 		handler: async (request, reply) => {
-			reply.hijack();
-			reply.raw.writeHead(200, {
-				"content-type": "text/event-stream",
-				"cache-control": "no-cache",
-				connection: "keep-alive",
-				"x-accel-buffering": "no",
-				...forwardedStreamHeaders(reply)
-			});
-			reply.raw.flushHeaders();
-			const unsubscribers = [];
+			const stream = openSseStream(request, reply, { heartbeatMs: heartbeat });
+			stream.onCleanup(() => activeConnections.delete(stream.close));
 			const requestOrgId = getOrgId(request.scope ?? PUBLIC_SCOPE);
 			const dropOrgEvents = orgScoped && !requestOrgId;
 			for (const pattern of patterns) {
@@ -57,27 +50,11 @@ const ssePlugin = async (fastify, opts = {}) => {
 							timestamp: event.meta.timestamp
 						}
 					});
-					if (!reply.raw.write(`event: ${event.type}\ndata: ${data}\n\n`)) {
-						request.raw.destroy(/* @__PURE__ */ new Error("SSE connection terminated: slow client backpressure"));
-						cleanup();
-					}
+					stream.write(event.type, data);
 				});
-				unsubscribers.push(unsub);
+				stream.onCleanup(unsub);
 			}
-			const heartbeatTimer = setInterval(() => {
-				if (!reply.raw.write(": heartbeat\n\n")) {
-					request.raw.destroy(/* @__PURE__ */ new Error("SSE connection terminated: heartbeat backpressure"));
-					cleanup();
-				}
-			}, heartbeat);
-			const cleanup = () => {
-				clearInterval(heartbeatTimer);
-				for (const unsub of unsubscribers) unsub();
-				if (!reply.raw.writableEnded) reply.raw.end();
-				activeConnections.delete(cleanup);
-			};
-			activeConnections.add(cleanup);
-			request.raw.on("close", cleanup);
+			activeConnections.add(stream.close);
 		}
 	};
 	if (requireAuth) {

package/dist/sseStream-BQ7Qaynp.mjs

@@ -0,0 +1,57 @@
+import { n as forwardedStreamHeaders } from "./streaming-BQcW6_Kq.mjs";
+//#region src/utils/sseStream.ts
+/**
+* Take over the reply socket and open an SSE stream. Call ONLY after every
+* gate (auth, permissions, validation) has passed — after `hijack()` no
+* JSON error can be sent.
+*/
+function openSseStream(request, reply, options = {}) {
+	const { heartbeatMs = 3e4, retryMs } = options;
+	reply.hijack();
+	reply.raw.writeHead(200, {
+		"content-type": "text/event-stream",
+		"cache-control": "no-cache",
+		connection: "keep-alive",
+		"x-accel-buffering": "no",
+		...forwardedStreamHeaders(reply)
+	});
+	reply.raw.flushHeaders();
+	if (retryMs !== void 0) reply.raw.write(`retry: ${retryMs}\n\n`);
+	const cleanups = [];
+	let closed = false;
+	const close = () => {
+		if (closed) return;
+		closed = true;
+		clearInterval(heartbeatTimer);
+		for (const fn of cleanups) try {
+			fn();
+		} catch {}
+		if (!reply.raw.writableEnded) reply.raw.end();
+	};
+	const destroyOnBackpressure = (context) => {
+		request.raw.destroy(/* @__PURE__ */ new Error(`SSE connection terminated: ${context} backpressure`));
+		close();
+	};
+	const heartbeatTimer = setInterval(() => {
+		if (closed) return;
+		if (!reply.raw.write(": heartbeat\n\n")) destroyOnBackpressure("heartbeat");
+	}, heartbeatMs);
+	request.raw.on("close", close);
+	return {
+		write(eventName, data, id) {
+			if (closed) return false;
+			const idField = id !== void 0 ? `id: ${id}\n` : "";
+			if (!reply.raw.write(`${idField}event: ${eventName}\ndata: ${data}\n\n`)) {
+				destroyOnBackpressure("slow client");
+				return false;
+			}
+			return true;
+		},
+		close,
+		onCleanup(fn) {
+			cleanups.push(fn);
+		}
+	};
+}
+//#endregion
+export { openSseStream as t };

package/dist/testing/index.d.mts

@@ -1,6 +1,6 @@
-import { V as ResourceDefinition, qt as AnyRecord } from "../index-DbtgCOCj.mjs";
+import { Jt as AnyRecord, V as ResourceDefinition } from "../index-BBsvQt7U.mjs";
 import { n as ArcModuleInput } from "../module-B4u10iOJ.mjs";
-import { d as preloadResourcesAsync, t as CreateAppOptions, u as preloadResources } from "../index-BEu4wjbL.mjs";
+import { d as preloadResourcesAsync, t as CreateAppOptions, u as preloadResources } from "../index-Ba10fdKp.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Mock } from "vitest";