privateer-agent 0.12.18 → 0.12.20

package/src/providers/phala/aci-verifier/report.ts

@@ -1,49 +1,41 @@
 /**
- * Level 2 report-binding checks (§10.1 checks 2–6), minus the hardware root of
- * trust. This verifies the *cryptographic binding* of the report — that its
- * `workload_id`, keyset digest, `report_data`, and endorsement are internally
- * consistent and endorsed by the identity key — for the nonce the client
- * supplied. It does NOT do §10.1 check 1 (the TEE quote verifies to the vendor
- * root) or the "hardware evidence binds `report_data`" half of check 4: parsing
- * and checking a TDX/SEV-SNP quote is verifier-profile territory and needs
- * primitives outside the Web Crypto API. Compose this with a quote verifier and
- * the custody/provenance/channel checks (§10.1 checks 1, 7–10) for full Level 2.
+ * Report binding checks a verifier can run with pure Web Crypto — §9.1 check 2
+ * (binding and freshness: keyset bytes → digest → statement → `report_data`)
+ * and check 3 (expiry), plus the aci/1 protocol gate. Check 1 (the hardware
+ * quote verifies to the vendor root and binds `report_data`) is done by
+ * ../../phalaSeal.ts with @phala/dcap-qvl; checks 5–6 (custody, channel) stay
+ * policy / caller territory.
+ *
+ * Local omission (see VENDORED.md): upstream's `verifyQuote` and
+ * `verifyComposeMeasurement` live in this file too. They are not carried here —
+ * phalaSeal.ts owns the quote (it also gates TCB status and pins measurements)
+ * and measurements.ts owns the event-log replay across all four RTMRs. Leaving
+ * them out keeps this tree dependency-free and @phala/dcap-qvl off the import
+ * path of every startup.
  */
 
