@rebasepro/server 0.23.0 → 0.24.0

package/dist/auth/platform-token.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Platform tokens: a short-lived credential the platform hosting this server
+ * mints for one person, for one project, for a few read-only scopes.
+ *
+ * ## Why this exists
+ *
+ * On Rebase Cloud the owner of a project is signed in to the *control plane*,
+ * not to their own app. Their app's admin surfaces — the cron job list and its
+ * run history first — accept an admin user of the app, an `rk_` key, or the
+ * service key, and an owner may hold none of them: a fresh deploy has no admin
+ * account, and the service key is admin on the whole API, which is the wrong
+ * thing to hand someone who wants to read why last night's job failed.
+ *
+ * So the control plane signs a token instead. It checks the caller's project
+ * membership, then signs `{ aud: <project>, sub: <who>, scope: "cron:read" }`
+ * with a key only it holds, valid for minutes. This server verifies it against
+ * the public half — `REBASE_PLATFORM_TOKEN_KEY` — which the platform sets at
+ * deploy. Nothing secret lives in the tenant: the env holds a public key, and
+ * leaking it lets nobody mint anything.
+ *
+ * ## What a platform token can never do
+ *
+ * - **Exceed {@link PLATFORM_TOKEN_SCOPES}.** The token names scopes; this
+ *   server grants only the ones on that list, whatever the platform signed. The
+ *   ceiling lives here, in the tenant's code, so a compromised or buggy control
+ *   plane cannot widen it.
+ * - **Outlive {@link PLATFORM_TOKEN_MAX_LIFETIME_SECONDS}.** A token whose
+ *   `exp - iat` is longer is refused, not clamped: a long-lived platform token
+ *   is a static secret by another name.
+ * - **Reach another project.** One platform key signs for every tenant, so the
+ *   audience is what binds a token to this one: `aud` must equal
+ *   `REBASE_PLATFORM_TOKEN_AUDIENCE`.
+ * - **Act as a person of this app.** The caller is `platform:<sub>` with no
+ *   roles: row-level security sees nobody it knows, and every surface that
+ *   checks a scope other than the granted ones refuses it.
+ *
+ * ## Wire format
+ *
+ * `rpt_` followed by a compact ES256 JWS. The prefix keeps the credential
+ * classes apart the way `rk_` does: a platform token is never tried as a user
+ * session, and a user session is never tried as a platform token.
+ *
+ * @module
+ */
+import type { MiddlewareHandler } from "hono";
+import type { AdminScope } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types.js";
+/** Marks a bearer token as a platform token. */
+export declare const PLATFORM_TOKEN_PREFIX = "rpt_";
+/** The `iss` every platform token carries. */
+export declare const PLATFORM_TOKEN_ISSUER = "rebase-cloud";
+/**
+ * Everything a platform token can be granted on this server.
+ *
+ * Read-only on purpose. Adding a scope here is a decision about what the
+ * platform may do inside a customer's app on a person's behalf, and belongs in
+ * its own change.
+ */
+export declare const PLATFORM_TOKEN_SCOPES: readonly AdminScope[];
+/** The longest `exp - iat` a platform token may declare. */
+export declare const PLATFORM_TOKEN_MAX_LIFETIME_SECONDS = 600;
+/** The environment variables a platform sets to turn platform tokens on. */
+export declare const PLATFORM_TOKEN_KEY_ENV = "REBASE_PLATFORM_TOKEN_KEY";
+export declare const PLATFORM_TOKEN_AUDIENCE_ENV = "REBASE_PLATFORM_TOKEN_AUDIENCE";
+/** What this server verifies platform tokens against. */
+export interface PlatformTokenConfig {
+    /**
+     * PEM-encoded SPKI public keys, EC P-256. More than one during a key
+     * rotation: a token verifies against any of them.
+     */
+    publicKeys: string[];
+    /** This project, as the platform names it in `aud`. */
+    audience: string;
+}
+/** A verified platform token, as the request will act. */
+export interface PlatformCaller {
+    /** Who the platform minted it for — a control-plane account. */
+    subject: string;
+    /** The granted scopes: what the token asked for, within the ceiling. */
+    scopes: string[];
+    /** `jti`, when the platform set one — what an audit line quotes. */
+    tokenId?: string;
+}
+/** Why a presented platform token does not authenticate. */
+export interface PlatformTokenRefusal {
+    refusal: string;
+}
+export declare function isPlatformToken(token: string): boolean;
+/**
+ * The PEM blocks in an env value: real newlines, `\n`-escaped ones (what a
+ * one-line `.env` holds), or the whole thing base64-encoded.
+ */
+export declare function parsePublicKeys(value: string): string[];
+/**
+ * Read the platform-token configuration from the environment.
+ *
+ * `undefined` when platform tokens are off — neither variable set, which is
+ * every self-hosted server — or misconfigured. A misconfiguration is logged and
+ * leaves them off rather than failing the boot: the platform set these values,
+ * the app's owner cannot fix them, and the app serving traffic matters more
+ * than its cron history being readable from the CLI.
+ */
+export declare function platformTokensFromEnv(env: Record<string, string | undefined>): Promise<PlatformTokenConfig | undefined>;
+/**
+ * Verify a presented platform token: signature, issuer, audience, lifetime, and
+ * the scopes it may be granted here.
+ */
+export declare function verifyPlatformToken(token: string, config: PlatformTokenConfig, nowSeconds?: number): Promise<PlatformCaller | PlatformTokenRefusal>;
+/**
+ * Authenticate an `rpt_` bearer token ahead of an admin gate.
+ *
+ * Mounted where the `rk_` pre-auth is, and shaped like it: a request it does not
+ * recognise passes through untouched, a recognised one either becomes a caller
+ * with narrowed `scopes` or is refused here. The gate's scope check then decides
+ * — so a token holding `cron:read` reads cron, and is a 403 on every other
+ * surface.
+ *
+ * With `config` undefined, platform tokens are off on this server; an `rpt_`
+ * token is still recognised, so its holder learns that rather than the generic
+ * "invalid token" a JWT parser would answer.
+ */
+export declare function createPlatformTokenPreAuth(config: PlatformTokenConfig | undefined): MiddlewareHandler<HonoEnv>;

