@rebasepro/server 0.25.1 → 0.26.0

package/dist/auth/oauth-signin-policy.d.ts

@@ -6,25 +6,17 @@
 /** Why an incoming OAuth identity may not be auto-attached to an existing account. */
 export type AutoLinkRefusal = 
 /** The provider did not report that it verified the address. */
-"provider-email-unverified"
-/**
- * The local account holds a password nobody ever proved they own: it was
- * created through `POST /auth/register`, which does not verify the
- * address. Attaching a provider identity to it would hand the session to
- * whoever registered the address first — the classic pre-hijack.
- */
- | "local-account-unverified"
-/**
- * The local account has no password, and its address was never proven
- * either: it was made by a sign-in through a provider that did not vouch
- * for the address, or by someone who never had to. Its sign-in methods are
- * whatever that someone attached, so this is the same pre-hijack as a
- * password would be. Reported apart from `local-account-unverified` only
- * so a login screen does not tell its owner to use a password.
- */
- | "local-account-unverified-passwordless";
+"provider-email-unverified";
 export type AutoLinkDecision = {
     allowed: true;
+    /**
+     * The local account's address was never proven, and this sign-in
+     * proves it. The route settles the account the way an email code does
+     * (`confirmAddressOwnership`) before it links the identity: the
+     * password and every identity whose provider did not vouch for the
+     * address go, and every session ends.
+     */
+    provesAddress: boolean;
 } | {
     allowed: false;
     reason: AutoLinkRefusal;
@@ -37,25 +29,19 @@ export interface AutoLinkExistingUser {
 /**
  * May an OAuth identity be attached to a pre-existing account found *by email*?
  *
- * Both sides have to be trustworthy:
- *
- *  - the **provider** must have verified the address, or the caller has not
- *    shown they control it;
- *  - the **local account**'s address must have been verified too. Whoever
- *    made an unverified account never proved the address, and every way in
- *    they left on it — a password, an identity from a provider that did not
- *    vouch for the address — would go on opening the account the owner is
- *    about to be signed into.
- *
- * The second rule used to exempt an account with no password, on the theory
- * that one made by an OAuth sign-in holds no credential an attacker could have
- * planted. It holds exactly one: the identity it was made with, which is an
- * attacker's whenever the provider did not vouch for the address.
+ * Only when the **provider** verified the address. Otherwise the caller has
+ * not shown they control it, and linking would hand them the account.
  *
- * A refusal is not a dead end. `POST /auth/link/<provider>` attaches the
- * identity once the caller proves ownership by holding a session, and proving
- * the address (a magic link, an email code, a password reset) verifies the
- * account — removing what nobody proved — after which this answers yes.
+ * When it did, the caller has proven the address exactly as reading a code out
+ * of the inbox does: only the inbox's owner can hold a provider account that
+ * vouches for it. If the **local account**'s address was never verified,
+ * whoever made it never proved the address, and every way in they left on it —
+ * a password, an identity from a provider that did not vouch for the address,
+ * a live session — would go on opening the account the owner is about to be
+ * signed into. So that case answers `provesAddress: true`, and the route
+ * removes those ways in before it links (the pre-hijack defence). It used to
+ * refuse instead, which left the owner of the address locked out of their own
+ * address until they found a magic link or a reset.
  */
 export declare function decideOAuthAutoLink(args: {
     providerEmailVerified: boolean | undefined;

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

@@ -11,7 +11,7 @@
  *
  * @module
  */
-import type { DataDriver } from "@rebasepro/types";
+import type { CallerCredential, DataDriver } from "@rebasepro/types";
 /**
  * The identity the trusted server plane runs as: `rebase.dataAsAdmin`, and any
  * caller presenting the service key.
@@ -37,6 +37,21 @@ export declare const SERVICE_IDENTITY: {
     uid: string;
     roles: string[];
 };
+/**
+ * Who a request runs as, as a driver is scoped to it.
+ *
+ * `credential` is the API key the request authenticated with, when it was one.
+ * It changes nothing the database sees; the driver hands it to collection
+ * callbacks as `context.credential`, so a personal key's write can be told
+ * from its owner's own.
+ */
+export interface ScopeIdentity {
+    uid: string;
+    roles?: string[];
+    isAnonymous?: boolean;
+    claims?: Record<string, unknown>;
+    credential?: CallerCredential;
+}
 /**
  * Can this driver run a request as a specific user?
  *
@@ -71,9 +86,4 @@ export declare function scopeDataDriver(driver: DataDriver,
  * without this the database sees the same principal either way. See
  * `rebase.is_anonymous()`.
  */
-user: {
-    uid: string;
-    roles?: string[];
-    isAnonymous?: boolean;
-    claims?: Record<string, unknown>;
-}): Promise<DataDriver>;
+user: ScopeIdentity): Promise<DataDriver>;

package/dist/auth/rls-simulator-routes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The RLS simulator's admin surface, under `/api/admin/rls-simulator`.
+ *
+ * The data API answers one collection at a time for a simulated identity
+ * (`auth/simulation.ts`). This answers the questions the admin panel's
+ * "Simulate access" bar asks about all of them at once:
+ *
+ * - `GET /options` — what can be simulated: the roles the project names (the
+ *   access model's, the ones its row and field rules mention, and `anon`) and
+ *   the API keys that are live.
+ * - `POST /preview` — for `{ role?, userId?, apiKeyId? }`, each collection's
+ *   rows as that identity sees them against the caller's own view, whether a
+ *   key's scopes shut it out, and which fields its roles cannot read.
+ *
+ * The same decision as the data API: only an administrator's own session, a
+ * 403 for anyone else.
+ *
+ * @module
+ */
+import { Hono } from "hono";
+import { type CollectionConfig, type DataDriver } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types.js";
+import type { ApiKeyStore } from "./api-keys/api-key-store.js";
+import type { ImpersonationUserResolver } from "./impersonation.js";
+export interface RlsSimulatorRouteConfig {
+    /** The collections this backend serves, as they are now. */
+    collections(): readonly CollectionConfig[];
+    /** The unscoped driver a collection's rows live in. */
+    driverFor(slug: string): DataDriver;
+    resolveUser?: ImpersonationUserResolver;
+    apiKeyStore?: ApiKeyStore;
+}
+/** One collection, as the simulated identity reaches it. */
+export interface SimulatedCollectionView {
+    slug: string;
+    name: string;
+    /**
+     * Why the identity sees nothing here: its key's scopes, row policies
+     * hiding every row, or a read that fails for it (`error` says why).
+     */
+    hiddenBy?: "scope" | "rls" | "error";
+    /** Rows the simulated identity reads. Absent when not counted. */
+    visibleRows?: number;
+    /** Rows the administrator asking reads. */
+    totalRows?: number;
+    /** Fields the identity's roles cannot read. */
+    maskedColumns: string[];
+    /** Why the rows could not be counted. */
+    error?: string;
+}
+export declare function createRlsSimulatorRoutes(config: RlsSimulatorRouteConfig): Hono<HonoEnv>;

package/dist/auth/simulation-read-only.d.ts

@@ -0,0 +1,28 @@
+/**
+ * "Simulate access" is read-only.
+ *
+ * The simulator answers "what does this role, user or key see". A write made
+ * while simulating ran as the simulated identity for real: it committed as
+ * `rebase_user` with `app.uid` set to the simulated uid, `entity_history`
+ * recorded that uid as the author, callbacks saw `context.user` holding a role
+ * the account may not even have, and a role-only simulation stamped owner
+ * columns with the nobody uid. Only the request log named the administrator.
+ * So every door that honours the simulation headers refuses anything but a
+ * read, naming the simulation, rather than performing it as someone else.
+ *
+ * Its own module so the REST generator, history routes and the functions
+ * guard can share it without importing the simulator itself.
+ *
+ * @module
+ */
+import type { DataOperation } from "./api-keys/http-operation.js";
+/**
+ * Refuse a write or delete on a request that simulates access.
+ *
+ * `c` is anything with the request context's `get` — the REST generator calls
+ * this with a per-operation stand-in for each operation of a `_batch`.
+ * `operation` is what the request does, not its verb: `POST …/query` is a read.
+ */
+export declare function refuseSimulatedWrite(c: {
+    get: (key: string) => unknown;
+}, operation: DataOperation): void;

package/dist/auth/simulation.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The RLS simulator: an administrator's data-plane request run as a role, a
+ * user or a service key — `x-rebase-simulate-role`, `x-rebase-simulate-user-id`
+ * and `x-rebase-simulate-api-key-id`.
+ *
+ * Impersonation ({@link ./impersonation}) answers "what does this person see";
+ * this answers the question an author asks while writing policies, before any
+ * such person exists: "what does a `customer` see, what does `u_1` holding
+ * `customer` see, what does the support agent's key see". So a role need not be
+ * held by anyone and a uid sent with a role need not name an account. Nothing
+ * here widens what the caller could do: the caller is an administrator, whom
+ * the default policies already let read and write every row, and every
+ * simulated identity is narrower.
+ *
+ * The identity reaches the database exactly as a real caller's does —
+ * `scopeDataDriver` → `withAuth` → `applyAuthContext`, which sets the
+ * transaction-local identity (`app.uid`, `app.roles`, `app.jwt`) and switches to
+ * `rebase_user`, so every policy is evaluated for it. A simulated key also
+ * carries its scopes, so the data API refuses the collections the key cannot
+ * reach, as it would refuse the key. Fields the identity's roles cannot read
+ * are stripped by the driver as for any caller; {@link reportSimulatedContext}
+ * names them on the response.
+ *
+ * Who may: a signed-in administrator on their own session, judged on their
+ * roles as the database has them now. Never an API key, never the service
+ * key, never anyone else — a 403, never an answer as themselves.
+ *
+ * Where: the data API and custom functions, like impersonation. Every other
+ * route refuses the headers (`refuseUnhonouredImpersonation`).
+ *
+ * Read-only: a write, delete, batch, revert or non-GET function call that
+ * carries the headers is refused (`SIMULATION_READ_ONLY`, see
+ * {@link ./simulation-read-only}) rather than run as the simulated identity.
+ *
+ * Not simulated: the data API's `requireAuth` gate. A simulated anonymous
+ * caller is let past it, so the answer is what the rows' policies give an
+ * anonymous caller — a 401 there would send the admin panel to refresh a
+ * session that is fine. Everywhere else it is no session, as a real anonymous
+ * caller is: it carries no `user`, so a function's `requireAuth` refuses it.
+ *
+ * @module
+ */
+import type { Context, MiddlewareHandler } from "hono";
+import { type AccessSimulation, type ApiKeyMasked, type CollectionConfig, type DataDriver } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types.js";
+import { ApiError } from "../api/errors.js";
+import type { ImpersonationCredential, ImpersonationUserResolver } from "./impersonation.js";
+import type { ApiKeyStore } from "./api-keys/api-key-store.js";
+import { type AccessControl } from "./access.js";
+/**
+ * The uid a role simulated on its own runs as: a valid UUID that no row
+ * names, so an ownership policy matches nothing and a policy comparing a
+ * `uuid` column to `auth.uid()` still casts cleanly.
+ */
+export declare const SIMULATED_NOBODY_UID = "00000000-0000-0000-0000-000000000000";
+/** Who a granted simulation runs as. */
+export interface SimulatedIdentity {
+    uid: string;
+    roles: string[];
+    isAnonymous: boolean;
+    claims?: Record<string, unknown>;
+    /** A key's scopes. Absent for a person, whose data plane is RLS's to decide. */
+    scopes?: string[];
+    apiKey?: ApiKeyMasked;
+    /** What the response header names: the role (or roles) and the uid. */
+    role: string;
+}
+export interface SimulationRequest {
+    simulation: AccessSimulation;
+    /** What the caller presented. Only a `session` may simulate. */
+    credential: ImpersonationCredential;
+    caller?: {
+        uid: string;
+        roles: readonly string[];
+    };
+    /** Re-reads the caller's roles, and finds a user named without a role. */
+    resolveUser?: ImpersonationUserResolver;
+    /** Finds a key named by id. Absent: a key simulation is refused. */
+    apiKeyStore?: ApiKeyStore;
+    /** Whose access model a personal key's owner is judged against. */
+    access?: AccessControl;
+    /** Where the request came in, for the audit line; absent writes none. */
+    audit?: Record<string, unknown>;
+}
+export type SimulationDecision = {
+    granted: SimulatedIdentity;
+    simulator: string;
+} | {
+    refused: ApiError;
+};
+/** Read the three simulation headers, or `undefined` when none was sent. */
+export declare function simulationOf(header: (name: string) => string | undefined): AccessSimulation | undefined;
+/** Whether a request carries any simulation header. */
+export declare function carriesSimulation(header: (name: string) => string | undefined): boolean;
+/**
+ * Decide whether this caller may simulate what they asked for, and who the
+ * request then runs as.
+ *
+ * The caller is judged before anything they named is looked up, so a refusal
+ * says nothing about whether a user or key exists. Throws when a lookup fails.
+ */
+export declare function decideSimulation(request: SimulationRequest): Promise<SimulationDecision>;
+export interface SimulationOptions {
+    credential: ImpersonationCredential;
+    /** The unscoped delegate the request's driver was scoped from. */
+    driver: DataDriver;
+    resolveUser?: ImpersonationUserResolver;
+    apiKeyStore?: ApiKeyStore;
+}
+/** The caller the auth middleware put on the context, narrowed. */
+export declare function callerOf(c: Context<HonoEnv>): {
+    uid: string;
+    roles: string[];
+} | undefined;
+/**
+ * Honour or refuse this request's simulation headers.
+ *
+ * Called by the data-plane auth middlewares once the caller is on the context
+ * and before impersonation, which it excludes. On a grant the context's
+ * `user`, `driver`, `scopes` and `apiKey` become the simulated identity's,
+ * `impersonator` names the administrator for the request log, and
+ * `simulation` records what to report on the response.
+ *
+ * @returns The refusal to send, or `undefined` to carry on.
+ */
+export declare function applySimulation(c: Context<HonoEnv>, { credential, driver, resolveUser, apiKeyStore }: SimulationOptions): Promise<Response | undefined>;
+/**
+ * The fields of `collection` the roles cannot read: what the driver strips
+ * from every row it hands them. Fields hidden from everyone (`excludeFromApi`)
+ * are left out — no role sees those, so they say nothing about this one.
+ */
+export declare function maskedFieldsFor(collection: CollectionConfig, roles: readonly string[]): string[];
+/**
+ * Name what a simulated request ran as on its response
+ * ({@link SIMULATED_CONTEXT_HEADER}), refusals included.
+ *
+ * Mounted ahead of the data-plane groups; it reads, after the request is
+ * answered, what {@link applySimulation} and the REST generator recorded on
+ * the context — the identity, and which collection the request was about.
+ */
+export declare function reportSimulatedContext(): MiddlewareHandler<HonoEnv>;

package/dist/auth/sql-rate-limit-store.d.ts

@@ -46,6 +46,12 @@ import type { RateLimitStore } from "./rate-limit-store.js";
 export interface SqlRateLimitStoreOptions {
     /** How often to delete expired buckets. Defaults to 5 minutes. */
     sweepMs?: number;
+    /**
+     * Default `true`. `false` is a backend that changes nothing in its
+     * database: the table is used if it is there, never created, and counts
+     * stay per-process without it.
+     */
+    provision?: boolean;
     /**
      * Clock, for tests. Driving the window directly beats sleeping through half
      * of one — a real sleep overruns on a loaded machine and takes the hits it
@@ -60,4 +66,12 @@ export interface SqlRateLimitStoreOptions {
  * deployment on a driver with no SQL admin should degrade to per-process counts
  * with a warning, not refuse to serve.
  */
-export declare function createSqlRateLimitStore(driver: DataDriver, options?: SqlRateLimitStoreOptions): RateLimitStore | undefined;
+/** The shared store, plus the one step a provisioning run takes ahead of time. */
+export interface SqlRateLimitStore extends RateLimitStore {
+    /**
+     * Create the table now rather than on the first counted request — what a
+     * provisioning run calls. Resolves to whether it is usable.
+     */
+    ensureTable(): Promise<boolean>;
+}
+export declare function createSqlRateLimitStore(driver: DataDriver, options?: SqlRateLimitStoreOptions): SqlRateLimitStore | undefined;