#Signing Workflow

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

User registers signature image (SignatureResource or SignatureManager::store)
      |
      v
SignatureManager::store()
  - Forgery check (duplicate image hash)
  - Metadata validation on upload (HMAC + user ID + machine)
  - DB cross-validation (Sig-Record-Id → machine_fingerprint)
  - Document hash captured
  - UUID generated
  - PNG metadata embedded (tEXt + XMP: signer name, machine hash, UUID)
  - Signature record created (status: pending)
      |
      v
User signs a document (SignDocumentAction or custom flow)
      |
      v
SignatureManager::embedAndFinalize()   ← called directly (synchronous default)
  OR EmbedSignatureJob::handle()       ← via .queued()
      |
      v
SignatureManager::embedAndFinalize()
  - CRL check (if enabled)
  - Certificate loaded from PFX
  - PDF signed with PKCS#7 (FpdiDriver)
  - Signed PDF hash captured
  - Signature record updated (status: signed)
  - DocumentSigned event fired

1
2
3

use Kukux\DigitalSignature\Services\SignatureManager;

$manager = app(SignatureManager::class);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

$signature = $manager->store(
    userId:     $user->id,
    input:      $request->input('signature_data'),  // base64 data URI or UploadedFile
    source:     'draw',                              // 'draw' or 'upload'
    signable:   $contract,                           // optional Signable model
    signerName: $user->name . ' <' . $user->email . '>',  // optional, embedded in PNG
    position:   [                                    // optional stamp coordinates
        'page'   => 1,
        'x'      => 100.0,
        'y'      => 650.0,
        'width'  => 200.0,
        'height' => 80.0,
    ],
);

// $signature->uuid   — unique token embedded in the PNG and stored in DB
// $signature->status — 'pending'

1
2
3
4
5
6

$signature = $manager->store(
    userId:     $user->id,
    input:      $request->file('signature_image'),
    source:     'upload',
    signerName: $user->name . ' <' . $user->email . '>',
);

1

$manager->embedAndFinalize($signature, $request->input('certificate_password'));

1

$manager->sign($signature, $request->input('certificate_password'));

1
2
3
4
5

$manager->revoke($signature);

// $signature->status  → 'revoked'
// $signature->revoked_at → now()
// SignatureRevoked event fired

1
2
3
4
5
6
7
8
9
10

$contract = Contract::find(1);

$contract->isSigned();           // bool
$contract->latestSignature();    // ?Signature

$sig = $contract->latestSignature();

$sig->isPending();   // true while job is queued / before embedAndFinalize()
$sig->isSigned();    // true after embedAndFinalize() completes
$sig->isRevoked();   // true after revoke()

1
2
3
4
5
6
7
8
9
10
11

use Illuminate\Support\Facades\Storage;

$sig  = $contract->latestSignature();
$disk = Storage::disk(config('signature.storage_disk'));

// Verify the signed PDF has not changed since signing
$current = hash('sha256', $disk->get($sig->signed_document_path));

if ($current !== $sig->signed_document_hash) {
    // The signed file has been modified after it was produced
}

1
2
3
4
5
6
7

use Kukux\DigitalSignature\Security\PngMetaEmbedder;

$chunks = app(PngMetaEmbedder::class)->read(file_get_contents($path));

// $chunks['Sig-Record-Id'] — look up the DB record
// $chunks['Sig-Signer-Name'] — who it was registered to
// $chunks['Sig-Hmac'] — verify against your APP_KEY

1
2
3
4
5
6
7
8
9

// app/Providers/EventServiceProvider.php

use Kukux\DigitalSignature\Events\DocumentSigned;
use Kukux\DigitalSignature\Events\SignatureRevoked;

protected $listen = [
    DocumentSigned::class  => [SendSignedDocumentEmail::class],
    SignatureRevoked::class => [NotifyAdminOfRevocation::class],
];

1
2
3
4
5
6
7
8
9
10
11

use Kukux\DigitalSignature\Events\DocumentSigned;

Event::listen(DocumentSigned::class, function ($event) {
    $sig = $event->signature;

    // $sig->signed_document_path  — path to the signed PDF
    // $sig->signed_document_hash  — SHA-256 for integrity checks
    // $sig->certificate_fingerprint
    // $sig->signed_at
    // $sig->uuid                  — embedded in the PNG as Sig-Record-Id
});

1
2
3

// config/signature.php
'queue'            => env('SIGNATURE_QUEUE', 'default'),
'queue_connection' => env('SIGNATURE_QUEUE_CONNECTION', null),

1
2
3
4
5

Queue::failing(function (JobFailed $event) {
    if ($event->job->resolveName() === \Kukux\DigitalSignature\Jobs\EmbedSignatureJob::class) {
        // notify, log, etc.
    }
});