envelope-preparation.ts (8606B)
1 import { 2 identityMessagingOwnership, 3 subscribeIdentityInvalidation, 4 type IdentitySession 5 } from '../runtime/identity-session.ts'; 6 import { 7 reservedSendSnapshot, 8 type ReservedSendIdentity 9 } from './send-identity.ts'; 10 import { 11 capturePrivateSealOperation, 12 buildPrivateSeal, 13 stopPrivateSeal, 14 expirePrivateSealWait, 15 type PrivateSealOperation 16 } from '../nostr/seal-builder.ts'; 17 import { buildPrivateGiftwrap } from '../nostr/giftwrap-builder.ts'; 18 import { 19 verifyOutboundEnvelope, 20 verifiedOutboundSnapshot, 21 type VerifiedOutboundEnvelope 22 } from '../nostr/verify-outbound-envelope.ts'; 23 declare const pairBrand: unique symbol; 24 export type EnvelopePreparation = Readonly<{ [pairBrand]: true }>; 25 type Role = 'self' | 'peer'; 26 type Completed = Readonly<{ 27 operation?: PrivateSealOperation; 28 proof: VerifiedOutboundEnvelope; 29 }>; 30 export type EnvelopePreparationResult = Readonly<{ 31 status: 32 | 'prepared' 33 | 'complete' 34 | 'busy' 35 | 'invalid' 36 | 'out_of_order' 37 | 'stopped' 38 | 'refused' 39 | 'mismatch' 40 | 'unavailable'; 41 }>; 42 type Controller = { 43 run(role: unknown, review: unknown): Promise<EnvelopePreparationResult>; 44 snapshot(): 45 | Readonly<{ 46 phase: Role | 'complete'; 47 busy: boolean; 48 self: ReturnType<typeof verifiedOutboundSnapshot>; 49 peer: ReturnType<typeof verifiedOutboundSnapshot>; 50 }> 51 | undefined; 52 proof(role: unknown): VerifiedOutboundEnvelope | undefined; 53 stop(expired: boolean): void; 54 close(): void; 55 }; 56 const pairs = new WeakMap<EnvelopePreparation, Controller>(); 57 // Memory-only staged crypto preparation. Ciphertext snapshots/proofs are not 58 // durable acknowledgement, transport permission, inbox readiness or Send. 59 export function captureEnvelopePreparation( 60 session: IdentitySession, 61 reserved: ReservedSendIdentity, 62 review: unknown, 63 recoveredSelf?: VerifiedOutboundEnvelope 64 ): EnvelopePreparation | undefined { 65 if (review !== 'reviewed_envelope_pair') return undefined; 66 const inputRecord = reservedSendSnapshot(reserved), 67 ownership = identityMessagingOwnership(session); 68 if ( 69 !inputRecord || 70 !ownership || 71 inputRecord.owner !== ownership.owner || 72 !ownership.current() 73 ) 74 return undefined; 75 const record = inputRecord; 76 let retained: 77 | { 78 session: IdentitySession; 79 reserved: ReservedSendIdentity; 80 ownership: typeof ownership; 81 } 82 | undefined = { session, reserved, ownership }; 83 let self: Completed | undefined, 84 peer: Completed | undefined, 85 active: PrivateSealOperation | undefined; 86 if (recoveredSelf) { 87 const original = verifiedOutboundSnapshot(recoveredSelf); 88 if ( 89 !original || 90 original.role !== 'self' || 91 original.destination !== record.owner || 92 original.owner !== record.owner || 93 original.peer !== record.peer || 94 original.command !== record.id || 95 original.rumorHash !== record.rumorHash 96 ) 97 return undefined; 98 self = { proof: recoveredSelf }; 99 } 100 let busy = false, 101 generation = 0, 102 unsubscribe = () => {}; 103 function stop(expired: boolean) { 104 generation++; 105 if (active) { 106 if (expired) expirePrivateSealWait(active); 107 else stopPrivateSeal(active); 108 } 109 // Completed self remains current when only an incomplete peer is stopped. 110 // Admission stays occupied until the actual lower job settles. 111 } 112 function close() { 113 if (!retained) return; 114 retained = undefined; 115 stop(false); 116 if (self?.operation) stopPrivateSeal(self.operation); 117 if (peer?.operation) stopPrivateSeal(peer.operation); 118 self = undefined; 119 peer = undefined; 120 unsubscribe(); 121 unsubscribe = () => {}; 122 } 123 function current() { 124 const input = retained, 125 observed = input && reservedSendSnapshot(input.reserved); 126 if ( 127 !input || 128 !input.ownership.current() || 129 !observed || 130 observed.owner !== record.owner || 131 observed.peer !== record.peer || 132 observed.id !== record.id || 133 observed.rumorHash !== record.rumorHash || 134 observed.createdAt !== record.createdAt || 135 (self && !verifiedOutboundSnapshot(self.proof)) || 136 (peer && !verifiedOutboundSnapshot(peer.proof)) 137 ) { 138 close(); 139 return false; 140 } 141 return true; 142 } 143 function snapshot() { 144 if (!current()) return undefined; 145 return { 146 phase: peer 147 ? ('complete' as const) 148 : self 149 ? ('peer' as const) 150 : ('self' as const), 151 busy, 152 self: self && verifiedOutboundSnapshot(self.proof), 153 peer: peer && verifiedOutboundSnapshot(peer.proof) 154 }; 155 } 156 function proof(role: unknown) { 157 if (!current()) return undefined; 158 return role === 'self' 159 ? self?.proof 160 : role === 'peer' 161 ? peer?.proof 162 : undefined; 163 } 164 async function run( 165 role: unknown, 166 reviewed: unknown 167 ): Promise<EnvelopePreparationResult> { 168 if ( 169 reviewed !== 'reviewed_pair_role' || 170 (role !== 'self' && role !== 'peer') 171 ) 172 return { status: 'invalid' }; 173 if (!current()) return { status: 'stopped' }; 174 if (busy) return { status: 'busy' }; 175 if (role === 'peer' && !self) return { status: 'out_of_order' }; 176 if ((role === 'self' && self) || (role === 'peer' && peer)) 177 return { status: peer ? 'complete' : 'prepared' }; 178 // Set admission before the first yield; repeated calls cannot queue prompts. 179 busy = true; 180 const attempt = generation, 181 input = retained; 182 let operation: PrivateSealOperation | undefined; 183 const admitted = () => current() && attempt === generation; 184 try { 185 if (!input || !admitted()) return { status: 'stopped' }; 186 operation = capturePrivateSealOperation( 187 input.session, 188 input.reserved, 189 role, 190 'reviewed_private_seal' 191 ); 192 if (!operation || !admitted()) return { status: 'stopped' }; 193 active = operation; 194 const result = await buildPrivateSeal(operation); 195 if (!admitted()) return { status: 'stopped' }; 196 if (result.status !== 'sealed') return { status: result.status }; 197 const wrap = buildPrivateGiftwrap(result.seal, 'reviewed_private_wrap'); 198 if (!admitted()) return { status: 'stopped' }; 199 if (!wrap) return { status: 'mismatch' }; 200 const verified = verifyOutboundEnvelope( 201 input.reserved, 202 wrap, 203 'reviewed_outbound_layers' 204 ); 205 const observed = verified && verifiedOutboundSnapshot(verified); 206 if (!admitted()) return { status: 'stopped' }; 207 if ( 208 !verified || 209 !observed || 210 observed.command !== record.id || 211 observed.rumorHash !== record.rumorHash || 212 observed.owner !== record.owner || 213 observed.peer !== record.peer || 214 observed.role !== role || 215 observed.destination !== (role === 'self' ? record.owner : record.peer) 216 ) 217 return { status: 'mismatch' }; 218 const completed = { operation, proof: verified }; 219 if (role === 'self') self = completed; 220 else peer = completed; 221 active = undefined; 222 return { status: peer ? 'complete' : 'prepared' }; 223 } catch { 224 return { status: admitted() ? 'refused' : 'stopped' }; 225 } finally { 226 if (operation && active === operation) { 227 stopPrivateSeal(operation); 228 active = undefined; 229 } 230 busy = false; 231 } 232 } 233 const token = Object.freeze({}) as EnvelopePreparation; 234 pairs.set(token, { run, snapshot, proof, stop, close }); 235 unsubscribe = subscribeIdentityInvalidation(session, () => { 236 // Successful fresh same-owner checks notify observers without revoking 237 // this captured generation. Only actual owner/capability loss retires it. 238 if (!ownership.current()) close(); 239 }); 240 return current() ? token : undefined; 241 } 242 export function prepareEnvelopeRole( 243 pair: EnvelopePreparation, 244 role: unknown, 245 review: unknown 246 ): Promise<EnvelopePreparationResult> { 247 return ( 248 pairs.get(pair)?.run(role, review) ?? Promise.resolve({ status: 'invalid' }) 249 ); 250 } 251 export function envelopePreparationSnapshot(pair: EnvelopePreparation) { 252 return pairs.get(pair)?.snapshot(); 253 } 254 export function preparedEnvelopeProof( 255 pair: EnvelopePreparation, 256 role: unknown 257 ) { 258 return pairs.get(pair)?.proof(role); 259 } 260 export function stopEnvelopePreparation(pair: EnvelopePreparation): void { 261 pairs.get(pair)?.stop(false); 262 } 263 export function expireEnvelopePreparationWait(pair: EnvelopePreparation): void { 264 pairs.get(pair)?.stop(true); 265 } 266 export function closeEnvelopePreparation(pair: EnvelopePreparation): void { 267 pairs.get(pair)?.close(); 268 }