API: Extension-communicatie
Ticket 1B-03 • Bron: src/routes/extension.ts (gepland) • Status: ontwerp • Risico: hoog (SSE + intent-queue veiligheid)
Kerndefinitie: Extension-communicatie tussen MAOS core en browser-extensies via drie mechanismen: (1) intent-queue voor het sequentieel verwerken van verzoeken, (2) SSE (Server-Sent Events) voor real-time updates van core naar extension, en (3) ID-verificatie om de authenticiteit van extensies te waarborgen. Vereist signed manifest per extension.
1. Architectuur
Browser Extension
│
├── 1. ID-verificatie
│ ├── Extension stuurt signed manifest
│ ├── Server verifieert Ed25519 signature
│ ├── Pubkey in allowlist?
│ └── Ja → sessie token
│
├── 2. Intent-queue (extension → core)
│ ├── POST /extension/intent
│ ├── Method beperkingen (geen onbeperkte methods)
│ ├── Queue: FIFO verwerking
│ └── Response: intent resultaat
│
├── 3. SSE kanaal (core → extension)
│ ├── GET /extension/events
│ ├── Event stream: verzoeken, goedkeuringen, status
│ ├── Extension toont UI op basis van events
│ └── Automatische reconnect bij disconnect
│
└── 4. Heartbeat
├── GET /extension/heartbeat
└── Extension checkt of core nog actief is
Intent-queue verwerking:
Extension POST → intent-queue → kernel → resultaat → SSE event → Extension UI
2. Endpoints
| Endpoint | Methode | Beschrijving | Auth |
/extension/verify | POST | Extension ID-verificatie (signed manifest) | Ed25519 sig |
/extension/intent | POST | Intent toevoegen aan queue | Session token |
/extension/events | GET | SSE kanaal voor real-time updates | Session token |
/extension/heartbeat | GET | Health check / connection keepalive | Session token |
/extension/cancel/:intentId | POST | Intent annuleren (indien pending) | Session token |
3. Signed manifest vereist
Elke extension moet een signed manifest meesturen:
{
"extensionId": "unique-string",
"name": "MAOS Browser Extension",
"version": "1.0.0",
"allowedMethods": [
"wallet:connect",
"wallet:sign",
"storage:read",
"dapp:info"
],
"pubkey": "ed25519-pubkey-base64",
"sig": "ed25519-signature-base64"
}
Verificatie-flow:
1. Canonical JSON van manifest (gesorteerde keys)
2. Ed25519 verify(manifest, sig, pubkey)
3. Pubkey in extension allowlist?
4. Ja → geef session token
5. Nee → reject + audit log
4. Intent-queue met method-beperkingen
Intent-queue regels:
│
├── 1. Method beperkingen
│ ├── Extension manifest bepaalt welke methods toegestaan zijn
│ ├── wallet:connect ✓ (als in allowedMethods)
│ ├── wallet:sign ✓ (als in allowedMethods)
│ ├── storage:delete ✗ (niet in allowedMethods)
│ └── Niet-toegestane method → 403 + audit
│
├── 2. FIFO verwerking
│ ├── Intenten worden in volgorde verwerkt
│ ├── Geen parallelle verwerking (voorkom race conditions)
│ └── Wachtrij-limiet: max 10 pending intenten per extension
│
├── 3. Time-out
│ ├── Intent verloopt na 30 seconden als niet verwerkt
│ └── Automatische cleanup van verlopen intenten
│
└── 4. Resultaat
├── Succes → SSE event met resultaat
├── Fout → SSE event met foutmelding
└── Geannuleerd → SSE event met cancel-melding
4.1 Methode-beperkingen tabel
| Method | Beschrijving | Vereist goedkeuring |
wallet:connect | Wallet koppelen aan extension | Nee (automatisch) |
wallet:disconnect | Wallet ontkoppelen | Nee |
wallet:sign | Transactie tekenen | Ja — gebruiker moet goedkeuren |
wallet:send | Transactie verzenden | Ja — gebruiker moet goedkeuren |
storage:read | Storage uitlezen | Nee (binnen capabilities) |
storage:write | Storage schrijven | Ja — bij first-use |
dapp:info | DApp informatie ophalen | Nee |
5. SSE kanaal
GET /extension/events HTTP/1.1
Accept: text/event-stream
Response:
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
Event types:
event: intent-request
data: { "intentId": "abc", "method": "wallet:sign", "params": {...} }
event: intent-approved
data: { "intentId": "abc", "result": {...} }
event: intent-rejected
data: { "intentId": "abc", "reason": "user_rejected" }
event: heartbeat
data: { "ts": 1234567890 }
Reconnect strategie:
├── Exponential backoff: 1s, 2s, 4s, 8s, max 30s
├── Max reconnect attempts: 10
└── Na 10 mislukte pogingen → sessie verlopen
6. Request / Response voorbeelden
6.1 POST /extension/verify
POST /extension/verify HTTP/1.1
Content-Type: application/json
{
"extensionId": "maos-ext-001",
"name": "MAOS Browser Extension",
"version": "1.0.0",
"allowedMethods": ["wallet:connect", "wallet:sign"],
"pubkey": "base64-encoded-ed25519-pubkey",
"sig": "base64-encoded-ed25519-signature"
}
Response (geldig):
{
"verified": true,
"sessionToken": "ext_sess_abc123...",
"expiresAt": "2025-01-15T11:00:00Z"
}
Response (ongeldig):
{
"verified": false,
"error": "Invalid signature"
}
6.2 POST /extension/intent
POST /extension/intent HTTP/1.1
Authorization: Bearer ext_sess_abc123...
Content-Type: application/json
{
"method": "wallet:sign",
"params": {
"tx": {
"to": "0x742d35Cc...",
"value": "1000000000000000000",
"chainId": 270
}
}
}
Response:
{
"intentId": "intent_xyz789",
"status": "pending",
"message": "Intent queued, awaiting user approval"
}
6.3 SSE events stream
GET /extension/events HTTP/1.1
Authorization: Bearer ext_sess_abc123...
Accept: text/event-stream
event: intent-request
data: {"intentId":"intent_xyz789","method":"wallet:sign","status":"awaiting_approval"}
event: intent-approved
data: {"intentId":"intent_xyz789","result":{"txHash":"0xabc..."}}
event: heartbeat
data: {"ts":1705312800}
6.4 Foutafhandeling
// Niet-toegestane method
POST /extension/intent { "method": "storage:delete", ... }
→ 403 { "error": "Method not allowed", "allowed": ["wallet:connect", "wallet:sign"] }
// Teveel pending intenten
POST /extension/intent (10 al pending)
→ 429 { "error": "Intent queue full", "max": 10 }
// Session verlopen
POST /extension/intent (oude token)
→ 401 { "error": "Session expired" }
7. Acceptatiecriteria
- ID-verificatie: Ed25519 signature check op extension manifest
- Intent-queue: FIFO verwerking, max 10 pending per extension
- Method-beperkingen: alleen toegestane methods worden verwerkt
- SSE kanaal: real-time events van core naar extension
- Reconnect: exponential backoff bij disconnect
- Time-out: intenten verlopen na 30 seconden
- Audit logging: ongeldige signatures + niet-toegestane methods
8. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| SSE connectie kan blokkeren bij veel events | Medium | Event batching: max 10 events per seconde. Buffer voor burst. |
| Intent-queue vol (10 max) | Medium | Client-side rate-limiting. Oude intenten auto-cancel na 30s. |
| Extension manifest forged | High | Ed25519 verificatie + pubkey allowlist. Geen uitzonderingen. |
| SSE reconnect-storm bij server herstart | Medium | Max 10 reconnect attempts. Exponential backoff met jitter. |
9. Verwijzingen
Fase 1B Nog niet geimplementeerd. Vereist: Ed25519 library, SSE infrastructure, intent-queue state management. Prioriteit: hoog (blokkeert extension-integratie).