@protobase/server 0.49.0 → 0.49.1

package/dist/better-auth/auth-settings.d.ts

@@ -5,6 +5,7 @@ import { StaffSignIn } from "./staff-log.js";
 import { RoleDefinitions } from "./organizations/role-definitions.js";
 import { ConnectedApp } from "./mcp/connected-apps.js";
 import { ReplacingContext } from "./end-replaced-session.js";
+import { VersionedSecret } from "./secret-versions.js";
 import { UserDeletionListener } from "./user-deletion.js";
 import { OrganizationRole, StoredMember, StoredOrganization } from "./organizations/store.js";
 import { OrganizationsOptions, ResolvedOrganizations } from "./organizations/options.js";
@@ -1090,6 +1091,8 @@ export declare const buildAppAuth: (settings: AuthSettings, input: AppAuthInput)
         };
       };
       jwks: {
+        rotationInterval: number;
+        gracePeriod: number;
         keyPairConfigs: {
           readonly alg: "ES256";
         }[];
@@ -1352,6 +1355,21 @@ export declare const buildAppAuth: (settings: AuthSettings, input: AppAuthInput)
         };
       };
     };
+  } | {
+    id: "protobase-signing-keys";
+    endpoints: {
+      ensureSigningKey: import("better-call").StrictEndpoint<string, {
+        method: "POST";
+      }, {
+        ok: boolean;
+      }>;
+    };
+    hooks: {
+      before: {
+        matcher: (ctx: import("better-auth").HookEndpointContext) => boolean;
+        handler: import("better-call").Middleware<import("better-call").MiddlewareOptions, (inputContext: import("better-call").MiddlewareInputContext<import("better-call").MiddlewareOptions>) => Promise<void>>;
+      }[];
+    };
   } | {
     hooks: {
       after: {
@@ -8683,6 +8701,7 @@ export declare const buildAppAuth: (settings: AuthSettings, input: AppAuthInput)
   };
   basePath: string;
   secret: string;
+  secrets: VersionedSecret[];
   trustedOrigins: string[] | ((request?: Request) => string[]);
   emailAndPassword: {
     onPasswordReset?: ((data: {

package/dist/better-auth/create-auth.d.ts

@@ -5,6 +5,7 @@ import { StaffSignIn } from "./staff-log.js";
 import { RoleDefinitions, RolesInput } from "./organizations/role-definitions.js";
 import { ConnectedApp } from "./mcp/connected-apps.js";
 import { ReplacingContext } from "./end-replaced-session.js";
+import { VersionedSecret } from "./secret-versions.js";
 import { UserDeletionListener } from "./user-deletion.js";
 import { OrganizationRole } from "./organizations/store.js";
 import { OrganizationsOptions, ResolvedOrganizations } from "./organizations/options.js";
@@ -48,6 +49,15 @@ export type CreateAuthOptions = {
   appName?: string;
   /** Signs cookies and encrypts the JWT private keys. Generate with `openssl rand -base64 32`. */
   secret: string;
+  /**
+   * The secrets the app had before `secret`, newest first, such as `PROTOBASE_PREVIOUS_SECRETS`: what they encrypted
+   * still decrypts, so the signing keys keep signing after the secret changes. Default none.
+   */
+  previousSecrets?: string[];
+  /** Days a token signing key signs before a new one takes over; default 30. */
+  signingKeyDays?: number;
+  /** Days a replaced signing key still verifies the tokens it signed; default 7, at least 1. */
+  signingKeyGraceDays?: number;
   /** Extra origins that may call the auth endpoints, such as the exact host of a dev tunnel. `baseURL` and `origins` are always trusted. */
   trustedOrigins?: string[];
   /**
@@ -1200,6 +1210,8 @@ export declare const createAuth: (options: CreateAuthOptions, plugins?: AuthPlug
         };
       };
       jwks: {
+        rotationInterval: number;
+        gracePeriod: number;
         keyPairConfigs: {
           readonly alg: "ES256";
         }[];
@@ -1462,6 +1474,21 @@ export declare const createAuth: (options: CreateAuthOptions, plugins?: AuthPlug
         };
       };
     };
+  } | {
+    id: "protobase-signing-keys";
+    endpoints: {
+      ensureSigningKey: import("better-call").StrictEndpoint<string, {
+        method: "POST";
+      }, {
+        ok: boolean;
+      }>;
+    };
+    hooks: {
+      before: {
+        matcher: (ctx: import("better-auth").HookEndpointContext) => boolean;
+        handler: import("better-call").Middleware<import("better-call").MiddlewareOptions, (inputContext: import("better-call").MiddlewareInputContext<import("better-call").MiddlewareOptions>) => Promise<void>>;
+      }[];
+    };
   } | {
     hooks: {
       after: {
@@ -8787,6 +8814,7 @@ export declare const createAuth: (options: CreateAuthOptions, plugins?: AuthPlug
   };
   basePath: string;
   secret: string;
+  secrets: VersionedSecret[];
   trustedOrigins: string[] | ((request?: Request) => string[]);
   emailAndPassword: {
     onPasswordReset?: ((data: {

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

@@ -30,6 +30,8 @@ import { coreNames, pluginNames } from "./snake-case-names.js";
 import { passkeyPlugin } from "./passkey-plugin.js";
 import { passwordResetOptions } from "./password-reset.js";
 import { rolesPlugin } from "./roles/roles-plugin.js";
+import { versionedSecrets } from "./secret-versions.js";
+import { signingKeyRotation, signingKeys } from "./signing-keys.js";
 import { platformSignInFor, platformSignInProvider, readPlatformSignIn, resolvePlatformSignIn } from "./platform-sign-in.js";
 import { appSignInPolicy } from "./app-sign-in-policy.js";
 import { assertNoEndpointKeyClashes } from "./endpoint-key-clashes.js";
@@ -110,7 +112,10 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 	};
 	const jwtOptions = {
 		schema: pluginNames.jwt,
-		jwks: { keyPairConfigs: [goTrueKeyPair] },
+		jwks: {
+			keyPairConfigs: [goTrueKeyPair],
+			...signingKeyRotation(options)
+		},
 		jwt: {
 			expirationTime: tokenLifetime,
 			issuer: options.baseURL,
@@ -130,6 +135,8 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 		},
 		disableSettingJwtHeader: true
 	};
+	const keys = signingKeys(jwtOptions);
+	const { secrets, legacySecret } = versionedSecrets(options.secret, options.previousSecrets);
 	const trusted = [
 		options.baseURL,
 		...origins,
@@ -146,7 +153,8 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 		logger: authLogger,
 		baseURL: multiHostBaseURL(options.baseURL, origins),
 		basePath: authBasePath,
-		secret: options.secret,
+		secret: legacySecret,
+		secrets,
 		trustedOrigins: mobile ? (request) => [...trusted, ...mobile.trusted(request)] : trusted,
 		emailAndPassword: {
 			enabled: true,
@@ -175,6 +183,7 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 				roles: Object.fromEntries(roles.map((role) => [role, role === "admin" ? adminAc : userAc]))
 			}),
 			jwt(jwtOptions),
+			keys.plugin,
 			twoFactorAfterPasswordOrCode({
 				schema: pluginNames.twoFactor,
 				allowPasswordless: true,
@@ -201,6 +210,7 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 			goTrueSessionsPlugin({
 				issuer: goTrueIssuer(options.baseURL),
 				jwt: jwtOptions,
+				signingKey: keys.ensure,
 				policy
 			}),
 			staffSignInPlugin({

package/dist/better-auth/secret-versions.d.ts

@@ -0,0 +1,7 @@
+//#region src/better-auth/secret-versions.d.ts
+/** Better Auth's versioned secrets: the current one first, each with the version its ciphertexts name. */
+export type VersionedSecret = {
+  version: number;
+  value: string;
+};
+//#endregion

package/dist/better-auth/secret-versions.js

@@ -0,0 +1,21 @@
+import { createHash } from "node:crypto";
+//#region src/better-auth/secret-versions.ts
+const versionOf = (secret) => Number.parseInt(createHash("sha256").update(`protobase-secret-version:${secret}`).digest("hex").slice(0, 7), 16);
+/**
+* Better Auth's options for the app's `secret` and its `previousSecrets`: `secrets`, which encrypt with the current
+* one and decrypt with any of them, and `secret`, which Better Auth keeps for what was encrypted before secrets had
+* versions. That is the oldest secret listed: the one in use when the app last ran without versions, unless it was
+* changed since without being listed.
+*/
+const versionedSecrets = (secret, previousSecrets = []) => {
+	const all = [.../* @__PURE__ */ new Set([secret, ...previousSecrets])];
+	return {
+		secrets: all.map((value) => ({
+			version: versionOf(value),
+			value
+		})),
+		legacySecret: all.at(-1)
+	};
+};
+//#endregion
+export { versionedSecrets };

package/dist/better-auth/signing-keys.js

@@ -0,0 +1,86 @@
+import { createAuthEndpoint, createAuthMiddleware } from "better-auth/api";
+import { createJwk } from "better-auth/plugins";
+const daySeconds = 86400;
+/** The JWT plugin's rotation for `options`: `rotationInterval` and `gracePeriod`, in seconds. */
+const signingKeyRotation = ({ signingKeyDays = 30, signingKeyGraceDays = 7 } = {}) => {
+	if (!(signingKeyDays > 0)) throw new Error("signingKeyDays must be more than 0");
+	if (!(signingKeyGraceDays >= 1)) throw new Error("signingKeyGraceDays must be at least 1: tokens of `protobase token` last up to a day");
+	return {
+		rotationInterval: Math.round(signingKeyDays * daySeconds),
+		gracePeriod: Math.round(signingKeyGraceDays * daySeconds)
+	};
+};
+const isPrimary = (key) => key.alg === null || key.alg === void 0 || key.alg === "EdDSA";
+const marginMs = 6e4;
+const signingPaths = /* @__PURE__ */ new Set(["/token", "/oauth2/token"]);
+/**
+* Keeps a live EdDSA key for the app's tokens. The JWT plugin signs with the newest live key of the primary algorithm,
+* else with the newest live key of any: once the EdDSA key expired while the ES256 one of the GoTrue-compatible
+* tokens still lived, it would sign the app's tokens ES256 until that one expired too. So before every signing, a new
+* EdDSA key is made when none lives; a key made before rotation was on (without an expiry) gets the one it would have
+* had, its creation plus the rotation interval, so it rotates too. A key past its grace period, which no longer
+* verifies, is deleted, so the store keeps a few keys (Better Auth reads at most 100). The key set is read once per
+* key's lifetime: until the newest EdDSA key expires, signing reads nothing more.
+*/
+const signingKeys = (jwt) => {
+	const intervalMs = jwt.jwks.rotationInterval * 1e3;
+	const graceMs = jwt.jwks.gracePeriod * 1e3;
+	let liveUntil = 0;
+	let pending;
+	const check = async (ctx) => {
+		const now = Date.now();
+		const { adapter } = ctx.context;
+		const dated = (await adapter.findMany({ model: "jwks" })).map((key) => ({
+			...key,
+			undated: !key.expiresAt,
+			expiresAt: key.expiresAt ?? new Date(key.createdAt.getTime() + intervalMs)
+		}));
+		const retired = dated.filter((key) => key.expiresAt.getTime() + graceMs <= now);
+		if (retired.length > 0) await adapter.deleteMany({
+			model: "jwks",
+			where: [{
+				field: "id",
+				operator: "in",
+				value: retired.map((key) => key.id)
+			}]
+		});
+		const keys = dated.filter((key) => !retired.includes(key));
+		await Promise.all(keys.filter((key) => key.undated).map((key) => adapter.update({
+			model: "jwks",
+			where: [{
+				field: "id",
+				value: key.id
+			}],
+			update: { expiresAt: key.expiresAt }
+		})));
+		liveUntil = (keys.filter((key) => isPrimary(key) && key.expiresAt.getTime() - marginMs > now).sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())[0] ?? await createJwk(ctx, jwt)).expiresAt.getTime() - marginMs;
+	};
+	/** Makes sure a live EdDSA key signs the next token; concurrent callers share one check. */
+	const ensure = async (ctx) => {
+		if (Date.now() < liveUntil) return;
+		pending ??= check(ctx).finally(() => {
+			pending = void 0;
+		});
+		await pending;
+	};
+	return {
+		plugin: {
+			id: "protobase-signing-keys",
+			endpoints: { 
+			/** Makes sure a live EdDSA key signs the next token, for signing outside the plugin's paths (`issueToken`). */
+ensureSigningKey: createAuthEndpoint.serverOnly({ method: "POST" }, async (ctx) => {
+				await ensure(ctx);
+				return ctx.json({ ok: true });
+			}) },
+			hooks: { before: [{
+				matcher: (ctx) => signingPaths.has(ctx.path ?? ""),
+				handler: createAuthMiddleware(async (ctx) => {
+					await ensure(ctx);
+				})
+			}] }
+		},
+		ensure
+	};
+};
+//#endregion
+export { signingKeyRotation, signingKeys };

package/dist/better-auth/tokens.js

@@ -24,6 +24,7 @@ const issueToken = async (auth, options) => {
 	if (user.banned) throw new Error(`${options.email} is banned`);
 	const issuedAt = Math.floor(Date.now() / 1e3);
 	const { role } = narrowClaims({ role: parseRoles(user.role).join(",") }, [user.lastRole], Boolean(auth.organizations));
+	await auth.api.ensureSigningKey();
 	const { token } = await auth.api.signJWT({ body: { payload: {
 		iat: issuedAt,
 		exp: issuedAt + ttl,

package/dist/gotrue/sessions-plugin.js

@@ -4,7 +4,7 @@ import { goTrueUser } from "./user-json.js";
 import { accessClaims, goTrueSession } from "./session-json.js";
 import * as z$1 from "zod";
 import { APIError, createAuthEndpoint } from "better-auth/api";
-import { createJwk, signJWT } from "better-auth/plugins";
+import { signJWT } from "better-auth/plugins";
 import { generateRandomString } from "better-auth/crypto";
 //#region src/gotrue/sessions-plugin.ts
 const refreshTokenNotFound = () => new APIError("BAD_REQUEST", {
@@ -16,13 +16,7 @@ const refreshTokenNotFound = () => new APIError("BAD_REQUEST", {
 * so signing out anywhere, a ban or a revoked session ends it, and refreshing gives the session a new token, so each
 * refresh token works once. Server-side endpoints only, for `goTrueRoutes`.
 */
-const goTrueSessionsPlugin = ({ issuer, jwt, policy }) => {
-	let primaryKeyMade = false;
-	const makePrimaryKey = async (ctx) => {
-		if (primaryKeyMade) return;
-		if (!(await ctx.context.adapter.findMany({ model: "jwks" })).some((key) => key.alg === null || key.alg === void 0 || key.alg === "EdDSA")) await createJwk(ctx, jwt);
-		primaryKeyMade = true;
-	};
+const goTrueSessionsPlugin = ({ issuer, jwt, signingKey, policy }) => {
 	const sessionOf = async (ctx, sessionToken) => {
 		const found = await ctx.context.internalAdapter.findSession(sessionToken);
 		if (!found) throw refreshTokenNotFound();
@@ -31,7 +25,7 @@ const goTrueSessionsPlugin = ({ issuer, jwt, policy }) => {
 		if (refusal) throw new APIError("FORBIDDEN", refusal);
 		const accounts = await ctx.context.internalAdapter.findAccounts(user.id);
 		const now = Math.floor(Date.now() / 1e3);
-		await makePrimaryKey(ctx);
+		await signingKey(ctx);
 		const accessToken = await signJWT(ctx, {
 			options: jwt,
 			payload: accessClaims({

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.49.0";
+var version = "0.49.1";
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.49.0",
+  "version": "0.49.1",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -40,9 +40,9 @@
     "@better-auth/passkey": "^1.7.12",
     "@better-auth/sso": "^1.7.12",
     "@modelcontextprotocol/server": "^2.3.1",
-    "@protobase/layout": "0.49.0",
-    "@protobase/query": "0.49.0",
-    "@protobase/schema": "0.49.0",
+    "@protobase/layout": "0.49.1",
+    "@protobase/query": "0.49.1",
+    "@protobase/schema": "0.49.1",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",