@rebasepro/types 0.22.0 → 0.24.0

package/dist/types/scopes.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Scopes — what a credential may do, named `resource:action`.
+ *
+ * One vocabulary for every way of reaching a Rebase backend: a person's
+ * session, a service key, a personal key and an OAuth token for `/mcp` all
+ * answer "may this caller do X?" with the same strings, so a grant reads the
+ * same on a key, on a role and on a consent screen.
+ *
+ * A scope may carry a target — `data:read:posts` is `data:read` on the `posts`
+ * collection only. The unqualified scope covers every target. Only the data
+ * plane and app scopes take targets; see {@link SCOPE_TARGETS}.
+ *
+ * Two planes, held differently:
+ *
+ * - **The data plane** (`data:*`, `storage:*`, `functions:invoke`). Every
+ *   signed-in person holds all of it, because what a person may do with data
+ *   is decided row by row by the collection's `securityRules` and by storage
+ *   policies, never by a scope. On a key or a token these scopes narrow: a key
+ *   holding `data:read:posts` reaches nothing else, whatever RLS would allow.
+ * - **The admin plane** (everything else). Nobody holds it implicitly. The
+ *   `admin` role holds all of it; any other role holds what the app declares
+ *   for it under `auth.roles` on the users collection.
+ *
+ * Apps declare their own scopes too (`auth.scopes`), named the same way —
+ * `project:deploy`. Every signed-in person holds every app scope: like the data
+ * plane, the function behind it decides whether the person may act, and the
+ * scope exists so a key can be narrowed to that one action.
+ *
+ * @module
+ */
+/** @group Auth */
+export declare const DATA_PLANE_SCOPES: readonly ["data:read", "data:write", "data:delete", "storage:read", "storage:write", "storage:delete", "functions:invoke"];
+/** @group Auth */
+export declare const ADMIN_SCOPES: readonly ["users:read", "users:write", "schema:read", "schema:write", "database:read", "database:write", "backups:read", "cron:read", "cron:write", "logs:read", "keys:read", "keys:write"];
+/** @group Auth */
+export type DataPlaneScope = (typeof DATA_PLANE_SCOPES)[number];
+/** @group Auth */
+export type AdminScope = (typeof ADMIN_SCOPES)[number];
+/** @group Auth */
+export type BuiltInScope = DataPlaneScope | AdminScope;
+/** Every scope Rebase itself defines, in display order. @group Auth */
+export declare const BUILT_IN_SCOPES: readonly BuiltInScope[];
+/**
+ * Scopes no key may hold.
+ *
+ * A key that could manage keys could mint its own successor, widen itself, or
+ * revoke the keys other integrations run on — and revoking it would undo none
+ * of that. Managing keys is for a person (or the service key).
+ *
+ * @group Auth
+ */
+export declare const KEY_MANAGEMENT_SCOPES: readonly AdminScope[];
+/** The one built-in role. It holds every scope and is the RLS `admin` role. @group Auth */
+export declare const ADMIN_ROLE = "admin";
+/** What a scope's target names. @group Auth */
+export type ScopeTargetKind = "collection" | "bucket" | "function";
+/**
+ * The built-in scopes that accept a target, and what the target names.
+ *
+ * - `data:*` — a collection slug
+ * - `storage:*` — a storage source id (`(default)` for the default source)
+ * - `functions:invoke` — a custom function's name
+ *
+ * @group Auth
+ */
+export declare const SCOPE_TARGETS: Readonly<Partial<Record<BuiltInScope, ScopeTargetKind>>>;
+/** A scope's wording, for the screens that ask a person to grant it. @group Auth */
+export interface ScopeDescription {
+    /** Short, imperative: what a holder may do. */
+    label: string;
+    /** One sentence on what that reaches, including anything surprising. */
+    description: string;
+}
+/** @group Auth */
+export declare const BUILT_IN_SCOPE_DESCRIPTIONS: Readonly<Record<BuiltInScope, ScopeDescription>>;
+/**
+ * An app-declared scope, under `auth.scopes` on the users collection.
+ *
+ * @example
+ * ```ts
+ * auth: {
+ *     enabled: true,
+ *     scopes: {
+ *         "project:deploy": { label: "Deploy projects", target: "project" }
+ *     }
+ * }
+ * ```
+ *
+ * @group Auth
+ */
+export interface ScopeDefinition {
+    /** Short, imperative: what a holder may do. Shown wherever the scope is granted. */
+    label: string;
+    /** One sentence on what that reaches. */
+    description?: string;
+    /**
+     * What a target names, when the scope accepts one — `"project"` lets a
+     * key hold `project:deploy:<id>`. Unset, the scope takes no target.
+     */
+    target?: string;
+}
+/**
+ * An app-declared role, under `auth.roles` on the users collection.
+ *
+ * A role is a name the database sees (RLS policies match it) and a bundle of
+ * admin-plane and app scopes. Data-plane scopes are not role scopes: what a
+ * person may do with data is the collection's `securityRules`, so listing
+ * `data:write` here would read as a grant it is not, and is refused.
+ *
+ * @example
+ * ```ts
+ * auth: {
+ *     enabled: true,
+ *     roles: {
+ *         support: { name: "Support", scopes: ["users:read", "users:write", "logs:read"] },
+ *         developer: { name: "Developer", scopes: ["schema:read", "database:read", "logs:read", "cron:read"] }
+ *     }
+ * }
+ * ```
+ *
+ * @group Auth
+ */
+export interface RoleDefinition {
+    /** Display name. Defaults to the role id. */
+    name?: string;
+    /** One sentence on who holds it. */
+    description?: string;
+    /** Admin-plane and app scopes the role holds. */
+    scopes: readonly string[];
+}
+/**
+ * The declared access model: the app's own scopes and roles beside the
+ * built-in ones. What `scopesForRoles` and `validateScopes` read.
+ *
+ * @group Auth
+ */
+export interface AccessModel {
+    roles: Readonly<Record<string, RoleDefinition>>;
+    scopes: Readonly<Record<string, ScopeDefinition>>;
+}
+/** The access model of an app that declares nothing: built-ins only. @group Auth */
+export declare const EMPTY_ACCESS_MODEL: AccessModel;
+/** A scope string split into its scope and optional target. @group Auth */
+export interface ParsedScope {
+    /** `resource:action`. */
+    scope: string;
+    /** The one collection, bucket, function or app resource it is narrowed to. */
+    target?: string;
+}
+/**
+ * Split `resource:action[:target]`. Returns null for anything else.
+ *
+ * The target is everything after the second colon, so a target may itself
+ * contain colons. Resource and action are lower-case words.
+ *
+ * @group Auth
+ */
+export declare function parseScope(value: string): ParsedScope | null;
+/** @group Auth */
+export declare function isBuiltInScope(scope: string): scope is BuiltInScope;
+/** @group Auth */
+export declare function isDataPlaneScope(scope: string): scope is DataPlaneScope;
+/** @group Auth */
+export declare function isAdminScope(scope: string): scope is AdminScope;
+/** Does this list of roles include the built-in `admin` role? @group Auth */
+export declare function hasAdminRole(roles: readonly string[] | null | undefined): boolean;
+/**
+ * Does a set of held scopes grant `scope`, optionally on one `target`?
+ *
+ * The unqualified grant covers every target. A qualified grant covers its own
+ * target only, and never answers an unqualified question: a key holding
+ * `data:read:posts` is not asked "may you read data?" and told yes.
+ *
+ * @group Auth
+ */
+export declare function scopeGrants(held: readonly string[], scope: string, target?: string): boolean;
+/**
+ * Does a set of held scopes grant `scope` on at least one target?
+ *
+ * For a surface that lists what is reachable — the collections an MCP client
+ * may query — and filters per item afterwards.
+ *
+ * @group Auth
+ */
+export declare function scopeGrantsAny(held: readonly string[], scope: string): boolean;
+/**
+ * The targets a held set narrows `scope` to: `"all"` when it holds the
+ * unqualified scope, otherwise the listed targets (possibly none).
+ *
+ * @group Auth
+ */
+export declare function scopeTargets(held: readonly string[], scope: string): "all" | string[];
+/**
+ * Every scope a person holding `roles` has.
+ *
+ * The data plane and every app scope always; the whole admin plane with the
+ * `admin` role; otherwise each declared role's scopes. A role nobody declared
+ * adds nothing — it may still mean something to an RLS policy.
+ *
+ * @group Auth
+ */
+export declare function scopesForRoles(roles: readonly string[] | null | undefined, model?: AccessModel): string[];
+/**
+ * Every scope this access model knows, unqualified: the built-ins, then the
+ * app's own.
+ *
+ * @group Auth
+ */
+export declare function knownScopes(model?: AccessModel): string[];
+/** Does this scope accept a target? @group Auth */
+export declare function scopeAcceptsTarget(scope: string, model?: AccessModel): boolean;
+/** How a scope string failed to validate. @group Auth */
+export interface ScopeProblem {
+    scope: string;
+    reason: "malformed" | "unknown" | "target-not-accepted";
+}
+/**
+ * Check a list of scope strings against an access model. Returns the
+ * problems, empty when every entry is a known scope with an acceptable target.
+ *
+ * @group Auth
+ */
+export declare function validateScopes(values: readonly unknown[], model?: AccessModel): ScopeProblem[];
+/**
+ * The entries of `requested` that `held` does not cover — what a credential
+ * would hold beyond its minter. Empty means the request is within reach.
+ *
+ * `data:read:posts` is covered by `data:read`; `data:read` is not covered by
+ * `data:read:posts`.
+ *
+ * @group Auth
+ */
+export declare function scopesBeyond(requested: readonly string[], held: readonly string[]): string[];
+/**
+ * Narrow `requested` to what `held` covers, entry by entry. What a personal
+ * key holds today when its owner has lost a role since it was minted.
+ *
+ * @group Auth
+ */
+export declare function intersectScopes(requested: readonly string[], held: readonly string[]): string[];
+/**
+ * How a scope is worded for a person: the built-in description, the app's
+ * declared label, or the raw string when nothing describes it. A target is
+ * named after the label.
+ *
+ * @group Auth
+ */
+export declare function describeScope(value: string, model?: AccessModel): ScopeDescription;
+/** A role as a person managing access sees it. @group Auth */
+export interface RoleSummary {
+    id: string;
+    name: string;
+    description?: string;
+    /** Admin-plane and app scopes. The `admin` role lists every admin-plane scope. */
+    scopes: string[];
+    /** True for `admin`, which the app does not declare. */
+    builtIn: boolean;
+}
+/** A scope as a screen that grants it lists it. @group Auth */
+export interface ScopeSummary {
+    scope: string;
+    label: string;
+    description: string;
+    /** What a target names, when the scope takes one. */
+    target?: string;
+    /** `data`, `admin` or `app`: which plane the scope belongs to. */
+    plane: "data" | "admin" | "app";
+}
+/** The roles of an access model, `admin` first. @group Auth */
+export declare function summarizeRoles(model?: AccessModel): RoleSummary[];
+/** Every scope of an access model, described, in display order. @group Auth */
+export declare function summarizeScopes(model?: AccessModel): ScopeSummary[];

