@protobase/server 0.49.0 → 0.49.2

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/files/store-file.d.ts

@@ -1,13 +1,25 @@
+import { FileProvider } from "./store.js";
 import { FilesOptions } from "./options.js";
+import { FileProviderSettings } from "./provider-settings.js";
 //#region src/files/store-file.d.ts
+/** A provider in `files.providers`: as the config writes it, or made. */
+type ProviderEntry = FileProvider | FileProviderSettings | {
+  kind: 'custom';
+};
 export type StoreFileInput = {
   /** The provider's name, as a stored value starts with it: `public` in `public:listings/house-1.png`. */
   provider: string;
   /** The path in the provider, such as `listings/house-1.png`. */
   path: string;
   body: Uint8Array | ReadableStream<Uint8Array>;
-  /** `files` from `protobase.config.ts`, when it configures providers; the environment's apply on top, as for the server. */
-  files?: FilesOptions;
+  /**
+   * `files` from `protobase.config.ts`, when it configures providers, as the config writes it (`{ kind: 'local', dir }`,
+   * `{ kind: 's3', bucket }`) or with its providers made; the environment's apply on top, as for the server.
+   */
+  files?: Omit<FilesOptions, 'providers'> & {
+    providers?: Record<string, ProviderEntry>;
+    images?: string;
+  };
   /** Where `PROTOBASE_FILES_<NAME>` and the credentials are read from, usually `process.env`. */
   env: Record<string, string | undefined>;
 };

package/dist/files/store-file.js

@@ -1,12 +1,19 @@
 import { resolveProviders } from "./providers.js";
+import { fileProviderOf } from "./provider-settings.js";
 //#region src/files/store-file.ts
+const providerOf = (name, entry) => {
+	if (!("kind" in entry)) return entry;
+	if (entry.kind === "custom") throw new Error(`files.providers.${name} is the default export of files/${name}.ts: import it and pass it in place of { kind: 'custom' }`);
+	return fileProviderOf(name, entry);
+};
 /**
 * Writes a file into one of the app's providers outside a request, such as from a seed: the folder of a `file:`
 * provider, the bucket of an `s3:` one, resolved as the server resolves them (`PROTOBASE_FILES_<NAME>`, else the
 * config's, else `data/files/<name>` for `private` and `public`). A relative folder is taken from the working directory.
 */
 const storeFile = async ({ provider, path, body, files = {}, env }) => {
-	const providers = resolveProviders(files, env, [provider]);
+	const entry = files.providers?.[provider];
+	const providers = resolveProviders(entry ? { providers: { [provider]: providerOf(provider, entry) } } : {}, env, [provider]);
 	const stream = body instanceof ReadableStream ? body : new Blob([body]).stream();
 	return providers[provider].store.put(path, stream);
 };

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/index.d.ts

@@ -154,7 +154,7 @@ import { FileRef, formatUri, variantPath } from "./files/uri.js";
 import { aspectRatio, fileSize, fileType, imageSize, processor } from "./files/processors.js";
 import { defineJob, isJobDefinition, jobDefinitions } from "./jobs/define-job.js";
 import { FatalJobError } from "./jobs/run-job.js";
-import { JobDeclaration, JobRun, enqueueJob } from "./jobs/declared-job.js";
+import { ArgumentsPayload, EnqueueJob, JobDeclaration, JobName, JobPayload, JobRun, enqueueJob } from "./jobs/declared-job.js";
 import { isSchedule } from "./jobs/schedule.js";
 import { EmailComponent, EmailOptions, EmailTemplate, RenderedEmail, defineEmail } from "./mail/define-email.js";
 import { DrainResult, JobsRuntime, StartJobsOptions, startJobs } from "./jobs/runtime.js";
