@rebasepro/server 0.14.0 → 0.14.1

package/dist/api/rest/query-parser.d.ts

@@ -1,6 +1,42 @@
-import type { ListLimitBounds } from "@rebasepro/types";
+import type { ListLimitBounds, OrderByTuple } from "@rebasepro/types";
 import { QueryOptions } from "../types";
 export declare const mapOperator: (op: string) => import("@rebasepro/types").WhereFilterOp | null;
+type OrderByEntry = {
+    field: string;
+    direction: "asc" | "desc";
+};
+/**
+ * The parsed entries as the driver contract spells them: `[field, direction]`
+ * tuples in order of significance.
+ *
+ * The REST layer used to hand the driver `orderBy[0].field` and drop the rest,
+ * so `?orderBy=[{"field":"roles"},{"field":"created_at","direction":"desc"}]`
+ * — a shape this parser has always accepted and validated in full — sorted by
+ * `roles` alone and returned the ties in whatever order Postgres pleased.
+ */
+export declare function orderByEntriesToTuples(entries?: OrderByEntry[]): OrderByTuple[] | undefined;
+export interface ParsedAggregate {
+    fn: "count" | "sum" | "avg" | "min" | "max";
+    /** Absent only for `count()`, which counts rows rather than values. */
+    field?: string;
+    /** The key this appears under in the response. */
+    alias: string;
+}
+/**
+ * Parse `?select=count(),sum(total),avg(total)`.
+ *
+ * The spelling is SQL's, because whoever writes it is thinking in SQL and
+ * because any other spelling has to be learned first. `count()` with no field
+ * counts rows; every other function names a column.
+ *
+ * Aliases are derived rather than accepted: `sum(total)` returns as
+ * `sum_total`, `count()` as `count`. Letting a caller choose would mean
+ * checking their alias is not also a `groupBy` field — a rule nobody would
+ * guess, and a silently overwritten value if it went unchecked.
+ */
+export declare function parseAggregateSelect(raw: unknown): ParsedAggregate[] | undefined;
+/** Parse `?groupBy=status,country`. */
+export declare function parseGroupBy(raw: unknown): string[] | undefined;
 export { DEFAULT_LIST_LIMIT, DEFAULT_VECTOR_LIST_LIMIT, MAX_LIST_LIMIT } from "@rebasepro/types";
 /**
  * Overridable list-pagination bounds for {@link parseQueryOptions}. Without

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

@@ -85,3 +85,29 @@ export declare function assertWriteValuesValid(values: Record<string, unknown>,
 export declare function projectResponseFields<T extends Record<string, unknown>>(rows: T[], fields: readonly string[] | undefined, collection: CollectionConfig, options?: {
     include?: readonly string[];
 }): T[];
+/**
+ * Both write checks, as one call, for a transport that is not the REST router.
+ *
+ * The REST routes run `assertKnownWriteFields` and `assertWriteValuesValid`
+ * back to back on the caller's body, seven times over — and they were the only
+ * place either ran. The WebSocket `SAVE` handler took a client payload straight
+ * to `driver.save`, so the same write arrived validated through one door and
+ * unvalidated through the other: `PATCH /api/data/users/1 { age: 999 }` was a
+ * 400, and the socket wrote it.
+ *
+ * Exported for the sockets in `@rebasepro/server-postgres` and
+ * `@rebasepro/server-mongo`, which are the other request boundaries. Not the
+ * route builder — `index.ts` keeps that internal, and this is a rule rather
+ * than wiring.
+ *
+ * It stays at the boundary rather than moving into the driver deliberately: it
+ * validates what a *caller sent*, before `beforeSave` gets a chance to fill in
+ * or rewrite anything. In-process writes through `rebase.data` are trusted
+ * server code and are not run through it, which is the placement the REST layer
+ * already chose.
+ *
+ * @param values     the caller's payload, exactly as it arrived
+ * @param collection resolved from the registry by path — never the copy the
+ *                   client sent, or the rules would be the caller's to pick
+ */
+export declare function assertWriteRequestValid(values: Record<string, unknown>, collection: CollectionConfig): void;

