@stopnetic/js 0.0.5-pilot → 0.1.0

package/README.md

@@ -1,35 +1,63 @@
-# @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.5-pilot is prepared locally; it is not published yet**. The guide
-offers two explicit rendering paths: preserve SSR or retain a static/CSR app.
-Server document navigation is the default; leave startup/layout unchanged with
-no global checking screen. Optional SPA demos for all six frontends explain
-their asynchronous checks and use empty pending content. Unchanged
-0.0.2/0.0.3/0.0.4 guides migrate safely; custom edits require merging.
-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.4-pilot** 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](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 |
+| --- | --- |
+| Angular | AngularAppEngine Fetch entry or Express before AngularNodeAppEngine |
+| React Router | Existing Express entry; single-fetch `.data` aliases use page policy |
+| Custom React / Vue | Guard before the existing Node renderer; keep hydration |
+| Nuxt 3/4 (Nitro 2/H3 1) | Root Node server middleware before rendering/APIs |
+| SvelteKit | `handle` before `resolve(event)`; canonical page check for data requests |
+| Astro | `onRequest` before `next()` with an existing Node adapter |
+| SolidStart 1 / 2 | Version-specific request middleware before continuation |
+| Custom Node / plain JavaScript | Root Express middleware or complete Fetch wrapper |
+| Next.js | Dedicated `@stopnetic/next` guide |
+
+Merge existing files/context, preserve public routes and keep protected output
+out of prerender/static/CDN caches. These manual snippets are not automatic
+framework installers. Node compatibility does not validate a live provider.
+Only dashboard rules decide verification; Angular-specific flags are not instructions
+for other frameworks. React/Vue libraries without a server use the static option.
+
+To test server continuation contracts after `npm run build`, run
+`node tests/prepare-ssr-guide-tests.mjs`, then `node tests/ssr-guide-check.mjs`.
+Dependencies remain in ignored test-results. Native H3 1/2 and Express exercise
+signed access, control isolation, data aliases and unread POST bodies. Astro,
+SvelteKit and SolidStart factory imports use contract shims, not full framework
+builds. Angular's separate fixture compiles/renders real SSR. Live routing,
+prerender/cache behavior and complete framework/provider builds still need validation.
+
 The guide and `examples/frontend` contain complete, locally tested OPTIONAL
 browser-only SPA examples. The default document-navigation integration needs
 the server guard and normal links, not these full-layout browser gates. Keep SSR
@@ -71,19 +99,19 @@ npm run build
 npm pack
 ```
 
-Install the resulting `stopnetic-js-0.0.5-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:
@@ -110,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.
 
@@ -121,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
@@ -199,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
@@ -242,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 |
 
@@ -387,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
@@ -402,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)