package/dist/auth/rate-limiter.d.ts

@@ -83,6 +83,41 @@ export declare function setSharedRateLimitStore(store: RateLimitStore | undefine
  * Uses a sliding window: only hits within the last `windowMs` are counted.
  */
 export declare function createRateLimiter(options?: RateLimiterOptions): MiddlewareHandler<HonoEnv>;
+/**
+ * Default key generator: the client's address, from the most trustworthy source
+ * this deployment has.
+ *
+ * `X-Forwarded-For` is a client-writable header; only the entries appended by
+ * trusted reverse proxies can be believed. With `trustedProxyHops` proxies in
+ * front, each appends the address it saw, so the real client IP is the
+ * `trustedProxyHops`-th entry from the right — everything further left is
+ * client-supplied and must be ignored. This is what prevents a caller from
+ * spoofing `X-Forwarded-For` to spread its requests across many rate-limit keys.
+ *
+ * `X-Real-IP` is the *same* kind of header and needs the same rule, which it
+ * did not have: it was read unconditionally, including under
+ * `trustedProxyHops === 0` — the mode whose entire meaning is "no proxy is in
+ * front of me". With no proxy there, nothing writes `X-Real-IP` except the
+ * caller, so the key was theirs to choose: one header per request bought an
+ * unlimited number of buckets, and the limiters on login, registration and
+ * password reset counted to one. The reasoning had been done carefully for one
+ * spelling of a proxy header and not carried to its twin.
+ *
+ * So `X-Real-IP` is now believed only where a proxy is declared to exist. With
+ * none, the connection's own address is used — unforgeable, and available
+ * because the server runs on `@hono/node-server`. `"unknown"` is the last
+ * resort only, and it is a single shared bucket by design: better that
+ * anonymous callers throttle each other than that any of them throttles nobody.
+ */
+/**
+ * Where a request comes from, as the rate limiters judge it: the socket's own
+ * address, or — only behind as many proxies as `TRUSTED_PROXY_HOPS` declares —
+ * the address they report. What a session row records as its IP, so the
+ * sessions list shows the same address the limiter counted, rather than the
+ * raw `X-Forwarded-For` (whose leftmost entry the caller chooses) or
+ * `"unknown"` for every direct connection.
+ */
+export declare function requestClientAddress(c: Parameters<MiddlewareHandler<HonoEnv>>[0]): string;
 /**
  * Pre-configured rate limiter for general auth endpoints (login, register).
  * 200 requests per 15 minutes per IP.
@@ -209,6 +244,12 @@ export interface DataRateLimitConfig {
     anonymousFunctions?: number | null;
     /** Share counts across replicas. Defaults to this process's memory. */
     store?: RateLimitStore;
+    /**
+     * The deployment's service key, recognised as a Bearer before any auth
+     * middleware has run — the storage router's limiter runs ahead of its
+     * routes' auth — and never limited. See {@link dataRateLimitBuckets}.
+     */
+    serviceKey?: string;
 }
 /** @see DataRateLimitConfig.anonymousFunctions */
 export declare const DEFAULT_FUNCTIONS_ANONYMOUS_LIMIT = 3000;

