@ibgib/core-gib 0.1.57 → 0.1.59

package/src/sync/sync-peer/sync-peer-types.mts

@@ -3,12 +3,14 @@
  */
 
 import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
 
 import { SubjectWitness } from '../../common/pubsub/subject/subject-types.mjs';
 import { SyncSagaContextData_V1, SyncSagaContextIbGib_V1, SyncSagaContextRel8ns_V1 } from '../sync-saga-context/sync-saga-context-types.mjs';
 import { Witness_V1 } from '../../witness/witness-types.mjs';
 import { IbGibSpaceAny } from '../../witness/space/space-base-v1.mjs';
 import { MetaspaceService } from '../../witness/space/metaspace/metaspace-types.mjs';
+import { KeystoneIbGib_V1, KeystonePoolConfig } from '../../keystone/keystone-types.mjs';
 
 /**
  * Data for the SyncPeer witness.
@@ -36,13 +38,29 @@ export interface SyncPeerIbGib_V1 extends IbGib_V1<SyncPeerData_V1, SyncPeerRel8
  * opts used in `connect(opts)`
  */
 export interface ConnectSyncPeerOpts {
+    /**
+     * TODO: sagaId is now also on {@link InitializeSyncPeerOpts} since a peer
+     * is scoped to a single sync saga. Evaluate whether this duplicate is still
+     * needed when implementing the connect phase (Phase 2).
+     */
     sagaId: string;
 }
 
 /**
- * base initialization opts
+ * base initialization opts.
+ *
+ * A sync peer is scoped to exactly one sync saga. A new peer instance must be
+ * created for each `sync(...)` call. Reusing a peer across multiple sagas is
+ * not supported and would compromise the identity security model.
  */
 export interface InitializeSyncPeerOpts {
+    /**
+     * Unique id for the sync saga this peer is servicing.
+     * Generated by `SyncSagaCoordinator.sync()` and passed here so that
+     * `establishSessionIdentity` can derive the session secret via
+     * `KDF(senderSecret, sagaId)`.
+     */
+    sagaId?: string;
     /**
      * reference to the local metaspace
      */
@@ -62,6 +80,44 @@ export interface InitializeSyncPeerOpts {
      * received/created throughout the transaction until commit.
      */
     localTempSpace?: IbGibSpaceAny;
+    /**
+     * The sender's long-lived Domain Keystone (I) — Alice's identity.
+     * Optional; if omitted the sync runs without identity (anonymous).
+     * Must be the current tip frame of I's timeline.
+     *
+     * Both {@link senderIdentity} and {@link fnSenderSecret} must be provided
+     * together or omitted together.
+     */
+    senderIdentity?: KeystoneIbGib_V1;
+    /**
+     * Returns the plaintext secret corresponding to {@link senderIdentity}.
+     * Wrapped in a function to avoid holding the secret in memory longer than needed.
+     *
+     * Both {@link senderIdentity} and {@link fnSenderSecret} must be provided
+     * together or omitted together.
+     */
+    fnSenderSecret?: () => Promise<string>;
+    /**
+     * Pool config for the session keystone's transport connect handshake pool.
+     * Required when {@link senderIdentity} is provided.
+     *
+     * @see {@link POOL_ID_CONNECT}
+     */
+    sessionConnectPoolConfig?: KeystonePoolConfig;
+    /**
+     * Pool config for the session keystone's per-turn signing pool (`sync`).
+     * Required when {@link senderIdentity} is provided.
+     *
+     * @see {@link POOL_ID_SYNC}
+     */
+    sessionSyncPoolConfig?: KeystonePoolConfig;
+    /**
+     * Addresses of the synced domains (ibgibs).
+     * Used during `establishSessionIdentity` to bind the session keystone (S)
+     * strictly to these domains, preventing S from acting as a "blank check"
+     * for unauthorized domains.
+     */
+    targetAddrs?: string[];
 }
 
 /**
@@ -107,6 +163,26 @@ export interface SyncPeerWitness<TInitializeOpts extends InitializeSyncPeerOpts
      */
     payloadIbGibsDomainReceived$: SubjectWitness<IbGib_V1>;
 
+    currentSessionIdentity: KeystoneIbGib_V1 | undefined;
+    /**
+     * convenience getter for {@link currentSessionIdentity}
+     */
+    get currentSessionIdentityAddr(): IbGibAddr | undefined;
+
+    /**
+     * Pre-connect phase: creates the session keystone (S) locally, evolves
+     * `senderIdentity` (I → I1) with a `sync` claim targeting S, and posts
+     * both to the receiver's domain registry.
+     *
+     * Must be called before `connect()`. No-op if `senderIdentity` was not
+     * provided in {@link InitializeSyncPeerOpts}.
+     *
+     * @returns The session keystone genesis (S^Stjp). The coordinator holds
+     * this reference for the remainder of the saga. The name `newSenderIdentity`
+     * (I1) is intentionally scoped only within this method to avoid confusion.
+     */
+    establishSessionIdentity(): Promise<void>;
+
     /**
      * Establishes the connection context.
      *
@@ -115,4 +191,14 @@ export interface SyncPeerWitness<TInitializeOpts extends InitializeSyncPeerOpts
      * @param opts Connection options, including the sagaId for the upcoming sync saga.
      */
     connect(opts?: { sagaId?: string }): Promise<void>;
+
+    // /**
+    //  * Returns the sender's long-lived primary/domain identity.
+    //  */
+    // getSenderIdentity(): KeystoneIbGib_V1 | undefined;
+
+    /**
+     * Evolves the session identity (S_n -> S_n+1) and signs targeting contextAddr.
+     */
+    signContext(opts: { contextAddr: IbGibAddr }): Promise<KeystoneIbGib_V1 | undefined>;
 }

