@rebasepro/server 0.22.0 → 0.24.0

package/dist/auth/email-change-routes.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A signed-in user changes their own email address.
+ *
+ * `POST /auth/change-email { newEmail }` records the change and mails a link to
+ * the new address, and a notice without a link to the old one.
+ * `POST /auth/confirm-email-change { token }` — the link's landing screen calls
+ * it — moves the account onto the new address.
+ *
+ * The address moves only when its inbox answers, so the account is never
+ * pointed at an address nobody proved, and nothing is reserved meanwhile: a
+ * pending change that held the address would let any account keep a stranger
+ * from signing up with their own address. Whoever has the address when the link
+ * is followed keeps it, and the link answers 409.
+ *
+ * On confirmation the address is the account's, verified. The identities whose
+ * provider vouched for the old address are detached: the old address may be
+ * the reason for the change — a job left, an inbox lost — and whoever controls
+ * it now would otherwise sign in through that provider. The sessions stay: the
+ * change was asked for from one, and the link proves the new inbox, not
+ * anything about the others.
+ *
+ * @module
+ */
+import { Hono } from "hono";
+import { z } from "zod";
+import type { HonoEnv } from "../api/types.js";
+import type { MiddlewareHandler } from "hono";
+import type { resolveAuthHooks } from "./auth-hooks.js";
+import type { AuthModuleConfig } from "./routes.js";
+/** How long an address-change link stays usable. */
+export declare const EMAIL_CHANGE_TTL_MS: number;
+interface EmailChangeRoutesConfig {
+    router: Hono<HonoEnv>;
+    config: AuthModuleConfig;
+    ops: ReturnType<typeof resolveAuthHooks>;
+    parseBody: <T>(schema: z.ZodSchema<T>, body: unknown) => T;
+    /** A signed-in user, with the revocation watermark consulted. */
+    requireLiveSession: MiddlewareHandler<HonoEnv>;
+}
+export declare function mountEmailChangeRoutes(opts: EmailChangeRoutesConfig): void;
+export {};

package/dist/auth/expired-token-sweep.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Deleting the auth tokens nobody can use any more, on a schedule.
+ *
+ * `TokenRepository.deleteExpiredTokens` was declared, implemented and never
+ * called. Every expired reset link, magic link, email code, abandoned refresh
+ * token and stale MFA challenge stayed in the database for good: the tables
+ * grew by a row per sign-in attempt and nothing took one away.
+ *
+ * Runs on the process that owns the timers (`ownership.cronScheduler`), once
+ * an hour, and across instances once per hour in all: each tick claims its
+ * hour's slot in `rebase.cron_claims` — the claim the cron scheduler takes for
+ * a job's run — and only the instance that wins it sweeps. A store that cannot
+ * answer the claim means no sweep this hour rather than every instance at
+ * once; the tokens are already refused when presented, so a late sweep costs
+ * space, not safety.
+ *
+ * @module
+ */
+import type { DataDriver } from "@rebasepro/types";
+import type { TokenRepository } from "./interfaces.js";
+/** The slot key in `rebase.cron_claims`. Namespaced so no job file can take it. */
+export declare const EXPIRED_TOKEN_SWEEP_JOB_ID = "rebase:auth:expired-tokens";
+/** One sweep an hour, fleet-wide. */
+export declare const EXPIRED_TOKEN_SWEEP_INTERVAL_MS: number;
+export interface ExpiredTokenSweepOptions {
+    authRepo: Pick<TokenRepository, "deleteExpiredTokens">;
+    /**
+     * Claim `slot` for `jobId` across every instance: `true` for the one that
+     * wins it. Throws when the store cannot tell. Without it — a driver with
+     * no SQL, cron persistence switched off — every instance sweeps, which is
+     * wasted work but harmless: deleting what has expired is idempotent.
+     */
+    claimSlot?: (jobId: string, slot: string) => Promise<boolean>;
+    intervalMs?: number;
+    /** Clock, for tests. */
+    now?: () => number;
+}
+/** What one tick did. */
+export type ExpiredTokenSweepOutcome = "swept" | "claimed-elsewhere" | "unclaimed" | "failed";
+export interface ExpiredTokenSweep {
+    /** Sweep now, then once per interval. */
+    start(): void;
+    stop(): void;
+    /** One tick: claim this interval's slot and, if it is ours, sweep. */
+    runSlot(): Promise<ExpiredTokenSweepOutcome>;
+}
+export declare function createExpiredTokenSweep(options: ExpiredTokenSweepOptions): ExpiredTokenSweep;
+/** What {@link startExpiredTokenSweep} is given by the boot. */
+export interface ExpiredTokenSweepWiring {
+    /** The auth repository, when the backend has one. */
+    authRepo?: Partial<Pick<TokenRepository, "deleteExpiredTokens">>;
+    /** The default data driver: its SQL admin backs the slot claim. */
+    driver: DataDriver;
+    /** Whether this process owns the timers (`ownership.cronScheduler`). */
+    ownsTimers: boolean;
+    /** `cronPersistence: false` keeps the claims table out of the database, here too. */
+    persistClaims?: boolean;
+}
+/**
+ * Start the sweep where it belongs, or answer `undefined` where it does not:
+ * a process that does not own the timers, or a backend whose auth repository
+ * cannot delete expired tokens.
+ *
+ * The claim is the cron store's, made on the first tick rather than at boot so
+ * the boot does not wait on its tables.
+ */
+export declare function startExpiredTokenSweep(wiring: ExpiredTokenSweepWiring): ExpiredTokenSweep | undefined;

