sveltekit-admin 0.6.0 → 0.8.1

package/dist/server/adapters/types.d.ts

@@ -21,6 +21,11 @@ import type { RelationEdge } from '../introspection/relations.js';
 export interface SchemaIntrospector {
     introspect(): Schema | Promise<Schema>;
 }
+export interface TargetGuard {
+    targetModel: Model;
+    targetPk: string | number;
+    filter?: Filter;
+}
 /**
  * Per-request CRUD + relation-read surface `handler.ts` talks to instead of
  * a raw ORM client. See docs/superpowers/specs/2026-08-13-db-adapter-abstraction-design.md
@@ -65,6 +70,7 @@ export interface DataAdapter {
             targetPkField: string;
             ids: Array<string | number>;
         }>;
+        targetGuards?: TargetGuard[];
     }): Promise<Record<string, unknown>>;
     updateRecord(model: Model, id: string | number, input: {
         scalars: Record<string, unknown>;
@@ -72,8 +78,9 @@ export interface DataAdapter {
             targetPkField: string;
             ids: Array<string | number>;
         }>;
-    }): Promise<Record<string, unknown>>;
-    deleteRecord(model: Model, id: string | number): Promise<void>;
+        targetGuards?: TargetGuard[];
+    }, authorizationFilter?: Filter): Promise<Record<string, unknown>>;
+    deleteRecord(model: Model, id: string | number, authorizationFilter?: Filter): Promise<void>;
     /** `targetModel` est fourni par l'appelant : chaque site d'appel actuel l'a déjà résolu. */
     getM2mSelectedIds(model: Model, edge: RelationEdge, targetModel: Model, recordId: string | number): Promise<Array<string | number>>;
 }

package/dist/server/audit.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Audit-log helpers for successful admin writes.
+ *
+ * The package has no session store and no first-party AuditLog table — same
+ * bring-your-own philosophy as `authCheck` / `logout`. This module builds a
+ * redacted `AuditEvent` and emits it to the consumer's callback. Sensitive
+ * names (`isSensitiveFieldName`) and config `hidden` fields are stripped from
+ * every snapshot so the audit sink cannot become a second oracle for secrets.
+ */
+import type { Model } from './types/schema.js';
+export type AuditAction = 'create' | 'update' | 'delete';
+export type AuditEvent = {
+    event: any;
+    at: Date;
+    action: 'create';
+    model: string;
+    id: string | number;
+    values: Record<string, unknown>;
+    after: Record<string, unknown>;
+    m2m?: Record<string, Array<string | number>>;
+} | {
+    event: any;
+    at: Date;
+    action: 'update';
+    model: string;
+    id: string | number;
+    values: Record<string, unknown>;
+    before: Record<string, unknown> | null;
+    after: Record<string, unknown>;
+    changes: Record<string, {
+        from: unknown;
+        to: unknown;
+    }>;
+    m2m?: Record<string, Array<string | number>>;
+} | {
+    event: any;
+    at: Date;
+    action: 'delete';
+    model: string;
+    id: string | number;
+    before: Record<string, unknown> | null;
+};
+export declare function redactForAudit(record: Record<string, unknown>, model: Model, hidden: ReadonlySet<string>): Record<string, unknown>;
+export declare function diffRecords(before: Record<string, unknown>, after: Record<string, unknown>): Record<string, {
+    from: unknown;
+    to: unknown;
+}>;
+export interface BuildAuditEventInput {
+    event: any;
+    at?: Date;
+    action: AuditAction;
+    model: Model;
+    id: string | number;
+    hidden: ReadonlySet<string>;
+    values?: Record<string, unknown>;
+    m2m?: Record<string, {
+        targetPkField: string;
+        ids: Array<string | number>;
+    }>;
+    before?: Record<string, unknown> | null;
+    after?: Record<string, unknown>;
+}
+export declare function buildAuditEvent(input: BuildAuditEventInput): AuditEvent;
+export declare function readAuditSnapshot(getRecord: (model: Model, id: string | number) => Promise<Record<string, unknown> | null>, model: Model, id: string | number): Promise<Record<string, unknown> | null>;
+export declare function emitAudit(audit: ((entry: AuditEvent) => void | Promise<void>) | undefined, entry: AuditEvent): Promise<void>;

