@rebasepro/types 0.23.0 → 0.24.0

package/dist/types/collection_patch.d.ts

@@ -0,0 +1,74 @@
+/** One change to a collection. `path` is a list of object keys. */
+export type CollectionPatchOp = {
+    op: "set";
+    path: string[];
+    value: unknown;
+} | {
+    op: "remove";
+    path: string[];
+};
+/** @group Models */
+export type CollectionPatch = CollectionPatchOp[];
+/**
+ * Keys the runtime adds to a collection that must never be written into its
+ * source. `resolvedRelation` is the registry's resolved form of a relation; a
+ * file holding one does not type-check (`target` is missing from it).
+ */
+export declare const RUNTIME_ONLY_COLLECTION_KEYS: readonly string[];
+/** A JSON value as JSON would carry it: functions, `undefined` and symbols dropped. */
+export declare function toCollectionJson(value: unknown): unknown;
+/**
+ * The operations that take `before` to `after`, both JSON values.
+ *
+ * Objects are compared key by key; anything else that differs — a primitive,
+ * an array, a change of kind — is set whole.
+ */
+export declare function diffJsonValues(before: unknown, after: unknown, path?: string[]): CollectionPatch;
+/**
+ * The patch, with every flat presentation key moved into its `admin` block.
+ *
+ * The panel edits a flat view model — `icon` beside `name`, a property's
+ * `readOnly` beside its `type` — while the file keeps them under `admin`. The
+ * difference is taken on the flat model, because that is where a cleared field
+ * shows up as a removed key (the `admin` copy the model was loaded with still
+ * holds the old value), and moved here.
+ *
+ * The flat value wins over the `admin` copy, as in {@link nestAdminKeysOf}:
+ * operations that were already under `admin` are ordered first, so the flat
+ * one — what the form just wrote — is applied last.
+ */
+export declare function nestCollectionPatchPaths(patch: CollectionPatch): CollectionPatch;
+/**
+ * The patch that takes the collection the editor loaded to the one it is
+ * saving, in the authoring shape. Empty when nothing changed.
+ *
+ * Both sides go through JSON first, so whatever JSON cannot carry — a
+ * function, a value it drops — is equally absent from both and never appears
+ * as a change.
+ */
+export declare function diffCollections(loaded: unknown, saving: unknown): CollectionPatch;
+/**
+ * Why a patch may not be applied, or an empty list.
+ *
+ * Checked by every door that accepts one: a path is a list of non-empty object
+ * keys that cannot reach a prototype, and no runtime-only key may be written.
+ */
+export declare function collectionPatchProblems(patch: unknown): string[];
+/**
+ * The first runtime-only key (see {@link RUNTIME_ONLY_COLLECTION_KEYS}) found
+ * anywhere in a value, or `undefined`. For the doors that take a whole
+ * collection rather than a patch.
+ */
+export declare function runtimeOnlyKeyIn(value: unknown): string | undefined;
+/** A patch every door may apply: {@link collectionPatchProblems} found nothing. */
+export declare function isCollectionPatch(patch: unknown): patch is CollectionPatch;
+/**
+ * `target` with the patch applied, copying only what it changes.
+ *
+ * Everything the patch does not reach is shared with `target` by reference —
+ * functions, thunks and all — which is what lets a planner see a relation's
+ * `target()` on the patched collection exactly as it was. Intermediate objects
+ * a `set` needs are created; a `remove` of a key that is not there is nothing
+ * to do.
+ */
+export declare function applyCollectionPatch<T>(target: T, patch: CollectionPatch): T;

package/dist/types/collections.d.ts

@@ -4,6 +4,7 @@ import type { User } from "../users/index.js";
 import type { EmailSendResult } from "../controllers/email.js";
 import type { Relation } from "./relations.js";
 import type { SecurityRule } from "./security_rules.js";
+import type { RoleDefinition, ScopeDefinition } from "./scopes.js";
 import type { SearchConfig } from "./search.js";
 import type { CollectionIndex } from "./indexes.js";
 import type { CollectionTenantConfig } from "./tenancy.js";
