@pix3/vite-plugin 0.0.0-stage → 2.0.0-alpha.1

package/dist/server/guard.js

@@ -0,0 +1,165 @@
+import { timingSafeEqual } from 'node:crypto';
+import { BlockList, isIP } from 'node:net';
+import { headerValue, HttpError } from "./http.js";
+const LOOPBACK = new BlockList();
+LOOPBACK.addSubnet('127.0.0.0', 8, 'ipv4');
+LOOPBACK.addAddress('::1', 'ipv6');
+/** A literal IP address (`[…]` brackets dropped), or null for a name. */
+const ipLiteral = (name) => {
+    const bare = name.startsWith('[') && name.endsWith(']') ? name.slice(1, -1) : name;
+    const family = isIP(bare);
+    return family === 4
+        ? { address: bare, family: 'ipv4' }
+        : family === 6
+            ? { address: bare, family: 'ipv6' }
+            : null;
+};
+/** In 127.0.0.0/8 or ::1 (IPv4-mapped included) — by address, never by how a name begins. */
+const isLoopbackIp = (address) => {
+    const ip = ipLiteral(address);
+    return ip !== null && LOOPBACK.check(ip.address, ip.family);
+};
+/** `Host` header → lower-cased name (`[::1]` keeps its brackets), or null when malformed. */
+export const hostNameOf = (hostHeader) => {
+    const host = (hostHeader ?? '').trim().toLowerCase();
+    if (!host)
+        return null;
+    let name;
+    let port;
+    if (host.startsWith('[')) {
+        const close = host.indexOf(']');
+        if (close < 0)
+            return null;
+        name = host.slice(0, close + 1);
+        const rest = host.slice(close + 1);
+        if (rest && !rest.startsWith(':'))
+            return null;
+        port = rest.slice(1);
+    }
+    else {
+        const colon = host.indexOf(':');
+        name = colon < 0 ? host : host.slice(0, colon);
+        port = colon < 0 ? '' : host.slice(colon + 1);
+        if (colon >= 0 && !port)
+            return null;
+    }
+    if (port && !/^\d{1,5}$/.test(port))
+        return null;
+    return name || null;
+};
+/** Vite's rule for one `allowedHosts` entry: exact name, or `.example.com` for it and subdomains. */
+const matchesAllowed = (name, entry) => {
+    const allowed = entry.toLowerCase();
+    if (allowed.startsWith('.'))
+        return name === allowed.slice(1) || name.endsWith(allowed);
+    return name === allowed;
+};
+export const isAllowedHost = (hostHeader, allowed, options = {}) => {
+    const name = hostNameOf(hostHeader);
+    if (name === null)
+        return false;
+    if (name === 'localhost' || isLoopbackIp(name))
+        return true;
+    // An IP literal cannot be a rebinding page's name; the peer check still applies.
+    if (options.allowRemote && ipLiteral(name) !== null)
+        return true;
+    if (allowed === true)
+        return true;
+    return allowed.some(entry => matchesAllowed(name, entry));
+};
+export const isLoopbackAddress = (address) => Boolean(address) && isLoopbackIp(address ?? '');
+/** `Origin` header, or null when absent (a non-browser client). */
+const originOf = (req) => headerValue(req, 'origin');
+/** The origin a page served by this request's `Host` has. */
+const ownOrigins = (req) => {
+    const host = headerValue(req, 'host') ?? '';
+    return [`http://${host}`, `https://${host}`].map(origin => origin.toLowerCase());
+};
+export class RequestGuard {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Every `/__pix3/*` request, reads included. */
+    checkPeer(req) {
+        if (!isAllowedHost(req.headers.host, this.options.allowedHosts(), {
+            allowRemote: this.options.allowRemote,
+        })) {
+            throw new HttpError(403, 'forbidden_host', 'Forbidden host.');
+        }
+        if (!this.options.allowRemote && !isLoopbackAddress(req.socket.remoteAddress)) {
+            throw new HttpError(403, 'forbidden_remote', 'The Pix3 editor only answers this machine. Pass pix3({ allowRemote: true }) to serve it ' +
+                'to other hosts.');
+        }
+    }
+    /** The editor's WebSocket upgrade: no preflight exists, so its `Origin` is the only fence. */
+    checkSocket(req) {
+        this.checkPeer(req);
+        this.checkSameOrigin(req);
+    }
+    checkSameOrigin(req) {
+        const origin = originOf(req);
+        if (origin !== null && !ownOrigins(req).includes(origin.toLowerCase())) {
+            throw new HttpError(403, 'forbidden_origin', 'Origin not allowed.');
+        }
+    }
+    /** Anything that is not GET/HEAD. */
+    checkMutation(req) {
+        if (headerValue(req, 'x-pix3') !== '1') {
+            throw new HttpError(403, 'missing_x_pix3', 'Mutations need the header `X-Pix3: 1`.');
+        }
+        this.checkSameOrigin(req);
+    }
+    /**
+     * Routes only the editor page may use, reads included: the image-generation keys and proxy
+     * (plan §B.1). On top of {@link checkMutation}:
+     * - `Sec-Fetch-Site`, when the browser sends it, is `same-origin`;
+     * - `Referer`, when sent, is a page under `editorPrefix` (`<base>__pix3/`) — the game at `/` is
+     *   the same origin, so the origin alone cannot tell the two apart;
+     * - `X-Pix3-Session` is the token the plugin hands only to a top-level navigation of the editor
+     *   page ({@link editorSessionFor}). A `Referer` is the page's to choose within its origin
+     *   (`fetch(url, {referrer})`), the token is not.
+     * Same-origin isolation has limits a header cannot fix (a service worker the game registers on
+     * `/` sees the editor's traffic); the key itself never reaches any page.
+     */
+    checkEditorOnly(req, editorPrefix, sessionToken) {
+        this.checkMutation(req);
+        const site = headerValue(req, 'sec-fetch-site');
+        if (site !== null && site !== 'same-origin') {
+            throw new HttpError(403, 'forbidden_site', 'Only the editor page may call this route.');
+        }
+        const referer = headerValue(req, 'referer');
+        if (referer !== null) {
+            let path;
+            try {
+                path = new URL(referer).pathname;
+            }
+            catch {
+                path = '';
+            }
+            if (!path.startsWith(editorPrefix)) {
+                throw new HttpError(403, 'forbidden_page', 'Only the editor page may call this route.');
+            }
+        }
+        if (!sameSecret(headerValue(req, 'x-pix3-session') ?? '', sessionToken)) {
+            throw new HttpError(403, 'bad_session', 'Missing or stale editor session: reload the editor tab.');
+        }
+    }
+}
+const sameSecret = (given, expected) => {
+    const a = Buffer.from(given);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+};
+/**
+ * The session token for an editor-page request, or null when this request must not get it: the
+ * page fetched by script (`Sec-Fetch-Dest: empty`) or framed (`iframe`) — the game at `/` can do
+ * both. Browsers send `Sec-Fetch-*` only to secure origins (https, localhost); without them (a
+ * plain-http LAN address under `allowRemote`, a non-browser client) the token is handed out.
+ */
+export const editorSessionFor = (req, token) => {
+    const dest = headerValue(req, 'sec-fetch-dest');
+    if (dest === null)
+        return token;
+    return dest === 'document' ? token : null;
+};

