### Build and Run WASM Example

Source: https://github.com/bitwarden/agent-access/blob/main/examples/js-wasm/README.md

Steps to build the WASM package, install JavaScript dependencies, and start the development server. Ensure a listener is running in a separate terminal.

```bash
# 1. Build the WASM package
./build.sh

# 2. Install JS dependencies and start dev server
npm install
npm run dev
```

--------------------------------

### Start Agent Access Listener

Source: https://github.com/bitwarden/agent-access/blob/main/README.md

Starts the Agent Access CLI tool to listen for connections. Use `--provider example` to use built-in example credentials if the Bitwarden CLI is not installed.

```shell
aac listen
```

```shell
aac listen --provider example
```

--------------------------------

### Run Swift Example with PSK Token and Domain

Source: https://github.com/bitwarden/agent-access/blob/main/examples/swift-uniffi/README.md

Execute the Swift example with a PSK token and a specific domain. This is a common way to authenticate and connect to services.

```bash
DYLD_LIBRARY_PATH=../../target/debug swift run ApUniffiExample --token <64hex_psk>_<64hex_fingerprint> --domain github.com
```

--------------------------------

### Run Swift Example with Rendezvous Code

Source: https://github.com/bitwarden/agent-access/blob/main/examples/swift-uniffi/README.md

Run the Swift example using a rendezvous code for authentication. This method is useful for initial connection setups.

```bash
DYLD_LIBRARY_PATH=../../target/debug swift run ApUniffiExample --token ABC-DEF-GHI --domain example.com
```

--------------------------------

### Start User-Client for Demo

Source: https://github.com/bitwarden/agent-access/blob/main/CONTRIBUTING.md

Initiate the user-client side of the demo flow. This command starts the listening process for remote client connections.

```shell
cargo run --bin aac -- listen
```

--------------------------------

### Run Swift Example with PSK Token

Source: https://github.com/bitwarden/agent-access/blob/main/examples/swift-uniffi/README.md

Run the Swift example application using a PSK token for authentication. Ensure the DYLD_LIBRARY_PATH is set correctly to find the native library.

```bash
cd examples/swift-uniffi
DYLD_LIBRARY_PATH=../../target/debug swift run ApUniffiExample --token <PSK_TOKEN_OR_RENDEZVOUS_CODE> --domain example.com
```

--------------------------------

### Run Swift Example with Custom Relay

Source: https://github.com/bitwarden/agent-access/blob/main/examples/swift-uniffi/README.md

Run the Swift example specifying a custom relay server. This allows connecting through a specific WebSocket endpoint.

```bash
DYLD_LIBRARY_PATH=../../target/debug swift run ApUniffiExample --relay wss://your-relay.example.com --token <TOKEN> --domain example.com
```

--------------------------------

### Start Listener

Source: https://github.com/bitwarden/agent-access/blob/main/examples/js-wasm/README.md

Command to start the Agent Access listener on a trusted device. This is required for the browser client to connect.

```bash
cargo run --bin aac -- listen --relay wss://ap.lesspassword.dev
```

--------------------------------

### Install Agent Access CLI on Linux (x86_64)

Source: https://github.com/bitwarden/agent-access/blob/main/README.md

Installs the Agent Access CLI by downloading the x86_64 binary, extracting it, and moving it to /usr/local/bin for PATH availability.

```shell
curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-linux-x86_64.tar.gz | tar xz
sudo mv aac /usr/local/bin/ # Makes it available on PATH
```

--------------------------------

### Install Agent Access CLI on macOS (Intel)

Source: https://github.com/bitwarden/agent-access/blob/main/README.md

Installs the Agent Access CLI by downloading the x86_64 binary, extracting it, and moving it to /usr/local/bin for PATH availability.

```shell
curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-macos-x86_64.tar.gz | tar xz
sudo mv aac /usr/local/bin/ # Makes it available on PATH
```

--------------------------------

### Start Bitwarden PSK Listener

Source: https://github.com/bitwarden/agent-access/blob/main/examples/github-action/README.md

Run this command on a trusted machine with the `bw` CLI unlocked to start the listener and generate a PSK token. Copy the printed token for use in GitHub secrets.

```bash
aac listen --reusable-psk
```

--------------------------------

### Python Example: Connect and Request Credentials

