@openzeppelin/guardian-client 0.18.0-rc.3 → 0.18.1

package/src/http.ts

@@ -7,6 +7,8 @@ import type {
   AbandonStatus,
   ConfigureRequest,
   ConfigureResponse,
+  CreateSessionRequest,
+  CreateSessionResponse,
   DeltaObject,
   DeltaProposalRequest,
   DeltaProposalResponse,
@@ -16,6 +18,8 @@ import type {
   LookupResponse,
   PubkeyResponse,
   PushDeltaResponse,
+  SessionEndReason,
+  SessionRequestSigner,
   SignProposalRequest,
   SignatureScheme,
   Signer,
@@ -36,17 +40,23 @@ import type {
   ServerPubkeyResponse,
   ServerStateObject,
   ServerConfigureResponse,
+  ServerCreateSessionResponse,
   ServerPushDeltaResponse,
+  ServerRevokeAllSessionsRequest,
+  ServerRevokeAllSessionsResponse,
+  ServerRevokeSessionResponse,
   ServerStatusResponse,
 } from './server-types.js';
 import {
   fromServerCanonicalNonce,
   fromServerConfigureResponse,
+  fromServerCreateSessionResponse,
   fromServerDeltaObject,
   fromServerHistoryPage,
   fromServerLookupResponse,
   fromServerStateObject,
   toServerConfigureRequest,
+  toServerCreateSessionRequest,
   toServerDeltaProposalRequest,
   toServerExecutionDelta,
   toServerSignProposalRequest,
@@ -226,11 +236,46 @@ function parseRetryAfterSeconds(header: string | null | undefined): number | und
   return Number.isSafeInteger(secs) ? secs : undefined;
 }
 
+/**
+ * A session is set aside this long before it expires, so a request never
+ * reaches the server already expired; requests then fall back to the wallet.
+ */
+const SESSION_EXPIRY_MARGIN_MS = 30_000;
+
+/** Codes that end a session-signed request's session for good. */
+const SESSION_END_REASONS: Record<string, SessionEndReason> = {
+  session_expired: 'expired',
+  session_revoked: 'revoked',
+  authentication_failed: 'rejected',
+};
+
+/**
+ * Which key signs a per-account request. Mirrors the server: requests are
+ * wallet-signed unless the route is session-eligible.
+ */
+type AuthMode = 'session' | 'wallet';
+
+function authHeaders(
+  publicKey: string,
+  signature: string,
+  timestamp: number,
+  format?: 'eip712' | 'session'
+): Record<string, string> {
+  return {
+    'x-pubkey': publicKey,
+    'x-signature': signature,
+    'x-timestamp': timestamp.toString(),
+    ...(format ? { 'x-auth-format': format } : {}),
+  };
+}
+
 /**
  * Minimal HTTP client for GUARDIAN server.
  */
 export class GuardianHttpClient {
   private signer: Signer | null = null;
+  private session: SessionRequestSigner | null = null;
+  private readonly endedSessions = new WeakSet<SessionRequestSigner>();
   private readonly baseUrl: string;
   private lastTimestamp = 0;
 
@@ -254,6 +299,116 @@ export class GuardianHttpClient {
     this.signer = signer;
   }
 
+  /**
+   * Sign session-eligible requests (reads, proposal list/get, proposal
+   * create/sign) with a registered delegated signer instead of the wallet.
+   * Every other route, including `configure`, `pushDelta`,
+   * `abandonCandidate`, account lookup and `revokeAllSessions`, uses the
+   * wallet signer. Pass `null` to stop using the session.
+   */
+  setSession(session: SessionRequestSigner | null): void {
+    this.session = session;
+  }
+
+  /**
+   * The session in use, or `null` when none is set, no wallet signer is set,
+   * the session was granted by another wallet than the current signer, or it
+   * is about to expire. A session reaching its expiry margin is dropped and
+   * told so.
+   */
+  getSession(): SessionRequestSigner | null {
+    const session = this.session;
+    if (!session) {
+      return null;
+    }
+    if (session.expiresAt * 1000 - SESSION_EXPIRY_MARGIN_MS <= Date.now()) {
+      this.endSession(session, 'expired');
+      return null;
+    }
+    if (
+      !this.signer ||
+      this.signer.commitment.toLowerCase() !== session.signerCommitment.toLowerCase()
+    ) {
+      return null;
+    }
+    return session;
+  }
+
+  /**
+   * Stops using `session` if it is still the current one, and tells it why
+   * once. A newer session set meanwhile stays in use.
+   */
+  private endSession(session: SessionRequestSigner, reason: SessionEndReason): void {
+    if (this.session === session) {
+      this.session = null;
+    }
+    if (!this.endedSessions.has(session)) {
+      this.endedSessions.add(session);
+      session.onEnded?.(reason);
+    }
+  }
+
+  /** Register a wallet-signed session grant (`POST /session`). */
+  async createSession(request: CreateSessionRequest): Promise<CreateSessionResponse> {
+    const response = await this.fetch('/session', {
+      method: 'POST',
+      body: JSON.stringify(toServerCreateSessionRequest(request)),
+    });
+    return fromServerCreateSessionResponse((await response.json()) as ServerCreateSessionResponse);
+  }
+
+  /**
+   * Revoke a session on the server (`POST /session/logout`), the current one
+   * by default, and stop using it. Returns whether the server still had it
+   * active; `false` when there is none. On error the session stays in use.
+   */
+  async revokeSession(session: SessionRequestSigner | null = this.session): Promise<boolean> {
+    if (!session) {
+      return false;
+    }
+    const timestamp = this.nextTimestamp();
+    const signature = await session.signLogout(timestamp);
+    const response = await this.fetch('/session/logout', {
+      method: 'POST',
+      headers: authHeaders(session.publicKey, signature, timestamp),
+    });
+    const data = (await response.json()) as ServerRevokeSessionResponse;
+    this.endSession(session, 'logout');
+    return data.revoked;
+  }
+
+  /**
+   * Revoke every session of the wallet signer on the server
+   * (`POST /session/revoke-all`), including sessions started elsewhere, and
+   * stop using the session that was current when the call was made. A
+   * session started while the call is in flight was issued after it and
+   * stays in use. Signed by the wallet. Returns how many sessions the server
+   * revoked.
+   */
+  async revokeAllSessions(): Promise<number> {
+    const signer = this.signer;
+    if (!signer) {
+      throw new Error('No signer configured. Call setSigner() first.');
+    }
+    if (!signer.signSessionRevokeAll) {
+      throw new Error('This signer cannot sign Guardian session revocations');
+    }
+    const revoking = this.session;
+    const timestamp = this.nextTimestamp();
+    const signature = await signer.signSessionRevokeAll(signer.commitment, timestamp);
+    const body: ServerRevokeAllSessionsRequest = { signer_commitment: signer.commitment };
+    const response = await this.fetch('/session/revoke-all', {
+      method: 'POST',
+      headers: authHeaders(signer.publicKey, signature, timestamp, signer.requestAuthFormat),
+      body: JSON.stringify(body),
+    });
+    const data = (await response.json()) as ServerRevokeAllSessionsResponse;
+    if (revoking?.signerCommitment.toLowerCase() === signer.commitment.toLowerCase()) {
+      this.endSession(revoking, 'logout');
+    }
+    return data.revoked;
+  }
+
   async getPubkey(scheme?: SignatureScheme): Promise<PubkeyResponse> {
     const query = scheme ? `?scheme=${scheme}` : '';
     const response = await this.fetch(`/pubkey${query}`, { method: 'GET' });
@@ -274,11 +429,19 @@ export class GuardianHttpClient {
       environment: data.environment,
       startedAt: data.started_at,
       uptimeSeconds: data.uptime_seconds,
+      ...(data.sessions
+        ? {
+            sessions: {
+              maxTtlSeconds: data.sessions.max_ttl_seconds,
+            },
+          }
+        : {}),
     };
   }
 
   async configure(request: ConfigureRequest): Promise<ConfigureResponse> {
     const serverRequest = toServerConfigureRequest(request);
+    // Configuration changes who the account trusts: always the wallet.
     const response = await this.fetchAuthenticated('/configure', {
       method: 'POST',
       body: JSON.stringify(serverRequest),
@@ -292,7 +455,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/state?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery);
+    }, accountId, requestQuery, 'session');
     const server = (await response.json()) as ServerStateObject;
     return fromServerStateObject(server);
   }
@@ -309,7 +472,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/state/nonce?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery);
+    }, accountId, requestQuery, 'session');
     const server = (await response.json()) as ServerCanonicalNonceResponse;
     return fromServerCanonicalNonce(server);
   }
