@rebasepro/types 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/types/admin_block.d.ts

@@ -49,7 +49,7 @@ export type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];
  *
  * @group Models
  */
-export declare const ADMIN_PROPERTY_KEYS: readonly ["canAddElements", "clearable", "columnWidth", "customProps", "disabled", "expanded", "Field", "Filter", "filterOperators", "fixedFilter", "format", "hideFromCollection", "includeEntityLink", "includeId", "markdown", "minimalistView", "multiline", "Preview", "previewAsTag", "previewProperties", "readOnly", "renderInForm", "sortable", "span", "spreadChildren", "urlPreview", "widget"];
+export declare const ADMIN_PROPERTY_KEYS: readonly ["canAddElements", "clearable", "columnWidth", "customProps", "disabled", "expanded", "Field", "filledByServer", "Filter", "filterOperators", "fixedFilter", "format", "hideFromCollection", "includeEntityLink", "includeId", "markdown", "minimalistView", "multiline", "Preview", "previewAsTag", "previewProperties", "readOnly", "renderInForm", "sortable", "span", "spreadChildren", "urlPreview", "widget"];
 /** A key of a property's `admin` block. @group Models */
 export type AdminPropertyKey = typeof ADMIN_PROPERTY_KEYS[number];
 /**

package/dist/types/api_keys.d.ts

@@ -1,49 +1,52 @@
 /**
- * Service API keys — machine-to-machine authentication for scripts, cron jobs
- * and third-party integrations.
+ * API keys — long-lived bearer credentials for scripts, CI, agents and
+ * third-party integrations.
  *
- * The wire contract lives here because all three sides need it and used to
- * declare it separately: `@rebasepro/server` implements the routes,
- * `@rebasepro/client` calls them, and {@link ApiKeysAPI} types the SDK surface.
- * The client's copy had already drifted — it never gained `admin`.
+ * The wire contract lives here because all three sides need it:
+ * `@rebasepro/server` implements the routes, `@rebasepro/client` calls them,
+ * and {@link ApiKeysAPI} types the SDK surface. The database row itself
+ * (which carries `key_hash`) stays in the server package: nothing off the
+ * server may see it.
  *
- * The database row itself (`ApiKey`, which carries `key_hash`) stays in the
- * server package: nothing off the server may see it.
+ * What a key may do is a list of scopes — see `scopes.ts`.
  */
+import type { ScopeSummary } from "./scopes.js";
 /**
- * A single permission entry scoping an API key to a collection and set of
- * operations.
+ * Who a key acts as.
  *
- * Use `"*"` as the collection value to grant access to all collections (and all
- * custom functions). Custom functions are addressed with the `functions`
- * namespace: `"functions"` grants every function, `"functions/<name>"` grants a
- * single one.
+ * - `"service"` — the project's own machine identity, `api-key:<id>`. It is no
+ *   person: it runs as the RLS roles it was given (`service` always, plus any
+ *   in {@link ApiKeyMasked.roles}). Managed by holders of `keys:write`.
+ * - `"personal"` — its owner. It runs as the owner's account, with the owner's
+ *   roles as they are *now*, and can never hold a scope the owner does not.
+ *   Managed by the owner, when the app enables `auth.personalKeys`.
  *
  * @group Models
  */
