@rebasepro/server 0.9.1-canary.fd3754b → 0.10.0

package/dist/api/errors.d.ts

@@ -9,9 +9,24 @@ export declare class ApiError extends Error {
     readonly statusCode: number;
     readonly code: string;
     readonly details?: unknown;
-    constructor(statusCode: number, code: string, message: string, details?: unknown);
+    /**
+     * Whether this outcome is a routine part of normal operation rather than
+     * something an operator should look at. Expected errors log at debug; every
+     * other operational error logs at warn.
+     *
+     * The motivating case is `POST /auth/refresh` with no session: clients
+     * refresh on page load before they know whether one exists, so every
+     * anonymous page view is a 401 — correct, and not worth a warning line.
+     */
+    readonly expected: boolean;
+    constructor(statusCode: number, code: string, message: string, details?: unknown, expected?: boolean);
     static badRequest(message: string, code?: string, details?: unknown): ApiError;
     static unauthorized(message: string, code?: string): ApiError;
+    /**
+     * A 401 that is a normal outcome, not an incident — logged at debug.
+     * See {@link ApiError.expected}.
+     */
+    static unauthenticated(message: string, code?: string): ApiError;
     static forbidden(message: string, code?: string): ApiError;
     static notFound(message: string, code?: string): ApiError;
     static conflict(message: string, code?: string): ApiError;

package/dist/api/rest/api-generator.d.ts

@@ -5,12 +5,15 @@ import { HonoEnv } from "../types";
  * Lightweight REST API generator that leverages existing Rebase DataDriver.
  * Supports `include` query parameter for eager-loading relations via Drizzle.
  */
+/** Rows accepted by a single POST /<collection>/bulk. See `maxBulkRows`. */
+export declare const DEFAULT_MAX_BULK_ROWS = 1000;
 export declare class RestApiGenerator {
     private collections;
     private router;
     private driver;
+    private maxBulkRows;
     private authAdapter?;
-    constructor(collections: CollectionConfig[], driver: DataDriver, authAdapter?: AuthAdapter);
+    constructor(collections: CollectionConfig[], driver: DataDriver, authAdapter?: AuthAdapter, maxBulkRows?: number);
     /**
      * Generate REST routes using existing DataDriver
      */
@@ -21,6 +24,15 @@ export declare class RestApiGenerator {
      * No-ops if the request is not authenticated via an API key.
      */
     private enforceApiKeyPermission;
+    /**
+     * API key permission check for nested paths. The operation targets the
+     * LAST collection in the path (e.g. "posts" for /authors/1/posts), so
+     * that is the slug the key must hold permission for — checking the
+     * parent instead would let a key scoped to "authors" write "posts".
+     * `parseSubPath` always yields a collectionPath ending in a collection
+     * slug, never an id.
+     */
+    private enforceSubcollectionApiKeyPermission;
     /**
      * Get the request-scoped driver. Throws if none is set — never falls
      * back to the unscoped `this.driver` to avoid bypassing RLS/auth.

package/dist/api/rest/write-validation.d.ts

@@ -0,0 +1,22 @@
+import { CollectionConfig } from "@rebasepro/types";
+/**
+ * Reject a write naming a field the collection does not have.
+ *
+ * Unknown keys used to travel all the way into the INSERT, where Postgres
+ * rejected them — so a typo came back as `column "titel" does not exist`,
+ * phrased by the database, from a stack the caller cannot see, and only if the
+ * column really was absent. It is a request problem and belongs in a 400.
+ *
+ * What counts as known:
+ * - a declared property (for an introspected BaaS collection these *are* the
+ *   columns, so the set is exact);
+ * - the foreign-key column behind an owning relation, which callers may write
+ *   directly instead of through the relation property;
+ * - anything named in `options.extraKnownFields` — for an auth collection the
+ *   credential keys the auth adapter consumes before a row is ever built;
+ * - nothing else. `id` in particular is not automatically known — see below.
+ */
+export declare function assertKnownWriteFields(values: Record<string, unknown>, collection: CollectionConfig, options?: {
+    rowIndex?: number;
+    extraKnownFields?: readonly string[];
+}): void;

package/dist/api/types.d.ts

@@ -1,5 +1,5 @@
 import { VectorSearchParams, LogicalCondition, FilterValues } from "@rebasepro/types";
-import { AuthResult } from "../auth/middleware";
+import type { AuthResult } from "../auth/middleware";
 import { DataDriver } from "@rebasepro/types";
 import type { ApiKeyMasked } from "../auth/api-keys/api-key-types";
 /**
@@ -9,7 +9,7 @@ import type { ApiKeyMasked } from "../auth/api-keys/api-key-types";
 export type HonoEnv = {
     Variables: {
         user?: AuthResult | {
-            userId?: string;
+            uid?: string;
             roles?: string[];
         };
         driver?: DataDriver;

package/dist/auth/admin-users-route.d.ts

@@ -3,10 +3,10 @@
  *
  * Mounts:
  *   GET /users
- *   GET /users/:userId
+ *   GET /users/:uid
  *   POST /users
- *   PUT /users/:userId
- *   DELETE /users/:userId
+ *   PUT /users/:uid
+ *   DELETE /users/:uid
  *   POST /bootstrap
  */
 import { Hono } from "hono";

package/dist/auth/api-keys/api-key-middleware.d.ts

@@ -10,9 +10,18 @@
  * 4. Sets `c.set("user", ...)` and `c.set("apiKey", ...)` for downstream use
  * 5. Scopes the DataDriver via `withAuth()` using the API key's service identity
  *
+ * Authorization is double-gated for API keys: the key's own permission list
+ * (checked by the REST generator) is one ceiling, and Postgres RLS is another,
+ * independent one — `withAuth()` runs API-key requests as the restricted
+ * `rebase_user` role like any other caller. An `admin` key passes RLS via the
+ * injected `default_admin` policies; a non-admin key (roles `["service"]`,
+ * uid `api-key:<id>`) only sees rows that a policy explicitly grants to the
+ * `service` role or to the public. Owner-style policies
+ * (`owner_id = auth.uid()`) never match an API key's synthetic uid.
+ *
  * @module
  */
-import type { Context } from "hono";
+import type { Context, MiddlewareHandler } from "hono";
 import type { DataDriver } from "@rebasepro/types";
 import type { HonoEnv } from "../../api/types";
 import type { ApiKeyStore } from "./api-key-store";
@@ -37,3 +46,53 @@ export interface ApiKeyAuthOptions {
  * `createAuthMiddleware()` when a `rk_` prefixed token is detected.
  */
 export declare function validateApiKey(c: Context<HonoEnv>, token: string, options: ApiKeyAuthOptions): Promise<Response | true>;
+/**
+ * Permission guard for API-key requests to the storage router.
+ *
+ * Storage previously did not accept API keys at all (`rk_` tokens were
+ * misparsed as JWTs and 401'd). Now that the pre-auth middleware
+ * authenticates them, this guard decides what they may do: the key needs a
+ * `"storage"` permission entry (or the global `"*"` wildcard) covering the
+ * operation derived from the HTTP method. Requests not authenticated via an
+ * API key pass through to the storage router's own auth gates.
+ *
+ * TUS resumable-upload routes (`/tus`, `/tus/:id`) are classified as `write`
+ * for EVERY method: the protocol's offset check is a GET and its cancel is a
+ * DELETE, but both are steps of an upload — a write-scoped key must be able
+ * to complete (and abort) its own resumable upload without also holding
+ * `read`/`delete` on stored objects.
+ */
+export declare function createStorageApiKeyGuard(): MiddlewareHandler<HonoEnv>;
+/**
+ * Permission guard for API-key requests to the custom-functions router.
+ *
+ * The collection permission guard lives in the REST generator and never sees
+ * function routes, so before this middleware existed ANY valid API key —
+ * however narrowly scoped — could invoke every custom function. This guard
+ * closes that: API-key requests must hold a `"functions"`/`"functions/<name>"`
+ * permission entry (or the global `"*"` wildcard) for the derived operation.
+ *
+ * Non-API-key requests (JWT, service key, anonymous) pass through untouched —
+ * functions decide their own auth for those, as before.
+ *
+ * @param mountPrefix - The path the functions router is mounted at
+ *                      (e.g. `/api/functions`), used to extract the function
+ *                      name from the request path.
+ */
+export declare function createFunctionApiKeyGuard(mountPrefix: string): MiddlewareHandler<HonoEnv>;
+/**
+ * Standalone pre-auth middleware for `rk_` bearer tokens.
+ *
+ * Routers whose auth gate is JWT-based (`requireAuth` / `createRequireAuth` —
+ * the admin surfaces: admin users/roles, api-keys management, cron, backups,
+ * logs, schema editor) don't know about API keys. Mounting this middleware in
+ * front of them authenticates `rk_` tokens and populates the request context;
+ * the downstream gates then see the already-resolved user and apply their
+ * role checks (`requireAdmin`) as usual — so an `admin: true` key passes and
+ * a non-admin key is rejected with 403.
+ *
+ * Requests without an `rk_` bearer token pass through untouched. An invalid,
+ * revoked, or expired `rk_` token is rejected here (401) rather than falling
+ * through to be misparsed as a JWT.
+ */
+export declare function createApiKeyPreAuth(options: ApiKeyAuthOptions): MiddlewareHandler<HonoEnv>;

package/dist/auth/api-keys/api-key-permission-guard.d.ts

@@ -30,3 +30,36 @@ export declare function httpMethodToOperation(method: string): ApiKeyOperation;
  * @returns `true` if the operation is permitted.
  */
 export declare function isOperationAllowed(permissions: ApiKeyPermission[], collection: string, operation: ApiKeyOperation): boolean;
+/**
+ * Check whether the given permissions array allows a storage operation.
+ *
+ * Storage, like functions, lives outside the collection namespace: an entry
+ * with collection `"storage"` grants storage access for the listed
+ * operations (GET routes → `read`, upload/folder/tus → `write`,
+ * DELETE routes → `delete`), and the global `"*"` wildcard also matches.
+ * A collection-scoped key gets no storage access at all.
+ *
+ * Matching is exactly {@link isOperationAllowed} with `"storage"` as the
+ * resource name — delegated so the semantics can never drift.
+ */
+export declare function isStorageAllowed(permissions: ApiKeyPermission[], operation: ApiKeyOperation): boolean;
+/**
+ * Check whether the given permissions array allows invoking a custom function.
+ *
+ * Functions live outside the collection namespace, so they have their own
+ * resource names in the permission list:
+ *
+ * - `{ collection: "functions", ... }` grants every function
+ * - `{ collection: "functions/<name>", ... }` grants a single function
+ * - the global `"*"` wildcard (full-access keys) also matches
+ *
+ * The operation is derived from the HTTP method as usual (GET → read,
+ * POST/PUT/PATCH → write, DELETE → delete). The functions index route is
+ * checked as `functionName === ""`, which only the `"functions"` and `"*"`
+ * entries can grant.
+ *
+ * A collection-scoped key (e.g. read-only on `events`) therefore can NOT
+ * invoke functions — before this guard existed, any valid key could call
+ * every function.
+ */
+export declare function isFunctionAllowed(permissions: ApiKeyPermission[], functionName: string, operation: ApiKeyOperation): boolean;

package/dist/auth/api-keys/api-key-types.d.ts

@@ -10,10 +10,13 @@
 /**
  * A single permission entry scoping an API key to a collection and set of operations.
  *
- * Use `"*"` as the collection value to grant access to all collections.
+ * Use `"*"` as the collection value to grant access to all collections
+ * (and all custom functions). Custom functions are addressed with the
+ * `functions` namespace: `"functions"` grants every function,
+ * `"functions/<name>"` grants a single one.
  */
 export interface ApiKeyPermission {
-    /** Collection slug, or `"*"` for all collections. */
+    /** Collection slug, `"functions"`/`"functions/<name>"`, or `"*"` for everything. */
     collection: string;
     /** Allowed operations on the collection. */
     operations: ("read" | "write" | "delete")[];
@@ -30,9 +33,19 @@ export interface ApiKey {
     /** SHA-256 hash of the full plaintext key. */
     key_hash: string;
     permissions: ApiKeyPermission[];
-    /** When true, the key is granted the `admin` role (access to admin routes). */
+    /**
+     * When true, the key is granted the `admin` role: it passes the
+     * admin-gated routes (users, roles, cron, backups, logs, API keys) and
+     * the RLS `default_admin` policies. Non-admin keys carry only the
+     * `service` role — RLS grants them nothing unless a collection policy
+     * explicitly names that role.
+     */
     admin: boolean;
-    /** Requests per 15-minute window. `null` means unlimited. */
+    /**
+     * Requests per 15-minute window. `null` means "no per-key override" —
+     * the data rate limiter then applies its default API-key limit
+     * (1000/window unless configured otherwise), not unlimited.
+     */
     rate_limit: number | null;
     created_by: string;
     created_at: string;
@@ -50,7 +63,7 @@ export interface ApiKeyMasked {
     name: string;
     key_prefix: string;
     permissions: ApiKeyPermission[];
-    /** When true, the key is granted the `admin` role (access to admin routes). */
+    /** When true, the key is granted the `admin` role (admin routes + RLS `default_admin` policies). */
     admin: boolean;
     rate_limit: number | null;
     created_by: string;
@@ -66,9 +79,9 @@ export interface ApiKeyMasked {
 export interface CreateApiKeyRequest {
     name: string;
     permissions: ApiKeyPermission[];
-    /** When true, grants the `admin` role — allows access to admin routes. */
+    /** When true, grants the `admin` role (admin routes + RLS `default_admin` policies). */
     admin?: boolean;
-    /** Requests per 15-minute window. Omit or `null` for unlimited. */
+    /** Requests per 15-minute window. Omit or `null` to use the server default (1000/window). */
     rate_limit?: number | null;
     /** ISO-8601 expiration timestamp. Omit for no expiration. */
     expires_at?: string | null;
@@ -80,7 +93,7 @@ export interface CreateApiKeyRequest {
 export interface UpdateApiKeyRequest {
     name?: string;
     permissions?: ApiKeyPermission[];
-    /** When true, grants the `admin` role — allows access to admin routes. */
+    /** When true, grants the `admin` role (admin routes + RLS `default_admin` policies). */
     admin?: boolean;
     rate_limit?: number | null;
     expires_at?: string | null;

package/dist/auth/api-keys/index.d.ts

@@ -9,9 +9,9 @@
 export type { ApiKey, ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest } from "./api-key-types";
 export { createApiKeyStore } from "./api-key-store";
 export type { ApiKeyStore } from "./api-key-store";
-export { isApiKeyToken, validateApiKey } from "./api-key-middleware";
+export { isApiKeyToken, validateApiKey, createApiKeyPreAuth, createFunctionApiKeyGuard, createStorageApiKeyGuard } from "./api-key-middleware";
 export type { ApiKeyAuthOptions } from "./api-key-middleware";
-export { httpMethodToOperation, isOperationAllowed } from "./api-key-permission-guard";
+export { httpMethodToOperation, isOperationAllowed, isFunctionAllowed, isStorageAllowed } from "./api-key-permission-guard";
 export type { ApiKeyOperation } from "./api-key-permission-guard";
 export { createApiKeyRoutes } from "./api-key-routes";
 export type { ApiKeyRouteOptions } from "./api-key-routes";

package/dist/auth/auth-hooks.d.ts

@@ -135,7 +135,7 @@ export interface AuthHooks {
      *
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
-    afterLogout?(userId: string): Promise<void>;
+    afterLogout?(uid: string): Promise<void>;
     /**
      * Called after successful MFA verification.
      *
@@ -143,12 +143,12 @@ export interface AuthHooks {
      *
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
-    onMfaVerified?(userId: string, factorId: string): Promise<void>;
+    onMfaVerified?(uid: string, factorId: string): Promise<void>;
     /**
      * Customize JWT access token claims before signing.
      *
      * Return the modified claims object. The returned claims are merged
-     * into the JWT payload alongside standard claims (userId, roles).
+     * into the JWT payload alongside standard claims (uid, roles).
      *
      * @param claims - The default claims that would be included.
      * @param user - The authenticated user data.
@@ -178,14 +178,14 @@ export interface AuthHooks {
      *
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
-    onPasswordReset?(userId: string): Promise<void>;
+    onPasswordReset?(uid: string): Promise<void>;
     /**
      * Called before a user is deleted.
      *
      * Throw an error to prevent deletion (e.g. for users with active
      * subscriptions, pending transactions, etc.).
      */
-    beforeUserDelete?(userId: string): Promise<void>;
+    beforeUserDelete?(uid: string): Promise<void>;
     /**
      * Called after a user is deleted.
      *
@@ -193,7 +193,7 @@ export interface AuthHooks {
      *
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
-    afterUserDelete?(userId: string): Promise<void>;
+    afterUserDelete?(uid: string): Promise<void>;
     /**
      * Optional hook to customize or override the default user creation flow via the admin panel/REST API.
      * When provided, this replaces the built-in password generation, hashing, and invitation email logic.
@@ -212,7 +212,7 @@ export interface AuthHooks {
      * Optional hook to customize or override the default password reset flow via the admin panel.
      * When provided, this replaces the built-in password reset token generation, hashing, and email logic.
      */
-    onAdminResetPassword?(userId: string, ctx: {
+    onAdminResetPassword?(uid: string, ctx: {
         authRepo: AuthRepository;
         emailService?: EmailService;
         emailConfig?: EmailConfig;

package/dist/auth/collection-callback-warning.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Warn when the auth collection hangs data callbacks that auth will not fire.
+ *
+ * Creating a user through the auth subsystem — registration, OAuth, the admin
+ * user routes — writes to the user store directly, because that path owns
+ * password hashing, identity rows and its own transaction. It deliberately does
+ * not go through the collection save pipeline: a `beforeSave` able to rewrite
+ * `password_hash` on its way to the database is a footgun, not a feature, and
+ * the auth hooks (`afterUserCreate`, `beforeUserCreate`, …) exist to hang
+ * behaviour off those events with the right contract.
+ *
+ * The cost is a reasonable expectation quietly not being met: someone puts
+ * "send the welcome email" in `afterSave` on their users collection, tests it
+ * by creating a user in the admin, and it works — because *that* is a
+ * collection write. Then a real signup does nothing at all. Which is why this
+ * is said at boot, naming the callbacks that will not run.
+ */
+export declare function warnOnAuthCollectionDataCallbacks(collection?: {
+    slug?: string;
+    callbacks?: Record<string, unknown>;
+}): void;

package/dist/auth/index.d.ts

@@ -28,7 +28,10 @@ export type { AuthModuleConfig, CookieAuthConfig } from "./routes";
 export { mountMagicLinkRoutes } from "./magic-link-routes";
 export { createResetPasswordRoute } from "./reset-password-admin";
 export type { ResetPasswordRouteConfig } from "./reset-password-admin";
-export { createRateLimiter, defaultAuthLimiter, strictAuthLimiter, createApiKeyRateLimiter, apiKeyKeyGenerator } from "./rate-limiter";
+export { createRateLimiter, defaultAuthLimiter, strictAuthLimiter, createApiKeyRateLimiter, createDataRateLimiter, apiKeyKeyGenerator } from "./rate-limiter";
+export type { DataRateLimitConfig } from "./rate-limiter";
+export { MemoryRateLimitStore } from "./rate-limit-store";
+export type { RateLimitStore, RateLimitDecision } from "./rate-limit-store";
 export { createApiKeyStore, createApiKeyRoutes, isApiKeyToken, validateApiKey, httpMethodToOperation, isOperationAllowed } from "./api-keys";
 export type { ApiKey, ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest, ApiKeyStore, ApiKeyOperation } from "./api-keys";
 export { createBuiltinAuthAdapter } from "./builtin-auth-adapter";

package/dist/auth/interfaces.d.ts

@@ -40,7 +40,7 @@ export interface CreateUserData {
  */
 export interface UserIdentityData {
     id: string;
-    userId: string;
+    uid: string;
     provider: string;
     providerId: string;
     profileData?: Record<string, unknown> | null;
@@ -113,7 +113,7 @@ export interface CreateRoleData {
  */
 export interface RefreshTokenInfo {
     id: string;
-    userId: string;
+    uid: string;
     tokenHash: string;
     expiresAt: Date;
     createdAt: Date;
@@ -124,14 +124,14 @@ export interface RefreshTokenInfo {
  * Password reset token info
  */
 export interface PasswordResetTokenInfo {
-    userId: string;
+    uid: string;
     expiresAt: Date;
 }
 /**
  * Magic link token info
  */
 export interface MagicLinkTokenInfo {
-    userId: string;
+    uid: string;
     expiresAt: Date;
 }
 /**
@@ -185,11 +185,11 @@ export interface UserRepository {
     /**
      * Get all identities linked to a user
      */
-    getUserIdentities(userId: string): Promise<UserIdentityData[]>;
+    getUserIdentities(uid: string): Promise<UserIdentityData[]>;
     /**
      * Link a new OAuth identity to a user
      */
-    linkUserIdentity(userId: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
+    linkUserIdentity(uid: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
     /**
      * Update a user
      */
@@ -225,23 +225,23 @@ export interface UserRepository {
     /**
      * Get roles for a user
      */
-    getUserRoles(userId: string): Promise<RoleData[]>;
+    getUserRoles(uid: string): Promise<RoleData[]>;
     /**
      * Get role IDs for a user
      */
-    getUserRoleIds(userId: string): Promise<string[]>;
+    getUserRoleIds(uid: string): Promise<string[]>;
     /**
      * Set roles for a user (replaces existing roles)
      */
-    setUserRoles(userId: string, roleIds: string[]): Promise<void>;
+    setUserRoles(uid: string, roleIds: string[]): Promise<void>;
     /**
      * Assign a specific role to a new user
      */
-    assignDefaultRole(userId: string, roleId: string): Promise<void>;
+    assignDefaultRole(uid: string, roleId: string): Promise<void>;
     /**
      * Get user with their roles
      */
-    getUserWithRoles(userId: string): Promise<{
+    getUserWithRoles(uid: string): Promise<{
         user: UserData;
         roles: RoleData[];
     } | null>;
@@ -280,7 +280,7 @@ export interface TokenRepository {
     /**
      * Create a new refresh token
      */
-    createRefreshToken(userId: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
+    createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
     /**
      * Find a refresh token by hash
      */
@@ -292,19 +292,19 @@ export interface TokenRepository {
     /**
      * Delete all refresh tokens for a user
      */
-    deleteAllRefreshTokensForUser(userId: string): Promise<void>;
+    deleteAllRefreshTokensForUser(uid: string): Promise<void>;
     /**
      * List all refresh tokens for a user
      */
-    listRefreshTokensForUser(userId: string): Promise<RefreshTokenInfo[]>;
+    listRefreshTokensForUser(uid: string): Promise<RefreshTokenInfo[]>;
     /**
      * Delete a specific refresh token by its primary key ID
      */
-    deleteRefreshTokenById(id: string, userId: string): Promise<void>;
+    deleteRefreshTokenById(id: string, uid: string): Promise<void>;
     /**
      * Create a password reset token
      */
-    createPasswordResetToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    createPasswordResetToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     /**
      * Find a valid (not expired, not used) password reset token by hash
      */
@@ -316,7 +316,7 @@ export interface TokenRepository {
     /**
      * Delete all password reset tokens for a user
      */
-    deleteAllPasswordResetTokensForUser(userId: string): Promise<void>;
+    deleteAllPasswordResetTokensForUser(uid: string): Promise<void>;
     /**
      * Clean up expired tokens
      */
@@ -324,7 +324,7 @@ export interface TokenRepository {
     /**
      * Create a magic link token
      */
-    createMagicLinkToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    createMagicLinkToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     /**
      * Find a valid (not expired, not used) magic link token by hash
      */
@@ -339,7 +339,7 @@ export interface TokenRepository {
  */
 export interface MfaFactor {
     id: string;
-    userId: string;
+    uid: string;
     factorType: "totp";
     friendlyName?: string;
     verified: boolean;
@@ -361,7 +361,7 @@ export interface MfaChallengeInfo {
  */
 export interface RecoveryCode {
     id: string;
-    userId: string;
+    uid: string;
     usedAt?: Date;
 }
 /**
@@ -372,11 +372,11 @@ export interface MfaRepository {
     /**
      * Create a new MFA factor for a user
      */
-    createMfaFactor(userId: string, factorType: "totp", secretEncrypted: string, friendlyName?: string): Promise<MfaFactor>;
+    createMfaFactor(uid: string, factorType: "totp", secretEncrypted: string, friendlyName?: string): Promise<MfaFactor>;
     /**
      * Get all MFA factors for a user
      */
-    getMfaFactors(userId: string): Promise<MfaFactor[]>;
+    getMfaFactors(uid: string): Promise<MfaFactor[]>;
     /**
      * Get a specific MFA factor by ID
      */
@@ -390,7 +390,7 @@ export interface MfaRepository {
     /**
      * Delete an MFA factor
      */
-    deleteMfaFactor(factorId: string, userId: string): Promise<void>;
+    deleteMfaFactor(factorId: string, uid: string): Promise<void>;
     /**
      * Create an MFA challenge
      */
@@ -406,23 +406,23 @@ export interface MfaRepository {
     /**
      * Create recovery codes for a user
      */
-    createRecoveryCodes(userId: string, codeHashes: string[]): Promise<void>;
+    createRecoveryCodes(uid: string, codeHashes: string[]): Promise<void>;
     /**
      * Use a recovery code (mark as used)
      */
-    useRecoveryCode(userId: string, codeHash: string): Promise<boolean>;
+    useRecoveryCode(uid: string, codeHash: string): Promise<boolean>;
     /**
      * Get unused recovery code count for a user
      */
-    getUnusedRecoveryCodeCount(userId: string): Promise<number>;
+    getUnusedRecoveryCodeCount(uid: string): Promise<number>;
     /**
      * Delete all recovery codes for a user
      */
-    deleteAllRecoveryCodes(userId: string): Promise<void>;
+    deleteAllRecoveryCodes(uid: string): Promise<void>;
     /**
      * Check if a user has any verified MFA factors
      */
-    hasVerifiedMfaFactors(userId: string): Promise<boolean>;
+    hasVerifiedMfaFactors(uid: string): Promise<boolean>;
 }
 /**
  * Combined auth repository interface for convenience

package/dist/auth/jwt.d.ts

@@ -4,9 +4,14 @@ export interface JwtConfig {
     refreshExpiresIn?: string;
 }
 export interface AccessTokenPayload {
-    userId: string;
+    /**
+     * The user's id — the same spelling the domain model, the auth adapters and
+     * the RLS layer (`auth.uid()`) all use. Tokens minted before this rename
+     * carry `uid` instead, and older external IdPs may send `sub`;
+     * {@link verifyAccessToken} accepts all three and normalises to this.
+     */
+    uid: string;
     roles: string[];
-    uid?: string;
     /** Authentication Assurance Level: aal1 = password/oauth, aal2 = MFA verified */
     aal?: "aal1" | "aal2";
     /** Email claim from the JWT, if present */
@@ -28,7 +33,7 @@ export declare function configureJwt(config: JwtConfig): void;
 /**
  * Generate an access token (short-lived, 1 hour by default)
  */
-export declare function generateAccessToken(userId: string, roles: string[], aal?: "aal1" | "aal2", customClaims?: Record<string, unknown>): string;
+export declare function generateAccessToken(uid: string, roles: string[], aal?: "aal1" | "aal2", customClaims?: Record<string, unknown>): string;
 /**
  * Get the expiration time of an access token in milliseconds from now
  */
@@ -38,7 +43,18 @@ export declare function getAccessTokenExpiryMs(): number;
  */
 export declare function getAccessTokenExpiry(): number;
 /**
- * Verify and decode an access token
+ * Verify and decode an access token.
+ *
+ * Every token this server issues is signed with the same secret, so what a
+ * token *is* comes from its claims, not from its signature. A download token
+ * ({@link generateDownloadToken}) is therefore a validly-signed string that
+ * must never authenticate anybody: it is scoped to one file path and handed out
+ * in URLs, which is a far weaker thing to hold than a session.
+ *
+ * Today it is rejected below for want of an id — but only by luck, since
+ * nothing stops a future download token from carrying one. So the purpose is
+ * checked explicitly: a token minted for reading a file is not a token for
+ * being a user.
  */
 export declare function verifyAccessToken(token: string): AccessTokenPayload | null;
 /**

package/dist/auth/magic-link-routes.d.ts

@@ -23,10 +23,10 @@ export declare function mountMagicLinkRoutes(deps: {
         isAnonymous?: boolean;
         metadata?: Record<string, unknown> | null;
     }, roleIds: string[], accessToken: string, refreshToken: string, providerId: string) => unknown;
-    createSessionAndTokens: (userId: string, userAgent: string, ipAddress: string) => Promise<{
+    createSessionAndTokens: (uid: string, userAgent: string, ipAddress: string) => Promise<{
         roleIds: string[];
         accessToken: string;
         refreshToken: string;
     }>;
-    applyTransformHook: (response: AuthResponsePayload, method: TransformAuthResponseContext["method"], request: Request, userId: string) => Promise<AuthResponsePayload>;
+    applyTransformHook: (response: AuthResponsePayload, method: TransformAuthResponseContext["method"], request: Request, uid: string) => Promise<AuthResponsePayload>;
 }): void;