@@ -336,7 +499,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta/proposal?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery);
+    }, accountId, requestQuery, 'session');
     const data = (await response.json()) as ServerProposalsResponse;
     return data.proposals.map(fromServerDeltaObject);
   }
@@ -346,7 +509,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta/proposal/single?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery);
+    }, accountId, requestQuery, 'session');
     const data = (await response.json()) as ServerDeltaObject;
     return fromServerDeltaObject(data);
   }
@@ -356,7 +519,7 @@ export class GuardianHttpClient {
     const response = await this.fetchAuthenticated('/delta/proposal', {
       method: 'POST',
       body: JSON.stringify(serverRequest),
-    }, request.accountId, serverRequest);
+    }, request.accountId, serverRequest, 'session');
     const server = (await response.json()) as ServerDeltaProposalResponse;
     return {
       delta: fromServerDeltaObject(server.delta),
@@ -379,6 +542,7 @@ export class GuardianHttpClient {
    */
   async abandonCandidate(accountId: string, nonce: number): Promise<AbandonCandidateResponse> {
     const serverRequest: ServerAbandonCandidateRequest = { account_id: accountId, nonce };
+    // Abandoning changes the account's canonical chain: always the wallet.
     const response = await this.fetchAuthenticated('/delta/candidate/abandon', {
       method: 'POST',
       body: JSON.stringify(serverRequest),
@@ -438,13 +602,14 @@ export class GuardianHttpClient {
     const response = await this.fetchAuthenticated('/delta/proposal', {
       method: 'PUT',
       body: JSON.stringify(serverRequest),
-    }, request.accountId, serverRequest);
+    }, request.accountId, serverRequest, 'session');
     const server = (await response.json()) as ServerDeltaObject;
     return fromServerDeltaObject(server);
   }
 
   async pushDelta(delta: ExecutionDelta): Promise<PushDeltaResponse> {
     const serverDelta = toServerExecutionDelta(delta);
+    // Guardian's ACK commits the account to this transition: always the wallet.
     const response = await this.fetchAuthenticated('/delta', {
       method: 'POST',
       body: JSON.stringify(serverDelta),
@@ -472,7 +637,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta?${params}`, {
       method: 'GET',
-    }, accountId, requestPayload);
+    }, accountId, requestPayload, 'session');
     const server = (await response.json()) as ServerDeltaObject;
     return fromServerDeltaObject(server);
   }
@@ -489,7 +654,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta/since?${params}`, {
       method: 'GET',
-    }, accountId, requestPayload);
+    }, accountId, requestPayload, 'session');
     const server = (await response.json()) as ServerDeltaObject;
     return fromServerDeltaObject(server);
   }
@@ -516,7 +681,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestPayload);
     const response = await this.fetchAuthenticated(`/delta/history?${params}`, {
       method: 'GET',
-    }, accountId, requestPayload);
+    }, accountId, requestPayload, 'session');
     const server = (await response.json()) as ServerHistoryPage;
     return fromServerHistoryPage(server);
   }