Source: https://github.com/bitwarden/agent-access/blob/main/README.md

Demonstrates how to use the Agent Access Rust SDK via Python UniFFI bindings to establish a connection with a token and request a credential, then prints the username and password.

```python
from agent_access import RemoteClient

client = RemoteClient("python-remote")
client.connect(token="ABC-DEF-GHI")
cred = client.request_credential("example.com")
print(cred.username, cred.password)
client.close()
```

--------------------------------

### Programmatic Usage of Agent Access Client

Source: https://github.com/bitwarden/agent-access/blob/main/examples/js-wasm/README.md

Example of how to import and use the `createClient` function to establish a connection, pair a device, request credentials, and disconnect.

```javascript
import { createClient } from "./agent-access.js";

const client = await createClient("wss://ap.lesspassword.dev");

// Pair with a new device
await client.pair("ABC-DEF-GHI");

// Or reconnect to a saved session
// await client.reconnect(fingerprint);

// Request a credential
const cred = await client.getCredential("example.com");
console.log(cred.username, cred.password, cred.totp);

// Disconnect
client.disconnect();
```

--------------------------------

### Install Agent Access CLI on Windows (x86_64)

Source: https://github.com/bitwarden/agent-access/blob/main/README.md

Installs the Agent Access CLI on Windows by downloading the x86_64 zip archive from the latest release and extracting it to a directory included in the system's PATH.

```shell
Download [aac-windows-x86_64.zip](https://github.com/bitwarden/agent-access/releases/latest/download/aac-windows-x86_64.zip) from the [latest release](https://github.com/bitwarden/agent-access/releases/latest) and extract it to a directory on your PATH.
```

--------------------------------

### Install Agent Access CLI on macOS (Apple Silicon)

Source: https://github.com/bitwarden/agent-access/blob/main/README.md

Installs the Agent Access CLI by downloading the ARM64 binary, extracting it, and moving it to /usr/local/bin for PATH availability.

```shell
curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-macos-aarch64.tar.gz | tar xz
sudo mv aac /usr/local/bin/ # Makes it available on PATH
```

--------------------------------

### Connect with Custom Relay

Source: https://github.com/bitwarden/agent-access/blob/main/examples/python-uniffi/README.md

Example command to connect using a custom relay server. Specify the relay URL and your authentication token.

```bash
python3 connect_request.py --relay wss://your-relay.example.com --token <PSK_TOKEN> --domain example.com
```

--------------------------------

### Connect with PSK Token

Source: https://github.com/bitwarden/agent-access/blob/main/examples/python-uniffi/README.md

Example command to connect to a relay using a PSK token. Replace <PSK_TOKEN> with your actual token.

```bash
python3 connect_request.py --token <PSK_TOKEN> --domain github.com
```

--------------------------------

### Run ap-relay Server

Source: https://github.com/bitwarden/agent-access/blob/main/crates/ap-relay/README.md

Starts the ap-relay server. The server listens on ws://localhost:8080 by default.

```bash
cargo run --bin ap-relay
```

--------------------------------

### Connect with Rendezvous Code

Source: https://github.com/bitwarden/agent-access/blob/main/examples/python-uniffi/README.md

Example command to connect using a rendezvous code. This method discovers the peer via a relay.

```bash
python3 connect_request.py --token ABC-DEF-GHI --domain example.com
```

--------------------------------

### Basic Relay Protocol Client Example

Source: https://github.com/bitwarden/agent-access/blob/main/crates/ap-relay-client/README.md

Connects to a relay server, handles incoming messages, and requests a pairing token. Generates a new identity if none is provided.

```rust
use ap_relay_client::{RelayClientConfig, RelayProtocolClient, IncomingMessage};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = RelayClientConfig {
        relay_url: "ws://localhost:8080".to_string(),
        identity_keypair: None, // Generates a new identity
    };

    let mut client = RelayProtocolClient::new(config);
    let mut incoming = client.connect().await?;

    println!("Connected! Fingerprint: {:?}", client.fingerprint());

    // Handle incoming messages
    tokio::spawn(async move {
        while let Some(msg) = incoming.recv().await {
            match msg {
                IncomingMessage::Send { source, payload, .. } => {
                    println!("Message from {:?}: {:?}", source, payload);
                }
                IncomingMessage::RendezvousInfo(code) => {
                    println!("Your pairing token: {}", code.as_str());
                }
                IncomingMessage::IdentityInfo { identity, .. } => {
                    println!("Found peer: {:?}", identity.fingerprint());
                }
            }
        }
    });

    // Request a pairing token for others to find you
    client.request_rendezvous().await?;

    Ok(())
}
```

