orionplace-nuxt 0.1.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,170 @@
+# orionplace-nuxt
+
+Set up a Nuxt 4 storefront for your personal Orionplace marketplace API.
+The package includes a Nuxt module, a setup CLI, and commented server source
+that is copied into your project alongside an integration README.
+
+Requires Node.js 22.12+ and a Node server deployment. Static-only and edge
+hosting are not supported by this filesystem-based integration.
+
+## New project
+
+Your personal backend domain is already provided in your account at
+[orionmarket.place](https://orionmarket.place). You can change it there.
+Use that domain below and the public domain of your own storefront.
+
+```bash
+mkdir my-marketplace
+cd my-marketplace
+npm install orionplace-nuxt
+npx orionplace-nuxt set backend your-project.orionplace.app
+npx orionplace-nuxt add frontend shop.example.com
+npm install
+npm run dev
+```
+
+The first setup command creates the Nuxt configuration and app if needed.
+The final `npm install` installs the dependencies added to `package.json`.
+The backend command accepts either a hostname or its full HTTPS `/api` URL.
+The frontend command accepts a public hostname or its root HTTPS URL.
+
+You can also scaffold before installing:
+
+```bash
+npx orionplace-nuxt init my-marketplace
+cd my-marketplace
+npm install
+npx orionplace-nuxt set backend your-project.orionplace.app
+npx orionplace-nuxt add frontend shop.example.com
+npm run dev
+```
+
+## Existing Nuxt 4 project
+
+```bash
+npm install orionplace-nuxt
+npx orionplace-nuxt init --dry-run
+npx orionplace-nuxt set backend your-project.orionplace.app
+npx orionplace-nuxt add frontend shop.example.com
+```
+
+The CLI preserves unrelated Nuxt settings, scripts, and environment variables.
+It supports a standard root `nuxt.config.ts`, `.js`, or `.mjs` with a literal
+configuration object and module array. Resolve existing `/api` proxy or
+catch-all conflicts before setup. Custom source/server directories, Nuxt layers,
+and dynamic configuration expressions require manual integration.
+
+No install or postinstall hook changes your application. Only explicitly running
+the CLI writes files. Use `--cwd <directory>` to select a project and `--dry-run`
+to inspect planned changes without writing them.
+
+## Commands
+
+```bash
+npx orionplace-nuxt init [directory]
+npx orionplace-nuxt set backend your-project.orionplace.app
+npx orionplace-nuxt add frontend shop.example.com
+npx orionplace-nuxt add frontend www.shop.example.com
+npx orionplace-nuxt remove frontend www.shop.example.com
+npx orionplace-nuxt set frontend shop.example.com
+npx orionplace-nuxt --help
+```
+
+Either domain command can run first. Both settings are needed for a usable mapping.
+After setup, these npm script aliases are also available:
+
+```bash
+npm run orionplace:backend -- your-project.orionplace.app
+npm run orionplace:add-frontend -- shop.example.com
+npm run orionplace:remove-frontend -- www.shop.example.com
+```
+
+`npm set` belongs to npm's own configuration system; use the commands above.
+These commands configure local integration files. They do not provision a backend,
+change your account, create DNS records, configure TLS, or deploy a VPS.
+
+## Generated files
+
+| Path | Purpose |
+| --- | --- |
+| `nuxt.config.ts` | Registers the module; an existing supported config keeps its filename. |
+| `orionplace/runtime/marketplace.mjs` | Commented domain lookup and HTTP transport. |
+| `orionplace/runtime/api.mjs` | Nitro handler registered for `/api/**`. |
+| `orionplace/runtime/domain.mjs` | Domain resolution middleware. |
+| `orionplace/README.md` | Your settings, API examples, file explanations, verification and VPS deployment. |
+| `orionplace/settings.json` | Domain values selected by the CLI. |
+| `orionplace/.generated.json` | File hashes used to preserve your edits on subsequent setup. |
+| `sitemaps/shop.example.com.cfg` | One line: `https://your-project.orionplace.app/api`. |
+| `.env` | `MIMIC_FRONT_DOMAIN="shop.example.com"` for localhost. |
+
+The module executes the generated local runtime files. You can read and customize
+them. Later setup runs preserve edited runtime files and the project README,
+reporting which files were preserved. Unchanged generated files can be refreshed
+by running `init` after upgrading the package. A manually edited domain file is
+never silently overwritten. Keep the hash manifest in version control.
+
+## Multiple frontend domains
+
+Each frontend gets its own `sitemaps/<domain>.cfg`. `add frontend` preserves other
+domains and can be repeated safely. `set backend` updates every CLI-managed mapping
+to the new personal API; it refuses to overwrite a manually edited mapping.
+
+The first added frontend becomes `MIMIC_FRONT_DOMAIN` in `.env`. Further additions
+preserve that local development choice. `set frontend <domain>` adds the domain
+if needed and selects it for MIMIC; it does not remove other domains.
+
+`remove frontend <domain>` removes that domain from the list and deletes only its
+unchanged generated `.cfg`. Removing the MIMIC domain selects the first remaining
+domain. Removing the last one clears MIMIC. Unknown or edited mappings cause a
+clear error without changing files. Unrelated configurations remain untouched.
+
+Restart development after domain changes to refresh Vite's allowed hosts and
+Nuxt's environment. Production reloads mapping files on each API request; reload
+the process environment when changing MIMIC. Configure DNS, TLS, and the hosting
+proxy for each frontend separately.
+
+Existing 0.1.0 setup state is migrated automatically, including other domain
+mappings recorded in its generated-file manifest.
+
+## Runtime behavior
+
+The hosting proxy must overwrite `X-Front-Domain`, `X-Forwarded-Host`, and `Host`.
+The gateway selects the first valid public domain in that order, with the request
+URL hostname as another fallback. On localhost it uses `MIMIC_FRONT_DOMAIN`.
+An unknown public domain returns `503`; it never uses another domain's mapping.
+
+The corresponding `.cfg` is read on every request. Backend URLs must use HTTPS,
+end in `/api`, and belong to `*.orionplace.app`. API methods, query strings, bodies,
+authorization and cookies are forwarded. Backend statuses are retained and cookie
+Domain attributes are removed to bind cookies to the storefront. Gateway responses
+use `Cache-Control: no-store`. Network failures return `502`.
+
+Browser requests use `/api/...`. For SSR, use Nuxt's `useRequestFetch()` to pass
+the current request's domain and authentication to the same gateway. See the
+project README for examples and cookie handling.
+
+The module sets private `runtimeConfig.mimicFrontDomain`, adds domain `Vary`
+headers, extends Vite's allowed hosts from `.cfg` filenames, and defaults Nitro
+to `node-server`. It does not set a fixed public site URL or generate canonical
+links for your pages; use the resolved request domain for your own SEO metadata.
+
+Deploy `sitemaps` with the production server, or set an absolute `SITEMAPS_DIR`.
+The production process reads `MIMIC_FRONT_DOMAIN` without rebuilding. Run the
+server from the project root or explicitly point it at the configuration directory.
+
+## Documentation
+
+- [Create a Nuxt frontend](https://orionmarket.place/sandbox/new-project/nuxt)
+- [Connect your personal backend](https://orionmarket.place/sandbox/backend-domain/nuxt)
+- [Marketplace API documentation](https://orionmarket.place/sandbox/)
+
+## Development
+
+```bash
+npm install
+npm test
+npm pack --dry-run
+```
+
+The published tarball includes only the CLI, module, runtime source, README,
+license, and package metadata.

package/bin/orionplace-nuxt.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { setupProject } from '../src/setup.mjs';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+
+const help = `Orionplace Nuxt setup
+
+  npx orionplace-nuxt init [directory]
+  npx orionplace-nuxt set backend <personal-backend.orionplace.app>
+  npx orionplace-nuxt add frontend <shop.example.com>
+  npx orionplace-nuxt remove frontend <shop.example.com>
+  npx orionplace-nuxt set frontend <shop.example.com>
+
+Options: --cwd <directory>  --dry-run  --help  --version
+
+Set backend or add frontend also initializes the integration; either can come first.
+Add frontend keeps other domains and the current MIMIC domain. Set frontend selects MIMIC.
+Set backend updates every managed frontend mapping. Remove frontend deletes only that mapping.
+After creating a new project, run npm install and npm run dev in that directory.
+Documentation and editable server source are generated in orionplace/.`;
+try {
+  const argv = process.argv.slice(2);
+  if (!argv.length || argv.includes('--help') || argv.includes('-h')) {
+    console.log(help);
+  } else if (argv.includes('--version')) {
+    console.log(JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version);
+  } else {
+    const positional = [];
+    let cwd = process.cwd();
+    let dryRun = false;
+    for (let index = 0; index < argv.length; index++) {
+      if (argv[index] === '--dry-run') dryRun = true;
+      else if (argv[index] === '--cwd') {
+        if (!argv[index + 1]) throw new Error('--cwd needs a directory');
+        cwd = resolve(argv[++index]);
+      } else if (argv[index].startsWith('--')) throw new Error(`Unknown option: ${argv[index]}`);
+      else positional.push(argv[index]);
+    }
+    const [command, target] = positional;
+    let result;
+    if (command === 'init' && positional.length <= 2) {
+      result = await setupProject({ cwd: target ? resolve(cwd, target) : cwd, dryRun });
+    } else if (((command === 'set' && ['backend', 'frontend'].includes(target)) ||
+        (['add', 'remove'].includes(command) && target === 'frontend')) && positional.length <= 3) {
+      let value = positional[2];
+      if (!value && process.stdin.isTTY) {
+        const prompt = createInterface({ input: process.stdin, output: process.stdout });
+        try { value = await prompt.question(`${target === 'backend' ? 'Personal backend API' : 'Public frontend domain'}: `); }
+        finally { prompt.close(); }
+      }
+      if (!value) throw new Error(`Provide the ${target} domain. See --help.`);
+      result = await setupProject({ cwd, action: command, field: target, value, dryRun });
+    } else throw new Error('Unknown command. See --help.');
+    console.log(`${dryRun ? 'Planned' : 'Updated'} ${result.root}`);
+    for (const path of result.changed) console.log(`  ${result.removed.includes(path) ? 'Remove: ' : ''}${path}`);
+    for (const path of result.preserved) console.log(`  Preserved your edits: ${path}`);
+    console.log(result.settings.backend && result.settings.frontend
+      ? `Ready: ${result.settings.frontends.join(', ')} -> ${result.settings.backend}\nLocal MIMIC: ${result.settings.frontend}`
+      : `Next: ${result.settings.backend ? 'add frontend' : 'set backend'} to complete the domain mapping.`);
+    if (result.changed.some(path => path.endsWith('.cfg') || path === '.env')) console.log('Restart a running development server to refresh allowed hosts and MIMIC. Reload your production environment when changing MIMIC.');
+    if (result.isNewNuxt) console.log('Run npm install in the project, then npm run dev.');
+    console.log('Project documentation: orionplace/README.md');
+  }
+} catch (error) {
+  console.error(`Orionplace: ${error.message}`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "orionplace-nuxt",
+  "version": "0.1.1",
+  "description": "Nuxt integration and setup CLI for your Orionplace personal marketplace backend.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Orionplace",
+  "homepage": "https://orionmarket.place/sandbox/backend-domain/nuxt",
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "orionplace",
+    "marketplace"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "orionplace-nuxt": "./bin/orionplace-nuxt.mjs"
+  },
+  "main": "./src/module.mjs",
+  "types": "./src/module.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/module.d.ts",
+      "import": "./src/module.mjs"
+    },
+    "./runtime": "./runtime/marketplace.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "runtime",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.0.0"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.5.0",
+    "h3": "^1.15.4",
+    "magicast": "^0.5.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/runtime/api.mjs

@@ -0,0 +1,11 @@
+// All browser and SSR /api requests use this gateway.
+import { defineEventHandler, toWebRequest, sendWebResponse } from 'h3';
+import { useRuntimeConfig } from '#imports';
+import { forwardMarketplace } from './marketplace.mjs';
+
+export default defineEventHandler(async (event) => {
+  const response = await forwardMarketplace(toWebRequest(event), {
+    mimicFrontDomain: process.env.MIMIC_FRONT_DOMAIN ?? useRuntimeConfig(event).mimicFrontDomain,
+  });
+  return sendWebResponse(event, response);
+});

package/runtime/domain.mjs

@@ -0,0 +1,9 @@
+// Other server code can read event.context.marketplaceDomain for canonical URLs.
+import { defineEventHandler, toWebRequest } from 'h3';
+import { useRuntimeConfig } from '#imports';
+import { resolveFrontDomain } from './marketplace.mjs';
+
+export default defineEventHandler((event) => {
+  event.context.marketplaceDomain = resolveFrontDomain(toWebRequest(event),
+    process.env.MIMIC_FRONT_DOMAIN ?? useRuntimeConfig(event).mimicFrontDomain);
+});

package/runtime/marketplace.mjs

@@ -0,0 +1,211 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { isIP } from 'node:net';
+
+const environment = process.env;
+
+const hostnamePattern =
+	/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+/** @param {unknown} value */
+export function normalizeFrontDomain(value) {
+	if (typeof value !== 'string') return null;
+	const domain = value.split(',')[0].trim().toLowerCase().replace(/\.$/, '');
+	return hostnamePattern.test(domain) && !isIP(domain) ? domain : null;
+}
+
+/** @param {Request} request @param {string} mimic */
+export function resolveFrontDomain(
+	request,
+	mimic = environment.MIMIC_FRONT_DOMAIN || '',
+) {
+	// The hosting proxy must overwrite these headers. Public hosts win over MIMIC.
+	for (const candidate of [
+		request.headers.get('x-front-domain'),
+		request.headers.get('x-forwarded-host'),
+		request.headers.get('host'),
+		new URL(request.url).hostname,
+	]) {
+		const domain = normalizeFrontDomain(candidate);
+		if (domain) return domain;
+	}
+	return normalizeFrontDomain(mimic);
+}
+
+/** @param {Request} request @param {{mimicFrontDomain?: string}} configuration */
+export async function readMarketplace(request, configuration = {}) {
+	const domain = resolveFrontDomain(request, configuration.mimicFrontDomain);
+	if (!domain) throw new Error('Invalid storefront domain');
+
+	const directory = environment.SITEMAPS_DIR || resolve('sitemaps');
+	const source = await readFile(resolve(directory, `${domain}.cfg`), 'utf8');
+	const lines = source
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter((line) => line && !line.startsWith('#'));
+	if (lines.length !== 1) throw new Error('Expected one API URL');
+	const value = lines[0];
+	const api = new URL(value.includes('://') ? value : `https://${value}`);
+	api.pathname = api.pathname.replace(/\/+$/, '');
+	if (
+		api.protocol !== 'https:' ||
+		!hostnamePattern.test(api.hostname) ||
+		!api.hostname.endsWith('.orionplace.app') ||
+		isIP(api.hostname) ||
+		api.port ||
+		api.username ||
+		api.password ||
+		api.search ||
+		api.hash ||
+		api.pathname !== '/api'
+	) {
+		throw new Error('Expected https://<project>.orionplace.app/api');
+	}
+	return { domain, api };
+}
+
+/** @param {number} status @param {string} message */
+function failure(status, message) {
+	return Response.json(
+		{ error: message },
+		{
+			status,
+			headers: {
+				'Cache-Control': 'no-store',
+				'Vary': 'Host, X-Forwarded-Host, X-Front-Domain',
+			},
+		},
+	);
+}
+
+/** @param {Request} request @param {{mimicFrontDomain?: string}} configuration */
+export async function forwardMarketplace(request, configuration = {}) {
+	let tenant;
+	try {
+		tenant = await readMarketplace(request, configuration);
+	} catch {
+		return failure(
+			503,
+			'Storefront domain configuration is missing or invalid',
+		);
+	}
+
+	const incoming = new URL(request.url);
+	if (!incoming.pathname.startsWith('/api/'))
+		return failure(404, 'Unknown API path');
+	// Prevent encoded separators or traversal from escaping the /api namespace.
+	let path;
+	try {
+		path = decodeURIComponent(incoming.pathname);
+	} catch {
+		return failure(400, 'Invalid API path');
+	}
+	if (
+		path.includes('\\') ||
+		/%(?:2e|2f|5c)/i.test(path) ||
+		path.split('/').some((part) => part === '.' || part === '..')
+	) {
+		return failure(400, 'Invalid API path');
+	}
+	const target = new URL(
+		incoming.pathname + incoming.search,
+		tenant.api.origin,
+	);
+	if (!target.pathname.startsWith('/api/'))
+		return failure(400, 'Invalid API path');
+
+	const origin = request.headers.get('origin');
+	const publicHost = request.headers.get('host') || incoming.host;
+	const originHosts = [publicHost, tenant.domain];
+	if (!['GET', 'HEAD', 'OPTIONS'].includes(request.method)) {
+		try {
+			if (
+				request.headers.get('sec-fetch-site') === 'cross-site' ||
+				(origin && !originHosts.includes(new URL(origin).host))
+			) {
+				return failure(403, 'Cross-site API request rejected');
+			}
+		} catch {
+			return failure(403, 'Invalid Origin');
+		}
+	}
+
+	// An allowlist excludes hop-by-hop and client-supplied routing headers.
+	const headers = new Headers();
+	for (const name of [
+		'accept',
+		'content-type',
+		'authorization',
+		'cookie',
+		'origin',
+		'referer',
+		'x-csrftoken',
+		'accept-language',
+		'user-agent',
+		'x-tz',
+	]) {
+		const value = request.headers.get(name);
+		if (value) headers.set(name, value);
+	}
+	headers.set('X-Front-Domain', tenant.domain);
+	headers.set('Accept-Encoding', 'identity');
+	const clientIp =
+		request.headers.get('x-init-ip') ||
+		request.headers.get('x-real-ip') ||
+		request.headers.get('x-forwarded-for')?.split(',')[0]?.trim();
+	if (clientIp) headers.set('X-Init-Ip', clientIp);
+	/** @type {RequestInit & { duplex: 'half' }} */
+	const options = {
+		method: request.method,
+		headers,
+		redirect: 'manual',
+		cache: 'no-store',
+		signal: AbortSignal.any([request.signal, AbortSignal.timeout(30_000)]),
+		duplex: 'half',
+	};
+	if (!['GET', 'HEAD'].includes(request.method)) options.body = request.body;
+
+	let upstream;
+	try {
+		upstream = await fetch(target, options);
+	} catch {
+		return failure(502, 'Marketplace backend is unavailable');
+	}
+
+	const responseHeaders = new Headers();
+	for (const name of [
+		'content-type',
+		'content-disposition',
+		'www-authenticate',
+		'retry-after',
+		'allow',
+	]) {
+		const value = upstream.headers.get(name);
+		if (value) responseHeaders.set(name, value);
+	}
+	// Keep each cookie separate; remove the backend Domain attribute only.
+	for (const cookie of upstream.headers.getSetCookie()) {
+		responseHeaders.append(
+			'Set-Cookie',
+			cookie.replace(/;\s*Domain=[^;]*/gi, ''),
+		);
+	}
+	const location = upstream.headers.get('location');
+	if (location) {
+		const destination = new URL(location, target);
+		responseHeaders.set(
+			'Location',
+			destination.origin === tenant.api.origin
+				? destination.pathname + destination.search + destination.hash
+				: destination.href,
+		);
+	}
+	responseHeaders.set('Cache-Control', 'no-store');
+	responseHeaders.set('Vary', 'Host, X-Forwarded-Host, X-Front-Domain');
+	// fetch decodes compressed bodies: do not reuse upstream Content-Length/Encoding.
+	return new Response(upstream.body, {
+		status: upstream.status,
+		statusText: upstream.statusText,
+		headers: responseHeaders,
+	});
+}

package/src/module.d.ts

@@ -0,0 +1,3 @@
+import type { NuxtModule } from '@nuxt/schema';
+declare const module: NuxtModule<Record<string, never>>;
+export default module;

package/src/module.mjs

@@ -0,0 +1,49 @@
+import { defineNuxtModule, addServerHandler } from '@nuxt/kit';
+import { existsSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { normalizeFrontDomain } from '../runtime/marketplace.mjs';
+
+export default defineNuxtModule({
+  meta: { name: 'orionplace-nuxt', configKey: 'orionplace', compatibility: { nuxt: '^4.0.0' } },
+  setup(_options, nuxt) {
+    const directory = resolve(nuxt.options.rootDir, 'orionplace/runtime');
+    // Generated sources live outside server/, so inline them in development too.
+    nuxt.options.nitro.externals ||= {};
+    nuxt.options.nitro.externals.inline ||= [];
+    nuxt.options.nitro.externals.inline.push(directory);
+    if (!existsSync(resolve(directory, 'api.mjs'))) {
+      throw new Error('Run npx orionplace-nuxt init to generate the Orionplace integration.');
+    }
+    if (nuxt.options.nitro.preset && nuxt.options.nitro.preset !== 'node-server') {
+      throw new Error('Orionplace domain files require the Nitro node-server preset.');
+    }
+    const routes = nuxt.options.routeRules;
+    for (const path of ['/api', '/api/**', '/api/*']) {
+      if (routes[path]?.proxy || routes[path]?.redirect) {
+        throw new Error(`Remove the conflicting ${path} proxy/redirect: Orionplace handles API routing.`);
+      }
+    }
+    if (nuxt.options.vite.server?.proxy?.['/api']) {
+      throw new Error('Remove the Vite /api proxy: Orionplace provides a server gateway in development too.');
+    }
+    // Do not inherit page caching for authenticated API requests.
+    routes['/api/**'] = { ...routes['/api/**'], cache: false, swr: false,
+      headers: { ...routes['/api/**']?.headers, 'cache-control': 'no-store' } };
+    // Values stay private to the server. MIMIC_FRONT_DOMAIN is also read at runtime.
+    nuxt.options.runtimeConfig.mimicFrontDomain ??= '';
+    nuxt.options.runtimeConfig.mimicFrontDomain = process.env.MIMIC_FRONT_DOMAIN
+      ?? nuxt.options.runtimeConfig.mimicFrontDomain;
+    nuxt.options.nitro.preset ||= 'node-server';
+    const vary = new Set(String(routes['/**']?.headers?.vary || '').split(',').map(x => x.trim()).filter(Boolean));
+    for (const header of ['Host', 'X-Forwarded-Host', 'X-Front-Domain']) vary.add(header);
+    routes['/**'] = { ...routes['/**'], headers: { ...routes['/**']?.headers, vary: [...vary].join(', ') } };
+    const configs = resolve(nuxt.options.rootDir, process.env.SITEMAPS_DIR || 'sitemaps');
+    const hosts = existsSync(configs) ? readdirSync(configs).filter(x => x.endsWith('.cfg')).map(x => normalizeFrontDomain(x.slice(0, -4))).filter(Boolean) : [];
+    nuxt.options.vite.server ||= {};
+    if (nuxt.options.vite.server.allowedHosts !== true) {
+      nuxt.options.vite.server.allowedHosts = [...new Set([...(nuxt.options.vite.server.allowedHosts || []), ...hosts])];
+    }
+    addServerHandler({ route: '/api/**', handler: resolve(directory, 'api.mjs') });
+    addServerHandler({ middleware: true, handler: resolve(directory, 'domain.mjs') });
+  },
+});

package/src/project-readme.mjs

@@ -0,0 +1,180 @@
+export function projectReadme(settings) {
+  const frontend = settings.frontend || 'shop.example.com';
+  const backend = settings.backend || 'https://your-project.orionplace.app/api';
+  return `# Your Orionplace Nuxt integration
+
+This folder contains the integration source for your Nuxt 4 storefront.
+Your personal backend API is provided in your account at https://orionmarket.place.
+You can change that backend domain in your account, then update this project.
+
+## Current setup
+
+- Frontend domains: ${settings.frontends?.length ? settings.frontends.map(domain => '\`' + domain + '\`').join(', ') : 'not configured yet'}
+- Local MIMIC domain: \`${settings.frontend || 'not configured yet'}\`
+- Personal API: \`${settings.backend || 'not configured yet'}\`
+
+Set or change these values from the project root:
+
+\`\`\`bash
+npx orionplace-nuxt set backend ${backend}
+npx orionplace-nuxt add frontend ${frontend}
+npx orionplace-nuxt add frontend www.${frontend}
+npx orionplace-nuxt remove frontend www.${frontend}
+\`\`\`
+
+Set the backend or add a frontend first; either order works. Each frontend has its
+own \`sitemaps/<domain>.cfg\` mapping to your personal API. Adding a domain again
+is safe. Changing the backend updates every CLI-managed frontend mapping.
+
+The first added frontend becomes \`MIMIC_FRONT_DOMAIN\` in \`.env\`. Adding more
+domains preserves that choice. Use \`npx orionplace-nuxt set frontend <domain>\`
+to add and select a different local domain.
+
+Removing a frontend deletes only its unchanged generated \`.cfg\` file. If it was
+the selected MIMIC domain, the first remaining domain takes its place. Removing
+the last frontend clears MIMIC; add a frontend again before making API requests.
+Unknown or manually edited mappings are not removed automatically.
+
+Restart a running development server after changing domains so Vite reloads its
+allowed hosts and Nuxt reloads \`.env\`. Production reads domain files on each
+request; restart or reload the process environment when changing MIMIC. DNS, TLS
+and hosting-proxy settings must also cover each public frontend domain.
+Existing unrelated environment variables and Nuxt configuration are preserved.
+
+## Files you can read and customize
+
+| File | Purpose |
+| --- | --- |
+| \`runtime/marketplace.mjs\` | Domain lookup, configuration validation, API transport and cookies. |
+| \`runtime/api.mjs\` | The Nuxt/Nitro HTTP handler for \`/api/**\`. |
+| \`runtime/domain.mjs\` | Resolves the frontend domain into the request context. |
+| \`settings.json\` | The CLI's frontend list, local MIMIC domain and personal backend; not a secret store. |
+| \`../sitemaps/${frontend}.cfg\` | The backend URL used for this frontend domain. |
+| \`../.env\` | Local MIMIC setting; keep secrets out of version control. |
+| \`../nuxt.config.ts\` | Registers the \`orionplace-nuxt\` module. |
+
+The module registers these local source files with Nitro. You can edit them;
+subsequent setup runs preserve customized runtime files and this README.
+The CLI refuses to overwrite an unknown or manually changed domain mapping.
+
+## How requests reach your personal API
+
+The trusted hosting proxy supplies the public domain through \`X-Front-Domain\`,
+\`X-Forwarded-Host\`, or \`Host\`, in that order. On localhost,
+\`MIMIC_FRONT_DOMAIN\` supplies the domain instead. A known public domain takes
+priority over MIMIC; an unconfigured public domain returns \`503\`.
+
+The domain file is read for each request. The proxy preserves the request method,
+query, body, authorization and cookies. Backend HTTP status codes are preserved.
+Backend cookie domains are removed so cookies belong to the active frontend.
+Responses are not cached by this gateway. Network failures return \`502\`.
+
+The configuration directory defaults to \`sitemaps\` under the process working
+directory. Set \`SITEMAPS_DIR\` only if you store it elsewhere. Runtime configuration
+does not set a fixed public site URL. The middleware exposes the active domain
+as \`event.context.marketplaceDomain\`; use it when implementing your page metadata.
+
+## Start and verify
+
+Use Node.js 22.12 or newer. After scaffolding a new project, install dependencies:
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+In another terminal:
+
+\`\`\`bash
+curl -i http://localhost:3000/api/appload \\
+  -H 'Content-Type: application/json' \\
+  --data '{"ignore_cache":true,"detalize_mode":"full"}'
+\`\`\`
+
+Check both the HTTP status and \`form_errors\`. Successful initialization returns
+\`page_data\`; HTTP 200 by itself is insufficient. Documentation and public requests
+do not require a login prompt. Protected actions still require backend permission.
+
+Browser requests use the storefront's own API path:
+
+\`\`\`javascript
+const response = await fetch('/api/appload', {
+  method: 'POST',
+  credentials: 'same-origin',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ ignore_cache: true, detalize_mode: 'full' }),
+});
+const result = await response.json();
+console.log(response.status, result);
+\`\`\`
+
+For SSR, use Nuxt's \`useRequestFetch()\` so the request's domain, cookie and
+authorization headers reach the same gateway. For example, in \`app/app.vue\`:
+
+\`\`\`vue
+<script setup>
+const requestFetch = useRequestFetch();
+const { data, error } = await useAsyncData('marketplace-initialization', () =>
+  requestFetch('/api/appload', {
+    method: 'POST',
+    body: { ignore_cache: true, detalize_mode: 'full' },
+  }),
+);
+</script>
+
+<template>
+  <main>
+    <p v-if="error">The marketplace API is currently unavailable.</p>
+    <pre v-else>{{ data }}</pre>
+  </main>
+</template>
+\`\`\`
+
+Keep private data out of shared caches. This SSR example forwards incoming cookies;
+it does not relay new upstream cookies to the browser. Make session-changing calls
+from the browser, or explicitly append each returned Set-Cookie header to the SSR
+response in your server integration.
+
+
+## Deploy on your VPS
+
+This integration needs a Node.js server and its domain configuration files.
+It does not support static-only or edge hosting. Deploy the build, dependencies,
+\`sitemaps\`, and your environment configuration together; use an absolute
+\`SITEMAPS_DIR\` when running from another working directory.
+
+\`\`\`bash
+npm run build
+HOST=127.0.0.1 PORT=3000 node --env-file=.env .output/server/index.mjs
+\`\`\`
+
+The production process explicitly reads \`MIMIC_FRONT_DOMAIN\`. A public domain
+still takes precedence. The Node port must stay private behind your HTTPS proxy.
+
+Inside the storefront's HTTPS Nginx server block:
+
+\`\`\`nginx
+location / {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header X-Front-Domain $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Init-Ip $remote_addr;
+    proxy_buffering off;
+}
+\`\`\`
+
+Here localhost is your frontend process on your VPS. That process selects the
+remote personal API from the domain file. The proxy must overwrite those headers.
+An unknown domain never falls back to another tenant. This setup does not generate
+sitemap XML or add analytics.
+
+## More documentation
+
+- [Nuxt project setup](https://orionmarket.place/sandbox/new-project/nuxt)
+- [Domain setup and direct Nginx alternative](https://orionmarket.place/sandbox/backend-domain/nuxt)
+- [AppLoad](https://orionmarket.place/sandbox)
+`;
+}

package/src/setup.mjs

@@ -0,0 +1,188 @@
+import { readFile, readdir, lstat, mkdir, writeFile, rename, unlink } from 'node:fs/promises';
+import { resolve, dirname, relative, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseModule, generateCode } from 'magicast';
+import { backendUrl, frontendDomain } from './validation.mjs';
+import { projectReadme } from './project-readme.mjs';
+
+const metadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+const hash = text => createHash('sha256').update(text).digest('hex');
+async function read(path) {
+  try { return await readFile(path, 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+async function safePath(root, name) {
+  const target = resolve(root, name);
+  if (relative(root, target).startsWith('..') || target === root) throw new Error('Invalid generated path');
+  let cursor = root;
+  for (const piece of relative(root, target).split(sep)) {
+    cursor = resolve(cursor, piece);
+    try { if ((await lstat(cursor)).isSymbolicLink()) throw new Error(`Refusing symbolic link: ${name}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return target;
+}
+function configureNuxt(source) {
+  try {
+    const module = parseModule(source);
+    const options = module.exports.default.$type === 'function-call'
+      ? module.exports.default.$args[0] : module.exports.default;
+    if (!options || options.$type !== 'object') throw new Error('Dynamic configuration');
+    if (options.nitro?.preset && options.nitro.preset !== 'node-server') throw new Error('Unsupported Nitro preset');
+    if (options.srcDir || options.serverDir || options.extends) throw new Error('Custom directories or layers');
+    for (const route of ['/api', '/api/**', '/api/*']) {
+      if (options.routeRules?.[route]?.proxy || options.routeRules?.[route]?.redirect) throw new Error('Conflicting API routing');
+    }
+    if (options.vite?.server?.proxy?.['/api']) throw new Error('Conflicting Vite proxy');
+    options.modules ||= [];
+    if (!Array.from(options.modules).some(item => item === 'orionplace-nuxt' || (Array.isArray(item) && item[0] === 'orionplace-nuxt'))) {
+      options.modules.push('orionplace-nuxt');
+    }
+    return generateCode(module).code + '\n';
+  } catch {
+    throw new Error('Cannot safely update this Nuxt configuration. Use a standard Nuxt 4 root config with a literal modules array and no custom srcDir/serverDir, layers, non-Node presets, or /api proxy. No files were changed.');
+  }
+}
+function updateEnvironment(source, domain) {
+  const lines = (source || '').split(/\r?\n/);
+  let updated = false;
+  const result = lines.flatMap(line => {
+    if (!/^\s*(?:export\s+)?MIMIC_FRONT_DOMAIN\s*=/.test(line)) return [line];
+    if (updated) return [];
+    updated = true;
+    return [`MIMIC_FRONT_DOMAIN="${domain}"`];
+  });
+  if (!updated) result.push(`MIMIC_FRONT_DOMAIN="${domain}"`);
+  return result.join('\n').replace(/^\n/, '').replace(/\n*$/, '\n');
+}
+
+export async function setupProject({ cwd = process.cwd(), action = 'set', field, value, dryRun = false } = {}) {
+  if (!['set', 'add', 'remove'].includes(action) || (action !== 'set' && field !== 'frontend')) {
+    throw new Error('Use set backend, add frontend, remove frontend, or set frontend.');
+  }
+  const root = resolve(cwd);
+  const setting = field === 'backend' ? backendUrl(value) : field === 'frontend' ? frontendDomain(value) : null;
+  if (field && !setting) throw new Error('Choose backend or frontend.');
+  const names = ['package.json', 'nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs', 'orionplace/settings.json', 'orionplace/.generated.json', '.env', '.gitignore'];
+  const current = {};
+  for (const name of names) current[name] = await read(await safePath(root, name));
+  const pkg = current['package.json'] ? JSON.parse(current['package.json']) : { name: 'orionplace-storefront', private: true, type: 'module' };
+  const dependencies = { ...pkg.devDependencies, ...pkg.dependencies };
+  if (!dependencies.nuxt && ['next', '@sveltejs/kit'].some(name => dependencies[name])) throw new Error('This package sets up Nuxt projects only.');
+  if (dependencies.nuxt && !/^(?:[~^]|>=)?4(?:\.|$)/.test(dependencies.nuxt)) {
+    throw new Error('This release supports Nuxt 4. Upgrade your Nuxt dependency before setup.');
+  }
+  const configs = ['nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs'].filter(name => current[name] !== null);
+  if (configs.length > 1) throw new Error('Multiple Nuxt configuration files found; keep one root config.');
+  const configName = configs[0] || 'nuxt.config.ts';
+  const config = configureNuxt(current[configName] || 'export default defineNuxtConfig({ modules: [] });\n');
+  for (const directory of ['server/api', 'server/routes/api']) {
+    const path = await safePath(root, directory);
+    let entries = [];
+    try { entries = await readdir(path); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (entries.some(name => name.startsWith('[...'))) {
+      throw new Error(`Existing API catch-all in ${directory}. Resolve this route conflict first.`);
+    }
+  }
+  const settings = current['orionplace/settings.json'] ? JSON.parse(current['orionplace/settings.json']) : {};
+  const previous = current['orionplace/.generated.json'] ? JSON.parse(current['orionplace/.generated.json']) : {};
+  if (settings.backend) settings.backend = backendUrl(settings.backend);
+  if (settings.frontend) settings.frontend = frontendDomain(settings.frontend);
+  const oldFrontend = settings.frontend;
+  // Migrate the initial single-domain format, including its previously generated mappings.
+  const legacyDomains = Object.keys(previous)
+    .map(name => /^sitemaps\/([^/]+)\.cfg$/.exec(name)?.[1]).filter(Boolean);
+  const frontends = settings.frontends ?? [settings.frontend, ...legacyDomains].filter(Boolean);
+  if (!Array.isArray(frontends)) throw new Error('settings.frontends must be an array of domain names.');
+  settings.frontends = [...new Set(frontends.map(frontendDomain))];
+  if (settings.frontend && !settings.frontends.includes(settings.frontend)) settings.frontends.unshift(settings.frontend);
+  if (field === 'backend') settings.backend = setting;
+  if (field === 'frontend') {
+    if (action === 'remove') {
+      if (!settings.frontends.includes(setting)) throw new Error(`Frontend is not managed by this project: ${setting}`);
+      settings.frontends = settings.frontends.filter(domain => domain !== setting);
+      if (settings.frontend === setting) settings.frontend = settings.frontends[0];
+    } else {
+      if (!settings.frontends.includes(setting)) settings.frontends.push(setting);
+      // Adding an alias preserves the local development domain. "set" selects it.
+      if (action === 'set' || !settings.frontend) settings.frontend = setting;
+    }
+  }
+  settings.frontend ||= settings.frontends[0];
+  if (!settings.frontend) delete settings.frontend;
+  const manifest = { ...previous };
+  const changes = new Map();
+  const preserved = [];
+  async function plan(name, content, { managed = false, preserve = false } = {}) {
+    const path = await safePath(root, name);
+    const existing = await read(path);
+    if (managed && existing !== null && existing !== content && previous[name] !== hash(existing)) {
+      if (preserve && previous[name]) { preserved.push(name); return; }
+      throw new Error(`Refusing to overwrite ${name}: it is not an unchanged generated file. No files were changed.`);
+    }
+    if (existing !== content) changes.set(name, content);
+    if (managed) manifest[name] = hash(content);
+  }
+  async function planRemoval(name) {
+    const existing = await read(await safePath(root, name));
+    if (existing !== null && previous[name] !== hash(existing)) {
+      throw new Error(`Refusing to remove ${name}: it is not an unchanged generated file. No files were changed.`);
+    }
+    if (existing !== null) changes.set(name, null);
+    delete manifest[name];
+  }
+  // All checks and content generation happen before the first write.
+  await plan(configName, config);
+  const isNewNuxt = !dependencies.nuxt;
+  pkg.scripts ||= {};
+  pkg.scripts.dev ||= 'nuxt dev';
+  pkg.scripts.build ||= 'nuxt build';
+  pkg.scripts.preview ||= 'nuxt preview';
+  pkg.scripts['orionplace:backend'] ||= 'orionplace-nuxt set backend';
+  pkg.scripts['orionplace:frontend'] ||= 'orionplace-nuxt set frontend';
+  pkg.scripts['orionplace:add-frontend'] ||= 'orionplace-nuxt add frontend';
+  pkg.scripts['orionplace:remove-frontend'] ||= 'orionplace-nuxt remove frontend';
+  pkg.dependencies ||= {};
+  pkg.dependencies['orionplace-nuxt'] ||= dependencies['orionplace-nuxt'] || `^${metadata.version}`;
+  if (isNewNuxt) {
+    pkg.dependencies.nuxt = '^4.5.0';
+    pkg.dependencies.vue ||= '^3.5.0';
+    pkg.dependencies['vue-router'] ||= '^5.0.0';
+  }
+  await plan('package.json', JSON.stringify(pkg, null, 2) + '\n');
+  for (const file of ['marketplace.mjs', 'api.mjs', 'domain.mjs']) {
+    await plan(`orionplace/runtime/${file}`, await readFile(new URL(`../runtime/${file}`, import.meta.url), 'utf8'), { managed: true, preserve: true });
+  }
+  await plan('orionplace/README.md', projectReadme(settings), { managed: true, preserve: true });
+  if (isNewNuxt && !(await read(await safePath(root, 'app/app.vue')))) {
+    await plan('app/app.vue', '<template>\n  <main>\n    <h1>Your marketplace</h1>\n    <p>Domain setup and API instructions are in orionplace/README.md.</p>\n  </main>\n</template>\n', { managed: true });
+  }
+  if (settings.frontend || oldFrontend) await plan('.env', updateEnvironment(current['.env'], settings.frontend || ''));
+  if (settings.backend) {
+    const mappings = action === 'remove' ? []
+      : field === 'frontend' ? [setting] : settings.frontends;
+    for (const domain of mappings) {
+      await plan(`sitemaps/${domain}.cfg`, settings.backend + '\n', { managed: true });
+    }
+  }
+  if (action === 'remove') await planRemoval(`sitemaps/${setting}.cfg`);
+  let ignore = current['.gitignore'] || '';
+  for (const entry of ['node_modules/', '.nuxt/', '.output/', '.env', '.env.*', '!.env.example']) {
+    if (!ignore.split(/\r?\n/).includes(entry)) ignore = ignore.replace(/\n*$/, '\n') + entry + '\n';
+  }
+  await plan('.gitignore', ignore);
+  await plan('orionplace/settings.json', JSON.stringify(settings, null, 2) + '\n');
+  await plan('orionplace/.generated.json', JSON.stringify(manifest, null, 2) + '\n');
+  if (!dryRun) {
+    for (const [name, content] of changes) {
+      const target = await safePath(root, name);
+      if (content === null) { await unlink(target); continue; }
+      await mkdir(dirname(target), { recursive: true });
+      const temporary = `${target}.orionplace-${process.pid}.tmp`;
+      await writeFile(temporary, content, { mode: name === '.env' ? 0o600 : 0o644, flag: 'wx' });
+      await rename(temporary, target);
+    }
+  }
+  return { root, settings, changed: [...changes.keys()], removed: [...changes].filter(([, content]) => content === null).map(([name]) => name), preserved, dryRun, isNewNuxt };
+}

package/src/validation.mjs

@@ -0,0 +1,27 @@
+import { isIP } from 'node:net';
+const dns = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+export function frontendDomain(value) {
+  let url;
+  try { url = new URL(value.includes('://') ? value : `https://${value}`); }
+  catch { throw new Error('Use a public frontend hostname, for example shop.example.com.'); }
+  const domain = url.hostname.toLowerCase().replace(/\.$/, '');
+  if (!dns.test(domain) || isIP(domain) || url.username || url.password || url.port ||
+      url.search || url.hash || url.pathname !== '/' || !['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('Frontend must be a public hostname without a port, path, or credentials.');
+  }
+  return domain;
+}
+
+export function backendUrl(value) {
+  let url;
+  try { url = new URL(value.includes('://') ? value : `https://${value}`); }
+  catch { throw new Error('Use the personal backend domain shown in your Orionplace account.'); }
+  const path = url.pathname.replace(/\/+$/, '');
+  if (url.protocol !== 'https:' || !dns.test(url.hostname) ||
+      !url.hostname.endsWith('.orionplace.app') || url.username || url.password ||
+      url.port || url.search || url.hash || !['', '/api'].includes(path)) {
+    throw new Error('Backend must be https://<your-project>.orionplace.app or its /api URL.');
+  }
+  return `${url.origin}/api`;
+}