Authentication & Authorization

/**
 * Authentication interface with stores for keys, topics, and requests
 * Manages authentication flows and CACAO handling
 */
type IAuth = {
  /** Authentication key store */
  authKeys: IStore;
  /** Pairing topic store */ 
  pairingTopics: IStore;
  /** Authentication request store */
  requests: IStore<AuthTypes.PendingRequest>;
};

namespace AuthTypes {
  /**
   * Complete CACAO structure for authentication
   */
  interface Cacao {
    /** CACAO header */
    h: CacaoHeader;
    /** CACAO payload */
    p: CacaoPayload;
    /** CACAO signature */
    s: CacaoSignature;
  }

  /**
   * CACAO header structure
   */
  interface CacaoHeader {
    /** Token type (typically "CAIP-122") */
    t: string;
  }

  /**
   * CACAO payload structure with authentication details
   */
  interface CacaoPayload {
    /** Domain requesting authentication */
    domain: string;
    /** Audience (typically the dApp URL) */
    aud: string;
    /** CACAO version */
    version: string;
    /** Random nonce for replay protection */
    nonce: string;
    /** Issued at timestamp (ISO 8601) */
    iat: string;
    /** Not before timestamp (optional, ISO 8601) */
    nbf?: string;
    /** Expiration timestamp (optional, ISO 8601) */
    exp?: string;
    /** Human-readable statement (optional) */
    statement?: string;
    /** Request ID for tracking (optional) */
    requestId?: string;
    /** Additional resources (optional) */
    resources?: string[];
  }

  /**
   * CACAO signature structure
   */
  interface CacaoSignature {
    /** Signature type */
    t: string;
    /** Signature value */
    s: string;
    /** Optional signature metadata */
    m?: string;
  }
}

namespace AuthTypes {
  /**
   * Session authentication parameters
   */
  interface SessionAuthenticateParams {
    /** Supported blockchain chains */
    chains: string[];
    /** Domain requesting authentication */
    domain: string;
    /** Random nonce for replay protection */
    nonce: string;
    /** Authentication URI */
    uri: string;
    /** Not before timestamp (optional) */
    nbf?: string;
    /** Expiration timestamp (optional) */
    exp?: string;
    /** Human-readable statement (optional) */
    statement?: string;
    /** Request ID for tracking (optional) */
    requestId?: string;
    /** Additional resources (optional) */
    resources?: string[];
  }

  /**
   * Authentication payload parameters
   */
  interface PayloadParams {
    /** Chain identifier */
    chainId: string;
    /** Domain requesting authentication */
    domain: string;
    /** Random nonce */
    nonce: string;
    /** Authentication URI */
    uri: string;
    /** Version string */
    version: string;
    /** Not before timestamp (optional) */
    nbf?: string;
    /** Expiration timestamp (optional) */
    exp?: string;
    /** Human-readable statement (optional) */
    statement?: string;
    /** Request ID (optional) */
    requestId?: string;
    /** Additional resources (optional) */
    resources?: string[];
  }

  /**
   * Session authentication request structure
   */
  interface SessionAuthenticateRequest {
    /** Request parameters */
    params: SessionAuthenticateRequestParams;
    /** Verification context */
    verifyContext: Verify.Context;
  }

  /**
   * Session authentication request parameters
   */
  interface SessionAuthenticateRequestParams {
    /** Authentication requester */
    requester: Participant;
    /** Authentication parameters */
    authPayload: PayloadParams;
    /** Expiration timestamp */
    expiryTimestamp: number;
  }

  /**
   * Authentication participant with metadata
   */
  interface Participant {
    /** Participant's public key */
    publicKey: string;
    /** Participant metadata */
    metadata: CoreTypes.Metadata;
  }
}

namespace AuthTypes {
  /**
   * Parameters for formatting auth messages
   */
  type FormatMessageParams = PayloadParams;

