@ccmsg/protocol 1.20.0 → 1.22.0

package/README.md

@@ -20,8 +20,8 @@ bun add @ccmsg/protocol
 import { isValid, MessageSendRequest, OP_ATTRIBUTES, opErrors } from "@ccmsg/protocol";
 
 isValid(MessageSendRequest, incoming); // validating the wire is the contract's job
-OP_ATTRIBUTES.message_send.roles; // authorization reads the table, not a branch
-opErrors("session_rename"); // the codes this op may answer with
+OP_ATTRIBUTES["message.send"].roles; // authorization reads the table, not a branch
+opErrors("session.rename"); // the codes this op may answer with
 ```
 
 ## Documentation

package/package.json

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

package/src/attributes.ts

@@ -17,7 +17,14 @@ export interface OpAttributes {
   readonly plane: Plane;
   /** Roles allowed to call the op. A role outside this set gets `forbidden`. */
   readonly roles: readonly Role[];
-  /** Whether the op requires an identity settled by `hello`. */
+  /** Whether the op requires an identity settled by a greeting.
+   *
+   * On a WebSocket connection the only ops that may arrive before one are the
+   * three greetings: a caller that will not say who it is has nothing to be
+   * answered, and whether the instance is there is already known once the
+   * connection was made. The ops carried over HTTP answer before any connection exists, which is
+   * what `carrier` says; `needs_hello` is false on them because there is no
+   * greeting to have sent, not because they are open on a settled one. */
   readonly needs_hello: boolean;
   /** The capability the op needs, when it needs one. */
   readonly capability?: Capability;
@@ -51,32 +58,50 @@ const INSTANCE_ONLY = ["instance"] as const;
  * facts live: authorization, capability gating and forwarding all read it
  * rather than each carrying their own copy. */
 export const OP_ATTRIBUTES = {
-  // --- common: connect, declare the end, and subscribe (13) ---
-  // `hello` and `instance_ping` address the instance the caller reached, so
+  // --- common: connect, declare the end, and subscribe (15) ---
+  // A greeting settles what the connection is, and there is one per role: what
+  // each must carry is then the op's own schema rather than a rule read off a
+  // field, and a connection cannot be settled as something neither side meant.
+  //
+  // The greetings and `instance.ping` address the instance the caller reached, so
   // there is nothing to forward and no unreachable instance to report — which
   // is why they are `cluster` despite answering about one instance.
-  hello: {
+  "hello.session": {
+    plane: "common",
+    roles: ALL_ROLES,
+    needs_hello: false,
+    locality: "cluster",
+    errors: [],
+  },
+  "hello.user": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
     locality: "cluster",
     errors: [],
   },
-  instance_ping: {
+  "hello.instance": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
     locality: "cluster",
     errors: [],
   },
-  instance_shutdown: {
+  "instance.ping": {
+    plane: "common",
+    roles: ALL_ROLES,
+    needs_hello: true,
+    locality: "cluster",
+    errors: [],
+  },
+  "instance.shutdown": {
     plane: "common",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "instance-local",
     errors: [],
   },
-  session_stopping: {
+  "session.stopping": {
     plane: "common",
     roles: SESSION_ONLY,
     needs_hello: true,
@@ -86,14 +111,14 @@ export const OP_ATTRIBUTES = {
   // Open to every role, with which role may have which topic left to the topic
   // table: an instance subscribes as itself to what only instances may hold,
   // and a person is refused there by that table rather than here.
-  topic_subscribe: {
+  "topic.subscribe": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: true,
     locality: "cluster",
     errors: ["topic_unknown"],
   },
-  topic_unsubscribe: {
+  "topic.unsubscribe": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: true,
@@ -102,12 +127,12 @@ export const OP_ATTRIBUTES = {
   },
 
   // The four ops that authenticate a person are open to every role for the
-  // same reason `hello` is: they run before there is an identity to check, and
-  // what they answer is what settles one. They are `cluster` because whichever
+  // same reason the greetings are: they run before there is an identity to
+  // check, and what they answer is what settles one. They are `cluster` because whichever
   // instance is reached answers — behind a load balancer that is not a choice
   // the caller makes — and each asks the issuing instance itself for the parts
   // only it holds.
-  auth_challenge: {
+  "auth.challenge": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
@@ -115,7 +140,7 @@ export const OP_ATTRIBUTES = {
     carrier: "http",
     errors: [],
   },
-  auth_register: {
+  "auth.register": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
@@ -123,7 +148,7 @@ export const OP_ATTRIBUTES = {
     carrier: "http",
     errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
   },
-  auth_assert: {
+  "auth.assert": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
@@ -131,7 +156,7 @@ export const OP_ATTRIBUTES = {
     carrier: "http",
     errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
   },
-  auth_refresh_token: {
+  "auth.token.refresh": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
@@ -140,8 +165,8 @@ export const OP_ATTRIBUTES = {
     errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
   },
   // Addresses the connection it arrives on, which is on the instance that
-  // received it: nothing to forward, as with `hello`.
-  auth_refresh: {
+  // received it: nothing to forward, as with a greeting.
+  "auth.extend": {
     plane: "common",
     roles: USER_ONLY,
     needs_hello: true,
@@ -151,14 +176,14 @@ export const OP_ATTRIBUTES = {
   // Between instances: what an issuer alone can answer. Instance-local by the
   // usual rule — the subject belongs to one instance, and it is reached by
   // `to_instance` being that instance's id.
-  auth_resolve: {
+  "auth.resolve": {
     plane: "common",
     roles: INSTANCE_ONLY,
     needs_hello: true,
     locality: "instance-local",
     errors: ["auth_invalid", "auth_expired"],
   },
-  auth_rotate: {
+  "auth.rotate": {
     plane: "common",
     roles: INSTANCE_ONLY,
     needs_hello: true,
@@ -167,28 +192,28 @@ export const OP_ATTRIBUTES = {
   },
 
   // --- messaging: one-to-one delivery (4) ---
-  message_send: {
+  "message.send": {
     plane: "messaging",
     roles: AGENT_AND_USER,
     needs_hello: true,
     locality: "cluster",
     errors: ["session_not_found"],
   },
-  say_post: {
+  "say.post": {
     plane: "messaging",
     roles: SESSION_ONLY,
     needs_hello: true,
     locality: "cluster",
     errors: ["rate_limited"],
   },
-  say_mark_read: {
+  "say.unread.clear": {
     plane: "messaging",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "cluster",
     errors: [],
   },
-  notify_send: {
+  "notify.send": {
     plane: "messaging",
     roles: AGENT_AND_USER,
     needs_hello: true,
@@ -197,14 +222,14 @@ export const OP_ATTRIBUTES = {
   },
 
   // --- control: session observation and operation (10) ---
-  session_kill: {
+  "session.kill": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "instance-local",
     errors: ["session_not_found"],
   },
-  session_rename: {
+  "session.rename": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
@@ -212,35 +237,35 @@ export const OP_ATTRIBUTES = {
     locality: "instance-local",
     errors: ["session_not_found"],
   },
-  session_env_read: {
+  "session.env.read": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "instance-local",
     errors: ["session_not_found"],
   },
-  session_search: {
+  "session.search": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "instance-local",
     errors: [],
   },
-  session_dump_write: {
+  "session.dump.write": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "instance-local",
     errors: ["not_found"],
   },
-  dump_presets_read: {
+  "dump.presets.read": {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
     locality: "instance-local",
     errors: [],
   },
-  transcript_read: {
+  "transcript.read": {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
@@ -248,7 +273,7 @@ export const OP_ATTRIBUTES = {
     scope: "role",
     errors: ["not_found"],
   },
-  transcript_items_read: {
+  "transcript.items.read": {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
@@ -256,7 +281,7 @@ export const OP_ATTRIBUTES = {
     scope: "role",
     errors: ["not_found"],
   },
-  session_fork_origin: {
+  "session.fork.origin.read": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
@@ -264,7 +289,7 @@ export const OP_ATTRIBUTES = {
     locality: "instance-local",
     errors: ["not_found"],
   },
-  session_last_live_remove: {
+  "session.forget": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
@@ -273,7 +298,7 @@ export const OP_ATTRIBUTES = {
   },
 
   // --- control: file access (9) ---
-  dir_list: {
+  "dir.list": {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
@@ -281,7 +306,7 @@ export const OP_ATTRIBUTES = {
     scope: "role",
     errors: ["path_forbidden", "not_found"],
   },
-  file_read: {
+  "file.read": {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
@@ -289,49 +314,49 @@ export const OP_ATTRIBUTES = {
     scope: "role",
     errors: ["path_forbidden", "not_found"],
   },
-  file_write: {
+  "file.write": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "instance-local",
     errors: ["path_not_writable", "file_exists"],
   },
-  file_create: {
+  "file.create": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "instance-local",
     errors: ["file_exists", "path_forbidden"],
   },
-  file_edit: {
+  "file.edit": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "instance-local",
     errors: ["file_conflict", "not_a_text_file"],
   },
-  file_delete: {
+  "file.delete": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "instance-local",
     errors: ["path_forbidden", "not_found"],
   },
-  file_find: {
+  "file.find": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "instance-local",
     errors: ["path_forbidden"],
   },
-  file_stat_batch: {
+  "file.stat": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "instance-local",
     errors: [],
   },
-  dir_tree: {
+  "dir.tree": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
@@ -341,7 +366,7 @@ export const OP_ATTRIBUTES = {
   },
 
   // --- control: launcher / sandbox / translate / llm (7) ---
-  launcher_config_read: {
+  "launcher.config.read": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
@@ -349,7 +374,7 @@ export const OP_ATTRIBUTES = {
     locality: "instance-local",
     errors: [],
   },
-  launcher_run: {
+  "launcher.run": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
@@ -357,7 +382,7 @@ export const OP_ATTRIBUTES = {
     locality: "instance-local",
     errors: [],
   },
-  sandbox_grant: {
+  "sandbox.grant": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
@@ -365,7 +390,7 @@ export const OP_ATTRIBUTES = {
     locality: "instance-local",
     errors: ["path_forbidden"],
   },
-  sandbox_revoke: {
+  "sandbox.revoke": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
@@ -373,7 +398,7 @@ export const OP_ATTRIBUTES = {
     locality: "instance-local",
     errors: [],
   },
-  translate_run: {
+  "translate.run": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
@@ -381,7 +406,7 @@ export const OP_ATTRIBUTES = {
     locality: "instance-local",
     errors: ["translate_helper_failed"],
   },
-  llm_usage_read: {
+  "llm.usage.read": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
@@ -389,7 +414,7 @@ export const OP_ATTRIBUTES = {
     locality: "instance-local",
     errors: [],
   },
-  llm_stats_read: {
+  "llm.stats.read": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
@@ -401,21 +426,21 @@ export const OP_ATTRIBUTES = {
   // --- control: the shared key-value store (3) ---
   // The only control ops that are not instance-local: a value is held by every
   // instance rather than by one, so whichever is asked can answer.
-  kv_read: {
+  "kv.read": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "cluster",
     errors: ["not_found"],
   },
-  kv_write: {
+  "kv.write": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "cluster",
     errors: [],
   },
-  kv_delete: {
+  "kv.delete": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,

package/src/common/auth.ts

@@ -45,7 +45,7 @@ export type AuthChallengeArgs = Static<typeof AuthChallengeArgs>;
  * The issuer travels beside the value rather than inside it because the
  * instance that receives the answer is not necessarily the one that issued it:
  * behind a load balancer either may be reached, so the receiver reads the
- * issuer, asks it to consume the challenge (`auth_resolve`), and verifies the
+ * issuer, asks it to consume the challenge (`auth.resolve`), and verifies the
  * assertion itself. An issuer a caller made up names an instance that knows no
  * such challenge, which is a refusal and not a way in. */
 export const AuthChallenge = Type.Object(
@@ -63,14 +63,14 @@ export type AuthChallenge = Static<typeof AuthChallenge>;
 export const AuthChallengeResult = AuthChallenge;
 export type AuthChallengeResult = Static<typeof AuthChallengeResult>;
 
-export const AuthChallengeRequest = request("auth_challenge", AuthChallengeArgs);
-export const AuthChallengeResponse = response("auth_challenge", AuthChallengeResult);
+export const AuthChallengeRequest = request("auth.challenge", AuthChallengeArgs);
+export const AuthChallengeResponse = response("auth.challenge", AuthChallengeResult);
 
 // --- registration ----------------------------------------------------------
 
 /** What the registration URL carries, as the instance that issued it reads it
  * back. On the wire between a browser and an instance the whole of it is one
- * opaque string; this shape is what `auth_resolve` answers with, so the two
+ * opaque string; this shape is what `auth.resolve` answers with, so the two
  * instances involved agree on what was authorized.
  *
  * Its integrity rests on a secret made for this one registration and held only
@@ -175,8 +175,8 @@ export type AuthSession = Static<typeof AuthSession>;
 export const AuthRegisterResult = AuthSession;
 export type AuthRegisterResult = Static<typeof AuthRegisterResult>;
 
-export const AuthRegisterRequest = request("auth_register", AuthRegisterArgs);
-export const AuthRegisterResponse = response("auth_register", AuthRegisterResult);
+export const AuthRegisterRequest = request("auth.register", AuthRegisterArgs);
+export const AuthRegisterResponse = response("auth.register", AuthRegisterResult);
 
 // --- assertion -------------------------------------------------------------
 
@@ -207,8 +207,8 @@ export type AuthAssertArgs = Static<typeof AuthAssertArgs>;
 export const AuthAssertResult = AuthSession;
 export type AuthAssertResult = Static<typeof AuthAssertResult>;
 
-export const AuthAssertRequest = request("auth_assert", AuthAssertArgs);
-export const AuthAssertResponse = response("auth_assert", AuthAssertResult);
+export const AuthAssertRequest = request("auth.assert", AuthAssertArgs);
+export const AuthAssertResponse = response("auth.assert", AuthAssertResult);
 
 // --- refreshing a token pair ----------------------------------------------
 
@@ -224,7 +224,7 @@ export type AuthRefreshReason = Static<typeof AuthRefreshReason>;
 /** The refresh token is not among the arguments: it is a cookie the carrier
  * already holds, and a caller that could state it is a caller that could read
  * it. What is left is why the caller is asking, which nothing is decided by. */
-export const AuthRefreshTokenArgs = Type.Object({
+export const AuthTokenRefreshArgs = Type.Object({
   /** What prompted this refresh, as the client knows it: the page was loaded
    * again, the access token was about to expire, or a dropped connection is
    * being remade. A hint kept on the family (`last_refresh`) for a person
@@ -234,31 +234,31 @@ export const AuthRefreshTokenArgs = Type.Object({
    * refresh as any. */
   reason: Type.Optional(AuthRefreshReason),
 });
-export type AuthRefreshTokenArgs = Static<typeof AuthRefreshTokenArgs>;
+export type AuthTokenRefreshArgs = Static<typeof AuthTokenRefreshArgs>;
 
-export const AuthRefreshTokenResult = AuthSession;
-export type AuthRefreshTokenResult = Static<typeof AuthRefreshTokenResult>;
+export const AuthTokenRefreshResult = AuthSession;
+export type AuthTokenRefreshResult = Static<typeof AuthTokenRefreshResult>;
 
-export const AuthRefreshTokenRequest = request("auth_refresh_token", AuthRefreshTokenArgs);
-export const AuthRefreshTokenResponse = response("auth_refresh_token", AuthRefreshTokenResult);
+export const AuthTokenRefreshRequest = request("auth.token.refresh", AuthTokenRefreshArgs);
+export const AuthTokenRefreshResponse = response("auth.token.refresh", AuthTokenRefreshResult);
 
 // --- extending a live connection ------------------------------------------
 
-/** Carries a token got from `auth_refresh_token`, on the connection whose life
+/** Carries a token got from `auth.token.refresh`, on the connection whose life
  * it extends. Apart from that op because they answer different questions: one
  * mints, this one moves a live connection's deadline, and a client that had to
  * reconnect to use a fresh token would blink every few hours for no reason. */
-export const AuthRefreshArgs = Type.Object({ access_token: Base64Url });
-export type AuthRefreshArgs = Static<typeof AuthRefreshArgs>;
+export const AuthExtendArgs = Type.Object({ access_token: Base64Url });
+export type AuthExtendArgs = Static<typeof AuthExtendArgs>;
 
-export const AuthRefreshResult = Type.Object({
-  /** The connection's new deadline, as `hello` first stated it. */
+export const AuthExtendResult = Type.Object({
+  /** The connection's new deadline, as the greeting first stated it. */
   auth_expires_at: Timestamp,
 });
-export type AuthRefreshResult = Static<typeof AuthRefreshResult>;
+export type AuthExtendResult = Static<typeof AuthExtendResult>;
 
-export const AuthRefreshRequest = request("auth_refresh", AuthRefreshArgs);
-export const AuthRefreshResponse = response("auth_refresh", AuthRefreshResult);
+export const AuthExtendRequest = request("auth.extend", AuthExtendArgs);
+export const AuthExtendResponse = response("auth.extend", AuthExtendResult);
 
 // --- between instances -----------------------------------------------------
 
@@ -297,8 +297,8 @@ export const AuthResolveResult = Type.Union(
 );
 export type AuthResolveResult = Static<typeof AuthResolveResult>;
 
-export const AuthResolveRequest = request("auth_resolve", AuthResolveArgs);
-export const AuthResolveResponse = response("auth_resolve", AuthResolveResult);
+export const AuthResolveRequest = request("auth.resolve", AuthResolveArgs);
+export const AuthResolveResponse = response("auth.resolve", AuthResolveResult);
 
 /** Rotates a token family at the one instance allowed to write it.
  *
@@ -332,8 +332,8 @@ export const AuthRotateResult = Type.Object({
 });
 export type AuthRotateResult = Static<typeof AuthRotateResult>;
 
-export const AuthRotateRequest = request("auth_rotate", AuthRotateArgs);
-export const AuthRotateResponse = response("auth_rotate", AuthRotateResult);
+export const AuthRotateRequest = request("auth.rotate", AuthRotateArgs);
+export const AuthRotateResponse = response("auth.rotate", AuthRotateResult);
 
 // --- the replicated records ------------------------------------------------
 
@@ -513,7 +513,7 @@ export const AuthRecord = Type.Object(
 );
 export type AuthRecord = Static<typeof AuthRecord>;
 
-/** The `auth_records` topic: how credentials and token families reach every
+/** The `auth.records` topic: how credentials and token families reach every
  * instance.
  *
  * Apart from the store because of who may read it. The store is the person's to
@@ -522,6 +522,6 @@ export type AuthRecord = Static<typeof AuthRecord>;
  * it would be a new way in. Only instances subscribe, and a relay carries the
  * frames as the instance it is rather than on a person's behalf. */
 export const AuthRecordsFrame = topicFrame(
-  "auth_records",
+  "auth.records",
   Type.Object({ records: Type.Array(AuthRecord) }),
 );