package/dist/auth/impersonation.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Running a request as another user: the `x-rebase-impersonate` header, and
+ * the `impersonate` field of the realtime socket's `AUTHENTICATE`.
+ *
+ * It exists for an administrator checking what one user can see and do — "can
+ * B read A's rows, can B write them?" — against the real policies, from
+ * Studio's API explorer and JS editor. A granted request runs as one of B's
+ * own would: B's uid, B's roles as they are now, B's guest flag and the claims
+ * a token minted for B now would carry reach `withAuth`, so the statement runs
+ * as `rebase_user` with B's identity and every policy is evaluated for B.
+ *
+ * Who may: a signed-in administrator, on their own session, judged on their
+ * roles as the database has them now rather than as their token claims. Never
+ * an API key — not a personal key whose owner is an administrator either — and
+ * never the service key. Impersonation is a person checking on another person,
+ * and the audit line has to name one.
+ *
+ * Where: the data API, custom functions and the realtime socket. Every other
+ * route refuses the header ({@link refuseUnhonouredImpersonation}).
+ *
+ * Fail closed: a request asking to act as someone either runs as the user it
+ * names or is refused. It never runs as its caller, because that is the
+ * failure this exists to end — a response showing the administrator's rows
+ * under a label saying they were B's.
+ *
+ * @module
+ */
+import type { Context, MiddlewareHandler } from "hono";
+import { type AuthenticatedUser, type DataDriver } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types.js";
+import { ApiError } from "../api/errors.js";
+/** How the caller authenticated, as far as impersonation is concerned. */
+export type ImpersonationCredential = "session" | "api-key" | "service-key" | "none";
+/** How the auth in use turns a uid into a request identity — `AuthAdapter.resolveUser`. */
+export type ImpersonationUserResolver = (uid: string) => Promise<AuthenticatedUser | null>;
+export interface ImpersonationRequest {
+    /** The uid the request asked to act as, as sent. */
+    requestedUid: string;
+    /** What the caller presented. Only a `session` may impersonate. */
+    credential: ImpersonationCredential;
+    /** The caller, as their credential verified. */
+    caller?: {
+        uid: string;
+        roles: readonly string[];
+    };
+    /** Absent when the auth in use has no `resolveUser`: then nobody may. */
+    resolveUser?: ImpersonationUserResolver;
+    /**
+     * Where the request came in, for the security audit line — or absent to
+     * write none, for a decision that only re-confirms one already logged
+     * (the socket re-asks before every frame).
+     */
+    audit?: Record<string, unknown>;
+}
+/** The answer to a request to act as another user. */
+export type ImpersonationDecision = {
+    granted: AuthenticatedUser;
+    impersonator: string;
+} | {
+    refused: ApiError;
+};
+/**
+ * Decide whether this caller may act as the user they named, and who that
+ * user is now.
+ *
+ * The one decision both doors take — the HTTP data plane through
+ * {@link applyImpersonation}, the realtime socket at `AUTHENTICATE` and before
+ * every frame after it. The caller is judged before the named user is looked
+ * up, so the answer to a caller who may not impersonate says nothing about
+ * whether the uid exists.
+ *
+ * Throws when a lookup fails: that is not an answer about anyone, and each
+ * door refuses it its own way.
+ */
+export declare function decideImpersonation(request: ImpersonationRequest): Promise<ImpersonationDecision>;
+export interface ImpersonationOptions {
+    /** What the caller presented. Only a `session` may impersonate. */
+    credential: ImpersonationCredential;
+    /** The unscoped delegate the request's driver was scoped from. */
+    driver: DataDriver;
+    /** The auth adapter's `resolveUser`. Absent: the header is refused for everyone. */
+    resolveUser?: ImpersonationUserResolver;
+}
+/**
+ * Honour or refuse this request's {@link IMPERSONATE_HEADER}.
+ *
+ * Called by the data-plane auth middlewares once the caller is on the context
+ * and its driver is scoped. When the header names a user the caller may act
+ * as, the context's `user` and `driver` are replaced with that user's and
+ * `impersonator` names the caller.
+ *
+ * @returns The refusal to send, or `undefined` to carry on — as the caller
+ *          when the header is absent, as the named user when it was granted.
+ */
+export declare function applyImpersonation(c: Context<HonoEnv>, { credential, driver, resolveUser }: ImpersonationOptions): Promise<Response | undefined>;
+/**
+ * Refuse {@link IMPERSONATE_HEADER} on every route that does not honour it.
+ *
+ * Only the data API and custom functions run a request as another user; the
+ * rest — storage, auth, the admin surfaces — authenticate the caller and
+ * ignore the header. Ignored, a request asking to act as B would be answered
+ * as the administrator who sent it, which is the one outcome impersonation
+ * must never have. Mounted ahead of every route, so a surface added later is
+ * refused until it is listed here as honouring the header.
+ *
+ * @param honouredMounts - The mount points whose auth middleware applies the
+ *        header (`/api/data`, `/api/functions`). A path is under one when it
+ *        is the mount itself or continues it with a `/`.
+ */
+export declare function refuseUnhonouredImpersonation(honouredMounts: readonly string[]): MiddlewareHandler<HonoEnv>;

