@protobase/server 0.21.8 → 0.21.10

package/dist/better-auth/create-auth.js

@@ -1,5 +1,6 @@
 import { multiHostBaseURL, readOrigins, resolveOrigins } from "./origins.js";
 import { defaultAppName, readAppName } from "../app-name.js";
+import { authBasePath } from "./auth-base-path.js";
 import { platformMailer } from "../mail/platform-mailer.js";
 import { readOperatorSettings, resolveOperator } from "./operator-provider.js";
 import { roleDefinitions } from "./organizations/role-definitions.js";
@@ -15,6 +16,7 @@ import { narrowClaims } from "./roles/active-role.js";
 import { rolesPlugin } from "./roles/roles-plugin.js";
 import { platformSignInFor, platformSignInProvider, readPlatformSignIn, resolvePlatformSignIn } from "./platform-sign-in.js";
 import { signInPolicyPlugin } from "./policy-plugin.js";
+import { emailInDomains, resolveSamlProviders, samlDisabledPaths, samlGuardPlugin, samlPlugin } from "./saml-sign-in.js";
 import { emailCodeOptions, twoFactorCodeOptions, unusedEmailCodePaths } from "./sign-in-mail.js";
 import { signUpPaths, signUpPlugin } from "./sign-up/sign-up-plugin.js";
 import { staffSignInPlugin } from "./staff-plugin.js";
@@ -30,7 +32,6 @@ const platformOrigins = () => readOrigins(globalThis.process?.env ?? {});
 const platformPasskeyDomain = () => readPasskeyDomain(globalThis.process?.env ?? {});
 const platformAppName = () => readAppName(globalThis.process?.env ?? {});
 const tokenLifetime = "15m";
-const authBasePath = "/api/auth";
 /**
 * Better Auth for a single-tenant admin: sign-in with a password, an emailed code or a passkey, two-factor
 * authentication, and the sign-in policy admins set; no public sign-up unless `signUp` turns it on (every account is
@@ -46,7 +47,7 @@ const organizationPaths = ["/organization/set-active", "/organization/accept-inv
 * The options `createAuth` gives Better Auth, with the roles, default role, mailer, operator provider and platform
 * sign-in provider already resolved.
 */
-const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, definitions, defaultRole, appName = defaultAppName, mailer, signUpRole, operator, platformSignIn, organizations, context = noContext }) => {
+const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, definitions, defaultRole, appName = defaultAppName, mailer, signUpRole, operator, platformSignIn, saml = [], organizations, context = noContext }) => {
 	const secure = options.baseURL.startsWith("https://");
 	const signIn = platformSignInFor(platformSignIn, Object.keys(options.socialProviders ?? {}));
 	const hosts = passkeyHosts([options.baseURL, ...origins]);
@@ -55,6 +56,7 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 		appName,
 		baseURL: options.baseURL
 	};
+	const samlIds = saml.map((provider) => provider.id);
 	return {
 		appName,
 		database: options.database,
@@ -126,9 +128,10 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 				mail
 			})] : [],
 			...signIn ? [genericOAuth({ config: [platformSignInProvider(signIn)] })] : [],