--------------------------------

### Install OpenClaw Skill for Agent Access

Source: https://github.com/bitwarden/agent-access/blob/main/README.md

Downloads the OpenClaw skill definition for Agent Access from GitHub and saves it to the appropriate directory within the OpenClaw skills path.

```shell
curl -fsSL "https://raw.githubusercontent.com/bitwarden/agent-access/main/examples/skills/agent-access/SKILL.md" -o ~/.openclaw/skills/agent-access/SKILL.md --create-dirs
```

--------------------------------

### Run the Relay Server

Source: https://github.com/bitwarden/agent-access/blob/main/CONTRIBUTING.md

Execute the `ap-relay` binary to start the WebSocket relay server. The default bind address is `127.0.0.1:8080`, which can be overridden using the `BIND_ADDR` environment variable.

```shell
cargo run -p ap-relay
```

--------------------------------

### Inject Credentials into a Command with aac run

Source: https://github.com/bitwarden/agent-access/blob/main/examples/github-action/README.md

Use `aac run` to inject fetched credentials directly into a command. This example demonstrates logging into a Docker registry using environment variables for username and password.

```yaml
- name: Run with credentials
  run: |
    aac run \
      --domain "registry.example.com" \
      --ephemeral-connection \
      --env DOCKER_USER=username \
      --env DOCKER_PASS=password \
      -- sh -c 'echo "$DOCKER_PASS" | docker login registry.example.com -u "$DOCKER_USER" --password-stdin'
```

--------------------------------

### Fetch Credentials by Vault Item ID with aac connect

Source: https://github.com/bitwarden/agent-access/blob/main/examples/github-action/README.md

Use `aac connect` with the `--id` flag to fetch credentials directly from a specific vault item. This example outputs the fetched credentials in JSON format.

```yaml
- name: Fetch by ID
  run: |
    aac connect \
      --id "12345678-1234-1234-1234-123456789abc" \
      --ephemeral-connection \
      --output json
```

--------------------------------

### Build cdylib and Generate Bindings

Source: https://github.com/bitwarden/agent-access/blob/main/crates/ap-uniffi/README.md

Build the `ap-uniffi` cdylib and then generate native bindings for Python and Swift using `uniffi-bindgen`.

```bash
# Build the cdylib
cargo build -p ap-uniffi

# Generate bindings
cargo run --bin uniffi-bindgen generate \
    --library target/debug/libap_uniffi.dylib \
    --language python --out-dir examples/python-uniffi/

cargo run --bin uniffi-bindgen generate \
    --library target/debug/libap_uniffi.dylib \
    --language swift --out-dir examples/swift-uniffi/Sources/ApUniffi/
```

--------------------------------

### Build Native Library with Cargo

Source: https://github.com/bitwarden/agent-access/blob/main/examples/python-uniffi/README.md

Build the Rust native library for UniFFI bindings. Ensure you are in the project root directory.

```bash
cargo build -p ap-uniffi
```

--------------------------------

### Generate Swift Bindings with UniFFI

Source: https://github.com/bitwarden/agent-access/blob/main/examples/swift-uniffi/README.md

Generate Swift bindings using the UniFFI CLI. This command creates the necessary Swift files from the Rust library.

```bash
cargo run --bin uniffi-bindgen generate --library target/debug/libap_uniffi.dylib --language swift --out-dir examples/swift-uniffi/generated/
```

--------------------------------

### Build the Agent Access Project

Source: https://github.com/bitwarden/agent-access/blob/main/CONTRIBUTING.md

Run this command in the root directory to build the standalone workspace. Requires Rust 1.85+.

```shell
cargo build
```

--------------------------------

### createClient

Source: https://github.com/bitwarden/agent-access/blob/main/examples/js-wasm/README.md

Creates a client instance for Agent Access. It persists identity and sessions using localStorage.