@@ -164,4 +164,4 @@ import { MobileRelease, ReleaseFile, ServedReleaseFile, composeRelease, releaseM
 import { MobileReleaseAppInput, OfferedRelease, mobileReleaseApp } from "./mobile-release/release-app.js";
 import { mobileSigningKeyVariable, readSigningKey } from "./mobile-release/signing-key.js";
 import { AdminAuth, CreateAuthOptions, UserCreatedHook, normalizeRoles } from "./better-auth/create-auth.js";
-export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApiKeys, type ApiKeysOptions, type ApnsEnvironment, type AppIcons, type AppIdentity, type AppPoolConfig, type ApplyOptions, type ApplyResult, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type AuthHooks, type AuthSettings, type AuthenticateSettings, type Authenticator, type BatchOperation, type BatchResult, type BetterAuthAuthenticator, type BetterAuthAuthenticatorOptions, type Caller, type CallerOptions, type CapturedRow, type CascadingKey, type ChatMessage, type ChatTextPart, type CheckAiInput, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type CommentItem, type CommentUsers, type Completion, type CompletionOptions, ConnectionsBusy, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type Device, type DeviceColumn, type DeviceKind, type DeviceStore, DeviceStoreError, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EncryptionStatus, type EncryptionTools, type EncryptionToolsInput, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FieldApplied, type FieldStatus, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileProviderSettings, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSocket, type FunctionSource, type HistoryColumn, type HistoryOptions, type HistoryPosition, type HistoryStore, HistoryStoreError, type HookContext, HttpProblem, type IssueTokenOptions, type JobContext, type JobDeclaration, type JobDefinition, type JobOptions, type JobRun, type JobsRuntime, type JsonObject, type JsonValue, type JwtOptions, type JwtVerifyOptions, type KeyFunctionContext, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapLayer, type MapOptions, type MapSettings, type McpApprovals, type McpGateInput, type McpHandlerInput, type McpRoutesInput, type McpServerInput, type McpToolsInput, type McpWrites, type MemberInput, type Membership, MissingCredentials, type MobileConfig, type MobileRelease, type MobileReleaseAppInput, ModelError, type ModelSettings, type NewDevice, type NewNotification, type NewOrganization, type NewUser, type NotificationRecipients, NotificationSendError, type NotificationsOptions, type OfferedRelease, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PgModule, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type PngIcon, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type PushAnswer, type PushMessage, PushMessageError, type PushSender, type QueryOptions, type QueryResult, type ReadableResources, type ReasoningDetail, type ReasoningEffort, type RebindOption, type RecordKeyInput, type RecordPage, type ReleaseFile, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type SendNotification, type ServedReleaseFile, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SocketEvents, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredNotification, type StoredObject, type StoredOrganization, type StoredUser, type StrayValues, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolAnnotations, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type UnreadableEntry, type Urgency, type User, type UserCreatedHook, type VapidSettings, type ViewSource, type WebPushFields, type WebPushOptions, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, type WriteRecordToolsInput, addAppRoleToOwners, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appNameOver, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaDrift, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkResourcesOutsideAuthStore, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentsMigration, composeRelease, computedMigration, configExports, consoleAuditQueue, conversationKey, createAdmin, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultHistoryPage, defaultSignInPolicy, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, deviceIdParam, deviceStore, devicesPath, enqueueJob, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, generateVapidKeys, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, historyIdParam, historyIdPattern, historyLimits, historyPath, historyStore, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, longQueryTimeoutMs, mapSettings, mapStyleUrl, mapStyleVariable, maxDevicesPerUser, maxHistoryPage, maxMessageBytes, maxRecipients, maxTokenTtlSeconds, maxTtlSeconds, maxUnreadCount, maxWidgetPropsBytes, mcpApprovals, mcpGate, mcpHandler, mcpRoutes, mcpServer, mcpToolContext, mcpTools, migrationCommand, mobileReleaseApp, mobileSigningKeyVariable, newWebhookSecret, normalizeRoles, notFound, notificationSenders, notificationsMigration, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, poolWaitMs, postgresDeviceStore, postgresHistoryStore, processor, pushMessage, queryRunnerMigration, readDbConnections, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readSigningKey, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, recordOf, releaseManifest, removeDevicesWithUsers, removeHistoryWithUsers, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, seesAssistant, seesRuntime, sendNotification, sessionOf, setMemberRoles, setUserBanned, setUserRole, shownAppName, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, urgencies, vapidPrivateKeyVariable, vapidPublicKeyVariable, vapidSubjectVariable, variantPath, verifySignature, verifyStandardWebhook, waitUntil, wantsLongQueries, webManifestPath, webPushSender, webauthnPath, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };
+export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApiKeys, type ApiKeysOptions, type ApnsEnvironment, type AppIcons, type AppIdentity, type AppPoolConfig, type ApplyOptions, type ApplyResult, type ApprovalAnswer, type ApprovalRequest, type ArgumentsPayload, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type AuthHooks, type AuthSettings, type AuthenticateSettings, type Authenticator, type BatchOperation, type BatchResult, type BetterAuthAuthenticator, type BetterAuthAuthenticatorOptions, type Caller, type CallerOptions, type CapturedRow, type CascadingKey, type ChatMessage, type ChatTextPart, type CheckAiInput, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type CommentItem, type CommentUsers, type Completion, type CompletionOptions, ConnectionsBusy, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type Device, type DeviceColumn, type DeviceKind, type DeviceStore, DeviceStoreError, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EncryptionStatus, type EncryptionTools, type EncryptionToolsInput, type EnqueueJob, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FieldApplied, type FieldStatus, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileProviderSettings, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSocket, type FunctionSource, type HistoryColumn, type HistoryOptions, type HistoryPosition, type HistoryStore, HistoryStoreError, type HookContext, HttpProblem, type IssueTokenOptions, type JobContext, type JobDeclaration, type JobDefinition, type JobName, type JobOptions, type JobPayload, type JobRun, type JobsRuntime, type JsonObject, type JsonValue, type JwtOptions, type JwtVerifyOptions, type KeyFunctionContext, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapLayer, type MapOptions, type MapSettings, type McpApprovals, type McpGateInput, type McpHandlerInput, type McpRoutesInput, type McpServerInput, type McpToolsInput, type McpWrites, type MemberInput, type Membership, MissingCredentials, type MobileConfig, type MobileRelease, type MobileReleaseAppInput, ModelError, type ModelSettings, type NewDevice, type NewNotification, type NewOrganization, type NewUser, type NotificationRecipients, NotificationSendError, type NotificationsOptions, type OfferedRelease, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PgModule, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type PngIcon, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type PushAnswer, type PushMessage, PushMessageError, type PushSender, type QueryOptions, type QueryResult, type ReadableResources, type ReasoningDetail, type ReasoningEffort, type RebindOption, type RecordKeyInput, type RecordPage, type ReleaseFile, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type SendNotification, type ServedReleaseFile, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SocketEvents, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredNotification, type StoredObject, type StoredOrganization, type StoredUser, type StrayValues, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolAnnotations, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type UnreadableEntry, type Urgency, type User, type UserCreatedHook, type VapidSettings, type ViewSource, type WebPushFields, type WebPushOptions, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, type WriteRecordToolsInput, addAppRoleToOwners, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appNameOver, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaDrift, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkResourcesOutsideAuthStore, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentsMigration, composeRelease, computedMigration, configExports, consoleAuditQueue, conversationKey, createAdmin, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultHistoryPage, defaultSignInPolicy, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, deviceIdParam, deviceStore, devicesPath, enqueueJob, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, generateVapidKeys, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, historyIdParam, historyIdPattern, historyLimits, historyPath, historyStore, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, longQueryTimeoutMs, mapSettings, mapStyleUrl, mapStyleVariable, maxDevicesPerUser, maxHistoryPage, maxMessageBytes, maxRecipients, maxTokenTtlSeconds, maxTtlSeconds, maxUnreadCount, maxWidgetPropsBytes, mcpApprovals, mcpGate, mcpHandler, mcpRoutes, mcpServer, mcpToolContext, mcpTools, migrationCommand, mobileReleaseApp, mobileSigningKeyVariable, newWebhookSecret, normalizeRoles, notFound, notificationSenders, notificationsMigration, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, poolWaitMs, postgresDeviceStore, postgresHistoryStore, processor, pushMessage, queryRunnerMigration, readDbConnections, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readSigningKey, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, recordOf, releaseManifest, removeDevicesWithUsers, removeHistoryWithUsers, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, seesAssistant, seesRuntime, sendNotification, sessionOf, setMemberRoles, setUserBanned, setUserRole, shownAppName, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, urgencies, vapidPrivateKeyVariable, vapidPublicKeyVariable, vapidSubjectVariable, variantPath, verifySignature, verifyStandardWebhook, waitUntil, wantsLongQueries, webManifestPath, webPushSender, webauthnPath, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };

