@rebasepro/types 0.17.3 → 0.18.1

package/src/types/storage_authorize.ts

@@ -1,77 +0,0 @@
-/**
- * The storage access-control contract.
- *
- * Lives here rather than in `@rebasepro/server` because a project declares its
- * `storageAuthorize` hook from its **config package**, and a config package
- * depends on `@rebasepro/types` alone. A type the contract requires but the
- * contract's author cannot import is not much of a contract.
- *
- * `@rebasepro/server` re-exports all of this, so existing imports keep working.
- */
-
-export type StorageOperation = "read" | "write" | "delete" | "list";
-
-/** The caller, as resolved by whichever auth middleware ran. */
-export interface StorageAuthorizeUser {
-    uid: string;
-    email?: string;
-    roles?: string[];
-}
-
-export interface StorageAuthorizeContext {
-    /** Object key, bucket prefix stripped and traversal already sanitized. */
-    key: string;
-    bucket: string;
-    operation: StorageOperation;
-    /** Null when the route allows unauthenticated access. */
-    user: StorageAuthorizeUser | null;
-    /** Named backend the request targeted, when one was given. */
-    storageId?: string;
-    /**
-     * Trusted, RLS-bypassing data access, so the hook can answer the question it
-     * actually has to answer: *who owns this object?*
-     *
-     * Without it the hook can only do prefix arithmetic on the key, which
-     * expresses no real multi-tenant rule — ownership lives in a row, not in a
-     * string. And it cannot simply import the server to get one: a project
-     * declares this hook from its **config** package, which depends on
-     * `@rebasepro/types` alone and cannot resolve `@rebasepro/server` at
-     * runtime. So the accessor is handed in.
-     *
-     * It bypasses row-level security on purpose. The hook IS the authorization
-     * decision; asking it to make that decision through a reader that has
-     * already been narrowed by the caller's own permissions is circular.
-     */
-    data?: StorageAuthorizeData;
-}
-
-/**
- * The slice of the data API a storage hook needs: read a collection, in the
- * trusted server context.
- *
- * Deliberately read-only and deliberately tiny. A hook that can write is a hook
- * that can be tricked into writing, and an authorization check has no business
- * mutating anything.
- */
-export interface StorageAuthorizeData {
-    collection(slug: string): {
-        find(query?: Record<string, unknown>): Promise<{ data: Record<string, unknown>[] }>;
-        findById(id: string): Promise<Record<string, unknown> | null>;
-    };
-}
-
-/**
- * Per-object access control for storage, the analogue of an RLS policy on a
- * collection.
- *
- * Without it, storage routes authenticate but do not authorize: `requireAuth`
- * and `publicRead` are global switches, so any signed-in user could read any
- * key they could name. That is fine for a single-tenant app and useless for a
- * multi-tenant one, where the only thing separating two tenants' files would be
- * key unguessability — not an access-control model. Multi-tenant apps were
- * left to route every byte through a custom function to get an ownership check
- * in, and each of them had to invent it.
- *
- * Return false (or throw) to deny. Denials surface as 403.
- */
-export type StorageAuthorize = (ctx: StorageAuthorizeContext) => boolean | Promise<boolean>;

package/src/types/storage_source.ts

