motr/README.md

Sonr Motr

Motr is Sonr's decentralized vault and identity management system. It provides secure credential and profile management with online/offline capabilities through a progressive web application architecture.

Features

• Secure Identity Management: WebAuthn credential storage and verification
• Progressive Web App: Works online and offline with service worker integration
• WASM Architecture: Core functionality compiled to WebAssembly for cross-platform compatibility
• Local-First Design: Data stored locally with sync capabilities to the Sonr blockchain
• Containerized Deployment: Docker-based deployment for all components

Installation

Standard Installation

git clone https://github.com/sonr-io/motr.git
cd motr
go mod tidy

Docker Installation

git clone https://github.com/sonr-io/motr.git
cd motr
docker-compose up -d

Usage

Development Setup

Motr uses Task for managing development workflows. Here are the primary commands:

# Clean build artifacts
task clean

# Build all components
task build

# Deploy all components to Cloudflare
task deploy

# Start the local development server
task serve

Component-specific commands

# Start the Vault component (Cloudflare Worker)
task start:vault

# Start the Frontend component
task start:front

# Build specific components
task build:vault
task build:front

# Deploy specific components to Cloudflare
task deploy:vault
task deploy:front

Database operations

# Generate SQL models using sqlc
task gen:sqlc

# Migrate the database
task db:migrate

Compile to WebAssembly

The project uses WebAssembly for cross-platform compatibility. Components are compiled automatically when using the Task commands above, but you can also build manually:

# Build the signer as WASM
GOOS=js GOARCH=wasm go build -o build/signer.wasm ./cmd/signer/main.go

# Build the controller application as WASM
GOOS=js GOARCH=wasm go build -o build/controller.wasm ./controller/main.go

# Build the resolver application for Cloudflare Workers
GOOS=js GOARCH=wasm go build -o build/resolver.wasm ./resolver/main.go

Progressive Web App Integration

Motr can be integrated into progressive web applications, providing:

• Offline functionality via service workers
• Secure credential storage
• Seamless blockchain account management
• Cross-device synchronization

Commands

• Build: task build - Compiles WASM with GOOS=js GOARCH=wasm go build -o web/vault.wasm .
• Generate: task gen:templ - Generate Go code from templ templates
• Generate: task gen:sqlc - Generate Go code from SQL queries
• Test: task test - Run all tests with go test -v ./...
• Run single test: go test -v ./path/to/package -run TestName
• Serve: task serve - Run development server with bunx live-server in web directory

Code Style

• Imports: Standard library first, external packages second, local packages last
• Formatting: Use gofmt
• Types: Prefer explicit types over interface{}
• Naming: Follow Go conventions (CamelCase for exported, camelCase for unexported)
• Error Handling: Always check errors and return them when appropriate
• Domain Structure: Keep domain logic in /x directory with handler.go, model/ and view/ subdirectories
• Templates: Use templ for HTML templating
• Database: Use sqlc for type-safe SQL queries
• Middleware: Place middleware in pkg/[service]/middleware.go

Architecture

MOTR follows a modular architecture with domain-driven design principles. WebAssembly is used for browser execution with progressive web app capabilities.

Architecture

Motr consists of several components:

• Vault: Core component deployed as a Cloudflare Worker with WebAssembly
• Controller: Manages WebAuthn credential creation and verification
• Resolver: Handles name resolution and identity lookups
• Signer: WebAssembly-based cryptographic operations for secure signing
• Service Worker: Handles offline capabilities and request caching
• IndexedDB Storage: Local data persistence
• Sonr Blockchain Integration: Identity verification and data synchronization

Component Details

1. Vault

   • Core component deployed as a Cloudflare Worker
   • Manages decentralized identity and authentication
   • Integrates with IPFS/Helia for decentralized storage
   • Uses WebAssembly plugins for cryptographic operations
   • Package located at cmd/vault/

2. Controller

   • Manages user credentials and authentication
   • Integrates with WebAuthn for credential storage
   • Uses SQLite via D1 database for persistent storage

3. Resolver

   • Resolves Sonr names to addresses and profiles
   • Serves as a gateway to the Sonr network
   • Implemented as a Cloudflare Worker

4. Signer

   • Secure cryptographic operations
   • WebAssembly-based for cross-platform compatibility
   • Handles key management and signatures

Development

Build System

Motr uses the following build tools:

• Task: Task runner for development workflows
• GoReleaser: Handles building and releasing Go applications
• SQLC: Generates type-safe Go code from SQL
• Templ: Template engine for Go HTML templates
• Air: Live reload for Go applications during development
• Bun: JavaScript runtime and package manager

Release Process

# Create a new release
task release

The release process uses GoReleaser with configuration in .goreleaser.yaml.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

To contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes using conventional commits (git commit -m 'feat: add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT

Copyright (c) 2024, Sonr Labs, Inc.