@rebasepro/server 0.22.0 → 0.24.0

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,12 +28,24 @@ 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
+     * the boot once. `/anonymous/link` is registration — it is where a guest
+     * becomes an account — so it is guarded by the same challenge as
+     * `/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.
  *
@@ -68,5 +117,8 @@ export declare function revokeAllSessions(authRepo: Pick<AuthRepository, "delete
  * `test/password-change-revokes-sessions.test.ts` holds every route that sets a
  * password to this, and fails if anything but this function calls
  * `updatePassword`.
+ *
+ * `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): 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>;