sveltekit-admin 0.2.0 → 0.5.0

package/README.md

@@ -5,6 +5,8 @@
 ![Version](https://img.shields.io/npm/v/sveltekit-admin)
 ![License](https://img.shields.io/npm/l/sveltekit-admin)
 
+See [CHANGELOG.md](./CHANGELOG.md) for release notes and breaking changes.
+
 ## Features
 
 - 🔍 **Auto-introspection** of Prisma schema
@@ -75,7 +77,6 @@ createAdminHandler({
   // Custom branding
   branding: {
     title: 'My Admin',
-    logo: '/logo.svg',
     primaryColor: '#6366f1'
   }
 });
@@ -106,6 +107,31 @@ const adminHandle = createAdminHandler({
 export const handle = sequence(authHandle, adminHandle);
 ```
 
+### Logout
+
+Same philosophy as `authCheck`: the library has no session system of its
+own, so it can't clear one for you. Provide the side effect (clear a
+cookie, invalidate a session, call your auth library's sign-out...) and a
+"Log out" button appears in the sidebar automatically — no button is
+rendered at all if `logout` isn't set.
+
+```typescript
+const adminHandle = createAdminHandler({
+  prisma,
+  authCheck: (event) => event.locals.session?.user?.role === 'admin',
+  logout: (event) => {
+    event.cookies.delete('session', { path: '/' });
+  },
+  logoutRedirectTo: '/login' // default: '/'
+});
+```
+
+The button submits a `POST {basePath}/_logout` form (never a bare link —
+logging out must never be triggerable by a GET, unlike a crawler or link
+prefetch would allow), and this route is checked *before* `authCheck`, so
+a user whose session already expired can still use it to clean up
+client-side state instead of being stuck behind a 401 with no way back.
+
 ## How It Works
 
 The admin handler intercepts all requests to `/admin/*` and:
@@ -140,6 +166,49 @@ models: {
 }
 ```
 
+## Multi-tenant / row-level scoping (`listWhere`) — read this before relying on it
+
+```typescript
+models: {
+  Post: {
+    // Applied to the LIST VIEW ONLY: search, sidebar filters (including
+    // the FK filter), and pagination counts. Composed with an AND, never
+    // a spread, so it can never be overwritten by a user-supplied filter
+    // on the same field.
+    listWhere: ({ locals }) => ({ tenantId: locals.tenantId })
+  }
+}
+```
+
+**`listWhere` does NOT scope anything except the list view.** The detail
+view, the edit form, the delete action, and the dashboard's per-model
+counts have no equivalent scoping hook in this version and remain fully
+open regardless of this config. Concretely: with only `listWhere` set, a
+user who obtains another tenant's row ID through any other channel (a
+referrer header, a log line, or simple enumeration on a model with an
+`Int` primary key) can still view, edit, and delete that row directly —
+`listWhere` only stops them from *discovering* the ID through the list or
+the FK filter in the first place.
+
+If you configure a `relations[field].where` scope for an FK filter (to
+resolve the target's display options/label, see the FK filter docs), it
+is a **separate function** from `listWhere` and is **not** kept in sync
+automatically — you must set both if you want the FK filter's dropdown
+*and* its active-value chip *and* the list rows to all be scoped
+consistently for the same relation.
+
+A `listWhere` function that returns `{}` throws instead of silently
+disabling the scope — this is deliberate: an empty object composed into
+an `AND` clause matches every row, which would fail *open* exactly when a
+caller (e.g. one built from a session value that unexpectedly turned out
+to be undefined) most needs protection. Make sure your scope function
+either returns a real condition or isn't called at all for a given
+request.
+
+Real per-record scoping (detail/edit/delete) is a known gap, not an
+oversight — track it separately if your application needs it; do not
+assume `listWhere` covers it.
+
 ## Prisma Schema Introspection
 
 The admin automatically parses your Prisma schema and:
@@ -148,7 +217,16 @@ The admin automatically parses your Prisma schema and:
 - Detects field types and generates appropriate form inputs
 - Handles relations (excluded from forms for now)
 - Respects field attributes (@id, @unique, @default, @updatedAt)
-- Auto-hides common sensitive fields (password, hash, secret, token)
+- Auto-hides common sensitive fields from the list view: any field whose name
+  contains `password`, `hash`, `secret` or `token` (case-insensitive), so
+  `hashedPassword`, `passwordHash` and `refreshToken` are all covered. Two things
+  to know about it:
+  - The match is on substrings, so it also catches ordinary names such as
+    `hashtag`, `tokenCount` or `secretariat`. Listing a field in
+    `models[].listFields` shows it regardless — that is the explicit override,
+    and the way to display a column the heuristic gets wrong.
+  - It only applies to the list view. Edit forms still render these fields, so
+    you can set a value; use `models[].hidden` to remove one everywhere.
 
 ## Supported Field Types
 

package/dist/index.d.ts

@@ -3,10 +3,5 @@
  * Django-like admin panel for SvelteKit + Prisma
  */
 export { createAdminHandler, type AdminHandlerConfig } from './server/handler.js';
-export { createAdmin, createLayoutLoad, createDashboardLoad, createModelListLoad, createModelNewLoad, createModelNewAction, createModelEditLoad, createModelEditAction, createModelDeleteAction, createAdminGuard, type AdminConfig, type AdminContext } from './admin.js';
-export { parsePrismaSchema, parseSchemaContent, getDisplayFields, getEditableFields, getInputType, fieldToLabel, type PrismaSchema, type PrismaModel, type PrismaField } from './server/introspection/parser.js';
-export { createListOperation, createGetOperation, createCreateOperation, createUpdateOperation, createDeleteOperation, buildSearchWhere, buildFilterWhere, type ListOptions, type ListResult } from './server/crud/operations.js';
-export { createAuthGuard, defaultAdminCheck, type AdminAuthConfig, type AdminSession } from './server/auth/guard.js';
-export { default as AdminLayout } from './components/AdminLayout.svelte';
-export { default as DataTable } from './components/DataTable.svelte';
-export { default as AdminForm } from './components/AdminForm.svelte';
+export { defaultAdminCheck } from './server/auth.js';
+export { parsePrismaSchema, parseSchemaContent, type PrismaSchema, type PrismaModel, type PrismaField } from './server/introspection/parser.js';

package/dist/index.js

@@ -2,17 +2,6 @@
  * SvelteKit Admin
  * Django-like admin panel for SvelteKit + Prisma
  */
-// Standalone handler (recommended - zero config!)
 export { createAdminHandler } from './server/handler.js';
-// Core admin factory and loaders (legacy)
-export { createAdmin, createLayoutLoad, createDashboardLoad, createModelListLoad, createModelNewLoad, createModelNewAction, createModelEditLoad, createModelEditAction, createModelDeleteAction, createAdminGuard } from './admin.js';
-// Prisma introspection utilities
-export { parsePrismaSchema, parseSchemaContent, getDisplayFields, getEditableFields, getInputType, fieldToLabel } from './server/introspection/parser.js';
-// CRUD operations
-export { createListOperation, createGetOperation, createCreateOperation, createUpdateOperation, createDeleteOperation, buildSearchWhere, buildFilterWhere } from './server/crud/operations.js';
-// Auth utilities
-export { createAuthGuard, defaultAdminCheck } from './server/auth/guard.js';
-// Re-export components
-export { default as AdminLayout } from './components/AdminLayout.svelte';
-export { default as DataTable } from './components/DataTable.svelte';
-export { default as AdminForm } from './components/AdminForm.svelte';
+export { defaultAdminCheck } from './server/auth.js';
+export { parsePrismaSchema, parseSchemaContent } from './server/introspection/parser.js';

package/dist/server/auth.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Role-based access check for the admin panel
+ */
+/**
+ * Default admin check - looks for role field
+ */
+export declare function defaultAdminCheck(user: unknown, adminRole?: string): boolean;

package/dist/server/auth.js

@@ -0,0 +1,19 @@
+/**
+ * Role-based access check for the admin panel
+ */
+/**
+ * Default admin check - looks for role field
+ */
+export function defaultAdminCheck(user, adminRole = 'admin') {
+    if (!user || typeof user !== 'object')
+        return false;
+    const u = user;
+    // Check common role field names
+    if (u.role === adminRole)
+        return true;
+    if (u.isAdmin === true)
+        return true;
+    if (Array.isArray(u.roles) && u.roles.includes(adminRole))
+        return true;
+    return false;
+}

package/dist/server/data.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Data access layer - derives Prisma model keys, coerces ids and form payloads,
+ * and wraps the CRUD calls the handler orchestrates.
+ */
+import type { PrismaModel } from './introspection/parser.js';
+export declare function toPrismaModel(name: string): string;
+export declare function primaryKeyOf(model: PrismaModel): string;
+/**
+ * Coerce l'id issu de l'URL vers le type de la clé primaire du modèle.
+ *
+ * L'ancienne implémentation appliquait `/^\d+$/.test(id) ? parseInt(id) : id`
+ * sans consulter le schéma : une PK String dont la valeur est entièrement
+ * numérique partait donc en nombre, et le vrai client Prisma rejetait la requête
+ * (`Argument \`id\`: Invalid value provided. Expected String, provided Int.`).
+ * Le mock, lui, acceptait n'importe quel type — d'où le test de régression
+ * côté intégration.
+ */
+export declare function coerceId(id: string, model: PrismaModel): string | number;
+/** Convertit un FormData en payload Prisma, en ignorant les champs auto-gérés. */
+export declare function formDataToPrisma(formData: FormData, model: PrismaModel): Record<string, unknown>;
+/**
+ * Traduit le paramètre `?page=` en fenêtre Prisma. Toute entrée qui n'est pas un
+ * entier sûr >= 1 retombe sur la première page : sans ce garde-fou, `?page=abc`
+ * envoyait `skip: NaN` et `?page=0` un `skip` négatif directement au client.
+ */
+export declare function paginate(pageParam: string | null, perPage: number): {
+    page: number;
+    skip: number;
+    take: number;
+};
+export declare function listRecords(prisma: any, model: PrismaModel, page: number, perPage: number, where?: Record<string, unknown>): Promise<{
+    items: any[];
+    total: number;
+}>;
+export declare function getRecord(prisma: any, model: PrismaModel, id: string): Promise<any | null>;
+export declare function createRecord(prisma: any, model: PrismaModel, data: Record<string, unknown>): Promise<void>;
+export declare function updateRecord(prisma: any, model: PrismaModel, id: string, data: Record<string, unknown>): Promise<void>;
+export declare function deleteRecord(prisma: any, model: PrismaModel, id: string): Promise<void>;

package/dist/server/data.js

@@ -0,0 +1,116 @@
+/**
+ * Data access layer - derives Prisma model keys, coerces ids and form payloads,
+ * and wraps the CRUD calls the handler orchestrates.
+ */
+export function toPrismaModel(name) {
+    return name.charAt(0).toLowerCase() + name.slice(1);
+}
+export function primaryKeyOf(model) {
+    return model.fields.find((f) => f.isId)?.name || 'id';
+}
+/**
+ * Coerce l'id issu de l'URL vers le type de la clé primaire du modèle.
+ *
+ * L'ancienne implémentation appliquait `/^\d+$/.test(id) ? parseInt(id) : id`
+ * sans consulter le schéma : une PK String dont la valeur est entièrement
+ * numérique partait donc en nombre, et le vrai client Prisma rejetait la requête
+ * (`Argument \`id\`: Invalid value provided. Expected String, provided Int.`).
+ * Le mock, lui, acceptait n'importe quel type — d'où le test de régression
+ * côté intégration.
+ */
+export function coerceId(id, model) {
+    const pkField = model.fields.find((f) => f.name === primaryKeyOf(model));
+    return pkField?.type === 'Int' ? parseInt(id) : id;
+}
+/** Convertit un FormData en payload Prisma, en ignorant les champs auto-gérés. */
+export function formDataToPrisma(formData, model) {
+    const data = {};
+    for (const field of model.fields) {
+        if (field.isId || field.isUpdatedAt || field.isCreatedAt || field.relation)
+            continue;
+        const value = formData.get(field.name);
+        if (value === null) {
+            if (field.type === 'Boolean')
+                data[field.name] = false;
+            continue;
+        }
+        switch (field.type) {
+            case 'Int':
+            case 'BigInt':
+                data[field.name] = value ? parseInt(value.toString()) : null;
+                break;
+            case 'Float':
+            case 'Decimal':
+                data[field.name] = value ? parseFloat(value.toString()) : null;
+                break;
+            case 'Boolean':
+                data[field.name] = value === 'on' || value === 'true' || value === '1';
+                break;
+            case 'DateTime':
+                data[field.name] = value ? new Date(value.toString()) : null;
+                break;
+            case 'Json':
+                try {
+                    data[field.name] = value ? JSON.parse(value.toString()) : null;
+                }
+                catch {
+                    data[field.name] = null;
+                }
+                break;
+            default:
+                data[field.name] = value.toString();
+        }
+    }
+    return data;
+}
+/**
+ * Traduit le paramètre `?page=` en fenêtre Prisma. Toute entrée qui n'est pas un
+ * entier sûr >= 1 retombe sur la première page : sans ce garde-fou, `?page=abc`
+ * envoyait `skip: NaN` et `?page=0` un `skip` négatif directement au client.
+ */
+export function paginate(pageParam, perPage) {
+    const parsed = parseInt(pageParam || '1');
+    const page = Number.isSafeInteger(parsed) && parsed >= 1 ? parsed : 1;
+    return { page, skip: (page - 1) * perPage, take: perPage };
+}
+export async function listRecords(prisma, model, page, perPage, where) {
+    const key = toPrismaModel(model.name);
+    const primaryKey = primaryKeyOf(model);
+    // Le calcul `(page - 1) * perPage` est dupliqué avec `paginate` DÉLIBÉRÉMENT.
+    // Router `listRecords` vers `paginate(String(page), perPage)` serait lossy : la
+    // conversion aller-retour passe par `parseInt`, et `String(1e24)` donne
+    // `'1e+24'`, que `parseInt` ramène à `1`. `listRecords` reçoit un `number` déjà
+    // validé par l'appelant ; ne pas « simplifier » en réintroduisant un parse.
+    const [items, total] = await Promise.all([
+        prisma[key].findMany({
+            where,
+            skip: (page - 1) * perPage,
+            take: perPage,
+            orderBy: { [primaryKey]: 'desc' }
+        }),
+        prisma[key].count({ where })
+    ]);
+    return { items, total };
+}
+export function getRecord(prisma, model, id) {
+    const primaryKey = primaryKeyOf(model);
+    return prisma[toPrismaModel(model.name)].findUnique({
+        where: { [primaryKey]: coerceId(id, model) }
+    });
+}
+export async function createRecord(prisma, model, data) {
+    await prisma[toPrismaModel(model.name)].create({ data });
+}
+export async function updateRecord(prisma, model, id, data) {
+    const primaryKey = primaryKeyOf(model);
+    await prisma[toPrismaModel(model.name)].update({
+        where: { [primaryKey]: coerceId(id, model) },
+        data
+    });
+}
+export async function deleteRecord(prisma, model, id) {
+    const primaryKey = primaryKeyOf(model);
+    await prisma[toPrismaModel(model.name)].delete({
+        where: { [primaryKey]: coerceId(id, model) }
+    });
+}

package/dist/server/handler.d.ts

@@ -11,24 +11,143 @@ export interface AdminHandlerConfig {
     basePath?: string;
     /** Authentication check - return true if user can access admin */
     authCheck?: (event: any) => boolean | Promise<boolean>;
+    /**
+     * Logout logic — same "bring your own auth" philosophy as `authCheck`:
+     * this library has no session system of its own, so it can't know how
+     * to clear yours (a cookie, a Lucia/Better-Auth/Auth.js call, whatever).
+     * You provide the side effect (clear the cookie, invalidate the
+     * session...); the handler wires it to a POST-only route and a sidebar
+     * button. No button is rendered at all if this isn't set — an admin
+     * with no `logout` configured looks exactly as it did before this
+     * option existed.
+     *
+     * POST-only, never a bare link: logging out must never be triggerable
+     * by a GET (a crawler, a link prefetch, `<img src>`), which a plain
+     * `<a href="/admin/_logout">` would allow. Runs BEFORE `authCheck` — a
+     * user whose session already expired (so `authCheck` would now reject
+     * them) must still be able to hit the logout route to clean up
+     * client-side state (e.g. clear a stale cookie) without being stuck
+     * behind a 401 first.
+     */
+    logout?: (event: any) => void | Promise<void>;
+    /** Where to redirect after logout (default: '/') */
+    logoutRedirectTo?: string;
     /** Per-model configuration */
     models?: Record<string, {
         hidden?: string[];
         readonly?: string[];
         listFields?: string[];
         label?: string;
-        icon?: string;
+        /**
+         * Scoping `where` applied to the LIST VIEW ONLY of this model
+         * (search, sidebar filters, FK filter, pagination count) — composed
+         * via `AND` with active filters, never a spread (docs/design
+         * §0.c/§5.2). Deliberately named `listWhere`, not `where`: a bare
+         * `where` invites a developer to believe it scopes every operation
+         * on the model (detail view, edit, delete, dashboard counts), which
+         * it does NOT — those have no equivalent scoping in this version and
+         * remain fully open regardless of this config (a real risk found in
+         * review: a multi-tenant app that relies on `listWhere` alone gets a
+         * false sense of safety while `getRecord`/`updateRecord`/
+         * `deleteRecord` stay unscoped for anyone who obtains a row's ID
+         * through another channel — a referrer, a log line, or straight
+         * enumeration on a model with an Int primary key).
+         *
+         * Without this scope, the FK filter this feature adds makes
+         * cross-tenant row discovery through the list trivial: `?f.authorId=
+         * 1..N` used to return another tenant's row (its label stayed
+         * protected via `relations[x].where`, §6.3.b, but the row itself did
+         * not). This config closes that specific hole for the list — nothing
+         * more. If you need every view scoped, you currently have to wire
+         * `relations[x].where` for the active-FK-label lookup separately
+         * (they are NOT the same function and are NOT automatically kept in
+         * sync), and there is no scoping hook at all yet for
+         * detail/edit/delete/dashboard — track that as a real gap, not an
+         * oversight to work around silently.
+         *
+         * A scope function that returns `{}` (e.g. because `locals.userId`
+         * was undefined after a session expired) is NOT treated as "no
+         * scope" — `{}` would silently fail open (an intersection with an
+         * empty clause matches everything) exactly when a caller most needs
+         * protection. It throws instead: fail loud on a misbehaving scope
+         * function, never fail open on a data leak.
+         */
+        listWhere?: (ctx: {
+            locals?: any;
+        }) => Record<string, unknown>;
+        relations?: Record<string, {
+            widget?: 'select' | 'raw-id' | 'hidden';
+            labelTemplate?: string;
+            orderBy?: Record<string, 'asc' | 'desc'>;
+            where?: (ctx: {
+                locals?: any;
+            }) => Record<string, unknown>;
+            nullLabel?: string;
+        }>;
+        /**
+         * Champs interrogés par la barre de recherche texte libre. Sans
+         * config, une heuristique conservatrice reprend `relationDefaults.labelFields`
+         * parmi les champs String non sensibles (voir docs/design/list-search-filters.md §2.1).
+         * Une config explicite gagne toujours et n'est jamais tronquée par
+         * l'heuristique — un champ non filtrable au sens de `isFilterableFieldType`
+         * (relation, liste, Json, Bytes) ou sensible (password/hash/secret/token)
+         * y est silencieusement ignoré.
+         */
+        searchFields?: string[];
+        /**
+         * Champs filtrables via la sidebar de la liste. Config explicite
+         * (forme courte `'published'` ou objet `{ field, label }`) — sinon
+         * une heuristique auto-détecte les champs Boolean et enum uniquement
+         * (domaine de valeurs connu statiquement, zéro requête pour rendre la
+         * sidebar ; voir docs/design/list-search-filters.md §3.5). Une config
+         * invalide (champ inexistant, sensible, relation, type non supporté)
+         * lève une erreur au démarrage — c'est une erreur de développeur, elle
+         * doit échouer fort plutôt que produire un filtre silencieusement mort.
+         */
+        listFilter?: import('./query/filterDetection.js').ListFilterConfigEntry[];
     }>;
     /** Models to exclude from admin */
     exclude?: string[];
+    /** Hide pivot/junction tables automatically (default: true) */
+    hidePivotTables?: boolean;
+    /** Relation defaults */
+    relationDefaults?: {
+        /** Au-delà de ce nombre d'options, une FK est rendue en raw-id (default: 200) */
+        selectThreshold?: number;
+        /** Champs candidats pour le label, dans l'ordre de préférence */
+        labelFields?: string[];
+    };
+    /**
+     * Défauts pour la sidebar de filtres (listFilter).
+     * `linkThreshold`: en dessous ou égal à ce nombre d'options, un filtre FK
+     * est rendu en liens dans la sidebar ; au-dessus (et ≤ relationDefaults.selectThreshold),
+     * en `<select>` dans un mini form GET (docs/design/list-search-filters.md §3.2).
+     * `autoDetect`: auto-détection des champs Boolean/enum quand pas de config
+     * `listFilter` explicite (default: true).
+     */
+    listFilterDefaults?: {
+        linkThreshold?: number;
+        autoDetect?: boolean;
+    };
+    /**
+     * Recherche texte libre : configuration globale.
+     * `mode`: 'auto' détecte le provider du schéma et n'émet `mode: 'insensitive'`
+     * que sur postgresql/cockroachdb/mongodb (les seuls où Prisma le supporte —
+     * l'émettre sur sqlite/mysql/sqlserver lève une erreur Prisma). 'insensitive'
+     * et 'default' forcent le comportement, pour un provider non détectable
+     * (`provider = env(...)`) ou un besoin spécifique (index `citext`, etc.).
+     * Voir docs/design/list-search-filters.md §2.5.
+     */
+    search?: {
+        mode?: 'auto' | 'insensitive' | 'default';
+    };
     /** Custom branding */
     branding?: {
         title?: string;
-        logo?: string;
         primaryColor?: string;
     };
 }
 export declare function createAdminHandler(config: AdminHandlerConfig): ({ event, resolve }: {
     event: any;
-    resolve: Function;
-}) => Promise<any>;
+    resolve: (event: any) => Response | Promise<Response>;
+}) => Promise<Response>;