@goplausible/algorand-mcp 3.0.7

package/dist/resources/knowledge/taxonomy/liquid-auth:docs:architecture.md

@@ -0,0 +1,101 @@
+---
+title: Architecture
+sidebar:
+  order: 6
+prev: false
+next: false
+---
+
+This is a high level overview of the sequence of events that happens while using Liquid Auth.
+See the [Getting Started](./guides/getting-started) section for more detailed information on each step.
+Diagrams are generated using [Mermaid](https://mermaid-js.github.io/mermaid/#/).
+
+## Authentication
+
+A user can link their device to a website by scanning a QR code. 
+The website will subscribe to a WebSocket channel to receive the link status. 
+The wallet will scan the QR code and send a [FIDO2 PublicKeyCredential]() to the server. 
+The server will validate the FIDO2 credential and send a response to the wallet and website.
+
+```mermaid
+sequenceDiagram
+    participant Website as Answer Client
+    participant Server
+    participant Wallet as Offer Client
+    Website->>Server: Subscribe to 'wss:link'
+    Website-->>Website: Display QR Connect Request ID
+    Wallet->>Website: Scan QR Code
+    Server-->>Wallet: Get Challenge/Options
+    Wallet->>Server: POST FIDO2 Credential + Liquid Auth Extension
+    Server-->>Server: Validate Signatures
+    Server-->>Website: HTTPOnly Session
+    Server->>Wallet: Ok Response + HTTPOnly Session
+    Server->>Website: Emit to `wss:link` client
+```
+
+## Signaling
+
+The website and wallet can subscribe to an isolated WebSocket channel to broker [Session Description]() answers and offers.
+[ICE Candidates]() are discovered when any peer has both an offer and answer.
+
+```mermaid
+sequenceDiagram
+    participant Website as Answer Client
+    participant Server
+    participant Wallet as Offer Client
+    Website-->>Server: Subscribe to 'wss:offer-description'
+    Website-->>Server: Subscribe to 'wss:offer-candidate'
+    Wallet-->>Server: Subscribe to 'wss:answer-description'
+    Wallet-->>Server: Subscribe to 'wss:answer-candidate'
+```
+
+### Offer
+
+[Offers]() are created by a peer and sent through the signaling service. 
+A client with an offer will listen for an answer description. 
+Answers are only emitted in response to an offer.
+Offer clients are responsible for creating the [Data Channel]().
+
+```mermaid
+sequenceDiagram
+    participant Website as Answer Client
+    participant Server
+    participant Wallet as Offer Client
+    Wallet-->>Wallet: On answer-description, set Remote SDP
+    Wallet-->>Wallet: On answer-candidate, add ICE Candidate
+    Wallet-->>Wallet: Create Peer Offer & DataChannel
+    Wallet-->>Server: Emit `wss:offer-description`
+    Wallet-->>Server: Emit `wss:offer-candidate`
+```
+
+### Answer
+
+An [Answer]() is created by a peer in response to an offer.
+The answer description and candidates are emitted to the signaling service.
+
+```mermaid
+sequenceDiagram
+    participant Website as Answer Client
+    participant Server
+    participant Wallet as Offer Client
+    Website-->>Website: On offer-description, set Remote SDP and create Answer
+    Website-->>Website: On offer-candidate, add ICE Candidate
+    Website-->>Server: Emit `wss:answer-description`
+    Website-->>Server: Emit `wss:answer-candidate`
+```
+
+### Data Channel
+
+Once an Offer and Answer have been exchanged, a [Data Channel]() will be emitted to the peer who created the answer.
+This channel is used to send messages between the website and wallet in real-time over the established P2P connection.
+```mermaid
+sequenceDiagram
+    participant Website as Answer Client
+    participant Server
+    participant Wallet as Offer Client
+    Wallet-->>Website: Emit DataChannel
+    Wallet-->>Wallet: On Message, Handle Message
+    Website-->>Website: On DataChannel, listen for Messages
+    Website-->>Wallet: Emit Messages
+    Wallet-->>Website: Emit Messages
+```

package/dist/resources/knowledge/taxonomy/liquid-auth:docs:clients:android:provider-service:authenticate.md

@@ -0,0 +1,13 @@
+---
+title: "Android 14: Authenticate"
+---
+
+```kotlin
+// MainActivity.kt
+val request = PendingIntentHandler.retrieveProviderCreateCredentialRequest(intent)
+if (request.callingRequest is CreatePublicKeyCredentialRequest) {
+    val result = viewModel.processCreatePasskey(this@CreatePasskeyActivity, request)
+} else {
+   val text = resources.getString(R.string.get_passkey_error)
+}
+```

package/dist/resources/knowledge/taxonomy/liquid-auth:docs:clients:android:provider-service:register.md

@@ -0,0 +1,18 @@
+---
+title: "Android 14: Register"
+---
+
+
+```kotlin
+val request = PendingIntentHandler.retrieveProviderGetCredentialRequest(intent)
+if (request != null) {
+    lifecycleScope.launch {
+        val result = viewModel.processGetPasskey(this@GetPasskeyActivity, request, intent.getBundleExtra("CREDENTIAL_DATA"))
+        Log.d(TAG, "result: $result")
+        setResult(Activity.RESULT_OK, result)
+        finish()
+    }
+} else {
+    val text = resources.getString(R.string.get_passkey_error)
+}
+```

package/dist/resources/knowledge/taxonomy/liquid-auth:docs:clients:browser:authentication.md

@@ -0,0 +1,107 @@
+---
+title: 'Browser: Authentication'
+sidebar:
+  badge:
+    text: "TODO"
+    variant: danger
+---
+
+Authenticate an existing [Passkey](/guides/concepts/#passkeys) with the [Service](/guides/server/introduction).
+
+### Who is this for?
+
+- **dApps** logging back into the service without connecting to another client
+- **Browser Wallets** that want to communicate with other clients
+
+## Client
+
+Sign in with an existing account using an instance of the `SignalClient`
+```typescript
+//app.ts
+await client.assertion(
+    credentialId, // Some known credential ID
+    {requestId: 12345} // Optional requestId to link
+)
+```
+
+## Stateless
+
+Using the stateless method without a `SignalClient`
+
+```typescript
+//app.ts
+import {assertion} from '@algorandfoundation/liquid-auth/assertion'
+await assertion(
+  "https://my-liquid-service.com",
+  credentialId, // Some known credential ID
+  {requestId: 12345} // Optional requestId to link
+)
+```
+
+## Manual
+
+If you want to manually handle the process of creating a passkey, you can use the following methods and preforming
+the three steps of the process.
+
+### 🧮 Options
+
+Manually fetching the `Options` from the service.
+
+```typescript
+import {fetchAssertionRequestOptions} from '@algorandfoundation/liquid-client/assertion'
+
+const encodedOptions = await fetchAssertionRequestOptions("https://my-liquid-service.com", "<KNOWN_CREDENTIAL_ID>")
+```
+
+### 🎉 Retrieving
+
+Decode the options and fetch the Passkey.
+
+```typescript
+import {fromBase64Url} from "@algorandfoundation/liquid-client/encoding";
+const options = { ...encodedOptions };
+// Challenge from the service
+options.challenge = fromBase64Url(options.challenge);
+// Decode any known credentials
+if (options.allowCredentials) {
+  for (const cred of options.allowCredentials) {
+    cred.id = fromBase64Url(cred.id);
+  }
+}
+const credential = navigator.credentials.get({
+  publicKey: options
+})
+```
+
+### 🔐 Liquid Extension
+
+Optionally, Authenticate a remote user with the Liquid Extension.
+
+```typescript
+credential.clientExtensionResults = {
+    // Optionally authenticate a remote peer
+    requestId: "<UUID_FROM_QR_CODE>"
+}
+```
+
+### 🚚 Response
+
+Encode and submit the passkey to the service.
+
+```typescript
+import {fetchAssertionResponse} from '@algorandfoundation/liquid-client/assertion'
+import {toBase64URL} from '@algorandfoundation/liquid-client/encoding'
+
+const result = await fetchAssertionResponse("https://my-liquid-service.com", {
+  id: credential.id,
+  type: credential.type,
+  rawId: toBase64URL(credential.rawId),
+  clientExtensionResults: credential.clientExtensionResults,
+  response: Object.keys(AuthenticatorAssertionResponse.prototype).reduce((prev, curr) => {
+    prev[curr] = toBase64URL(credential.response[curr]);
+    return prev;
+  }, {
+    clientDataJSON: toBase64URL(credential.response.clientDataJSON),
+  }),
+})
+```

package/dist/resources/knowledge/taxonomy/liquid-auth:docs:clients:browser:example.md

@@ -0,0 +1,64 @@
+---
+title: 'Browser: Example'
+next: false
+---
+
+You can check the example in the <a href="https://github.com/algorandfoundation/liquid-auth-js/tree/develop/example" target="blank">GitHub repository</a> for a working browser based application
+
+
+## Answer Client
+A dApp that wants a remote wallet to log into the service and create a peer-to-peer connection.
+```typescript
+import { SignalClient } from "@algorandfoundation/liquid-client";
+const client = new SignalClient(window.origin);
+
+const requestId = SignalClient.generateRequestId() // 12345
+
+// Wait for the Offer Client to connect
+client.peer(requestId, 'offer').then((dc)=>{
+  // Handle Peer Messages
+  dc.onmessage = (event: MessageEvent) => {
+    console.log(event.data)
+  }
+  // Send Messages to Peer
+  dc.send('Hello World')
+})
+
+// Generate a QR Code
+const qrData = await client.qrCode()
+```
+
+## Offer Client
+
+The remote browser-based wallet. This could be an extension or hybrid mobile application.
+
+```typescript
+import * as nacl from 'tweetnacl'
+import { SignalClient, toBase64URL } from "@algorandfoundation/liquid-client";
+
+const requestId = 12345 // A known request ID from a Answer Client
+const origin = "https://example.com" // Some known origin
+const address = "encoded-address" // Some known address
+const secretKey = new Uint8Array(32) // Some secret key
+
+// Sign in to the service with a new credential
+await client.attestation(async (challenge: Uint8Array) => ({
+  type: 'algorand',
+  requestId,
+  origin,
+  address,
+  signature: toBase64URL(nacl.sign.detached(challenge, secretKey)),
+  device: 'Demo Web Wallet'
+}))
+
+// Wait for the Answer Client to connect
+client.peer(requestId, 'answer').then((dc)=>{
+  // Handle Peer Messages
+  dc.onmessage = (event: MessageEvent) => {
+    console.log(event.data)
+  }
+  // Send Messages to Peer
+  dc.send('Hello World')
+})
+```
+

package/dist/resources/knowledge/taxonomy/liquid-auth:docs:introduction.md

@@ -0,0 +1,18 @@
+---
+title: Introduction
+description: Welcome to the Liquid Auth documentation.
+pagefind: false
+---
+
+Liquid Auth aims to give the user full control over their data and privacy.
+There are far too many services that act as a middle man between the end user and the wallet provider.
+
+By combining the security of FIDO2/WebAuthn with the decentralized nature of WebRTC, Liquid Auth provides a secure and private way for users to communicate.
+
+
+## What is Liquid Auth?
+
+Liquid Auth is a self-hosted authentication service that provides a simple way to associate Passkeys to KeyPair(s) commonly found in cryptocurrencies.
+
+In addition to authentication, Liquid Auth provides a Peer to Peer signaling service.
+Not only can you authenticate users, but you can also establish secure connections between them.

package/dist/resources/knowledge/taxonomy/liquid-auth:docs:server:environment-variables.md

@@ -0,0 +1,75 @@
+---
+title: "Server: Configuration"
+sidebar:
+  order: 2
+  label: 'Configuration'
+---
+
+All configurations are set using environment variables.
+Creating a `.env.docker` file is recommended to store all the environment variables required to run the server.
+
+The following sections describe the environment variables required to run the server.
+
+## Environment Variables
+
+Attestations and Assertions require a valid `RP_NAME`, `HOSTNAME`, and `ORIGIN` to be set.
+`ORIGIN` and `HOSTNAME` must be set to a valid domain secured with HTTPS.
+
+```sh
+RP_NAME=<SERVICE_NAME> # Friendly name of the service
+HOSTNAME=<DOMAIN_NAME> # Hostname of the service
+ORIGIN=https://<DOMAIN_NAME> # Origin of the service
+```
+
+If you are using a custom Android client, make sure to update the `SHA256` fingerprint.
+
+```bash
+ANDROID_SHA256HASH=<00:00:...> # SHA256 fingerprint of the Android client
+ANDROID_PACKAGENAME=<com.example.my-wallet> # Package name of the Android client
+```
+
+Configuration for MongoDB
+
+```bash
+DB_HOST=<MONGO_DB_HOST:PORT> # Hostname of the MongoDB instance
+DB_USERNAME=<MONGO_DB_USERNAME> # Username for the MongoDB instance
+DB_PASSWORD=<MONGO_DB_PASSWORD> # Password for the MongoDB instance
+DB_NAME=<MONGO_DB_NAME> # Database name
+DB_ATLAS=false # Set to true if using MongoDB Atlas
+```
+
+Configuration for Redis
+
+```bash
+REDIS_HOST=<REDIS_HOST> # Hostname of the Redis instance
+REDIS_PORT=<REDIS_PORT> # Port for the Redis instance
+REDIS_USERNAME=<REDIS_USERNAME> # Username for the Redis instance
+REDIS_PASSWORD= # Password for the Redis instance
+```
+
+## Full Example 
+
+```bash
+# .env.docker
+
+# Database
+DB_HOST=mongo:27017
+DB_USERNAME=algorand
+DB_PASSWORD=algorand
+DB_NAME=fido
+DB_ATLAS=false
+
+# Events
+REDIS_HOST=redis
+REDIS_PORT=6379
+REDIS_USERNAME=default
+REDIS_PASSWORD=
+
+# FIDO2
+RP_NAME="Auth Server"
+HOSTNAME=my-static-domain.ngrok-free.app
+ORIGIN=https://my-static-domain.ngrok-free.app
+
+ANDROID_SHA256HASH=47:CC:4E:EE:B9:50:59:A5:8B:E0:19:45:CA:0A:6D:59:16:F9:A9:C2:96:75:F8:F3:64:86:92:46:2B:7D:5D:5C
+ANDROID_PACKAGENAME=foundation.algorand.demo
+```

package/dist/resources/knowledge/taxonomy/liquid-auth:docs:server:integrations.md

@@ -0,0 +1,168 @@
+---
+title: "Server: Integrations"
+sidebar:
+  order: 3
+  label: 'Integrations'
+next: false
+---
+
+### NGINX
+
+The official Docker image supports ENV variable substitution in the template folder.
+Add your distribution to the container under `/usr/share/nginx/html`
+Make sure to configure a `LIQUID_API_HOST` ENV variable that points to your deployed Liquid Auth API.
+
+```nginx
+///etc/nginx/template/default.conf.template
+
+server {
+    listen            80;
+    listen       [::]:80;
+    server_name  localhost;
+    
+    root   /usr/share/nginx/html;
+
+    location / {
+        index  index.html index.htm;
+        expires -1;
+        try_files $uri $uri/ @fallback;
+    }
+
+    location @fallback  {
+        proxy_set_header Host ${LIQUID_API_HOST};
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_ssl_server_name on;
+        proxy_pass https://${LIQUID_API_HOST};
+    }
+}
+
+```
+
+### Vite
+> We recommend running a proxy server like Nginx in production. This will work for local development
+
+```typescript
+//vite.config.ts
+
+const DEFAULT_PROXY_URL = 'http://localhost:3000';
+const DEFAULT_WSS_PROXY_URL = 'ws://localhost:3000';
+export default defineConfig({
+  server: {
+    proxy: {
+      '^/auth/.*': process.env.PROXY_URL || DEFAULT_PROXY_URL,
+      '^/.well-known/.*': process.env.PROXY_URL || DEFAULT_PROXY_URL,
+      '^/attestation/.*': process.env.PROXY_URL || DEFAULT_PROXY_URL,
+      '^/assertion/.*': process.env.PROXY_URL || DEFAULT_PROXY_URL,
+      '/socket.io': {
+        target: process.env.WSS_PROXY_SERVER || DEFAULT_WSS_PROXY_URL,
+        ws: true,
+      },
+    }
+  },
+})
+```
+
+### Next.js
+> We recommend running a proxy server like Nginx in production. This will work in a pinch or to test locally.
+
+Deploy the service to a platform like Render or AWS then configure the Proxy in `next.config.js`.
+
+```typescript
+//next.config.js
+/** @type {import('next').NextConfig} */
+
+const serverURL = "https://my-liquid-service.com";
+
+const nextConfig = {
+  trailingSlash: true,
+  async rewrites() {
+    return [
+      {
+        source: '/auth/:path*',
+        destination: `${serverURL}/auth/:path*`,
+      },
+      {
+        source: '/.well-known/:path*',
+        destination: `${serverURL}/.well-known/:path*`,
+      },
+      {
+        source: '/attestation/:path*',
+        destination: `${serverURL}/attestation/:path*`,
+      },
+
+      {
+        source: '/assertion/:path*',
+        destination: `${serverURL}/assertion/:path*`,
+      },
+      {
+        source: '/socket.io/',
+        destination: `${serverURL}/socket.io/`,
+      },
+      {
+        source: '/socket.io',
+        destination: `${serverURL}/socket.io/`,
+      },
+    ]
+  },
+};
+
+export default nextConfig;
+```
+
+### Nest.js[WIP]
+> Warning, the Service package is not available publicly.
+> Please contact if you are interested in mounting the server
+
+See the [Demo Express](https://github.com/algorandfoundation/liquid-auth/blob/develop/sites/express-dapp/src/main.ts) app for an example of how to mount the server.
+
+```shell
+npm install @algorandfoundation/liquid-server --save
+```
+
+```typescript
+//src/main.ts
+import { AppModule, RedisIoAdapter } from '@algorandfoundation/liquid-server';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.useWebSocketAdapter(new RedisIoAdapter(app));
+  await app.listen(3000);
+}
+```
+
+### Vercel
+> We recommend running a proxy server like Nginx in production. This will work in a pinch
+
+```json
+//vercel.json
+{
+  "rewrites": [
+    {
+      "source": "/auth/:path*",
+      "destination": "${serverURL}/auth/:path*"
+    },
+    {
+      "source": "/.well-known/:path*",
+      "destination": "${serverURL}/.well-known/:path*"
+    },
+    {
+      "source": "/attestation/:path*",
+      "destination": "/attestation/:path*"
+    },
+
+    {
+      "source": "/assertion/:path*",
+      "destination": "${serverURL}/assertion/:path*"
+    },
+    {
+      "source": "/socket.io/",
+      "destination": "${serverURL}/socket.io/"
+    },
+    {
+      "source": "/socket.io",
+      "destination": "${serverURL}/socket.io/"
+    }
+  ]
+}
+```
+

package/dist/resources/knowledge/taxonomy/liquid-auth:docs:server:introduction.md

@@ -0,0 +1,22 @@
+---
+title: 'Server: Introduction'
+prev: false
+sidebar:
+  order: 0
+  label: 'Introduction'
+---
+
+Liquid Auth is a self-hosted authentication service that provides a simple way to associate Passkeys to KeyPair(s) commonly found in cryptocurrencies.
+
+#### Technical Details
+
+It is built using the [NestJS](https://nestjs.com/) framework
+and uses [mongoose](https://docs.nestjs.com/techniques/mongodb) to interact with MongoDB.
+Signaling is handled using [Socket.IO](https://docs.nestjs.com/websockets/gateways)
+backed by a [Redis Adapter](https://socket.io/docs/v4/redis-adapter/).
+
+The service request to be running on the same origin as the dApp.
+We recommend configuring your frontend service to proxy requests to the authentication service.
+
+
+

package/dist/resources/knowledge/taxonomy/liquid-auth:docs:server:running-locally.md

@@ -0,0 +1,88 @@
+---
+title: 'Server: Running Locally'
+sidebar:
+  order: 1
+  label: "Running Locally" 
+---
+
+The Liquid Auth service is distributed as a Docker image. FIDO2 and WebRTC require a secure connection, we recommend [using ngrok](#ngrok) to create a secure tunnel to your local server.
+See the server [integrations](./integrations) guide for examples of how to add Liquid Auth to a web application.
+
+### Prerequisites
+
+[Install Docker]() and [login to the GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic).
+```bash
+export CR_PAT=<YOUR_TOKEN>
+echo $CR_PAT | docker login ghcr.io -u <USERNAME> --password-stdin
+```
+
+## Docker Image
+
+The service is designed to be run in a Docker container, it requires a [MongoDB]() and [Redis]() instance to be running.
+See the [Environment Variables](../environment-variables) section for more information about crafting a `.env.docker` file.
+
+```bash 
+docker run -d --env-file .env.docker -p 3000:3000 ghcr.io/algorandfoundation/liquid-auth:develop
+```
+
+### Compose Example
+> Example of using Docker Compose to run the Liquid Auth service.
+
+```yaml
+#docker-compose.yml
+services:
+  liquid-auth:
+    image: ghcr.io/algorandfoundation/liquid-auth:develop
+    env_file:
+      - .env.docker
+    ports:
+      - "3000:3000"
+    depends_on:
+      - redis
+      - mongo
+  redis:
+    image: redis
+    ports:
+      - "6379:6379"
+  mongo:
+    image: mongo:7.0
+    environment:
+      - MONGO_INITDB_DATABASE=${DB_NAME:-fido}
+      - MONGO_INITDB_ROOT_USERNAME=${DB_USERNAME:-algorand}
+      - MONGO_INITDB_ROOT_PASSWORD=${DB_PASSWORD:-algorand}
+    ports:
+      - "27017:27017"
+    volumes:
+      - mongo:/data/db
+volumes:
+  mongo:
+```
+
+### Building
+
+Optionally, create the Docker image locally from the source:
+
+```bash
+git clone git@github.com:algorandfoundation/liquid-auth.git && cd liquid-auth
+docker build -t my-amazing-liquid-auth:latest .
+```
+
+## NGROK
+
+Sign up for a free account at [ngrok](https://ngrok.com/) and follow the instructions to get your `<NGROK_AUTH_TOKEN>` and `<NGROK_STATIC_DOMAIN>`.
+
+#### Configuration
+ngrok will ask you to add your auth token to your configuration file.
+
+``` bash
+ngrok config add-authtoken <NGROK_AUTH_TOKEN>
+```
+
+It will then ask you to deploy your static domain, make sure to change the port to **3000** like this:
+
+``` bash
+ngrok http --domain=<NGROK_STATIC_DOMAIN> 3000
+```
+
+
+Ensure the service's `ORIGIN` and `HOSTNAME` [environment variables](../environment-variables) are configured correctly with the ngrok domain.

package/dist/resources/knowledge/taxonomy/liquid-auth:services:liquid-auth-api-js:src:assertion:assertion.controller.post.request.md

@@ -0,0 +1,3 @@
+# POST Assertion Request
+
+This endpoint is used to request assertion options from the FIDO2 service.

package/dist/resources/knowledge/taxonomy/liquid-auth:services:liquid-auth-api-js:src:assertion:assertion.controller.post.response.md

@@ -0,0 +1,3 @@
+# POST Assertion Response
+
+This endpoint is used to request assertion options from the FIDO2 service.

package/dist/resources/knowledge/taxonomy/liquid-auth:services:liquid-auth-api-js:src:attestation:attestation.controller.post.request.md

@@ -0,0 +1 @@
+# TITLE