# Stopnetic installation instructions for a coding agent: JavaScript / Node

Guide revision: 2026-11-10.

## Task and boundaries

Integrate Stopnetic into the owner's existing JavaScript/TypeScript application.
Inspect first and follow the owner's/project's instructions. Preserve UI, routing,
SSR, hydration, authentication, data permissions and package manager. Do not copy
a demo over the app or silently change SSR to CSR. **Next.js 16 App Router uses
@stopnetic/next and the separate Next.js agent guide.**

This public guide contains no credentials. Use actual site configuration from
Stopnetic Integration in ignored server env files and hosting settings. Never ask
for secrets in chat, print them, commit them or expose them to browsers. If a
setting is missing, report its variable name and where the owner must configure
it. Do not invent credentials or bypass failures.

## 1. Inspect rendering and runtime

Find package.json, lockfile, server request entry, framework/version, rendering
modes, routes, APIs, hosting adapter, static output and caching configuration.
This SDK requires **Node.js 22 or newer on the server**.

| Project | Guard location |
| --- | --- |
| Express or custom Node renderer | Before static files, body parsers, APIs and rendering |
| Node Fetch application | Wrap the complete Request -> Response application |
| Angular SSR, Nuxt, SvelteKit, Astro, SolidStart, React Router SSR | Actual framework's Node request hook; preserve its context |
| Existing static React/Vue/Angular/Svelte/Solid/plain HTML | Node hosting guard BEFORE HTML; independently guarded APIs |
| Browser-only hosting without request-time code | Needs compatible server/gateway; a frontend script alone cannot enforce access |
| Edge/Deno/Cloudflare Workers or PHP/Python/Java | Do not import this Node SDK there; a compatible Node gateway/separate adapter is needed |

Keep the current rendering mode. Prerendered HTML/public bundles can bypass
request-time checks if served directly. Changing hosting or rendering is a
project decision, not an automatic workaround for runtime incompatibility.

## 2. Obtain the six SERVER settings

The owner adds the website, completes required account/domain verification and
creates a key in Stopnetic Integration. Copy actual values into ignored server
.env/.env.local AND the hosting provider's server environment:

| Variable | Source |
| --- | --- |
| STOPNETIC_WEBSITE_ORIGIN | Canonical HTTPS website origin |
| STOPNETIC_SITE_ID | Site ID from Integration |
| STOPNETIC_API_URL | Decision endpoint URL from Integration |
| STOPNETIC_API_TOKEN | Private installation key; retain a valid existing key |
| STOPNETIC_DECISION_PUBLIC_KEY | Complete public Ed25519 PEM |
| STOPNETIC_COOKIE_SECRET | Independent random secret; retain an existing valid secret |

Preserve additional public keys if supplied. The service's private signing key
never belongs on a customer's website. Keep the PEM header/footer/newlines;
literal \n escapes are supported. Hosting fields take values only, without names
or extra quotes. Local files do not configure hosting automatically. The installer
can generate a missing cookie secret; reuse the same value across deployments.

Never use VITE_, REACT_APP_ or NEXT_PUBLIC_ prefixes for these settings. Angular
environment.ts is browser configuration, not a private server environment.

## 3. Install and read the matching SDK reference

These examples use npm; adapt to the existing package manager/lockfile:

```sh
node --version
npm install @stopnetic/js
npm exec --no -- stopnetic-js --help
```

Before wiring code, read the installed version's documentation/types:

- node_modules/@stopnetic/js/README.md
- node_modules/@stopnetic/js/dist/client-guide.md
- node_modules/@stopnetic/js/dist/server.d.ts
- The appropriate node_modules/@stopnetic/js/examples/ssr/ example.

The full client-guide.md contains matching framework and hosting code. Use it
rather than guessing APIs or copying another framework's instructions. Its
browser-router examples are optional demos, not replacements for an existing app.

## 4. Preview and generate appropriate hosting files

Choose ONE actual hosting platform. Example for Node/Express:

```sh
npm exec --no -- stopnetic-js init --platform node --dry-run
npm exec --no -- stopnetic-js init --platform node
```

Use --platform netlify or --platform vercel instead for those platforms. Review
existing server/provider files before applying setup. Do not overwrite custom
integration files or switch an existing platform without reviewing its migration.