@@ -1,248 +0,0 @@
-/**
- * Describes a named storage backend — a place files live.
- *
- * Declared once and shared front + back: the frontend uses it to decide
- * transport (HTTP proxy vs direct SDK), the backend uses the same `key`
- * to resolve a StorageController, and collection properties reference
- * a definition by its `key` via `StorageConfig.storageSource`.
- *
- * This mirrors the {@link DataSourceDefinition} pattern used for databases.
- *
- * @group Models
- */
-
-/**
- * The default storage source key, used when a property does not specify
- * a `storageSource`. Shared by the frontend and backend registries so
- * both agree on "the default storage backend".
- * @group Models
- */
-export const DEFAULT_STORAGE_SOURCE_KEY = "(default)";
-
-/**
- * How the *frontend* reaches a storage backend.
- *
- * - `"server"` — through the Rebase backend REST API (`/api/storage`).
- *   The backend holds the actual `StorageController` and routes by
- *   storage-source key. This is the default and covers Local, S3, GCS,
- *   and any other server-mediated engine.
- * - `"direct"` — straight from the client to the external backend via
- *   its own SDK (e.g. Firebase Storage via `@firebase/storage`).
- *   The Rebase backend is **not** in the upload/download path.
- *
- * @group Models
- */
-export type StorageSourceTransport = "server" | "direct";
-
-/**
- * Declarative definition of a storage source — a named place files live.
- *
- * Declared once and shared front and back: the frontend uses it to decide
- * transport (client HTTP proxy vs direct provider SDK), the backend uses
- * the same `key` to resolve a `StorageController`, and collection
- * properties reference a definition by its `key` via
- * `StorageConfig.storageSource`.
- *
- * @group Models
- */
-export interface StorageSourceDefinition {
-    /**
-     * Unique identifier for this storage source. Collection properties
-     * point at it via `StorageConfig.storageSource`.
-     * Defaults to {@link DEFAULT_STORAGE_SOURCE_KEY}.
-     */
-    key: string;
-
-    /**
-     * The engine backing this storage source (e.g. `"local"`, `"s3"`,
-     * `"gcs"`, `"firebase"`, `"azure"`, or a custom id).
-     */
-    engine: string;
-
-    /**
-     * The credential set this source signs with, when several sources share one.
-     *
-     * ## What it is for
-     *
-     * Every binding a bucket needs is read per key — `S3_BUCKET__MEDIA`,
-     * `S3_ACCESS_KEY_ID__MEDIA`, and so on. That is right for the bucket *name*,
-     * which is different for every source by definition, and wrong for the
-     * credentials, which usually are not: fifteen buckets on one MinIO install
-     * meant fifteen copies of the same endpoint, access key and secret — ninety
-     * variables where eighteen would do, and one key rotation became fifteen
-     * paired edits where a single missed one fails at upload time with an opaque
-     * signing error.
-     *
-     * Naming an account here lets the *account-scoped* bindings fall back to
-     * `<BASE>__<ACCOUNT>` when no per-key value is set. The bucket name never
-     * falls back: it is what distinguishes one source from another.
-     *
-     * ## Why it does not fall back to the bare variable
-     *
-     * A source with no `account` reads only its own suffixed names, exactly as
-     * before — so every project that predates this is wire-identical. The
-     * unsuffixed `S3_ACCESS_KEY_ID` belongs to the *default* source, and letting
-     * a named bucket inherit it would mean a typo'd key silently signs with
-     * another source's credentials. Two forms, both explicit, opt-in.
-     */
-    account?: string;
-
-    /**
-     * How the frontend reaches this storage. Defaults to `"server"`.
-     *
-     * When `"direct"`, the client uses a provider-specific SDK
-     * (e.g. `@firebase/storage`) and the backend does not proxy
-     * upload/download traffic for this source.
-     */
-    transport: StorageSourceTransport;
-
-    /** Human-readable label for the UI (e.g. "Firebase Storage", "S3 Media"). */
-    label?: string;
-}
-
-/**
- * A resolved storage source: the single source of truth that the frontend
- * router and backend registry both derive from.
- *
- * @group Models
- */
-export interface ResolvedStorageSource {
-    /** Storage source key (routing key, shared front + back). */
-    key: string;
-    /** Engine backing the source. */
-    engine: string;
-    /** Frontend transport. */
-    transport: StorageSourceTransport;
-    /** Human-readable label. */
-    label?: string;
-}
-
-/**
- * The environment-variable suffix for a storage or data source key.
- *
- * `""` for the default source — so a single-bucket project keeps configuring
- * plain `S3_BUCKET` — and `__<KEY>` for every named one, uppercased with
- * non-alphanumerics collapsed to underscores: `media-cdn` → `S3_BUCKET__MEDIA_CDN`.
- *
- * The rule derives the variable name from the declared key rather than
- * discovering keys by scanning the environment. Scanning would have to guess how
- * `S3_BUCKET__MEDIA_CDN` splits into a key; deriving cannot be ambiguous, and a
- * typo surfaces as a missing source at boot instead of a silently ignored
- * variable.
- *
- * It lives in this package, with no dependencies, because four things must agree
- * on it exactly: the CLI (validating a build), the runtime (reading its own
- * environment), the control plane (writing a tenant's Secret), and the docs. A
- * second implementation of a naming convention is a second chance to disagree.
- *
- * @group Models
- */
-export function storageEnvSuffix(key: string, defaultKey: string = DEFAULT_STORAGE_SOURCE_KEY): string {
-    if (!key || key === defaultKey) return "";
-    const normalized = key
-        .replace(/[^A-Za-z0-9]+/g, "_")
-        .replace(/^_+|_+$/g, "")
-        .toUpperCase();
-    if (!normalized) {
-        throw new Error(
-            `Source key "${key}" cannot be turned into an environment variable name. ` +
-            "Use a key containing at least one letter or digit."
-        );
-    }
-    return `__${normalized}`;
-}
-
-/**
- * Two distinct keys that collapse onto the same variable name, or `null`.
- *
- * `media-cdn` and `media_cdn` are different source keys but the same suffix, so
- * without this one of them silently reads the other's configuration. Returns the
- * offending pair rather than throwing, so each caller can raise it in its own
- * idiom — a `BundleError` at boot, a build failure in the CLI, a rejected deploy
- * in a control plane.
- *
- * @group Models
- */
-export function findStorageSuffixCollision(
-    keys: string[],
-    defaultKey: string = DEFAULT_STORAGE_SOURCE_KEY
-): { a: string; b: string; suffix: string } | null {
-    const seen = new Map<string, string>();
-    for (const key of keys) {
-        const suffix = storageEnvSuffix(key, defaultKey);
-        const existing = seen.get(suffix);
-        if (existing !== undefined && existing !== key) {
-            return { a: existing, b: key, suffix };
-        }
-        seen.set(suffix, key);
-    }
-    return null;
-}
-
-/** The `storage` block of `rebase.json`, structurally. */
-export type DeclaredStorageSources = Record<string, {
-    engine: string;
-    transport?: StorageSourceTransport;
-    label?: string;
-}>;
-
-/**
- * Merge the two places a project may declare storage sources into one list.
- *
- * `rebase.json` is authoritative for every field it states. Config code may add
- * sources it does not mention and fill in fields it left out, but may not
- * contradict it: the manifest is what a host reads to decide which buckets need
- * configuring, and a runtime that quietly disagreed with it would put the
- * console back to describing a topology the tenant does not have — the exact
- * failure this whole mechanism exists to end.
- *
- * Note what is *not* here: no default source is invented when both inputs are
- * empty. That decision belongs to the resolver, which knows whether declaring
- * nothing means "one plain bucket" (it does) or "no storage at all".
- *
- * @group Models
- */
-export function normalizeStorageSources(
-    declared: DeclaredStorageSources | StorageSourceDefinition[] | undefined,
-    exported: StorageSourceDefinition[] | undefined
-): StorageSourceDefinition[] {
-    const merged = new Map<string, StorageSourceDefinition>();
-
-    // Two shapes, one meaning. `rebase.json` states sources as a record keyed by
-    // source key, which is how JSON expresses a set of named things; the bundle
-    // manifest stores the already-resolved array. Accepting both is what lets the
-    // CLI and the runtime call this with what each of them happens to hold.
-    const declaredEntries: [string, { engine: string; transport?: StorageSourceTransport; label?: string }][] =
-        Array.isArray(declared)
-            ? declared.filter(d => d?.key).map(d => [d.key, d])
-            : Object.entries(declared ?? {});
-
-    for (const [key, config] of declaredEntries) {
-        merged.set(key, {
-            key,
-            engine: config.engine,
-            transport: config.transport ?? "server",
-            ...(config.label !== undefined ? { label: config.label } : {})
-        });
-    }
-
-    for (const definition of exported ?? []) {
-        if (!definition?.key) continue;
-        const existing = merged.get(definition.key);
-        if (!existing) {
-            merged.set(definition.key, {
-                key: definition.key,
-                engine: definition.engine,
-                transport: definition.transport ?? "server",
-                ...(definition.label !== undefined ? { label: definition.label } : {})
-            });
-            continue;
-        }
-        // Fill gaps only. `rebase.json` stated these; code does not overrule it.
-        if (existing.label === undefined && definition.label !== undefined) {
-            existing.label = definition.label;
-        }
-    }
-
-    return Array.from(merged.values());
-}