  /**
   * Base parameters for auth requests
   */
  interface BaseAuthRequestParams {
    /** Chain identifier */
    chainId: string;
    /** Domain requesting authentication */
    domain: string;
    /** Random nonce */
    nonce: string;
    /** Authentication URI */
    uri: string;
  }

  /**
   * Full authentication request parameters
   */
  interface RequestParams extends BaseAuthRequestParams {
    /** Expiration timestamp (optional) */
    expiry?: number;
    /** Not before timestamp (optional) */
    nbf?: string;
    /** Human-readable statement (optional) */
    statement?: string;
    /** Request ID (optional) */
    requestId?: string;
    /** Additional resources (optional) */
    resources?: string[];
  }

  /**
   * Pending authentication request
   */
  interface PendingRequest {
    /** Request ID */
    id: number;
    /** Request parameters */
    params: SessionAuthenticateParams;
    /** Verification context */
    verifyContext: Verify.Context;
  }

  /**
   * Parameters for approving session authentication
   */
  interface ApproveSessionAuthenticateParams {
    /** Request ID */
    id: number;
    /** Authentication objects */
    auths: Cacao[];
  }

  /**
   * Response parameters for session authentication
   */
  interface SessionAuthenticateResponseParams {
    /** Cached CACAOs */
    cacaos: Cacao[];
    /** Responder information */
    responder: Participant;
  }

  /**
   * Authentication error response
   */
  interface AuthErrorResponse {
    /** Error code */
    code: number;
    /** Error message */
    message: string;
  }

  /**
   * Authentication response type (success or error)
   */
  type AuthResponse = SessionAuthenticateResponseParams | AuthErrorResponse;

  /**
   * Authentication response result
   */
  interface AuthenticateResponseResult {
    /** Session topic */
    topic: string;
    /** Session structure */
    session?: SessionTypes.Struct;
  }
}

namespace AuthTypes {
  /**
   * Authentication event type
   */
  type Event = "session_authenticate";

  /**
   * Base event arguments structure
   */
  interface BaseEventArgs<T = {}> {
    /** Event ID */
    id: number;
    /** Event topic */
    topic: string;
    /** Event parameters */
    params: T;
  }

  /**
   * All authentication event argument types
   */
  interface EventArguments {
    session_authenticate: SessionAuthenticateRequest;
  }

  /**
   * Authentication request event arguments
   */
  interface AuthRequestEventArgs extends BaseEventArgs<SessionAuthenticateParams> {
    /** Verification context */
    verifyContext: Verify.Context;
  }

  /**
   * Authentication response event arguments
   */
  type AuthResponseEventArgs = BaseEventArgs<AuthResponse>;

  /**
   * Authentication client options
   */
  interface Options {
    /** WalletConnect Cloud project ID */
    projectId: string;
    /** Client metadata */
    metadata: CoreTypes.Metadata;
    /** Include optional namespaces (default: false) */
    includeOptionalNamespaces?: boolean;
  }

  /**
   * Authentication metadata structure
   */
  interface Metadata extends CoreTypes.Metadata {
    /** Additional authentication-specific metadata */
    [key: string]: any;
  }

  /**
   * Authentication event callback
   */
  interface EventCallback<T = any> {
    resolve: (value: T) => void;
    reject: (reason: any) => void;
  }
}

namespace JsonRpcTypes {
  /**
   * Default JSON-RPC response type
   */
  type DefaultResponse = true | ErrorResponse;

  /**
   * WalletConnect method names for JSON-RPC communication
   */
  type WcMethod = 
    | "wc_sessionPropose"
    | "wc_sessionSettle" 
    | "wc_sessionUpdate"
    | "wc_sessionExtend"
    | "wc_sessionRequest"
    | "wc_sessionEvent"
    | "wc_sessionDelete"
    | "wc_sessionPing"
    | "wc_sessionAuthenticate";