The generator writes stopnetic.setup.json, .env.stopnetic.example,
stopnetic-client-guide.md and the platform's helper/control endpoint. Node gets
stopnetic.server.mjs; Netlify/Vercel get their own endpoint files. Inspect actual
output and configured paths. Preserve working credentials and cookie secrets.

**A generated control endpoint is not complete page/API protection.** Read the
generated guide and wire the guard into the existing application. Custom SSR
hooks should use the appropriate installed framework example, not an Express
helper blindly mounted into a non-Express application.

## 5. Enforce access before content is sent

- Express: install the generated helper BEFORE body parsers, static files,
  private APIs and the existing renderer. Do not consume request bodies first.
- Node Fetch: use createStopneticAppHandler around the COMPLETE application.
- SSR framework: use the documented Node hook before rendering/resolving;
  preserve framework context, hydration, streaming and error handling.
- Static Netlify/Vercel: add hosting page guard/middleware BEFORE HTML delivery
  using the installed guide. Configure actual provider rewrites/static precedence;
  a normal SPA fallback alone does not enforce protection.

Choose one complete-app guard integration; do not stack alternative wrappers.
Keep /api/stopnetic/access and /api/stopnetic/verify reachable before SPA fallbacks
and excluded from recursive guard interception.

Independently guard every protected API before reading, mutating or returning
data, using the installed server helper/types (for example withStopnetic). Keep
the application's own login/roles/data permissions. Do not embed private records
in public HTML, JS bundles, prerendered output or static files.

Use normal document navigation for the default server integration and preserve
the existing browser bootstrap. If client-side SPA navigation is required, merge
the appropriate optional hooks into the existing router. Explain asynchronous
pending/denied behavior and withhold protected target content until authorized.
Do not apply a global browser demo gate to a hydrated SSR root. Browser UI checks
alone do not authorize backend data or undo already disclosed content.

## 6. Configure intended Policies

Use actual owner-approved paths, not every demo route. Example only:

| Path | Type | Action |
| --- | --- | --- |
| /members | Page | Automatic browser flow |
| /api/members/* | API | Require verified session (no challenge) |

First matching rule wins. Generated site mode leaves unmatched routes public.
Do not add broad blocks or require verification on every page without instruction.
Protect pages and their APIs separately. Same-origin browser fetches can send the
verified cookie; another API host needs its own guard or a guarded server proxy.
Cookies are not automatically shared/trusted across unrelated domains.

Optional passwords, interactive verification, countries or budgets require their
documented SDK/server support before the owner enables them. Do not enable a
budget without its required trusted ingress and cost callback setup.

## 7. Check, deploy and test real coverage

```sh
npm exec --no -- stopnetic-js check
npm run build
```

This check is offline. Use check --local-http only for loopback local pilots.
It does not configure hosting, validate live domain/key/plan health, deploy the
app or prove interception. This JS CLI does not have Next.js's test-connection
command. Use the actual project's deployment/runtime tools. Vite alone cannot
run Netlify/Vercel functions; use the provider's local runtime when appropriate.

Follow the owner's deployment instructions and set the hosting server environment
for the actual context. Prevent protected static/CDN/cache/origin aliases from
bypassing the guard. Never change failed checks into permissive access.

Test the deployed routing with a fresh browser and raw requests:

1. Public pages retain their original UI and rendering mode.
2. Protected documents verify BEFORE sending content; an eligible first challenge
   can be 404, followed by the permitted page after verification succeeds.
3. Unverified direct protected API requests withhold private data (normally 404).
4. Block rules withhold content even with a verified session.
5. Authorized API requests still enforce application data permissions.
6. JS/CSS/assets, SSR/hydration, navigation and framework data aliases work.
7. No public static/cache/origin alias exposes protected data around the guard.
8. Service/configuration failures withhold private content (503). Recent SDKs
   show browser retry pages; API/mutation requests are not automatically replayed.

The first actual protected decision can start the owner's 72-hour trial. Report
changed files, installed versions, runtime/hosting, coverage, checks/results and
remaining limitations. Do not print secrets/private response bodies. Distinguish
installed, built, deployed and live-tested. Verification is not proof of a human
or a guarantee against every AI agent. Later policy edits apply on guarded
requests without reinstalling npm or deploying again.

Product documentation: https://www.stopnetic.com/docs