package/dist/auth/index.d.ts

@@ -49,8 +49,10 @@ export { createSqlRateLimitStore } from "./sql-rate-limit-store.js";
 export type { SqlRateLimitStoreOptions } from "./sql-rate-limit-store.js";
 export { resolveRateLimitStoreKind, RateLimitStoreConfigurationError } from "./resolve-rate-limit-store.js";
 export type { RateLimitStoreKind, RateLimitStoreEnv } from "./resolve-rate-limit-store.js";
-export { createApiKeyStore, createApiKeyRoutes, isApiKeyToken, validateApiKey, httpMethodToOperation, isOperationAllowed } from "./api-keys/index.js";
-export type { ApiKey, ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest, ApiKeyStore, ApiKeyOperation } from "./api-keys/index.js";
+export { createApiKeyStore, createApiKeyRoutes, createPersonalKeyRoutes, isApiKeyToken, resolveApiKey, validateApiKey, httpMethodToOperation } from "./api-keys/index.js";
+export type { ApiKey, ApiKeyKind, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, CreatePersonalKeyRequest, UpdateApiKeyRequest, ApiKeyStore, DataOperation, KeyTargets } from "./api-keys/index.js";
+export { requireScope, requireScopeByMethod, hasScope, callerScopes, getAccessModel, configureAccess, accessModelFromCollections, AccessModelError } from "./access.js";
+export type { KeyOwnerResolver } from "./access.js";
 export { createBuiltinAuthAdapter } from "./builtin-auth-adapter.js";
 export type { BuiltinAuthAdapterConfig } from "./builtin-auth-adapter.js";
 export { createCustomAuthAdapter } from "./custom-auth-adapter.js";

