diff --git a/docs/build/guides/conventions/check-auth-tutorials.mdx b/docs/build/guides/conventions/check-auth-tutorials.mdx index 4ccc0b7a7..f41aa1e53 100644 --- a/docs/build/guides/conventions/check-auth-tutorials.mdx +++ b/docs/build/guides/conventions/check-auth-tutorials.mdx @@ -12,23 +12,23 @@ title: Using __check_auth in interesting ways /> -# Tutorial 1: time based restriction on token transfers +## Tutorial 1: time based restriction on token transfers Imagine a multi-sig account contract where certain actions, like transferring tokens, need to be controlled by the time elapsed between consecutive transfers. For example, a token transfer should only be allowed if a certain period of time has passed since the last transfer. This can be useful in scenarios where you want to limit the frequency of transactions to prevent misuse or to implement rate limiting. -## Base Concepts +### Base concepts -#### Time-Based Restrictions +#### Time-based restrictions The idea is to enforce a minimum time interval between consecutive token transfers. Each token can have its own time limit, and the contract will track the last transfer time for each token. -#### Data Storage +#### Data storage The contract will store the time limit and last transfer time for each token in its storage to keep track of these values across transactions. -## Code walkthrough +### Code walkthrough -### Contract Structure and Imports +#### Contract structure and imports ```rust #![no_std] @@ -72,10 +72,10 @@ const TRANSFER_FN: Symbol = symbol_short!("transfer"); ``` -### Contract Initialization: +#### Contract initialization -1. Initializes the contract with a list of signers' public keys. -2. Stores the count of signers in the contract's storage. +1. Initializes the contract with a list of signers' public keys +2. Stores the count of signers in the contract's storage ```rust #[contractimpl] @@ -92,10 +92,10 @@ impl AccountContract { } ``` -### Setting Time Limits +#### Setting time limits -1. Allows setting a time limit for a specific token. -2. Ensures that only the contract itself can set these limits by requiring the contract's authorization. +1. Allows setting a time limit for a specific token +2. Ensures that only the contract itself can set these limits by requiring the contract's authorization ```rust #[contractimpl] @@ -110,11 +110,11 @@ impl AccountContract { } ``` -### Custom authentication and authorization +#### Custom authentication and authorization -1. Authenticates the signatures. -2. Checks if all required signers have signed. -3. Iterates through the authorization context to verify the authorization policy. +1. Authenticates the signatures +2. Checks if all required signers have signed +3. Iterates through the authorization context to verify the authorization policy ```rust #[contractimpl] @@ -156,10 +156,10 @@ impl CustomAccountInterface for AccountContract { } ``` -### Authentication logic +#### Authentication logic -1. Verifies that the signatures are in the correct order and that each signer is authorized. -2. Uses [ed25519_verify](https://docs.rs/soroban-sdk/latest/soroban_sdk/crypto/struct.Crypto.html#method.ed25519_verify) function to verify each signature. +1. Verifies that the signatures are in the correct order and that each signer is authorized +2. Uses [ed25519_verify](https://docs.rs/soroban-sdk/latest/soroban_sdk/crypto/struct.Crypto.html#method.ed25519_verify) function to verify each signature ```rust fn authenticate( @@ -192,11 +192,11 @@ impl CustomAccountInterface for AccountContract { } ``` -### Authorization Policy Verification +#### Authorization policy verification -1. Checks if the function being called is a transfer or approve function. -2. Enforces the time-based restriction by comparing the current time with the last transfer time. -3. Updates the last transfer time if the transfer is allowed. +1. Checks if the function being called is a transfer or approve function +2. Enforces the time-based restriction by comparing the current time with the last transfer time +3. Updates the last transfer time if the transfer is allowed ```rust fn verify_authorization_policy( @@ -247,11 +247,11 @@ fn verify_authorization_policy( } ``` -### Summary +#### Summary The contract begins by initializing with a set of authorized signers. It allows setting a time limit for token transfers, which controls how frequently a token can be transferred. The \_\_check_auth function is the core of the authorization process, ensuring that all necessary signatures are valid and checking the time-based restriction for token transfers. If the required time has not passed since the last transfer, the contract will deny the operation, enforcing the desired rate limiting. By tracking the last transfer time and enforcing a minimum time interval between transfers, the contract effectively limits the frequency of token transfers, resolving the issue of potential abuse through rapid consecutive transactions. -### Complete Code +#### Complete code Here are all the snippets stacked together in a single file for convenience: @@ -430,7 +430,7 @@ fn verify_authorization_policy( mod test; ``` -These are the test cases +These are the test cases: ```rust #![cfg(test)] @@ -593,13 +593,13 @@ fn test_token_auth() { } ``` -# Tutorial 2: implementing a smart wallet (webauthn) +## Tutorial 2: implementing a smart wallet (WebAuthn) -Imagine a world where traditional passwords are obsolete. In this world, WebAuthn (Web Authentication) has become the standard for secure online interactions. Alice, a blockchain enthusiast, wants to create a wallet that leverages WebAuthn technology for enhanced security. She decides to implement a WebAuthn wallet on the Soroban platform, allowing users to manage their digital assets using their device's biometric features or security keys (eg. YubiKey, Google Titan Security Key, etc). +Imagine a world where traditional passwords are obsolete. In this world, WebAuthn (Web Authentication) has become the standard for secure online interactions. Alice, a blockchain enthusiast, wants to create a wallet that leverages WebAuthn technology for enhanced security. She decides to implement a WebAuthn wallet on Stellar, allowing users to manage their digital assets using their device's biometric features or security keys (e.g., YubiKey, Google Titan Security Key, etc.). -## Base Concept: +### Base concepts -WebAuthn is a web standard for passwordless authentication. It allows users to authenticate using biometrics (like fingerprints or facial recognition) +WebAuthn is a web standard for passwordless authentication. It allows users to authenticate using biometrics (like fingerprints or facial recognition). The WebAuthn wallet implemented in this tutorial will be able to: @@ -610,13 +610,13 @@ The WebAuthn wallet implemented in this tutorial will be able to: :::info -This tutorial's code credit goes to [@kalepail](https://github.com/kalepail) work on passkeys, which you can explore more [here](https://github.com/kalepail/passkey-kit) +This tutorial's code credit goes to [@kalepail's](https://github.com/kalepail) work on passkeys, which you can explore more [here](https://github.com/kalepail/passkey-kit). ::: -## Code Walkthrough: +### Code walkthrough -### Contract Structure and Imports +#### Contract structure and imports This section sets up the contract structure and imports necessary components from the Soroban SDK. @@ -634,7 +634,7 @@ use soroban_sdk::{ pub struct Contract; ``` -### Error Definitions: +#### Error definitions This enum defines possible errors that can occur during contract execution. @@ -652,9 +652,9 @@ pub enum Error { } ``` -### Core Contract Functions: +#### Core contract functions -These functions handle adding/removing signers, updating the contract, and managing admin counts. +These functions handle adding and removing signers, updating the contract, and managing admin counts. ```rust // Implementing the Contract struct with various methods @@ -802,7 +802,7 @@ impl Contract { ``` -### Signature Structure +#### Signature structure This structure represents a WebAuthn signature. @@ -816,7 +816,7 @@ pub struct Signature { } ``` -### CustomAccountInterface Implementation: +#### CustomAccountInterface implementation This implements the core authentication logic for the WebAuthn wallet. @@ -915,7 +915,7 @@ impl CustomAccountInterface for Contract { } ``` -### Base64 url encoding: +#### Base64 url encoding This function provides Base64 URL encoding functionality used in the WebAuthn process. @@ -973,11 +973,11 @@ pub fn encode(dst: &mut [u8], src: &[u8]) { ``` -### Written explanation of code: +#### Written explanation of code The WebAuthn wallet contract manages user credentials and authentication. It allows adding and removing signers, distinguishing between admin and regular users. The add function registers new signers, storing admin keys persistently and regular keys temporarily. The remove function deletes signers, and update allows contract upgrades. The core of the wallet's security is the `__check_auth` function, which verifies WebAuthn signatures. It checks the signature against the stored public key, verifies the client data JSON, and ensures the challenge matches the expected value. The contract uses Soroban's storage capabilities to manage keys and admin counts, with different TTLs (Time To Live) for persistent and temporary storage. -### Test cases: +#### Test cases These are test cases to ensure our WebAuthn wallet is functioning correctly. We'll use the Soroban SDK's testing utilities to create and run these tests. @@ -1066,11 +1066,11 @@ mod test { } ``` -### Summary +#### Summary -This WebAuthn wallet implementation provides a secure and user-friendly way to manage digital assets on the Soroban platform. It leverages the security benefits of WebAuthn while maintaining the flexibility needed for blockchain interactions. +This WebAuthn wallet implementation provides a secure and user-friendly way to manage digital assets on Stellar. It leverages the security benefits of WebAuthn while maintaining the flexibility needed for blockchain interactions. -### Complete Code +#### Complete code Here are all the snippets stacked together in a single file for convenience: