@stopnetic/js 0.0.0-stage → 0.0.1-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,199 @@
-# Temporary Holding Version
+# @stopnetic/js — JavaScript website guard
 
-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.
+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.
+
+This package is prepared locally and **not published yet**. After publication:
+
+```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.1-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.
+
+## 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. 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/dist/guard.d.ts

@@ -0,0 +1,21 @@
+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;
+};
+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,203 @@
+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 }) {
+  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.length < 32) throw new Error('cookieSecret must be at least 32 characters');
+  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');
+  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);
+  }
+
+  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);
+    const eligible = request.method === 'GET' && (request.headers.get('accept') || '').includes('text/html');
+    const binding = !session && eligible ? browserBinding(request) || randomBytes(32).toString('base64url') : null;
+    let policy;
+    try {
+      policy = await remote('decision', { path, method: request.method, ...(binding ? { browser_binding: binding } : {}) });
+    } catch (error) { return unavailable(error?.retryAfter); }
+    if (!policy || !['public', 'block', 'human', 'verified', 'entitled', 'default'].includes(policy.action)) 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), 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/signing-keys.js

@@ -0,0 +1,29 @@
+import { createPublicKey } from 'node:crypto';
+
+function publicKey(value) {
+  if (typeof value !== 'string' || value.length > 2048
+    || !/^-----BEGIN PUBLIC KEY-----\r?\n[A-Za-z0-9+/=\r\n]+-----END PUBLIC KEY-----\s*$/.test(value)) {
+    throw new Error('Signing verification keys must be public PEMs');
+  }
+  const key = createPublicKey(value);
+  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,47 @@
 {
   "name": "@stopnetic/js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-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"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "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"
+  }
+}