@@ -614,6 +615,28 @@ export type InferCollectionConfigType<S extends CollectionConfig> = S extends Co
 export interface AuthCollectionConfig {
     /** Set to true to mark this collection as the authentication collection. */
     enabled: boolean;
+    /**
+     * The app's roles and the admin-plane scopes each holds.
+     *
+     * `admin` is built in — it holds every scope — and cannot be declared. A
+     * role used only by RLS policies needs no entry here. See
+     * {@link RoleDefinition}.
+     */
+    roles?: Record<string, RoleDefinition>;
+    /**
+     * Scopes the app defines for its own operations, named `resource:action`
+     * like the built-in ones and checked with `requireScope` in a function.
+     * Every signed-in person holds them; they exist so a key can be narrowed
+     * to one action. See {@link ScopeDefinition}.
+     */
+    scopes?: Record<string, ScopeDefinition>;
+    /**
+     * Let every signed-in account mint personal API keys at
+     * `/api/auth/keys`. A personal key acts as its owner and can never hold
+     * a scope its owner does not. Off by default: each one is a long-lived
+     * credential for the account, and an app opts into handing those out.
+     */
+    personalKeys?: boolean;
     /**
      * Called when an admin creates a user, through the collection REST API or
      * `POST /admin/users`.

package/dist/types/cron.d.ts

@@ -94,7 +94,11 @@ export interface CronJobContext {
     jobId: string;
     /** The current scheduled tick timestamp. */
     scheduledAt: Date;
-    /** A simple logger scoped to this job run. */
+    /**
+     * A simple logger scoped to this job run. Each line is kept with the
+     * run's log entry and also written to the server log at `info`, with a
+     * `cron` field holding the job ID.
+     */
     log: (...args: unknown[]) => void;
     /**
      * Aborted when the run exceeds `timeoutSeconds`, or when the server
@@ -179,11 +183,43 @@ export interface CronJobStatus {
     lastDurationMs?: number;
     /** Error message from the last failed run. */
     lastError?: string;
-    /** Total number of executions since server start. */
+    /**
+     * Executions in the run history: every process's, read from `cron_logs`
+     * where runs are persisted, and this process's own otherwise.
+     */
     totalRuns: number;
-    /** Total number of failed executions since server start. */
+    /** How many of {@link totalRuns} failed. */
     totalFailures: number;
 }
+/**
+ * A job the scheduler refused, and why.
+ *
+ * It is not a `CronJobStatus`: it has no state, no next run and no counters,
+ * because it was never registered. Reporting it as a job with `state: "error"`
+ * would be a lie in the other direction — nothing is going to run it.
+ */
+export interface RejectedCronJob {
+    id: string;
+    name: string;
+    schedule: string;
+    /** Why it was refused — most often `Expected 5 fields, got 6`. */
+    reason: string;
+}
+/** What the cron listing (`GET /admin/cron`) answers. */
+export interface CronJobListing {
+    /** The registered jobs. */
+    jobs: CronJobStatus[];
+    /**
+     * Cron files that did not become jobs: the files that failed to load,
+     * plus the jobs in {@link rejected}. Absent when there are none. None of
+     * them is scheduled.
+     */
+    skipped?: number;
+    /** The jobs the scheduler refused, by name, with the reason. */
+    rejected?: RejectedCronJob[];
+    /** {@link skipped} and {@link rejected}, in a sentence. */
+    note?: string;
+}
 export type CronLogLevel = "info" | "error" | "warn";
 /**
  * A single execution log entry stored in the in-memory ring buffer.

package/dist/types/database_adapter.d.ts

@@ -21,7 +21,7 @@
  */
 import type { DataDriver } from "../controllers/data_driver.js";
 import type { CollectionConfig } from "./collections.js";
-import type { CollectionRegistryInterface, DatabaseAdmin, InitializedDriver, RealtimeProvider, RealtimeSocketLimits, BootstrappedAuth } from "./backend.js";
+import type { CollectionRegistryInterface, DatabaseAdmin, InitializedDriver, RealtimeProvider, RealtimeSocketOptions, BootstrappedAuth } from "./backend.js";
 import type { HistoryConfig } from "../controllers/client.js";
 /**
  * A `DatabaseAdapter` provides data persistence for Rebase.
@@ -78,7 +78,7 @@ export interface DatabaseAdapter {
      * socket's frames: it serves the same rows, and without them a frame had
      * neither. Forwarded for the same reason `adapter` is.
      */
