composer-state.ts (10288B)
1 import { 2 identityMessagingOwnership, 3 subscribeIdentityInvalidation, 4 type IdentitySession 5 } from '../runtime/identity-session.ts'; 6 import { boundedUtf8 } from '../contracts/food-availability-v1/text.ts'; 7 import { PRIVATE_TRANSPORT_BUDGETS } from '../config/budgets.ts'; 8 import { buildEnquiryMessage, type EnquiryContext } from './enquiry-context.ts'; 9 import { 10 reservedSendSnapshot, 11 reservedSendRumorWire, 12 type ReservedSendIdentity 13 } from './send-identity.ts'; 14 import { 15 selfRecoveryPreparationSnapshot, 16 preparedSelfRecovery, 17 stopSelfRecoveryPreparation, 18 type SelfRecoveryPreparation 19 } from './prepare-send.ts'; 20 import { 21 selfRecoveryAcknowledgementSnapshot, 22 type SelfRecoveryAcknowledgement 23 } from '../persistence/private-sends.ts'; 24 25 declare const composerBrand: unique symbol; 26 export type PrivateComposer = Readonly<{ [composerBrand]: true }>; 27 type TextState = 28 | 'empty' 29 | 'unsaved' 30 | 'preparing' 31 | 'saved_encrypted' 32 | 'unknown_completion' 33 | 'needs_action'; 34 type Snapshot = Readonly<{ 35 revision: number; 36 dirty: boolean; 37 busy: boolean; 38 state: TextState; 39 pairState: 40 | 'unprepared' 41 | 'preparing' 42 | 'prepared' 43 | 'unknown_completion' 44 | 'needs_action'; 45 copy: string; 46 pairCopy: string; 47 }>; 48 type Controller = { 49 text(): string | undefined; 50 update(text: unknown, review: unknown): boolean; 51 snapshot(): Snapshot | undefined; 52 bind( 53 reserved: ReservedSendIdentity, 54 preparation: SelfRecoveryPreparation, 55 enquiry: EnquiryContext | undefined, 56 review: unknown 57 ): boolean; 58 discard(revision: unknown, review: unknown): boolean; 59 close(): void; 60 }; 61 const composers = new WeakMap<PrivateComposer, Controller>(); 62 63 // Private input is memory only. The controller has no storage, URL, logging, 64 // public-draft, signer or transport sink. Canonical message admission and all 65 // effects remain owned by the existing genuine intent/preparation workflow. 66 export function createPrivateComposer( 67 session: IdentitySession, 68 review: unknown 69 ): PrivateComposer | undefined { 70 if (typeof window === 'undefined' || review !== 'reviewed_private_composer') 71 return undefined; 72 const ownership = identityMessagingOwnership(session); 73 if (!ownership?.current()) return undefined; 74 let active = true, 75 body = '', 76 revision = 0, 77 unsubscribe = () => {}; 78 type Binding = { 79 revision: number; 80 preparation: SelfRecoveryPreparation; 81 owner: string; 82 command: string; 83 peer: string; 84 rumorHash: string; 85 createdAt: number; 86 }; 87 let binding: Binding | undefined; 88 let lastState: ReturnType<typeof selfRecoveryPreparationSnapshot>; 89 let acknowledgement: SelfRecoveryAcknowledgement | undefined; 90 function close() { 91 if (!active) return; 92 active = false; 93 body = ''; 94 if (binding) stopSelfRecoveryPreparation(binding.preparation); 95 binding = undefined; 96 lastState = undefined; 97 acknowledgement = undefined; 98 unsubscribe(); 99 unsubscribe = () => {}; 100 } 101 function current() { 102 if (!active || !ownership?.current()) { 103 close(); 104 return false; 105 } 106 return true; 107 } 108 function observe() { 109 if (!binding) return undefined; 110 const workflow = selfRecoveryPreparationSnapshot(binding.preparation); 111 if ( 112 workflow?.owner !== binding.owner || 113 workflow.command !== binding.command 114 ) 115 return undefined; 116 lastState = workflow; 117 return workflow; 118 } 119 function acknowledged() { 120 if (!binding) return false; 121 const workflow = selfRecoveryPreparationSnapshot(binding.preparation); 122 const actual = preparedSelfRecovery(binding.preparation); 123 // A genuine historical local fact may survive crypto retirement. A live 124 // controller explicitly losing its acknowledgement must not hide that loss. 125 if (workflow && !actual) acknowledgement = undefined; 126 const receipt = actual ?? acknowledgement, 127 saved = receipt && selfRecoveryAcknowledgementSnapshot(receipt); 128 const matches = 129 !!saved && 130 saved.owner === binding.owner && 131 saved.id === binding.command && 132 saved.peer === binding.peer && 133 saved.rumorHash === binding.rumorHash && 134 saved.createdAt === binding.createdAt; 135 if (matches) acknowledgement = receipt; 136 return matches; 137 } 138 function snapshot(): Snapshot | undefined { 139 if (!current()) return undefined; 140 const currentWorkflow = observe(), 141 workflow = 142 currentWorkflow ?? 143 (lastState 144 ? { 145 ...lastState, 146 state: 147 lastState.state === 'unknown_completion' 148 ? 'unknown_completion' 149 : 'needs_action', 150 busy: false 151 } 152 : undefined), 153 exact = binding?.revision === revision, 154 saved = exact && acknowledged(), 155 dirty = body.length > 0 && !saved; 156 const state: TextState = 157 body.length === 0 158 ? 'empty' 159 : saved 160 ? 'saved_encrypted' 161 : !exact 162 ? 'unsaved' 163 : workflow?.state === 'unknown_completion' 164 ? 'unknown_completion' 165 : workflow?.state === 'preparing' 166 ? 'preparing' 167 : workflow?.state === 'needs_action' || !workflow 168 ? 'needs_action' 169 : 'unsaved'; 170 return { 171 revision, 172 dirty, 173 busy: currentWorkflow?.busy ?? false, 174 state, 175 pairState: workflow?.pairState ?? 'unprepared', 176 copy: 177 state === 'saved_encrypted' 178 ? 'Saved encrypted in this browser' 179 : state === 'unknown_completion' 180 ? 'Encrypted save could not be confirmed. Keep this text and review the existing preparation.' 181 : state === 'preparing' 182 ? 'Private text is unsaved memory while encryption is preparing.' 183 : state === 'needs_action' 184 ? 'Private text has no acknowledged encrypted save in this browser. Keep editing or review preparation.' 185 : state === 'empty' 186 ? 'Private text stays in memory until encrypted capture.' 187 : 'Private text is unsaved memory.', 188 pairCopy: 189 workflow?.pairCopy ?? 'No paired delivery preparation is acknowledged.' 190 }; 191 } 192 function update(text: unknown, reviewed: unknown) { 193 if ( 194 reviewed !== 'reviewed_private_text' || 195 !current() || 196 typeof text !== 'string' || 197 !boundedUtf8(text, PRIVATE_TRANSPORT_BUDGETS.bodyBytes) 198 ) 199 return false; 200 if (body !== text) { 201 body = text; 202 revision++; 203 } 204 return true; 205 } 206 function bind( 207 reserved: ReservedSendIdentity, 208 preparation: SelfRecoveryPreparation, 209 enquiry: EnquiryContext | undefined, 210 reviewed: unknown 211 ) { 212 if (reviewed !== 'reviewed_composer_preparation' || !current()) 213 return false; 214 const previous = observe(); 215 if ( 216 (binding && !previous) || 217 previous?.busy || 218 previous?.state === 'unknown_completion' || 219 previous?.pairState === 'unknown_completion' 220 ) 221 return false; 222 const identity = reservedSendSnapshot(reserved), 223 wire = reservedSendRumorWire(reserved), 224 workflow = selfRecoveryPreparationSnapshot(preparation); 225 if ( 226 !identity || 227 !wire || 228 !workflow || 229 identity.owner !== ownership?.owner || 230 workflow.owner !== identity.owner || 231 workflow.command !== identity.id 232 ) 233 return false; 234 // This wire is available only from the genuine current reserved identity; 235 // no caller-provided body/hash can substitute for its canonical rumor. 236 let content: unknown; 237 try { 238 content = (JSON.parse(wire) as { content: unknown }).content; 239 } catch { 240 return false; 241 } 242 const expected = 243 enquiry === undefined 244 ? body 245 : buildEnquiryMessage(enquiry, body)?.content; 246 if (typeof expected !== 'string' || content !== expected) return false; 247 if ( 248 binding && 249 (binding.command !== identity.id || binding.preparation !== preparation) 250 ) 251 stopSelfRecoveryPreparation(binding.preparation); 252 binding = { 253 revision, 254 preparation, 255 owner: identity.owner, 256 command: identity.id, 257 peer: identity.peer, 258 rumorHash: identity.rumorHash, 259 createdAt: identity.createdAt 260 }; 261 lastState = undefined; 262 acknowledgement = undefined; 263 return true; 264 } 265 function discard(expectedRevision: unknown, reviewed: unknown) { 266 if ( 267 reviewed !== 'reviewed_discard_private_text' || 268 !current() || 269 expectedRevision !== revision 270 ) 271 return false; 272 // Retirement revokes continuations, but the shared SDK scheduler retains 273 // an unsettled extension job until the actual promise completes. 274 if (binding) stopSelfRecoveryPreparation(binding.preparation); 275 binding = undefined; 276 lastState = undefined; 277 acknowledgement = undefined; 278 body = ''; 279 revision++; 280 return true; 281 } 282 const token = Object.freeze({}) as PrivateComposer; 283 composers.set(token, { 284 text: () => (current() ? body : undefined), 285 update, 286 snapshot, 287 bind, 288 discard, 289 close 290 }); 291 unsubscribe = subscribeIdentityInvalidation(session, () => { 292 if (!ownership.current()) close(); 293 }); 294 return current() ? token : undefined; 295 } 296 export function updatePrivateComposerText( 297 token: PrivateComposer, 298 text: unknown, 299 review: unknown 300 ) { 301 return composers.get(token)?.update(text, review) ?? false; 302 } 303 export function privateComposerText(token: PrivateComposer) { 304 return composers.get(token)?.text(); 305 } 306 export function privateComposerSnapshot(token: PrivateComposer) { 307 return composers.get(token)?.snapshot(); 308 } 309 export function bindPrivateComposerPreparation( 310 token: PrivateComposer, 311 reserved: ReservedSendIdentity, 312 preparation: SelfRecoveryPreparation, 313 enquiry: EnquiryContext | undefined, 314 review: unknown 315 ) { 316 return ( 317 composers.get(token)?.bind(reserved, preparation, enquiry, review) ?? false 318 ); 319 } 320 export function discardPrivateComposer( 321 token: PrivateComposer, 322 revision: unknown, 323 review: unknown 324 ) { 325 return composers.get(token)?.discard(revision, review) ?? false; 326 } 327 export function closePrivateComposer(token: PrivateComposer) { 328 composers.get(token)?.close(); 329 composers.delete(token); 330 }