Skip to main content

Signing Flow

This page describes the complete journey from opening a PDF to producing a signed, blockchain-anchored document.

Step-by-Step​

1. Authentication & Identity​

Before signing, the user must authenticate via one of:

  • Magic link -- enter email, receive a 6-digit code, verify
  • Google OAuth -- sign in with Google account
  • Microsoft OAuth -- sign in with Microsoft account

After authentication, the user completes their signer profile (name, signer type, company, position). Both the JWT and profile are stored in the OS keychain and persist across app restarts.

The authentication method becomes the trust anchor recorded in each signature (e.g. "google", "microsoft", "email"), allowing verifiers to see how the signer's identity was confirmed.

2. Document Selection​

The user opens a PDF through the file picker or via the OS "Open With" menu. A scrollable preview is rendered.

3. Signature Placement​

The user drags their signature image onto the PDF preview. They can:

  • Place signatures across multiple pages
  • Resize and reposition each placement
  • Add text fields (name, date, custom text)
  • Drag saved text snippets from their library (e.g. pre-configured name, address, company)
  • See a live preview of the QR code area

Signatures and text snippets can be saved to the My Library for reuse across documents. The library is stored locally in the app data directory and persists across sessions. Users can opt in to cloud sync to back up their library and access it on other devices.

4. Confirmation​

A confirmation dialog shows the number of placements and warns that the action cannot be undone.

5. Processing​

After confirmation, the app executes these steps:

Pick anchor ID + key -> Stamp one layer -> Save -> Hash saved file
  -> Build + seal record -> Anchor on blockchain -> Signed PDF

Generate Anchor ID and Key​

Before anything is stamped, the app generates two random 16-byte values:

  • an anchor ID, which names this signature on the blockchain
  • an AES-128-GCM key, which seals the signing record

Both go into the QR link <VERIFY SITE>/V/<anchor ID>#<key>, each written as 40 digits to keep the QR code small. Because the link is known before the document is fingerprinted, the QR code can be placed on the page and covered by the document hash.

Stamp One Layer​

The app appends a single incremental update to the PDF. It contains the signature image at each placement, the text fields, the QR code next to each signature, and the signer's entry in the signing history (the /SignChainMeta catalog stream, format version 3). Before stamping, each page's existing content is wrapped in q … Q, so graphics state left over by the original content cannot move the stamps. Earlier layers are never changed.

Compute Hash​

The layer is saved once. The document hash is the SHA-256 of exactly those saved bytes, through the layer's %%EOF. Nothing is written to the file afterwards, so anyone holding the file can cut it at that point and recompute the same hash.

Build & Seal the Signing Record​

The anchor ID, document hash, signer identity, timestamp, geolocation (if available), and a random salt are assembled into a JSON signing record. The composite hash is the SHA-256 of that exact JSON text. It is the only value about the signature stored on the blockchain.

The record is encrypted with the key from the QR link. The encrypted record is sent to the API for storage. The key is never sent to any server.

Anchor on Blockchain​

The app sends the anchor ID, composite hash, previous signer's anchor ID, and encrypted record to the API. The API submits them to the smart contract and returns the anchor ID, transaction hash, and block number.

6. Save​

The user saves the signed PDF. The original file is never modified.

Multiple Signatures​

When a previously signed document is signed again:

  1. The app reads the signing history in the document
  2. The new signer appends their own layer after the previous ones, so every signed version stays a byte-for-byte prefix of the final file
  3. The new signature names the previous signer's anchor ID, creating a signature chain. The contract rejects a previous anchor ID that is not on the blockchain.
  4. Verification shows all signatures in order

Files signed with earlier Veylent formats can't be signed further. The app asks for an unsigned copy instead.