@adminiumjs/adminium 0.1.0-rc.1

package/dist/crud/identifiers.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Snapshot-backed identifier allowlisting (08-server-api.md §2.7 / §7 item 1):
+ * every `:table` and column name in a data request resolves against the
+ * active schema snapshot — the strings that reach SQL are the snapshot's
+ * own, never the client's. Unknown identifiers → 422 `UNKNOWN_IDENTIFIER`;
+ * masked/secret columns → 403 `COLUMN_FORBIDDEN` (§5.3).
+ */
+import type { LogicalType } from '@adminium/engine';
+import { AppError } from '../errors.js';
+import type { EffectiveModel, EffectiveTable } from '../connections/effective-schema.js';
+export declare class UnknownIdentifierError extends AppError {
+    readonly name = "UnknownIdentifierError";
+    constructor(message: string, details?: unknown);
+}
+export interface ResolvedColumn {
+    /** The snapshot's own column name — safe to pass to dynamic Kysely. */
+    name: string;
+    logicalType: LogicalType;
+    nullable: boolean;
+    isPrimaryKey: boolean;
+    masked: boolean;
+    secret: boolean;
+    textish: boolean;
+}
+export interface ResolvedTable {
+    /** Qualified snapshot id, e.g. `public.customers` — safe for SQL. */
+    id: string;
+    schema: string;
+    name: string;
+    /** Ordered PK column names; empty ⇒ read-only (no mutations, no undo). */
+    primaryKey: string[];
+    columns: Map<string, ResolvedColumn>;
+    /** Views / PK-less tables are read-only variants (05 §8.2). */
+    readOnly: boolean;
+    table: EffectiveTable;
+}
+export declare class SnapshotView {
+    #private;
+    readonly connectionId: string;
+    readonly model: EffectiveModel;
+    constructor(connectionId: string, model: EffectiveModel);
+    /** Resolve the client's `:table` segment to snapshot identifiers (422 otherwise). */
+    table(clientName: string): ResolvedTable;
+    /** Resolve a column; secret columns are invisible (422, §7.1 rule 1). */
+    column(table: ResolvedTable, clientName: string): ResolvedColumn;
+    /** Resolve a column that the caller intends to read/filter/sort (403 when masked). */
+    readableColumn(table: ResolvedTable, clientName: string, canReadPii: boolean): ResolvedColumn;
+    /** Non-secret columns, for the default SELECT list. */
+    selectableColumns(table: ResolvedTable): ResolvedColumn[];
+    /** Inbound relations (other tables' FKs pointing here) for reference counts. */
+    inboundRelations(table: ResolvedTable): {
+        relationId: string;
+        fromTable: string;
+        fromColumns: string[];
+        toColumns: string[];
+    }[];
+}
+//# sourceMappingURL=identifiers.d.ts.map

package/dist/crud/identifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../../src/crud/identifiers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAE,QAAQ,EAAkB,MAAM,cAAc,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAUzF,qBAAa,sBAAuB,SAAQ,QAAQ;IAClD,SAAkB,IAAI,4BAA4B;gBAEtC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAG/C;AAED,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACrC,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;CACvB;AAED,qBAAa,YAAY;;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;gBAGnB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc;IA+BvD,qFAAqF;IACrF,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa;IAUxC,yEAAyE;IACzE,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc;IAWhE,sFAAsF;IACtF,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,cAAc;IAY7F,uDAAuD;IACvD,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,EAAE;IAIzD,gFAAgF;IAChF,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE;CAUhI"}

package/dist/crud/identifiers.js