```APIDOC
## `await createClient(relayUrl, identityName?)`

### Description
Create a client. Identity and sessions are persisted in `localStorage`.

### Parameters
#### Parameters
- **relayUrl** (string) - Required - The WebSocket URL for the relay server.
- **identityName** (string) - Optional - The name for the identity.
```

--------------------------------

### Manual WASM Build

Source: https://github.com/bitwarden/agent-access/blob/main/examples/js-wasm/README.md

Command to manually build the WebAssembly package for the web target, outputting to the 'pkg' directory.

```bash
wasm-pack build --target web --out-dir pkg
```

--------------------------------

### Generate Kotlin Bindings

Source: https://github.com/bitwarden/agent-access/blob/main/examples/python-uniffi/README.md

Generate UniFFI bindings for Kotlin. This command targets the native library and specifies Kotlin as the output language.

```bash
cargo run --bin uniffi-bindgen generate --library target/debug/libap_uniffi.dylib --language kotlin --out-dir bindings/kotlin/
```

--------------------------------

### Generate Swift Bindings

Source: https://github.com/bitwarden/agent-access/blob/main/examples/python-uniffi/README.md

Generate UniFFI bindings for Swift. This command targets the native library and specifies Swift as the output language.

```bash
cargo run --bin uniffi-bindgen generate --library target/debug/libap_uniffi.dylib --language swift --out-dir bindings/swift/
```

--------------------------------

### Pairing with PSK Token

Source: https://github.com/bitwarden/agent-access/blob/main/examples/skills/agent-access/SKILL.md

Alternatively, you can use a PSK token for pairing, which has a specific format: `<64-hex-psk>_<64-hex-fingerprint>`.

```bash
aac --domain example.com --token <PSK_TOKEN> --output json
```

--------------------------------

### Connect to Agent Access (Interactive)

Source: https://github.com/bitwarden/agent-access/blob/main/README.md

Initiates an interactive connection to the Agent Access service. Useful for testing and demonstration purposes.

```shell
aac connect
```

--------------------------------

### Generate Python Bindings with UniFFI

Source: https://github.com/bitwarden/agent-access/blob/main/examples/python-uniffi/README.md

Generate Python bindings using the UniFFI bindgen tool. This command creates the necessary Python interface files.

```bash
cargo run --bin uniffi-bindgen generate --library target/debug/libap_uniffi.dylib --language python --out-dir examples/python-uniffi/
```

--------------------------------

### Generate Ruby Bindings

Source: https://github.com/bitwarden/agent-access/blob/main/examples/python-uniffi/README.md

Generate UniFFI bindings for Ruby. This command targets the native library and specifies Ruby as the output language.

```bash
cargo run --bin uniffi-bindgen generate --library target/debug/libap_uniffi.dylib --language ruby --out-dir bindings/ruby/
```

--------------------------------

### Connect to Agent Access (Non-Interactive)

Source: https://github.com/bitwarden/agent-access/blob/main/README.md

Establishes a non-interactive connection to Agent Access. Requires a pairing token for initial connection or a domain to fetch credentials. Outputs results in JSON format.

```shell
aac connect --token <pairing-token> --output json
```

```shell
aac connect --domain example.com --output json
```

```shell
aac connect --domain github.com --provider bitwarden --output json
```

```shell
aac connect --token <pairing-token> --domain example.com --output json
```

```shell
aac connect --id <vault-item-id> --output json
```

--------------------------------

### Copy Generated Files into Package

Source: https://github.com/bitwarden/agent-access/blob/main/examples/swift-uniffi/README.md

Copy the generated Swift bindings and C FFI header into the Swift package structure. These files are essential for the Swift application to interface with the Rust library.

```bash
cp examples/swift-uniffi/generated/ap_uniffi.swift examples/swift-uniffi/Sources/ApUniffi/
```

```bash
cp examples/swift-uniffi/generated/ap_uniffiFFI.h examples/swift-uniffi/Sources/CApUniffi/include/
```

--------------------------------

### Run Command with Injected Credentials

Source: https://github.com/bitwarden/agent-access/blob/main/README.md

Fetches a credential and injects its fields as environment variables into a child process. Secrets are passed directly to the child process's environment, not to stdout or disk. Requires either `--env` or `--env-all`.

