> ## Documentation Index
> Fetch the complete documentation index at: https://musubinetwork.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Model

> Authentication, data isolation, privacy, and cryptographic guarantees.

Musubi is designed for institutional participants with strict security requirements. This page covers the security architecture for your InfoSec and integration teams.

## Authentication

API access is authenticated via JWT bearer tokens.

| Property              | Value                                                             |
| --------------------- | ----------------------------------------------------------------- |
| **Token type**        | JWT (JSON Web Token)                                              |
| **Signing algorithm** | HMAC-256 (testnet); RSA-256 via external IdP (production)         |
| **Lifetime**          | 3600 seconds (1 hour) default                                     |
| **Issuer**            | `musubi`                                                          |
| **Audience**          | `musubi-api`                                                      |
| **Key claims**        | `canton_party_id` (your identity), `role` (your participant type) |

Tokens are obtained from your own participant backend (`POST /auth/token`). In production, this will integrate with your organization's identity provider (Keycloak, Auth0, or equivalent SSO).

<Warning>
  The testnet uses a shared HMAC-256 secret across all services. Production deployment will use asymmetric RSA-256 signing where only the authentication service holds the private key.
</Warning>

## Intent Signing

Every order includes an `intent_signature` — a cryptographic signature over the order payload produced by the sender institution's private key.

**What this guarantees:**

* **Non-repudiation**: The sender cannot deny having authorized the payment
* **Integrity**: Any modification to the order payload invalidates the signature
* **Off-chain verifiability**: The signature can be verified independently, without network access

**What this does NOT replace:**

* Custodian authorization (separate co-signature, enforced by the settlement protocol)

## Data Isolation

Each participant runs their own **isolated infrastructure stack**:

```mermaid actions=false theme={null}
graph LR
  subgraph Your Infrastructure
    Apps[Your Apps<br/>Treasury, Recon] --> MB[Musubi Backend<br/>your instance]
    MB --> DB[Your Database<br/>PostgreSQL]
  end
  MB -->|TLS| SN[Settlement Network<br/>Canton]
```

**Key properties:**

* Your backend and database run in **your infrastructure**, not Musubi's
* Your database contains only **your contracts and transactions** — no other participant's data
* Communication between participants flows through the **settlement network protocol**, not direct API calls
* No participant can query another participant's backend or database

## Privacy Model

The settlement network enforces privacy at the protocol level — each participant sees only the contracts they are authorized to see.

| Data                    | You (Sender)    | Your Custodian  | Market Makers   | Receiver Institution      |
| ----------------------- | --------------- | --------------- | --------------- | ------------------------- |
| Order details           | Full visibility | Full visibility | NOT visible     | NOT visible until settled |
| Your identity           | n/a             | Visible         | **NOT visible** | Visible at settlement     |
| Competing quotes        | Visible         | Visible         | Own quotes only | NOT visible               |
| FX rate negotiation     | Visible         | Visible         | Own quotes only | NOT visible               |
| Settlement confirmation | Visible         | Visible         | Visible         | Visible                   |
| Transaction hash        | Visible         | Visible         | Visible         | Visible                   |

Key privacy guarantees:

* **Market makers never see your identity** — RFQs are anonymized (currency pair + amount only)
* **Receiver institution sees only the settlement result** — not the quoting or rate negotiation process
* **No global ledger** — unlike public blockchains, there is no shared state that all participants can read

## Transport Security

| Connection                                            | Security                                         |
| ----------------------------------------------------- | ------------------------------------------------ |
| API requests (your apps to your backend)              | HTTPS/TLS 1.2+                                   |
| Settlement network connections (your node to network) | Mutual TLS with participant certificates         |
| Database connections (backend to PostgreSQL)          | Encrypted, localhost-only on your infrastructure |

## What You Control

| Component                       | Controlled By                                                        |
| ------------------------------- | -------------------------------------------------------------------- |
| Your backend instance           | You                                                                  |
| Your database                   | You                                                                  |
| Your private keys               | You (via your custodian for asset keys, directly for intent signing) |
| JWT token issuance (production) | Your IdP                                                             |
| Network access policies         | You                                                                  |
| Your settlement node            | You                                                                  |