@rebasepro/server 0.23.0 → 0.24.1-canary.g19596ef

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

@@ -2,11 +2,17 @@ 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 AuthLimiters } from "./rate-limiter.js";
+import { type JwtService } from "./jwt.js";
+import type { AuthModuleConfig, CreateSessionAndTokens } from "./routes.js";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
 import type { resolveAuthHooks } from "./auth-hooks.js";
 interface SessionRoutesConfig {
     router: Hono<HonoEnv>;
+    /** The backend these routes sign and verify for. */
+    jwt: JwtService;
+    /** The backend's auth limiters. */
+    limiters: AuthLimiters;
     config: AuthModuleConfig;
     /**
      * The caller's guard for a signed-in user, with the revocation watermark
@@ -28,11 +34,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 +43,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,61 @@ 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.
+ *
+ * Except one failure that is an answer: the store refusing the uid as a value
+ * its id column cannot hold — `u1` against a UUID key. That names no account,
+ * exactly as a well-formed id nobody has does, so it is `account-deleted` and
+ * the caller answers 401. Answered as a failure it was a 503 asking the
+ * client to try again, which it would do forever.
+ */
+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 +127,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/user-picking.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Who may read the user picker (`GET /api/admin/users/pick`).
+ *
+ * A `userSelect` field stores a user's id, and the person filling it in picks
+ * that user from a list. Listing the users is an admin-plane read
+ * (`users:read`), which an editor does not hold — so the picker answers a
+ * narrower question for a wider audience: id, name, email and avatar, to
+ * anyone who may write a collection that has such a field.
+ *
+ * "May write" is the collection's `securityRules` for an insert or an update,
+ * evaluated the way the admin panel decides whether to offer the form, with
+ * one difference. A rule that depends only on the row (an owner field) counts
+ * as allowing, since the person may write some row. A rule written as SQL the
+ * policy model cannot read cannot be judged ahead, and here it counts as
+ * refusing: read optimistically, it would let any signed-in person list every
+ * user's name and email. A key or token narrowed by scopes must also hold
+ * `data:write` on that collection.
+ *
+ * The collections are the backend's own (`c.var.services`), read when the
+ * question is asked, so a schema edited live is what is judged.
+ *
+ * @module
+ */
+import type { Context } from "hono";
+import { type CollectionConfig, type Properties } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types.js";
+/** Tell the process default's picker which collections it serves. */
+export declare function configureUserPicking(collections: () => readonly CollectionConfig[]): void;
+/** @internal The process default's collections getter, to snapshot or restore it. */
+export declare function defaultUserPicking(): () => readonly CollectionConfig[];
+/** Whether any property, at any depth, is a `userSelect` field. */
+export declare function propertiesReferenceUsers(properties: Properties | undefined): boolean;
+/**
+ * Whether this request's caller may read the user picker: they hold
+ * `users:read`, or they may write a collection with a `userSelect` field.
+ */
+export declare function mayPickUsers(c: Context<HonoEnv>): boolean;

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

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ *
+ * A backend answers for itself — `backend.verifyCredential(token)`, against its
+ * own keys, store and access model. {@link verifyCredential} answers for the
+ * process default.
+ *
+ * @module
+ */
+import type { ApiKeyStore } from "./api-keys/api-key-store.js";
+import { type AccessControl } from "./access.js";
+import { type JwtService } from "./jwt.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";
+}
+/** What a credential is checked against: one backend's keys, key store and access model. */
+export interface CredentialAuthority {
+    jwt: JwtService;
+    access: AccessControl;
+    apiKeyStore?: ApiKeyStore;
+}
+/** Install the key store the process default's {@link verifyCredential} checks `rk_` keys against. */
+export declare function configureCredentialStore(store: ApiKeyStore | undefined): void;
+/** @internal The process default's key store, to snapshot or restore it. */
+export declare function defaultCredentialStore(): ApiKeyStore | undefined;
+/**
+ * The identity and scopes behind a bearer credential, checked against one
+ * backend, or null when it does not verify — expired, revoked, unknown, or a
+ * key on a backend with no key store.
+ */
+export declare function verifyCredentialAgainst(authority: CredentialAuthority, token: string): Promise<VerifiedCredential | null>;
+/**
+ * The identity and scopes behind a bearer credential, as the process default
+ * answers — expired, revoked, unknown, or a key on a backend with no key store
+ * all come back null. A backend built by `createRebaseBackend` answers for
+ * itself: `backend.verifyCredential(token)`.
+ */
+export declare function verifyCredential(token: string): Promise<VerifiedCredential | null>;