Your privacy choices

We use necessary cookies, and others only if you allow them. You can change your mind at any time.

Family · 2 packages, one product
FS

Fancy Sign

PHP + React · 2 packages

E-signature designed to support simple electronic signatures: email codes to view and to sign, a hash-chained audit trail, a sealed final PDF and a certificate of completion, with the signer's ceremony in React.

UI+ BackendPHP · React
26 downloads this month26 downloads all-time
Open the surface
UI surfaces1
React components

one shared contract
Backend · renders no UI1
install, then call the API
Everything in this family ships against one shared contract — install only the pieces your stack needs. Language mirrors behave identically, so you pick your backend and get the same product.

Envelopes, codes, audit trail and seal

1 package · headless — install and call it · e-signature envelopes with email one-time codes, a hash-chained audit trail and a sealed completion record

fancy-signPHP Backend · renders no UI26 downloads/mo

E-signature for Laravel and PHP, designed to support simple electronic signatures (SES): envelopes and signers with no accounts, an email one-time code to view and a fresh one to accept, consent and intent captured as hashes, signature, initials and date fields with a generated final signature page and optional per-page initials an organisation admin turns on, a per-envelope hash-chained audit trail of every view and sign event, a final PDF that keeps the as-sent bytes as a prefix, an Ed25519-sealed completion record and a certificate of completion, and a verifier that names each failure. Standard library only; PDF by fine-print. Have it reviewed by a lawyer before relying on it.

$composer require particle-academy/fancy-sign

React UI

1 package · component previews inside

fancy-sign-uiReact UI surface

React surfaces for fancy-sign, built from react-fancy, for simple electronic signatures: the signer ceremony (email code, consent, document with per-page view reports, signature pad, a fresh code to sign, or decline), the organisation admin's per-page switch, envelope setup with staged send and void, the timeline with browser-reported events labelled, the certificate of completion and a verifier. Controlled, with stable data-fancy-sign-* handles; an agent can manage an envelope and can never sign one. A React-free client on ./client.

$npm install @particle-academy/fancy-sign-ui
readmeShared model & API — README.md

fancy-sign (PHP)

particle-academy/fancy-sign: e-signature envelopes for PHP, with a Laravel bridge.

Designed to support simple electronic signatures (SES): consent and intent captured, signer verified by email one-time code, a hash-chained audit trail, and a sealed final document.

Whether an electronic signature is appropriate for a given document, and which level it needs, depends on the jurisdiction and the document type. Have it reviewed by a lawyer before relying on it.

Standard library only: SHA-256, HMAC, random_int and Ed25519 through ext-sodium. The PDF engine is particle-academy/fine-print. No third-party code.

For agents. This package is not listed on the Fancy MCP catalog server yet. The server, https://ui.particle.academy/mcp (streamable HTTP, no API key; MCP id fancy-ui), lists the released Fancy packages with install commands and docs. How an agent installs and uses this package is in AGENTS.md.

