@estifanos-sh/convex-auth 0.0.1-preview.0

package/dist/server/connection/provision.js

@@ -0,0 +1,182 @@
+import { ErrorCode } from "../../shared/codes.js";
+import { convexError } from "../errors.js";
+import { getGroupConnection, getScimConfigByConnection, getScimConfigByTokenHash, getScimIdentity, upsertScimConfig, upsertScimIdentity } from "../contract.js";
+
+//#region src/server/connection/provision.ts
+function getScimConfigShape(scimConfig) {
+	return typeof scimConfig?.extend === "object" && scimConfig.extend !== null ? scimConfig.extend : {};
+}
+function getPublicScimConfig(scimConfig) {
+	if (!scimConfig) return null;
+	const { tokenHash, ...rest } = scimConfig;
+	return {
+		...rest,
+		hasToken: typeof tokenHash === "string" && tokenHash.length > 0
+	};
+}
+function createGroupScimDomain(deps) {
+	const { config, requireEnv, generateRandomString, INVITE_TOKEN_ALPHABET, sha256, loadGroupPolicyOrThrow, emitGroupAuthEvent } = deps;
+	const getScimBasePath = (connectionId) => `${requireEnv("CONVEX_SITE_URL")}/connections/${connectionId}/scim/v2`;
+	const validateScim = async (ctx, connectionId) => {
+		const checks = [];
+		const connection = await getGroupConnection(ctx, config.component.connection, connectionId);
+		if (!connection) return {
+			ok: false,
+			connectionId,
+			checks: [{
+				name: "group_connection_exists",
+				ok: false,
+				message: "Connection not found."
+			}]
+		};
+		const policy = await loadGroupPolicyOrThrow(ctx, connection.groupId);
+		const scimConfig = await getScimConfigByConnection(ctx, config.component.connection, connectionId);
+		const hasConfig = scimConfig !== null && scimConfig !== void 0;
+		checks.push({
+			name: "scim_config_exists",
+			ok: hasConfig,
+			message: hasConfig ? void 0 : "SCIM has not been configured."
+		});
+		const isActive = scimConfig?.status === "active";
+		checks.push({
+			name: "scim_config_active",
+			ok: isActive,
+			message: isActive ? void 0 : `SCIM config status is ${hasConfig ? scimConfig?.status : "unknown"}.`
+		});
+		const hasToken = typeof scimConfig?.tokenHash === "string" && scimConfig.tokenHash.length > 0;
+		checks.push({
+			name: "token_hash_set",
+			ok: hasToken,
+			message: hasToken ? void 0 : "SCIM bearer token has not been set."
+		});
+		const hasBasePath = typeof scimConfig?.basePath === "string" && scimConfig.basePath === getScimBasePath(connection._id);
+		checks.push({
+			name: "base_path_matches_route",
+			ok: hasBasePath,
+			message: hasBasePath ? void 0 : "SCIM basePath does not match the derived route."
+		});
+		const supportsIdempotentExternalId = policy.provisioning.scimReuse.user === "externalId";
+		checks.push({
+			name: "user_external_id_reuse_enabled",
+			ok: supportsIdempotentExternalId,
+			message: supportsIdempotentExternalId ? void 0 : "SCIM user retry-safe provisioning works best with scimReuse.user = externalId."
+		});
+		checks.push({
+			name: "filter_subset_supported",
+			ok: true,
+			message: "Supported filters: eq, co, sw, ew, pr on common user/group fields."
+		});
+		checks.push({
+			name: "protocol_capabilities_declared",
+			ok: true
+		});
+		return {
+			ok: checks.every((c) => c.ok),
+			connectionId: connection._id,
+			basePath: getScimBasePath(connection._id),
+			deprovisionMode: policy.provisioning.deprovision.mode,
+			capabilities: {
+				users: true,
+				groups: true,
+				patch: true,
+				put: true,
+				filters: [
+					"eq",
+					"co",
+					"sw",
+					"ew",
+					"pr"
+				],
+				bulk: false,
+				etag: false
+			},
+			checks
+		};
+	};
+	return {
+		upsert: async (ctx, data) => {
+			const connection = await getGroupConnection(ctx, config.component.connection, data.connectionId);
+			if (connection === null) throw convexError(ErrorCode.INVALID_PARAMETERS, "Connection not found.");
+			const rawToken = generateRandomString(48, INVITE_TOKEN_ALPHABET);
+			const tokenHash = await sha256(rawToken);
+			const basePath = getScimBasePath(connection._id);
+			const configId = await upsertScimConfig(ctx, config.component.connection, {
+				connectionId: connection._id,
+				groupId: connection.groupId,
+				status: data.status ?? "active",
+				basePath,
+				tokenHash,
+				lastRotatedAt: Date.now(),
+				extend: {
+					security: data.security,
+					profile: data.profile
+				}
+			});
+			await emitGroupAuthEvent(ctx, {
+				connectionId: connection._id,
+				groupId: connection.groupId,
+				kind: "connection.scim.set",
+				actor: { type: "system" },
+				subject: {
+					type: "connection",
+					id: connection._id
+				},
+				data: { scimConfigId: configId },
+				webhook: { payload: {
+					connectionId: connection._id,
+					scimConfigId: configId
+				} }
+			});
+			return {
+				connectionId: connection._id,
+				configId,
+				basePath,
+				token: rawToken
+			};
+		},
+		get: async (ctx, args) => {
+			const scimConfig = await getScimConfigByConnection(ctx, config.component.connection, args.connectionId);
+			if (!scimConfig) return null;
+			const shape = getScimConfigShape(scimConfig);
+			return {
+				...getPublicScimConfig(scimConfig),
+				security: shape.security,
+				profile: shape.profile
+			};
+		},
+		status: async (ctx, args) => {
+			const { connectionId } = args;
+			const currentConfig = await getScimConfigByConnection(ctx, config.component.connection, connectionId);
+			const result = await validateScim(ctx, connectionId);
+			return {
+				connectionId,
+				configured: currentConfig?.status !== void 0,
+				ready: result.ok,
+				config: getPublicScimConfig(currentConfig),
+				checks: result.checks,
+				capabilities: "capabilities" in result ? result.capabilities : void 0
+			};
+		},
+		getConfigByToken: async (ctx, args) => {
+			return await getScimConfigByTokenHash(ctx, config.component.connection, await sha256(args.token));
+		},
+		validate: async (ctx, args) => {
+			return await validateScim(ctx, args.connectionId);
+		},
+		identity: {
+			get: async (ctx, data) => {
+				return await getScimIdentity(ctx, config.component.connection, data);
+			},
+			upsert: async (ctx, data) => {
+				return await upsertScimIdentity(ctx, config.component.connection, {
+					...data,
+					lastProvisionedAt: Date.now()
+				});
+			}
+		}
+	};
+}
+
+//#endregion
+export { createGroupScimDomain };
+//# sourceMappingURL=provision.js.map

package/dist/server/connection/saml/api.js

@@ -0,0 +1,70 @@
+import { DOMParser } from "@xmldom/xmldom";
+
+//#region src/server/connection/saml/api.ts
+/**
+* Resolve a DOMParser constructor: the platform global if present, else xmldom's.
+* xmldom implements the standard DOM interfaces but its declared types don't unify
+* with the global ones, so its constructor is bridged to {@link DomParserCtor}
+* through the single typed assertion at that cross-package boundary.
+*/
+function loadDomParserCtor() {
+	const globalParser = globalThis.DOMParser;
+	if (typeof globalParser === "function") return globalParser;
+	if (typeof DOMParser === "function") return DOMParser;
+	throw new Error("ERR_DOM_PARSER_NOT_AVAILABLE");
+}
+const DOCTYPE_OR_ENTITY = /<!\s*(DOCTYPE|ENTITY)\b/i;
+function rejectDoctypeOrEntity(xml) {
+	if (DOCTYPE_OR_ENTITY.test(xml)) throw new Error("ERR_XML_DOCTYPE_OR_ENTITY_FORBIDDEN");
+}
+function createDOMParser(options = {}) {
+	const parser = new (loadDomParserCtor())(options);
+	return { parseFromString: (xml, mimeType = "text/xml") => {
+		rejectDoctypeOrEntity(xml);
+		return parser.parseFromString(xml, mimeType);
+	} };
+}
+const context = {
+	validate: void 0,
+	dom: void 0,
+	readFile: void 0,
+	writeFile: void 0
+};
+/** Return the shared module context, lazily initializing a safe DOM parser. */
+function getContext() {
+	if (context.dom === void 0) context.dom = createDOMParser();
+	return context;
+}
+/**
+* Parse XML through the configured DOMParser, with DOCTYPE/ENTITY rejection.
+* Use this for any XML coming from a network peer (IdP responses, signed
+* payloads, encrypted assertions) instead of constructing a `DOMParser`
+* directly — direct construction bypasses the doctype/entity guard.
+*/
+function safeParseXml(xml, mimeType = "text/xml") {
+	const { dom } = getContext();
+	return dom.parseFromString(xml, mimeType);
+}
+/** Register the XML schema validation callback used by {@link safeParseXml} consumers. */
+function setSchemaValidator(params) {
+	if (typeof params.validate !== "function") throw new Error("validate must be a callback function having one argument as xml input");
+	context.validate = params.validate;
+}
+/**
+* Check if the xml string is valid and bounded.
+*
+* Security: a validator must be registered (see {@link setSchemaValidator}).
+* A user may supply a validate function that always resolves to deliberately
+* skip validation, but then takes responsibility for the resulting exposure;
+* when no validator is registered this rejects rather than passing untrusted
+* XML through unchecked.
+*/
+async function isValidXml(input) {
+	const { validate } = getContext();
+	if (!validate) return Promise.reject("XML validation was requested but no validator is registered; refusing to process untrusted XML without validation. Register a schema validator before validating XML.");
+	return await validate(input);
+}
+
+//#endregion
+export { getContext, isValidXml, safeParseXml, setSchemaValidator };
+//# sourceMappingURL=api.js.map

