@stopnetic/js 0.0.1-pilot → 0.0.3-pilot

package/dist/browser.js

@@ -0,0 +1,21 @@
+// Browser-only entry: no Node imports, installation keys or cookie secrets.
+export async function checkAccess(path, { signal, fetchImpl = globalThis.fetch } = {}) {
+  if (typeof path !== 'string' || !path.startsWith('/') || path.startsWith('//') || /[\\\s#]/.test(path)) throw new Error('Use a same-origin page path');
+  const url = `/api/stopnetic/access?${new URLSearchParams({ path, mode: 'check' })}`;
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (signal?.aborted) abort();
+  signal?.addEventListener('abort', abort, { once: true });
+  const timer = setTimeout(abort, 10000);
+  let response, result;
+  try {
+    response = await fetchImpl(url, { credentials: 'same-origin', cache: 'no-store', signal: controller.signal, headers: { Accept: 'application/json' } });
+    result = await response.json();
+  } catch (error) { if (signal?.aborted) throw error; return { allowed: false, reason: 'unavailable' }; }
+  finally { clearTimeout(timer); signal?.removeEventListener('abort', abort); }
+  if (response.status === 200 && result?.allowed === true) return { allowed: true };
+  if (response.status === 404 && result?.reason === 'verification_required') {
+    return { allowed: false, reason: 'verification_required', verificationUrl: `/api/stopnetic/access?${new URLSearchParams({ path })}` };
+  }
+  return { allowed: false, reason: response.status === 404 ? 'blocked' : 'unavailable' };
+}

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/guard.d.ts

@@ -1,21 +1,23 @@
-export type StopneticOptions = {
-  siteId: string;
-  apiUrl: string;
-  apiToken: string;
-  decisionPublicKey: string;
-  /** Explicitly trusted replacement/retiring public PEMs, at most two. */
-  additionalDecisionPublicKeys?: string[];
-  cookieSecret: string;
-  verifyPath?: string;
-  cookieName?: string;
-  secureCookie?: boolean;
-  fetchImpl?: typeof fetch;
-  timeoutMs?: number;
-  publicPaths?: string[];
-  reportEvents?: boolean;
-};
-export function parseAdditionalDecisionPublicKeys(value?: string): string[];
-export function createStopnetic(options: StopneticOptions): {
-  check(request: Request): Promise<Response | null>;
-  verify(request: Request): Promise<Response>;
-};
+export type StopneticOptions = {
+  siteId: string;
+  apiUrl: string;
+  apiToken: string;
+  decisionPublicKey: string;
+  /** Explicitly trusted replacement/retiring public PEMs, at most two. */
+  additionalDecisionPublicKeys?: string[];
+  cookieSecret: string;
+  verifyPath?: string;
+  cookieName?: string;
+  secureCookie?: boolean;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+  publicPaths?: string[];
+  reportEvents?: boolean;
+  /** Whole-site mode: unmatched routes public; requires the updated service. */
+  guardMode?: 'selected' | 'site';
+};
+export function parseAdditionalDecisionPublicKeys(value?: string): string[];
+export function createStopnetic(options: StopneticOptions): {
+  check(request: Request): Promise<Response | null>;
+  verify(request: Request): Promise<Response>;
+};