package/dist/auth/routes.d.ts

@@ -4,6 +4,8 @@ import type { AuthHooks } from "./auth-hooks.js";
 import { EmailService, EmailConfig } from "../email/index.js";
 import { HonoEnv } from "../api/types.js";
 import { type CaptchaConfig } from "./captcha.js";
+import { isDeliverableAddress } from "./deliverable-address.js";
+export { isDeliverableAddress };
 /**
  * Shared configuration for auth and admin route factories.
  */
@@ -86,7 +88,30 @@ export interface AuthModuleConfig {
      * how long a captured token stays useful to someone who copied it.
      */
     refreshTokenReuseIntervalSeconds?: number;
+    /**
+     * Let a magic-link or email-code request for an address with no account
+     * create one (no password, unverified until the link or code is used),
+     * while registration is open. Off by default. See `passwordless-signup.ts`.
+     */
+    magicLinkCreatesUsers?: boolean;
+    /**
+     * What a refresh token presented after its reuse window does to its
+     * session. See `RebaseAuthConfig.refreshTokenReuse`. Default `"reject"`.
+     */
+    refreshTokenReuse?: RefreshTokenReusePolicy;
+    /**
+     * Refuse password sign-in until the account's address is verified, and
+     * register confirm-first: `POST /auth/register` answers the same "check
+     * your inbox" whether or not the address already has an account, and
+     * signs nobody in. Off by default. Needs email; the boot refuses it
+     * without. See `RebaseAuthConfig.requireEmailVerification`.
+     */
+    requireEmailVerification?: boolean;
 }
+/** What a refresh token replayed after its reuse window does to its session. */
+export type RefreshTokenReusePolicy = "reject" | "revoke-session";
+/** How long an email-verification link stays usable. */
+export declare const EMAIL_VERIFICATION_TTL_MS: number;
 /**
  * Configuration for httpOnly refresh-token cookies.
  */
@@ -109,4 +134,24 @@ export interface CookieAuthConfig {
      */
     secure?: boolean;
 }
+/**
+ * What {@link CreateSessionAndTokens} is told about the sign-in it opens.
+ *
+ * `method` is what `providerId` says for the session from now on — stored on
+ * its refresh token and carried across every rotation — so each door names
+ * its own rather than leaving it to a default.
+ */
+export interface SessionOptions {
+    /** `"password"`, `"anonymous"`, `"magic-link"`, `"otp"`, `"mfa"` or a provider id. */
+    method: string;
+    /** Only for the route that has just seen the second factor. */
+    skipMfaGate?: boolean;
+    aal?: "aal1" | "aal2";
+}
+/** Mint a session, as every sign-in door does. See `createSessionAndTokens`. */
+export type CreateSessionAndTokens = (uid: string, userAgent: string, ipAddress: string, options: SessionOptions) => Promise<{
+    roleIds: string[];
+    accessToken: string;
+    refreshToken: string;
+}>;
 export declare function createAuthRoutes(config: AuthModuleConfig): Hono<HonoEnv>;