package/dist/server/connection/saml/binding/post.js

@@ -0,0 +1,140 @@
+import { SAML_STATUS_SUCCESS } from "../constants.js";
+import { base64Encode, get } from "../encoding.js";
+import { constructSamlSignature } from "../signature.js";
+import { defaultLoginRequestTemplate, defaultLogoutResponseTemplate, replaceTagsByValue } from "../template.js";
+import { getBindingField } from "./shared.js";
+
+//#region src/server/connection/saml/binding/post.ts
+/**
+* Binding-level API for functions using POST binding.
+*/
+/**
+* Assemble the signing config from entity settings. The IdP signing path always
+* carries a configured `privateKey` and algorithm, and the signing certificate
+* resolves to a single PEM string. The signer declares these as `string` /
+* `string | Uint8Array`; the boundary casts narrow the optional `BinaryLike`
+* settings and the `string | string[] | null` certificate return to those
+* established types with no runtime change.
+*/
+function buildSignatureConfig(privateKey, privateKeyPass, signatureAlgorithm, signingCert) {
+	return {
+		privateKey,
+		privateKeyPass,
+		signatureAlgorithm,
+		signingCert,
+		isBase64Output: false
+	};
+}
+/** Generate a base64-encoded login request for the POST binding. */
+async function base64LoginRequest(referenceTagXPath, entity, customTagReplacement) {
+	const metadata = {
+		idp: entity.idp.entityMeta,
+		sp: entity.sp.entityMeta
+	};
+	const spSetting = entity.sp.entitySetting;
+	let id = "";
+	if (metadata && metadata.idp && metadata.sp) {
+		const base = metadata.idp.getSingleSignOnService("post");
+		let rawSamlRequest;
+		if (spSetting.loginRequestTemplate && customTagReplacement) {
+			const info = customTagReplacement(spSetting.loginRequestTemplate.context);
+			id = getBindingField(info, "id");
+			rawSamlRequest = getBindingField(info, "context");
+		} else {
+			const nameIDFormat = spSetting.nameIDFormat;
+			const selectedNameIDFormat = Array.isArray(nameIDFormat) ? nameIDFormat[0] : nameIDFormat;
+			id = spSetting.generateID();
+			rawSamlRequest = replaceTagsByValue(defaultLoginRequestTemplate.context, {
+				ID: id,
+				Destination: base,
+				Issuer: metadata.sp.getEntityID(),
+				IssueInstant: (/* @__PURE__ */ new Date()).toISOString(),
+				AssertionConsumerServiceURL: metadata.sp.getAssertionConsumerService("post"),
+				EntityID: metadata.sp.getEntityID(),
+				AllowCreate: spSetting.allowCreate,
+				NameIDFormat: selectedNameIDFormat
+			});
+		}
+		if (metadata.idp.isWantAuthnRequestsSigned()) {
+			const { privateKey, privateKeyPass, requestSignatureAlgorithm: signatureAlgorithm, transformationAlgorithms } = spSetting;
+			return {
+				id,
+				context: await constructSamlSignature({
+					...buildSignatureConfig(privateKey, privateKeyPass, signatureAlgorithm, metadata.sp.getX509Certificate("signing")),
+					referenceTagXPath,
+					transformationAlgorithms,
+					rawSamlMessage: rawSamlRequest,
+					signatureConfig: spSetting.signatureConfig || {
+						prefix: "ds",
+						location: {
+							reference: "/*[local-name(.)='AuthnRequest']/*[local-name(.)='Issuer']",
+							action: "after"
+						}
+					}
+				})
+			};
+		}
+		return {
+			id,
+			context: base64Encode(rawSamlRequest)
+		};
+	}
+	throw new Error("ERR_GENERATE_POST_LOGIN_REQUEST_MISSING_METADATA");
+}
+/** Generate a base64-encoded logout response for the POST binding. */
+async function base64LogoutResponse(requestInfo, entity, customTagReplacement) {
+	const metadata = {
+		init: entity.init.entityMeta,
+		target: entity.target.entityMeta
+	};
+	let id = "";
+	const initSetting = entity.init.entitySetting;
+	if (metadata && metadata.init && metadata.target) {
+		let rawSamlResponse;
+		if (initSetting.logoutResponseTemplate) {
+			const template = customTagReplacement(initSetting.logoutResponseTemplate.context);
+			id = template.id;
+			rawSamlResponse = template.context;
+		} else {
+			id = initSetting.generateID();
+			const tvalue = {
+				ID: id,
+				Destination: metadata.target.getSingleLogoutService("post"),
+				EntityID: metadata.init.getEntityID(),
+				Issuer: metadata.init.getEntityID(),
+				IssueInstant: (/* @__PURE__ */ new Date()).toISOString(),
+				StatusCode: SAML_STATUS_SUCCESS,
+				InResponseTo: get(requestInfo, "extract.request.id", null)
+			};
+			rawSamlResponse = replaceTagsByValue(defaultLogoutResponseTemplate.context, tvalue);
+		}
+		if (entity.target.entitySetting.wantLogoutResponseSigned) {
+			const { privateKey, privateKeyPass, requestSignatureAlgorithm: signatureAlgorithm, transformationAlgorithms } = initSetting;
+			return {
+				id,
+				context: await constructSamlSignature({
+					...buildSignatureConfig(privateKey, privateKeyPass, signatureAlgorithm, metadata.init.getX509Certificate("signing")),
+					isMessageSigned: true,
+					transformationAlgorithms,
+					rawSamlMessage: rawSamlResponse,
+					signatureConfig: {
+						prefix: "ds",
+						location: {
+							reference: "/*[local-name(.)='LogoutResponse']/*[local-name(.)='Issuer']",
+							action: "after"
+						}
+					}
+				})
+			};
+		}
+		return {
+			id,
+			context: base64Encode(rawSamlResponse)
+		};
+	}
+	throw new Error("ERR_GENERATE_POST_LOGOUT_RESPONSE_MISSING_METADATA");
+}
+
+//#endregion
+export { base64LoginRequest, base64LogoutResponse };
+//# sourceMappingURL=post.js.map