-    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: DataDriver, config?: unknown, adapter?: import("./auth_adapter.js").AuthAdapter, limits?: RealtimeSocketLimits): Promise<void> | void;
+    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: DataDriver, config?: unknown, adapter?: import("./auth_adapter.js").AuthAdapter, limits?: RealtimeSocketOptions): Promise<void> | void;
     /**
      * Ask the database whether it is there, before boot's first real query. See
      * `BackendBootstrapper.verifyConnection` for the contract.

package/dist/types/index.d.ts

@@ -15,6 +15,7 @@ export * from "./entity_callbacks.js";
 export * from "./websockets.js";
 export * from "./backend.js";
 export * from "./schema_editing.js";
+export * from "./collection_patch.js";
 export * from "./channel_bus.js";
 export * from "./data_source.js";
 export * from "./resources.js";
@@ -27,6 +28,7 @@ export * from "./component_ref.js";
 export * from "./auth_adapter.js";
 export * from "./database_adapter.js";
 export * from "./api_keys.js";
+export * from "./scopes.js";
 export * from "./history.js";
 export * from "./postgres_introspection.js";
 export * from "./project_manifest.js";

package/dist/types/project_manifest.d.ts

@@ -132,6 +132,20 @@ export interface RebaseStaticAppConfig {
      * loads and every asset 404s: a blank page with no server error. `rebase
      * build` passes it as `REBASE_APP_BASE` and asserts the emitted HTML honours
      * it. Changing this value requires rebuilding the app.
+     *
+     * **Or a full URL, to give the app a hostname of its own:**
+     * `"https://admin.example.com"`, or `"https://admin.example.com/cms"` for a
+     * path under it. The app then answers only on that hostname, and every app
+     * without one keeps answering on all the others. The URL form is split by
+     * {@link parseAppAddress}: the hostname travels as the bundle's
+     * {@link RebaseBundleStatic.host}, and the path part is what the rules above
+     * (and `REBASE_APP_BASE`) apply to. HTTPS only, with no port, query or
+     * fragment — a hostname is served over TLS by the platform, not chosen per
+     * request.
+     *
+     * On Rebase Cloud the deploy registers the hostname on the project. It is
+     * live once its DNS records verify, which the deploy prints when they don't
+     * yet.
      */
     path?: string;
     /**
@@ -191,6 +205,42 @@ export declare const RESERVED_BACKEND_PREFIXES: readonly ["/api", "/health", "/h
  * that is looser admits paths that will not.
  */
 export declare function reservedPrefixFor(path: string): string | undefined;
