valis - Building Your Own System on valis

protocol (valis/src/protocol) carries the per-port contract: a name, the ports it claims, and a description. Subclass it and provide a constructor that fixes those:

(defclass echo-protocol (valis/src/protocol:protocol) ())

(defun make-echo-protocol ()
  (make-instance 'echo-protocol
                 :name :echo
                 :ports (list 7007)
                 :description "Line echo over the recovered port."))

handle-connection (valis/src/protocol, a generic of (protocol connection)) is your per-connection entry point. By the time it runs, the recovered destination port has already selected your module and the connection arrives with its principal resolved. Read and write over connection-stream; the connection also exposes connection-principal and connection-destination-port. You never parse the wire to learn who is calling: identity is resolved for you.

(defmethod valis/src/protocol:handle-connection
    ((protocol echo-protocol) connection)
  (let ((stream (valis/src/connection:connection-stream connection)))
    (loop for line = (read-line stream nil)
          while line do (write-line line stream) (force-output stream))))

register-protocol (valis/src/registry) claims every port in the protocol's protocol-ports; the listener then routes matching connections to your handle-connection through dispatch-connection. Register once at boot:

(valis/src/registry:register-protocol (make-echo-protocol))

A port may be claimed once: a second claim signals port-already-claimed, and a connection for an unclaimed port signals no-protocol-for-port. The process-wide *registry* is the default; pass :registry to use your own.

The point of an adapter is to project a person's data, not to own it. Obtain a view for the connection's principal and walk it, rather than reaching for files directly. view-for (valis/src/edge/seam) returns a root handle and a 9P session for the resolved principal; and, when the view is per-request (a keyed principal, or a capability mount), a teardown thunk you must call when the request ends:

(multiple-value-bind (root session teardown)
    (valis/src/edge/seam:view-for connection principal nil)
  (unwind-protect
       (;; walk ROOT with seven's client (walk / read-bytes) and render
        )
    (when teardown (funcall teardown))))

An anonymous caller (a nil principal) resolves to the read-only published /pub floor; an owner-proven caller reaches the fuller frame. To mount a specific capability for the span of one request, use with-request-capability (valis/src/edge/seam), which mounts the designated grant, runs the body, and unmounts under unwind-protect. The HTTP adapter does exactly this to serve its two identity-selected views over one URL space.

start-fabric (valis/src/fabric) stands up the namespace tree, the identity seals, the capability service, and the 9P listener:

(valis/src/fabric:start-fabric 0
  :host "127.0.0.1"
  :keyfile "/path/to/owner.key")   ; the owner's Ed25519 seed

It binds HOST:PORT (pass 0 for an ephemeral port and read the bound port back with listener-port). The default host is loopback, the shape a developer uses to bring a keyed responder up locally. A production owner terminus does not self-bind a public address this way; it adopts an already-listening descriptor the host agent bound for it (see below). Either way, serving a non-loopback surface requires *fabric-auth-enabled-p* to stay true, so every remote peer must complete the Noise_XX handshake: valis refuses to serve a public network surface in the clear. Tear down with stop-fabric.

In production valis reaches the network on a port it is too unprivileged to bind itself. A co-located privileged host agent binds the routable owner port, then hands valis the already-listening descriptor, the same inherited-descriptor handoff valis already uses for :53 and :443. The resident boot receives that descriptor as --owner-fd <N> and threads it into start-fabric, exactly as it threads --dns-tcp-fd and --edge-tcp-fd. start-fabric adopts it by rebinding the *keyed-socket-source* seam (valis/src/transport/keyed-acceptor) to wrap the inherited fd as a keyed accept loop's passive socket. There is no second bind, so an already-listening fd cannot collide, and the adoption dups the descriptor: valis closes only its own dup on teardown and never the borrowed fd.

The owner terminus is a second keyed listener on the same namespace root: the loopback fabric (start-fabric 0) stays the local management path, and the owner terminus is the routable addition, present only when --owner-fd is supplied. Absent it, no owner terminus comes up (the default-closed posture) and every other resident shape is unchanged. Its reachability is owned by the host agent's descriptor, not by valis self-binding a public address. The registered 9P port (564) is the default valis records; the number the host agent actually opens is authoritative, and valis serves whatever descriptor it is handed.

The owner terminus carries the full owner surface to any peer that completes the handshake, so who answers matters as much as who dials. The anti-spoof guarantee is inherently client-side: the owner's client (ubik) must pin the deployed node's transport did:key and verify the peer's recovered static key against that pin, refusing a peer that does not match. valis cannot enforce this from the server: a server cannot stop a client from dialing an impostor.

The honest server-side lever is therefore exposure, not a code flag. The host agent's firewall keeps the owner port closed by default; it carries no valis switch that claims to prevent a client-side impersonation, because none could. Opening the port is a deliberate operator step, and the sequence is fixed:

1. Verify the deployed node's transport did:key is pinned in the owner's client, so a first off-host attach validates the responder rather than trusting whatever peer answers at the address.
2. Only then open the owner port in the host agent's allowlist.

Reverse that order and the first off-host use is spoofable. Until the pin is in place, the owner manages the node over the existing local path; the routable terminus stays firewall-dark even though the adoption code is wired.

A peer dials the listener and runs the standard 9P Tauth=/=Tattach exchange carrying a Noise_XX handshake. On a completed handshake, valis maps the peer's static key to a did:key principal and binds that principal to the session; from the first reply onward, every record on that connection is sealed. A peer that proves no key resolves to anonymous. You write none of this: it happens on seven's auth seam, with the cryptography owned by the mercer sibling (the floor in valis.asd is 0.6.0). valis holds only an opaque session handle and performs zero crypto itself.

The resolved principal then sees its own view. The factotum subtree exposes a read-only /id/owner node whose contents are the session principal's own did:key. A peer that reads it over the sealed session confirms it reached its authenticated view, not a shared or anonymous one.

valis is the responder. A reusable client that drives the keyed handshake and holds a sealing session lives under tests/support/ as test support: it proves the responder against a standard-conformant transcript and is not a shipped dial surface. If your system needs to initiate keyed sessions in production, that client is the seam to promote; a shippable dial client is a deliberate future addition, not part of the proven surface. Until then, model an initiator on the test-support sealing client and seven's client.lisp session.