package/dist/server/connection/saml/binding/redirect.js

@@ -0,0 +1,139 @@
+import { SAML_STATUS_SUCCESS, SamlQueryParam } from "../constants.js";
+import { base64Encode, deflateString } from "../encoding.js";
+import { constructMessageSignature } from "../signature.js";
+import { defaultLoginRequestTemplate, defaultLogoutResponseTemplate, getQueryParamByType, replaceTagsByValue } from "../template.js";
+import { getBindingField } from "./shared.js";
+
+//#region src/server/connection/saml/binding/redirect.ts
+/**
+* Binding-level API for functions using Redirect binding.
+*/
+/**
+* View the extractor's genuinely-open {@link ExtractedProperties} through the
+* concrete request shape these response/logout builders read. The extract is
+* dynamically assembled from inbound XML, so this is the single dynamic-shape
+* boundary where the open record is narrowed to {@link ParsedRequestExtract}.
+*/
+function asParsedRequest(extract) {
+	return extract;
+}
+function pvPair(param, value, first) {
+	return (first === true ? "?" : "&") + param + "=" + value;
+}
+function hasNoQuery(baseUrl) {
+	const queryIndex = baseUrl.indexOf("?");
+	if (queryIndex < 0) return true;
+	return queryIndex === baseUrl.length - 1;
+}
+/** Build the redirect-binding URL, optionally appending a query-string signature. */
+async function buildRedirectURL(opts) {
+	const { baseUrl, type, isSigned, context, entitySetting } = opts;
+	let { relayState = "" } = opts;
+	const noParams = hasNoQuery(baseUrl);
+	const queryParam = getQueryParamByType(type);
+	const samlRequest = encodeURIComponent(base64Encode(deflateString(context)));
+	if (relayState !== "") relayState = pvPair(SamlQueryParam.relayState, encodeURIComponent(relayState));
+	if (isSigned) {
+		/**
+		* The signed redirect path always runs with a configured algorithm and key
+		* (the entity defaults supply `requestSignatureAlgorithm`, and a signed
+		* request requires `privateKey`); the signer also declares `privateKey` as
+		* `string`. These two boundary casts narrow the optional/`BinaryLike`
+		* settings to what the signer consumes without runtime change.
+		*/
+		const sigAlg = pvPair(SamlQueryParam.sigAlg, encodeURIComponent(entitySetting.requestSignatureAlgorithm));
+		const octetString = samlRequest + relayState + sigAlg;
+		const signature = await constructMessageSignature(queryParam + "=" + octetString, entitySetting.privateKey, entitySetting.privateKeyPass, void 0, entitySetting.requestSignatureAlgorithm);
+		return baseUrl + pvPair(queryParam, octetString, noParams) + pvPair(SamlQueryParam.signature, encodeURIComponent(signature.toString()));
+	}
+	return baseUrl + pvPair(queryParam, samlRequest + relayState, noParams);
+}
+/** Build the redirect-binding URL for a login request. */
+async function loginRequestRedirectURL(entity, customTagReplacement) {
+	const metadata = {
+		idp: entity.idp.entityMeta,
+		sp: entity.sp.entityMeta
+	};
+	const spSetting = entity.sp.entitySetting;
+	let id = "";
+	if (metadata && metadata.idp && metadata.sp) {
+		const base = metadata.idp.getSingleSignOnService("redirect");
+		let rawSamlRequest;
+		if (spSetting.loginRequestTemplate && customTagReplacement) {
+			const info = customTagReplacement(spSetting.loginRequestTemplate);
+			id = getBindingField(info, "id");
+			rawSamlRequest = getBindingField(info, "context");
+		} else {
+			const nameIDFormat = spSetting.nameIDFormat;
+			const selectedNameIDFormat = Array.isArray(nameIDFormat) ? nameIDFormat[0] : nameIDFormat;
+			id = spSetting.generateID();
+			rawSamlRequest = replaceTagsByValue(defaultLoginRequestTemplate.context, {
+				ID: id,
+				Destination: base,
+				Issuer: metadata.sp.getEntityID(),
+				IssueInstant: (/* @__PURE__ */ new Date()).toISOString(),
+				NameIDFormat: selectedNameIDFormat,
+				AssertionConsumerServiceURL: metadata.sp.getAssertionConsumerService("post"),
+				EntityID: metadata.sp.getEntityID(),
+				AllowCreate: spSetting.allowCreate
+			});
+		}
+		return {
+			id,
+			context: await buildRedirectURL({
+				context: rawSamlRequest,
+				type: "SAMLRequest",
+				isSigned: metadata.sp.isAuthnRequestSigned(),
+				entitySetting: spSetting,
+				baseUrl: base,
+				relayState: spSetting.relayState
+			})
+		};
+	}
+	throw new Error("ERR_GENERATE_REDIRECT_LOGIN_REQUEST_MISSING_METADATA");
+}
+/** Build the redirect-binding URL for a logout response. */
+async function logoutResponseRedirectURL(requestInfo, entity, relayState, customTagReplacement) {
+	const metadata = {
+		init: entity.init.entityMeta,
+		target: entity.target.entityMeta
+	};
+	const initSetting = entity.init.entitySetting;
+	let id = initSetting.generateID();
+	if (metadata && metadata.init && metadata.target) {
+		const base = metadata.target.getSingleLogoutService("redirect");
+		let rawSamlResponse;
+		if (initSetting.logoutResponseTemplate && customTagReplacement) {
+			const template = customTagReplacement(initSetting.logoutResponseTemplate);
+			id = getBindingField(template, "id");
+			rawSamlResponse = getBindingField(template, "context");
+		} else {
+			const tvalue = {
+				ID: id,
+				Destination: base,
+				Issuer: metadata.init.getEntityID(),
+				EntityID: metadata.init.getEntityID(),
+				IssueInstant: (/* @__PURE__ */ new Date()).toISOString(),
+				StatusCode: SAML_STATUS_SUCCESS
+			};
+			if (requestInfo && requestInfo.extract && asParsedRequest(requestInfo.extract).request) tvalue.InResponseTo = asParsedRequest(requestInfo.extract).request.id;
+			rawSamlResponse = replaceTagsByValue(defaultLogoutResponseTemplate.context, tvalue);
+		}
+		return {
+			id,
+			context: await buildRedirectURL({
+				baseUrl: base,
+				type: "LogoutResponse",
+				isSigned: entity.target.entitySetting.wantLogoutResponseSigned,
+				context: rawSamlResponse,
+				entitySetting: initSetting,
+				relayState
+			})
+		};
+	}
+	throw new Error("ERR_GENERATE_REDIRECT_LOGOUT_RESPONSE_MISSING_METADATA");
+}
+
+//#endregion
+export { loginRequestRedirectURL, logoutResponseRedirectURL };
+//# sourceMappingURL=redirect.js.map

package/dist/server/connection/saml/binding/shared.js

@@ -0,0 +1,18 @@
+import { get } from "../encoding.js";
+
+//#region src/server/connection/saml/binding/shared.ts
+/**
+* Helpers and entity types shared by the redirect and POST binding builders.
+*/
+/**
+* `get` performs lodash-style traversal and returns `unknown`; a custom-tag
+* replacement yields a {@link BindingContext}, so `id`/`context` are strings.
+* The single boundary cast preserves `get`'s truthy-or-null runtime semantics.
+*/
+function getBindingField(source, field) {
+	return get(source, field, null);
+}
+
+//#endregion
+export { getBindingField };
+//# sourceMappingURL=shared.js.map