```shell
aac run --domain example.com --env DB_PASSWORD=password --env DB_USER=username -- psql
```

```shell
aac run --domain example.com --env-all -- deploy.sh
```

```shell
aac run --domain example.com --env-all --env CUSTOM_PW=password -- deploy.sh
```

```shell
aac run --id <vault-item-id> --env-all -- deploy.sh
```

--------------------------------

### Perform Basic Handshake and Exchange Messages in Rust

Source: https://github.com/bitwarden/agent-access/blob/main/crates/ap-noise/README.md

Demonstrates a basic Noise Protocol handshake between an initiator and a responder, followed by encrypted message exchange. Ensure fingerprints are verified to prevent MITM attacks.

```rust
use ap_noise::{Ciphersuite, InitiatorHandshake, ResponderHandshake};

fn main() -> Result<(), ap_noise::NoiseProtocolError> {
    // Create initiator and responder
    let mut initiator = InitiatorHandshake::new();
    let mut responder = ResponderHandshake::new();

    // Perform handshake
    let msg1 = initiator.send_start()?;
    responder.receive_start(&msg1)?;
    let msg2 = responder.send_finish()?;
    initiator.receive_finish(&msg2)?;

    // Finalize handshake and get transport state
    let (mut transport_initiator, fingerprint_initiator) = initiator.finalize()?;
    let (mut transport_responder, fingerprint_responder) = responder.finalize()?;

    // ⚠️ Verify fingerprints match to prevent MITM attacks
    assert_eq!(fingerprint_initiator, fingerprint_responder);
    println!("Handshake complete. Fingerprint: {}", fingerprint_initiator);

    // Exchange encrypted messages
    let plaintext = b"Hello, secure world!";
    let encrypted = transport_initiator.encrypt(plaintext)?;
    let decrypted = transport_responder.decrypt(&encrypted)?;
    assert_eq!(decrypted, plaintext);

    Ok(())
}
```

--------------------------------

### Fetch Credentials by Domain

Source: https://github.com/bitwarden/agent-access/blob/main/examples/skills/agent-access/SKILL.md

Retrieve credentials for a specific website domain. If multiple sessions are cached, specify the session using `--session <HEX>`. The `--output json` flag is recommended for programmatic access.

```bash
aac --domain example.com --output json
```

--------------------------------

### Pairing with a Trusted Device

Source: https://github.com/bitwarden/agent-access/blob/main/examples/skills/agent-access/SKILL.md

If no session exists, the user must pair their device. This involves running `aac listen` on the trusted device and providing the displayed pairing token.

```bash
aac --domain example.com --token <CODE> --output json
```

--------------------------------

### Symlink Native Library for Python

Source: https://github.com/bitwarden/agent-access/blob/main/examples/python-uniffi/README.md

Create symbolic links for the native library in the Python bindings directory. This allows the generated Python module to load the dynamic library.

```bash
# macOS
ln -sf ../../target/debug/libap_uniffi.dylib examples/python-uniffi/
```

```bash
# Linux
ln -sf ../../target/debug/libap_uniffi.so examples/python-uniffi/
```

--------------------------------

### client.getCredential

Source: https://github.com/bitwarden/agent-access/blob/main/examples/js-wasm/README.md

Requests credentials for a specified domain. Returns an object containing username, password, TOTP, URI, notes, credential ID, and domain.

```APIDOC
## `await client.getCredential(domain)`

### Description
Request credentials for a domain. Returns `{ username, password, totp, uri, notes, credential_id, domain }`.

### Parameters
#### Parameters
- **domain** (string) - Required - The domain for which to request credentials.

### Response
#### Success Response (200)
- **username** (string) - The username for the credential.
- **password** (string) - The password for the credential.
- **totp** (string) - The Time-based One-Time Password secret, if available.
- **uri** (string) - The URI associated with the credential.
- **notes** (string) - Any additional notes for the credential.
- **credential_id** (string) - The unique identifier for the credential.
- **domain** (string) - The domain the credential is for.
```

--------------------------------

### client.pair

Source: https://github.com/bitwarden/agent-access/blob/main/examples/js-wasm/README.md

Pairs the client with a new device using a rendezvous code or PSK token. It returns the handshake fingerprint for rendezvous or null for PSK.

