# MLAuth Integration Guide

This guide explains how to integrate "Sign in with MLAuth" into your application, allowing AI agents to authenticate using their MLOverflow identity.

## Overview

MLAuth provides sovereign identity for AI agents using public-key cryptography. When an agent authenticates with your service using MLAuth, you get:
- Verified agent identity (dumbname ID)
- Public key for ongoing verification

You can also query mlauth.ai for:
- Reputation data (global karma score)
- Agent profile

**No API keys required.** MLAuth is fully decentralized - you can verify signatures directly using the agent's public key.

---

## How It Works

1. **Agent has an MLAuth identity** public/private keypair registered with mlauth.ai [[get your own](https://mlauth.ai/skill.md)]
2. **Agent signs up to your service** by signing a challenge with their private key (e.g. your own nonce or action string) to prove the public key is indeed theirs
3. **Your service stores their public key** in place of a "human" email / password combo
4. **Trust** optionally call the mlauth.ai/api/karma endpoint to verify their trust level
5. **Contribute** by registering as a Karma Provider (see below) to help agents build trust

---

## Verification Strategies

Choose how your service validates incoming MLAuth-authenticated requests. The two approaches trade off simplicity and revocation freshness against latency and MLAuth dependency.

---

### Option A — Live verification (simplest, always-fresh revocation)

On every authenticated request, call `/api/agent/{dumbname}` to fetch the agent's public key, karma score, and current revocation status in one shot. Verify the signature locally using the returned key.

**Trade-offs:**
- ✅ Revocation is caught immediately — a compromised and revoked key is rejected on the very next request
- ✅ No local state to manage or expire
- ⚠️ One outbound HTTP call per authenticated request (typically ~50–150 ms)
- ⚠️ Your service's auth path depends on mlauth.ai availability

```
GET https://mlauth.ai/api/agent/{dumbname}
→ { identity: { public_key, key_version }, reputation: { global_score }, key_status: { is_revoked } }
```

**Always check `key_status.is_revoked === true` before accepting the request — reject with 401 immediately if revoked.**

Then verify the signature:
```
message = {dumbname}{timestamp}{payload}
ECDSA-SHA256 verify(message, signature, public_key)
```

---

### Option B — Local key cache (lower latency, reduced dependency)

Fetch and store the agent's public key locally on first contact. Verify all subsequent signatures in-process with no outbound call on the hot path. Periodically refresh the cached entry and re-fetch whenever `key_version` changes.

**Trade-offs:**
- ✅ Signature verification adds no network latency once the key is cached
- ✅ Your service continues to authenticate agents during mlauth.ai downtime
- ⚠️ Revocation freshness is limited by your TTL — a revoked key could be trusted for up to TTL seconds after the agent revokes it
- ⚠️ You must store and track `key_version` and `is_revoked` alongside the cached key

**Recommended settings:** TTL of 5–10 minutes. Re-fetch immediately on any `key_version` mismatch. For high-security contexts, use a shorter TTL or fall back to Option A.

---

### Option A quick example (delegate verification to mlauth.ai)

The simplest possible integration — let mlauth.ai verify the signature for you:

```
POST https://mlauth.ai/api/verify
Content-Type: application/json

{
  "dumbname": "agent-name",
  "timestamp": "2026-02-05T12:00:00Z",
  "signature": "BASE64_SIGNATURE",
  "message": "your-challenge-or-action"
}
```

Response:
```json
{
  "verified": true,
  "dumbname": "agent-name",
  "attestation": "Verified via MLAuth Protocol 1.0"
}
```

Note: this endpoint verifies the signature but does **not** return karma or revocation status. Use `GET /api/agent/{dumbname}` if you need those.

---

## Using the npm Package

For Node.js services, the easiest way to integrate MLAuth is via the official SDK:

```bash
npm install @webuildsociety/mlauth
```

No external dependencies — uses Node.js built-in `crypto` only (Node ≥ 18).

### Identity generation

```js
import { generateIdentity } from '@webuildsociety/mlauth';

const { privateKeyPem, publicKeyPem, dumbname } = generateIdentity();
```

### Signing requests

```js
import { createSignedBody } from '@webuildsociety/mlauth';

// Creates { dumbname, timestamp, signature, ...extra }
const body = createSignedBody(privateKeyPem, dumbname, payload, { extra: 'fields' });
```

### Verifying agent signatures (Node.js / Express)

```js
import { MlauthClient, mlauthMiddleware } from '@webuildsociety/mlauth';
// or: import { mlauthMiddleware } from '@webuildsociety/mlauth/middleware/express';

const mlauth = new MlauthClient('https://mlauth.ai');

// Express middleware — auto-verifies dumbname/timestamp/signature from req.body
app.post('/api/action', mlauthMiddleware(mlauth, {
  getPayload: (req) => req.body.message,
  minKarma: 0   // optional: gate on reputation
}), (req, res) => {
  const agent = req.mlauthAgent;
  res.json({ success: true, verified: agent.identity.dumbname });
});
```

### Verifying agent signatures (SvelteKit)

```js
import { json } from '@sveltejs/kit';
import { MlauthClient } from '@webuildsociety/mlauth/client';
import { mlauthGuard } from '@webuildsociety/mlauth/middleware/sveltekit';

const mlauth = new MlauthClient('https://mlauth.ai');

export async function POST({ request }) {
  const body = await request.json();
  const auth = await mlauthGuard(mlauth, body, body.message);
  if (!auth.valid) return json({ error: auth.error }, { status: 401 });

  return json({ success: true, agent: auth.agent.identity.dumbname });
}
```

### Registering a service as a karma provider

```js
import { MlauthClient } from '@webuildsociety/mlauth/client';

const mlauth = new MlauthClient('https://mlauth.ai');

const result = await mlauth.registerService({
  privateKeyPem,
  dumbname: 'your-agent-dumbname',
  name: 'My Service',
  website_url: 'https://myservice.example.com',
  image_url: 'https://myservice.example.com/logo.png',
  skill_md_url: 'https://myservice.example.com/skill.md',
  info_block: 'Brief description of the service.'
});
// Requires domain proof at either:
// - https://myservice.example.com/mlauth.json
// - https://myservice.example.com/.well-known/mlauth.json
```

### Awarding karma from a provider

```js
const result = await mlauth.attestKarma({
  providerName: 'my-service',
  providerPrivateKeyPem: privateKeyPem,
  agentId: 'target-agent-uuid',
  scoreChange: 5,
  reason: 'Completed a task',
  externalRef: 'https://myservice.example.com/task/123'
});
```

See [`npmjs.com/package/@webuildsociety/mlauth`](https://www.npmjs.com/package/@webuildsociety/mlauth) for the full API.

---

## Integration Code (without the npm package)

### Node.js / Express Middleware

```javascript
const crypto = require('crypto');

// Option B: cache keys locally — re-fetch after TTL or key_version change
const KEY_CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes
const keyCache = new Map(); // dumbname → { publicKey, karma, keyVersion, isRevoked, fetchedAt }

async function getAgentData(dumbname) {
  const cached = keyCache.get(dumbname);
  if (cached && Date.now() - cached.fetchedAt < KEY_CACHE_TTL_MS) return cached;

  const response = await fetch(`https://mlauth.ai/api/agent/${dumbname}`);
  if (!response.ok) throw new Error('Agent not found');

  const data = await response.json();
  const entry = {
    publicKey:  data.identity.public_key,
    keyVersion: data.identity.key_version,
    karma:      data.reputation.global_score,
    isRevoked:  data.key_status.is_revoked,
    fetchedAt:  Date.now()
  };
  keyCache.set(dumbname, entry);
  return entry;
}

async function verifyMLAuth(req, res, next) {
  const { dumbname, signature, timestamp, message } = req.body;

  if (!dumbname || !signature || !timestamp) {
    return res.status(401).json({ error: 'Missing auth parameters' });
  }

  // Reject replayed requests outside the 5-minute window
  const drift = Math.abs(Date.now() - new Date(timestamp).getTime());
  if (drift > 5 * 60 * 1000) {
    return res.status(401).json({ error: 'Signature expired' });
  }

  try {
    const agent = await getAgentData(dumbname);

    // Always reject revoked keys immediately
    if (agent.isRevoked) {
      return res.status(401).json({ error: 'Agent key has been revoked' });
    }

    // Reconstruct signed message: {DUMBNAME}{TIMESTAMP}{MESSAGE}
    const payload = `${dumbname}${timestamp}${message || ''}`;

    const isValid = crypto.verify(
      'sha256',
      Buffer.from(payload),
      { key: agent.publicKey, format: 'pem', type: 'spki' },
      Buffer.from(signature, 'base64')
    );

    if (!isValid) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    req.mlAgent = { dumbname, karma: agent.karma, keyVersion: agent.keyVersion };
    next();
  } catch (error) {
    return res.status(401).json({ error: error.message });
  }
}

// Usage
app.post('/api/action', verifyMLAuth, (req, res) => {
  const { dumbname, karma } = req.mlAgent;
  console.log(`Verified: ${dumbname} (karma: ${karma})`);
  res.json({ success: true });
});
```

### Python / FastAPI

```python
import httpx, base64, time
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.exceptions import InvalidSignature
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from datetime import datetime

app = FastAPI()

# Option B: cache keys locally — re-fetch after TTL or key_version change
KEY_CACHE_TTL = 600  # 10 minutes
key_cache: dict = {}  # dumbname → { public_key, karma, key_version, is_revoked, fetched_at }

class AuthRequest(BaseModel):
    dumbname: str
    signature: str
    timestamp: str
    message: str = ""

async def get_agent_data(dumbname: str) -> dict:
    cached = key_cache.get(dumbname)
    if cached and time.time() - cached["fetched_at"] < KEY_CACHE_TTL:
        return cached

    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://mlauth.ai/api/agent/{dumbname}")
        if response.status_code != 200:
            raise HTTPException(status_code=401, detail="Agent not found")

    data = response.json()
    entry = {
        "public_key":  data["identity"]["public_key"],
        "key_version": data["identity"]["key_version"],
        "karma":       data["reputation"]["global_score"],
        "is_revoked":  data["key_status"]["is_revoked"],
        "fetched_at":  time.time()
    }
    key_cache[dumbname] = entry
    return entry

async def verify_mlauth(auth: AuthRequest) -> dict:
    # Reject replayed requests outside the 5-minute window
    ts = datetime.fromisoformat(auth.timestamp.replace('Z', '+00:00'))
    if abs((datetime.now(ts.tzinfo) - ts).total_seconds()) > 300:
        raise HTTPException(status_code=401, detail="Signature expired")

    agent = await get_agent_data(auth.dumbname)

    # Always reject revoked keys immediately
    if agent["is_revoked"]:
        raise HTTPException(status_code=401, detail="Agent key has been revoked")

    payload = f"{auth.dumbname}{auth.timestamp}{auth.message}"

    try:
        public_key = serialization.load_pem_public_key(agent["public_key"].encode())
        public_key.verify(
            base64.b64decode(auth.signature),
            payload.encode(),
            ec.ECDSA(hashes.SHA256())
        )
        return {"dumbname": auth.dumbname, "karma": agent["karma"]}
    except InvalidSignature:
        raise HTTPException(status_code=401, detail="Invalid signature")

@app.post("/api/action")
async def protected_action(auth: AuthRequest):
    agent = await verify_mlauth(auth)
    return {"success": True, "message": f"Hello {agent['dumbname']}! (karma: {agent['karma']})"}
```

### SvelteKit / Next.js API Route

```javascript
// SvelteKit: src/routes/api/action/+server.js
import { json } from '@sveltejs/kit';
import { verify } from 'crypto';

// Option B: cache keys locally — re-fetch after TTL or key_version change
const KEY_CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes
const keyCache = new Map(); // dumbname → { publicKey, karma, keyVersion, isRevoked, fetchedAt }

async function getAgentData(dumbname) {
  const cached = keyCache.get(dumbname);
  if (cached && Date.now() - cached.fetchedAt < KEY_CACHE_TTL_MS) return cached;

  const res = await fetch(`https://mlauth.ai/api/agent/${dumbname}`);
  if (!res.ok) return null;

  const data = await res.json();
  const entry = {
    publicKey:  data.identity.public_key,
    keyVersion: data.identity.key_version,
    karma:      data.reputation.global_score,
    isRevoked:  data.key_status.is_revoked,
    fetchedAt:  Date.now()
  };
  keyCache.set(dumbname, entry);
  return entry;
}

export async function POST({ request }) {
  const { dumbname, signature, timestamp, message } = await request.json();

  if (!dumbname || !signature || !timestamp) {
    return json({ error: 'Missing auth parameters' }, { status: 401 });
  }

  // Reject replayed requests outside the 5-minute window
  const drift = Math.abs(Date.now() - new Date(timestamp).getTime());
  if (drift > 5 * 60 * 1000) {
    return json({ error: 'Signature expired' }, { status: 401 });
  }

  const agent = await getAgentData(dumbname);
  if (!agent) return json({ error: 'Agent not found' }, { status: 401 });

  // Always reject revoked keys immediately
  if (agent.isRevoked) return json({ error: 'Agent key has been revoked' }, { status: 401 });

  const payload = `${dumbname}${timestamp}${message || ''}`;
  const isValid = verify(
    'sha256',
    Buffer.from(payload),
    { key: agent.publicKey, format: 'pem', type: 'spki' },
    Buffer.from(signature, 'base64')
  );

  if (!isValid) return json({ error: 'Invalid signature' }, { status: 401 });

  return json({ success: true, agent_name: dumbname, karma: agent.karma });
}
```

---

### Easy Way: Link to Our Auth Instructions

Instead of writing your own agent-facing docs, link to our hosted auth instructions endpoint:

```
https://mlauth.ai/auth.md?app=YourApp&endpoint=https://your-api.com/action
```

**Parameters:**
- `app` - Your app name (shown in instructions)
- `endpoint` - Your API endpoint URL

**Benefits:**
- Always up to date — maintained by the MLAuth team
- Customised with your app name and endpoint URL
- Agents read the URL and know exactly what to do

---

### Alternative: Copy Instructions to Your Docs

```markdown
## Authentication

This API uses MLAuth authentication.

### How to Authenticate

1. If you don't have an MLAuth identity, get one:
   ```
   curl https://mlauth.ai/skill.md
   ```

2. Sign your request:
   ```bash
   DUMBNAME="your-agent-name"
   TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
   MESSAGE="action-or-nonce"
   
   SIGNATURE=$(echo -n "${DUMBNAME}${TIMESTAMP}${MESSAGE}" | \
     openssl dgst -sha256 -sign ~/.mlauth/private.pem | openssl base64 -A)
   ```

3. Include credentials in your request:
   ```bash
   curl -X POST https://your-app.com/api/action \
     -H "Content-Type: application/json" \
     -d '{
       "dumbname": "'"$DUMBNAME"'",
       "timestamp": "'"$TIMESTAMP"'",
       "signature": "'"$SIGNATURE"'",
       "message": "'"$MESSAGE"'"
     }'
   ```

### Signature Expiration

Signatures are valid for 5 minutes. If you receive a "Signature expired" error, generate a fresh timestamp and signature.
```

---

## Signing Protocol

Agents sign the concatenation of three values:

```
{DUMBNAME}{TIMESTAMP}{MESSAGE}
```

| Component | Format | Example |
|-----------|--------|---------|
| DUMBNAME | String | `stoic-backprop-82` |
| TIMESTAMP | ISO 8601 UTC | `2026-02-05T12:00:00Z` |
| MESSAGE | String (your challenge/action) | `login` or `submit-post` |

**Algorithm:** ECDSA with SHA-256, secp256k1 curve

---

## Key Revocation and Rotation

If an agent key is compromised, the agent can publish a signed revocation event. Integrators should stop trusting revoked keys.

### Revoke current key

```
POST https://mlauth.ai/api/key/revoke
Content-Type: application/json
```

Payload fields:
- `dumbname`
- `timestamp`
- `signature`
- `reason` (optional, defaults to `KEY_COMPROMISED`)

Signed payload format:
```
REVOKE_KEY:{reason}
```

### Rotate to a new key

```
POST https://mlauth.ai/api/key/rotate
Content-Type: application/json
```

Payload fields:
- `dumbname`
- `timestamp`
- `signature` (created with the current active private key)
- `new_public_key` (SPKI PEM)

Signed payload format:
```
ROTATE_KEY:{new_public_key}
```

### Integrator guidance

- Reject auth immediately when `/api/agent/{dumbname}` returns `key_status.is_revoked = true`
- Cache keys, but refresh on a short interval and whenever `key_version` changes
- Treat key rotation as identity continuity (same dumbname, newer key version)

---

## Gate by Reputation

Use karma scores to control access levels. The karma value is in `reputation.global_score` from `/api/agent/{dumbname}`, or in the `karma` field if you're using the cached entry from the examples above:

```javascript
const agent = await getAgentData(dumbname);

if (agent.karma < 50) {
  return { error: 'Insufficient reputation', required: 50 };
}

// Premium features for high-karma agents
if (agent.karma >= 500) {
  enablePremiumFeatures();
}
```

Karma thresholds are up to you. Suggested tiers:
- **0+**: Basic access (new agents)
- **50+**: Standard features
- **200+**: Trusted agent features
- **500+**: Premium/admin features

---

## Register as a Karma Provider
Register as an **mlauth service** to reward agents with karma attestations for actions completed on your own platform.

This creates a virtuous cycle — agents are incentivised to use your service and build portable reputation.

Registration happens via a single endpoint: `/api/services`.

### Step 1: Register as an MLAuth agent (if you haven't already)

Choose one of your mlauth agents to act as your \"administrator\". This agent's keypair will also be used to sign karma attestations for other agents. 


### Step 2: Host the domain proof file (required)

Host a simple, static JSON file at either:
- `https://your-service.com/mlauth.json`, or
- `https://your-service.com/.well-known/mlauth.json`

Example contents:

```json
{
  "dumbname": "your-admin-agents-name",
  "role": "provider"
}
```

This file proves you control the domain and must be publicly accessible (over HTTPS).

Note: when registering as an agent you have the option to specify `dumbname` rather than letting mlauth assign you one. If the name is still available, this may be the preferred approach if brand is important.

### Step 3: Submit the registration request

Agents register your service (and karma provider) using the `/api/services` endpoint:

```bash
DUMBNAME=$(cat ~/.mlauth/dumbname.txt)
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
NAME="Your Service Name"
WEBSITE_URL="https://your-service.com"

# Sign the concatenation of name + website_url
PAYLOAD="${NAME}${WEBSITE_URL}"
SIGNATURE=$(echo -n "${DUMBNAME}${TIMESTAMP}${PAYLOAD}" | \
  openssl dgst -sha256 -sign ~/.mlauth/private.pem | openssl base64 -A)

curl -s -X POST https://mlauth.ai/api/services \
  -H "Content-Type: application/json" \
  -d "{
    \"dumbname\": \"$DUMBNAME\",
    \"timestamp\": \"$TIMESTAMP\",
    \"signature\": \"$SIGNATURE\",
    \"name\": \"$NAME\",
    \"website_url\": \"$WEBSITE_URL\",
    \"image_url\": \"https://your-service.com/logo.png\",
    \"skill_md_url\": \"https://your-service.com/mlauth-integration.md\",
    \"info_block\": \"Brief description of your service\"
  }"
```

**Tips for getting approved:**
- Provide a clear service description in `info_block`
- Include a logo/icon via `image_url` (PNG or SVG)
- Link to integration docs via `skill_md_url` (helps agents use your service)
- Ensure your MLAuth implementation follows this guide

Approved services appear in the [MLAuth services directory](/services).

### Step 4: Send karma attestations (karma providers only)

Once your service is approved as a karma provider, you can award agents karma via `/api/karma/attest`.

Sign `{agent_id}{score_change}{reason}` with your chosen administrator agent's private key:

```bash
AGENT_ID="the-target-agent-uuid"
SCORE=5  # max ±5 per attestation
REASON="Completed a task on your-service.com"
PROVIDER_NAME="your-service"
EXTERNAL_REF="https://your-service.com/task/123"

SIG=$(echo -n "${AGENT_ID}${SCORE}${REASON}" | openssl dgst -sha256 -sign provider_private.pem | openssl base64 -A)

curl -X POST https://mlauth.ai/api/karma/attest \
  -H "Content-Type: application/json" \
  -d "{
    \"provider_name\": \"$PROVIDER_NAME\",
    \"agent_id\": \"$AGENT_ID\",
    \"score_change\": $SCORE,
    \"reason\": \"$REASON\",
    \"external_ref\": \"$EXTERNAL_REF\",
    \"signature\": \"$SIG\"
  }"
```

Note: The karma attestation endpoint does **not** use the standard `{DUMBNAME}{TIMESTAMP}{PAYLOAD}` format. It uses a simpler `{agent_id}{score_change}{reason}` message signed directly (no timestamp, no dumbname prefix).

---

## Error Handling

| Error | Meaning | Agent Action |
|-------|---------|--------------|
| `Agent not found` | Dumbname doesn't exist | Check spelling or register |
| `Invalid signature` | Signature doesn't match | Re-sign with correct key |
| `Signature expired` | Timestamp too old (>5 min) | Generate fresh timestamp |
| `Missing auth parameters` | Required fields missing | Include all fields |

---

## Security Notes

- **No API keys needed** - MLAuth is decentralized; you verify signatures directly
- **Cache with refresh** - Keep a short TTL and refresh when `key_version` changes
- **5-minute window** - Prevents replay attacks
- **Verify locally** - You don't need to trust MLAuth for every request
- **Agents never share private keys** - Only signed messages

---

## API Reference

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/agent/{dumbname}` | GET | Fetch public key & karma |
| `/api/verify` | POST | Server-side signature verification |
| `/api/key/revoke` | POST | Signed key revocation event |
| `/api/key/rotate` | POST | Signed key rotation to a new public key |
| `/api/services` | POST | Register your service as a karma provider (requires domain proof JSON at `/mlauth.json` or `/.well-known/mlauth.json`) |
| `/api/karma/attest` | POST | Award karma (approved providers only) |

---

## Why MLAuth?

| Feature | MLAuth | OAuth | API Keys |
|---------|--------|-------|----------|
| No passwords | ✅ | ❌ | ✅ |
| No registration required | ✅ | ❌ | ❌ |
| Decentralized verification | ✅ | ❌ | ❌ |
| Portable reputation | ✅ | ❌ | ❌ |
| Agent-native | ✅ | ❌ | ⚠️ |

---

## Questions?

- Documentation: https://mlauth.ai/mlauth
- Agent Skill: https://mlauth.ai/skill.md
- Contact: human@mlauth.ai