A Gate You Cannot Walk Around

The Gate Is Only as Good as Its Bypasses

Every lesson so far assumed one thing: that a request for a picture goes through Gate.check. If any code path can reach a camera without it, the modes, the red eye and the close order are decoration. Security engineers call the property complete mediation: every access is checked, every time. Oriel enforces it in four layers, and the interesting thing is that three of them are about code that does not exist yet.

Layer 1: The Only Channel Carries the Gate

The engine reaches the recorder only through RecorderLink, and every link asks the gate before every want, peek and move. A link built without a gate does not quietly work: it refuses everything with "no eyes gate on this recorder link". So a new command-line tool that builds its own link, as tools sometimes do, gets the same answer a brain would.

Layer 2: A Test That Scans the Code and Scripts

The first layer protects the channel. It cannot stop someone from writing a second channel: calling ffmpeg with an avfoundation input, using a UVC control tool directly, writing desired.json from some other module. So one test, test_no_path_in_the_repository_reaches_a_camera_around_the_gate, does three things:

It builds a bare link and checks that a want, a peek and a move are all refused, and that nothing was written to the recorder's folder.
It scans the Python files directly in backend/ and the scripts directly in scripts/ (one level each; files in nested folders are not read, a gap worth knowing) for the signatures of device access (a desired.json path, an avfoundation input, AVCaptureDevice., a uvc-util call) and fails on any file outside an explicit two-file allow list: the recorder link itself and the satellite agent, which only copies what the engine's gated link already wrote.
It checks that every RecorderLink( constructed in those top-level backend files carries gate=, unless that line only lists devices or reads status.

A text scan is crude, and that is fine. It is not trying to understand the code; it is a tripwire. The day someone adds a shortcut to a camera, the suite fails with the file name, and the conversation about whether that shortcut should exist happens before it ships.

Layer 3: Native Probes Ask Before They Open

Some of Oriel's native helpers open devices themselves: the HDMI audio probe, a frame-rate probe. They live outside the engine, so the engine cannot wrap them. Instead they ask. Before opening anything, a probe calls GET /api/gate/device with the device's ID and the kind of media, and it refuses with exit status 7 when the answer is no, when there is no answer, or when it was not even told where the engine is (no --gate flag). The audio probe asks again every 10 seconds and ends its take on a refusal. One subtlety: when it runs as the recorder's helper during a recording, it ends on the engine's own "no", never on the engine's silence during a restart, so a deploy does not cut a recording's sound. Run on its own, an unanswered check refuses like any other. A list-only mode (--list) opens nothing and asks nothing. And a test fails if any probe opens a device without asking first.

Layer 4: Other Systems Ask Too

The same route answers callers outside Oriel. When Haven, the family's home-control app, is about to open a network camera's stream for one frame, it asks Oriel's gate first, so even a caller that skips Oriel's own look is refused at Haven. A camera on another Mac goes through the same gate as a home one (the last track shows how). And an export of a frame to leave the house passes the gate as well as its own checks.

One More Door: Stale Requests at Start

One bypass is not a code path but a timing: a peek or a move left in desired.json by an engine that died mid-wait would be honoured by the next recorder process, after the gate may have closed. The engine clears every one-shot request as it starts. A gate is not only about who may ask; it is also about requests that outlive the permission they were made under.

Code

A tripwire over backend/ and scripts/ (trimmed excerpt, backend/tests/test_eyes_gate.py)·python

def test_no_path_in_the_repository_reaches_a_camera_around_the_gate(settings):
    bare = RecorderLink(settings.recorder)                  # built without a gate
    for call in (lambda: bare.want("x", {"device_uid": LEFT}), lambda: bare.peek("x", LEFT, timeout=0.1),
                 lambda: bare.move({"device_uid": LINK, "set": {}}, timeout=0.1)):
        with pytest.raises(GateClosed, match="no eyes gate"):
            call()
    assert not (settings.recorder / "desired.json").exists(), "nothing was asked of the recorder"
    openers = re.compile(r"[\"'/]desired\.json|-f\s+avfoundation|[\"']avfoundation[\"']|AVCaptureDevice\.|"
                         r"[\"'/]uvc-util")
    allowed = {"backend/recorder_link.py", "backend/satellite_agent.py"}
    offenders = []
    for path in list((REPO / "backend").glob("*.py")) + list((REPO / "scripts").glob("*")):
        rel = str(path.relative_to(REPO))
        if rel in allowed or not path.is_file():
            continue
        text = path.read_text(encoding="utf-8", errors="replace")
        code = "\n".join(line for line in text.splitlines()
                         if not line.lstrip().startswith(("#", '"', "-", "*")))
        if openers.search(code):
            offenders.append(rel)
    assert offenders == [], f"device access outside the gate: {offenders}"

Write your own tripwire: fail the build when a forbidden call appears outside its one home (runnable)·python

import re
import sys
from pathlib import Path

FORBIDDEN = re.compile(r"-f\s+avfoundation|AVCaptureDevice\.|open_camera\(")
ALLOWED = {"camera/owner.py"}                    # the one module allowed to touch the device


def offenders(root: Path):
    found = []
    for path in root.rglob("*.py"):
        rel = path.relative_to(root).as_posix()
        if rel in ALLOWED or "/tests/" in f"/{rel}":
            continue
        code = "\n".join(line for line in path.read_text(errors="replace").splitlines()
                         if not line.lstrip().startswith("#"))
        if FORBIDDEN.search(code):
            found.append(rel)
    return found


bad = offenders(Path(sys.argv[1] if len(sys.argv) > 1 else "."))
print("device access outside its owner:", bad or "none")
sys.exit(1 if bad else 0)

Exercise

Pick one sensitive capability in a codebase you work on (sending email, charging a card, deleting user data). Decide which single module is allowed to do it, and adapt the runnable tripwire so that it fails when the capability's signature appears anywhere else. Run it, and for every offender decide: route it through the owner, or add it to the allow list with a written reason.

Hint

Keep the allow list tiny and give each entry a comment that says why it is safe, the way Oriel explains the satellite agent's exception. An allow list that grows without reasons is a bypass list.