-export interface ApiKeyPermission {
-    /** Collection slug, `"functions"`/`"functions/<name>"`, or `"*"` for everything. */
-    collection: string;
-    /** Allowed operations on the collection. */
-    operations: ("read" | "write" | "delete")[];
-}
+export type ApiKeyKind = "service" | "personal";
 /**
- * An API key with the secret portion masked — what list / get / update return.
+ * An API key with the secret masked — what list / get / update return.
  * @group Models
  */
 export interface ApiKeyMasked {
     id: string;
     name: string;
+    kind: ApiKeyKind;
     /** First 12 characters of the plaintext key, for display only. */
     key_prefix: string;
-    permissions: ApiKeyPermission[];
     /**
-     * When true, the key is granted the `admin` role: it passes the admin-gated
-     * routes (users, roles, cron, backups, logs, API keys) and the RLS
-     * `default_admin` policies. Non-admin keys carry only the `service` role —
-     * RLS grants them nothing unless a collection policy names that role.
+     * What the key may do, as `resource:action[:target]` scope strings —
+     * `data:read:posts`, `functions:invoke`, `logs:read`.
+     */
+    scopes: string[];
+    /**
+     * The RLS roles a service key runs as, beside `service`. `["admin"]` reads
+     * every row through the default admin policies. Always empty on a personal
+     * key, which runs as its owner's live roles.
      */
-    admin: boolean;
+    roles: string[];
+    /** The account a personal key acts as. Null on a service key. */
+    owner_uid: string | null;
     /**
      * Requests per 15-minute window. `null` means "no per-key override" — the
      * data rate limiter then applies its default API-key limit (1000/window
@@ -67,32 +70,44 @@ export interface ApiKeyWithSecret extends ApiKeyMasked {
     key: string;
 }
 /**
- * Payload for creating a new API key.
+ * Payload for creating a service key.
  * @group Models
  */
 export interface CreateApiKeyRequest {
     name: string;
-    permissions: ApiKeyPermission[];
-    /** When true, grants the `admin` role. See {@link ApiKeyMasked.admin}. */
-    admin?: boolean;
+    /** At least one. `keys:*` is refused, and so is any scope the creator does not hold. */
+    scopes: string[];
+    /** RLS roles beside `service`. A creator may only give roles they hold, unless they are an admin. */
+    roles?: string[];
     /** Requests per 15-minute window. Omit or `null` for the server default. */
     rate_limit?: number | null;
     /** ISO-8601 expiration timestamp. Omit for no expiration. */
     expires_at?: string | null;
 }
 /**
- * Payload for updating an existing API key. Only the fields provided change.
+ * Payload for updating a service key. Only the fields provided change.
  * @group Models
  */
 export interface UpdateApiKeyRequest {
     name?: string;
-    permissions?: ApiKeyPermission[];
-    /** When true, grants the `admin` role. See {@link ApiKeyMasked.admin}. */
-    admin?: boolean;
+    scopes?: string[];
+    roles?: string[];
     rate_limit?: number | null;
     expires_at?: string | null;
 }
-/** @group Models */
+/**
+ * Payload for creating a personal key. It acts as the caller, so it carries no
+ * roles and no rate-limit override.
+ * @group Models
+ */
+export interface CreatePersonalKeyRequest {
+    name: string;
+    /** At least one, and none the caller does not hold. `keys:*` is refused. */
+    scopes: string[];
+    /** ISO-8601 expiration timestamp. Omit for no expiration. */
+    expires_at?: string | null;
+}
+/** The project's service keys. Requires `keys:read` / `keys:write`. @group Models */
 export interface ApiKeysAPI {
     listKeys(): Promise<{
         keys: ApiKeyMasked[];
@@ -110,3 +125,20 @@ export interface ApiKeysAPI {
         success: boolean;
     }>;
 }
+/** The signed-in person's own keys, when the app enables them. @group Models */
+export interface PersonalKeysAPI {
+    listKeys(): Promise<{
+        keys: ApiKeyMasked[];
+    }>;
+    createKey(data: CreatePersonalKeyRequest): Promise<{
+        key: ApiKeyWithSecret;
+    }>;
+    revokeKey(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** Every scope the backend knows, described, and the ones the caller holds. */
+    listScopes(): Promise<{
+        scopes: ScopeSummary[];
+        held: string[];
+    }>;
+}

package/dist/types/auth_adapter.d.ts

@@ -53,6 +53,18 @@ export interface MountableRouter {
     /** The routes the sub-app declares. Only its presence is contractual. */
     routes: readonly unknown[];
 }
+/**
+ * The request header that asks for a data-plane request to run as another
+ * user, named by uid.
+ *
+ * The server honours it only on a signed-in administrator's own session —
+ * never on an API key or the service key — and only through an adapter that
+ * implements {@link AuthAdapter.resolveUser}. Everywhere else a request that
+ * carries it is refused, never run as its caller.
+ *
+ * @group Auth
+ */
+export declare const IMPERSONATE_HEADER = "x-rebase-impersonate";
 /**
  * The normalized user object returned by `AuthAdapter.verifyRequest()`.
  *
@@ -72,7 +84,11 @@ export interface AuthenticatedUser {
     photoUrl?: string | null;
     /** Role identifiers the user holds. */
     roles: string[];
-    /** Whether the user has admin privileges. */
+    /**
+     * Whether `roles` includes `admin`. Informational — every authorization
+     * decision reads `roles` and the scopes they hold, so an adapter that
+     * wants a user treated as an administrator gives them the `admin` role.
+     */
     isAdmin: boolean;
     /**
      * Whether this session is a GUEST — anonymous sign-in rather than an
@@ -90,6 +106,12 @@ export interface AuthenticatedUser {
     rawToken?: string;
     /** Extra claims/metadata from the auth provider. */
     claims?: Record<string, unknown>;
+    /**
+     * What this credential may do, when it is narrower than its person — set
+     * for an API key. Absent means everything the user's roles hold
+     * (`scopesForRoles`).
+     */
+    scopes?: string[];
 }
 /**
  * Feature flags advertised by an auth adapter.
@@ -171,6 +193,26 @@ export interface AuthAdapterCapabilities {
      */
     needsSetup?: boolean;
 }
+/**
+ * What `GET /api/auth/config` answers: the auth adapter's capabilities, plus
+ * the optional features of the backend around it.
+ *
+ * The admin panel reads this document before anything else, so it is where
+ * the panel learns that a feature is off, without first asking for that
+ * feature and getting a refusal.
+ *
+ * @group Auth
+ */
+export interface AuthConfigDocument extends AuthAdapterCapabilities {
+    /**
+     * Whether this backend serves file storage. When it is `false`, no storage
+     * backend is configured: `GET /storage/sources` lists nothing and every
+     * other `/storage` route answers 501 `STORAGE_NOT_CONFIGURED`. Absent from
+     * a backend that predates the field, so a client must ask
+     * `GET /storage/sources` there.
+     */
+    storage?: boolean;
+}
 /**
  * Options for paginated user listing.
  * @group Auth
@@ -217,6 +259,11 @@ export interface AuthCreateUserData {
     displayName?: string;
     photoUrl?: string;
     metadata?: Record<string, unknown>;
+    /**
+     * Store the address as verified: whoever creates the account named it
+     * (an operator, an administrator), so nobody needs to prove it.
+     */
+    emailVerified?: boolean;
 }
 /**
  * User management operations for the admin panel.
@@ -256,6 +303,23 @@ export interface UserCreationPrepareResult {
     /** Whether an invitation was sent (only relevant when hookHandledEmail is true). */
     invitationSent: boolean;
 }
