@navette-js/wire 0.0.0-stage → 1.0.0-beta.1

package/lib/index.js

@@ -0,0 +1,413 @@
+// @navette-js/wire — runtime serveur de composants à état, compatible avec le protocole du client livewire.js 4.4.8.
+// Prototype du jalon 0 (ADR 0001). Référence : sources/demo/vendor/livewire/livewire/src/Mechanisms/HandleComponents.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { UploadStore } from "./uploads.js";
+export { UploadStore } from "./uploads.js";
+export class WireError extends Error {
+    status;
+    constructor(status, message) { super(message); this.status = status; }
+}
+/** Classe de base d'un composant. Toute propriété propre énumérable ne commençant pas par `_` est de l'état public. */
+export class Component {
+    _id = '';
+    _effects = {};
+    _skipRender = false;
+    _errors = {};
+    /** Contexte de la requête HTTP en cours (requête, réponse, panel…), fourni par l'intégration. */
+    _ctx = null;
+    /** Runtime et requête d'origine : servent à monter des composants enfants pendant le rendu. */
+    _runtime = null;
+    _request = {};
+    /** Enfants rendus pendant cette requête, et enfants déjà présents dans le navigateur : clé → [balise, identifiant]. */
+    _children = {};
+    _previousChildren = {};
+    /** HTML affiché tant qu'un composant « lazy » n'est pas chargé : une seule racine. */
+    placeholder() { return '<div></div>'; }
+    /**
+     * Monte un composant enfant et rend son HTML, à insérer dans le rendu du parent (équivalent de `@livewire`).
+     * Si le navigateur possède déjà cet enfant (même clé), seule une souche est rendue : le client conserve l'enfant tel quel.
+     * `lazy` : l'enfant affiche son `placeholder()` et se charge quand il devient visible.
+     */
+    async mountChild(name, params = {}, key, options = {}) {
+        if (!this._runtime)
+            throw new Error('mountChild() : composant hors runtime.');
+        const previous = this._previousChildren[key];
+        if (previous) {
+            this._children[key] = previous;
+            // Propriétés réactives : l'enfant, mis à jour dans la même requête, reprendra ces valeurs (équivalent de #[Reactive]).
+            this._runtime.passPropsToChild(previous[1], params);
+            return `<${previous[0]} wire:id="${previous[1]}" wire:name="${escapeAttr(name)}" wire:key="${escapeAttr(key)}"></${previous[0]}>`;
+        }
+        const { html, component } = await this._runtime.mountWithInstance(name, params, { ...this._request, ctx: this._ctx, lazy: options.lazy, key });
+        this._children[key] = [/^\s*<([a-zA-Z0-9-]+)/.exec(html)[1], component.id];
+        return html;
+    }
+    mount(_params) { }
+    boot() { }
+    hydrate() { }
+    dehydrate() { }
+    get id() { return this._id; }
+    /** `self` : l'événement n'est reçu que par ce composant (équivalent de `->self()`). */
+    dispatch(name, params = {}, options = {}) {
+        (this._effects.dispatches ??= []).push({ name, params: params, ...(options.self ? { self: true } : {}) });
+    }
+    redirect(url, navigate = false) {
+        this._effects.redirect = url;
+        if (navigate)
+            this._effects.redirectUsingNavigate = true;
+    }
+    skipRender() { this._skipRender = true; }
+    /** Rendu partiel à la Filament : seul le fragment `wire:partial="<nom>"` est renvoyé (effects.partials), sans re-rendre tout le composant. */
+    renderPartial(name, html) { (this._effects.partials ??= {})[name] = html; this._skipRender = true; }
+    addError(path, message) { (this._errors[path] ??= []).push(message); }
+    resetErrorBag() { this._errors = {}; }
+}
+const LIFECYCLE = new Set(['constructor', 'render', 'mount', 'boot', 'hydrate', 'dehydrate', 'dispatch', 'redirect', 'skipRender', 'renderPartial', 'addError', 'resetErrorBag', 'mountChild', 'placeholder']);
+// Seuls les hooks de propriété (updatingFoo / updatedFoo) sont réservés par préfixe : `mountAction`, par exemple, est une méthode publique ordinaire.
+const isLifecycleHook = (m) => LIFECYCLE.has(m) || /^(updating|updated)[A-Z]/.test(m) || m.startsWith('_');
+/**
+ * Méthodes appelables depuis le navigateur : uniquement celles que la classe (ou une classe parente) nomme dans `static callable`.
+ * TypeScript efface `protected` et `private` à l'exécution : sans cette liste, toute méthode interne serait appelable par une
+ * requête forgée, et sa valeur de retour renvoyée au navigateur.
+ */
+export function callableMethods(component) {
+    const out = new Set();
+    for (let cls = component.constructor; cls && cls !== Component; cls = Object.getPrototypeOf(cls)) {
+        if (!Object.prototype.hasOwnProperty.call(cls, 'callable') || !Array.isArray(cls.callable))
+            continue;
+        for (const name of cls.callable)
+            if (typeof name === 'string' && !isLifecycleHook(name) && typeof component[name] === 'function')
+                out.add(name);
+    }
+    return out;
+}
+export function publicProperties(component) {
+    return Object.keys(component).filter((k) => !k.startsWith('_'));
+}
+// --- Synthétiseurs : les tableaux et objets voyagent sous la forme [valeur, { s: 'arr' }] (HandleSynths de Livewire).
+export function dehydrateValue(value) {
+    if (value === undefined)
+        return null;
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return [value.map(dehydrateValue), { s: 'arr' }];
+    return [Object.fromEntries(Object.entries(value).map(([k, v]) => [k, dehydrateValue(v)])), { s: 'arr' }];
+}
+export function hydrateValue(value) {
+    if (Array.isArray(value) && value.length === 2 && value[1] && typeof value[1] === 'object' && 's' in value[1]) {
+        const inner = value[0];
+        if (Array.isArray(inner))
+            return inner.map(hydrateValue);
+        return Object.fromEntries(Object.entries(inner).map(([k, v]) => [k, hydrateValue(v)]));
+    }
+    return value;
+}
+const escapeAttr = (s) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/'/g, '&#039;');
+/** Équivalent de Utils::insertAttributesIntoHtmlRoot : pose des attributs sur la balise racine. */
+export function insertAttributesIntoHtmlRoot(html, attributes) {
+    const m = /^\s*<([a-zA-Z0-9-]+)/.exec(html);
+    if (!m)
+        throw new WireError(500, 'Le rendu d\'un composant doit commencer par une balise racine.');
+    const attrs = Object.entries(attributes)
+        .map(([k, v]) => `${k}="${escapeAttr(typeof v === 'string' ? v : JSON.stringify(v))}"`)
+        .join(' ');
+    const at = m.index + m[0].length;
+    return html.slice(0, at) + ' ' + attrs + html.slice(at);
+}
+function setByPath(target, segments, value) {
+    let node = target;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const key = segments[i];
+        if (node[key] === null || typeof node[key] !== 'object')
+            node[key] = {};
+        node = node[key];
+    }
+    const last = segments[segments.length - 1];
+    if (value === '__rm__') {
+        Array.isArray(node) ? node.splice(Number(last), 1) : delete node[last];
+    }
+    else
+        node[last] = value;
+}
+/** Identifiant alphanumérique de 20 caractères, comme Str::random(20) de Livewire (il sert dans des id HTML et des sélecteurs). */
+const randomId = () => Array.from(randomBytes(20), (b) => 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'[b % 62]).join('');
+const MAGIC_ACTIONS = new Set(['$refresh', '$set', '$sync', '$commit']);
+const studly = (s) => s.replace(/(^|[_.-])(\w)/g, (_, __, c) => c.toUpperCase());
+/** Faux si la valeur contient, à n'importe quelle profondeur, une référence de fichier temporaire qui ne désigne aucun fichier reçu. */
+function uploadReferencesAreValid(value, store, depth = 0) {
+    if (typeof value === 'string')
+        return value.startsWith('livewire-files:') ? false : value.startsWith('livewire-file:') ? !!store?.resolve(value) : true;
+    if (!value || typeof value !== 'object')
+        return true;
+    if (depth > 8)
+        return false;
+    return Object.values(value).every((v) => uploadReferencesAreValid(v, store, depth + 1));
+}
+/** Propriétés réactives d'un composant (`static reactive`) : fixées par le parent, jamais par le navigateur. */
+const reactiveProps = (component) => component.constructor.reactive ?? [];
+export class WireRuntime {
+    registry = new Map();
+    options;
+    constructor(options) { this.options = options; }
+    get uploads() { return this.options.uploads ?? null; }
+    /** Paramètres passés par un parent à ses enfants déjà présents, pendant la requête en cours : identifiant de l'enfant → paramètres. */
+    requestScope = new AsyncLocalStorage();
+    passPropsToChild(childId, params) { this.requestScope.getStore()?.childProps.set(childId, params); }
+    register(name, cls) { this.registry.set(name, cls); cls.componentName = name; return this; }
+    make(name) {
+        const cls = this.registry.get(name);
+        if (!cls)
+            throw new WireError(404, `Composant inconnu : ${name}`);
+        return new cls();
+    }
+    checksum(snapshot) {
+        const { children: _children, ...memo } = snapshot.memo; // les enfants peuvent être modifiés par le client
+        return createHmac('sha256', this.options.key).update(JSON.stringify({ data: snapshot.data, memo })).digest('hex');
+    }
+    snapshot(component, name, memo) {
+        const data = {};
+        for (const k of publicProperties(component))
+            data[k] = dehydrateValue(component[k]);
+        const body = { data, memo: { id: component.id, name, ...memo, errors: component._errors } };
+        return { ...body, checksum: this.checksum(body) };
+    }
+    /** Paramètres de montage d'un composant « lazy », signés : le navigateur les renvoie tels quels à `__lazyLoad` (conteneur `__mountParamsContainer` de Livewire). */
+    encodeMountParams(name, params, request) {
+        const body = { data: { forMount: dehydrateValue(params), forComponent: name }, memo: { id: randomId(), name: '__mountParamsContainer', path: request.path ?? '/', method: request.method ?? 'GET', release: 'a-a-a' } };
+        return Buffer.from(JSON.stringify({ ...body, checksum: this.checksum(body) })).toString('base64');
+    }
+    decodeMountParams(name, encoded) {
+        let container;
+        try {
+            container = JSON.parse(Buffer.from(String(encoded), 'base64').toString('utf8'));
+        }
+        catch {
+            throw new WireError(404, 'Paramètres de montage illisibles.');
+        }
+        if (!container || typeof container.data !== 'object' || typeof container.memo !== 'object' || typeof container.checksum !== 'string')
+            throw new WireError(404, 'Paramètres de montage invalides.');
+        const expected = Buffer.from(this.checksum(container)), given = Buffer.from(container.checksum);
+        if (expected.length !== given.length || !timingSafeEqual(expected, given))
+            throw new WireError(419, 'Somme de contrôle des paramètres de montage invalide.');
+        // Les paramètres signés pour un composant ne valent pas pour un autre.
+        if (container.memo.name !== '__mountParamsContainer' || container.data.forComponent !== name)
+            throw new WireError(403, 'Paramètres de montage destinés à un autre composant.');
+        return (hydrateValue(container.data.forMount) ?? {});
+    }
+    /** Comme Livewire : un paramètre de montage du même nom qu'une propriété publique y est copié. */
+    assignMatchingProperties(component, params) {
+        const known = new Set(publicProperties(component));
+        for (const [k, v] of Object.entries(params))
+            if (known.has(k))
+                component[k] = v;
+    }
+    async renderRoot(component, name) {
+        const html = await component.render();
+        return insertAttributesIntoHtmlRoot(html, { 'wire:id': component.id, 'wire:name': name });
+    }
+    /** Premier rendu : HTML avec wire:snapshot et wire:effects sur la racine.
+     *  Le mémo ne porte `lazyLoaded` / `lazyIsolated` que pour un composant réellement « lazy » : leur seule présence fait ignorer les événements au client. */
+    async mount(name, params = {}, request = {}) {
+        return (await this.mountWithInstance(name, params, request)).html;
+    }
+    /** Comme mount(), mais rend aussi l'instance montée (pour lire son titre, par exemple). */
+    async mountWithInstance(name, params = {}, request = {}) {
+        const component = this.make(name);
+        component._ctx = request.ctx ?? null;
+        // Identifiant alphanumérique de 20 caractères, comme Str::random(20) de Livewire (il sert dans des id HTML et des sélecteurs).
+        component._id = randomId();
+        component._runtime = this;
+        component._request = { path: request.path, method: request.method };
+        await component.boot();
+        this.assignMatchingProperties(component, params);
+        let html;
+        if (request.lazy) {
+            // Composant « lazy » : `mount()` et le rendu attendent l'appel `__lazyLoad` du navigateur.
+            const placeholder = insertAttributesIntoHtmlRoot(await component.placeholder(), { 'x-intersect': `$wire.__lazyLoad('${this.encodeMountParams(name, params, request)}')` });
+            html = insertAttributesIntoHtmlRoot(placeholder, { 'wire:id': component.id, 'wire:name': name });
+        }
+        else {
+            await component.mount(params);
+            html = await this.renderRoot(component, name);
+        }
+        await component.dehydrate();
+        const snapshot = this.snapshot(component, name, {
+            path: request.path ?? '/', method: request.method ?? 'GET', release: 'a-a-a', children: Object.keys(component._children).length ? component._children : [], scripts: [], assets: [],
+            ...(request.lazy ? { lazyLoaded: false, lazyIsolated: true } : {}), ...(reactiveProps(component).length ? { props: reactiveProps(component) } : {}), locale: this.options.locale ?? 'en', islands: [],
+        });
+        const { html: _h, ...effects } = component._effects;
+        // Écouteurs d'événements (équivalent de #[On]) : le client appellera `__dispatch(événement, paramètres)`.
+        const listeners = Object.keys(component.constructor.listeners ?? {});
+        if (listeners.length)
+            effects.listeners = listeners;
+        return { html: insertAttributesIntoHtmlRoot(html, { ...(request.key !== undefined ? { 'wire:key': request.key } : {}), 'wire:snapshot': JSON.stringify(snapshot), 'wire:effects': JSON.stringify(effects) }), component };
+    }
+    /** Requête de mise à jour d'un composant : hydratation, mises à jour, appels, rendu, déshydratation. */
+    async update(snapshot, updates, calls, ctx = null) {
+        if (!snapshot || typeof snapshot.data !== 'object' || typeof snapshot.memo !== 'object' || typeof snapshot.checksum !== 'string')
+            throw new WireError(404, 'Snapshot invalide.');
+        const expected = Buffer.from(this.checksum(snapshot)), given = Buffer.from(snapshot.checksum);
+        if (expected.length !== given.length || !timingSafeEqual(expected, given))
+            throw new WireError(419, 'Somme de contrôle du snapshot invalide.');
+        const name = snapshot.memo.name;
+        const component = this.make(name);
+        const cls = component.constructor;
+        component._id = snapshot.memo.id;
+        component._ctx = ctx;
+        component._errors = { ...(snapshot.memo.errors ?? {}) };
+        component._runtime = this;
+        component._request = { path: snapshot.memo.path, method: snapshot.memo.method };
+        // `memo.children` n'est pas couvert par la somme de contrôle (le client le tient à jour) : seules les entrées bien formées sont retenues.
+        if (snapshot.memo.children && typeof snapshot.memo.children === 'object' && !Array.isArray(snapshot.memo.children)) {
+            for (const [key, value] of Object.entries(snapshot.memo.children)) {
+                if (Array.isArray(value) && /^[a-zA-Z][a-zA-Z0-9-]*$/.test(String(value[0])) && /^[A-Za-z0-9]{1,64}$/.test(String(value[1])))
+                    component._previousChildren[key] = [String(value[0]), String(value[1])];
+            }
+        }
+        const awaitsLazyLoad = snapshot.memo.lazyLoaded === false;
+        let lazyLoaded = false;
+        const known = new Set(publicProperties(component));
+        for (const [k, v] of Object.entries(snapshot.data))
+            if (known.has(k))
+                component[k] = hydrateValue(v);
+        // Propriétés réactives : elles ne viennent que du parent, rendu plus tôt dans la même requête.
+        const reactive = new Set(reactiveProps(component));
+        const passed = this.requestScope.getStore()?.childProps.get(component.id);
+        if (passed)
+            for (const prop of reactive)
+                if (Object.prototype.hasOwnProperty.call(passed, prop) && known.has(prop))
+                    component[prop] = passed[prop];
+        await component.boot();
+        await component.hydrate();
+        const applyUpdate = async (path, value) => {
+            const segments = path.split('.');
+            const prop = segments[0];
+            if (!known.has(prop))
+                throw new WireError(404, `Propriété publique introuvable : ${prop}`);
+            if (cls.locked?.includes(prop))
+                throw new WireError(403, `Propriété verrouillée : ${prop}`);
+            if (reactive.has(prop))
+                throw new WireError(403, `Propriété réactive, fixée par le composant parent : ${prop}`);
+            // Un segment comme `__proto__` écrirait dans le prototype partagé par tous les objets du serveur.
+            if (segments.some((segment) => segment === '__proto__' || segment === 'constructor' || segment === 'prototype'))
+                throw new WireError(403, `Chemin d'état refusé : ${path}`);
+            const anyC = component;
+            await anyC.updating?.(path, value);
+            await anyC[`updating${studly(prop)}`]?.(value, segments.slice(1).join('.') || null);
+            setByPath(component, segments, value);
+            await anyC.updated?.(path, value);
+            await anyC[`updated${studly(prop)}`]?.(value, segments.slice(1).join('.') || null);
+        };
+        for (const [path, value] of Object.entries(updates)) {
+            // Une référence de fichier temporaire renvoyée par le navigateur doit désigner un fichier réellement reçu.
+            if (!uploadReferencesAreValid(value, this.uploads))
+                throw new WireError(403, `Référence de fichier refusée : ${path}`);
+            await applyUpdate(path, value);
+        }
+        const allowed = callableMethods(component);
+        const returns = [];
+        for (const call of calls) {
+            if (typeof call?.method !== 'string' || !Array.isArray(call.params))
+                throw new WireError(404, 'Appel invalide.');
+            // Actions magiques : sans effet côté serveur, les valeurs voyagent dans `updates` (SupportMagicActions de Livewire).
+            if (MAGIC_ACTIONS.has(call.method)) {
+                returns.push(null);
+                continue;
+            }
+            if (call.method === '__lazyLoad') {
+                if (!awaitsLazyLoad || lazyLoaded)
+                    throw new WireError(404, 'Ce composant n\'attend pas de chargement différé.');
+                const params = this.decodeMountParams(name, call.params[0]);
+                this.assignMatchingProperties(component, params);
+                await component.mount(params);
+                lazyLoaded = true;
+                returns.push(null);
+                continue;
+            }
+            // Tant qu'il n'est pas chargé, un composant « lazy » n'a pas été monté : rien d'autre n'est appelable.
+            if (awaitsLazyLoad && !lazyLoaded)
+                throw new WireError(404, 'Composant non chargé.');
+            // --- téléversement de fichiers (port de WithFileUploads) : la cible est un chemin d'état, soumis aux mêmes gardes qu'une mise à jour
+            if (call.method === '_startUpload' || call.method === '_finishUpload' || call.method === '_uploadErrored' || call.method === '_removeUpload') {
+                const store = this.uploads;
+                const target = call.params[0];
+                if (!store || typeof target !== 'string' || target.length > 500)
+                    throw new WireError(404, 'Téléversement indisponible.');
+                if (call.method === '_startUpload') {
+                    component.dispatch('upload:generatedSignedUrl', { name: target, url: store.signedUrl(this.options.uploadPrefix ?? '/livewire') }, { self: true });
+                    component._skipRender = true;
+                }
+                else if (call.method === '_finishUpload') {
+                    const ids = Array.isArray(call.params[1]) ? call.params[1].map(String) : [];
+                    if (!ids.length || ids.some((id) => !store.resolve(id)))
+                        throw new WireError(404, 'Fichier temporaire introuvable.');
+                    await applyUpdate(target, call.params[2] === true ? ids.map((id) => UploadStore.reference(id)) : UploadStore.reference(ids[0]));
+                    component.dispatch('upload:finished', { name: target, tmpFilenames: ids }, { self: true });
+                }
+                else if (call.method === '_uploadErrored') {
+                    component.dispatch('upload:errored', { name: target }, { self: true });
+                    component.addError(target, 'The file failed to upload.');
+                }
+                else {
+                    component.dispatch('upload:removed', { name: target, tmpFilename: String(call.params[1] ?? '') }, { self: true });
+                    component._skipRender = true;
+                }
+                returns.push(null);
+                continue;
+            }
+            if (call.method === '__dispatch') {
+                const handler = cls.listeners?.[String(call.params[0])];
+                if (!handler)
+                    throw new WireError(404, `Aucun écouteur pour l'événement : ${String(call.params[0])}`);
+                const args = call.params[1] && typeof call.params[1] === 'object' ? Object.values(call.params[1]) : [];
+                returns.push((await component[handler](...args)) ?? null);
+                continue;
+            }
+            if (!allowed.has(call.method)) {
+                // Aide au développement : la méthode existe mais n'est pas déclarée appelable.
+                if (process.env.NODE_ENV !== 'production' && typeof component[call.method] === 'function' && !isLifecycleHook(call.method))
+                    console.warn(`[wire] ${name} : « ${call.method} » existe mais n'est pas dans static callable — appel refusé.`);
+                throw new WireError(404, `Méthode introuvable : ${call.method}`);
+            }
+            returns.push((await component[call.method](...call.params)) ?? null);
+        }
+        const effects = component._effects;
+        effects.returns = returns;
+        if (awaitsLazyLoad && !lazyLoaded)
+            component._skipRender = true;
+        const rendered = !component._skipRender && !effects.redirect;
+        if (rendered) {
+            effects.html = await this.renderRoot(component, name);
+            effects.partials ??= {};
+        }
+        await component.dehydrate();
+        const { id: _i, name: _n, errors: _e, ...memo } = snapshot.memo;
+        // Après un rendu complet, la liste des enfants est celle qui vient d'être rendue ; sinon elle est conservée.
+        if (rendered)
+            memo.children = Object.keys(component._children).length ? component._children : [];
+        if (lazyLoaded) {
+            memo.lazyLoaded = true;
+            delete memo.lazyIsolated;
+        }
+        return { snapshot: this.snapshot(component, name, memo), effects };
+    }
+    /** Point d'entrée HTTP : corps `{ _token, components: [{ snapshot, updates, calls }] }`. */
+    async handle(body, ctx = null) {
+        const list = body?.components;
+        if (!Array.isArray(list) || list.length === 0)
+            throw new WireError(404, 'Charge utile invalide.');
+        const components = [];
+        // Les composants d'une requête sont traités dans l'ordre : un parent passe ses propriétés réactives aux enfants qui le suivent.
+        await this.requestScope.run({ childProps: new Map() }, async () => {
+            for (const c of list) {
+                if (typeof c?.snapshot !== 'string' || typeof c.updates !== 'object' || !Array.isArray(c.calls))
+                    throw new WireError(404, 'Charge utile invalide.');
+                const { snapshot, effects } = await this.update(JSON.parse(c.snapshot), c.updates ?? {}, c.calls, ctx);
+                components.push({ snapshot: JSON.stringify(snapshot), effects });
+            }
+        });
+        return { components, assets: [] };
+    }
+}

package/lib/uploads.d.ts

@@ -0,0 +1,37 @@
+import type { IncomingMessage } from 'node:http';
+export type TemporaryFile = {
+    id: string;
+    path: string;
+    name: string;
+    type: string;
+    size: number;
+    extension: string;
+};
+export type UploadOptions = {
+    maxFileSize?: number;
+    maxFiles?: number;
+    ttl?: number;
+    urlTtl?: number;
+};
+export declare class UploadStore {
+    readonly dir: string;
+    private key;
+    private maxFileSize;
+    private maxFiles;
+    private ttl;
+    private urlTtl;
+    constructor(dir: string, key: string, options?: UploadOptions);
+    private sign;
+    /** Adresse d'envoi signée, valable quelques minutes. */
+    signedUrl(prefix?: string): string;
+    verifySignature(expires: unknown, signature: unknown): boolean;
+    /** Reçoit un envoi `multipart/form-data` (champ `files[]`) et rend les identifiants temporaires, dans l'ordre. */
+    receive(req: IncomingMessage): Promise<string[]>;
+    /** Fichier temporaire désigné par une valeur d'état (`livewire-file:<id>`) ou un identifiant, s'il existe encore. */
+    resolve(value: unknown): TemporaryFile | null;
+    static isTemporary(value: unknown): boolean;
+    static reference(id: string): string;
+    remove(id: string): void;
+    /** Supprime les fichiers temporaires plus vieux que la durée de conservation. */
+    private sweep;
+}

package/lib/uploads.js

@@ -0,0 +1,149 @@
+// Téléversements temporaires (équivalent de WithFileUploads / TemporaryUploadedFile de Livewire).
+// Le navigateur demande une adresse signée (`_startUpload`), y envoie les fichiers, puis annonce leurs noms temporaires (`_finishUpload`) :
+// la propriété visée reçoit alors `livewire-file:<identifiant>`. Le fichier ne quitte le dossier temporaire que si l'application l'enregistre.
+import busboy from 'busboy';
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { open } from 'node:fs/promises';
+import path from 'node:path';
+const PREFIX = 'livewire-file:';
+const ID = /^[a-f0-9]{32}$/;
+/** Types reconnus à leur signature binaire : le type annoncé par le navigateur n'est jamais cru. */
+const SIGNATURES = [
+    { type: 'image/jpeg', extension: 'jpg', test: (b) => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
+    { type: 'image/png', extension: 'png', test: (b) => b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) },
+    { type: 'image/gif', extension: 'gif', test: (b) => ['GIF87a', 'GIF89a'].includes(b.subarray(0, 6).toString('latin1')) },
+    { type: 'image/webp', extension: 'webp', test: (b) => b.subarray(0, 4).toString('latin1') === 'RIFF' && b.subarray(8, 12).toString('latin1') === 'WEBP' },
+    { type: 'application/pdf', extension: 'pdf', test: (b) => b.subarray(0, 5).toString('latin1') === '%PDF-' },
+    { type: 'application/zip', extension: 'zip', test: (b) => b[0] === 0x50 && b[1] === 0x4b && b[2] === 0x03 && b[3] === 0x04 },
+];
+/** Texte brut : uniquement pour ces extensions, et seulement si le début du fichier ne contient pas d'octet nul. */
+const TEXT = { txt: 'text/plain', csv: 'text/csv', json: 'application/json', md: 'text/markdown' };
+export class UploadStore {
+    dir;
+    key;
+    maxFileSize;
+    maxFiles;
+    ttl;
+    urlTtl;
+    constructor(dir, key, options = {}) {
+        this.dir = dir;
+        this.key = key;
+        this.maxFileSize = options.maxFileSize ?? 12 * 1024 * 1024; // 12 Mo, comme la règle par défaut de Livewire
+        this.maxFiles = options.maxFiles ?? 20;
+        this.ttl = options.ttl ?? 24 * 60 * 60 * 1000;
+        this.urlTtl = options.urlTtl ?? 5 * 60 * 1000;
+        mkdirSync(dir, { recursive: true });
+    }
+    sign(expires) { return createHmac('sha256', this.key).update(`upload:${expires}`).digest('hex'); }
+    /** Adresse d'envoi signée, valable quelques minutes. */
+    signedUrl(prefix = '/livewire') {
+        const expires = Date.now() + this.urlTtl;
+        return `${prefix}/upload-file?expires=${expires}&signature=${this.sign(expires)}`;
+    }
+    verifySignature(expires, signature) {
+        const at = Number(expires);
+        if (!Number.isFinite(at) || at < Date.now())
+            return false;
+        const expected = Buffer.from(this.sign(at)), given = Buffer.from(String(signature ?? ''));
+        return expected.length === given.length && timingSafeEqual(expected, given);
+    }
+    /** Reçoit un envoi `multipart/form-data` (champ `files[]`) et rend les identifiants temporaires, dans l'ordre. */
+    receive(req) {
+        this.sweep();
+        return new Promise((resolve, reject) => {
+            const ids = [];
+            const pending = [];
+            let failure = null;
+            const fail = (message) => { failure ??= Object.assign(new Error(message), { status: 422 }); };
+            let parser;
+            try {
+                parser = busboy({ headers: req.headers, limits: { fileSize: this.maxFileSize, files: this.maxFiles, fields: 5 } });
+            }
+            catch {
+                reject(Object.assign(new Error('Envoi invalide.'), { status: 422 }));
+                return;
+            }
+            parser.on('file', (_field, stream, info) => {
+                const id = randomBytes(16).toString('hex');
+                const target = path.join(this.dir, id);
+                ids.push(id);
+                const out = createWriteStream(target, { flags: 'wx' });
+                stream.on('limit', () => fail('Fichier trop volumineux.'));
+                pending.push(new Promise((done) => { out.on('close', done); out.on('error', () => { fail('Écriture impossible.'); done(); }); }).then(async () => {
+                    if (failure)
+                        return;
+                    const detected = await detect(target, info.filename);
+                    writeFileSync(`${target}.json`, JSON.stringify({ name: path.basename(String(info.filename ?? 'file')).slice(0, 255), type: detected.type, extension: detected.extension }));
+                }));
+                stream.pipe(out);
+            });
+            parser.on('filesLimit', () => fail('Trop de fichiers.'));
+            parser.on('error', () => fail('Envoi invalide.'));
+            parser.on('close', async () => {
+                await Promise.all(pending);
+                if (failure || !ids.length) {
+                    for (const id of ids)
+                        this.remove(id);
+                    reject(failure ?? Object.assign(new Error('Aucun fichier.'), { status: 422 }));
+                    return;
+                }
+                resolve(ids);
+            });
+            req.pipe(parser);
+        });
+    }
+    /** Fichier temporaire désigné par une valeur d'état (`livewire-file:<id>`) ou un identifiant, s'il existe encore. */
+    resolve(value) {
+        const id = typeof value === 'string' ? (value.startsWith(PREFIX) ? value.slice(PREFIX.length) : value) : '';
+        if (!ID.test(id))
+            return null;
+        const file = path.join(this.dir, id);
+        if (!existsSync(file) || !existsSync(`${file}.json`))
+            return null;
+        try {
+            const meta = JSON.parse(readFileSync(`${file}.json`, 'utf8'));
+            return { id, path: file, name: String(meta.name), type: String(meta.type), extension: String(meta.extension), size: statSync(file).size };
+        }
+        catch {
+            return null;
+        }
+    }
+    static isTemporary(value) { return typeof value === 'string' && value.startsWith(PREFIX) && ID.test(value.slice(PREFIX.length)); }
+    static reference(id) { return PREFIX + id; }
+    remove(id) {
+        if (!ID.test(id))
+            return;
+        for (const suffix of ['', '.json'])
+            rmSync(path.join(this.dir, id + suffix), { force: true });
+    }
+    /** Supprime les fichiers temporaires plus vieux que la durée de conservation. */
+    sweep() {
+        const limit = Date.now() - this.ttl;
+        try {
+            for (const name of readdirSync(this.dir)) {
+                const file = path.join(this.dir, name);
+                if (statSync(file).mtimeMs < limit)
+                    rmSync(file, { force: true });
+            }
+        }
+        catch { /* dossier inaccessible : rien à nettoyer */ }
+    }
+}
+async function detect(file, filename) {
+    const handle = await open(file, 'r');
+    try {
+        const { buffer, bytesRead } = await handle.read(Buffer.alloc(512), 0, 512, 0);
+        const head = buffer.subarray(0, bytesRead);
+        const known = SIGNATURES.find((signature) => signature.test(head));
+        if (known)
+            return { type: known.type, extension: known.extension };
+        const extension = path.extname(String(filename ?? '')).slice(1).toLowerCase();
+        if (TEXT[extension] && !head.includes(0))
+            return { type: TEXT[extension], extension };
+        return { type: 'application/octet-stream', extension: 'bin' };
+    }
+    finally {
+        await handle.close();
+    }
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@navette-js/wire",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-beta.1",
+  "description": "Server-side runtime compatible with Livewire 3 for Node.js and Express.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./express": {
+      "types": "./lib/express.d.ts",
+      "default": "./lib/express.js"
+    }
+  },
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib",
+    "vendor",
+    "LICENSE",
+    "README.md",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NavetteJS/navette.git",
+    "directory": "packages/wire"
+  },
+  "homepage": "https://github.com/NavetteJS/navette#readme",
+  "bugs": {
+    "url": "https://github.com/NavetteJS/navette/issues"
+  },
+  "keywords": [
+    "navette",
+    "filament",
+    "admin",
+    "panel",
+    "livewire",
+    "express",
+    "node"
+  ],
+  "dependencies": {
+    "busboy": "^1.6.0",
+    "express": "^5.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  }
+}