package/dist/server/audit.js

@@ -0,0 +1,106 @@
+/**
+ * Audit-log helpers for successful admin writes.
+ *
+ * The package has no session store and no first-party AuditLog table — same
+ * bring-your-own philosophy as `authCheck` / `logout`. This module builds a
+ * redacted `AuditEvent` and emits it to the consumer's callback. Sensitive
+ * names (`isSensitiveFieldName`) and config `hidden` fields are stripped from
+ * every snapshot so the audit sink cannot become a second oracle for secrets.
+ */
+import { isSensitiveFieldName } from './introspection/parser.js';
+export function redactForAudit(record, model, hidden) {
+    const out = {};
+    for (const field of model.fields) {
+        if (field.relation || field.isList)
+            continue;
+        if (isSensitiveFieldName(field.name) || hidden.has(field.name))
+            continue;
+        if (!(field.name in record))
+            continue;
+        out[field.name] = record[field.name];
+    }
+    return out;
+}
+function auditValuesEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (a instanceof Date && b instanceof Date)
+        return a.getTime() === b.getTime();
+    if (typeof a === 'bigint' && typeof b === 'bigint')
+        return a === b;
+    if (typeof a === 'object' && typeof b === 'object') {
+        try {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+export function diffRecords(before, after) {
+    const changes = {};
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const key of keys) {
+        const from = before[key];
+        const to = after[key];
+        if (!auditValuesEqual(from, to)) {
+            changes[key] = { from, to };
+        }
+    }
+    return changes;
+}
+function compactM2m(m2m) {
+    if (!m2m)
+        return undefined;
+    const keys = Object.keys(m2m);
+    if (keys.length === 0)
+        return undefined;
+    const out = {};
+    for (const key of keys) {
+        out[key] = m2m[key].ids;
+    }
+    return out;
+}
+export function buildAuditEvent(input) {
+    const at = input.at ?? new Date();
+    const hidden = input.hidden;
+    const m2m = compactM2m(input.m2m);
+    const base = { event: input.event, at, model: input.model.name, id: input.id };
+    if (input.action === 'delete') {
+        const before = input.before ? redactForAudit(input.before, input.model, hidden) : null;
+        return { ...base, action: 'delete', before };
+    }
+    const values = redactForAudit(input.values ?? {}, input.model, hidden);
+    if (input.action === 'create') {
+        const after = redactForAudit(input.after ?? {}, input.model, hidden);
+        return m2m
+            ? { ...base, action: 'create', values, after, m2m }
+            : { ...base, action: 'create', values, after };
+    }
+    const afterRaw = { ...(input.before ?? {}), ...(input.after ?? {}) };
+    const after = redactForAudit(afterRaw, input.model, hidden);
+    const before = input.before ? redactForAudit(input.before, input.model, hidden) : null;
+    const changes = before ? diffRecords(before, after) : {};
+    return m2m
+        ? { ...base, action: 'update', values, before, after, changes, m2m }
+        : { ...base, action: 'update', values, before, after, changes };
+}
+export async function readAuditSnapshot(getRecord, model, id) {
+    try {
+        return await getRecord(model, id);
+    }
+    catch {
+        return null;
+    }
+}
+export async function emitAudit(audit, entry) {
+    if (!audit)
+        return;
+    try {
+        await audit(entry);
+    }
+    catch (e) {
+        console.error('[sveltekit-admin] audit callback failed:', e);
+    }
+}

package/dist/server/csrf.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Vérification d'origine des requêtes mutantes servies sous `basePath`.
+ *
+ * SvelteKit fait le même contrôle (`runtime/server/respond.js`) mais ne peut
+ * pas porter la garantie ici : il tourne avant le hook `handle` (invisible
+ * pour cette lib), un `kit.csrf.checkOrigin: false` posé pour une route sans
+ * rapport le désactive partout, et il est court-circuité en dev. Revérifié
+ * ici, dev compris : un proxy qui strippe `Origin` doit casser sur
+ * `pnpm run dev`, pas en production.
+ */
+export type CsrfConfig = false | {
+    /**
+     * Origines acceptées en plus de celle de la requête. Normalisées en
+     * origine, donc `https://ops.example/` et `https://ops.example` sont
+     * la même entrée.
+     */
+    trustedOrigins?: string[];
+};
+export interface ResolvedCsrf {
+    enabled: boolean;
+    trustedOrigins: Set<string>;
+}
+/** Résolue au boot : une entrée illisible doit faire échouer `createAdminHandler`. */
+export declare function resolveCsrfConfig(csrf: CsrfConfig | undefined): ResolvedCsrf;
+export declare function verifyOrigin(csrf: ResolvedCsrf, event: {
+    url: URL;
+    request: {
+        method: string;
+        headers: {
+            get(name: string): string | null;
+        };
+    };
+}): Response | null;

package/dist/server/csrf.js

@@ -0,0 +1,55 @@
+/**
+ * Vérification d'origine des requêtes mutantes servies sous `basePath`.
+ *
+ * SvelteKit fait le même contrôle (`runtime/server/respond.js`) mais ne peut
+ * pas porter la garantie ici : il tourne avant le hook `handle` (invisible
+ * pour cette lib), un `kit.csrf.checkOrigin: false` posé pour une route sans
+ * rapport le désactive partout, et il est court-circuité en dev. Revérifié
+ * ici, dev compris : un proxy qui strippe `Origin` doit casser sur
+ * `pnpm run dev`, pas en production.
+ */
+/** Sans effet de bord : jamais un vecteur CSRF, jamais inspectées. */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+/** Résolue au boot : une entrée illisible doit faire échouer `createAdminHandler`. */
+export function resolveCsrfConfig(csrf) {
+    if (csrf === false)
+        return { enabled: false, trustedOrigins: new Set() };
+    const trustedOrigins = new Set();
+    for (const entry of csrf?.trustedOrigins ?? []) {
+        let origin;
+        try {
+            origin = new URL(entry).origin;
+        }
+        catch {
+            throw new Error(`[sveltekit-admin] csrf.trustedOrigins contains "${entry}", which is not an absolute ` +
+                'URL. Use a full origin such as "https://admin.example.com".');
+        }
+        // `javascript:`, `data:`, `file:`… normalisent en "null", ce qu'envoie
+        // aussi une iframe sandboxée : les accepter ouvrirait à tout contexte opaque.
+        if (origin === 'null') {
+            throw new Error(`[sveltekit-admin] csrf.trustedOrigins contains "${entry}", whose origin is opaque ` +
+                '("null"). Only http(s) origins can be trusted.');
+        }
+        trustedOrigins.add(origin);
+    }
+    return { enabled: true, trustedOrigins };
+}
+export function verifyOrigin(csrf, event) {
+    if (!csrf.enabled)
+        return null;
+    if (SAFE_METHODS.has(event.request.method))
+        return null;
+    const origin = event.request.headers.get('origin');
+    if (origin === event.url.origin)
+        return null;
+    // `trustedOrigins` ne contient jamais `null` (rejeté au boot) : un en-tête
+    // absent ne peut donc pas y correspondre.
+    if (origin !== null && csrf.trustedOrigins.has(origin))
+        return null;
+    // Corps statique : ne jamais réfléchir l'`Origin` reçu ni énumérer les
+    // origines acceptées.
+    return new Response('[sveltekit-admin] Cross-site request forbidden', {
+        status: 403,
+        headers: { 'Content-Type': 'text/plain; charset=utf-8' }
+    });
+}

package/dist/server/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Forme unique des échecs de mutation admin.
+ *
+ * Deux producteurs, un seul type : `mutations.ts` pour les refus que la
+ * bibliothèque décide elle-même (validation, scope), `classifyWriteError`
+ * pour ceux que le moteur signale. Un seul consommateur : le site d'appel
+ * de `handleMutation` dans `handler.ts`, qui ne rend QUE le message d'une
+ * `AdminMutationError` — jamais celui d'une erreur pilote brute.
+ *
+ * La classification se fait par code, jamais par texte : les messages des
+ * pilotes changent entre versions, les codes non.
+ */
+export type MutationErrorKind = 'validation' | 'conflict' | 'reference' | 'restrict' | 'authorization' | 'notFound' | 'unknown';
+export declare class AdminMutationError extends Error {
+    readonly kind: MutationErrorKind;
+    readonly field?: string;
+    constructor(kind: MutationErrorKind, message: string, field?: string);
+}
+/**
+ * Erreur de configuration de la bibliothèque elle-même (scope non injectable,
+ * tenant absent…), destinée au développeur intégrateur et non à l'utilisateur
+ * de l'admin. Distincte d'`AdminMutationError` : elle ne décrit pas un refus
+ * de la donnée soumise, mais un montage incorrect côté consommateur, et c'est
+ * la SEULE erreur non typée que le chemin de mutation relaie telle quelle.
+ */
+export declare class AdminConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Les pilotes exposent le code SQLSTATE à des endroits différents : `code` sur
+ * `pg`, `mysql2` et `better-sqlite3`, `meta.code` sur une
+ * `PrismaClientKnownRequestError` issue d'une transaction interactive.
+ *
+ * Vit ici plutôt que dans `retry.ts` : deux modules classent désormais les
+ * erreurs pilote, et un second exemplaire de ce helper dériverait du premier.
+ */
+export declare function codeOf(error: unknown): string | undefined;
+/**
+ * Traduit un échec d'écriture en `AdminMutationError`, ou `null` si le code
+ * n'est pas reconnu — l'appelant rend alors un message générique.
+ *
+ * `reference` et `restrict` partagent le même code SQLSTATE (PostgreSQL 23503,
+ * SQLite SQLITE_CONSTRAINT_FOREIGNKEY) : c'est l'action en cours qui les
+ * sépare, pas le message. Sur create/update une cible soumise est invalide ;
+ * sur delete la ligne est référencée ailleurs.
+ */
+export declare function classifyWriteError(error: unknown, action: 'create' | 'update' | 'delete'): AdminMutationError | null;

package/dist/server/errors.js

@@ -0,0 +1,90 @@
+/**
+ * Forme unique des échecs de mutation admin.
+ *
+ * Deux producteurs, un seul type : `mutations.ts` pour les refus que la
+ * bibliothèque décide elle-même (validation, scope), `classifyWriteError`
+ * pour ceux que le moteur signale. Un seul consommateur : le site d'appel
+ * de `handleMutation` dans `handler.ts`, qui ne rend QUE le message d'une
+ * `AdminMutationError` — jamais celui d'une erreur pilote brute.
+ *
+ * La classification se fait par code, jamais par texte : les messages des
+ * pilotes changent entre versions, les codes non.
+ */
+export class AdminMutationError extends Error {
+    kind;
+    field;
+    constructor(kind, message, field) {
+        super(message);
+        this.name = 'AdminMutationError';
+        this.kind = kind;
+        this.field = field;
+    }
+}
+/**
+ * Erreur de configuration de la bibliothèque elle-même (scope non injectable,
+ * tenant absent…), destinée au développeur intégrateur et non à l'utilisateur
+ * de l'admin. Distincte d'`AdminMutationError` : elle ne décrit pas un refus
+ * de la donnée soumise, mais un montage incorrect côté consommateur, et c'est
+ * la SEULE erreur non typée que le chemin de mutation relaie telle quelle.
+ */
+export class AdminConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AdminConfigError';
+    }
+}
+/**
+ * Les pilotes exposent le code SQLSTATE à des endroits différents : `code` sur
+ * `pg`, `mysql2` et `better-sqlite3`, `meta.code` sur une
+ * `PrismaClientKnownRequestError` issue d'une transaction interactive.
+ *
+ * Vit ici plutôt que dans `retry.ts` : deux modules classent désormais les
+ * erreurs pilote, et un second exemplaire de ce helper dériverait du premier.
+ */
+export function codeOf(error) {
+    const candidate = error;
+    const raw = candidate?.code ?? candidate?.meta?.code;
+    return typeof raw === 'string' ? raw : undefined;
+}
+const UNIQUE_CODES = new Set([
+    'P2002', // Prisma
+    '23505', // PostgreSQL — unique_violation
+    'ER_DUP_ENTRY', // MySQL 1062
+    'SQLITE_CONSTRAINT_UNIQUE'
+]);
+const FOREIGN_KEY_CODES = new Set([
+    'P2003', // Prisma
+    '23503', // PostgreSQL — foreign_key_violation
+    'ER_NO_REFERENCED_ROW_2', // MySQL 1452 — la cible soumise n'existe pas
+    'ER_ROW_IS_REFERENCED_2', // MySQL 1451 — la ligne est référencée ailleurs
+    'SQLITE_CONSTRAINT_FOREIGNKEY'
+]);
+const NOT_FOUND_CODES = new Set(['P2025']);
+/**
+ * Traduit un échec d'écriture en `AdminMutationError`, ou `null` si le code
+ * n'est pas reconnu — l'appelant rend alors un message générique.
+ *
+ * `reference` et `restrict` partagent le même code SQLSTATE (PostgreSQL 23503,
+ * SQLite SQLITE_CONSTRAINT_FOREIGNKEY) : c'est l'action en cours qui les
+ * sépare, pas le message. Sur create/update une cible soumise est invalide ;
+ * sur delete la ligne est référencée ailleurs.
+ */
+export function classifyWriteError(error, action) {
+    if (error instanceof AdminMutationError)
+        return error;
+    const code = codeOf(error);
+    if (code === undefined)
+        return null;
+    if (UNIQUE_CODES.has(code)) {
+        return new AdminMutationError('conflict', 'A record with these values already exists.');
+    }
+    if (FOREIGN_KEY_CODES.has(code)) {
+        return action === 'delete'
+            ? new AdminMutationError('restrict', 'This record is referenced by other records.')
+            : new AdminMutationError('reference', 'A referenced record no longer exists.');
+    }
+    if (NOT_FOUND_CODES.has(code)) {
+        return new AdminMutationError('notFound', 'This record no longer exists.');
+    }
+    return null;
+}

