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

EndpointMethodeBeschrijvingAuth
/extension/verifyPOSTExtension ID-verificatie (signed manifest)Ed25519 sig
/extension/intentPOSTIntent toevoegen aan queueSession token
/extension/eventsGETSSE kanaal voor real-time updatesSession token
/extension/heartbeatGETHealth check / connection keepaliveSession token
/extension/cancel/:intentIdPOSTIntent 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

MethodBeschrijvingVereist goedkeuring
wallet:connectWallet koppelen aan extensionNee (automatisch)
wallet:disconnectWallet ontkoppelenNee
wallet:signTransactie tekenenJa — gebruiker moet goedkeuren
wallet:sendTransactie verzendenJa — gebruiker moet goedkeuren
storage:readStorage uitlezenNee (binnen capabilities)
storage:writeStorage schrijvenJa — bij first-use
dapp:infoDApp informatie ophalenNee

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

8. Risico's en aanbevelingen

RisicoImpactMitigatie
SSE connectie kan blokkeren bij veel eventsMediumEvent batching: max 10 events per seconde. Buffer voor burst.
Intent-queue vol (10 max)MediumClient-side rate-limiting. Oude intenten auto-cancel na 30s.
Extension manifest forgedHighEd25519 verificatie + pubkey allowlist. Geen uitzonderingen.
SSE reconnect-storm bij server herstartMediumMax 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).