@@ -0,0 +1,99 @@
+/**
+ * Snapshot-backed identifier allowlisting (08-server-api.md §2.7 / §7 item 1):
+ * every `:table` and column name in a data request resolves against the
+ * active schema snapshot — the strings that reach SQL are the snapshot's
+ * own, never the client's. Unknown identifiers → 422 `UNKNOWN_IDENTIFIER`;
+ * masked/secret columns → 403 `COLUMN_FORBIDDEN` (§5.3).
+ */
+import { AppError, ForbiddenError } from '../errors.js';
+import { columnPolicyFor } from '../connections/effective-schema.js';
+/**
+ * Text-ish logical types the `q=` quick search matches over (§2.7.1).
+ * `enum`/`uuid` are excluded — PG has no ILIKE operator for them without a
+ * cast, and casting is a widget-data concern (04 §5), not quick search.
+ */
+const TEXTISH = new Set(['text', 'varchar']);
+export class UnknownIdentifierError extends AppError {
+    name = 'UnknownIdentifierError';
+    constructor(message, details) {
+        super(422, 'UNKNOWN_IDENTIFIER', message, details);
+    }
+}
+export class SnapshotView {
+    connectionId;
+    model;
+    #tables = new Map();
+    constructor(connectionId, model) {
+        this.connectionId = connectionId;
+        this.model = model;
+        for (const table of model.tables) {
+            const policy = columnPolicyFor(table);
+            const columns = new Map();
+            for (const column of table.columns) {
+                columns.set(column.name, {
+                    name: column.name,
+                    logicalType: column.logicalType,
+                    nullable: column.nullable,
+                    isPrimaryKey: column.isPrimaryKey,
+                    masked: policy.masked.has(column.name),
+                    secret: policy.secret.has(column.name),
+                    textish: TEXTISH.has(column.logicalType),
+                });
+            }
+            const resolved = {
+                id: table.id,
+                schema: table.schema,
+                name: table.name,
+                primaryKey: [...table.primaryKey],
+                columns,
+                readOnly: table.kind !== 'table' || table.primaryKey.length === 0,
+                table,
+            };
+            this.#tables.set(table.id, resolved);
+            if (table.schema === model.defaultSchema)
+                this.#tables.set(table.name, resolved);
+        }
+    }
+    /** Resolve the client's `:table` segment to snapshot identifiers (422 otherwise). */
+    table(clientName) {
+        const resolved = this.#tables.get(clientName);
+        if (resolved === undefined) {
+            throw new UnknownIdentifierError(`Unknown table ${JSON.stringify(clientName)}.`, {
+                table: clientName,
+            });
+        }
+        return resolved;
+    }
+    /** Resolve a column; secret columns are invisible (422, §7.1 rule 1). */
+    column(table, clientName) {
+        const column = table.columns.get(clientName);
+        if (column === undefined || column.secret) {
+            throw new UnknownIdentifierError(`Unknown column ${JSON.stringify(clientName)} on ${table.id}.`, { table: table.id, column: clientName });
+        }
+        return column;
+    }
+    /** Resolve a column that the caller intends to read/filter/sort (403 when masked). */
+    readableColumn(table, clientName, canReadPii) {
+        const column = this.column(table, clientName);
+        if (column.masked && !canReadPii) {
+            throw new ForbiddenError(`Column ${JSON.stringify(clientName)} is masked for your role.`, 'COLUMN_FORBIDDEN', { table: table.id, column: clientName });
+        }
+        return column;
+    }
+    /** Non-secret columns, for the default SELECT list. */
+    selectableColumns(table) {
+        return [...table.columns.values()].filter((column) => !column.secret);
+    }
+    /** Inbound relations (other tables' FKs pointing here) for reference counts. */
+    inboundRelations(table) {
+        return this.model.relations
+            .filter((relation) => relation.to.tableId === table.id && relation.through === null)
+            .map((relation) => ({
+            relationId: relation.id,
+            fromTable: relation.from.tableId,
+            fromColumns: [...relation.from.columns],
+            toColumns: [...relation.to.columns],
+        }));
+    }
+}
+//# sourceMappingURL=identifiers.js.map

package/dist/crud/identifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.js","sourceRoot":"","sources":["../../src/crud/identifiers.ts"],"names":[],"mappings":"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"}

package/dist/crud/list.d.ts

