@rebasepro/types 0.25.0 → 0.26.0

package/dist/call_context.d.ts

@@ -4,6 +4,7 @@ import type { RebaseClient } from "./controllers/client.js";
 import type { RebaseSdkData } from "./controllers/data.js";
 import type { User } from "./users/index.js";
 import type { RegisteredDatabase } from "./types/register.js";
+import type { CallerCredential } from "./types/api_keys.js";
 /**
  * The client a collection callback is handed as `context.client`: the Rebase
  * client **without `data`**.
@@ -159,4 +160,21 @@ export type RebaseCallContext<USER extends User = User, DB = RegisteredDatabase>
      * Set by the backend when callbacks are executed on the server.
      */
     user?: USER;
+    /**
+     * The API key the write was made with, when it was one: its `kind`, `id`
+     * and `name`. Absent for a person's own session, a service-key request,
+     * server-context work (`rebase.dataAsAdmin`, crons) and in the browser.
+     *
+     * A personal key acts as its owner, so {@link user} is the owner whether
+     * they saved by hand or a CI job wrote with their key. Read this to tell
+     * the two apart, for example to attribute an audit entry to the token.
+     *
+     * @example
+     * afterSave: async ({ context }) => {
+     *     const who = context.credential
+     *         ? `${context.credential.name} (key of ${context.user?.uid})`
+     *         : context.user?.uid;
+     * }
+     */
+    credential?: CallerCredential;
 };

package/dist/controllers/client.d.ts

@@ -9,6 +9,7 @@ import type { ApiKeysAPI, PersonalKeysAPI } from "../types/api_keys.js";
 import type { RoleSummary } from "../types/scopes.js";
 import type { StorageSourceDefinition } from "../types/storage_source.js";
 import type { RegisteredDatabase } from "../types/register.js";
+import type { AccessSimulation } from "../types/auth_adapter.js";
 /**
  * Event type for authentication state changes
  */
@@ -502,6 +503,24 @@ export interface RebaseClient<DB = unknown> {
     setOnUnauthorized?(handler: () => Promise<boolean>): void;
     /** Resolve the current auth token */
     resolveToken?(): Promise<string | null>;
+    /**
+     * A client whose data requests run with simulated access — as a role, a
+     * uid holding a role, or a service key — for an administrator checking
+     * what row-level security lets that identity read (the admin panel's
+     * "Simulate access" bar).
+     *
+     * Every request carries the `x-rebase-simulate-*` headers and this
+     * client's token; the server honours them on the data API and custom
+     * functions for an administrator's own session and refuses them anywhere
+     * else. The derived client opens no realtime socket (live queries fetch
+     * once), keeps no offline cache, and holds no session: a refusal of its
+     * token is answered by this client. Close it with `close()` when done.
+     *
+     * Read-only: a write, delete, batch, history revert or non-GET function
+     * call through it is refused with `403 SIMULATION_READ_ONLY`, since it
+     * would run as the simulated identity rather than the administrator.
+     */
+    simulate?(simulation: AccessSimulation): RebaseClient<Record<string, unknown>>;
     /**
      * POST to an arbitrary path on the backend — the escape hatch, not the way
      * to call a function.
@@ -522,10 +541,17 @@ export interface RebaseClient<DB = unknown> {
     /**
      * Execute raw SQL against the database.
      * Only available server-side with a SQL database.
+     *
+     * The same options as {@link RebaseServerClient.sql}: pass values through
+     * `params` as `$1`, `$2`, … rather than into the query text. This is what
+     * a collection callback's `context.client.sql` is typed by, and it used to
+     * have no `params`, so the one typed way to run SQL from a hook left
+     * interpolating row values into the string as the way to write it.
      */
     sql?(query: string, options?: {
-        database?: string;
+        database?: ResourceRef;
         role?: string;
+        params?: unknown[];
     }): Promise<Record<string, unknown>[]>;
 }
 /**
@@ -568,6 +594,11 @@ export interface RebaseServerClient<DB = RegisteredDatabase> extends Omit<Rebase
      * engines. Values interpolated into the query should be passed via
      * `params`, referenced as `$1`, `$2`, … placeholders in the query text.
      *
+     * `database` names a declared data source — the handle `database("analytics")`
+     * returned, or its key — and the query runs on that source's own
+     * connection. Omitted, it runs on the default source. A key no configured
+     * source has is refused by name.
+     *
      * **Runtime note.** This is the one accessor on this object that is not
      * portable. It runs on the database owner connection over a TCP socket, so
      * it is available wherever the framework holds that connection — every Node

package/dist/controllers/data_driver.d.ts

@@ -593,6 +593,28 @@ export interface DataDriver {
      * Optional: a driver without it is called directly, read by read.
      */
     readTogether?<T>(work: (driver: DataDriver) => Promise<T>): Promise<T>;
