mid-signin
The drop-in Relying-Party kit for Sign in with MATA (mID). Ten lines to production sign-in — replay-safe, rollback-checked, zero schema work, and zero runtime calls to MATA infrastructure (there is no MATA server in the protocol to call).
mid-verify does the cryptography and
deliberately stops there — it is a pure, stateless function. A production RP
still owes three duties the verifier cannot perform, and every integrator ends
up rebuilding them by hand. This crate is those duties, done once:
| Duty | Why it exists | Who enforces it |
|---|---|---|
| Single-use nonces | The verifier only checks nonce equality; without issuance + one-time consumption, a captured token replays forever | NonceStore (TTL + flood ceiling built in) |
| Genesis anchoring | A known DID must present the same genesis-roster hash every time; a different one is identity spoofing | AnchorStore |
| Rollback detection | The head-roster version must never decrease; a decrease is a stolen device presenting a pre-revocation roster | AnchorStore |
| Session production | Turning "verified token" into "this request is Alice" | Your app — the kit returns an RpSession and gets out of the way |
Authenticator composes the flow: verify → consume nonce → check anchor.
A failed verification never burns the nonce, so a legitimate retry survives.
Quickstart (axum)
[]
= { = "0.1", = ["routes", "redb-store"] }
use Arc;
use ;
// One file on disk. No schema, no migration. Nonces + anchors survive restarts.
let store = new;
let auth = new;
let rp = new;
let app = new
.merge;
// POST /auth/mid/nonce → {"nonce": "…"}
// POST /auth/mid/verify → 200 {"did", "claims", "roster_version"} | 401 {"error"}
Frontend (any page, @matanetwork/sovereign-id):
import from "@matanetwork/sovereign-id";
const = await .;
const result = await ;
const session = await .;
// session.did is the user's stable identifier.
That's the whole integration. No registration, no client_id, no shared secret, no JWKS refresh, no MATA account.
Minting your own session cookie
Pass a responder to routes::router_with — it runs after successful
verification and can take over the response:
let hook: OnVerified = new;
let app = router_with;
Apps with richer needs (async session stores, custom framing) skip the router and call the flow directly — it is one method:
let session = rp.verify_jwt?; // peek nonce → verify → consume → anchor check
Bolting into your own database
The stores are two small traits — implement them over your users table instead of using redb:
Suggested columns on your users table: did TEXT PRIMARY KEY,
genesis_roster_hash BYTEA, last_seen_roster_version BIGINT. Guard updates
with WHERE genesis_roster_hash = $presented — a mismatch is an attack, not a
conflict.
Native-app RPs: use a loopback callback page, not a custom URL scheme
On desktop, users without the browser extension sign in via the MATA native
app: your RP deep-links mata-mid://request?payload=… and the wallet
returns the token by opening your callback URL. Two hard-won rules:
- Don't use a custom scheme (
myapp://…) as the callback unless you ship a real OS bundle. On macOS only a bundled.app(withCFBundleURLTypesin its Info.plist) can register a scheme with LaunchServices — a bare binary cannot, and the wallet's callback then dies silently after the user approved. Windows needs the equivalent HKCU registration. - The portable answer is a loopback HTTP page. Set
callback: "http://127.0.0.1:<your-port>/auth/mid/callback"and serve a tiny page there that readslocation.hash(#mid_response=<base64url>), extracts the token, and POSTs it to your verify endpoint on the same loopback address. The token rides the URL fragment, which browsers never transmit in the HTTP request, and loopback never leaves the machine. Your app polls its own session endpoint until sign-in lands. One brief browser hop, zero registration, works from any binary.
The deep link itself is best dispatched via the OS launcher (open /
ShellExecuteW / xdg-open), not by navigating a webview — webviews may
cancel top-level navigations to custom schemes.
What this crate never does
- Re-implement verification. Every cryptographic check is
mid_verify::verify_mid_response— one canonical verifier. - Call MATA. No resolver, no JWKS, no revocation list, no telemetry. Compile-time dependency only, per the mID protocol's zero-backdoor design.
- Invent a session format. Cookies/tokens stay your choice.
Features
| Feature | Adds | Default |
|---|---|---|
| (none) | Traits, in-memory stores, Authenticator — pure core, no clock reads, no I/O |
✅ |
redb-store |
RedbStore: single-file embedded persistence (pure-Rust redb) |
off |
routes |
MidRp + ready-made axum endpoints (the only impure module) |
off |
License
MIT OR Apache-2.0.