@@ -0,0 +1,51 @@
+/**
+ * List pipeline for `GET /data/:connectionId/:table` (08-server-api.md
+ * §2.7.1): select allowlisting, filter DSL, `q=` quick search, ≤ 3 sort
+ * keys with a PK tiebreaker, offset pagination with exact counts, and
+ * opaque keyset cursors (mutually exclusive with `offset`).
+ */
+import type { Kysely } from 'kysely';
+import type { Dialect } from '@adminium/engine';
+import type { SourceDatabase } from '../connections/manager.js';
+import type { ResolvedTable, SnapshotView } from './identifiers.js';
+import { type Row } from './mask.js';
+export declare const LIST_LIMIT_MAX = 200;
+export declare const LIST_LIMIT_DEFAULT = 50;
+export declare const MAX_SORT_KEYS = 3;
+export interface SortKey {
+    column: string;
+    dir: 'asc' | 'desc';
+}
+export interface ListParams {
+    select?: string | undefined;
+    where?: string | undefined;
+    q?: string | undefined;
+    order?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    cursor?: string | undefined;
+    count?: 'exact' | 'estimated' | 'none' | undefined;
+}
+export interface ListResult {
+    data: Row[];
+    page?: {
+        limit: number;
+        offset: number;
+        total: number | null;
+    };
+    cursor?: {
+        next: string | null;
+    };
+}
+/** `col.desc,col2.asc` → validated sort keys; a PK tiebreaker is always appended. */
+export declare function parseOrder(view: SnapshotView, table: ResolvedTable, raw: string | undefined, canReadPii: boolean): SortKey[];
+export interface RunListOptions {
+    db: Kysely<SourceDatabase>;
+    view: SnapshotView;
+    table: ResolvedTable;
+    params: ListParams;
+    canReadPii: boolean;
+    dialect: Dialect;
+}
+export declare function runList(opts: RunListOptions): Promise<ListResult>;
+//# sourceMappingURL=list.d.ts.map

package/dist/crud/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/crud/list.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAsB,MAAM,QAAQ,CAAC;AAEzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAGhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAQhE,OAAO,KAAK,EAAkB,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EAAY,KAAK,GAAG,EAAE,MAAM,WAAW,CAAC;AAE/C,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,KAAK,GAAG,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,CAAC;CACpD;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,IAAI,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC/D,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAClC;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CACxB,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,UAAU,EAAE,OAAO,GAClB,OAAO,EAAE,CAoBX;AAsBD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;IAC3B,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAqFvE"}

package/dist/crud/list.js