package/dist/server/http.d.ts

@@ -0,0 +1,24 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * HTTP primitives of `/__pix3/api/*` (port of `packages/cli/src/server/http.ts`). Errors are always
+ * `{ error: <code>, message, ...extra }` JSON, the shape the editor's `WorkspaceClient` parses.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly extra: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, extra?: Record<string, unknown>);
+}
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const DEFAULT_MAX_JSON_BYTES: number;
+/** The request body as bytes, refused past `maxBytes`. */
+export declare const readBytes: (req: IncomingMessage, maxBytes?: number) => Promise<Buffer>;
+export declare const readBody: (req: IncomingMessage, maxBytes?: number) => Promise<string>;
+export declare const readJson: (req: IncomingMessage, maxBytes?: number) => Promise<Record<string, unknown>>;
+export declare const headerValue: (req: IncomingMessage, name: string) => string | null;
+export declare const sendJson: (res: ServerResponse, status: number, body: Record<string, unknown>, extraHeaders?: Record<string, string>) => void;
+export declare const errnoCode: (error: unknown) => string | undefined;
+export declare const errorBody: (error: unknown) => {
+    status: number;
+    body: Record<string, unknown>;
+};

package/dist/server/http.js

@@ -0,0 +1,70 @@
+/**
+ * HTTP primitives of `/__pix3/api/*` (port of `packages/cli/src/server/http.ts`). Errors are always
+ * `{ error: <code>, message, ...extra }` JSON, the shape the editor's `WorkspaceClient` parses.
+ */
+export class HttpError extends Error {
+    status;
+    code;
+    extra;
+    constructor(status, code, message, extra = {}) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.extra = extra;
+    }
+}
+export const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+export const DEFAULT_MAX_JSON_BYTES = 1024 * 1024;
+/** The request body as bytes, refused past `maxBytes`. */
+export const readBytes = (req, maxBytes = DEFAULT_MAX_JSON_BYTES) => new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > maxBytes) {
+            reject(new HttpError(413, 'too_large', 'Request body too large.'));
+            req.destroy();
+            return;
+        }
+        chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+});
+export const readBody = async (req, maxBytes = DEFAULT_MAX_JSON_BYTES) => (await readBytes(req, maxBytes)).toString('utf8');
+export const readJson = async (req, maxBytes = DEFAULT_MAX_JSON_BYTES) => {
+    const raw = await readBody(req, maxBytes);
+    if (!raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (isRecord(parsed))
+            return parsed;
+    }
+    catch {
+        // fall through
+    }
+    throw new HttpError(400, 'bad_json', 'Body must be a JSON object.');
+};
+export const headerValue = (req, name) => {
+    const value = req.headers[name];
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.join(', ');
+    return null;
+};
+export const sendJson = (res, status, body, extraHeaders = {}) => {
+    if (res.writableEnded || res.destroyed)
+        return;
+    res.writeHead(status, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'no-store',
+        ...extraHeaders,
+    });
+    res.end(JSON.stringify(body));
+};
+export const errnoCode = (error) => error && typeof error === 'object' && 'code' in error ? String(error.code) : undefined;
+export const errorBody = (error) => error instanceof HttpError
+    ? { status: error.status, body: { error: error.code, message: error.message, ...error.extra } }
+    : { status: 500, body: { error: 'internal', message: 'Internal error.' } };