package/src/sync/sync-peer/sync-peer-v1.mts

@@ -7,11 +7,8 @@
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
-import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
-import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
 
 import { GLOBAL_LOG_A_LOT } from '../../core-constants.mjs';
-import { SYNC_MSG_REL8N_NAME, SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN } from '../sync-constants.mjs';
 import { SubjectWitness } from '../../common/pubsub/subject/subject-types.mjs';
 import { SyncSagaContextIbGib_V1 } from '../sync-saga-context/sync-saga-context-types.mjs';
 import {
@@ -19,16 +16,18 @@ import {
     SyncPeerRel8ns_V1, SyncPeerWitness
 } from './sync-peer-types.mjs';
 import { LightWitnessBase_V1 } from '../../witness/light-witness-base-v1.mjs';
-import { IbGibSpaceAny } from '../../witness/space/space-base-v1.mjs';
 import { newupSubject } from '../../common/pubsub/subject/subject-helper.mjs';
-import { authenticateContext, authorizeContext, validateContextAndSagaFrame } from '../sync-saga-context/sync-saga-context-helpers.mjs';
+import { authenticateContextIntrinsically, validateContextAndSagaFrame } from '../sync-saga-context/sync-saga-context-helpers.mjs';
 import { getFromSpace } from '../../witness/space/space-helper.mjs';
-import { getFullSyncSagaHistory } from '../sync-helpers.mjs';
-import { SyncSagaFrameDependencyGraph } from '../sync-types.mjs';
+import { getFullSyncSagaHistory, deriveSessionSecret } from '../sync-helpers.mjs';
+import { SessionGenesisFrameDetails, SyncSagaFrameDependencyGraph } from '../sync-types.mjs';
+import { KeystoneService_V1 } from '../../keystone/keystone-service-v1.mjs';
+import { KeystoneIbGib_V1 } from '../../keystone/keystone-types.mjs';
+import { KEYSTONE_VERB_SYNC, } from '../../keystone/keystone-constants.mjs';
+import { getTjpAddr } from '../../common/other/ibgib-helper.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
-const logalotControlDomain = false;
-const lcControlDomain = '[ControlDomain]';
 
 
 /**
@@ -51,6 +50,54 @@ export abstract class SyncPeer_V1<
 
     public opts: TInitializeOpts | undefined;
     public payloadIbGibsDomainReceived$!: SubjectWitness<IbGib_V1>;
+    public currentSessionIdentity: KeystoneIbGib_V1 | undefined;
+    public get currentSessionIdentityAddr(): IbGibAddr | undefined {
+        return this.currentSessionIdentity ?
+            getIbGibAddr({ ibGib: this.currentSessionIdentity }) :
+            undefined;
+    }
+
+    // public getSenderIdentity(): KeystoneIbGib_V1 | undefined {
+    //     return this.opts?.senderIdentity;
+    // }
+
+    public async signContext({
+        contextAddr,
+    }: {
+        contextAddr: IbGibAddr;
+    }): Promise<KeystoneIbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.signContext.name}]`;
+        try {
+            if (!this.currentSessionIdentity) {
+                return undefined;
+            }
+            if (!this.opts) { throw new Error(`opts not initialized. (E: bcf5978aed789b0ebcbdc51971ebe826)`); }
+            const { fnSenderSecret, sagaId, localMetaspace, localSpace } = this.opts;
+            if (!fnSenderSecret) { throw new Error(`fnSenderSecret not initialized. (E: 207fd292a2e8c53c05fd0a74a4ae6d26)`); }
+            if (!sagaId) { throw new Error(`sagaId not initialized. (E: f2e35cc13ed873b638116188119d1826)`); }
+
+            const senderSecret = await fnSenderSecret();
+            const sessionSecret = await deriveSessionSecret({ senderSecret, sagaId });
+
+            const keystoneSvc = new KeystoneService_V1();
+            const evolved = await keystoneSvc.sign({
+                latestKeystone: this.currentSessionIdentity,
+                masterSecret: sessionSecret,
+                claim: {
+                    verb: KEYSTONE_VERB_SYNC,
+                    target: contextAddr,
+                },
+                metaspace: localMetaspace,
+                space: localSpace,
+            });
+
+            this.currentSessionIdentity = evolved;
+            return evolved;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
 
     get classname(): string {
         if (!this.data) { throw new Error(`(UNEXPECTED) this.data falsy? (E: 1ab1841e9338b54f3aa615fa37024826)`); }
@@ -107,6 +154,108 @@ export abstract class SyncPeer_V1<
      */
     protected abstract connectImpl(opts: TConnectOpts): Promise<void>;
 
+    /**
+     * Pre-connect phase: establishes session identity.
+     *
+     * Shared base implementation:
+     * 1. Derives `sessionSecret = KDF(senderSecret, sagaId)`.
+     * 2. Creates session keystone genesis S (connect + sync pools) in `localSpace`.
+     * 3. Evolves `senderIdentity` → `newSenderIdentity` (I1) with a `sync`
+     *    claim targeting S^Stjp, stored in `localSpace`.
+     * 4. Delegates posting of both keystones to the receiver via the abstract
+     *    hook {@link postEstablishToReceiver} (peer-specific transport).
+     *
+     * Returns `undefined` (no-op) if no `senderIdentity` was provided in opts.
+     *
+     * @returns The session keystone genesis (S^Stjp) so the coordinator can
+     * hold a reference for subsequent per-turn signing. The name
+     * `newSenderIdentity` (I1) is scoped only within this method.
+     */
+    public async establishSessionIdentity(): Promise<void> {
+        const lc = `${this.lc}[${this.establishSessionIdentity.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: f2a1b3c4d5e6f7a8b9c0d1e2f3a4b526)`); }
+
+            if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? Call initializeOpts first. (E: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c526)`); }
+
+            const { senderIdentity, fnSenderSecret, sagaId, localMetaspace, localSpace } = this.opts;
+
+            // No identity provided — anonymous sync, nothing to establish.
+            if (!senderIdentity || !fnSenderSecret) {
+                if (logalot) { console.log(`${lc} no senderIdentity/fnSenderSecret — skipping establish (I: f29348a77d1542326d14043ea4b69126)`); }
+                return undefined;
+            }
+            const senderIdentityAddr = getIbGibAddr({ ibGib: senderIdentity });
+            const senderIdentityTjpAddr = getTjpAddr({ ibGib: senderIdentity });
+            if (!senderIdentityTjpAddr) { throw new Error(`(UNEXPECTED) senderIdentityTjpAddr falsy? (E: d5d8c3ab25a83a2c127904fe96de1526)`); }
+
+            if (!sagaId) { throw new Error(`(UNEXPECTED) sagaId falsy? Must be set in initializeOpts before calling establishSessionIdentity. (E: c6ba389d51b8af07d82458f875cf9826)`); }
+
+            const senderSecret = await fnSenderSecret();
+            if (!senderSecret) { throw new Error(`senderSecret falsy. senderSecret required. (E: 1a8b0298bf78cbdf284b7988983b9826)`); }
+            const sessionSecret = await deriveSessionSecret({ senderSecret, sagaId });
+
+            const keystoneSvc = new KeystoneService_V1();
+
+            // Step 1: Create S genesis in localSpace.
+            // Pool configs must be provided via opts (set by coordinator before calling establish).
+            if (!this.opts.sessionConnectPoolConfig) { throw new Error(`(UNEXPECTED) opts.sessionConnectPoolConfig falsy? (E: 3351fd566eb8bbd2f821bb08c4419826)`); }
+            if (!this.opts.sessionSyncPoolConfig) { throw new Error(`(UNEXPECTED) opts.sessionSyncPoolConfig falsy? (E: dbffa810d9e7ff6079088deb5b8e7826)`); }
+
+            // session genesis keystone should have soft links to both
+            // targetAddrs and the sender identity that spawned it.
+            const frameDetails: SessionGenesisFrameDetails = {
+                senderIdentityAddr,
+                senderIdentityTjpAddr,
+            }
+            if (this.opts.targetAddrs) {
+                frameDetails.targetAddrs = this.opts.targetAddrs
+            }
+            const sessionIdentity = await keystoneSvc.genesis({
+                masterSecret: sessionSecret,
+                configs: [this.opts.sessionConnectPoolConfig, this.opts.sessionSyncPoolConfig],
+                frameDetails,
+                metaspace: localMetaspace,
+                space: localSpace,
+            });
+            const sessionIdentityAddr = getIbGibAddr({ ibGib: sessionIdentity });
+
+            // Step 2: Evolve senderIdentity → newSenderIdentity (I1) with sync claim.
+            const newSenderIdentity = await keystoneSvc.sign({
+                latestKeystone: senderIdentity,
+                masterSecret: senderSecret,
+                claim: {
+                    verb: KEYSTONE_VERB_SYNC,
+                    target: sessionIdentityAddr,
+                },
+                metaspace: localMetaspace,
+                space: localSpace,
+            });
+
+            // Step 3: Post both to the receiver (peer-specific).
+            await this.postEstablishToReceiver({ newSenderIdentity, sessionIdentity });
+
+            this.currentSessionIdentity = sessionIdentity;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Peer-specific hook: transmits `newSenderIdentity` (I1) and
+     * `sessionIdentity` (S) to the receiver's domain registry.
+     *
+     * - **Innerspace**: puts both into `receiverMetaspace` / `receiverSpace`.
+     * - **WebSocket**: HTTP POST to the domain provider's keystone endpoint.
+     */
+    protected abstract postEstablishToReceiver(opts: {
+        newSenderIdentity: KeystoneIbGib_V1;
+        sessionIdentity: KeystoneIbGib_V1;
+    }): Promise<void>;
+
     /**
      * base implementation just sets the opts property.
      *
@@ -164,16 +313,12 @@ export abstract class SyncPeer_V1<
     //     }
     // }
 
-
-
-    protected async authenticateValidateAuthorize({
+    protected async authenticateAndValidate({
         context,
-        fullSagaHistory,
     }: {
         context: SyncSagaContextIbGib_V1,
-        fullSagaHistory: SyncSagaFrameDependencyGraph[],
     }): Promise<void> {
-        const lc = `${this.lc}[${this.authenticateValidateAuthorize.name}]`;
+        const lc = `${this.lc}[${this.authenticateAndValidate.name}]`;
         try {
             if (logalot) { console.log(`${lc} starting... (I: add238055cd84a222c5b8c89913af526)`); }
 
@@ -181,7 +326,8 @@ export abstract class SyncPeer_V1<
             const { localSpace } = this.opts;
 
             // first authenticate, because invalid authn is a non-starter
-            const authenticationErrors = await authenticateContext({
+            // (already validated intrinsically)
+            const authenticationErrors = await authenticateContextIntrinsically({
                 context,
                 space: localSpace,
             });
@@ -195,12 +341,6 @@ export abstract class SyncPeer_V1<
             if (validationErrors.length > 0) {
                 throw new Error(`invalid context received. validationErrors: ${validationErrors} (E: 8b34c875c968af29bc433138e57a7826)`);
             }
-            // we have a valid authentication that points to a valid context,
-            // but what exactly is authorized ?
-            const authorizationErrors = await authorizeContext({ context, fullSagaHistory });
-            if (authorizationErrors.length > 0) {
-                throw new Error(`invalid context authorization. authorizationErrors: ${authorizationErrors} (E: 8ddc284a758cf10ba829334c1babb826)`);
-            }
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
             throw error;
@@ -268,14 +408,12 @@ export abstract class SyncPeer_V1<
             // this is not just happening on the client, but this peer may be
             // the one receiving the context as well.
 
-            const sagaHistory_beforeSend = await getFullSyncSagaHistory({
-                sagaIbGib: context.sagaFrame,
-                space: this.opts.localSpace
-            });
+            // const sagaHistory_beforeSend = await getFullSyncSagaHistory({
+            //     sagaIbGib: context.sagaFrame,
+            //     space: this.opts.localSpace
+            // });
 
-            await this.authenticateValidateAuthorize({
-                context, fullSagaHistory: sagaHistory_beforeSend,
-            });
+            await this.authenticateAndValidate({ context });
 
             // at this point, we have a valid, authenticated, authorized context
 
@@ -296,9 +434,10 @@ export abstract class SyncPeer_V1<
                     space: this.opts.localSpace
                 });
 
-                await this.authenticateValidateAuthorize({
-                    context, fullSagaHistory: sagaHistory_afterSend,
-                });
+                // NOTE: I think this is the wrong place for this, as we must do this in the peer **before** storing any control ibgibs. This needs to be done in the continueSync I _think_ (not sure yet)
+                // await this.authenticateValidateAuthorize({
+                //     context, fullSagaHistory: sagaHistory_afterSend,
+                // });
 
                 return response;
             } else {

package/src/sync/sync-peer/sync-peer-websocket/sync-peer-websocket-constants.mts

@@ -0,0 +1,68 @@
+// #region SyncWebSocketMsgType enum
+
+export const SYNC_WEB_SOCKET_MSG_TYPE_AUTH_CHALLENGE_INIT = 'auth-challenge-init';
+export const SYNC_WEB_SOCKET_MSG_TYPE_AUTH_INIT = 'auth-init';
+export const SYNC_WEB_SOCKET_MSG_TYPE_AUTH_CHALLENGE = 'auth-challenge';
+export const SYNC_WEB_SOCKET_MSG_TYPE_AUTH_PROOF = 'auth-proof';
+export const SYNC_WEB_SOCKET_MSG_TYPE_AUTH_OK = 'auth-ok';
+export const SYNC_WEB_SOCKET_MSG_TYPE_AUTH_FAIL = 'auth-fail';
+export const SYNC_WEB_SOCKET_MSG_TYPE_SYNC_FRAME = 'sync-frame';
+export const SYNC_WEB_SOCKET_MSG_TYPE_SYNC_FRAME_RESPONSE = 'sync-frame-response';
+export const SYNC_WEB_SOCKET_MSG_TYPE_SYNC_FRAME_AUTHENTICATED = 'sync-frame-authenticated';
+export const SYNC_WEB_SOCKET_MSG_TYPE_SYNC_FRAME_RESPONSE_AUTHENTICATED = 'sync-frame-response-authenticated';
+export const SYNC_WEB_SOCKET_MSG_TYPE_DOMAIN_PAYLOAD = 'domain-payload';
+export const SYNC_WEB_SOCKET_MSG_TYPE_SYNC_ERROR = 'sync-error';
+
+/**
+ * Message types transmitted over the stateful WebSocket connection
+ * during a sync saga session handshake and execution.
+ */
+export type SyncWebSocketMsgType =
+    | typeof SYNC_WEB_SOCKET_MSG_TYPE_AUTH_CHALLENGE_INIT
+    | typeof SYNC_WEB_SOCKET_MSG_TYPE_AUTH_INIT
+    | typeof SYNC_WEB_SOCKET_MSG_TYPE_AUTH_CHALLENGE
+    | typeof SYNC_WEB_SOCKET_MSG_TYPE_AUTH_PROOF
+    | typeof SYNC_WEB_SOCKET_MSG_TYPE_AUTH_OK
+    | typeof SYNC_WEB_SOCKET_MSG_TYPE_AUTH_FAIL
+    | typeof SYNC_WEB_SOCKET_MSG_TYPE_SYNC_FRAME
+    | typeof SYNC_WEB_SOCKET_MSG_TYPE_SYNC_FRAME_RESPONSE
+    | typeof SYNC_WEB_SOCKET_MSG_TYPE_SYNC_FRAME_AUTHENTICATED
+    | typeof SYNC_WEB_SOCKET_MSG_TYPE_SYNC_FRAME_RESPONSE_AUTHENTICATED
+    | typeof SYNC_WEB_SOCKET_MSG_TYPE_DOMAIN_PAYLOAD
+    | typeof SYNC_WEB_SOCKET_MSG_TYPE_SYNC_ERROR
+    ;
+
+export const SyncWebSocketMsgType = {
+    /** Sent by server/receiver to trigger connection authentication. */
+    auth_challenge_init: SYNC_WEB_SOCKET_MSG_TYPE_AUTH_CHALLENGE_INIT,
+    /** Sent by client/sender to start the authentication handshake with the target session address. */
+    auth_init: SYNC_WEB_SOCKET_MSG_TYPE_AUTH_INIT,
+    /** Sent by server/receiver with dynamic connect challenges to be solved. */
+    auth_challenge: SYNC_WEB_SOCKET_MSG_TYPE_AUTH_CHALLENGE,
+    /** Sent by client/sender with proof of session keystone evolution solving challenges. */
+    auth_proof: SYNC_WEB_SOCKET_MSG_TYPE_AUTH_PROOF,
+    /** Sent by server/receiver signaling successful challenge resolution and upgrade to active sync. */
+    auth_ok: SYNC_WEB_SOCKET_MSG_TYPE_AUTH_OK,
+    /** Sent when authentication fails. */
+    auth_fail: SYNC_WEB_SOCKET_MSG_TYPE_AUTH_FAIL,
+    /** Sent by client/sender to transmit the next sync transaction context without payload ibgibs. */
+    sync_frame: SYNC_WEB_SOCKET_MSG_TYPE_SYNC_FRAME,
+    /** Sent by server/receiver responding with the next sync transaction context. */
+    sync_frame_response: SYNC_WEB_SOCKET_MSG_TYPE_SYNC_FRAME_RESPONSE,
+    /** Sent by server/receiver after context is validated/authenticated to signal payload transmission. */
+    sync_frame_authenticated: SYNC_WEB_SOCKET_MSG_TYPE_SYNC_FRAME_AUTHENTICATED,
+    /** Sent by client/sender after response context is validated/authenticated to signal payload transmission. */
+    sync_frame_response_authenticated: SYNC_WEB_SOCKET_MSG_TYPE_SYNC_FRAME_RESPONSE_AUTHENTICATED,
+    /** Sent to stream a single domain payload ibgib. */
+    domain_payload: SYNC_WEB_SOCKET_MSG_TYPE_DOMAIN_PAYLOAD,
+    /** Sent when a sync runtime execution error occurs. */
+    sync_error: SYNC_WEB_SOCKET_MSG_TYPE_SYNC_ERROR,
+} satisfies { readonly [key: string]: SyncWebSocketMsgType };
+
+export const SYNC_WEB_SOCKET_MSG_TYPE_VALID_VALUES: SyncWebSocketMsgType[] = Object.values(SyncWebSocketMsgType);
+
+export function isSyncWebSocketMsgType(value: any): value is SyncWebSocketMsgType {
+    return SYNC_WEB_SOCKET_MSG_TYPE_VALID_VALUES.includes(value);
+}
+
+// #endregion SyncWebSocketMsgType enum

package/src/sync/sync-peer/sync-peer-websocket/sync-peer-websocket-receiver/sync-peer-websocket-receiver-types.mts

@@ -0,0 +1,36 @@
+/**
+ * @module sync-peer-websocket-receiver-types
+ */
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import {
+    SyncPeerData_V1, SyncPeerRel8ns_V1, SyncPeerWitness,
+    InitializeSyncPeerOpts, ConnectSyncPeerOpts
+} from '../../sync-peer-types.mjs';
+import { SyncSagaCoordinator } from '../../../sync-saga-coordinator.mjs';
+
+/**
+ * Data for the SyncPeerWebSocketReceiver witness.
+ */
+export interface SyncPeerWebSocketReceiverData_V1 extends SyncPeerData_V1 {
+}
+
+/**
+ * Relations for the SyncPeerWebSocketReceiver witness.
+ */
+export interface SyncPeerWebSocketReceiverRel8ns_V1 extends SyncPeerRel8ns_V1 {
+}
+
+/**
+ * The SyncPeerWebSocketReceiver witness IbGib.
+ */
+export interface SyncPeerWebSocketReceiverIbGib_V1 extends IbGib_V1<SyncPeerWebSocketReceiverData_V1, SyncPeerWebSocketReceiverRel8ns_V1> { }
+
+export interface ConnectSyncPeerWebSocketReceiverOpts extends ConnectSyncPeerOpts {
+}
+
+export interface InitializeSyncPeerWebSocketReceiverOpts extends InitializeSyncPeerOpts {
+    /**
+     * The local SyncSagaCoordinator instance running on the receiver/server.
+     */
+    localCoordinator: SyncSagaCoordinator;
+}