@@ -0,0 +1,126 @@
+/**
+ * List pipeline for `GET /data/:connectionId/:table` (08-server-api.md
+ * §2.7.1): select allowlisting, filter DSL, `q=` quick search, ≤ 3 sort
+ * keys with a PK tiebreaker, offset pagination with exact counts, and
+ * opaque keyset cursors (mutually exclusive with `offset`).
+ */
+import { ValidationFailedError } from '../errors.js';
+import { compileFilter, compileQuickSearch, parseWhereParam, } from './filters.js';
+import { maskRows } from './mask.js';
+export const LIST_LIMIT_MAX = 200;
+export const LIST_LIMIT_DEFAULT = 50;
+export const MAX_SORT_KEYS = 3;
+/** `col.desc,col2.asc` → validated sort keys; a PK tiebreaker is always appended. */
+export function parseOrder(view, table, raw, canReadPii) {
+    const keys = [];
+    if (raw !== undefined && raw.length > 0) {
+        for (const part of raw.split(',')) {
+            const [name, dir = 'asc'] = part.split('.', 2);
+            if (name === undefined || name.length === 0 || (dir !== 'asc' && dir !== 'desc')) {
+                throw new ValidationFailedError('`order` must be `col.asc` / `col.desc` pairs.', { part });
+            }
+            // Masked columns are rejected in `order` (§5.3 rule 2).
+            const column = view.readableColumn(table, name, canReadPii);
+            keys.push({ column: column.name, dir });
+        }
+        if (keys.length > MAX_SORT_KEYS) {
+            throw new ValidationFailedError('At most 3 sort keys.', { max: MAX_SORT_KEYS });
+        }
+    }
+    for (const pk of table.primaryKey) {
+        if (!keys.some((key) => key.column === pk))
+            keys.push({ column: pk, dir: 'asc' });
+    }
+    return keys;
+}
+function encodeCursor(values) {
+    return Buffer.from(JSON.stringify({ k: values }), 'utf8').toString('base64url');
+}
+function decodeCursor(cursor, expectedKeys) {
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new ValidationFailedError('Malformed cursor.', {});
+    }
+    const values = payload.k;
+    if (!Array.isArray(values) || values.length !== expectedKeys) {
+        throw new ValidationFailedError('Cursor does not match the current sort.', {});
+    }
+    return values;
+}
+export async function runList(opts) {
+    const { db, view, table, params, canReadPii, dialect } = opts;
+    const dynamic = db.dynamic;
+    const ctx = { view, table, canReadPii, dynamic, dialect };
+    const limit = Math.min(Math.max(params.limit ?? LIST_LIMIT_DEFAULT, 1), LIST_LIMIT_MAX);
+    const offset = Math.max(params.offset ?? 0, 0);
+    if (params.cursor !== undefined && params.offset !== undefined) {
+        throw new ValidationFailedError('`cursor` and `offset` are mutually exclusive.', {});
+    }
+    // SELECT list: default = every non-secret column — masked ones serialize
+    // as null + `_masked` marker (§5.3 rule 1); explicitly selecting a masked
+    // column without the grant → 403 COLUMN_FORBIDDEN (§2.7.1).
+    let selected;
+    if (params.select !== undefined && params.select.length > 0) {
+        selected = params.select.split(',').map((name) => view.readableColumn(table, name.trim(), canReadPii));
+    }
+    else {
+        selected = view.selectableColumns(table);
+    }
+    // PK columns ride along for cursors/refs even when not selected.
+    const selectNames = new Set(selected.map((column) => column.name));
+    for (const pk of table.primaryKey)
+        selectNames.add(pk);
+    const filter = params.where === undefined ? null : parseWhereParam(params.where);
+    const sortKeys = parseOrder(view, table, params.order, canReadPii);
+    const applyFilters = (qb) => {
+        let out = qb;
+        if (filter !== null)
+            out = out.where((eb) => compileFilter(eb, ctx, filter));
+        if (params.q !== undefined && params.q.length > 0) {
+            out = out.where((eb) => {
+                const search = compileQuickSearch(eb, ctx, params.q);
+                return search ?? eb(eb.val(1), '=', 1);
+            });
+        }
+        return out;
+    };
+    let qb = applyFilters(db.selectFrom(table.id).select([...selectNames].map((name) => dynamic.ref(name))));
+    for (const key of sortKeys)
+        qb = qb.orderBy(dynamic.ref(key.column), key.dir);
+    const cursorMode = params.cursor !== undefined;
+    if (cursorMode && params.cursor.length > 0) {
+        if (table.primaryKey.length === 0) {
+            throw new ValidationFailedError('Keyset pagination needs a primary key; use offset.', {
+                table: table.id,
+            });
+        }
+        const values = decodeCursor(params.cursor, sortKeys.length);
+        // Lexicographic keyset predicate over the mixed-direction sort tuple.
+        qb = qb.where((eb) => eb.or(sortKeys.map((key, i) => eb.and([
+            ...sortKeys.slice(0, i).map((prev, j) => eb(dynamic.ref(prev.column), '=', values[j])),
+            eb(dynamic.ref(key.column), key.dir === 'asc' ? '>' : '<', values[i]),
+        ]))));
+    }
+    if (cursorMode) {
+        const rows = (await qb.limit(limit + 1).execute());
+        const hasMore = rows.length > limit;
+        const pageRows = hasMore ? rows.slice(0, limit) : rows;
+        const last = pageRows.at(-1);
+        const next = hasMore && last !== undefined ? encodeCursor(sortKeys.map((key) => last[key.column])) : null;
+        return { data: maskRows(pageRows, table, canReadPii), cursor: { next } };
+    }
+    const rows = (await qb.limit(limit).offset(offset).execute());
+    let total = null;
+    if (params.count !== 'none') {
+        // `estimated` falls back to exact until adapter statistics land (05 §10).
+        const countRow = await applyFilters(db.selectFrom(table.id))
+            .select((eb) => eb.fn.countAll().as('total'))
+            .executeTakeFirst();
+        total = Number(countRow?.total ?? 0);
+    }
+    return { data: maskRows(rows, table, canReadPii), page: { limit, offset, total } };
+}
+//# sourceMappingURL=list.js.map