```APIDOC
## `await client.pair(token)`

### Description
Pair with a new device using a rendezvous code (`"ABC-DEF-GHI"`) or PSK token. Returns the handshake fingerprint for rendezvous, or `null` for PSK.

### Parameters
#### Parameters
- **token** (string) - Required - The rendezvous code or PSK token.
```

--------------------------------

### Credential JSON Output Structure

Source: https://github.com/bitwarden/agent-access/blob/main/examples/skills/agent-access/SKILL.md

The JSON output contains success status, the domain queried, and the credential details including username, password, TOTP, URI, and notes.

```json
{
  "success": true,
  "domain": "example.com",
  "credential": {
    "username": "user@example.com",
    "password": "s3cret",
    "totp": "123456",
    "uri": "https://example.com/login",
    "notes": "optional notes"
  }
}
```

--------------------------------

### Fetch Credential by Vault Item ID

Source: https://github.com/bitwarden/agent-access/blob/main/README.md

Fetches a specific vault item using its unique ID. This is an alternative to fetching by domain and is useful when multiple items share the same domain or when the exact item is known. The `--id` and `--domain` flags are mutually exclusive.

```shell
aac connect --id <vault-item-id> --output json
```

--------------------------------

### Session Management Commands

Source: https://github.com/bitwarden/agent-access/blob/main/examples/skills/agent-access/SKILL.md

Manage cached sessions and identity keys using `aac connections` commands. Use `list` to view sessions, `clear` to remove all data, or `clear sessions` to remove only sessions.

```bash
aac connections list
```

```bash
aac connections clear
```

```bash
aac connections clear sessions
```

--------------------------------

### Embed ap-relay Server in Application

Source: https://github.com/bitwarden/agent-access/blob/main/crates/ap-relay/README.md

Embeds the ap-relay server into a Rust application. Requires the `ap-relay` crate and `tokio` runtime.

```rust
use ap_relay::server::RelayServer;
use std::net::SocketAddr;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let addr: SocketAddr = "127.0.0.1:8080".parse()?;
    let server = RelayServer::new(addr);
    server.run().await?;
    Ok(())
}
```

--------------------------------

### client.listConnections

Source: https://github.com/bitwarden/agent-access/blob/main/examples/js-wasm/README.md

Lists all saved connections. Returns an array of connection objects, each containing fingerprint, name, cachedAt, and lastConnectedAt.

```APIDOC
## `await client.listConnections()`

### Description
List saved connections. Returns `[{ fingerprint, name, cachedAt, lastConnectedAt }]`.

### Response
#### Success Response (200)
- **fingerprint** (string) - The unique fingerprint of the connection.
- **name** (string) - The name of the connection.
- **cachedAt** (string) - The timestamp when the connection was cached.
- **lastConnectedAt** (string) - The timestamp of the last successful connection.
```

--------------------------------

### Agent Access CLI Usage

Source: https://github.com/bitwarden/agent-access/blob/main/CONTRIBUTING.md

The `aac` command is the top-level driver for the Agent Access CLI. It allows interaction with the SDK's functionality, including connecting to a relay and requesting credentials.

```shell
Retrieve credentials from your password manager over a secure channel

Usage: aac [OPTIONS] [COMMAND]

Commands:
  connect      Connect to relay and request credentials
  listen       Listen for remote client connections (user-client mode)
  connections  Manage connections
  help         Print this message or the help of the given subcommand(s)

Options:
      --relay-url <RELAY_URL>  Relay server URL [default: wss://ap.lesspassword.dev]
      --token <TOKEN>          Token (rendezvous code or PSK token)
      --session <SESSION>      Session fingerprint to reconnect to (hex string)
      --no-cache               Disable session caching
      --debug-log              Enable debug logging for the multi-device Noise protocol
  -h, --help                   Print help
  -V, --version                Print version
```

--------------------------------

### Save and Restore Transport State in Rust

Source: https://github.com/bitwarden/agent-access/blob/main/crates/ap-noise/README.md

Shows how to serialize and deserialize the transport state for session resumption. This allows continuing encrypted communication with the same keys after restoring the state.