+/**
+ * Where a static app answers: on one hostname or all of them, at a path.
+ *
+ * `host` absent is every hostname the project is served on.
+ */
+export interface AppAddress {
+    host?: string;
+    path: string;
+}
+export type AppAddressResult = {
+    ok: true;
+    address: AppAddress;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Split a static app's declared `path` into the hostname it claims and the path
+ * under it.
+ *
+ * `"/admin"` is `{ path: "/admin" }`, returned as written: the path rules
+ * (leading slash, no `..`, reserved prefixes) belong to the caller, which
+ * applies them to the path part of either form. `"https://admin.example.com/cms"`
+ * is `{ host: "admin.example.com", path: "/cms" }`.
+ *
+ * Shared because three parties must read the same value the same way: the CLI
+ * while `rebase.json` is edited, the control plane at deploy intake (a bundle can
+ * come from any CLI, or none), and the runtime choosing which app answers.
+ */
+export declare function parseAppAddress(value: string): AppAddressResult;
+/**
+ * Whether `host` is a public DNS name an app can be given: lowercase labels of
+ * letters, digits and hyphens, at least two of them, not an IP address and not
+ * `localhost`. Internationalised names arrive here already in punycode.
+ */
+export declare function isValidAppHost(host: string): boolean;
 /**
  * One declared storage source, as authored in `rebase.json`.
  *
@@ -375,8 +425,22 @@ export interface RebaseBundleEntrypoints {
 }
 /** One built static app inside a bundle. */
 export interface RebaseBundleStatic {
-    /** Public base path, e.g. `/` or `/admin`. */
+    /** Public base path, e.g. `/` or `/admin`. Always a path, never a URL. */
     path: string;
+    /**
+     * The one hostname this app answers on, lowercase, e.g. `admin.example.com`.
+     *
+     * Absent means every hostname the project is served on, which is what every
+     * app was before this field existed. Present, the app answers only for
+     * requests whose `Host` is exactly this — the path part of its address is
+     * still `path`. At an equal `path`, an app naming the request's hostname
+     * wins over one that does not.
+     *
+     * A runtime that predates this field ignores it and would mount two apps at
+     * the same `path`, so a bundle carrying it must only ever reach a runtime
+     * that reads it. The control plane enforces that at intake.
+     */
+    host?: string;
     /** Bundle-relative directory holding the built assets. */
     dir: string;
     /** Serve `index.html` for unmatched paths under `path`. */

package/dist/types/properties.d.ts

@@ -435,6 +435,13 @@ export interface StringProperty extends BaseProperty {
      * Drizzle append: `.primaryKey()`
      * UI behavior: Field value cannot be changed after creation.
      *
+     * Marking several properties declares one composite key: the table gets a
+     * single `PRIMARY KEY (a, b)` constraint (Drizzle: `primaryKey({ columns })`)
+     * and a row is addressed by all of its key values, joined in declaration
+     * order — `1:::en_US`. A foreign key cannot point at a composite key, so a
+     * relation or reference into such a collection is refused by the schema
+     * generators.
+     *
      * You can set this to `"manual"` for a user-defined ID, or specify a generation strategy:
      * 'uuid' -> Drizzle `.defaultRandom()` (Postgres gen_random_uuid())
      * Or any other string to act as a raw SQL default expression, written either
@@ -565,6 +572,10 @@ export interface NumberProperty extends BaseProperty {
      * Drizzle append: `.primaryKey()`
      * UI behavior: Field value cannot be changed after creation.
      *
+     * Marking several properties declares one composite key — see
+     * {@link StringProperty.isId}. A column whose value the database does not
+     * generate, such as a foreign key that is part of the key, takes `true`.
+     *
      * You can set this to `"manual"` for a user-defined ID, or specify a generation strategy:
      * 'increment' -> PostgreSQL `INTEGER GENERATED BY DEFAULT AS IDENTITY`.
      * Or any other string to act as a raw SQL default expression, bare or in

package/dist/types/schema_editing.d.ts

@@ -24,7 +24,19 @@
  *   changing a type, moving a primary key.
  */
 export type SchemaChangeVerdict = "safe" | "diverges" | "needs-migration";
-export type SchemaChangeKind = "add-collection" | "remove-collection" | "add-property" | "remove-property" | "change-property-type" | "rename-column" | "add-enum-value" | "remove-enum-value" | "change-required" | "change-primary-key" | "rename-table";
+export type SchemaChangeKind = "add-collection" | "remove-collection" | "add-property" | "remove-property" | "change-property-type" | "rename-column" | "add-enum-value" | "remove-enum-value" | "change-required" | "change-primary-key" | "rename-table"
+/** A property key renamed while keeping its column: no data moves. */
+ | "rename-property"
+/** A relation's kind, foreign key or link column changes. */
+ | "change-relation"
+/** A UNIQUE constraint, an index or an update trigger appears or goes. */
+ | "change-constraint"
+/** A column's DEFAULT is set, changed or dropped. */
+ | "change-default"
+/** The proposed collections cannot be planned at all. */
+ | "invalid-collection"
+/** A collection's row-level security policies change. */
+ | "change-security-rules";
 export interface SchemaChange {
     kind: SchemaChangeKind;
     verdict: SchemaChangeVerdict;
@@ -36,6 +48,15 @@ export interface SchemaChange {
     detail: string;
     /** What to do instead, when the verdict is not `safe`. */
     remedy?: string;
+    /**
+     * What "Edit source only" leaves behind for this change: the collection is
+     * committed and the database is not touched. Absent on a change that may
+     * not be written source-only at all — one that would leave a project that
+     * does not start, or reads its data as the wrong type.
+     */
+    sourceOnly?: string;
+    /** The same, in a few words for a commit subject: `column products.sku kept`. */
+    kept?: string;
 }
 export interface ClassifiedSchemaChanges {
     changes: SchemaChange[];
@@ -56,24 +77,23 @@ export interface ClassifiedSchemaChanges {
 export interface SchemaCommitPaths {
     /** Drizzle schema, imported by the backend. */
     schemaFile: string;
-    /** Declarative DDL, what `db push` applies and Atlas diffs against. */
-    ddlFile: string;
-    policiesFile: string;
-    searchFile: string;
-    /** Vector columns and ANN indexes — like search, applied by Rebase not Atlas. */
-    vectorFile: string;
-    /**
-     * `autoValue: "on_update"` triggers and the function they share. Atlas's
-     * free tier will not parse a desired state containing a function, so this
-     * is applied by Rebase like search and vector.
-     */
-    triggersFile: string;
 }
+/**
+ * The SQL `db push` and `db generate` render — `schema.sql`, `policies.sql` and
+ * the rest — is not here, and must not come back. Both commands regenerate it
+ * from the collections before reading it, so nothing ever read a committed
+ * copy; it lives in the gitignored `.rebase/sql/`. When the commit carried it,
+ * it carried a second copy besides: these paths are from the project root,
+ * while the CLI writes beside the backend, so a live edit left `drizzle/` and
+ * `backend/drizzle/` disagreeing about the schema.
+ */
 export declare const DEFAULT_COMMIT_PATHS: SchemaCommitPaths;
 /** One file the commit writes, as content rather than as a path on a disk. */
 export interface SchemaChangeFile {
     path: string;
     contents: string;
+    /** The commit removes this file — a deleted collection. `contents` is ignored. */
+    deleted?: boolean;
 }
 /**
  * Everything a change needs written and run.
@@ -131,5 +151,11 @@ export interface SchemaEditingAdmin {
      */
     planSchemaChange(before: unknown[], after: unknown[], options?: {
         paths?: Partial<SchemaCommitPaths>;
+        /**
+         * Plan a commit of the source alone — "Edit source only": never
+         * rejects an unapplicable change, carries no statements, and its
+         * message names what is left in the database.
+         */
+        sourceOnly?: boolean;
     }): Promise<SchemaChangePlan>;
 }

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