@@ -573,10 +738,7 @@ export class GuardianHttpClient {
       ...init,
       headers: {
         ...init.headers,
-        'x-pubkey': this.signer.publicKey,
-        'x-signature': signature,
-        'x-timestamp': timestamp.toString(),
-        ...(this.signer.requestAuthFormat ? { 'x-auth-format': this.signer.requestAuthFormat } : {}),
+        ...authHeaders(this.signer.publicKey, signature, timestamp, this.signer.requestAuthFormat),
       },
     });
   }
@@ -586,30 +748,40 @@ export class GuardianHttpClient {
     init: RequestInit,
     accountId: string,
     requestPayload: unknown,
+    mode: AuthMode = 'wallet',
     retries = 2
   ): Promise<Response> {
-    if (!this.signer) {
-      throw new Error('No signer configured. Call setSigner() first.');
-    }
-
     const timestamp = this.nextTimestamp();
     const authPayload = RequestAuthPayload.fromRequest(requestPayload);
-    const signature = this.signer.signRequest
-      ? await this.signer.signRequest(accountId, timestamp, authPayload)
-      : await this.signer.signAccountIdWithTimestamp(accountId, timestamp);
+    const session = mode === 'session' ? this.getSession() : null;
+    const headers = session
+      ? authHeaders(
+          session.publicKey,
+          await session.signRequest(accountId, timestamp, authPayload),
+          timestamp,
+          'session'
+        )
+      : await this.walletAuthHeaders(accountId, timestamp, authPayload);
 
     try {
       return await this.fetch(path, {
         ...init,
         headers: {
           ...init.headers,
-          'x-pubkey': this.signer.publicKey,
-          'x-signature': signature,
-          'x-timestamp': timestamp.toString(),
-          ...(this.signer.requestAuthFormat ? { 'x-auth-format': this.signer.requestAuthFormat } : {}),
+          ...headers,
         },
       });
     } catch (err) {
+      // A session Guardian ended or no longer accepts (unknown key after a
+      // restart, rotated Guardian key or network) is dead for good: stop
+      // using it so the caller can start a new one; meanwhile the wallet
+      // signs again.
+      if (session && err instanceof GuardianHttpError) {
+        const reason = SESSION_END_REASONS[err.code ?? ''];
+        if (reason) {
+          this.endSession(session, reason);
+        }
+      }
       // Replay rejections are transient: the request was correctly signed
       // but lost the server's per-signer timestamp CAS. Retry with a fresh
       // timestamp and signature, branching only on the dedicated
@@ -622,9 +794,23 @@ export class GuardianHttpClient {
         err.code === 'authentication_replay'
       ) {
         await new Promise((resolve) => setTimeout(resolve, 50));
-        return this.fetchAuthenticated(path, init, accountId, requestPayload, retries - 1);
+        return this.fetchAuthenticated(path, init, accountId, requestPayload, mode, retries - 1);
       }
       throw err;
     }
   }
