@ibgib/core-gib 0.1.57 → 0.1.59

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

@@ -0,0 +1,345 @@
+/**
+ * @module sync-peer-websocket-sender-v1
+ */
+
+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 { KeystoneIbGib_V1 } from '../../../../keystone/keystone-types.mjs';
+import { KeystoneService_V1 } from '../../../../keystone/keystone-service-v1.mjs';
+import { KeystoneStrategyFactory } from '../../../../keystone/strategy/keystone-strategy-factory.mjs';
+import { deriveSessionSecret } from '../../../sync-helpers.mjs';
+import { SyncPeer_V1 } from '../../sync-peer-v1.mjs';
+import { SyncSagaContextIbGib_V1 } from '../../../sync-saga-context/sync-saga-context-types.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../../../core-constants.mjs';
+import {
+    ConnectSyncPeerWebSocketSenderOpts,
+    InitializeSyncPeerWebSocketSenderOpts,
+    SyncPeerWebSocketSenderData_V1,
+    SyncPeerWebSocketSenderRel8ns_V1,
+    SyncPeerWebSocketSenderIbGib_V1
+} from './sync-peer-websocket-sender-types.mjs';
+import {
+    SESSION_KEYSTONE_POLICY,
+    getConnectChallenge
+} from '../sync-peer-websocket-receiver/sync-websocket-peer-helpers.mjs';
+import { SyncWebSocketMsgType } from '../sync-peer-websocket-constants.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+/**
+ * WebSocket Sender Peer implementation running in browser/native environment.
+ */
+export class SyncPeerWebSocketSender_V1
+    extends SyncPeer_V1<ConnectSyncPeerWebSocketSenderOpts, InitializeSyncPeerWebSocketSenderOpts>
+    implements SyncPeerWebSocketSenderIbGib_V1 {
+
+    protected override lc: string = `[${SyncPeerWebSocketSender_V1.name}]`;
+
+    override get classname(): string {
+        return SyncPeerWebSocketSender_V1.name;
+    }
+
+    public get isSocketOpen(): boolean {
+        return this.ws !== undefined && this.ws.readyState === WebSocket.OPEN;
+    }
+
+    declare data: SyncPeerWebSocketSenderData_V1 | undefined;
+    declare rel8ns: SyncPeerWebSocketSenderRel8ns_V1 | undefined;
+
+    protected ws?: WebSocket;
+    protected activeResolve?: (value: SyncSagaContextIbGib_V1 | undefined) => void;
+    protected activeReject?: (reason: any) => void;
+    protected pendingPayloadsToSend: IbGib_V1[] = [];
+
+    constructor(
+        initialData: SyncPeerWebSocketSenderData_V1,
+        initialRel8ns?: SyncPeerWebSocketSenderRel8ns_V1,
+    ) {
+        super(initialData, initialRel8ns);
+    }
+
+    protected override async preConnectCheck(opts: ConnectSyncPeerWebSocketSenderOpts): Promise<void> {
+        const lc = `${this.lc}[${this.preConnectCheck.name}]`;
+        if (!this.data?.wsUrl) {
+            throw new Error(`Missing wsUrl in peer data (E: a3b2c1d0e9f8e7d6c5b4a3f2e1d0c910)`);
+        }
+        if (!this.data?.httpEvolveUrl) {
+            throw new Error(`Missing httpEvolveUrl in peer data (E: a3b2c1d0e9f8e7d6c5b4a3f2e1d0c911)`);
+        }
+    }
+
+    /**
+     * Submits the evolved master identity (I1) and new session keystone (S) to the server's HTTP registry.
+     */
+    protected override async postEstablishToReceiver({
+        newSenderIdentity,
+        sessionIdentity,
+    }: {
+        newSenderIdentity: KeystoneIbGib_V1;
+        sessionIdentity: KeystoneIbGib_V1;
+    }): Promise<void> {
+        const lc = `${this.lc}[${this.postEstablishToReceiver.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} posting evolved keystones to ${this.data!.httpEvolveUrl}...`); }
+            if (!this.data) { throw new Error(`(UNEXPECTED) this.data falsy? (E: d642e8a9af18b532c87c6f581aa53b26)`); }
+
+            if (!this.data.httpEvolveUrl) { throw new Error(`(UNEXPECTED) this.data.httpEvolveUrl falsy? (E: 8589ddbb155914d85c09658881da2c26)`); }
+
+            const response = await fetch(this.data.httpEvolveUrl, {
+                method: 'PUT',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    keystoneIbGib: newSenderIdentity,
+                    relatedIbGibs: [sessionIdentity]
+                }),
+            });
+
+            if (!response.ok) {
+                const data = await response.json().catch(() => ({}));
+                const errorMsg = data.message || data.error || 'Unknown error';
+                throw new Error(`HTTP ${response.status} evolution post rejected. errorMsg: ${errorMsg} (E: e8a478291b88d05c68cf6b385684b826)`);
+            }
+
+            if (logalot) { console.log(`${lc} evolve post accepted by server.`); }
+        } catch (error) {
+            console.error(`${lc} establish post failed: ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+
+    /**
+     * Establishes the stateful WebSocket connection and performs the multi-turn cryptographic challenge connect.
+     */
+    protected override async connectImpl(opts: ConnectSyncPeerWebSocketSenderOpts): Promise<void> {
+        const lc = `${this.lc}[${this.connectImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            const { senderIdentity, fnSenderSecret, sagaId, localMetaspace, localSpace } = this.opts!;
+            if (!senderIdentity || !fnSenderSecret || !sagaId) {
+                throw new Error(`Missing identity parameters in peer options (E: ed49b6711ac82efcdb42b8a28c5b6826)`);
+            }
+
+            // 1. Solve upfront pre-filter solution
+            const senderSecret = await fnSenderSecret();
+            const sessionSecret = await deriveSessionSecret({ senderSecret, sagaId });
+
+            // Fetch session identity S that establishSessionIdentity just created
+            const sAddr_tjp = getIbGibAddr({ ibGib: senderIdentity }); // wait, S's past contains I
+            // Actually, we can get the S keystone that was returned by establishSessionIdentity.
+            // Let's resolve S from the sender localSpace using its target claim or the targetAddrs
+            const sAddr = getIbGibAddr({ ibGib: senderIdentity.rel8ns?.past ? senderIdentity : senderIdentity }); // stub: get the actual generated S
+
+            // To make sure we have the exact session identity S, we can query localSpace.
+            // Since we know the sagaId, we can walk or locate it.
+            // But wait, the coordinator calls establishSessionIdentity first, which returns the created S keystone!
+            // Let's store a reference to the sessionIdentity S on this class during establish, or lookup from localSpace.
+            // Wait, does the coordinator let the peer store S? No, but let's query the latest keystone in localSpace.
+            const senderIdentityLatestAddr =
+                await localMetaspace.getLatestAddr({ ibGib: senderIdentity, space: localSpace });
+            if (!senderIdentityLatestAddr) { throw new Error(`senderIdentityLatestAddr falsy. we should have a latest addr that is different than the sender identity at this point (done in the peer establish phase) (E: 225607318bef485d7821f82de97b6826)`); }
+
+            const resGet = await localMetaspace.get({ addrs: [senderIdentityLatestAddr], space: localSpace });
+            const I_tip = resGet.ibGibs?.[0] as KeystoneIbGib_V1;
+
+            // const targetSAddr = I_tip?.rel8ns?.past?.[0] ?? I_tip?.data?.proofs?.[0]?.claim?.target;
+            const targetSAddr = I_tip.data.proofs.at(0)?.claim.target;
+            if (!targetSAddr) {
+                throw new Error(`Could not locate session keystone target from identity (E: 5ec4882f7e5e4c33fbd00ab8b3166726)`);
+            }
+
+            const resGetS = await localMetaspace.get({ addrs: [targetSAddr], space: localSpace });
+            const sessionS = resGetS.ibGibs?.[0] as KeystoneIbGib_V1;
+            if (!sessionS) {
+                throw new Error(`Session keystone not found in local space: ${targetSAddr} (E: 9ba818e6622808bb4ae749be31f80b26)`);
+            }
+
+            // Solve dynamic upfront picket-fence challenge
+            const connectPool =
+                (sessionS.data?.challengePools ?? [])
+                    .find(p => p.id === SESSION_KEYSTONE_POLICY.CONNECT_POOL.ID);
+            if (!connectPool) {
+                throw new Error(`Session keystone missing connect pool (E: f50968afca04b6d38ec19824ea201826)`);
+            }
+
+            const { challengeId } = getConnectChallenge(sessionS);
+            const strategy = KeystoneStrategyFactory.create({ config: connectPool.config });
+            const poolSecret = await strategy.derivePoolSecret({ masterSecret: sessionSecret });
+            const solution = await strategy.generateSolution({
+                poolSecret,
+                poolId: SESSION_KEYSTONE_POLICY.CONNECT_POOL.ID,
+                challengeId
+            });
+
+            // 2. Open WebSocket connection
+            const wsUrl = `${this.data!.wsUrl}?sAddr=${encodeURIComponent(targetSAddr)}&solution=${encodeURIComponent(solution.value)}`;
+            if (logalot) { console.log(`${lc} connecting to WebSocket: ${wsUrl}`); }
+
+            const ws = new WebSocket(wsUrl);
+            this.ws = ws;
+
+            return new Promise<void>((resolve, reject) => {
+                let isResolved = false;
+
+                ws.addEventListener('open', () => {
+                    if (logalot) { console.log(`${lc} WebSocket opened. Awaiting challenge...`); }
+                });
+
+                ws.addEventListener('message', async (ev) => {
+                    try {
+                        const msg = JSON.parse(ev.data);
+                        if (logalot) { console.log(`${lc} received frame: ${msg.type}`); }
+
+                        if (msg.type === SyncWebSocketMsgType.auth_challenge_init) {
+                            ws.send(JSON.stringify({
+                                type: SyncWebSocketMsgType.auth_init,
+                                sAddr: targetSAddr
+                            }));
+                        } else if (msg.type === SyncWebSocketMsgType.auth_challenge) {
+                            const { challengeUuid, demandedIds } = msg;
+                            if (logalot) { console.log(`${lc} solving demanded challenges: ${demandedIds.join(', ')}`); }
+
+                            const keystoneService = new KeystoneService_V1();
+                            const proofFrame = await keystoneService.sign({
+                                latestKeystone: sessionS,
+                                masterSecret: sessionSecret,
+                                poolId: SESSION_KEYSTONE_POLICY.CONNECT_POOL.ID,
+                                requiredChallengeIds: demandedIds,
+                                claim: {
+                                    verb: SESSION_KEYSTONE_POLICY.CONNECT_POOL.VERB,
+                                    target: challengeUuid
+                                },
+                                metaspace: localMetaspace,
+                                space: localSpace
+                            });
+
+                            ws.send(JSON.stringify({
+                                type: SyncWebSocketMsgType.auth_proof,
+                                proofFrame
+                            }));
+                        } else if (msg.type === SyncWebSocketMsgType.auth_ok) {
+                            if (logalot) { console.log(`${lc} WebSocket connect SUCCESS!`); }
+                            isResolved = true;
+
+                            // Setup persistent runtime listeners
+                            ws.removeEventListener('message', (() => { }) as any);
+                            ws.addEventListener('message', (event) => this.handleRuntimeMessage(event));
+
+                            resolve();
+                        } else if (msg.type === SyncWebSocketMsgType.auth_fail) {
+                            reject(new Error(`Connect failed: ${msg.message}`));
+                        }
+                    } catch (error) {
+                        reject(error);
+                    }
+                });
+
+                ws.addEventListener('close', (event) => {
+                    if (!isResolved) {
+                        reject(new Error(`WebSocket closed before connect completed (code: ${event.code})`));
+                    }
+                });
+
+                ws.addEventListener('error', (err) => {
+                    if (!isResolved) {
+                        reject(new Error(`WebSocket connection error`));
+                    }
+                });
+            });
+
+        } catch (error) {
+            console.error(`${lc} connect failed: ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+
+    /**
+     * Handles synchronizing messages and evolved context frames during active transaction turns.
+     */
+    protected async handleRuntimeMessage(event: MessageEvent): Promise<void> {
+        const lc = `${this.lc}[${this.handleRuntimeMessage.name}]`;
+        try {
+            const msg = JSON.parse(event.data);
+            if (logalot) { console.log(`${lc} received runtime frame: ${msg.type}`); }
+
+            if (msg.type === SyncWebSocketMsgType.sync_frame_response) {
+                const responseContext = msg.context as SyncSagaContextIbGib_V1;
+
+                // Validate and authenticate Bob's response context first
+                await this.authenticateAndValidate({ context: responseContext });
+
+                // If response has expected payloads, authorize Bob to stream them
+                const expectedPayloadAddrs = responseContext.data?.['@payloadAddrsDomain'] || [];
+                if (expectedPayloadAddrs.length > 0) {
+                    this.ws!.send(JSON.stringify({
+                        type: SyncWebSocketMsgType.sync_frame_response_authenticated,
+                        contextAddr: getIbGibAddr({ ibGib: responseContext })
+                    }));
+                }
+
+                if (this.activeResolve) {
+                    const resolve = this.activeResolve;
+                    this.activeResolve = undefined;
+                    this.activeReject = undefined;
+                    resolve(responseContext);
+                }
+            } else if (msg.type === SyncWebSocketMsgType.sync_frame_authenticated) {
+                // Bob authenticated our context, stream buffered payloads
+                const payloads = this.pendingPayloadsToSend || [];
+                this.pendingPayloadsToSend = [];
+                for (const ibGib of payloads) {
+                    this.ws!.send(JSON.stringify({
+                        type: SyncWebSocketMsgType.domain_payload,
+                        ibGib
+                    }));
+                }
+            } else if (msg.type === SyncWebSocketMsgType.domain_payload) {
+                const payload = msg.ibGib as IbGib_V1;
+                this.payloadIbGibsDomainReceived$.next(payload);
+            }
+        } catch (error) {
+            console.error(`${lc} failed parsing runtime frame: ${extractErrorMsg(error)}`);
+            if (this.activeReject) {
+                this.activeReject(error);
+            }
+        }
+    }
+
+    /**
+     * Serializes the transaction context and payload down the active WebSocket connection.
+     */
+    protected override async sendContextRequest(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.sendContextRequest.name}]`;
+        try {
+            if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+                throw new Error(`WebSocket is not connected or open (E: a3b2c1d0e9f8e7d6c5b4a3f2e1d0c915)`);
+            }
+
+            // 1. Separate payloads to send later
+            const domainPayloads = context.payloadIbGibsDomain ?? [];
+            this.pendingPayloadsToSend = [...domainPayloads];
+
+            // 2. Clone context without payloads for transport
+            const contextToSend = { ...context };
+            delete contextToSend.payloadIbGibsDomain;
+
+            // 3. Transmit the synchronizing transaction context
+            return new Promise<SyncSagaContextIbGib_V1 | undefined>((resolve, reject) => {
+                this.activeResolve = resolve;
+                this.activeReject = reject;
+
+                this.ws!.send(JSON.stringify({
+                    type: SyncWebSocketMsgType.sync_frame,
+                    context: contextToSend
+                }));
+            });
+
+        } catch (error) {
+            console.error(`${lc} sendContextRequest failed: ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+}

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

@@ -2,11 +2,9 @@
  * @module sync saga context helpers
  */
 
-import { extractErrorMsg, getTimestamp } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-import { IbGib_V1, } from '@ibgib/ts-gib/dist/V1/types.mjs';
-import { Ib } from '@ibgib/ts-gib/dist/types.mjs';
+import { extractErrorMsg, } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr, } from '@ibgib/ts-gib/dist/helper.mjs';
+import { Ib, } 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';
@@ -14,13 +12,15 @@ import { SYNC_SAGA_CONTEXT_ATOM } from './sync-saga-context-constants.mjs';
 import { SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN } from '../sync-constants.mjs';
 import {
     SyncSagaContextData_V1, SyncSagaContextIbGib_V1, SyncSagaContextIb_V1,
-    SyncSagaContextRel8ns_V1,
 } from './sync-saga-context-types.mjs';
 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 { getFromSpace, getLatestAddrs, getTjpIbGib } from '../../witness/space/space-helper.mjs';
+import { SessionGenesisFrameDetails, } from '../sync-types.mjs';
 import { validateSyncSagaFrame } from '../sync-helpers.mjs';
 import { isIbGibWithAtom } from '../../common/other/ibgib-helper.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';
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -192,42 +192,231 @@ export async function validateContextDomainPayloadIbGibs({ context }: { context:
     }
 }
 
-export async function authenticateContext({
-}): Promise<string[]> {
-    const lc = `[${authenticateContext.name}]`;
-    try {
-        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;
-    } finally {
-        if (logalot) { console.log(`${lc} complete.`); }
-    }
-}
-
 /**
- * move to sync-peer-helpers.mts as a pure function?
+ * "Intrinsically": This authenticates assuming we have already established that
+ * this context is a valid continuation of previous sync contexts/saga state. It
+ * does not check that the session identity contained on this context is a valid
+ * continuation.
+ *
+ * ## notes
+ *
+ * Say an attacker tries to hijack a legit sync process by capturing previous
+ * context(s). Then the attacker just either creates its own sessionIdentity
+ *
+ * ## implementation notes
+ *
+ * This is a HUGE function right now, because there are just a lot of things to
+ * check. I'm basically going through and just taking every assumption that I
+ * can think of and encoding it.
+ *
+ * We will need to refactor this at some point to neaten it up, but we should
+ * not remove sections without EXTREMELY good reasoning, as this would reduce
+ * security.
  */
-export async function authorizeContext({
+export async function authenticateContextIntrinsically({
     context,
-    fullSagaHistory
+    space,
+    // stageInProtocol,
 }: {
     context: SyncSagaContextIbGib_V1,
-    fullSagaHistory: SyncSagaFrameDependencyGraph[],
+    space: IbGibSpaceAny,
+    // /**
+    //  * @see {@link StageInProtocol}
+    //  */
+    // stageInProtocol: StageInProtocol,
 }): Promise<string[]> {
-    const lc = `[${authorizeContext.name}]`;
+    const lc = `[${authenticateContextIntrinsically.name}]`;
     try {
-        if (logalot) { console.log(`${lc} starting... (I: 48c918b41ceec0cd489ca3b8819e6826)`); }
+        if (logalot) { console.log(`${lc} starting... (I: 3c34e8f1d6ef965f98725c88459ea926)`); }
+
+        const errors: string[] = [];
 
-        console.error(`${lc} NAG ERROR (NOT THROWN): not implemented. authorize business logic (v1 must have this, but later when we are working on admin vs. student)(E: bc3a78f2dab18ab64c36d055a4b50526)`);
+        if (!context.data) { throw new Error(`(UNEXPECTED) context.data falsy? (E: 3e4ddd0eb4b828ad489658d88d9a6326)`); }
+        if (!context.rel8ns) { throw new Error(`(UNEXPECTED) context.rel8ns falsy? (E: 8026589d4fed69c828334ee842074326)`); }
 
-        return [];
+        const { sagaFrame, signedSessionIdentity: currSessionIdentity } = context;
+        if (!sagaFrame.data) { throw new Error(`(UNEXPECTED) sagaFrame.data falsy? (E: b61cc82d25984c92f75db74a5a855b26)`); }
+
+        // We only sign at the context level.
+        // If context has no signedSessionIdentity, skip authentication (anonymous or broker response).
+        if (!currSessionIdentity) {
+            // check the sync saga to determine if there _should_ be a session
+            // identity according to the given sagaFrame (which could be
+            // malicious, remember!!)
+            // todo: add logic to SET this property when using identity, then (and only then) remove this todo.
+            console.error(`${lc}[NAG][not thrown] sagaFrame.data.sessionIdentityTjpAddr logic needs to be added in coordinator (E: 4fc47800a1086c917a47381824280826)`);
+            if (sagaFrame.data.sessionIdentityTjpAddr) {
+                errors.push('Context has no session identity, but sync saga frame shows a session identity (sagaFrame.data.sessionIdentityTjpAddr is truthy). (E: 69dd6cdc2e1859c0f3d62958c4339826)')
+                return errors; /* <<<< returns early */
+            } else if (context.rel8ns.sessionIdentity) {
+                errors.push('Context has no signed session identity, but context.rel8ns.sessionIdentity is truthy. (E: 96a04a8a6c88ea8bf88118f89ad8e326)')
+                return errors; /* <<<< returns early */
+            } else {
+                // nothing further to authenticate
+                if (logalot) { console.log(`${lc} context has no signedSessionIdentity and sync saga frame doesn't state there should be session identity. So nothing further to authenticate - returning early with no authentication errors. (I: d708735f9a2899ee98f762b8a09ed826)`); }
+                return []; /* <<<< returns early */
+            }
+        }
+        const currSessionIdentityAddr = getIbGibAddr({ ibGib: currSessionIdentity });
+
+        // ensure the context rel8ns points to a session identity
+        const prevSessionIdentityAddrs_accordingToContextRel8ns = context.rel8ns?.sessionIdentity ?? [];
+        if (prevSessionIdentityAddrs_accordingToContextRel8ns.length === 0) {
+            errors.push(`context.rel8ns.sessionIdentity is falsy/empty but context.signedSessionIdentity is present. (E: 66f906421eb2468c0b33f908a3cf2826)`);
+            return errors; /* <<<< returns early */
+        }
+
+        if (prevSessionIdentityAddrs_accordingToContextRel8ns.length > 1) {
+            errors.push(`context.rel8ns.sessionIdentity has multiple identity addrs. (E: 489428bfe6fdaa4cd885b938dc4c5826)`);
+            return errors; /* <<<< returns early */
+        }
+
+        // ensure the context session identity is the immediate past of the
+        // current session identity
+        const prevSessionIdentityAddr = prevSessionIdentityAddrs_accordingToContextRel8ns[0];
+
+        // Confirm previous session identity addr exists in space and that it is
+        // the most recent in the session keystone's timeline
+
+        const resGetLatestAddr = await getLatestAddrs({ addrs: [prevSessionIdentityAddr], space });
+        if (!resGetLatestAddr) { throw new Error(`(UNEXPECTED) resGetLatestAddr for prevSessionIdentityAddr in space (${space.ib}) falsy? (E: 7b207e5cbcec9037ea5adbe822ead826)`); }
+        if (!resGetLatestAddr.data) { throw new Error(`(UNEXPECTED) resGetLatestAddr.data for prevSessionIdentityAddr in space (${space.ib}) falsy? (E: de4eb8d730c8c4dcb59c8b9c79277826)`); }
+        if (!resGetLatestAddr.data.success) {
+            throw new Error(`(UNEXPECTED) resGetLatestAddr.data.success falsy? (E: c94298dfd9684ad6a87eb748459aa826)`);
+        }
+        const { latestAddrsMap } = resGetLatestAddr.data;
+        if (!latestAddrsMap) { throw new Error(`(UNEXPECTED) resGetLatestAddr.data.latestAddrsMap falsy? (E: 19f1fd5fe798cf2e5fa923919169d826)`); }
+        if (Object.keys(latestAddrsMap).length !== 1) {
+            throw new Error(`(UNEXPECTED) Object.keys(latestAddrsMap).length !== 1? (E: fe526a0747589c6427a8bcc86da34a26)`);
+        }
+        const prevSessionIdentityAddr_latest = latestAddrsMap[prevSessionIdentityAddr];
+        if (!prevSessionIdentityAddr_latest) {
+            errors.push(`prevSessionIdentityAddr (${prevSessionIdentityAddr}) not found in space (${space.ib}). this should have been the incoming prevSessionIdentityAddr (E: f6d042bd6b54819998653228dee34226)`);
+            return errors; /* <<<< returns early */
+        }
+        if (prevSessionIdentityAddr !== prevSessionIdentityAddr_latest) {
+            if (prevSessionIdentityAddr_latest === currSessionIdentityAddr) {
+                // this is ok? if the sender peer is calling this just to validate **before sending**, then this will be the case. If the receiver is calling this code before continuing the sync/at the start of continuing the sync, then this will not hit.
+                // debugger; // in sync saga context auth, want to know if this hits...this does hit, so my thoughts on the innerspace/sender peer seem to be correct
+            } else {
+                // debugger; // in sync saga context auth, want to know if this hits...so far this does NOT hit
+                errors.push(`context.rel8ns.sessionIdentity does not point to the most recent in the space (${space.ib}). (E: 2f8288f53c87b6aa47bd2178d9df0c26)`)
+                return errors; /* <<<< returns early */
+            }
+        }
+
+        const resGetPrevSessionIdentity = await getFromSpace({ addr: prevSessionIdentityAddr, space });
+        if (!resGetPrevSessionIdentity.success || resGetPrevSessionIdentity.ibGibs?.length !== 1) {
+            errors.push(`could not fetch latest sender identity ${prevSessionIdentityAddr} from space (${space.ib}). (E: fd48c3e64c9fa4efd8a1f8280af18226)`);
+            return errors;
+        }
+        const prevSessionIdentity = resGetPrevSessionIdentity.ibGibs[0] as KeystoneIbGib_V1;
+
+        // get the session identity tjp, which has frame details that link back
+        // to the identity that authorized the session
+        const sessionIdentityTjp =
+            await getTjpIbGib({ ibGib: prevSessionIdentity, naive: true, space }) as KeystoneIbGib_V1 | undefined;
+        if (!sessionIdentityTjp) { throw new Error(`(UNEXPECTED) couldn't get sessionIdentityTjp in space (${space.ib})? we have already gotten the identity itself in the space, so we would expect the entire timeline to exist in it. (E: 9be0382ff1c8a0e77645ea38c096f826)`); }
+        const sessionIdentityTjpAddr = getIbGibAddr({ ibGib: sessionIdentityTjp });
+        if (sessionIdentityTjpAddr !== sagaFrame.data.sessionIdentityTjpAddr) {
+            throw new Error(`(UNEXPECTED) sessionIdentityTjpAddr !== sagaFrame.data.sessionIdentityTjpAddr? (E: c9a4ad5c2728fe38e86afc58e4abaf26)`);
+        }
+
+        const sessionGenesisFrameDetails = sessionIdentityTjp.data.frameDetails as SessionGenesisFrameDetails;
+        if (!sessionGenesisFrameDetails) {
+            errors.push(`Invalid session identity tjp: sessionIdentityTjp.data.frameDetails is falsy. (E: 0187f8f804a84256281720586620b826)`);
+            return errors; /* <<<< returns early */
+        }
+        const { senderIdentityAddr, senderIdentityTjpAddr } = sessionGenesisFrameDetails;
+        if (!senderIdentityAddr) { throw new Error(`sessionGenesisFrameDetails.senderIdentityAddr falsy (E: 02a0c80a3ead9e3af8af4cf3b156e826)`); }
+        if (!senderIdentityTjpAddr) { throw new Error(`sessionGenesisFrameDetails.senderIdentityTjpAddr falsy (E: 271928090ff5dc56d4bb63d8d5c68826)`); }
+
+        const resGetLatestAddr_senderIdentity =
+            await getLatestAddrs({ addrs: [senderIdentityTjpAddr, senderIdentityAddr], space });
+        if (!resGetLatestAddr_senderIdentity) { throw new Error(`(UNEXPECTED) resGetLatestAddr_senderIdentity for prevSessionIdentityAddr in space (${space.ib}) falsy? (E: 2e4ae8083b6fb7cbb8fae2a519062926)`); }
+        if (!resGetLatestAddr_senderIdentity.data) { throw new Error(`(UNEXPECTED) resGetLatestAddr_senderIdentity.data for prevSessionIdentityAddr in space (${space.ib}) falsy? (E: 2e231850c2a898cc282b4b2841056826)`); }
+        if (!resGetLatestAddr_senderIdentity.data.success) {
+            throw new Error(`(UNEXPECTED) resGetLatestAddr_senderIdentity.data.success falsy? (E: e93508f03e0475925875b00746ffd826)`);
+        }
+        const { latestAddrsMap: latestAddrsMap_senderIdentity } = resGetLatestAddr_senderIdentity.data;
+        if (!latestAddrsMap_senderIdentity) { throw new Error(`(UNEXPECTED) resGetLatestAddr_senderIdentity.data.latestAddrsMap falsy? (E: 87a91e3f9968ad9ba79cdfe8cd878326)`); }
+        if (Object.keys(latestAddrsMap_senderIdentity).length !== 2 && senderIdentityTjpAddr !== senderIdentityAddr) {
+            throw new Error(`(UNEXPECTED) Object.keys(latestAddrsMap_senderIdentity).length !== 2 && senderIdentityTjpAddr !== senderIdentityAddr? (E: fe46bd584853d8e1e8e2d11f52012826)`);
+        }
+        // these two should be the same, we're just confirming that they're both
+        // on the same timeline.
+        const senderIdentityTjpAddr_latest = latestAddrsMap_senderIdentity[senderIdentityTjpAddr];
+        const senderIdentityAddr_latest = latestAddrsMap_senderIdentity[senderIdentityAddr];
+        if (!senderIdentityAddr_latest) { throw new Error(`(UNEXPECTED) senderIdentityAddr_latest falsy? (E: e151798ae2e9241578d09948937c4b26)`); }
+        if (senderIdentityTjpAddr_latest !== senderIdentityAddr_latest) {
+            throw new Error(`senderIdentityTjpAddr_latest !== senderIdentityAddr_latest (E: 52478a1053589e72665031a853cc1826)`);
+        }
+
+        // ATOW, we're only allowing a single sync to occur on an identity at
+        // any given time (which makes sense). We also are assuming that the
+        // sender identity is not doing anything ELSE at this time, which in
+        // the (far) future may change. So the user couldn't edit their primary
+        // identity's profile, description, etc., while the sync is in progress.
+        // This may ultimately be asking too much though. But for now, we'll
+        // enforce that the latest senderIdentity addr should be that addr that
+        // authorized the session keystone.
+        // if (senderIdentityAddr_latest !== senderIdentityAddr) {
+        //     errors.push(`The senderIdentityAddr referenced in the session keystone's genesis frameDetails (${senderIdentityAddr}) is DIFFERENT than the latest sender identity addr (${senderIdentityAddr_latest}). This means that the sender has done something besides the current sync operation, which isn't supported at this time. (E: a02598271b48cbeb584e45abde121826)`);
+        //     return errors; /* <<<< returns early */
+        // }
+
+        // now we confirm the other direction: sender identity should have been
+        // signed with "sync" verb and targeting the sessionIdentity tjp
+        // (genesis) frame.
+        const resGetSenderIdentity_latest = await getFromSpace({
+            addr: senderIdentityAddr_latest,
+            space,
+        });
+        if (!resGetSenderIdentity_latest.success || resGetSenderIdentity_latest.ibGibs?.length !== 1) {
+            errors.push(`could not fetch latest sender identity ${prevSessionIdentityAddr} from space (${space.ib}). (E: 3565ff0ed458f5a2384c40b16e849826)`);
+            return errors; /* <<<< returns early */
+        }
+        const senderIdentity_latest = resGetSenderIdentity_latest.ibGibs[0] as KeystoneIbGib_V1;
+        if (!senderIdentity_latest.data.proofs) {
+            errors.push(`Invalid sender identity. Proofs empty/falsy. (E: ebf488853061614d2b5b137828119526)`);
+            return errors; /* <<<< returns early */
+        }
+        const syncClaim = senderIdentity_latest.data.proofs.find(p =>
+            p.claim.verb === KEYSTONE_VERB_SYNC
+        )?.claim;
+        if (!syncClaim) {
+            errors.push(`Most recent senderIdentity has no proof whose claim.verb === ${KEYSTONE_VERB_SYNC}. (E: b0f488ecccbbfe43d9a0b7c8a29d7826)`);
+            return errors; /* <<<< returns early */
+        }
+        if (syncClaim.target !== sessionIdentityTjpAddr) {
+            errors.push(`Most recent sender identity claim has claim.verb === ${KEYSTONE_VERB_SYNC} but DOES NOT target expected session identity addr ${prevSessionIdentityAddr}. (E: 3e7f18d99848969be8586423d5ccb826)`);
+            return errors;
+        }
+
+        const keystoneSvc = new KeystoneService_V1();
+        const transitionErrors = await keystoneSvc.validate({
+            currentIbGib: currSessionIdentity,
+            prevIbGib: prevSessionIdentity,
+        });
+        if (transitionErrors.length > 0) {
+            errors.push(`Invalid session identity transition: ${transitionErrors.join(', ')} (E: da1c81c6d3c86aec3254f48fe7514226)`);
+        }
+
+        // we have a valid keystone evolution/signing, but was it specifically
+        // for this incoming context? verify that the signing targets context.
+        const contextAddr = getIbGibAddr({ ibGib: context });
+        const targetsThisContext =
+            currSessionIdentity.data?.proofs?.some(p => p.claim.target === contextAddr);
+        if (!targetsThisContext) {
+            errors.push(`Session identity signature does not target current context ibgib (${contextAddr}). (E: acae68938c287178c878d1b88bebb826)`);
+        }
+
+        return errors;
     } catch (error) {
-        console.error(`${lc} ${extractErrorMsg(error)}`);
-        throw error;
+        const emsg = `${lc} ${extractErrorMsg(error)}`;
+        console.error(emsg);
+        return [`authentication produced an error: ${emsg} (E: 45e014b82af81993d936611ca6fc4d26)`];
     } finally {
         if (logalot) { console.log(`${lc} complete.`); }
     }
-}
+}

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

@@ -8,6 +8,7 @@ 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;
@@ -48,6 +49,10 @@ export interface SyncSagaContextRel8ns_V1 extends IbGibRel8ns_V1 {
      */
     sagaFrame: IbGibAddr[];
 
+    /**
+     * Ephemeral session identity genesis address to confirm S_genesis.
+     */
+    sessionIdentity?: IbGibAddr[];
 }
 
 /**
@@ -70,4 +75,8 @@ export interface SyncSagaContextIbGib_V1 extends IbGib_V1<SyncSagaContextData_V1
      */
     sagaFrame: SyncIbGib_V1;
 
+    /**
+     * Evolved session identity frame signed by Alice targeting this context.
+     */
+    signedSessionIdentity?: KeystoneIbGib_V1;
 }