@stopnetic/js 0.1.0 → 0.1.1

package/README.md

@@ -1,11 +1,38 @@
 # @stopnetic/js - JavaScript and TypeScript website guard
 
+Unreleased country controls: server options `countryBlocking: true` and a trusted
+`countrySource` enable the compatible protocol. The `/server` environment helper
+also reads `STOPNETIC_COUNTRY_BLOCKING=true`. Deploy and test guarded requests
+before enabling the country policy in the dashboard. Remove local `publicPaths`
+bypasses and secure your ingress/origin. Published 0.1.0 lacks this feature.
+See [setup, recovery and coverage limits](../../docs/country-access.md).
+
 Stopnetic checks access **on your server before sending pages, files or API data**.
 Use it with Node.js and Express, with frontend examples for Angular, React, Vue,
 Svelte, Solid and plain JavaScript. No frontend framework is a required dependency.
 Your hosting server must run **Node.js 22 or newer**; browser-only JavaScript does
 not enforce protection on its own. Keep your existing SSR or static rendering.
 
+## Optional traffic insights (unreleased)
+
+The working tree supports `trafficInsights: true` and
+`countrySource: 'none' | 'vercel' | 'cloudflare'` in server guard options. The
+`@stopnetic/js/server` helpers also read `STOPNETIC_TRAFFIC_INSIGHTS=true` and
+`STOPNETIC_COUNTRY_SOURCE=none` from the website's server environment. These
+settings are optional and collection is off by default. Published 0.1.0 does
+not send these fields; use a compatible future release or local packed SDK.
+
+Only a country code/source and broad device category are sent. No raw IPs or full
+user-agent strings leave the server for this feature, and no network location
+lookup is made. Unsupported sources/devices remain Unknown. Reported metadata
+is approximate and does not authorize requests or identify people/bots.
+
+Explicitly trust a country source only on the correct hosting ingress. For
+Cloudflare, prevent direct-origin access or strip and rewrite visitor-supplied
+headers. Deploy compatible service ingestion before updating and deploying the
+website's guard. Disabling collection stops new context; stored context follows
+the event retention/deletion policy.
+
 ## Install
 
 Run inside your website project:

package/dist/guard.d.ts

@@ -13,6 +13,13 @@ export type StopneticOptions = {
   timeoutMs?: number;
   publicPaths?: string[];
   reportEvents?: boolean;
+  /** Optional coarse request analytics. No raw visitor IP or user-agent is sent. */
+  trafficInsights?: boolean;
+  /** Opt into country controls; requires trusted countrySource and no publicPaths. */
+  countryBlocking?: boolean;
+  /** Explicitly trust country headers from your ingress; default none. Cloudflare
+   * origins must prevent direct requests/header spoofing. */
+  countrySource?: 'none' | 'vercel' | 'cloudflare';
   /** Whole-site mode: unmatched routes public; requires the updated service. */
   guardMode?: 'selected' | 'site';
 };

package/dist/guard.js

@@ -1,5 +1,6 @@
 import { createHash, createHmac, randomBytes, timingSafeEqual, verify as verifySignature } from 'node:crypto';
 import { trustedSigningKeys } from './signing-keys.js';