What it does

  • Envelopes and signers. A sender builds an envelope from a fine-print document (the last-word JSON model) and a list of signers. Customers have no accounts.
  • Fields. signatureField, initialsField and dateSignedField nodes in the document. fine-print lays them out and reports where each landed, so no coordinate is ever stored by hand.
  • A final signature page, generated and appended, with a signature and a date-signed field per signer. It is part of the document the signer sees. settings.final_page decides where it goes: always (the default) appends it as its own page; auto appends nothing when every signer already has a required signature and date field in the document, and otherwise lets the section flow straight after the content, moving it whole to a new page only when it does not fit; never appends nothing and refuses an envelope whose signer has no required signature field. Without a generated section, the envelope reference and content hash are printed in the last page's footer. An organisation admin can set the org's default.
  • Signing order. settings.order is parallel (the default: everyone is mailed at once and may sign in any order) or sequential: each signer has an order, only the lowest-order group is mailed when the envelope is sent, and the next group is mailed once every signer in the one before has signed. Signers with the same order sign in parallel. So a customer signs a quote first and the sender's countersigner after. A link opened before its turn is refused (not_your_turn). An organisation admin can set the org's default.
  • Per-page initials or signatures, an organisation admin's setting (PUT /fancy-sign/org/settings { per_page }). When it is on, every envelope of that organisation carries it, and a sender cannot turn it off; drafts take the setting in force when they are sent. An envelope with no organisation uses its own settings.per_page. The marks go on the authored pages only and never on the final page.
  • Email one-time codes, purpose-bound. A view code opens a short signer session; a separate, fresh accept code is sent with the signature. Six digits from a CSPRNG, stored only as an HMAC, never logged or written to an event, expiring after 10 minutes, locking after 5 wrong tries, and consumed on use so a replay fails. Unknown, expired and wrong codes all answer otp_invalid; only otp_locked is distinct.
  • Consent and intent. Consent to sign electronically comes before the document is shown; the event records the disclosure's SHA-256 and version. At signing the signer adopts a mark with the adoption text (hashed into mark.adopted), completes every required field and presses Sign with the fresh code.
  • Drawn signatures are strokes, JSON points, drawn as vector paths. No image from the browser is ever decoded.
  • A per-envelope hash-chained event log (change-council's scheme): hash = sha256(prev_hash + "\n" + canonical({seq, envelope_id, at, type, actor, source, ip, user_agent, data})).
  • Engagement events: sent (envelope.sent, email.sent), opened (document.opened, observed by the server), per-page viewed (page.viewed, reported by the signer's browser and labelled so everywhere), signed (signer.signed) and declined (signer.declined, with the reason).
  • Request changes. Beside Decline, the signer can send the sender a required message (bounded like a decline reason), recorded as signer.requested_changes with its text. It does not end the envelope: the signer can still sign or decline, and can ask again up to limits.max_change_requests times (5 by default).
  • The final PDF is the as-sent PDF plus one incremental update with the marks. The as-sent file stays a byte-for-byte prefix: truncate the final file at as_sent_bytes and hash it to prove the signed content did not change, with no tool of ours.
  • An Ed25519-sealed completion record, fsig_v1_<sha256>, naming the envelope, both document hashes, each signer, and the chain head.
  • A certificate of completion, PDF and JSON, listing every event with its source, the signers' IP addresses and user agents, and the seal.
  • verify(final.pdf, completion.json, events?) names the first failure: completion_invalid, token_mismatch, seal_invalid, final_hash_mismatch, prefix_mismatch, chain_broken, chain_head_mismatch.

Honest limits

  • The seal is checked by our verifier with the host's public key (GET /fancy-sign/public-key). A PDF reader shows no signature panel for it. A PAdES seal that any reader can check is a later phase, as are advanced signatures through a trust service. settings.level other than ses and settings.seal other than none are refused today.
  • page.viewed is what the signer's browser says. It is a claim, never proof of reading. So is document.rendered in data mode.
  • In data mode the package fixes the CONTENT, not the presentation: the host's rendering is part of what a reader must trust (see Data mode below).
  • IP addresses and user agents are personal data. They are kept because the evidence asks for them; list them in your privacy notice.

Laravel

composer require particle-academy/fancy-sign
php artisan migrate

Set a seal key (a base64 Ed25519 secret key) in .env as FANCY_SIGN_SEAL_KEY:

php -r "echo base64_encode(sodium_crypto_sign_secretkey(sodium_crypto_sign_keypair())), PHP_EOL;"

Publish the config to change anything (php artisan vendor:publish --tag=fancy-sign-config). Every limit has a secure default and can be overridden under limits.

Setting Default
prefix fancy-sign
sender_middleware ['web', 'auth']
signer_url {app.url}/sign/{token}: your page running <SignerCeremony> from @particle-academy/fancy-sign-ui
limits.otp.ttl_seconds / max_attempts / sends_per_window / sends_per_ip 600 / 5 / 5 / 30
limits.session_ttl_seconds 1800
limits.mark.max_strokes / max_points / max_typed 64 / 2048 / 128
limits.page_views.per_page / per_signer 20 / 1000
verify_max_bytes 20 MB

Bind your own FancySign\Mail\SignMailer for branded mail, your own FancySign\Laravel\SenderPolicy for teams (the default lets a sender reach only the envelopes they created; its orgId() names the sender's organisation), your own FancySign\Laravel\OrgAdminPolicy to say who may change an organisation's signing settings (the default names nobody), and a FancySign\StepUp\StepUpVerifier to allow settings.step_up = passkey (for example with fancy-passkeys).

Routes

The package registers JSON and PDF endpoints only, no pages.

Sender (your auth):
  GET  /fancy-sign/envelopes                  POST /fancy-sign/envelopes
  GET  /fancy-sign/envelopes/{id}             PUT  /fancy-sign/envelopes/{id}   (draft)
  POST /fancy-sign/envelopes/{id}/send        POST /fancy-sign/envelopes/{id}/void
  POST /fancy-sign/envelopes/{id}/remind      GET  /fancy-sign/envelopes/{id}/events
  GET  /fancy-sign/envelopes/{id}/certificate (?format=json)
  GET  /fancy-sign/envelopes/{id}/document
  POST /fancy-sign/envelopes/{id}/signers/{signerId}/invite                  (data mode)
  GET  /fancy-sign/envelopes/{id}/signatures                                 (data mode)
  POST /fancy-sign/envelopes/{id}/final       { sha256, bytes }              (data mode, after completion)
  GET  /fancy-sign/org/settings               PUT  /fancy-sign/org/settings  { per_page, final_page, order }  (org admin)

Signer (link token, then X-Fancy-Sign-Session):
  POST /fancy-sign/s/{token}/otp          { purpose: view|accept }
  POST /fancy-sign/s/{token}/otp/verify   { purpose: view, code }  -> { session }
  GET  /fancy-sign/s/{token}/envelope     POST /fancy-sign/s/{token}/consent { version }
  GET  /fancy-sign/s/{token}/document     POST /fancy-sign/s/{token}/events  { type: page.viewed, page, ms }
  POST /fancy-sign/s/{token}/sign         { fields, mark, adoption, code }
  POST /fancy-sign/s/{token}/decline      { reason }
  POST /fancy-sign/s/{token}/request-changes  { text }   (envelope stays open; 429 limit_exceeded over the cap)

Public:
  POST /fancy-sign/verify                 multipart pdf + completion (+ events)
  GET  /fancy-sign/public-key

Errors are the kit-wide error envelope (the same one fancy-http-guard emits): {"error", "message", "requestId"} with the request id also in the x-request-id header, and codes from a closed set (FancySign\SignError::CODES). A code whose status is 422 (invalid_request, otp_invalid, fields_incomplete, mark_invalid) arrives as "error": "validation_failed" with the code as its one item in errors. When the host runs fancy-http-guard, its request id is reused.

Without Laravel

use FancySign\Signing;
use FancySign\Repository\InMemoryRepository; // implement FancySign\Repository\Repository for real storage

$signing = new Signing(
    repo: new InMemoryRepository(),
    mailer: $myMailer,                         // FancySign\Mail\SignMailer
    sealSecretKey: $sealKeyBase64,
    appKey: $thirtyTwoSecretBytes,
    linkUrl: fn (string $token) => "https://app.example.com/sign/{$token}",
);
$env = $signing->create(['title' => 'Quote', 'document' => $doc, 'signers' => [['id' => 'alice', 'name' => 'Alice', 'email' => '[email protected]']]], 'user:1');
$signing->send($env['id'], 'user:1');

Preview before sending

Signing::preview(array $input, ?string $orgId = null): string returns the PDF bytes send() would produce for the same input (what create() takes) and organisation: the signature page, per-page initials or signatures from the organisation's per_page setting, and every signature and date field in its place. Nothing is stored, no event is recorded and no mail is sent. Invalid input is refused with the same SignError as create().

The envelope reference and the content hash are not assigned before sending, so those two lines read PREVIEW, assigned when sent (Renderer::PREVIEW_PLACEHOLDER). Everything else matches the sent document.

$pdf = $signing->preview(['title' => 'Quote', 'document' => $doc, 'signers' => $signers], $orgId);

To draw the review from data rather than a PDF, Signing::previewDocument(array $input, ?string $orgId = null): array returns the as-sent document model from the same build step: the document with the generated signature section as nodes, the per-page fields as field nodes, the footer line when there is no section, and the fields. It has the same guarantees as preview(), and (new Renderer())->render($model)['bytes'] is exactly the preview() PDF.

$model = $signing->previewDocument(['title' => 'Quote', 'document' => $doc, 'signers' => $signers, 'settings' => ['final_page' => 'auto']], $orgId);
$model['document'];                        // render it in your own viewer
$model['signature_section']['placement']; // signature_page, after_content or footer

Data mode: sign the host's data, not a PDF (0.7.0)

settings.mode: "data" signs an opaque JSON object the host owns (a quote, an order) instead of a PDF this package renders. In data mode the package seals the data and the signing evidence; how the data was displayed to each signer, and any document made from it, are the host application's. It supplies signing primitives, never a workflow:

use FancySign\Data\CanonicalDocument;

$json = json_encode($quote);                    // the host's own data
$env = $signing->create([
    'title' => 'Quote Q-1001',
    'settings' => ['mode' => 'data'],
    'signers' => [['id' => 'buyer', 'name' => 'Pat Buyer', 'email' => '[email protected]']],
    'data' => $json,                            // JSON text, or json_decode($json, false)
    'data_sha256' => CanonicalDocument::sha256($json),
    'fields' => [['id' => 'buyer-sig', 'signer' => 'buyer', 'kind' => 'signature', 'anchor' => ['pointer' => '/lines']]],
], 'user:1');
$signing->send($env['id'], 'user:1');          // fixes the data; mails NO ONE
$signing->invite($env['id'], 'buyer', 'user:1'); // when YOUR workflow says so
  • The data is hashed in fsig-data-1, a canonical JSON form any runtime can reproduce (fancy-conformance sign/data); data_sha256 is required, so a canonicalisation difference is a 422 at create time, never a contract that does not verify.
  • Each signature is its own sealed record (fsig_sig_v1_); completion (version 2, fsig_v2_) is the reported fact that everyone has signed, and nothing follows it. Verifier::verifySignature() proves one signature before anyone else has signed; Verifier::verifyData() checks the whole envelope.
  • What the signer's browser says it showed (document.rendered, the host's template and release) is recorded as a claim, and copied into each record as one.
  • Optionally, once everyone has signed, the host registers the hash of the final PDF it made: attachFinal($id, $sha256, $bytes, $actor), once and idempotent, sealed as a fsig_fin_v1_ record and named by the certificate. The package never receives the PDF.
  • Changing the data means voiding and sending a new envelope. The signing page itself stays live: a new host template or fancy-sign-ui release reaches every open envelope with no resend.

Reacting to signatures

Every event committed to an envelope's chain reaches the host as FancySign\Events\EnvelopeEventRecorded (envelope id, event type, seq, time): a Laravel event, and a call to a FancySign\Listener\SignListener if you bind one. Under Laravel it is delivered by a queued job after the database commit, retried on failure, at least once (dedupe on the seq), and a failing listener never fails the signer's request. Close a deal on envelope.completed; AGENTS.md has the example.

Agents

The registerSignBridge in @particle-academy/agent-integrations lets an agent manage envelopes: read them, place fields, set signers and settings, and propose sending, voiding or a reminder for a human to confirm. No tool signs, verifies a code, accepts consent, adopts a mark or declines: those acts belong to the signer.

License

MIT.

What next
Open a surface and click any component for a live demo with source.