@openzeppelin/guardian-client 0.15.2 → 0.16.0

package/src/http.ts

@@ -1,4 +1,10 @@
+import {
+  type GuardianErrorCode,
+  normalizeGuardianErrorCode,
+} from './error-codes.js';
 import type {
+  AbandonCandidateResponse,
+  AbandonStatus,
   ConfigureRequest,
   ConfigureResponse,
   DeltaObject,
@@ -16,6 +22,8 @@ import type {
 } from './types.js';
 import { RequestAuthPayload } from './auth-request.js';
 import type {
+  ServerAbandonCandidateRequest,
+  ServerAbandonCandidateResponse,
   ServerDeltaObject,
   ServerDeltaProposalResponse,
   ServerLookupResponse,
@@ -38,21 +46,105 @@ import {
 } from './conversion.js';
 
 /**
- * Error thrown by the GUARDIAN HTTP client.
+ * Structured machine-readable side-data on a GUARDIAN error
+ * (feature `009-human-readable-errors`). `retryable` is always present.
+ */
+export interface GuardianErrorMeta {
+  retryable: boolean;
+  retryAfterSecs?: number;
+  missingPermissions?: string[];
+  pausedAt?: string;
+  pausedReason?: string | null;
+  releasedAt?: string;
+}
+
+interface ParsedGuardianError {
+  /** Typed code, or `null` when the wire code is outside the known vocabulary. */
+  code: GuardianErrorCode | null;
+  /** Verbatim wire code, kept even when it does not narrow to the union. */
+  rawCode: string;
+  message: string;
+  meta: GuardianErrorMeta;
+}
+
+/**
+ * Parse a GUARDIAN error body `{ code, message, meta }` (feature 009),
+ * mapping the server's snake_case `meta` fields to camelCase. Returns
+ * `undefined` for non-JSON or non-conforming bodies — including a missing
+ * `meta` or a non-boolean `meta.retryable`, which the contract requires;
+ * treating those as conforming would silently misclassify retryability for
+ * bodies from older servers or intermediary proxies.
+ */
+function parseGuardianErrorBody(body: string): ParsedGuardianError | undefined {
+  let json: unknown;
+  try {
+    json = JSON.parse(body);
+  } catch {
+    return undefined;
+  }
+  if (typeof json !== 'object' || json === null) return undefined;
+  const obj = json as Record<string, unknown>;
+  if (typeof obj.code !== 'string' || typeof obj.message !== 'string') return undefined;
+
+  if (typeof obj.meta !== 'object' || obj.meta === null || Array.isArray(obj.meta)) {
+    return undefined;
+  }
+  const rawMeta = obj.meta as Record<string, unknown>;
+  if (typeof rawMeta.retryable !== 'boolean') return undefined;
+  const code = normalizeGuardianErrorCode(obj.code);
+  const meta: GuardianErrorMeta = { retryable: rawMeta.retryable };
+  if (
+    typeof rawMeta.retry_after_secs === 'number' &&
+    Number.isInteger(rawMeta.retry_after_secs) &&
+    rawMeta.retry_after_secs >= 0
+  ) {
+    meta.retryAfterSecs = rawMeta.retry_after_secs;
+  }
+  if (Array.isArray(rawMeta.missing_permissions)) {
+    meta.missingPermissions = rawMeta.missing_permissions.filter(
+      (x): x is string => typeof x === 'string'
+    );
+  }
+  if (typeof rawMeta.paused_at === 'string') meta.pausedAt = rawMeta.paused_at;
+  if (typeof rawMeta.released_at === 'string') meta.releasedAt = rawMeta.released_at;
+  if (typeof rawMeta.paused_reason === 'string' || rawMeta.paused_reason === null) {
+    meta.pausedReason = rawMeta.paused_reason as string | null;
+  }
+  return { code, rawCode: obj.code, message: obj.message, meta };
+}
+
+/**
+ * Error thrown by the GUARDIAN HTTP client. Parses the `{ code, message, meta }`
+ * error body (feature 009): branch on {@link code}, display {@link userMessage}.
  */
 export class GuardianHttpError extends Error {
   /**
-   * Stable machine-readable error code from the server's JSON error
-   * envelope (e.g. `GUARDIAN_ACCOUNT_RELEASED`, `GUARDIAN_ACCOUNT_PAUSED`,
-   * `commitment_mismatch`), or `null` when the body is not a JSON
-   * envelope. Callers SHOULD branch on this rather than on `body` text
-   * or the HTTP status alone.
+   * Typed, compiler-checked Guardian error code (issue #318), normalized to
+   * snake_case (e.g. `account_paused`, `account_released`,
+   * `commitment_mismatch`). `null` when the body is not a conforming JSON
+   * envelope OR the server emitted a code outside this client's known
+   * vocabulary — in the latter case {@link rawCode} still carries the
+   * verbatim wire string. Branch on this rather than on `body` text or the
+   * HTTP status alone; comparing against a non-member literal is a type
+   * error, so typos are caught at compile time.
    */
-  public readonly code: string | null;
+  public readonly code: GuardianErrorCode | null;
+  /**
+   * Verbatim wire code as the server sent it (e.g.
+   * `GUARDIAN_ACCOUNT_PAUSED`), including codes a newer server may emit
+   * that this client does not know. `null` only when the body carried no
+   * conforming envelope. For logging/telemetry; branch on {@link code}.
+   */
+  public readonly rawCode: string | null;
+  /** Short, user-safe message — safe to display verbatim in a wallet UI. */
+  readonly userMessage?: string;
+  /** Structured side-data (`retryable`, `retryAfterSecs`, …). */
+  readonly meta?: GuardianErrorMeta;
   /**
    * RFC 3339 UTC timestamp at which the guardian released the account
-   * after it switched to a different guardian. Present only when
-   * `code === 'GUARDIAN_ACCOUNT_RELEASED'` (HTTP 409); the account is
+   * after it switched to a different guardian. Convenience accessor for
+   * `meta.releasedAt`; present only when `code === 'account_released'`
+   * (wire form `GUARDIAN_ACCOUNT_RELEASED`, HTTP 409); the account is
    * terminal on this server until re-onboarded via `configure`.
    */
   public readonly releasedAt: string | null;
@@ -62,26 +154,17 @@ export class GuardianHttpError extends Error {
     public readonly statusText: string,
     public readonly body: string
   ) {
-    super(`GUARDIAN HTTP error ${status}: ${statusText} - ${body}`);
+    // Only the parsed, user-safe message is folded into Error.message; the
+    // raw body (which may carry backend/proxy internals) stays on the `body`
+    // field for diagnostics only.
+    const parsed = parseGuardianErrorBody(body);
+    super(`GUARDIAN HTTP error ${status}: ${statusText}${parsed ? ` - ${parsed.message}` : ''}`);
     this.name = 'GuardianHttpError';
-    let code: string | null = null;
-    let releasedAt: string | null = null;
-    try {
-      const parsed: unknown = JSON.parse(body);
-      if (parsed !== null && typeof parsed === 'object') {
-        const record = parsed as Record<string, unknown>;
-        if (typeof record['code'] === 'string') {
-          code = record['code'];
-        }
-        if (typeof record['released_at'] === 'string') {
-          releasedAt = record['released_at'];
-        }
-      }
-    } catch {
-      // Non-JSON body (e.g. proxy HTML error page): keep raw `body` only.
-    }
-    this.code = code;
-    this.releasedAt = releasedAt;
+    this.code = parsed?.code ?? null;
+    this.rawCode = parsed?.rawCode ?? null;
+    this.userMessage = parsed?.message;
+    this.meta = parsed?.meta;
+    this.releasedAt = parsed?.meta.releasedAt ?? null;
   }
 }
 
@@ -206,6 +289,65 @@ export class GuardianHttpClient {
     };
   }
 
+  /**
+   * Request abandonment of a pending canonicalization candidate whose
+   * transaction will never land on-chain (issue #319).
+   *
+   * Records an abandon *intent* (`202 Accepted`): the delta stays a
+   * candidate — the account stays locked — until the guardian's worker
+   * confirms over the abandon quarantine that the transaction did not
+   * land, then discards the delta as `client_abandoned` and releases the
+   * account (typically well under a minute). Poll {@link abandonStatus}
+   * for the resolution. Refused with `GUARDIAN_CANDIDATE_LANDED` (409)
+   * when the transaction actually landed. Retries are idempotent and
+   * preserve the original request timestamp.
+   */
+  async abandonCandidate(accountId: string, nonce: number): Promise<AbandonCandidateResponse> {
+    const serverRequest: ServerAbandonCandidateRequest = { account_id: accountId, nonce };
+    const response = await this.fetchAuthenticated('/delta/candidate/abandon', {
+      method: 'POST',
+      body: JSON.stringify(serverRequest),
+    }, accountId, serverRequest);
+    const server = (await response.json()) as ServerAbandonCandidateResponse;
+    return {
+      accountId: server.account_id,
+      nonce: server.nonce,
+      state: server.state,
+      abandonRequestedAt: server.abandon_requested_at,
+    };
+  }
+
+  /**
+   * Poll the resolution of an abandon request made with
+   * {@link abandonCandidate}: `'waiting'` while the quarantine runs,
+   * `'landed'` if the transaction landed after all (the delta
+   * canonicalized), `'abandoned'` once the delta is discarded as
+   * client-abandoned and the account released, `'unexpected'` for any
+   * state no abandon flow produces (including a missing delta).
+   */
+  async abandonStatus(accountId: string, nonce: number): Promise<AbandonStatus> {
+    let delta: DeltaObject;
+    try {
+      delta = await this.getDelta(accountId, nonce);
+    } catch (e) {
+      if (e instanceof GuardianHttpError && e.code === 'delta_not_found') {
+        return 'unexpected';
+      }
+      throw e;
+    }
+    switch (delta.status.status) {
+      case 'candidate':
+        return 'waiting';
+      case 'canonical':
+        return 'landed';
+      case 'discarded':
+        return delta.status.reason === 'client_abandoned' ? 'abandoned' : 'unexpected';
+      default:
+        return 'unexpected';
+    }
+  }
+
+
   async signDeltaProposal(request: SignProposalRequest): Promise<DeltaObject> {
     const serverRequest = toServerSignProposalRequest(request);
     const response = await this.fetchAuthenticated('/delta/proposal', {
@@ -352,7 +494,16 @@ export class GuardianHttpClient {
         },
       });
     } catch (err) {
-      if (retries > 0 && err instanceof GuardianHttpError && err.body.includes('Replay attack')) {
+      // Replay rejections (stale timestamp) are transient: retry once with a
+      // fresh timestamp. The specific "Replay attack" detail is now sanitized
+      // off the wire (feature 009), so branch on the stable auth code instead.
+      // Retrying a genuine auth failure is harmless — one extra attempt that
+      // also fails — and only happens when a retry budget remains.
+      if (
+        retries > 0 &&
+        err instanceof GuardianHttpError &&
+        err.code === 'authentication_failed'
+      ) {
         await new Promise((resolve) => setTimeout(resolve, 50));
         return this.fetchAuthenticated(path, init, accountId, requestPayload, retries - 1);
       }

package/src/index.ts

@@ -1,7 +1,16 @@
 export { GuardianHttpClient, GuardianHttpError } from './http.js';
+export type { GuardianErrorMeta } from './http.js';
+export {
+  GUARDIAN_ERROR_CODES,
+  isGuardianErrorCode,
+  normalizeGuardianErrorCode,
+} from './error-codes.js';
+export type { GuardianErrorCode } from './error-codes.js';
 export { RequestAuthPayload } from './auth-request.js';
 
 export type {
+  AbandonCandidateResponse,
+  AbandonStatus,
   Signer,
   FalconSignature,
   EcdsaSignature,

package/src/server-types.ts

@@ -21,7 +21,7 @@ export type ServerDeltaStatus =
   | { status: 'pending'; timestamp: string; proposer_id: string; cosigner_sigs: ServerCosignerSignature[] }
   | { status: 'candidate'; timestamp: string }
   | { status: 'canonical'; timestamp: string }
-  | { status: 'discarded'; timestamp: string };
+  | { status: 'discarded'; timestamp: string; reason?: string };
 
 export type ServerProposalType =
   | 'add_signer'
@@ -54,6 +54,8 @@ export interface ServerProposalMetadata {
   recipient_id?: string;
   faucet_id?: string;
   amount?: string;
+  /** P2ID note visibility, "public" or "private" (issue #322). Absent => public. */
+  note_type?: string;
 }
 
 export interface ServerDeltaObject {
@@ -137,6 +139,18 @@ export interface ServerProposalsResponse {
   proposals: ServerDeltaObject[];
 }
 
+export interface ServerAbandonCandidateRequest {
+  account_id: string;
+  nonce: number;
+}
+
+export interface ServerAbandonCandidateResponse {
+  account_id: string;
+  nonce: number;
+  state: 'pending' | 'abandoned';
+  abandon_requested_at?: string;
+}
+
 export interface ServerSignProposalRequest {
   account_id: string;
   commitment: string;

package/src/types.ts

@@ -65,7 +65,7 @@ export type DeltaStatus =
   | { status: 'pending'; timestamp: string; proposerId: string; cosignerSigs: CosignerSignature[] }
   | { status: 'candidate'; timestamp: string }
   | { status: 'canonical'; timestamp: string }
-  | { status: 'discarded'; timestamp: string };
+  | { status: 'discarded'; timestamp: string; reason?: string };
 
 export type ProposalType =
   | 'add_signer'
@@ -98,6 +98,8 @@ export interface ProposalMetadata {
   recipientId?: string;
   faucetId?: string;
   amount?: string;
+  /** P2ID note visibility, "public" or "private" (issue #322). Absent => public. */
+  noteType?: string;
 }
 
 export interface DeltaObject {
@@ -187,6 +189,26 @@ export interface SignProposalRequest {
   signature: ProposalSignature;
 }
 
+export interface AbandonCandidateResponse {
+  accountId: string;
+  nonce: number;
+  /**
+   * `'pending'` while the guardian's worker still has to resolve the
+   * abandon intent (the account stays locked until then); `'abandoned'`
+   * once the delta is discarded as client-abandoned and the account
+   * released.
+   */
+  state: 'pending' | 'abandoned';
+  /**
+   * RFC 3339 UTC timestamp of the recorded abandon request. Retries
+   * return the original timestamp; absent once resolved.
+   */
+  abandonRequestedAt?: string;
+}
+
+/** Resolution of an abandon request, as observed via the delta feed. */
+export type AbandonStatus = 'waiting' | 'landed' | 'abandoned' | 'unexpected';
+
 export interface PushDeltaResponse {
   accountId: string;
   nonce: number;

package/dist/auth-request.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=auth-request.test.d.ts.map

package/dist/auth-request.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"auth-request.test.d.ts","sourceRoot":"","sources":["../src/auth-request.test.ts"],"names":[],"mappings":""}

package/dist/auth-request.test.js

@@ -1,10 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { RequestAuthPayload } from './auth-request.js';
-describe('RequestAuthPayload', () => {
-    it('canonicalizes object keys recursively', () => {
-        const left = RequestAuthPayload.fromRequest({ b: 2, a: { y: 2, x: 1 } });
-        const right = RequestAuthPayload.fromRequest({ a: { x: 1, y: 2 }, b: 2 });
-        expect(left.toCanonicalJson()).toEqual(right.toCanonicalJson());
-    });
-});
-//# sourceMappingURL=auth-request.test.js.map

package/dist/auth-request.test.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"auth-request.test.js","sourceRoot":"","sources":["../src/auth-request.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,IAAI,GAAG,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QACzE,MAAM,KAAK,GAAG,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAE1E,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/conversion.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=conversion.test.d.ts.map

package/dist/conversion.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"conversion.test.d.ts","sourceRoot":"","sources":["../src/conversion.test.ts"],"names":[],"mappings":""}