@adminiumjs/adminium 0.1.0-rc.1

package/dist/connections/manager.js

@@ -0,0 +1,224 @@
+/**
+ * ConnectionManager — the three-connection privilege model at runtime
+ * (01-architecture.md §3, M3-T04):
+ *
+ * - `introspect` — a short-lived adapter instance per introspection run,
+ * - `data`      — a pooled dynamic-Kysely handle per connection (the CRUD
+ *                 query port, 08-server-api.md §2.7), created lazily and
+ *                 disposed on connection delete,
+ * - `meta`      — the existing MetaDb; never handed to adapters.
+ *
+ * Meta-placement enforcement (01 §3.1): when the meta store lives in the
+ * same physical database as a source's data DSN and the probed data role is
+ * read-only or DDL-less, the manager refuses with `META_PLACEMENT_INVALID`
+ * — the rule lives here, not only in the wizard UI.
+ */
+import { Kysely } from 'kysely';
+import { AdapterError, adapterRegistry, } from '@adminium/engine/adapter';
+import { connectionsRepo } from '@adminium/meta';
+import { AppError, NotFoundError, ValidationFailedError } from '../errors.js';
+import { guardDsn, MetaPlacementError, sameDatabase } from './dsn.js';
+/** 502-ish mapping for adapter failures surfaced through API routes. */
+export function adapterErrorToAppError(error) {
+    const status = error.code === 'AUTH' || error.code === 'PERMISSION' ? 502 : 502;
+    return new AppError(status, 'SOURCE_DB_UNREACHABLE', error.message, {
+        adapterCode: error.code,
+        hint: error.hint,
+    });
+}
+export class ConnectionManager {
+    #meta;
+    #registry;
+    #metaDsn;
+    #blockLoopback;
+    connections;
+    #dataHandles = new Map();
+    constructor(opts) {
+        this.#meta = opts.meta;
+        this.#registry = opts.registry ?? adapterRegistry;
+        this.#metaDsn = opts.metaDsn ?? null;
+        this.#blockLoopback = opts.blockLoopback ?? process.env.NODE_ENV === 'production';
+        this.connections = connectionsRepo(opts.meta, opts.crypto);
+    }
+    get meta() {
+        return this.#meta;
+    }
+    provider(engine) {
+        return this.#registry.get(engine);
+    }
+    hasAdapter(engine) {
+        return this.#registry.has(engine);
+    }
+    /** Guard + dial + test + probe one DSN with a short-lived introspect-role instance. */
+    async testDsn(engine, dsn) {
+        guardDsn(dsn, { blockLoopback: this.#blockLoopback });
+        const provider = this.provider(engine);
+        let adapter = null;
+        try {
+            // AdapterProvider.create() receives the config and owns the dial.
+            adapter = await provider.create({ role: 'introspect', dsn });
+            const test = await adapter.test();
+            if (!test.ok) {
+                return {
+                    ok: false,
+                    latencyMs: test.latencyMs,
+                    serverVersion: test.serverVersion,
+                    readOnly: !test.canWrite,
+                    capabilities: null,
+                    error: test.error === undefined
+                        ? { code: 'UNKNOWN', message: 'connection test failed', hint: null }
+                        : { code: test.error.code, message: test.error.message, hint: test.error.hint },
+                };
+            }
+            const capabilities = await adapter.probeCapabilities();
+            return {
+                ok: true,
+                latencyMs: test.latencyMs,
+                serverVersion: test.serverVersion ?? capabilities.serverVersion,
+                readOnly: capabilities.currentRole.readOnly || !capabilities.privileges.canWrite,
+                capabilities,
+                error: null,
+            };
+        }
+        catch (error) {
+            if (error instanceof AdapterError) {
+                return {
+                    ok: false,
+                    latencyMs: 0,
+                    serverVersion: null,
+                    readOnly: false,
+                    capabilities: null,
+                    error: { code: error.code, message: error.message, hint: error.hint },
+                };
+            }
+            throw error;
+        }
+        finally {
+            await adapter?.close().catch(() => undefined);
+        }
+    }
+    /**
+     * 01 §3.1 decision-tree rule, re-validated server-side: same-db meta
+     * placement is impossible against a read-only or DDL-less data role.
+     */
+    enforceMetaPlacement(dataDsn, probe) {
+        if (this.#metaDsn === null)
+            return;
+        if (!sameDatabase(this.#metaDsn, dataDsn))
+            return;
+        const privileges = probe.capabilities?.privileges;
+        const canWrite = privileges?.canWrite ?? !probe.readOnly;
+        const canDDL = privileges?.canDDL ?? false;
+        if (!canWrite || !canDDL) {
+            throw new MetaPlacementError(canWrite
+                ? 'This role cannot run DDL — Adminium migrations need CREATE TABLE. Choose a separate database for Adminium’s own tables.'
+                : 'Your role is read-only — Adminium never writes to this database. Choose a separate database for Adminium’s own tables.', { placement: 'same-db', canWrite, canDDL });
+        }
+    }
+    async mustFind(connectionId) {
+        const connection = await this.connections.findById(connectionId);
+        if (connection === null) {
+            throw new NotFoundError('Connection not found.', { connectionId });
+        }
+        return connection;
+    }
+    /**
+     * Short-lived introspect-role adapter for one run. The caller owns the
+     * lifecycle and must `close()` it (runIntrospection does).
+     */
+    async introspectAdapter(connectionId) {
+        const connection = await this.mustFind(connectionId);
+        if (connection.sourceKind !== 'dsn') {
+            throw new ValidationFailedError('Schema-file connections have no live database to introspect.', {
+                connectionId,
+            });
+        }
+        const dsns = await this.connections.getDsns(connectionId);
+        if (dsns?.introspectDsn == null) {
+            throw new ValidationFailedError('Connection has no introspect DSN.', { connectionId });
+        }
+        guardDsn(dsns.introspectDsn, { blockLoopback: this.#blockLoopback });
+        const provider = this.provider(connection.engine);
+        return provider.create({ role: 'introspect', dsn: dsns.introspectDsn });
+    }
+    /**
+     * Short-lived DATA-role adapter for one run — the symmetric twin of
+     * {@link introspectAdapter}, and the only way to reach the adapter methods
+     * that need row access (`collectTableStats`, 06 §4.2). The caller owns the
+     * lifecycle and must `close()` it. Deliberately NOT pooled alongside
+     * {@link data}: that handle is a long-lived Kysely for CRUD serving, whereas
+     * this is opened for one statistics pass and released.
+     *
+     * The DATA role, not introspect: the introspect role is schema-only by design
+     * (§3), so aggregates collected over it would fail on permissions.
+     */
+    async dataAdapter(connectionId) {
+        const connection = await this.mustFind(connectionId);
+        if (connection.sourceKind !== 'dsn') {
+            throw new ValidationFailedError('Schema-file connections have no live database to read.', {
+                connectionId,
+            });
+        }
+        const dsns = await this.connections.getDsns(connectionId);
+        if (dsns?.dataDsn == null) {
+            throw new ValidationFailedError('Connection has no data DSN.', { connectionId });
+        }
+        guardDsn(dsns.dataDsn, { blockLoopback: this.#blockLoopback });
+        const provider = this.provider(connection.engine);
+        return provider.create({ role: 'data', dsn: dsns.dataDsn });
+    }
+    /** Pooled data handle (dynamic Kysely over the data DSN); lazy + cached. */
+    async data(connectionId) {
+        const cached = this.#dataHandles.get(connectionId);
+        if (cached !== undefined)
+            return cached;
+        const pending = this.#openDataHandle(connectionId);
+        this.#dataHandles.set(connectionId, pending);
+        try {
+            return await pending;
+        }
+        catch (error) {
+            this.#dataHandles.delete(connectionId);
+            throw error;
+        }
+    }
+    async #openDataHandle(connectionId) {
+        const connection = await this.mustFind(connectionId);
+        const dsns = await this.connections.getDsns(connectionId);
+        if (dsns?.dataDsn == null) {
+            throw new ValidationFailedError('Connection has no data DSN.', { connectionId });
+        }
+        guardDsn(dsns.dataDsn, { blockLoopback: this.#blockLoopback });
+        const provider = this.provider(connection.engine);
+        const engine = await provider.createQueryEngine({ role: 'data', dsn: dsns.dataDsn });
+        // The engine package types the dialect opaquely; the server (which owns
+        // the kysely dependency) casts at this composition boundary (05 §3).
+        const db = new Kysely({ dialect: engine.dialect });
+        // `connection.engine` is validated against DIALECTS at connection create.
+        return { db, engine, dialect: connection.engine };
+    }
+    /** Tear down a connection's pooled handles (connection delete / DSN change). */
+    async dispose(connectionId) {
+        const pending = this.#dataHandles.get(connectionId);
+        this.#dataHandles.delete(connectionId);
+        if (pending === undefined)
+            return;
+        let handle;
+        try {
+            handle = await pending;
+        }
+        catch {
+            return; // pool never opened — nothing to release
+        }
+        // Kysely.destroy() and QueryEngine.destroy() may share one pool — treat
+        // a double-close as already-released.
+        await handle.db.destroy().catch(() => undefined);
+        await handle.engine.destroy().catch(() => undefined);
+    }
+    /** Graceful shutdown: release every pooled data handle. */
+    async disposeAll() {
+        const ids = [...this.#dataHandles.keys()];
+        await Promise.all(ids.map(async (id) => this.dispose(id)));
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/connections/manager.js.map

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

package/dist/connections/register-adapters.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Boot-time adapter registration (01-architecture.md §2.3.1): the server —
+ * and only the server — composes concrete adapter packages into the engine's
+ * process-wide registry. Adapter packages import `@adminium/engine/adapter`;
+ * the engine never imports adapters; everything stays acyclic.
+ *
+ * The adapter package is loaded dynamically and duck-checked because the
+ * provider export lands in the same wave as this module — a stub package
+ * (M0 scaffold) simply registers nothing, and PG-dependent features report
+ * `UNSUPPORTED` through the registry's typed error instead of crashing boot.
+ */
+import { type AdapterProvider, type AdapterRegistry } from '@adminium/engine/adapter';
+/** Find an AdapterProvider among a module's exports (named, default, or factory). */
+export declare function providerFromModule(mod: unknown): AdapterProvider | null;
+export interface RegisterAdaptersResult {
+    /** Dialects registered by this call (already-registered ones are skipped). */
+    registered: string[];
+    /** Adapter packages present but exposing no provider yet (wave-A stubs). */
+    missing: string[];
+}
+/**
+ * The v1 adapter packages — all THREE engines BRIEF §3 ships and the `init`
+ * wizard offers (PostgreSQL, MySQL/MariaDB, SQLite), and all three that M10's
+ * exit criterion names ("connect any of the 3 engines").
+ *
+ * Registering only postgres here meant the wizard let the user answer every
+ * prompt, pick "Point at a SQLite file" or "MySQL / MariaDB", and then die on
+ * the registry's bare UNSUPPORTED error at `manager.testDsn` — after all the
+ * questions, with no hint. Both packages exported working providers the whole
+ * time; they were simply never composed in. They are also declared dependencies
+ * of `@adminium/server` now, so they resolve inside the deployed image and not
+ * just in a workspace checkout (01 §2.3.1: the server, and only the server,
+ * composes concrete adapters).
+ */
+export declare const ADAPTER_PACKAGES: readonly string[];
+/**
+ * Register every available adapter package. Idempotent: dialects already in
+ * the registry are left untouched (tests re-build apps against the same
+ * process-wide registry).
+ */
+export declare function registerAdapters(registry?: AdapterRegistry<AdapterProvider>): Promise<RegisterAdaptersResult>;
+//# sourceMappingURL=register-adapters.d.ts.map

package/dist/connections/register-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-adapters.d.ts","sourceRoot":"","sources":["../../src/connections/register-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAmB,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAYvG,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAkBvE;AAED,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAI7C,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,GAAE,eAAe,CAAC,eAAe,CAAmB,GAC3D,OAAO,CAAC,sBAAsB,CAAC,CAsBjC"}

package/dist/connections/register-adapters.js

@@ -0,0 +1,92 @@
+/**
+ * Boot-time adapter registration (01-architecture.md §2.3.1): the server —
+ * and only the server — composes concrete adapter packages into the engine's
+ * process-wide registry. Adapter packages import `@adminium/engine/adapter`;
+ * the engine never imports adapters; everything stays acyclic.
+ *
+ * The adapter package is loaded dynamically and duck-checked because the
+ * provider export lands in the same wave as this module — a stub package
+ * (M0 scaffold) simply registers nothing, and PG-dependent features report
+ * `UNSUPPORTED` through the registry's typed error instead of crashing boot.
+ */
+import { adapterRegistry } from '@adminium/engine/adapter';
+function isAdapterProvider(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.dialect === 'string' &&
+        typeof candidate.create === 'function' &&
+        typeof candidate.createQueryEngine === 'function');
+}
+/** Find an AdapterProvider among a module's exports (named, default, or factory). */
+export function providerFromModule(mod) {
+    if (typeof mod !== 'object' || mod === null)
+        return null;
+    const exportsRecord = mod;
+    const preferred = [
+        'postgresAdapter',
+        'mysqlAdapter',
+        'sqliteAdapter',
+        'adapterProvider',
+        'provider',
+        'default',
+    ];
+    for (const key of preferred) {
+        if (isAdapterProvider(exportsRecord[key]))
+            return exportsRecord[key];
+    }
+    for (const value of Object.values(exportsRecord)) {
+        if (isAdapterProvider(value))
+            return value;
+    }
+    return null;
+}
+/**
+ * The v1 adapter packages — all THREE engines BRIEF §3 ships and the `init`
+ * wizard offers (PostgreSQL, MySQL/MariaDB, SQLite), and all three that M10's
+ * exit criterion names ("connect any of the 3 engines").
+ *
+ * Registering only postgres here meant the wizard let the user answer every
+ * prompt, pick "Point at a SQLite file" or "MySQL / MariaDB", and then die on
+ * the registry's bare UNSUPPORTED error at `manager.testDsn` — after all the
+ * questions, with no hint. Both packages exported working providers the whole
+ * time; they were simply never composed in. They are also declared dependencies
+ * of `@adminium/server` now, so they resolve inside the deployed image and not
+ * just in a workspace checkout (01 §2.3.1: the server, and only the server,
+ * composes concrete adapters).
+ */
+export const ADAPTER_PACKAGES = [
+    '@adminium/adapter-postgres',
+    '@adminium/adapter-mysql',
+    '@adminium/adapter-sqlite',
+];
+/**
+ * Register every available adapter package. Idempotent: dialects already in
+ * the registry are left untouched (tests re-build apps against the same
+ * process-wide registry).
+ */
+export async function registerAdapters(registry = adapterRegistry) {
+    const result = { registered: [], missing: [] };
+    const packages = ADAPTER_PACKAGES;
+    for (const pkg of packages) {
+        let mod;
+        try {
+            mod = await import(pkg);
+        }
+        catch {
+            result.missing.push(pkg);
+            continue;
+        }
+        const provider = providerFromModule(mod);
+        if (provider === null) {
+            result.missing.push(pkg);
+            continue;
+        }
+        if (!registry.has(provider.dialect)) {
+            registry.register(provider);
+            result.registered.push(provider.dialect);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=register-adapters.js.map

package/dist/connections/register-adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-adapters.js","sourceRoot":"","sources":["../../src/connections/register-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,eAAe,EAA8C,MAAM,0BAA0B,CAAC;AAEvG,SAAS,iBAAiB,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,SAAS,GAAG,KAAgC,CAAC;IACnD,OAAO,CACL,OAAO,SAAS,CAAC,OAAO,KAAK,QAAQ;QACrC,OAAO,SAAS,CAAC,MAAM,KAAK,UAAU;QACtC,OAAO,SAAS,CAAC,iBAAiB,KAAK,UAAU,CAClD,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACzD,MAAM,aAAa,GAAG,GAA8B,CAAC;IACrD,MAAM,SAAS,GAAG;QAChB,iBAAiB;QACjB,cAAc;QACd,eAAe;QACf,iBAAiB;QACjB,UAAU;QACV,SAAS;KACV,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC5B,IAAI,iBAAiB,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,aAAa,CAAC,GAAG,CAAoB,CAAC;IAC1F,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;QACjD,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;IAC7C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AASD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAsB;IACjD,4BAA4B;IAC5B,yBAAyB;IACzB,0BAA0B;CAC3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,WAA6C,eAAe;IAE5D,MAAM,MAAM,GAA2B,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACvE,MAAM,QAAQ,GAAG,gBAAgB,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,GAAY,CAAC;QACjB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC5B,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/crud/filters.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The list-DSL filter grammar and its dynamic-Kysely compiler
+ * (08-server-api.md §2.7.1). Identifiers are resolved against the snapshot
+ * before they reach Kysely (`db.dynamic.ref` receives snapshot strings
+ * only); every value binds as a parameter — §7 item 1 by construction.
+ */
+import type { DynamicModule, Expression, ExpressionBuilder, SqlBool } from 'kysely';
+import { z } from 'zod';
+import type { Dialect } from '@adminium/engine';
+import { ForbiddenError } from '../errors.js';
+import type { SourceDatabase } from '../connections/manager.js';
+import type { ResolvedTable, SnapshotView } from './identifiers.js';
+export declare const FILTER_OPS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "in", "like", "ilike", "is_null", "not_null", "between"];
+export type FilterOp = (typeof FILTER_OPS)[number];
+export interface FilterCondition {
+    column: string;
+    op: FilterOp;
+    /** Required except for is_null / not_null. */
+    value?: unknown;
+}
+export type RecordFilter = FilterCondition | {
+    and: RecordFilter[];
+} | {
+    or: RecordFilter[];
+};
+export declare const recordFilterSchema: z.ZodType<RecordFilter>;
+export declare const MAX_FILTER_CONDITIONS = 16;
+export declare const MAX_FILTER_GROUP_DEPTH = 2;
+export declare const MAX_IN_VALUES = 200;
+/** Structural limits (§2.7.1 refinement): depth ≤ 2 groups, ≤ 16 conditions. */
+export declare function assertFilterLimits(filter: RecordFilter): void;
+/** Parse the `where` query param (URL-encoded JSON) into a validated tree. */
+export declare function parseWhereParam(raw: string): RecordFilter;
+export interface CompileFilterContext {
+    view: SnapshotView;
+    table: ResolvedTable;
+    /** `table:<conn>:<table>:read_pii`-equivalent — masked columns usable when true. */
+    canReadPii: boolean;
+    dynamic: DynamicModule<SourceDatabase>;
+    /** Source dialect — decides `ilike` (postgres) vs `LOWER(...) LIKE` (mysql/sqlite). */
+    dialect: Dialect;
+}
+type Eb = ExpressionBuilder<Record<string, Record<string, unknown>>, string>;
+/** Compile a validated filter tree inside a Kysely `where((eb) => …)` callback. */
+export declare function compileFilter(eb: Eb, ctx: CompileFilterContext, filter: RecordFilter): Expression<SqlBool>;
+/** Escape LIKE wildcards in user text for the `q=` quick search. */
+export declare function escapeLike(text: string): string;
+/**
+ * `q=` quick search (§2.7.1): a case-insensitive `%q%` substring match OR-ed
+ * across the table's text-ish columns from the snapshot, excluding masked ones
+ * for non-PII readers. Compiled per dialect via {@link compileILike} — postgres
+ * `ILIKE`, mysql/sqlite `LOWER(...) LIKE LOWER(...)`.
+ */
+export declare function compileQuickSearch(eb: Eb, ctx: CompileFilterContext, q: string): Expression<SqlBool> | null;
+/** Re-exported for routes that need the masked-column rejection directly. */
+export { ForbiddenError };
+//# sourceMappingURL=filters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../src/crud/filters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAuB,OAAO,EAAE,MAAM,QAAQ,CAAC;AACzG,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD,OAAO,EAAE,cAAc,EAAyB,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEpE,eAAO,MAAM,UAAU,2GAab,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,QAAQ,CAAC;IACb,8CAA8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,YAAY,GACpB,eAAe,GACf;IAAE,GAAG,EAAE,YAAY,EAAE,CAAA;CAAE,GACvB;IAAE,EAAE,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC;AAQ3B,eAAO,MAAM,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAM3B,CAAC;AAE7B,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,eAAO,MAAM,sBAAsB,IAAI,CAAC;AACxC,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAqB7D;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAezD;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,aAAa,CAAC;IACrB,oFAAoF;IACpF,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACvC,uFAAuF;IACvF,OAAO,EAAE,OAAO,CAAC;CAClB;AAYD,KAAK,EAAE,GAAG,iBAAiB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAgE7E,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,oBAAoB,EAAE,MAAM,EAAE,YAAY,GAAG,UAAU,CAAC,OAAO,CAAC,CAQ1G;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,EAAE,EACN,GAAG,EAAE,oBAAoB,EACzB,CAAC,EAAE,MAAM,GACR,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI,CAO5B;AAED,6EAA6E;AAC7E,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/crud/filters.js

@@ -0,0 +1,177 @@
+/**
+ * The list-DSL filter grammar and its dynamic-Kysely compiler
+ * (08-server-api.md §2.7.1). Identifiers are resolved against the snapshot
+ * before they reach Kysely (`db.dynamic.ref` receives snapshot strings
+ * only); every value binds as a parameter — §7 item 1 by construction.
+ */
+import { z } from 'zod';
+import { ForbiddenError, ValidationFailedError } from '../errors.js';
+export const FILTER_OPS = [
+    'eq',
+    'neq',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'in',
+    'like',
+    'ilike',
+    'is_null',
+    'not_null',
+    'between',
+];
+const conditionSchema = z.object({
+    column: z.string().min(1),
+    op: z.enum(FILTER_OPS),
+    value: z.unknown().optional(),
+});
+export const recordFilterSchema = z.lazy(() => z.union([
+    conditionSchema,
+    z.object({ and: z.array(recordFilterSchema).min(1).max(16) }),
+    z.object({ or: z.array(recordFilterSchema).min(1).max(16) }),
+]));
+export const MAX_FILTER_CONDITIONS = 16;
+export const MAX_FILTER_GROUP_DEPTH = 2;
+export const MAX_IN_VALUES = 200;
+/** Structural limits (§2.7.1 refinement): depth ≤ 2 groups, ≤ 16 conditions. */
+export function assertFilterLimits(filter) {
+    let conditions = 0;
+    const walk = (node, groupDepth) => {
+        if ('and' in node || 'or' in node) {
+            if (groupDepth >= MAX_FILTER_GROUP_DEPTH) {
+                throw new ValidationFailedError('Filter groups may nest at most 2 levels deep.', {
+                    maxDepth: MAX_FILTER_GROUP_DEPTH,
+                });
+            }
+            const children = 'and' in node ? node.and : node.or;
+            for (const child of children)
+                walk(child, groupDepth + 1);
+            return;
+        }
+        conditions += 1;
+        if (conditions > MAX_FILTER_CONDITIONS) {
+            throw new ValidationFailedError('Filters are limited to 16 conditions.', {
+                maxConditions: MAX_FILTER_CONDITIONS,
+            });
+        }
+    };
+    walk(filter, 0);
+}
+/** Parse the `where` query param (URL-encoded JSON) into a validated tree. */
+export function parseWhereParam(raw) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw new ValidationFailedError('`where` must be URL-encoded JSON.', {});
+    }
+    const parsed = recordFilterSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new ValidationFailedError('`where` does not match the filter grammar.', {
+            issues: parsed.error.issues,
+        });
+    }
+    assertFilterLimits(parsed.data);
+    return parsed.data;
+}
+function requireValue(condition) {
+    if (condition.value === undefined) {
+        throw new ValidationFailedError(`Filter op "${condition.op}" requires a value.`, {
+            column: condition.column,
+            op: condition.op,
+        });
+    }
+    return condition.value;
+}
+/**
+ * Case-insensitive substring match, compiled per dialect. Postgres has a
+ * native `ILIKE`; MySQL and SQLite have neither (`ILIKE` is a syntax error on
+ * both), so both operands are folded with `LOWER()`. Folding — rather than a
+ * bare `LIKE` — keeps the match case-insensitive regardless of the column's
+ * collation: SQLite's default `LIKE` only folds ASCII, and a `_bin`/`_cs`
+ * MySQL column would otherwise compare case-sensitively. The value still binds
+ * as a parameter; `LOWER()` wraps the placeholder, not an inlined literal.
+ */
+function compileILike(eb, dialect, ref, pattern) {
+    if (dialect === 'postgres')
+        return eb(ref, 'ilike', pattern);
+    return eb(eb.fn('lower', [ref]), 'like', eb.fn('lower', [eb.val(pattern)]));
+}
+function compileCondition(eb, ctx, condition) {
+    // Masked columns are rejected in `where` for non-PII readers (§5.3 rule 2).
+    const column = ctx.view.readableColumn(ctx.table, condition.column, ctx.canReadPii);
+    const ref = ctx.dynamic.ref(column.name);
+    switch (condition.op) {
+        case 'eq':
+            return eb(ref, '=', requireValue(condition));
+        case 'neq':
+            return eb(ref, '!=', requireValue(condition));
+        case 'gt':
+            return eb(ref, '>', requireValue(condition));
+        case 'gte':
+            return eb(ref, '>=', requireValue(condition));
+        case 'lt':
+            return eb(ref, '<', requireValue(condition));
+        case 'lte':
+            return eb(ref, '<=', requireValue(condition));
+        case 'in': {
+            const value = requireValue(condition);
+            if (!Array.isArray(value) || value.length > MAX_IN_VALUES) {
+                throw new ValidationFailedError('`in` takes an array of at most 200 values.', {
+                    column: condition.column,
+                });
+            }
+            if (value.length === 0)
+                return eb(eb.val(1), '=', 0); // empty set matches nothing
+            return eb(ref, 'in', value);
+        }
+        case 'like':
+            return eb(ref, 'like', String(requireValue(condition)));
+        case 'ilike':
+            return compileILike(eb, ctx.dialect, ref, String(requireValue(condition)));
+        case 'is_null':
+            return eb(ref, 'is', null);
+        case 'not_null':
+            return eb(ref, 'is not', null);
+        case 'between': {
+            const value = requireValue(condition);
+            if (!Array.isArray(value) || value.length !== 2) {
+                throw new ValidationFailedError('`between` takes a [low, high] pair.', {
+                    column: condition.column,
+                });
+            }
+            return eb.and([eb(ref, '>=', value[0]), eb(ref, '<=', value[1])]);
+        }
+    }
+}
+/** Compile a validated filter tree inside a Kysely `where((eb) => …)` callback. */
+export function compileFilter(eb, ctx, filter) {
+    if ('and' in filter) {
+        return eb.and(filter.and.map((child) => compileFilter(eb, ctx, child)));
+    }
+    if ('or' in filter) {
+        return eb.or(filter.or.map((child) => compileFilter(eb, ctx, child)));
+    }
+    return compileCondition(eb, ctx, filter);
+}
+/** Escape LIKE wildcards in user text for the `q=` quick search. */
+export function escapeLike(text) {
+    return text.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+/**
+ * `q=` quick search (§2.7.1): a case-insensitive `%q%` substring match OR-ed
+ * across the table's text-ish columns from the snapshot, excluding masked ones
+ * for non-PII readers. Compiled per dialect via {@link compileILike} — postgres
+ * `ILIKE`, mysql/sqlite `LOWER(...) LIKE LOWER(...)`.
+ */
+export function compileQuickSearch(eb, ctx, q) {
+    const pattern = `%${escapeLike(q)}%`;
+    const targets = [...ctx.table.columns.values()].filter((column) => column.textish && !column.secret && (ctx.canReadPii || !column.masked));
+    if (targets.length === 0)
+        return null;
+    return eb.or(targets.map((column) => compileILike(eb, ctx.dialect, ctx.dynamic.ref(column.name), pattern)));
+}
+/** Re-exported for routes that need the masked-column rejection directly. */
+export { ForbiddenError };
+//# sourceMappingURL=filters.js.map

package/dist/crud/filters.js.map

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