package/dist/internal.js

@@ -5,9 +5,9 @@ import { localFiles } from "./files/local-files.js";
 import { s3Files } from "./files/s3-files.js";
 import { appPool, longQueryPool } from "./app-pool.js";
 import { betterAuthAuthenticator } from "./better-auth/authenticator.js";
+import { fileProviderOf } from "./files/provider-settings.js";
 import { declaredJob } from "./jobs/declared-job.js";
 import { appAuthOptions, buildAppAuth } from "./better-auth/auth-settings.js";
 import { buildAuthenticator } from "./better-auth/authenticate-settings.js";
-import { fileProviderOf } from "./files/provider-settings.js";
 import { webhooksModule } from "./webhooks/table/webhooks-module.js";
 export { appAuthOptions, appPool, betterAuthAuthenticator, buildAppAuth, buildAuth, buildAuthenticator, checkNotificationsOptions, createAuth, declaredJob, fileProviderOf, isSubscription, loadAuthPlugins, localFiles, longQueryPool, s3Files, webhooksModule };

package/dist/jobs/declared-job.d.ts

@@ -1,5 +1,5 @@
 import { EnqueueOptions, JobContext, JobDefinition, JobOptions } from "./job-types.js";
-import { ArgumentsSpec } from "@protobase/schema";
+import { ArgumentType, ArgumentsSpec } from "@protobase/schema";
 import { Db } from "@protobase/query";
 //#region src/jobs/declared-job.d.ts
 /**
@@ -18,7 +18,42 @@ export type JobRun<Payload = Record<string, unknown>> = (payload: Payload, conte
 export declare const declaredJob: (name: string, { description: _, arguments: args, ...options }: JobDeclaration, load: () => Promise<JobRun>) => JobDefinition;
 /**
  * Enqueues the job named `name`, which the config declares, in `db`'s own transaction when it is one, and returns its
- * id: what a write hook calls, so the job commits with the write or not at all.
+ * id: what a write hook calls, so the job commits with the write or not at all. `EnqueueJob<typeof config>` types it
+ * with the config's job names and arguments.
  */
 export declare const enqueueJob: (db: Db, name: string, payload?: Record<string, unknown>, options?: EnqueueOptions) => Promise<string>;
