Smart Account Authentication

Authentication Library / SDK for working with various cryptographic credentials / authenticators

• Client-side tools for requesting credentials and their serializations
• Verification (+ storage) logic for Rust environments.
• Ideal for smart accounts, wallets and apps with build-in authentication

Goals and Focus-Area

• Definition of useful data structure, trais and utlity functions
• Formatting data according to specs. Primarily with use of envelopes
• Serialisation and deserialisation of the date depending on context
• Passing data to underlying cryptographic APIs and libraries
• Dealing with batches / multiple credentials at the same time
• [FEAT] Protection against replay attacks
• [FEAT] Encapsulated storage of the credentials
• [FEAT] Encapsulated reconstruction & verification of credentials from payload

Cryptography

• ⚡ Delegations verification to available APIs for efficiency
• ⚙️ Native version relies on cosmwasm-crypto

Other Info

• Encoding: By default using base64 everywhere. The exceptions are primarily when it makes sense according to the specs of a credential such as Eth addresses using hex or webauthn challenge using base64url

Supported Credentials

Virtual Machine Support

Legend: Complete = fully supported, Partial = limited or experimental, Serialization = only data formatting available

Smart Contracts / Programs

Installation

# Add the library to your project
cargo add smart-account-auth

You can also give the library an alias to simplify typing

# to import for CosmWasm(v1) contracts with all default features 
saa  = { package = "smart-account-auth", version = "0.24.5", features = ["cosmwasm"] }

Features

Environment specific features that are mutually exclusive and shouldn't be used together. Pick depending on your virtual machine:

Credential specific features allow you to include / exclude specific credential types for better control and optimizing the binary size:

The following features give you access to additional logic related to better control or additional security

The following features enable or disable inner primitives to ether help you out or to reduce the binary size as much as possible

The following credentials are not meant to be specified directly and used only internal purposes 🚫

Verification

Single Credential

use cosmwasm_std::Binary;
use smart_acccount_auth::{traits::Verifiable, EvmCredential};

let evm_credential = EvmCredential {
    message:   Binary::from_base64( ** your message ** ),
    signature: Binary::from_base64( ** your signature **),
    signer:    String::from("0x...") // your eth address
}

# native rust code
evm_credential.verify()?:

# cosmwasm (feature) api code
evm_credential.verify_cosmwasm(deps.api)?;

Multiple Credentials / Credentil Data Wrapper

use smart_acccount_auth::{traits::{Verifiable, CredentialsWrapper}, CredentialData};

let credential_data = CredentialData {
    credentials         :  vec![ ** your credentials here **  ],
    // whether to allow the sender address to be an authority over account
    // set to false if calling using a relayer 
    with_caller         :  Some(true),
    // index of "main" credential if it exists
    primary_index   :  Some(0)
}

# native rust code
credential_data.verify()?;

# cosmwasm (feature) api code
credential_data.verify_cosmwasm(deps.api)?;

// pick a credential under primary index, (first credential if not set)
let cred = data.primary();

// Examples of using the credential
let id = cred.id();

if cred.is_cosmos_derivable() {
    // wull be using passed hrp if available or the default
    let cosmos_address = cred.cosmos_address(deps.api);
}

Typescript

Installation

Add the library to your project

npm install smart-account-auth

Usage

Basics

Requesting a credential is as simple as calling a function with a message to be signed and passing the neccecary signer information

import { getEthPersonalSignCredential } from 'smart-account-auth';
const ethCredential = await getEthPersonalSignCredential(window.ethereum, message)

or

import { getCosmosArbitraryCredential } from 'smart-account-auth';
const cosmosCredential = await getCosmosArbitraryCredential(window.keplr, chainId, message)

Passkeys

For passkeys you need to check whether a credential has been registeted and prompt the user to register one if it hasn't

import { getPasskeyCredential, registerPasskey } from 'smart-account-auth'

// By default the library uses local storage to store passkeys
const stored = localStorage.getItem('passkeys');
let getPasskeyCredPromise : Promise<Credential>;

if (stored) {
    // id and pubkey will be read from local storage
    getPasskeyCredPromise = getPasskeyCredential(message)
} else {
    const passkeyName = "My App Passkey";
    const { id, pubkey } = await registerPasskey(passkeyName);
    getPasskeyCredPromise =  getPasskeyCredential(message, id, pubkey)
}

const credential = await getPasskeyCredPromise;

Replay Attack Protection

If replay attack protection is enabled on the contract side, the message to be signed must be a json string of the following format

type DataToSign = {
    chain_id: string,
    contract_address: string,
    messages: any[],
    nonce: string
  }

The order of the fields is important (set to alphabetical order) and the nonce must be equal to the current account number

Multiple Credentials / Credential Data Wrapper

You can use CredentialData object to wrap multiple credentials and efficiently verify them in a single call

import { CredentialData } from 'smart-account-auth'

const data : CredentialData = {
    // whether to allow the sender address to be an authority over account
    with_caller: false,
    // credentials that can control the account
    credentials: [ethCredential, passkeyCredential],
    // index of "main" credential that will be used by default
    primaryIndex: 0
} 

Meta / Usage

• OpenSource -> Low Funding / Resources -> Contributions are especially needed and welcomed
• Authors of the library are also its main users. The experience is iteratively used to improve the SDK by understanding the needs and shifting more and more logic from apps to the lib.
• CosmWasm retains the status of the primary target and used the most often during feature design stage and for tests. The main reason is being funded through quadrating funding on DoraHacks.

Disclaimer

• 🛠 In-Active development. Breaking changes might occur
• 👾 Test coverage to be improved and some bugs might occur
• ⚠️ The project hasn't been audited. Use at your own risk