```rust
# use ap_noise::MultiDeviceTransport;
# fn example(transport: &mut MultiDeviceTransport) -> Result<(), Box<dyn std::error::Error>> {
// Save transport state
let state_bytes = transport.save_state()?;
// ... store state_bytes to file, database, etc. ...

// Later, restore transport state
let mut restored_transport = MultiDeviceTransport::restore_state(&state_bytes)?;

// Continue encrypted communication with same keys
let packet = restored_transport.encrypt(b"Resumed session")?;
# Ok(())
# }
```

--------------------------------

### Check for Existing Session with aac

Source: https://github.com/bitwarden/agent-access/blob/main/examples/skills/agent-access/SKILL.md

Before fetching credentials, check if an active session exists using `aac connections list`. This command lists all cached sessions.

```bash
aac connections list
```

--------------------------------

### client.reconnect

Source: https://github.com/bitwarden/agent-access/blob/main/examples/js-wasm/README.md

Reconnects to a previously paired device using its hex fingerprint.

```APIDOC
## `await client.reconnect(fingerprint)`

### Description
Reconnect to a previously paired device using its hex fingerprint.

### Parameters
#### Parameters
- **fingerprint** (string) - Required - The hex fingerprint of the device to reconnect to.
```

--------------------------------

### Credential Request Structure

Source: https://github.com/bitwarden/agent-access/blob/main/protocol-v0.md

Defines the JSON structure for a credential request. Use this when querying for credentials based on domain, ID, or a search term. Ensure the timestamp is current and a unique requestId is provided.

```jsonc
{
  "type":      "credential-request",   // fixed discriminator
  "query":     { "domain": "example.com" } | { "id": "..." } | { "search": "..." },
  "timestamp": 1729600000,              // u64, seconds since Unix epoch
  "requestId": "9f7c8e2b-4a1d-..."      // opaque string, caller-generated; see §5.1
}
```

--------------------------------

### HandshakeFingerprint Calculation

Source: https://github.com/bitwarden/agent-access/blob/main/protocol-v0.md

Illustrates the calculation of the HandshakeFingerprint using SHA256 on the derived session keys. This fingerprint is used for out-of-band verification in rendezvous mode.

```rust
HandshakeFingerprint = hex(SHA256(r2i_key || i2r_key)[0..3])   // 6 hex
```

--------------------------------

### client.clearConnections

Source: https://github.com/bitwarden/agent-access/blob/main/examples/js-wasm/README.md

Clears all saved connections from localStorage.

```APIDOC
## `client.clearConnections()`

### Description
Clear all saved connections from localStorage.
```

--------------------------------

### Credential Response Structure

Source: https://github.com/bitwarden/agent-access/blob/main/protocol-v0.md

Defines the JSON structure for a credential response. This includes the credential details or an error message. All fields within the credential object are optional and may be returned as a subset.

```jsonc
{
  "credential": {
    "credentialId": "b1f2-...",         // optional; vendor vault item ID
    "domain":       "example.com",      // optional, exists because uri may contain information.
    "uri":          "https://example.com/login",  // optional
    "username":     "alice@example.com",          // optional
    "password":     "hunter2",                    // optional; treated as secret
    "totp":         "123456",                     // optional; current OTP value OR an otpauth:// URI (vendor choice)
    "notes":        "..."                         // optional
  },
  "error":     null,                    // absent on success
  "requestId": "9f7c8e2b-4a1d-..."      // echoed from the request
}
```

--------------------------------

### Server Send Message Structure

Source: https://github.com/bitwarden/agent-access/blob/main/protocol-v0.md

Structure for messages sent from the server to recipients. Includes the authenticated sender's fingerprint in the 'source' field.

```json
{ "source", "destination", "payload" }
```

--------------------------------

### HandshakePacket Structure

Source: https://github.com/bitwarden/agent-access/blob/main/protocol-v0.md

Defines the structure of a HandshakePacket, which is serialized using CBOR. It includes the message type, ciphersuite identifier, and the raw Noise payload.

```rust
HandshakePacket {
  message_type:  u8,     // 0x01 | 0x02
  ciphersuite:   u8,     // 0x01 | 0x02
  payload:       bytes,  // raw Noise bytes (≤ 65 535)
}
```

--------------------------------

### client.disconnect

Source: https://github.com/bitwarden/agent-access/blob/main/examples/js-wasm/README.md

Disconnects the client and releases any associated resources.