package/src/types/websockets.ts

@@ -1,117 +0,0 @@
-export interface WebSocketErrorPayload {
-    error?: string | { message: string; code?: string };
-    message?: string;
-    code?: string;
-}
-
-export interface WebSocketMessage {
-    type: string;
-    payload?: unknown;
-    subscriptionId?: string;
-    requestId?: string;
-    rows?: Record<string, unknown>[];
-    row?: Record<string, unknown> | null;
-    error?: string;
-    /**
-     * Channel name, on broadcast and presence frames.
-     *
-     * These are addressed by channel rather than by `requestId` or
-     * `subscriptionId`, so this is the only field that routes them.
-     */
-    channel?: string;
-}
-
-/**
- * The key columns a collection's rows are addressed by.
- *
- * A row is exactly its columns and carries no address, so a subscriber that has
- * to recognise one — to patch it, or to keep its reference across a refetch —
- * derives the address from these. The SDK is usable with no collections
- * declared at all, so the server is the only side that knows them.
- *
- * Undefined when the server cannot resolve them: a table with no primary key
- * and no `id` column has no address, and rows of it cannot be recognised by
- * anyone.
- */
-export type WirePrimaryKeys = { fieldName: string; type: "string" | "number"; isUUID?: boolean }[];
-
-export interface CollectionUpdateMessage extends WebSocketMessage {
-    type: "collection_update";
-    subscriptionId: string;
-    rows: Record<string, unknown>[];
-    /**
-     * See {@link WirePrimaryKeys}. Sent with the rows themselves — and not only
-     * with a patch — because a CDC-originated change sends no patch at all: it
-     * invalidates and goes straight to a refetch, and the merge that preserves
-     * unchanged rows' references needs an address to match them by.
-     */
-    pks?: WirePrimaryKeys;
-}
-
-export interface SingleUpdateMessage extends WebSocketMessage {
-    type: "single_update";
-    subscriptionId: string;
-    row: Record<string, unknown> | null;
-}
-
-/**
- * Lightweight patch message sent to collection subscribers when a single
- * row is created, updated, or deleted. The client can merge this into
- * its cached collection data for near-instant cross-tab updates without
- * waiting for a full collection refetch.
- */
-export interface CollectionPatchMessage extends WebSocketMessage {
-    type: "collection_patch";
-    subscriptionId: string;
-    /** The address of the row this patch refers to — derived, never read off it. */
-    id: string;
-    /** The updated row, or null if deleted */
-    row: Record<string, unknown> | null;
-    /** See {@link WirePrimaryKeys}: how the subscriber finds {@link id} in its cache. */
-    pks?: WirePrimaryKeys;
-}
-
-/**
- * One retained broadcast, as it travels on the wire.
- *
- * `seq` is per-channel, dense and monotonically increasing — it is the only
- * thing a reconnecting client needs to say where it got to. See
- * {@link ChannelHistoryMessage}.
- */
-export interface ChannelHistoryEntry {
-    seq: number;
-    event: string;
-    payload: unknown;
-    /**
-     * The server-side client id of whoever sent it, for information only.
-     *
-     * Deliberately not used to filter a client's own messages out of a replay:
-     * a reconnect assigns a brand-new client id, so the very case replay exists
-     * for is the case where this would fail to match. Consumers that cannot
-     * tolerate re-applying their own operations must make them idempotent.
-     */
-    senderId?: string;
-    /** When the server accepted it, ISO-8601. */
-    at: string;
-}
-
-/**
- * Server → client: the retained messages a client missed.
- *
- * `retained: false` means the channel has no retention rule configured, so
- * there is no history to replay and there never will be — an explicit answer
- * rather than an empty one, so a client can tell "nothing missed" apart from
- * "this channel does not keep history".
- */
-export interface ChannelHistoryMessage extends WebSocketMessage {
-    type: "channel_history";
-    channel: string;
-    messages: ChannelHistoryEntry[];
-    retained: boolean;
-    /**
-     * The highest seq the server holds for this channel, whether or not it was
-     * returned. Lets a client that capped its request with `limit` see that it
-     * is still behind, and decide to resync wholesale instead of paging.
-     */
-    latestSeq?: number;
-}

