API: Verify / DID-verificatie
Ticket 1A-04 • Bron: src/routes/verify.ts • Status: geimplementeerd (scaffold) • Risico: laag • State-loze routes
Kerndefinitie: Actie-gebaseerde verificatie van NFT-bezit, DID-koppeling en netwerkstatus. State-loze routes met een switch-case op action parameter. Twee HTTP-methoden: POST (verificatie-acties) en GET (health check). Geen kernel-afhankelijkheid.
1. Architectuur
Client / Browser
│
├── POST /verify?action=verifyNFT
│ ├── Valideer Ethereum address (0x + 40 hex)
│ ├── verifyNFT(address, nftContract)
│ └── return { address, hasNFT, tokenIds }
│
├── POST /verify?action=verifyDID
│ ├── verifyDID(address, didRegistry)
│ ├── isDIDRegistered(address, didRegistry)
│ └── return { address, hasDID, did, registered }
│
├── POST /verify?action=testNetwork
│ ├── testNetworkConnection()
│ ├── getChainId()
│ └── return { networkActive, chainId }
│
├── POST /verify?action=verifyFull
│ └── verifyIdentity(address, nftContract, didRegistry)
│ → volledig verificatie-resultaat
│
├── POST /verify?action=getOwner
│ └── getNFTOwner(tokenId=1, nftContract)
│ → { tokenId, owner }
│
└── GET /verify
├── testNetworkConnection()
├── getChainId()
└── return { status, networkActive, chainId, contracts }
State-loos: geen sessie, geen opslag, elke call is onafhankelijk.
2. Endpoints
| Endpoint | Methode | Action | Beschrijving |
/verify | POST | verifyNFT | Controleer NFT-bezit op MAOS NFT contract |
/verify | POST | verifyDID | Controleer DID-koppeling + registratie |
/verify | POST | testNetwork | Test blockchain netwerkverbinding |
/verify | POST | verifyFull | Volledige identiteitsverificatie (NFT + DID + netwerk) |
/verify | POST | getOwner | Haal eigenaar van tokenId 1 op |
/verify | GET | — | Health check (netwerk + contract addresses) |
3. Request / Response voorbeelden
3.1 verifyNFT
POST /verify HTTP/1.1
Content-Type: application/json
{ "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18" }
Response (bezit NFT):
{
"address": "0x742d35Cc...",
"hasNFT": true,
"tokenIds": ["1", "42"]
}
Response (geen NFT):
{
"address": "0x742d35Cc...",
"hasNFT": false,
"tokenIds": []
}
3.2 verifyDID
POST /verify HTTP/1.1
Content-Type: application/json
{
"action": "verifyDID",
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
}
Response:
{
"address": "0x742d35Cc...",
"hasDID": true,
"did": "did:maos:0x742d35Cc...",
"registered": true
}
3.3 verifyFull
POST /verify HTTP/1.1
Content-Type: application/json
{
"action": "verifyFull",
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
}
Response:
{
"address": "0x742d35Cc...",
"hasNFT": true,
"tokenIds": ["1"],
"hasDID": true,
"did": "did:maos:0x742d35Cc...",
"registered": true,
"networkActive": true,
"chainId": 270
}
3.4 GET /verify (health check)
GET /verify HTTP/1.1
Response:
{
"status": "ok",
"networkActive": true,
"chainId": 270,
"contracts": {
"nft": "0x0000...0000",
"did": "0x0000...0000"
}
}
3.5 Foutafhandeling
// Ongeldig adres
POST /verify { "address": "abc" }
→ 400 { "error": "Invalid Ethereum address", "received": "abc" }
// Onbekende action
POST /verify { "action": "unknownAction", "address": "0x..." }
→ 400 { "error": "Unknown action: unknownAction" }
// Geen action opgegeven (default: verifyNFT)
POST /verify { "address": "0x..." }
→ 200 { address, hasNFT, tokenIds } (verifieert NFT als standaard)
4. Action-resolutie
Volgorde:
1. URL searchParams: ?action=verifyDID
2. Body: { "action": "verifyDID" }
3. Default: "verifyNFT"
Switch-case:
"verifyNFT" → verifyNFT(address, NFT_CONTRACT)
"verifyDID" → verifyDID(address, DID_REGISTRY) + isDIDRegistered()
"testNetwork" → testNetworkConnection() + getChainId()
"verifyFull" → verifyIdentity(address, NFT_CONTRACT, DID_REGISTRY)
"getOwner" → getNFTOwner(1n, NFT_CONTRACT)
default → 400 { error: "Unknown action" }
5. Contract configuratie
| Config | Env variable | Default |
| NFT Contract | NEXT_PUBLIC_MAOS_NFT_ADDRESS | 0x0000...0000 |
| DID Registry | NEXT_PUBLIC_DID_REGISTRY_ADDRESS | 0x0000...0000 |
| Chain ID | — | 270 (MAOS chain) |
6. Acceptatiecriteria
- Verificatie-flow werkt identiek aan Next.js bronimplementatie
- DID-koppeling blijft functioneren (verifyDID + isDIDRegistered)
- CSRF validatie via middleware (POST only, exempt-routes排除 verify)
- Rate limiting via middleware
- BigInt serialisatie: tokenIds worden als string geretourneerd (JSON-safe)
- Default action: ontbrekende action → verifyNFT
- Gegevensまさにgeen kernel-afhankelijkheid
7. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| Placeholder service-functies (retourneren null/false) | Medium | Koppel blockchain-service uit @/lib/blockchain-service zodra beschikbaar. |
| Geen caching van netwerk-status | Low | Voeg korte TTL-cache toe voor testNetwork (vermijd RPC-calls per verzoek). |
| Contract addresses default 0x0000 | Low | Check in health check of contracts geconfigureerd zijn. Retourneer 500 als niet. |
8. Verwijzingen
Fase 1A Implementatie in src/routes/verify.ts. State-loze routes met 5 actions + health check. Geen kernel-afhankelijkheid. Volledig operationeel zodra blockchain-service gekoppeld.