package/dist/server/image-keys.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Image-generation API keys (plan §B.1 «Ключи генерации картинок»). They live on this machine,
+ * never in the browser: the origin is the dev server's port, which every project and the game's
+ * own code share, so localStorage / IndexedDB is no place for a secret. The plugin's proxy
+ * (`image-proxy.ts`) reads the key per request and adds it to the upstream call.
+ *
+ * Where: `~/.pix3/keys.json` (`PIX3_HOME` overrides `~/.pix3`, as for the CLI), mode 0600 in a
+ * 0700 directory. When `~` cannot be written (a sandbox), `.pix3/local/keys.json` in the project —
+ * `.pix3/` is gitignored by the starter, and the file API refuses `.pix3/local` (`paths.ts`).
+ * The file is read on every request, so an edit by hand applies at once; unknown entries survive
+ * a write.
+ */
+export declare const IMAGE_PROVIDERS: readonly ["gemini", "openai"];
+export type ImageProvider = (typeof IMAGE_PROVIDERS)[number];
+export declare const isImageProvider: (value: unknown) => value is ImageProvider;
+/** What the editor may learn about a key: whether it is there, and its last four characters. */
+export interface KeyStatus {
+    readonly set: boolean;
+    readonly last4?: string;
+}
+export interface KeyStoreOptions {
+    /** `~/.pix3` (or `PIX3_HOME`). */
+    readonly home: string;
+    readonly projectRoot: string;
+}
+export declare const defaultPix3Home: (env?: NodeJS.ProcessEnv) => string;
+export declare const KEYS_FILE = "keys.json";
+export declare const LOCAL_KEYS_PATH = ".pix3/local/keys.json";
+export declare class ImageKeyStore {
+    private readonly homeFile;
+    private readonly localFile;
+    constructor(options: KeyStoreOptions);
+    /** The key for `provider`, or null. The home file wins over the project fallback. */
+    key(provider: ImageProvider): Promise<string | null>;
+    status(): Promise<Record<ImageProvider, KeyStatus>>;
+    /**
+     * Set (or with `null` remove) one provider's key. Written to `~/.pix3/keys.json`, or to the
+     * project's `.pix3/local/keys.json` when the home directory refuses the write. A removal clears
+     * the key from both files, so the fallback cannot bring it back.
+     */
+    set(provider: ImageProvider, key: string | null): Promise<{
+        readonly status: KeyStatus;
+        readonly where: 'home' | 'project';
+    }>;
+    private update;
+}

