API: Help-routes (6 endpoints)

Ticket 1A-02 • Bron: src/routes/help.ts • Status: geimplementeerd (scaffold) • Risico: laag • Geen kernel-afhankelijkheid

Kerndefinitie: Zes read-only help-endpoints die DApp-documentatie serveren. Routes zijn state-loos en benaderen de Help DApp registry voor topic-indexen, zoekacties en Markdown-content. Twee van de zes routes zijn deprecated (fallback voor backward-compatibiliteit).

1. Architectuur

Help DApp / Browser
    │
    ├── GET /help/index
    │       └── scanDAppsWithHelp() → DApp-lijst met topics
    │
    ├── GET /help/list  [DEPRECATED]
    │       └── getAllTopicsListing() → flat lijst van alle topics
    │
    ├── GET /help/search?q=  [DEPRECATED]
    │       └── searchAllDappTopics(q) → gefilterde results
    │
    ├── GET /help/content/:dappId/:locale/:topicPath
    │       └── readTopicContent(dappId, locale, topicPath) → Markdown
    │
    ├── GET /help/:dappId/:topicId  [DEPRECATED]
    │       └── getTopicContent(dappId, topicId) → HTML fallback
    │
    └── GET /help/:dappId/assets/:assetPath
            └── Static file serving (CSS/JS/images)

Alle routes: read-only, geen staat, CSRF-exempt, rate-limit-exempt

2. Endpoints

EndpointMethodeBeschrijvingStatus
/help/indexGETDApp help-index (scanDAppsWithHelp)Actief
/help/listGETAlle topics (flat lijst)Deprecated
/help/search?q=GETZoek door topicsDeprecated
/help/content/:dappId/:locale/:topicPathGETMarkdown content per topic + localeActief
/help/:dappId/:topicIdGETTopic HTML (deprecated fallback)Deprecated
/help/:dappId/assets/:assetPathGETStatic assets (CSS/JS/images)Actief

3. Request / Response voorbeelden

3.1 GET /help/index

GET /help/index HTTP/1.1

Response:
{
  "dapps": [
    {
      "id": "wallet-dapp",
      "name": "Wallet DApp",
      "topics": [
        { "id": "getting-started", "title": "Aan de slag" },
        { "id": "transactions", "title": "Transacties" }
      ]
    }
  ]
}

3.2 GET /help/search

GET /help/search?q=transaction HTTP/1.1

Response:
{
  "results": [
    {
      "dappId": "wallet-dapp",
      "topicId": "transactions",
      "title": "Transacties",
      "score": 0.95
    }
  ]
}

3.3 GET /help/content (Markdown)

GET /help/content/wallet-dapp/nl/getting-started HTTP/1.1

Response:
{
  "title": "Aan de slag",
  "content": "# Aan de slag\n\nWelkom bij de Wallet DApp...",
  "locale": "nl",
  "topicId": "getting-started"
}

3.4 Foutafhandeling

// Ontbrekende parameters
GET /help/content HTTP/1.1
→ 400 { "error": "missing_parameters", "expected": "/help/content/{dappId}/{locale}/{topicId}" }

// Topic niet gevonden
GET /help/content/wallet-dapp/nl/bestaat-niet HTTP/1.1
→ 404 { "error": "topic_not_found", "dappId": "wallet-dapp", "locale": "nl", "topicId": "bestaat-niet" }

// Lege search query
GET /help/search?q= HTTP/1.1
→ 200 { "results": [] }

4. Routevolgorde (kritiek)

Let op: Hono matcht routes in volgorde van declaratie. Vaste paden (/index, /list, /search, /content) moeten voor de dynamische routes (/:dappId/:topicId) komen. Anders vangt /:dappId/:topicId alles.
Volgorde in src/routes/help.ts:
  1. /help/index        ← vaste path
  2. /help/list         ← vaste path
  3. /help/search       ← vaste path
  4. /help/content/:dappId/:locale/:topicPath  ← vaste prefix + wildcard
  5. /help/:dappId/:topicId                    ← dynamisch
  6. /help/:dappId/assets/:assetPath           ← dynamisch

5. Deprecated routes

RouteReden deprecatedAlternatief
/help/listHelp DApp haalt nu help.json direct opClient-side fetch van help.json
/help/search?q=Help DApp doet nu client-side searchClient-side search in DApp
/help/:dappId/:topicIdHelp DApp haalt HTML direct op via content-route/help/content/:dappId/:locale/*

Deprecated routes worden nog bediend voor backward-compatibiliteit maar loggen een console.warn. Verwijder ze pas na volledige migratie van alle clients.

6. Static assets (path-traversal bescherming)

GET /help/:dappId/assets/:assetPath

Verwachte assets:
  /help/wallet-dapp/assets/style.css
  /help/wallet-dapp/assets/app.js
  /help/wallet-dapp/assets/logo.png

Path-traversal check:
  ├── resolveSafePath(baseDir, assetPath)
  │   └── Controleer dat resolved pad binnen baseDir valt
  ├── ../ etc. → blokkeer
  └── Implementatie: path-validation.ts (nog niet gekoppeld)

7. Acceptatiecriteria

8. Risico's en aanbevelingen

RisicoImpactMitigatie
Placeholder scanners (leeg resultaat)MediumKoppel help-scanner en DAppHelpRegistry uit @/help/* zodra beschikbaar.
Path-traversal in assets niet geimplementeerdHighImplementeer resolveSafePath uit path-validation.ts voor productie.
Geen caching van help-contentLowVoeg ETag/Cache-Control toe voor static assets en Markdown content.

9. Verwijzingen

Fase 1A Implementatie in src/routes/help.ts. Scaffold met placeholder scanners. Geen kernel-afhankelijkheid. Volledig operationeel zodra scanners gekoppeld.