diff --git a/docs/guides/decentralized-authentication.mdx b/docs/guides/decentralized-authentication.mdx deleted file mode 100644 index f58ab5aea..000000000 --- a/docs/guides/decentralized-authentication.mdx +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: "Migrating from Centralized to Decentralized Authentication" -description: "A comprehensive guide to migrating from centralized 8787 endpoints to decentralized OIDC authentication with WebAuthn" -sidebarTitle: "Decentralized Authentication" -icon: "key" ---- - -# Migrating from Centralized to Decentralized Authentication - -## Overview - -Sonr is transitioning from a centralized authentication model using 8787 endpoints to a fully decentralized, privacy-preserving authentication system leveraging OpenID Connect (OIDC), Self-Issued OpenID Provider (SIOP), and WebAuthn technologies. - -### Key Improvements - -- **Decentralization**: Move from centralized identity management to self-sovereign identity -- **WebAuthn Integration**: Hardware-backed, phishing-resistance authentication -- **Gasless Onboarding**: Zero-cost user registration and transactions -- **Automatic Vault Creation**: Seamless user experience with instant identity setup -- **Enhanced Privacy**: DID-based authentication with verifiable presentations - -## Architecture Comparison - -### Old Architecture: Centralized 8787 Endpoints - -- Centralized authentication server -- Fixed credential storage -- Limited authentication methods -- Higher security risks - -### New Architecture: Decentralized OIDC Provider - -```mermaid -graph TD - A[User Device] --> B{WebAuthn Registration} - B --> |Credential Generation| C[Blockchain Bridge] - C --> |Broadcast Credential| D[Sonr Blockchain] - D --> |Create DID| E[User's Decentralized Identity] - E --> |SIOP Flow| F[OIDC Provider] - F --> |Verifiable Presentation| G[Service Provider] -``` - -## Migration Steps - -### 1. Prerequisites - -- Go 1.24.1+ -- Cosmos SDK v0.50.14 -- WebAuthn-compatible browser/device -- Updated Sonr SDK - -### 2. Configuration Changes - -#### Environment Variables - - -```bash title="Old Configuration" -# Centralized auth endpoints -AUTH_ENDPOINT=https://8787.sonr.io/auth -AUTH_CLIENT_ID=legacy-client-id -``` - -```bash title="New Configuration" -# Decentralized OIDC configuration -OIDC_PROVIDER_URL=https://oidc.sonr.network -WEBAUTHN_ORIGIN=https://your-app.com -DID_RESOLVER_URL=https://did.sonr.network -``` - - - -### 3. Endpoint Migration - -| Old Endpoint | New Endpoint | Changes | -| ---------------- | -------------------- | ----------------------- | -| `/auth/login` | `/oidc/authorize` | OIDC authorization flow | -| `/auth/register` | `/webauthn/register` | WebAuthn registration | -| `/auth/token` | `/oidc/token` | Token issuance via SIOP | - -### 4. API Changes - -#### Request Format - - -```json title="Legacy Request" -{ - "username": "user@example.com", - "password": "legacy-password" -} -``` - -```json title="New WebAuthn Request" -{ - "challenge": "base64-encoded-challenge", - "attestation": { - "type": "public-key", - "id": "credential-id", - "rawId": "base64-encoded-raw-credential", - "response": { - "clientDataJSON": "...", - "attestationObject": "..." - } - } -} -``` - - - -### 5. WebAuthn Integration - -#### Registration Flow - -1. Generate registration challenge -2. Create WebAuthn credential -3. Broadcast credential to blockchain -4. Automatically create user vault -5. Issue decentralized identifier (DID) - -#### Code Example - -```go title="WebAuthn Registration Handler" -func (s *Server) HandleWebAuthnRegistration(w http.ResponseWriter, r *http.Request) { - // 1. Validate WebAuthn attestation - credential, err := s.webAuthnService.VerifyRegistration(attestationData) - - // 2. Broadcast to blockchain - didDoc, err := s.blockchainBridge.CreateDID(credential) - - // 3. Create user vault - vault, err := s.vaultService.CreateVault(didDoc) - - // 4. Issue OIDC token - token := s.oidcService.IssueToken(didDoc) -} -``` - -### 6. SIOP (Self-Issued OpenID Provider) - -#### Key Concepts - -- Verifiable Presentations -- Decentralized Identifiers (DIDs) -- User-controlled authentication - -### 7. Error Handling - -#### Migration Errors - -| Error Code | Description | Mitigation | -| ------------------------ | ---------------------- | -------------------- | -| `AUTH_LEGACY_DEPRECATED` | Legacy auth method | Upgrade client | -| `WEBAUTHN_UNSUPPORTED` | Device incompatibility | Use alternative auth | -| `DID_RESOLUTION_FAILED` | Identity verification | Retry registration | - -### 8. Testing Migration - -```bash -# Validate WebAuthn registration -sonr webauthn test-registration - -# Verify OIDC provider -sonr oidc validate-provider - -# Check DID resolution -sonr did resolve did:sonr:example -``` - -### 9. Breaking Changes - -- Legacy password authentication removed -- Token format changed to JWT with DID claims -- New client libraries required -- WebAuthn mandatory for registration - -## Rollback Procedure - -If issues arise: - -1. Maintain legacy user mappings -2. Provide fallback authentication -3. Gradual, opt-in migration - -## Conclusion - -This migration represents a significant leap in authentication security and user privacy. By adopting WebAuthn, SIOP, and blockchain-backed identities, we're creating a more robust, user-controlled authentication ecosystem. - -## Support - -- [Sonr Developer Docs](/docs) -- [WebAuthn Specification](https://www.w3.org/TR/webauthn-2/) -- [OIDC Community](https://openid.net/developers/specs/) diff --git a/docs/guides/decentralized-identity.mdx b/docs/guides/decentralized-identity.mdx deleted file mode 100644 index 56afd2a0b..000000000 --- a/docs/guides/decentralized-identity.mdx +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: "DID Generation and Management" -description: "Learn how to generate and manage Decentralized Identifiers (DIDs) using advanced crypto interfaces" -sidebarTitle: "Identity Generation" -icon: "signature" ---- - -# DID Generation Patterns - -The Sonr project provides a robust and flexible DID (Decentralized Identifier) generation system supporting multiple key types and cryptographic methods. - -## Supported Key Types - -The `didkey.go` interface supports the following key types: - -- RSA Public Keys -- Ed25519 Public Keys -- Secp256k1 Public Keys - -## Basic DID Generation - -### Creating a DID from a Public Key - -```go -import ( - "github.com/libp2p/go-libp2p/core/crypto" - "github.com/sonr-io/crypto/keys" -) - -// Generate a new key pair -privateKey, publicKey, err := crypto.GenerateKeyPair(crypto.Ed25519, -1) - -// Create a DID -did, err := keys.NewDID(publicKey) -``` - -### Parsing an Existing DID - -```go -// Parse a DID string -did, err := keys.Parse("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGTsyDFWYviJr4") -``` - -## Advanced DID Operations - -### Address Derivation - -```go -// Get a blockchain-compatible address from a DID -address, err := did.Address() -``` - -### Compressed Public Key Retrieval - -```go -// Get a compressed public key (for Secp256k1) -compressedPubKey, err := did.CompressedPubKey() -``` - -## MPC Enclave DID Generation - -For MPC (Multi-Party Computation) enclaves, use a specialized method: - -```go -// Create a DID from MPC enclave public key bytes -did, err := keys.NewFromMPCPubKey(enclavePublicKeyBytes) -``` - -## DID Validation - -```go -// Validate a DID format -err := keys.ValidateFormat("did:key:example123") -``` - -## Multicodec Support - -The library supports various multicodec prefixes for different key types: - -- RSA: `0x1205` -- Ed25519: `0xed` -- Secp256k1: `0xe7` - -## Security Considerations - -- Always generate keys using cryptographically secure methods -- Validate DIDs before using them in critical operations -- Use the appropriate key type for your security requirements - -## Example: Complete DID Workflow - -```go -package main - -import ( - "fmt" - "github.com/libp2p/go-libp2p/core/crypto" - "github.com/sonr-io/crypto/keys" -) - -func main() { - // Generate a new key pair - privateKey, publicKey, err := crypto.GenerateKeyPair(crypto.Ed25519, -1) - if err != nil { - panic(err) - } - - // Create a DID - did, err := keys.NewDID(publicKey) - if err != nil { - panic(err) - } - - // Get the DID string - didString := did.String() - fmt.Println("Generated DID:", didString) - - // Derive blockchain address - address, err := did.Address() - if err != nil { - panic(err) - } - fmt.Println("Blockchain Address:", address) -} -``` - -## Compatibility and Interoperability - -The Sonr DID implementation follows the W3C DID specification, ensuring broad compatibility with other decentralized identity systems. diff --git a/docs/guides/migrate-to-decentralized-authentication.mdx b/docs/guides/migrate-to-decentralized-authentication.mdx deleted file mode 100644 index f58ab5aea..000000000 --- a/docs/guides/migrate-to-decentralized-authentication.mdx +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: "Migrating from Centralized to Decentralized Authentication" -description: "A comprehensive guide to migrating from centralized 8787 endpoints to decentralized OIDC authentication with WebAuthn" -sidebarTitle: "Decentralized Authentication" -icon: "key" ---- - -# Migrating from Centralized to Decentralized Authentication - -## Overview - -Sonr is transitioning from a centralized authentication model using 8787 endpoints to a fully decentralized, privacy-preserving authentication system leveraging OpenID Connect (OIDC), Self-Issued OpenID Provider (SIOP), and WebAuthn technologies. - -### Key Improvements - -- **Decentralization**: Move from centralized identity management to self-sovereign identity -- **WebAuthn Integration**: Hardware-backed, phishing-resistance authentication -- **Gasless Onboarding**: Zero-cost user registration and transactions -- **Automatic Vault Creation**: Seamless user experience with instant identity setup -- **Enhanced Privacy**: DID-based authentication with verifiable presentations - -## Architecture Comparison - -### Old Architecture: Centralized 8787 Endpoints - -- Centralized authentication server -- Fixed credential storage -- Limited authentication methods -- Higher security risks - -### New Architecture: Decentralized OIDC Provider - -```mermaid -graph TD - A[User Device] --> B{WebAuthn Registration} - B --> |Credential Generation| C[Blockchain Bridge] - C --> |Broadcast Credential| D[Sonr Blockchain] - D --> |Create DID| E[User's Decentralized Identity] - E --> |SIOP Flow| F[OIDC Provider] - F --> |Verifiable Presentation| G[Service Provider] -``` - -## Migration Steps - -### 1. Prerequisites - -- Go 1.24.1+ -- Cosmos SDK v0.50.14 -- WebAuthn-compatible browser/device -- Updated Sonr SDK - -### 2. Configuration Changes - -#### Environment Variables - - -```bash title="Old Configuration" -# Centralized auth endpoints -AUTH_ENDPOINT=https://8787.sonr.io/auth -AUTH_CLIENT_ID=legacy-client-id -``` - -```bash title="New Configuration" -# Decentralized OIDC configuration -OIDC_PROVIDER_URL=https://oidc.sonr.network -WEBAUTHN_ORIGIN=https://your-app.com -DID_RESOLVER_URL=https://did.sonr.network -``` - - - -### 3. Endpoint Migration - -| Old Endpoint | New Endpoint | Changes | -| ---------------- | -------------------- | ----------------------- | -| `/auth/login` | `/oidc/authorize` | OIDC authorization flow | -| `/auth/register` | `/webauthn/register` | WebAuthn registration | -| `/auth/token` | `/oidc/token` | Token issuance via SIOP | - -### 4. API Changes - -#### Request Format - - -```json title="Legacy Request" -{ - "username": "user@example.com", - "password": "legacy-password" -} -``` - -```json title="New WebAuthn Request" -{ - "challenge": "base64-encoded-challenge", - "attestation": { - "type": "public-key", - "id": "credential-id", - "rawId": "base64-encoded-raw-credential", - "response": { - "clientDataJSON": "...", - "attestationObject": "..." - } - } -} -``` - - - -### 5. WebAuthn Integration - -#### Registration Flow - -1. Generate registration challenge -2. Create WebAuthn credential -3. Broadcast credential to blockchain -4. Automatically create user vault -5. Issue decentralized identifier (DID) - -#### Code Example - -```go title="WebAuthn Registration Handler" -func (s *Server) HandleWebAuthnRegistration(w http.ResponseWriter, r *http.Request) { - // 1. Validate WebAuthn attestation - credential, err := s.webAuthnService.VerifyRegistration(attestationData) - - // 2. Broadcast to blockchain - didDoc, err := s.blockchainBridge.CreateDID(credential) - - // 3. Create user vault - vault, err := s.vaultService.CreateVault(didDoc) - - // 4. Issue OIDC token - token := s.oidcService.IssueToken(didDoc) -} -``` - -### 6. SIOP (Self-Issued OpenID Provider) - -#### Key Concepts - -- Verifiable Presentations -- Decentralized Identifiers (DIDs) -- User-controlled authentication - -### 7. Error Handling - -#### Migration Errors - -| Error Code | Description | Mitigation | -| ------------------------ | ---------------------- | -------------------- | -| `AUTH_LEGACY_DEPRECATED` | Legacy auth method | Upgrade client | -| `WEBAUTHN_UNSUPPORTED` | Device incompatibility | Use alternative auth | -| `DID_RESOLUTION_FAILED` | Identity verification | Retry registration | - -### 8. Testing Migration - -```bash -# Validate WebAuthn registration -sonr webauthn test-registration - -# Verify OIDC provider -sonr oidc validate-provider - -# Check DID resolution -sonr did resolve did:sonr:example -``` - -### 9. Breaking Changes - -- Legacy password authentication removed -- Token format changed to JWT with DID claims -- New client libraries required -- WebAuthn mandatory for registration - -## Rollback Procedure - -If issues arise: - -1. Maintain legacy user mappings -2. Provide fallback authentication -3. Gradual, opt-in migration - -## Conclusion - -This migration represents a significant leap in authentication security and user privacy. By adopting WebAuthn, SIOP, and blockchain-backed identities, we're creating a more robust, user-controlled authentication ecosystem. - -## Support - -- [Sonr Developer Docs](/docs) -- [WebAuthn Specification](https://www.w3.org/TR/webauthn-2/) -- [OIDC Community](https://openid.net/developers/specs/)