-import {
-  computeWorkloadId,
-  computeKeysetDigest,
-  computeReportData,
-  keysetEndorsementPayload,
-} from './digest';
-import { verifySignature, fromHex } from './crypto';
-import type { AttestationReport, Check, ReportVerification } from './types';
+import { computeKeysetDigest, computeReportData } from './digest';
+import type { AttestationReport, Check, ReportVerification, WorkloadKeyset } from './types';
 
 /** Options for {@link verifyReportBinding}. */
 export interface ReportBindingOptions {
   /**
-   * Current time in Unix seconds for the freshness check (§10.1 check 6).
-   * Defaults to the local clock. Pass an explicit value for deterministic tests.
+   * Current time in Unix seconds for the expiry check (§9.1 check 3).
+   * Defaults to the local clock; pass an explicit value for deterministic tests.
    */
   now?: number;
-  /**
-   * Whether the profile trusts the platform's declared validity window
-   * (`freshness.fetched_at`/`stale_after`, §5.1). Off by default — recency comes
-   * from the nonce binding, and `fetched_at`/`stale_after` need a securely
-   * synced TEE clock to mean anything.
-   */
-  trustPlatformClock?: boolean;
 }
 
 /**
- * Verify the report's cryptographic bindings for `nonce` (§10.1 checks 2–6).
- * `nonce` is the value the verifier supplied to `GET /v1/aci/attestation`, or
- * `null`/`undefined` when it requested no nonce (§4.4).
+ * Verify the report's cryptographic bindings for `nonce` — the value this
+ * client sent to `GET /v1/aci/attestation`, or `null`/`undefined` when it sent
+ * none (§3.2). One recomputation establishes that the keyset is exactly what
+ * the quote bound and that the quote postdates the challenge (§9.1 check 2).
  *
- * Returns a per-check result and the identity recomputed from the report's
- * keyset; a failed check is `ok: false`, never thrown. Throws
- * {@link UnsupportedAlgorithmError} when the identity key algorithm is outside
- * Web Crypto scope (e.g. `ecdsa-secp256k1`).
+ * Returns per-check results plus the established keyset (digest, exact bytes,
+ * parsed form); a failed check on the served report is `ok: false`, never
+ * thrown. The one exception is the caller's own input: a nonce that is not
+ * 64 lowercase hex throws {@link AciFormatError} (§3.2).
  */
 export async function verifyReportBinding(
   report: AttestationReport,
@@ -53,71 +45,56 @@ export async function verifyReportBinding(
   const now = options.now ?? Math.floor(Date.now() / 1000);
   const checks: Check[] = [];
 
-  const keyset = report.attestation.workload_keyset;
-  const identityKey = keyset.workload_identity.public_key;
-
-  // Check 2: workload_id == digest of the identity public key in the report's keyset.
-  const workloadId = await computeWorkloadId(identityKey);
-  pushEqual(checks, 'workload_id', report.workload_id, workloadId);
+  // Protocol gate (Appendix B): artifacts with another version are rejected.
+  const versionOk = report.api_version === 'aci/1';
+  checks.push({
+    name: 'api_version',
+    ok: versionOk,
+    ...(versionOk ? {} : { detail: `api_version "${report.api_version}" is not "aci/1"` }),
+  });
 
-  // Check 3: workload_keyset_digest == digest of the report's keyset.
-  const workloadKeysetDigest = await computeKeysetDigest(keyset);
-  pushEqual(checks, 'workload_keyset_digest', report.workload_keyset_digest, workloadKeysetDigest);
+  const keysetValue = report.attestation.workload_keyset;
+  if (keysetValue === null || typeof keysetValue !== 'object' || Array.isArray(keysetValue)) {
+    const detail = 'workload_keyset is not a JSON object';
+    for (const name of ['workload_keyset_digest', 'report_data', 'not_after']) {
+      checks.push({ name, ok: false, detail });
+    }
+    return { ok: false, checks };
+  }
 
-  // Check 4 (binding half): report_data == the §4.4 statement digest for this nonce.
-  // The hardware-evidence-binds-report_data half is out of scope (see file header).
-  const expectedReportData = await computeReportData(workloadId, workloadKeysetDigest, nonce);
+  // §9.1 check 2: recompute the whole chain from the served keyset object —
+  // canonicalize exactly what was parsed, unknown members included. The
+  // recomputed digest is authoritative (Appendix A) — the report's restated copy is
+  // checked for consistency but never feeds the statement.
+  const digest = await computeKeysetDigest(keysetValue);
+  pushEqual(checks, 'workload_keyset_digest', report.workload_keyset_digest, digest);
+  const expectedReportData = await computeReportData(digest, nonce);
   pushEqual(checks, 'report_data', report.attestation.report_data, expectedReportData);
 
-  // Check 5: keyset endorsement verifies under the identity key, algo matching.
-  const endorsement = report.attestation.keyset_endorsement;
-  if (endorsement.algo !== identityKey.algo) {
+  const keyset = keysetValue as WorkloadKeyset;
+
+  // §9.1 check 3: now < not_after in the decoded keyset.
+  if (typeof keyset.not_after !== 'number') {
     checks.push({
-      name: 'keyset_endorsement',
+      name: 'not_after',
       ok: false,
-      detail: `endorsement.algo "${endorsement.algo}" != identity key algo "${identityKey.algo}"`,
+      detail: 'keyset has no numeric not_after',
     });
   } else {
-    const ok = await verifySignature(
-      identityKey.algo,
-      fromHex(identityKey.public_key),
-      fromHex(endorsement.value),
-      keysetEndorsementPayload(workloadKeysetDigest),
-      'keyset endorsement (§4.3)',
-    );
+    const ok = now < keyset.not_after;
     checks.push({
-      name: 'keyset_endorsement',
+      name: 'not_after',
       ok,
-      ...(ok ? {} : { detail: 'endorsement signature failed under identity key' }),
-    });
-  }
-
-  // Check 6: freshness. Nonce binding is check 4; here bound the epoch and,
-  // when trusted, the declared validity window.
-  const notAfter = keyset.keyset_epoch.not_after;
-  const epochOk = now < notAfter;
-  checks.push({
-    name: 'keyset_epoch.not_after',
-    ok: epochOk,
-    ...(epochOk ? {} : { detail: `now ${now} >= not_after ${notAfter}` }),
-  });
-  if (options.trustPlatformClock) {
-    const freshness = report.attestation.freshness;
-    const fetchedAt = freshness?.fetched_at;
-    const staleAfter = freshness?.stale_after;
-    const windowOk =
-      typeof fetchedAt === 'number' &&
-      typeof staleAfter === 'number' &&
-      fetchedAt <= now &&
-      now < staleAfter;
-    checks.push({
-      name: 'freshness_window',
-      ok: windowOk,
-      ...(windowOk ? {} : { detail: `now ${now} outside [${fetchedAt}, ${staleAfter})` }),
+      ...(ok ? {} : { detail: `now ${now} >= not_after ${keyset.not_after}` }),
     });
   }
 
-  return { ok: checks.every((c) => c.ok), checks, workloadId, workloadKeysetDigest };
+  return {
+    ok: checks.every((c) => c.ok),
+    checks,
+    workloadKeysetDigest: digest,
+    keyset,
+  };
 }
 
 function pushEqual(checks: Check[], name: string, actual: string, expected: string): void {

package/src/providers/phala/aci-verifier/session.ts

@@ -0,0 +1,40 @@
+/**
+ * Attested-session helpers (§8, §9.3). A session is content-addressed: its id
+ * is the SHA-256 of the exact served document bytes, and the signed receipt
+ * commits to that id — there is no session signature.
+ */
+
+import { sha256Hex, sha256Prefixed, fromBase64 } from './crypto';
+import { jcsBytes } from './jcs';
+import type { SessionRecord, SessionEvidence } from './types';
+
+/** `session_id` (§8): bare 64-hex sha256 of the JCS form of the parsed document. */
+export async function computeSessionId(record: unknown): Promise<string> {
+  return sha256Hex(jcsBytes(record));
+}
+
+/** Appendix B: reject session documents whose `api_version` is not `aci/1`. */
+export function checkSessionApiVersion(record: Pick<SessionRecord, 'api_version'>): boolean {
+  return record.api_version === 'aci/1';
+}
+
+/**
+ * §9.2(2): `evidence.data` decodes and hashes to `evidence.digest`.
+ * Returns false when the data URI is absent, malformed, or does not hash.
+ */
+export async function checkSessionEvidence(evidence: SessionEvidence): Promise<boolean> {
+  if (evidence == null || typeof evidence !== 'object') return false;
+  const { digest, data } = evidence;
+  if (typeof digest !== 'string' || typeof data !== 'string') return false;
+  const comma = data.indexOf(',');
+  if (!data.startsWith('data:') || comma < 0 || !data.slice(0, comma).endsWith(';base64')) {
+    return false;
+  }
+  let bytes: Uint8Array;
+  try {
+    bytes = fromBase64(data.slice(comma + 1));
+  } catch {
+    return false;
+  }
+  return (await sha256Prefixed(bytes)) === digest;
+}

package/src/providers/phala/aci-verifier/types.ts

@@ -1,139 +1,149 @@
 /**
  * Wire shapes for the ACI artifacts this verifier reads, plus the result types
- * it returns. These mirror spec/aci.md §4, §5, §8, §9; only the fields the
+ * it returns. These mirror spec/aci.md §3, §4, §7, §8; only the fields the
  * verifier touches are typed precisely, with an index signature left open so
- * unknown extension fields (§3.2) survive canonicalization untouched.
+ * extension fields (Appendix B) are visible to callers.
  */
 
-import type { JcsValue } from './jcs';
-
-/** A public key object: `{ algo, public_key }` (§4.1). */
-export interface PublicKey {
+/** A keyed public-key entry (§3.1) — receipt signing and E2EE keys. */
+export interface KeysetKey {
+  key_id: string;
   algo: string;
   public_key: string;
-  [key: string]: JcsValue | undefined;
+  [key: string]: unknown;
 }
 
-/** The workload identity (§4.2): the identity public key plus an optional subject. */
-export interface WorkloadIdentity {
-  public_key: PublicKey;
-  subject?: string | null;
-  [key: string]: JcsValue | undefined;
+/** A TLS pin entry (§3.1): the certificate SPKI digest, optionally domain-scoped. */
+export interface TlsKeyPin {
+  spki_sha256: string;
+  domain?: string;
+  [key: string]: unknown;
 }
 
-/** A receipt signing key entry (§4.2). */
-export interface ReceiptSigningKey {
-  key_id: string;
-  algo: string;
-  public_key: string;
-  [key: string]: JcsValue | undefined;
-}
-
-/** The workload keyset (§4.2). Digested with JCS to yield `workload_keyset_digest`. */
+/**
+ * The workload keyset (§3.1) — the unit of workload identity. It travels as
+ * `workload_keyset`; its digest is the SHA-256 of the JCS form of the
+ * parsed object (Appendix A).
+ */
 export interface WorkloadKeyset {
-  workload_identity: WorkloadIdentity;
-  keyset_epoch: { version: number; not_after: number; [key: string]: JcsValue | undefined };
-  receipt_signing_keys: ReceiptSigningKey[];
-  e2ee_public_keys?: JcsValue[];
-  tls_public_keys?: JcsValue[];
-  [key: string]: JcsValue | undefined;
+  subject?: string | null;
+  not_after: number;
+  receipt_signing_keys: KeysetKey[];
+  e2ee_public_keys: KeysetKey[];
+  tls_public_keys?: TlsKeyPin[];
+  [key: string]: unknown;
 }
 
-/** A receipt signature block (§8.2). `value` is dropped for canonical signing bytes (§8.5). */
-export interface ReceiptSignature {
-  algo: string;
-  key_id: string;
-  value: string;
-  [key: string]: JcsValue | undefined;
+/** Source provenance (§4.1); each field is `null` when unknown. */
+export interface SourceProvenance {
+  repo_url?: string | null;
+  repo_commit?: string | null;
+  image_digest?: string | null;
+  image_provenance?: unknown;
+  [key: string]: unknown;
 }
 
-/** A single receipt event (§8.3). Only `seq`/`type` are fixed; other fields are type-specific. */
-export interface ReceiptEvent {
-  seq: number;
-  type: string;
-  [key: string]: JcsValue | undefined;
+/** The `attestation` object of a report (§4.1). `evidence` is policy-defined (§4.2). */
+export interface Attestation {
+  tee_type: string;
+  workload_keyset: unknown;
+  report_data: string;
+  source_provenance?: SourceProvenance | null;
+  evidence?: unknown;
+  [key: string]: unknown;
 }
 
-/** An inference receipt (§8.2). */
-export interface Receipt {
+/** An attestation report (§4.1). */
+export interface AttestationReport {
   api_version: string;
-  receipt_id: string;
-  workload_id: string;
   workload_keyset_digest: string;
-  event_log: ReceiptEvent[];
-  signature: ReceiptSignature;
-  [key: string]: JcsValue | undefined;
+  attestation: Attestation;
+  service_capabilities?: { supported_e2ee_versions?: string[]; [key: string]: unknown };
+  [key: string]: unknown;
 }
 
-/** The keyset endorsement / revocation signature block (§4.3, §5.1). */
-export interface Endorsement {
-  algo: string;
-  value: string;
-  [key: string]: JcsValue | undefined;
+/**
+ * The receipt document served by `GET /v1/aci/receipts/{id}` (§7.2): the
+ * §7.3 payload members plus `key_id` and `signature`. The signature covers
+ * JCS(document minus `signature`).
+ */
+export interface ReceiptEnvelope {
+  key_id: string;
+  signature: string;
+  [key: string]: unknown;
 }
 
-/** The `attestation` object of a report (§5.1); only the fields Level 1 reads are typed. */
-export interface Attestation {
-  workload_keyset: WorkloadKeyset;
-  report_data: string;
-  keyset_endorsement: Endorsement;
-  freshness?: { fetched_at?: number; stale_after?: number; [key: string]: JcsValue | undefined };
-  [key: string]: JcsValue | undefined;
+/** A receipt event (§7.3): `type` plus type-specific fields; order is array order. */
+export interface ReceiptEvent {
+  type: string;
+  body_hash?: string;
+  [key: string]: unknown;
 }
 
-/** An attestation report (§5.1). */
-export interface AttestationReport {
+/** The receipt payload the envelope signs (§7.3). */
+export interface ReceiptPayload {
   api_version: string;
-  workload_id: string;
+  receipt_id: string;
+  chat_id?: string | null;
+  model?: string | null;
   workload_keyset_digest: string;
-  attestation: Attestation;
-  [key: string]: JcsValue | undefined;
+  endpoint: string;
+  method: string;
+  served_at: number;
+  event_log: ReceiptEvent[];
+  [key: string]: unknown;
 }
 
-/** A verifier-provided evidence block on a session record (§9.2). */
+/** A session evidence block (§8.2): a base64 data URI plus the digest of its decoded bytes. */
 export interface SessionEvidence {
-  digest?: string | null;
+  digest: string;
   data?: string;
-  [key: string]: JcsValue | undefined;
+  [key: string]: unknown;
 }
 
 /**
- * An attested session record (§9.2). The `session_id` is recomputed from the
- * named fields; absent optional fields (`endpoint`, `identity`, `evidence.digest`)
- * are restored as JSON `null` in the content-addressing material.
+ * An attested session record (§8.2). Its id is the SHA-256 of the JCS form
+ * of the parsed document ({@link computeSessionId}).
  */
 export interface SessionRecord {
+  api_version: string;
   upstream_name: string;
   endpoint?: string | null;
   verifier_id: string;
-  identity?: JcsValue;
-  channel_binding: JcsValue[];
-  claims: JcsValue;
-  evidence?: SessionEvidence | null;
-  [key: string]: JcsValue | undefined;
+  established_at: number;
+  expires_at: number;
+  identity?: unknown;
+  channel_binding: unknown[];
+  claims: unknown;
+  evidence: SessionEvidence;
+  [key: string]: unknown;
 }
 
 /** Outcome of one named verification check. */
 export interface Check {
-  /** Stable machine-readable id, e.g. `signature`, `workload_id`. */
+  /** Stable machine-readable id, e.g. `signature`, `report_data`. */
   name: string;
   ok: boolean;
   /** Human-readable detail, present when the check fails. */
   detail?: string;
 }
 
-/** Result of {@link verifyReceipt}: overall pass plus the individual §10.2 checks. */
+/** Result of {@link verifyReceipt}: overall pass plus the individual §9.3 checks. */
 export interface ReceiptVerification {
   ok: boolean;
   checks: Check[];
+  /** The receipt document read as its §7.3 payload members. */
+  payload?: ReceiptPayload;
 }
 
-/** Result of {@link verifyReportBinding}: overall pass, the §10.1 checks, and the derived identity. */
+/**
+ * Result of {@link verifyReportBinding}: overall pass, the checks, and the
+ * keyset established from the report — the digest is recomputed over the
+ * served keyset object's JCS form (§3.1).
+ */
 export interface ReportVerification {
   ok: boolean;
   checks: Check[];
-  /** `workload_id` recomputed from the report's keyset (§4.1). */
-  workloadId: string;
-  /** `workload_keyset_digest` recomputed from the report's keyset (§4.2). */
-  workloadKeysetDigest: string;
+  workloadKeysetDigest?: string;
+  keyset?: WorkloadKeyset;
 }

package/src/providers/phalaSeal.ts

@@ -8,13 +8,16 @@
 // (`${server}/api/sealed/phala`, treeview/server/routes/sealed.js) injects PHALA_API_KEY
 // and forwards ciphertext — it can't read prompts or responses.
 //
-// Crypto is the vendored @dstack/aci-verifier (./phala/aci-verifier), pure Web Crypto
+// Crypto is the vendored aci-verifier (./phala/aci-verifier), pure Web Crypto
 // (X25519/HKDF/AES-GCM/Ed25519). Node ≥ 22 provides all of it on globalThis.crypto —
 // no polyfills, unlike the RN app.
 //
 // Two-layer attestation, fail-secure:
-//   (1) verifyAciReportBinding — the report's crypto binding (keyset digest,
-//       report_data == statement(nonce), endorsement sig). Self-attesting alone.
+//   (1) verifyReportBinding — the report's crypto binding (§9.1 checks 2–3): the
+//       served keyset canonicalizes to the digest that the attestation statement for
+//       OUR nonce hashes into report_data, and the keyset has not expired. Every key
+//       we go on to use — the X25519 key we seal to above all — is a member of that
+//       one object, so the binding covers them without a separate signature.
 //   (2) verifyHardwareQuote — the hardware root: @phala/dcap-qvl verifies the TDX quote
 //       against Intel collateral and binds the quote's report_data to (1)'s statement
 //       digest. requireQuote defaults TRUE; PRIVATEER_PHALA_REQUIRE_QUOTE=0 drops it
@@ -23,17 +26,13 @@
 import type { Report } from "@phala/dcap-qvl";
 import {
   openE2eeChannel,
+  verifyReportBinding,
   toHex,
   fromHex,
   type AttestationReport,
   type ReportVerification,
   type E2eeChannel,
 } from "./phala/aci-verifier/index.ts";
-// Not the vendored verifyReportBinding directly: the deployed gateway signs its
-// keyset endorsement with ecdsa-secp256k1, which upstream's Web-Crypto-only verifier
-// refuses. This wrapper delegates ed25519 to it unchanged and adds the secp256k1 arm
-// the spec allows (§4.3), leaving aci-verifier/ pristine for re-pulls.
-import { verifyAciReportBinding } from "./phala/reportBinding.ts";
 import {
   parseEventLog,
   appIdentityFrom,
@@ -153,7 +152,7 @@ async function establishAttestation(): Promise<VerifiedAttestation> {
   if (!res.ok) throw new Error(`phala attestation HTTP ${res.status}`);
   const report = (await res.json()) as AttestationReport;
 
-  const verification = await verifyAciReportBinding(report, nonce);
+  const verification = await verifyReportBinding(report, nonce);
   if (!verification.ok) {
     const failed = verification.checks.filter((c) => !c.ok).map((c) => c.name).join(", ");
     throw new Error(`phala attestation binding failed: ${failed}`);

package/src/remote/relayClient.ts

@@ -383,6 +383,11 @@ export class RelayClient {
   private reconnectDelay = RECONNECT_MS;
   // Last refusal reason reported, so a 4xx is logged once instead of on every retry.
   private refusal: string | null = null;
+  // Why the last connection attempt failed, kept for connectionStatus(). A refusal
+  // (4xx) outranks it — that one is a decision, not a hiccup — but without either,
+  // every un-connected relay reports as a bare "connecting…", which is the same
+  // sentence whether the socket opens in two seconds or never opens again.
+  private lastFailure: string | null = null;
   // Ordered delta buffer (text/reasoning) coalesced into one frame per flush.
   private bufKind: "text" | "reasoning" | null = null;
   private buf = "";
@@ -518,6 +523,7 @@ export class RelayClient {
       ws.on("open", () => {
         opened = true;
         this.refusal = null; // a later refusal is news again
+        this.lastFailure = null; // whatever kept us out is history
         this.reconnectDelay = RECONNECT_MS; // reachable again — next blip retries fast
         this.connectedAt = Date.now();
         this.startHeartbeat(ws);
@@ -537,6 +543,9 @@ export class RelayClient {
         // attach/detach frame said. Re-learned on the next attach or inbound frame.
         this.controllerHere = false;
         this.cb.onDisconnected?.();
+        // A socket that never opened failed for a reason worth reporting; one that
+        // opened and dropped is an ordinary blip the reconnect handles.
+        this.lastFailure = opened ? null : lastErr || "the relay connection closed before it opened";
         if (!this.closed) {
           this.cb.onStatus?.(
             opened
@@ -560,6 +569,7 @@ export class RelayClient {
       const status = (err as { status?: number })?.status;
       const refused = typeof status === "number" && status >= 400 && status < 500;
       if (refused) {
+        this.lastFailure = msg;
         this.settleFirstConnect(err instanceof Error ? err : new Error(msg));
         // A refusal is a decision, not a hiccup: hammering the same request every few
         // seconds can't change it, and for a harbor — whose onStatus goes to a log file,
@@ -578,6 +588,7 @@ export class RelayClient {
       }
       // Transient (network/route/5xx): stay on the fast retry.
       this.refusal = null;
+      this.lastFailure = msg;
       this.cb.onStatus?.(`Remote access couldn't reach the relay (${msg}) — retrying…`);
       this.scheduleReconnect();
     } finally {
@@ -970,8 +981,19 @@ export class RelayClient {
   // quiet for longer than the server's 25s ping cadence is the shape of the half-open
   // failure the watchdog exists to catch, so it is worth showing rather than a bare
   // "connected".
-  connectionStatus(): { connected: boolean; upSec?: number; quietSec?: number } {
-    if (!this.isConnected()) return { connected: false };
+  connectionStatus(): { connected: boolean; upSec?: number; quietSec?: number; detail?: string; refused?: boolean } {
+    // Not connected: say WHY when we know. A standing refusal (the plan's agent cap,
+    // a rejected ticket) is the answer that matters most — it will not clear on its
+    // own, and it's the one case a caller should present as a decision rather than a
+    // wait — so it wins over the last transient error and is flagged as itself.
+    if (!this.isConnected()) {
+      const detail = this.refusal ?? this.lastFailure;
+      return {
+        connected: false,
+        ...(detail ? { detail } : {}),
+        ...(this.refusal ? { refused: true } : {}),
+      };
+    }
     const now = Date.now();
     return {
       connected: true,