@stopnetic/js 0.0.3-pilot → 0.0.5-pilot

package/dist/setup.js

@@ -35,7 +35,11 @@ function platformFor(root, supplied) {
   if (vercel && !netlify) return 'vercel';
   throw new SetupError('Choose your hosting explicitly: --platform netlify, vercel or node.');
 }
-const legacyGuideDigest = 'b1f149af44f9ceb08fb80c18cb5d4b521620196f536d8ad422ab94d15d1d125d';
+const legacyGuideDigests = new Set([
+  'b1f149af44f9ceb08fb80c18cb5d4b521620196f536d8ad422ab94d15d1d125d', // 0.0.2
+  '55e36295b6aa87ad9558cde29786998483095adeae74e149ff5c7fe78507fad7', // published 0.0.3
+  '08f919257d8c85af4e56e842705825832ae2810ed68d5c1dfc8405c8f7be7610', // published 0.0.4
+]);
 const clientGuide = readFileSync(new URL('./client-guide.md', import.meta.url), 'utf8');
 
 function filesFor(root, platform) {
@@ -79,8 +83,9 @@ export function setup(input, { platform: supplied, dryRun = false } = {}) {
   for (const [name, content] of Object.entries(files)) {
     const file = destination(root, name);
     if (existsSync(file) && text(file) !== content) {
-      if (name === 'stopnetic-client-guide.md' && manifest?.files?.[name] === legacyGuideDigest
-        && digest(text(file)) === legacyGuideDigest) upgraded.add(name);
+      const recorded = manifest?.files?.[name];
+      if (name === 'stopnetic-client-guide.md' && legacyGuideDigests.has(recorded)
+        && digest(text(file)) === recorded) upgraded.add(name);
       else throw new SetupError(`Existing file needs manual merging: ${name}`);
     }
   }
@@ -115,5 +120,5 @@ export function checkSetup(input, { localHttp = false } = {}) {
     if (!localHttp && !options.apiUrl?.startsWith('https:')) throw new Error();
     createStopneticAccessHandler(options);
   } catch { throw new SetupError('Check server settings, HTTPS URLs, installation/signing keys and the separate cookie secret. No secret values are displayed.'); }
-  return `Checked ${manifest.platform} generated files and server configuration offline. Confirm the browser boundary, API wrappers and hosting routing with a deployed test. This does not prove coverage or start a trial.`;
+  return `Checked ${manifest.platform} generated files and server configuration offline. Confirm server page enforcement, your chosen navigation mode, API wrappers and hosting routing with a deployed test. Preserve existing SSR; browser gates are optional. This does not prove coverage or start a trial.`;
 }

package/examples/frontend/angular/app/app.config.ts

@@ -0,0 +1,8 @@
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient } from '@angular/common/http';
+import { provideRouter } from '@angular/router';
+import { routes } from './app.routes';
+export const appConfig: ApplicationConfig = {
+  providers: [provideRouter(routes), provideHttpClient()],
+};
+// Merge these providers into your existing appConfig; retain its other settings.

package/examples/frontend/angular/app/app.routes.ts

@@ -0,0 +1,20 @@
+import { Component } from '@angular/core';
+import { Routes } from '@angular/router';
+import { MembersPage } from './members.page';
+import { stopneticRouteGuard } from './stopnetic-access.service';
+
+@Component({ template: '<main><h1>Home</h1></main>' })
+class HomePage {}
+@Component({ template: '<main><h1>Slow</h1></main>' })
+class OtherPage {}
+
+const pages: Routes = [
+  { path: '', pathMatch: 'full', component: HomePage },
+  { path: 'members', component: MembersPage },
+  { path: 'slow', component: OtherPage },
+  { path: 'blocked', component: OtherPage },
+  { path: 'offline', component: OtherPage },
+];
+export const routes: Routes = pages.map(route => ({
+  ...route, canActivate: [stopneticRouteGuard], runGuardsAndResolvers: 'always' as const,
+}));

package/examples/frontend/angular/app/app.ts

@@ -0,0 +1,21 @@
+import { Component, inject } from '@angular/core';
+import { RouterLink, RouterOutlet } from '@angular/router';
+import { StopneticAccess } from './stopnetic-access.service';
+
+@Component({
+  selector: 'app-root', imports: [RouterLink, RouterOutlet],
+  template: `
+    @if (access.state() === 'allowed') {
+      <header><nav>
+        <a routerLink="/">Home</a> <a routerLink="/members">Members</a>
+        <a routerLink="/slow">Slow</a> <a routerLink="/blocked">Blocked</a>
+        <a routerLink="/offline">Offline</a>
+      </nav></header>
+      <router-outlet/>
+      <footer>Example site</footer>
+    } @else if (access.state() === 'denied') {
+      <p role="alert">Access unavailable.</p>
+    }
+  `,
+})
+export class App { readonly access = inject(StopneticAccess); }

