Trusted Timestamping Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dracoder/trusted-timestamping
   

   Add to config/app.php under providers:

   Dracoder\TrustedTimestamping\TrustedTimestampingServiceProvider::class,
   

2. Publish Config

   php artisan vendor:publish --provider="Dracoder\TrustedTimestamping\TrustedTimestampingServiceProvider"
   

   Configure config/trusted-timestamping.php with your timestamping service (e.g., tsa URL, credentials).

3. First Use Case: Timestamp a File

   use Dracoder\TrustedTimestamping\Facades\TrustedTimestamping;
   
   $filePath = storage_path('app/example.pdf');
   $timestampToken = TrustedTimestamping::timestamp($filePath);
   
   // $timestampToken now contains the signed timestamp response.
   

Implementation Patterns

Core Workflows

1. Timestamping Files

   • Single File:

     $token = TrustedTimestamping::timestamp($filePath);
     

   • Batch Processing:

     $filePaths = [storage_path('file1.pdf'), storage_path('file2.pdf')];
     foreach ($filePaths as $file) {
         $token = TrustedTimestamping::timestamp($file);
         // Store $token in DB or filesystem.
     }
     

2. Verifying Timestamps

   $isValid = TrustedTimestamping::verify($timestampToken, $filePath);
   

3. Integration with Storage

   • Laravel Filesystem: Use Storage::disk('local')->path() to get file paths for timestamping.
   • S3/Cloud Storage: Download files locally first, timestamp, then re-upload:

     $file = Storage::disk('s3')->get('remote-file.pdf');
     $localPath = tempnam(sys_get_temp_dir(), 'tt_');
     file_put_contents($localPath, $file);
     $token = TrustedTimestamping::timestamp($localPath);
     unlink($localPath); // Cleanup
     

4. Event-Based Timestamping

   • Trigger timestamping on file uploads via HasFile events:

     use Illuminate\Support\Facades\Event;
     use Dracoder\TrustedTimestamping\Facades\TrustedTimestamping;
     
     Event::listen('eloquent.saved: App\Models\Document', function ($model) {
         if ($model->file_path) {
             $token = TrustedTimestamping::timestamp($model->file_path);
             $model->timestamp_token = $token;
             $model->save();
         }
     });
     

5. Queueing Timestamp Jobs

   • Offload timestamping to a queue for large files:

     use Dracoder\TrustedTimestamping\Jobs\TimestampFile;
     
     dispatch(new TimestampFile($filePath))->onQueue('timestamping');
     

Gotchas and Tips

Pitfalls

1. File Size Limits

   • TSA servers often enforce size limits (e.g., 10MB). Handle exceptions:

     try {
         $token = TrustedTimestamping::timestamp($filePath);
     } catch (\Dracoder\TrustedTimestamping\Exceptions\FileTooLargeException $e) {
         // Split file or notify user.
     }
     

2. Network Dependencies

   • Timestamping requires external TSA service calls. Add retries for transient failures:

     TrustedTimestamping::setRetryPolicy(3); // Retry 3 times.
     

3. Token Storage

   • Timestamp tokens can be large (base64-encoded). Store them efficiently:

     // Use a text column in DB or compress before storing.
     $compressedToken = gzcompress($timestampToken);
     

4. Clock Skew

   • Verify timestamps with a tolerance for minor clock differences:

     $isValid = TrustedTimestamping::verify($token, $filePath, 60); // 60-second tolerance.
     

Debugging

1. Enable Logging Configure config/trusted-timestamping.php:

   'debug' => env('APP_DEBUG', false),
   

   Logs will appear in storage/logs/laravel.log.

2. Mocking for Tests Use the MockTimestampService in tests:

   $this->app->bind(
       \Dracoder\TrustedTimestamping\Contracts\TimestampService::class,
       \Dracoder\TrustedTimestamping\MockTimestampService::class
   );
   

Extension Points

1. Custom Timestamp Services Implement Dracoder\TrustedTimestamping\Contracts\TimestampService for alternative providers (e.g., local HSM):

   class CustomTimestampService implements TimestampService {
       public function timestamp(string $filePath): string {
           // Custom logic.
       }
   }
   

2. Pre/Post-Processing Hooks Extend the service provider to add hooks:

   // In a custom service provider:
   $this->app->afterResolving(\Dracoder\TrustedTimestamping\Facades\TrustedTimestamping::class, function ($service) {
       $service->extend(function ($token) {
           // Modify token before returning.
           return $token;
       });
   });
   

3. Custom Verification Rules Override verification logic in a macro:

   TrustedTimestamping::macro('verifyWithTolerance', function ($token, $filePath, $tolerance = 60) {
       return $this->verify($token, $filePath, $tolerance);
   });
   

Configuration Quirks

1. HTTPS Requirement Ensure config/trusted-timestamping.php uses HTTPS for TSA endpoints to avoid mixed-content warnings.

2. Caching Tokens Cache verified tokens to avoid repeated TSA calls:

   Cache::remember("tt_{$filePath}", now()->addHours(24), function () use ($filePath) {
       return TrustedTimestamping::timestamp($filePath);
   });
   

3. Environment-Specific TSAs Use environment variables for dynamic TSA URLs:

   'tsa_url' => env('TSA_URL', 'https://default-tsa.example.com'),