Port recording
+ +Review aids
+ + +Differences require matched lossless frame identity, viewport and crop metadata.
+ +Raw recordings above remain unobstructed. Differences are review aids; lossy video is not a numerical fidelity measure.
+diff --git a/tests/fidelity-viewer.test.mjs b/tests/fidelity-viewer.test.mjs index 36faddd..c40644b 100644 --- a/tests/fidelity-viewer.test.mjs +++ b/tests/fidelity-viewer.test.mjs @@ -1,7 +1,8 @@ -import test from 'node:test'; +import nodeTest from 'node:test'; import assert from 'node:assert/strict'; -import {pathToFileURL} from 'node:url'; import {existsSync} from 'node:fs'; +let declared = 0; +function test(name, action) { declared++; return nodeTest(name, action); } const modulePath = new URL('../tools/recon/fidelity_viewer/viewer.mjs', import.meta.url); const api = existsSync(modulePath) ? await import(modulePath) : {}; @@ -54,5 +55,5 @@ test('capability navigation is supplied through a renderer', () => { assert.equal(typeof api.renderCapabilities, 'function'); }); test('suite executes a positive declared count', () => { - assert.ok(6 > 0); + assert.ok(declared >= 6, 'runner must register a positive number of behavior tests'); }); diff --git a/tests/test_fidelity_review.py b/tests/test_fidelity_review.py index 6478c5a..235cd2e 100644 --- a/tests/test_fidelity_review.py +++ b/tests/test_fidelity_review.py @@ -146,6 +146,9 @@ class FidelityReview(unittest.TestCase): value['limitations'].append(hostile) raw = self.original.parent / 'raw.json' raw.write_text(json.dumps(value)) + # A new collector bundle has no import sidecar; do not reuse another + # receipt's immutable metadata identity for this changed observation. + (self.original.parent / 'receipt.sha256').unlink() data = self.api().export_review(raw, None, self.output) self.assertIn(hostile, data['sides']['original']['limitations']) self.assertNotIn(hostile, (self.output / 'index.html').read_text()) diff --git a/tools/recon/fidelity_review.py b/tools/recon/fidelity_review.py new file mode 100644 index 0000000..7774701 --- /dev/null +++ b/tools/recon/fidelity_review.py @@ -0,0 +1,280 @@ +"""Export validated local receipts; serve only the generated, read-only tree. + +CLI: export --original IMPORT/receipt.json --port IMPORT/receipt.json --output NEW + serve --root NEW [--port 8765] +Either side may be omitted. Exports are review aids, never acceptance receipts. +The cooperative offline filesystem boundary matches fidelity_receipts: revalidate +before review; hostile concurrent filesystem replacement is outside this model. +""" +import argparse +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +import json +import mimetypes +import os +from pathlib import Path +import re +import shutil +import tempfile +from urllib.parse import quote, unquote, urlsplit + +from fidelity_receipts import (MAX_JSON_BYTES, canonical_bytes, contained_path, + identify_file, read_json, read_receipt, separated_roots, + validate_receipt) + +VIEWER = Path(__file__).with_name('fidelity_viewer') +PROJECT = Path(__file__).resolve().parents[2] +STATIC = ('index.html', 'viewer.mjs', 'style.css') +MAX_RANGE = 16 * 1024 * 1024 + + +def _side(path, side): + if path is None: + return {'missing': 'Missing ' + side + ' reference recording', 'media': None, + 'artifacts': [], 'events': [], 'derivatives': []}, [] + path = Path(path) + if path.is_symlink(): + raise ValueError('Receipt must not be a symlink') + path = path.resolve(strict=True) + value = read_receipt(path) + validation = validate_receipt(value, path.parent) + prefix = 'sides/' + side + '/' + paths = {a['path'] for a in value['artifacts']} + paths.update(a['path'] for a in value['identity'].values() if isinstance(a, dict) and 'path' in a) + if any(name.casefold() in ('receipt.json', 'receipt.sha256') for name in paths): + raise ValueError('Artifact collides with exported receipt') + artifacts = [dict(a, url=quote(prefix + a['path'], safe='/')) for a in value['artifacts']] + videos = [a for a in artifacts if a['role'] in ('video', 'preview')] + # A preview is explicit derivative provenance; a raw recording remains linked. + media = next((a for a in videos if a['role'] == 'preview'), next(iter(videos), None)) + events = [e for e in value['events'] if media and e['artifact'] == media['path']] + result = {key: value.get(key) for key in ('receipt_id', 'session_id', 'case_id', 'scope', + 'evidence_kind', 'status', 'platform', 'historical', 'limitations', 'identity', 'clocks')} + result.update(artifacts=artifacts, media=media, events=events, + derivatives=value['derivatives'], receipt_url=prefix + 'receipt.json', + missing_evidence=validation['missing_evidence'], + missing='' if media else 'Missing ' + side + ' playable video/preview', + acceptance={'state': 'open', 'remaining': ['Review export is not acceptance']}) + copies = [(contained_path(path.parent, name), prefix + name) for name in sorted(paths)] + copies.append((path, prefix + 'receipt.json')) + return result, copies + + +def _events(sides): + indexed = {} + for side, record in sides.items(): + seen = set() + for event in record['events']: + if event['name'] in seen: + raise ValueError('Ambiguous duplicate event on selected media: ' + event['name']) + seen.add(event['name']) + indexed.setdefault(event['name'], {'name': event['name'], 'original': None, 'port': None})[side] = event + return list(indexed.values()) + + +def _ledger(path): + if path is None: + return {'schema_version': 1, 'capabilities': []} + data = read_json(path) + if data.get('schema_version') != 1 or not isinstance(data.get('capabilities'), list): + raise ValueError('Unsupported capability export') + # Source links are references, never commands or remote URLs. Only exported + # media/receipt links are clickable; source paths remain inert navigation text. + return data + + +def export_review(original, port, output, ledger=None): + """Return review model and atomically publish a NEW self-contained directory.""" + output = Path(output) + if output.is_symlink() or output.exists(): + raise ValueError('Review output must be a new directory') + output = output.resolve() + separated_roots(PROJECT.parent / 'Original', output) + sides, copies = {}, [] + for side, path in [('original', original), ('port', port)]: + if path: + separated_roots(Path(path).resolve().parent, output) + sides[side], files = _side(path, side) + copies += files + present = [s for s in sides.values() if 'case_id' in s] + if len({(s['case_id'], s['scope']) for s in present}) > 1: + raise ValueError('Paired receipts must describe the same case and scope') + model = {'schema_version': 1, 'case_id': present[0]['case_id'] if present else 'empty', + 'sides': sides, 'events': _events(sides), 'ledger': _ledger(ledger), + 'acceptance': {'state': 'open', 'remaining': ['Actual identified runtime and audiovisual review required']}} + encoded = canonical_bytes(model) + if len(encoded) > MAX_JSON_BYTES: + raise ValueError('Review JSON exceeds bound') + output.parent.mkdir(parents=True, exist_ok=True) + temporary = Path(tempfile.mkdtemp(prefix='.' + output.name + '-incomplete-', dir=output.parent)) + # Failure retains the temporary tree for diagnosis; never partially publish. + (temporary / 'incomplete.json').write_text('{"status":"incomplete"}\n') + for source, relative in copies: + target = temporary / relative + target.parent.mkdir(parents=True, exist_ok=True) + shutil.copyfile(source, target) + if identify_file(source) != identify_file(target): + raise ValueError('Artifact changed during review copy') + for name in STATIC: + shutil.copyfile(VIEWER / name, temporary / name) + (temporary / 'review.json').write_bytes(encoded) + files = list(STATIC) + ['review.json'] + [name for _, name in copies] + manifest = {'schema_version': 1, 'tool': 'fidelity_review', 'files': + [dict(path=name, **identify_file(temporary / name)) for name in files]} + (temporary / '.review-root.json').write_bytes(canonical_bytes(manifest)) + (temporary / 'incomplete.json').unlink() + # Recheck the receipt/artifact copies with the shared validator at publication. + for side in ('original', 'port'): + receipt = temporary / 'sides' / side / 'receipt.json' + if receipt.exists(): + validate_receipt(read_receipt(receipt), receipt.parent) + if output.exists(): + raise ValueError('Review output allocated by another writer') + os.rename(temporary, output) + return model + + +class ReviewHandler(BaseHTTPRequestHandler): + """No directory listing, upload, repository root, symlink or remote access.""" + def log_message(self, *_args): + pass + + def end_headers(self): + self.send_header('X-Content-Type-Options', 'nosniff') + self.send_header('Content-Security-Policy', "default-src 'none'; script-src 'self'; style-src 'self'; " + "media-src 'self'; img-src 'self'; connect-src 'self'; base-uri 'none'; " + "frame-ancestors 'none'; form-action 'none'; object-src 'none'") + self.send_header('Referrer-Policy', 'no-referrer') + self.send_header('Cache-Control', 'no-store') + super().end_headers() + + def do_GET(self): + self._read(False) + + def do_HEAD(self): + self._read(True) + + def _reject(self): + self.send_response(405) + self.send_header('Allow', 'GET, HEAD') + self.send_header('Content-Length', '0') + self.end_headers() + + do_POST = do_PUT = do_DELETE = do_PATCH = do_OPTIONS = do_TRACE = do_CONNECT = _reject + + def _read(self, head): + try: + parsed = urlsplit(self.path) + if parsed.scheme or parsed.netloc or parsed.query or parsed.fragment: + raise ValueError('Only generated local paths are readable') + name = unquote(parsed.path, errors='strict') + name = 'index.html' if name == '/' else name.removeprefix('/') + path = contained_path(self.server.root, name) + if name not in self.server.allowed or not path.is_file(): + self.send_error(404) + return + size = path.stat().st_size + start, end, status = 0, size - 1, 200 + range_value = self.headers.get('Range') + if range_value: + match = re.fullmatch(r'bytes=([0-9]{0,20})-([0-9]{0,20})', range_value) + if not match or not any(match.groups()) or size == 0: + raise IndexError('Invalid range') + left, right = match.groups() + if left: + start = int(left) + end = min(int(right), size - 1) if right else size - 1 + else: + suffix = int(right) + if suffix <= 0: + raise IndexError('Invalid suffix') + start = max(0, size - suffix) + if start >= size or start > end: + raise IndexError('Unsatisfiable range') + end = min(end, start + MAX_RANGE - 1) + status = 206 + self.send_response(status) + mime = 'text/javascript' if name.endswith('.mjs') else mimetypes.guess_type(name)[0] + mime = mime or 'application/octet-stream' + # Imported HTML/SVG/scripts never become active same-origin content. + if name not in STATIC and not (mime.startswith(('video/', 'audio/')) or + mime in ('image/png', 'image/jpeg', 'image/webp', 'application/json')): + mime = 'application/octet-stream' + self.send_header('Content-Disposition', 'attachment') + self.send_header('Content-Type', mime) + self.send_header('Accept-Ranges', 'bytes') + self.send_header('Content-Length', str(max(0, end - start + 1))) + if status == 206: + self.send_header('Content-Range', f'bytes {start}-{end}/{size}') + self.end_headers() + if not head: + with path.open('rb') as stream: + stream.seek(start) + remaining = end - start + 1 + while remaining > 0: + block = stream.read(min(65536, remaining)) + if not block: + break + self.wfile.write(block) + remaining -= len(block) + except IndexError: + self.send_response(416) + self.send_header('Content-Range', f'bytes */{size}') + self.send_header('Content-Length', '0') + self.end_headers() + except (ValueError, UnicodeError, OSError): + self.send_error(403) + + +def make_server(root, port=8765, host='127.0.0.1'): + if host != '127.0.0.1': + raise ValueError('Viewer binds literal IPv4 loopback only') + root = Path(root) + if root.is_symlink(): + raise ValueError('Review root must not be a symlink') + root = root.resolve(strict=True) + separated_roots(PROJECT.parent / 'Original', root) + manifest = read_json(contained_path(root, '.review-root.json')) + if manifest.get('tool') != 'fidelity_review' or manifest.get('schema_version') != 1: + raise ValueError('Only generated review trees can be served') + allowed = set() + for item in manifest.get('files', []): + path = contained_path(root, item['path']) + actual = identify_file(path) + if item['sha256'] != actual['sha256'] or item['size'] != actual['size']: + raise ValueError('Generated review changed; export again') + allowed.add(item['path']) + if not set(STATIC + ('review.json',)).issubset(allowed): + raise ValueError('Incomplete generated review') + server = ThreadingHTTPServer((host, port), ReviewHandler) + server.daemon_threads = True + server.root, server.allowed = root, allowed + return server + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + commands = parser.add_subparsers(dest='command', required=True) + export = commands.add_parser('export') + export.add_argument('--original', type=Path) + export.add_argument('--port', type=Path) + export.add_argument('--output', type=Path, required=True) + export.add_argument('--ledger', type=Path) + serve = commands.add_parser('serve') + serve.add_argument('--root', type=Path, required=True) + serve.add_argument('--port', type=int, default=8765) + args = parser.parse_args() + try: + if args.command == 'export': + model = export_review(args.original, args.port, args.output, args.ledger) + print(json.dumps({'path': str(args.output / 'index.html'), + 'events': len(model['events']), 'acceptance': 'OPEN'})) + else: + with make_server(args.root, args.port) as server: + print(f'Local review: http://127.0.0.1:{server.server_port}/ — acceptance OPEN', flush=True) + server.serve_forever() + except (ValueError, OSError) as error: + parser.exit(2, 'Review error: ' + str(error) + '\n') + + +if __name__ == '__main__': + main() diff --git a/tools/recon/fidelity_viewer/index.html b/tools/recon/fidelity_viewer/index.html new file mode 100644 index 0000000..c777fb8 --- /dev/null +++ b/tools/recon/fidelity_viewer/index.html @@ -0,0 +1,40 @@ + + +
+ + +NEUTRON GAMEPORT / LOCAL EVIDENCE
Loading local review…
Acceptance OPEN · export and fixture playback do not establish original or native gameplay parity.
Differences require matched lossless frame identity, viewport and crop metadata.
+ +Raw recordings above remain unobstructed. Differences are review aids; lossy video is not a numerical fidelity measure.
+