package/dist/crud/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../src/crud/list.ts"],"names":[],"mappings":"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"}

package/dist/crud/mask.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Field-level PII read masking (08-server-api.md §5.3): callers without the
+ * unmask permission receive masked columns as `null` plus a `_masked`
+ * sibling marker so the UI renders the masked-cell treatment. Secret
+ * columns (05 §7.1 rule 1) never appear at all.
+ *
+ * PERMISSION MAPPING NOTE: 08 §5.1 names a `table:<t>:read_pii` action and
+ * 05 §7.2 a `data.unmask_pii` grant; the v1 grammar shipped in M2
+ * (rbac/permissions.ts + meta's closed SYSTEM_ACTION_KEYS) has neither.
+ * Until the grammar grows the action (M5 remap/roles work), unmasking is
+ * granted by `system:connections:manage` — admins and super-admins see PII,
+ * editors/viewers do not. Centralized here so the swap is one line.
+ */
+import type { FastifyRequest } from 'fastify';
+import type { ResolvedTable } from './identifiers.js';
+export declare const UNMASK_PERMISSION = "system:connections:manage";
+/** Resolve the caller's unmask capability once per request. */
+export declare function canReadPii(request: FastifyRequest): Promise<boolean>;
+export type Row = Record<string, unknown>;
+/** Strip secret columns and mask PII columns on one row (§5.3 rules 1–3). */
+export declare function maskRow(row: Row, table: ResolvedTable, unmasked: boolean): Row;
+export declare function maskRows(rows: Row[], table: ResolvedTable, unmasked: boolean): Row[];
+//# sourceMappingURL=mask.d.ts.map

package/dist/crud/mask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.d.ts","sourceRoot":"","sources":["../../src/crud/mask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,eAAO,MAAM,iBAAiB,8BAA8B,CAAC;AAE7D,+DAA+D;AAC/D,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAE1E;AAED,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C,6EAA6E;AAC7E,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,OAAO,GAAG,GAAG,CAe9E;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,OAAO,GAAG,GAAG,EAAE,CAEpF"}

package/dist/crud/mask.js

@@ -0,0 +1,41 @@
+/**
+ * Field-level PII read masking (08-server-api.md §5.3): callers without the
+ * unmask permission receive masked columns as `null` plus a `_masked`
+ * sibling marker so the UI renders the masked-cell treatment. Secret
+ * columns (05 §7.1 rule 1) never appear at all.
+ *
+ * PERMISSION MAPPING NOTE: 08 §5.1 names a `table:<t>:read_pii` action and
+ * 05 §7.2 a `data.unmask_pii` grant; the v1 grammar shipped in M2
+ * (rbac/permissions.ts + meta's closed SYSTEM_ACTION_KEYS) has neither.
+ * Until the grammar grows the action (M5 remap/roles work), unmasking is
+ * granted by `system:connections:manage` — admins and super-admins see PII,
+ * editors/viewers do not. Centralized here so the swap is one line.
+ */
+export const UNMASK_PERMISSION = 'system:connections:manage';
+/** Resolve the caller's unmask capability once per request. */
+export async function canReadPii(request) {
+    return request.can(UNMASK_PERMISSION);
+}
+/** Strip secret columns and mask PII columns on one row (§5.3 rules 1–3). */
+export function maskRow(row, table, unmasked) {
+    const out = {};
+    const maskedHere = [];
+    for (const [key, value] of Object.entries(row)) {
+        const column = table.columns.get(key);
+        if (column?.secret === true)
+            continue; // hard-excluded, even for admins
+        if (column?.masked === true && !unmasked) {
+            out[key] = null;
+            maskedHere.push(key);
+            continue;
+        }
+        out[key] = value;
+    }
+    if (maskedHere.length > 0)
+        out._masked = maskedHere;
+    return out;
+}
+export function maskRows(rows, table, unmasked) {
+    return rows.map((row) => maskRow(row, table, unmasked));
+}
+//# sourceMappingURL=mask.js.map

package/dist/crud/mask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.js","sourceRoot":"","sources":["../../src/crud/mask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,CAAC,MAAM,iBAAiB,GAAG,2BAA2B,CAAC;AAE7D,+DAA+D;AAC/D,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAuB;IACtD,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;AACxC,CAAC;AAID,6EAA6E;AAC7E,MAAM,UAAU,OAAO,CAAC,GAAQ,EAAE,KAAoB,EAAE,QAAiB;IACvE,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,MAAM,EAAE,MAAM,KAAK,IAAI;YAAE,SAAS,CAAC,iCAAiC;QACxE,IAAI,MAAM,EAAE,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACzC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;YAChB,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACnB,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,OAAO,GAAG,UAAU,CAAC;IACpD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAW,EAAE,KAAoB,EAAE,QAAiB;IAC3E,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC1D,CAAC"}

package/dist/crud/records.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Single-record helpers for the CRUD routes (08-server-api.md §2.7.2):
+ * `:recordId` parsing (JSON tuple for composite PKs), PK-filtered fetches,
+ * and the inbound-FK reference counts behind the cascade preflight.
+ */
+import type { Kysely } from 'kysely';
+import type { SourceDatabase } from '../connections/manager.js';
+import type { ResolvedTable, SnapshotView } from './identifiers.js';
+import type { Row } from './mask.js';
+/**
+ * Parse `:recordId` into a full PK map. Single-column PKs take the raw
+ * segment; composite PKs take a JSON-encoded object (`{"order_id":1,…}`)
+ * or tuple aligned with the snapshot's PK column order.
+ */
+export declare function parseRecordId(table: ResolvedTable, raw: string): Row;
+/** Stable string form of a PK map (audit labels, bulk results). */
+export declare function pkLabel(table: ResolvedTable, pk: Row): string;
+type Db = Kysely<SourceDatabase>;
+export declare function fetchByPk(db: Db, table: ResolvedTable, pk: Row): Promise<Row | undefined>;
+export declare function fetchManyByPk(db: Db, table: ResolvedTable, pks: Row[]): Promise<Row[]>;
+export interface ReferenceCount {
+    relationId: string;
+    table: string;
+    column: string;
+    count: number;
+}
+/**
+ * Inbound-FK counts for the cascade preflight
+ * (`GET /data/:conn/:table/:id/references`, `DELETE ?dryRun=true`).
+ */
+export declare function referenceCounts(db: Db, view: SnapshotView, table: ResolvedTable, pk: Row): Promise<ReferenceCount[]>;
+export {};
+//# sourceMappingURL=records.d.ts.map

package/dist/crud/records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/crud/records.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAgBrC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,GAAG,CA0CpE;AAED,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,GAAG,GAAG,MAAM,CAG7D;AAED,KAAK,EAAE,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;AAEjC,wBAAsB,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC,CAO/F;AAED,wBAAsB,aAAa,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAO5F;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,aAAa,EACpB,EAAE,EAAE,GAAG,GACN,OAAO,CAAC,cAAc,EAAE,CAAC,CAuB3B"}

package/dist/crud/records.js

@@ -0,0 +1,126 @@
+/**
+ * Single-record helpers for the CRUD routes (08-server-api.md §2.7.2):
+ * `:recordId` parsing (JSON tuple for composite PKs), PK-filtered fetches,
+ * and the inbound-FK reference counts behind the cascade preflight.
+ */
+import { ValidationFailedError } from '../errors.js';
+/** Coerce a path-segment string to the column's JS type for binding. */
+function coerce(value, logicalType) {
+    if (typeof value !== 'string')
+        return value;
+    if (logicalType === 'integer' || logicalType === 'bigint') {
+        const n = Number(value);
+        if (!Number.isNaN(n))
+            return n;
+    }
+    if (logicalType === 'boolean') {
+        if (value === 'true')
+            return true;
+        if (value === 'false')
+            return false;
+    }
+    return value;
+}
+/**
+ * Parse `:recordId` into a full PK map. Single-column PKs take the raw
+ * segment; composite PKs take a JSON-encoded object (`{"order_id":1,…}`)
+ * or tuple aligned with the snapshot's PK column order.
+ */
+export function parseRecordId(table, raw) {
+    if (table.primaryKey.length === 0) {
+        throw new ValidationFailedError('Table has no primary key — record routes are unavailable.', {
+            table: table.id,
+        });
+    }
+    if (table.primaryKey.length === 1) {
+        const pkName = table.primaryKey[0];
+        const column = table.columns.get(pkName);
+        return { [pkName]: coerce(raw, column?.logicalType ?? 'text') };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ValidationFailedError('Composite PK record ids are JSON-encoded.', { table: table.id });
+    }
+    const pk = {};
+    if (Array.isArray(parsed)) {
+        if (parsed.length !== table.primaryKey.length) {
+            throw new ValidationFailedError('PK tuple arity mismatch.', { expected: table.primaryKey });
+        }
+        table.primaryKey.forEach((name, i) => {
+            pk[name] = parsed[i];
+        });
+        return pk;
+    }
+    if (typeof parsed === 'object' && parsed !== null) {
+        for (const name of table.primaryKey) {
+            const value = parsed[name];
+            if (value === undefined) {
+                throw new ValidationFailedError(`PK component ${JSON.stringify(name)} missing.`, {
+                    expected: table.primaryKey,
+                });
+            }
+            pk[name] = value;
+        }
+        return pk;
+    }
+    throw new ValidationFailedError('Composite PK record ids are JSON objects or tuples.', {
+        table: table.id,
+    });
+}
+/** Stable string form of a PK map (audit labels, bulk results). */
+export function pkLabel(table, pk) {
+    if (table.primaryKey.length === 1)
+        return String(pk[table.primaryKey[0]]);
+    return JSON.stringify(table.primaryKey.map((name) => pk[name]));
+}
+export async function fetchByPk(db, table, pk) {
+    let qb = db.selectFrom(table.id).selectAll();
+    for (const [column, value] of Object.entries(pk)) {
+        qb = qb.where((eb) => eb(db.dynamic.ref(column), '=', value));
+    }
+    const row = await qb.executeTakeFirst();
+    return row;
+}
+export async function fetchManyByPk(db, table, pks) {
+    const rows = [];
+    for (const pk of pks) {
+        const row = await fetchByPk(db, table, pk);
+        if (row !== undefined)
+            rows.push(row);
+    }
+    return rows;
+}
+/**
+ * Inbound-FK counts for the cascade preflight
+ * (`GET /data/:conn/:table/:id/references`, `DELETE ?dryRun=true`).
+ */
+export async function referenceCounts(db, view, table, pk) {
+    const out = [];
+    for (const relation of view.inboundRelations(table)) {
+        // Only count single-column FKs whose target is part of this PK (v1).
+        const toColumn = relation.toColumns[0];
+        const fromColumn = relation.fromColumns[0];
+        if (toColumn === undefined || fromColumn === undefined)
+            continue;
+        const value = pk[toColumn] ?? (await fetchByPk(db, table, pk))?.[toColumn];
+        if (value === undefined)
+            continue;
+        // Both identifiers come from the snapshot's relation graph, never the client.
+        const row = await db
+            .selectFrom(relation.fromTable)
+            .select((eb) => eb.fn.countAll().as('count'))
+            .where((eb) => eb(db.dynamic.ref(fromColumn), '=', value))
+            .executeTakeFirst();
+        out.push({
+            relationId: relation.relationId,
+            table: relation.fromTable,
+            column: fromColumn,
+            count: Number(row?.count ?? 0),
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=records.js.map

package/dist/crud/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../../src/crud/records.ts"],"names":[],"mappings":"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"}