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
| Endpoint | Methode | Beschrijving | Status |
/help/index | GET | DApp help-index (scanDAppsWithHelp) | Actief |
/help/list | GET | Alle topics (flat lijst) | Deprecated |
/help/search?q= | GET | Zoek door topics | Deprecated |
/help/content/:dappId/:locale/:topicPath | GET | Markdown content per topic + locale | Actief |
/help/:dappId/:topicId | GET | Topic HTML (deprecated fallback) | Deprecated |
/help/:dappId/assets/:assetPath | GET | Static 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
| Route | Reden deprecated | Alternatief |
/help/list | Help DApp haalt nu help.json direct op | Client-side fetch van help.json |
/help/search?q= | Help DApp doet nu client-side search | Client-side search in DApp |
/help/:dappId/:topicId | Help 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
- Elke endpoint retourneert identieke JSON als de Next.js bronimplementatie
- Search ondersteunt query parameter
q=
- Content-route retourneert Markdown + locale + topicId
- Foutafhandeling: 400 bij ontbrekende params, 404 bij niet-gevonden
- Rate-limiting van
proxy.ts wordt toegepast (exempt voor help)
- Deprecated routes loggen waarschuwing en werken nog
- Static assets: path-traversal check is placeholder (todo: koppel path-validation.ts)
8. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| Placeholder scanners (leeg resultaat) | Medium | Koppel help-scanner en DAppHelpRegistry uit @/help/* zodra beschikbaar. |
| Path-traversal in assets niet geimplementeerd | High | Implementeer resolveSafePath uit path-validation.ts voor productie. |
| Geen caching van help-content | Low | Voeg 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.