@openzeppelin/guardian-client 0.13.2

package/src/http.ts

@@ -0,0 +1,244 @@
+import type {
+  ConfigureRequest,
+  ConfigureResponse,
+  DeltaObject,
+  DeltaProposalRequest,
+  DeltaProposalResponse,
+  ExecutionDelta,
+  PubkeyResponse,
+  PushDeltaResponse,
+  SignProposalRequest,
+  SignatureScheme,
+  Signer,
+  StateObject,
+} from './types.js';
+import { RequestAuthPayload } from './auth-request.js';
+import type {
+  ServerDeltaObject,
+  ServerDeltaProposalResponse,
+  ServerProposalsResponse,
+  ServerPubkeyResponse,
+  ServerStateObject,
+  ServerConfigureResponse,
+  ServerPushDeltaResponse,
+} from './server-types.js';
+import {
+  fromServerConfigureResponse,
+  fromServerDeltaObject,
+  fromServerStateObject,
+  toServerConfigureRequest,
+  toServerDeltaProposalRequest,
+  toServerExecutionDelta,
+  toServerSignProposalRequest,
+} from './conversion.js';
+
+/**
+ * Error thrown by the GUARDIAN HTTP client.
+ */
+export class GuardianHttpError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly statusText: string,
+    public readonly body: string
+  ) {
+    super(`GUARDIAN HTTP error ${status}: ${statusText} - ${body}`);
+    this.name = 'GuardianHttpError';
+  }
+}
+
+/**
+ * Minimal HTTP client for GUARDIAN server.
+ */
+export class GuardianHttpClient {
+  private signer: Signer | null = null;
+  private readonly baseUrl: string;
+  private lastTimestamp = 0;
+
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl;
+  }
+
+  setSigner(signer: Signer): void {
+    this.signer = signer;
+  }
+
+  async getPubkey(scheme?: SignatureScheme): Promise<PubkeyResponse> {
+    const query = scheme ? `?scheme=${scheme}` : '';
+    const response = await this.fetch(`/pubkey${query}`, { method: 'GET' });
+    const data = (await response.json()) as ServerPubkeyResponse;
+    return {
+      commitment: data.commitment,
+      pubkey: data.pubkey,
+    };
+  }
+
+  async configure(request: ConfigureRequest): Promise<ConfigureResponse> {
+    const serverRequest = toServerConfigureRequest(request);
+    const response = await this.fetchAuthenticated('/configure', {
+      method: 'POST',
+      body: JSON.stringify(serverRequest),
+    }, request.accountId, serverRequest);
+    const server = (await response.json()) as ServerConfigureResponse;
+    return fromServerConfigureResponse(server);
+  }
+
+  async getState(accountId: string): Promise<StateObject> {
+    const requestQuery = { account_id: accountId };
+    const params = new URLSearchParams(requestQuery);
+    const response = await this.fetchAuthenticated(`/state?${params}`, {
+      method: 'GET',
+    }, accountId, requestQuery);
+    const server = (await response.json()) as ServerStateObject;
+    return fromServerStateObject(server);
+  }
+
+  async getDeltaProposals(accountId: string): Promise<DeltaObject[]> {
+    const requestQuery = { account_id: accountId };
+    const params = new URLSearchParams(requestQuery);
+    const response = await this.fetchAuthenticated(`/delta/proposal?${params}`, {
+      method: 'GET',
+    }, accountId, requestQuery);
+    const data = (await response.json()) as ServerProposalsResponse;
+    return data.proposals.map(fromServerDeltaObject);
+  }
+
+  async getDeltaProposal(accountId: string, commitment: string): Promise<DeltaObject> {
+    const requestQuery = { account_id: accountId, commitment };
+    const params = new URLSearchParams(requestQuery);
+    const response = await this.fetchAuthenticated(`/delta/proposal/single?${params}`, {
+      method: 'GET',
+    }, accountId, requestQuery);
+    const data = (await response.json()) as ServerDeltaObject;
+    return fromServerDeltaObject(data);
+  }
+
+  async pushDeltaProposal(request: DeltaProposalRequest): Promise<DeltaProposalResponse> {
+    const serverRequest = toServerDeltaProposalRequest(request);
+    const response = await this.fetchAuthenticated('/delta/proposal', {
+      method: 'POST',
+      body: JSON.stringify(serverRequest),
+    }, request.accountId, serverRequest);
+    const server = (await response.json()) as ServerDeltaProposalResponse;
+    return {
+      delta: fromServerDeltaObject(server.delta),
+      commitment: server.commitment,
+    };
+  }
+
+  async signDeltaProposal(request: SignProposalRequest): Promise<DeltaObject> {
+    const serverRequest = toServerSignProposalRequest(request);
+    const response = await this.fetchAuthenticated('/delta/proposal', {
+      method: 'PUT',
+      body: JSON.stringify(serverRequest),
+    }, request.accountId, serverRequest);
+    const server = (await response.json()) as ServerDeltaObject;
+    return fromServerDeltaObject(server);
+  }
+
+  async pushDelta(delta: ExecutionDelta): Promise<PushDeltaResponse> {
+    const serverDelta = toServerExecutionDelta(delta);
+    const response = await this.fetchAuthenticated('/delta', {
+      method: 'POST',
+      body: JSON.stringify(serverDelta),
+    }, delta.accountId, serverDelta);
+    const server = (await response.json()) as ServerPushDeltaResponse;
+    return {
+      accountId: server.account_id,
+      nonce: server.nonce,
+      newCommitment: server.new_commitment,
+      ackSig: server.ack_sig,
+      ackPubkey: server.ack_pubkey,
+      ackScheme: server.ack_scheme,
+    };
+  }
+
+  async getDelta(accountId: string, nonce: number): Promise<DeltaObject> {
+    const requestPayload = {
+      account_id: accountId,
+      nonce,
+    };
+    const requestQuery = {
+      account_id: accountId,
+      nonce: nonce.toString(),
+    };
+    const params = new URLSearchParams(requestQuery);
+    const response = await this.fetchAuthenticated(`/delta?${params}`, {
+      method: 'GET',
+    }, accountId, requestPayload);
+    const server = (await response.json()) as ServerDeltaObject;
+    return fromServerDeltaObject(server);
+  }
+
+  async getDeltaSince(accountId: string, fromNonce: number): Promise<DeltaObject> {
+    const requestPayload = {
+      account_id: accountId,
+      nonce: fromNonce,
+    };
+    const requestQuery = {
+      account_id: accountId,
+      nonce: fromNonce.toString(),
+    };
+    const params = new URLSearchParams(requestQuery);
+    const response = await this.fetchAuthenticated(`/delta/since?${params}`, {
+      method: 'GET',
+    }, accountId, requestPayload);
+    const server = (await response.json()) as ServerDeltaObject;
+    return fromServerDeltaObject(server);
+  }
+
+  private async fetch(path: string, init: RequestInit): Promise<Response> {
+    const url = `${this.baseUrl}${path}`;
+    const response = await fetch(url, {
+      ...init,
+      headers: {
+        'Content-Type': 'application/json',
+        ...init.headers,
+      },
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      throw new GuardianHttpError(response.status, response.statusText, body);
+    }
+
+    return response;
+  }
+
+  private async fetchAuthenticated(
+    path: string,
+    init: RequestInit,
+    accountId: string,
+    requestPayload: unknown,
+    retries = 2
+  ): Promise<Response> {
+    if (!this.signer) {
+      throw new Error('No signer configured. Call setSigner() first.');
+    }
+
+    const now = Date.now();
+    const timestamp = now > this.lastTimestamp ? now : this.lastTimestamp + 1;
+    this.lastTimestamp = timestamp;
+    const authPayload = RequestAuthPayload.fromRequest(requestPayload);
+    const signature = this.signer.signRequest
+      ? await this.signer.signRequest(accountId, timestamp, authPayload)
+      : await this.signer.signAccountIdWithTimestamp(accountId, timestamp);
+
+    try {
+      return await this.fetch(path, {
+        ...init,
+        headers: {
+          ...init.headers,
+          'x-pubkey': this.signer.publicKey,
+          'x-signature': signature,
+          'x-timestamp': timestamp.toString(),
+        },
+      });
+    } catch (err) {
+      if (retries > 0 && err instanceof GuardianHttpError && err.body.includes('Replay attack')) {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        return this.fetchAuthenticated(path, init, accountId, requestPayload, retries - 1);
+      }
+      throw err;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export { GuardianHttpClient, GuardianHttpError } from './http.js';
+export { RequestAuthPayload } from './auth-request.js';
+
+export type {
+  Signer,
+  FalconSignature,
+  EcdsaSignature,
+  ProposalSignature,
+  SignatureScheme,
+  CosignerSignature,
+  AuthConfig,
+  DeltaStatus,
+  DeltaObject,
+  ExecutionDelta,
+  StateObject,
+  ProposalType,
+  ProposalMetadata,
+  ConfigureRequest,
+  ConfigureResponse,
+  PubkeyResponse,
+  DeltaProposalRequest,
+  DeltaProposalResponse,
+  ProposalsResponse,
+  SignProposalRequest,
+} from './types.js';

package/src/server-types.ts

@@ -0,0 +1,142 @@
+export interface ServerFalconSignature {
+  scheme: 'falcon';
+  signature: string;
+}
+
+export interface ServerEcdsaSignature {
+  scheme: 'ecdsa';
+  signature: string;
+  public_key?: string;
+}
+
+export type ServerProposalSignature = ServerFalconSignature | ServerEcdsaSignature;
+
+export interface ServerCosignerSignature {
+  signer_id: string;
+  signature: ServerProposalSignature;
+  timestamp: string;
+}
+
+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 };
+
+export type ServerProposalType =
+  | 'add_signer'
+  | 'remove_signer'
+  | 'change_threshold'
+  | 'update_procedure_threshold'
+  | 'switch_guardian'
+  | 'consume_notes'
+  | 'p2id'
+  | 'custom';
+
+export interface ServerProposalMetadata {
+  proposal_type?: ServerProposalType;
+  target_threshold?: number;
+  required_signatures?: number;
+  signer_commitments?: string[];
+  target_procedure?: string;
+  salt?: string;
+  description?: string;
+  new_guardian_pubkey?: string;
+  new_guardian_endpoint?: string;
+  note_ids?: string[];
+  recipient_id?: string;
+  faucet_id?: string;
+  amount?: string;
+}
+
+export interface ServerDeltaObject {
+  account_id: string;
+  nonce: number;
+  prev_commitment: string;
+  new_commitment?: string;
+  delta_payload: {
+    tx_summary?: { data: string };
+    data?: string;
+    signatures?: Array<{ signer_id: string; signature: ServerProposalSignature }>;
+    metadata?: ServerProposalMetadata;
+  };
+  ack_sig?: string;
+  ack_pubkey?: string;
+  ack_scheme?: string;
+  status: ServerDeltaStatus;
+}
+
+export interface ServerPushDeltaResponse {
+  account_id: string;
+  nonce: number;
+  new_commitment?: string;
+  ack_sig?: string;
+  ack_pubkey?: string;
+  ack_scheme?: string;
+}
+
+export interface ServerExecutionDelta {
+  account_id: string;
+  nonce: number;
+  prev_commitment: string;
+  new_commitment?: string;
+  delta_payload: { data: string };
+  ack_sig?: string;
+  status: ServerDeltaStatus;
+}
+
+export interface ServerStateObject {
+  account_id: string;
+  commitment: string;
+  state_json: { data: string };
+  created_at: string;
+  updated_at: string;
+  auth_scheme?: string;
+}
+
+export type ServerAuthConfig =
+  | { MidenFalconRpo: { cosigner_commitments: string[] } }
+  | { MidenEcdsa: { cosigner_commitments: string[] } };
+
+export interface ServerConfigureRequest {
+  account_id: string;
+  auth: ServerAuthConfig;
+  initial_state: { data: string; account_id: string };
+}
+
+export interface ServerConfigureResponse {
+  success: boolean;
+  message: string;
+  ack_pubkey?: string;
+  ack_commitment?: string;
+}
+
+export interface ServerDeltaProposalRequest {
+  account_id: string;
+  nonce: number;
+  delta_payload: {
+    tx_summary: { data: string };
+    signatures: Array<{ signer_id: string; signature: ServerProposalSignature }>;
+    metadata?: ServerProposalMetadata;
+  };
+}
+
+export interface ServerDeltaProposalResponse {
+  delta: ServerDeltaObject;
+  commitment: string;
+}
+
+export interface ServerProposalsResponse {
+  proposals: ServerDeltaObject[];
+}
+
+export interface ServerSignProposalRequest {
+  account_id: string;
+  commitment: string;
+  signature: ServerProposalSignature;
+}
+
+export interface ServerPubkeyResponse {
+  commitment: string;
+  pubkey?: string;
+}

package/src/types.ts

@@ -0,0 +1,167 @@
+import type { RequestAuthPayload } from './auth-request.js';
+
+export interface Signer {
+  readonly commitment: string;
+  readonly publicKey: string;
+  readonly scheme: SignatureScheme;
+  signAccountIdWithTimestamp(accountId: string, timestamp: number): Promise<string> | string;
+  signRequest?(
+    accountId: string,
+    timestamp: number,
+    requestPayload: RequestAuthPayload
+  ): Promise<string> | string;
+  signCommitment(commitmentHex: string): Promise<string> | string;
+}
+
+export interface FalconSignature {
+  scheme: 'falcon';
+  signature: string;
+}
+
+export interface EcdsaSignature {
+  scheme: 'ecdsa';
+  signature: string;
+  publicKey?: string;
+}
+
+export type ProposalSignature = FalconSignature | EcdsaSignature;
+
+export type SignatureScheme = 'falcon' | 'ecdsa';
+
+export type AuthConfig =
+  | {
+      MidenFalconRpo: {
+        cosigner_commitments: string[];
+      };
+    }
+  | {
+      MidenEcdsa: {
+        cosigner_commitments: string[];
+      };
+    };
+
+export interface CosignerSignature {
+  signerId: string;
+  signature: ProposalSignature;
+  timestamp: string;
+}
+
+export type DeltaStatus =
+  | { status: 'pending'; timestamp: string; proposerId: string; cosignerSigs: CosignerSignature[] }
+  | { status: 'candidate'; timestamp: string }
+  | { status: 'canonical'; timestamp: string }
+  | { status: 'discarded'; timestamp: string };
+
+export type ProposalType =
+  | 'add_signer'
+  | 'remove_signer'
+  | 'change_threshold'
+  | 'update_procedure_threshold'
+  | 'switch_guardian'
+  | 'consume_notes'
+  | 'p2id'
+  | 'custom'
+  | 'unknown';
+
+export interface ProposalMetadata {
+  proposalType?: ProposalType;
+  targetThreshold?: number;
+  requiredSignatures?: number;
+  signerCommitments?: string[];
+  targetProcedure?: string;
+  salt?: string;
+  description?: string;
+  newGuardianPubkey?: string;
+  newGuardianEndpoint?: string;
+  noteIds?: string[];
+  recipientId?: string;
+  faucetId?: string;
+  amount?: string;
+}
+
+export interface DeltaObject {
+  accountId: string;
+  nonce: number;
+  prevCommitment: string;
+  newCommitment?: string;
+  deltaPayload: {
+    txSummary: { data: string };
+    signatures: Array<{ signerId: string; signature: ProposalSignature }>;
+    metadata?: ProposalMetadata;
+  };
+  ackSig?: string;
+  ackPubkey?: string;
+  ackScheme?: string;
+  status: DeltaStatus;
+}
+
+export interface ExecutionDelta {
+  accountId: string;
+  nonce: number;
+  prevCommitment: string;
+  newCommitment?: string;
+  deltaPayload: { data: string };
+  ackSig?: string;
+  status: DeltaStatus;
+}
+
+export interface StateObject {
+  accountId: string;
+  commitment: string;
+  stateJson: { data: string };
+  createdAt: string;
+  updatedAt: string;
+  authScheme?: string;
+}
+
+export interface ConfigureRequest {
+  accountId: string;
+  auth: AuthConfig;
+  initialState: { data: string; accountId: string };
+}
+
+export interface ConfigureResponse {
+  success: boolean;
+  message: string;
+  ackPubkey?: string;
+  ackCommitment?: string;
+}
+
+export interface PubkeyResponse {
+  commitment: string;
+  pubkey?: string;
+}
+
+export interface DeltaProposalRequest {
+  accountId: string;
+  nonce: number;
+  deltaPayload: {
+    txSummary: { data: string };
+    signatures: Array<{ signerId: string; signature: ProposalSignature }>;
+    metadata?: ProposalMetadata;
+  };
+}
+
+export interface DeltaProposalResponse {
+  delta: DeltaObject;
+  commitment: string;
+}
+
+export interface ProposalsResponse {
+  proposals: DeltaObject[];
+}
+
+export interface SignProposalRequest {
+  accountId: string;
+  commitment: string;
+  signature: ProposalSignature;
+}
+
+export interface PushDeltaResponse {
+  accountId: string;
+  nonce: number;
+  newCommitment?: string;
+  ackSig?: string;
+  ackPubkey?: string;
+  ackScheme?: string;
+}