@stopnetic/js 0.0.6-pilot → 0.1.1

package/dist/server.js

@@ -1,123 +1,128 @@
-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` }),
-  };
-}
+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,
+    // The shared parser decodes quotes BEFORE escaped newlines. Decoding here
+    // would turn a valid JSON-quoted PEM into invalid JSON with raw newlines.
+    decisionPublicKey: env.STOPNETIC_DECISION_PUBLIC_KEY,
+    additionalDecisionPublicKeys: parseAdditionalDecisionPublicKeys(env.STOPNETIC_DECISION_ADDITIONAL_PUBLIC_KEYS),
+    cookieSecret: env.STOPNETIC_COOKIE_SECRET,
+    guardMode: 'site',
+    trafficInsights: env.STOPNETIC_TRAFFIC_INSIGHTS === 'true',
+    countryBlocking: env.STOPNETIC_COUNTRY_BLOCKING === 'true',
+    countrySource: env.STOPNETIC_COUNTRY_SOURCE || 'none',
+    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

@@ -1,125 +1,126 @@
-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 legacyGuideDigests = new Set([
-  'b1f149af44f9ceb08fb80c18cb5d4b521620196f536d8ad422ab94d15d1d125d', // 0.0.2
-  '55e36295b6aa87ad9558cde29786998483095adeae74e149ff5c7fe78507fad7', // published 0.0.3
-  '08f919257d8c85af4e56e842705825832ae2810ed68d5c1dfc8405c8f7be7610', // published 0.0.4
-  '45bd696f196c3d1447a978987a787755b239f75e9e6a3697f4efbb210ce75597', // published 0.0.5
-]);
-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) {
-      const recorded = manifest?.files?.[name];
-      if (name === 'stopnetic-client-guide.md' && legacyGuideDigests.has(recorded)
-        && digest(text(file)) === recorded) 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 server page enforcement, your chosen navigation mode, API wrappers and hosting routing with a deployed test. Preserve existing SSR; browser gates are optional. This does not prove coverage or start a trial.`;
-}
+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 legacyGuideDigests = new Set([
+  'b1f149af44f9ceb08fb80c18cb5d4b521620196f536d8ad422ab94d15d1d125d', // 0.0.2
+  '55e36295b6aa87ad9558cde29786998483095adeae74e149ff5c7fe78507fad7', // published 0.0.3
+  '08f919257d8c85af4e56e842705825832ae2810ed68d5c1dfc8405c8f7be7610', // published 0.0.4
+  '45bd696f196c3d1447a978987a787755b239f75e9e6a3697f4efbb210ce75597', // published 0.0.5
+  'a5b2c1100ff704c2675feb6fecb50cf7371dda446b33d4655d43089bfba14a2e', // published 0.0.6
+]);
+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) {
+      const recorded = manifest?.files?.[name];
+      if (name === 'stopnetic-client-guide.md' && legacyGuideDigests.has(recorded)
+        && digest(text(file)) === recorded) 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 server page enforcement, your chosen navigation mode, API wrappers and hosting routing with a deployed test. Preserve existing SSR; browser gates are optional. This does not prove coverage or start a trial.`;
+}

package/dist/traffic-context.js

@@ -0,0 +1,26 @@
+// Only broad categories leave the customer's server. No IP or raw user-agent.
+export const countryCodes = 'AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW'.split(' ');
+const countries = new Set(countryCodes);
+
+function deviceCategory(value) {
+  if (!value || value.length > 1024 || /bot|crawler|spider|curl|wget|python|headless/i.test(value)) return 'unknown';
+  if (/ipad|tablet|kindle|silk\/|playbook/i.test(value) || (/android/i.test(value) && !/mobile/i.test(value))) return 'tablet';
+  if (/mobi|iphone|ipod|windows phone/i.test(value)) return 'mobile';
+  if (/mozilla\//i.test(value) && /windows nt|macintosh|x11|cros/i.test(value)) return 'desktop';
+  return 'unknown';
+}
+
+export function trafficContext(request, enabled, source) {
+  if (!enabled) return undefined;
+  try {
+    // Selecting a source is an explicit deployment trust decision. Never auto-detect
+    // providers from visitor-supplied headers. Origins behind Cloudflare must reject
+    // direct traffic or strip/rewrite these headers at their trusted ingress.
+    const value = source === 'vercel' ? request.headers.get('x-vercel-ip-country')
+      : source === 'cloudflare' ? request.headers.get('cf-ipcountry') : null;
+    const country = typeof value === 'string' && value.length === 2 && countries.has(value.toUpperCase()) ? value.toUpperCase() : null;
+    return { country, device: deviceCategory(request.headers.get('user-agent')), country_source: country ? source : 'unknown' };
+  } catch {
+    return { country: null, device: 'unknown', country_source: 'unknown' };
+  }
+}

package/examples/frontend/angular/app/app.config.ts

@@ -1,8 +1,8 @@
-import { ApplicationConfig } from '@angular/core';
-import { provideHttpClient } from '@angular/common/http';
-import { provideRouter } from '@angular/router';
-import { routes } from './app.routes';
-export const appConfig: ApplicationConfig = {
-  providers: [provideRouter(routes), provideHttpClient()],
-};
-// Merge these providers into your existing appConfig; retain its other settings.
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient } from '@angular/common/http';
+import { provideRouter } from '@angular/router';
+import { routes } from './app.routes';
+export const appConfig: ApplicationConfig = {
+  providers: [provideRouter(routes), provideHttpClient()],
+};
+// Merge these providers into your existing appConfig; retain its other settings.