@classytic/arc 2.11.4 → 2.13.1

package/dist/scim/index.mjs

@@ -0,0 +1,963 @@
+import fp from "fastify-plugin";
+//#region src/scim/errors.ts
+var ScimError = class extends Error {
+	statusCode;
+	scimType;
+	constructor(statusCode, scimType, detail) {
+		super(detail);
+		this.statusCode = statusCode;
+		this.scimType = scimType;
+		this.name = "ScimError";
+	}
+	toResponse() {
+		return {
+			schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+			status: String(this.statusCode),
+			...this.scimType ? { scimType: this.scimType } : {},
+			detail: this.message
+		};
+	}
+};
+//#endregion
+//#region src/scim/helpers.ts
+/** Combine plugin defaults with the host's per-resource mapping override. */
+function mergeMapping(defaults, override) {
+	if (!override) return defaults;
+	return {
+		schema: override.schema ?? defaults.schema,
+		attributes: {
+			...defaults.attributes,
+			...override.attributes ?? {}
+		},
+		reverseAttributes: override.reverseAttributes,
+		fromScim: override.fromScim ?? defaults.fromScim,
+		toScim: override.toScim ?? defaults.toScim
+	};
+}
+/**
+* Build the per-request auth check from `bearer` (static) or `verify` (callback).
+* Throws at plugin construction if both / neither are configured.
+*/
+function makeAuthCheck(opts) {
+	if (opts.bearer && opts.verify) throw new Error("scimPlugin: pass either `bearer` or `verify`, not both");
+	if (opts.bearer) {
+		const expected = `Bearer ${opts.bearer}`;
+		return async (request) => {
+			if (request.headers.authorization !== expected) throw new ScimError(401, void 0, "Invalid bearer token");
+		};
+	}
+	if (opts.verify) {
+		const verify = opts.verify;
+		return async (request) => {
+			if (!await verify(request)) throw new ScimError(401, void 0, "SCIM authentication failed");
+		};
+	}
+	throw new Error("scimPlugin: configure either `bearer` (static token) or `verify` (callback)");
+}
+/**
+* Format any thrown value into the canonical SCIM 2.0 error envelope and
+* write it to the reply. Always sends `application/scim+json`.
+*/
+function sendScimError(reply, err) {
+	if (err instanceof ScimError) return reply.code(err.statusCode).header("Content-Type", "application/scim+json").send(err.toResponse());
+	const fallback = new ScimError(500, void 0, err instanceof Error ? err.message : "Internal SCIM error");
+	return reply.code(fallback.statusCode).header("Content-Type", "application/scim+json").send(fallback.toResponse());
+}
+function unwrapList(result) {
+	if (Array.isArray(result)) return {
+		items: result,
+		total: result.length
+	};
+	if (result && typeof result === "object") {
+		const r = result;
+		if (Array.isArray(r.data)) return {
+			items: r.data,
+			total: r.total ?? r.data.length
+		};
+		if (Array.isArray(r.docs)) return {
+			items: r.docs,
+			total: r.total ?? r.docs.length
+		};
+	}
+	return {
+		items: [],
+		total: 0
+	};
+}
+/** Coerce a Mongoose / Drizzle / plain doc to a plain `Record`. */
+function asRecord(doc) {
+	if (!doc || typeof doc !== "object") return {};
+	if (typeof doc.toObject === "function") return doc.toObject();
+	return doc;
+}
+/**
+* Register the `application/scim+json` Fastify content-type parser. Idempotent
+* — second registration in the same scope is a no-op. Empty bodies (DELETE,
+* GET) yield `undefined` rather than crashing on `JSON.parse("")`.
+*/
+function ensureScimContentTypeParser(fastify) {
+	if (fastify.hasContentTypeParser("application/scim+json")) return;
+	fastify.addContentTypeParser("application/scim+json", { parseAs: "string" }, (_req, body, done) => {
+		const raw = body;
+		if (!raw || raw.length === 0) {
+			done(null, void 0);
+			return;
+		}
+		try {
+			done(null, JSON.parse(raw));
+		} catch (err) {
+			done(err, void 0);
+		}
+	});
+}
+/**
+* Does the repo expose `findOneAndUpdate` (StandardRepo optional)? Required
+* for SCIM PATCH because operator-shaped updates ($set / $unset / $push /
+* $pull) need to flow through unchanged.
+*/
+function hasFindOneAndUpdate(repo) {
+	return typeof repo.findOneAndUpdate === "function";
+}
+/**
+* Does the repo expose `bulkWrite` with `replaceOne` support? Required for
+* SCIM PUT — full document replacement is not in MinimalRepo, only reachable
+* via `bulkWrite([{ replaceOne }])`.
+*/
+function hasBulkWrite(repo) {
+	return typeof repo.bulkWrite === "function";
+}
+//#endregion
+//#region src/scim/discovery.ts
+function mountDiscoveryRoutes(fastify, prefix, hasGroups, authCheck, maxResults, observe) {
+	fastify.get(`${prefix}/ServiceProviderConfig`, async (request, reply) => {
+		const start = Date.now();
+		try {
+			await authCheck(request);
+			const baseUrl = `${request.protocol}://${request.hostname}${prefix}`;
+			const payload = {
+				schemas: ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
+				documentationUri: "https://datatracker.ietf.org/doc/html/rfc7644",
+				patch: { supported: true },
+				bulk: {
+					supported: false,
+					maxOperations: 0,
+					maxPayloadSize: 0
+				},
+				filter: {
+					supported: true,
+					maxResults
+				},
+				changePassword: { supported: false },
+				sort: { supported: true },
+				etag: { supported: false },
+				authenticationSchemes: [{
+					type: "oauthbearertoken",
+					name: "OAuth Bearer Token",
+					description: "Authentication via OAuth 2.0 bearer token",
+					specUri: "https://datatracker.ietf.org/doc/html/rfc6750",
+					primary: true
+				}],
+				meta: {
+					location: `${baseUrl}/ServiceProviderConfig`,
+					resourceType: "ServiceProviderConfig"
+				}
+			};
+			observe({
+				resourceType: "discovery",
+				op: "discovery.serviceProviderConfig",
+				status: 200,
+				durationMs: Date.now() - start,
+				path: "/ServiceProviderConfig"
+			});
+			return reply.code(200).header("Content-Type", "application/scim+json").send(payload);
+		} catch (err) {
+			observe({
+				resourceType: "discovery",
+				op: "discovery.serviceProviderConfig",
+				status: 401,
+				durationMs: Date.now() - start,
+				path: "/ServiceProviderConfig"
+			});
+			return sendScimError(reply, err);
+		}
+	});
+	fastify.get(`${prefix}/ResourceTypes`, async (request, reply) => {
+		const start = Date.now();
+		try {
+			await authCheck(request);
+			const baseUrl = `${request.protocol}://${request.hostname}${prefix}`;
+			const types = [{
+				schemas: ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
+				id: "User",
+				name: "User",
+				endpoint: "/Users",
+				schema: "urn:ietf:params:scim:schemas:core:2.0:User",
+				meta: {
+					location: `${baseUrl}/ResourceTypes/User`,
+					resourceType: "ResourceType"
+				}
+			}];
+			if (hasGroups) types.push({
+				schemas: ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
+				id: "Group",
+				name: "Group",
+				endpoint: "/Groups",
+				schema: "urn:ietf:params:scim:schemas:core:2.0:Group",
+				meta: {
+					location: `${baseUrl}/ResourceTypes/Group`,
+					resourceType: "ResourceType"
+				}
+			});
+			observe({
+				resourceType: "discovery",
+				op: "discovery.resourceTypes",
+				status: 200,
+				durationMs: Date.now() - start,
+				path: "/ResourceTypes"
+			});
+			return reply.code(200).header("Content-Type", "application/scim+json").send({
+				schemas: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
+				totalResults: types.length,
+				Resources: types
+			});
+		} catch (err) {
+			observe({
+				resourceType: "discovery",
+				op: "discovery.resourceTypes",
+				status: 401,
+				durationMs: Date.now() - start,
+				path: "/ResourceTypes"
+			});
+			return sendScimError(reply, err);
+		}
+	});
+	fastify.get(`${prefix}/Schemas`, async (request, reply) => {
+		const start = Date.now();
+		try {
+			await authCheck(request);
+			observe({
+				resourceType: "discovery",
+				op: "discovery.schemas",
+				status: 200,
+				durationMs: Date.now() - start,
+				path: "/Schemas"
+			});
+			return reply.code(200).header("Content-Type", "application/scim+json").send({
+				schemas: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
+				totalResults: hasGroups ? 2 : 1,
+				Resources: [{
+					id: "urn:ietf:params:scim:schemas:core:2.0:User",
+					name: "User"
+				}, ...hasGroups ? [{
+					id: "urn:ietf:params:scim:schemas:core:2.0:Group",
+					name: "Group"
+				}] : []]
+			});
+		} catch (err) {
+			observe({
+				resourceType: "discovery",
+				op: "discovery.schemas",
+				status: 401,
+				durationMs: Date.now() - start,
+				path: "/Schemas"
+			});
+			return sendScimError(reply, err);
+		}
+	});
+}
+//#endregion
+//#region src/scim/mapping.ts
+const SCIM_USER_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:User";
+const SCIM_GROUP_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:Group";
+const SCIM_ENTERPRISE_USER_SCHEMA = "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User";
+const DEFAULT_USER_MAPPING = {
+	schema: SCIM_USER_SCHEMA,
+	attributes: {
+		id: "id",
+		userName: "email",
+		"name.formatted": "name",
+		displayName: "name",
+		"emails.value": "email",
+		active: "isActive",
+		externalId: "externalId",
+		"meta.created": "createdAt",
+		"meta.lastModified": "updatedAt"
+	}
+};
+const DEFAULT_GROUP_MAPPING = {
+	schema: SCIM_GROUP_SCHEMA,
+	attributes: {
+		id: "id",
+		displayName: "name",
+		externalId: "externalId",
+		"meta.created": "createdAt",
+		"meta.lastModified": "updatedAt"
+	}
+};
+function buildReverseMap(forward) {
+	const out = {};
+	for (const [scim, backend] of Object.entries(forward)) if (!(backend in out)) out[backend] = scim;
+	return out;
+}
+function getDeep(obj, path) {
+	const parts = path.split(".");
+	let cur = obj;
+	for (const p of parts) if (cur && typeof cur === "object") cur = cur[p];
+	else return void 0;
+	return cur;
+}
+function setDeep(obj, path, value) {
+	const parts = path.split(".");
+	let cur = obj;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const k = parts[i];
+		if (typeof cur[k] !== "object" || cur[k] === null) cur[k] = {};
+		cur = cur[k];
+	}
+	cur[parts[parts.length - 1]] = value;
+}
+/** Translate inbound SCIM JSON → resource shape. */
+function scimToResource(scim, mapping) {
+	const mapped = {};
+	for (const [scimAttr, backendField] of Object.entries(mapping.attributes)) {
+		const v = getDeep(scim, scimAttr);
+		if (v !== void 0 && v !== null && v !== "") mapped[backendField] = v;
+	}
+	if (Array.isArray(scim.emails)) {
+		const list = scim.emails;
+		const primary = list.find((e) => e.primary === true) ?? list[0];
+		if (primary?.value && mapping.attributes["emails.value"]) mapped[mapping.attributes["emails.value"]] = primary.value;
+	}
+	return mapping.fromScim ? mapping.fromScim(scim, mapped) : mapped;
+}
+/** Translate resource → SCIM JSON. */
+function resourceToScim(resource, mapping, baseUrl) {
+	const reverse = mapping.reverseAttributes ?? buildReverseMap(mapping.attributes);
+	const out = { schemas: [mapping.schema] };
+	for (const [backendField, value] of Object.entries(resource)) {
+		if (value === void 0 || value === null) continue;
+		const scimAttr = reverse[backendField];
+		if (!scimAttr) continue;
+		setDeep(out, scimAttr, value);
+	}
+	const primaryEmail = resource[mapping.attributes["emails.value"] ?? "email"];
+	if (primaryEmail) out.emails = [{
+		value: primaryEmail,
+		primary: true,
+		type: "work"
+	}];
+	const id = resource.id ?? resource._id;
+	if (id) {
+		const resourceType = mapping.schema.endsWith("User") ? "User" : "Group";
+		const meta = out.meta ?? {};
+		meta.resourceType = resourceType;
+		meta.location = `${baseUrl}/${resourceType}s/${id}`;
+		out.meta = meta;
+	}
+	return mapping.toScim ? mapping.toScim(resource, out) : out;
+}
+//#endregion
+//#region src/scim/filter.ts
+/**
+* SCIM 2.0 filter language parser (RFC 7644 §3.4.2.2)
+*
+* Translates SCIM filter expressions into arc's query DSL so existing
+* resources can serve `/scim/v2/Users?filter=...` without per-resource glue.
+*
+* Supports the subset every IdP actually emits in production:
+*   - Comparison ops: eq, ne, co, sw, ew, gt, ge, lt, le, pr (present)
+*   - Logical: and, or, not
+*   - Grouping: ( )
+*   - Attribute paths: `userName`, `name.familyName`, `emails[type eq "work"].value`
+*
+* Out of scope (yields a 400 with a clear reason):
+*   - Complex value paths beyond one level
+*   - Sub-attribute traversal in operands
+*
+* @example
+* parseScimFilter('userName eq "alice@acme.com"')
+*   → { userName: 'alice@acme.com' }
+*
+* parseScimFilter('active eq true and name.familyName sw "S"')
+*   → { $and: [{ active: true }, { 'name.familyName': { $regex: '^S' } }] }
+*/
+const COMPARISON_OPS = new Set([
+	"eq",
+	"ne",
+	"co",
+	"sw",
+	"ew",
+	"gt",
+	"ge",
+	"lt",
+	"le",
+	"pr"
+]);
+const LOGICAL_OPS = new Set([
+	"and",
+	"or",
+	"not"
+]);
+function tokenize(input) {
+	const tokens = [];
+	let i = 0;
+	while (i < input.length) {
+		const c = input[i] ?? "";
+		if (c === " " || c === "	" || c === "\n" || c === "\r") {
+			i++;
+			continue;
+		}
+		if (c === "(") {
+			tokens.push({ kind: "lparen" });
+			i++;
+			continue;
+		}
+		if (c === ")") {
+			tokens.push({ kind: "rparen" });
+			i++;
+			continue;
+		}
+		if (c === "[") {
+			tokens.push({ kind: "lbracket" });
+			i++;
+			continue;
+		}
+		if (c === "]") {
+			tokens.push({ kind: "rbracket" });
+			i++;
+			continue;
+		}
+		if (c === "\"") {
+			let j = i + 1;
+			let value = "";
+			while (j < input.length && input[j] !== "\"") if (input[j] === "\\" && j + 1 < input.length) {
+				value += input[j + 1];
+				j += 2;
+			} else {
+				value += input[j];
+				j++;
+			}
+			if (j >= input.length) throw new ScimError(400, "invalidFilter", "Unterminated string literal");
+			tokens.push({
+				kind: "string",
+				value
+			});
+			i = j + 1;
+			continue;
+		}
+		const next = input[i + 1] ?? "";
+		if (c >= "0" && c <= "9" || c === "-" && next >= "0" && next <= "9") {
+			let j = i;
+			if (input[j] === "-") j++;
+			while (j < input.length) {
+				const cj = input[j] ?? "";
+				if (!(cj >= "0" && cj <= "9" || cj === ".")) break;
+				j++;
+			}
+			const num = Number(input.slice(i, j));
+			if (Number.isNaN(num)) throw new ScimError(400, "invalidFilter", `Invalid number near "${input.slice(i, j)}"`);
+			tokens.push({
+				kind: "number",
+				value: num
+			});
+			i = j;
+			continue;
+		}
+		if (/[a-zA-Z_]/.test(c ?? "")) {
+			let j = i;
+			while (j < input.length && /[a-zA-Z0-9_.$:-]/.test(input[j] ?? "")) j++;
+			const word = input.slice(i, j);
+			const lower = word.toLowerCase();
+			if (lower === "true" || lower === "false") tokens.push({
+				kind: "bool",
+				value: lower === "true"
+			});
+			else if (lower === "null") tokens.push({ kind: "null" });
+			else if (COMPARISON_OPS.has(lower) || LOGICAL_OPS.has(lower)) tokens.push({
+				kind: "op",
+				value: lower
+			});
+			else tokens.push({
+				kind: "ident",
+				value: word
+			});
+			i = j;
+			continue;
+		}
+		throw new ScimError(400, "invalidFilter", `Unexpected character "${c}" at position ${i}`);
+	}
+	return tokens;
+}
+var Parser = class {
+	pos = 0;
+	tokens;
+	constructor(tokens) {
+		this.tokens = tokens;
+	}
+	parse() {
+		const node = this.parseOr();
+		if (this.pos < this.tokens.length) throw new ScimError(400, "invalidFilter", `Unexpected token at end of filter`);
+		return node;
+	}
+	peek() {
+		return this.tokens[this.pos];
+	}
+	consume() {
+		const t = this.tokens[this.pos++];
+		if (!t) throw new ScimError(400, "invalidFilter", "Unexpected end of filter");
+		return t;
+	}
+	parseOr() {
+		let left = this.parseAnd();
+		while (this.peek()?.kind === "op" && this.peek().value === "or") {
+			this.consume();
+			left = {
+				kind: "or",
+				left,
+				right: this.parseAnd()
+			};
+		}
+		return left;
+	}
+	parseAnd() {
+		let left = this.parseNot();
+		while (this.peek()?.kind === "op" && this.peek().value === "and") {
+			this.consume();
+			left = {
+				kind: "and",
+				left,
+				right: this.parseNot()
+			};
+		}
+		return left;
+	}
+	parseNot() {
+		if (this.peek()?.kind === "op" && this.peek().value === "not") {
+			this.consume();
+			const next = this.peek();
+			if (!next || next.kind !== "lparen") throw new ScimError(400, "invalidFilter", "Expected '(' after 'not'");
+			this.consume();
+			const child = this.parseOr();
+			if (this.consume().kind !== "rparen") throw new ScimError(400, "invalidFilter", "Expected ')' after 'not(...)'");
+			return {
+				kind: "not",
+				child
+			};
+		}
+		return this.parsePrimary();
+	}
+	parsePrimary() {
+		const t = this.peek();
+		if (!t) throw new ScimError(400, "invalidFilter", "Unexpected end of filter");
+		if (t.kind === "lparen") {
+			this.consume();
+			const inner = this.parseOr();
+			if (this.consume().kind !== "rparen") throw new ScimError(400, "invalidFilter", "Expected ')' after grouped expression");
+			return inner;
+		}
+		return this.parseComparison();
+	}
+	parseComparison() {
+		const attrTok = this.consume();
+		if (attrTok.kind !== "ident") throw new ScimError(400, "invalidFilter", "Expected attribute path");
+		let attr = attrTok.value;
+		if (this.peek()?.kind === "lbracket") {
+			this.consume();
+			let depth = 1;
+			while (depth > 0 && this.pos < this.tokens.length) {
+				const inner = this.consume();
+				if (inner.kind === "lbracket") depth++;
+				if (inner.kind === "rbracket") depth--;
+			}
+			const next = this.peek();
+			if (next?.kind === "ident" && next.value.startsWith(".")) {
+				this.consume();
+				attr += next.value;
+			}
+		}
+		const opTok = this.consume();
+		if (opTok.kind !== "op" || !COMPARISON_OPS.has(opTok.value)) throw new ScimError(400, "invalidFilter", `Expected comparison operator after "${attr}"`);
+		if (opTok.value === "pr") return {
+			kind: "present",
+			attr
+		};
+		const valTok = this.consume();
+		let value;
+		if (valTok.kind === "string") value = valTok.value;
+		else if (valTok.kind === "number") value = valTok.value;
+		else if (valTok.kind === "bool") value = valTok.value;
+		else if (valTok.kind === "null") value = null;
+		else throw new ScimError(400, "invalidFilter", `Expected literal after "${opTok.value}"`);
+		return {
+			kind: "compare",
+			attr,
+			op: opTok.value,
+			value
+		};
+	}
+};
+function escapeRegex(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function nodeToQuery(node, mapAttr) {
+	switch (node.kind) {
+		case "and": return { $and: [nodeToQuery(node.left, mapAttr), nodeToQuery(node.right, mapAttr)] };
+		case "or": return { $or: [nodeToQuery(node.left, mapAttr), nodeToQuery(node.right, mapAttr)] };
+		case "not": return { $nor: [nodeToQuery(node.child, mapAttr)] };
+		case "present": {
+			const field = mapAttr(node.attr);
+			if (!field) throw new ScimError(400, "invalidFilter", `Attribute "${node.attr}" is not filterable`);
+			return { [field]: {
+				$exists: true,
+				$ne: null
+			} };
+		}
+		case "compare": {
+			const field = mapAttr(node.attr);
+			if (!field) throw new ScimError(400, "invalidFilter", `Attribute "${node.attr}" is not filterable`);
+			switch (node.op) {
+				case "eq": return { [field]: node.value };
+				case "ne": return { [field]: { $ne: node.value } };
+				case "co":
+					if (typeof node.value !== "string") throw new ScimError(400, "invalidFilter", "'co' requires a string operand");
+					return { [field]: {
+						$regex: escapeRegex(node.value),
+						$options: "i"
+					} };
+				case "sw":
+					if (typeof node.value !== "string") throw new ScimError(400, "invalidFilter", "'sw' requires a string operand");
+					return { [field]: {
+						$regex: `^${escapeRegex(node.value)}`,
+						$options: "i"
+					} };
+				case "ew":
+					if (typeof node.value !== "string") throw new ScimError(400, "invalidFilter", "'ew' requires a string operand");
+					return { [field]: {
+						$regex: `${escapeRegex(node.value)}$`,
+						$options: "i"
+					} };
+				case "gt": return { [field]: { $gt: node.value } };
+				case "ge": return { [field]: { $gte: node.value } };
+				case "lt": return { [field]: { $lt: node.value } };
+				case "le": return { [field]: { $lte: node.value } };
+			}
+		}
+	}
+}
+/**
+* Parse a SCIM 2.0 filter expression and translate to arc/Mongo query shape.
+*
+* @param filter Raw filter string from `?filter=...`
+* @param mapAttr Mapping function: SCIM attr → backend field name. Return
+*   `undefined` to deny (yields 400 invalidFilter). Use `IDENTITY_MAP` when
+*   the resource exposes SCIM-named attributes directly.
+*/
+function parseScimFilter(filter, mapAttr) {
+	if (!filter || filter.trim().length === 0) return {};
+	return nodeToQuery(new Parser(tokenize(filter)).parse(), mapAttr);
+}
+/** Pass-through mapper for resources that already use SCIM attribute names. */
+const IDENTITY_MAP = (a) => a;
+//#endregion
+//#region src/scim/patch.ts
+/**
+* SCIM 2.0 PATCH parser (RFC 7644 §3.5.2)
+*
+* Translates SCIM PATCH operations into a flat update object the resource's
+* existing PATCH handler can apply. Supports the three operations every IdP
+* actually emits: `add`, `replace`, `remove`.
+*
+* **Path support**:
+*   - Simple attribute: `userName` → `{ userName: <value> }`
+*   - Sub-attribute: `name.familyName` → `{ 'name.familyName': <value> }`
+*   - No path (op-level value): `replace` with object value → spread into update
+*   - Multi-value with filter: `emails[type eq "work"].value` — parsed but
+*     translated to a `$set` on the matching array element by index lookup
+*     (host resolves index via the supplied `lookupArrayIndex` callback)
+*
+* @example
+* parseScimPatch({
+*   schemas: ['urn:ietf:params:scim:api:messages:2.0:PatchOp'],
+*   Operations: [
+*     { op: 'replace', path: 'displayName', value: 'Alice S.' },
+*     { op: 'add',     path: 'emails', value: [{ type: 'work', value: 'a@x.com' }] },
+*     { op: 'remove',  path: 'emails[type eq "old"]' },
+*   ],
+* })
+*   → { $set: { displayName: 'Alice S.' }, $push: { emails: ... }, $pull: { emails: ... } }
+*/
+function parseScimPatch(req) {
+	const ops = req.Operations ?? req.operations ?? [];
+	if (ops.length === 0) throw new ScimError(400, "invalidSyntax", "PATCH request must include at least one operation");
+	const out = {
+		$set: {},
+		$push: {},
+		$pull: {},
+		$unset: {}
+	};
+	for (const op of ops) {
+		const verb = (op.op ?? "").toLowerCase();
+		if (verb !== "add" && verb !== "replace" && verb !== "remove") throw new ScimError(400, "invalidSyntax", `Unsupported PATCH op "${op.op}" (allowed: add, replace, remove)`);
+		if (!op.path) {
+			if (verb === "remove") throw new ScimError(400, "noTarget", "remove operation requires a path");
+			if (op.value === void 0 || op.value === null || typeof op.value !== "object") throw new ScimError(400, "invalidValue", "Path-less add/replace must carry an object value");
+			Object.assign(out.$set, op.value);
+			continue;
+		}
+		const bracketIdx = op.path.indexOf("[");
+		if (bracketIdx >= 0) {
+			const closeBracket = op.path.indexOf("]", bracketIdx);
+			if (closeBracket < 0) throw new ScimError(400, "invalidPath", `Unterminated bracket in path "${op.path}"`);
+			const arrayField = op.path.slice(0, bracketIdx);
+			if (verb === "remove") out.$pull[arrayField] = { __scimFilter: op.path.slice(bracketIdx + 1, closeBracket) };
+			else if (verb === "add") out.$push[arrayField] = op.value;
+			else {
+				out.$pull[arrayField] = { __scimFilter: op.path.slice(bracketIdx + 1, closeBracket) };
+				out.$push[arrayField] = op.value;
+			}
+			continue;
+		}
+		if (verb === "remove") {
+			out.$unset[op.path] = true;
+			continue;
+		}
+		if (verb === "add" && Array.isArray(op.value)) {
+			out.$push[op.path] = { $each: op.value };
+			continue;
+		}
+		out.$set[op.path] = op.value;
+	}
+	return out;
+}
+/**
+* Flatten a {@link ScimUpdate} into a plain `{ field: value }` object suitable
+* for arc resource `PATCH` handlers that expect a partial document. Drops
+* `$push` / `$pull` / `$unset` semantics — use {@link parseScimPatch} directly
+* when the host needs the full op stream (e.g. to issue array mutations).
+*/
+function scimUpdateToFlatPatch(update) {
+	const out = { ...update.$set };
+	for (const k of Object.keys(update.$unset)) out[k] = null;
+	return out;
+}
+//#endregion
+//#region src/scim/routes.ts
+/**
+* Wrap a route body so every outcome (success, ScimError, unknown error)
+* funnels through one observability path. Generic over the request type so
+* Fastify's route-shape generics (`<{ Params, Body, Querystring }>`) narrow
+* `request.params` / `request.body` natively — no `as FastifyRequest & {...}`
+* casts at call sites.
+*/
+function withObserve(fastify, observe, resourceType, op, path, body) {
+	return async (request, reply) => {
+		const start = Date.now();
+		try {
+			const result = await body(request);
+			reply.code(result.status).header("Content-Type", "application/scim+json");
+			if (result.headers) for (const [k, v] of Object.entries(result.headers)) reply.header(k, v);
+			observe({
+				resourceType,
+				op,
+				status: result.status,
+				durationMs: Date.now() - start,
+				path
+			});
+			return result.payload === void 0 ? reply.send() : reply.send(result.payload);
+		} catch (err) {
+			const scim = err instanceof ScimError ? err : null;
+			observe({
+				resourceType,
+				op,
+				status: scim?.statusCode ?? 500,
+				durationMs: Date.now() - start,
+				scimType: scim?.scimType,
+				path
+			});
+			fastify.log?.warn?.({
+				err,
+				resourceType,
+				op,
+				path
+			}, "SCIM request failed");
+			return sendScimError(reply, err);
+		}
+	};
+}
+/**
+* Build a backend-shaped patch from SCIM ops, mapping SCIM attribute names
+* onto backend field names per the resource's mapping. Returns canonical
+* Mongo-style operators that flow through `findOneAndUpdate` unchanged.
+*
+* Returns `null` when the SCIM body parses but contains nothing the kit can
+* apply through the canonical contract — caller surfaces 400 in that case.
+*/
+function scimOpsToBackendOps(scimOps, attrMap) {
+	const $set = {};
+	const $unset = {};
+	const $push = {};
+	const $pull = {};
+	const map = (scimAttr) => attrMap[scimAttr] ?? scimAttr;
+	for (const [scimAttr, value] of Object.entries(scimOps.$set)) $set[map(scimAttr)] = value;
+	for (const scimAttr of Object.keys(scimOps.$unset)) $unset[map(scimAttr)] = true;
+	for (const [scimAttr, value] of Object.entries(scimOps.$push)) $push[map(scimAttr)] = value;
+	for (const [scimAttr, value] of Object.entries(scimOps.$pull)) $pull[map(scimAttr)] = value;
+	const ops = {};
+	if (Object.keys($set).length > 0) ops.$set = $set;
+	if (Object.keys($unset).length > 0) ops.$unset = $unset;
+	if (Object.keys($push).length > 0) ops.$push = $push;
+	if (Object.keys($pull).length > 0) ops.$pull = $pull;
+	return {
+		ops,
+		hasArrayOps: Object.keys($push).length > 0 || Object.keys($pull).length > 0,
+		arrayOpFields: [...Object.keys($push), ...Object.keys($pull)]
+	};
+}
+/** Pluck the id field a kit wrote on the document, accepting `id` or `_id`. */
+function extractId(doc) {
+	const raw = doc.id ?? doc._id;
+	return raw == null ? "" : String(raw);
+}
+/**
+* Mount the canonical SCIM CRUD surface for one resource type (Users /
+* Groups) under the plugin's prefix. Authentication is enforced inside
+* each handler so the observability span captures auth failures too.
+*/
+function mountResourceRoutes(fastify, resourceTypeName, mounted, authCheck, maxResults, observe) {
+	const prefix = mounted.basePath;
+	const repo = mounted.binding.resource.adapter.repository;
+	const mapping = mounted.mapping;
+	const filterMapper = (attr) => mapping.attributes[attr] ?? attr;
+	const toScim = (doc, request) => resourceToScim(asRecord(doc), mapping, `${request.protocol}://${request.hostname}${prefix}`);
+	const supportsOperators = hasFindOneAndUpdate(repo);
+	const supportsReplace = hasBulkWrite(repo);
+	const notFound = () => new ScimError(404, void 0, `${resourceTypeName.slice(0, -1)} not found`);
+	const applyPatch = supportsOperators ? async (id, p) => {
+		try {
+			return await repo.findOneAndUpdate({ id }, p.ops);
+		} catch (err) {
+			if (p.hasArrayOps) throw new ScimError(400, "invalidValue", `Array mutations ($push/$pull) on field(s) ${p.arrayOpFields.join(", ")} are not supported by this kit's repository. Use a kit with native array-column support (e.g. @classytic/mongokit), or replace the field wholesale via PUT. Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+			throw err;
+		}
+	} : async (id, p, raw) => {
+		if (Object.keys(raw.$unset).length > 0 || p.hasArrayOps) throw new ScimError(400, "invalidValue", "This kit's repository does not implement findOneAndUpdate; only $set-shaped PATCH operations are supported. Drop $unset / $push / $pull from the request, or use a kit that exposes findOneAndUpdate.");
+		const setData = p.ops.$set ?? {};
+		if (Object.keys(setData).length === 0) return repo.getById(id);
+		return repo.update(id, setData);
+	};
+	fastify.get(`${prefix}/${resourceTypeName}`, withObserve(fastify, observe, resourceTypeName, "list", `/${resourceTypeName}`, async (request) => {
+		await authCheck(request);
+		const q = request.query;
+		const startIndex = Math.max(1, Number.parseInt(q.startIndex ?? "1", 10) || 1);
+		const count = Math.min(maxResults, Number.parseInt(q.count ?? "100", 10) || 100);
+		const filters = q.filter ? parseScimFilter(q.filter, filterMapper) : {};
+		const sort = q.sortBy ? { [filterMapper(q.sortBy)]: q.sortOrder === "descending" ? -1 : 1 } : void 0;
+		const { items, total } = unwrapList(await repo.getAll({
+			filters,
+			page: Math.floor((startIndex - 1) / count) + 1,
+			limit: count,
+			sort
+		}));
+		const resources = items.map((item) => toScim(item, request));
+		return {
+			status: 200,
+			payload: {
+				schemas: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
+				totalResults: total,
+				startIndex,
+				itemsPerPage: resources.length,
+				Resources: resources
+			}
+		};
+	}));
+	fastify.get(`${prefix}/${resourceTypeName}/:id`, withObserve(fastify, observe, resourceTypeName, "get", `/${resourceTypeName}/:id`, async (request) => {
+		await authCheck(request);
+		const doc = await repo.getById(request.params.id);
+		if (!doc) throw notFound();
+		return {
+			status: 200,
+			payload: toScim(doc, request)
+		};
+	}));
+	fastify.post(`${prefix}/${resourceTypeName}`, withObserve(fastify, observe, resourceTypeName, "create", `/${resourceTypeName}`, async (request) => {
+		await authCheck(request);
+		const data = scimToResource(request.body ?? {}, mapping);
+		const created = await repo.create(data);
+		const id = extractId(asRecord(created));
+		const baseUrl = `${request.protocol}://${request.hostname}${prefix}`;
+		return {
+			status: 201,
+			payload: toScim(created, request),
+			headers: { Location: `${baseUrl}/${resourceTypeName}/${id}` }
+		};
+	}));
+	fastify.put(`${prefix}/${resourceTypeName}/:id`, withObserve(fastify, observe, resourceTypeName, "replace", `/${resourceTypeName}/:id`, async (request) => {
+		await authCheck(request);
+		if (!supportsReplace) throw new ScimError(501, void 0, "Full replacement (PUT) requires the underlying repository to expose bulkWrite([{ replaceOne }]). This kit does not implement bulkWrite. Use PATCH to apply partial updates instead.");
+		const data = scimToResource(request.body ?? {}, mapping);
+		await repo.bulkWrite([{ replaceOne: {
+			filter: { id: request.params.id },
+			replacement: data
+		} }]);
+		const updated = await repo.getById(request.params.id);
+		if (!updated) throw notFound();
+		return {
+			status: 200,
+			payload: toScim(updated, request)
+		};
+	}));
+	fastify.patch(`${prefix}/${resourceTypeName}/:id`, withObserve(fastify, observe, resourceTypeName, "patch", `/${resourceTypeName}/:id`, async (request) => {
+		await authCheck(request);
+		const scimOps = parseScimPatch(request.body);
+		const patchOps = scimOpsToBackendOps(scimOps, mapping.attributes);
+		const updated = await applyPatch(request.params.id, patchOps, scimOps);
+		if (!updated) throw notFound();
+		return {
+			status: 200,
+			payload: toScim(updated, request)
+		};
+	}));
+	fastify.delete(`${prefix}/${resourceTypeName}/:id`, withObserve(fastify, observe, resourceTypeName, "delete", `/${resourceTypeName}/:id`, async (request) => {
+		await authCheck(request);
+		await repo.delete(request.params.id);
+		return { status: 204 };
+	}));
+}
+//#endregion
+//#region src/scim/index.ts
+const scimPlugin = async (fastify, opts) => {
+	if (!opts.users) throw new Error("scimPlugin: `users` binding is required");
+	const prefix = opts.prefix ?? "/scim/v2";
+	const maxResults = opts.maxResults ?? 200;
+	const authCheck = makeAuthCheck(opts);
+	const observe = opts.observe ?? ((event) => {
+		fastify.log?.info?.({ scim: event }, "scim.request");
+	});
+	ensureScimContentTypeParser(fastify);
+	mountResourceRoutes(fastify, "Users", {
+		binding: opts.users,
+		mapping: mergeMapping(DEFAULT_USER_MAPPING, opts.users.mapping),
+		basePath: prefix
+	}, authCheck, maxResults, observe);
+	let hasGroups = false;
+	if (opts.groups) {
+		hasGroups = true;
+		mountResourceRoutes(fastify, "Groups", {
+			binding: opts.groups,
+			mapping: mergeMapping(DEFAULT_GROUP_MAPPING, opts.groups.mapping),
+			basePath: prefix
+		}, authCheck, maxResults, observe);
+	}
+	mountDiscoveryRoutes(fastify, prefix, hasGroups, authCheck, maxResults, observe);
+	fastify.log?.debug?.({
+		prefix,
+		hasGroups,
+		auth: opts.bearer ? "bearer" : "verify"
+	}, "SCIM 2.0 plugin mounted");
+};
+var scim_default = fp(scimPlugin, {
+	name: "arc-scim",
+	fastify: "5.x"
+});
+//#endregion
+export { DEFAULT_GROUP_MAPPING, DEFAULT_USER_MAPPING, IDENTITY_MAP, SCIM_ENTERPRISE_USER_SCHEMA, SCIM_GROUP_SCHEMA, SCIM_USER_SCHEMA, ScimError, scim_default as default, parseScimFilter, parseScimPatch, resourceToScim, scimPlugin, scimToResource, scimUpdateToFlatPatch };