package/examples/frontend/angular/app/members.page.ts

@@ -0,0 +1,21 @@
+import { isPlatformBrowser } from '@angular/common';
+import { Component, DestroyRef, inject, OnInit, PLATFORM_ID, signal } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+
+@Component({ template: '<main><h1>Members</h1><p>{{ data() }}</p></main>' })
+export class MembersPage implements OnInit {
+  readonly data = signal('Loading data...');
+  private readonly http = inject(HttpClient);
+  private readonly destroyRef = inject(DestroyRef);
+  private readonly platform = inject(PLATFORM_ID);
+  ngOnInit() {
+    // This example loads data in the browser. SSR fetches need request cookies
+    // forwarded explicitly, plus server authorization; do not bypass the guard.
+    if (!isPlatformBrowser(this.platform)) return;
+    this.http.get('/api/private', { withCredentials: true })
+      .pipe(takeUntilDestroyed(this.destroyRef))
+      .subscribe({ next: value => this.data.set(JSON.stringify(value)),
+        error: () => this.data.set('API access unavailable.') });
+  }
+}

package/examples/frontend/angular/app/stopnetic-access.service.ts

@@ -0,0 +1,27 @@
+import { isPlatformBrowser } from '@angular/common';
+import { inject, Injectable, PLATFORM_ID, signal } from '@angular/core';
+import { CanActivateFn } from '@angular/router';
+import { checkAccess } from '@stopnetic/js/browser';
+
+@Injectable({ providedIn: 'root' })
+export class StopneticAccess {
+  readonly state = signal<'checking' | 'allowed' | 'denied'>('checking');
+  private readonly platform = inject(PLATFORM_ID);
+  private current?: AbortController;
+  async check(path: string): Promise<boolean> {
+    // Node SSR must be authorized by the SERVER guard before Angular renders.
+    if (!isPlatformBrowser(this.platform)) { this.state.set('allowed'); return true; }
+    this.current?.abort();
+    const controller = new AbortController(); this.current = controller;
+    this.state.set('checking');
+    try {
+      const result = await checkAccess(path.split('#')[0], { signal: controller.signal });
+      if (controller.signal.aborted) return false;
+      if (result.allowed) { this.state.set('allowed'); return true; }
+      if (result.reason === 'verification_required' && result.verificationUrl) location.assign(result.verificationUrl);
+    } catch { if (controller.signal.aborted) return false; }
+    this.state.set('denied'); return false;
+  }
+}
+export const stopneticRouteGuard: CanActivateFn = (_route, state) =>
+  inject(StopneticAccess).check(state.url);

package/examples/frontend/angular/main.ts

@@ -0,0 +1,4 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+import { App } from './app/app';
+import { appConfig } from './app/app.config';
+bootstrapApplication(App, appConfig).catch(error => console.error(error));

package/examples/frontend/load-private-data.d.ts

@@ -0,0 +1 @@
+export function loadPrivateData(signal?: AbortSignal): Promise<unknown>;

package/examples/frontend/load-private-data.js

@@ -0,0 +1,9 @@
+// Browser example. The /api/private SERVER handler must also be guarded.
+export async function loadPrivateData(signal) {
+  const response = await fetch('/api/private', {
+    credentials: 'same-origin', cache: 'no-store', signal,
+    headers: { Accept: 'application/json' },
+  });
+  if (!response.ok) throw new Error(`Request failed (HTTP ${response.status}).`);
+  return response.json();
+}

package/examples/frontend/react/App.tsx

