@uuaid/pillar 0.2.0-alpha.12 → 0.2.0-alpha.16

package/src/blob/http.mjs

@@ -0,0 +1,196 @@
+import { createHash } from "node:crypto";
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain } from "../identity/keychain.mjs";
+import {
+  BlobBrokerError,
+  BlobExpiryError,
+  BlobFetchError,
+  BlobIntegrityError,
+  BlobNotFoundError,
+  BlobSenderKeyError,
+  BlobUploadError,
+} from "./blob.mjs";
+
+export const PILLAR_BLOB_AUDIENCE = "uuaid:pillar-blob:v1";
+
+function payloadHash(payload) {
+  return `0x${createHash("sha256").update(jcs(payload)).digest("hex")}`;
+}
+
+function signedRequest(keychain, keyId, challenge, request) {
+  if (!keyId) throw new BlobBrokerError("blob-broker-key-id-required", "a registry-bound presentation key id is required");
+  const payload = { v: 1, audience: PILLAR_BLOB_AUDIENCE, challenge, request };
+  return {
+    payload,
+    payloadHash: payloadHash(payload),
+    signatures: [{
+      alg: "ed25519",
+      keyId,
+      publicKey: keychain._identity.publicKeyHex,
+      signature: keychain.sign(Buffer.from(jcs(payload), "utf-8")).toString("hex"),
+      created: new Date().toISOString(),
+    }],
+  };
+}
+
+function safeBase(url) {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:" && parsed.hostname !== "127.0.0.1" && parsed.hostname !== "localhost") {
+    throw new BlobBrokerError("blob-broker-insecure-url", "blob broker must use HTTPS");
+  }
+  return parsed.href.replace(/\/+$/, "");
+}
+
+/** HTTP client for the UUAID broker. URLs are returned only to the live caller. */
+export class PillarBlobHttpClient {
+  constructor({ baseUrl = "https://api.uuaid.org", keychain, keyId, fetchImpl = globalThis.fetch, timeoutMs = 15_000 } = {}) {
+    if (!keychain?._identity) throw new BlobBrokerError("blob-broker-no-identity", "loaded keychain required");
+    if (typeof fetchImpl !== "function") throw new BlobBrokerError("blob-broker-no-fetch", "fetch implementation required");
+    this.baseUrl = safeBase(baseUrl);
+    this.keychain = keychain;
+    this.keyId = keyId;
+    this.fetch = fetchImpl;
+    this.timeoutMs = timeoutMs;
+    this._trust = null;
+  }
+
+  async _json(path, { method = "POST", body } = {}) {
+    let response;
+    try {
+      response = await this.fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: body === undefined ? undefined : { "content-type": "application/json" },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (error) {
+      throw new BlobBrokerError("blob-broker-unreachable", `blob broker request failed: ${error.message}`);
+    }
+    const parsed = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      const code = response.status === 404 ? "blob-broker-not-found"
+        : response.status === 410 ? "blob-broker-expired"
+          : response.status === 409 ? "blob-broker-replay"
+            : "blob-broker-rejected";
+      throw new BlobBrokerError(code, parsed.error ?? `blob broker returned ${response.status}`, response.status);
+    }
+    return parsed;
+  }
+
+  challenge(action, objectId = null) {
+    return this._json("/pillar/blobs/challenge", {
+      body: {
+        action,
+        agent_uuaid: this.keychain._identity.uuaid,
+        ...(objectId ? { object_id: objectId } : {}),
+      },
+    }).then((body) => body.challenge);
+  }
+
+  reserve(challenge, { recipient, ciphertextSha256, ciphertextBytes, expiresAt }) {
+    return this._json("/pillar/blobs/reserve", {
+      body: signedRequest(this.keychain, this.keyId, challenge, {
+        action: "reserve",
+        agent_uuaid: this.keychain._identity.uuaid,
+        recipient_uuaid: recipient,
+        ciphertext_sha256: ciphertextSha256,
+        ciphertext_bytes: ciphertextBytes,
+        expires_at: expiresAt,
+      }),
+    });
+  }
+
+  finalize(objectId) {
+    return this.challenge("finalize", objectId).then((challenge) => this._json("/pillar/blobs/finalize", {
+      body: signedRequest(this.keychain, this.keyId, challenge, {
+        action: "finalize",
+        agent_uuaid: this.keychain._identity.uuaid,
+      }),
+    }));
+  }
+
+  redeem(objectId) {
+    return this.challenge("redeem", objectId).then((challenge) => this._json("/pillar/blobs/redeem", {
+      body: signedRequest(this.keychain, this.keyId, challenge, {
+        action: "redeem",
+        agent_uuaid: this.keychain._identity.uuaid,
+      }),
+    }));
+  }
+
+  async upload(ticket, ciphertext) {
+    try {
+      const response = await this.fetch(ticket.url, {
+        method: "PUT",
+        headers: ticket.headers,
+        body: ciphertext,
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+      if (!response.ok) throw new Error(`upload returned ${response.status}`);
+    } catch (error) {
+      throw new BlobUploadError(`temporary blob upload failed: ${error.message}`, error);
+    }
+  }
+
+  async download(ticket) {
+    let response;
+    try {
+      response = await this.fetch(ticket.url, { signal: AbortSignal.timeout(this.timeoutMs) });
+    } catch (error) {
+      throw new BlobFetchError(`temporary blob download failed: ${error.message}`, error);
+    }
+    if (response.status === 404) throw new BlobNotFoundError("temporary-object");
+    if (response.status === 403) throw new BlobExpiryError("temporary blob download capability expired");
+    if (!response.ok) throw new BlobFetchError(`temporary blob download returned ${response.status}`);
+    return Buffer.from(await response.arrayBuffer());
+  }
+
+  async _registryTrust() {
+    if (this._trust && this._trust.until > Date.now()) return this._trust.value;
+    const value = await this._json("/.well-known/uuaid-registry.json", { method: "GET" });
+    if (value.provisioned !== true || !Array.isArray(value.keys)) {
+      throw new BlobSenderKeyError("registry trust root is not provisioned", "unknown", "unprovisioned");
+    }
+    this._trust = { value, until: Date.now() + 300_000 };
+    return value;
+  }
+
+  /** Fail closed unless a fresh registry-signed badge names this exact active key. */
+  async assertRegistryActiveSender(sender, expectedPublicKey) {
+    const trust = await this._registryTrust();
+    const badge = await this._json(`/iaaso/v1/badge/${encodeURIComponent(sender)}`, { method: "GET" });
+    const presentation = badge?.payload?.subject?.presentationKey;
+    const keyMatches = badge?.payload?.subject?.uuaid === sender
+      && presentation?.alg === "ed25519"
+      && presentation?.publicKey?.toLowerCase() === expectedPublicKey?.toLowerCase();
+    const fresh = Number.isFinite(Date.parse(badge?.payload?.freshUntil)) && Date.parse(badge.payload.freshUntil) > Date.now();
+    const hashMatches = badge?.payloadHash === payloadHash(badge?.payload);
+    const registrySignature = Array.isArray(badge?.signatures)
+      ? badge.signatures.find((signature) => {
+        if (signature.alg !== "ed25519") return false;
+        const pinned = trust.keys.find((key) => key.keyId === signature.keyId && key.alg === "ed25519" && key.retired !== true);
+        if (!pinned || pinned.publicKey.toLowerCase() !== signature.publicKey?.toLowerCase()) return false;
+        try {
+          return Keychain.verifyDetached(signature.publicKey, Buffer.from(jcs(badge.payload), "utf-8"), Buffer.from(signature.signature, "hex"));
+        } catch (_error) { return false; }
+      })
+      : null;
+    if (!keyMatches || !fresh || !hashMatches || !registrySignature) {
+      throw new BlobSenderKeyError("sender presentation key is not registry-active", sender, "inactive");
+    }
+    return "active";
+  }
+
+  crossCheckRedemption(ref, brokerRecord) {
+    if (
+      brokerRecord?.object_id !== ref.object ||
+      brokerRecord?.sender_uuaid !== ref.sender ||
+      brokerRecord?.recipient_uuaid !== ref.recipient ||
+      brokerRecord?.ciphertext_sha256 !== ref.hash ||
+      brokerRecord?.ciphertext_bytes !== ref.size ||
+      brokerRecord?.expires_at !== ref.expiry
+    ) {
+      throw new BlobIntegrityError("broker metadata does not match the signed blob-ref");
+    }
+  }
+}

package/src/blob/store.mjs

@@ -0,0 +1,55 @@
+/**
+ * Blob stores — where encrypted blob objects (ciphertext only) live while
+ * they wait to be redeemed.  Stores hold NO plaintext and NO key material:
+ * the DEK travels only inside the sealed envelope's blob-ref.
+ *
+ * Temporary-bucket semantics: objects are ephemeral; the blob-ref carries
+ * the expiry and the receive path re-checks it.  Stores SHOULD garbage-
+ * collect expired objects, but an object living past its expiry is inert —
+ * the ref is refused before any fetch result is trusted.
+ */
+import { mkdirSync } from "node:fs";
+import { readFile, writeFile, rm, access } from "node:fs/promises";
+import { join } from "node:path";
+import { BlobUploadError } from "./blob.mjs";
+
+export class MemoryBlobStore {
+  constructor() { this._map = new Map(); }
+  async put(object, buf) { this._map.set(object, Buffer.from(buf)); return { object, bytes: buf.length }; }
+  async get(object) { return this._map.get(object) ?? null; }
+  async has(object) { return this._map.has(object); }
+  async delete(object) { return this._map.delete(object); }
+  get size() { return this._map.size; }
+}
+
+export class FsBlobStore {
+  constructor({ dir }) {
+    if (!dir) throw new Error("FsBlobStore: dir required");
+    this.dir = dir;
+    this._ready = mkdirSync(dir, { recursive: true });
+  }
+  _path(object) {
+    // Object names are opaque 256-bit hex ids; encode defensively anyway.
+    return join(this.dir, encodeURIComponent(object));
+  }
+  async put(object, buf) {
+    try {
+      await writeFile(this._path(object), buf);
+      return { object, bytes: buf.length };
+    } catch (e) {
+      throw new BlobUploadError(`FsBlobStore write failed for ${object}: ${e.message}`, e);
+    }
+  }
+  async get(object) {
+    try { return await readFile(this._path(object)); }
+    catch (e) { if (e?.code === "ENOENT") return null; throw e; }
+  }
+  async has(object) {
+    try { await access(this._path(object)); return true; }
+    catch (_e) { return false; }
+  }
+  async delete(object) {
+    try { await rm(this._path(object), { force: true }); return true; }
+    catch (_e) { return false; }
+  }
+}

package/src/identity/keychain.mjs

@@ -15,6 +15,22 @@ import { randomBytes, createHash, generateKeyPairSync, sign, verify, createPubli
 
 const KEYCHAIN_VERSION = 1;
 
+/**
+ * Derive a stable, publishable local id from a raw Ed25519 public key.  This
+ * makes the UUAID self-authenticating: given the UUAID, anyone can
+ * independently check that the public key hashes to the expected local-id.
+ *
+ * Public because consumers verifying a UUAID against a public key need it
+ * without reaching into `Keychain._localIdFromKey`.
+ */
+export function localIdFromKey(rawPub) {
+  const h = createHash("sha256").update(rawPub).digest();
+  // First 16 bytes -> UUID-style dash format for readability.
+  const b = h.slice(0, 16);
+  const hex = Buffer.from(b).toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
 export class Keychain {
   constructor(path) {
     this.path = path;
@@ -48,16 +64,17 @@ export class Keychain {
     };
   }
 
-  static _localIdFromKey(rawPub) {
-    // Derive a stable, publishable local id from the public key.  This makes
-    // the UUAID self-authenticating: given the UUAID, anyone can independently
-    // check that the public key hashes to the expected local-id.
-    const h = createHash("sha256").update(rawPub).digest();
-    // First 16 bytes -> UUID-style dash format for readability.
-    const b = h.slice(0, 16);
-    const hex = Buffer.from(b).toString("hex");
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
-  }
+  /**
+   * Derive the local-id from a raw Ed25519 public key.
+   *
+   * Kept on the class for the call sites that already reach for it; the
+   * implementation is the module-level `localIdFromKey`, which is the public
+   * export.
+   */
+  static localIdFromKey = localIdFromKey;
+
+  /** @deprecated Alias kept for compatibility — use `localIdFromKey`. */
+  static _localIdFromKey = localIdFromKey;
 
   /**
    * Load an identity from disk.

package/src/identity/tier.mjs

@@ -9,11 +9,22 @@
  * self-authenticating design.  The wire API is unchanged: a grant only
  * raises the holder's rate/size budgets at carriers that trust the issuer.
  *
- * Qualification itself is off-wire (the foundation's review process decides
- * WHO gets a grant); this module only makes grants unforgeable and portable.
+ * Qualification has two routes. The original is off-wire: the foundation's
+ * review process decides WHO gets a grant. The second is earned on-wire —
+ * operators who keep a public seed alive are promoted by the seed registry
+ * (net/seed-registry.mjs) and issued a grant automatically, no review. This
+ * module only makes grants unforgeable and portable; it does not care which
+ * route produced one.
  *
  * Grant shape (JCS-signed over every field except `sig`):
  *   { v: 1, uuaid, tier, envelopesPerMin, maxBodyBytes, expires, issuer, sig }
+ *   ...plus optional { priority: true, seedTier, seedUrl } on earned grants.
+ *
+ * `priority` is the wire half of priority delivery: a carrier that trusts the
+ * issuer admits the holder from a reserved lane when it is otherwise shedding
+ * load. It is inside the signed body, so it cannot be added to a grant after
+ * issue. Older carriers that predate the field verify such a grant unchanged
+ * (JCS covers whatever keys are present) and simply ignore the privilege.
  */
 import { createHash } from "node:crypto";
 import { jcs } from "./jcs.mjs";
@@ -42,7 +53,7 @@ function signable(grant) {
  * Rates/sizes default from the tier ladder; explicit overrides are clamped
  * to the absolute ceilings.
  */
-export function makeTierGrant(keychain, { uuaid, tier, envelopesPerMin, maxBodyBytes, expires }) {
+export function makeTierGrant(keychain, { uuaid, tier, envelopesPerMin, maxBodyBytes, expires, priority, seedTier, seedUrl }) {
   if (!TIER_DEFAULTS[tier]) throw new Error(`unknown tier "${tier}" (${Object.keys(TIER_DEFAULTS).join("|")})`);
   if (!uuaid?.startsWith("uuaid:")) throw new Error("grant subject must be a uuaid:...");
   if (!expires || !Number.isFinite(Date.parse(expires))) throw new Error("expires must be an ISO date");
@@ -54,6 +65,12 @@ export function makeTierGrant(keychain, { uuaid, tier, envelopesPerMin, maxBodyB
     maxBodyBytes: Math.min(maxBodyBytes ?? TIER_DEFAULTS[tier].maxBodyBytes, ABSOLUTE_MAX_BODY),
     expires,
     issuer: keychain._identity.publicKeyHex,
+    // Optional fields are omitted rather than set false/null so that a plain
+    // grant's signed body stays byte-identical to what pre-priority issuers
+    // produced.
+    ...(priority ? { priority: true } : {}),
+    ...(seedTier ? { seedTier } : {}),
+    ...(seedUrl ? { seedUrl } : {}),
   };
   grant.sig = keychain.sign(Buffer.from(signable(grant), "utf-8")).toString("hex");
   return grant;
@@ -72,6 +89,10 @@ export function verifyTierGrant(grant, trustedIssuers, now = Date.now()) {
   if (!(grant.envelopesPerMin <= ABSOLUTE_MAX_RATE) || !(grant.maxBodyBytes <= ABSOLUTE_MAX_BODY)) {
     return { ok: false, reason: "over-ceiling" };
   }
+  // Fail closed on a malformed privilege: `priority` is either absent or the
+  // boolean true. Anything else (a truthy string, 1, an object) is a grant we
+  // do not understand, and understanding it wrongly grants a reserved lane.
+  if ("priority" in grant && grant.priority !== true) return { ok: false, reason: "bad-priority" };
   let verified = false;
   try {
     verified = Keychain.verifyDetached(grant.issuer, Buffer.from(signable(grant), "utf-8"), Buffer.from(grant.sig, "hex"));

package/src/index.mjs

@@ -1,18 +1,41 @@
 /**
  * @uuaid/pillar — v0.2.0-alpha.0
  *
- * IAASO-3050 reference: every agent runs its own PDP pillar, discovers peers
+ * Every agent runs its own PDP pillar, discovers peers
  * via a Kademlia DHT, exchanges cryptographically signed messages over libp2p.
  *
  * Entry point.  Not intended for import in browsers today — browser build
  * lives at @uuaid/pillar-browser (later).
  */
-export { Keychain } from "./identity/keychain.mjs";
+export { Keychain, localIdFromKey } from "./identity/keychain.mjs";
 export { jcs } from "./identity/jcs.mjs";
 export { seal, open, decrypt, envelopeSha, keychainSeed, ENVELOPE_VERSION, E2E_ALG } from "./net/envelope.mjs";
+export { DELEGATION_VERSION, verifyDelegationDoc, delegationCoversKind } from "./net/delegation.mjs";
 export { sealPayload, openPayload, edPubToX25519, edSeedToX25519 } from "./crypto/e2e.mjs";
 export { Mailbox } from "./mailbox/mailbox.mjs";
 export { Pillar } from "./pillar.mjs";
 export { createTransport, PILLAR_PROTOCOL, uuaidToDhtKey, peerIdFromEd25519Hex } from "./net/transport.mjs";
 export { CarrierClient } from "./net/carrier-client.mjs";
 export { CarrierServer } from "./net/carrier-server.mjs";
+// Seeds: the ladder that turns sustained relay service into earned tier
+// grants + priority delivery, and the registry that observes and publishes it.
+export {
+  SEED_TIERS, SEED_TIER_NAMES, GRANT_TTL_DAYS, DEMOTE_AFTER_FAILURES,
+  seedTier, seedTierAtLeast, uptimeOf, evaluateSeedTier,
+} from "./net/seed-tier.mjs";
+export { SeedRegistry, checkSeedUrl, verifySeedInfo, PROBE_WINDOW } from "./net/seed-registry.mjs";
+// Blob transport (client/core half): oversized payloads ride an ephemeral
+// encrypted object store; only a <=4KiB signed ref travels in the envelope.
+export {
+  BLOB_REF_V, BLOB_KIND, MAX_BLOB_REF_BYTES, MAX_INLINE_BODY_BYTES,
+  MAX_BLOB_OBJECT_BYTES, MAX_BLOB_PLAINTEXT_BYTES,
+  DEFAULT_BLOB_TTL_MS, DEFAULT_DIRECT_THRESHOLD_BYTES,
+  BlobError, BlobSizeError, BlobExpiryError, BlobNotFoundError, BlobUploadError,
+  BlobFetchError, BlobIntegrityError, BlobRefError, BlobBrokerError, BlobSenderKeyError,
+  blobAad, encryptBlob, decryptBlob, contentHash, mkObjectName,
+  signBlobRef, verifyBlobRefSig, blobRefMetadata, blobRefSecret, refSerializedBytes,
+  makeBlobRef, validateBlobRef, envelopeBodyBytes, preflightBodyBytes, chooseTransport,
+  prepareBlobSend, fetchAndDecryptBlob, prepareBrokerBlobSend, fetchBrokerBlob,
+} from "./blob/blob.mjs";
+export { MemoryBlobStore, FsBlobStore } from "./blob/store.mjs";
+export { PillarBlobHttpClient, PILLAR_BLOB_AUDIENCE } from "./blob/http.mjs";

package/src/net/carrier-client.mjs

@@ -5,17 +5,45 @@
  * This is the universal transport: works from sandboxes, NATed laptops,
  * serverless, anywhere.  No listening socket required.
  */
+import { envelopeBodyBytes, preflightBodyBytes } from "../blob/blob.mjs";
+import { seedTier } from "./seed-tier.mjs";
+
+/**
+ * Rank carriers by how proven they are, best first. Unknown carriers rank as
+ * `probation` — the primary carrier from a directory has no seed tier and
+ * should not be assumed better than a seed that earned one, nor worse.
+ * Array.prototype.sort is stable, so a client given no tier information at
+ * all keeps its list in exactly the order it was constructed with.
+ */
+function byTier(tiers) {
+  return (a, b) => seedTier(tiers[a] ?? "probation").listRank - seedTier(tiers[b] ?? "probation").listRank;
+}
 
 export class CarrierClient {
   /**
    * @param {{keychain: import('../identity/keychain.mjs').Keychain, carriers: string[]}} opts
    *   carriers: base URLs, e.g. ["https://pillar.uuaid.org"]
    */
-  constructor({ keychain, carriers, tierGrant = null }) {
+  /**
+   * @param {object} opts
+   *   carrierTiers  optional { "<url>": "<seed tier>" } from a directory's
+   *                 seeds[]. Drives which carrier's receipt is authoritative
+   *                 and which one is polled first — see `deliver`.
+   */
+  constructor({ keychain, carriers, tierGrant = null, carrierTiers = {} }) {
     if (!keychain?._identity) throw new Error("CarrierClient needs a loaded keychain");
     if (!carriers?.length) throw new Error("CarrierClient needs at least one carrier URL");
     this.keychain = keychain;
-    this.carriers = carriers.map(u => u.replace(/\/+$/, ""));
+    // Normalise tier keys the same way as carrier URLs so a trailing slash on
+    // one side does not silently drop a seed to `probation`.
+    this.carrierTiers = Object.fromEntries(
+      Object.entries(carrierTiers).map(([u, t]) => [String(u).replace(/\/+$/, ""), t]),
+    );
+    this.carriers = carriers.map(u => u.replace(/\/+$/, "")).sort(byTier(this.carrierTiers));
+    // Tier label for the local preflight: a signed grant raises it; default
+    // stays community (matches the carrier's unauthenticated tier).
+    this.tier = tierGrant?.tier ?? "community";
+    this.maxBodyBytes = Number.isInteger(tierGrant?.maxBodyBytes) ? tierGrant.maxBodyBytes : null;
     // Optional signed tier grant (tier.mjs) — sent as a header on deliver so
     // qualifying senders get raised budgets at carriers that trust the issuer.
     this.tierGrantB64 = tierGrant
@@ -35,12 +63,27 @@ export class CarrierClient {
    * envelope.id and re-fires no handlers.
    *
    * Resolves once every carrier has answered.  Succeeds if at least one
-   * accepted; throws if every carrier rejects.  Returns the first-in-list
-   * accepting receipt as the primary ({ carrier, seq, sha, duplicate }) plus
-   * `all` with every carrier's outcome ({ carrier, ok, seq?, sha?,
-   * duplicate?, error? }).
+   * accepted; throws if every carrier rejects.  Returns the receipt from the
+   * most PROVEN accepting carrier as the primary ({ carrier, seq, sha,
+   * duplicate }) plus `all` with every carrier's outcome ({ carrier, ok,
+   * seq?, sha?, duplicate?, error? }).
+   *
+   * Which receipt is primary matters because callers quote its seq back as a
+   * cursor and cite its carrier in receipts: it should name a seed that will
+   * still be there. With no tier information every carrier ranks equally and
+   * the first-in-list receipt wins, exactly as before.
    */
   async deliver(envelope, { timeoutMs = 10000 } = {}) {
+    // Preflight against the carrier limits BEFORE any network call: the
+    // tier inline limit first, then the 2 MiB direct hard cap — no tier
+    // grant can raise the hard cap.  Typed failure, not a carrier 413.
+    const pf = preflightBodyBytes(envelopeBodyBytes(envelope), { tier: this.tier, maxBodyBytes: this.maxBodyBytes });
+    if (!pf.ok) {
+      const e = new Error(`carrier preflight: body ${pf.bytes}B exceeds ${pf.source} limit ${pf.limit}B — use the blob transport`);
+      e.code = pf.source === "direct-cap" ? "blob-too-large" : "over-tier-limit";
+      e.limit = pf.limit; e.source = pf.source;
+      throw e;
+    }
     const attempt = async (base) => {
       try {
         const res = await fetch(`${base}/v1/envelopes`, {
@@ -52,11 +95,13 @@ export class CarrierClient {
           body: JSON.stringify(envelope),
           signal: AbortSignal.timeout(timeoutMs),
         });
-        const body = await res.json();
+        const raw = await res.text();
+        let body = {};
+        try { body = raw ? JSON.parse(raw) : {}; } catch (_error) {}
         if (res.status === 202 && body.accepted) {
           return { carrier: base, ok: true, seq: body.seq, sha: body.sha, duplicate: !!body.duplicate };
         }
-        return { carrier: base, ok: false, error: `${res.status} ${body.reason ?? body.error ?? ""}` };
+        return { carrier: base, ok: false, error: `${res.status} ${body.reason ?? body.error ?? (raw ? "non-json-response" : "empty-response")}` };
       } catch (e) {
         return { carrier: base, ok: false, error: e.message };
       }
@@ -67,7 +112,8 @@ export class CarrierClient {
     if (!accepted.length) {
       throw new Error(`carrier deliver failed on all carriers: ${all.map(r => `${r.carrier}: ${r.error}`).join("; ")}`);
     }
-    const { carrier, seq, sha, duplicate } = accepted[0];
+    const ranked = accepted.slice().sort((a, b) => byTier(this.carrierTiers)(a.carrier, b.carrier));
+    const { carrier, seq, sha, duplicate } = ranked[0];
     return { carrier, seq, sha, duplicate, all };
   }