release(v4.8.0): sender-fingerprint attribution + Inbox.start race fix

Two unblocking changes for first-contact flows.

Sender attribution: relay captures shortHash(senderSigningKey) at
PUT time (after signature verification, no new trust surface) and
surfaces it on bridge push (IncomingMessage.from) + inbox-fetch
(FetchedBlob.from) + DecryptHandler raw arg. Apps receiving a prekey
envelope from a never-before-seen peer can now bootstrap X3DH via
shade.receive('fp:<hex>', env) — pre-4.8 the wire envelope didn't
authenticate the sender and there was no out-of-band hint to use.
Idempotent ALTER TABLE migrations for SQLite + Postgres add a
sender_fp TEXT column; legacy rows surface as from=undefined
(inter-version compat).

Inbox.start() race: pre-4.8 start() called register() fire-and-forget
AND schedulePoll(0) synchronously, so the first poll on a fresh
address often beat the register HTTP RTT and got SHADE_NOT_FOUND.
start() now defers; register() success kicks schedulePoll(0). Manual
tick() is unaffected (deliberate user action, no gating).

Both reported by Prism. Tests cover all five acceptance criteria
from the sender-attribution request (PUT capture, bridge surface,
fetch surface, inter-version compat, end-to-end pair smoke) plus
the three from the race-fix request.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

packages/shade-inbox/src/client.ts

@@ -40,6 +40,16 @@ export interface FetchedBlob {
   receivedAt: number;
   /** Absolute expiry time (ms since epoch) reported by the server. */
   expiresAt: number;
+  /**
+   * Sender fingerprint — 8-byte hex of SHA-256(senderSigningKey),
+   * captured by the relay at PUT time when the sender's signature was
+   * verified. Empty/undefined when the relay is pre-4.8 or the blob
+   * predates sender-fingerprint tracking. Use as an unknown-sender
+   * bootstrap label (`fp:<hex>`) for X3DH first-contact; the
+   * authoritative sender identity is recovered post-decrypt from the
+   * envelope itself, so `from` is a hint, not a trust anchor.
+   */
+  from?: string;
 }
 
 export interface FetchResult {
@@ -151,12 +161,18 @@ export class InboxClient {
     );
     const blobs = Array.isArray(json.blobs) ? json.blobs : [];
     return {
-      blobs: blobs.map((b: any) => ({
-        msgId: String(b.msgId),
-        ciphertext: fromBase64(String(b.ciphertext)),
-        receivedAt: Number(b.receivedAt),
-        expiresAt: Number(b.expiresAt),
-      })),
+      blobs: blobs.map((b: any): FetchedBlob => {
+        const out: FetchedBlob = {
+          msgId: String(b.msgId),
+          ciphertext: fromBase64(String(b.ciphertext)),
+          receivedAt: Number(b.receivedAt),
+          expiresAt: Number(b.expiresAt),
+        };
+        // V4.8 — relay-supplied sender fingerprint hint. Optional; absent
+        // on pre-4.8 relays or for blobs persisted before tracking landed.
+        if (typeof b.from === 'string' && b.from.length > 0) out.from = b.from;
+        return out;
+      }),
       cursor: Number(json.cursor ?? sinceCursor),
       hasMore: Boolean(json.hasMore),
     };

packages/shade-inbox/src/inbox.ts

@@ -16,9 +16,20 @@ import { InboxClientEvents, type InboxClientListener } from './events.js';
  * decrypt path it owns) and either return a sender-hint for telemetry
  * (the address the SDK extracted, or `null`) or throw to keep the blob
  * on the server for a later retry.
+ *
+ * V4.8: `raw.from` is the relay-captured sender fingerprint (8-byte hex
+ * of SHA-256 over the sender's signing key). Empty when the relay is
+ * pre-4.8 or didn't track the sender. Use it as the `fp:<hex>` bootstrap
+ * label for X3DH first-contact handshakes.
  */
 export type DecryptHandler = (
-  raw: { msgId: string; ciphertext: Uint8Array; receivedAt: number; expiresAt: number },
+  raw: {
+    msgId: string;
+    ciphertext: Uint8Array;
+    receivedAt: number;
+    expiresAt: number;
+    from?: string;
+  },
 ) => Promise<string | null | undefined> | string | null | undefined;
 
 export interface InboxOptions {
@@ -149,6 +160,14 @@ export class Inbox {
       signingKey: this.options.signingPublicKey,
     });
     this.registered = true;
+    // V4.8: gate the first poll on register success. `start()` calls
+    // `register()` fire-and-forget; without this kick, the very first
+    // `pollOnce()` (scheduled synchronously alongside register) would
+    // race the register HTTP RTT and return SHADE_NOT_FOUND. The
+    // pollOnce() guard skips polls until `registered === true`; this
+    // immediate schedule ensures we don't wait the full pollIntervalMs
+    // for the next attempt once register lands.
+    if (this.started) this.schedulePoll(0);
   }
 
   /** Drop the address from the server. Local queue/cursor are preserved. */
@@ -217,7 +236,11 @@ export class Inbox {
       this.scheduleRegisterRetry();
     });
     this.scheduleFlush();
-    this.schedulePoll(0);
+    // V4.8: do NOT schedule the first poll synchronously. `register()`
+    // success kicks `schedulePoll(0)` so the first poll fires after the
+    // server has acknowledged the address. Pre-fix this raced register
+    // and burned a 404 on every fresh-address `start()`.
+    if (this.registered) this.schedulePoll(0);
   }
 
   /** Stop background timers. Pending entries remain in the queue. */
@@ -375,12 +398,20 @@ export class Inbox {
 
     let senderHint: string | null = null;
     try {
-      const result = await this.incomingHandler({
+      const raw: {
+        msgId: string;
+        ciphertext: Uint8Array;
+        receivedAt: number;
+        expiresAt: number;
+        from?: string;
+      } = {
         msgId: blob.msgId,
         ciphertext: blob.ciphertext,
         receivedAt: blob.receivedAt,
         expiresAt: blob.expiresAt,
-      });
+      };
+      if (blob.from !== undefined) raw.from = blob.from;
+      const result = await this.incomingHandler(raw);
       senderHint = result ?? null;
     } catch (err) {
       this.events.emit('inbox.message_decrypt_failed', {