@universis/signer-worker 1.1.0 → 1.6.0

package/README.md

@@ -8,7 +8,7 @@ Install `@universis/signer-worker`
 
     npm i @universis/signer-worker
 
-Important note: Verify that [Universis Signer](https://gitlab.com/universis/universis-signer) is already installed as aservice. Follow [installation instructions](https://gitlab.com/universis/universis-signer#installation) to install and configure Universis Signer.
+Important note: Verify that [Universis Signer](https://gitlab.com/universis/universis-signer) is already installed as a service. Follow [installation instructions](https://gitlab.com/universis/universis-signer#installation) to install and configure Universis Signer.
 
 ## Configuration
 
@@ -16,10 +16,129 @@ Configure [Universis api server](https://gitlab.com/universis/universis-api) to
 
     {
         "services": [
-            ...,
             {
                 "serviceType": "@universis/signer-worker#SignerWorker"
             }
         ]
-    ...
     }
+
+or configure  [Universis api server](https://gitlab.com/universis/universis-api) to use `SignerService` service.
+
+    {
+        "services": [
+            {
+                "serviceType": "@universis/signer-worker#SignerService"
+            }
+        ]
+    }
+
+## Sign documents
+
+> `SignerService.signFile(context: DataContext, file: string, contentType?: string, options?: { timestampServer?: string, position?: string, reason?: string })`
+
+`SignerService.signFile` can be used for signing *.pdf files using a server instance of [Universis Signer](https://gitlab.com/universis/universis-signer#use-docker-image)
+
+For completing sign process, the signer service instance should be configured by adding `settings/universis/signerService` section at application configuration
+
+```json
+
+{
+  "settings": {
+    "universis": {
+      "signerService": {
+        "user": "user",
+        "password": "password",
+        "host": "http://localhost:2465"
+      }
+    }
+  }
+}
+
+```
+
+where `host` is the URL of the Universis Signer service, `user` and `password` are the credentials for the Universis Signer service.
+
+Normally, the Universis Signer service which is running on `http://localhost:2465`, uses a PKCS12 store with secret key and certificate for signing.
+In this case, the `user` and `password` are used to access the PKCS12 store. `SignerService` service will try to get valid certificates, 
+and select the first one that is valid for signing. Use the configuration setting `thumbnail` if you want to explicitly define 
+the certificate that should be used for signing.
+
+```json
+{
+  "settings": {
+    "universis": {
+      "signerService": {
+        "user": "user",
+        "password": "password",
+        "host": "http://localhost:2465",
+        "thumbnail": "2d49be3b03db5d176482640549d5aaede84c925d"
+      }
+    }
+  }
+}
+``` 
+
+## Sign data
+
+> `SignerService.sign(context: DataContext, data: unknown, options?: { timestampServer?: string, reason?: string })`
+
+`SignerService.sign` method can be used for signing data. 
+The data can be any JSON-serializable object, and the method will return a signed version of the data.
+
+The `options` parameter can include a `timestampServer` URL for timestamping the signature, a `position` string to specify the position of the signature in the document, 
+and a `reason` string to specify the reason for signing.
+
+### Example
+
+```typescript
+import {SignerService} from '@universis/signer-worker';
+
+function signJson(context: DataContext, data: unknown) {
+    const signerService = context.getApplication().getService(SignerService);
+    return signerService.sign(context, data, {
+        timestampServer: "http://timestamp.server.com",
+        reason: "Signing example data"
+    });
+}
+
+signJson(context, { message: "Hello, World!" })
+    .then(signedData => {
+        console.log("Signed data:", signedData);
+    })
+    .catch(error => {
+        console.error("Error signing data:", error);
+    });
+```
+  
+## Remote Signer Worker
+
+To use the remote signer worker, you need to configure the Universis API server to use the `RemoteSignerWorker` service. This service will communicate with the Universis Signer service running on a remote server. Register `@universis/signer-worker#RemoteSignerWorker` under universis api server services section of application configuration:
+
+```json
+{
+  "services": [
+    {
+      "serviceType": "@universis/signer-worker#RemoteSignerWorker"
+    }
+  ]
+}
+```
+This will allow the Universis API server to use the remote signer worker for signing operations. The remote signer worker will handle the communication with the Universis Signer service and perform the signing operations as needed.
+
+The remote signer service host should be configured in the application settings:
+
+```json
+{
+  "settings": {
+    "universis": {
+      "remoteSignerWorker": {
+        "host": "http://remote-signer-server:8480"
+      }
+    }
+  }
+}
+```
+
+Where `host` is the URL of the remote Universis Signer service.
+
+Remote signer worker will expose the same methods under `/services/remoteSigner` as the local signer worker, allowing you to sign files and data in the same way as described above.

package/dist/RemoteSignerWorker.d.ts

@@ -0,0 +1,7 @@
+import { ApplicationBase } from '@themost/common';
+import { SignerWorker } from './SignerWorker';
+declare class RemoteSignerWorker extends SignerWorker {
+    constructor(app: ApplicationBase);
+    install(): void;
+}
+export { RemoteSignerWorker };

package/dist/SignerService.d.ts

@@ -0,0 +1,72 @@
+/// <reference types="node" />
+import { ApplicationBase, ApplicationService } from '@themost/common';
+import { ExpressDataContext } from '@themost/express';
+import { Certificate, JsonWebKey, VerifySignatureResult, SignJsonSignatureResult, SignerServiceImpl } from './SignerServiceImpl';
+import { TOTPOptions } from 'xotp';
+export declare class SignerService extends ApplicationService implements SignerServiceImpl {
+    protected options?: {
+        host?: string;
+        user?: string;
+        password?: string;
+        secret?: string;
+        thumbprint?: string;
+        inspector?: {
+            text?: string[];
+            textPosition: string;
+            width?: number;
+            height?: number;
+        };
+    };
+    constructor(app: ApplicationBase);
+    /**
+     * @param {ExpressDataContext} context The underlying data context
+     * @param {*} data The data to be verified
+     * @param {{filename: string, contentType: string}=} options Extra attributes (optional)
+     * @returns {Promise<VerifySignatureResult[]>}
+     */
+    verify(context: ExpressDataContext, data: unknown, options?: {
+        filename: string;
+        contentType: string;
+    }): Promise<VerifySignatureResult[]>;
+    getJwks(): Promise<JsonWebKey[]>;
+    getCerts(): Promise<Certificate[]>;
+    /**
+     * Generates a one-time password using the configured secret.
+     */
+    generateVerificationCode(options?: TOTPOptions): string;
+    /**
+     * @param {ExpressDataContext} context The underlying data context
+     * @param {*} data Any JSON object to be signed
+     * @param {{timestampServer?:string}} extraOptions
+     * @returns {Promise<SignJsonSignatureResult>} An array of signatures
+     */
+    sign(context: ExpressDataContext, data: unknown, extraOptions?: {
+        timestampServer?: string;
+        reason?: string;
+    }): Promise<SignJsonSignatureResult>;
+    signFile(context: ExpressDataContext, file: string, contentType?: string, extraOptions?: {
+        page?: number;
+        position?: number[];
+        timestampServer?: string;
+        reason?: string;
+    }): Promise<Buffer>;
+    verifyFile(context: ExpressDataContext, file: string, options?: {
+        filename: string;
+        contentType: string;
+    }): Promise<VerifySignatureResult[]>;
+    inspect(context: ExpressDataContext, file: string, options?: {
+        filename: string;
+        contentType: string;
+    }): Promise<{
+        page: number;
+        position: number[];
+        text: string;
+    }>;
+    requiresVerificationCode(): boolean;
+    protected signFinal<T>(context: ExpressDataContext, file: string, contentType?: string, extraOptions?: {
+        position?: number[];
+        page?: number;
+        timestampServer?: string;
+        reason?: string;
+    }): Promise<T>;
+}

package/dist/SignerServiceImpl.d.ts

@@ -0,0 +1,61 @@
+/// <reference types="node" />
+import { ExpressDataContext } from '@themost/express';
+export declare interface Certificate {
+    version: number;
+    subjectDN: string;
+    sigAlgName?: string;
+    sigAlgOID?: string;
+    issuerDN: string;
+    serialNumber: any;
+    notAfter: string;
+    notBefore: string;
+    expired: boolean;
+    thumbprint: string;
+    commonName: string;
+}
+export declare interface JsonWebKey {
+    kty: string;
+    use: string;
+    kid: string;
+    alg: string;
+    n: string;
+    e: string;
+}
+export declare interface VerifySignatureResult {
+    valid: boolean;
+    certificates: Certificate[];
+    signatureProperties?: {
+        signingDate: string;
+        reason: string;
+        signingCertificate: Certificate;
+    };
+}
+export declare interface SignJsonSignatureResult {
+    payload: string;
+    signatures: {
+        protected: string;
+        signature: string;
+    }[];
+}
+export declare interface SignerServiceImpl {
+    getCerts(): Promise<Certificate[]>;
+    getJwks(): Promise<JsonWebKey[]>;
+    verify(context: ExpressDataContext, document: string, options?: {
+        filename: string;
+        contentType: string;
+    }): Promise<VerifySignatureResult[]>;
+    verifyFile(context: ExpressDataContext, file: string, options?: {
+        filename: string;
+        contentType: string;
+    }): Promise<VerifySignatureResult[]>;
+    signFile(context: ExpressDataContext, file: string, contentType?: string, extraOptions?: {
+        page?: number;
+        position?: number[];
+        timestampServer?: string;
+        reason?: string;
+    }): Promise<Buffer>;
+    sign(context: ExpressDataContext, data: unknown, extraOptions?: {
+        timestampServer?: string;
+        reason?: string;
+    }): Promise<SignJsonSignatureResult>;
+}

package/dist/SignerWorker.d.ts

@@ -1,39 +1,26 @@
 import { ApplicationBase, ApplicationService } from '@themost/common';
+import { BehaviorSubject } from 'rxjs';
+import { Application } from 'express';
 import { ExpressDataContext } from '@themost/express';
-declare interface Certificate {
-    version: number;
-    subjectDN: string;
-    sigAlgName?: string;
-    sigAlgOID?: string;
-    issuerDN: string;
-    serialNumber: any;
-    notAfter: string;
-    notBefore: string;
-    expired: boolean;
-    thumbprint: string;
-    commonName: string;
-}
-declare interface VerifySignatureResult {
-    valid: boolean;
-    certificates: Certificate[];
-    signatureProperties?: {
-        signingDate: string;
-        reason: string;
-        signingCertificate: Certificate;
-    };
+import { VerifySignatureResult } from './SignerServiceImpl';
+export declare interface ApplicationBaseWithContainer extends ApplicationBase {
+    container?: BehaviorSubject<Application>;
 }
 export declare class SignerWorker extends ApplicationService {
+    protected options?: {
+        host?: string;
+    };
     constructor(app: ApplicationBase);
+    install(): void;
     /**
      *
      * @param {ExpressDataContext} context The underlying data context
      * @param {string} document The file path
      * @param {{filename: string, contentType: string}=} options Extra attributes (optional)
-     * @returns
+     * @returns Promise<VerifySignatureResult[]>
      */
     verify(context: ExpressDataContext, document: string, options?: {
         filename: string;
         contentType: string;
     }): Promise<VerifySignatureResult[]>;
 }
-export {};

package/dist/index.d.ts

@@ -1,2 +1,6 @@
 export * from './SignerWorker';
+export * from './SignerServiceImpl';
 export * from './signerWorkerRouter';
+export * from './SignerService';
+export * from './RemoteSignerWorker';
+export * from './remoteSignerWorkerRouter';