@materializecms/db 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Novità di Materialize
+
+Ogni versione, dalla più recente. Le novità in arrivo si scrivono sotto «Prossima versione»: `npm run bump` le assegna alla nuova versione.
+
+## Prossima versione
+
+## 0.1.0 — 2026-10-31
+
+La prima versione pubblica.
+
+- **Editor visuale**: pagine disegnate su una tela, con sezioni, colonne, testi, immagini, video, icone e forme; componenti riutilizzabili con varianti; righelli, guide, allineamenti e misure; modalità Contenuti per chi modifica solo i testi.
+- **Animazioni ed effetti**: animazioni allo scorrimento e con linee temporali, stati al passaggio del mouse, sfondi WebGL e oggetti 3D.
+- **Contenuti**: raccolte come Progetti, Diario e Team, con pagine modello; azioni rapide e selezione multipla negli elenchi e nei Media.
+- **Siti in più lingue**: traduzioni collegate tra loro, anche con l’AI, e un selettore di lingua per il sito.
+- **SEO**: titoli e descrizioni, sitemap, controlli sulla pagina e reindirizzamenti automatici quando cambia un indirizzo.
+- **Moduli di contatto** con invio delle email dal tuo server di posta.
+- **Assistente AI e server MCP**: testi, traduzioni e modifiche alle pagine chiedendole a parole.
+- **Importazione da WordPress**: pagine, articoli e immagini.
+- **Statistiche e cookie**: Google Analytics, Tag Manager, Meta Pixel, Plausible, Matomo e codice personalizzato, con il banner per il consenso.
+- **Installazione su VPS con un comando**: Node.js, HTTPS con Caddy, servizio che riparte da solo, firewall e link per finire nel browser.
+- **Immagine Docker** con `compose.yaml` pronto per l'HTTPS: il sito sta in un volume, quindi gli aggiornamenti dal pannello restano anche ricreando il container.
+- **Installazione nel browser**: controllo del server, nome e lingua del sito, account amministratore, passo per passo.
+- **Aggiornamenti con un clic** da Impostazioni → Aggiornamenti, con backup prima e ritorno automatico alla versione precedente se la nuova non parte; le correzioni possono installarsi da sole.
+- **Sicurezza**: verifica in due passaggi, pausa dopo i tentativi di accesso falliti, registro delle attività, backup giornalieri del database e dei media.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristiano Casazza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @materializecms/db
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Il database di Materialize: contenuti con bozze, pubblicazione e revisioni, utenti e sessioni (SQLite o libSQL).
+
+Lo usa il server di Materialize: di solito non serve importarlo direttamente. Funziona con un file SQLite locale o con un database libSQL ospitato.
+
+## Materialize
+
+CMS open source con editor visuale: le pagine si disegnano sulla tela, il sito è fatto di file statici veloci. Per un nuovo sito (serve Node 24):
+
+```bash
+npm create materialize@latest
+```
+
+Documentazione e codice: https://github.com/materializecms/materialize · Licenza MIT.

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@materializecms/db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Il database di Materialize: contenuti con bozze, pubblicazione e revisioni, utenti e sessioni (SQLite o libSQL).",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/materializecms/materialize.git",
+    "directory": "packages/db"
+  },
+  "homepage": "https://github.com/materializecms/materialize#readme",
+  "bugs": "https://github.com/materializecms/materialize/issues",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "dependencies": {
+    "@libsql/client": "0.18.0",
+    "drizzle-orm": "0.45.4"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/activity.d.ts

@@ -0,0 +1,38 @@
+import type { Db } from './database.ts';
+export interface ActivityEntry {
+    id: string;
+    at: Date;
+    userId: string | null;
+    userName: string;
+    /** A dotted code: "login.failed", "document.published", "user.removed"… */
+    action: string;
+    target: string;
+    detail: Record<string, unknown> | null;
+    ip: string | null;
+    /** Position in the log, to continue a list from (entries of the same millisecond included). */
+    seq: number;
+}
+/** The activity log: written by the server as things happen, read by administrators. */
+export declare function createActivityStore(db: Db): {
+    record(entry: Omit<ActivityEntry, 'id' | 'at' | 'seq'>): Promise<void>;
+    /**
+     * Newest first. `prefixes` keeps the actions of some groups ("login.", "user."…); `before`
+     * continues a list from the `seq` of its last entry.
+     */
+    list(options?: {
+        prefixes?: string[];
+        before?: number;
+        limit?: number;
+    }): Promise<ActivityEntry[]>;
+    /** How many times an action happened since a moment: failed sign-ins in the last day… */
+    countSince(action: string, since: Date): Promise<number>;
+    /** Emails and addresses paused right now after failed sign-ins. */
+    lockedKeys(): Promise<string[]>;
+    /** Access tokens, with whose they are and when last used: for the security overview. */
+    tokens(): Promise<{
+        userId: string;
+        createdAt: Date;
+        lastUsedAt: Date | null;
+    }[]>;
+};
+export type ActivityStore = ReturnType<typeof createActivityStore>;

package/src/activity.js

@@ -0,0 +1,52 @@
+import { randomUUID } from 'node:crypto';
+import { and, count, desc, eq, getTableColumns, gt, like, lt, or, sql } from 'drizzle-orm';
+import { activity, apiTokens, loginAttempts } from './tables.js';
+/** Entries older than this are deleted as new ones come in. */
+const KEEP_MS = 365 * 24 * 60 * 60_000;
+/** The activity log: written by the server as things happen, read by administrators. */
+export function createActivityStore(db) {
+    let writes = 0;
+    return {
+        async record(entry) {
+            await db.insert(activity).values({ id: randomUUID(), at: new Date(), ...entry });
+            // Now and then, the oldest entries go.
+            if (++writes % 500 === 1)
+                await db.delete(activity).where(lt(activity.at, new Date(Date.now() - KEEP_MS)));
+        },
+        /**
+         * Newest first. `prefixes` keeps the actions of some groups ("login.", "user."…); `before`
+         * continues a list from the `seq` of its last entry.
+         */
+        async list(options = {}) {
+            const rows = await db
+                .select({ ...getTableColumns(activity), seq: sql `rowid` })
+                .from(activity)
+                .where(and(options.before ? sql `rowid < ${options.before}` : undefined, options.prefixes?.length ? or(...options.prefixes.map((p) => like(activity.action, `${p}%`))) : undefined))
+                .orderBy(desc(sql `rowid`))
+                .limit(Math.min(options.limit ?? 50, 200));
+            return rows.map((r) => ({ ...r, detail: r.detail ?? null, ip: r.ip ?? null, userId: r.userId ?? null }));
+        },
+        /** How many times an action happened since a moment: failed sign-ins in the last day… */
+        async countSince(action, since) {
+            const [row] = await db
+                .select({ n: count() })
+                .from(activity)
+                .where(and(eq(activity.action, action), gt(activity.at, since)));
+            return row?.n ?? 0;
+        },
+        /** Emails and addresses paused right now after failed sign-ins. */
+        async lockedKeys() {
+            const rows = await db
+                .select({ key: loginAttempts.key })
+                .from(loginAttempts)
+                .where(gt(loginAttempts.lockedUntil, new Date()));
+            return rows.map((r) => r.key);
+        },
+        /** Access tokens, with whose they are and when last used: for the security overview. */
+        async tokens() {
+            return db
+                .select({ userId: apiTokens.userId, createdAt: apiTokens.createdAt, lastUsedAt: apiTokens.lastUsedAt })
+                .from(apiTokens);
+        },
+    };
+}

package/src/auth.d.ts

@@ -0,0 +1,154 @@
+import type { Db } from './database.ts';
+export type Role = 'admin' | 'editor';
+export interface User {
+    id: string;
+    email: string;
+    name: string;
+    role: Role;
+    /** Signs in with a code from an authenticator app too. */
+    twoFactor: boolean;
+}
+/** A signed-in device, as listed in Profilo → Sicurezza. */
+export interface DeviceSession {
+    /** The hash of the session token: safe to show, useless to sign in. */
+    id: string;
+    userAgent: string | null;
+    ip: string | null;
+    createdAt: Date;
+    lastSeenAt: Date;
+}
+export interface Member extends User {
+    createdAt: Date;
+    /** Most recent sign-in, if any. */
+    lastSeenAt: Date | null;
+}
+export interface Invite {
+    id: string;
+    kind: 'invite' | 'reset';
+    email: string;
+    name: string;
+    role: Role;
+    userId: string | null;
+    createdAt: Date;
+    expiresAt: Date;
+}
+/** A personal access token as listed: the secret itself is shown only once, when created. */
+export interface ApiToken {
+    id: string;
+    name: string;
+    /** The last characters of the secret, to tell tokens apart. */
+    hint: string;
+    createdAt: Date;
+    lastUsedAt: Date | null;
+}
+/** Prefix of every personal access token, so they are easy to recognise (and to scan for if leaked). */
+export declare const TOKEN_PREFIX = "mzp_";
+/** Raised when an email already belongs to someone. */
+export declare class EmailTakenError extends Error {
+    constructor(email: string);
+}
+export declare function createAuthStore(db: Db): {
+    countUsers(): Promise<number>;
+    createUser(input: {
+        email: string;
+        name: string;
+        role: Role;
+        passwordHash: string;
+    }): Promise<User>;
+    findForLogin(email: string): Promise<(User & {
+        passwordHash: string;
+    }) | null>;
+    /** Returns the raw token for the cookie; only its hash is stored. */
+    createSession(userId: string, ttlMs: number, device?: {
+        userAgent?: string | null;
+        ip?: string | null;
+    }): Promise<{
+        token: string;
+        expiresAt: Date;
+    }>;
+    /**
+     * Who a session belongs to. It ends when it expires or when it has not been used for
+     * `idleMs`; use is noted at most every few minutes.
+     */
+    userForSession(token: string, idleMs?: number): Promise<User | null>;
+    /** The id under which a session is listed. */
+    sessionId: (token: string) => string;
+    listSessions(userId: string): Promise<DeviceSession[]>;
+    /** Signs one device out; only its owner can. */
+    endSession(userId: string, id: string): Promise<boolean>;
+    /** Signs every device out, except the session given. */
+    endOtherSessions(userId: string, keepToken?: string): Promise<number>;
+    twoFactorOf(userId: string): Promise<{
+        secret: string | null;
+        pending: string | null;
+        lastStep: number | null;
+        recoveryLeft: number;
+    } | null>;
+    /** A new secret during setup, not in use until a first code confirms it. */
+    setPendingSecret(userId: string, secret: string | null): Promise<void>;
+    /** The pending secret becomes the one in use, with fresh recovery codes (stored as hashes). */
+    enableTwoFactor(userId: string, step: number, recoveryCodes: string[]): Promise<void>;
+    disableTwoFactor(userId: string): Promise<void>;
+    /** Notes the time step of an accepted code, so the same code cannot be used again. */
+    useStep(userId: string, step: number): Promise<void>;
+    setRecoveryCodes(userId: string, codes: string[]): Promise<void>;
+    /** A recovery code works once: true when it was valid (and is now spent). */
+    useRecoveryCode(userId: string, code: string): Promise<boolean>;
+    /** Until when a key (an email, an address) is locked, if it is. */
+    lockedUntil(key: string): Promise<Date | null>;
+    /**
+     * Counts a failure. From `threshold` failures on, the key is locked for a time that doubles
+     * with each further failure (1, 2, 4… minutes, at most an hour). Failures are forgotten
+     * after a day without any.
+     */
+    recordFailure(key: string, threshold: number): Promise<{
+        failures: number;
+        lockedUntil: Date | null;
+    }>;
+    clearFailures(key: string): Promise<void>;
+    /** A new personal access token for someone: returns the secret, which is never stored. */
+    createToken(userId: string, name: string): Promise<{
+        token: string;
+        record: ApiToken;
+    }>;
+    listTokens(userId: string): Promise<ApiToken[]>;
+    /** Only the owner can revoke a token. */
+    revokeToken(id: string, userId: string): Promise<boolean>;
+    /** Who a token belongs to; notes when it was last used (at most once a minute). */
+    userForToken(token: string): Promise<User | null>;
+    deleteSession(token: string): Promise<void>;
+    purgeExpiredSessions(): Promise<void>;
+    listUsers(): Promise<Member[]>;
+    getUser(id: string): Promise<User | null>;
+    getPasswordHash(id: string): Promise<string | null>;
+    countAdmins(): Promise<number>;
+    /** Changes name, role or email; an email someone else already uses raises EmailTakenError. */
+    updateUser(id: string, input: {
+        name?: string;
+        role?: Role;
+        email?: string;
+    }): Promise<User | null>;
+    deleteUser(id: string): Promise<boolean>;
+    /** Sets a new password and signs the user out everywhere, except the session given. */
+    setPassword(id: string, passwordHash: string, keepSession?: string): Promise<void>;
+    emailTaken(email: string): Promise<boolean>;
+    /** Returns the raw token for the link; only its hash is stored. Replaces earlier links of the same kind. */
+    createInvite(input: {
+        kind: Invite['kind'];
+        email: string;
+        name?: string;
+        role: Role;
+        userId?: string;
+        createdBy?: string;
+        ttlMs: number;
+    }): Promise<{
+        token: string;
+        invite: Invite;
+    }>;
+    pendingInvites(): Promise<Invite[]>;
+    findInvite(token: string): Promise<Invite | null>;
+    revokeInvite(id: string): Promise<boolean>;
+    /** A link works once. */
+    consumeInvite(token: string): Promise<void>;
+};
+export type AuthStore = ReturnType<typeof createAuthStore>;