uniplex 1.2.1
Python SDK for the Uniplex protocol - AI agent trust infrastructure
Requires Python: >=3.9
Keywords: agents, ai, authorization, mcp, passport, trust

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/uniplex-logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="assets/uniplex-logo-light.svg">
    <img alt="Uniplex" src="assets/uniplex-logo-dark.svg" width="700">
  </picture>
</p>

<p align="center">
  <sub>Specification v1.1.0 — SDKs available (Python, TypeScript)</sub>
</p>

<p align="center">
  <a href="https://uniplex.io">Documentation</a> ·
  <a href="SPECIFICATION.md">Specification</a> ·
  <a href="UNIPLEX-COMMERCE-EXTENSION-v1.0.0.md">Commerce Extension</a> ·
  <a href="#quickstart">Quickstart</a> ·
  <a href="https://github.com/uniplexprotocol/uniplex/discussions">Discuss</a>
</p>

<br>

## An open protocol to authorize agents and protect what they access.

There's no standard way for AI agents to prove they're authorized or for tools to enforce what's allowed. Uniplex is an open protocol that solves both sides — Gates protect tools, Passports authorize agents, everything verified locally.

- **Gates:** Any tool—MCP servers, APIs, or agent tool calls—can verify passports locally and make an allow/deny decision.
- **Passports:** Agents carry signed credentials that prove what they are, who issued them, and what they're allowed to do.
- **Pluggable (no rip-and-replace):** Works alongside your existing auth (API keys, OAuth/JWT, mTLS) and can be adopted incrementally—start at one tool boundary; run standalone in a single system or federate across many systems as needed.
- **Local-First:** Runs locally in the request flow—no network calls in the hot path and no shared secrets.
- **Security Tiers (L1/L2/L3):** L1 is dev/test (optionally allow self-issued). L2 is production (trusted issuers + theft/replay protections + revocation policy). L3 is strictest (no implicit trust + hardened controls).
- **Vendor-Neutral:** Not tied to any model provider; works with any agent framework, model, or tool stack—no single vendor is privileged by the protocol.

### How It Works

```mermaid
sequenceDiagram
    participant I as Issuer
    participant A as Agent
    participant G as Gate

    I->>A: Issues Passport (credentials + scoped permissions)
    A->>G: Request + Passport
    G->>G: Verify signature & check policy (L1/L2/L3)
    G->>A: Allow/Deny + Attestation
```

**Key insight:** Verification happens locally at the Gate — no round-trip to a central server for every tool call.

## Why Uniplex?

| Feature | API Keys | OAuth 2.0 | Uniplex |
|---------|----------|-----------|---------|
| **Designed&nbsp;For** | Systems/Services | Human-centric | AI Agents |
| **Scoping** | All-or-nothing | Centralized scopes | Action + Resource + Constraints |
| **Verification** | Server-side lookup | JWT validation or introspection | Local cryptographic check |
| **Latency** | Network round-trip | Often local (JWT); sometimes network (introspection) | Designed for sub-millisecond local checks |
| **Offline&nbsp;Support** | No | Possible (JWT); not inherent | First-class |
| **Auditability** | Opaque logs | Token-based | Signed attestations |

> **Note:** OAuth can be validated locally when using JWT access tokens; Uniplex is purpose-built for agent credentials and tool-bound scoping with local-first verification.

## SDK Feature Coverage

Implements **Uniplex Specification v1.1.0 + Commerce Extension v1.0.0**.

### Core Protocol

| Feature | Spec | TypeScript | Python |
|---------|------|:----------:|:------:|
| L1/L2/L3 Verification | §7, §8 | Yes | Yes |
| Delegation Chains | §27 | Yes | Yes |
| Anonymous Access | §14A | Yes | Yes |
| Constraint Enforcement (CEL) | §14B | Yes | Yes |
| Session Grants | §24 | Yes | Yes |
| Proof of Possession | §12 | Yes | Yes |
| Trust Registry | §18 | Yes | Yes |
| Failure Mode Table | §22.1 | Yes | Yes |
| MCP Integration | — | Yes | Yes |

### Commerce Extension

| Feature | TypeScript | Python |
|---------|:----------:|:------:|
| Catalog Publishing | Yes | Yes |
| Consumption Attestations | Yes | Yes |
| Commerce PoP | Yes | Yes |
| Settlement Aggregation | Yes | Yes |
| SLA Compliance | Yes | Yes |
| Service Discovery | Yes | Yes |
| Dispute Resolution | Yes | Yes |
| Mutual Attestation | Yes | Yes |
| Session Digests | Yes | Yes |

## Packages