package/dist/types/security_rules.d.ts

@@ -53,7 +53,7 @@ export type SecurityOperation = "select" | "insert" | "update" | "delete" | "all
  *
  * @group Models
  */
-export type SecurityRule = OwnerSecurityRule | PublicSecurityRule | StructuredSecurityRule | RawSQLSecurityRule | RolesOnlySecurityRule;
+export type SecurityRule = OwnerSecurityRule | PublicSecurityRule | StructuredSecurityRule | RawSQLSecurityRule | RawSQLCheckOnlySecurityRule | RolesOnlySecurityRule;
 /**
  * Shared fields for all SecurityRule variants.
  * @group Models
@@ -297,6 +297,33 @@ export interface RawSQLSecurityRule extends SecurityRuleBase {
     condition?: never;
     check?: never;
 }
+/**
+ * Security rule with a raw SQL `WITH CHECK` clause and no `USING` clause — the
+ * shape of every INSERT policy, which checks the row being written and has no
+ * existing row to filter.
+ *
+ * On an operation that takes a `USING` clause, the missing one grants no rows,
+ * as a Postgres policy without one does.
+ *
+ * @example
+ * // Anyone may insert a row they own
+ * { operation: "insert", withCheck: "{owner_id} = rebase.uid()" }
+ *
+ * @group Models
+ */
+export interface RawSQLCheckOnlySecurityRule extends SecurityRuleBase {
+    /**
+     * Raw SQL expression for the `WITH CHECK` clause.
+     * This controls which *new/updated* row values are allowed.
+     * Applied to INSERT and UPDATE.
+     */
+    withCheck: string;
+    using?: never;
+    ownerField?: never;
+    access?: never;
+    condition?: never;
+    check?: never;
+}
 /**
  * Security rule that only filters by application roles, without any
  * row-level condition (USING/WITH CHECK).

package/dist/types/storage_authorize.d.ts

@@ -22,7 +22,11 @@ export interface StorageAuthorizeContext {
     operation: StorageOperation;
     /** Null when the route allows unauthenticated access. */
     user: StorageAuthorizeUser | null;
-    /** Named backend the request targeted, when one was given. */
+    /**
+     * Named backend the request targeted, when one was given — as its canonical
+     * key, the one the request is served from (`" media "` arrives as
+     * `"media"`). Absent for the default source, however the request named it.
+     */
     storageId?: string;
     /**
      * Trusted, RLS-bypassing data access, so the hook can answer the question it

package/dist/users/user.d.ts

@@ -45,6 +45,13 @@ export type User = {
      * Whether the user's email address has been verified.
      */
     readonly emailVerified?: boolean;
+    /**
+     * The address this account is moving to, while the link mailed there is
+     * waiting to be followed (`client.auth.changeEmail`). `email` stays the
+     * account's address until then. `null` or absent when no change is
+     * waiting.
+     */
+    readonly pendingEmail?: string | null;
     /**
      * Role IDs assigned to this user (e.g. `["admin", "editor"]`).
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/types",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "keywords": [
     "rebase",
@@ -46,7 +46,7 @@
     "@types/node": "^26.1.2",
     "@types/object-hash": "^3.0.6",
     "@types/react-measure": "^2.0.12",
-    "hono": "^4.13.0",
+    "hono": "^4.13.5",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.12",
     "typescript": "^6.0.3",