@stopnetic/js 0.0.2-pilot → 0.0.3-pilot

package/README.md

@@ -6,12 +6,18 @@ 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.1-pilot is published** on npm. This repository prepares
-**0.0.2-pilot**, which adds a reusable browser/server setup for Netlify, Vercel
+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. The new version is not published yet. Install the
-currently published manual server pilot with:
+keys as cookie secrets. Install the published pilot with:
 
 ```sh
 npm install @stopnetic/js@pilot
@@ -25,15 +31,20 @@ npm run build
 npm pack
 ```
 
-Install the resulting `stopnetic-js-0.0.2-pilot.tgz` into the website project using
+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)
 
-Use the local tarball above until this version is published. Installing the current
-registry pilot (0.0.1) does not provide these new commands or subpath exports.
+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:
 
@@ -67,7 +78,31 @@ 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.
 
-### React Router
+### 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:
@@ -119,6 +154,21 @@ 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

package/dist/client-guide.md

@@ -0,0 +1,276 @@
+# Stopnetic setup for JavaScript applications
+
+Angular, React, Vue, Svelte, Solid and plain JavaScript use the same server guard
+and browser access check. React is optional. Install `@stopnetic/js` in the
+website project; choose a hosting platform, not a frontend framework.
+
+The generated control endpoint is only part of installation. It does not
+automatically intercept pages, edit your router or protect existing APIs.
+
+## 1. Choose the actual rendering and server runtime
+
+| Application | Where the shared guard belongs |
+| --- | --- |
+| Node/Express SSR or static-file server | Before body parsers, static files, API handlers and rendering |
+| Node server with a Fetch `Request` → `Response` handler | Wrap the complete application handler before it renders or returns API data |
+| Static Angular, React, Vue, Svelte, Solid or plain HTML | A Node hosting function/middleware before HTML, plus the shared browser check below |
+| Angular SSR, Nuxt, SvelteKit, Astro, SolidStart, React Router server mode | The deployed Node request entry, before the framework renderer; preserve framework context |
+| Next.js | Use `@stopnetic/next` and its Next.js installation guide |
+| Edge/Deno/Cloudflare Workers, PHP, Python, Ruby, C# or Java | This Node SDK cannot be imported there; use a Node gateway or an adapter for that runtime |
+
+Node.js 22 or newer is required. SSR support alone does not establish runtime
+compatibility. A Fetch API on an Edge runtime is not a Node server.
+Prerendering runs at build time: it is not a request-time access check. Do not
+publish protected prerendered pages or private data to a public static directory.
+
+## 2. Save the six server environment settings
+
+Copy actual values from Stopnetic Integration into your hosting SERVER
+environment. Use `https://www.example.com` only as an example; replace it with
+your website's canonical origin.
+
+```dotenv
+STOPNETIC_WEBSITE_ORIGIN=https://www.example.com
+STOPNETIC_SITE_ID=your_site_id
+STOPNETIC_API_URL=https://your-stopnetic-service/api/integration/decision
+STOPNETIC_API_TOKEN=your_private_installation_key
+STOPNETIC_DECISION_PUBLIC_KEY=your_complete_public_PEM
+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.
+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.
+
+## 3. Protect the server before rendering
+
+### Node/Express: every frontend uses the same mount
+
+```js
+import { installStopnetic } from './stopnetic.server.mjs';
+installStopnetic(app);
+// Existing body parsers, static files, APIs and framework renderer follow.
+```
+
+Generate that helper with `stopnetic-js init --platform node`. Only expose the
+guarded server. Keep the control endpoints `/api/stopnetic/access` and
+`/api/stopnetic/verify` reachable before SPA fallbacks. Preserve the canonical
+Host at your proxy. This works without a React dependency or browser boundary.
+
+### Node Fetch application: one wrapper for pages and APIs
+
+In SDK 0.0.3-pilot or newer:
+
+```js
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+
+let protectedApp;
+export async function handleRequest(request, context) {
+  protectedApp ??= createStopneticAppHandler(async (checked, frameworkContext) => {
+    // Your existing Node framework handler. Return a Response.
+    return renderApplication(checked, frameworkContext);
+  });
+  return protectedApp(request, context);
+}
+```
+
+Lazy initialization reads environment settings at runtime, not during a
+prerender build. Control requests are handled by Stopnetic. Other requests are
+checked before the application handler runs; denied responses do not render
+the site's navigation or private API data. Context and unread request bodies
+are preserved. Continue enforcing your application's own user/data permissions.
+
+For a framework hook, keep its existing request/context conventions and call
+the shared guard before its `resolve`, `next` or renderer. A Fetch wrapper is
+for a complete handler returning a Response, not every framework middleware
+signature. Node/Express can mount the generated helper around any renderer.
+
+### Angular SSR on Node
+
+For a Fetch-style Angular SSR entry in `src/server.ts`:
+
+```ts
+import { AngularAppEngine, createRequestHandler } from '@angular/ssr';
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+
+const engine = new AngularAppEngine();
+let guarded: ReturnType<typeof createStopneticAppHandler> | undefined;
+async function handle(request: Request): Promise<Response> {
+  guarded ??= createStopneticAppHandler(async checked =>
+    await engine.handle(checked) ?? new Response(null, { status: 404 }));
+  return guarded(request);
+}
+export const reqHandler = createRequestHandler(handle);
+```
+
+Keep existing Angular host configuration and request context if your entry
+uses them. For an Express-based Angular entry, mount `installStopnetic(app)`
+before `express.static` and `AngularNodeAppEngine.handle` instead.
+
+Protected routes in `src/app/app.routes.server.ts` must use request-time
+rendering rather than `RenderMode.Prerender`:
+
+```ts
+import { RenderMode, ServerRoute } from '@angular/ssr';
+export const serverRoutes: ServerRoute[] = [
+  // All routes are rendered on incoming requests in this example.
+  { path: '**', renderMode: RenderMode.Server },
+];
+```
+
+Netlify's automatic Angular SSR adapter currently uses Edge Functions. Do not
+import this Node SDK into that Edge entry, and do not assume a Netlify Node
+function runs before the Edge renderer. Use a Node SSR deployment, a Node
+gateway that cannot be bypassed, or a static Angular build with Node page
+handling. Switching to static rendering changes SSR behavior; choose deliberately.
+
+### Static apps on Netlify / Vercel
+
+The generated Netlify control file serves `/api/stopnetic/access` and
+`/api/stopnetic/verify`; Vercel uses `api/stopnetic/[operation].mjs`. They do not
+guard the original page request by themselves. Add a Node page function or
+Node routing middleware before serving HTML if you need real page HTTP 404s.
+The full hosting guide is at your Stopnetic dashboard's `/docs#javascript`.
+
+Use your actual build output. Vite often uses `dist`; Angular commonly uses
+`dist/<project>/browser`. Angular scripts/styles may be at that directory's
+root rather than `/assets`. Bundle the correct HTML and assets, preserve their
+MIME types, and do not use the Vite-only file paths unchanged for Angular.
+Reject direct entry-HTML and function aliases that would bypass protected paths.
+
+## 4. Browser startup: the same code for every frontend
+
+For a browser-only/static app, move the existing startup code from `src/main.ts`
+or `src/main.js` into `src/bootstrap.ts` or `src/bootstrap.js`. Keep its original
+framework imports and bootstrap code. Replace the browser entry with:
+
+```js
+import { checkAccess } from '@stopnetic/js/browser';
+
+async function start() {
+  try {
+    const result = await checkAccess(location.pathname + location.search);
+    if (result.allowed) {
+      await import('./bootstrap'); // Your existing app startup, unchanged.
+    } else if (result.reason === 'verification_required' && result.verificationUrl) {
+      location.replace(result.verificationUrl);
+    } else {
+      document.body.replaceChildren(document.createTextNode(
+        result.reason === 'blocked' ? 'Not found.' : 'Access unavailable.'));
+    }
+  } catch {
+    document.body.replaceChildren(document.createTextNode('Access unavailable.'));
+  }
+}
+void start();
+```
+
+This is browser code, not a server hook. The startup file can use any framework:
+
+| Frontend | Existing startup retained in `bootstrap` |
+| --- | --- |
+| Angular | `bootstrapApplication(App, appConfig)` or your existing NgModule bootstrap |
+| React | `createRoot(...).render(...)` |
+| Vue | `createApp(...).use(router).mount(...)` |
+| Svelte | Your existing `mount(...)` or older constructor |
+| Solid | Your existing `render(...)` |
+| Plain JavaScript | Your existing DOM rendering code |
+
+Use ordinary `<a href>` document links for guarded navigation: each navigation
+then reaches the server before a new page is shown. Client router navigation
+does not rerun the startup file. If keeping SPA navigation, call `checkAccess`
+in that router's before-navigation guard for every target and handle denial,
+verification redirects, outages and stale/cancelled requests. A UI check cannot
+set the original HTTP status or make public bundles private.
+
+### Angular client router, if retaining routerLink
+
+```ts
+import { isPlatformBrowser } from '@angular/common';
+import { inject, PLATFORM_ID } from '@angular/core';
+import { CanActivateFn } from '@angular/router';
+import { checkAccess } from '@stopnetic/js/browser';
+
+export const stopneticRouteGuard: CanActivateFn = async (_route, state) => {
+  if (!isPlatformBrowser(inject(PLATFORM_ID))) return true;
+  // SSR is authorized by the SERVER wrapper above, never by this true value.
+  const result = await checkAccess(state.url.split('#')[0]);
+  if (result.allowed) return true;
+  if (result.reason === 'verification_required' && result.verificationUrl) location.assign(result.verificationUrl);
+  return false;
+};
+```
+
+Apply `canActivate: [stopneticRouteGuard]` and
+`runGuardsAndResolvers: 'always'` on each page route, including root, or use an
+equivalent parent `canActivateChild` guard. Keep the full header/router/footer
+inside the gated layout. Render a visible unavailable/denied state when a
+navigation is cancelled; returning false alone retains the previous view.
+This guard is UX only. It does not authorize API data or replace server checks.
+
+React users may additionally use `StopneticBoundary` from `@stopnetic/js/react`
+inside BrowserRouter around the entire layout; that optional module is not
+required for Angular, Vue, Svelte, Solid or plain JavaScript.
+
+## 5. Protect APIs independently
+
+If the full application wrapper is in front of an API, it checks that API too.
+Separate Netlify/Vercel API functions need their own wrapper:
+
+```js
+import { withStopnetic } from '@stopnetic/js/server';
+const handler = withStopnetic(async (request, context) => {
+  // Also enforce your application's login/data permissions.
+  return Response.json({ example: true });
+});
+// Netlify: export default handler;
+// export const config = { path: '/api/private', preferStatic: false };
+// Vercel: export default { fetch: handler };
+```
+
+Use the public custom `/api/private` path in all clients and Policies, not
+Netlify's default `/.netlify/functions/` alias. Fetch same-origin data with
+`credentials: 'same-origin'`. API requests cannot run a verification page;
+verify on an HTML page first. An API on another origin needs its own server
+protection and session, or a guarded same-origin server proxy. CORS alone does
+not authorize data, and the current SDK does not share sessions across hosts.
+
+## 6. Rules, deployment and testing
+
+Save the actual page as Page / Automatic browser flow and its APIs as API /
+Require verified session in Policies. First matching rule wins. Unmatched paths
+are public in the generated site's whole-site mode. Public and block rules still
+require a valid signed policy response. Verification can be completed by capable
+automated browsers; retain your own authentication and authorization.
+
+Run `stopnetic-js check`, build and deploy. Configure server env in each hosted
+context and redeploy after changing it. For local Netlify/Vercel functions use
+the full local server, not just `ng serve` or Vite. For Node use
+`node --env-file=.env.local your-server.mjs` or your server environment loader.
+
+Test raw document requests, verified browser requests, direct private API calls,
+denial and service failure. Check status/body, session cookies, JS/CSS MIME types,
+client navigation, entry HTML, aliases, prerender outputs and caches. A denied
+request must not execute the renderer or data handler. The offline CLI check
+validates configuration and generated files, not deployed coverage.
+
+Ordinary policy changes apply on subsequent guarded requests without reinstalling
+or redeploying. Already loaded content is not recalled. Public HTML/JS/assets and
+content bundled into frontend code remain public; keep private data in guarded
+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-pilot 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.
+
+References: https://angular.dev/guide/ssr,
+https://angular.dev/guide/routing/route-guards,
+https://docs.netlify.com/build/frameworks/framework-setup-guides/angular/.

