unwrap-admission.ts (11905B)
1 import { ExtensionSigner } from 'applesauce-signers'; 2 import type { UnsignedEvent } from 'applesauce-core/helpers'; 3 import { PRIVATE_TRANSPORT_BUDGETS } from '../config/budgets.ts'; 4 import { canonicalPublicKey } from '../contracts/public-key.ts'; 5 import { exactLocalFields } from '../contracts/local-records.ts'; 6 import { 7 incomingGiftWrapTags, 8 parseIncomingLayer, 9 readIncomingPairRumor 10 } from './incoming-wire.ts'; 11 import { 12 identityMessagingOwnership, 13 subscribeIdentityInvalidation, 14 disconnectIdentity, 15 type IdentitySession 16 } from '../runtime/identity-session.ts'; 17 import { 18 loadPrivateRecord, 19 type PrivateStorageRepository, 20 type PrivateStorageFailure 21 } from '../persistence/private-storage.ts'; 22 import { 23 privateRecordSnapshot, 24 privateRecordWire 25 } from '../persistence/private-records.ts'; 26 import { 27 verifyEnvelope, 28 verifiedEnvelopeSnapshot 29 } from './verified-envelope.ts'; 30 import { sealCiphertextV2 } from './seal-template.ts'; 31 import { 32 browserExtensionScheduler, 33 runExtensionAction, 34 callExtension, 35 stopExtensionAction, 36 markExtensionWaitExpired, 37 type ExtensionAction 38 } from './extension-scheduler.ts'; 39 40 const unsignedFields = [ 41 'id', 42 'pubkey', 43 'created_at', 44 'kind', 45 'tags', 46 'content' 47 ]; 48 const signedFields = [...unsignedFields, 'sig']; 49 function outerLayer(raw: unknown, owner: string) { 50 const parsed = parseIncomingLayer( 51 raw, 52 PRIVATE_TRANSPORT_BUDGETS.envelopeBytes 53 ); 54 if ( 55 !exactLocalFields(parsed, signedFields) || 56 parsed.kind !== 1059 || 57 !incomingGiftWrapTags(parsed.tags, owner) || 58 !sealCiphertextV2(parsed.content) 59 ) 60 return undefined; 61 const verified = verifyEnvelope(raw); 62 return verified.ok ? verifiedEnvelopeSnapshot(verified.value) : undefined; 63 } 64 function sealLayer(raw: unknown) { 65 const parsed = parseIncomingLayer(raw, PRIVATE_TRANSPORT_BUDGETS.sealBytes); 66 if ( 67 !exactLocalFields(parsed, signedFields) || 68 parsed.kind !== 13 || 69 !Array.isArray(parsed.tags) || 70 parsed.tags.length !== 0 || 71 !sealCiphertextV2(parsed.content) 72 ) 73 return undefined; 74 const verified = verifyEnvelope(raw); 75 return verified.ok ? verifiedEnvelopeSnapshot(verified.value) : undefined; 76 } 77 function rumorLayer( 78 raw: unknown, 79 sender: string 80 ): Readonly<UnsignedEvent & { id: string }> | undefined { 81 return readIncomingPairRumor(raw, sender)?.original; 82 } 83 // Detached inspection only: supplied plaintext cannot prove ciphertext 84 // correspondence. Only the scoped actual SDK issuer below mints nested custody. 85 // Owner room membership and inbound/archive role are a separate admission. 86 export function verifyReceivedLayerData( 87 outerRaw: unknown, 88 sealRaw: unknown, 89 rumorRaw: unknown, 90 expectedOwner: unknown 91 ): boolean { 92 const owner = canonicalPublicKey(expectedOwner); 93 if (!owner) return false; 94 try { 95 const outer = outerLayer(outerRaw, owner), 96 seal = sealLayer(sealRaw); 97 return !!outer && !!seal && !!rumorLayer(rumorRaw, seal.pubkey); 98 } catch { 99 return false; 100 } 101 } 102 103 declare const readerBrand: unique symbol; 104 declare const nestedBrand: unique symbol; 105 export type ReceivedUnwrap = Readonly<{ [readerBrand]: true }>; 106 export type ReceivedNestedEnvelope = Readonly<{ [nestedBrand]: true }>; 107 type Snapshot = Readonly<{ 108 owner: string; 109 outerId: string; 110 outerWire: string; 111 sealWire: string; 112 rumorWire: string; 113 }>; 114 export type ReceivedUnwrapResult = 115 | Readonly<{ status: 'authenticated'; envelope: ReceivedNestedEnvelope }> 116 | Readonly<{ 117 status: 118 | PrivateStorageFailure 119 | 'invalid' 120 | 'stopped' 121 | 'busy' 122 | 'refused' 123 | 'mismatch' 124 | 'lost_evidence'; 125 }>; 126 type Reader = { 127 run(): Promise<ReceivedUnwrapResult>; 128 stop(expired: boolean): void; 129 }; 130 const readers = new WeakMap<ReceivedUnwrap, Reader>(); 131 const nested = new WeakMap< 132 ReceivedNestedEnvelope, 133 { snapshot: Snapshot; session: symbol; current: () => boolean } 134 >(); 135 // No common unwrap helper/cache or caller event objects are consulted. Original 136 // owner storage finishes each IDB transaction before serialized SDK work begins. 137 export function captureReceivedUnwrap( 138 repository: PrivateStorageRepository, 139 session: IdentitySession, 140 eventId: unknown, 141 review: unknown 142 ): ReceivedUnwrap | undefined { 143 if ( 144 typeof window === 'undefined' || 145 review !== 'reviewed_inbox_unlock' || 146 typeof eventId !== 'string' || 147 !/^[0-9a-f]{64}$/u.test(eventId) 148 ) 149 return undefined; 150 const captured = identityMessagingOwnership(session); 151 if (!captured?.current()) return undefined; 152 const ownership = captured, 153 id = eventId; 154 let stopped = false, 155 started = false, 156 active: ExtensionAction | undefined, 157 proof: ReceivedNestedEnvelope | undefined, 158 unsubscribe = () => {}; 159 const current = () => !stopped && ownership.current(); 160 function stop(expired: boolean) { 161 stopped = true; 162 if (active) { 163 if (expired) markExtensionWaitExpired(active); 164 else stopExtensionAction(active); 165 } 166 if (proof) nested.delete(proof); 167 proof = undefined; 168 unsubscribe(); 169 unsubscribe = () => {}; 170 } 171 function port() { 172 try { 173 if (!current()) return undefined; 174 const cipher = new ExtensionSigner().nip44; 175 if (!cipher || !current() || typeof cipher.decrypt !== 'function') 176 return undefined; 177 const decrypt = cipher.decrypt.bind(cipher); 178 return current() ? { decrypt } : undefined; 179 } catch { 180 return undefined; 181 } 182 } 183 async function fresh(action: ExtensionAction) { 184 if (!current()) return false; 185 const result = await callExtension(action, 'key', () => 186 new ExtensionSigner().getPublicKey() 187 ); 188 if (!current()) return false; 189 if ( 190 result.status !== 'settled' || 191 !result.current || 192 result.value !== ownership.owner || 193 !port() 194 ) { 195 disconnectIdentity(session); 196 return false; 197 } 198 return current(); 199 } 200 async function run(): Promise<ReceivedUnwrapResult> { 201 if (started || !current()) return { status: 'stopped' }; 202 started = true; 203 try { 204 const loaded = await loadPrivateRecord( 205 repository, 206 'received_envelopes', 207 id 208 ); 209 if (!current()) return { status: 'stopped' }; 210 if (!loaded.ok) 211 return { 212 status: 213 loaded.reason === 'invalid_record' ? 'lost_evidence' : loaded.reason 214 }; 215 const record = privateRecordSnapshot(loaded.value, ownership.owner, id), 216 storedWire = privateRecordWire(loaded.value, ownership.owner, id); 217 if (!record || record.family !== 'received_envelope' || !storedWire) 218 return { status: 'invalid_scope' }; 219 const outer = outerLayer(record.outer, ownership.owner); 220 if (!outer || outer.id !== id) return { status: 'mismatch' }; 221 const scheduler = browserExtensionScheduler(); 222 if (!scheduler) return { status: 'unavailable' }; 223 const result = await runExtensionAction( 224 scheduler, 225 { 226 owner: ownership.owner, 227 session: ownership.session, 228 operation: Symbol() 229 }, 230 current, 231 async (action): Promise<ReceivedUnwrapResult> => { 232 active = action; 233 if (!(await fresh(action))) return { status: 'stopped' }; 234 const outerPort = port(); 235 if (!outerPort || !current()) return { status: 'stopped' }; 236 const opened = await callExtension(action, 'decrypt', () => 237 outerPort.decrypt(outer.pubkey, outer.content) 238 ); 239 if (!current()) return { status: 'stopped' }; 240 if (opened.status !== 'settled' || !opened.current) 241 return { 242 status: opened.status === 'denied' ? 'refused' : 'stopped' 243 }; 244 const seal = sealLayer(opened.value); 245 if (!seal || typeof opened.value !== 'string') 246 return { status: 'mismatch' }; 247 const sealWire = opened.value; 248 if (!(await fresh(action))) return { status: 'stopped' }; 249 const innerPort = port(); 250 if (!innerPort || !current()) return { status: 'stopped' }; 251 const decrypted = await callExtension(action, 'decrypt', () => 252 innerPort.decrypt(seal.pubkey, seal.content) 253 ); 254 if (!current()) return { status: 'stopped' }; 255 if (decrypted.status !== 'settled' || !decrypted.current) 256 return { 257 status: decrypted.status === 'denied' ? 'refused' : 'stopped' 258 }; 259 if ( 260 typeof decrypted.value !== 'string' || 261 !rumorLayer(decrypted.value, seal.pubkey) 262 ) 263 return { status: 'mismatch' }; 264 const rumorWire = decrypted.value; 265 if (!(await fresh(action))) return { status: 'stopped' }; 266 const readback = await loadPrivateRecord( 267 repository, 268 'received_envelopes', 269 id 270 ); 271 if (!current()) return { status: 'stopped' }; 272 if (!readback.ok) 273 return { 274 status: 275 readback.reason === 'invalid_record' 276 ? 'lost_evidence' 277 : readback.reason 278 }; 279 if ( 280 privateRecordWire(readback.value, ownership.owner, id) !== 281 storedWire 282 ) 283 return { status: 'conflict' }; 284 // Last actual storage readback is followed by no SDK/asynchronous 285 // wait before minting original retained-record custody. 286 const token = Object.freeze({}) as ReceivedNestedEnvelope; 287 nested.set(token, { 288 session: ownership.session, 289 snapshot: { 290 owner: ownership.owner, 291 outerId: id, 292 outerWire: record.outer, 293 sealWire, 294 rumorWire 295 }, 296 current 297 }); 298 proof = token; 299 return { status: 'authenticated', envelope: token }; 300 } 301 ); 302 if (!current()) return { status: 'stopped' }; 303 if (result.status === 'busy') return { status: 'busy' }; 304 return result.status === 'completed' && 'value' in result && result.value 305 ? result.value 306 : { status: result.status === 'denied' ? 'refused' : 'stopped' }; 307 } catch { 308 return { status: current() ? 'mismatch' : 'stopped' }; 309 } finally { 310 active = undefined; 311 if (!proof) { 312 unsubscribe(); 313 unsubscribe = () => {}; 314 } 315 } 316 } 317 const token = Object.freeze({}) as ReceivedUnwrap; 318 readers.set(token, { run, stop }); 319 unsubscribe = subscribeIdentityInvalidation(session, () => { 320 if (!ownership.current()) stop(false); 321 }); 322 return current() ? token : undefined; 323 } 324 export function unwrapReceivedEnvelope( 325 reader: ReceivedUnwrap 326 ): Promise<ReceivedUnwrapResult> { 327 return readers.get(reader)?.run() ?? Promise.resolve({ status: 'invalid' }); 328 } 329 export function stopReceivedUnwrap(reader: ReceivedUnwrap): void { 330 readers.get(reader)?.stop(false); 331 } 332 export function expireReceivedUnwrapWait(reader: ReceivedUnwrap): void { 333 readers.get(reader)?.stop(true); 334 } 335 export function receivedNestedEnvelopeSnapshot( 336 token: ReceivedNestedEnvelope 337 ): Snapshot | undefined { 338 const saved = nested.get(token); 339 return saved?.current() 340 ? (JSON.parse(JSON.stringify(saved.snapshot)) as Snapshot) 341 : undefined; 342 } 343 344 // HCP093 original-generation custody port. This observation is not a Send, 345 // persistence, inbox-readiness or AUTH capability. Structural copies never 346 // replace the original nested proof in the WeakMap. 347 export function receivedNestedEnvelopeOwnership( 348 token: ReceivedNestedEnvelope 349 ): 350 Readonly<{ owner: string; session: symbol; current(): boolean }> | undefined { 351 const saved = nested.get(token); 352 return saved?.current() 353 ? { 354 owner: saved.snapshot.owner, 355 session: saved.session, 356 current: saved.current 357 } 358 : undefined; 359 }