package/dist/auth/scope-routes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `GET /auth/scopes` — every scope this backend knows, described, and the
+ * ones the caller holds.
+ *
+ * What a screen needs to offer scopes for a key or a role: the built-in ones,
+ * the app's own `auth.scopes`, their wording and what their targets name. Any
+ * authenticated caller may read it; it describes the backend's vocabulary,
+ * not anybody's data.
+ *
+ * @module
+ */
+import { Hono, type MiddlewareHandler } from "hono";
+import type { AccessJudgeRepository } from "./token-revocation.js";
+import type { HonoEnv } from "../api/types.js";
+export interface ScopeRouteOptions {
+    serviceKey?: string;
+    resolveRoles?: (uid: string) => Promise<string[]>;
+    revocationRepo?: AccessJudgeRepository;
+    /** Authenticates `rk_` keys first, so a key can read what it holds. */
+    apiKeyPreAuth?: MiddlewareHandler<HonoEnv>;
+}
+export declare function createScopeRoutes(options: ScopeRouteOptions): Hono<HonoEnv>;

package/dist/auth/session-routes.d.ts

@@ -2,7 +2,7 @@ import { Hono } from "hono";
 import { z } from "zod";
 import { HonoEnv } from "../api/types.js";
 import type { MiddlewareHandler } from "hono";
-import type { AuthModuleConfig } from "./routes.js";
+import type { AuthModuleConfig, CreateSessionAndTokens } from "./routes.js";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
 import type { resolveAuthHooks } from "./auth-hooks.js";
 interface SessionRoutesConfig {
@@ -28,11 +28,7 @@ interface SessionRoutesConfig {
         isAnonymous?: boolean;
         metadata?: Record<string, unknown> | null;
     }, roleIds: string[], accessToken: string, refreshToken: string, providerId: string) => unknown;
-    createSessionAndTokens: (uid: string, userAgent: string, ipAddress: string) => Promise<{
-        roleIds: string[];
-        accessToken: string;
-        refreshToken: string;
-    }>;
+    createSessionAndTokens: CreateSessionAndTokens;
     applyTransformHook: (response: AuthResponsePayload, method: TransformAuthResponseContext["method"], request: Request, uid: string) => Promise<AuthResponsePayload>;
     /**
      * The `register` captcha, built by the caller so a misconfiguration fails
@@ -41,6 +37,15 @@ interface SessionRoutesConfig {
      * `/register`. Absent when captcha is off or `register` is not protected.
      */
     registerCaptcha?: MiddlewareHandler<HonoEnv>;
+    /**
+     * Mail the account a verification link, in the background. Upgrading a
+     * guest is registration, and registration starts the address proof.
+     */
+    sendVerificationMail?: (user: {
+        id: string;
+        email: string;
+        displayName?: string | null;
+    }) => void;
 }
 export declare function mountSessionRoutes(opts: SessionRoutesConfig): void;
 export {};

package/dist/auth/token-revocation.d.ts

@@ -37,6 +37,55 @@ import type { AccessTokenPayload } from "./jwt.js";
  * failure is logged at warn so it is visible rather than silent.
  */
 export declare function isAccessTokenRevoked(authRepo: Pick<AuthRepository, "getTokensValidAfter">, payload: Pick<AccessTokenPayload, "uid" | "iat">): Promise<boolean>;
