@rebasepro/common 0.19.1 → 0.19.2-canary.g09316f6

package/dist/util/entities.d.ts

@@ -1,5 +1,22 @@
 import { DataType, Entity, EntityReference, EntityRelation, EntityStatus, EntityValues, Properties, Property } from "@rebasepro/types";
 export declare function isPropertyBuilder(property?: Property): boolean;
+/**
+ * What a form opens with: a value for every property it can write.
+ *
+ * `excludeFromApi` columns are left out, and that is the whole of the rule —
+ * they are not part of the API surface in either direction, so there is nothing
+ * for a form to open showing and nothing it may send back. Including them was
+ * not cosmetic: the baseline is what gets submitted, so a new record carried
+ * `passwordHash: null` and `emailVerificationToken: null` into the create, and
+ * the server refused the whole write with "these columns are the server's to
+ * set" — the users collection could not be added to from the panel at all. The
+ * fields were invisible on screen (`admin.disabled.hidden`), which is what made
+ * the error read as being about the roles the operator *had* just edited.
+ *
+ * Server-side defaulting does not come through here: `applyDefaultValuesOnCreate`
+ * asks each property for its own default, so an excluded column with a declared
+ * `defaultValue` is still filled in on an in-process write.
+ */
 export declare function getDefaultValuesFor<M extends Record<string, unknown>>(properties: Properties): Partial<EntityValues<M>>;
 export declare function getDefaultValueFor(property?: Property): unknown;
 export declare function getDefaultValueFortype(type: DataType): unknown;
@@ -13,6 +30,68 @@ export declare function updateDateAutoValues<M extends Record<string, unknown>>(
     status: EntityStatus;
     timestampNowValue: unknown;
 }): EntityValues<M>;
+/**
+ * Stamp the acting user's uid into the `user_on_create` / `user_on_update`
+ * columns a collection declares.
+ *
+ * A deliberate sibling of {@link updateDateAutoValues} rather than another
+ * branch inside it. The two share a shape and nothing else: one takes an
+ * instant the server generates and the other takes an identity the request
+ * carries, so overloading the timestamp function would have meant threading a
+ * second, unrelated argument through every one of its callers and letting a
+ * `date` property and a `string` property compete for the same `autoValue`
+ * union. Called side by side in the driver.
+ *
+ * The stamped value overwrites whatever arrived in the body. A caller who can
+ * set `createdBy` is a caller who can attribute their write to somebody else,
+ * which is the one thing an audit column must not allow.
+ *
+ * `uid` is `undefined` for an anonymous request, a service token or an
+ * in-process write; the column is set to an explicit `null` there. Explicit
+ * matters on an update: leaving the key absent would keep whatever uid the
+ * column already held, so an anonymous edit would be recorded as the previous
+ * editor's. Refusing that write outright is `required`'s job, not this
+ * function's — see `assertWriteValuesValid`.
+ *
+ * Top-level properties only, deliberately, unlike {@link updateDateAutoValues}.
+ * `traverseValuesProperties` cannot express "set this key to null" — a `null`
+ * from its operation means "leave the key out" — and an audit column nested
+ * inside a `map` is not a column at all, so there is nothing down there to
+ * stamp.
+ *
+ * @group Driver
+ */
+export declare function updateUserAutoValues<M extends Record<string, unknown>>({ inputValues, properties, status, uid }: {
+    inputValues: Partial<EntityValues<M>>;
+    properties: Properties;
+    status: EntityStatus;
+    uid: string | undefined;
+}): EntityValues<M>;
+/**
+ * Fill in the `defaultValue`s a create left unset.
+ *
+ * `defaultValue` was read by exactly one thing: the Studio's form, which uses it
+ * to prefill inputs. Every other way into the same collection — the REST create,
+ * the SDK, the socket, an import — stored whatever arrived and nothing where the
+ * key was absent. So `active: { type: "boolean", defaultValue: true }` produced
+ * rows with `active` unset through the API and `true` through the panel, from
+ * one declaration that reads like a promise about the data.
+ *
+ * Only genuinely absent keys are filled. An explicit `null` is a caller saying
+ * "no value", which is a different statement from not mentioning the field, and
+ * overwriting it would make the default impossible to opt out of.
+ *
+ * `getDefaultValuesFor` also invents a per-type default for properties with no
+ * `defaultValue` at all (`false` for a boolean, `[]` for an array, `null` for
+ * the rest) — right for a form, which must render *something* in every input,
+ * and wrong here, where an absent key must stay absent so the column's own
+ * DEFAULT applies. Only declared defaults are taken.
+ *
+ * @param values the caller's payload
+ * @param properties the collection's declared properties
+ * @group Driver
+ */
+export declare function applyDefaultValuesOnCreate<M extends Record<string, unknown>>(values: Partial<EntityValues<M>> | undefined, properties: Properties): Partial<EntityValues<M>>;
 /**
  * Add missing required fields, expected in the collection, to the values of a entity
  * @param values

package/dist/util/index.d.ts

@@ -16,6 +16,7 @@ export * from "./relations.js";
 export * from "./resolve-relation.js";
 export * from "./auth-default-policies.js";
 export * from "./junction-policies.js";
+export * from "./tenant.js";
 export * from "./conditions.js";
 export * from "./pg-column-to-property.js";
 export * from "./string-column-length.js";

package/dist/util/junction-policies.d.ts

@@ -1,4 +1,4 @@
-import { CollectionConfig, PolicyExpression, Relation, SecurityRule } from "@rebasepro/types";
+import { CollectionConfig, PolicyExpression, Properties, Relation, SecurityRule } from "@rebasepro/types";
 /**
  * RLS derivation for many-to-many junction tables.
  *
@@ -72,6 +72,15 @@ export interface JunctionSpec {
     endpoints: [JunctionEndpoint, JunctionEndpoint];
     /** Every collection that declares a relation through this table. */
     declaringSides: JunctionDeclaringSide[];