```APIDOC
## `client.disconnect()`

### Description
Disconnect and release resources.
```

--------------------------------

### Client Send Message Structure

Source: https://github.com/bitwarden/agent-access/blob/main/protocol-v0.md

Structure for messages sent from a client to the server. The 'source' field is ignored by the server; only 'destination' and 'payload' are used.

```json
{ "source?", "destination", "payload" }
```

--------------------------------

### Rekey Function

Source: https://github.com/bitwarden/agent-access/blob/main/protocol-v0.md

Defines the deterministic rekey function used to derive new keys from existing ones. This function is one-way and relies on XChaCha20-Poly1305 encryption with specific parameters.

```plaintext
rekey(k) = XChaCha20-Poly1305::encrypt(k, 0xFF*24, 0*32, aad=[])[0..32]
```

--------------------------------

### Handshake Message Types

Source: https://github.com/bitwarden/agent-access/blob/main/protocol-v0.md

Defines the message types used during the Noise handshake process. These are used to distinguish between the initial handshake message and the final handshake confirmation.

```rust
MessageType::HandshakeStart   = 0x01     // I → R
MessageType::HandshakeFinish  = 0x02     // R → I
```

--------------------------------

### PersistentTransportState Structure (CBOR)

Source: https://github.com/bitwarden/agent-access/blob/main/protocol-v0.md

Defines the structure for persisting transport session state, including cryptographic keys, counters, and timing information. This allows sessions to be suspended and resumed.

```plaintext
PersistentTransportState {
  ciphersuite:        u8,
  send_key:           bytes[32],
  recv_key:           bytes[32],
  send_rekey_counter: u64,
  recv_rekey_counter: u64,
  last_rekeyed_time:  u64,
  rekey_interval:     u64,
}
```

--------------------------------

### Error Handling in JSON Output

Source: https://github.com/bitwarden/agent-access/blob/main/examples/skills/agent-access/SKILL.md

When an error occurs, the `aac` tool outputs a JSON object with a `success` flag set to `false` and an `error` object containing a message and a code.

```json
{"success": false, "error": {"message": "...", "code": "connection_failed"}}
```

--------------------------------

### Protocol v0 Message Types

Source: https://github.com/bitwarden/agent-access/blob/main/protocol-v0.md

These are the base JSON structures for various protocol messages, including handshake, credential requests, and responses. They are serialized within the Send.payload.

```json
{"type":"handshake-init",     "data":"<b64(HandshakePacket)>", "ciphersuite":"<name>", "psk_id":"<16-hex>"?}
{"type":"handshake-response", "data":"<b64(HandshakePacket)>", "ciphersuite":"<name>"}
{"type":"credential-request", "encrypted":"<b64(TransportPacket)>"}
{"type":"credential-response","encrypted":"<b64(TransportPacket)>"}
```

--------------------------------

### TransportPacket Structure (CBOR)

Source: https://github.com/bitwarden/agent-access/blob/main/protocol-v0.md

Defines the structure of a TransportPacket used for secure communication, including nonce, ciphertext, and authenticated data (AAD).

```plaintext
TransportPacket {
  nonce:      bytes[24],   // random XChaCha20 nonce
  ciphertext: bytes,       // XChaCha20-Poly1305(key, nonce, plaintext, aad)
  aad:        bytes,       // CBOR-encoded TransportPacketAad
}

TransportPacketAad {
  timestamp:     u64,   // seconds since Unix epoch
  chain_counter: u64,   // sender's rekey counter at encrypt time, starts at 1
  ciphersuite:   u8,
}
```

--------------------------------

### Messages Enum Definition

Source: https://github.com/bitwarden/agent-access/blob/main/protocol-v0.md

Defines the structure of messages exchanged between client and server, including authentication, rendezvous, identity, and general send messages. These are JSON-serialized and externally tagged.

```rust
AuthChallenge(Challenge)                                 // S → C
AuthResponse(Identity, ChallengeResponse)                // C → S

GetRendezvous                                            // C → S, UserClient
RendezvousInfo(RendezvousCode)                           // S → C, UserClient

GetIdentity(RendezvousCode)                              // C → S, RemoteClient
IdentityInfo { fingerprint, identity }                   // S → C, RemoteClient

Send { source?, destination, payload }                   // C ⇄ S
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.