@stopnetic/js 0.0.1-pilot → 0.0.3-pilot

package/dist/index.js

@@ -1,172 +1,172 @@
-import { createStopnetic } from './guard.js';
-export { createStopnetic, parseAdditionalDecisionPublicKeys } from './guard.js';
-
-const denied = () => new Response(null, { status: 404, headers: { 'cache-control': 'no-store' } });
-const unavailable = () => new Response(null, { status: 503, headers: { 'cache-control': 'no-store' } });
-
-function canonicalOrigin(value) {
-  let url;
-  try { url = new URL(value); } catch { throw new Error('origin must be an HTTPS origin (HTTP only on localhost)'); }
-  if (url.username || url.password || url.pathname !== '/' || url.search || url.hash
-    || !(url.protocol === 'https:' || (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))) {
-    throw new Error('origin must be an HTTPS origin (HTTP only on localhost)');
-  }
-  return url.origin;
-}
-
-function target(raw, origin) {
-  if (typeof raw !== 'string' || !raw.startsWith('/') || raw.startsWith('//') || /[\\\s#]/.test(raw)) throw new Error('Invalid request target');
-  const url = new URL(raw, origin);
-  // Do not let URL normalization or downstream decoding change the checked path.
-  if (url.origin !== origin || url.pathname + url.search !== raw) throw new Error('Invalid request target');
-  const decoded = decodeURIComponent(url.pathname);
-  if (/[\\\s?#%]/.test(decoded) || /[\x00-\x1f\x7f]/.test(decoded)
-    || decoded.split('/').some(part => part === '.' || part === '..')
-    || /%[0-7][0-9a-f]/i.test(url.pathname) || url.pathname.includes('//')) throw new Error('Ambiguous request path');
-  return url;
-}
-
-function optionsForGuard(options, origin) {
-  const local = origin.startsWith('http:');
-  if (!local && options.secureCookie === false) throw new Error('HTTPS sites require secure cookies');
-  // A verification request must reach the verification handler, not a bypass.
-  return { ...options, secureCookie: !local };
-}
-
-async function boundedWebBody(request) {
-  if (Number(request.headers.get('content-length')) > 4096) throw new Error('Body too large');
-  const reader = request.body?.getReader();
-  if (!reader) throw new Error('Missing body');
-  const chunks = [];
-  let size = 0;
-  let timer;
-  let finished = false;
-  const deadline = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Body timeout')), 5000); });
-  try {
-    for (;;) {
-      const { value, done } = await Promise.race([reader.read(), deadline]);
-      if (done) { finished = true; return Buffer.concat(chunks, size); }
-      size += value.byteLength;
-      if (size > 4096) throw new Error('Body too large');
-      chunks.push(Buffer.from(value));
-    }
-  } finally {
-    clearTimeout(timer);
-    if (!finished) void reader.cancel().catch(() => {});
-    reader.releaseLock();
-  }
-}
-
-/** Fetch-style adapter for Node-hosted frameworks. Always handles verification. */
-export function createStopneticHandler(options) {
-  const origin = canonicalOrigin(options.origin);
-  const guard = createStopnetic(optionsForGuard(options, origin));
-  const verifyPath = options.verifyPath || '/__stopnetic/verify';
-  return async function handle(request, next) {
-    let response;
-    try {
-      const url = new URL(request.url);
-      if (url.origin !== origin || (request.headers.has('host') && request.headers.get('host').toLowerCase() !== url.host)) return denied();
-      target(url.pathname + url.search, origin);
-      if (url.pathname === verifyPath) {
-        if (request.method !== 'POST' || request.headers.get('origin') !== origin
-          || !(request.headers.get('content-type') || '').toLowerCase().startsWith('application/json')) {
-          return request.method === 'POST' ? denied() : new Response(null, { status: 405, headers: { allow: 'POST', 'cache-control': 'no-store' } });
-        }
-        try {
-          const body = await boundedWebBody(request);
-          response = await guard.verify(new Request(request.url, { method: 'POST', headers: request.headers, body }));
-        } catch { return denied(); }
-      } else response = await guard.check(request);
-    } catch { return unavailable(); }
-    if (response) return response;
-    const result = await next(request);
-    // Copy headers, including individual cookies, without buffering the body.
-    const headers = new Headers(result.headers);
-    headers.set('cache-control', 'private, no-store');
-    return new Response(result.body, { status: result.status, statusText: result.statusText, headers });
-  };
-}
-
-function requestHeaders(req, origin) {
-  const headers = new Headers();
-  for (const name of ['accept', 'cookie', 'origin', 'content-type', 'content-length']) {
-    const value = req.headers[name];
-    if (Array.isArray(value)) throw new Error('Ambiguous request headers');
-    if (value !== undefined) headers.set(name, value);
-  }
-  headers.set('host', new URL(origin).host);
-  return headers;
-}
-
-function verificationBody(req) {
-  return new Promise((resolve, reject) => {
-    if (req.readableEnded || req.destroyed) { reject(new Error('Verification body unavailable')); return; }
-    const chunks = [];
-    let size = 0;
-    const cleanup = () => {
-      clearTimeout(timer);
-      req.off('data', data); req.off('end', end); req.off('error', fail); req.off('aborted', fail);
-    };
-    const fail = () => { cleanup(); req.pause(); reject(new Error('Invalid verification body')); };
-    const data = chunk => {
-      const bytes = Buffer.from(chunk);
-      size += bytes.length;
-      if (size > 4096) { fail(); return; }
-      chunks.push(bytes);
-    };
-    const end = () => { cleanup(); resolve(Buffer.concat(chunks, size)); };
-    const timer = setTimeout(fail, 5000);
-    req.on('data', data); req.once('end', end); req.once('error', fail); req.once('aborted', fail);
-  });
-}
-
-async function send(response, req, res, close = false) {
-  res.statusCode = response.status;
-  response.headers.forEach((value, name) => { if (name !== 'set-cookie') res.setHeader(name, value); });
-  const cookies = response.headers.getSetCookie();
-  if (cookies.length) res.setHeader('set-cookie', cookies);
-  if (close) res.setHeader('connection', 'close');
-  const body = req.method === 'HEAD' ? undefined : Buffer.from(await response.arrayBuffer());
-  res.end(body);
-}
-
-/** Use first, at the application root, before parsers, static files and routes. */
-export function createStopneticMiddleware(options) {
-  const origin = canonicalOrigin(options.origin);
-  const guard = createStopnetic(optionsForGuard(options, origin));
-  const verifyPath = options.verifyPath || '/__stopnetic/verify';
-  return async function stopnetic(req, res, next) {
-    let response;
-    let close = false;
-    try {
-      const host = req.headers.host;
-      if (typeof host !== 'string' || host.toLowerCase() !== new URL(origin).host) response = denied();
-      else {
-        const url = target(req.originalUrl || req.url, origin);
-        const headers = requestHeaders(req, origin);
-        const method = req.method || 'GET';
-        if (url.pathname === verifyPath) {
-          if (method !== 'POST') response = new Response(null, { status: 405, headers: { allow: 'POST', 'cache-control': 'no-store' } });
-          else if (headers.get('origin') !== origin || !(headers.get('content-type') || '').toLowerCase().startsWith('application/json')
-            || Number(headers.get('content-length')) > 4096) { response = denied(); close = true; }
-          else {
-            try {
-              const body = await verificationBody(req);
-              response = await guard.verify(new Request(url, { method, headers, body }));
-            } catch { response = denied(); close = true; }
-          }
-        } else {
-          // Checking ordinary requests must leave their bodies for the application.
-          response = await guard.check(new Request(url, { method, headers }));
-        }
-      }
-    } catch { response = unavailable(); close = true; }
-    if (response) {
-      try { await send(response, req, res, close); } catch { res.destroy(); }
-      return;
-    }
-    res.setHeader('cache-control', 'private, no-store');
-    return next();
-  };
-}
+import { createStopnetic } from './guard.js';
+export { createStopnetic, parseAdditionalDecisionPublicKeys } from './guard.js';
+
+const denied = () => new Response(null, { status: 404, headers: { 'cache-control': 'no-store' } });
+const unavailable = () => new Response(null, { status: 503, headers: { 'cache-control': 'no-store' } });
+
+function canonicalOrigin(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new Error('origin must be an HTTPS origin (HTTP only on localhost)'); }
+  if (url.username || url.password || url.pathname !== '/' || url.search || url.hash
+    || !(url.protocol === 'https:' || (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))) {
+    throw new Error('origin must be an HTTPS origin (HTTP only on localhost)');
+  }
+  return url.origin;
+}
+
+function target(raw, origin) {
+  if (typeof raw !== 'string' || !raw.startsWith('/') || raw.startsWith('//') || /[\\\s#]/.test(raw)) throw new Error('Invalid request target');
+  const url = new URL(raw, origin);
+  // Do not let URL normalization or downstream decoding change the checked path.
+  if (url.origin !== origin || url.pathname + url.search !== raw) throw new Error('Invalid request target');
+  const decoded = decodeURIComponent(url.pathname);
+  if (/[\\\s?#%]/.test(decoded) || /[\x00-\x1f\x7f]/.test(decoded)
+    || decoded.split('/').some(part => part === '.' || part === '..')
+    || /%[0-7][0-9a-f]/i.test(url.pathname) || url.pathname.includes('//')) throw new Error('Ambiguous request path');
+  return url;
+}
+
+function optionsForGuard(options, origin) {
+  const local = origin.startsWith('http:');
+  if (!local && options.secureCookie === false) throw new Error('HTTPS sites require secure cookies');
+  // A verification request must reach the verification handler, not a bypass.
+  return { ...options, secureCookie: !local };
+}
+
+async function boundedWebBody(request) {
+  if (Number(request.headers.get('content-length')) > 4096) throw new Error('Body too large');
+  const reader = request.body?.getReader();
+  if (!reader) throw new Error('Missing body');
+  const chunks = [];
+  let size = 0;
+  let timer;
+  let finished = false;
+  const deadline = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Body timeout')), 5000); });
+  try {
+    for (;;) {
+      const { value, done } = await Promise.race([reader.read(), deadline]);
+      if (done) { finished = true; return Buffer.concat(chunks, size); }
+      size += value.byteLength;
+      if (size > 4096) throw new Error('Body too large');
+      chunks.push(Buffer.from(value));
+    }
+  } finally {
+    clearTimeout(timer);
+    if (!finished) void reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}
+
+/** Fetch-style adapter for Node-hosted frameworks. Always handles verification. */
+export function createStopneticHandler(options) {
+  const origin = canonicalOrigin(options.origin);
+  const guard = createStopnetic(optionsForGuard(options, origin));
+  const verifyPath = options.verifyPath || '/__stopnetic/verify';
+  return async function handle(request, next) {
+    let response;
+    try {
+      const url = new URL(request.url);
+      if (url.origin !== origin || (request.headers.has('host') && request.headers.get('host').toLowerCase() !== url.host)) return denied();
+      target(url.pathname + url.search, origin);
+      if (url.pathname === verifyPath) {
+        if (request.method !== 'POST' || request.headers.get('origin') !== origin
+          || !(request.headers.get('content-type') || '').toLowerCase().startsWith('application/json')) {
+          return request.method === 'POST' ? denied() : new Response(null, { status: 405, headers: { allow: 'POST', 'cache-control': 'no-store' } });
+        }
+        try {
+          const body = await boundedWebBody(request);
+          response = await guard.verify(new Request(request.url, { method: 'POST', headers: request.headers, body }));
+        } catch { return denied(); }
+      } else response = await guard.check(request);
+    } catch { return unavailable(); }
+    if (response) return response;
+    const result = await next(request);
+    // Copy headers, including individual cookies, without buffering the body.
+    const headers = new Headers(result.headers);
+    headers.set('cache-control', 'private, no-store');
+    return new Response(result.body, { status: result.status, statusText: result.statusText, headers });
+  };
+}
+
+function requestHeaders(req, origin) {
+  const headers = new Headers();
+  for (const name of ['accept', 'cookie', 'origin', 'content-type', 'content-length']) {
+    const value = req.headers[name];
+    if (Array.isArray(value)) throw new Error('Ambiguous request headers');
+    if (value !== undefined) headers.set(name, value);
+  }
+  headers.set('host', new URL(origin).host);
+  return headers;
+}
+
+function verificationBody(req) {
+  return new Promise((resolve, reject) => {
+    if (req.readableEnded || req.destroyed) { reject(new Error('Verification body unavailable')); return; }
+    const chunks = [];
+    let size = 0;
+    const cleanup = () => {
+      clearTimeout(timer);
+      req.off('data', data); req.off('end', end); req.off('error', fail); req.off('aborted', fail);
+    };
+    const fail = () => { cleanup(); req.pause(); reject(new Error('Invalid verification body')); };
+    const data = chunk => {
+      const bytes = Buffer.from(chunk);
+      size += bytes.length;
+      if (size > 4096) { fail(); return; }
+      chunks.push(bytes);
+    };
+    const end = () => { cleanup(); resolve(Buffer.concat(chunks, size)); };
+    const timer = setTimeout(fail, 5000);
+    req.on('data', data); req.once('end', end); req.once('error', fail); req.once('aborted', fail);
+  });
+}
+
+async function send(response, req, res, close = false) {
+  res.statusCode = response.status;
+  response.headers.forEach((value, name) => { if (name !== 'set-cookie') res.setHeader(name, value); });
+  const cookies = response.headers.getSetCookie();
+  if (cookies.length) res.setHeader('set-cookie', cookies);
+  if (close) res.setHeader('connection', 'close');
+  const body = req.method === 'HEAD' ? undefined : Buffer.from(await response.arrayBuffer());
+  res.end(body);
+}
+
+/** Use first, at the application root, before parsers, static files and routes. */
+export function createStopneticMiddleware(options) {
+  const origin = canonicalOrigin(options.origin);
+  const guard = createStopnetic(optionsForGuard(options, origin));
+  const verifyPath = options.verifyPath || '/__stopnetic/verify';
+  return async function stopnetic(req, res, next) {
+    let response;
+    let close = false;
+    try {
+      const host = req.headers.host;
+      if (typeof host !== 'string' || host.toLowerCase() !== new URL(origin).host) response = denied();
+      else {
+        const url = target(req.originalUrl || req.url, origin);
+        const headers = requestHeaders(req, origin);
+        const method = req.method || 'GET';
+        if (url.pathname === verifyPath) {
+          if (method !== 'POST') response = new Response(null, { status: 405, headers: { allow: 'POST', 'cache-control': 'no-store' } });
+          else if (headers.get('origin') !== origin || !(headers.get('content-type') || '').toLowerCase().startsWith('application/json')
+            || Number(headers.get('content-length')) > 4096) { response = denied(); close = true; }
+          else {
+            try {
+              const body = await verificationBody(req);
+              response = await guard.verify(new Request(url, { method, headers, body }));
+            } catch { response = denied(); close = true; }
+          }
+        } else {
+          // Checking ordinary requests must leave their bodies for the application.
+          response = await guard.check(new Request(url, { method, headers }));
+        }
+      }
+    } catch { response = unavailable(); close = true; }
+    if (response) {
+      try { await send(response, req, res, close); } catch { res.destroy(); }
+      return;
+    }
+    res.setHeader('cache-control', 'private, no-store');
+    return next();
+  };
+}

package/dist/react.d.ts

@@ -0,0 +1,4 @@
+import type { ReactNode } from 'react';
+export function StopneticBoundary(props: {
+  path: string; children?: ReactNode; pending?: ReactNode; blocked?: ReactNode; redirect?: boolean;
+}): ReactNode;

package/dist/react.js

@@ -0,0 +1,24 @@
+import { createElement, useEffect, useState } from 'react';
+import { checkAccess } from './browser.js';
+
+/** UI boundary only. Keep private data in independently guarded server endpoints. */
+export function StopneticBoundary(props) {
+  return createElement(CheckedBoundary, { ...props, key: props.path });
+}
+
+function CheckedBoundary({ path, children, pending = 'Checking access…', blocked = 'Access unavailable.', redirect = true }) {
+  const [result, setResult] = useState(null);
+  useEffect(() => {
+    const controller = new AbortController();
+    checkAccess(path, { signal: controller.signal }).then(value => {
+      if (!controller.signal.aborted) {
+        setResult({ ...value, path });
+        if (redirect && value.reason === 'verification_required') window.location.assign(value.verificationUrl);
+      }
+    }).catch(() => { if (!controller.signal.aborted) setResult({ allowed: false, reason: 'unavailable', path }); });
+    return () => controller.abort();
+  }, [path, redirect]);
+  if (!result || result.path !== path) return createElement('div', { role: 'status' }, pending);
+  if (!result.allowed) return createElement('div', { role: 'alert' }, blocked);
+  return children;
+}

package/dist/server.d.ts

@@ -0,0 +1,17 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { StopneticServerOptions } from './index.js';
+export const accessBase: '/api/stopnetic';
+export function optionsFromEnv(env?: Record<string, string | undefined>): StopneticServerOptions;
+export function createStopneticAccessHandler(options?: StopneticServerOptions): (request: Request) => Promise<Response>;
+export function withStopnetic<Context extends unknown[]>(handler: (request: Request, ...context: Context) => Response | Promise<Response>,
+  options?: StopneticServerOptions): (request: Request, ...context: Context) => Promise<Response>;
+/** Node.js application wrapper: control endpoints, pages and APIs before rendering. */
+export function createStopneticAppHandler<Context extends unknown[]>(handler: (request: Request, ...context: Context) => Response | Promise<Response>,
+  options?: StopneticServerOptions): (request: Request, ...context: Context) => Promise<Response>;
+export function createStopneticAccessMiddleware(options?: StopneticServerOptions): (
+  request: IncomingMessage & { originalUrl?: string }, response: ServerResponse, next: () => unknown,
+) => Promise<unknown>;
+export function createStopneticServer(options?: StopneticServerOptions): {
+  access: ReturnType<typeof createStopneticAccessMiddleware>;
+  guard: ReturnType<typeof import('./index.js').createStopneticMiddleware>;
+};

package/dist/server.js

@@ -0,0 +1,123 @@
+import { createStopneticHandler, createStopneticMiddleware, parseAdditionalDecisionPublicKeys } from './index.js';
+
+export const accessBase = '/api/stopnetic';
+
+/** Server environment only. Never import this module into browser code. */
+export function optionsFromEnv(env = process.env) {
+  return {
+    origin: env.STOPNETIC_WEBSITE_ORIGIN,
+    siteId: env.STOPNETIC_SITE_ID,
+    apiUrl: env.STOPNETIC_API_URL,
+    apiToken: env.STOPNETIC_API_TOKEN,
+    decisionPublicKey: env.STOPNETIC_DECISION_PUBLIC_KEY?.replaceAll('\\n', '\n'),
+    additionalDecisionPublicKeys: parseAdditionalDecisionPublicKeys(env.STOPNETIC_DECISION_ADDITIONAL_PUBLIC_KEYS),
+    cookieSecret: env.STOPNETIC_COOKIE_SECRET,
+    guardMode: 'site',
+    verifyPath: `${accessBase}/verify`,
+  };
+}
+
+const empty = status => new Response(null, { status, headers: { 'cache-control': 'private, no-store' } });
+function checkedPath(path, origin) {
+  if (typeof path !== 'string' || path.length > 2048 || !path.startsWith('/') || path.startsWith('//')
+    || /[\\\s#]/.test(path)) throw new Error('Invalid page path');
+  const url = new URL(path, origin);
+  if (url.origin !== origin || url.pathname + url.search !== path
+    || url.pathname === accessBase || url.pathname.startsWith(`${accessBase}/`)) throw new Error('Invalid page path');
+  return url;
+}
+
+/** Same-origin UI checks. These never authorize a separate data handler. */
+export function createStopneticAccessHandler(options = optionsFromEnv()) {
+  const origin = new URL(options.origin).origin;
+  const verifyPath = `${accessBase}/verify`;
+  const protect = createStopneticHandler({ ...options, verifyPath });
+  return async function access(request) {
+    const url = new URL(request.url);
+    if (url.origin !== origin || (request.headers.has('host') && request.headers.get('host').toLowerCase() !== url.host)) return empty(404);
+    if (url.pathname === verifyPath) return protect(request, () => empty(404));
+    if (url.pathname !== `${accessBase}/access`) return empty(404);
+    if (request.method !== 'GET') return new Response(null, { status: 405, headers: { allow: 'GET', 'cache-control': 'private, no-store' } });
+    let target;
+    try { target = checkedPath(url.searchParams.get('path'), origin); } catch { return empty(400); }
+    if (url.searchParams.getAll('path').length !== 1 || url.searchParams.getAll('mode').length > 1
+      || [...url.searchParams.keys()].some(key => !['path', 'mode'].includes(key))
+      || (url.searchParams.has('mode') && url.searchParams.get('mode') !== 'check')) return empty(400);
+    // Navigation checks use the real page path and cookie, not the control URL.
+    const headers = new Headers(request.headers);
+    headers.set('accept', 'text/html');
+    const check = url.searchParams.get('mode') === 'check';
+    const response = await protect(new Request(target, { headers }), () => check
+      ? Response.json({ allowed: true })
+      : new Response(null, { status: 303, headers: { location: target.pathname + target.search } }));
+    if (!check || response.ok) return response;
+    const challenge = response.status === 404 && response.headers.get('content-type')?.startsWith('text/html');
+    const resultHeaders = new Headers({ 'cache-control': 'private, no-store' });
+    for (const cookie of response.headers.getSetCookie()) resultHeaders.append('set-cookie', cookie);
+    await response.body?.cancel();
+    return Response.json({ allowed: false, reason: challenge ? 'verification_required' : response.status === 404 ? 'blocked' : 'unavailable' },
+      { status: response.status, headers: resultHeaders });
+  };
+}
+
+/** Wrap EACH protected Fetch-style API; the UI's allowed flag is never trusted. */
+export function withStopnetic(handler, options = optionsFromEnv()) {
+  const protect = createStopneticHandler(options);
+  return (request, ...context) => {
+    // Netlify's default function alias must not bypass a custom API path's rule.
+    // Declare a custom config.path for these functions and use it in Policies.
+    if (new URL(request.url).pathname.startsWith('/.netlify/functions/')) return Promise.resolve(empty(404));
+    return protect(request, checked => handler(checked, ...context));
+  };
+}
+
+/** Guard a complete Fetch-style application before its renderer or API runs.
+ * The application must run in Node.js; accepting Request/Response alone does
+ * not make an Edge runtime compatible. Context arguments are preserved.
+ */
+export function createStopneticAppHandler(handler, options = optionsFromEnv()) {
+  if (typeof handler !== 'function') throw new TypeError('An application handler is required');
+  const settings = { ...options, verifyPath: `${accessBase}/verify` };
+  const access = createStopneticAccessHandler(settings);
+  const application = withStopnetic(handler, settings);
+  return (request, ...context) => {
+    const path = new URL(request.url).pathname;
+    if (path === accessBase || path.startsWith(`${accessBase}/`)) return access(request);
+    return application(request, ...context);
+  };
+}
+
+/** Node/Express: mount first, then the root guard, then parsers/static/API handlers. */
+export function createStopneticAccessMiddleware(options = optionsFromEnv()) {
+  const access = createStopneticAccessHandler(options);
+  const verification = createStopneticMiddleware({ ...options, verifyPath: `${accessBase}/verify` });
+  return async (req, res, next) => {
+    const path = (req.originalUrl || req.url || '').split('?')[0];
+    if (path !== `${accessBase}/access` && path !== `${accessBase}/verify`) return next();
+    if (path === `${accessBase}/verify`) return verification(req, res, next);
+    try {
+      const headers = new Headers();
+      for (const [name, value] of Object.entries(req.headers)) {
+        if (Array.isArray(value)) { res.writeHead(400, { 'cache-control': 'no-store' }); res.end(); return; }
+        if (value !== undefined) headers.set(name, value);
+      }
+      const request = new Request(new URL(req.originalUrl || req.url, options.origin), {
+        method: req.method, headers,
+        ...(['GET', 'HEAD'].includes(req.method) ? {} : { body: req, duplex: 'half' }),
+      });
+      const response = await access(request);
+      res.statusCode = response.status;
+      response.headers.forEach((value, name) => { if (name !== 'set-cookie') res.setHeader(name, value); });
+      const cookies = response.headers.getSetCookie();
+      if (cookies.length) res.setHeader('set-cookie', cookies);
+      res.end(Buffer.from(await response.arrayBuffer()));
+    } catch { res.writeHead(503, { 'cache-control': 'private, no-store' }); res.end(); }
+  };
+}
+
+export function createStopneticServer(options = optionsFromEnv()) {
+  return {
+    access: createStopneticAccessMiddleware(options),
+    guard: createStopneticMiddleware({ ...options, verifyPath: `${accessBase}/verify` }),
+  };
+}

package/dist/setup.js

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, lstatSync, realpathSync } from 'node:fs';
+import { resolve, relative, dirname, isAbsolute } from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+import { parseEnv } from 'node:util';
+import { createStopneticAccessHandler, optionsFromEnv } from './server.js';
+
+export class SetupError extends Error {}
+const digest = value => createHash('sha256').update(value).digest('hex');
+const manifestName = 'stopnetic.setup.json';
+function destination(root, name) {
+  const file = resolve(root, name);
+  const inside = relative(root, file);
+  if (!inside || inside.startsWith('..') || isAbsolute(inside) || /[\x00-\x1f]/.test(name)) throw new SetupError('Setup paths must stay inside the project.');
+  for (let cursor = file; cursor !== root; cursor = dirname(cursor)) {
+    if (lstatSync(cursor, { throwIfNoEntry: false })?.isSymbolicLink()) throw new SetupError('Setup refuses symbolic links.');
+  }
+  return file;
+}
+function text(file) { return existsSync(file) ? readFileSync(file, 'utf8') : ''; }
+function environment(root) {
+  try {
+    return { ...parseEnv(text(destination(root, '.env'))), ...parseEnv(text(destination(root, '.env.local'))), ...process.env };
+  } catch { throw new SetupError('Check server environment file formatting.'); }
+}
+function project(root) {
+  try { return JSON.parse(readFileSync(destination(root, 'package.json'), 'utf8')); }
+  catch { throw new SetupError('Run setup from a project with a valid package.json.'); }
+}
+function platformFor(root, supplied) {
+  if (supplied && !['netlify', 'vercel', 'node'].includes(supplied)) throw new SetupError('Choose netlify, vercel or node.');
+  if (supplied) return supplied;
+  const netlify = existsSync(destination(root, 'netlify.toml'));
+  const vercel = existsSync(destination(root, 'vercel.json'));
+  if (netlify && !vercel) return 'netlify';
+  if (vercel && !netlify) return 'vercel';
+  throw new SetupError('Choose your hosting explicitly: --platform netlify, vercel or node.');
+}
+const legacyGuideDigest = 'b1f149af44f9ceb08fb80c18cb5d4b521620196f536d8ad422ab94d15d1d125d';
+const clientGuide = readFileSync(new URL('./client-guide.md', import.meta.url), 'utf8');
+
+function filesFor(root, platform) {
+  const files = {
+    'stopnetic-client-guide.md': clientGuide,
+    '.env.stopnetic.example': `# SERVER settings; copy actual values from Stopnetic Integration.\nSTOPNETIC_WEBSITE_ORIGIN=https://www.example.com\nSTOPNETIC_SITE_ID=\nSTOPNETIC_API_URL=https://your-stopnetic-service/api/integration/decision\nSTOPNETIC_API_TOKEN=\nSTOPNETIC_DECISION_PUBLIC_KEY=\nSTOPNETIC_COOKIE_SECRET=\n`,
+  };
+  if (platform === 'netlify') {
+    const toml = text(destination(root, 'netlify.toml'));
+    const build = toml.match(/\[build\]([^]*?)(?=\n\[|$)/)?.[1] || '';
+    if (/^\s*base\s*=/m.test(build)) throw new SetupError('Run from the Netlify base directory and review custom base configuration before using setup.');
+    const section = toml.match(/\[functions\]([^]*?)(?=\n\[|$)/)?.[1] || '';
+    const match = section.match(/^\s*directory\s*=\s*["']([^"']+)["']\s*(?:#.*)?$/m);
+    if (/^\s*directory\s*=/m.test(section) && !match) throw new SetupError('Review your custom Netlify functions directory.');
+    const directory = match?.[1] || 'netlify/functions';
+    destination(root, directory);
+    files[`${directory}/stopnetic.mjs`] = `import { createStopneticAccessHandler } from '@stopnetic/js/server';\nlet access;\nexport default request => (access ??= createStopneticAccessHandler())(request);\nexport const config = { path: ['/api/stopnetic/access', '/api/stopnetic/verify'], preferStatic: false };\n`;
+  } else if (platform === 'vercel') {
+    files['api/stopnetic/[operation].mjs'] = `import { createStopneticAccessHandler } from '@stopnetic/js/server';\nlet access;\nexport default { fetch: request => (access ??= createStopneticAccessHandler())(request) };\n`;
+  } else {
+    files['stopnetic.server.mjs'] = `import { createStopneticServer } from '@stopnetic/js/server';\nexport function installStopnetic(app) {\n  const { access, guard } = createStopneticServer();\n  app.use(access);\n  app.use(guard);\n}\n`;
+  }
+  return files;
+}
+
+export function setup(input, { platform: supplied, dryRun = false } = {}) {
+  const root = realpathSync(resolve(input));
+  const pkg = project(root);
+  if (pkg.dependencies?.next || pkg.devDependencies?.next) throw new SetupError('Use @stopnetic/next for a Next.js project.');
+  const platform = platformFor(root, supplied);
+  const files = filesFor(root, platform);
+  const manifestPath = destination(root, manifestName);
+  let manifest;
+  if (existsSync(manifestPath)) {
+    try { manifest = JSON.parse(text(manifestPath)); } catch { throw new SetupError('Check the existing Stopnetic setup manifest.'); }
+    if (manifest.platform !== platform) throw new SetupError('A different hosting setup already exists. Review it before changing platform.');
+  }
+  const upgraded = new Set();
+  // Validate every destination before making any change. Only an unchanged
+  // older generated guide can be replaced; customer modifications are refused.
+  for (const [name, content] of Object.entries(files)) {
+    const file = destination(root, name);
+    if (existsSync(file) && text(file) !== content) {
+      if (name === 'stopnetic-client-guide.md' && manifest?.files?.[name] === legacyGuideDigest
+        && digest(text(file)) === legacyGuideDigest) upgraded.add(name);
+      else throw new SetupError(`Existing file needs manual merging: ${name}`);
+    }
+  }
+  const local = destination(root, '.env.local');
+  const ignore = destination(root, '.gitignore');
+  const env = environment(root);
+  if (dryRun) return `Dry run: ${platform}; would prepare ${Object.keys(files).join(', ')} and private cookie configuration. No files changed.`;
+  for (const [name, content] of Object.entries(files)) {
+    const file = destination(root, name);
+    mkdirSync(dirname(file), { recursive: true });
+    if (upgraded.has(name)) writeFileSync(file, content);
+    else if (!existsSync(file)) writeFileSync(file, content, { flag: 'wx' });
+  }
+  if (!env.STOPNETIC_COOKIE_SECRET) writeFileSync(local, `${text(local).replace(/\n?$/, '\n')}STOPNETIC_COOKIE_SECRET=${randomBytes(32).toString('base64url')}\n`, { mode: 0o600 });
+  if (!/(^|\n)\.env\.local$/.test(text(ignore).trimEnd())) writeFileSync(ignore, `${text(ignore).replace(/\n?$/, '\n')}.env.local\n`);
+  writeFileSync(manifestPath, JSON.stringify({ v: 1, platform, files: Object.fromEntries(Object.entries(files).map(([name, content]) => [name, digest(content)])) }, null, 2) + '\n');
+  return `Prepared ${platform} setup. Follow stopnetic-client-guide.md, configure server env, wrap protected APIs, build and deploy. Then run stopnetic-js check. No service requests or trial activation occurred.`;
+}
+
+export function checkSetup(input, { localHttp = false } = {}) {
+  const root = realpathSync(resolve(input));
+  let manifest;
+  try { manifest = JSON.parse(text(destination(root, manifestName))); } catch { throw new SetupError('Run stopnetic-js init first.'); }
+  if (manifest.v !== 1 || !['netlify', 'vercel', 'node'].includes(manifest.platform)) throw new SetupError('Invalid setup manifest.');
+  const expected = filesFor(root, manifest.platform);
+  for (const [name, content] of Object.entries(expected)) {
+    if (manifest.files?.[name] !== digest(content) || text(destination(root, name)) !== content) throw new SetupError(`Generated file changed or missing: ${name}`);
+  }
+  try {
+    const options = optionsFromEnv(environment(root));
+    if (!localHttp && !options.origin?.startsWith('https:')) throw new Error();
+    if (!localHttp && !options.apiUrl?.startsWith('https:')) throw new Error();
+    createStopneticAccessHandler(options);
+  } catch { throw new SetupError('Check server settings, HTTPS URLs, installation/signing keys and the separate cookie secret. No secret values are displayed.'); }
+  return `Checked ${manifest.platform} generated files and server configuration offline. Confirm the browser boundary, API wrappers and hosting routing with a deployed test. This does not prove coverage or start a trial.`;
+}