+    /**
+     * The junction's own columns beyond the two keys — `through.properties`,
+     * merged across every declaring side. `{}` when there are none.
+     *
+     * See {@link ManyToManyRelation.through} for what they are; every side that
+     * names a key has to describe the same column, which is checked when the
+     * specs are resolved rather than left for `CREATE TABLE` to discover.
+     */
+    properties: Properties;
 }
 /**
  * Walk every collection's resolved relations and aggregate the junction tables
@@ -85,6 +94,13 @@ export declare function resolveJunctionSpecs(collections: CollectionConfig[]): M
  * compilation and naming. Its two FK columns carry explicit `columnName`s so
  * `outerField` operands resolve to the exact columns the CREATE TABLE emitted,
  * whatever their casing.
+ *
+ * The payload columns are here too, exactly as authored. That is what lets one
+ * reading of a `Property` serve the junction as well as a collection: the
+ * schema planner plans these columns with the same function it plans a
+ * collection's with, and the write path validates a `_pivot` against them with
+ * the same validator a row's values go through. A second description of a
+ * payload column anywhere is a second description that can disagree.
  */
 export declare function getJunctionCollectionConfig(spec: JunctionSpec): CollectionConfig;
 /**

package/dist/util/tenant.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The one reading of `collection.tenant`.
+ *
+ * Four things have to agree for a tenant-scoped collection to work — the
+ * column, the RLS policy, the value stamped on insert and the index — and
+ * before this they were four hand-written declarations that nothing compared.
+ * The three that are schema become a {@link SecurityRule} and a column effect
+ * derived here and in `planSchema`; the fourth, the write path, is
+ * {@link resolveTenantWrite}.
+ *
+ * Everything in this module is pure. The policy it builds is a `SecurityRule`
+ * like any other, which is what makes `db push`, the doctor, boot-ensure, the
+ * drift detector and the Studio treat the tenancy policy as what it is —
+ * generated, named, and recognisable — rather than as somebody's hand-written
+ * SQL that a push should offer to drop.
+ */
+import { type CollectionConfig, type CollectionTenantConfig, type EntityStatus, type PolicyExpression, type SecurityRule } from "@rebasepro/types";
+/**
+ * The collection's tenancy declaration, or nothing.
+ *
+ * Read through this rather than off the object, so the one shape check —
+ * `tenant` is an object carrying a `field` and a `from` — is in one place. A
+ * config that is *wrong* is refused by `validateCollectionConfig` with a
+ * message; this is only asking whether there is one.
+ */
+export declare function getTenantConfig(collection: CollectionConfig | undefined): CollectionTenantConfig | undefined;
+/** The roles tenancy does not apply to, defaulted. */
+export declare function tenantBypassRoles(tenant: CollectionTenantConfig): readonly string[];
+/**
+ * The name of the policy a tenant declaration compiles to.
+ *
+ * Explicit — not a `getPolicyNameHash` of the rule — precisely because the
+ * rule's *body* is compiled with more information in some callers than in
+ * others (`planSchema` can resolve a relation's target collection and so knows
+ * the column's type; the Studio, asking only for names, cannot). A hashed name
+ * would then differ between the two, and the same policy would read as drift.
+ * A frozen identifier: see `contracts/derived-names.txt`.
+ */
+export declare function tenantPolicyName(tableName: string): string;
+/** The `reason` on the index a tenant column gets. Rendered into `schema.sql`. */
+export declare const TENANT_INDEX_REASON = "tenant scope";
+/**
+ * The condition a tenant declaration means, as a policy expression.
+ *
+ * `serverContext()` first, for the same reason every injected baseline rule
+ * carries it: the trusted plane runs migrations, the auth flows and the boot,
+ * and a restrictive policy that excluded it would not protect a tenant, it
+ * would stop the server from starting.
+ *
+ * Then the bypass roles, then the tenancy test itself — a claim comparison or a
+ * correlated `EXISTS` over the membership table, which are the two ways a
+ * deployment answers "which tenant is this caller in".
+ */
+export declare function tenantScopeExpression(tenant: CollectionTenantConfig): PolicyExpression;
+/**
+ * The rule a tenant declaration compiles to, or nothing when there is none.
+ *
+ * **Restrictive**, and that is the whole design. A restrictive policy is ANDed
+ * with every other policy on the table, so tenancy narrows what the
+ * collection's own `securityRules` allow and can never widen it. A permissive
+ * one would OR with them, and a single `access: "public"` rule elsewhere in the
+ * file would take the entire tenancy boundary off without contradicting
+ * anything a reader could see.
+ *
+ * One rule with `operation: "all"` rather than four with `operations: [...]`:
+ * `FOR ALL` gives Postgres the USING clause for SELECT/UPDATE/DELETE and the
+ * WITH CHECK clause for INSERT/UPDATE, which is exactly the coverage wanted,
+ * as one policy with one name instead of four.
+ */
+export declare function buildTenantSecurityRule(collection: CollectionConfig): SecurityRule | undefined;
+/** Why a write was refused by tenancy. */
+export interface TenantWriteRefusal {
+    code: "TENANT_REQUIRED" | "TENANT_MISMATCH" | "TENANT_IMMUTABLE";
+    /** The property, for a `violations` entry and for the message. */
+    field: string;
+    message: string;
+}
+/** What {@link resolveTenantWrite} decided. */
+export type TenantWriteDecision = 
+/** The values to write, with the tenant stamped if it was missing. */
+{
+    values: Record<string, unknown>;
+    refusal?: undefined;
+} | {
+    refusal: TenantWriteRefusal;
+    values?: undefined;
+};
+export interface TenantWriteInput {
+    tenant: CollectionTenantConfig;
+    /** The write's values, after defaults and hooks. */
+    values: Record<string, unknown>;
+    status: EntityStatus;
+    /**
+     * Every tenant the caller may write into.
+     *
+     * One entry for a claim, however many memberships they hold for the
+     * membership form, and none for a caller carrying neither.
+     */
+    callerTenants: readonly unknown[];
+    /**
+     * Whether `callerTenants` is the whole list.
+     *
+     * A membership lookup is capped — a caller with more memberships than the
+     * cap would otherwise make every write of theirs a large read. When the cap
+     * is hit this is `false`, and a value that is not in the list is **let
+     * through** rather than refused: the list is no longer evidence of absence,
+     * and the policy's `WITH CHECK` is what actually decides. The API check is
+     * an earlier, clearer refusal of the same writes, never a second authority.
+     */
+    callerTenantsComplete?: boolean;
+    /**
+     * True when tenancy does not apply to this caller — a bypass role, or the
+     * trusted server context. The same set the policy lets through, so the API
+     * and the database refuse the same writes.
+     */
+    bypass: boolean;
+    /** The row's current values, on an update. */
+    previousValues?: Record<string, unknown>;
+    /** The collection slug, for the message. */
+    slug: string;
+}
+/**
+ * Stamp, or refuse, the tenant on a write.
+ *
+ * Three refusals, and each exists because the alternative lands somewhere
+ * worse:
+ *
+ * - **`TENANT_REQUIRED`** — the caller has no tenant, or belongs to several and
+ *   named none. Stamping a guess would put the row in the wrong tenant; letting
+ *   it through would write a NULL into a `NOT NULL` column and surface as a
+ *   23502 naming a column the caller never wrote.
+ * - **`TENANT_MISMATCH`** — the caller named a tenant that is not theirs. The
+ *   database refuses this too, through the policy's `WITH CHECK`, but as a
+ *   42501 "new row violates row-level security policy" with no mention of which
+ *   field or why. Refused here so the answer names the field.
+ * - **`TENANT_IMMUTABLE`** — an update that moves a row to another tenant. RLS
+ *   would allow it whenever the caller belongs to both, and it is almost never
+ *   what anybody meant: it takes the row out of one tenant's history and drops
+ *   it into another's, with no trace on either side. A deliberate move is a
+ *   `bypassRoles` operation.
+ *
+ * A bypass caller is exempt from all three: they are trusted across tenants by
+ * declaration, and stamping their write would silently confine a support
+ * operator's row to whichever tenant they happen to carry.
+ */
+export declare function resolveTenantWrite(input: TenantWriteInput): TenantWriteDecision;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/common",
-  "version": "0.19.1",
+  "version": "0.19.2-canary.g09316f6",
   "description": "Rebase shared core — collection registry, data driver adapter and fluent query builder. No React dependency.",
   "keywords": [
     "rebase",
@@ -44,8 +44,8 @@
   "dependencies": {
     "fast-equals": "6.0.2",
     "json-logic-js": "^2.0.5",
-    "@rebasepro/types": "0.19.1",
-    "@rebasepro/utils": "0.19.1"
+    "@rebasepro/types": "0.19.2-canary.g09316f6",
+    "@rebasepro/utils": "0.19.2-canary.g09316f6"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",