+/**
+ * What the door creating a user knows about its caller, for
+ * `AuthAdapter.prepareUserCreation()`.
+ *
+ * @group Auth
+ */
+export interface UserCreationOptions {
+    /**
+     * Whether the caller may waive the password policy with
+     * `skipPasswordPolicy: true` in the body. The doors set it for an
+     * administrator (the service key signs in as one) and for nobody else, so
+     * an adapter that reads the flag is taking an administrator at their word —
+     * an import of accounts whose passwords were set under another system's
+     * rules. Absent, the flag waives nothing.
+     */
+    mayWaivePasswordPolicy?: boolean;
+}
 /**
  * What a create body for an auth collection may name beyond the collection's
  * own declared fields — see `AuthAdapter.describeUserCreationContract()`.
@@ -275,6 +339,16 @@ export interface UserCreationWriteContract {
      * deletes it before the row is ever built.
      */
     extraFields: string[];
+    /**
+     * Each body's `prepareUserCreation` touches nothing but its own result —
+     * no hook, no email, no write — so a bulk create may prepare several at
+     * once. The built-in adapter's path with no `onCreateUser`, no
+     * `onAdminCreateUser` and the default `hashPassword` is: it hashes a
+     * password and normalizes an email, and a 1,000-row bulk spent half a
+     * minute hashing one password at a time. Leave it unset when a hook runs:
+     * preparations then run one at a time, in the order the rows were given.
+     */
+    independent?: boolean;
 }
 /**
  * Result of `AuthAdapter.finalizeUserCreation()`.
@@ -390,6 +464,23 @@ export interface AuthAdapter {
      * @returns The authenticated user, or `null` if the token is invalid.
      */
     verifyToken?(token: string): Promise<AuthenticatedUser | null>;
+    /**
+     * The identity a verified request from this account would carry right
+     * now, with no credential involved: its uid, its roles as they are now,
+     * its guest flag, and the custom claims a token minted for it now would
+     * hold. `null` when no active account has this uid — none at all, or one
+     * that is disabled.
+     *
+     * This is what lets an administrator run a request as another user (the
+     * {@link IMPERSONATE_HEADER} header). The server calls it only after it
+     * has decided the caller may do that, and it calls it for the caller too,
+     * so the decision rests on the caller's roles as they are now rather than
+     * on the ones their token claims.
+     *
+     * Optional. An adapter without it cannot be impersonated through, and a
+     * request carrying the header is refused rather than run as its caller.
+     */
+    resolveUser?(uid: string): Promise<AuthenticatedUser | null>;
     /**
      * User CRUD for the admin panel's user management UI.
      * Optional — if not provided, user management UI is hidden.
@@ -441,11 +532,15 @@ export interface AuthAdapter {
      *
      * If not implemented, the collection saves values as-is (no password hashing).
      *
+     * A chosen `password` is held to the password policy unless the body says
+     * `skipPasswordPolicy: true` and `options.mayWaivePasswordPolicy` is set.
+     *
      * @param values - Raw request body from the client.
      * @param collectionAuth - The parsed `AuthCollectionConfig` from the collection (if `auth` is an object).
+     * @param options - What the door knows about its caller.
      * @returns Processed values ready for `driver.save()`, plus metadata for the post-save step.
      */
-    prepareUserCreation?(values: Record<string, unknown>, collectionAuth?: unknown): Promise<UserCreationPrepareResult>;
+    prepareUserCreation?(values: Record<string, unknown>, collectionAuth?: unknown, options?: UserCreationOptions): Promise<UserCreationPrepareResult>;
     /**
      * Describe what a create body for this auth collection is allowed to name,
      * so unknown-field validation can run on it.