SignLocal setup guide

This guide is for the person who makes SignLocal available to others: IT, a SharePoint administrator, or a team lead. People who sign documents only need the user guide.

1. Choose a way to provide SignLocal
2. Option A: Hosted website (no setup)
3. Option B: Single file
4. Option C: SharePoint Online and Microsoft Teams
5. Option D: Host it on your own web server

6. Signing identities and trust

   • Timestamp relay
7. Security and data handling (for IT review)
8. Developer setup: build, test and deploy
9. Updating SignLocal
10. Troubleshooting

1. Choose a way to provide SignLocal

All four options run the same app with the same features. Pick what suits your users.

Browser requirements (all options): a current version of Microsoft Edge, Google Chrome, Mozilla Firefox, or Safari (macOS, iOS and iPadOS 16.4 or later). Internet Explorer is not supported.

Downloads

Option A: Hosted website (no setup)

Send users the address https://signlocal.pages.dev.

• Desktop: it runs in the browser. In Edge or Chrome, users can choose Install (the icon in the address bar, or the browser menu → Apps → Install SignLocal) to get a desktop shortcut and a standalone window.
• iPhone / iPad (Safari): Share → Add to Home Screen.
• Android (Chrome): ⋮ → Install app.

After the first visit the app is cached on the device and works offline.

Documents are never sent to the website. The site serves only the program files, and its security policy (see section 7) prevents the page from contacting any server.

Option B: Single file

1. Download SignLocal.html (about 2.4 MB) from the link above or from dist/ in the repository.
2. Give it to users however suits you: a network share, intranet download, email attachment, Teams files, a USB stick, or a desktop shortcut deployed by Intune or Group Policy.
3. Users double-click it. It opens in their default browser.

Notes:

• The single file contains everything, including all libraries. It never loads anything from the internet, so it suits air-gapped networks.
• SharePoint and OneDrive libraries: if users click an .html file there, SharePoint downloads it instead of running it (by design). Users then open the downloaded copy. For running SignLocal inside SharePoint, use Option C.
• Signatures and keys are stored per browser. If users open the file from different locations, each copy keeps the same browser storage for a file:// page in Chrome and Edge, but this can differ between browsers.
• Some email filters block .html attachments. Zip it first, or share a link instead.

Option C: SharePoint Online and Microsoft Teams

SignLocal is packaged as a SharePoint Framework (SPFx 1.24) web part:

• All code is inside the package, and SharePoint serves it from your tenant's own app catalog storage. Nothing loads from outside your tenant.
• It does not require custom scripts to be enabled, and it complies with SharePoint Online's Content Security Policy enforcement.
• It requests no API permissions (no Microsoft Graph or SharePoint API access). It can't read or write your SharePoint content; users choose files from their device, and signed files are downloaded to their device.
• Its only outside connection is the optional timestamp relay, which receives a signature fingerprint, never documents.
• It is deployable tenant-wide, so there's no per-site installation.

Why not upload the HTML file to a document library? SharePoint Online opens .html files as downloads rather than running them, and modern sites block .aspx uploads ("NoScript"). An SPFx package is the supported way to run custom code in SharePoint Online.

C1. Prerequisites

• SharePoint Administrator (or Global Administrator) rights in Microsoft 365, to upload the app.
• A tenant app catalog. Most tenants already have one. To check, go to the SharePoint admin center → More features → Apps → Open. If you're asked to create an app catalog, accept and wait a few minutes.

C2. Upload and enable the app (once per tenant)

