Master (#1262)

* clear * feat: Add everything * fix: Commenht
2026-08-04 18:31:41 +00:00 · 2025-10-03 14:45:52 -04:00
parent 43b4a11c06
commit 13e6c3e84d
1935 changed files with 655061 additions and 40058 deletions
@@ -0,0 +1,173 @@
+---
+title: Requesting Permissions
+description: A guide to setting up and managing wallet connections with the Sonr decentralized identity system
+icon: "shield-check"
+---
+
+Sonr provides a seamless and secure way for users to connect their wallets to decentralized applications. This guide covers the different methods for establishing and managing wallet connections, from simple browser-based interactions to backend service integrations.
+
+## The Sonr Connection Model
+
+Unlike traditional Web3 wallets that require browser extensions, Sonr uses a combination of WebAuthn and Decentralized Identifiers (DIDs) to create a secure, passwordless connection experience.
+
+<CardGroup>
+  <Card title="User-Centric" href="/blockchain/modules/did/">
+    Users control their identity and grant permissions to applications, not the
+    other way around.
+  </Card>
+  <Card title="Passwordless" href="/blockchain/modules/did/">
+    WebAuthn enables biometric and security key authentication, eliminating the
+    need for seed phrases.
+  </Card>
+  <Card title="Multi-Device" href="/blockchain/modules/dwn/">
+    Users can securely access their Vault from any device with a modern web
+    browser.
+  </Card>
+</CardGroup>
+
+## Connecting in the Browser
+
+For web applications, the Sonr SDK provides a simple way to initiate a wallet connection.
+
+<Steps>
+<Step>
+### 1. Initialize the SDK
+
+First, initialize the Sonr SDK in your application. For this example, we'll use the CDN version.
+
+```html
+<script type="module">
+  import { Sonr } from "https://cdn.jsdelivr.net/npm/@sonr/sdk";
+  const sonr = new Sonr({ httpUrl: "http://localhost:1317" });
+</script>
+```
+
+</Step>
+
+<Step>
+### 2. Request Authentication
+
+Use the `sonr.authenticate()` method to prompt the user to connect their wallet. This will trigger the browser's WebAuthn flow.
+
+```javascript
+async function connectWallet() {
+  try {
+    const session = await sonr.authenticate();
+    console.log("Wallet connected!", session);
+    // You now have a secure session with the user's Vault
+  } catch (error) {
+    console.error("Failed to connect wallet:", error);
+  }
+}
+```
+
+</Step>
+
+<Step>
+### 3. Handle the Session
+
+The `session` object returned from `authenticate()` contains the user's DID and a UCAN token with the requested permissions. You can use this session to interact with the user's Vault.
+
+```javascript
+// Example: Get the user's balance
+const balance = await session.vault.getAccountBalance();
+console.log("User balance:", balance);
+```
+
+</Step>
+</Steps>
+
+## Backend Wallet Connections
+
+For backend services, you can use the Sonr SDK to interact with user Vaults on behalf of your application.
+
+<Steps>
+<Step>
+### 1. Service Registration
+
+Your backend service must be registered on the Sonr network. This provides your service with its own DID and allows it to request permissions from users.
+
+{/* Service registration documentation is referenced but not yet available in the docs structure */}
+
+</Step>
+
+<Step>
+### 2. Requesting Permissions
+
+Your service can request permissions from users by generating a UCAN request. This is typically done through a user-facing application.
+
+```typescript
+// Example: Requesting permission to read a user's profile
+const ucanRequest = await sonr.ucan.request({
+  audience: "did:sonr:your-service-did",
+  resource: `dwn://user-did/profile/read`,
+});
+
+// Present this request to the user to be signed by their Vault
+```
+
+</Step>
+
+<Step>
+### 3. Using Delegated Capabilities
+
+Once a user has approved your request, you will receive a delegated UCAN token. You can use this token to perform actions on the user's behalf.
+
+```go
+// Example: Using a delegated UCAN in a Go backend
+import "github.com/sonr-io/sonr/x/sonr/pkgs/sdk"
+
+func GetUserProfile(userDID string, delegatedUcan string) (*Profile, error) {
+    sonr, _ := sdk.NewSonr(rpcEndpoint, "")
+
+    // Use the delegated UCAN to access the user's profile
+    profile, err := sonr.GetUserProfile(userDID, delegatedUcan)
+    if err != nil {
+        return nil, err
+    }
+
+    return profile, nil
+}
+```
+
+</Step>
+</Steps>
+
+## Managing Connections
+
+### Checking Connection Status
+
+You can check the current connection status at any time:
+
+```javascript
+const session = await sonr.getSession();
+
+if (session) {
+  console.log("User is connected:", session.did);
+} else {
+  console.log("User is not connected.");
+}
+```
+
+### Disconnecting
+
+To disconnect a wallet, simply clear the session from your application's state:
+
+```javascript
+await sonr.logout();
+console.log("User has been disconnected.");
+```
+
+This will revoke the current session's UCAN token, but it will not remove any permissions the user has granted to your service.
+
+## Security Considerations
+
+- **UCAN Scopes**: Always request the minimum permissions necessary for your application to function.
+- **Token Storage**: Securely store delegated UCAN tokens on your backend. Never expose them on the client-side.
+- **Revocation**: Your application should handle UCAN revocations gracefully.
+
+## Next Steps
+
+- [Sending Payments](/highway/wallets/sending-payments)
+- [Understanding UCANs](/blockchain/modules/svc/ucan)
+- [Explore DWN Architecture](/blockchain/modules/dwn/)