@protobase/server 0.7.0 → 0.8.0

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

@@ -1,6 +1,11 @@
 import { readMailSettings } from "../mail/mail-settings.js";
 import { smtpMailer } from "../mail/smtp-mailer.js";
 import { readOperatorSettings, resolveOperator } from "./operator-provider.js";
+import { roleDefinitions } from "./organizations/role-definitions.js";
+import { lastOrganizationField, organizationClaims, sessionOrganizationHooks } from "./organizations/session-organization.js";
+import { organizationPlugin } from "./organizations/organization-plugin.js";
+import { protobaseOrganizationPlugin } from "./organizations/protobase-plugin.js";
+import { resolveOrganizations } from "./organizations/options.js";
 import { passwordResetOptions } from "./password-reset.js";
 import { platformSignInFor, platformSignInProvider, readPlatformSignIn, resolvePlatformSignIn } from "./platform-sign-in.js";
 import { signInPolicyPlugin } from "./policy-plugin.js";
@@ -28,19 +33,16 @@ const authBasePath = "/api/auth";
 * `createUser`, or by an admin through the admin plugin), roles from the admin plugin's `role` column, 15 minute JWTs
 * at `/api/auth/token` with the keys at `/api/auth/jwks`.
 */
-const roleName = /^[a-z][a-z0-9_-]*$/;
 /** The configured roles with `admin` first; `admin` is added when missing. */
-const normalizeRoles = (roles = ["admin", "user"]) => {
-	const bad = roles.find((role) => !roleName.test(role));
-	if (bad !== void 0) throw new Error(`Invalid role "${bad}": use lowercase letters, digits, "_" or "-"`);
-	return ["admin", ...new Set(roles.filter((role) => role !== "admin"))];
-};
+const normalizeRoles = (roles) => roleDefinitions(roles).names;
 const adminImpersonationPaths = ["/admin/impersonate-user", "/admin/stop-impersonating"];
+const noContext = () => Promise.reject(/* @__PURE__ */ new Error("The auth context is read only once createAuth has made the instance"));
+const organizationPaths = ["/organization/set-active", "/organization/accept-invitation"];
 /**
 * The options `createAuth` gives Better Auth, with the roles, default role, mailer, operator provider and platform
 * sign-in provider already resolved.
 */