package/dist/auth/interfaces.d.ts

@@ -19,6 +19,11 @@ export interface UserData {
     emailVerificationToken?: string | null;
     emailVerificationSentAt?: Date | null;
     isAnonymous?: boolean;
+    /**
+     * An administrator switched the account off: no sign-in, no refresh, and
+     * no token it already holds is honoured. See `setUserDisabled`.
+     */
+    disabled?: boolean;
     metadata?: Record<string, unknown>;
     createdAt: Date;
     updatedAt: Date;
@@ -35,6 +40,16 @@ export interface CreateUserData {
     isAnonymous?: boolean;
     metadata?: Record<string, unknown>;
 }
+/**
+ * An address change waiting for its confirmation link. See
+ * {@link UserRepository.setPendingEmailChange}.
+ */
+export interface PendingEmailChange {
+    /** The address the account is moving to, normalized. */
+    email: string;
+    /** When the link was mailed; it is refused 24 hours after this. */
+    sentAt: Date;
+}
 /**
  * User Identity Data (OAuth accounts linked to user)
  */
@@ -92,36 +107,6 @@ export interface OAuthProvider<T = unknown> {
      */
     verify(payload: T): Promise<OAuthProviderProfile | null>;
 }
-/**
- * Role data structure
- */
-export interface RoleData {
-    id: string;
-    name: string;
-    isAdmin: boolean;
-    defaultPermissions: {
-        read?: boolean;
-        create?: boolean;
-        edit?: boolean;
-        delete?: boolean;
-    } | null;
-    collectionPermissions: Record<string, {
-        read?: boolean;
-        create?: boolean;
-        edit?: boolean;
-        delete?: boolean;
-    }> | null;
-}
-/**
- * Data for creating a new role
- */
-export interface CreateRoleData {
-    id: string;
-    name: string;
-    isAdmin?: boolean;
-    defaultPermissions?: RoleData["defaultPermissions"];
-    collectionPermissions?: RoleData["collectionPermissions"];
-}
 /**
  * Refresh token info
  */
@@ -161,6 +146,31 @@ export interface RefreshTokenInfo {
      * that do not store it; both read as `aal1`, the restrictive value.
      */
     aal?: "aal1" | "aal2";
+    /**
+     * How the session was signed in — `"password"`, `"anonymous"`,
+     * `"magic-link"`, `"otp"`, `"mfa"` or a provider id such as `"google"`.
+     * See {@link RefreshTokenSession.method}. Absent on rows written before
+     * the column existed, which read as `"password"`.
+     */
+    method?: string;
+}
+/**
+ * What {@link TokenRepository.getAccountAccessState} reads about an account
+ * that exists.
+ */
+export interface AccountAccessState {
+    /** The account's roles as the database has them now. */
+    roles: string[];
+    /** The revocation watermark: sessions that began before it are void. */
+    tokensValidAfter: Date | null;
+    /**
+     * Whether the session asked about has a refresh token that is not
+     * revoked. `undefined` when no session was asked about, or the store
+     * cannot tell (a refresh-token table without session grouping).
+     */
+    sessionActive?: boolean;
+    /** The account is switched off (`UserData.disabled`). */
+    disabled?: boolean;
 }
 /**
  * Identity of the sign-in a refresh token belongs to, threaded through
@@ -179,6 +189,28 @@ export interface RefreshTokenSession {
      * assurance level is a property of the *sign-in*, not of the account.
      */
     aal?: "aal1" | "aal2";
+    /**
+     * How the session was signed in: what `providerId` says in every auth
+     * response for it. Written at sign-in and carried across rotations like
+     * {@link aal}, because a refresh is not a sign-in and has nothing else to
+     * read it from — answering `"password"` there turned a Google session into
+     * a password one an access-token lifetime after it began.
+     */
+    method?: string;
+    /**
+     * The hash of the token this one replaces, when it is minted by rotating
+     * one. A repository that honours it writes the new token only while that
+     * token is still live — present and not revoked — decided in the same
+     * transaction as the write, and answers `false` from
+     * {@link TokenRepository.createRefreshToken} when it is not.
+     *
+     * That is the sign-out that landed while the rotation was in flight: the
+     * refresh read a live token, the logout revoked every row of the session,
+     * and the refresh then wrote a new, unrevoked row into it — in cookie mode
+     * re-setting the cookie, so the sign-out silently did not happen. A
+     * repository that ignores this keeps that race.
+     */
+    rotatedFrom?: string;
 }
 /**
  * Password reset token info
@@ -202,7 +234,11 @@ export interface ListUsersOptions {
     limit?: number;
     /** Number of results to skip (default 0) */
     offset?: number;
