@stopnetic/js 0.0.6-pilot → 0.1.0

package/README.md

@@ -1,40 +1,35 @@
-# @stopnetic/js — JavaScript website guard
+# @stopnetic/js - JavaScript and TypeScript 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.6-pilot is prepared locally; it is not published yet**. It adds
-framework-specific SSR instructions and a dashboard SSR selector for Angular,
-React Router, custom React SSR, Nuxt, custom Vue SSR, SvelteKit, Astro, SolidStart
-and custom Node servers. Examples identify the actual server entry, prerender
-settings, deployed Node runtime and context/body preservation. Next.js uses its
-dedicated adapter; other languages/Edge are explicitly outside this Node SDK.
-Unchanged 0.0.2/0.0.3/0.0.4/0.0.5 guides migrate safely; custom edits require merging.
-SSR and static rendering remain separate choices, with document navigation
-default and no global checking screen. Optional browser demos remain available.
-Angular, React, Vue, Svelte, Solid and plain JavaScript share the browser/server
-contracts; no React dependency is required. See the
-[complete generated guide](dist/client-guide.md) for SSR, static builds, frameworks,
-client navigation, API protection and runtime restrictions.
-
-The currently published **0.0.5-pilot** clarifies rendering/navigation and includes full frontend examples and the
-framework-independent server/browser setup, complete Node application wrapper
-and older-guide migration. Version 0.0.2 added the 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. Install the published pilot with:
+Use it with Node.js and Express, with frontend examples for Angular, React, Vue,
+Svelte, Solid and plain JavaScript. No frontend framework is a required dependency.
+Your hosting server must run **Node.js 22 or newer**; browser-only JavaScript does
+not enforce protection on its own. Keep your existing SSR or static rendering.
+
+## Install
+
+Run inside your website project:
 
 ```sh
-npm install @stopnetic/js@pilot
+npm install @stopnetic/js
 ```
 