-const betterAuthOptions = (options, { roles, defaultRole, mailer, operator, platformSignIn }) => {
+const betterAuthOptions = (options, { roles, defaultRole, mailer, operator, platformSignIn, organizations, context = noContext }) => {
 	const secure = options.baseURL.startsWith("https://");
 	const signIn = platformSignInFor(platformSignIn, Object.keys(options.socialProviders ?? {}));
 	return {
@@ -61,7 +63,10 @@ const betterAuthOptions = (options, { roles, defaultRole, mailer, operator, plat
 			...mailer && passwordResetOptions(mailer)
 		},
 		...options.socialProviders && { socialProviders: options.socialProviders },
-		user: coreNames.user,
+		user: organizations ? {
+			...coreNames.user,
+			additionalFields: lastOrganizationField
+		} : coreNames.user,
 		session: coreNames.session,
 		verification: coreNames.verification,
 		account: {
@@ -81,9 +86,10 @@ const betterAuthOptions = (options, { roles, defaultRole, mailer, operator, plat
 					expirationTime: tokenLifetime,
 					issuer: options.baseURL,
 					audience: options.baseURL,
-					definePayload: ({ user }) => ({
+					definePayload: async ({ user, session }) => ({
 						email: user.email,
-						role: user.role
+						role: user.role,
+						...organizations && await organizationClaims((await context()).adapter, user, session.activeOrganizationId)
 					})
 				},
 				disableSettingJwtHeader: true
@@ -108,21 +114,37 @@ const betterAuthOptions = (options, { roles, defaultRole, mailer, operator, plat
 			staffSignInPlugin({
 				...operator && { operator },
 				...mailer && { mailer }
-			})
+			}),
+			...organizations ? [organizationPlugin({
+				resolved: organizations,
+				secret: options.secret,
+				...mailer && { mailer },
+				context
+			}), protobaseOrganizationPlugin({
+				resolved: organizations,
+				mail: Boolean(mailer)
+			})] : []
 		],
-		disabledPaths: [...unusedEmailCodePaths, ...adminImpersonationPaths],
-		databaseHooks: { user: { create: {
-			before: async (user, context) => {
-				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(", ")}` });
-				return { data: context?.path === "/admin/create-user" ? {
-					...user,
-					emailVerified: true
-				} : user };
-			},
-			...options.onUserCreated && { after: options.onUserCreated }
-		} } },
+		disabledPaths: [
+			...unusedEmailCodePaths,
+			...adminImpersonationPaths,
+			...organizations ? organizationPaths : []
+		],
+		databaseHooks: {
+			user: { create: {
+				before: async (user, context) => {
+					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(", ")}` });
+					return { data: context?.path === "/admin/create-user" ? {
+						...user,
+						emailVerified: true
+					} : user };
+				},
+				...options.onUserCreated && { after: options.onUserCreated }
+			} },
+			...organizations && { session: sessionOrganizationHooks(context) }
+		},
 		rateLimit: {
 			enabled: true,
 			window: 60,
@@ -135,6 +157,10 @@ const betterAuthOptions = (options, { roles, defaultRole, mailer, operator, plat
 				"/staff/sign-in": {
 					window: 60,
 					max: 5
+				},
+				"/invitation/sign-up": {
+					window: 60,
+					max: options.signInPerMinute ?? 5
 				}
 			}
 		},
@@ -149,25 +175,36 @@ const betterAuthOptions = (options, { roles, defaultRole, mailer, operator, plat
 	};
 };
 const createAuth = (options) => {
-	const roles = normalizeRoles(options.roles);
+	const definitions = roleDefinitions(options.roles, { organizations: options.organizations !== void 0 });
+	const roles = definitions.names;
 	if (options.defaultRole !== void 0 && !roles.includes(options.defaultRole)) throw new Error(`defaultRole "${options.defaultRole}" is not one of the roles: ${roles.join(", ")}`);
 	const others = roles.filter((role) => role !== "admin");
-	const defaultRole = options.defaultRole ?? (others.length === 1 ? others[0] : void 0);
+	const defaultRole = options.defaultRole ?? (options.organizations ? "user" : others.length === 1 ? others[0] : void 0);
 	const mailer = options.mailer === void 0 ? platformMailer() : options.mailer || void 0;
 	const provider = options.operator === void 0 ? platformOperator() : options.operator || void 0;
 	const operator = provider && resolveOperator(provider);
 	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 organizations = options.organizations && resolveOrganizations(options.organizations, definitions, options.baseURL);
+	let instance;
+	const context = () => instance?.$context ?? Promise.reject(/* @__PURE__ */ new Error("The auth instance is not made yet"));
 	const auth = betterAuth(betterAuthOptions(options, {
 		roles,
 		defaultRole,
 		mailer,
 		operator,
-		platformSignIn
+		platformSignIn,
+		...organizations && {
+			organizations,
+			context
+		}
 	}));
+	instance = auth;
 	return Object.assign(auth, {
 		roles,
+		roleDefinitions: definitions,
+		organizations,
 		defaultRole,
 		mail: Boolean(mailer),
 		passwordReset: Boolean(mailer),

package/dist/better-auth/organizations/accept-invitation.js

@@ -0,0 +1,80 @@
+import { parseAppRoles } from "./app-roles.js";
+import { findMember, membersOf } from "./store.js";
+import { invitationIdOf, verifyInvitationToken } from "./invitation-token.js";
+import { APIError } from "better-auth/api";
+//#region src/better-auth/organizations/accept-invitation.ts
+const invalid = {
+	code: "INVITATION_INVALID",
+	message: "This invitation link is not valid any more: it was used, revoked, replaced by a newer one, or it expired."
+};
+/** The pending invitation an emailed link's token names, or a 400 `INVITATION_INVALID`. */
+const invitationOfToken = async (context, token) => {
+	const id = invitationIdOf(token);
+	const row = id && await context.adapter.findOne({
+		model: "invitation",
+		where: [{
+			field: "id",
+			value: id
+		}]
+	});
+	if (!row || !await verifyInvitationToken(context.secret, token, row)) throw new APIError("BAD_REQUEST", invalid);
+	if (row.status !== "pending" || new Date(row.expiresAt).getTime() < Date.now()) throw new APIError("BAD_REQUEST", invalid);
+	return {
+		...row,
+		appRoles: parseAppRoles(row.appRoles)
+	};
+};
+/**
+* Makes `user` a member as the invitation says, with its organization role and app roles, in one transaction with the
+* invitation's acceptance, so a member never exists without the app roles they were invited with. Better Auth's own
+* accept leaves the app roles out; it is turned off with organizations.
+*/
+const acceptInvitation = async (context, invitation, user, membershipLimit) => {
+	if (invitation.email.toLowerCase() !== user.email.toLowerCase()) throw new APIError("FORBIDDEN", {
+		code: "NOT_THE_INVITED_ADDRESS",
+		message: `This invitation is for ${invitation.email}; sign in with that address to accept it.`
+	});
+	if (!user.emailVerified) throw new APIError("FORBIDDEN", {
+		code: "EMAIL_NOT_VERIFIED",
+		message: "Verify your email address before accepting an invitation."
+	});
+	if (await findMember(context.adapter, {
+		organizationId: invitation.organizationId,
+		userId: user.id
+	})) throw new APIError("BAD_REQUEST", {
+		code: "ALREADY_A_MEMBER",
+		message: "You are a member of this organization already."
+	});
+	if ((await membersOf(context.adapter, invitation.organizationId)).length >= membershipLimit) throw new APIError("FORBIDDEN", {
+		code: "MEMBERSHIP_LIMIT_REACHED",
+		message: "This organization has as many members as it can have."
+	});
+	return context.adapter.transaction(async (trx) => {
+		if (!await trx.update({
+			model: "invitation",
+			where: [{
+				field: "id",
+				value: invitation.id
+			}, {
+				field: "status",
+				value: "pending"
+			}],
+			update: { status: "accepted" }
+		})) throw new APIError("BAD_REQUEST", invalid);
+		return {
+			...await trx.create({
+				model: "member",
+				data: {
+					organizationId: invitation.organizationId,
+					userId: user.id,
+					role: invitation.role,
+					appRoles: invitation.appRoles,
+					createdAt: /* @__PURE__ */ new Date()
+				}
+			}),
+			appRoles: invitation.appRoles
+		};
+	});
+};
+//#endregion
+export { acceptInvitation, invitationOfToken };

package/dist/better-auth/organizations/active-organization.js

@@ -0,0 +1,12 @@
+//#region src/better-auth/organizations/active-organization.ts
+/**
+* The organization a new session starts in: the last one the person worked in while they may still enter it (a member
+* there, or holding a global role, which enters any that still exists), else their oldest membership, else none.
+*/
+const initialOrganization = (input) => {
+	const { memberships, last } = input;
+	if (last && (memberships.some((membership) => membership.organizationId === last) || input.entersAny && input.lastExists)) return last;
+	return [...memberships].sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime())[0]?.organizationId;
+};
+//#endregion
+export { initialOrganization };

package/dist/better-auth/organizations/admin-routes.js

@@ -0,0 +1,83 @@
+import { globalRoles } from "./app-roles.js";
+import { findMember, findOrganization } from "./store.js";
+import { auditOrigin } from "../../audit/origin.js";
+import { Hono } from "hono";
+import { exactCount } from "@protobase/query";
+//#region src/better-auth/organizations/admin-routes.ts
+/** The resources with rows in an organization, soft-deleted ones too: they would point at nothing once it is gone. */
+const resourcesWithRecords = async (registry, db, organizationId) => {
+	const names = [];
+	for (const entry of registry.entries) {
+		if (!entry.model.tenant) continue;
+		const { softDelete: _, ...model } = entry.model;
+		if (await exactCount(db, model, void 0, { tenantValue: organizationId }) > 0) names.push(entry.name);
+	}
+	return names;
+};
+const refusal = (status, code, message) => ({
+	status,
+	code,
+	message
+});
+/**
+* The organization routes that need the admin's own parts, mounted before Better Auth's handler: switching the
+* organization one works in, which writes an audit event when someone enters one they are not a member of, and, while
+* `deleteRecords` is `'refuse'`, deleting only an organization without records.
+*/
+const organizationRoutes = ({ auth, audit, registry, db }) => {
+	const app = new Hono();
+	const contextOf = async () => await auth.$context;
+	const fail = (c, problem) => c.json({
+		code: problem.code,
+		message: problem.message
+	}, problem.status);
+	/**
+	* `POST /organization/switch` with `{ organizationId }`: the session works in that organization from its next token
+	* on, for a member, or for someone with a global role, who may enter any; `null` leaves it.
+	*/
+	app.post("/organization/switch", async (c) => {
+		const session = await auth.api.getSession({ headers: c.req.raw.headers });
+		if (!session) return fail(c, refusal(401, "UNAUTHORIZED", "Sign in first."));
+		const organizationId = (await c.req.json().catch(() => void 0))?.organizationId;
+		if (organizationId !== null && typeof organizationId !== "string") return fail(c, refusal(400, "ORGANIZATION_REQUIRED", "Name the organization to work in."));
+		const { adapter, internalAdapter } = await contextOf();
+		if (organizationId !== null) {
+			const member = await findMember(adapter, {
+				organizationId,
+				userId: session.user.id
+			});
+			const global = globalRoles(session.user.role);
+			if (!member) {
+				if (global.length === 0 || !await findOrganization(adapter, organizationId)) return fail(c, refusal(403, "NOT_A_MEMBER", "You are not a member of this organization."));
+				await audit.publish({
+					type: "organization.entered",
+					at: (/* @__PURE__ */ new Date()).toISOString(),
+					actor: {
+						id: session.user.id,
+						roles: global
+					},
+					organization: organizationId,
+					origin: auditOrigin(c.req.raw.headers)
+				});
+			}
+		}
+		await internalAdapter.updateSession(session.session.token, { activeOrganizationId: organizationId });
+		return c.json({ organizationId });
+	});
+	if (auth.organizations?.deleteRecords !== "cascade") app.post("/organization/delete", async (c, next) => {
+		const body = await c.req.raw.clone().json().catch(() => void 0);
+		const session = await auth.api.getSession({ headers: c.req.raw.headers });
+		if (!session || typeof body?.organizationId !== "string") return next();
+		const member = await findMember((await contextOf()).adapter, {
+			organizationId: body.organizationId,
+			userId: session.user.id
+		});
+		if (!member || !member.role.split(",").includes("owner")) return next();
+		const names = await resourcesWithRecords(registry, db, body.organizationId);
+		if (names.length > 0) return fail(c, refusal(409, "ORGANIZATION_HAS_RECORDS", `Delete the organization's records first: ${names.join(", ")}.`));
+		return next();
+	});
+	return app;
+};
+//#endregion
+export { organizationRoutes, resourcesWithRecords };

package/dist/better-auth/organizations/app-roles.js

@@ -0,0 +1,43 @@
+import { parseRoles } from "../parse-roles.js";
+import { membershipRoles, noGlobalRole } from "./role-definitions.js";
+//#region src/better-auth/organizations/app-roles.ts
+/** A user's global roles, from the admin plugin's `role` column; the placeholder `user` is none. */
+const globalRoles = (role) => parseRoles(role).filter((name) => name !== noGlobalRole);
+/** App roles stored on a membership or an invitation: a JSON array, as the store returns it or as text. */
+const parseAppRoles = (value) => {
+	const list = typeof value === "string" ? JSON.parse(value) : value;
+	return Array.isArray(list) ? list.filter((name) => typeof name === "string") : [];
+};
+/** The roles a request has: the global ones, then the membership's in the active organization, each once. */
+const effectiveRoles = (global, membership = []) => [.../* @__PURE__ */ new Set([...global, ...membership])];
+/**
+* The roles someone may give or take away: those they hold, globally or in the organization, and those a held role
+* lists in its `grants`. Grants do not chain. A superuser may give every role.
+*/
+const grantableRoles = (held, definitions) => {
+	if (held.includes("admin")) return new Set(definitions.names);
+	return /* @__PURE__ */ new Set([...held, ...held.flatMap((name) => definitions.grants[name] ?? [])]);
+};
+/**
+* Whether someone holding `held` may change a membership's app roles from `before` to `after`: every role added or
+* removed must be grantable by them, and every role in `after` one a member can hold. `undefined` when allowed.
+*/
+const checkAppRoleChange = (input) => {
+	const allowed = membershipRoles(input.definitions);
+	const unknown = input.after.filter((name) => !allowed.includes(name));
+	if (unknown.length > 0) return {
+		status: "BAD_REQUEST",
+		code: "UNKNOWN_APP_ROLE",
+		message: `A member cannot hold ${unknown.join(", ")}; choose from ${allowed.join(", ")}`
+	};
+	const grantable = grantableRoles(input.held, input.definitions);
+	const refused = [...input.after.filter((name) => !input.before.includes(name)), ...input.before.filter((name) => !input.after.includes(name))].filter((name) => !grantable.has(name));
+	if (refused.length === 0) return void 0;
+	return {
+		status: "FORBIDDEN",
+		code: "APP_ROLE_NOT_GRANTABLE",
+		message: `You cannot give or take away ${refused.map((name) => input.definitions.labels[name] ?? name).join(", ")}: hold the role, or one that grants it`
+	};
+};
+//#endregion
+export { checkAppRoleChange, effectiveRoles, globalRoles, grantableRoles, parseAppRoles };

package/dist/better-auth/organizations/host.d.ts

@@ -0,0 +1,53 @@
+import { OrganizationRole, StoredMember, StoredOrganization } from "./store.js";
+import { AdminAuth } from "../create-auth.js";
+//#region src/better-auth/organizations/host.d.ts
+export type NewOrganization = {
+  name: string;
+  slug: string;
+  owner: string;
+  id?: string;
+};
+/**
+ * Creates an organization with `owner` (an email) as its owner, holding the creator's app roles. `id` keeps an existing
+ * tenant value, for an app that had one organization before; otherwise the configured `generateId` makes one.
+ */
+export declare const createOrganization: (auth: AdminAuth, input: NewOrganization) => Promise<{
+  organization: StoredOrganization;
+  member: {
+    appRoles: string[];
+    id: string;
+    organizationId: string;
+    userId: string;
+    role: string;
+    createdAt: Date;
+  };
+}>;
+export type MemberInput = {
+  organization: string;
+  email: string;
+  role?: string;
+  appRoles?: string[];
+};
+/** Adds someone with an account as a member: organization role `member` unless given, and the app roles given. */
+export declare const addMember: (auth: AdminAuth, input: MemberInput) => Promise<StoredMember>;
+/** Changes a member's organization role, app roles, or both. */
+export declare const setMemberRoles: (auth: AdminAuth, input: MemberInput) => Promise<StoredMember | undefined>;
+/** Removes a member; refuses the last owner. */
+export declare const removeMember: (auth: AdminAuth, input: {
+  organization: string;
+  email: string;
+}) => Promise<void>;
+/** Every organization, oldest first, with its members' emails and roles. */
+export declare const listOrganizations: (auth: AdminAuth) => Promise<{
+  id: string;
+  name: string;
+  slug: string;
+  members: {
+    email: string;
+    role: OrganizationRole;
+    appRoles: string[];
+  }[];
+}[]>;
+/** Gives an app role to every owner of every organization, for a role the project adds once organizations exist. */
+export declare const addAppRoleToOwners: (auth: AdminAuth, appRole: string) => Promise<number>;
+//#endregion