@stopnetic/js 0.0.1-pilot → 0.0.2-pilot

package/dist/setup.js

@@ -0,0 +1,165 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, lstatSync, realpathSync } from 'node:fs';
+import { resolve, relative, dirname, isAbsolute } from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+import { parseEnv } from 'node:util';
+import { createStopneticAccessHandler, optionsFromEnv } from './server.js';
+
+export class SetupError extends Error {}
+const digest = value => createHash('sha256').update(value).digest('hex');
+const manifestName = 'stopnetic.setup.json';
+function destination(root, name) {
+  const file = resolve(root, name);
+  const inside = relative(root, file);
+  if (!inside || inside.startsWith('..') || isAbsolute(inside) || /[\x00-\x1f]/.test(name)) throw new SetupError('Setup paths must stay inside the project.');
+  for (let cursor = file; cursor !== root; cursor = dirname(cursor)) {
+    if (lstatSync(cursor, { throwIfNoEntry: false })?.isSymbolicLink()) throw new SetupError('Setup refuses symbolic links.');
+  }
+  return file;
+}
+function text(file) { return existsSync(file) ? readFileSync(file, 'utf8') : ''; }
+function environment(root) {
+  try {
+    return { ...parseEnv(text(destination(root, '.env'))), ...parseEnv(text(destination(root, '.env.local'))), ...process.env };
+  } catch { throw new SetupError('Check server environment file formatting.'); }
+}
+function project(root) {
+  try { return JSON.parse(readFileSync(destination(root, 'package.json'), 'utf8')); }
+  catch { throw new SetupError('Run setup from a project with a valid package.json.'); }
+}
+function platformFor(root, supplied) {
+  if (supplied && !['netlify', 'vercel', 'node'].includes(supplied)) throw new SetupError('Choose netlify, vercel or node.');
+  if (supplied) return supplied;
+  const netlify = existsSync(destination(root, 'netlify.toml'));
+  const vercel = existsSync(destination(root, 'vercel.json'));
+  if (netlify && !vercel) return 'netlify';
+  if (vercel && !netlify) return 'vercel';
+  throw new SetupError('Choose your hosting explicitly: --platform netlify, vercel or node.');
+}
+const clientGuide = `# Stopnetic client/server setup
+
+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,
+    '.env.stopnetic.example': `# SERVER settings; copy actual values from Stopnetic Integration.\nSTOPNETIC_WEBSITE_ORIGIN=https://www.example.com\nSTOPNETIC_SITE_ID=\nSTOPNETIC_API_URL=https://your-stopnetic-service/api/integration/decision\nSTOPNETIC_API_TOKEN=\nSTOPNETIC_DECISION_PUBLIC_KEY=\nSTOPNETIC_COOKIE_SECRET=\n`,
+  };
+  if (platform === 'netlify') {
+    const toml = text(destination(root, 'netlify.toml'));
+    const build = toml.match(/\[build\]([^]*?)(?=\n\[|$)/)?.[1] || '';
+    if (/^\s*base\s*=/m.test(build)) throw new SetupError('Run from the Netlify base directory and review custom base configuration before using setup.');
+    const section = toml.match(/\[functions\]([^]*?)(?=\n\[|$)/)?.[1] || '';
+    const match = section.match(/^\s*directory\s*=\s*["']([^"']+)["']\s*(?:#.*)?$/m);
+    if (/^\s*directory\s*=/m.test(section) && !match) throw new SetupError('Review your custom Netlify functions directory.');
+    const directory = match?.[1] || 'netlify/functions';
+    destination(root, directory);
+    files[`${directory}/stopnetic.mjs`] = `import { createStopneticAccessHandler } from '@stopnetic/js/server';\nlet access;\nexport default request => (access ??= createStopneticAccessHandler())(request);\nexport const config = { path: ['/api/stopnetic/access', '/api/stopnetic/verify'], preferStatic: false };\n`;
+  } else if (platform === 'vercel') {
+    files['api/stopnetic/[operation].mjs'] = `import { createStopneticAccessHandler } from '@stopnetic/js/server';\nlet access;\nexport default { fetch: request => (access ??= createStopneticAccessHandler())(request) };\n`;
+  } else {
+    files['stopnetic.server.mjs'] = `import { createStopneticServer } from '@stopnetic/js/server';\nexport function installStopnetic(app) {\n  const { access, guard } = createStopneticServer();\n  app.use(access);\n  app.use(guard);\n}\n`;
+  }
+  return files;
+}
+
+export function setup(input, { platform: supplied, dryRun = false } = {}) {
+  const root = realpathSync(resolve(input));
+  const pkg = project(root);
+  if (pkg.dependencies?.next || pkg.devDependencies?.next) throw new SetupError('Use @stopnetic/next for a Next.js project.');
+  const platform = platformFor(root, supplied);
+  const files = filesFor(root, platform);
+  const manifestPath = destination(root, manifestName);
+  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.
+  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}`);
+  }
+  const local = destination(root, '.env.local');
+  const ignore = destination(root, '.gitignore');
+  const env = environment(root);
+  if (dryRun) return `Dry run: ${platform}; would prepare ${Object.keys(files).join(', ')} and private cookie configuration. No files changed.`;
+  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 (!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`);
+  writeFileSync(manifestPath, JSON.stringify({ v: 1, platform, files: Object.fromEntries(Object.entries(files).map(([name, content]) => [name, digest(content)])) }, null, 2) + '\n');
+  return `Prepared ${platform} setup. Follow stopnetic-client-guide.md, configure server env, wrap protected APIs, build and deploy. Then run stopnetic-js check. No service requests or trial activation occurred.`;
+}
+
+export function checkSetup(input, { localHttp = false } = {}) {
+  const root = realpathSync(resolve(input));
+  let manifest;
+  try { manifest = JSON.parse(text(destination(root, manifestName))); } catch { throw new SetupError('Run stopnetic-js init first.'); }
+  if (manifest.v !== 1 || !['netlify', 'vercel', 'node'].includes(manifest.platform)) throw new SetupError('Invalid setup manifest.');
+  const expected = filesFor(root, manifest.platform);
+  for (const [name, content] of Object.entries(expected)) {
+    if (manifest.files?.[name] !== digest(content) || text(destination(root, name)) !== content) throw new SetupError(`Generated file changed or missing: ${name}`);
+  }
+  try {
+    const options = optionsFromEnv(environment(root));
+    if (!localHttp && !options.origin?.startsWith('https:')) throw new Error();
+    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.`;
+}

package/dist/signing-keys.js

@@ -1,29 +1,40 @@
-import { createPublicKey } from 'node:crypto';
-
+import { createPublicKey } from 'node:crypto';
+
 function publicKey(value) {
-  if (typeof value !== 'string' || value.length > 2048
-    || !/^-----BEGIN PUBLIC KEY-----\r?\n[A-Za-z0-9+/=\r\n]+-----END PUBLIC KEY-----\s*$/.test(value)) {
+  if (typeof value !== 'string' || value.length > 2048) {
     throw new Error('Signing verification keys must be public PEMs');
   }
-  const key = createPublicKey(value);
-  if (key.asymmetricKeyType !== 'ed25519') throw new Error('Signing verification keys must be Ed25519');
-  return key;
-}
-
-export function trustedSigningKeys(primary, additional) {
-  if (!Array.isArray(additional) || additional.length > 2) throw new Error('Use at most two additional signing public keys');
-  const keys = [primary, ...additional].map(publicKey);
-  return [...new Map(keys.map(key => [key.export({ type: 'spki', format: 'der' }).toString('hex'), key])).values()];
-}
-
-/** Parse a server environment JSON array without exposing malformed values. */
-export function parseAdditionalDecisionPublicKeys(value) {
-  if (value === undefined || value === '') return [];
-  try {
-    if (typeof value !== 'string' || value.length > 8192) throw new Error();
-    const keys = JSON.parse(value);
-    if (!Array.isArray(keys) || keys.length > 2) throw new Error();
-    keys.forEach(publicKey);
-    return keys;
-  } catch { throw new Error('Invalid additional signing public keys'); }
-}
+  // Hosting value fields may receive the quoted/escaped dotenv representation.
+  // Normalize only formatting; retain bounded, public-only Ed25519 trust checks.
+  let pem = value.trim();
+  try { if (pem.startsWith('"')) pem = JSON.parse(pem); }
+  catch { throw new Error('Signing verification keys must be public PEMs'); }
+  if (typeof pem !== 'string') throw new Error('Signing verification keys must be public PEMs');
+  pem = pem.replaceAll('\\r\\n', '\n').replaceAll('\\n', '\n');
+  if (!/^-----BEGIN PUBLIC KEY-----\r?\n[A-Za-z0-9+/=\r\n]+-----END PUBLIC KEY-----\s*$/.test(pem)) {
+    throw new Error('Signing verification keys must be public PEMs');
+  }
+  let key;
+  try { key = createPublicKey(pem); }
+  catch { throw new Error('Signing verification keys must be public PEMs'); }
+  if (key.asymmetricKeyType !== 'ed25519') throw new Error('Signing verification keys must be Ed25519');
+  return key;
+}
+
+export function trustedSigningKeys(primary, additional) {
+  if (!Array.isArray(additional) || additional.length > 2) throw new Error('Use at most two additional signing public keys');
+  const keys = [primary, ...additional].map(publicKey);
+  return [...new Map(keys.map(key => [key.export({ type: 'spki', format: 'der' }).toString('hex'), key])).values()];
+}
+
+/** Parse a server environment JSON array without exposing malformed values. */
+export function parseAdditionalDecisionPublicKeys(value) {
+  if (value === undefined || value === '') return [];
+  try {
+    if (typeof value !== 'string' || value.length > 8192) throw new Error();
+    const keys = JSON.parse(value);
+    if (!Array.isArray(keys) || keys.length > 2) throw new Error();
+    keys.forEach(publicKey);
+    return keys;
+  } catch { throw new Error('Invalid additional signing public keys'); }
+}

package/package.json

@@ -1,47 +1,54 @@
-{
-  "name": "@stopnetic/js",
-  "version": "0.0.1-pilot",
-  "description": "Server-side Stopnetic guard for JavaScript websites, Node.js and Express-compatible servers.",
-  "type": "module",
-  "license": "MIT",
-  "author": "Stopnetic",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/KlimentSidorov/stopin.git",
-    "directory": "integrations/javascript"
-  },
-  "keywords": [
-    "stopnetic",
-    "javascript",
-    "nodejs",
-    "express",
-    "access-control"
-  ],
-  "files": [
-    "dist"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
-  },
-  "engines": {
-    "node": ">=22"
-  },
-  "publishConfig": {
-    "access": "public",
-    "tag": "pilot",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "prepack": "npm run build",
-    "test": "npm run build && node --test tests/*.test.mjs",
-    "test:package": "npm run build && node tests/package-check.mjs"
-  },
-  "devDependencies": {
-    "express": "^4.22.3",
-    "express5": "npm:express@^5.2.1"
-  }
-}
+{
+  "name": "@stopnetic/js",
+  "version": "0.0.2-pilot",
+  "description": "Server-side Stopnetic guard for JavaScript websites, Node.js and Express-compatible servers.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Stopnetic",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KlimentSidorov/stopin.git",
+    "directory": "integrations/javascript"
+  },
+  "keywords": [
+    "stopnetic",
+    "javascript",
+    "nodejs",
+    "express",
+    "access-control"
+  ],
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "bin": { "stopnetic-js": "./bin/stopnetic-js.js" },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": { "types": "./dist/server.d.ts", "default": "./dist/server.js" },
+    "./browser": { "types": "./dist/browser.d.ts", "default": "./dist/browser.js" },
+    "./react": { "types": "./dist/react.d.ts", "default": "./dist/react.js" }
+  },
+  "peerDependencies": { "react": "*" },
+  "peerDependenciesMeta": { "react": { "optional": true } },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "pilot",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "test:package": "npm run build && node tests/package-check.mjs"
+  },
+  "devDependencies": {
+    "express": "^4.22.3",
+    "express5": "npm:express@^5.2.1"
+  }
+}