@hammadj/better-auth-scim 1.5.0-beta.9

package/src/scim-error.ts

@@ -0,0 +1,99 @@
+import type { Status } from "better-auth";
+import { APIError } from "better-auth";
+import { statusCodes } from "better-call";
+
+/**
+ * SCIM compliant error
+ * See: https://datatracker.ietf.org/doc/html/rfc7644#section-3.12
+ */
+export class SCIMAPIError extends APIError {
+	constructor(
+		status: keyof typeof statusCodes | Status = "INTERNAL_SERVER_ERROR",
+		overrides: any = {},
+	) {
+		const body = {
+			schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+			status: (typeof status === "number"
+				? status
+				: statusCodes[status]
+			).toString(),
+			detail: overrides.detail,
+			...overrides,
+		};
+		super(status, body);
+		this.message = body.detail ?? body.message;
+	}
+}
+
+const SCIMErrorOpenAPISchema = {
+	type: "object",
+	properties: {
+		schemas: {
+			type: "array",
+			items: { type: "string" },
+		},
+		status: {
+			type: "string",
+		},
+		detail: {
+			type: "string",
+		},
+		scimType: {
+			type: "string",
+		},
+	},
+} as const;
+
+export const SCIMErrorOpenAPISchemas = {
+	"400": {
+		description:
+			"Bad Request. Usually due to missing parameters, or invalid parameters",
+		content: {
+			"application/json": {
+				schema: SCIMErrorOpenAPISchema,
+			},
+		},
+	},
+	"401": {
+		description: "Unauthorized. Due to missing or invalid authentication.",
+		content: {
+			"application/json": {
+				schema: SCIMErrorOpenAPISchema,
+			},
+		},
+	},
+	"403": {
+		description: "Unauthorized. Due to missing or invalid authentication.",
+		content: {
+			"application/json": {
+				schema: SCIMErrorOpenAPISchema,
+			},
+		},
+	},
+	"404": {
+		description: "Not Found. The requested resource was not found.",
+		content: {
+			"application/json": {
+				schema: SCIMErrorOpenAPISchema,
+			},
+		},
+	},
+	"429": {
+		description:
+			"Too Many Requests. You have exceeded the rate limit. Try again later.",
+		content: {
+			"application/json": {
+				schema: SCIMErrorOpenAPISchema,
+			},
+		},
+	},
+	"500": {
+		description:
+			"Internal Server Error. This is a problem with the server that you cannot fix.",
+		content: {
+			"application/json": {
+				schema: SCIMErrorOpenAPISchema,
+			},
+		},
+	},
+};

package/src/scim-filters.ts

@@ -0,0 +1,69 @@
+import { SCIMUserResourceSchema } from "./user-schemas";
+
+export type DBFilter = {
+	field: string;
+	value: string | string[];
+	operator?: any;
+};
+
+const SCIMOperators: Record<string, string | undefined> = {
+	eq: "eq",
+};
+
+const SCIMUserAttributes: Record<string, string | undefined> = {
+	userName: "email",
+};
+
+export class SCIMParseError extends Error {}
+
+const SCIMFilterRegex =
+	/^\s*(?<attribute>[^\s]+)\s+(?<op>eq|ne|co|sw|ew|pr)\s*(?:(?<value>"[^"]*"|[^\s]+))?\s*$/i;
+
+const parseSCIMFilter = (filter: string) => {
+	const match = filter.match(SCIMFilterRegex);
+	if (!match) {
+		throw new SCIMParseError("Invalid filter expression");
+	}
+
+	const attribute = match.groups?.attribute;
+	const op = match.groups?.op?.toLowerCase();
+	const value = match.groups?.value;
+
+	if (!attribute || !op || !value) {
+		throw new SCIMParseError("Invalid filter expression");
+	}
+
+	const operator = SCIMOperators[op];
+	if (!operator) {
+		throw new SCIMParseError(`The operator "${op}" is not supported`);
+	}
+
+	return { attribute, operator, value };
+};
+
+export const parseSCIMUserFilter = (filter: string) => {
+	const { attribute, operator, value } = parseSCIMFilter(filter);
+
+	const filters: DBFilter[] = [];
+	const targetAttribute = SCIMUserAttributes[attribute];
+	const resourceAttribute = SCIMUserResourceSchema.attributes.find(
+		(attr) => attr.name === attribute,
+	);
+
+	if (!targetAttribute || !resourceAttribute) {
+		throw new SCIMParseError(`The attribute "${attribute}" is not supported`);
+	}
+
+	let finalValue = value.replaceAll('"', "");
+	if (!resourceAttribute.caseExact) {
+		finalValue = finalValue.toLowerCase();
+	}
+
+	filters.push({
+		field: targetAttribute,
+		value: finalValue,
+		operator,
+	});
+
+	return filters;
+};

package/src/scim-metadata.ts

@@ -0,0 +1,128 @@
+const MetadataFieldSupportOpenAPISchema = {
+	type: "object",
+	properties: {
+		supported: {
+			type: "boolean",
+		},
+	},
+};
+
+export const ServiceProviderOpenAPISchema = {
+	type: "object",
+	properties: {
+		patch: MetadataFieldSupportOpenAPISchema,
+		bulk: MetadataFieldSupportOpenAPISchema,
+		filter: MetadataFieldSupportOpenAPISchema,
+		changePassword: MetadataFieldSupportOpenAPISchema,
+		sort: MetadataFieldSupportOpenAPISchema,
+		etag: MetadataFieldSupportOpenAPISchema,
+		authenticationSchemes: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					name: {
+						type: "string",
+					},
+					description: {
+						type: "string",
+					},
+					specUri: {
+						type: "string",
+					},
+					type: {
+						type: "string",
+					},
+					primary: {
+						type: "boolean",
+					},
+				},
+			},
+		},
+		schemas: {
+			type: "array",
+			items: {
+				type: "string",
+			},
+		},
+		meta: {
+			type: "object",
+			properties: {
+				resourceType: {
+					type: "string",
+				},
+			},
+		},
+	},
+} as const;
+
+export const ResourceTypeOpenAPISchema = {
+	type: "object",
+	properties: {
+		schemas: {
+			type: "array",
+			items: { type: "string" },
+		},
+		id: { type: "string" },
+		name: { type: "string" },
+		endpoint: { type: "string" },
+		description: { type: "string" },
+		schema: { type: "string" },
+		meta: {
+			type: "object",
+			properties: {
+				resourceType: { type: "string" },
+				location: { type: "string" },
+			},
+		},
+	},
+} as const;
+
+const SCIMSchemaAttributesOpenAPISchema = {
+	type: "object",
+	properties: {
+		name: { type: "string" },
+		type: { type: "string" },
+		multiValued: { type: "boolean" },
+		description: { type: "string" },
+		required: { type: "boolean" },
+		caseExact: { type: "boolean" },
+		mutability: { type: "string" },
+		returned: { type: "string" },
+		uniqueness: { type: "string" },
+	},
+} as const;
+
+export const SCIMSchemaOpenAPISchema = {
+	type: "object",
+	properties: {
+		id: { type: "string" },
+		schemas: {
+			type: "array",
+			items: { type: "string" },
+		},
+		name: { type: "string" },
+		description: { type: "string" },
+		attributes: {
+			type: "array",
+			items: {
+				...SCIMSchemaAttributesOpenAPISchema,
+				properties: {
+					...SCIMSchemaAttributesOpenAPISchema.properties,
+					subAttributes: {
+						type: "array",
+						items: SCIMSchemaAttributesOpenAPISchema,
+					},
+				},
+			},
+		},
+		meta: {
+			type: "object",
+			properties: {
+				resourceType: { type: "string" },
+				location: { type: "string" },
+			},
+			required: ["resourceType", "location"],
+		},
+	},
+} as const;

