@rebasepro/server 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/auth/interfaces.d.ts

@@ -19,6 +19,11 @@ export interface UserData {
     emailVerificationToken?: string | null;
     emailVerificationSentAt?: Date | null;
     isAnonymous?: boolean;
+    /**
+     * An administrator switched the account off: no sign-in, no refresh, and
+     * no token it already holds is honoured. See `setUserDisabled`.
+     */
+    disabled?: boolean;
     metadata?: Record<string, unknown>;
     createdAt: Date;
     updatedAt: Date;
@@ -35,6 +40,16 @@ export interface CreateUserData {
     isAnonymous?: boolean;
     metadata?: Record<string, unknown>;
 }
+/**
+ * An address change waiting for its confirmation link. See
+ * {@link UserRepository.setPendingEmailChange}.
+ */
+export interface PendingEmailChange {
+    /** The address the account is moving to, normalized. */
+    email: string;
+    /** When the link was mailed; it is refused 24 hours after this. */
+    sentAt: Date;
+}
 /**
  * User Identity Data (OAuth accounts linked to user)
  */
@@ -92,36 +107,6 @@ export interface OAuthProvider<T = unknown> {
      */
     verify(payload: T): Promise<OAuthProviderProfile | null>;
 }
-/**
- * Role data structure
- */
-export interface RoleData {
-    id: string;
-    name: string;
-    isAdmin: boolean;
-    defaultPermissions: {
-        read?: boolean;
-        create?: boolean;
-        edit?: boolean;
-        delete?: boolean;
-    } | null;
-    collectionPermissions: Record<string, {
-        read?: boolean;
-        create?: boolean;
-        edit?: boolean;
-        delete?: boolean;
-    }> | null;
-}
-/**
- * Data for creating a new role
- */
-export interface CreateRoleData {
-    id: string;
-    name: string;
-    isAdmin?: boolean;
-    defaultPermissions?: RoleData["defaultPermissions"];
-    collectionPermissions?: RoleData["collectionPermissions"];
-}
 /**
  * Refresh token info
  */
@@ -161,6 +146,31 @@ export interface RefreshTokenInfo {
      * that do not store it; both read as `aal1`, the restrictive value.
      */
     aal?: "aal1" | "aal2";
+    /**
+     * How the session was signed in — `"password"`, `"anonymous"`,
+     * `"magic-link"`, `"otp"`, `"mfa"` or a provider id such as `"google"`.
+     * See {@link RefreshTokenSession.method}. Absent on rows written before
+     * the column existed, which read as `"password"`.
+     */
+    method?: string;
+}
+/**
+ * What {@link TokenRepository.getAccountAccessState} reads about an account
+ * that exists.
+ */
+export interface AccountAccessState {
+    /** The account's roles as the database has them now. */
+    roles: string[];
+    /** The revocation watermark: sessions that began before it are void. */
+    tokensValidAfter: Date | null;
+    /**
+     * Whether the session asked about has a refresh token that is not
+     * revoked. `undefined` when no session was asked about, or the store
+     * cannot tell (a refresh-token table without session grouping).
+     */
+    sessionActive?: boolean;
+    /** The account is switched off (`UserData.disabled`). */
+    disabled?: boolean;
 }
 /**
  * Identity of the sign-in a refresh token belongs to, threaded through
@@ -179,6 +189,14 @@ export interface RefreshTokenSession {
      * assurance level is a property of the *sign-in*, not of the account.
      */
     aal?: "aal1" | "aal2";
+    /**
+     * How the session was signed in: what `providerId` says in every auth
+     * response for it. Written at sign-in and carried across rotations like
+     * {@link aal}, because a refresh is not a sign-in and has nothing else to
+     * read it from — answering `"password"` there turned a Google session into
+     * a password one an access-token lifetime after it began.
+     */
+    method?: string;
     /**
      * The hash of the token this one replaces, when it is minted by rotating
      * one. A repository that honours it writes the new token only while that
@@ -216,7 +234,11 @@ export interface ListUsersOptions {
     limit?: number;
     /** Number of results to skip (default 0) */
     offset?: number;
-    /** Search term — matches against email and displayName (case-insensitive) */
+    /**
+     * Search term — a case-insensitive substring of the email, the display
+     * name, any role the user holds, or the uid. (The Postgres store matches
+     * all four; the Mongo store, email and display name.)
+     */
     search?: string;
     /** Field to sort by (default "createdAt") */
     orderBy?: string;
@@ -302,6 +324,16 @@ export interface UserRepository {
      * List users with server-side pagination, search, and sorting.
      */
     listUsersPaginated(options?: ListUsersOptions): Promise<PaginatedUsersResult>;
+    /**
+     * The ids of at most `limit` users, in no particular order. Answers "is
+     * there any user?" (`limit` 1) and "is this the only one?" (`limit` 2).
+     *
+     * `listUsersPaginated` answered those by counting the whole table and
+     * sorting it, on every anonymous `GET /auth/config` and every sign-up.
+     * Optional: a repository without it is asked through `listUsersPaginated`
+     * instead (`isUserTableEmpty` / `isOnlyUser` in `registration-policy.ts`).
+     */
+    firstUserIds?(limit: number): Promise<string[]>;
     /**
      * Update user's password hash. `null` removes the password: the account
      * then signs in only by link, code or provider.
@@ -319,10 +351,6 @@ export interface UserRepository {
      * Find user by email verification token
      */
     getUserByVerificationToken(token: string): Promise<UserData | null>;
-    /**
-     * Get roles for a user
-     */
-    getUserRoles(uid: string): Promise<RoleData[]>;
     /**
      * Get role IDs for a user
      */
@@ -340,34 +368,45 @@ export interface UserRepository {
      */
     getUserWithRoles(uid: string): Promise<{
         user: UserData;
-        roles: RoleData[];
+        roles: string[];
     } | null>;
-}
-/**
- * Abstract role repository interface.
- * Handles all role-related database operations.
- */
-export interface RoleRepository {
-    /**
-     * Get a role by ID
-     */
-    getRoleById(id: string): Promise<RoleData | null>;
     /**
-     * List all roles
+     * Switch an account off, or back on. Off, it cannot sign in or refresh,
+     * and the tokens it holds are refused (`judgeAccessToken`). Optional: a
+     * repository without it cannot disable accounts, and the admin route says
+     * so rather than pretending.
      */
-    listRoles(): Promise<RoleData[]>;
+    setUserDisabled?(uid: string, disabled: boolean): Promise<void>;
     /**
-     * Create a new role
-     */
-    createRole(data: CreateRoleData): Promise<RoleData>;
-    /**
-     * Update a role
-     */
-    updateRole(id: string, data: Partial<Omit<RoleData, "id">>): Promise<RoleData | null>;
+     * Record the address an account is moving to and the hash of the token
+     * mailed there, stamped now — or with `null`, drop it. One per account: a
+     * new request replaces the last, and its link stops working.
+     *
+     * Nothing is reserved by it. The address stays free for anyone to
+     * register until the link is followed, because a pending change that held
+     * it would let any account lock a stranger out of signing up with their
+     * own address.
+     */
+    setPendingEmailChange?(uid: string, change: {
+        email: string;
+        tokenHash: string;
+    } | null): Promise<void>;
+    /** The account's pending change, if it has one. */
+    getPendingEmailChange?(uid: string): Promise<PendingEmailChange | null>;
+    /** The account whose pending change `tokenHash` confirms, with the change. */
+    findPendingEmailChange?(tokenHash: string): Promise<{
+        user: UserData;
+        change: PendingEmailChange;
+    } | null>;
     /**
-     * Delete a role
+     * Move the account onto its pending address, in one write that holds only
+     * while `tokenHash` is still that change's token: the address becomes the
+     * account's, verified, and the pending change and any outstanding
+     * verification token are cleared. `null` when the token no longer names
+     * the change (confirmed already, replaced, cancelled). An address another
+     * account holds by then is a 409 `EMAIL_EXISTS`, as `updateUser` answers.
      */
-    deleteRole(id: string): Promise<void>;
+    applyPendingEmailChange?(uid: string, tokenHash: string): Promise<UserData | null>;
 }
 /**
  * Abstract token repository interface.
@@ -418,6 +457,24 @@ export interface TokenRepository {
      * user's tokens so a rotation racing the delete cannot survive it.
      */
     setTokensValidAfter?(uid: string, at: Date): Promise<void>;
+    /**
+     * Everything an access token is judged against, in one read — or `null`
+     * when there is no such account.
+     *
+     * An access token is a bearer credential minted up to an hour ago, and the
+     * account it names may since have been deleted, revoked or demoted. Every
+     * door that honours one asks this before it does: the data plane, the admin
+     * gates, the realtime socket on every frame. See `judgeAccessToken`.
+     *
+     * `sessionId` is the token's `sid`: when given, the state also says
+     * whether that sign-in is still live, which is how signing one device out
+     * reaches the access token that device holds.
+     *
+     * Optional. Without it the judge composes the answer from
+     * `getUserWithRoles` and `getTokensValidAfter`, two reads instead of one,
+     * and cannot see one revoked session — only every session at once.
+     */
+    getAccountAccessState?(uid: string, sessionId?: string): Promise<AccountAccessState | null>;
     /**
      * Find a refresh token by hash
      */
@@ -455,7 +512,11 @@ export interface TokenRepository {
      */
     deleteAllPasswordResetTokensForUser(uid: string): Promise<void>;
     /**
-     * Clean up expired tokens
+     * Delete every token past its expiry: reset links, magic links and email
+     * codes, refresh tokens, and whatever else the repository keeps that
+     * expires. A token is refused when presented whether or not this has run,
+     * so it is housekeeping, not revocation. The server calls it once an hour
+     * on one instance of the fleet (`startExpiredTokenSweep`).
      */
     deleteExpiredTokens(): Promise<void>;
     /**
@@ -613,5 +674,5 @@ export interface MfaRepository {
 /**
  * Combined auth repository interface for convenience
  */
-export interface AuthRepository extends UserRepository, RoleRepository, TokenRepository, MfaRepository {
+export interface AuthRepository extends UserRepository, TokenRepository, MfaRepository {
 }

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

@@ -74,6 +74,13 @@ export declare function signJwt(payload: JwtClaims, key: JwtSigningKey, options:
 export declare function verifyJwt(token: string, key: JwtVerificationKey, options: {
     algorithms: string[];
 }): Promise<JwtClaims>;
+/**
+ * Whether a {@link verifyJwt} rejection says only that the token's `exp` has
+ * passed — the routine refusal that sends a client to refresh — rather than
+ * that the token is not one we signed. Here because the library decides how
+ * that is spelled.
+ */
+export declare function isExpiredJwtError(error: unknown): boolean;
 /**
  * The token's unverified header — `kid` and `alg` — or an empty object.
  *

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

@@ -106,3 +106,7 @@ export declare function normalizePemFromEnv(value: string): string;
 export declare function toJwks(keys: ResolvedJwtKey[]): {
     keys: PublicJwk[];
 };
+/** A verification key, as `jsonwebtoken.verify` would import it, once per string. */
+export declare function importedVerificationKey<K>(key: K): K | KeyObject;
+/** A signing key, as `jsonwebtoken.sign` would import it, once per string. */
+export declare function importedSigningKey<K>(key: K): K | KeyObject;

package/dist/auth/jwt.d.ts

@@ -61,6 +61,23 @@ export interface AccessTokenPayload {
      * comparison and the watermark was read on exactly one path — refresh.
      */
     iat?: number;
+    /**
+     * When the token expires, in seconds since the epoch — the standard `exp`
+     * claim. Carried through because a socket authenticated with this token
+     * has to stop honouring it at this instant, and has no request to refuse.
+     */
+    exp?: number;
+    /**
+     * The sign-in this token was minted for: the session id its refresh
+     * tokens share, carried across every rotation.
+     *
+     * What lets one device be signed out — `POST /auth/logout`,
+     * `DELETE /auth/sessions/:id` — reach that device's access token rather
+     * than only its refresh token, and what lets `GET /auth/sessions` mark the
+     * caller's own session. Absent on tokens minted before it existed; those
+     * keep working until they expire, judged by the watermark alone.
+     */
+    sid?: string;
     /** Email claim from the JWT, if present */
     email?: string;
     /** Display name claim from the JWT, if present */
@@ -89,6 +106,19 @@ export interface AccessTokenPayload {
      */
     claims?: Record<string, unknown>;
 }
+/**
+ * The custom half of a verified token, or nothing when there is none.
+ *
+ * Exported for the one other place that builds a request identity's claims
+ * without a token to verify — `resolveUser`, which reads what a token minted
+ * now would carry — so both drop the same identity claims.
+ */
+export declare function customClaimsOf(decoded: Record<string, unknown>): Record<string, unknown> | undefined;
+/**
+ * How long a refresh token survives inactivity when no lifetime is configured.
+ * Sliding: every rotation re-ups it, so an active user stays signed in.
+ */
+export declare const DEFAULT_REFRESH_EXPIRES_IN = "30d";
 /**
  * Configure JWT settings - call this during initialization.
  * Validates the secret strength to prevent deployment with default/weak secrets.
@@ -105,6 +135,12 @@ export declare function configureJwt(config: JwtConfig): void;
 export declare function getJwks(): {
     keys: PublicJwk[];
 };
+/**
+ * The secret `configureJwt` was given, or undefined before it is called. For
+ * `mfa-crypto.ts`, which falls back to it when no MFA key is set — the secret
+ * passed in code, not only the one in `JWT_SECRET`.
+ */
+export declare function configuredJwtSecret(): string | undefined;
 /** Is this backend signing access tokens asymmetrically? */
 export declare function hasAsymmetricSigningKey(): boolean;
 /**
@@ -128,7 +164,12 @@ export declare function generateAccessToken(uid: string, roles: string[], aal?:
  * account. Written into the token so the RLS identity and the WebSocket
  * path can tell the two apart without a database lookup.
  */
-isAnonymous?: boolean): Promise<string>;
+isAnonymous?: boolean, 
+/**
+ * The sign-in this token belongs to — see {@link AccessTokenPayload.sid}.
+ * Every token the auth routes mint carries one.
+ */
+sessionId?: string): Promise<string>;
 /**
  * Get the expiration time of an access token in milliseconds from now
  */
@@ -165,7 +206,8 @@ export declare function getAccessTokenExpiry(): number;
  */
 export declare function verifyAccessToken(token: string): Promise<AccessTokenPayload | null>;
 /**
- * Generate a random refresh token (long-lived, 30 days by default)
+ * Generate a random refresh token. Long-lived: 30 days by default, sliding —
+ * see {@link getRefreshTokenTtlMs}.
  */
 export declare function generateRefreshToken(): string;
 /**
@@ -236,6 +278,13 @@ export interface DownloadTokenPayload {
      * existed are read.
      */
     storageId: string;
+    /**
+     * An opaque mark of the user who minted the token, for rate limiting only:
+     * a read that spends the token is charged to that user's allowance rather
+     * than to the reader's address. A hash, because the token travels in a URL.
+     * Absent for a token minted for nobody.
+     */
+    rl?: string;
 }
 /**
  * Generate a short-lived download token scoped to a specific file path or prefix
@@ -254,7 +303,9 @@ export interface DownloadTokenPayload {
  * 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, storageId?: string | null): Promise<string>;
+export declare function generateDownloadToken(path: string, expiresInSeconds?: number, storageId?: string | null, 
+/** The user minting it, so the reads it buys are charged to them. */
+principal?: string | null): Promise<string>;
 /**
  * Verify and decode a download token.
  *

package/dist/auth/magic-link-routes.d.ts

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
 import type { MiddlewareHandler } from "hono";
-import type { AuthModuleConfig } from "./routes.js";
+import type { AuthModuleConfig, CreateSessionAndTokens } from "./routes.js";
 import type { ResolvedAuthHooks } from "./auth-hooks.js";
 import type { HonoEnv } from "../api/types.js";
 import { z } from "zod";
@@ -24,11 +24,7 @@ export declare function mountMagicLinkRoutes(deps: {
         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>;
     /**
      * Built by the caller so a misconfiguration fails the boot once, rather

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

@@ -1,7 +1,7 @@
 import { Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
 import { HonoEnv } from "../api/types.js";
-import type { AuthModuleConfig } from "./routes.js";
+import type { AuthModuleConfig, CreateSessionAndTokens } from "./routes.js";
 import { resolveAuthHooks } from "./auth-hooks.js";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
 interface MfaRoutesConfig {
@@ -27,14 +27,7 @@ interface MfaRoutesConfig {
         isAnonymous?: boolean;
         metadata?: Record<string, unknown> | null;
     }, roleIds: string[], accessToken: string, refreshToken: string, providerId: string) => unknown;
-    createSessionAndTokens: (uid: string, userAgent: string, ipAddress: string, options?: {
-        skipMfaGate?: boolean;
-        aal?: "aal1" | "aal2";
-    }) => Promise<{
-        roleIds: string[];
-        accessToken: string;
-        refreshToken: string;
-    }>;
+    createSessionAndTokens: CreateSessionAndTokens;
     applyTransformHook?: (response: AuthResponsePayload, method: TransformAuthResponseContext["method"], request: Request, uid: string) => Promise<AuthResponsePayload>;
 }
 export declare function mountMfaRoutes(opts: MfaRoutesConfig): void;

package/dist/auth/middleware.d.ts

@@ -1,5 +1,5 @@
 import { MiddlewareHandler, Context } from "hono";
-import type { AuthRepository } from "./interfaces.js";
+import { type AccessJudgeRepository } from "./token-revocation.js";
 import { DataDriver } from "@rebasepro/types";
 import { AccessTokenPayload } from "./jwt.js";
 import type { HonoEnv } from "../api/types.js";
@@ -131,11 +131,15 @@ export declare function createRequireAuth(options?: {
      * invalidated by `logout` or a password reset stops working on admin routes
      * too, not just on the data plane.
      */
-    revocationRepo?: Pick<AuthRepository, "getTokensValidAfter">;
+    revocationRepo?: AccessJudgeRepository;
 }): MiddlewareHandler<HonoEnv>;
 /**
- * Middleware that requires the user to have an admin or schema-admin role.
- * Must be used AFTER requireAuth or on a route where user is guaranteed.
+ * Middleware that requires the user to hold the `admin` role, which holds
+ * every scope. Must be used AFTER requireAuth or on a route where user is
+ * guaranteed.
+ *
+ * Prefer `requireScope` from `./access` for anything a scope names: a scope
+ * can be granted to a narrower role and to a key, and `admin` cannot.
  */
 export declare const requireAdmin: MiddlewareHandler<HonoEnv>;
 /**
@@ -197,6 +201,14 @@ export declare const queryTokenAuth: MiddlewareHandler<HonoEnv>;
  * requested object path is public, it sets a minimal "public" principal so the
  * downstream `requireAuth` gate lets the read through. Private paths are left
  * untouched, so they still require a valid token.
+ *
+ * Public means the object the route will serve is public, so the decision is
+ * made on that object's canonical key, derived by the route's own function
+ * (`requestedStorageObject`). It used to be made on the raw path, through a
+ * check that strips a `scheme://`: `notes://public/secret.txt` read as
+ * `public/secret.txt` here while the route served the private
+ * `notes:/public/secret.txt`, and the authorize hook — not asked about this
+ * principal — never saw it.
  */
 export declare const publicObjectAuth: MiddlewareHandler<HonoEnv>;
 /**
@@ -217,7 +229,7 @@ export declare const publicObjectAuth: MiddlewareHandler<HonoEnv>;
  * Hono routes the request, so this comparison already runs on a resolved path.
  * But that is a guarantee of the runtime rather than of this code, and it is
  * one line to not depend on it. The same rule already guards the public-object
- * path — see `isPublicStoragePath`.
+ * path — see `isPublicStorageKey`.
  */
 export declare function isPathMatch(requested: string, allowed: string): boolean;
 /**

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

@@ -42,7 +42,7 @@
 import { Hono } from "hono";
 import type { MiddlewareHandler } from "hono";
 import { z } from "zod";
-import type { AuthModuleConfig } from "./routes.js";
+import type { AuthModuleConfig, CreateSessionAndTokens } from "./routes.js";
 import type { ResolvedAuthHooks } from "./auth-hooks.js";
 import type { HonoEnv } from "../api/types.js";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
@@ -78,11 +78,7 @@ export declare function mountOtpRoutes(deps: {
         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>;
     /** Built by the caller, as for magic link. Absent when captcha is off. */
     captchaMiddleware?: MiddlewareHandler<HonoEnv>;

