@ibgib/core-gib 0.1.54 → 0.1.55

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

@@ -3,12 +3,12 @@
  */
 
 import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
-import { SubjectWitness } from '../../common/pubsub/subject/subject-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 { KeystoneService_V1 } from '../../keystone/keystone-service-v1.mjs';
+import { MetaspaceService } from '../../witness/space/metaspace/metaspace-types.mjs';
 
 /**
  * Data for the SyncPeer witness.
@@ -31,10 +31,22 @@ export interface SyncPeerRel8ns_V1 extends IbGibRel8ns_V1 {
  */
 export interface SyncPeerIbGib_V1 extends IbGib_V1<SyncPeerData_V1, SyncPeerRel8ns_V1> { }
 
+
+/**
+ * opts used in `connect(opts)`
+ */
+export interface ConnectSyncPeerOpts {
+    sagaId: string;
+}
+
 /**
  * base initialization opts
  */
 export interface InitializeSyncPeerOpts {
+    /**
+     * reference to the local metaspace
+     */
+    localMetaspace: MetaspaceService;
     /**
      * local durable space.
      *
@@ -50,10 +62,6 @@ export interface InitializeSyncPeerOpts {
      * received/created throughout the transaction until commit.
      */
     localTempSpace?: IbGibSpaceAny;
-    /**
-     * Shared keystone service for signing and validation.
-     */
-    keystoneSvc?: KeystoneService_V1;
 }
 
 /**
@@ -98,4 +106,13 @@ export interface SyncPeerWitness<TInitializeOpts extends InitializeSyncPeerOpts
      * The handling code (e.g. SyncSagaCoordinator) will subscribe to this.
      */
     payloadIbGibsDomainReceived$: SubjectWitness<IbGib_V1>;
+
+    /**
+     * Establishes the connection context.
+     *
+     * This handles concrete communication substrate (e.g., WebSocket upgrade)
+     *
+     * @param opts Connection options, including the sagaId for the upcoming sync saga.
+     */
+    connect(opts?: { sagaId?: string }): Promise<void>;
 }

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