package/dist/server.d.ts

@@ -5,6 +5,9 @@ export function optionsFromEnv(env?: Record<string, string | undefined>): Stopne
 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>;

package/dist/server.js

@@ -71,6 +71,22 @@ export function withStopnetic(handler, options = optionsFromEnv()) {
   };
 }
 
+/** 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);

package/dist/setup.js

@@ -35,62 +35,9 @@ function platformFor(root, supplied) {
   if (vercel && !netlify) return 'vercel';
   throw new SetupError('Choose your hosting explicitly: --platform netlify, vercel or node.');
 }
-const clientGuide = `# Stopnetic client/server setup
+const legacyGuideDigest = 'b1f149af44f9ceb08fb80c18cb5d4b521620196f536d8ad422ab94d15d1d125d';
+const clientGuide = readFileSync(new URL('./client-guide.md', import.meta.url), 'utf8');
 
-Copy .env.stopnetic.example settings to the hosting platform's SERVER environment.
-Use Node.js 22+. Never prefix private settings with VITE_ or REACT_APP_.
-Use the same cookie secret locally and in hosting; do not commit .env.local.
-
-## React Router (inside BrowserRouter)
-
-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>;
-}
-
-Wrap your Routes with RouteGuard. Other frontends can await
-checkAccess(path) from @stopnetic/js/browser before rendering; when reason is
-verification_required, navigate to result.verificationUrl. Handle denial/outages.
-
-## API protection
-
-EACH protected Netlify/Vercel Fetch-style API must use:
-import { withStopnetic } from '@stopnetic/js/server';
-const protectedHandler = withStopnetic(async (request, context) => {
-  // Enforce your application's login/data permissions here too.
-  return Response.json({ example: true });
-});
-// Netlify: export default protectedHandler;
-//          export const config = { path: '/api/private', preferStatic: false };
-// Vercel: export default { fetch: protectedHandler };
-
-Node/Express: call installStopnetic(app) from ./stopnetic.server.mjs BEFORE
-parsers, static files and routes. Only expose that guarded server to visitors.
-
-Add a Page / Automatic browser flow rule and API / Require verified session rules
-in Stopnetic Policies. The generated setup leaves unmatched routes public.
-Netlify's default /.netlify/functions/ aliases are rejected by the wrapper; use
-custom config.path endpoints in React and Policies. Fetch protected data with
-credentials: 'same-origin'. API requests cannot start
-the browser verification flow. All control endpoints must reach their function
-before a SPA catch-all; verify redirects and custom function directories.
-
-Deploy once, then change rules in the dashboard. Rules apply to subsequent
-guarded requests; loaded content is not recalled. Wrap new API handlers too.
-For local Netlify/Vercel testing, use their full local development server
-(netlify dev / vercel dev), not Vite alone: the server functions must run too.
-For Node, load .env.local with node --env-file=.env.local your-server.mjs,
-or your existing server environment loader.
-Static HTML/JS and content bundled into the frontend remain public. A UI gate
-does not secure that content. Put private data in guarded server endpoints.
-No Edge/Deno/Cloudflare Workers adapter is supplied. Next.js uses @stopnetic/next.
-Test real hosting, custom domains, cookies, caches, aliases and API enforcement.
-`;
 function filesFor(root, platform) {
   const files = {
     'stopnetic-client-guide.md': clientGuide,
@@ -121,15 +68,21 @@ export function setup(input, { platform: supplied, dryRun = false } = {}) {
   const platform = platformFor(root, supplied);
   const files = filesFor(root, platform);
   const manifestPath = destination(root, manifestName);
+  let manifest;
   if (existsSync(manifestPath)) {
-    let manifest;
     try { manifest = JSON.parse(text(manifestPath)); } catch { throw new SetupError('Check the existing Stopnetic setup manifest.'); }
     if (manifest.platform !== platform) throw new SetupError('A different hosting setup already exists. Review it before changing platform.');
   }
-  // Validate every destination before making any change. No customer file is replaced.
+  const upgraded = new Set();
+  // Validate every destination before making any change. Only an unchanged
+  // older generated guide can be replaced; customer modifications are refused.
   for (const [name, content] of Object.entries(files)) {
     const file = destination(root, name);
-    if (existsSync(file) && text(file) !== content) throw new SetupError(`Existing file needs manual merging: ${name}`);
+    if (existsSync(file) && text(file) !== content) {
+      if (name === 'stopnetic-client-guide.md' && manifest?.files?.[name] === legacyGuideDigest
+        && digest(text(file)) === legacyGuideDigest) upgraded.add(name);
+      else throw new SetupError(`Existing file needs manual merging: ${name}`);
+    }
   }
   const local = destination(root, '.env.local');
   const ignore = destination(root, '.gitignore');
@@ -138,7 +91,8 @@ export function setup(input, { platform: supplied, dryRun = false } = {}) {
   for (const [name, content] of Object.entries(files)) {
     const file = destination(root, name);
     mkdirSync(dirname(file), { recursive: true });
-    if (!existsSync(file)) writeFileSync(file, content, { flag: 'wx' });
+    if (upgraded.has(name)) writeFileSync(file, content);
+    else if (!existsSync(file)) writeFileSync(file, content, { flag: 'wx' });
   }
   if (!env.STOPNETIC_COOKIE_SECRET) writeFileSync(local, `${text(local).replace(/\n?$/, '\n')}STOPNETIC_COOKIE_SECRET=${randomBytes(32).toString('base64url')}\n`, { mode: 0o600 });
   if (!/(^|\n)\.env\.local$/.test(text(ignore).trimEnd())) writeFileSync(ignore, `${text(ignore).replace(/\n?$/, '\n')}.env.local\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stopnetic/js",
-  "version": "0.0.2-pilot",
+  "version": "0.0.3-pilot",
   "description": "Server-side Stopnetic guard for JavaScript websites, Node.js and Express-compatible servers.",
   "type": "module",
   "license": "MIT",