package/src/scim-resources.ts

@@ -0,0 +1,35 @@
+import type { Account, User } from "better-auth";
+import { SCIMUserResourceSchema } from "./user-schemas";
+import { getResourceURL } from "./utils";
+
+export const createUserResource = (
+	baseURL: string,
+	user: User,
+	account?: Account | null,
+) => {
+	return {
+		// Common attributes
+		// See https://datatracker.ietf.org/doc/html/rfc7643#section-3.1
+
+		id: user.id,
+		externalId: account?.accountId,
+		meta: {
+			resourceType: "User",
+			created: user.createdAt,
+			lastModified: user.updatedAt,
+			location: getResourceURL(`/scim/v2/Users/${user.id}`, baseURL),
+		},
+
+		// SCIM user resource
+		// See https://datatracker.ietf.org/doc/html/rfc7643#section-4.1
+
+		userName: user.email,
+		name: {
+			formatted: user.name,
+		},
+		displayName: user.name,
+		active: true,
+		emails: [{ primary: true, value: user.email }],
+		schemas: [SCIMUserResourceSchema.id],
+	};
+};

package/src/scim-tokens.ts

@@ -0,0 +1,71 @@
+import type { GenericEndpointContext } from "better-auth";
+import { symmetricDecrypt, symmetricEncrypt } from "better-auth/crypto";
+import { defaultKeyHasher } from "better-auth/plugins";
+import type { SCIMOptions } from "./types";
+
+export async function storeSCIMToken(
+	ctx: GenericEndpointContext,
+	opts: SCIMOptions,
+	scimToken: string,
+) {
+	if (opts.storeSCIMToken === "encrypted") {
+		return await symmetricEncrypt({
+			key: ctx.context.secret,
+			data: scimToken,
+		});
+	}
+	if (opts.storeSCIMToken === "hashed") {
+		return await defaultKeyHasher(scimToken);
+	}
+	if (
+		typeof opts.storeSCIMToken === "object" &&
+		"hash" in opts.storeSCIMToken
+	) {
+		return await opts.storeSCIMToken.hash(scimToken);
+	}
+	if (
+		typeof opts.storeSCIMToken === "object" &&
+		"encrypt" in opts.storeSCIMToken
+	) {
+		return await opts.storeSCIMToken.encrypt(scimToken);
+	}
+
+	return scimToken;
+}
+
+export async function verifySCIMToken(
+	ctx: GenericEndpointContext,
+	opts: SCIMOptions,
+	storedSCIMToken: string,
+	scimToken: string,
+): Promise<boolean> {
+	if (opts.storeSCIMToken === "encrypted") {
+		return (
+			(await symmetricDecrypt({
+				key: ctx.context.secret,
+				data: storedSCIMToken,
+			})) === scimToken
+		);
+	}
+	if (opts.storeSCIMToken === "hashed") {
+		const hashedSCIMToken = await defaultKeyHasher(scimToken);
+		return hashedSCIMToken === storedSCIMToken;
+	}
+	if (
+		typeof opts.storeSCIMToken === "object" &&
+		"hash" in opts.storeSCIMToken
+	) {
+		const hashedSCIMToken = await opts.storeSCIMToken.hash(scimToken);
+		return hashedSCIMToken === storedSCIMToken;
+	}
+	if (
+		typeof opts.storeSCIMToken === "object" &&
+		"decrypt" in opts.storeSCIMToken
+	) {
+		const decryptedSCIMToken =
+			await opts.storeSCIMToken.decrypt(storedSCIMToken);
+		return decryptedSCIMToken === scimToken;
+	}
+
+	return scimToken === storedSCIMToken;
+}