+			...saml.length > 0 ? [samlPlugin(saml, options.baseURL), samlGuardPlugin(samlIds)] : [],
 			signInPolicyPlugin({
 				mail: Boolean(mailer),
-				socialProviders: Object.keys(options.socialProviders ?? {}),
+				socialProviders: [...Object.keys(options.socialProviders ?? {}), ...samlIds],
 				...operator && { operator: operator.name },
 				...signIn && { platformSignIn: {
 					provider: signIn.provider,
@@ -153,7 +156,8 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 		disabledPaths: [
 			...unusedEmailCodePaths,
 			...adminImpersonationPaths,
-			...organizations ? organizationPaths : []
+			...organizations ? organizationPaths : [],
+			...saml.length > 0 ? samlDisabledPaths : []
 		],
 		databaseHooks: {
 			user: { create: {
@@ -161,11 +165,16 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 					const given = String(user.role ?? "").split(",").map((name) => name.trim()).filter(Boolean);
 					const unknown = given.find((name) => !roles.includes(name));
 					if (given.length === 0 || unknown !== void 0) throw new APIError("BAD_REQUEST", { message: `Choose a role for the new user: ${roles.join(", ")}` });
+					const samlProvider = context?.path === "/sso/saml2/sp/acs/:providerId" ? saml.find((provider) => provider.id === context.params?.providerId) : void 0;
+					if (samlProvider && !emailInDomains(user.email, samlProvider.domains)) throw new APIError("FORBIDDEN", {
+						code: "EMAIL_DOMAIN_NOT_ALLOWED",
+						message: "This address is not one the identity provider may sign up."
+					});
 					const withId = options.generateUserId ? {
 						...user,
 						id: await options.generateUserId()
 					} : user;
-					return { data: context?.path === "/admin/create-user" ? {
+					return { data: context?.path === "/admin/create-user" || samlProvider ? {
 						...withId,
 						emailVerified: true
 					} : withId };
@@ -235,6 +244,7 @@ const createAuth = (options) => {
 	const signInSettings = options.signInProvider === void 0 ? platformSignInSettings() : options.signInProvider || void 0;
 	const socialProviders = Object.keys(options.socialProviders ?? {});
 	const platformSignIn = platformSignInFor(signInSettings && resolvePlatformSignIn(signInSettings), socialProviders);
+	const saml = resolveSamlProviders(options.sso?.saml ?? [], [...socialProviders, ...platformSignIn ? [platformSignIn.provider] : []]);
 	const origins = resolveOrigins(options.baseURL, options.origins ?? platformOrigins());
 	const passkeyDomain = resolvePasskeyDomain(options.passkeyDomain ?? platformPasskeyDomain(), [options.baseURL, ...origins]);
 	const organizations = options.organizations && resolveOrganizations(options.organizations, definitions, options.baseURL);
@@ -251,6 +261,7 @@ const createAuth = (options) => {
 		signUpRole,
 		operator,
 		platformSignIn,
+		saml,
 		...organizations && {
 			organizations,
 			context
@@ -281,7 +292,12 @@ const createAuth = (options) => {
 		platformSignIn: platformSignIn && {
 			provider: platformSignIn.provider,
 			name: platformSignIn.name
-		}
+		},
+		/** The id and name of each SAML provider, for the sign-in page. */
+		samlProviders: saml.map(({ id, name }) => ({
+			id,
+			name
+		}))
 	});
 };
 //#endregion

package/dist/better-auth/platform-sign-in.js

@@ -29,12 +29,13 @@ const readPlatformSignIn = (env) => {
 		...name && { name }
 	};
 };
-const providerId = /^[a-z][a-z0-9-]*$/;
+/** What a sign-in provider id may be: lowercase letters, digits or "-", starting with a letter. */
+const providerIdPattern = /^[a-z][a-z0-9-]*$/;
 /** The provider with its defaults filled in; an issuer that is not a URL or a malformed id is an error. */
 const resolvePlatformSignIn = (signIn) => {
 	if (!URL.canParse(signIn.issuer)) throw new Error(`The platform sign-in provider's issuer must be a URL, not "${signIn.issuer}"`);
 	const provider = signIn.provider ?? "oidc";
-	if (!providerId.test(provider)) throw new Error(`Invalid sign-in provider id "${provider}": use lowercase letters, digits or "-"`);
+	if (!providerIdPattern.test(provider)) throw new Error(`Invalid sign-in provider id "${provider}": use lowercase letters, digits or "-"`);
 	return {
 		...signIn,
 		provider,
@@ -85,4 +86,4 @@ const platformSignInProvider = (signIn) => ({
 	getUserInfo: async (tokens) => idTokenUser(tokens.idToken, signIn.issuer)
 });
 //#endregion
-export { idTokenUser, platformSignInFor, platformSignInProvider, readPlatformSignIn, resolvePlatformSignIn, signInClientIdVariable, signInClientSecretVariable, signInIssuerVariable, signInNameVariable, signInProviderVariable };
+export { idTokenUser, platformSignInFor, platformSignInProvider, providerIdPattern, readPlatformSignIn, resolvePlatformSignIn, signInClientIdVariable, signInClientSecretVariable, signInIssuerVariable, signInNameVariable, signInProviderVariable };

package/dist/better-auth/saml-sign-in.d.ts

@@ -0,0 +1,37 @@
+import "@better-auth/sso";
+//#region src/better-auth/saml-sign-in.d.ts
+/**
+ * A SAML 2.0 identity provider people of the app sign in with, for example the company's Okta, Entra ID or Google
+ * Workspace. Give its admin this app's entity ID and metadata, `{baseURL}/api/auth/sso/saml2/sp/metadata?providerId={id}`,
+ * and the ACS URL `{origin}/api/auth/sso/saml2/sp/acs/{id}` of each origin the app serves.
+ */
+export type SamlProvider = {
+  /** The id: the button's `?sign-in=` link, the provider's paths and the namespace of its accounts. Lowercase letters, digits or "-". */
+  id: string;
+  /** Shown on the sign-in page as "Continue with {name}". Default `SSO`. */
+  name?: string;
+  /**
+   * The email domains of its people, for example `['example.com']`; subdomains count. Only an address there signs up,
+   * or links to the account that has it.
+   */
+  domains: string[];
+  /** The provider's metadata XML, or its entity ID, sign-in URL and signing certificate(s) (PEM; several while one rotates). */
+  idp: {
+    metadata: string;
+  } | {
+    entityId: string;
+    ssoUrl: string;
+    certificate: string | string[];
+  };
+  /** The assertion's attribute names, when they are not `email`, `givenName`, `surname` and `displayName`. */
+  attributes?: {
+    email?: string;
+    name?: string;
+    firstName?: string;
+    lastName?: string;
+  };
+};
+export type SsoOptions = {
+  saml: SamlProvider[];
+};
+//#endregion

package/dist/better-auth/saml-sign-in.js

@@ -0,0 +1,133 @@
+import { authBasePath } from "./auth-base-path.js";
+import { providerIdPattern } from "./platform-sign-in.js";
+import { APIError, createAuthMiddleware } from "better-auth/api";
+import { sso } from "@better-auth/sso";
+//#region src/better-auth/saml-sign-in.ts
+const domainPattern = /^[a-z0-9-]+(\.[a-z0-9-]+)*$/;
+const checkIdp = (id, idp) => {
+	if ("metadata" in idp && typeof idp.metadata === "string" && idp.metadata.trim()) return;
+	const manual = idp;
+	if (!manual.entityId || !manual.ssoUrl || !manual.certificate || manual.certificate.length === 0) throw new Error(`SAML provider "${id}": give idp.metadata, or all of idp.entityId, idp.ssoUrl and idp.certificate`);
+	if (!URL.canParse(manual.ssoUrl)) throw new Error(`SAML provider "${id}": idp.ssoUrl must be a URL, not "${manual.ssoUrl}"`);
+};
+/**
+* The providers with their defaults filled in: the name `SSO`, and the domains trimmed and lowercased. A malformed id,
+* an id used twice or by another sign-in provider (`takenIds`), no domains or a domain that is not a host name, and IdP
+* settings that are missing or not a URL are errors.
+*/
+const resolveSamlProviders = (saml, takenIds) => {
+	const seen = /* @__PURE__ */ new Set();
+	return saml.map((provider) => {
+		const { id } = provider;
+		if (!providerIdPattern.test(id)) throw new Error(`Invalid SAML provider id "${id}": use lowercase letters, digits or "-"`);
+		if (seen.has(id)) throw new Error(`SAML provider id "${id}" is used twice`);
+		if (takenIds.includes(id)) throw new Error(`SAML provider id "${id}" is already the id of another sign-in provider`);
+		seen.add(id);
+		const domains = (provider.domains ?? []).map((domain) => domain.trim().toLowerCase());
+		if (domains.length === 0) throw new Error(`SAML provider "${id}": give the email domains of its people in domains`);
+		const invalid = domains.find((domain) => !domainPattern.test(domain));
+		if (invalid !== void 0) throw new Error(`SAML provider "${id}": domains must be host names such as example.com, not "${invalid}"`);
+		checkIdp(id, provider.idp);
+		return {
+			...provider,
+			name: provider.name ?? "SSO",
+			domains
+		};
+	});
+};
+/** The app's SP entity ID for a provider: its metadata URL on `baseURL`, the same on every origin. */
+const samlEntityId = (baseURL, id) => `${baseURL.replace(/\/$/, "")}${authBasePath}/sso/saml2/sp/metadata?providerId=${encodeURIComponent(id)}`;
+/** The provider as one of the SSO plugin's configured providers (`defaultSSO`). */
+const defaultSsoEntry = (provider, baseURL) => {
+	const { idp, attributes = {} } = provider;
+	const mapping = Object.fromEntries(Object.entries(attributes).filter(([, name]) => name !== void 0));
+	return {
+		providerId: provider.id,
+		domain: provider.domains.join(","),
+		samlConfig: {
+			issuer: samlEntityId(baseURL, provider.id),
+			entryPoint: "ssoUrl" in idp ? idp.ssoUrl : "",
+			idpMetadata: "metadata" in idp ? { metadata: idp.metadata } : {
+				entityID: idp.entityId,
+				cert: idp.certificate
+			},
+			...Object.keys(mapping).length > 0 && { mapping }
+		}
+	};
+};
+/**
+* Better Auth's SSO plugin with the configured providers. Their domains are trusted, so an address there links to the
+* account that has it; organizations are not assigned by provider, and nobody registers providers.
+*/
+const samlPlugin = (providers, baseURL) => {
+	const { schema: _schema, ...plugin } = sso({
+		defaultSSO: providers.map((provider) => defaultSsoEntry(provider, baseURL)),
+		domainVerification: { enabled: true },
+		organizationProvisioning: { disabled: true },
+		providersLimit: 0
+	});
+	return plugin;
+};
+/** The SSO plugin's endpoints for providers kept in its table, and its OIDC callback, which Protobase does not serve. */
+const samlDisabledPaths = [
+	"/sso/register",
+	"/sso/providers",
+	"/sso/get-provider",
+	"/sso/update-provider",
+	"/sso/delete-provider",
+	"/sso/request-domain-verification",
+	"/sso/verify-domain",
+	"/sso/callback"
+];
+const providerPaths = [
+	"/sso/saml2/sp/acs/:providerId",
+	"/sso/saml2/sp/slo/:providerId",
+	"/sso/saml2/logout/:providerId"
+];
+const signInPath = "/sign-in/sso";
+const metadataPath = "/sso/saml2/sp/metadata";
+const oidcCallbackPath = "/sso/callback/:providerId";
+/** Whether `path`, as `ctx.path` names it, is one of the SSO plugin's endpoints that name a provider. */
+const isSamlPath = (path) => path !== void 0 && [
+	signInPath,
+	metadataPath,
+	oidcCallbackPath,
+	...providerPaths
+].includes(path);
+/**
+* Why a request to the SSO plugin is refused, or `undefined` when it names a configured provider: a request that names
+* none, or another one, would make the plugin look in its provider table. Sign-in names the provider by `providerId`
+* only, not by an address, domain or organization; the OIDC callback is always refused.
+*/
+const samlRefusal = ({ path, body, query, params }, ids) => {
+	if (!isSamlPath(path)) return void 0;
+	if (path === oidcCallbackPath) return "No OpenID Connect provider is configured";
+	const named = path === signInPath ? body?.providerId : path === metadataPath ? query?.providerId : params?.providerId;
+	if (typeof named !== "string" || !named) return "Name the SAML provider by its providerId";
+	return ids.includes(named) ? void 0 : `No SAML provider ${named}`;
+};
+/** Keeps every request to the SSO plugin to the configured providers; see `samlRefusal`. */
+const samlGuardPlugin = (ids) => ({
+	id: "protobase-saml-guard",
+	hooks: { before: [{
+		matcher: (context) => isSamlPath(context.path),
+		handler: createAuthMiddleware(async (ctx) => {
+			const refusal = samlRefusal({
+				path: ctx.path,
+				body: ctx.body,
+				query: ctx.query,
+				params: ctx.params
+			}, ids);
+			if (refusal) throw new APIError("NOT_FOUND", { message: refusal });
+		})
+	}] }
+});
+/** Whether the address is at one of the domains, or a subdomain of one. */
+const emailInDomains = (email, domains) => {
+	const at = email.lastIndexOf("@");
+	if (at < 0) return false;
+	const domain = email.slice(at + 1).toLowerCase();
+	return domains.some((allowed) => domain === allowed || domain.endsWith(`.${allowed}`));
+};
+//#endregion
+export { defaultSsoEntry, emailInDomains, isSamlPath, resolveSamlProviders, samlDisabledPaths, samlEntityId, samlGuardPlugin, samlPlugin, samlRefusal };

package/dist/better-auth/status-route.js

@@ -10,7 +10,7 @@ import { Hono } from "hono";
 * `signInMethods`, the ways to sign in the sign-in policy leaves on (`password`, `emailCode`, `passkey`), so it offers
 * only those; `passwordReset` when reset mail can be sent and passwords are on, so it offers "Forgot password?" only
 * then; `signUp` when the app has open sign-up, so it offers "Create an account"; the ids of the `socialProviders` people can sign in with, so it offers "Continue with GitHub" when `github` is
-* one; `platformSignIn`, the id and name of the platform's provider when it is one of them; `staffSignIn`, the
+* one; `platformSignIn`, the id and name of the platform's provider when it is one of them; `samlProviders`, the id and name of each SAML provider, when the app has any; `staffSignIn`, the
 * operator provider's name, when staff can sign in as people; `passkeyDomains`, when people have passkeys for more than
 * one of the app's hosts, the RP IDs a passkey sign-in can ask for, the passkey domain first; with organizations, who may create them and the roles
 * with their labels, `membership` for those a member can hold, and the roles each one's holders may also give; and
@@ -39,6 +39,7 @@ const statusRoute = (auth, { anonymous = false, plugins = [] } = {}) => {
 			...auth.signUp && { signUp: true },
 			socialProviders,
 			...platformSignIn && { platformSignIn },
+			...auth.samlProviders.length > 0 && { samlProviders: auth.samlProviders },
 			...staffSignIn && { staffSignIn },
 			...passkeyDomains.length > 1 && { passkeyDomains },
 			...anonymous && { anonymous },

package/dist/check-views.js

@@ -47,10 +47,16 @@ const valueColorErrors = (view, model) => Object.entries(view.fields).flatMap(([
 	return Object.keys(hints.valueColors).filter((value) => !field.enumValues?.includes(value)).map((value) => `value colour "${value}" is not a value of "${name}"`);
 });
 const textHints = ["multiline", "markdown"];
+const textFormats = /* @__PURE__ */ new Set([
+	"email",
+	"phone",
+	"url"
+]);
 const textHintErrors = (view, model) => Object.entries(view.fields).flatMap(([name, hints]) => {
 	const field = model.fields[name];
 	if (!field || field.type === "text") return [];
-	return textHints.filter((hint) => hints[hint]).map((hint) => `${hint} "${name}" needs a text field, not ${field.type}`);
+	const format = hints.format !== void 0 && textFormats.has(hints.format) ? [`format('${hints.format}') of "${name}" needs a text field, not ${field.type}`] : [];
+	return [...textHints.filter((hint) => hints[hint]).map((hint) => `${hint} "${name}" needs a text field, not ${field.type}`), ...format];
 });
 const linkErrors = (view, model, models, pages) => view.actions.flatMap(({ name, label, run }) => {
 	if (run?.kind !== "link") return [];

package/dist/create-admin.js

@@ -11,7 +11,7 @@ import { consoleAuditQueue } from "./audit/console-queue.js";
 import { webauthnPath } from "./better-auth/origins.js";
 import { apiCors, readCorsOrigins } from "./api-cors.js";
 import { readAppName } from "./app-name.js";
-import { authBasePath } from "./better-auth/create-auth.js";
+import { authBasePath } from "./better-auth/auth-base-path.js";
 import { organizationRoutes } from "./better-auth/organizations/admin-routes.js";
 import { statusRoute } from "./better-auth/status-route.js";
 import { changesSchema } from "./changes/events-options.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.21.8",
+  "version": "0.21.10",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,9 +30,10 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
-    "@protobase/layout": "0.21.8",
-    "@protobase/query": "0.21.8",
-    "@protobase/schema": "0.21.8",
+    "@better-auth/sso": "^1.7.7",
+    "@protobase/layout": "0.21.10",
+    "@protobase/query": "0.21.10",
+    "@protobase/schema": "0.21.10",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",
@@ -60,5 +61,8 @@
     "sharp": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "samlify": "^2.13.1"
   }
 }