libresign/libresign

✍️ Nextcloud app to sign PDF documents

Nextcloud app to sign PDF documents.

Setup

After installing LibreSign, go to Administration Settings > LibreSign and:

• Click in the Download binaries button. When it show status successful to all items, except root certificate not configured, is time to configure root certificate in the next section.

Integrations

• GLPI: Plugin to sign GLPI tickets
• Approval: Approve/reject files based on workflows defined by admins

Contributing

There are many ways to contribute, including writing code, filing issues on GitHub, helping people Overflow, helping to triage, reproduce, or fix bugs that people have filed, adding to our documentation. To get more details go to our contributing guide.

API Documentation

API Documentation

libresign's Issues

GLPI flow to sign document errors message.

Based on the assumption that I am properly logged in and I am signing the document to which I am allowed, at the moment I am going to sign, if I do not enter the password, I get an 'Internal Error` response.

I must now receive the error password was not informed, if the password is not compatible with the registered one, I should receive the error Incorrect password.

Rename branch master to main

Regenerate root certificate

Go to Settings > Security, is necessary create the possibility to invalidate the current certificate and generate a new certificate.

Setting to authorize use of webhook

Implement in the LibreSign administration settings field to define the user groups that will be able to access the webhook.

Reference:

https://github.com/nextcloud/impersonate/blob/master/js/admin_settings.js

https://github.com/nextcloud/impersonate/blob/master/templates/admin_settings.php

Example of setting form:

Setting: webhook_authorized
format: array
content: list of authorized user groups

Definition of ready:

Check if the settings are being saved in the database when defining a new group besides the admin group.

select *
  from oc_appconfig oa
 where appid = 'libresign'
   and configkey = 'webhook_authorized'

l10n: Password or passwords?

Is this information:

libresign/src/views/CreateUser.vue

Line 62 in 99d9ca0

content: t('libresign', 'Password does not match'),

concerns the comparison of two entered passwords?

If so, it should be: Passwords do not match.

Unless it is a password comparison to another signature password.

Send email to signer when sign request is removed

It is possible to exclude a sign request by API but when this is done it is necessary to choose whether or not to notify who has been removed.
Estimate: 4h

Implement tab in the descriptions of the Files app and remove dsv folder from the project

Implement in VueJS everything in the dsv folder and revmove this folder.

Suggested scenarios:

Scenario: See LibreSign in Files

• Given I'm on Files
• And I see a PDF file
• And I access the details of this file
• Then I see a LibreSign tab

Scenario: Request sign

• Given I'm on the LibreSign tab
• And I see inviting people to sign
• And I fill in with email from someone who is not on Nextcloud
• And I see the person's email
• And I click on the person's email
• And the person is added to a list
• And I can define a description of the file for this person
• And I can search for someone else to add
• And I'm looking for someone who's already on Nextcloud
• And I see the person’s name
• And I add this person
• And I define the name of the file to be signed
• And I click on request sign
• And the list is sent to the API with the file id
• Then I see "Invitation sent successfully"

Scenario: File details with pending signature

• Given I'm on the LibreSign tab
• And I’ve already asked people to sign
• And file has not yet been signed by anyone
• Then I see a list of these people and a button to remove a subscription request for someone.

Scenario: One person signed

• Given I'm on the LibreSign tab
• And someone already signed
• Then I must see in the list of who should sign that this person has already signed

Scenario: Everyone has already signed

• Given I'm on the LibreSign tab
• And everyone has already signed
• Then I should see everyone with the mark of who signed and the date they signed

Scenario: I need to subscribe

• Given I'm on the LibreSign tab
• And I have to sign
• And I see a field to enter the subscription password
• And fill in the password
• And I click subscribe
• And some password field
• And I see the status as signed
• And I see the date that the file was signed
• Then I must see: File successfully signed

Estimate: 40h

Create repo for app and Docker

Necessary separate the Nextcloud app in a reposistory and Docker environment in another repository

Change signature validation URL

The PDF signature validation URL is in an external application that does not require an authenticated user. Need to be able to inform what is the URL of the validation page.

Frontend

• implement field to save the validation_site property in the settings

Backend

• Use setting validation_site in the PDF signature.

URL to get PDF details

Backend

• Implement route /file/<uuid> in the validation page that returns the front with a <script> block containing a json with all the necessary metadata to display the page created in issue #130
  Estimate: 2h

Frontend

• Make changes to the page created in issue #130 to be displayed without having to make a request to the API, you only need to read the JSON that will be in a variable in the body of the page.
  Estimate: 2h

PS: The page displayed with the API request will continue to exist but will only be loaded when the user informs the UUID on the form. This issue is for the person who accesses the /file/<uuid> page. This person will access this page by clicking on the link in the PDF or by accessing the URL read in the document's validation qrcode.

i18n

• README in pt_BR and en_US
• doc's folder in pt_BR and en_US
• Translate all text of frontend

