@stopnetic/js 0.0.1-pilot → 0.0.3-pilot

package/README.md

@@ -1,199 +1,372 @@
-# @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.
-
-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.
+# @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.3-pilot is prepared locally; it is not published yet**. It adds a
+framework-independent generated guide, a complete Node application wrapper
+(`createStopneticAppHandler`) and safe migration of the unchanged older guide.
+Angular, React, Vue, Svelte, Solid and plain JavaScript share the browser/server
+contracts; no React dependency is required. See the
+[complete generated guide](src/client-guide.md) for SSR, static builds, Angular,
+client navigation, API protection and runtime restrictions.
+
+The currently published **0.0.2-pilot** 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. Install the published 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.3-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)
+
+Follow the [hosting guide](../../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.
+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:
+
+```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.
+
+### Shared browser startup and Node SSR
+
+The generated [framework-independent guide](src/client-guide.md) gives one
+browser entry that calls `checkAccess` before importing the application's
+existing bootstrap. Keep Angular's bootstrapApplication, React's createRoot,
+Vue's createApp, Svelte's mount, Solid's render or plain DOM startup unchanged
+in that bootstrap module. Use document links for server-checked navigation,
+or recheck target access in the client router. A browser-only check is UI behavior.
+
+For Node SSR use the generated Express helper before static files/rendering,
+or `createStopneticAppHandler` around a Fetch-style application entry (0.0.3).
+The wrapper handles access/verification control endpoints and guards pages and
+APIs before calling the renderer. It preserves context, streams and request
+bodies. Framework hooks with another signature still need their continuation
+adapted; accepting Request/Response does not make an Edge runtime supported.
+
+The guide includes Angular SSR/rendering and client router examples. Angular
+SSR compiled with the installed Angular 22 dependencies and served real HTML
+after verification in an isolated local fixture. That does not validate a live
+provider deployment. Netlify's automatic Angular SSR uses Edge; choose Node SSR,
+a Node gateway or a deliberate static build. Do not publish protected prerendered
+HTML. For other frameworks use the same Node server entry and verify their
+actual deployed runtime. React's boundary remains an optional convenience.
+
+### Optional React Router boundary
+
+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`.
+
+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).
+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
+automatically. Keep static bundles public and private data in guarded APIs.
+
+For Vercel page responses, the manual Node routing middleware in
+`examples/vercel-spa-middleware.mjs` checks pages before static HTML, using
+`@vercel/functions` and the existing SDK. The CLI's generated Vercel control
+function alone does not guard page documents. Follow the hosting guide for
+middleware, API/asset routing and SPA rewrite configuration. Local signed tests
+cover it; live Vercel deployment validation remains required.
+
+### 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.
+
+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>;