+type TypeValue<Type> = Type extends 'integer' ? number : Type extends 'boolean' ? boolean : Type extends 'json' ? unknown : string;
+type ArgumentValue<Spec> = Spec extends ArgumentType ? TypeValue<Spec> : Spec extends {
+  type: 'enum';
+  values: readonly (infer Value)[];
+} ? Value : Spec extends {
+  type: infer Type extends ArgumentType;
+} ? TypeValue<Type> : unknown;
+type Optional<Spec> = Spec extends {
+  optional: true;
+} ? true : false;
+type Flat<Type> = { [Key in keyof Type]: Type[Key]; };
+/**
+ * The payload of a job with these arguments, as it is enqueued with it and its run gets it: `{ invoiceId: string }` for
+ * `{ invoiceId: 'bigint' }`, an argument with `optional: true` left out at will.
+ */
+export type ArgumentsPayload<Spec extends ArgumentsSpec> = Flat<{ -readonly [Name in keyof Spec as Optional<Spec[Name]> extends true ? never : Name]: ArgumentValue<Spec[Name]>; } & { -readonly [Name in keyof Spec as Optional<Spec[Name]> extends true ? Name : never]?: ArgumentValue<Spec[Name]>; }>;
+type DeclaredJobs<Config> = (Config extends ((...args: never[]) => infer Returned) ? Awaited<Returned> : Config) extends {
+  jobs?: infer Jobs;
+} ? NonNullable<Jobs> : never;
+/** The names of the jobs a config declares, from `typeof config` of its `protobase.config.ts`. */
+export type JobName<Config> = keyof DeclaredJobs<Config> & string;
+/**
+ * The payload of the job `Name` a config declares, from its `arguments` (see `ArgumentsPayload`): what the job is
+ * enqueued with and what its `JobRun` gets. A job without `arguments` takes any payload, unchecked.
+ */
+export type JobPayload<Config, Name extends JobName<Config>> = DeclaredJobs<Config>[Name] extends {
+  arguments: infer Spec extends ArgumentsSpec;
+} ? ArgumentsPayload<Spec> : Record<string, unknown>;
+/**
+ * `enqueueJob`, typed with the jobs of a config, so a name it does not declare or a payload that does not fit its
+ * arguments fails to compile: `const enqueue: EnqueueJob<typeof config> = enqueueJob`. The payload may be left out when
+ * no argument is required.
+ */
+export type EnqueueJob<Config> = <Name extends JobName<Config>>(db: Db, name: Name, ...rest: {} extends JobPayload<Config, Name> ? [payload?: JobPayload<Config, Name>, options?: EnqueueOptions] : [payload: JobPayload<Config, Name>, options?: EnqueueOptions]) => Promise<string>;
 //#endregion

package/dist/jobs/declared-job.js

@@ -14,7 +14,8 @@ const declaredJob = (name, { description: _, arguments: args, ...options }, load
 };
 /**
 * Enqueues the job named `name`, which the config declares, in `db`'s own transaction when it is one, and returns its
-* id: what a write hook calls, so the job commits with the write or not at all.
+* id: what a write hook calls, so the job commits with the write or not at all. `EnqueueJob<typeof config>` types it
+* with the config's job names and arguments.
 */
 const enqueueJob = (db, name, payload, options) => {
 	const runtime = currentJobs();

package/dist/jobs/job-types.d.ts

@@ -17,7 +17,7 @@ export type JobContext = {
   };
   /** Aborted when the job's timeout passes, or when the worker shuts down and its grace period ends. */
   signal: AbortSignal;
-  /** Sends mail through the app's SMTP server (`PROTOBASE_SMTP_URL`, `PROTOBASE_MAIL_FROM`); `undefined` when the app has no mail. */
+  /** Sends mail with the app's mailer: its auth/mailer.ts, else the SMTP server of `PROTOBASE_SMTP_URL` and `PROTOBASE_MAIL_FROM`; `undefined` when the app has no mail. */
   mail?: Mailer;
   /** Sends a notification as `sendNotification` does; `undefined` when the app has no `notifications`. */
   sendNotification?: SendNotification;

package/dist/package.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.49.0",
+  "version": "0.49.2",
   "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.2",
+    "@protobase/query": "0.49.2",
+    "@protobase/schema": "0.49.2",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",