package/dist/server/image-keys.js

@@ -0,0 +1,118 @@
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { errnoCode } from "./http.js";
+/**
+ * Image-generation API keys (plan §B.1 «Ключи генерации картинок»). They live on this machine,
+ * never in the browser: the origin is the dev server's port, which every project and the game's
+ * own code share, so localStorage / IndexedDB is no place for a secret. The plugin's proxy
+ * (`image-proxy.ts`) reads the key per request and adds it to the upstream call.
+ *
+ * Where: `~/.pix3/keys.json` (`PIX3_HOME` overrides `~/.pix3`, as for the CLI), mode 0600 in a
+ * 0700 directory. When `~` cannot be written (a sandbox), `.pix3/local/keys.json` in the project —
+ * `.pix3/` is gitignored by the starter, and the file API refuses `.pix3/local` (`paths.ts`).
+ * The file is read on every request, so an edit by hand applies at once; unknown entries survive
+ * a write.
+ */
+export const IMAGE_PROVIDERS = ['gemini', 'openai'];
+export const isImageProvider = (value) => typeof value === 'string' && IMAGE_PROVIDERS.includes(value);
+export const defaultPix3Home = (env = process.env) => env.PIX3_HOME || join(homedir(), '.pix3');
+export const KEYS_FILE = 'keys.json';
+export const LOCAL_KEYS_PATH = '.pix3/local/keys.json';
+/** Errors that mean "this directory is not ours to write" — the cue for the project fallback. */
+const UNWRITABLE = new Set(['EACCES', 'EPERM', 'EROFS', 'ENOTDIR']);
+const statusOf = (key) => key ? { set: true, last4: key.length >= 12 ? key.slice(-4) : undefined } : { set: false };
+export class ImageKeyStore {
+    homeFile;
+    localFile;
+    constructor(options) {
+        this.homeFile = join(options.home, KEYS_FILE);
+        this.localFile = join(options.projectRoot, ...LOCAL_KEYS_PATH.split('/'));
+    }
+    /** The key for `provider`, or null. The home file wins over the project fallback. */
+    async key(provider) {
+        const home = await readKeys(this.homeFile);
+        const value = home?.[provider] ?? (await readKeys(this.localFile))?.[provider];
+        return typeof value === 'string' && value.trim() ? value.trim() : null;
+    }
+    async status() {
+        const out = {};
+        for (const provider of IMAGE_PROVIDERS) {
+            out[provider] = statusOf((await this.key(provider)) ?? undefined);
+        }
+        return out;
+    }
+    /**
+     * Set (or with `null` remove) one provider's key. Written to `~/.pix3/keys.json`, or to the
+     * project's `.pix3/local/keys.json` when the home directory refuses the write. A removal clears
+     * the key from both files, so the fallback cannot bring it back.
+     */
+    async set(provider, key) {
+        const value = key?.trim() || null;
+        if (value === null) {
+            await this.update(this.homeFile, provider, null).catch(ignoreUnwritable);
+            await this.update(this.localFile, provider, null).catch(ignoreUnwritable);
+            return { status: { set: false }, where: 'home' };
+        }
+        try {
+            await this.update(this.homeFile, provider, value);
+            // A key moved home must not leave a stale copy behind in the project.
+            await this.update(this.localFile, provider, null).catch(ignoreUnwritable);
+            return { status: statusOf(value), where: 'home' };
+        }
+        catch (error) {
+            if (!UNWRITABLE.has(errnoCode(error) ?? ''))
+                throw error;
+            await this.update(this.localFile, provider, value);
+            return { status: statusOf(value), where: 'project' };
+        }
+    }
+    async update(file, provider, value) {
+        const current = await readKeys(file);
+        if (value === null && !current?.[provider])
+            return;
+        const next = { ...(current ?? {}) };
+        if (value === null)
+            delete next[provider];
+        else
+            next[provider] = value;
+        await writeSecretFile(file, `${JSON.stringify(next, null, 2)}\n`);
+    }
+}
+const ignoreUnwritable = (error) => {
+    const code = errnoCode(error) ?? '';
+    if (!UNWRITABLE.has(code) && code !== 'ENOENT')
+        throw error;
+};
+const readKeys = async (file) => {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        // An inaccessible home store must not hide the project fallback. In particular, macOS
+        // reports ENOTDIR for a file in a parent path, where other systems may report ENOENT.
+        const code = errnoCode(error) ?? '';
+        if (code === 'ENOENT' || UNWRITABLE.has(code))
+            return null;
+        throw error;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        // A hand edit that broke the JSON: no key rather than a crash (the message never quotes it).
+        return null;
+    }
+};
+/** 0600 file in a 0700 directory, replaced atomically (never a moment with looser bits). */
+const writeSecretFile = async (file, text) => {
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tmp, text, { mode: 0o600 });
+    await chmod(tmp, 0o600);
+    await rename(tmp, file);
+};

