Waardepapieren Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require common-gateway/waardepapieren-bundle
   

   Add the bundle to config/bundles.php:

   CommonGateway\WaardepapierenBundle\CommonGatewayWaardepapierenBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference --env=prod | grep waardepapieren
   

   Override settings in config/packages/common_gateway_waardepapieren.yaml:

   waardepapieren:
       issuer: "https://your-gov-domain.nl"
       storage: "%kernel.project_dir%/var/waardepapieren"
       jwt_secret: "%env(WAARDEPAPIEREN_JWT_SECRET)%"
   

3. First Use Case Generate a Proof of Residency credential (e.g., BasisregistratiePersonen extract):

   use CommonGateway\WaardepapierenBundle\Service\WaardepapierGenerator;
   
   $generator = $this->container->get(WaardepapierGenerator::class);
   $credential = $generator->generate(
       subject: 'urn:uuid:123e4567-e89b-12d3-a456-426614174000',
       type: 'ProofOfResidency',
       claims: [
           'bsn' => '123456789',
           'address' => 'Main St 123, 2000 AA Haarlem',
           'valid_from' => '2024-01-01',
           'valid_until' => '2024-12-31'
       ]
   );
   

Implementation Patterns

Core Workflows

1. Issuing Credentials

   • Dynamic Generation: Use WaardepapierGenerator to create credentials on-the-fly (e.g., after user authentication).

     $generator->generate($subject, $type, $claims, $options);
     

   • Batch Processing: For bulk issuance (e.g., retroactive credentials), extend BatchCredentialIssuer:

     $batchIssuer = new BatchCredentialIssuer($generator);
     $batchIssuer->issueForUsers($userIds, 'ProofOfResidency');
     

2. Verification

   • Client-Side Validation: Provide the generated JWT to frontend via API:

     return $this->json(['credential' => $credential->toJWT()]);
     

   • Server-Side Verification: Use WaardepapierVerifier in controllers:

     $verifier = $this->container->get(WaardepapierVerifier::class);
     $isValid = $verifier->verify($jwtString, $expectedIssuer);
     

3. Integration with External Systems

   • API Gateway: Expose endpoints to fetch/revoke credentials:

     # config/routes.yaml
     waardepapieren_credential:
         path: /api/credentials/{id}
         controller: CommonGateway\WaardepapierenBundle\Controller\CredentialController::getCredential
     

   • Event Listeners: Trigger actions on credential events (e.g., revocation):

     // src/EventListener/CredentialRevokedListener.php
     public function onRevoked(CredentialRevokedEvent $event) {
         $this->mailer->send(new RevocationNotification($event->getSubject()));
     }
     

4. Storage Backend

   • Default: Filesystem storage (configurable via waardepapieren.storage).
   • Custom: Implement StorageInterface for databases or cloud storage:

     class DatabaseStorage implements StorageInterface {
         public function save(Credential $credential) { /* ... */ }
         public function find(string $id) { /* ... */ }
     }
     

Gotchas and Tips

Pitfalls

1. JWT Secret Management

   • Issue: Hardcoded secrets in config break security.
   • Fix: Use environment variables (%env(WAARDEPAPIEREN_JWT_SECRET)%) and rotate secrets via:

     php bin/console waardepapieren:rotate-secrets
     

2. Claim Validation

   • Issue: Invalid claims (e.g., malformed BSN) may pass silently.
   • Fix: Extend ClaimValidator or use Symfony’s validator:

     # config/validator/constraints/Waardepapieren.yaml
     CommonGateway\WaardepapierenBundle\Validator\Constraints\ValidBSN: ~
     

3. Revocation Latency

   • Issue: Revoked credentials may still be used if not synced.
   • Fix: Implement a background job (e.g., Symfony Messenger) to update revocation lists:

     $message = new SyncRevocationListMessage();
     $this->messageBus->dispatch($message);
     

4. Performance with Large Datasets

   • Issue: Batch operations may time out.
   • Fix: Use chunking in BatchCredentialIssuer:

     $batchIssuer->setChunkSize(100); // Process 100 users at a time
     

Debugging Tips

1. Enable Verbose Logging

   # config/packages/monolog.yaml
   handlers:
       waardepapieren:
           type: stream
           path: "%kernel.logs_dir%/waardepapieren.log"
           level: debug
   

2. Test Locally with Mock Data Use the WaardepapierGenerator with dummy claims to verify flows:

   $generator->generate('urn:test', 'ProofOfResidency', ['bsn' => '999999999']);
   

3. Validate JWTs Manually Decode JWTs at jwt.io to debug payloads/headers:

   php bin/console waardepapieren:decode-jwt "your.jwt.here"
   

Extension Points

1. Custom Credential Types Extend AbstractCredential to add domain-specific logic:

   class PropertyOwnershipCredential extends AbstractCredential {
       public function getSubjectType(): string { return 'PropertyOwner'; }
       protected function getDefaultClaims(): array {
           return ['property_id' => 'urn:property:123', 'ownership_percentage' => 100];
       }
   }
   

2. Plugin Architecture Use Symfony’s event system to hook into the lifecycle:

   // src/EventSubscriber/CredentialSubscriber.php
   public static function getSubscribedEvents(): array {
       return [
           CredentialGeneratedEvent::class => 'onGenerated',
           CredentialRevokedEvent::class => ['onRevoked', 100] // Low priority
       ];
   }
   

3. UI Integration

   • Frontend SDK: Package the verifier logic into a JavaScript library for client-side checks.
   • Admin Panel: Extend the CredentialController to add CRUD for manual issuance/revocation.