| Package | Description | Install |
|---------|-------------|---------|
| [`uniplex`](https://pypi.org/project/uniplex/) | Core protocol library — Passports, Gates, Attestations | `npm install uniplex` / `pip install uniplex` |
| [`uniplex-mcp-sdk`](https://github.com/uniplexprotocol/uniplex-mcp-sdk) | Protect your MCP server with Gates — permission verification, constraints, and audit trail | `npm install uniplex-mcp-sdk` / `pip install uniplex-mcp-sdk` |
| [`uniplex-mcp-manage`](https://github.com/uniplexprotocol/uniplex-mcp-manage) | Manage issuers, passports, gates, and attestations from Claude or any MCP client | `npx uniplex-mcp-manage` |

## Quickstart

### Installation

```bash
npm install uniplex    # TypeScript
pip install uniplex    # Python
```

### Create a Self-Issued Passport (L1)

> **Note:** L1/self-issued passports are intended for dev/test and low-risk reads. For production, use L2/L3 with trusted issuer policy and theft/replay protections.

```python
from uniplex import Passport

passport = Passport.create_self_issued(
    agent_id="my-agent",
    permissions=[
        {"action": "read", "resource": "file:*.txt"}
    ],
    ttl_hours=24
)
```

### Verify at a Gate

`Gate.check` accepts a `Passport` object or a base64-encoded passport string.

```python
from uniplex import Gate

# L1 is dev/test only; use L2/L3 in production
gate = Gate(profile="L1")

decision = gate.check(
    passport=passport,
    action="read",
    resource="file:config.txt"
)

if decision.allowed:
    # Proceed with operation
    pass
else:
    print(f"Denied: {decision.reason}")
```

### MCP Integration

For MCP servers, [`uniplex-mcp-sdk`](https://github.com/uniplexprotocol/uniplex-mcp-sdk) provides a turnkey integration with a fluent tool builder, automatic passport verification, constraint enforcement, and attestation logging:

```python
from uniplex_mcp import UniplexMCPServer, define_tool

search_flights = (
    define_tool()
    .name('search_flights')
    .permission('flights:search')
    .schema({
        'type': 'object',
        'properties': {
            'origin': {'type': 'string'},
            'destination': {'type': 'string'},
            'date': {'type': 'string', 'format': 'date'}
        },
        'required': ['origin', 'destination', 'date']
    })
    .handler(search_flights_handler)
    .build()
)

server = UniplexMCPServer(
    gate_id='gate_acme-travel',
    tools=[search_flights]
)
server.start()
```

Or use the core library directly for full control — `Gate.check` works in any Python context:

```python
from uniplex import Gate

gate = Gate(profile="L2")

@mcp_server.tool()
def charge_card(card_id: str, amount: int, passport_b64: str):
    decision = gate.check(
        passport=passport_b64,
        action="payments.charge",
        resource=f"card:{card_id}"
    )

    if not decision.allowed:
        raise PermissionError(f"Denied: {decision.reason}")

    return {"status": "ok", "charged": amount}
```

## Integrations

Uniplex is framework-agnostic. It works with any tool, API, or agent framework that can accept a Passport (string/header).

## Trust Profiles

| Profile | When to Use | Requirements |
|---------|-------------|--------------|
| **L1&nbsp;Baseline** | Dev/test, low-risk reads | Self-issued allowed only if explicitly enabled by Gate policy |
| **L2&nbsp;Standard** | Production authorization | Non-self-issued passport + theft/replay protections + explicit revocation policy |
| **L3&nbsp;Strict** | High assurance / multi-tenant | All L2 requirements + strict trust resolution (no implicit trust) + hardened theft protection |

## Documentation

- **[Specification](SPECIFICATION.md)** — Full protocol specification (v1.1.0)
- **[Commerce Extension](UNIPLEX-COMMERCE-EXTENSION-v1.0.0.md)** — Uniplex Commerce enables agent-to-agent commerce: service advertising, consumption metering, settlement, and dispute resolution.
- **[Documentation](https://uniplex.io)** — Guides, tutorials, API reference
- **[Examples](examples/)** — Working code samples

## Contributing

We'd love your help — whether it's fixing bugs, improving docs, or shaping the protocol itself. See our [contributing guide](CONTRIBUTING.md) to get started.

- 💬 [Discussions](https://github.com/uniplexprotocol/uniplex/discussions) — Questions and ideas
- 🐛 [Issues](https://github.com/uniplexprotocol/uniplex/issues) — Bug reports and feature requests
- 𝕏 [@uniplexprotocol](https://x.com/uniplexprotocol) — Updates and announcements

## License

Apache-2.0 — see [LICENSE](LICENSE) for details.

---

<p align="center">
  <sub>Maintained by <a href="https://standardlogic.ai">Standard Logic Co.</a></sub>
</p>