@classytic/arc 2.9.1 → 2.10.8

package/dist/{types-DZi1aYhm.d.mts → fields-C8Y0XLAu.d.mts}

@@ -1,4 +1,4 @@
-import { r as RequestScope } from "./types-BD85MlEK.mjs";
+import { r as RequestScope } from "./types-tgR4Pt8F.mjs";
 import { FastifyRequest } from "fastify";
 
 //#region src/permissions/types.d.ts
@@ -175,4 +175,124 @@ interface PermissionCheckMeta {
   _orgInScopeTarget?: string | ((ctx: PermissionContext) => string | undefined);
 }
 //#endregion
-export { getUserRoles as a, UserBase as i, PermissionContext as n, normalizeRoles as o, PermissionResult as r, PermissionCheck as t };
+//#region src/permissions/fields.d.ts
+/**
+ * Field-Level Permissions
+ *
+ * Control field visibility and writability per role.
+ * Integrated into the response path (read) and sanitization path (write).
+ *
+ * @example
+ * ```typescript
+ * import { fields, defineResource } from '@classytic/arc';
+ *
+ * const userResource = defineResource({
+ *   name: 'user',
+ *   adapter: userAdapter,
+ *   fields: {
+ *     salary: fields.visibleTo(['admin', 'hr']),
+ *     internalNotes: fields.writableBy(['admin']),
+ *     email: fields.redactFor(['viewer']),
+ *     password: fields.hidden(),
+ *   },
+ * });
+ * ```
+ */
+type FieldPermissionType = "hidden" | "visibleTo" | "writableBy" | "redactFor";
+interface FieldPermission {
+  readonly _type: FieldPermissionType;
+  readonly roles?: readonly string[];
+  readonly redactValue?: unknown;
+}
+type FieldPermissionMap = Record<string, FieldPermission>;
+declare const fields: {
+  /**
+   * Field is never included in responses. Not writable via API.
+   *
+   * @example
+   * ```typescript
+   * fields: { password: fields.hidden() }
+   * ```
+   */
+  hidden(): FieldPermission;
+  /**
+   * Field is only visible to users with specified roles.
+   * Other users don't see the field at all.
+   *
+   * @example
+   * ```typescript
+   * fields: { salary: fields.visibleTo(['admin', 'hr']) }
+   * ```
+   */
+  visibleTo(roles: readonly string[]): FieldPermission;
+  /**
+   * Field is only writable by users with specified roles.
+   * All users can still read the field. Users without the role
+   * have the field silently stripped from write operations.
+   *
+   * @example
+   * ```typescript
+   * fields: { role: fields.writableBy(['admin']) }
+   * ```
+   */
+  writableBy(roles: readonly string[]): FieldPermission;
+  /**
+   * Field is redacted (replaced with a placeholder) for specified roles.
+   * Other users see the real value.
+   *
+   * @param roles - Roles that see the redacted value
+   * @param redactValue - Replacement value (default: '***')
+   *
+   * @example
+   * ```typescript
+   * fields: {
+   *   email: fields.redactFor(['viewer']),
+   *   ssn: fields.redactFor(['basic'], '***-**-****'),
+   * }
+   * ```
+   */
+  redactFor(roles: readonly string[], redactValue?: unknown): FieldPermission;
+};
+/**
+ * Apply field-level READ permissions to a response object.
+ * Strips hidden fields, enforces visibility, and applies redaction.
+ *
+ * @param data - The response object (mutated in place for performance)
+ * @param fieldPermissions - Field permission map from resource config
+ * @param userRoles - Current user's roles (empty array for unauthenticated)
+ * @returns The filtered object
+ */
+declare function applyFieldReadPermissions<T extends Record<string, unknown>>(data: T, fieldPermissions: FieldPermissionMap, userRoles: readonly string[]): T;
+/**
+ * Result of applying write permissions — includes both the filtered body
+ * and the list of fields that were stripped so callers can decide whether
+ * to reject the request (secure default) or silently strip (legacy).
+ */
+interface FieldWritePermissionResult<T extends Record<string, unknown>> {
+  readonly body: T;
+  readonly deniedFields: readonly string[];
+}
+/**
+ * Apply field-level WRITE permissions to request body.
+ *
+ * Returns both the filtered body and the list of denied fields. Callers are
+ * expected to reject the request when `deniedFields.length > 0` — silently
+ * stripping fields hides misconfigurations and real attacks. See
+ * `BodySanitizer` for the default policy.
+ *
+ * @param body - The request body (returns a new filtered copy)
+ * @param fieldPermissions - Field permission map from resource config
+ * @param userRoles - Current user's roles
+ */
+declare function applyFieldWritePermissions<T extends Record<string, unknown>>(body: T, fieldPermissions: FieldPermissionMap, userRoles: readonly string[]): FieldWritePermissionResult<T>;
+/**
+ * Resolve effective roles by merging global user roles with org-level roles.
+ *
+ * Global roles come from `req.user.role` (normalized via getUserRoles()).
+ * Org roles come from `req.context.orgRoles` (set by BA adapter's org bridge).
+ *
+ * When no org context exists, returns global roles only — backward compatible.
+ */
+declare function resolveEffectiveRoles(userRoles: readonly string[], orgRoles: readonly string[]): string[];
+//#endregion
+export { applyFieldWritePermissions as a, PermissionCheck as c, UserBase as d, getUserRoles as f, applyFieldReadPermissions as i, PermissionContext as l, FieldPermissionMap as n, fields as o, normalizeRoles as p, FieldPermissionType as r, resolveEffectiveRoles as s, FieldPermission as t, PermissionResult as u };

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-import { An as beforeCreate, Cn as HookPhase, Dn as afterCreate, En as HookSystemOptions, Mn as beforeUpdate, Nn as createHookSystem, On as afterDelete, Pn as defineHook, Sn as HookOperation, Tn as HookSystem, bn as HookContext, jn as beforeDelete, kn as afterUpdate, wn as HookRegistration, xn as HookHandler, yn as DefineHookOptions } from "../interface-YrWsmKqE.mjs";
+import { $ as beforeCreate, G as HookOperation, H as DefineHookOptions, J as HookSystem, K as HookPhase, Q as afterUpdate, U as HookContext, W as HookHandler, X as afterCreate, Y as HookSystemOptions, Z as afterDelete, et as beforeDelete, nt as createHookSystem, q as HookRegistration, rt as defineHook, tt as beforeUpdate } from "../index-BGbpGVyM.mjs";
 export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/idempotency/index.d.mts