Remove Signature Request

While the document is not signed it should be possible to remove people who should sign it.

[Question] How to use webhooks with this app?

Hi
First of all, thanks for the efforts to create this app, it is extremely useful. I am currently in the process of setting it up to test it. I have been able to configure the cfssl server, and now it is possible for the users to create signatures and there is a signature tab when I open the pdf sidebar.

Unfortunately, I have not been able to request file signatures using webhooks. Should I write my own webhooks and made them available at this address?
https://nextcloud.local/index.php/apps/libresign/api/v1.0

I have been trying to follow a similar example of a POST request in the documentation with no luck.

Would it be possible to provide me a minimal example or a pointer for me to move forward?

PS: I am sorry if this is an obvious question, I am a complete noob with Nextcloud.

Thank you!

Use project exceptions

There are many places in the code using \Exception, it is good that the exceptions generated are unique to LibreSign to improve tracking of possible errors.

For example, where to find:

throw \Exception

Replace with:

use OCA\Libresign\Exception\LibresignException;
// ...
throw LibresignException

API endpoint to list docs

The main screen need show two list of files: need to sign and signed.

List of docs with:

• File name
• List with status of signatures containing who has to sign and individual status of each signature with the date the signature was requested and the date when signed when this date exists
• Document status: unsigned and signed
• Actions containing whether the person can sign, or delete subscription requests, or delete the doc
• Who requested the doc to be signed
• Download PDF link

Integration test for the user creation form.

Create integration test for the user creation form.

• Check that passwords are identical.
• Minimum size of the pfx key.
• Enable button to create user if checked previous checkbox.
• Passwords do not match, display tooltip.
• Password is less than 8, display tooltip.
• If any of the mandatory requirements are not met, unfasten the button.
• When hovering over, display informational hover.
• When clicking register, if registration is successful, redirect to the page to sign the document.
• When clicking on register and fail, display toast informing the error and disable the button until there is a change in the data.

Confirm that everyone has signed for sign caller

Replace first and last name by displayName

Places to change:

• table libresign_file_user
• class FileUser
• class FileUserMapper
• all places that have first or last name

FAQ

Create a FAQ in the project documentation (doc directory in the project root) with possible questions/problems and the answers/solutions to these questions/problems.

Implement PATCH in webhook/request to add or change data

Required to receive the UUID of a file that has already been requested to be signed.

This route at this moment will only add new signers.

Create or reset signature password

Today the sign password is created only for new users and cannot be modified.

Frontend

• Display link to request sign password reset
• Implement flow to define sign password for those who do not have a sign password. This will make it possible for existing users of Nextcloud to have their subscription password.
  Estimate: 32h

Backend

• Endpoint to create a pfx
• Endpoint to "reset" pfx password
  Estimate: 32h

Request photos of user identification documents to validate a signature

When a person requests a signature from another person, they must have the option to tell which photo documents they want the other person to attach to validate the signature.

When someone is going to sign a document and it is necessary to attach a document, that person must choose:

• associate this document with the current document only
• Associate the document with the profile
  • Display or not the attached document name in your profile

Backend

• Create table for types of attachments that are from the system
• Create table for types of attachments required only for a single document to be signed
• When requesting a signature from a person, add an array to inform which document photos should be attached and requested when signing the document and whether these documents will need to be approved before allowing the document to be signed.
• Endpoint to save a document attached to a signature
  • Request document type and binary to be attached
  • validate the binary to only accept allowed formats
• When a person signs a document, validate that all attachments have been sent and approved
• Endpoint to approve or disapprove an attached document photo
  Estimate: 40h

Frontend

• Request photos of attached documents that are required when signing a document
• To ask:
• want to save these photos to your profile?
• Allow others to request documents that are in the profile
• Use the attached photos of documents only to sign the current document
  Estimate: 40h

Document already signed

When loading the document signature page, if the document has already been signed by the logged in user, return in the OC.appConfig variable informing that the current document has already been signed by the user.

{
     sign: true,
     errors: "['The document has already been signed by you']"
}

When loading the page read the variable and check if the document has already been signed by the logged in user, if it is already signed, disable the button to sign and display a toast with the message received by the API.

Parse \r\n in the file description.

When the file description sent by webhook contains a line break, this line break is not displayed correctly.

Check the possibility of using a markdown.

Create a widget to approve the subscription.

Implement sliding widget for signature approval. This helps to ensure that the user did not accidentally sign because it required a different interaction when signing a document and not just clicking a button.

Create password when enable account

Only when enable account is necessary create the pfx password when enable account.

The user have only one pfx file.

If the user lost the password, is necessary create a new pfx file and don't will see the previous file.

The user don't need see the pfx file.

return logged in user

Within the route / flow for user creation.
When creating the user, when successful, return the data to sign the document with the newly created user already logged in.

Change email theme

Add instructions in the documentation on how to change the subject of LibreSign emails.