+For Next.js 16 App Router, use [@stopnetic/next](https://www.npmjs.com/package/@stopnetic/next).
+
+This release includes server/browser helpers, framework-specific SSR instructions,
+complete optional frontend examples, Netlify/Vercel/Node setup commands and bounded
+public-key parsing for raw, escaped or JSON-quoted public PEM values. Existing
+unmodified generated guides can migrate safely; customized files require merging.
+
+Read the [complete generated guide](https://unpkg.com/@stopnetic/js@0.1.0/dist/client-guide.md)
+for SSR, static builds, client navigation, API protection and runtime restrictions.
+Validate the actual deployed routing, caching and provider configuration before
+production use. Browser verification does not prove human identity.
+
 ## Framework implementation examples
 
 SSR apps use the **SSR framework** selector, not the optional browser-demo
-selector. [Framework SSR instructions](dist/client-guide.md#ssr-framework-instructions)
+selector. [Framework SSR instructions](https://unpkg.com/@stopnetic/js@0.1.0/dist/client-guide.md#ssr-framework-instructions)
 and `examples/ssr` contain matching server code:
 
 | SSR app | Server connection |
@@ -104,19 +99,19 @@ npm run build
 npm pack
 ```
 
-Install the resulting `stopnetic-js-0.0.6-pilot.tgz` into the website project using
+Install the resulting `stopnetic-js-0.1.0.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)
+## Reusable client/server setup
 
-Follow the [hosting guide](../../docs/javascript-hosting-guide.md) for the full
+Follow the [hosting guide](https://github.com/KlimentSidorov/stopnetic/blob/main/docs/javascript-hosting-guide.md) for the full
 Netlify, Vercel or Node procedure, server settings, page HTTP 404 enforcement,
 frontend/API wiring and diagnosis. The dashboard's Integration and Documentation
 pages offer the same provider choices and complete copyable page-guard examples.
 
-The published 0.0.2-pilot includes these commands and subpath exports.
+These commands and subpath exports are included in this release.
 Older 0.0.1-pilot installations must upgrade before using them.
 
 Run setup at the app's package.json, choose hosting, and preview before writing:
@@ -143,7 +138,7 @@ Functions secret store. Copy the generated cookie secret without committing it.
 Wire the server page guard and EACH protected API following the generated guide.
 Browser route checks are optional for retained SPA navigation.
 Run `npm exec --no -- stopnetic-js check` after setting credentials (`--local-http`
-for a loopback pilot). This check validates configuration and generated files
+for a loopback local test). 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.
 
@@ -154,7 +149,7 @@ server environment loader. Production credentials belong in runtime settings.
 
 ### Shared browser startup and Node SSR
 
-The generated [framework-independent guide](dist/client-guide.md) defaults to
+The generated [framework-independent guide](https://unpkg.com/@stopnetic/js@0.1.0/dist/client-guide.md) defaults to
 server document navigation: leave browser startup/layout intact, use normal
 links, and let the server apply dashboard policies. It also gives an OPTIONAL
 browser startup gate and separate OPTIONAL SPA router demos. Do not combine
@@ -232,10 +227,10 @@ request and preserve ordinary request bodies. Denials/outages return empty
 
 For a real HTTP 404 on a Netlify SPA page, use the optional page-serving function
 in `examples/netlify-spa-pages.mjs` and follow
-[`docs/netlify-spa-page-requests.md`](../../docs/netlify-spa-page-requests.md).
+[`docs/netlify-spa-page-requests.md`](https://github.com/KlimentSidorov/stopnetic/blob/main/docs/netlify-spa-page-requests.md).
 It checks signed access before reading the bundled entry HTML. The browser
 boundary alone cannot change the initial document's HTTP status. This example
-uses the published 0.0.2-pilot server helpers; the setup CLI does not install it
+uses the server helpers included in this release; the setup CLI does not install it
 automatically. Keep static bundles public and private data in guarded APIs.
 
 For Vercel page responses, the manual Node routing middleware in
@@ -275,7 +270,7 @@ rollout. Hosting contracts are simulated locally; live provider tests are pendin
 | 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 |
+| Next.js 16 App Router | Published `@stopnetic/next` 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 |
 
@@ -420,14 +415,14 @@ 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.
-
-Validate your actual hosting, cache rules, browser flow, API paths and provider configuration
+Access reports are best effort and cannot establish delivery guarantees.
+With the updated dashboard, the SDK 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.
+
+Validate your actual hosting, cache rules, browser flow, API paths and provider configuration
 before onboarding paying customers.
 
 ## Maintainer checks and release
@@ -435,14 +430,19 @@ before onboarding paying customers.
 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
+The tarball includes runtime/types in `dist`, the setup CLI in `bin`, the public
+frontend/SSR examples, README, MIT license and manifest. No secrets, 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/
+npm publish --access public --tag latest --registry=https://registry.npmjs.org/
 ```
 
 Publishing this package does not update the existing `@stopnetic/next` release.
+
+## Source and support
+
+[Source repository](https://github.com/KlimentSidorov/stopnetic/tree/main/integrations/javascript) | [Report an issue](https://github.com/KlimentSidorov/stopnetic/issues)

package/dist/client-guide.md

@@ -101,8 +101,11 @@ STOPNETIC_COOKIE_SECRET=your_separate_random_cookie_secret
 
 The installer creates a private cookie secret in `.env.local` when missing.
 Reuse it across deployments. Do not commit `.env.local`. Copy complete PEM
-header/body/footer with real newlines or literal `\n`; quote multiline values
-in local env files. Hosting value fields do not need surrounding quotes.
+header/body/footer with real newlines or literal `\n`. The dashboard's generated
+local configuration uses an unquoted single-line key with literal `\n`; the SDK
+restores its line breaks. Hosting fields take only the value, with no variable
+name, equals sign or surrounding quotes. Manually written actual multiline PEMs
+still need quotes in env files. Previously generated quoted env files remain valid.
 Never put private settings in frontend environment files or prefix them with
 `VITE_`, `REACT_APP_` or `NEXT_PUBLIC_`. Angular's `environment.ts` is browser
 configuration, not a private server environment.
@@ -1308,7 +1311,7 @@ server endpoints.
 ## Updating an existing generated guide
 
 After installing the new SDK, rerun `stopnetic-js init --platform <same-platform>`
-(preview with `--dry-run`). An unchanged 0.0.2/0.0.3/0.0.4/0.0.5 generated guide is upgraded
+(preview with `--dry-run`). An unchanged 0.0.2/0.0.3/0.0.4/0.0.5/0.0.6 generated guide is upgraded
 with its setup manifest. Your key, cookie secret and server files are preserved.
 Customized guides or handlers require manual merging; switching platforms also
 requires review. This command does not publish, deploy or contact Stopnetic.

package/dist/server.d.ts

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

package/dist/server.js

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