Every Caller Has a Name

Doors That Answered Anyone

Pippa reaches Oriel through two doors: the eyes door for looks, over the tailnet's HTTPS twin, and the app door for writes, on loopback. Until the same day the page moved to PIN sessions, the eyes door answered anyone on the tailnet and the app door answered any program on Pippa's home Mac. The eyes gate and Dad's quoted words still stood behind both, so nothing could be opened without approval. But nothing said the caller was cwkPippa. A curious script on the tailnet could still ask for a look while the eyes were in Auto, and that is a look the house did not intend.

Coop 1110-13 gave every caller a name. The doors now ask for a bearer token, and each token belongs to exactly one named caller, minted by Oriel, for one purpose.

Tokens Kept as Hashes

Every kind of named caller in Oriel (Pippa's service, Oriel's own tools, Dad's other screens, satellites on other Macs, watch-along watchers) uses the same small registry. Its rules are the ones you would want for any secret:

Minted once, shown once. python -m backend.callers add cwkpippa --label "…" prints the token a single time; it is delivered to the holder on stdin, never as a command-line argument (which other users of the machine can see in a process list) and never in a log.
Only the hash is stored. The registry file keeps the token's SHA-256, written with mode 0600 from the moment the file exists (the kit's atomic writer sets the mode before the rename, so there is no instant when the file is readable by others).
Compared in constant time. A request names itself with Authorization: Bearer <token>, and the comparison does not leak, through timing, how much of a guess was right.
One shared implementation. The satellites' and the watchers' registries were two copies of this code until 2026-11-06; now there is one root and every caller kind is an instance of it.

A Name Opens Only Its Door

The point of names is not just knowing who called; it is limiting what each caller can do.

Caller	What its token opens
cwkPippa (`cwkpippa`)	the eyes door and the app door; never a page route, never an approval on its own (the gate and Dad's words are still asked)
Oriel's own tools (`local`)	the same two doors, from this Mac; the engine mints it at start into a file only her account can read
Dad's other screens (surfaces)	set the eyes mode, press the kill switch, and start or stop Solo Mode, as Dad's hand on that screen; no look, no frame
Satellites, watchers	their own worker routes only

The surfaces row is worth a second look. A family screen like cwkPippa's web app has already verified Dad's PIN session on its own side, so its press can carry his hand to Oriel. But its token cannot take a picture. If that screen's engine were compromised, its token could change the mode, press the kill switch, or start, extend and stop Solo Mode, but never take a look or a frame. One route is guarded by the gate rather than by a name, and it is worth knowing: a camera's latest frame answers any caller that reaches the engine while the eyes gate covers that camera. There, the gate is the whole guard. Put the two facts together and a compromised surface could set Auto with its own press and then read a home camera's latest frame through that route; its token never carries a picture, but that two-step path exists, and what makes it visible is that every mode change is logged with the surface's name, and the red eye lights the moment a camera is actually in use.

Reads Without a Picture Need a Name Too

The last gap was subtle. Reads that return no picture (the state, the eye, the session list, the activity log) still describe the house: which cameras are open, when Dad was on air. Dad closed it the same day: put the picture-less reads behind the PIN too. Every such route now answers only Dad's session, a named service caller, or a surface by its token. A few routes stay open, as in every family app, and each has a reason: health and version (for the registry's census and the fleet monitor), the sign-in state (so the page can show the sign-in card), and the probes' question to the gate (a refusal carries its reason; a yes carries the input's id, name and media kind, nothing more).

Code

Minted once, stored as a hash, file born 0600 (trimmed excerpt, backend/tokens.py)·python

def token_hash(token: str) -> str:
    return hashlib.sha256(token.encode("utf-8")).hexdigest()


class TokenRegistry:
    """``{name: {token_sha256, label, added_at, ...}}`` in one JSON file."""

    def _write(self, config):
        atomic_write_text(self.path, json.dumps(config, indent=2, sort_keys=True) + "\n", mode=0o600,
                          preserve_mode=False)

    def mint(self, name: str, label: str = "", **fields) -> str:
        """A new token for ``name`` (a new one for a known name); returned once."""
        if not NAME.match(name):
            raise self._bad_name(f"a {self.what} name is lowercase letters, digits and dashes, 2 to 31 long")
        token = secrets.token_urlsafe(32)
        config = self.config()
        config[name] = {"token_sha256": token_hash(token), "label": " ".join(label.split())[:80],
                        "added_at": time.time(), **fields}
        ...  # written with _write; the plain token is returned to the caller and never stored

A named-token registry you can run: mint, check in constant time, refuse with a reason·python

import hashlib
import hmac
import secrets

registry = {}                                   # name -> sha256 of its token


def mint(name):
    token = secrets.token_urlsafe(32)
    registry[name] = hashlib.sha256(token.encode()).hexdigest()
    return token                                # shown once; never stored in clear


def name_of(authorization):
    if not authorization or not authorization.startswith("Bearer "):
        raise PermissionError("no bearer token")
    digest = hashlib.sha256(authorization[7:].encode()).hexdigest()
    for name, stored in registry.items():
        if hmac.compare_digest(stored, digest):
            return name
    raise PermissionError("an unknown token")


OPENS = {"cwkpippa": {"eyes", "app"}, "surface-webui": {"mode", "kill"}}


def allowed(authorization, door):
    name = name_of(authorization)
    if door not in OPENS.get(name, set()):
        raise PermissionError(f"{name} does not open the {door} door")
    return name


t = mint("surface-webui")
print(allowed(f"Bearer {t}", "kill"))
try:
    allowed(f"Bearer {t}", "eyes")
except PermissionError as exc:
    print("refused:", exc)

Exercise

Extend the runnable registry: store it in a JSON file created with mode 0600 (set the mode on a temporary file before renaming it into place), add a rotate(name) that mints a new token and invalidates the old one, and write a tiny CLI that reads a new token from stdin to configure a client. Then list three doors in a system you know and write which named caller should open each.

Hint

os.open with flags and mode 0o600, write, fsync, then os.replace gives a file that is never world-readable. For the CLI, sys.stdin.readline().strip() keeps the token out of argv and out of shell history.