+    /**
+     * Every row a collection stores, as stored, a page at a time: soft-deleted
+     * rows included, and past every read hook — no `beforeQuery`, no
+     * `afterRead`, no per-field read rules.
+     *
+     * For whole-store sweeps run by the server itself, never for a read served
+     * to anyone. `rebase storage orphans` reads it to find the files no row
+     * names: read through `fetchCollection` instead, a `beforeQuery` scoping
+     * rows to `context.user` (there is none in a sweep) or an `afterRead` that
+     * rewrites a file field hides references, and the files they name are
+     * reported as unused and deleted.
+     *
+     * Optional. A sweep reads a collection without read hooks through
+     * `fetchCollection`, and refuses one with read hooks whose driver lacks
+     * this, rather than trust what the hooks let through.
+     */
+    scanStoredRows?(props: {
+        path: string;
+        collection: CollectionConfig;
+        /** Rows per page. */
+        pageSize?: number;
+    }): AsyncIterable<Record<string, unknown>[]>;
     /**
      * Check if the given filter combination is valid
      * @param props

package/dist/index.es.js

@@ -2348,6 +2348,108 @@ function isLazyComponentRef(ref) {
 * @group Auth
 */
 var IMPERSONATE_HEADER = "x-rebase-impersonate";
+/**
+* The request header that asks for a data-plane request to run as a role —
+* the RLS simulator's "view as". Alone it runs as a signed-in holder of that
+* role who owns no rows; with {@link SIMULATE_USER_ID_HEADER} it runs as that
+* uid holding that role, whether or not such an account exists.
+*
+* `anon` (or `anonymous`) runs as a caller with no session at all.
+*
+* Like {@link IMPERSONATE_HEADER}, only a signed-in administrator's own session
+* may send it; anyone else is refused with 403, never answered as themselves.
+*
+* @group Auth
+*/
+var SIMULATE_ROLE_HEADER = "x-rebase-simulate-role";
+/**
+* The uid a simulated request runs as. With {@link SIMULATE_ROLE_HEADER} it is
+* a hypothetical — "u_1 holding customer" — and need not name an account;
+* without it, the uid must be an active user and runs with their roles now.
+*
+* @group Auth
+*/
+var SIMULATE_USER_ID_HEADER = "x-rebase-simulate-user-id";
+/**
+* The id of a service API key a simulated request runs as: the key's identity,
+* its RLS roles and its scopes, exactly as a request presenting the key would.
+* Excludes the other two simulation headers.
+*
+* @group Auth
+*/
+var SIMULATE_API_KEY_ID_HEADER = "x-rebase-simulate-api-key-id";
+/**
+* The response header naming what a simulated request ran as:
+* `role=<role>;sub=<uid>;masked_columns=<a,b>`, plus `api_key=<id>` and
+* `collection=<slug>` when they apply. Every value is URI-encoded. Read it
+* with {@link parseSimulatedContext}.
+*
+* @group Auth
+*/
+var SIMULATED_CONTEXT_HEADER = "x-rebase-simulated-context";
+/**
+* The request headers for an {@link AccessSimulation}. Empty when it asks for
+* nothing, so spreading it into a header set is always safe.
+*
+* @group Auth
+*/
+function simulationHeaders(simulation) {
+	if (!simulation) return {};
+	const headers = {};
+	if (simulation.role) headers[SIMULATE_ROLE_HEADER] = simulation.role;
+	if (simulation.userId) headers[SIMULATE_USER_ID_HEADER] = simulation.userId;
+	if (simulation.apiKeyId) headers[SIMULATE_API_KEY_ID_HEADER] = simulation.apiKeyId;
+	return headers;
+}
+/**
+* Write a {@link SimulatedContext} as the header value.
+*
+* @group Auth
+*/
+function formatSimulatedContext(context) {
+	const parts = [
+		`role=${encodeURIComponent(context.role)}`,
+		`sub=${encodeURIComponent(context.sub)}`,
+		`masked_columns=${context.maskedColumns.map(encodeURIComponent).join(",")}`
+	];
+	if (context.apiKeyId) parts.push(`api_key=${encodeURIComponent(context.apiKeyId)}`);
+	if (context.collection) parts.push(`collection=${encodeURIComponent(context.collection)}`);
+	return parts.join(";");
+}
+/**
+* Read {@link SIMULATED_CONTEXT_HEADER}. `undefined` for an absent header or one
+* missing `role` or `sub`.
+*
+* @group Auth
+*/
+function parseSimulatedContext(value) {
+	if (!value) return void 0;
+	const fields = /* @__PURE__ */ new Map();
+	for (const part of value.split(";")) {
+		const at = part.indexOf("=");
+		if (at > 0) fields.set(part.slice(0, at).trim(), part.slice(at + 1).trim());
+	}
+	const role = fields.get("role");
+	const sub = fields.get("sub");
+	if (role === void 0 || sub === void 0) return void 0;
+	const decode = (raw) => {
+		try {
+			return decodeURIComponent(raw);
+		} catch {
+			return raw;
+		}
+	};
+	const masked = fields.get("masked_columns") ?? "";
+	const apiKeyId = fields.get("api_key");
+	const collection = fields.get("collection");
+	return {
+		role: decode(role),
+		sub: decode(sub),
+		maskedColumns: masked === "" ? [] : masked.split(",").map(decode),
+		...apiKeyId ? { apiKeyId: decode(apiKeyId) } : {},
+		...collection ? { collection: decode(collection) } : {}
+	};
+}
 //#endregion
 //#region src/types/scopes.ts
 /**
@@ -2563,6 +2665,25 @@ function hasAdminRole(roles) {
 	return !!roles?.includes(ADMIN_ROLE);
 }
 /**
+* Why `name` cannot be written as a role, or `undefined` when it can.
+*
+* No naming pattern is imposed — an app may call its roles anything. What is
+* refused is a name that would be read back as *other* roles: a role travels as
+* one element of a Postgres `text[]` and as one entry of the comma-joined
+* `app.user_roles` setting that RLS policies split with
+* `string_to_array(…, ',')`. Written as `"support,admin"`, a role comes back as
+* `admin`; braces, quotes and backslashes are array-literal syntax, so they are
+* refused too, as are empty names and control characters.
+*
+* @group Auth
+*/
+function roleNameProblem(name) {
+	if (typeof name !== "string") return "is not a string";
+	if (name.trim() === "") return "is empty";
+	if (/[,{}"\\]/.test(name)) return "contains , { } \" or \\";
+	if (/[\u0000-\u001f\u007f]/.test(name)) return "contains a control character";
+}
+/**
 * Does a set of held scopes grant `scope`, optionally on one `target`?
 *
 * The unqualified grant covers every target. A qualified grant covers its own
@@ -3694,6 +3815,6 @@ function resolverFromSources(client) {
 	};
 }
 //#endregion
-export { ADMIN_COLLECTION_KEYS, ADMIN_PROPERTY_KEYS, ADMIN_ROLE, ADMIN_SCOPES, ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, BATCH_REF_KEY, BUILT_IN_SCOPES, BUILT_IN_SCOPE_DESCRIPTIONS, BUNDLE_FORMAT_VERSION, CANONICAL_TO_REST, DATA_PLANE_SCOPES, DEFAULT_CAPABILITIES, DEFAULT_COMMIT_PATHS, DEFAULT_DATA_SOURCE_KEY, DEFAULT_FILTERABLE_RELATION_KINDS, DEFAULT_FUZZY_THRESHOLD, DEFAULT_LIST_LIMIT, DEFAULT_RESOURCE_KEY, DEFAULT_SEARCH_COLUMN, DEFAULT_SEARCH_LANGUAGE, DEFAULT_SEARCH_MODE, DEFAULT_SEARCH_WEIGHT, DEFAULT_STORAGE_SOURCE_KEY, DEFAULT_TENANT_BYPASS_ROLES, DEFAULT_VECTOR_LIST_LIMIT, EMPTY_ACCESS_MODEL, EntityReference, EntityRelation, FIELD_OPERATORS, FIREBASE_CAPABILITIES, GeoPoint, IMPERSONATE_HEADER, INCLUDE_COUNT_KEY, JUNCTION_PIVOT_KEY, KEY_MANAGEMENT_SCOPES, LEGACY_RLS_JWT_SQL, LEGACY_RLS_ROLES_SQL, LEGACY_RLS_SCHEMA, LEGACY_RLS_UID_SQL, LIST_OPS, ListLimitError, MAX_INCLUDE_DEPTH, MAX_LIST_LIMIT, MONGODB_CAPABILITIES, NULL_OPS, POSTGRES_CAPABILITIES, PUBLIC_STORAGE_PREFIX, REBASE_SCHEMA, RELEVANCE_SORT_FIELD, RESERVED_BACKEND_PREFIXES, RESOURCE_GRAPH_VERSION, REST_TO_CANONICAL, RLS_IS_ANONYMOUS_SQL, RLS_JWT_SQL, RLS_ROLES_SQL, RLS_UID_SQL, RUNTIME_CONTRACT_VERSION, RUNTIME_ONLY_COLLECTION_KEYS, RebaseApiError, RebaseClientError, SCHEMA_VERSION_HEADER, SCOPE_TARGETS, STORAGE_REFERENCE_SCHEME, Vector, amendResourceKind, applyCollectionPatch, bucket, buildResourceGraph, canonicalSchemaPayload, collectionPatchProblems, computeSchemaVersion, database, declareCron, declareFunction, declareResource, declaredDataSources, declaredDatabaseExtensions, declaredQueueConsumers, declaredResources, declaredStorageSources, declaredSubscriptions, describeScope, deserializeCollections, diffCollections, diffJsonValues, encodeRelationAggregateSort, envBasesForResource, findEnvSuffixCollision, findStorageSuffixCollision, getCollectionDataPath, getDataSourceCapabilities, getDeclaredSubcollections, hasAdminRole, hasFieldOperation, hasForeignKeyOnTarget, intersectScopes, isAdminScope, isAnonymousUid, isBranchAdmin, isBuiltInScope, isChannelBusInstance, isCollectionPatch, isContentHashedFileName, isDataPlaneScope, isDocumentAdmin, isFieldOperation, isFirebaseCollectionConfig, isLazyComponentRef, isManyToMany, isMongoDBCollectionConfig, isPostgresCollectionConfig, isPublicStorageKey, isPublicStoragePath, isRelationAggregateSort, isRelationalCollectionConfig, isResourceHandle, isSQLAdmin, isSchemaAdmin, isSchemaEditingAdmin, isSerializedCollectionRef, isStorageReference, isTenantClaimSource, isTenantMembershipSource, isToMany, isUnsupported, isValidAppHost, isValidEngine, knownScopes, nestAdminCollectionKeys, nestAdminKeysOf, nestAdminPropertyKeys, nestCollectionPatchPaths, parseAppAddress, parseEnvBoolean, parseRelationAggregateSort, parseScope, parseStorageReference, policy, queue, registerDataSourceCapabilities, registerResourceKind, reservedPrefixFor, resetDeclaredQueueConsumers, resetDeclaredResources, resetDeclaredSubscriptions, resolveClientListLimit, resolveResourceRefs, resolveStorageReferences, resourceEnvSuffix, resourceId, resourceKeyOf, resourceKind, resourceKinds, resourceToDataSource, resourceToStorageSource, rewriteLegacyRlsFunctions, runtimeOnlyKeyIn, scopeAcceptsTarget, scopeGrants, scopeGrantsAny, scopeTargets, scopesBeyond, scopesForRoles, serializeCollections, setQueueRuntime, setTopicRuntime, sortKeyToString, storageEnvSuffix, storageObjectPath, storageReference, storageReferencesForDownloadUrls, storageTargetOfDownloadUrl, storageTargetsInText, summarizeRoles, summarizeScopes, toCanonicalOp, toCollectionJson, topic, unsupportedMethod, usesLegacyRlsFunctions, validateScopes };
+export { ADMIN_COLLECTION_KEYS, ADMIN_PROPERTY_KEYS, ADMIN_ROLE, ADMIN_SCOPES, ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, BATCH_REF_KEY, BUILT_IN_SCOPES, BUILT_IN_SCOPE_DESCRIPTIONS, BUNDLE_FORMAT_VERSION, CANONICAL_TO_REST, DATA_PLANE_SCOPES, DEFAULT_CAPABILITIES, DEFAULT_COMMIT_PATHS, DEFAULT_DATA_SOURCE_KEY, DEFAULT_FILTERABLE_RELATION_KINDS, DEFAULT_FUZZY_THRESHOLD, DEFAULT_LIST_LIMIT, DEFAULT_RESOURCE_KEY, DEFAULT_SEARCH_COLUMN, DEFAULT_SEARCH_LANGUAGE, DEFAULT_SEARCH_MODE, DEFAULT_SEARCH_WEIGHT, DEFAULT_STORAGE_SOURCE_KEY, DEFAULT_TENANT_BYPASS_ROLES, DEFAULT_VECTOR_LIST_LIMIT, EMPTY_ACCESS_MODEL, EntityReference, EntityRelation, FIELD_OPERATORS, FIREBASE_CAPABILITIES, GeoPoint, IMPERSONATE_HEADER, INCLUDE_COUNT_KEY, JUNCTION_PIVOT_KEY, KEY_MANAGEMENT_SCOPES, LEGACY_RLS_JWT_SQL, LEGACY_RLS_ROLES_SQL, LEGACY_RLS_SCHEMA, LEGACY_RLS_UID_SQL, LIST_OPS, ListLimitError, MAX_INCLUDE_DEPTH, MAX_LIST_LIMIT, MONGODB_CAPABILITIES, NULL_OPS, POSTGRES_CAPABILITIES, PUBLIC_STORAGE_PREFIX, REBASE_SCHEMA, RELEVANCE_SORT_FIELD, RESERVED_BACKEND_PREFIXES, RESOURCE_GRAPH_VERSION, REST_TO_CANONICAL, RLS_IS_ANONYMOUS_SQL, RLS_JWT_SQL, RLS_ROLES_SQL, RLS_UID_SQL, RUNTIME_CONTRACT_VERSION, RUNTIME_ONLY_COLLECTION_KEYS, RebaseApiError, RebaseClientError, SCHEMA_VERSION_HEADER, SCOPE_TARGETS, SIMULATED_CONTEXT_HEADER, SIMULATE_API_KEY_ID_HEADER, SIMULATE_ROLE_HEADER, SIMULATE_USER_ID_HEADER, STORAGE_REFERENCE_SCHEME, Vector, amendResourceKind, applyCollectionPatch, bucket, buildResourceGraph, canonicalSchemaPayload, collectionPatchProblems, computeSchemaVersion, database, declareCron, declareFunction, declareResource, declaredDataSources, declaredDatabaseExtensions, declaredQueueConsumers, declaredResources, declaredStorageSources, declaredSubscriptions, describeScope, deserializeCollections, diffCollections, diffJsonValues, encodeRelationAggregateSort, envBasesForResource, findEnvSuffixCollision, findStorageSuffixCollision, formatSimulatedContext, getCollectionDataPath, getDataSourceCapabilities, getDeclaredSubcollections, hasAdminRole, hasFieldOperation, hasForeignKeyOnTarget, intersectScopes, isAdminScope, isAnonymousUid, isBranchAdmin, isBuiltInScope, isChannelBusInstance, isCollectionPatch, isContentHashedFileName, isDataPlaneScope, isDocumentAdmin, isFieldOperation, isFirebaseCollectionConfig, isLazyComponentRef, isManyToMany, isMongoDBCollectionConfig, isPostgresCollectionConfig, isPublicStorageKey, isPublicStoragePath, isRelationAggregateSort, isRelationalCollectionConfig, isResourceHandle, isSQLAdmin, isSchemaAdmin, isSchemaEditingAdmin, isSerializedCollectionRef, isStorageReference, isTenantClaimSource, isTenantMembershipSource, isToMany, isUnsupported, isValidAppHost, isValidEngine, knownScopes, nestAdminCollectionKeys, nestAdminKeysOf, nestAdminPropertyKeys, nestCollectionPatchPaths, parseAppAddress, parseEnvBoolean, parseRelationAggregateSort, parseScope, parseSimulatedContext, parseStorageReference, policy, queue, registerDataSourceCapabilities, registerResourceKind, reservedPrefixFor, resetDeclaredQueueConsumers, resetDeclaredResources, resetDeclaredSubscriptions, resolveClientListLimit, resolveResourceRefs, resolveStorageReferences, resourceEnvSuffix, resourceId, resourceKeyOf, resourceKind, resourceKinds, resourceToDataSource, resourceToStorageSource, rewriteLegacyRlsFunctions, roleNameProblem, runtimeOnlyKeyIn, scopeAcceptsTarget, scopeGrants, scopeGrantsAny, scopeTargets, scopesBeyond, scopesForRoles, serializeCollections, setQueueRuntime, setTopicRuntime, simulationHeaders, sortKeyToString, storageEnvSuffix, storageObjectPath, storageReference, storageReferencesForDownloadUrls, storageTargetOfDownloadUrl, storageTargetsInText, summarizeRoles, summarizeScopes, toCanonicalOp, toCollectionJson, topic, unsupportedMethod, usesLegacyRlsFunctions, validateScopes };
 
 //# sourceMappingURL=index.es.js.map