+
+  private async walletAuthHeaders(
+    accountId: string,
+    timestamp: number,
+    authPayload: RequestAuthPayload
+  ): Promise<Record<string, string>> {
+    if (!this.signer) {
+      throw new Error('No signer configured. Call setSigner() first.');
+    }
+    const signature = this.signer.signRequest
+      ? await this.signer.signRequest(accountId, timestamp, authPayload)
+      : await this.signer.signAccountIdWithTimestamp(accountId, timestamp);
+    return authHeaders(this.signer.publicKey, signature, timestamp, this.signer.requestAuthFormat);
+  }
 }

package/src/index.ts

@@ -29,6 +29,12 @@ export type {
   ConfigureResponse,
   PubkeyResponse,
   StatusResponse,
+  SessionsStatus,
+  SessionGrantFields,
+  SessionRequestSigner,
+  SessionEndReason,
+  CreateSessionRequest,
+  CreateSessionResponse,
   DeltaProposalRequest,
   DeltaProposalResponse,
   ProposalsResponse,

package/src/server-types.ts

@@ -22,7 +22,7 @@ export type ServerDeltaStatus =
   | { status: 'pending'; timestamp: string; proposer_id: string; cosigner_sigs: ServerCosignerSignature[] }
   | { status: 'candidate'; timestamp: string }
   | { status: 'canonical'; timestamp: string }
-  | { status: 'retained'; timestamp: string; reason?: 'retry_exhausted' | 'diverged' }
+  | { status: 'retained'; timestamp: string; reason?: 'retry_exhausted' | 'diverged' | 'orphaned' }
   | { status: 'discarded'; timestamp: string; reason?: string };
 
 export type ServerProposalType =
@@ -58,7 +58,9 @@ export interface ServerProposalMetadata {
   amount?: string;
   /** P2ID note visibility, "public" or "private" (issue #322). Absent => public. */
   note_type?: string;
-  /** Base64-serialized Miden `ChainAnchor` pinning the proposal's reference block. */
+  /** The block the proposal's transaction summary binds (unsigned). */
+  bound_block_num?: number;
+  /** Legacy base64 Miden `ChainAnchor` written by 0.18 clients. */
   chain_anchor?: string;
   /** P2IDE reclaim block height (issue #366). Presence of either height means a P2IDE note. */
   reclaim_height?: number;
@@ -183,6 +185,42 @@ export interface ServerStatusResponse {
   environment: string;
   started_at: string;
   uptime_seconds: number;
+  sessions?: {
+    max_ttl_seconds: number;
+  };
+}
+
+export interface ServerCreateSessionRequest {
+  scheme: string;
+  auth_format?: string;
+  public_key?: string;
+  signature: string;
+  grant: {
+    signer_commitment: string;
+    session_public_key: string;
+    origin: string;
+    issued_at: number;
+    expires_at: number;
+    guardian_commitment: string;
+    network: string;
+  };
+}
+
+export interface ServerCreateSessionResponse {
+  signer_commitment: string;
+  expires_at: string;
+}
+
+export interface ServerRevokeSessionResponse {
+  revoked: boolean;
+}
+
+export interface ServerRevokeAllSessionsRequest {
+  signer_commitment: string;
+}
+
+export interface ServerRevokeAllSessionsResponse {
+  revoked: number;
 }
 
 export interface ServerLookupAccount {

package/src/types.ts

@@ -31,6 +31,110 @@ export interface Signer {
     keyCommitmentHex: string,
     timestampMs: number
   ): Promise<string> | string;
+
+  /**
+   * Sign a session grant once, authorizing a delegated signer to sign
+   * per-account requests. Raw signers sign the grant's RPO digest; EIP-712
+   * signers sign readable `GuardianSession` typed data. The canonical
+   * implementation lives in `@openzeppelin/miden-multisig-client`.
+   */
+  signSessionGrant?(grant: SessionGrantFields): Promise<string> | string;
+
+  /**
+   * Sign the account-less revoke-all message for `POST /session/revoke-all`,
+   * which ends every session of this signer on the Guardian. Raw signers sign
+   * its RPO digest; EIP-712 signers sign `GuardianSessionRevokeAll` typed data.
+   */
+  signSessionRevokeAll?(
+    signerCommitment: string,
+    timestampMs: number
+  ): Promise<string> | string;
+}
+
+/**
+ * Fields of a session grant, as the wallet signs and displays them. The scope
+ * is fixed in v1 (every account the signer cosigns on this Guardian) and is
+ * not a field.
+ */
+export interface SessionGrantFields {
+  /** Hex commitment of the wallet key that signs the grant. */
+  signerCommitment: string;
+  /** Hex SEC1-compressed P-256 delegated-signer public key (33 bytes). */
+  sessionPublicKey: string;
+  /**
+   * The website asking for the session, e.g. `https://app.example`; empty
+   * outside a browser. The wallet displays it so the user sees who asks;
+   * Guardian does not check it against requests.
+   */
+  origin: string;
+  /** Unix seconds. */
+  issuedAt: number;
+  /** Unix seconds. */
+  expiresAt: number;
+  /** This Guardian's ACK key commitment for the wallet's scheme (`GET /pubkey`). */
+  guardianCommitment: string;
+  /** `environment` from `GET /status`. */
+  network: string;
+}
+
+/**
+ * Why a client stopped using a session:
+ * - `logout`: the app ended it with `revokeSession` or `revokeAllSessions`
+ *   (the multisig SDK also logs out a session it replaces); do not start a
+ *   new one in response;
+ * - `expired`: it reached its expiry;
+ * - `revoked`: Guardian answered `session_revoked` (logout or revoke-all
+ *   elsewhere);
+ * - `rejected`: Guardian no longer accepts it (`authentication_failed`, e.g.
+ *   after a restart forgot it or the Guardian key was rotated).
+ */
+export type SessionEndReason = 'logout' | 'expired' | 'revoked' | 'rejected';
+
+/**
+ * Signs session-eligible requests on behalf of a wallet after a session grant
+ * was registered. Requests carry `x-auth-format: session`.
+ */
+export interface SessionRequestSigner {
+  /** Hex SEC1-compressed P-256 session public key, sent as `x-pubkey`. */
+  readonly publicKey: string;
+  /**
+   * Commitment of the wallet that granted the session. The client only uses
+   * the session while that wallet is its signer.
+   */
+  readonly signerCommitment: string;
+  /** Unix seconds. */
+  readonly expiresAt: number;
+  signRequest(
+    accountId: string,
+    timestamp: number,
+    requestPayload: RequestAuthPayload
+  ): Promise<string> | string;
+  /** Sign the account-less `SessionLogoutMessage` for `POST /session/logout`. */
+  signLogout(timestampMs: number): Promise<string> | string;
+  /** Called once when the client stops using the session. */
+  onEnded?(reason: SessionEndReason): void;
+}
+
+export interface CreateSessionRequest {
+  scheme: SignatureScheme;
+  /** `eip712` for EIP-712 wallet signatures; omitted for raw signatures. */
+  authFormat?: 'eip712';
+  /** Wallet public key; required for ECDSA. */
+  publicKey?: string;
+  signature: string;
+  grant: SessionGrantFields;
+}
+
+export interface CreateSessionResponse {
+  signerCommitment: string;
+  /** RFC 3339 UTC. */
+  expiresAt: string;
+}
+
+/** Session parameters a Guardian advertises on `GET /status`. */
+export interface SessionsStatus {
+  /** Grants may expire at most this many seconds after registration. */
+  maxTtlSeconds: number;
 }
 
 export interface FalconSignature {
@@ -71,11 +175,17 @@ export type DeltaStatus =
   | { status: 'pending'; timestamp: string; proposerId: string; cosignerSigs: CosignerSignature[] }
   | { status: 'candidate'; timestamp: string }
   | { status: 'canonical'; timestamp: string }
-  /** Candidate the Guardian gave up verifying (retry exhaustion or a
-   * confirmed-diverged observation) but kept for background
-   * reconciliation (issue #345); promoted to `canonical` if the chain
-   * ever shows it landed, dropped after a server-side TTL otherwise. */
-  | { status: 'retained'; timestamp: string; reason?: 'retry_exhausted' | 'diverged' }
+  /** Candidate the Guardian gave up verifying (retry exhaustion, a
+   * confirmed-diverged observation, or an orphaned position in the
+   * account's candidate queue after its predecessor was parked) but
+   * kept for background reconciliation (issue #345 / #17); promoted to
+   * `canonical` if the chain ever shows it landed, dropped after a
+   * server-side TTL otherwise. */
+  | {
+      status: 'retained';
+      timestamp: string;
+      reason?: 'retry_exhausted' | 'diverged' | 'orphaned';
+    }
   | { status: 'discarded'; timestamp: string; reason?: string };
 
 export type ProposalType =
@@ -112,11 +222,13 @@ export interface ProposalMetadata {
   /** P2ID note visibility, "public" or "private" (issue #322). Absent => public. */
   noteType?: string;
   /**
-   * Base64-serialized Miden `ChainAnchor` pinning the reference block the
-   * proposal's transaction summary was built at. Since protocol 0.16 the
-   * signed summary binds the reference block commitment, so cosigners and the
-   * executor need this anchor to reproduce the summary the proposer signed.
+   * The block the proposal's transaction summary binds. Not signed: the
+   * multisig SDKs read the block from the summary and refuse a proposal whose
+   * value disagrees, so a wrong value can deny a proposal but never get a
+   * wrong one accepted.
    */
+  boundBlockNum?: number;
+  /** Legacy: the base64 Miden `ChainAnchor` 0.18 clients wrote instead of `boundBlockNum`. */
   chainAnchor?: string;
   /** P2IDE reclaim block height (issue #366). Presence of either height means a P2IDE note. */
   reclaimHeight?: number;
@@ -198,6 +310,8 @@ export interface StatusResponse {
   environment: string;
   startedAt: string;
   uptimeSeconds: number;
+  /** Present on every Guardian that accepts session grants; absent on older servers. */
+  sessions?: SessionsStatus;
 }
 
 export interface DeltaProposalRequest {