  /**
   * Request parameters for all WC methods
   */
  interface RequestParams {
    wc_sessionPropose: {
      relays: RelayerTypes.ProtocolOptions[];
      requiredNamespaces: ProposalTypes.RequiredNamespaces;
      optionalNamespaces?: ProposalTypes.OptionalNamespaces;
      sessionProperties?: ProposalTypes.SessionProperties;
      proposer: SessionTypes.Participant;
    };
    wc_sessionSettle: {
      relay: RelayerTypes.ProtocolOptions;
      namespaces: SessionTypes.Namespaces;
      controller: SessionTypes.Participant;
      expiry: number;
    };
    wc_sessionUpdate: {
      namespaces: SessionTypes.Namespaces;
    };
    wc_sessionExtend: {};
    wc_sessionRequest: {
      request: {
        method: string;
        params: any;
      };
      chainId: string;
    };
    wc_sessionEvent: {
      event: {
        name: string;
        data: any;
      };
      chainId: string;
    };
    wc_sessionDelete: {
      code: number;
      message: string;
    };
    wc_sessionPing: {};
    wc_sessionAuthenticate: {
      authPayload: AuthTypes.PayloadParams;
      requester: AuthTypes.Participant;
      expiryTimestamp: number;
    };
  }

  /**
   * Response results for all WC methods
   */
  interface Results {
    wc_sessionPropose: DefaultResponse;
    wc_sessionSettle: DefaultResponse;
    wc_sessionUpdate: DefaultResponse;
    wc_sessionExtend: DefaultResponse;
    wc_sessionRequest: any;
    wc_sessionEvent: DefaultResponse;
    wc_sessionDelete: DefaultResponse;
    wc_sessionPing: DefaultResponse;
    wc_sessionAuthenticate: {
      cacaos: AuthTypes.Cacao[];
      responder: AuthTypes.Participant;
    };
  }

  /**
   * JSON-RPC error type
   */
  type Error = ErrorResponse;
}

namespace PendingRequestTypes {
  /**
   * Pending request structure
   */
  interface Struct {
    /** Request ID */
    id: number;
    /** Request topic */
    topic: string;
    /** Request parameters */
    params: any;
    /** Verification context */
    verifyContext: Verify.Context;
  }
}

/**
 * Store interface for pending requests
 */
type IPendingRequest = IStore<PendingRequestTypes.Struct>;

import { AuthTypes, JsonRpcTypes } from "@walletconnect/types";

// Create CACAO for authentication
const cacao: AuthTypes.Cacao = {
  h: { t: "CAIP-122" },
  p: {
    domain: "example.com",
    aud: "https://example.com/app",
    version: "1",
    nonce: "random-nonce-123",
    iat: new Date().toISOString(),
    statement: "Sign in to Example App"
  },
  s: {
    t: "eip191",
    s: "0x..."
  }
};

// Session authentication parameters
const authParams: AuthTypes.SessionAuthenticateParams = {
  chains: ["eip155:1", "eip155:137"],
  domain: "example.com",
  nonce: "random-nonce-456", 
  uri: "https://example.com/app",
  statement: "Sign in to access your wallet",
  resources: ["https://example.com/terms"]
};

// Authentication request
const authRequest: JsonRpcTypes.RequestParams["wc_sessionAuthenticate"] = {
  authPayload: {
    chainId: "eip155:1",
    domain: "example.com",
    nonce: "random-nonce-789",
    uri: "https://example.com/app",
    version: "1"
  },
  requester: {
    publicKey: "0x04...",
    metadata: {
      name: "Example dApp",
      description: "A sample decentralized application",
      url: "https://example.com",
      icons: ["https://example.com/icon.png"]
    }
  },
  expiryTimestamp: Date.now() + 300000 // 5 minutes
};

// Approve authentication
const approveParams: AuthTypes.ApproveSessionAuthenticateParams = {
  id: 1,
  auths: [cacao]
};