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-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/inbox-server",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-inbox-server/src/bridge.ts

@@ -497,6 +497,8 @@ interface BlobRow {
   ciphertext: Uint8Array;
   receivedAt: number;
   expiresAt: number;
+  /** V4.8 — relay-captured sender fingerprint. Optional for legacy rows. */
+  senderFp?: string;
 }
 
 interface BlobWriter {
@@ -542,13 +544,26 @@ function serializeBlob(blob: BlobRow): {
   ciphertext: string;
   receivedAt: number;
   expiresAt: number;
+  from?: string;
 } {
-  return {
+  const out: {
+    msgId: string;
+    ciphertext: string;
+    receivedAt: number;
+    expiresAt: number;
+    from?: string;
+  } = {
     msgId: blob.msgId,
     ciphertext: toBase64(blob.ciphertext),
     receivedAt: blob.receivedAt,
     expiresAt: blob.expiresAt,
   };
+  // V4.8 — relay-captured sender fingerprint. The transport-bridge
+  // wire format already accepts `from`; populating it lets receivers
+  // bootstrap unknown-sender first-contact via `shade.receive('fp:<hex>',
+  // env)` without requiring an out-of-band sender hint.
+  if (blob.senderFp) out.from = blob.senderFp;
+  return out;
 }
 
 function buildPollResponse(blobs: BlobRow[], sinceFallback: number): {

packages/shade-inbox-server/src/memory-store.ts

@@ -5,6 +5,7 @@ interface BlobRow {
   ciphertext: Uint8Array;
   receivedAt: number;
   expiresAt: number;
+  senderFp?: string;
 }
 
 /**
@@ -33,6 +34,7 @@ export class MemoryInboxStore implements InboxStore {
     msgId: string;
     ciphertext: Uint8Array;
     expiresAt: number;
+    senderFp?: string;
   }): Promise<{ created: boolean; receivedAt: number }> {
     const list = this.blobs.get(args.address) ?? [];
     const existing = list.find((r) => r.msgId === args.msgId);
@@ -41,12 +43,14 @@ export class MemoryInboxStore implements InboxStore {
     // multiple blobs land in the same millisecond.
     const receivedAt = Math.max(this.nextReceivedAt + 1, Date.now());
     this.nextReceivedAt = receivedAt;
-    list.push({
+    const row: BlobRow = {
       msgId: args.msgId,
       ciphertext: new Uint8Array(args.ciphertext),
       receivedAt,
       expiresAt: args.expiresAt,
-    });
+    };
+    if (args.senderFp !== undefined) row.senderFp = args.senderFp;
+    list.push(row);
     this.blobs.set(args.address, list);
     return { created: true, receivedAt };
   }
@@ -56,18 +60,36 @@ export class MemoryInboxStore implements InboxStore {
     sinceCursor: number;
     now: number;
     limit: number;
-  }): Promise<Array<{ msgId: string; ciphertext: Uint8Array; receivedAt: number; expiresAt: number }>> {
+  }): Promise<
+    Array<{
+      msgId: string;
+      ciphertext: Uint8Array;
+      receivedAt: number;
+      expiresAt: number;
+      senderFp?: string;
+    }>
+  > {
     const list = this.blobs.get(args.address) ?? [];
     return list
       .filter((r) => r.receivedAt > args.sinceCursor && r.expiresAt > args.now)
       .sort((a, b) => a.receivedAt - b.receivedAt)
       .slice(0, args.limit)
-      .map((r) => ({
-        msgId: r.msgId,
-        ciphertext: new Uint8Array(r.ciphertext),
-        receivedAt: r.receivedAt,
-        expiresAt: r.expiresAt,
-      }));
+      .map((r) => {
+        const out: {
+          msgId: string;
+          ciphertext: Uint8Array;
+          receivedAt: number;
+          expiresAt: number;
+          senderFp?: string;
+        } = {
+          msgId: r.msgId,
+          ciphertext: new Uint8Array(r.ciphertext),
+          receivedAt: r.receivedAt,
+          expiresAt: r.expiresAt,
+        };
+        if (r.senderFp !== undefined) out.senderFp = r.senderFp;
+        return out;
+      });
   }
 
   async deleteBlob(address: string, msgId: string): Promise<boolean> {

packages/shade-inbox-server/src/routes.ts

@@ -255,11 +255,19 @@ export function createInboxRoutes(
       );
     }
 
+    // V4.8: capture sender fingerprint at PUT time. The sender's
+    // signing key was just verified for this request, so the fingerprint
+    // is bound to the same authentication path that authorized the
+    // store. Surfaced on bridge push + inbox-fetch responses to
+    // bootstrap unknown-sender first-contact (X3DH pair handshake).
+    const senderFp = await shortHash(senderKey);
+
     const result = await store.putBlob({
       address,
       msgId,
       ciphertext: ctBytes,
       expiresAt,
+      senderFp,
     });
     if (result.created) {
       events?.emit('inbox.blob_stored', {
@@ -319,12 +327,22 @@ export function createInboxRoutes(
     let bytes = 0;
     const blobs = rows.map((r) => {
       bytes += r.ciphertext.length;
-      return {
+      const out: {
+        msgId: string;
+        ciphertext: string;
+        receivedAt: number;
+        expiresAt: number;
+        from?: string;
+      } = {
         msgId: r.msgId,
         ciphertext: toBase64(r.ciphertext),
         receivedAt: r.receivedAt,
         expiresAt: r.expiresAt,
       };
+      // V4.8: surface sender fingerprint when present. Empty for blobs
+      // persisted by a pre-4.8 relay that didn't track sender provenance.
+      if (r.senderFp) out.from = r.senderFp;
+      return out;
     });
     const nextCursor = rows.length > 0 ? rows[rows.length - 1]!.receivedAt : sinceCursor;
 

packages/shade-inbox-server/src/store.ts

@@ -36,12 +36,20 @@ export interface InboxStore {
    * **Idempotent**: if a row already exists for `(address, msgId)` the
    * implementation MUST return `{ created: false }` and leave the existing
    * row untouched. A fresh insert returns `{ created: true, receivedAt }`.
+   *
+   * `senderFp` (V4.8+) is the 8-byte hex of SHA-256(senderSigningKey)
+   * — captured at PUT time when the relay verified the sender's
+   * signature. Optional so legacy 4.7 callers compile, but populated by
+   * `createInboxRoutes` from 4.8 onward and surfaced on bridge push +
+   * inbox-fetch responses to bootstrap unknown-sender first-contact
+   * (X3DH pair handshake).
    */
   putBlob(args: {
     address: string;
     msgId: string;
     ciphertext: Uint8Array;
     expiresAt: number;
+    senderFp?: string;
   }): Promise<{ created: boolean; receivedAt: number }>;
 
   /**
@@ -57,7 +65,20 @@ export interface InboxStore {
     sinceCursor: number;
     now: number;
     limit: number;
-  }): Promise<Array<{ msgId: string; ciphertext: Uint8Array; receivedAt: number; expiresAt: number }>>;
+  }): Promise<
+    Array<{
+      msgId: string;
+      ciphertext: Uint8Array;
+      receivedAt: number;
+      expiresAt: number;
+      /**
+       * Sender fingerprint — 8-byte hex of SHA-256(senderSigningKey)
+       * captured at PUT time. Empty/undefined for blobs persisted by a
+       * pre-4.8 relay that didn't track sender provenance.
+       */
+      senderFp?: string;
+    }>
+  >;
 
   /**
    * Delete a single blob by `(address, msgId)`. Returns true if a row was