@stopnetic/js 0.0.1-pilot → 0.0.2-pilot

package/dist/index.js

@@ -1,172 +1,172 @@
-import { createStopnetic } from './guard.js';
-export { createStopnetic, parseAdditionalDecisionPublicKeys } from './guard.js';
-
-const denied = () => new Response(null, { status: 404, headers: { 'cache-control': 'no-store' } });
-const unavailable = () => new Response(null, { status: 503, headers: { 'cache-control': 'no-store' } });
-
-function canonicalOrigin(value) {
-  let url;
-  try { url = new URL(value); } catch { throw new Error('origin must be an HTTPS origin (HTTP only on localhost)'); }
-  if (url.username || url.password || url.pathname !== '/' || url.search || url.hash
-    || !(url.protocol === 'https:' || (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))) {
-    throw new Error('origin must be an HTTPS origin (HTTP only on localhost)');
-  }
-  return url.origin;
-}
-
-function target(raw, origin) {
-  if (typeof raw !== 'string' || !raw.startsWith('/') || raw.startsWith('//') || /[\\\s#]/.test(raw)) throw new Error('Invalid request target');
-  const url = new URL(raw, origin);
-  // Do not let URL normalization or downstream decoding change the checked path.
-  if (url.origin !== origin || url.pathname + url.search !== raw) throw new Error('Invalid request target');
-  const decoded = decodeURIComponent(url.pathname);
-  if (/[\\\s?#%]/.test(decoded) || /[\x00-\x1f\x7f]/.test(decoded)
-    || decoded.split('/').some(part => part === '.' || part === '..')
-    || /%[0-7][0-9a-f]/i.test(url.pathname) || url.pathname.includes('//')) throw new Error('Ambiguous request path');
-  return url;
-}
-
-function optionsForGuard(options, origin) {
-  const local = origin.startsWith('http:');
-  if (!local && options.secureCookie === false) throw new Error('HTTPS sites require secure cookies');
-  // A verification request must reach the verification handler, not a bypass.
-  return { ...options, secureCookie: !local };
-}
-
-async function boundedWebBody(request) {
-  if (Number(request.headers.get('content-length')) > 4096) throw new Error('Body too large');
-  const reader = request.body?.getReader();
-  if (!reader) throw new Error('Missing body');
-  const chunks = [];
-  let size = 0;
-  let timer;
-  let finished = false;
-  const deadline = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Body timeout')), 5000); });
-  try {
-    for (;;) {
-      const { value, done } = await Promise.race([reader.read(), deadline]);
-      if (done) { finished = true; return Buffer.concat(chunks, size); }
-      size += value.byteLength;
-      if (size > 4096) throw new Error('Body too large');
-      chunks.push(Buffer.from(value));
-    }
-  } finally {
-    clearTimeout(timer);
-    if (!finished) void reader.cancel().catch(() => {});
-    reader.releaseLock();
-  }
-}
-
-/** Fetch-style adapter for Node-hosted frameworks. Always handles verification. */
-export function createStopneticHandler(options) {
-  const origin = canonicalOrigin(options.origin);
-  const guard = createStopnetic(optionsForGuard(options, origin));
-  const verifyPath = options.verifyPath || '/__stopnetic/verify';
-  return async function handle(request, next) {
-    let response;
-    try {
-      const url = new URL(request.url);
-      if (url.origin !== origin || (request.headers.has('host') && request.headers.get('host').toLowerCase() !== url.host)) return denied();
-      target(url.pathname + url.search, origin);
-      if (url.pathname === verifyPath) {
-        if (request.method !== 'POST' || request.headers.get('origin') !== origin
-          || !(request.headers.get('content-type') || '').toLowerCase().startsWith('application/json')) {
-          return request.method === 'POST' ? denied() : new Response(null, { status: 405, headers: { allow: 'POST', 'cache-control': 'no-store' } });
-        }
-        try {
-          const body = await boundedWebBody(request);
-          response = await guard.verify(new Request(request.url, { method: 'POST', headers: request.headers, body }));
-        } catch { return denied(); }
-      } else response = await guard.check(request);
-    } catch { return unavailable(); }
-    if (response) return response;
-    const result = await next(request);
-    // Copy headers, including individual cookies, without buffering the body.
-    const headers = new Headers(result.headers);
-    headers.set('cache-control', 'private, no-store');
-    return new Response(result.body, { status: result.status, statusText: result.statusText, headers });
-  };
-}
-
-function requestHeaders(req, origin) {
-  const headers = new Headers();
-  for (const name of ['accept', 'cookie', 'origin', 'content-type', 'content-length']) {
-    const value = req.headers[name];
-    if (Array.isArray(value)) throw new Error('Ambiguous request headers');
-    if (value !== undefined) headers.set(name, value);
-  }
-  headers.set('host', new URL(origin).host);
-  return headers;
-}
-
-function verificationBody(req) {
-  return new Promise((resolve, reject) => {
-    if (req.readableEnded || req.destroyed) { reject(new Error('Verification body unavailable')); return; }
-    const chunks = [];
-    let size = 0;
-    const cleanup = () => {
-      clearTimeout(timer);
-      req.off('data', data); req.off('end', end); req.off('error', fail); req.off('aborted', fail);
-    };
-    const fail = () => { cleanup(); req.pause(); reject(new Error('Invalid verification body')); };
-    const data = chunk => {
-      const bytes = Buffer.from(chunk);
-      size += bytes.length;
-      if (size > 4096) { fail(); return; }
-      chunks.push(bytes);
-    };
-    const end = () => { cleanup(); resolve(Buffer.concat(chunks, size)); };
-    const timer = setTimeout(fail, 5000);
-    req.on('data', data); req.once('end', end); req.once('error', fail); req.once('aborted', fail);
-  });
-}
-
-async function send(response, req, res, close = false) {
-  res.statusCode = response.status;
-  response.headers.forEach((value, name) => { if (name !== 'set-cookie') res.setHeader(name, value); });
-  const cookies = response.headers.getSetCookie();
-  if (cookies.length) res.setHeader('set-cookie', cookies);
-  if (close) res.setHeader('connection', 'close');
-  const body = req.method === 'HEAD' ? undefined : Buffer.from(await response.arrayBuffer());
-  res.end(body);
-}
-
-/** Use first, at the application root, before parsers, static files and routes. */
-export function createStopneticMiddleware(options) {
-  const origin = canonicalOrigin(options.origin);
-  const guard = createStopnetic(optionsForGuard(options, origin));
-  const verifyPath = options.verifyPath || '/__stopnetic/verify';
-  return async function stopnetic(req, res, next) {
-    let response;
-    let close = false;
-    try {
-      const host = req.headers.host;
-      if (typeof host !== 'string' || host.toLowerCase() !== new URL(origin).host) response = denied();
-      else {
-        const url = target(req.originalUrl || req.url, origin);
-        const headers = requestHeaders(req, origin);
-        const method = req.method || 'GET';
-        if (url.pathname === verifyPath) {
-          if (method !== 'POST') response = new Response(null, { status: 405, headers: { allow: 'POST', 'cache-control': 'no-store' } });
-          else if (headers.get('origin') !== origin || !(headers.get('content-type') || '').toLowerCase().startsWith('application/json')
-            || Number(headers.get('content-length')) > 4096) { response = denied(); close = true; }
-          else {
-            try {
-              const body = await verificationBody(req);
-              response = await guard.verify(new Request(url, { method, headers, body }));
-            } catch { response = denied(); close = true; }
-          }
-        } else {
-          // Checking ordinary requests must leave their bodies for the application.
-          response = await guard.check(new Request(url, { method, headers }));
-        }
-      }
-    } catch { response = unavailable(); close = true; }
-    if (response) {
-      try { await send(response, req, res, close); } catch { res.destroy(); }
-      return;
-    }
-    res.setHeader('cache-control', 'private, no-store');
-    return next();
-  };
-}
+import { createStopnetic } from './guard.js';
+export { createStopnetic, parseAdditionalDecisionPublicKeys } from './guard.js';
+
+const denied = () => new Response(null, { status: 404, headers: { 'cache-control': 'no-store' } });
+const unavailable = () => new Response(null, { status: 503, headers: { 'cache-control': 'no-store' } });
+
+function canonicalOrigin(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new Error('origin must be an HTTPS origin (HTTP only on localhost)'); }
+  if (url.username || url.password || url.pathname !== '/' || url.search || url.hash
+    || !(url.protocol === 'https:' || (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))) {
+    throw new Error('origin must be an HTTPS origin (HTTP only on localhost)');
+  }
+  return url.origin;
+}
+
+function target(raw, origin) {
+  if (typeof raw !== 'string' || !raw.startsWith('/') || raw.startsWith('//') || /[\\\s#]/.test(raw)) throw new Error('Invalid request target');
+  const url = new URL(raw, origin);
+  // Do not let URL normalization or downstream decoding change the checked path.
+  if (url.origin !== origin || url.pathname + url.search !== raw) throw new Error('Invalid request target');
+  const decoded = decodeURIComponent(url.pathname);
+  if (/[\\\s?#%]/.test(decoded) || /[\x00-\x1f\x7f]/.test(decoded)
+    || decoded.split('/').some(part => part === '.' || part === '..')
+    || /%[0-7][0-9a-f]/i.test(url.pathname) || url.pathname.includes('//')) throw new Error('Ambiguous request path');
+  return url;
+}
+
+function optionsForGuard(options, origin) {
+  const local = origin.startsWith('http:');
+  if (!local && options.secureCookie === false) throw new Error('HTTPS sites require secure cookies');
+  // A verification request must reach the verification handler, not a bypass.
+  return { ...options, secureCookie: !local };
+}
+
+async function boundedWebBody(request) {
+  if (Number(request.headers.get('content-length')) > 4096) throw new Error('Body too large');
+  const reader = request.body?.getReader();
+  if (!reader) throw new Error('Missing body');
+  const chunks = [];
+  let size = 0;
+  let timer;
+  let finished = false;
+  const deadline = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Body timeout')), 5000); });
+  try {
+    for (;;) {
+      const { value, done } = await Promise.race([reader.read(), deadline]);
+      if (done) { finished = true; return Buffer.concat(chunks, size); }
+      size += value.byteLength;
+      if (size > 4096) throw new Error('Body too large');
+      chunks.push(Buffer.from(value));
+    }
+  } finally {
+    clearTimeout(timer);
+    if (!finished) void reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}
+
+/** Fetch-style adapter for Node-hosted frameworks. Always handles verification. */
+export function createStopneticHandler(options) {
+  const origin = canonicalOrigin(options.origin);
+  const guard = createStopnetic(optionsForGuard(options, origin));
+  const verifyPath = options.verifyPath || '/__stopnetic/verify';
+  return async function handle(request, next) {
+    let response;
+    try {
+      const url = new URL(request.url);
+      if (url.origin !== origin || (request.headers.has('host') && request.headers.get('host').toLowerCase() !== url.host)) return denied();
+      target(url.pathname + url.search, origin);
+      if (url.pathname === verifyPath) {
+        if (request.method !== 'POST' || request.headers.get('origin') !== origin
+          || !(request.headers.get('content-type') || '').toLowerCase().startsWith('application/json')) {
+          return request.method === 'POST' ? denied() : new Response(null, { status: 405, headers: { allow: 'POST', 'cache-control': 'no-store' } });
+        }
+        try {
+          const body = await boundedWebBody(request);
+          response = await guard.verify(new Request(request.url, { method: 'POST', headers: request.headers, body }));
+        } catch { return denied(); }
+      } else response = await guard.check(request);
+    } catch { return unavailable(); }
+    if (response) return response;
+    const result = await next(request);
+    // Copy headers, including individual cookies, without buffering the body.
+    const headers = new Headers(result.headers);
+    headers.set('cache-control', 'private, no-store');
+    return new Response(result.body, { status: result.status, statusText: result.statusText, headers });
+  };
+}
+
+function requestHeaders(req, origin) {
+  const headers = new Headers();
+  for (const name of ['accept', 'cookie', 'origin', 'content-type', 'content-length']) {
+    const value = req.headers[name];
+    if (Array.isArray(value)) throw new Error('Ambiguous request headers');
+    if (value !== undefined) headers.set(name, value);
+  }
+  headers.set('host', new URL(origin).host);
+  return headers;
+}
+
+function verificationBody(req) {
+  return new Promise((resolve, reject) => {
+    if (req.readableEnded || req.destroyed) { reject(new Error('Verification body unavailable')); return; }
+    const chunks = [];
+    let size = 0;
+    const cleanup = () => {
+      clearTimeout(timer);
+      req.off('data', data); req.off('end', end); req.off('error', fail); req.off('aborted', fail);
+    };
+    const fail = () => { cleanup(); req.pause(); reject(new Error('Invalid verification body')); };
+    const data = chunk => {
+      const bytes = Buffer.from(chunk);
+      size += bytes.length;
+      if (size > 4096) { fail(); return; }
+      chunks.push(bytes);
+    };
+    const end = () => { cleanup(); resolve(Buffer.concat(chunks, size)); };
+    const timer = setTimeout(fail, 5000);
+    req.on('data', data); req.once('end', end); req.once('error', fail); req.once('aborted', fail);
+  });
+}
+
+async function send(response, req, res, close = false) {
+  res.statusCode = response.status;
+  response.headers.forEach((value, name) => { if (name !== 'set-cookie') res.setHeader(name, value); });
+  const cookies = response.headers.getSetCookie();
+  if (cookies.length) res.setHeader('set-cookie', cookies);
+  if (close) res.setHeader('connection', 'close');
+  const body = req.method === 'HEAD' ? undefined : Buffer.from(await response.arrayBuffer());
+  res.end(body);
+}
+
+/** Use first, at the application root, before parsers, static files and routes. */
+export function createStopneticMiddleware(options) {
+  const origin = canonicalOrigin(options.origin);
+  const guard = createStopnetic(optionsForGuard(options, origin));
+  const verifyPath = options.verifyPath || '/__stopnetic/verify';
+  return async function stopnetic(req, res, next) {
+    let response;
+    let close = false;
+    try {
+      const host = req.headers.host;
+      if (typeof host !== 'string' || host.toLowerCase() !== new URL(origin).host) response = denied();
+      else {
+        const url = target(req.originalUrl || req.url, origin);
+        const headers = requestHeaders(req, origin);
+        const method = req.method || 'GET';
+        if (url.pathname === verifyPath) {
+          if (method !== 'POST') response = new Response(null, { status: 405, headers: { allow: 'POST', 'cache-control': 'no-store' } });
+          else if (headers.get('origin') !== origin || !(headers.get('content-type') || '').toLowerCase().startsWith('application/json')
+            || Number(headers.get('content-length')) > 4096) { response = denied(); close = true; }
+          else {
+            try {
+              const body = await verificationBody(req);
+              response = await guard.verify(new Request(url, { method, headers, body }));
+            } catch { response = denied(); close = true; }
+          }
+        } else {
+          // Checking ordinary requests must leave their bodies for the application.
+          response = await guard.check(new Request(url, { method, headers }));
+        }
+      }
+    } catch { response = unavailable(); close = true; }
+    if (response) {
+      try { await send(response, req, res, close); } catch { res.destroy(); }
+      return;
+    }
+    res.setHeader('cache-control', 'private, no-store');
+    return next();
+  };
+}

package/dist/react.d.ts

@@ -0,0 +1,4 @@
+import type { ReactNode } from 'react';
+export function StopneticBoundary(props: {
+  path: string; children?: ReactNode; pending?: ReactNode; blocked?: ReactNode; redirect?: boolean;
+}): ReactNode;

package/dist/react.js

@@ -0,0 +1,24 @@
+import { createElement, useEffect, useState } from 'react';
+import { checkAccess } from './browser.js';
+
+/** UI boundary only. Keep private data in independently guarded server endpoints. */
+export function StopneticBoundary(props) {
+  return createElement(CheckedBoundary, { ...props, key: props.path });
+}
+
+function CheckedBoundary({ path, children, pending = 'Checking access…', blocked = 'Access unavailable.', redirect = true }) {
+  const [result, setResult] = useState(null);
+  useEffect(() => {
+    const controller = new AbortController();
+    checkAccess(path, { signal: controller.signal }).then(value => {
+      if (!controller.signal.aborted) {
+        setResult({ ...value, path });
+        if (redirect && value.reason === 'verification_required') window.location.assign(value.verificationUrl);
+      }
+    }).catch(() => { if (!controller.signal.aborted) setResult({ allowed: false, reason: 'unavailable', path }); });
+    return () => controller.abort();
+  }, [path, redirect]);
+  if (!result || result.path !== path) return createElement('div', { role: 'status' }, pending);
+  if (!result.allowed) return createElement('div', { role: 'alert' }, blocked);
+  return children;
+}

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { StopneticServerOptions } from './index.js';
+export const accessBase: '/api/stopnetic';
+export function optionsFromEnv(env?: Record<string, string | undefined>): StopneticServerOptions;
+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>;
+export function createStopneticAccessMiddleware(options?: StopneticServerOptions): (
+  request: IncomingMessage & { originalUrl?: string }, response: ServerResponse, next: () => unknown,
+) => Promise<unknown>;
+export function createStopneticServer(options?: StopneticServerOptions): {
+  access: ReturnType<typeof createStopneticAccessMiddleware>;
+  guard: ReturnType<typeof import('./index.js').createStopneticMiddleware>;
+};

package/dist/server.js

@@ -0,0 +1,107 @@
+import { createStopneticHandler, createStopneticMiddleware, parseAdditionalDecisionPublicKeys } from './index.js';
+
+export const accessBase = '/api/stopnetic';
+
+/** Server environment only. Never import this module into browser code. */
+export function optionsFromEnv(env = process.env) {
+  return {
+    origin: env.STOPNETIC_WEBSITE_ORIGIN,
+    siteId: env.STOPNETIC_SITE_ID,
+    apiUrl: env.STOPNETIC_API_URL,
+    apiToken: env.STOPNETIC_API_TOKEN,
+    decisionPublicKey: env.STOPNETIC_DECISION_PUBLIC_KEY?.replaceAll('\\n', '\n'),
+    additionalDecisionPublicKeys: parseAdditionalDecisionPublicKeys(env.STOPNETIC_DECISION_ADDITIONAL_PUBLIC_KEYS),
+    cookieSecret: env.STOPNETIC_COOKIE_SECRET,
+    guardMode: 'site',
+    verifyPath: `${accessBase}/verify`,
+  };
+}
+
+const empty = status => new Response(null, { status, headers: { 'cache-control': 'private, no-store' } });
+function checkedPath(path, origin) {
+  if (typeof path !== 'string' || path.length > 2048 || !path.startsWith('/') || path.startsWith('//')
+    || /[\\\s#]/.test(path)) throw new Error('Invalid page path');
+  const url = new URL(path, origin);
+  if (url.origin !== origin || url.pathname + url.search !== path
+    || url.pathname === accessBase || url.pathname.startsWith(`${accessBase}/`)) throw new Error('Invalid page path');
+  return url;
+}
+
+/** Same-origin UI checks. These never authorize a separate data handler. */
+export function createStopneticAccessHandler(options = optionsFromEnv()) {
+  const origin = new URL(options.origin).origin;
+  const verifyPath = `${accessBase}/verify`;
+  const protect = createStopneticHandler({ ...options, verifyPath });
+  return async function access(request) {
+    const url = new URL(request.url);
+    if (url.origin !== origin || (request.headers.has('host') && request.headers.get('host').toLowerCase() !== url.host)) return empty(404);
+    if (url.pathname === verifyPath) return protect(request, () => empty(404));
+    if (url.pathname !== `${accessBase}/access`) return empty(404);
+    if (request.method !== 'GET') return new Response(null, { status: 405, headers: { allow: 'GET', 'cache-control': 'private, no-store' } });
+    let target;
+    try { target = checkedPath(url.searchParams.get('path'), origin); } catch { return empty(400); }
+    if (url.searchParams.getAll('path').length !== 1 || url.searchParams.getAll('mode').length > 1
+      || [...url.searchParams.keys()].some(key => !['path', 'mode'].includes(key))
+      || (url.searchParams.has('mode') && url.searchParams.get('mode') !== 'check')) return empty(400);
+    // Navigation checks use the real page path and cookie, not the control URL.
+    const headers = new Headers(request.headers);
+    headers.set('accept', 'text/html');
+    const check = url.searchParams.get('mode') === 'check';
+    const response = await protect(new Request(target, { headers }), () => check
+      ? Response.json({ allowed: true })
+      : new Response(null, { status: 303, headers: { location: target.pathname + target.search } }));
+    if (!check || response.ok) return response;
+    const challenge = response.status === 404 && response.headers.get('content-type')?.startsWith('text/html');
+    const resultHeaders = new Headers({ 'cache-control': 'private, no-store' });
+    for (const cookie of response.headers.getSetCookie()) resultHeaders.append('set-cookie', cookie);
+    await response.body?.cancel();
+    return Response.json({ allowed: false, reason: challenge ? 'verification_required' : response.status === 404 ? 'blocked' : 'unavailable' },
+      { status: response.status, headers: resultHeaders });
+  };
+}
+
+/** Wrap EACH protected Fetch-style API; the UI's allowed flag is never trusted. */
+export function withStopnetic(handler, options = optionsFromEnv()) {
+  const protect = createStopneticHandler(options);
+  return (request, ...context) => {
+    // Netlify's default function alias must not bypass a custom API path's rule.
+    // Declare a custom config.path for these functions and use it in Policies.
+    if (new URL(request.url).pathname.startsWith('/.netlify/functions/')) return Promise.resolve(empty(404));
+    return protect(request, checked => handler(checked, ...context));
+  };
+}
+
+/** Node/Express: mount first, then the root guard, then parsers/static/API handlers. */
+export function createStopneticAccessMiddleware(options = optionsFromEnv()) {
+  const access = createStopneticAccessHandler(options);
+  const verification = createStopneticMiddleware({ ...options, verifyPath: `${accessBase}/verify` });
+  return async (req, res, next) => {
+    const path = (req.originalUrl || req.url || '').split('?')[0];
+    if (path !== `${accessBase}/access` && path !== `${accessBase}/verify`) return next();
+    if (path === `${accessBase}/verify`) return verification(req, res, next);
+    try {
+      const headers = new Headers();
+      for (const [name, value] of Object.entries(req.headers)) {
+        if (Array.isArray(value)) { res.writeHead(400, { 'cache-control': 'no-store' }); res.end(); return; }
+        if (value !== undefined) headers.set(name, value);
+      }
+      const request = new Request(new URL(req.originalUrl || req.url, options.origin), {
+        method: req.method, headers,
+        ...(['GET', 'HEAD'].includes(req.method) ? {} : { body: req, duplex: 'half' }),
+      });
+      const response = await access(request);
+      res.statusCode = response.status;
+      response.headers.forEach((value, name) => { if (name !== 'set-cookie') res.setHeader(name, value); });
+      const cookies = response.headers.getSetCookie();
+      if (cookies.length) res.setHeader('set-cookie', cookies);
+      res.end(Buffer.from(await response.arrayBuffer()));
+    } catch { res.writeHead(503, { 'cache-control': 'private, no-store' }); res.end(); }
+  };
+}
+
+export function createStopneticServer(options = optionsFromEnv()) {
+  return {
+    access: createStopneticAccessMiddleware(options),
+    guard: createStopneticMiddleware({ ...options, verifyPath: `${accessBase}/verify` }),
+  };
+}