@stopnetic/js 0.0.0-stage → 0.0.2-pilot

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stopnetic
+
+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

@@ -1,3 +1,322 @@
-# Temporary Holding Version
+# @stopnetic/js — JavaScript website guard
+
+Stopnetic checks access **on your server before sending pages, files or API data**.
+Your frontend can be Angular, Vue, React, Svelte, plain JavaScript, or an older
+frontend build. No React/Vue/Angular dependency or version upgrade is required.
+The hosting server must run Node.js 22 or newer. This is an MIT-licensed pilot SDK;
+hosted production/provider validation is still required before paid rollout.
+
+Version **0.0.1-pilot is published** on npm. This repository prepares
+**0.0.2-pilot**, which adds a reusable browser/server setup for Netlify, Vercel
+and Node/Express, a browser access check and optional React boundary. It also
+normalizes public PEM formatting and rejects placeholder or reused installation
+keys as cookie secrets. The new version is not published yet. Install the
+currently published manual server pilot with:
+
+```sh
+npm install @stopnetic/js@pilot
+```
+
+For local testing, build and pack from this repository:
+
+```sh
+cd integrations/javascript
+npm run build
+npm pack
+```
+
+Install the resulting `stopnetic-js-0.0.2-pilot.tgz` into the website project using
+`npm install <absolute-path-to-tarball>`. The installed package has no Next.js or
+other runtime dependency. The build packages the same signed decision implementation
+as the Next.js adapter. Keep `@stopnetic/next` for its Next.js 16 guided installer.
+
+## Reusable client/server setup (requires 0.0.2-pilot)
+
+Use the local tarball above until this version is published. Installing the current
+registry pilot (0.0.1) does not provide these new commands or subpath exports.
+
+Run setup at the app's package.json, choose hosting, and preview before writing:
+
+```sh
+npm exec --no -- stopnetic-js init --platform netlify --dry-run
+npm exec --no -- stopnetic-js init --platform netlify
+```
+
+Use `--platform vercel` or `--platform node` for the other adapters. Netlify/Vercel
+configuration files can select a platform automatically; ambiguous projects need
+explicit selection. Next.js projects use `@stopnetic/next`. This SDK needs a
+Node.js 22+ runtime; it does not run as a Deno/Workers/Edge function.
+
+Setup prepares a server control endpoint, `.env.stopnetic.example`, an ignored
+`.env.local` cookie secret, a setup manifest and `stopnetic-client-guide.md`.
+It does not install dependencies, edit your React app, overwrite existing files,
+contact providers or deploy. Changed generated files require manual merging.
+Custom Netlify base directories require review; custom functions directories are
+preserved. Vercel configuration is preserved. Put runtime settings in the hosting
+provider's server/Functions environment; plain `netlify.toml` build env is not a
+Functions secret store. Copy the generated cookie secret without committing it.
+
+Wire browser route checks and EACH protected API following the generated guide.
+Run `npm exec --no -- stopnetic-js check` after setting credentials (`--local-http`
+for a loopback pilot). This check validates configuration and generated files
+offline; it cannot prove deployment routing, API coverage or browser integration.
+Deploy once, then dashboard changes apply on subsequent guarded requests.
+
+Test locally with `netlify dev` or `vercel dev`, which must run both the frontend
+and server functions; Vite alone does not provide the generated server endpoints.
+For Node, use `node --env-file=.env.local your-server.mjs` or your existing
+server environment loader. Production credentials belong in runtime settings.
+
+### React Router
+
+The optional React entry uses Hooks. The core/browser modules need no React.
+Place this component inside BrowserRouter, wrapping your Routes:
+
+```jsx
+import { useLocation } from 'react-router-dom';
+import { StopneticBoundary } from '@stopnetic/js/react';
+
+function RouteGuard({ children }) {
+  const location = useLocation();
+  return <StopneticBoundary path={location.pathname + location.search}>
+    {children}
+  </StopneticBoundary>;
+}
+// <BrowserRouter><RouteGuard><Routes>...</Routes></RouteGuard></BrowserRouter>
+```
+
+The boundary hides children while checking, ignores canceled/stale checks and
+redirects to same-origin verification when required. Block/outage displays a
+denial; customize `pending` and `blocked` with your UI. Vue, Angular, Svelte and
+plain JS can await `checkAccess(path)` from `@stopnetic/js/browser` and use
+`result.allowed`, `result.reason` and `result.verificationUrl` in their router.
+This is a UI check, never an authorization credential for a data request.
+
+### Netlify / Vercel APIs
+
+Import server helpers only in server files. Wrap every protected function before
+it loads/returns data, keeping your application's own login/data permissions:
+
+```js
+import { withStopnetic } from '@stopnetic/js/server';
+const api = withStopnetic(async request => {
+  // Enforce application permissions, then retrieve private data here.
+  return Response.json({ example: true });
+});
+// Netlify function:
+export default api;
+export const config = { path: '/api/private', preferStatic: false };
+// Vercel api/private.mjs instead: export default { fetch: api };
+```
+
+Netlify's default `/.netlify/functions/` aliases are rejected by this wrapper
+so they cannot bypass rules on a custom path. Use custom `config.path` endpoints
+in your frontend and Policies. Keep the generated `/api/stopnetic/access` and
+`/api/stopnetic/verify` endpoints reachable before any SPA catch-all. The access
+endpoint checks the requested page using signed decisions, establishes browser
+verification and redirects back to the same origin. It never returns private
+content or an API authorization token. API wrappers independently check every
+request and preserve ordinary request bodies. Denials/outages return empty
+404/503 responses; approved data responses use `private, no-store`.
+
+### Node servers on other hosts
+
+Import `installStopnetic` from generated `stopnetic.server.mjs`, then call
+`installStopnetic(app)` before Express parsers, static files, SPA fallback and
+API handlers. This checks the control endpoints and the rest of the server.
+It can run on any host supporting Node.js 22+, not just Netlify/Vercel. For a
+custom Fetch-based Node framework, use the shared `createStopneticAccessHandler`
+and `withStopnetic` in its request hooks. Existing low-level adapters remain
+available below with their original default-blocking behavior.
+
+### Rules and the protection boundary
+
+The generated setup opts into dashboard-managed mode: unmatched guarded requests
+are public. Add explicit Page / Automatic browser flow rules and API / Require
+verified session rules. Keep private data exclusively in guarded APIs. An API
+fetch does not start browser verification; it needs the established same-origin
+cookie. Static HTML/JavaScript, routes without a browser boundary, external APIs,
+unwrapped handlers, alternate hosts and previously loaded content are not made
+private by this setup. No installer can hide content already in a public bundle.
+Browser automation can still complete verification. Test your actual provider,
+custom-domain routing, redirects, cookies, caches and direct API access before
+rollout. Hosting contracts are simulated locally; live provider tests are pending.
+
+## Which installation fits my site?
+
+| Site | Where to install |
+| --- | --- |
+| Angular, Vue, React, Svelte SPA or plain HTML/JS | Node/Express server serving its built output, before static files and SPA fallback |
+| Existing Node/Express server, including Express 4 and 5 | First root middleware, before body parsers, routes and data handlers |
+| Node-hosted framework with Web `Request`/`Response` hooks | `createStopneticHandler` before the framework renders or serves data |
+| Next.js 16 App Router | Published `@stopnetic/next@pilot` and its guided installer |
+| Older Next.js with a customer-owned Node server | Generic middleware before the Next request handler; native older Next installers are not supplied |
+| Static-only hosting / browser-only scripts | Needs a server or compatible edge/proxy in front, or a separately protected content API |
+
+Do not import this SDK in browser components or add a public `<script>` containing
+your installation key. Hiding a screen cannot protect HTML, JS bundles or data that
+the hosting provider already serves publicly. This package uses `node:crypto`; it
+is not a Cloudflare Workers/browser/Edge-runtime adapter. Framework-native SSR
+adapters and serverless platform wiring need their own deployment validation.
+
+## Server configuration
+
+Add a site in Stopnetic, verify its domain, and create an installation key in
+Integration. Site ID identifies your website; the private installation key
+authenticates it. Copy the service public signing key from Integration too.
+Set these **server-only** environment variables, using your actual URLs and keys:
+
+```dotenv
+STOPNETIC_WEBSITE_ORIGIN=https://www.example.com
+STOPNETIC_SITE_ID=<generated-site-id>
+STOPNETIC_API_URL=https://<your-stopnetic-service>/api/integration/decision
+STOPNETIC_API_TOKEN=<your-one-time-installation-key>
+STOPNETIC_DECISION_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n<service-public-key>\n-----END PUBLIC KEY-----\n"
+STOPNETIC_COOKIE_SECRET=<separate-random-secret-at-least-32-characters>
+```
+
+Generate the cookie secret with
+`node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"`.
+Never use frontend prefixes such as `VITE_`, `NEXT_PUBLIC_` or `REACT_APP_` for secrets.
+The optional `STOPNETIC_DECISION_ADDITIONAL_PUBLIC_KEYS` is a JSON array of at most
+two explicitly trusted public PEMs for staged signing-key rotation.
+
+The origin is the public website's protocol and hostname, with an optional port.
+No `/home`, credentials, query or fragment. HTTPS is required except on localhost.
+Configure your TLS proxy to preserve the public `Host` header and keep the backend
+private. The adapter uses the configured origin and never trusts forwarded host or
+protocol headers. HTTPS origins always produce secure cookies; HTTP localhost
+origins automatically use development cookies.
+
+## Node/Express middleware
+
+```js
+import express from 'express';
+import { createStopneticMiddleware, parseAdditionalDecisionPublicKeys } from '@stopnetic/js';
+
+const app = express();
+app.set('case sensitive routing', true);
+app.set('strict routing', true);
+app.use(createStopneticMiddleware({
+  origin: process.env.STOPNETIC_WEBSITE_ORIGIN,
+  siteId: process.env.STOPNETIC_SITE_ID,
+  apiUrl: process.env.STOPNETIC_API_URL,
+  apiToken: process.env.STOPNETIC_API_TOKEN,
+  decisionPublicKey: process.env.STOPNETIC_DECISION_PUBLIC_KEY?.replaceAll('\\n', '\n'),
+  additionalDecisionPublicKeys: parseAdditionalDecisionPublicKeys(process.env.STOPNETIC_DECISION_ADDITIONAL_PUBLIC_KEYS),
+  cookieSecret: process.env.STOPNETIC_COOKIE_SECRET,
+}));
+// Your existing application follows the guard.
+app.use(express.json());
+app.post('/api/private', yourExistingApiHandler);
+app.use(express.static('dist', { dotfiles: 'deny', cacheControl: false }));
+// Add your existing guarded SPA fallback here.
+app.listen(8080);
+```
+
+Install `express` separately in your website if needed. The repository includes
+`integrations/javascript/examples/express-server.mjs` for a complete SPA server.
+Serve only the build output directory (`dist`, `build`, or Angular's browser output),
+never your project root. A framework-independent fallback after your static middleware:
+
+```js
+app.use((req, res) => {
+  if (req.method === 'GET' && req.get('accept')?.includes('text/html')
+    && !req.path.startsWith('/api/') && !req.path.split('/').some(p => p.startsWith('.'))) {
+    res.sendFile('index.html', { root: absoluteBuildDirectory, cacheControl: false });
+  } else res.status(404).end();
+});
+```
+
+Place the guard **first at the root**, before body parsers and before anything can
+send bytes. It checks every request except explicitly configured `publicPaths`.
+Ordinary POST bodies stay intact for your application's parser. The same middleware
+handles `/__stopnetic/verify`; do not mount it only on `/members`.
+
+With Node's built-in HTTP server, the same middleware works without Express:
+
+```js
+import { createServer } from 'node:http';
+const protect = createStopneticMiddleware(options);
+createServer((req, res) => {
+  void protect(req, res, () => existingApplication(req, res)).catch(() => res.destroy());
+}).listen(8080);
+```
+
+For an older CommonJS application, initialize at startup with
+`const { createStopneticMiddleware } = await import('@stopnetic/js')` inside an async
+function. Only the server runtime needs to meet the minimum version; the frontend
+framework can remain unchanged.
+
+## Request/Response hook
+
+```js
+import { createStopneticHandler } from '@stopnetic/js';
+const protect = createStopneticHandler(options); // same options, including origin
+
+export async function handle({ request, resolve }) {
+  return protect(request, checkedRequest => resolve(checkedRequest));
+}
+```
+
+Wire this function to the Node-hosted framework's actual request hook. For SvelteKit,
+the hook receives an `event`, so use
+`protect(event.request, () => resolve(event))` in `hooks.server.js`. The request URL
+must contain the configured public origin. Configure the framework's trusted proxy
+settings explicitly. This is a generic hook example, not a tested matrix of all
+SvelteKit/Nuxt/framework releases.
+
+## Policies, failures and hosting
+
+In Policies, choose public, automatic browser flow, verified session, or blocked
+routes. Automatic flow serves a short verification page first, then a cookie-bound
+session; requests from ordinary fetchers and non-navigation clients get no protected
+bytes. Browser-capable automation may complete the challenge. Your application must
+still enforce its own sign-in, membership and purchase permissions. Entitlement
+rules are not implemented and withhold content.
+
+Both adapters automatically route verification, bound its body to 4 KiB and five
+seconds, and reject foreign origins. Protected requests fail closed with empty
+404/503 responses on denial, malformed signed decisions or service outages. Approved
+application responses receive `Cache-Control: private, no-store`; middleware users
+must keep that header in their downstream handlers. Prevent CDN, prerendered files,
+service workers or another origin from serving protected content before the guard.
+WebSockets/upgrades are not covered; protect them separately or disable them.
+
+By default **all paths are checked**, including assets and APIs. Optional local
+`publicPaths: ['/health', '/public/*']` bypass the policy service even during outages.
+Use only paths deliberately intended to remain public. Ambiguous encoded separators,
+dot segments, encoded ASCII characters, repeated slashes and malformed targets are
+rejected by the Node middleware. Policy paths are case sensitive. Match your router's
+case/slash behavior to the policies, cover directory-index and other aliases, and
+keep the service's default blocking behavior. Avoid a broad public catch-all that
+could expose an alternative path to protected content.
+
+An installed guard's first valid request starts the site's account trial. Key
+rotation/revocation and domain/account/subscription gates are checked by the service.
+Access reports are best effort and cannot establish delivery guarantees.
+With the updated dashboard, prepared 0.0.2 links same-page challenges, verification
+and the first reported access result. The Challenge outcomes panel distinguishes
+allowed, blocked, waiting, not completed and verified without an access result;
+older evidence may be unavailable. It does not identify humans or bots. Install
+the updated SDK on your server after deploying the dashboard update.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Validate your actual hosting, cache rules, browser flow, API paths and provider configuration
+before onboarding paying customers.
+
+## Maintainer checks and release
+
+From this folder: `npm ci`, `npm test`, `npm run test:package`. Tests include real
+Node HTTP traffic, Express 4/5 static/SPA/API serving, challenges, body preservation,
+signed decision failures and package consumption from ESM, CommonJS and TypeScript.
+The tarball includes only `dist`, README, MIT license and manifest. No secrets,
+examples, tests, build scripts or dashboard are published. Build from the repository
+before packing; published consumers do not need the repository or build scripts.
+
+Publishing is a separate owner step after these checks:
+
+```sh
+npm publish --access public --tag pilot --registry=https://registry.npmjs.org/
+```
+
+Publishing this package does not update the existing `@stopnetic/next` release.

package/bin/stopnetic-js.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { setup, checkSetup, SetupError } from '../dist/setup.js';
+const help = `Stopnetic JavaScript setup — Node.js 22+
+  stopnetic-js init --platform netlify|vercel|node [--dry-run]
+  stopnetic-js check [--local-http]
+
+Netlify/Vercel config files can select the platform automatically. Explicit
+selection is otherwise required. Setup creates a server control endpoint,
+browser/API integration guide and a private cookie secret, preserving customer
+files. Follow the guide to wire route checks and EACH protected API. The package
+does not make bundled frontend content private. Server settings stay out of
+browser code. No network calls, package installation or deployment occurs.
+`;
+try {
+  const [operation, ...args] = process.argv.slice(2);
+  if (!operation || ['help', '-h', '--help'].includes(operation)) process.stdout.write(help);
+  else {
+    if (!['init', 'check'].includes(operation)) throw new SetupError('Choose init or check. Use --help for usage.');
+    const options = {};
+    for (let index = 0; index < args.length; index++) {
+      const flag = args[index];
+      if (flag === '--platform' && operation === 'init' && !options.platform) {
+        options.platform = args[++index];
+        if (!options.platform) throw new SetupError('Choose netlify, vercel or node after --platform.');
+      } else if (flag === '--dry-run' && operation === 'init') options.dryRun = true;
+      else if (flag === '--local-http' && operation === 'check') options.localHttp = true;
+      else throw new SetupError('Unsupported option. Use --help for usage.');
+    }
+    process.stdout.write((operation === 'init' ? setup(process.cwd(), options) : checkSetup(process.cwd(), options)) + '\n');
+  }
+} catch (error) {
+  process.stderr.write((error instanceof SetupError ? error.message : 'Setup failed. Check project files and permissions.') + '\n');
+  process.exitCode = 1;
+}

package/dist/browser.d.ts

@@ -0,0 +1,4 @@
+export type AccessResult = { allowed: true } | {
+  allowed: false; reason: 'blocked' | 'unavailable' | 'verification_required'; verificationUrl?: string;
+};
+export function checkAccess(path: string, options?: { signal?: AbortSignal; fetchImpl?: typeof fetch }): Promise<AccessResult>;

package/dist/browser.js

@@ -0,0 +1,21 @@
+// Browser-only entry: no Node imports, installation keys or cookie secrets.
+export async function checkAccess(path, { signal, fetchImpl = globalThis.fetch } = {}) {
+  if (typeof path !== 'string' || !path.startsWith('/') || path.startsWith('//') || /[\\\s#]/.test(path)) throw new Error('Use a same-origin page path');
+  const url = `/api/stopnetic/access?${new URLSearchParams({ path, mode: 'check' })}`;
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (signal?.aborted) abort();
+  signal?.addEventListener('abort', abort, { once: true });
+  const timer = setTimeout(abort, 10000);
+  let response, result;
+  try {
+    response = await fetchImpl(url, { credentials: 'same-origin', cache: 'no-store', signal: controller.signal, headers: { Accept: 'application/json' } });
+    result = await response.json();
+  } catch (error) { if (signal?.aborted) throw error; return { allowed: false, reason: 'unavailable' }; }
+  finally { clearTimeout(timer); signal?.removeEventListener('abort', abort); }
+  if (response.status === 200 && result?.allowed === true) return { allowed: true };
+  if (response.status === 404 && result?.reason === 'verification_required') {
+    return { allowed: false, reason: 'verification_required', verificationUrl: `/api/stopnetic/access?${new URLSearchParams({ path })}` };
+  }
+  return { allowed: false, reason: response.status === 404 ? 'blocked' : 'unavailable' };
+}

package/dist/guard.d.ts

@@ -0,0 +1,23 @@
+export type StopneticOptions = {
+  siteId: string;
+  apiUrl: string;
+  apiToken: string;
+  decisionPublicKey: string;
+  /** Explicitly trusted replacement/retiring public PEMs, at most two. */
+  additionalDecisionPublicKeys?: string[];
+  cookieSecret: string;
+  verifyPath?: string;
+  cookieName?: string;
+  secureCookie?: boolean;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+  publicPaths?: string[];
+  reportEvents?: boolean;
+  /** Whole-site mode: unmatched routes public; requires the updated service. */
+  guardMode?: 'selected' | 'site';
+};
+export function parseAdditionalDecisionPublicKeys(value?: string): string[];
+export function createStopnetic(options: StopneticOptions): {
+  check(request: Request): Promise<Response | null>;
+  verify(request: Request): Promise<Response>;
+};

package/dist/guard.js

@@ -0,0 +1,216 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual, verify as verifySignature } from 'node:crypto';
+import { trustedSigningKeys } from './signing-keys.js';
+export { parseAdditionalDecisionPublicKeys } from './signing-keys.js';
+
+const unavailable = retryAfter => new Response(null, { status: 503, headers: {
+  'cache-control': 'no-store', ...(retryAfter ? { 'retry-after': String(retryAfter) } : {}),
+} });
+const concealed = () => new Response(null, { status: 404, headers: { 'cache-control': 'no-store' } });
+const hash = value => createHash('sha256').update(value).digest('hex');
+
+function signed(payload, secret) {
+  const data = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const mac = createHmac('sha256', secret).update(data).digest('base64url');
+  return `${data}.${mac}`;
+}
+
+function verified(token, secret) {
+  if (!token || typeof token !== 'string' || token.length > 8192) return null;
+  const [data, mac, extra] = token.split('.');
+  if (!data || !mac || extra) return null;
+  const expected = createHmac('sha256', secret).update(data).digest();
+  let supplied;
+  try { supplied = Buffer.from(mac, 'base64url'); } catch { return null; }
+  if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(data, 'base64url').toString('utf8'));
+    return payload?.v === 1 && Number.isSafeInteger(payload.exp) && payload.exp > Date.now() ? payload : null;
+  } catch { return null; }
+}
+
+function cookieValue(request, name) {
+  const found = (request.headers.get('cookie') || '').split(';').map(part => part.trim())
+    .find(part => part.startsWith(`${name}=`));
+  return found ? found.slice(name.length + 1) : null;
+}
+
+async function limitedBody(request, maxBytes) {
+  const reader = request.body?.getReader();
+  if (!reader) throw new Error('Missing body');
+  const chunks = [];
+  let length = 0;
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    length += value.byteLength;
+    if (length > maxBytes) { await reader.cancel(); throw new Error('Body too large'); }
+    chunks.push(Buffer.from(value));
+  }
+  return Buffer.concat(chunks, length).toString('utf8');
+}
+
+function bootstrap(ticket, verifyPath) {
+  const nonce = randomBytes(16).toString('base64');
+  const script = `fetch(${JSON.stringify(verifyPath)}, {method:'POST', credentials:'same-origin', headers:{'content-type':'application/json'}, body:JSON.stringify({ticket:${JSON.stringify(ticket)}})}).then(r=>{if(r.ok)location.reload()})`;
+  const html = `<!doctype html><html><head><meta charset="utf-8"><title>Checking access</title></head><body><p>Checking access...</p><script nonce="${nonce}">${script}</script></body></html>`;
+  return new Response(html, { status: 404, headers: {
+    'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'vary': 'Cookie',
+    'content-security-policy': `default-src 'none'; script-src 'nonce-${nonce}'; connect-src 'self'; base-uri 'none'; form-action 'none'`,
+    'x-content-type-options': 'nosniff',
+  } });
+}
+
+/** 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' }) {
+  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');
+  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))) {
+    throw new Error('apiUrl must use HTTPS outside localhost');
+  }
+  if (!/^\/[a-zA-Z0-9/_-]+$/.test(verifyPath)) throw new Error('Invalid verifyPath');
+  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 (!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');
+  const publicKeys = trustedSigningKeys(decisionPublicKey, additionalDecisionPublicKeys);
+  const verifyEndpoint = new URL('./verify', endpoint);
+  const eventsEndpoint = new URL('./events', endpoint);
+  const browserCookieName = `${cookieName}_browser`;
+  const installation = hash(apiToken);
+
+  function browserBinding(request) {
+    const payload = verified(cookieValue(request, browserCookieName), cookieSecret);
+    return payload?.kind === 'browser' && payload.site === siteId && payload.installation === installation
+      && /^[A-Za-z0-9_-]{43}$/.test(payload.binding || '') ? payload.binding : null;
+  }
+
+  function cookie(name, value, age) {
+    return `${name}=${value}; Max-Age=${age}; Path=/; HttpOnly; SameSite=Lax${secureCookie ? '; Secure' : ''}`;
+  }
+
+  async function remote(purpose, input) {
+    const context = { site_id: siteId, path: input.path, method: input.method, request_id: randomBytes(16).toString('base64url') };
+    const response = await fetchImpl(purpose === 'decision' ? endpoint : verifyEndpoint, {
+      method: 'POST', signal: AbortSignal.timeout(timeoutMs), redirect: 'error',
+      headers: { authorization: `Bearer ${apiToken}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ ...input, ...context }), cache: 'no-store',
+    });
+    if (!response.ok) {
+      const retry = response.headers.get('retry-after') || '';
+      const retryAfter = response.status === 429 && /^[1-9][0-9]?$/.test(retry) && Number(retry) <= 60 ? Number(retry) : undefined;
+      await response.body?.cancel();
+      throw Object.assign(new Error('Policy service unavailable'), { retryAfter });
+    }
+    const envelope = JSON.parse(await limitedBody(response, 16_384));
+    if (typeof envelope?.decision !== 'string' || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{86}$/.test(envelope.decision)) throw new Error('Invalid signature envelope');
+    const [data, signature] = envelope.decision.split('.');
+    if (!publicKeys.some(key => verifySignature(null, Buffer.from(data), key, Buffer.from(signature, 'base64url')))) throw new Error('Invalid signature');
+    const payload = JSON.parse(Buffer.from(data, 'base64url').toString('utf8'));
+    const now = Date.now();
+    if (payload?.v !== 1 || payload.purpose !== purpose || payload.key_id !== installationId || Object.entries(context).some(([name, value]) => payload[name] !== value)
+      || !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');
+    return { ...payload, receipt: envelope.decision };
+  }
+
+  async function report(policy, outcome, session = false) {
+    if (!reportEvents) return;
+    try {
+      const response = await fetchImpl(eventsEndpoint, {
+        method: 'POST', signal: AbortSignal.timeout(Math.min(timeoutMs, 500)), redirect: 'error', cache: 'no-store',
+        headers: { authorization: `Bearer ${apiToken}`, 'content-type': 'application/json' },
+        body: JSON.stringify({ receipt: policy.receipt, outcome, session_verified: !!session }),
+      });
+      await response.body?.cancel();
+    } catch { /* Reporting cannot change a validated access decision. */ }
+  }
+
+  function validSession(request) {
+    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;
+  }
+
+  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 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;
+    let policy;
+    try {
+      policy = await remote('decision', { path, method: request.method, ...(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.
+    if (guardMode === 'site' && policy.guard_mode !== 'site') return unavailable();
+    if (policy.action === 'public') { await report(policy, 'ALLOW', session); return null; }
+    if (policy.action === 'block' || policy.action === 'entitled' || policy.action === 'default') { await report(policy, 'BLOCK', session); return concealed(); }
+    if (session) { await report(policy, 'ALLOW', true); return null; }
+    if (policy.action === 'verified' || !eligible) { await report(policy, 'BLOCK'); return concealed(); }
+    if (!/^[A-Za-z0-9_-]{43}$/.test(policy.challenge_id || '')) return unavailable();
+    const ticket = signed({ v: 1, kind: 'challenge', site: siteId, path, exp: Date.now() + 60_000,
+      challenge_id: policy.challenge_id, browser_hash: hash(binding), installation }, cookieSecret);
+    const response = bootstrap(ticket, verifyPath);
+    response.headers.set('set-cookie', cookie(browserCookieName, signed({ v: 1, kind: 'browser', site: siteId,
+      binding, installation, exp: Date.now() + 600_000 }, cookieSecret), 600));
+    await report(policy, 'CHALLENGE');
+    return response;
+  }
+
+  async function verify(request) {
+    if (request.method !== 'POST') return new Response(null, { status: 405, headers: { 'cache-control': 'no-store' } });
+    const origin = request.headers.get('origin');
+    if (!origin) return concealed();
+    // Next.js may use an internal hostname in request.url. Host is the browser's
+    // destination; retain the request URL's scheme to reject cross-scheme calls.
+    const destination = new URL(request.url);
+    const host = request.headers.get('host') || destination.host;
+    if (origin !== `${destination.protocol}//${host}`) return concealed();
+    if (!(request.headers.get('content-type') || '').toLowerCase().startsWith('application/json')) return concealed();
+    if ((Number(request.headers.get('content-length')) || 0) > 4096) return concealed();
+    let body;
+    try { body = await limitedBody(request, 4096); } catch { return concealed(); }
+    let ticket;
+    try { ticket = JSON.parse(body).ticket; } catch { return concealed(); }
+    const payload = verified(ticket, cookieSecret);
+    const binding = browserBinding(request);
+    if (payload?.kind !== 'challenge' || payload.site !== siteId || payload.installation !== installation
+      || 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 });
+      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);
+    return new Response(null, { status: 204, headers: {
+      'cache-control': 'no-store',
+      'set-cookie': cookie(cookieName, session, 300),
+    } });
+  }
+
+  return { check, verify };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { StopneticOptions } from './guard.js';
+export { createStopnetic, parseAdditionalDecisionPublicKeys } from './guard.js';
+export type { StopneticOptions } from './guard.js';
+export type StopneticServerOptions = StopneticOptions & {
+  /** Public website origin, e.g. https://example.com. Never taken from forwarded headers. */
+  origin: string;
+};
+export function createStopneticMiddleware(options: StopneticServerOptions): (
+  request: IncomingMessage & { originalUrl?: string }, response: ServerResponse,
+  next: () => unknown,
+) => Promise<unknown>;
+export function createStopneticHandler(options: StopneticServerOptions): (
+  request: Request, next: (request: Request) => Response | Promise<Response>,
+) => Promise<Response>;

package/dist/index.js

@@ -0,0 +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();
+  };
+}

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,14 @@
+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>;
+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,107 @@
+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));
+  };
+}
+
+/** 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,165 @@
+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 clientGuide = `# Stopnetic client/server setup
+
+Copy .env.stopnetic.example settings to the hosting platform's SERVER environment.
+Use Node.js 22+. Never prefix private settings with VITE_ or REACT_APP_.
+Use the same cookie secret locally and in hosting; do not commit .env.local.
+
+## React Router (inside BrowserRouter)
+
+import { useLocation } from 'react-router-dom';
+import { StopneticBoundary } from '@stopnetic/js/react';
+
+function RouteGuard({ children }) {
+  const location = useLocation();
+  return <StopneticBoundary path={location.pathname + location.search}>
+    {children}
+  </StopneticBoundary>;
+}
+
+Wrap your Routes with RouteGuard. Other frontends can await
+checkAccess(path) from @stopnetic/js/browser before rendering; when reason is
+verification_required, navigate to result.verificationUrl. Handle denial/outages.
+
+## API protection
+
+EACH protected Netlify/Vercel Fetch-style API must use:
+import { withStopnetic } from '@stopnetic/js/server';
+const protectedHandler = withStopnetic(async (request, context) => {
+  // Enforce your application's login/data permissions here too.
+  return Response.json({ example: true });
+});
+// Netlify: export default protectedHandler;
+//          export const config = { path: '/api/private', preferStatic: false };
+// Vercel: export default { fetch: protectedHandler };
+
+Node/Express: call installStopnetic(app) from ./stopnetic.server.mjs BEFORE
+parsers, static files and routes. Only expose that guarded server to visitors.
+
+Add a Page / Automatic browser flow rule and API / Require verified session rules
+in Stopnetic Policies. The generated setup leaves unmatched routes public.
+Netlify's default /.netlify/functions/ aliases are rejected by the wrapper; use
+custom config.path endpoints in React and Policies. Fetch protected data with
+credentials: 'same-origin'. API requests cannot start
+the browser verification flow. All control endpoints must reach their function
+before a SPA catch-all; verify redirects and custom function directories.
+
+Deploy once, then change rules in the dashboard. Rules apply to subsequent
+guarded requests; loaded content is not recalled. Wrap new API handlers too.
+For local Netlify/Vercel testing, use their full local development server
+(netlify dev / vercel dev), not Vite alone: the server functions must run too.
+For Node, load .env.local with node --env-file=.env.local your-server.mjs,
+or your existing server environment loader.
+Static HTML/JS and content bundled into the frontend remain public. A UI gate
+does not secure that content. Put private data in guarded server endpoints.
+No Edge/Deno/Cloudflare Workers adapter is supplied. Next.js uses @stopnetic/next.
+Test real hosting, custom domains, cookies, caches, aliases and API enforcement.
+`;
+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);
+  if (existsSync(manifestPath)) {
+    let manifest;
+    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.');
+  }
+  // Validate every destination before making any change. No customer file is replaced.
+  for (const [name, content] of Object.entries(files)) {
+    const file = destination(root, name);
+    if (existsSync(file) && text(file) !== content) 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 (!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.`;
+}

package/dist/signing-keys.js

@@ -0,0 +1,40 @@
+import { createPublicKey } from 'node:crypto';
+
+function publicKey(value) {
+  if (typeof value !== 'string' || value.length > 2048) {
+    throw new Error('Signing verification keys must be public PEMs');
+  }
+  // Hosting value fields may receive the quoted/escaped dotenv representation.
+  // Normalize only formatting; retain bounded, public-only Ed25519 trust checks.
+  let pem = value.trim();
+  try { if (pem.startsWith('"')) pem = JSON.parse(pem); }
+  catch { throw new Error('Signing verification keys must be public PEMs'); }
+  if (typeof pem !== 'string') throw new Error('Signing verification keys must be public PEMs');
+  pem = pem.replaceAll('\\r\\n', '\n').replaceAll('\\n', '\n');
+  if (!/^-----BEGIN PUBLIC KEY-----\r?\n[A-Za-z0-9+/=\r\n]+-----END PUBLIC KEY-----\s*$/.test(pem)) {
+    throw new Error('Signing verification keys must be public PEMs');
+  }
+  let key;
+  try { key = createPublicKey(pem); }
+  catch { throw new Error('Signing verification keys must be public PEMs'); }
+  if (key.asymmetricKeyType !== 'ed25519') throw new Error('Signing verification keys must be Ed25519');
+  return key;
+}
+
+export function trustedSigningKeys(primary, additional) {
+  if (!Array.isArray(additional) || additional.length > 2) throw new Error('Use at most two additional signing public keys');
+  const keys = [primary, ...additional].map(publicKey);
+  return [...new Map(keys.map(key => [key.export({ type: 'spki', format: 'der' }).toString('hex'), key])).values()];
+}
+
+/** Parse a server environment JSON array without exposing malformed values. */
+export function parseAdditionalDecisionPublicKeys(value) {
+  if (value === undefined || value === '') return [];
+  try {
+    if (typeof value !== 'string' || value.length > 8192) throw new Error();
+    const keys = JSON.parse(value);
+    if (!Array.isArray(keys) || keys.length > 2) throw new Error();
+    keys.forEach(publicKey);
+    return keys;
+  } catch { throw new Error('Invalid additional signing public keys'); }
+}

package/package.json

@@ -1,6 +1,54 @@
-{
-  "name": "@stopnetic/js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@stopnetic/js",
+  "version": "0.0.2-pilot",
+  "description": "Server-side Stopnetic guard for JavaScript websites, Node.js and Express-compatible servers.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Stopnetic",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KlimentSidorov/stopin.git",
+    "directory": "integrations/javascript"
+  },
+  "keywords": [
+    "stopnetic",
+    "javascript",
+    "nodejs",
+    "express",
+    "access-control"
+  ],
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "bin": { "stopnetic-js": "./bin/stopnetic-js.js" },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": { "types": "./dist/server.d.ts", "default": "./dist/server.js" },
+    "./browser": { "types": "./dist/browser.d.ts", "default": "./dist/browser.js" },
+    "./react": { "types": "./dist/react.d.ts", "default": "./dist/react.js" }
+  },
+  "peerDependencies": { "react": "*" },
+  "peerDependenciesMeta": { "react": { "optional": true } },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "pilot",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "test:package": "npm run build && node tests/package-check.mjs"
+  },
+  "devDependencies": {
+    "express": "^4.22.3",
+    "express5": "npm:express@^5.2.1"
+  }
+}