@cavos/cli 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+import { Call } from 'starknet';
+export { Call } from 'starknet';
+
+interface SessionKeyPolicy {
+    spendingLimits: Array<{
+        token: string;
+        limit: bigint;
+    }>;
+    allowedContracts: string[];
+    maxCallsPerTx: number;
+}
+interface AgentConfig {
+    appId: string;
+    network?: 'mainnet' | 'sepolia';
+    backendUrl?: string;
+    starknetRpcUrl?: string;
+    paymasterApiKey?: string;
+    policy?: SessionKeyPolicy;
+    sessionDuration?: number;
+    renewalGracePeriod?: number;
+}
+interface NonceParams {
+    sessionPubKey: string;
+    validAfter: bigint;
+    validUntil: bigint;
+    renewalDeadline: bigint;
+    randomness: bigint;
+}
+interface JWTClaims {
+    sub: string;
+    nonce: string;
+    exp: number;
+    iss: string;
+    aud: string;
+}
+interface SessionStatus {
+    registered: boolean;
+    expired: boolean;
+    canRenew: boolean;
+    validUntil?: bigint;
+    renewalDeadline?: bigint;
+}
+
+declare class CavosAgent {
+    private config;
+    private provider;
+    private session;
+    private appSalt;
+    constructor(config: AgentConfig);
+    /**
+     * Login with Firebase email/password.
+     * Generates session keys, authenticates, and persists the session.
+     */
+    login(email: string, password: string, walletName?: string): Promise<void>;
+    /**
+     * Login using a pre-existing JWT token.
+     * Useful for non-interactive agents or CI/CD.
+     */
+    loginWithJWT(jwt: string, walletName?: string): Promise<void>;
+    /**
+     * Check if the agent has a valid session.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get the wallet address.
+     */
+    getAddress(): string | null;
+    /**
+     * Logout — clear the persisted session.
+     */
+    logout(): void;
+    /**
+     * Execute one or more calls via paymaster.
+     * Handles session registration automatically on first call.
+     */
+    execute(calls: Call | Call[]): Promise<string>;
+    /**
+     * Transfer ERC-20 tokens.
+     */
+    transfer(tokenAddress: string, to: string, amount: bigint): Promise<string>;
+    /**
+     * Approve ERC-20 spending.
+     */
+    approve(tokenAddress: string, spender: string, amount: bigint): Promise<string>;
+    /**
+     * Deploy the account contract.
+     */
+    deploy(): Promise<string>;
+    /**
+     * Get ERC-20 balance.
+     */
+    getBalance(tokenAddress?: string): Promise<bigint>;
+    /**
+     * Check if the account is deployed.
+     */
+    isDeployed(): Promise<boolean>;
+    /**
+     * Get on-chain session status.
+     */
+    getSessionStatus(): Promise<SessionStatus>;
+    /**
+     * Renew the current session (if in grace period).
+     */
+    renewSession(): Promise<string>;
+    /**
+     * Revoke a specific session key (defaults to current).
+     */
+    revokeSession(sessionKey?: string): Promise<string>;
+    /**
+     * Emergency revoke all sessions.
+     */
+    emergencyRevokeAll(): Promise<string>;
+    private ensureSession;
+    private getSalt;
+    private getPaymasterKey;
+    private restoreSession;
+}
+
+/**
+ * Generate a new session key pair.
+ */
+declare function generateSessionKeyPair(): {
+    privateKey: string;
+    publicKey: string;
+};
+/**
+ * Build a lightweight session signature (SESSION_V1).
+ * Used for transactions after the session is registered on-chain.
+ */
+declare function buildSessionSignature(transactionHash: string, sessionPrivateKey: string, sessionPubKey: string, calls?: {
+    contractAddress: string;
+}[], policy?: SessionKeyPolicy): string[];
+/**
+ * Build the full JWT signature data (OAUTH_JWT_V1) for on-chain verification.
+ * Used for the first transaction to register the session.
+ */
+declare function buildJWTSignatureData(transactionHash: string, session: {
+    jwt: string;
+    sessionPrivateKey: string;
+    sessionPubKey: string;
+    nonce: string;
+    nonceParams: NonceParams;
+    jwtClaims: {
+        sub: string;
+        nonce: string;
+        exp: number;
+        iss: string;
+        aud: string;
+    };
+    sessionPolicy?: SessionKeyPolicy;
+}, salt: string, backendUrl: string): Promise<string[]>;
+
+/**
+ * Compute the nonce for a session.
+ * Must match Cairo: PoseidonTrait::new().update(session_key).update(valid_until).update(randomness).finalize()
+ */
+declare function computeNonce(params: NonceParams): string;
+/**
+ * Generate nonce parameters for a new session.
+ */
+declare function generateNonceParams(sessionPubKey: string, currentTimestamp: bigint, sessionDurationSeconds?: bigint, renewalGraceSeconds?: bigint): NonceParams;
+
+/**
+ * Compute the address seed from a user's OAuth `sub` claim and a salt.
+ * The salt can optionally incorporate a wallet name to allow multiple addresses per sub.
+ */
+declare function computeAddressSeed(sub: string, salt: string, walletName?: string): string;
+/**
+ * Compute the contract address for an OAuth wallet.
+ */
+declare function computeContractAddress(sub: string, salt: string, classHash: string, jwksRegistryAddress: string, walletName?: string): string;
+
+/**
+ * Compute Merkle root from a list of allowed contract addresses.
+ * Uses Poseidon hash, matching the on-chain verification.
+ */
+declare function computeMerkleRoot(contracts: string[]): string;
+/**
+ * Compute Merkle proof for a given contract address.
+ */
+declare function computeMerkleProof(contracts: string[], targetContract: string): string[];
+
+declare const TOKENS_SEPOLIA: {
+    readonly STRK: "0x04718f5a0Fc34cC1AF16A1cdee98fFB20C31f5cD61D6Ab07201858f4287c938D";
+    readonly ETH: "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
+};
+declare const TOKENS_MAINNET: {
+    readonly STRK: "0x04718f5a0Fc34cC1AF16A1cdee98fFB20C31f5cD61D6Ab07201858f4287c938D";
+    readonly ETH: "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
+};
+
+export { type AgentConfig, CavosAgent, type JWTClaims, type NonceParams, type SessionKeyPolicy, type SessionStatus, TOKENS_MAINNET, TOKENS_SEPOLIA, buildJWTSignatureData, buildSessionSignature, computeAddressSeed, computeContractAddress, computeMerkleProof, computeMerkleRoot, computeNonce, generateNonceParams, generateSessionKeyPair };