-    /** Search term — matches against email and displayName (case-insensitive) */
+    /**
+     * Search term — a case-insensitive substring of the email, the display
+     * name, any role the user holds, or the uid. (The Postgres store matches
+     * all four; the Mongo store, email and display name.)
+     */
     search?: string;
     /** Field to sort by (default "createdAt") */
     orderBy?: string;
@@ -263,6 +299,15 @@ export interface UserRepository {
      * Link a new OAuth identity to a user
      */
     linkUserIdentity(uid: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
+    /**
+     * Detach one OAuth identity from a user.
+     *
+     * Used when the owner of an address proves it for the first time, to
+     * remove the identities someone attached to the account before anyone had
+     * proven the address. Optional: a repository without it cannot do that,
+     * and such a proof is refused rather than leaving the identities in place.
+     */
+    unlinkUserIdentity?(uid: string, provider: string, providerId: string): Promise<void>;
     /**
      * Update a user
      */
@@ -280,9 +325,10 @@ export interface UserRepository {
      */
     listUsersPaginated(options?: ListUsersOptions): Promise<PaginatedUsersResult>;
     /**
-     * Update user's password hash
+     * Update user's password hash. `null` removes the password: the account
+     * then signs in only by link, code or provider.
      */
-    updatePassword(id: string, passwordHash: string): Promise<void>;
+    updatePassword(id: string, passwordHash: string | null): Promise<void>;
     /**
      * Set email verification status
      */
@@ -295,10 +341,6 @@ export interface UserRepository {
      * Find user by email verification token
      */
     getUserByVerificationToken(token: string): Promise<UserData | null>;
-    /**
-     * Get roles for a user
-     */
-    getUserRoles(uid: string): Promise<RoleData[]>;
     /**
      * Get role IDs for a user
      */
@@ -316,34 +358,45 @@ export interface UserRepository {
      */
     getUserWithRoles(uid: string): Promise<{
         user: UserData;
-        roles: RoleData[];
+        roles: string[];
     } | null>;
-}
-/**
- * Abstract role repository interface.
- * Handles all role-related database operations.
- */
-export interface RoleRepository {
-    /**
-     * Get a role by ID
-     */
-    getRoleById(id: string): Promise<RoleData | null>;
     /**
-     * List all roles
+     * Switch an account off, or back on. Off, it cannot sign in or refresh,
+     * and the tokens it holds are refused (`judgeAccessToken`). Optional: a
+     * repository without it cannot disable accounts, and the admin route says
+     * so rather than pretending.
      */
-    listRoles(): Promise<RoleData[]>;
+    setUserDisabled?(uid: string, disabled: boolean): Promise<void>;
     /**
-     * Create a new role
-     */
-    createRole(data: CreateRoleData): Promise<RoleData>;
-    /**
-     * Update a role
-     */
-    updateRole(id: string, data: Partial<Omit<RoleData, "id">>): Promise<RoleData | null>;
+     * Record the address an account is moving to and the hash of the token
+     * mailed there, stamped now — or with `null`, drop it. One per account: a
+     * new request replaces the last, and its link stops working.
+     *
+     * Nothing is reserved by it. The address stays free for anyone to
+     * register until the link is followed, because a pending change that held
+     * it would let any account lock a stranger out of signing up with their
+     * own address.
+     */
+    setPendingEmailChange?(uid: string, change: {
+        email: string;
+        tokenHash: string;
+    } | null): Promise<void>;
+    /** The account's pending change, if it has one. */
+    getPendingEmailChange?(uid: string): Promise<PendingEmailChange | null>;
+    /** The account whose pending change `tokenHash` confirms, with the change. */
+    findPendingEmailChange?(tokenHash: string): Promise<{
+        user: UserData;
+        change: PendingEmailChange;
+    } | null>;
     /**
-     * Delete a role
+     * Move the account onto its pending address, in one write that holds only
+     * while `tokenHash` is still that change's token: the address becomes the
+     * account's, verified, and the pending change and any outstanding
+     * verification token are cleared. `null` when the token no longer names
+     * the change (confirmed already, replaced, cancelled). An address another
+     * account holds by then is a 409 `EMAIL_EXISTS`, as `updateUser` answers.
      */
-    deleteRole(id: string): Promise<void>;
+    applyPendingEmailChange?(uid: string, tokenHash: string): Promise<UserData | null>;
 }
 /**
  * Abstract token repository interface.
@@ -357,8 +410,12 @@ export interface TokenRepository {
      * optional so that repositories written against an older release keep
      * satisfying this interface; implementations that ignore it degrade to one
      * session per token.
+     *
+     * Resolves `false` when `session.rotatedFrom` names a token that is no
+     * longer live, in which case nothing was written. Anything else means the
+     * token was written.
      */
-    createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<void>;
+    createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<boolean | void>;
     /**
      * Mark a token as superseded by a rotation, WITHOUT making it unusable.
      *
@@ -390,6 +447,24 @@ export interface TokenRepository {
      * user's tokens so a rotation racing the delete cannot survive it.
      */
     setTokensValidAfter?(uid: string, at: Date): Promise<void>;
+    /**
+     * Everything an access token is judged against, in one read — or `null`
+     * when there is no such account.
+     *
+     * An access token is a bearer credential minted up to an hour ago, and the
+     * account it names may since have been deleted, revoked or demoted. Every
+     * door that honours one asks this before it does: the data plane, the admin
+     * gates, the realtime socket on every frame. See `judgeAccessToken`.
+     *
+     * `sessionId` is the token's `sid`: when given, the state also says
+     * whether that sign-in is still live, which is how signing one device out
+     * reaches the access token that device holds.
+     *
+     * Optional. Without it the judge composes the answer from
+     * `getUserWithRoles` and `getTokensValidAfter`, two reads instead of one,
+     * and cannot see one revoked session — only every session at once.
+     */
+    getAccountAccessState?(uid: string, sessionId?: string): Promise<AccountAccessState | null>;
     /**
      * Find a refresh token by hash
      */
@@ -427,7 +502,11 @@ export interface TokenRepository {
      */
     deleteAllPasswordResetTokensForUser(uid: string): Promise<void>;
     /**
-     * Clean up expired tokens
+     * Delete every token past its expiry: reset links, magic links and email
+     * codes, refresh tokens, and whatever else the repository keeps that
+     * expires. A token is refused when presented whether or not this has run,
+     * so it is housekeeping, not revocation. The server calls it once an hour
+     * on one instance of the fleet (`startExpiredTokenSweep`).
      */
     deleteExpiredTokens(): Promise<void>;
     /**
@@ -571,9 +650,11 @@ export interface MfaRepository {
      */
     claimMfaFactorCounter?(factorId: string, counter: number): Promise<boolean>;
     /**
-     * Record a failed verification against a challenge and return the new
-     * total. Atomic (`UPDATE … SET attempts = attempts + 1 RETURNING attempts`)
-     * so concurrent guesses cannot share one increment.
+     * Record a verification attempt against a challenge and return the new
+     * total. The route claims it before judging the code and refuses a claim
+     * past the cap, so this count is the cap. Atomic (`UPDATE … SET attempts =
+     * attempts + 1 RETURNING attempts`) so concurrent guesses cannot share
+     * one increment.
      *
      * Optional; where it is absent the route falls back to the rate limiters
      * alone.
@@ -583,5 +664,5 @@ export interface MfaRepository {
 /**
  * Combined auth repository interface for convenience
  */
-export interface AuthRepository extends UserRepository, RoleRepository, TokenRepository, MfaRepository {
+export interface AuthRepository extends UserRepository, TokenRepository, MfaRepository {
 }