@@ -0,0 +1,48 @@
+import { useEffect, useState, type ReactNode } from 'react';
+import { BrowserRouter, Link, Route, Routes, useLocation } from 'react-router-dom';
+import { StopneticBoundary } from '@stopnetic/js/react';
+import { loadPrivateData } from '../load-private-data.js';
+
+function RouteGuard({ children }: { children: ReactNode }) {
+  const location = useLocation();
+  return <StopneticBoundary path={location.pathname + location.search}
+    pending={null}
+    blocked={<p>Access unavailable.</p>}>
+    {children}
+  </StopneticBoundary>;
+}
+
+function Members() {
+  const [data, setData] = useState('Loading data...');
+  useEffect(() => {
+    const controller = new AbortController();
+    loadPrivateData(controller.signal)
+      .then(value => { if (!controller.signal.aborted) setData(JSON.stringify(value) ?? 'No data.'); })
+      .catch(() => { if (!controller.signal.aborted) setData('API access unavailable.'); });
+    return () => controller.abort();
+  }, []);
+  return <main><h1>Members</h1><p>{data}</p></main>;
+}
+
+function Layout() {
+  return <>
+    <header><nav>
+      <Link to="/">Home</Link>{' '}<Link to="/members">Members</Link>{' '}
+      <Link to="/slow">Slow</Link>{' '}<Link to="/blocked">Blocked</Link>{' '}
+      <Link to="/offline">Offline</Link>
+    </nav></header>
+    <Routes>
+      <Route caseSensitive path="/" element={<main><h1>Home</h1></main>}/>
+      <Route caseSensitive path="/members" element={<Members/>}/>
+      <Route caseSensitive path="/slow" element={<main><h1>Slow</h1></main>}/>
+      <Route caseSensitive path="/blocked" element={<main><h1>Blocked</h1></main>}/>
+      <Route caseSensitive path="/offline" element={<main><h1>Offline</h1></main>}/>
+      <Route path="*" element={<main><h1>Not found</h1></main>}/>
+    </Routes>
+    <footer>Example site</footer>
+  </>;
+}
+
+export default function App() {
+  return <BrowserRouter><RouteGuard><Layout/></RouteGuard></BrowserRouter>;
+}

package/examples/frontend/react/main.tsx

@@ -0,0 +1,3 @@
+import { createRoot } from 'react-dom/client';
+import App from './App';
+createRoot(document.getElementById('app')!).render(<App/>);

package/examples/frontend/solid/App.tsx

@@ -0,0 +1,54 @@
+import { createEffect, createSignal, onCleanup, Show, type ParentComponent } from 'solid-js';
+import { A, Route, Router, useLocation } from '@solidjs/router';
+import { checkAccess } from '@stopnetic/js/browser';
+import { loadPrivateData } from '../load-private-data.js';
+
+const GuardedLayout: ParentComponent = props => {
+  const location = useLocation();
+  const path = () => location.pathname + location.search;
+  const [result, setResult] = createSignal({ path: '', allowed: false, pending: true });
+  createEffect(() => {
+    const target = path();
+    const controller = new AbortController();
+    setResult({ path: target, allowed: false, pending: true });
+    checkAccess(target, { signal: controller.signal }).then(value => {
+      if (controller.signal.aborted) return;
+      if (!value.allowed && value.reason === 'verification_required' && value.verificationUrl) locationRedirect(value.verificationUrl);
+      setResult({ path: target, allowed: value.allowed, pending: false });
+    }).catch(() => {
+      if (!controller.signal.aborted) setResult({ path: target, allowed: false, pending: false });
+    });
+    onCleanup(() => controller.abort());
+  });
+  return <Show when={result().allowed && result().path === path() ? result() : undefined}
+    fallback={<Show when={!result().pending && result().path === path()}>
+      <p role="alert">Access unavailable.</p></Show>}>
+    {_checked => <>
+      <header><nav><A href="/">Home</A>{' '}<A href="/members">Members</A>{' '}
+        <A href="/slow">Slow</A>{' '}<A href="/blocked">Blocked</A>{' '}<A href="/offline">Offline</A>
+      </nav></header>
+      {props.children}
+      <footer>Example site</footer>
+    </>}
+  </Show>;
+};
+const locationRedirect = (url: string) => window.location.assign(url);
+
+function Members() {
+  const [data, setData] = createSignal('Loading data...');
+  const controller = new AbortController();
+  loadPrivateData(controller.signal)
+    .then(value => { if (!controller.signal.aborted) setData(JSON.stringify(value) ?? 'No data.'); })
+    .catch(() => { if (!controller.signal.aborted) setData('API access unavailable.'); });
+  onCleanup(() => controller.abort());
+  return <main><h1>Members</h1><p>{data()}</p></main>;
+}
+export default function App() {
+  return <Router root={GuardedLayout}>
+    <Route path="/" component={() => <main><h1>Home</h1></main>}/>
+    <Route path="/members" component={Members}/>
+    <Route path="/slow" component={() => <main><h1>Slow</h1></main>}/>
+    <Route path="/blocked" component={() => <main><h1>Blocked</h1></main>}/>
+    <Route path="/offline" component={() => <main><h1>Offline</h1></main>}/>
+  </Router>;
+}