+import { trafficContext } from './traffic-context.js';
 export { parseAdditionalDecisionPublicKeys } from './signing-keys.js';
 
 const unavailable = retryAfter => new Response(null, { status: 503, headers: {
@@ -62,14 +63,14 @@ function bootstrap(ticket, verifyPath) {
 
 /** Pilot guard for server-side Next.js Proxy and Route Handlers. */
 export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, additionalDecisionPublicKeys = [], cookieSecret, verifyPath = '/__stopnetic/verify',
-  cookieName = 'stopnetic_pilot_session', secureCookie = true, fetchImpl = fetch, timeoutMs = 2000, publicPaths = [], reportEvents = true, guardMode = 'selected' }) {
+  cookieName = 'stopnetic_pilot_session', secureCookie = true, fetchImpl = fetch, timeoutMs = 2000, publicPaths = [], reportEvents = true, guardMode = 'selected', trafficInsights = false, countrySource = 'none', countryBlocking = false }) {
   if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(siteId || '')) throw new Error('Invalid siteId');
   const credential = typeof apiToken === 'string' ? apiToken.match(/^[a-z]{1,32}_([a-f0-9]{32})\.[A-Za-z0-9_-]{43}$/) : null;
   if (!credential) throw new Error('apiToken must be an issued installation key');
   const installationId = credential[1];
-  if (typeof cookieSecret !== 'string' || cookieSecret.trim().length < 32
-    || /^<[^]*>$/.test(cookieSecret.trim())) throw new Error('cookieSecret must be at least 32 characters');
-  if (cookieSecret === apiToken) throw new Error('cookieSecret must be independent of apiToken');
+  if (typeof cookieSecret !== 'string' || cookieSecret.trim().length < 32
+    || /^<[^]*>$/.test(cookieSecret.trim())) throw new Error('cookieSecret must be at least 32 characters');
+  if (cookieSecret === apiToken) throw new Error('cookieSecret must be independent of apiToken');
   const endpoint = new URL(apiUrl);
   if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) throw new Error('Invalid apiUrl');
   if (endpoint.protocol !== 'https:' && !(endpoint.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(endpoint.hostname))) {
@@ -79,8 +80,12 @@ export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, a
   if (!/^[a-zA-Z0-9_-]+$/.test(cookieName)) throw new Error('Invalid cookieName');
   if (!Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 10000) throw new Error('Invalid timeoutMs');
   if (typeof reportEvents !== 'boolean') throw new Error('Invalid reportEvents');
+  if (typeof trafficInsights !== 'boolean') throw new Error('Invalid trafficInsights');
+  if (!['none', 'vercel', 'cloudflare'].includes(countrySource)) throw new Error('Invalid countrySource');
   if (!Array.isArray(publicPaths) || publicPaths.some(path => typeof path !== 'string' || !/^\/[a-zA-Z0-9_\-/.]*(?:\*)?$/.test(path))) throw new Error('Invalid publicPaths');
   if (!['selected', 'site'].includes(guardMode)) throw new Error('Invalid guardMode');
+  if (typeof countryBlocking !== 'boolean') throw new Error('Invalid countryBlocking');
+  if (countryBlocking && (countrySource === 'none' || publicPaths.length)) throw new Error('countryBlocking requires an explicit countrySource and no publicPaths bypasses');
   const publicKeys = trustedSigningKeys(decisionPublicKey, additionalDecisionPublicKeys);
   const verifyEndpoint = new URL('./verify', endpoint);
   const eventsEndpoint = new URL('./events', endpoint);
@@ -120,6 +125,15 @@ export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, a
       || !Number.isSafeInteger(payload.issued_at) || !Number.isSafeInteger(payload.expires_at)
       || payload.issued_at > now + 5000 || payload.expires_at <= now || payload.expires_at <= payload.issued_at
       || payload.expires_at - payload.issued_at > 30_000) throw new Error('Invalid decision context or expiry');
+    if (countryBlocking) {
+      const control = payload.country_control;
+      const country = payload.country_decision;
+      if (!control || control.version !== 1 || control.source !== input.country_control?.source || control.country !== input.country_control?.country
+        || !country || country.version !== 1 || !['disabled', 'pass', 'country_blocked', 'country_unknown_blocked', 'country_guard_required'].includes(country.result)
+        || (country.revision !== null && (typeof country.revision !== 'string' || !/^[a-f0-9-]{36}$/.test(country.revision)))
+        || (country.result !== 'disabled' && country.revision === null)
+        || (!['disabled', 'pass'].includes(country.result) && payload.action !== 'block')) throw new Error('Invalid country decision');
+    }
     return { ...payload, receipt: envelope.decision };
   }
 
@@ -139,27 +153,33 @@ export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, a
     const value = cookieValue(request, cookieName);
     const payload = verified(value, cookieSecret);
     const binding = browserBinding(request);
