@gate-forge/witness 0.12.0 → 0.13.0

package/dist/witness/server.js

@@ -155,6 +155,7 @@ import { join, resolve } from 'node:path';
 import { ATTESTATION_VERSION, attestationMac, behaviorActionDigestOf, DEFAULT_QUEUE_POLL_INTERVAL_MS, DEFAULT_QUEUE_TERMINAL_TIMEOUT_MS, BehaviorCatalogSchema, BEHAVIOR_CASE_KIND, enumerationDigestOf, interpretObservedPath, pathMatchesShape, recordIdOf, resolveHttpRoute, } from '@gate-forge/core';
 import { canonicalOf } from '../json.js';
 import { DEFAULT_REQUEST_TIMEOUT_MS, HTTP_OBSERVED_KIND, KNOWN_RECORD_KINDS, LOOPBACK_HOSTNAME, OBSERVED_KIND, OBSERVED_EXCHANGES_CAP, PERSISTENCE_KIND, RUN_HEADER, VERIFIER_HEADER, } from '../constants.js';
+import { PageObserverRegistrationError, registerPageObserver, sweepPageVisits } from './page-observer-registration.js';
 import { loadAdapters, makeAdapterContext } from './adapter-registry.js';
 import { AttestationError, assertLoopback, envFingerprintMismatch, probeEnvFingerprint, } from './env-attestation.js';
 import { hostResolverRules, isLoopbackAddress, pinnedLoopbackIps, pinnedGet } from './loopback-pins.js';
@@ -777,6 +778,21 @@ async function stopSessionProxy(session) {
         server.close(() => resolveClose());
     });
 }