+/**
+ * The repository reads {@link judgeAccessToken} may make. All optional: a
+ * repository answers what it can, and the judge says what it could not ask.
+ */
+export type AccessJudgeRepository = Partial<Pick<AuthRepository, "getAccountAccessState" | "getUserWithRoles" | "getTokensValidAfter">>;
+/**
+ * Why an access token that verifies is not honoured.
+ *
+ * - `revoked`: issued before the account's revocation watermark — a sign-out
+ *   everywhere, a password change or reset.
+ * - `session-revoked`: its own sign-in was ended — `POST /auth/logout`, or
+ *   `DELETE /auth/sessions/:id` from another device. Needs the token's `sid`.
+ * - `account-deleted`: the account it names no longer exists.
+ * - `account-disabled`: an administrator switched the account off.
+ */
+export type AccessTokenRefusal = "revoked" | "session-revoked" | "account-deleted" | "account-disabled";
+export type AccessTokenVerdict = {
+    live: true;
+    /**
+     * The account's roles now, or `undefined` when the repository could
+     * not say (it reads neither the account nor its roles).
+     */
+    roles?: string[];
+} | {
+    live: false;
+    refusal: AccessTokenRefusal;
+};
+/**
+ * Is the account behind this verified access token still the one that may use
+ * it — and with which roles?
+ *
+ * A verified signature says who the token was minted for, an hour ago at
+ * most. This asks the database what has happened to that account since. Every
+ * door that honours an access token — the data plane, the admin gates, the
+ * realtime socket — asks it here, so they cannot disagree about it.
+ *
+ * They did. A deleted account read as "not revoked": the watermark lives on
+ * the user row, so once the row was gone there was no watermark, and the
+ * roles lookup answered `[]` rather than "nobody". A token its owner had
+ * revoked came back to life when an administrator deleted the account, as an
+ * authenticated principal with that uid, for the rest of its lifetime. MCP
+ * refresh and personal API keys already treated a missing account as revoked;
+ * the main door did not.
+ *
+ * Throws when the repository does. Unlike the watermark read on its own, this
+ * one decides the roles a request runs with, so a failure is a refusal (the
+ * callers answer 503) rather than a guess.
+ */
+export declare function judgeAccessToken(authRepo: AccessJudgeRepository, payload: Pick<AccessTokenPayload, "uid" | "iat" | "sid">): Promise<AccessTokenVerdict>;
 /**
  * End every session this user holds, on every device.
  *
@@ -72,4 +121,4 @@ export declare function revokeAllSessions(authRepo: Pick<AuthRepository, "delete
  * `null` removes the password instead, for the same reason and with the same
  * revocation: see `confirmAddressOwnership`.
  */
-export declare function replaceUserPassword(authRepo: Pick<AuthRepository, "updatePassword" | "deleteAllRefreshTokensForUser" | "setTokensValidAfter">, uid: string, passwordHash: string | null): Promise<void>;
+export declare function replaceUserPassword(authRepo: Pick<AuthRepository, "updatePassword" | "deleteAllRefreshTokensForUser" | "setTokensValidAfter"> & Partial<Pick<AuthRepository, "deleteAllPasswordResetTokensForUser">>, uid: string, passwordHash: string | null): Promise<void>;

package/dist/auth/verify-credential.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Verify a bearer credential outside the HTTP middlewares — for a custom
+ * socket, a tunnel, anything an app authenticates from a frame or a header it
+ * read itself.
+ *
+ * One answer for the two kinds of credential a person can hold: a session
+ * token, and an API key (`rk_`). Both come back as who the caller acts as and
+ * what it may do, so the endpoint checks a scope the same way either way.
+ *
+ * @module
+ */
+import type { ApiKeyStore } from "./api-keys/api-key-store.js";
+/** Who a verified credential acts as, and what it may do. */
+export interface VerifiedCredential {
+    uid: string;
+    roles: string[];
+    scopes: string[];
+    /** `"api-key"` when an `rk_` key was presented, otherwise `"session"`. */
+    kind: "session" | "api-key";
+}
+/** Install the key store `verifyCredential` checks `rk_` keys against. Called once at boot. */
+export declare function configureCredentialStore(store: ApiKeyStore | undefined): void;
+/**
+ * The identity and scopes behind a bearer credential, or null when it does
+ * not verify — expired, revoked, unknown, or a key on a backend with no key
+ * store.
+ */
+export declare function verifyCredential(token: string): Promise<VerifiedCredential | null>;