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

package/lib/index.js

@@ -0,0 +1,417 @@
+// @navette-js/wire — server runtime for stateful components, speaking the Livewire client protocol (livewire.js 4.4.8).
+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; }
+}
+/** Base class of a component. Every own enumerable property not starting with `_` is public state. */
+export class Component {
+    _id = '';
+    _effects = {};
+    _skipRender = false;
+    _errors = {};
+    /** Context of the current HTTP request (request, response, panel…), supplied by the integration. */
+    _ctx = null;
+    /** Runtime and originating request, used to mount child components while rendering. */
+    _runtime = null;
+    _request = {};
+    /** Children rendered during this request, and children already in the browser: key → [tag, id]. */
+    _children = {};
+    _previousChildren = {};
+    /** HTML shown until a lazy component is loaded; must have a single root. */
+    placeholder() { return '<div></div>'; }
+    /**
+     * Mounts a child component and returns its HTML, to insert into the parent's render.
+     * If the browser already has this child (same key), only a stub is rendered and the client keeps the child as is.
+     * `lazy`: the child shows its `placeholder()` and loads once it becomes visible.
+     */
+    async mountChild(name, params = {}, key, options = {}) {
+        if (!this._runtime)
+            throw new Error('mountChild(): component is not attached to a runtime.');
+        const previous = this._previousChildren[key];
+        if (previous) {
+            this._children[key] = previous;
+            // Reactive props: the child, updated later in the same request, picks these values up.
+            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; }
+    /** Dispatches a browser event; with `self`, only this component receives it. */
+    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; }
+    /** Partial render: only the `wire:partial="<name>"` fragment is sent back (effects.partials), the component is not re-rendered. */
+    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']);
+// Only property hooks (updatingFoo / updatedFoo) are reserved by prefix: `mountAction`, for example, is an ordinary public method.
+const isLifecycleHook = (m) => LIFECYCLE.has(m) || /^(updating|updated)[A-Z]/.test(m) || m.startsWith('_');
+/**
+ * Methods callable from the browser: only those the class (or a parent class) lists in `static callable`.
+ * TypeScript erases `protected` and `private` at runtime: without this allowlist, any internal method could be called by a
+ * forged request and its return value sent back to the browser.
+ */
+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('_'));
+}
+// Wire format: arrays and objects travel as [value, { s: 'arr' }] tuples.
+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;');
+/** Adds attributes to the root element of an HTML fragment. */
+export function insertAttributesIntoHtmlRoot(html, attributes) {
+    const m = /^\s*<([a-zA-Z0-9-]+)/.exec(html);
+    if (!m)
+        throw new WireError(500, 'A component render must start with a root element.');
+    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;
+}
+/** 20-character alphanumeric id (used in HTML ids and CSS selectors, so no symbols). */
+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());
+/** False if the value contains, at any depth, a temporary file reference that does not point to a received file. */
+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));
+}
+/** Reactive props of a component (`static reactive`): set by the parent, never by the browser. */
+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; }
+    /** Params passed by a parent to its existing children during the current request: child id → params. */
+    requestScope = new AsyncLocalStorage();
+    passPropsToChild(childId, params) { this.requestScope.getStore()?.childProps.set(childId, params); }
+    names = new Map();
+    register(name, cls) { this.registry.set(name, cls); if (!this.names.has(cls))
+        this.names.set(cls, name); cls.componentName = name; return this; }
+    /** Name under which this runtime registered a class. A class shared by several runtimes (one per panel) keeps one name per runtime. */
+    nameOf(cls) { return this.names.get(cls) ?? cls.componentName ?? ''; }
+    make(name) {
+        const cls = this.registry.get(name);
+        if (!cls)
+            throw new WireError(404, `Unknown component: ${name}`);
+        return new cls();
+    }
+    checksum(snapshot) {
+        const { children: _children, ...memo } = snapshot.memo; // the client may rewrite `children`, so it is not signed
+        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) };
+    }
+    /** Signed mount params of a lazy component, in a `__mountParamsContainer`: the browser sends them back unchanged to `__lazyLoad`. */
+    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, 'Unreadable mount params.');
+        }
+        if (!container || typeof container.data !== 'object' || typeof container.memo !== 'object' || typeof container.checksum !== 'string')
+            throw new WireError(404, 'Invalid mount params.');
+        const expected = Buffer.from(this.checksum(container)), given = Buffer.from(container.checksum);
+        if (expected.length !== given.length || !timingSafeEqual(expected, given))
+            throw new WireError(419, 'Invalid mount params checksum.');
+        // Params signed for one component are not valid for another.
+        if (container.memo.name !== '__mountParamsContainer' || container.data.forComponent !== name)
+            throw new WireError(403, 'Mount params were issued for another component.');
+        return (hydrateValue(container.data.forMount) ?? {});
+    }
+    /** A mount param named like a public property is copied into it. */
+    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 });
+    }
+    /**
+     * Initial render: HTML with wire:snapshot and wire:effects on the root.
+     * The memo only carries `lazyLoaded` / `lazyIsolated` for lazy components: their mere presence makes the client ignore events.
+     */
+    async mount(name, params = {}, request = {}) {
+        return (await this.mountWithInstance(name, params, request)).html;
+    }
+    /** Like mount(), but also returns the mounted instance (to read its title, for example). */
+    async mountWithInstance(name, params = {}, request = {}) {
+        const component = this.make(name);
+        component._ctx = request.ctx ?? null;
+        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) {
+            // Lazy component: `mount()` and rendering wait for the browser's `__lazyLoad` call.
+            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;
+        // Event listeners: the client calls `__dispatch(event, params)` when one fires.
+        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 };
+    }
+    /** Component update request: hydrate, apply updates, run calls, render, dehydrate. */
+    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, 'Invalid snapshot.');
+        const expected = Buffer.from(this.checksum(snapshot)), given = Buffer.from(snapshot.checksum);
+        if (expected.length !== given.length || !timingSafeEqual(expected, given))
+            throw new WireError(419, 'Invalid snapshot checksum.');
+        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` is not covered by the checksum (the client maintains it): only well-formed entries are kept.
+        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);
+        // Reactive props only come from the parent, rendered earlier in the same request.
+        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, `Public property not found: ${prop}`);
+            if (cls.locked?.includes(prop))
+                throw new WireError(403, `Locked property: ${prop}`);
+            if (reactive.has(prop))
+                throw new WireError(403, `Reactive property, set by the parent component: ${prop}`);
+            // A segment such as `__proto__` would write into the prototype shared by every object on the server.
+            if (segments.some((segment) => segment === '__proto__' || segment === 'constructor' || segment === 'prototype'))
+                throw new WireError(403, `State path rejected: ${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)) {
+            // A temporary file reference sent by the browser must point to a file that was actually received.
+            if (!uploadReferencesAreValid(value, this.uploads))
+                throw new WireError(403, `File reference rejected: ${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, 'Invalid call.');
+            // Magic actions are no-ops on the server: their values travel in `updates`.
+            if (MAGIC_ACTIONS.has(call.method)) {
+                returns.push(null);
+                continue;
+            }
+            if (call.method === '__lazyLoad') {
+                if (!awaitsLazyLoad || lazyLoaded)
+                    throw new WireError(404, 'This component is not waiting for a lazy load.');
+                const params = this.decodeMountParams(name, call.params[0]);
+                this.assignMatchingProperties(component, params);
+                await component.mount(params);
+                lazyLoaded = true;
+                returns.push(null);
+                continue;
+            }
+            // Until it is loaded, a lazy component has not been mounted: nothing else is callable.
+            if (awaitsLazyLoad && !lazyLoaded)
+                throw new WireError(404, 'Component not loaded yet.');
+            // File uploads: the target is a state path, subject to the same guards as an update.
+            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, 'Uploads are not available.');
+                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, 'Temporary file not found.');
+                    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, `No listener for event: ${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)) {
+                // Development hint: the method exists but is not declared callable.
+                if (process.env.NODE_ENV !== 'production' && typeof component[call.method] === 'function' && !isLifecycleHook(call.method))
+                    console.warn(`[wire] ${name}: "${call.method}" exists but is not listed in static callable; call rejected.`);
+                throw new WireError(404, `Method not found: ${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;
+        // After a full render, the children list is the one just rendered; otherwise it is kept.
+        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 };
+    }
+    /** HTTP entry point; body: `{ _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, 'Invalid payload.');
+        const components = [];
+        // Components are processed in order so a parent can pass its reactive props to the children that follow it.
+        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, 'Invalid payload.');
+                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;
+    /** Signed upload URL, valid for a few minutes (`urlTtl`). */
+    signedUrl(prefix?: string): string;
+    verifySignature(expires: unknown, signature: unknown): boolean;
+    /** Receives a `multipart/form-data` upload (`files[]` field) and returns the temporary ids, in order. */
+    receive(req: IncomingMessage): Promise<string[]>;
+    /** Temporary file referenced by a state value (`livewire-file:<id>`) or a bare id, if it still exists. */
+    resolve(value: unknown): TemporaryFile | null;
+    static isTemporary(value: unknown): boolean;
+    static reference(id: string): string;
+    remove(id: string): void;
+    /** Deletes temporary files older than the retention time (`ttl`). */
+    private sweep;
+}

package/lib/uploads.js

@@ -0,0 +1,148 @@
+// Temporary uploads. The browser asks for a signed URL (`_startUpload`), posts the files to it, then reports their temporary ids
+// (`_finishUpload`): the target property then holds `livewire-file:<id>`. A file only leaves the temporary directory if the app stores it.
+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 detected from their magic bytes: the type announced by the browser is never trusted. */
+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 },
+];
+/** Plain text: only for these extensions, and only if the start of the file contains no null byte. */
+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 MB
+        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'); }
+    /** Signed upload URL, valid for a few minutes (`urlTtl`). */
+    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);
+    }
+    /** Receives a `multipart/form-data` upload (`files[]` field) and returns the temporary ids, in order. */
+    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('Invalid upload.'), { 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('File too large.'));
+                pending.push(new Promise((done) => { out.on('close', done); out.on('error', () => { fail('Could not write the file.'); 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('Too many files.'));
+            parser.on('error', () => fail('Invalid upload.'));
+            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('No file.'), { status: 422 }));
+                    return;
+                }
+                resolve(ids);
+            });
+            req.pipe(parser);
+        });
+    }
+    /** Temporary file referenced by a state value (`livewire-file:<id>`) or a bare id, if it still exists. */
+    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 });
+    }
+    /** Deletes temporary files older than the retention time (`ttl`). */
+    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 { /* directory unreadable: nothing to sweep */ }
+    }
+}
+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,53 @@
 {
   "name": "@navette-js/wire",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-beta.2",
+  "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",
+    "admin",
+    "panel",
+    "livewire",
+    "express",
+    "node"
+  ],
+  "dependencies": {
+    "busboy": "^1.6.0",
+    "express": "^5.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  }
+}