Today the Nextcloud theme is used, it should be possible for administrators to define a new theme for emails.

Backend

• Set location folder to store the theme
• Use the email theme informed in the setting email_theme

Frontend

• Implement the LibreSign administrative settings field to list the existing themes and save the theme that the administrator selects in the email_theme setting.

endpoint to sign pdf

suggested route: /api/doc

method: post

payload: doc_id, password

response:

success | error messages

Error install

App "LibreSign" cannot be installed because the following dependencies are not fulfilled: The command line tool java could not be found

kann you help me?

Setup GitHub Actions

• Implement workflow to run phpunit and phpcs

Interaction with the API

Remove mocks and add API interaction for external access routes, creating users and signing documents.

• Configure check action code and redirect to new page using a code as a base.
• Create a route for Default Error page.
• In page for create users, colect data insertion and pass to api.

Configure libraries for integration and unit tests

• Configure Cypres for Integration
• Configure Jest for Units

Add setup instructions to app description

Change the info.xml file by adding a reference to the installation instructions.

resolve #120

Make it ready for NC21

NC21 will be out 22nd of February.

Implement code coverage in PHP

• create github actions to run coverage
• Add badge of coverage percentage in README.md

l10n: Singular or plural

Should the user plural be here?

libresign/lib/Service/WebhookService.php

Line 123 in 99d9ca0

throw new \Exception($this->l10n->t('Empty users collection'));

Move description from file to relation of signer and file

Actually the field description stay in file table, is necessary move to file_user to customize the description by signer.

Webhook to request pdf sing

Route: webhook/register

Request body

Format: JSON

Parameter	Type	Description
file	string	File to sign base64 encoded
users	array of User	List of users to sign file
callback	string	Callback url when a user sign file

Parameters of User object

Parameter	Type	Description
email	string	Email of user
firstName	string	optional Fist name of user
fullName	string	optional Full name of user

Response

200 Success

{
    "message": "Success"
}

403 Forbidden

A 403 response might be returned if the users ability to access webhook has been disabled by the administrator.

{
    "message": "Insufficient permissions to use API"
}

Add footer to signed PDF

Add a footer to the signed pdf containing visual data for PDF validation

GitHub Actions for frontend

• JavaScript lint
• Functional tests
• Configure Cypress for Integration Tests
• Configure Jest for Unit Tests
• Configure Coverage Report
  Estimate: 8h

Organize project

• Remove setup of a new instance of Nextcloud
• Update node and composer dependencies
• Move all files of app to root folder
• Check if unit tests are working
• Remove dependency of docker in Makefile
• Create README.md with setup instructions in root folder

Don't is necessary merge LibreSign (Signer) and DSV apps. This task will be done in the next version

Sign a doc

When the user click in sign or the application request a route to sign a specific document, is necessary show a option to view the PDF and a place to request the pfx password to sign the document.

Success case:

Check if is necessary redirect to a callback URL.
If don't exist a callback URL, the list of docs will updated and the doc will visible in signed list.

If exist a callback url is necessary redirect to that.

Endpoint to create user

Validate file using UUID

All files have a file UUID. This UUID must be printed on the PDF so that it can be used on the document validation site.

Backend

• Implement endpoint in the API to validate a UUID
  • /apps/libresign/api/0.1/file/validate/<uuid>
• Print the UUID of the file in the PDF.
• Check if there is a need to return data contained in the signed PDF in addition to the metadata saved in the system.
  Estimate: 2h

Frontend

• Request the UUID field on the validation form
• Make a request to the endpoint that returns the data of a UUID
• Display the data on the screen.
• Show link to download or view the PDF file. I don't know what the best option is
  Estimate: 2h

l10n: Question for a text string

Is this text string correct?

libresign/lib/Controller/LibresignController.php

Line 136 in b7869a1

$this->l10n->t('signed.%s', $originalFile->getExtension()),

My guess is it is because it is the name of the file with the extension, but when translating in Transifex, translators can make mistakes and add a space between signed. and %s.

I propose to separate the translation of the word signed from .%s.

l10n: Date: at or on?

Question from Transifex user:

Available at {date} or on {date} ?

Applies to this text string:

libresign/src/views/LibresignTab.vue

Line 141 in a3e3085

this.response = t('libresign', 'Signed document available at {date}', { date: response.data.fileSigned })

Send email to signers

If the signer already has an account:
Send email with link to subscribe.

If the signer doesn't have an account:
Send email notification of file to subscribe and request to create account.

Nextcloud 21.0.1: Sidebar to sign a document not available anymore

After the upgrade to nextcloud 21.0.1(stable), the app sidebar vanished.

1. Updated by web-updater
2. Disable libresign
3. Reinstall libresign app
4. Create new certificate
5. LibreSign menu and "Certificate creator" is available, but not for PDF-files to be signed.

Endpoint to request PDF metadata

Suggested route: /api/doc

method: get

payload: doc_id

response:

url to preview
callback url