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

EndpointMethodeActionBeschrijving
/verifyPOSTverifyNFTControleer NFT-bezit op MAOS NFT contract
/verifyPOSTverifyDIDControleer DID-koppeling + registratie
/verifyPOSTtestNetworkTest blockchain netwerkverbinding
/verifyPOSTverifyFullVolledige identiteitsverificatie (NFT + DID + netwerk)
/verifyPOSTgetOwnerHaal eigenaar van tokenId 1 op
/verifyGET—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

ConfigEnv variableDefault
NFT ContractNEXT_PUBLIC_MAOS_NFT_ADDRESS0x0000...0000
DID RegistryNEXT_PUBLIC_DID_REGISTRY_ADDRESS0x0000...0000
Chain ID—270 (MAOS chain)

6. Acceptatiecriteria

7. Risico's en aanbevelingen

RisicoImpactMitigatie
Placeholder service-functies (retourneren null/false)MediumKoppel blockchain-service uit @/lib/blockchain-service zodra beschikbaar.
Geen caching van netwerk-statusLowVoeg korte TTL-cache toe voor testNetwork (vermijd RPC-calls per verzoek).
Contract addresses default 0x0000LowCheck 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.