@ccmsg/protocol 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/protocol",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Wire contract (schema + types + op attribute table) shared by the ccmsg daemon and web UI",
   "license": "MIT",
   "author": "kawaz",

package/src/control/peers.ts

@@ -1,4 +1,5 @@
 import { type Static, Type } from "@sinclair/typebox";
+import { InstanceInfo } from "../common/hello.ts";
 import { topicFrame } from "../envelope.ts";
 import { InstanceId, Sid, Timestamp } from "../identifiers.ts";
 import { SessionMetaFields } from "../session-meta.ts";
@@ -189,5 +190,15 @@ export const PeersFrame = topicFrame(
   Type.Object({
     peers: Type.Array(PeerInfo),
     last_live: Type.Array(LastLiveSession),
+    /** The instances the sending one can see, itself included, as `hello`
+     * answers it. Carried here so that a link going down is something a
+     * subscriber learns from the topic it is already on, rather than by
+     * greeting again to find out. It is the sender's own view like the two
+     * lists above — `reachable` says whether that instance can reach the one it
+     * names, which two instances may legitimately disagree about.
+     *
+     * Absent from an instance that states no view; a client then keeps what it
+     * last knew rather than reading the omission as nothing being reachable. */
+    instances: Type.Optional(Type.Array(InstanceInfo)),
   }),
 );

package/src/envelope.ts

@@ -1,6 +1,6 @@
 import { type Static, type TSchema, Type } from "@sinclair/typebox";
 import { ErrorBody } from "./errors.ts";
-import { InstanceId } from "./identifiers.ts";
+import { InstanceId, Role, Sid } from "./identifiers.ts";
 
 /** The generation of this wire contract. Within a generation, only optional
  * fields and whole new ops may be added; a removal or a change of meaning
@@ -8,14 +8,27 @@ import { InstanceId } from "./identifiers.ts";
  * connections and on mesh links alike. */
 export const PROTOCOL_VERSION = 2;
 
+/** The identity a forwarded request is dispatched as: the connection the
+ * forwarding instance received it on, in the two fields that decide anything —
+ * the role the attribute table is read against, and the session it speaks for. */
+export const CallerIdentity = Type.Object(
+  {
+    role: Role,
+    /** Present exactly when the role is `session`, as in `hello`. */
+    sid: Type.Optional(Sid),
+  },
+  { $id: "CallerIdentity" },
+);
+export type CallerIdentity = Static<typeof CallerIdentity>;
+
 /** Fields a request carries in addition to its own arguments.
  *
  * `request_id` pairs a reply with its request so one connection can run its
  * requests concurrently instead of in arrival order. Uniqueness only has to
  * hold among one connection's in-flight requests.
  *
- * The three mesh fields are the whole of the mesh plane: an op forwarded to
- * another instance is the same op in the same shape, wrapped in these. */
+ * The mesh fields are the whole of the mesh plane: an op forwarded to another
+ * instance is the same op in the same shape, wrapped in these. */
 export const RequestEnvelope = Type.Object(
   {
     request_id: Type.String({ minLength: 1 }),
@@ -28,6 +41,19 @@ export const RequestEnvelope = Type.Object(
     /** Instances this request has already passed through, in order. A request
      * that would revisit an instance is dropped rather than looped. */
     hops: Type.Optional(Type.Array(InstanceId)),
+    /** Who the forwarding instance says made this request.
+     *
+     * The destination runs every stage of dispatch again against this identity
+     * — the role check, the capability check, the whole of it — rather than
+     * taking the forwarder's outcome for it. What it does take is the identity
+     * itself: the forwarder is an authenticated peer, so what it says about who
+     * called is believed, which is the assumption that holds inside one
+     * deployment and nowhere else.
+     *
+     * A forwarded request that names none is dispatched as the `instance` role
+     * it arrived on, which the attribute table already answers: an
+     * instance-local op called by an instance is `forbidden`. */
+    caller: Type.Optional(CallerIdentity),
   },
   { $id: "RequestEnvelope" },
 );

package/src/messaging/direct-delivery.ts

@@ -23,9 +23,14 @@ export const DIRECT_DELIVERY_TAG = "cross-session-message";
  *
  * Not the sender's session and not a `uds:` path. Those are the addresses the
  * harness itself dials, and dialing one that has gone ends the recipient's turn
- * in failure; the sender here is a daemon that offers no such socket anyway.
- * A name asks for no answer, so there is nothing to dangle — the way back is
- * the reply line, which the recipient runs rather than the harness. */
+ * in failure. A name asks for no answer, so there is nothing to dangle — the
+ * way back is the reply line, which the recipient runs rather than the harness.
+ *
+ * The frame this wrapper is written in is a separate address: there the
+ * instance may name a `uds:` socket of its own, which is where the receiving
+ * harness writes what became of the delivery. Those receipts are negative only
+ * — `refused`, `denied`, `dropped`, `expired`, `held` — so silence within the
+ * window is what says the message was taken. */
 export const DIRECT_DELIVERY_FROM = "ccmsg";
 
 /** What the recipient is told the sender is doing. `prompting` is what a peer