package/src/users/index.ts

@@ -1,2 +0,0 @@
-export * from "./user";
-

package/src/users/user.ts

@@ -1,69 +0,0 @@
-
-/**
- * The canonical representation of an authenticated user in the Rebase ecosystem.
- *
- * Used by {@link AuthController}, collections, callbacks, and both the
- * `@rebasepro/client` and `@rebasepro/app` packages. It is the only user type
- * those packages export — the `RebaseUser` / `UserInfo` aliases are gone.
- *
- * **Backend-managed fields** (`uid`, `email`, `roles`, `metadata`, `createdAt`)
- * are populated by the server. **Client-visible fields** (`displayName`,
- * `photoURL`, `providerId`, `isAnonymous`, `emailVerified`) may be set during
- * authentication or profile updates.
- *
- * @see AdminUser — the admin-API DTO, which adds audit fields (`createdAt`,
- * `updatedAt`) and required `roles`.
- *
- * @group Models
- */
-export type User = {
-    /**
-     * The user's unique ID, scoped to the project.
-     */
-    readonly uid: string;
-    /**
-     * The display name of the user.
-     */
-    readonly displayName: string | null;
-    /**
-     * The email of the user.
-     */
-    readonly email: string | null;
-    /**
-     * The profile photo URL of the user.
-     */
-    readonly photoURL: string | null;
-    /**
-     * The provider used to authenticate the user (e.g. `"password"`,
-     * `"google"`, `"github"`).
-     */
-    readonly providerId: string;
-    /**
-     * Whether the user is anonymous (created via anonymous sign-in).
-     */
-    readonly isAnonymous: boolean;
-
-    /**
-     * Whether the user's email address has been verified.
-     */
-    readonly emailVerified?: boolean;
-
-    /**
-     * Role IDs assigned to this user (e.g. `["admin", "editor"]`).
-     */
-    roles?: string[];
-
-    /**
-     * The date and time when the user was created.
-     */
-    createdAt?: Date | string | null;
-
-    /**
-     * Additional metadata/custom claims associated with the user.
-     * Accessible by the frontend, but only writable by the backend.
-     */
-    readonly metadata?: Record<string, any>;
-
-    getIdToken?: (forceRefresh?: boolean) => Promise<string>;
-
-};