-    return payload?.kind === 'session' && payload.site === siteId && payload.installation === installation
-      && binding && payload.browser_hash === hash(binding) ? payload : null;
+    return payload?.kind === 'session' && payload.site === siteId && payload.installation === installation
+      && binding && payload.browser_hash === hash(binding) ? payload : null;
+  }
+
+  function countryControl(request) {
+    return countryBlocking ? { country_control: { version: 1, source: countrySource,
+      country: trafficContext(request, true, countrySource).country } } : {};
   }
 
   async function check(request) {
     const path = new URL(request.url).pathname;
     if (path === verifyPath) return null;
     if (publicPaths.some(rule => rule.endsWith('*') ? path.startsWith(rule.slice(0, -1)) : path === rule)) return null;
-    const session = validSession(request);
-    // Only link access to the page that originally requested this challenge.
-    // Sessions still authorize other configured routes without attributing them
-    // to this page's verification outcome. Legacy sessions remain usable.
-    const challenge = session?.challenge_path === path && /^[A-Za-z0-9_-]{43}$/.test(session.challenge_id || '')
-      ? session.challenge_id : null;
+    const session = validSession(request);
+    // Only link access to the page that originally requested this challenge.
+    // Sessions still authorize other configured routes without attributing them
+    // to this page's verification outcome. Legacy sessions remain usable.
+    const challenge = session?.challenge_path === path && /^[A-Za-z0-9_-]{43}$/.test(session.challenge_id || '')
+      ? session.challenge_id : null;
     const eligible = request.method === 'GET' && (request.headers.get('accept') || '').includes('text/html');
-    const binding = challenge ? browserBinding(request)
-      : !session && eligible ? browserBinding(request) || randomBytes(32).toString('base64url') : null;
+    const binding = challenge ? browserBinding(request)
+      : !session && eligible ? browserBinding(request) || randomBytes(32).toString('base64url') : null;
     let policy;
     try {
-      policy = await remote('decision', { path, method: request.method, ...(guardMode === 'site' ? { guard_mode: 'site' } : {}), ...(binding ? { browser_binding: binding } : {}),
-        ...(challenge ? { session_challenge: challenge } : {}) });
+      const context = trafficContext(request, trafficInsights, countrySource);
+      policy = await remote('decision', { path, method: request.method, ...countryControl(request), ...(context ? { traffic_context: context } : {}), ...(guardMode === 'site' ? { guard_mode: 'site' } : {}), ...(binding ? { browser_binding: binding } : {}),
+        ...(challenge ? { session_challenge: challenge } : {}) });
     } catch (error) { return unavailable(error?.retryAfter); }
     if (!policy || !['public', 'block', 'human', 'verified', 'entitled', 'default'].includes(policy.action)) return unavailable();
     // An older service must not silently apply selected-path semantics here.
@@ -199,13 +219,17 @@ export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, a
       || typeof payload.path !== 'string' || !/^\/[^\s?#]*$/.test(payload.path) || !binding
       || payload.browser_hash !== hash(binding) || !/^[A-Za-z0-9_-]{43}$/.test(payload.challenge_id || '')) return concealed();
     try {
-      const result = await remote('verify', { path: payload.path, method: 'POST', challenge_id: payload.challenge_id, browser_binding: binding });
+      const result = await remote('verify', { path: payload.path, method: 'POST', challenge_id: payload.challenge_id, browser_binding: binding, ...countryControl(request) });
+      if (result.action === 'block' && result.country_decision && !['disabled', 'pass'].includes(result.country_decision.result)) {
+        await report(result, 'BLOCK');
+        return concealed();
+      }
       if (result.action !== 'verified' || result.challenge_id !== payload.challenge_id) return unavailable();
       await report(result, 'VERIFIED');
     } catch (error) { return unavailable(error?.retryAfter); }
-    const session = signed({ v: 1, kind: 'session', site: siteId, installation,
-      browser_hash: hash(binding), challenge_id: payload.challenge_id, challenge_path: payload.path,
-      exp: Date.now() + 300_000 }, cookieSecret);
+    const session = signed({ v: 1, kind: 'session', site: siteId, installation,
+      browser_hash: hash(binding), challenge_id: payload.challenge_id, challenge_path: payload.path,
+      exp: Date.now() + 300_000 }, cookieSecret);
     return new Response(null, { status: 204, headers: {
       'cache-control': 'no-store',
       'set-cookie': cookie(cookieName, session, 300),

package/dist/index.js

@@ -96,6 +96,13 @@ function requestHeaders(req, origin) {
     if (value !== undefined) headers.set(name, value);
   }
   headers.set('host', new URL(origin).host);
+  for (const name of ['user-agent', 'x-vercel-ip-country', 'cf-ipcountry']) {
+    const value = req.headers[name];
+    // Optional analytics must not turn malformed metadata into an access failure.
+    if (typeof value === 'string' && value.length <= (name === 'user-agent' ? 1024 : 2)) {
+      try { headers.set(name, value); } catch { /* Leave unsupported metadata unknown. */ }
+    }
+  }
   return headers;
 }
 

package/dist/server.js

@@ -15,6 +15,9 @@ export function optionsFromEnv(env = process.env) {
     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`,
   };
 }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stopnetic/js",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Server-side Stopnetic guard for JavaScript websites, Node.js and Express-compatible servers.",
   "type": "module",
   "license": "MIT",