package/dist/server/image-proxy.d.ts

@@ -0,0 +1,32 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type ImageKeyStore, type ImageProvider } from './image-keys.ts';
+/**
+ * `/__pix3/api/keys` and `/__pix3/api/proxy/{gemini,openai}/…` (plan §B.1 «Ключи генерации
+ * картинок»). The editor's Generate panel calls the providers through here; the plugin adds the
+ * key from {@link ImageKeyStore}, so the page never holds it. Only the two generation endpoints
+ * the panel uses are forwarded — the key is not a general-purpose credential for the page.
+ * Who may call is the router's business (`RequestGuard.checkEditorOnly`).
+ *
+ * The key never leaves this module: responses and logs carry the provider, the path, the status
+ * and the size; an upstream answer that happens to contain the key gets it replaced by `[key]`.
+ */
+export declare const DEFAULT_UPSTREAMS: Readonly<Record<ImageProvider, string>>;
+/** Env overrides of the upstream origins (a local mock in an e2e run). */
+export declare const UPSTREAM_ENV: Readonly<Record<ImageProvider, string>>;
+export interface ImageProxyDeps {
+    readonly keys: ImageKeyStore;
+    readonly upstreams: Readonly<Record<ImageProvider, string>>;
+    readonly log: (line: string) => void;
+    /** For specs; the global `fetch` otherwise. */
+    readonly fetchImpl?: typeof fetch;
+}
+export declare class ImageProxy {
+    private readonly deps;
+    constructor(deps: ImageProxyDeps);
+    /** `GET /__pix3/api/keys` → `{keys: {gemini: {set, last4?}, openai: …}}`. */
+    keyStatus(res: ServerResponse): Promise<void>;
+    /** `PUT /__pix3/api/keys` `{provider, key}` (`key: null` or `''` removes) → the new status only. */
+    setKey(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /** `POST /__pix3/api/proxy/<provider>/<path>` → the upstream's answer, the key added. */
+    forward(req: IncomingMessage, res: ServerResponse, rest: string): Promise<void>;
+}

package/dist/server/image-proxy.js

@@ -0,0 +1,124 @@
+import { HttpError, readBytes, readJson, sendJson } from "./http.js";
+import { isImageProvider } from "./image-keys.js";
+/**
+ * `/__pix3/api/keys` and `/__pix3/api/proxy/{gemini,openai}/…` (plan §B.1 «Ключи генерации
+ * картинок»). The editor's Generate panel calls the providers through here; the plugin adds the
+ * key from {@link ImageKeyStore}, so the page never holds it. Only the two generation endpoints
+ * the panel uses are forwarded — the key is not a general-purpose credential for the page.
+ * Who may call is the router's business (`RequestGuard.checkEditorOnly`).
+ *
+ * The key never leaves this module: responses and logs carry the provider, the path, the status
+ * and the size; an upstream answer that happens to contain the key gets it replaced by `[key]`.
+ */
+export const DEFAULT_UPSTREAMS = {
+    gemini: 'https://generativelanguage.googleapis.com',
+    openai: 'https://api.openai.com',
+};
+/** Env overrides of the upstream origins (a local mock in an e2e run). */
+export const UPSTREAM_ENV = {
+    gemini: 'PIX3_PROXY_GEMINI_URL',
+    openai: 'PIX3_PROXY_OPENAI_URL',
+};
+/** The upstream paths a provider may be called on (relative to its origin, no leading `/`). */
+const ALLOWED_PATHS = {
+    gemini: /^v1(beta)?\/models\/[A-Za-z0-9._-]+:generateContent$/,
+    openai: /^v1\/images\/(generations|edits)$/,
+};
+/** Reference images ride in the body as base64 / multipart. */
+const MAX_REQUEST_BYTES = 64 * 1024 * 1024;
+const UPSTREAM_TIMEOUT_MS = 5 * 60_000;
+const authHeaders = (provider, key) => provider === 'gemini' ? { 'x-goog-api-key': key } : { Authorization: `Bearer ${key}` };
+const KEY_HINT = 'Set it in the Generate panel (the key icon) or in Editor Settings → AI Images.';
+export class ImageProxy {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** `GET /__pix3/api/keys` → `{keys: {gemini: {set, last4?}, openai: …}}`. */
+    async keyStatus(res) {
+        sendJson(res, 200, { keys: await this.deps.keys.status() });
+    }
+    /** `PUT /__pix3/api/keys` `{provider, key}` (`key: null` or `''` removes) → the new status only. */
+    async setKey(req, res) {
+        const body = await readJson(req, 16 * 1024);
+        if (!isImageProvider(body.provider)) {
+            throw new HttpError(400, 'bad_provider', '`provider` must be "gemini" or "openai".');
+        }
+        if (body.key !== null && typeof body.key !== 'string') {
+            throw new HttpError(400, 'bad_key', '`key` must be a string, or null to remove it.');
+        }
+        if (typeof body.key === 'string' && /[\s\0]/.test(body.key.trim())) {
+            throw new HttpError(400, 'bad_key', 'An API key has no spaces or control characters.');
+        }
+        const { status, where } = await this.deps.keys.set(body.provider, body.key);
+        this.deps.log(`image-gen: ${body.provider} key ${status.set ? 'set' : 'removed'} (${where})`);
+        sendJson(res, 200, { provider: body.provider, ...status, where });
+    }
+    /** `POST /__pix3/api/proxy/<provider>/<path>` → the upstream's answer, the key added. */
+    async forward(req, res, rest) {
+        const slash = rest.indexOf('/');
+        const provider = slash < 0 ? rest : rest.slice(0, slash);
+        const path = slash < 0 ? '' : rest.slice(slash + 1);
+        if (!isImageProvider(provider)) {
+            throw new HttpError(404, 'not_found', 'Unknown image provider.');
+        }
+        if (req.method !== 'POST')
+            throw new HttpError(405, 'method', 'POST only.');
+        if (!ALLOWED_PATHS[provider].test(path)) {
+            throw new HttpError(403, 'path_not_allowed', `The ${provider} proxy forwards image generation only.`);
+        }
+        const key = await this.deps.keys.key(provider);
+        if (!key) {
+            req.resume();
+            throw new HttpError(409, 'no_key', `No ${provider} API key on this machine. ${KEY_HINT}`);
+        }
+        const body = await readBytes(req, MAX_REQUEST_BYTES);
+        const headers = authHeaders(provider, key);
+        const contentType = req.headers['content-type'];
+        if (typeof contentType === 'string')
+            headers['Content-Type'] = contentType;
+        const target = `${this.deps.upstreams[provider].replace(/\/+$/, '')}/${path}`;
+        const started = Date.now();
+        const abort = new AbortController();
+        const timer = setTimeout(() => abort.abort(), UPSTREAM_TIMEOUT_MS);
+        // The editor's Cancel (or a closed tab) aborts the upstream call too.
+        res.on('close', () => {
+            if (!res.writableFinished)
+                abort.abort();
+        });
+        let upstream;
+        let bytes;
+        try {
+            upstream = await (this.deps.fetchImpl ?? fetch)(target, {
+                method: 'POST',
+                headers,
+                body,
+                signal: abort.signal,
+            });
+            bytes = Buffer.from(await upstream.arrayBuffer());
+        }
+        catch (error) {
+            const reason = abort.signal.aborted ? 'aborted' : 'unreachable';
+            this.deps.log(`image-gen: ${provider} ${path} → ${reason} (${Date.now() - started} ms)`);
+            throw new HttpError(502, 'upstream_unreachable', `The ${provider} API did not answer (${reason}): ${scrub(describe(error), key)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const scrubbed = scrubBuffer(bytes, key);
+        this.deps.log(`image-gen: ${provider} ${path} → ${upstream.status} (${scrubbed.length} bytes, ` +
+            `${Date.now() - started} ms)`);
+        if (res.writableEnded || res.destroyed)
+            return;
+        res.writeHead(upstream.status, {
+            'Content-Type': upstream.headers.get('content-type') ?? 'application/octet-stream',
+            'Cache-Control': 'no-store',
+        });
+        res.end(scrubbed);
+    }
+}
+const describe = (error) => error instanceof Error
+    ? `${error.message}${error.cause instanceof Error ? ` (${error.cause.message})` : ''}`
+    : String(error);
+const scrub = (text, key) => text.split(key).join('[key]');
+const scrubBuffer = (bytes, key) => bytes.includes(key) ? Buffer.from(scrub(bytes.toString('utf8'), key), 'utf8') : bytes;

package/dist/server/router.d.ts

@@ -0,0 +1,54 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ProjectFiles } from '../files/project-files.ts';
+import { type SyncBarrier } from '../sync/barrier.ts';
+import type { EditorSocket } from './editor-socket.ts';
+import { type RequestGuard } from './guard.ts';
+import type { ImageProxy } from './image-proxy.ts';
+/**
+ * `/__pix3/*` (plan §B.1): the editor page and the file API. Mounted as a pre-middleware, so it
+ * sees `req.url` with Vite's `base` still on it.
+ *
+ * | Route | |
+ * |---|---|
+ * | `GET /__pix3/` | the editor page (raw HTML: no `transformIndexHtml`, no `/@vite/client`) |
+ * | `GET /__pix3/editor.css` | the prebuilt editor's stylesheet |
+ * | `GET /__pix3/api/hello` | project, versions, `seq`, `revision`, current writer |
+ * | `GET\|HEAD\|PUT /__pix3/api/file?path=` | bytes with sha256 ETag; conditional atomic write |
+ * | `GET /__pix3/api/manifest` | full rescan + every file with its hash |
+ * | `POST /__pix3/api/hash` | `{paths}` → `{hashes}` |
+ * | `POST /__pix3/api/{mkdir,delete,move}` | |
+ * | `POST /__pix3/api/changeset` | `{files: [{path, text\|base64, ifMatch?, createOnly?}]}` as one transaction (§C.4) |
+ * | `GET /__pix3/api/history?path=` | `{entries}` of the version journal, newest first |
+ * | `GET\|HEAD /__pix3/api/history/version?path=&id=` | one journaled version's raw bytes |
+ * | `POST /__pix3/api/history/record` | `{path, text, author: 'rejected-draft', note?}` → the entry (any tab) |
+ * | `POST /__pix3/api/history/restore` | `{path, id}` (+ `If-Match`) → written back, seen as `external` |
+ * | `POST /__pix3/api/handover/claim` | `{writerId}` → the disk the new writer starts from |
+ * | `POST /__pix3/api/sync` | the barrier (§B.3) |
+ * | `POST /__pix3/api/flush` | step 0 of the barrier on its own (`vite build`, `pix3 check`/`smoke` before they read the disk) |
+ * | `GET\|PUT /__pix3/api/keys` | image-gen key status `{set, last4?}` per provider / set or remove one (never echoed) |
+ * | `POST /__pix3/api/proxy/{gemini,openai}/…` | the provider's generation endpoint, the key added server-side |
+ *
+ * `keys` and `proxy` answer the editor page only (`RequestGuard.checkEditorOnly`: the page's
+ * session token, its `Referer`, `Sec-Fetch-Site`). No URL with a `.pix3` segment is served at all —
+ * the project's `.pix3/` holds `local/keys.json` when `~` is not writable.
+ */
+export interface RouterDeps {
+    readonly base: string;
+    readonly guard: RequestGuard;
+    readonly files: ProjectFiles;
+    readonly socket: EditorSocket;
+    readonly barrier: SyncBarrier;
+    readonly hello: () => Record<string, unknown>;
+    /** `session`: the token for this request's page, or null (`editorSessionFor`). */
+    readonly editorPage: (session: string | null) => {
+        status: number;
+        html: string;
+    };
+    /** Handed to the editor page on a top-level navigation; required by `keys` and `proxy`. */
+    readonly sessionToken: string;
+    readonly imageProxy: ImageProxy;
+    /** The prebuilt editor's stylesheet (`@pix3/editor-core/dist/editor.css`), or null. */
+    readonly editorCss: () => Buffer | null;
+    readonly log: (line: string) => void;
+}
+export declare const createRouter: (deps: RouterDeps) => (req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void) => void;