@@ -14,7 +14,10 @@ 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 { InitializeSyncPeerOpts, SyncPeerData_V1, SyncPeerRel8ns_V1, SyncPeerWitness } from './sync-peer-types.mjs';
+import {
+    ConnectSyncPeerOpts, InitializeSyncPeerOpts, SyncPeerData_V1,
+    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';
@@ -33,13 +36,15 @@ const lcControlDomain = '[ControlDomain]';
  *
  * Takes a SyncSagaContext (Request) and returns a SyncSagaContext (Response).
  *
- * Implements the core "Sync Protocol Transport" logic:
+ * Implements the core "Sync Protocol Transport" logic. Once connected, does:
  * 1. Push Context & Dependencies (Sender -> Receiver)
  * 2. Send Request (RPC)
  * 3. Pull Response & Dependencies (Receiver -> Sender)
  */
-export abstract class SyncPeer_V1<TInitializeOpts extends InitializeSyncPeerOpts = InitializeSyncPeerOpts>
-    extends LightWitnessBase_V1<SyncPeerData_V1, SyncPeerRel8ns_V1>
+export abstract class SyncPeer_V1<
+    TConnectOpts extends ConnectSyncPeerOpts = ConnectSyncPeerOpts,
+    TInitializeOpts extends InitializeSyncPeerOpts = InitializeSyncPeerOpts
+> extends LightWitnessBase_V1<SyncPeerData_V1, SyncPeerRel8ns_V1>
     implements SyncPeerWitness<TInitializeOpts> {
 
     protected lc: string = `[${SyncPeer_V1.name}]`;
@@ -61,6 +66,47 @@ export abstract class SyncPeer_V1<TInitializeOpts extends InitializeSyncPeerOpts
         this.payloadIbGibsDomainReceived$ = await newupSubject<IbGib_V1>();
     }
 
+    /**
+     * Establishes the connection context.
+     *
+     * This method provides boilerplate error handling and logging,
+     * delegating the actual connection logic to `connectImpl`.
+     */
+    public async connect(opts: TConnectOpts): Promise<void> {
+        const lc = `${this.lc}[${this.connect.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: ad89d8137351662fb8a30114a1fa4826)`); }
+
+            await this.preConnectCheck(opts);
+            await this.connectImpl(opts);
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Concrete pre-connect check. Should throw if connect conditions are not
+     * met.
+     *
+     * Use this to check what {@link opts} are, as well as any other state per
+     * concrete sync peer.
+     *
+     * @see {@link connect}
+     * @see {@link connectImpl}
+     */
+    protected abstract preConnectCheck(opts: TConnectOpts): Promise<void>;
+
+    /**
+     * Concrete implementation for establishing the connection context.
+     *
+     * This MUST be implemented by subclasses to handle transport-specific
+     * negotiation (e.g., WebSocket upgrade)
+     */
+    protected abstract connectImpl(opts: TConnectOpts): Promise<void>;
+
     /**
      * base implementation just sets the opts property.
      *
@@ -132,30 +178,25 @@ export abstract class SyncPeer_V1<TInitializeOpts extends InitializeSyncPeerOpts
             if (logalot) { console.log(`${lc} starting... (I: add238055cd84a222c5b8c89913af526)`); }
 
             if (!this.opts) { throw new Error(`(UNEXPECTED) opts falsy in authenticateValidateAuthorize (E: b7e5a8ad99d84e1ba8d8f7facd288826)`); }
-            const { keystoneSvc, localSpace } = this.opts;
-
-            if (keystoneSvc) {
-                // first authenticate, because invalid identity is a non-starter
-                const authenticationErrors = await authenticateContext({ 
-                    context, 
-                    space: localSpace, 
-                    keystoneSvc 
-                });
-                if (authenticationErrors.length > 0) {
-                    throw new Error(`invalid context authentication. authenticationErrors: ${authenticationErrors} (E: da89da5ee1269aeb78952d475d607526)`);
-                }
-            } else {
-                if (logalot) { console.warn(`${lc} No keystoneSvc provided. Skipping context authentication. (W: d34b8ad92d84a1ba8d8f7facd288826)`); }
+            const { localSpace } = this.opts;
+
+            // first authenticate, because invalid authn is a non-starter
+            const authenticationErrors = await authenticateContext({
+                context,
+                space: localSpace,
+            });
+            if (authenticationErrors.length > 0) {
+                throw new Error(`invalid context authentication. authenticationErrors: ${authenticationErrors} (E: da89da5ee1269aeb78952d475d607526)`);
             }
-            // next, we have a valid keystone, which should point to the
+            // next, we have a valid authn, which should point to the
             // context. But is that context and the saga data it contains valid?
-            // Does the keystone actually point to this context?
+            // Does the authentication actually point to this context?
             const validationErrors = await validateContextAndSagaFrame({ context, });
             if (validationErrors.length > 0) {
                 throw new Error(`invalid context received. validationErrors: ${validationErrors} (E: 8b34c875c968af29bc433138e57a7826)`);
             }
-            // we have a valid keystone that points to a valid context, but what
-            // exactly does the keystone authorize?
+            // 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)`);
@@ -206,7 +247,7 @@ export abstract class SyncPeer_V1<TInitializeOpts extends InitializeSyncPeerOpts
             //       issues
             // The following is a sketch where some of these may be blurred
 
-            // persist the context, sagaframe, identity(s) ONLY in the receiver's durable space
+            // persist the context, sagaframe, authentication details ONLY in the receiver's durable space
             // if sending domain ibgibs...
             //   verify the domain ibgibs intrinsically.
             //   persist the domain ibgibs in the receiver's temp space (push all addrs?)
@@ -214,8 +255,7 @@ export abstract class SyncPeer_V1<TInitializeOpts extends InitializeSyncPeerOpts
             // process the context with the receiver's coordinator to get a new response context
             // analyze the response context
             //   validate context intrinsically
-            //   validate return identity if present
-            // persist the response context's dependency graph (context, saga frame and msg(s), identities)
+            // persist the response context's dependency graph (context, saga frame and msg(s))
             // if response has payload domain ibgibs,
             //   spin off...
             //     pull domain ibgibs to local temp space
@@ -246,7 +286,7 @@ export abstract class SyncPeer_V1<TInitializeOpts extends InitializeSyncPeerOpts
             if (response) {
                 // at this point, all outgoing payload domain ibgibs have been sent.
                 // we have received the response context, wherein the sync saga
-                // frame/msg stone(s) and any keystones should be evolved. Depending
+                // frame/msg stone(s) should be evolved. Depending
                 // on the concrete implementation, if there are domain ibgibs to
                 // receive, they may still be transferring. These will be published
                 // to this.payloadIbGibsDomainReceived$
@@ -282,11 +322,11 @@ export abstract class SyncPeer_V1<TInitializeOpts extends InitializeSyncPeerOpts
      * This is responsible for:
      *
      * * physical sending outgoing {@link context}, the sync saga frame and msg
-     *   stone(s), and identities...
+     *   stone(s)...
      * * AND sending OUTGOING domain ibgibs
      *   {@link SyncSagaContextIbGib_V1.payloadIbGibsDomain}
      * * getting back the other end's resultant context ibgib, sync saga frame
-     *   and msg stone(s), and identities in their entirety...
+     *   and msg stone(s) in their entirety...
      * * AND stream/receiving the RESPONSE payload domain ibgibs, publishing
      *   these to this.payloadIbGibsDomainReceived$.
      *   * BUT this should return as soon as the resultant context ibgib comes

package/src/sync/sync-saga-context/sync-saga-context-helpers.mts

@@ -20,9 +20,6 @@ import { IbGibSpaceAny } from '../../witness/space/space-base-v1.mjs';
 import { getFromSpace, putInSpace, registerNewIbGib } from '../../witness/space/space-helper.mjs';
 import { SyncIbGib_V1, SyncSagaFrameDependencyGraph } from '../sync-types.mjs';
 import { validateSyncSagaFrame } from '../sync-helpers.mjs';
-import { validateKeystoneGraph, validateKeystoneTransition } from '../../keystone/keystone-helpers.mjs';
-import { KeystoneService_V1 } from '../../keystone/keystone-service-v1.mjs';
-import { KeystoneIbGib_V1 } from '../../keystone/keystone-types.mjs';
 import { isIbGibWithAtom } from '../../common/other/ibgib-helper.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
@@ -115,13 +112,12 @@ export function isSyncSagaContextIbGib(x: any): x is SyncSagaContextIbGib_V1 {
     }
 }
 
-
 /**
  * Validates ONLY the {@link context} ibgib itself and saga frame/msg stone(s)
  * ({@link SyncSagaContextIbGib_V1.sagaFrame}).
  *
  * Does NOT...
- * * validate keystones (authn or authz)
+ * * validate authn or authz
  * * validate domain payload ibgibs...
  *   * intrinsically
  *   * in relation to this context (addrs match up)
@@ -154,11 +150,10 @@ export async function validateContextAndSagaFrame({
             errors.push(`context.sagaFrame is falsy. (E: b4edd88f4963f493789f83b29ba2df26)`);
         }
 
-        // if this is already invalid, we could have intrinsic validation errors, which are a non-starter.
+        // if this is already invalid, we could have intrinsic validation
+        // errors, which are a non-starter.
         if (errors.length > 0) { return errors; /* <<<< returns early */ }
 