package/dist/auth/passwordless-signup.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sign-up by magic link or email code (`auth.magicLinkCreatesUsers`).
+ *
+ * Both passwordless doors refuse an address with no account — silently, so
+ * they do not say which addresses have one. A passwordless-only app then had
+ * no way to create accounts at all. With the option on, and registration open,
+ * an unknown address gets an account at request time — no password, unverified
+ * — and the link or code mailed to it is what proves the address and signs it
+ * in, exactly as for an existing account. Supabase's `shouldCreateUser`.
+ *
+ * @module
+ */
+import type { AuthModuleConfig } from "./routes.js";
+import type { ResolvedAuthHooks } from "./auth-hooks.js";
+import type { UserData } from "./interfaces.js";
+/**
+ * The account a passwordless request for `email` should mail, creating it
+ * when the deployment lets passwordless requests sign people up. `null` when
+ * there is none and none may be made — the caller answers as for any unknown
+ * address.
+ *
+ * Registration's controls hold: the kill switch, `allowRegistration` (with no
+ * first-user exception: the first admin is made by registering or by the
+ * operator, never by whoever asks for a link first), `beforeUserCreate`,
+ * `afterUserCreate` and the default role.
+ */
+export declare function accountForPasswordlessRequest(config: AuthModuleConfig, ops: ResolvedAuthHooks, email: string): Promise<UserData | null>;

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>;