package/dist/server/handler.d.ts

@@ -3,23 +3,17 @@
  * Zero files needed in routes - everything handled via hook
  */
 import type { DataAdapter, SchemaIntrospector } from './adapters/types.js';
+import type { AuditEvent } from './audit.js';
+import { type CsrfConfig } from './csrf.js';
+import type { AdminPlugin } from './plugin.js';
 export interface AdminHandlerConfig {
     /**
-     * Prisma client instance. Required unless `adapter` is provided directly —
-     * exactly one of the two must be set. Kept required-looking here (not `?`)
-     * for source compatibility with every existing call site; passing neither
-     * throws at handler-creation time (see the boot block).
+     * Explicit `{ introspector, data }` pair, from `createPrismaAdapter`,
+     * `createDrizzleAdapter`, or a custom implementation. The `{ prisma,
+     * prismaSchemaPath }` shortcut lives on the Prisma wrapper exported by
+     * the package root, not here.
      */
-    prisma?: any;
-    /** Path to Prisma schema file */
-    prismaSchemaPath?: string;
-    /**
-     * Explicit adapter, built via `createPrismaAdapter(...)` (or, in a future
-     * release, a Drizzle/other adapter). Takes priority over `prisma`/
-     * `prismaSchemaPath` when both are somehow set. Most consumers never touch
-     * this — passing `prisma`/`prismaSchemaPath` builds one internally.
-     */
-    adapter?: {
+    adapter: {
         introspector: SchemaIntrospector;
         data: DataAdapter;
     };
@@ -48,12 +42,50 @@ export interface AdminHandlerConfig {
     logout?: (event: any) => void | Promise<void>;
     /** Where to redirect after logout (default: '/') */
     logoutRedirectTo?: string;
+    /**
+     * Cross-site protection for every state-changing admin request (create /
+     * update / delete, `_logout`, `_search`). On by default; a missing `Origin`
+     * is rejected, as SvelteKit does. `trustedOrigins` allows a second
+     * legitimate origin, `csrf: false` opts out entirely.
+     *
+     * Why this isn't left to `kit.csrf.checkOrigin`, and the same-origin threat
+     * it does not cover: see `csrf.ts` and /docs/csrf.
+     */
+    csrf?: CsrfConfig;
+    /**
+     * Audit sink — same "bring your own" philosophy as `authCheck` / `logout`.
+     * The library has no log table and no session of its own, so it cannot
+     * know where to persist "admin X changed row Y" (your `AuditLog` model,
+     * a logger, an HTTP sink…). You provide the side effect; the handler
+     * calls it **after a successful create / update / delete** with a
+     * redacted `AuditEvent`. No callback means no behaviour change: no
+     * extra reads, no calls.
+     *
+     * The actor is whatever you already put on `event.locals` (the same
+     * object `authCheck` sees). Sensitive field names (`password` / `hash` /
+     * `secret` / `token`) and per-model `hidden` fields are stripped from
+     * `values` / `before` / `after` / `changes` so the sink cannot become a
+     * second oracle for secrets. Reads (GET), logout, and `_search` are
+     * not audited.
+     *
+     * Awaited before the 303 so a `prisma.auditLog.create(...)` inside the
+     * callback commits before the redirect. If the callback throws, the
+     * mutation still redirects — the write is the source of truth, the log
+     * is a sidecar (`console.error` with prefix
+     * `[sveltekit-admin] audit callback failed:`). There is no way to wrap
+     * the adapter write and your sink in one transaction without owning
+     * both stores.
+     */
+    audit?: (entry: AuditEvent) => void | Promise<void>;
     /** Per-model configuration */
     models?: Record<string, {
         hidden?: string[];
         readonly?: string[];
         listFields?: string[];
         label?: string;
+        scope?: (ctx: {
+            locals?: any;
+        }) => Record<string, unknown> | import('./adapters/types.js').Filter;
         /**
          * Scoping `where` applied to the LIST VIEW ONLY of this model
          * (search, sidebar filters, FK filter, pagination count) — composed
@@ -145,23 +177,22 @@ export interface AdminHandlerConfig {
         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;
         primaryColor?: string;
     };
+    /**
+     * Optional admin plugins (new pages + record actions). Omitted or `[]`
+     * keeps every builtin view byte-identical to a build without plugins.
+     * Plugin routes are matched before builtins, so a registered pattern
+     * with a literal token in a `:model`/`:id` position can take over a
+     * builtin path when it matches first (e.g. `['user']` shadows the User
+     * list); only an identical, token-for-token overlay throws at boot.
+     * See `AdminPlugin`. Options like graph `depth` belong on the author's
+     * factory, not here.
+     */
+    plugins?: AdminPlugin[];
 }
 export declare function createAdminHandler(config: AdminHandlerConfig): ({ event, resolve }: {
     event: any;