-        // validate the entire context graph intrinsically, including saga frame, stones, identity(s) (if applicable but not authentication, that will be done in a separate step)
-
         // ~~ensure the non-dto properties on the context object (i.e. props
         // that are not ib, gib, data, or rel8ns) match the data in the
         // context object~~ NO. THIS WILL BE IN A SEPARATE FUNCTION.
@@ -176,7 +171,6 @@ export async function validateContextAndSagaFrame({
     }
 }
 
-
 /**
  * validates {@link SyncSagaContextIbGib_V1.payloadIbGibsDomain} intrinsically,
  * and ensures that these payloadIbGibs also match the expected addrs in
@@ -198,67 +192,13 @@ export async function validateContextDomainPayloadIbGibs({ context }: { context:
     }
 }
 
-/**
- * move to sync-peer-helpers.mts as a pure function?
- */
 export async function authenticateContext({
-    context,
-    space,
-    keystoneSvc,
-}: {
-    context: SyncSagaContextIbGib_V1,
-    space: IbGibSpaceAny,
-    keystoneSvc?: KeystoneService_V1,
 }): Promise<string[]> {
     const lc = `[${authenticateContext.name}]`;
     try {
-        if (logalot) { console.log(`${lc} starting... (I: 2677a482dfa873dcd1aa04a3031ff826)`); }
-
-        const errors: string[] = [];
-        if (!keystoneSvc) {
-            if (logalot) { console.warn(`${lc} No keystoneSvc provided. Skipping context authentication. (W: d34b8ad93d84a1ba8d8f7facd288826)`); }
-            return errors;
-        }
-
-        // Bill Architecture: We only sign at the context level.
-        // If the context refers to a session keystone, we must have a signedSessionKeystone 
-        // as well to verify the most recent turn.
-        const { sessionKeystone: prevKeystoneAddrs } = context.rel8ns || {};
-        const { signedSessionKeystone: currKeystone } = context;
-
-        if (prevKeystoneAddrs && prevKeystoneAddrs.length > 0) {
-            if (!currKeystone) {
-                errors.push(`context.rel8ns.sessionKeystone present but context.signedSessionKeystone falsy. (E: b6e5a8ad93d84260a8d8e7facd288826)`);
-                return errors;
-            }
-
-            // Retrieve the previous keystone frame from space
-            const prevKeystoneAddr = prevKeystoneAddrs[0];
-            const getPrevRes = await getFromSpace({ addr: prevKeystoneAddr, space });
-            if (!getPrevRes.success || !getPrevRes.ibGibs || getPrevRes.ibGibs.length === 0) {
-                errors.push(`couldn't find previous session keystone (${prevKeystoneAddr}) in space (${space.ib}). (E: 7c34b8ad94d84a9ba8cbe7facd288826)`);
-                return errors;
-            }
-            const prevKeystone = getPrevRes.ibGibs[0] as KeystoneIbGib_V1;
-
-            // 1. Validate the transition (API replay of evolution + intrinsic validation)
-            const transitionErrors = await keystoneSvc.validate({
-                currentIbGib: currKeystone,
-                prevIbGib: prevKeystone,
-            });
-            if (transitionErrors.length > 0) {
-                errors.push(`Invalid session keystone transition: ${transitionErrors.join(', ')} (E: d34b8ad95d84b90a8d8ef7facd288826)`);
-            }
-
-            // 2. Verify that the signature in current keystone actually targets this context
-            const contextAddr = getIbGibAddr({ ibGib: context });
-            const proofTargetsThisContext = currKeystone.data?.proofs.some(p => p.claim.target === contextAddr);
-            if (!proofTargetsThisContext) {
-                errors.push(`Session keystone signature does not target the current context ibgib (${contextAddr}). (E: f3e5a8ad96d84c1ba8d8f7facd288826)`);
-            }
-        }
-
-        return errors;
+        if (logalot) { console.log(`${lc} starting... (I: 3c34e8f1d6ef965f98725c88459ea926)`); }
+        console.warn(`${lc}[NAG] not thrown. not implemented right now after removing all identity-related code. (W: e5fad31cfb49eef198a189a82dbcf726)`)
+        return [];
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)}`);
         throw error;

package/src/sync/sync-saga-context/sync-saga-context-types.mts

@@ -8,7 +8,6 @@ import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/ty
 import { SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN } from '../sync-constants.mjs';
 import { SyncIbGib_V1 } from '../sync-types.mjs';
 import { SYNC_SAGA_CONTEXT_ATOM } from './sync-saga-context-constants.mjs';
-import { KeystoneIbGib_V1 } from '../../keystone/keystone-types.mjs';
 
 export interface SyncSagaContextIb_V1 {
     atom: typeof SYNC_SAGA_CONTEXT_ATOM;
@@ -39,7 +38,7 @@ export interface SyncSagaContextData_V1 extends IbGibData_V1 {
 
 /**
  * Relationships for the Sync Saga Context.
- * Contains the "Tip" saga frame and all necessary dependency stones/identities/claims.
+ * Contains the "Tip" saga frame and all necessary dependency stones.
  */
 export interface SyncSagaContextRel8ns_V1 extends IbGibRel8ns_V1 {
     /**
@@ -49,24 +48,6 @@ export interface SyncSagaContextRel8ns_V1 extends IbGibRel8ns_V1 {
      */
     sagaFrame: IbGibAddr[];
 
-    /**
-     * The Ephemeral Session Keystone Identity used for this saga. Required for
-     * validating the saga frame and this context.
-     *
-     * WARNING!!!: THIS DOES NOT POINT TO THE CURRENT SESSION KEYSTONE IN
-     * {@link SyncSagaContextIbGib_V1.signedSessionKeystone}. This points to the
-     * PREVIOUS FRAME (immediate past) of that frame. That session keystone
-     * signs with THIS context's frame as its target, so it is logically
-     * impossible because the hash would be different.
-     *
-     * ## notes
-     *
-     * ATOW (02/18/2026), this is a single address that will have a primary pool
-     * for the sender and a delegated pool for the receiver.
-     *
-     * @see {@link SyncSagaContextIbGib_V1.signedSessionKeystone}
-     */
-    sessionKeystone?: IbGibAddr[];
 }
 
 /**
@@ -89,32 +70,4 @@ export interface SyncSagaContextIbGib_V1 extends IbGib_V1<SyncSagaContextData_V1
      */
     sagaFrame: SyncIbGib_V1;
 
-    /**
-     * If session keystone is in play, then this will be populated with that
-     * keystone. This session keystone will point to the this context ibgib,
-     * BUT, this context ibgib will point to the **PREVIOUS** frame of the
-     * keystone.
-     *
-     * So in order to verify this context ibgib, we must verify the keystone
-     * points to this context ibgib AND that this context ibgib points to the
-     * previous frame of the keystone.
-     */
-    signedSessionKeystone?: KeystoneIbGib_V1;
-
-    /**
-     * If identity is used in the sync transaction, this should be provided. It
-     * will drive both primary identity keystone evolution (to create session
-     * keystone), as well as signing the session keystone itself.
-     *
-     * when a peer transmits the context ibgib, this does not need to be
-     * transmitted. Note, however, that if sync is occuring between two remote
-     * peers and the peer design is not a proxy-based one, then the receiver
-     * should assign this with their own provider function.
-     *
-     * @returns the identity secret when needed to sign/evolve keystone
-     *
-     * NOTE: Not 100% sure where I'm putting this so this may end up being
-     * unused and should thus be removed. Right now, I think this will work.
-     */
-    fnIdentitySecret?: () => Promise<string>;
 }