+/** Detaches the independent browser observer when its test session ends. */
+async function stopPageObserver(state, sessionId) {
+    const observer = state.pageObservers.get(sessionId);
+    state.pageObservers.delete(sessionId);
+    await observer?.close();
+}
+/** Only a test session sealed as passing can retain its page observations. */
+function sealPageObservationRecords(state, sessionId, outcome) {
+    const recordIds = state.pageObservationRecords.get(sessionId) ?? [];
+    if (outcome !== 'passed') {
+        for (const recordId of recordIds)
+            state.ledger.delete(recordId);
+    }
+    state.pageObservationRecords.delete(sessionId);
+}
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -950,13 +966,16 @@ export async function startWitness(options) {
         twinShapes: options.twinShapes === undefined || options.twinShapes === null ? null : options.twinShapes,
         expectedTests: new Map(),
         enumerationDigest: null,
+        pageObservation: null,
         behaviorCatalog: null,
         caseExecutions: new Map(),
         tick: 0,
+        pageObservationRecords: new Map(),
         sessions: new Map(),
         workerSessions: new Map(),
         sessionIdentities: new Map(),
         sessionPageOrigins: new Map(),
+        pageObservers: new Map(),
         // The engine browser is OPTIONAL here and required only by the
         // ENGINE-BROWSER proof channel: this package is runner-neutral and
         // must not assume a browser is installed. A witness started without
@@ -1583,6 +1602,37 @@ async function handleRequest(state, req, res) {
             await handleRecords(state, res, (await readBody(req)));
             return;
         }
+        if (req.method === 'POST' && path === '/runs/page-sweep') {
+            requireSupervisor(state, req.headers[VERIFIER_HEADER]);
+            const body = (await readBody(req));
+            if (typeof body.audience !== 'string' || body.audience.length === 0 ||
+                !Array.isArray(body.pages) ||
+                body.pages.some((page) => !isPlainObject(page) ||
+                    typeof page['id'] !== 'string' || page['id'].length === 0 ||
+                    typeof page['path'] !== 'string' || !page['path'].startsWith('/') ||
+                    !(page['anonymous'] === undefined || typeof page['anonymous'] === 'boolean')) ||
+                !Array.isArray(body.loginRoutes) ||
+                body.loginRoutes.some((route) => typeof route !== 'string') ||
+                !Array.isArray(body.errorMarkers) ||
+                body.errorMarkers.some((marker) => typeof marker !== 'string')) {
+                throw new HttpError(400, 'page sweep configuration is invalid');
+            }
+            if (state.engineBrowser === null)
+                throw new HttpError(503, 'page sweep needs the engine browser');
+            const visits = await sweepPageVisits({
+                browser: state.engineBrowser,
+                sessionId: `page-sweep-${state.options.runId}-${body.audience}`,
+                testId: 'page-sweep',
+                appBase: requireTrustedUiBase(state),
+                routes: body.pages,
+                loginRoutes: body.loginRoutes,
+                errorMarkers: body.errorMarkers,
+                storageState: body.storageState,
+                issueRecord: (obligationId, testId, payload) => issueRecord(state, obligationId, 'page.observed', testId, payload, 'engine-observed').recordId,
+            });
+            sendJson(res, 200, { visits });
+            return;
+        }
         if (req.method === 'POST' && path === '/runs/expected-set') {
             await handleExpectedSet(state, res, req.headers[VERIFIER_HEADER], (await readBody(req)));
             return;
@@ -1686,6 +1736,48 @@ async function handleRequest(state, req, res) {
             await handleSessionPageOrigins(state, res, (await readBody(req)));
             return;
         }
+        if (req.method === 'POST' && path === '/sessions/page-observer') {
+            const body = (await readBody(req));
+            try {
+                await registerPageObserver({
+                    state,
+                    response: res,
+                    body,
+                    requireSession: (value) => {
+                        const session = requireOpenSession(state, value);
+                        return {
+                            sessionId: session.sessionId,
+                            testId: session.testId,
+                            activity: session.activity,
+                            // The supervisor-opened identity (0.13 authority cutover):
+                            // static tamper risks match against THIS file, never
+                            // suite-supplied metadata.
+                            registeredFile: session.registered === null ? null : session.registered.file,
+                        };
+                    },
+                    issueRecord: (obligationId, testId, payload) => issueRecord(state, obligationId, 'page.observed', testId, payload, 'engine-observed').recordId,
+                });
+            }
+            catch (error) {
+                if (error instanceof PageObserverRegistrationError)
+                    throw new HttpError(error.status, error.message);
+                throw error;
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/sessions/page-observer/flush') {
+            const body = (await readBody(req));
+            const session = requireOpenSession(state, body);
+            if (body.testId !== session.testId)
+                throw new HttpError(403, 'page observer flush test identity does not match its session');
+            const observer = state.pageObservers.get(session.sessionId);
+            if (observer === undefined)
+                throw new HttpError(409, 'page observer is not registered for this session');
+            await observer.flush();
+            session.activity += 1;
+            sendJson(res, 200, { flushed: true });
+            return;
+        }
         if (req.method === 'POST' && path === '/sessions/intervals/open') {
             await handleIntervalOpen(state, res, (await readBody(req)));
             return;
@@ -1796,7 +1888,9 @@ function sendJson(res, status, body) {
  *   state: running witness state.
  *   res: response to answer.
  *   verifier: the `x-gateforge-verifier` header value.
- *   body: the parsed request body ({tests: [...]}, identity-shaped).
+ *   body: the parsed request body ({tests: [...], pageObservation?},
+ *     identity-shaped; the optional controller-held page-observation
+ *     context binds once alongside the set and is never suite-supplied).
  */
 async function handleExpectedSet(state, res, verifier, body) {
     requireSupervisor(state, verifier);
@@ -1835,9 +1929,90 @@ async function handleExpectedSet(state, res, verifier, body) {
             observationOnly,
         });
     }
+    // Controller-held page-observation context (0.13 authority cutover):
+    // validated HERE, once, supervisor-authenticated, and stored alongside
+    // the expected set. The suite never supplies any of it — the registrar
+    // grades with THIS context or issues no page proof at all.
+    let pageObservation = null;
+    const rawContext = body['pageObservation'];
+    if (rawContext !== undefined) {
+        if (!isPlainObject(rawContext)) {
+            throw new HttpError(400, 'expected-set pageObservation must be an object');
+        }
+        const rawPages = rawContext['pages'];
+        const rawLoginRoutes = rawContext['loginRoutes'];
+        const rawErrorMarkers = rawContext['errorMarkers'];
+        const rawAppOrigins = rawContext['appOrigins'];
+        const rawTamperRisks = rawContext['tamperRisks'];
+        const validPages = Array.isArray(rawPages) && rawPages.length > 0 &&
+            rawPages.every((page) => typeof page === 'object' && page !== null &&
+                typeof page['id'] === 'string' &&
+                page['id'].length > 0 &&
+                !page['id'].includes(':') &&
+                typeof page['path'] === 'string' &&
+                page['path'].startsWith('/') &&
+                (page['anonymous'] === undefined ||
+                    typeof page['anonymous'] === 'boolean'));
+        const validLoginRoutes = Array.isArray(rawLoginRoutes) &&
+            rawLoginRoutes.every((path) => typeof path === 'string' && path.startsWith('/'));
+        const validErrorMarkers = Array.isArray(rawErrorMarkers) &&
+            rawErrorMarkers.every((marker) => typeof marker === 'string' && marker.length > 0);
+        const validAppOrigins = Array.isArray(rawAppOrigins) &&
+            rawAppOrigins.every((origin) => {
+                if (typeof origin !== 'string')
+                    return false;
+                try {
+                    return new URL(origin).origin === origin;
+                }
+                catch {
+                    return false;
+                }
+            });
+        const validTamperRisks = Array.isArray(rawTamperRisks) &&
+            rawTamperRisks.every((risk) => {
+                if (typeof risk !== 'object' || risk === null)
+                    return false;
+                const row = risk;
+                return ((row['testId'] === null || typeof row['testId'] === 'string') &&
+                    typeof row['file'] === 'string' && row['file'].length > 0 &&
+                    typeof row['locationFile'] === 'string' && row['locationFile'].length > 0 &&
+                    typeof row['line'] === 'number' && Number.isInteger(row['line']) && row['line'] >= 1);
+            });
+        if (!validPages || !validLoginRoutes || !validErrorMarkers || !validAppOrigins || !validTamperRisks) {
+            throw new HttpError(400, 'expected-set pageObservation requires pages (non-empty {id, path, anonymous?} rows), loginRoutes ' +
+                "('/'-prefixed strings), errorMarkers (non-empty strings), appOrigins (valid origin " +
+                'strings), and tamperRisks ({testId: string|null, file, locationFile, line})');
+        }
+        pageObservation = {
+            pages: rawPages.map((page) => ({
+                id: page['id'],
+                path: page['path'],
+                ...(page['anonymous'] === undefined ? {} : { anonymous: page['anonymous'] }),
+            })),
+            loginRoutes: rawLoginRoutes,
+            errorMarkers: rawErrorMarkers,
+            appOrigins: rawAppOrigins,
+            tamperRisks: rawTamperRisks.map((risk) => ({
+                testId: risk['testId'],
+                file: risk['file'],
+                locationFile: risk['locationFile'],
+                line: risk['line'],
+            })),
+        };
+    }
     const digest = enumerationDigestOf(tests);
     if (state.enumerationDigest !== null) {
         if (state.enumerationDigest === digest) {
+            // Identical tests with a DIFFERENT page-observation context are a
+            // relabeling attempt, exactly like a changed test set: the context
+            // is a PRE-run fact bound once with the set.
+            if (canonicalOf(state.pageObservation) !== canonicalOf(pageObservation)) {
+                sendJson(res, 409, {
+                    error: 'an expected set with the same tests is already bound to this run with a different ' +
+                        'page-observation context; the context is a PRE-run fact and is never relabeled',
+                });
+                return;
+            }
             sendJson(res, 200, { bound: true, enumerationDigest: digest, count: state.expectedTests.size });
             return;
         }
@@ -1859,6 +2034,7 @@ async function handleExpectedSet(state, res, verifier, body) {
         state.expectedTests.set(expectedKey(test.project, test.file, test.titlePath), test);
     }
     state.enumerationDigest = digest;
+    state.pageObservation = pageObservation;
     sendJson(res, 200, { bound: true, enumerationDigest: digest, count: state.expectedTests.size });
 }
 /**
@@ -2812,6 +2988,7 @@ async function handleSessionClose(state, res, body) {
             }
             session.outcome = outcome;
         }
+        sealPageObservationRecords(state, sessionId, session.outcome);
         // The session's own evidence died with its proxy at release; the
         // observe snapshots are dropped HERE, at the moment the outcome is
         // finally recorded, so an unreleased session's before-state can
@@ -2819,6 +2996,7 @@ async function handleSessionClose(state, res, body) {
         state.observeSnapshots.delete(sessionId);
         state.sessionIdentities.delete(sessionId);
         state.sessionPageOrigins.delete(sessionId);
+        await stopPageObserver(state, sessionId);
         sendJson(res, 200, { sealed: true });
         return;
     }
@@ -2826,6 +3004,7 @@ async function handleSessionClose(state, res, body) {
         session.status = 'sealed';
         session.sealedTick = (state.tick += 1);
         session.outcome = typeof outcome === 'string' ? outcome : null;
+        sealPageObservationRecords(state, sessionId, session.outcome);
         state.workerSessions.delete(session.workerIndex);
         // Observe snapshots die with the session: finalize runs BEFORE seal
         // (the drain finalizes a passed test, then seals), so anything left
@@ -2840,6 +3019,7 @@ async function handleSessionClose(state, res, body) {
         // (or submit) through it afterwards. The engine browser context dies
         // too — a sealed session's pages are never driven again.
         await stopSessionProxy(session);
+        await stopPageObserver(state, sessionId);
         await state.engineBrowser?.closeSession(session.sessionId);
     }
     sendJson(res, 200, { sealed: true });
@@ -3035,6 +3215,7 @@ async function handleSessionRelease(state, res, body) {
         // The dedicated channel dies with the release: no exchange can be
         // observed through this session after its test finished.
         await stopSessionProxy(session);
+        await stopPageObserver(state, sessionId);
         await state.engineBrowser?.closeSession(session.sessionId);
     }
     sendJson(res, 200, { released: true });
@@ -5105,6 +5286,12 @@ async function stopWitness(state) {
     for (const session of state.sessions.values()) {
         await stopSessionProxy(session);
     }
+    for (const sessionId of state.pageObservers.keys()) {
+        await stopPageObserver(state, sessionId);
+    }
+    for (const sessionId of state.pageObservationRecords.keys()) {
+        sealPageObservationRecords(state, sessionId, null);
+    }
     // Phase 4 lifecycle shutdown: release every live fixture lease namespace.
     // Timeouts/failures release only their own namespace and never flip a
     // verdict — releases here are best-effort shutdown hygiene.