package/examples/frontend/solid/main.tsx

@@ -0,0 +1,3 @@
+import { render } from 'solid-js/web';
+import App from './App';
+render(() => <App/>, document.getElementById('app')!);

package/examples/frontend/svelte/App.svelte

@@ -0,0 +1,56 @@
+<script>
+  import { onMount } from 'svelte';
+  import { checkAccess } from '@stopnetic/js/browser';
+  import { loadPrivateData } from '../load-private-data.js';
+
+  let path = '';
+  let state = 'checking';
+  let data = '';
+  let current;
+  async function showPage() {
+    current?.abort();
+    const controller = new AbortController();
+    current = controller;
+    path = location.pathname;
+    state = 'checking'; data = '';
+    try {
+      const result = await checkAccess(path + location.search, { signal: controller.signal });
+      if (controller.signal.aborted) return;
+      if (!result.allowed) {
+        if (result.reason === 'verification_required' && result.verificationUrl) location.assign(result.verificationUrl);
+        state = 'denied'; return;
+      }
+      state = 'allowed';
+      if (path === '/members') {
+        data = 'Loading data...';
+        try {
+          const value = await loadPrivateData(controller.signal);
+          if (!controller.signal.aborted) data = JSON.stringify(value);
+        } catch { if (!controller.signal.aborted) data = 'API access unavailable.'; }
+      }
+    } catch { if (!controller.signal.aborted) state = 'denied'; }
+  }
+  function navigate(event) {
+    if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    event.preventDefault();
+    history.pushState(null, '', event.currentTarget.href);
+    void showPage();
+  }
+  onMount(() => {
+    void showPage();
+    addEventListener('popstate', showPage);
+    return () => { current?.abort(); removeEventListener('popstate', showPage); };
+  });
+</script>
+
+{#if state === 'allowed'}
+  <header><nav>
+    <a href="/" onclick={navigate}>Home</a> <a href="/members" onclick={navigate}>Members</a>
+    <a href="/slow" onclick={navigate}>Slow</a> <a href="/blocked" onclick={navigate}>Blocked</a>
+    <a href="/offline" onclick={navigate}>Offline</a>
+  </nav></header>
+  <main><h1>{path === '/members' ? 'Members' : path === '/' ? 'Home' : path === '/slow' ? 'Slow' : 'Not found'}</h1><p>{data}</p></main>
+  <footer>Example site</footer>
+{:else if state === 'denied'}
+  <p role="alert">Access unavailable.</p>
+{/if}

package/examples/frontend/svelte/main.js

@@ -0,0 +1,4 @@
+// Svelte 5 entry. Svelte 4 apps retain their existing `new App(...)` entry.
+import { mount } from 'svelte';
+import App from './App.svelte';
+mount(App, { target: document.getElementById('app') });

package/examples/frontend/vanilla/main.js

@@ -0,0 +1,46 @@
+import { checkAccess } from '@stopnetic/js/browser';
+import { loadPrivateData } from '../load-private-data.js';
+const root = document.getElementById('app');
+let current;
+async function showPage() {
+  current?.abort();
+  const controller = new AbortController(); current = controller;
+  root.replaceChildren();
+  try {
+    const path = location.pathname;
+    const result = await checkAccess(path + location.search, { signal: controller.signal });
+    if (controller.signal.aborted) return;
+    if (!result.allowed) {
+      if (result.reason === 'verification_required' && result.verificationUrl) location.assign(result.verificationUrl);
+      const alert = document.createElement('p'); alert.setAttribute('role', 'alert');
+      alert.textContent = 'Access unavailable.'; root.replaceChildren(alert); return;
+    }
+    const header = document.createElement('header');
+    const nav = document.createElement('nav'); header.append(nav);
+    for (const [url, name] of [['/', 'Home'], ['/members', 'Members'], ['/slow', 'Slow'], ['/blocked', 'Blocked'], ['/offline', 'Offline']]) {
+      const link = document.createElement('a'); link.href = url; link.textContent = name;
+      link.addEventListener('click', event => {
+        if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+        event.preventDefault(); history.pushState(null, '', url); void showPage();
+      });
+      nav.append(link, document.createTextNode(' '));
+    }
+    const main = document.createElement('main'); const heading = document.createElement('h1');
+    heading.textContent = path === '/members' ? 'Members' : path === '/' ? 'Home' : path === '/slow' ? 'Slow' : 'Not found';
+    const data = document.createElement('p'); main.append(heading, data);
+    const footer = document.createElement('footer'); footer.textContent = 'Example site';
+    root.replaceChildren(header, main, footer);
+    if (path === '/members') {
+      data.textContent = 'Loading data...';
+      try {
+        const value = await loadPrivateData(controller.signal);
+        if (!controller.signal.aborted) data.textContent = JSON.stringify(value);
+      } catch { if (!controller.signal.aborted) data.textContent = 'API access unavailable.'; }
+    }
+  } catch {
+    if (!controller.signal.aborted) root.replaceChildren(document.createTextNode('Access unavailable.'));
+  }
+}
+addEventListener('popstate', showPage);
+addEventListener('pagehide', () => current?.abort());
+void showPage();

package/examples/frontend/vue/App.vue

@@ -0,0 +1,17 @@
+<script setup>
+import { RouterLink, RouterView } from 'vue-router';
+import { accessState } from './router.js';
+</script>
+
+<template>
+  <template v-if="accessState === 'allowed'">
+    <header><nav>
+      <RouterLink to="/">Home</RouterLink> <RouterLink to="/members">Members</RouterLink>
+      <RouterLink to="/slow">Slow</RouterLink> <RouterLink to="/blocked">Blocked</RouterLink>
+      <RouterLink to="/offline">Offline</RouterLink>
+    </nav></header>
+    <RouterView/>
+    <footer>Example site</footer>
+  </template>
+  <p v-else-if="accessState === 'denied'" role="alert">Access unavailable.</p>
+</template>

package/examples/frontend/vue/Members.vue

@@ -0,0 +1,14 @@
+<script setup>
+import { onMounted, onUnmounted, ref } from 'vue';
+import { loadPrivateData } from '../load-private-data.js';
+const data = ref('Loading data...');
+const controller = new AbortController();
+onMounted(() => {
+  loadPrivateData(controller.signal)
+    .then(value => { if (!controller.signal.aborted) data.value = JSON.stringify(value); })
+    .catch(() => { if (!controller.signal.aborted) data.value = 'API access unavailable.'; });
+});
+onUnmounted(() => controller.abort());
+</script>
+
+<template><main><h1>Members</h1><p>{{ data }}</p></main></template>

package/examples/frontend/vue/main.js

@@ -0,0 +1,4 @@
+import { createApp } from 'vue';
+import App from './App.vue';
+import { router } from './router.js';
+createApp(App).use(router).mount('#app');

package/examples/frontend/vue/router.js

@@ -0,0 +1,40 @@
+import { h, ref } from 'vue';
+import { createRouter, createWebHistory } from 'vue-router';
+import { checkAccess } from '@stopnetic/js/browser';
+import Members from './Members.vue';
+
+export const accessState = ref('checking');
+const page = title => ({ render: () => h('main', h('h1', title)) });
+export const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: '/', component: page('Home') },
+    { path: '/members', component: Members },
+    { path: '/slow', component: page('Slow') },
+    { path: '/blocked', component: page('Blocked') },
+    { path: '/offline', component: page('Offline') },
+  ],
+});
+
+let current;
+let approvedPath = '';
+router.beforeEach(async to => {
+  current?.abort();
+  const controller = new AbortController();
+  current = controller;
+  approvedPath = '';
+  accessState.value = 'checking';
+  try {
+    const result = await checkAccess(to.fullPath.split('#')[0], { signal: controller.signal });
+    if (controller.signal.aborted) return false;
+    if (result.allowed) { approvedPath = to.fullPath; return true; }
+    if (result.reason === 'verification_required' && result.verificationUrl) {
+      location.assign(result.verificationUrl);
+    }
+    accessState.value = 'denied';
+  } catch { if (!controller.signal.aborted) accessState.value = 'denied'; }
+  return false;
+});
+router.afterEach((to, _from, failure) => {
+  if (!failure && approvedPath === to.fullPath) accessState.value = 'allowed';
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stopnetic/js",
-  "version": "0.0.3-pilot",
+  "version": "0.0.5-pilot",
   "description": "Server-side Stopnetic guard for JavaScript websites, Node.js and Express-compatible servers.",
   "type": "module",
   "license": "MIT",
@@ -19,7 +19,8 @@
   ],
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "examples/frontend"
   ],
   "bin": { "stopnetic-js": "./bin/stopnetic-js.js" },
   "exports": {