package/dist/auth/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./interfaces";
-export { configureJwt, isJwtConfigured, generateAccessToken, verifyAccessToken, generateRefreshToken, hashRefreshToken, getRefreshTokenExpiry, getAccessTokenExpiry, generateDownloadToken, verifyDownloadToken } from "./jwt";
+export { configureJwt, isJwtConfigured, generateAccessToken, verifyAccessToken, generateRefreshToken, hashRefreshToken, getRefreshTokenExpiry, getAccessTokenExpiry, generateDownloadToken, verifyDownloadToken, getJwks, hasAsymmetricSigningKey } from "./jwt";
 export type { JwtConfig, AccessTokenPayload, DownloadTokenPayload } from "./jwt";
+export { createJwksRoutes } from "./jwks-routes";
+export type { JwtSigningKeyConfig, JwtSigningAlgorithm, PublicJwk } from "./jwt-keys";
 export { hashPassword, verifyPassword, validatePasswordStrength } from "./password";
 export { safeCompare } from "./crypto-utils";
 export type { PasswordValidationResult } from "./password";

package/dist/auth/interfaces.d.ts

@@ -227,7 +227,20 @@ export interface PaginatedUsersResult {
  */
 export interface UserRepository {
     /**
-     * Create a new user
+     * Create a new user.
+     *
+     * **An email already in use is a 409 `EMAIL_EXISTS`, not a 500.** Every
+     * caller checks first — `POST /auth/register` reads `getUserByEmail` and
+     * answers 409 — and every engine backs that check with a unique index,
+     * because a check cannot hold its answer still. What is left is the window
+     * between the two, and a double-clicked signup button is wide enough: both
+     * requests read "no such user", both insert, one wins.
+     *
+     * The loser's insert violates the index either way; the only question is
+     * what it is turned into. An unmapped driver error is a 500 "Internal
+     * Server Error", which tells the person who clicked twice that the server
+     * is broken rather than that they already have an account — and tells the
+     * operator to go looking for a fault that is not there.
      */
     createUser(data: CreateUserData): Promise<UserData>;
     /**

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

@@ -0,0 +1,17 @@
+import { Hono } from "hono";
+import type { HonoEnv } from "../api/types";
+/**
+ * `GET /.well-known/jwks.json` — the public keys that verify this issuer's
+ * access tokens.
+ *
+ * Deliberately unauthenticated and world-readable: the whole point is that a
+ * gateway, an edge function or a neighbouring service can check a Rebase token
+ * without being trusted with anything. Public keys are not a secret, and
+ * `jwt-keys.ts` derives what is served here from the public half of each pair.
+ *
+ * Mounted at the root rather than under `basePath`, because `/.well-known/` is
+ * where every verifier looks — an issuer of `https://api.example.com` implies
+ * `https://api.example.com/.well-known/jwks.json`, whatever the API happens to
+ * be prefixed with.
+ */
+export declare function createJwksRoutes(): Hono<HonoEnv>;

package/dist/auth/jwt-keys.d.ts

@@ -0,0 +1,108 @@
+import { type KeyObject } from "crypto";
+/**
+ * Asymmetric signing keys for access tokens, and the JWKS built from them.
+ *
+ * The symmetric secret this replaces is not going away — it still signs every
+ * purpose-scoped token (download, MFA-pending, password reset), which are read
+ * only by the server that minted them and are better off short. What a shared
+ * secret cannot do is let *anybody else* verify a session:
+ *
+ *  - a gateway, an edge worker, or a second service that wants to check a token
+ *    has to be handed the key that mints them, so every verifier becomes a
+ *    forger;
+ *  - and rotating it invalidates every token in circulation at once, which is
+ *    why in practice it never gets rotated at all.
+ *
+ * A private key signs, the matching public key verifies, and the public half is
+ * published at `/.well-known/jwks.json` for anyone to fetch. Rotation stops
+ * being an outage: mint with the new key, keep the old one in the list until
+ * the last token signed by it has expired, then drop it.
+ *
+ * **The key is chosen by `kid`, and the algorithm comes from the key — never
+ * from the token.** A verifier that reads `alg` out of the header it is
+ * checking will accept an `HS256` token whose "secret" is the RSA public key it
+ * published, which is a complete authentication bypass and the best-known way
+ * to get this wrong. {@link resolveVerificationKey} therefore returns the
+ * algorithm alongside the key, and the caller pins it.
+ */
+/** The algorithms a signing key may use. Both are widely supported by verifiers. */
+export type JwtSigningAlgorithm = "RS256" | "ES256";
+/**
+ * One asymmetric key pair, as an operator configures it.
+ *
+ * Only the private key is supplied: the public half is derived from it, so a
+ * mismatched pair — a configuration error that produces tokens nobody can
+ * verify, and which no amount of local testing catches because the signer never
+ * consults the public key — cannot be expressed.
+ */
+export interface JwtSigningKeyConfig {
+    /**
+     * Names this key in the token header and in the JWKS. Any stable string;
+     * something that identifies *when* it was minted (`"2026-08"`) is the usual
+     * choice, because the question you ask of a `kid` later is always "is this
+     * the old one?".
+     */
+    kid: string;
+    /** PEM-encoded PKCS#8 or SEC1 private key. */
+    privateKey: string;
+    /**
+     * Defaults to the algorithm implied by the key type — RSA keys sign RS256,
+     * EC keys sign ES256. Worth setting only to be explicit.
+     */
+    algorithm?: JwtSigningAlgorithm;
+}
+/** A configured key, parsed and ready to sign or verify with. */
+export interface ResolvedJwtKey {
+    kid: string;
+    algorithm: JwtSigningAlgorithm;
+    privateKey: KeyObject;
+    publicKey: KeyObject;
+}
+/** A JSON Web Key, as served by the JWKS endpoint. Public parameters only. */
+export type PublicJwk = Record<string, unknown> & {
+    kid: string;
+    alg: JwtSigningAlgorithm;
+    use: "sig";
+};
+/**
+ * Parse the configured keys, deriving each public half from its private key.
+ *
+ * Throws on anything malformed. This runs at boot, from `configureJwt`, so a
+ * key that cannot sign takes the process down at start rather than at the first
+ * login — the same bargain every other credential in this file makes.
+ */
+export declare function resolveSigningKeys(configs: JwtSigningKeyConfig[]): ResolvedJwtKey[];
+/**
+ * The key a token names, or `null` if it names none we hold.
+ *
+ * The returned algorithm is the *key's*, and the caller must verify with that
+ * one alone. See the module docblock for what happens otherwise.
+ */
+export declare function resolveVerificationKey(keys: ResolvedJwtKey[], kid: string | undefined): ResolvedJwtKey | null;
+/**
+ * A PEM as an environment variable can actually carry it.
+ *
+ * A PEM is multi-line and environment variables are not, so every deployment
+ * tool solves it differently: `.env` files and most secret managers escape the
+ * newlines to `\n`, Kubernetes and Docker secrets pass the bytes through
+ * intact, and CI systems that mangle both are usually fed base64. All three
+ * arrive here, and guessing wrong produces "not a readable PEM private key" at
+ * boot with a key the operator can see is perfectly valid.
+ *
+ * Detection is on content, not on a flag: a PEM says so on its first line, and
+ * anything that does not is tried as base64.
+ */
+export declare function normalizePemFromEnv(value: string): string;
+/**
+ * The public halves, in JWKS form.
+ *
+ * Node exports a JWK containing only public parameters for a public
+ * `KeyObject` — no `d`, no primes — so the private material cannot leak
+ * through this path even if a private key were passed by mistake. The keys are
+ * derived from `publicKey` regardless, and this is asserted in the tests,
+ * because "cannot" is worth checking on the one endpoint whose entire job is to
+ * be world-readable.
+ */
+export declare function toJwks(keys: ResolvedJwtKey[]): {
+    keys: PublicJwk[];
+};

package/dist/auth/jwt.d.ts

@@ -1,7 +1,26 @@
+import { type JwtSigningKeyConfig, type PublicJwk } from "./jwt-keys";
 export interface JwtConfig {
     secret: string;
     accessExpiresIn?: string;
     refreshExpiresIn?: string;
+    /**
+     * Asymmetric keys for signing **access tokens**, newest first.
+     *
+     * Optional and additive: with none configured everything below behaves
+     * exactly as it did, signing HS256 with {@link JwtConfig.secret}. With one
+     * configured, access tokens are signed by {@link JwtConfig.activeKid} (or
+     * the first entry) and carry its `kid`, and every key in the list keeps
+     * verifying — which is what makes rotation a deploy rather than a mass
+     * sign-out. Tokens minted before any key existed carry no `kid` and are
+     * still verified against the secret until they expire.
+     *
+     * The secret stays required regardless: purpose-scoped tokens (download,
+     * MFA-pending, password reset) are read only by this server, and are
+     * shorter and cheaper symmetric. See `jwt-keys.ts`.
+     */
+    signingKeys?: JwtSigningKeyConfig[];
+    /** Which key signs. Defaults to the first entry of {@link JwtConfig.signingKeys}. */
+    activeKid?: string;
 }
 export interface AccessTokenPayload {
     /**
@@ -42,6 +61,19 @@ export interface AccessTokenPayload {
  * Validates the secret strength to prevent deployment with default/weak secrets.
  */
 export declare function configureJwt(config: JwtConfig): void;
+/**
+ * The public keys, in JWKS form, for `/.well-known/jwks.json`.
+ *
+ * An empty `keys` array on a backend with no asymmetric keys configured is the
+ * correct answer rather than a 404: it says "this issuer publishes none",
+ * which a verifier can act on, where a 404 is indistinguishable from a
+ * misconfigured URL.
+ */
+export declare function getJwks(): {
+    keys: PublicJwk[];
+};
+/** Is this backend signing access tokens asymmetrically? */
+export declare function hasAsymmetricSigningKey(): boolean;
 /**
  * Has this server been given a JWT secret?
  *
@@ -141,12 +173,40 @@ export declare function verifyMfaPendingToken(token: string): {
 export interface DownloadTokenPayload {
     purpose: "file-read";
     path: string;
+    /**
+     * The storage source the grant is good for, canonicalized by
+     * {@link canonicalStorageId}. Always present on a decoded payload; see
+     * {@link verifyDownloadToken} for how tokens minted before this claim
+     * existed are read.
+     */
+    storageId: string;
 }
 /**
  * Generate a short-lived download token scoped to a specific file path or prefix
+ * *within one storage source*.
+ *
+ * Both halves of that scope are load-bearing. A key is only unique inside its
+ * own bucket, and a project with more than one source routinely holds the same
+ * key in several of them — `avatars/u1.png` in `(default)` and in `media` are
+ * different objects, quite possibly with different owners. A token that names
+ * only the path is therefore a grant on every source at once: authorize a read
+ * on the source whose `storageAuthorize` hook says yes, then spend the token
+ * against `?storageId=` pointing somewhere else.
+ *
+ * `storageId` is optional here only because omitting it *is* the default
+ * source, which is what the overwhelming majority of deployments have. A mint
+ * site that forgets to pass a named source produces a default-scoped token,
+ * which fails closed at `/file/*` rather than over-granting.
  */
-export declare function generateDownloadToken(path: string, expiresInSeconds?: number): string;
+export declare function generateDownloadToken(path: string, expiresInSeconds?: number, storageId?: string | null): string;
 /**
- * Verify and decode a download token
+ * Verify and decode a download token.
+ *
+ * A token minted before `storageId` existed carries no such claim. It is read
+ * as a grant on the **default source** rather than on all of them: that is the
+ * fail-closed reading, and it is what such a token almost always was, since a
+ * named source has to be asked for explicitly. The cost is bounded by the
+ * five-minute TTL — for at most that long after a deploy, an in-flight token
+ * for a *named* source is refused and the client re-fetches `/metadata`.
  */
 export declare function verifyDownloadToken(token: string): DownloadTokenPayload | null;