@stopnetic/js 0.0.1-pilot → 0.0.2-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/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>;
+};

package/dist/guard.js

@@ -1,203 +1,216 @@
-import { createHash, createHmac, randomBytes, timingSafeEqual, verify as verifySignature } from 'node:crypto';
-import { trustedSigningKeys } from './signing-keys.js';
-export { parseAdditionalDecisionPublicKeys } from './signing-keys.js';
-
-const unavailable = retryAfter => new Response(null, { status: 503, headers: {
-  'cache-control': 'no-store', ...(retryAfter ? { 'retry-after': String(retryAfter) } : {}),
-} });
-const concealed = () => new Response(null, { status: 404, headers: { 'cache-control': 'no-store' } });
-const hash = value => createHash('sha256').update(value).digest('hex');
-
-function signed(payload, secret) {
-  const data = Buffer.from(JSON.stringify(payload)).toString('base64url');
-  const mac = createHmac('sha256', secret).update(data).digest('base64url');
-  return `${data}.${mac}`;
-}
-
-function verified(token, secret) {
-  if (!token || typeof token !== 'string' || token.length > 8192) return null;
-  const [data, mac, extra] = token.split('.');
-  if (!data || !mac || extra) return null;
-  const expected = createHmac('sha256', secret).update(data).digest();
-  let supplied;
-  try { supplied = Buffer.from(mac, 'base64url'); } catch { return null; }
-  if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) return null;
-  try {
-    const payload = JSON.parse(Buffer.from(data, 'base64url').toString('utf8'));
-    return payload?.v === 1 && Number.isSafeInteger(payload.exp) && payload.exp > Date.now() ? payload : null;
-  } catch { return null; }
-}
-
-function cookieValue(request, name) {
-  const found = (request.headers.get('cookie') || '').split(';').map(part => part.trim())
-    .find(part => part.startsWith(`${name}=`));
-  return found ? found.slice(name.length + 1) : null;
-}
-
-async function limitedBody(request, maxBytes) {
-  const reader = request.body?.getReader();
-  if (!reader) throw new Error('Missing body');
-  const chunks = [];
-  let length = 0;
-  for (;;) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    length += value.byteLength;
-    if (length > maxBytes) { await reader.cancel(); throw new Error('Body too large'); }
-    chunks.push(Buffer.from(value));
-  }
-  return Buffer.concat(chunks, length).toString('utf8');
-}
-
-function bootstrap(ticket, verifyPath) {
-  const nonce = randomBytes(16).toString('base64');
-  const script = `fetch(${JSON.stringify(verifyPath)}, {method:'POST', credentials:'same-origin', headers:{'content-type':'application/json'}, body:JSON.stringify({ticket:${JSON.stringify(ticket)}})}).then(r=>{if(r.ok)location.reload()})`;
-  const html = `<!doctype html><html><head><meta charset="utf-8"><title>Checking access</title></head><body><p>Checking access...</p><script nonce="${nonce}">${script}</script></body></html>`;
-  return new Response(html, { status: 404, headers: {
-    'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'vary': 'Cookie',
-    'content-security-policy': `default-src 'none'; script-src 'nonce-${nonce}'; connect-src 'self'; base-uri 'none'; form-action 'none'`,
-    'x-content-type-options': 'nosniff',
-  } });
-}
-
-/** Pilot guard for server-side Next.js Proxy and Route Handlers. */
-export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, additionalDecisionPublicKeys = [], cookieSecret, verifyPath = '/__stopnetic/verify',
-  cookieName = 'stopnetic_pilot_session', secureCookie = true, fetchImpl = fetch, timeoutMs = 2000, publicPaths = [], reportEvents = true }) {
-  if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(siteId || '')) throw new Error('Invalid siteId');
-  const credential = typeof apiToken === 'string' ? apiToken.match(/^[a-z]{1,32}_([a-f0-9]{32})\.[A-Za-z0-9_-]{43}$/) : null;
-  if (!credential) throw new Error('apiToken must be an issued installation key');
-  const installationId = credential[1];
-  if (typeof cookieSecret !== 'string' || cookieSecret.length < 32) throw new Error('cookieSecret must be at least 32 characters');
-  const endpoint = new URL(apiUrl);
-  if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) throw new Error('Invalid apiUrl');
-  if (endpoint.protocol !== 'https:' && !(endpoint.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(endpoint.hostname))) {
-    throw new Error('apiUrl must use HTTPS outside localhost');
-  }
-  if (!/^\/[a-zA-Z0-9/_-]+$/.test(verifyPath)) throw new Error('Invalid verifyPath');
-  if (!/^[a-zA-Z0-9_-]+$/.test(cookieName)) throw new Error('Invalid cookieName');
-  if (!Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 10000) throw new Error('Invalid timeoutMs');
-  if (typeof reportEvents !== 'boolean') throw new Error('Invalid reportEvents');
-  if (!Array.isArray(publicPaths) || publicPaths.some(path => typeof path !== 'string' || !/^\/[a-zA-Z0-9_\-/.]*(?:\*)?$/.test(path))) throw new Error('Invalid publicPaths');
-  const publicKeys = trustedSigningKeys(decisionPublicKey, additionalDecisionPublicKeys);
-  const verifyEndpoint = new URL('./verify', endpoint);
-  const eventsEndpoint = new URL('./events', endpoint);
-  const browserCookieName = `${cookieName}_browser`;
-  const installation = hash(apiToken);
-
-  function browserBinding(request) {
-    const payload = verified(cookieValue(request, browserCookieName), cookieSecret);
-    return payload?.kind === 'browser' && payload.site === siteId && payload.installation === installation
-      && /^[A-Za-z0-9_-]{43}$/.test(payload.binding || '') ? payload.binding : null;
-  }
-
-  function cookie(name, value, age) {
-    return `${name}=${value}; Max-Age=${age}; Path=/; HttpOnly; SameSite=Lax${secureCookie ? '; Secure' : ''}`;
-  }
-
-  async function remote(purpose, input) {
-    const context = { site_id: siteId, path: input.path, method: input.method, request_id: randomBytes(16).toString('base64url') };
-    const response = await fetchImpl(purpose === 'decision' ? endpoint : verifyEndpoint, {
-      method: 'POST', signal: AbortSignal.timeout(timeoutMs), redirect: 'error',
-      headers: { authorization: `Bearer ${apiToken}`, 'content-type': 'application/json' },
-      body: JSON.stringify({ ...input, ...context }), cache: 'no-store',
-    });
-    if (!response.ok) {
-      const retry = response.headers.get('retry-after') || '';
-      const retryAfter = response.status === 429 && /^[1-9][0-9]?$/.test(retry) && Number(retry) <= 60 ? Number(retry) : undefined;
-      await response.body?.cancel();
-      throw Object.assign(new Error('Policy service unavailable'), { retryAfter });
-    }
-    const envelope = JSON.parse(await limitedBody(response, 16_384));
-    if (typeof envelope?.decision !== 'string' || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{86}$/.test(envelope.decision)) throw new Error('Invalid signature envelope');
-    const [data, signature] = envelope.decision.split('.');
-    if (!publicKeys.some(key => verifySignature(null, Buffer.from(data), key, Buffer.from(signature, 'base64url')))) throw new Error('Invalid signature');
-    const payload = JSON.parse(Buffer.from(data, 'base64url').toString('utf8'));
-    const now = Date.now();
-    if (payload?.v !== 1 || payload.purpose !== purpose || payload.key_id !== installationId || Object.entries(context).some(([name, value]) => payload[name] !== value)
-      || !Number.isSafeInteger(payload.issued_at) || !Number.isSafeInteger(payload.expires_at)
-      || payload.issued_at > now + 5000 || payload.expires_at <= now || payload.expires_at <= payload.issued_at
-      || payload.expires_at - payload.issued_at > 30_000) throw new Error('Invalid decision context or expiry');
-    return { ...payload, receipt: envelope.decision };
-  }
-
-  async function report(policy, outcome, session = false) {
-    if (!reportEvents) return;
-    try {
-      const response = await fetchImpl(eventsEndpoint, {
-        method: 'POST', signal: AbortSignal.timeout(Math.min(timeoutMs, 500)), redirect: 'error', cache: 'no-store',
-        headers: { authorization: `Bearer ${apiToken}`, 'content-type': 'application/json' },
-        body: JSON.stringify({ receipt: policy.receipt, outcome, session_verified: !!session }),
-      });
-      await response.body?.cancel();
-    } catch { /* Reporting cannot change a validated access decision. */ }
-  }
-
-  function validSession(request) {
-    const value = cookieValue(request, cookieName);
-    const payload = verified(value, cookieSecret);
-    const binding = browserBinding(request);
+import { createHash, createHmac, randomBytes, timingSafeEqual, verify as verifySignature } from 'node:crypto';
+import { trustedSigningKeys } from './signing-keys.js';
+export { parseAdditionalDecisionPublicKeys } from './signing-keys.js';
+
+const unavailable = retryAfter => new Response(null, { status: 503, headers: {
+  'cache-control': 'no-store', ...(retryAfter ? { 'retry-after': String(retryAfter) } : {}),
+} });
+const concealed = () => new Response(null, { status: 404, headers: { 'cache-control': 'no-store' } });
+const hash = value => createHash('sha256').update(value).digest('hex');
+
+function signed(payload, secret) {
+  const data = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const mac = createHmac('sha256', secret).update(data).digest('base64url');
+  return `${data}.${mac}`;
+}
+
+function verified(token, secret) {
+  if (!token || typeof token !== 'string' || token.length > 8192) return null;
+  const [data, mac, extra] = token.split('.');
+  if (!data || !mac || extra) return null;
+  const expected = createHmac('sha256', secret).update(data).digest();
+  let supplied;
+  try { supplied = Buffer.from(mac, 'base64url'); } catch { return null; }
+  if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(data, 'base64url').toString('utf8'));
+    return payload?.v === 1 && Number.isSafeInteger(payload.exp) && payload.exp > Date.now() ? payload : null;
+  } catch { return null; }
+}
+
+function cookieValue(request, name) {
+  const found = (request.headers.get('cookie') || '').split(';').map(part => part.trim())
+    .find(part => part.startsWith(`${name}=`));
+  return found ? found.slice(name.length + 1) : null;
+}
+
+async function limitedBody(request, maxBytes) {
+  const reader = request.body?.getReader();
+  if (!reader) throw new Error('Missing body');
+  const chunks = [];
+  let length = 0;
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    length += value.byteLength;
+    if (length > maxBytes) { await reader.cancel(); throw new Error('Body too large'); }
+    chunks.push(Buffer.from(value));
+  }
+  return Buffer.concat(chunks, length).toString('utf8');
+}
+
+function bootstrap(ticket, verifyPath) {
+  const nonce = randomBytes(16).toString('base64');
+  const script = `fetch(${JSON.stringify(verifyPath)}, {method:'POST', credentials:'same-origin', headers:{'content-type':'application/json'}, body:JSON.stringify({ticket:${JSON.stringify(ticket)}})}).then(r=>{if(r.ok)location.reload()})`;
+  const html = `<!doctype html><html><head><meta charset="utf-8"><title>Checking access</title></head><body><p>Checking access...</p><script nonce="${nonce}">${script}</script></body></html>`;
+  return new Response(html, { status: 404, headers: {
+    'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'vary': 'Cookie',
+    'content-security-policy': `default-src 'none'; script-src 'nonce-${nonce}'; connect-src 'self'; base-uri 'none'; form-action 'none'`,
+    'x-content-type-options': 'nosniff',
+  } });
+}
+
+/** Pilot guard for server-side Next.js Proxy and Route Handlers. */
+export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, additionalDecisionPublicKeys = [], cookieSecret, verifyPath = '/__stopnetic/verify',
+  cookieName = 'stopnetic_pilot_session', secureCookie = true, fetchImpl = fetch, timeoutMs = 2000, publicPaths = [], reportEvents = true, guardMode = 'selected' }) {
+  if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(siteId || '')) throw new Error('Invalid siteId');
+  const credential = typeof apiToken === 'string' ? apiToken.match(/^[a-z]{1,32}_([a-f0-9]{32})\.[A-Za-z0-9_-]{43}$/) : null;
+  if (!credential) throw new Error('apiToken must be an issued installation key');
+  const installationId = credential[1];
+  if (typeof cookieSecret !== 'string' || cookieSecret.trim().length < 32
+    || /^<[^]*>$/.test(cookieSecret.trim())) throw new Error('cookieSecret must be at least 32 characters');
+  if (cookieSecret === apiToken) throw new Error('cookieSecret must be independent of apiToken');
+  const endpoint = new URL(apiUrl);
+  if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) throw new Error('Invalid apiUrl');
+  if (endpoint.protocol !== 'https:' && !(endpoint.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(endpoint.hostname))) {
+    throw new Error('apiUrl must use HTTPS outside localhost');
+  }
+  if (!/^\/[a-zA-Z0-9/_-]+$/.test(verifyPath)) throw new Error('Invalid verifyPath');
+  if (!/^[a-zA-Z0-9_-]+$/.test(cookieName)) throw new Error('Invalid cookieName');
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 10000) throw new Error('Invalid timeoutMs');
+  if (typeof reportEvents !== 'boolean') throw new Error('Invalid reportEvents');
+  if (!Array.isArray(publicPaths) || publicPaths.some(path => typeof path !== 'string' || !/^\/[a-zA-Z0-9_\-/.]*(?:\*)?$/.test(path))) throw new Error('Invalid publicPaths');
+  if (!['selected', 'site'].includes(guardMode)) throw new Error('Invalid guardMode');
+  const publicKeys = trustedSigningKeys(decisionPublicKey, additionalDecisionPublicKeys);
+  const verifyEndpoint = new URL('./verify', endpoint);
+  const eventsEndpoint = new URL('./events', endpoint);
+  const browserCookieName = `${cookieName}_browser`;
+  const installation = hash(apiToken);
+
+  function browserBinding(request) {
+    const payload = verified(cookieValue(request, browserCookieName), cookieSecret);
+    return payload?.kind === 'browser' && payload.site === siteId && payload.installation === installation
+      && /^[A-Za-z0-9_-]{43}$/.test(payload.binding || '') ? payload.binding : null;
+  }
+
+  function cookie(name, value, age) {
+    return `${name}=${value}; Max-Age=${age}; Path=/; HttpOnly; SameSite=Lax${secureCookie ? '; Secure' : ''}`;
+  }
+
+  async function remote(purpose, input) {
+    const context = { site_id: siteId, path: input.path, method: input.method, request_id: randomBytes(16).toString('base64url') };
+    const response = await fetchImpl(purpose === 'decision' ? endpoint : verifyEndpoint, {
+      method: 'POST', signal: AbortSignal.timeout(timeoutMs), redirect: 'error',
+      headers: { authorization: `Bearer ${apiToken}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ ...input, ...context }), cache: 'no-store',
+    });
+    if (!response.ok) {
+      const retry = response.headers.get('retry-after') || '';
+      const retryAfter = response.status === 429 && /^[1-9][0-9]?$/.test(retry) && Number(retry) <= 60 ? Number(retry) : undefined;
+      await response.body?.cancel();
+      throw Object.assign(new Error('Policy service unavailable'), { retryAfter });
+    }
+    const envelope = JSON.parse(await limitedBody(response, 16_384));
+    if (typeof envelope?.decision !== 'string' || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{86}$/.test(envelope.decision)) throw new Error('Invalid signature envelope');
+    const [data, signature] = envelope.decision.split('.');
+    if (!publicKeys.some(key => verifySignature(null, Buffer.from(data), key, Buffer.from(signature, 'base64url')))) throw new Error('Invalid signature');
+    const payload = JSON.parse(Buffer.from(data, 'base64url').toString('utf8'));
+    const now = Date.now();
+    if (payload?.v !== 1 || payload.purpose !== purpose || payload.key_id !== installationId || Object.entries(context).some(([name, value]) => payload[name] !== value)
+      || !Number.isSafeInteger(payload.issued_at) || !Number.isSafeInteger(payload.expires_at)
+      || payload.issued_at > now + 5000 || payload.expires_at <= now || payload.expires_at <= payload.issued_at
+      || payload.expires_at - payload.issued_at > 30_000) throw new Error('Invalid decision context or expiry');
+    return { ...payload, receipt: envelope.decision };
+  }
+
+  async function report(policy, outcome, session = false) {
+    if (!reportEvents) return;
+    try {
+      const response = await fetchImpl(eventsEndpoint, {
+        method: 'POST', signal: AbortSignal.timeout(Math.min(timeoutMs, 500)), redirect: 'error', cache: 'no-store',
+        headers: { authorization: `Bearer ${apiToken}`, 'content-type': 'application/json' },
+        body: JSON.stringify({ receipt: policy.receipt, outcome, session_verified: !!session }),
+      });
+      await response.body?.cancel();
+    } catch { /* Reporting cannot change a validated access decision. */ }
+  }
+
+  function validSession(request) {
+    const value = cookieValue(request, cookieName);
+    const payload = verified(value, cookieSecret);
+    const binding = browserBinding(request);
     return payload?.kind === 'session' && payload.site === siteId && payload.installation === installation
-      && binding && payload.browser_hash === hash(binding);
-  }
-
-  async function check(request) {
-    const path = new URL(request.url).pathname;
-    if (path === verifyPath) return null;
-    if (publicPaths.some(rule => rule.endsWith('*') ? path.startsWith(rule.slice(0, -1)) : path === rule)) return null;
+      && binding && payload.browser_hash === hash(binding) ? payload : null;
+  }
+
+  async function check(request) {
+    const path = new URL(request.url).pathname;
+    if (path === verifyPath) return null;
+    if (publicPaths.some(rule => rule.endsWith('*') ? path.startsWith(rule.slice(0, -1)) : path === rule)) return null;
     const session = validSession(request);
-    const eligible = request.method === 'GET' && (request.headers.get('accept') || '').includes('text/html');
-    const binding = !session && eligible ? browserBinding(request) || randomBytes(32).toString('base64url') : null;
-    let policy;
-    try {
-      policy = await remote('decision', { path, method: request.method, ...(binding ? { browser_binding: binding } : {}) });
-    } catch (error) { return unavailable(error?.retryAfter); }
-    if (!policy || !['public', 'block', 'human', 'verified', 'entitled', 'default'].includes(policy.action)) return unavailable();
-    if (policy.action === 'public') { await report(policy, 'ALLOW', session); return null; }
-    if (policy.action === 'block' || policy.action === 'entitled' || policy.action === 'default') { await report(policy, 'BLOCK', session); return concealed(); }
-    if (session) { await report(policy, 'ALLOW', true); return null; }
-    if (policy.action === 'verified' || !eligible) { await report(policy, 'BLOCK'); return concealed(); }
-    if (!/^[A-Za-z0-9_-]{43}$/.test(policy.challenge_id || '')) return unavailable();
-    const ticket = signed({ v: 1, kind: 'challenge', site: siteId, path, exp: Date.now() + 60_000,
-      challenge_id: policy.challenge_id, browser_hash: hash(binding), installation }, cookieSecret);
-    const response = bootstrap(ticket, verifyPath);
-    response.headers.set('set-cookie', cookie(browserCookieName, signed({ v: 1, kind: 'browser', site: siteId,
-      binding, installation, exp: Date.now() + 600_000 }, cookieSecret), 600));
-    await report(policy, 'CHALLENGE');
-    return response;
-  }
-
-  async function verify(request) {
-    if (request.method !== 'POST') return new Response(null, { status: 405, headers: { 'cache-control': 'no-store' } });
-    const origin = request.headers.get('origin');
-    if (!origin) return concealed();
-    // Next.js may use an internal hostname in request.url. Host is the browser's
-    // destination; retain the request URL's scheme to reject cross-scheme calls.
-    const destination = new URL(request.url);
-    const host = request.headers.get('host') || destination.host;
-    if (origin !== `${destination.protocol}//${host}`) return concealed();
-    if (!(request.headers.get('content-type') || '').toLowerCase().startsWith('application/json')) return concealed();
-    if ((Number(request.headers.get('content-length')) || 0) > 4096) return concealed();
-    let body;
-    try { body = await limitedBody(request, 4096); } catch { return concealed(); }
-    let ticket;
-    try { ticket = JSON.parse(body).ticket; } catch { return concealed(); }
-    const payload = verified(ticket, cookieSecret);
-    const binding = browserBinding(request);
-    if (payload?.kind !== 'challenge' || payload.site !== siteId || payload.installation !== installation
-      || typeof payload.path !== 'string' || !/^\/[^\s?#]*$/.test(payload.path) || !binding
-      || payload.browser_hash !== hash(binding) || !/^[A-Za-z0-9_-]{43}$/.test(payload.challenge_id || '')) return concealed();
-    try {
-      const result = await remote('verify', { path: payload.path, method: 'POST', challenge_id: payload.challenge_id, browser_binding: binding });
-      if (result.action !== 'verified' || result.challenge_id !== payload.challenge_id) return unavailable();
-      await report(result, 'VERIFIED');
-    } catch (error) { return unavailable(error?.retryAfter); }
+    // Only link access to the page that originally requested this challenge.
+    // Sessions still authorize other configured routes without attributing them
+    // to this page's verification outcome. Legacy sessions remain usable.
+    const challenge = session?.challenge_path === path && /^[A-Za-z0-9_-]{43}$/.test(session.challenge_id || '')
+      ? session.challenge_id : null;
+    const eligible = request.method === 'GET' && (request.headers.get('accept') || '').includes('text/html');
+    const binding = challenge ? browserBinding(request)
+      : !session && eligible ? browserBinding(request) || randomBytes(32).toString('base64url') : null;
+    let policy;
+    try {
+      policy = await remote('decision', { path, method: request.method, ...(guardMode === 'site' ? { guard_mode: 'site' } : {}), ...(binding ? { browser_binding: binding } : {}),
+        ...(challenge ? { session_challenge: challenge } : {}) });
+    } catch (error) { return unavailable(error?.retryAfter); }
+    if (!policy || !['public', 'block', 'human', 'verified', 'entitled', 'default'].includes(policy.action)) return unavailable();
+    // An older service must not silently apply selected-path semantics here.
+    if (guardMode === 'site' && policy.guard_mode !== 'site') return unavailable();
+    if (policy.action === 'public') { await report(policy, 'ALLOW', session); return null; }
+    if (policy.action === 'block' || policy.action === 'entitled' || policy.action === 'default') { await report(policy, 'BLOCK', session); return concealed(); }
+    if (session) { await report(policy, 'ALLOW', true); return null; }
+    if (policy.action === 'verified' || !eligible) { await report(policy, 'BLOCK'); return concealed(); }
+    if (!/^[A-Za-z0-9_-]{43}$/.test(policy.challenge_id || '')) return unavailable();
+    const ticket = signed({ v: 1, kind: 'challenge', site: siteId, path, exp: Date.now() + 60_000,
+      challenge_id: policy.challenge_id, browser_hash: hash(binding), installation }, cookieSecret);
+    const response = bootstrap(ticket, verifyPath);
+    response.headers.set('set-cookie', cookie(browserCookieName, signed({ v: 1, kind: 'browser', site: siteId,
+      binding, installation, exp: Date.now() + 600_000 }, cookieSecret), 600));
+    await report(policy, 'CHALLENGE');
+    return response;
+  }
+
+  async function verify(request) {
+    if (request.method !== 'POST') return new Response(null, { status: 405, headers: { 'cache-control': 'no-store' } });
+    const origin = request.headers.get('origin');
+    if (!origin) return concealed();
+    // Next.js may use an internal hostname in request.url. Host is the browser's
+    // destination; retain the request URL's scheme to reject cross-scheme calls.
+    const destination = new URL(request.url);
+    const host = request.headers.get('host') || destination.host;
+    if (origin !== `${destination.protocol}//${host}`) return concealed();
+    if (!(request.headers.get('content-type') || '').toLowerCase().startsWith('application/json')) return concealed();
+    if ((Number(request.headers.get('content-length')) || 0) > 4096) return concealed();
+    let body;
+    try { body = await limitedBody(request, 4096); } catch { return concealed(); }
+    let ticket;
+    try { ticket = JSON.parse(body).ticket; } catch { return concealed(); }
+    const payload = verified(ticket, cookieSecret);
+    const binding = browserBinding(request);
+    if (payload?.kind !== 'challenge' || payload.site !== siteId || payload.installation !== installation
+      || typeof payload.path !== 'string' || !/^\/[^\s?#]*$/.test(payload.path) || !binding
+      || payload.browser_hash !== hash(binding) || !/^[A-Za-z0-9_-]{43}$/.test(payload.challenge_id || '')) return concealed();
+    try {
+      const result = await remote('verify', { path: payload.path, method: 'POST', challenge_id: payload.challenge_id, browser_binding: binding });
+      if (result.action !== 'verified' || result.challenge_id !== payload.challenge_id) return unavailable();
+      await report(result, 'VERIFIED');
+    } catch (error) { return unavailable(error?.retryAfter); }
     const session = signed({ v: 1, kind: 'session', site: siteId, installation,
-      browser_hash: hash(binding), exp: Date.now() + 300_000 }, cookieSecret);
-    return new Response(null, { status: 204, headers: {
-      'cache-control': 'no-store',
-      'set-cookie': cookie(cookieName, session, 300),
-    } });
-  }
-
-  return { check, verify };
-}
+      browser_hash: hash(binding), challenge_id: payload.challenge_id, challenge_path: payload.path,
+      exp: Date.now() + 300_000 }, cookieSecret);
+    return new Response(null, { status: 204, headers: {
+      'cache-control': 'no-store',
+      'set-cookie': cookie(cookieName, session, 300),
+    } });
+  }
+
+  return { check, verify };
+}

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { StopneticOptions } from './guard.js';
-export { createStopnetic, parseAdditionalDecisionPublicKeys } from './guard.js';
-export type { StopneticOptions } from './guard.js';
-export type StopneticServerOptions = StopneticOptions & {
-  /** Public website origin, e.g. https://example.com. Never taken from forwarded headers. */
-  origin: string;
-};
-export function createStopneticMiddleware(options: StopneticServerOptions): (
-  request: IncomingMessage & { originalUrl?: string }, response: ServerResponse,
-  next: () => unknown,
-) => Promise<unknown>;
-export function createStopneticHandler(options: StopneticServerOptions): (
-  request: Request, next: (request: Request) => Response | Promise<Response>,
-) => Promise<Response>;
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { StopneticOptions } from './guard.js';
+export { createStopnetic, parseAdditionalDecisionPublicKeys } from './guard.js';
+export type { StopneticOptions } from './guard.js';
+export type StopneticServerOptions = StopneticOptions & {
+  /** Public website origin, e.g. https://example.com. Never taken from forwarded headers. */
+  origin: string;
+};
+export function createStopneticMiddleware(options: StopneticServerOptions): (
+  request: IncomingMessage & { originalUrl?: string }, response: ServerResponse,
+  next: () => unknown,
+) => Promise<unknown>;
+export function createStopneticHandler(options: StopneticServerOptions): (
+  request: Request, next: (request: Request) => Response | Promise<Response>,
+) => Promise<Response>;