Relay: scoped clients, sealed slots, and a signed queue

docs/changes/unreleased/1928-scoped-client-relay.md

@@ -0,0 +1,11 @@
+---
+kind: added
+title: Scoped clients keep sealed slots and a signed queue
+pr: 1928
+surface: [remote, docs]
+invalidates:
+  - "The relay manual said the hosted Worker does not support scoped clients. The Go relay and the hosted Worker both register a client device, store its sealed slots, and accept a signed queue."
+  - "A device on the relay was a full device. A full device can now register a scoped client that cannot read the directory, the blob store, or another client's slots and queue."
+---
+
+Registration happens before the certificate is released. The relay cannot read sealed slots or calls. An executor must verify the retained request proof before it runs one.

docs/relay-clients.md

@@ -0,0 +1,102 @@
+# Scoped clients, slots and queue
+
+## Authentication and pairing
+
+All routes use the existing `Codeaf-Identity`, `Codeaf-Cert`, `Codeaf-Time`
+and `Codeaf-Sig` headers and `codeaf-req-v1` signing bytes (method, request
+URI including query, request time, SHA-256 of the exact body). Identity namespaces
+come exclusively from verified identity keys. Request skew is at most five minutes.
+Errors are JSON `{"err":"code"}`. All replies include `Codeaf-Now` (Unix ms).
+A store must be enabled. JSON bodies use UTF-8; sealed bytes use padded standard
+base64. Unknown JSON fields and trailing JSON are rejected on fabric routes.
+
+A full device pairs a client with `PUT /v1/clients/{device}` and body
+`{"cert":<identity.Cert>,"methods":["method.name"],"name":"sealed name"}`.
+The certificate must verify under the request's identity public key and name the
+path device. The client generates its own Ed25519 key; the full device signs only
+its public key with the existing certificate format. **Register before releasing
+the certificate to the client**: legacy certificates carry no cryptographic scope.
+The pairing grant contains only the certificate, identity public key and public
+connection information; never cell keys, dedup secrets, identity private keys or
+vault data. The relay accepts no grant or secret fields on this route.
+
+Registration returns 204 and creates a directory device record with `kind: client`
+and `methods`. At most 64 distinct method names, each 1–128 ASCII letters, digits,
+underscore, dot or hyphen; an empty list is a read-only client. Repeat registration
+returns 409 `exists`; scope changes require revocation and a new key. A full
+existing device cannot be converted to a client. Old records without kind remain
+full devices. `GET /v1/dir/list` by a full device includes the client records.
+Clients cannot access directory, identity or blob-store routes (401 unauthorized),
+including self-updates, approvals, leases and the vault. A client can read only its
+own slots and append only its own queue. The method allowlist is checked at append;
+the executing box must also check it before execution.
+
+`POST /v1/dir/devices/{device}/revoke` is the existing full-device revoke.
+A successful revoke deletes that client's slots, queue and sequence state. Its
+certificate stays revoked across restarts; requests return 401 `revoked`.
+
+## Slots
+
+`PUT /v1/clients/{device}/slots/{name}` by any full device of the same identity
+replaces one slot. Body: `{"sealed":"base64"}`. The receiver must be an active
+client. Names are 1–128 ASCII letters, digits, underscore, dot or hyphen. Maximum
+64 slots per client and 65536 decoded bytes per slot (nonempty).
+Success: 204. Writers are responsible for sealing to the current client key and
+publishing only chats whose lease they hold; the relay cannot inspect sealed data.
+
+`GET /v1/clients/{device}/slots/{name}` by that client returns 200
+`{"sealed":"base64","writer":"dev_…","at":1700000000000}`.
+The relay sets writer and Unix-ms time. Slots expire at age 24 hours, including
+across restart, and expired slots free capacity. Full devices cannot read slots.
+
+## Queue
+
+`POST /v1/clients/{device}/queue` by that client accepts
+`{"number":1,"at":1700000000000,"method":"method.name","target":"any","sealed":"base64"}`.
+Numbers start at 1 and increase by exactly one per client, even after ack or
+expiry. Integers must fit signed 64 bits. `at` is Unix ms, no more than five
+minutes in the future and strictly younger than 24 hours. Each nonempty sealed
+entry is at most 4096 decoded bytes; at most 128 unacknowledged entries per
+client. Target is `any` or an active registered full device id in this identity.
+The signed HTTP request authenticates all fields. Success: 204. Invalid numbers
+(replay or gap) return 409 `sequence`; stale timestamps return 400 `stale`.
+Denied methods return 403 `method_denied`. Expired entries free capacity but
+never reset numbering.
+
+`GET /v1/clients/{device}/queue` by a full device returns 200 `{"entries":[]}`,
+ordered by number, with fields above plus `signature`, `cert`, `identity`,
+`request_time`, `request_uri`, and `body` (base64 exact original JSON bytes).
+These preserve the original request proof for independent box verification.
+Only entries targeted at the caller, unclaimed `any` entries, or `any` entries
+claimed by the caller are listed. A list does not claim or change a chat lease.
+
+`POST /v1/clients/{device}/queue/{number}/claim` by a full device atomically
+claims an `any` entry; success 204, same claimer repeat 204, another claimer
+409 `claimed`. A targeted entry is claimable only by its target. Claims persist
+until ack or expiry; the relay never automatically reassigns work after a crash.
+An executor must claim before running. This prevents competing boxes executing
+the same entry; durable executor-side idempotency is still required after a crash.
+
+`DELETE /v1/clients/{device}/queue/{number}` by the claim owner deletes the entry
+and returns 204. Ack without owning the claim returns 409 `claimed`. Missing or
+expired entries return 404 `not_found`. A box must recheck age, signature, method
+scope, routing and any required biometric flag inside the sealed call, and log
+execution. The relay cannot verify encrypted call contents or biometric evidence.
+
+## Refusals, persistence and implementations
+
+Malformed bodies, names, targets or empty sealed values: 400 `bad_request`.
+Oversized HTTP bodies (maximum 96 KiB), decoded blobs or method lists: 413
+`too_large`. Slot/queue capacity: 429 `full`. Unknown client/slot/entry: 404
+`not_found`. Wrong role or identity: 401 `unauthorized`; revoked certificate:
+401 `revoked`; request skew: 401 `skew`; replaced identity: 410 `rotated`;
+deleted identity: 410 `gone`. Unsupported methods: 405. Internal storage failure:
+500 `internal`. Nonempty bodies on bodyless routes: 400 `bad_request`.
+
+Records, sequence watermarks, proof and claims survive relay restarts. Fabric
+mutations and revocation serialize within a relay process. One running Go relay
+owns a store directory, as with its in-memory directory revocation feed.
+Expiry is evaluated on reads and writes with the relay clock. Identity retirement
+erases fabric data with the existing directory and blobs.
+
+The Go relay and the Worker implement this contract.