1. Download signlocal.sppkg.
2. Open the SharePoint admin center (https://<your-tenant>-admin.sharepoint.com).
3. Go to More features → Apps → Open. The Manage apps page opens.
4. Choose Upload and select signlocal.sppkg.

5. In the Enable app panel:

   • Tick Enable this app and add it to all sites to make it available everywhere. Otherwise, only enable it, and site owners add it themselves (step C4).
   • Choose Enable.
6. (Optional) The panel offers Add to Teams. Choose it to make SignLocal available as a Teams app (see C5).

The app appears in the list as SignLocal, version 1.1.0.0.

C3. Add SignLocal to a page

1. Go to the SharePoint site, open the page (or + New → Page), and choose Edit.
2. Hover where you want it and choose + (Add a new web part).
3. Search for SignLocal (it's listed under Advanced) and select it.
4. Choose Publish (or Republish).

Recommendations:

• Put it in a full-width section (Edit → + Add section → Full-width section) or a one-column section, so documents have room.
• For a dedicated signing page, use SignLocal as a full-page app: on the site's home page choose + New → App, select SignLocal, give the page a name (for example Sign), and choose Create. The page then shows only SignLocal, with the most room for documents.
• Add a link to the page in the site navigation or a hub, for example Sign a document.

Anyone who can view the page can use it. Editing the page requires the usual page-edit permissions.

C4. If you didn't add it to all sites

Site owners add it once per site: Settings (⚙) → Add an app → SignLocal. Then follow C3.

C5. Microsoft Teams

If you chose Add to Teams in C2, or later selected the app in the app catalog and chose Sync to Teams:

• As a tab: in a channel or chat, choose + (Add a tab) → SignLocal.
• As a personal app: in Teams, choose Apps, search for SignLocal, and choose Add. You may need to allow it in the Teams admin center → Teams apps → Manage apps if your app permission policies block custom apps.

C6. Remove or roll back

• Remove from one page: edit the page, select the web part and choose the bin icon.
• Remove everywhere: in Manage apps, select SignLocal and choose Remove. Pages that use it then show an error, so remove it from pages first.
• Roll back: upload the previous .sppkg version over the current one.

C7. Content Security Policy notes

SignLocal's code is part of the package and runs from SharePoint's own storage, which SharePoint's CSP trusts by default, so no "Trusted script sources" entry is needed. To test before CSP enforcement reaches a page, add ?csp=enforce to the page URL and confirm SignLocal works (browser developer tools should show no CSP errors).

Option D: Host it on your own web server

SignLocal is a static website: plain files, no server code, no database.

1. Build the site folder (see section 8): npm run build:site. This writes site/:

   site/
     index.html, sw.js, manifest.webmanifest, icon.svg
     css/  js/  vendor/
     download/SignLocal.html, download/signlocal.sppkg
     _headers            (security headers, used by Cloudflare)

2. Copy the contents of site/ to your web server or static host (IIS, nginx, Apache, Azure Static Web Apps, Amazon S3 + CloudFront, Netlify…).
3. Serve it over HTTPS. Offline use and installing as an app need HTTPS (or localhost).
4. Add the security headers that site/_headers lists. Examples follow.

nginx

location / {
    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self'; connect-src 'self' data: blob:; worker-src 'self' blob:; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'self' https://*.sharepoint.com https://teams.microsoft.com" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer" always;
    add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=()" always;
}
location /download/ {
    add_header Content-Disposition "attachment" always;
}
types { application/manifest+json webmanifest; }

IIS (web.config in the site folder)

<configuration>
  <system.webServer>
    <staticContent>
      <remove fileExtension=".webmanifest" />
      <mimeMap fileExtension=".webmanifest" mimeType="application/manifest+json" />
      <remove fileExtension=".sppkg" />
      <mimeMap fileExtension=".sppkg" mimeType="application/octet-stream" />
    </staticContent>
    <httpProtocol>
      <customHeaders>
        <add name="Content-Security-Policy" value="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self'; connect-src 'self' data: blob:; worker-src 'self' blob:; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'self' https://*.sharepoint.com https://teams.microsoft.com" />
        <add name="X-Content-Type-Options" value="nosniff" />
        <add name="Referrer-Policy" value="no-referrer" />
        <add name="Permissions-Policy" value="camera=(), microphone=(), geolocation=(), payment=(), usb=()" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

Your own Cloudflare account: see 8.4.

If you host SignLocal at your own address, also change the ? help link in index.html (https://signlocal.pages.dev/guide.html) to point at your copy, then rebuild.

6. Signing identities and trust

How keys work by default

• The first time someone seals a document, their browser creates an RSA-2048 key and a self-signed certificate with their name and email. The key is stored in that browser's local storage on that device.
• The key's fingerprint (the Key ID) stays the same for that person on that browser until they choose Reset identity.
• Extra signers on the same device (signing together) get a one-time key for that signing.

This proves integrity (the document hasn't changed) and key continuity (same device and browser as before). It does not prove legal identity, because anyone can type any name.

Making signatures trusted in Adobe Acrobat

Pick one approach:

1. Per signer: the signer exports their certificate (Identity → Export certificate). Recipients import it in Acrobat as a trusted certificate. The steps are in the user guide.

2. Organisation-wide, recommended for formal use: issue each signer a certificate from your certificate authority (for example Active Directory Certificate Services, or a public CA's document-signing certificate) as a .p12/.pfx file with a password. Signers load it in Identity → Use your own certificate each session. The certificate chain is embedded in each signature, and devices that trust your CA (for example through the Windows certificate store, or Acrobat's AATL or EUTL lists for public CAs) show the signature as trusted.

   • The certificate needs an RSA key and the Digital Signature (and ideally Non-Repudiation) key usage.
   • Very long certificate chains (over about 12 KB) can't be embedded; SignLocal reports this.

Trusted certificates on users' devices

Each user's Identity → Trusted certificates list decides which signatures show as Verified. To roll out your organisation's CA, send users its root certificate (.cer) with instructions to add it there. They can also choose Trust this signer's certificate on a Verify result.

For what this means legally, see Legal validity.

Timestamp relay

Signatures get a trusted RFC 3161 timestamp from a public timestamp authority (TSA). Public TSAs don't allow browser requests (no CORS), so SignLocal sends its request through a tiny relay:

• What is sent: an RFC 3161 TimeStampReq, which contains a SHA-256 fingerprint of the signature value and a random number. No document content, names or emails.
• The relay: https://signlocal.pages.dev/api/timestamp, a Cloudflare Pages Function (functions/api/timestamp.js in the repository). It accepts only small DER timestamp requests, forwards them unchanged to DigiCert (with Sectigo, then GlobalSign as fallbacks), and stores and logs nothing.
• Checking the result: SignLocal checks every token: that it covers this signature and uses this request's nonce, that the TSA's signature is valid, and that the TSA chains to one of the bundled roots (vendor/tsa-roots.js: DigiCert, USERTrust/Sectigo, GlobalSign).
• Offline or blocked: signing still works with the device's clock, and the result says that no trusted timestamp was added.

Firewalls and proxies: allow HTTPS to signlocal.pages.dev. All three versions (web, single file and SharePoint) use this relay.

Using your own relay or a different TSA (for example an EU-qualified TSA):

1. Change the TSAS list in functions/api/timestamp.js.
2. Deploy it with the site to your own Cloudflare Pages project (npm run deploy deploys functions/ too). Alternatively, implement the same small POST relay on any server, returning Access-Control-Allow-Origin: *.

3. Point SignLocal at it:

   • Hosted on your own Pages project: if the site's domain isn't signlocal.pages.dev, change the default URL in ST.tsa.url() in js/cms.js.
   • Without rebuilding: set window.SIGNLOCAL_TSA_URL = 'https://your.host/api/timestamp' in a script that loads before js/cms.js, and allow that host in the page's connect-src.
4. Add your TSA's root certificate to vendor/tsa-roots.js, then rebuild (npm run build:site, npm run build:sharepoint).

Time without a trusted timestamp

If trusted timestamps are turned off or unavailable, times come from the signing device's clock. Keep automatic date and time on for managed devices (Windows Time service or NTP, and MDM settings on phones).

7. Security and data handling (for IT review)

8. Developer setup: build, test and deploy

8.1 Prerequisites

• Node.js 22.14+ or 24.x (node --version)
• Git
• For SharePoint builds: no extra tools; everything installs from npm.
• For Cloudflare deploys: a Cloudflare account.

8.2 Get the code and run it

git clone https://github.com/lipk-stack/signature-tool.git

cd signature-tool

npm install

There is no compile step for the web app. Open index.html in a browser to run it from source. To test offline mode and installation, serve the folder over HTTP instead, for example:

npx --yes http-server -p 8080 -c-1

Then open http://localhost:8080.

Source layout

8.3 Build commands

To build the SharePoint package:

npm --prefix sharepoint install

npm run build:sharepoint

Before releasing a new SharePoint version, raise version in sharepoint/config/package-solution.json (for example 1.2.0.0) and in package.json.

8.4 Deploy to Cloudflare Pages

1. Log in once:

   npx wrangler login

2. First time only, create the Pages project. With Wrangler 4.162 or later, --force is needed once to create a classic Pages project; leave it out on later deploys:

   npx wrangler pages project create signlocal --production-branch main --force

3. Deploy (this also builds site/):

   npm run deploy

The site is published at https://<project>.pages.dev. To use your own domain, go to the Cloudflare dashboard → Workers & Pages → signlocal → Custom domains → Set up a custom domain.

To use a different project name, change --project-name in the deploy script in package.json.

8.5 Testing a change

Check at least these before releasing:

1. Single signer: open a PDF, place a signature and a date, tick consent, finish, download. Verify shows Valid — unchanged since signing, with Signed at … trusted timestamp by DigiCert … (trusted authority) and PAdES baseline B-T.
2. Several signers: add a second signer on the same device and a Sign here box for a third. Open the result in a different browser profile, fill the box, finish. Verify shows three valid signatures.
3. Tamper check: change any byte of the signed PDF. Verify shows NOT valid.
4. Word file: sign a .docx with two signers. Verify on the .zip shows every signature valid, and the .docx opens in Word with the signature blocks at the end.
5. Phone size: repeat step 1 at phone width with touch.

6. Independent checks (optional):

   pip install pyhanko-cli

   pyhanko sign validate --pretty-print --trust signer.cer signed.pdf

   signer.cer is the certificate the signer exported from Identity → Export certificate. Expect "All modifications relate to signing and form filling operations" and "The signature is judged VALID". Without --trust, pyHanko reports self-signed certificates as untrusted and judges them INVALID even when the document is intact.

   openssl cms -verify -binary -noverify -inform DER -in file.docx.p7s -content file.docx -out /dev/null

9. Updating SignLocal

Documents signed with older versions stay valid; the signature format doesn't change between versions.

10. Troubleshooting