@@ -1,4 +1,4 @@
-import { o as RepositoryLike } from "../interface-YrWsmKqE.mjs";
+import { _n as RepositoryLike } from "../index-BGbpGVyM.mjs";
 import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-B-pe8fhj.mjs";
 import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-MXLp1oOf.mjs";
 import { FastifyPluginAsync } from "fastify";
@@ -82,6 +82,9 @@ declare module "fastify" {
 declare const idempotencyPlugin: FastifyPluginAsync<IdempotencyPluginOptions>;
 declare const _default: FastifyPluginAsync<IdempotencyPluginOptions>;
 //#endregion
+//#region src/idempotency/repository-idempotency-adapter.d.ts
+declare function repositoryAsIdempotencyStore(repository: RepositoryLike, defaultTtlMs: number): IdempotencyStore;
+//#endregion
 //#region src/idempotency/stores/memory.d.ts
 interface MemoryIdempotencyStoreOptions {
   /** Default TTL in milliseconds (default: 86400000 = 24h) */
@@ -117,4 +120,4 @@ declare class MemoryIdempotencyStore implements IdempotencyStore {
   private evictOldest;
 }
 //#endregion
-export { type IdempotencyLock, type IdempotencyPluginOptions, type IdempotencyResult, type IdempotencyStore, MemoryIdempotencyStore, type MemoryIdempotencyStoreOptions, type RedisClient, type RedisIdempotencyStoreOptions, createIdempotencyResult, _default as idempotencyPlugin, idempotencyPlugin as idempotencyPluginFn };
+export { type IdempotencyLock, type IdempotencyPluginOptions, type IdempotencyResult, type IdempotencyStore, MemoryIdempotencyStore, type MemoryIdempotencyStoreOptions, type RedisClient, type RedisIdempotencyStoreOptions, createIdempotencyResult, _default as idempotencyPlugin, idempotencyPlugin as idempotencyPluginFn, repositoryAsIdempotencyStore };

package/dist/idempotency/index.mjs

@@ -1,7 +1,28 @@
-import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-DFiZl5TL.mjs";
+import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-DYYUQbQN.mjs";
 import { createHash } from "node:crypto";
 import fp from "fastify-plugin";
+import { and, eq, exists, gt, lt, or, startsWith } from "@classytic/repo-core/filter";
+import { update } from "@classytic/repo-core/update";
 //#region src/idempotency/repository-idempotency-adapter.ts
+/**
+* RepositoryLike → IdempotencyStore adapter.
+*
+* Maps the idempotency store's verbs (get / set / tryLock / unlock / delete /
+* deleteByPrefix / findByPrefix) onto arc's canonical repository primitives
+* (`getOne` / `deleteMany` / `findOneAndUpdate`). `idempotencyPlugin` wraps
+* a passed repository with this helper when you use the `{ repository }`
+* option; the function is also re-exported from `@classytic/arc/idempotency`
+* so consumers can build and decorate the store (metrics, tracing, key
+* namespacing) before passing it via `store:`.
+*
+* Portability: filters compose via `@classytic/repo-core/filter` builders
+* (`and` / `or` / `eq` / `gt` / `lt` / `exists` / `startsWith`) and updates
+* via `@classytic/repo-core/update` (`update({ set, unset, setOnInsert })`).
+* Both IRs compile to Mongo operators on mongokit, SQL predicates on
+* sqlitekit / pgkit, and `WhereInput` / `update` on prismakit. The store
+* therefore runs identically on every backend that implements the
+* `StandardRepo.findOneAndUpdate` + `getOne` + `deleteMany` surface.
+*/
 function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 	const missing = [];
 	if (typeof repository.getOne !== "function") missing.push("getOne");
@@ -9,13 +30,13 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 	if (typeof repository.findOneAndUpdate !== "function") missing.push("findOneAndUpdate");
 	if (missing.length > 0) throw new Error(`idempotencyPlugin: repository is missing required methods: ${missing.join(", ")}. mongokit ≥3.8 satisfies these; other kits must implement them to back idempotency via a repository.`);
 	const r = repository;
+	const idField = repository.idField ?? "_id";
 	const isDuplicateKeyError = createIsDuplicateKeyError(repository);
 	const safeGetOne = createSafeGetOne(repository);
-	const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 	return {
 		name: "repository",
 		async get(key) {
-			const doc = await safeGetOne({ _id: key });
+			const doc = await safeGetOne(eq(idField, key));
 			if (!doc?.result) return void 0;
 			if (new Date(doc.expiresAt) < /* @__PURE__ */ new Date()) return void 0;
 			return {
@@ -28,8 +49,8 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 			};
 		},
 		async set(key, result) {
-			await r.findOneAndUpdate({ _id: key }, {
-				$set: {
+			await r.findOneAndUpdate(eq(idField, key), update({
+				set: {
 					result: {
 						statusCode: result.statusCode,
 						headers: result.headers,
@@ -38,8 +59,8 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 					createdAt: result.createdAt,
 					expiresAt: result.expiresAt
 				},
-				$unset: { lock: "" }
-			}, {
+				unset: ["lock"]
+			}), {
 				upsert: true,
 				returnDocument: "after"
 			});
@@ -49,19 +70,16 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 			const lockExpiresAt = new Date(now.getTime() + ttlMs);
 			const docExpiresAt = new Date(now.getTime() + defaultTtlMs);
 			try {
-				const doc = await r.findOneAndUpdate({
-					_id: key,
-					$or: [{ lock: { $exists: false } }, { "lock.expiresAt": { $lt: now } }]
-				}, {
-					$set: { lock: {
+				const doc = await r.findOneAndUpdate(and(eq(idField, key), or(exists("lock", false), lt("lock.expiresAt", now))), update({
+					set: { lock: {
 						requestId,
 						expiresAt: lockExpiresAt
 					} },
-					$setOnInsert: {
+					setOnInsert: {
 						createdAt: now,
 						expiresAt: docExpiresAt
 					}
-				}, {
+				}), {
 					upsert: true,
 					returnDocument: "after"
 				});
@@ -72,31 +90,24 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 			}
 		},
 		async unlock(key, requestId) {
-			await r.findOneAndUpdate({
-				_id: key,
-				"lock.requestId": requestId
-			}, { $unset: { lock: "" } });
+			await r.findOneAndUpdate(and(eq(idField, key), eq("lock.requestId", requestId)), update({ unset: ["lock"] }));
 		},
 		async isLocked(key) {
-			const doc = await safeGetOne({ _id: key });
+			const doc = await safeGetOne(eq(idField, key));
 			if (!doc?.lock) return false;
 			return new Date(doc.lock.expiresAt) > /* @__PURE__ */ new Date();
 		},
 		async delete(key) {
-			await r.deleteMany({ _id: key });
+			await r.deleteMany(eq(idField, key));
 		},
 		async deleteByPrefix(prefix) {
-			return (await r.deleteMany({ _id: { $regex: `^${escapeRegex(prefix)}` } })).deletedCount ?? 0;
+			return (await r.deleteMany(startsWith(idField, prefix, "sensitive"))).deletedCount ?? 0;
 		},
 		async findByPrefix(prefix) {
-			const doc = await safeGetOne({
-				_id: { $regex: `^${escapeRegex(prefix)}` },
-				result: { $exists: true },
-				expiresAt: { $gt: /* @__PURE__ */ new Date() }
-			});
+			const doc = await safeGetOne(and(startsWith(idField, prefix, "sensitive"), exists("result", true), gt("expiresAt", /* @__PURE__ */ new Date())));
 			if (!doc?.result) return void 0;
 			return {
-				key: doc._id,
+				key: String(doc[idField] ?? prefix),
 				statusCode: doc.result.statusCode,
 				headers: doc.result.headers,
 				body: doc.result.body,
@@ -361,6 +372,7 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 			return;
 		}
 		request._idempotencyFullKey = fullKey;
+		reply.header(HEADER_IDEMPOTENCY_KEY, idempotencyKey);
 	};
 	fastify.decorate("idempotency", {
 		invalidate: async (key) => {
@@ -371,15 +383,12 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		},
 		middleware: idempotencyMiddleware
 	});
-	fastify.addHook("onSend", async (request, reply, payload) => {
+	fastify.addHook("preSerialization", async (request, reply, payload) => {
 		if (request.idempotencyReplayed) return payload;
 		const fullKey = request._idempotencyFullKey;
 		if (!fullKey) return payload;
 		const statusCode = reply.statusCode;
-		if (statusCode < 200 || statusCode >= 300) {
-			await store.unlock(fullKey, request.id);
-			return payload;
-		}
+		if (statusCode < 200 || statusCode >= 300) return payload;
 		const headersToCache = {};
 		const excludeHeaders = new Set([
 			"content-length",
@@ -399,13 +408,13 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		}
 		const result = createIdempotencyResult(statusCode, body, headersToCache, ttlMs);
 		await store.set(fullKey, result);
-		await store.unlock(fullKey, request.id);
-		reply.header(HEADER_IDEMPOTENCY_KEY, request.idempotencyKey);
 		return payload;
 	});
-	fastify.addHook("onError", async (request) => {
+	fastify.addHook("onResponse", async (request) => {
+		if (request.idempotencyReplayed) return;
 		const fullKey = request._idempotencyFullKey;
-		if (fullKey) await store.unlock(fullKey, request.id);
+		if (!fullKey) return;
+		await store.unlock(fullKey, request.id);
 	});
 	fastify.addHook("onClose", async () => {
 		await store.close?.();
@@ -421,4 +430,4 @@ var idempotencyPlugin_default = fp(idempotencyPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { MemoryIdempotencyStore, createIdempotencyResult, idempotencyPlugin_default as idempotencyPlugin, idempotencyPlugin as idempotencyPluginFn };
+export { MemoryIdempotencyStore, createIdempotencyResult, idempotencyPlugin_default as idempotencyPlugin, idempotencyPlugin as idempotencyPluginFn, repositoryAsIdempotencyStore };