internal/clusterstate/apply.go

@@ -166,6 +166,9 @@ func Dependencies(c Command) []RecordKey {
 	if m.PutDevice != nil {
 		keys = append(keys, DeviceKey(m.PutDevice.ID))
 	}
+	if m.RegisterClient != nil {
+		keys = append(keys, DeviceKey(m.RegisterClient.Device), AuthorityKey(m.RegisterClient.Device))
+	}
 	if m.Revoke != nil {
 		keys = append(keys, DeviceKey(m.Revoke.Device))
 	}
@@ -412,6 +415,10 @@ func evaluateCommand(c Command, meta ApplicationMeta, read ReadRecord, paged boo
 		out.Result.Code = Revoked
 		return out, nil
 	}
+	if actor.Kind == "client" {
+		out.Result.Code = Unauthorized
+		return out, nil
+	}
 	// Worker incarnation and scope precede dedup so an old successful result
 	// cannot restart activity after a process replacement, expiry or revocation.
 	if auth.Worker != nil {
@@ -517,7 +524,7 @@ func evaluateCommand(c Command, meta ApplicationMeta, read ReadRecord, paged boo
 				if Decode(d, &seen) != nil {
 					return out, ErrDependency
 				}
-				if !seen.Revoked {
+				if !seen.Revoked && seen.Kind != "client" {
 					seen.LastSeen = out.Now
 					put(DeviceKey(c.Change.DeviceSeen.Device), seen)
 				}
@@ -741,9 +748,43 @@ func applyMutation(c Command, now int64, identity IdentityRec, rows map[RecordKe
 		return OK
 	case m.PutDevice != nil:
 		v := m.PutDevice
+		if v.Device.Kind != "" || len(v.Device.Methods) > 0 {
+			return BadRequest
+		}
 		old, had := device(v.ID)
 		put(DeviceKey(v.ID), Stamped(old, had, v.Device, now))
 		return OK
+	case m.RegisterClient != nil:
+		v := m.RegisterClient
+		if !validClientDeviceID(v.Device) || len(v.Name) > MaxClientName || len(v.Methods) > MaxClientMethods {
+			return BadRequest
+		}
+		seen := map[string]bool{}
+		for _, method := range v.Methods {
+			if !validFabricName(method) || seen[method] {
+				return BadRequest
+			}
+			seen[method] = true
+		}
+		if _, had := device(v.Device); had || rows[AuthorityKey(v.Device)] != nil || v.Device == c.Actor {
+			return Exists
+		}
+		if PersonalCertificate(identity, v.Device, v.Cert) != nil {
+			return BadRequest
+		}
+		var methods []string
+		if len(v.Methods) > 0 {
+			methods = append([]string(nil), v.Methods...)
+		}
+		put(DeviceKey(v.Device), Device{
+			V:       1,
+			Kind:    "client",
+			Methods: methods,
+			Name:    v.Name,
+			AddedBy: identity.Identity,
+			Created: now,
+		})
+		return OK
 	case m.Revoke != nil:
 		v := m.Revoke
 		old, had := device(v.Device)
@@ -843,6 +884,9 @@ func applyMutation(c Command, now int64, identity IdentityRec, rows map[RecordKe
 			if old.Revoked {
 				return Revoked
 			}
+			if old.Kind == "client" || v.Record.Kind != "" || len(v.Record.Methods) > 0 {
+				return BadRequest
+			}
 			public, e := JoinCertificate(identity, request, v.Cert)
 			if e != nil || validGrant(v.Grant) == false {
 				return BadRequest

internal/clusterstate/effects.go

@@ -121,6 +121,9 @@ func applyEffect(c Command, now int64, rows map[RecordKey][]byte, put func(Recor
 		if d.Revoked {
 			return Revoked
 		}
+		if d.Kind == "client" {
+			return Unauthorized
+		}
 		if Decode(rows[AuthorityKey(r.Device)], &auth) != nil || !auth.ValidRole() || auth.Cluster != c.Cluster || !auth.Personal && auth.Worker == nil {
 			return Unauthorized
 		}

internal/clusterstate/liveness.go

@@ -75,6 +75,9 @@ func renewHolds(c Command, now int64, rows map[RecordKey][]byte, put func(Record
 	if actor.Revoked {
 		return Revoked
 	}
+	if actor.Kind == "client" {
+		return Unauthorized
+	}
 	if auth.Worker != nil {
 		var identity IdentityRec
 		if Decode(rows[IdentityKey()], &identity) != nil {

internal/clusterstate/personal_host.go

@@ -26,7 +26,7 @@ func personalAllowed(cluster, actor, certificate string, read ReadRecord) (Code,
 	}
 	if raw != nil {
 		var d Device
-		if Decode(raw, &d) != nil || d.Revoked {
+		if Decode(raw, &d) != nil || d.Revoked || d.Kind == "client" {
 			return Unauthorized, nil
 		}
 	}

internal/clusterstate/records.go

@@ -55,6 +55,12 @@ type Device struct {
 	// Codeaf-Chat-Notes.
 	Outbox []Note   `json:"outbox,omitempty"`
 	Took   []string `json:"took,omitempty"`
+
+	// Kind is "" for a full device and "client" for a scoped client that may
+	// only read its slots and append to its call queue. Methods lists the queue
+	// methods a scoped client may invoke.
+	Kind    string   `json:"kind,omitempty"`
+	Methods []string `json:"methods,omitempty"`
 }
 
 // Note is one message waiting in a device's outbox for whichever computer

internal/clusterstate/rules.go

@@ -135,6 +135,7 @@ func RevokeOf(target Device, caller, targetID string) (Device, error) {
 // relay-owned fields are never taken from the client: Revoked and LastSeen stay
 // as stored, and Created is the time of the first write.
 func Stamped(old Device, had bool, d Device, now int64) Device {
+	d.Kind, d.Methods = old.Kind, old.Methods
 	d.Revoked, d.LastSeen, d.Created = old.Revoked, old.LastSeen, old.Created
 	if !had {
 		d.Created = now

internal/clusterstate/types.go

@@ -81,6 +81,7 @@ type Mutation struct {
 	Release            *ReleaseCell        `json:"release,omitempty"`
 	Archive            *CellID             `json:"archive,omitempty"`
 	PutDevice          *PutDevice          `json:"put_device,omitempty"`
+	RegisterClient     *ClientRegistration `json:"register_client,omitempty"`
 	Revoke             *DeviceID           `json:"revoke,omitempty"`
 	SetVault           *VaultCAS           `json:"set_vault,omitempty"`
 	AdvanceTime        *AdvanceTime        `json:"advance_time,omitempty"`
@@ -143,6 +144,15 @@ type PutDevice struct {
 	Device Device `json:"device"`
 }
 
+// ClientRegistration records a scoped client device and its allowed queue
+// methods in the replicated directory. Only a full device may submit it.
+type ClientRegistration struct {
+	Device  string   `json:"device"`
+	Cert    string   `json:"cert"`
+	Name    string   `json:"name,omitempty"`
+	Methods []string `json:"methods,omitempty"`
+}
+
 type VaultCAS struct {
 	Old string `json:"old"`
 	New string `json:"new"`