@vchasno/signer 1.0.0

package/README.md

@@ -0,0 +1,156 @@
+# Vchasno Signer
+
+Library to work with private keys, sign data and verify signatures.
+(@evo/vchasno-signer => @vchasno/signer)
+
+# Instalation
+
+```
+npm install @vchasno/signer
+```
+
+# Usage
+
+```javascript
+import vchasnoSigner from '@vchasno/signer';
+
+// Minimal config for signer, more details you can find in config object section
+const configObject = { proxyServiceUrl: '/internal-api/proxy' };
+
+// Initialize signer
+await vchasnoSigner.init(configObject);
+
+// Read private key
+const key = await vchasnoSigner.readKey(keyFile, password, caServerIdx, certificateFiles);
+
+// Sign data
+const eSign = vchasnoSigner.signData(data, key);
+
+// Verify signature
+const signInfo = vchasnoSigner.verifySign(data, eSign);
+```
+
+## Config object
+
+```javascript
+{
+    // Allow to use only power certificates, default is true
+    checkIsPowerCertificate: true,
+    // Download internal sign library from specific url. If not specified, library
+    // will be downloaded from Vchasno servers
+    downloadSignLibraryUrl: null,
+    // Max data size to work with in bytes, library will take 10x size in memory.
+    // *Implicit* default value is 5Mb for desktop and 2Mb for mobile
+    maxFileSize: undefined,
+    // By default path to library is `/js/lib/iit`, but you can specify your own path
+    pathToLibrary: '/path/to/library',
+    // To work library need proxy service in your backend.
+    // Library send a POST request to proxy service url with address in GET parameter
+    // and data string in body. Backend needs to make a request to this address with
+    // data string and return received data to the library
+    proxyServiceUrl: '/internal-api/proxy',
+    // By default library will use Web Workers if supported, but you can force it
+    // by setting useMainThread = true
+    useMainThread: false,
+}
+```
+
+## Read private key
+
+Read PK file to get key object with PK content, associated certificates, information about PK and actual certificate.
+
+Parameters:
+
+- `keyFile`: PK file in `Blob` format
+- `password`: PK password
+- `caServerIdx`: PK vendor, you can get list of supported CA servers with `getCAServers` function
+- `certificateFiles`: optional parameter, some CA use certificates from file, so we need to pass PK file and associated certificates file/files. You can use `getCAServerSettings` function to find out which certificates type are used.
+
+```javascript
+// List of supported CA servers
+const caServers = vchasnoSigner.getCAServers();
+
+// CA server settings
+const caServerSettings = vchasnoSigner.getCAServerSettings(caServers[idx]);
+caServerSettings.loadCertsFromFile;  // true - need to pass associated certificates, false - certificates will be found in CA servers
+
+// Read PK
+const key = await vchasnoSigner.readKey(keyFile, password, caServerIdx, certificateFiles);
+key.keyData //content of PK
+key.password //PK password
+key.certificates //PK associated certificates
+key.keyInfo //information about PK owner
+key.certificateInfo //information about actual associated certificate
+```
+
+## Sign data
+
+Sign data with PK, verify signature and return signature object.
+
+Parameters:
+
+- `data`: data to sign in `Blob`, `ArrayBuffer`, or `Uint8Array` format
+- `key`: key object from `readKey` function
+
+```javascript
+const eSign = vchasnoSigner.signData(data, key);
+```
+
+Also data can be signed internaly in p7s container
+
+```javascript
+const [eSign, p7s] = vchasnoSigner.signDataInternal(data, key);
+```
+
+## Verify signature
+
+Verify association between data and signature, return information about signature.
+
+Parameters:
+
+- `data`: data to sign in `Blob`, `ArrayBuffer` or `Uint8Array` format
+- `eSign`: signature string from `signData` function
+
+```javascript
+const signInfo = vchasnoSigner.verifySign(data, eSign);
+```
+
+For internal signatures need to pass only p7s container.
+
+Parameters:
+
+- `p7s`: p7s container from `signDataInternal` function
+
+```javascript
+const signInfo = vchasnoSigner.verifySignInternal(p7s);
+```
+
+# For library developers
+
+## Autodeploy
+
+To deploy new version:
+
+```
+npm version <patch|minor|major>
+git push origin --atomic HEAD v0.0.1
+```
+
+## Update certificates
+
+1. Update CAs.json, CACertificates
+    - Docker with [just](https://github.com/casey/just)
+      ```
+      # buid container if needed
+      just docker-build-image
+      # update certificates
+      just docker-update-ca-servers
+      ```
+    - Node
+      ```
+      wget --output-document ./scripts/rawCAs.json https://iit.com.ua/download/productfiles/CAs.json
+      wget --output-document ./src/files/CACertificates.p7b https://iit.com.ua/download/productfiles/CACertificates.p7b
+
+      node scripts/generateCAServers.js
+      ```
+2. [Add new tag](https://gitlab.vchasno.com.ua/libs/signerjs/-/tags)

package/docker/entrypoint.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+set -euo pipefail
+
+NPM_RC_FILE="/build/.npmrc"
+
+# Check if NPM_TOKEN is set and not empty string
+if [ -n "${NPM_TOKEN:-}" ]; then
+    echo "Found NPM_TOKEN. Configuring registry authentication..."
+    echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > "$NPM_RC_FILE"
+else
+    echo "Notice: NPM_TOKEN is not set. Proceeding without configuring npm authentication."
+fi
+
+# Execute the passed command
+exec "$@"

package/index.d.ts

@@ -0,0 +1,210 @@
+// Type definitions for @vchasno/signer
+// Project: https://vchasno.ua
+// Definitions by: vchasno
+
+export = VchasnoSigner;
+export as namespace VchasnoSigner;
+
+declare namespace VchasnoSigner {
+    interface VchasnoSignerConfig {
+        /**
+         * Sign library need proxy service to work, specify it here
+         */
+        proxyServiceUrl: string;
+        /**
+        * Allow to use only power certificates
+        */
+        checkIsPowerCertificate?: boolean;
+        /**
+        * download sign library from specific url
+        */
+        downloadSignLibraryUrl?: string;
+        /**
+         * Max data size to work with in bytes, library will take 10x size in memory
+         */
+        maxFileSize?: number;
+        /**
+         * Path to sign library files
+         */
+        pathToLibrary?: string;
+        /**
+         * Version helps to avoid CDN library file caching.
+         */
+        libraryVersion?: string;
+        /**
+         * By default, library will use Web Workers if supported
+         */
+        useMainThread?: boolean;
+        /**
+         * By default, library will use CAdES-BES (1)
+         */
+        signType?: number;
+        /**
+         * Add properties for setting with SetRuntimeParameter
+         */
+        runtimeParameters?: Record<string, string | boolean | number>;
+    }
+
+    interface CaServer {
+        name: string;
+        issuerCNs: string;
+        address: string;
+        ocspAccessPointAddress: string;
+        ocspAccessPointPort: string;
+        cmpAddress: string;
+        tspAddress: string;
+        tspAddressPort: string;
+        certsInKey?: boolean;
+    }
+    interface CaServerSetting {
+        offline: boolean;
+        useCMP: boolean;
+        loadCertsFromFile: boolean;
+    }
+
+    interface JksKey {
+        privateKeyName: string;
+        subjectName: string;
+        keyData: Uint8Array;
+        certificates: Uint8Array[];
+    }
+    interface Key {
+        keyData: Uint8Array;
+        password: string;
+        certificates: Uint8Array;
+        keyInfo: KeyInfo;
+        certificateInfo: CertificateInfo;
+    }
+    interface KeyCtx {
+        keyContextId: string;
+        keyInfo: KeyInfo;
+        certificateInfo: CertificateInfo;
+    }
+    interface KeyCtxCAIdx extends KeyCtx {
+        caServerIdx: number
+    }
+    interface CertificateInfo {
+        publicKeyID: string;
+        isPowerCert: boolean;
+        isStamp: boolean;
+        certBeginDate: Date;
+        certEndDate: Date;
+        keyBeginDate: Date;
+        keyEndDate: Date;
+        state: string;
+        locality: string;
+    }
+    interface KeyInfo {
+        isLegal: boolean;
+        edrpou: string;
+        drfo: string | null;
+        caServer: string;
+        companyName: string;
+        ownerFullName: string;
+        ownerPosition: string;
+        serialNumber: string;
+    }
+
+    interface Signature {
+        keyType: string;
+        eds: string;
+        edsInfo: SignatureInfo;
+    }
+    interface SignatureInfo extends KeyInfo {
+        timemark: string;
+        data?: Uint8Array;
+    }
+
+    interface ReceiptResult {
+        receiptNumber: string | null;
+        initiators: string[];
+        receiptData: Uint8Array;
+    }
+
+    interface GeneratedKeyData {
+        privateKeyName: string;
+        privateKey: Uint8Array;
+        uaRequestName: string;
+        uaRequest: Uint8Array;
+        uaKEPRequestName: string;
+        uaKEPRequest: Uint8Array;
+    }
+
+    // Not the best typings, but it's better than nothing
+    interface GeneratedKeyDataExt {
+        privateKeyName: string;
+        privateKeyInfoName: string;
+        privateKey: Uint8Array;
+        privateKeyInfo: Uint8Array;
+        intRequest: Uint8Array | null;
+        intRequestName: string | null;
+        uaKEPRequest: Uint8Array | null;
+        uaKEPRequestName: string | null;
+        uaRequest: Uint8Array | null;
+        uaRequestName: string | null;
+    }
+
+    interface SessionData {
+        session: string;
+        authData: Uint8Array;
+    }
+
+    type Data = Blob | ArrayBuffer | Uint8Array;
+
+    function base64Encode(data: Uint8Array): Promise<string>;
+    function base64Decode(data: string): Promise<Uint8Array>;
+    function clearKeyCtx(keyContextId: string): Promise<void>;
+    function clearKeysCtx(): Promise<void>;
+    function generatePrivateKey(pkPassword: string, isStamp: boolean): Promise<GeneratedKeyData>;
+    function generatePrivateKeyExt(pkPassword: string, params?: Partial<{
+        uaKeysType: number,
+        uaDSKeysSpec: number,
+        useDSKeyAsKEP: boolean,
+        uaKepSpec: number,
+        intKeysType: number,
+        intKeysSpec: number,
+        userInfo: unknown,
+        extKeyUsages: string,
+    }>): Promise<GeneratedKeyDataExt>;
+    function getCAServers(): Promise<CaServer[]>;
+    function getCAServerSettings(caServer: CaServer): Promise<CaServerSetting>;
+    function getRootCertificates(enableTestCertificates?: boolean): Uint8Array;
+    function init(inputConfig: VchasnoSignerConfig): Promise<void>;
+    function protectData(data: string): Promise<string>;
+    function protectReport(
+        reportData: Data,
+        recipientCert: Blob,
+        senderEmail: string,
+        reportName: string,
+        directorPKey: KeyCtx | null,
+        accountantPKey: KeyCtx | null,
+        stampPKey: KeyCtx | null,
+    ): Promise<Uint8Array>;
+    function envelopDataCtx(
+        data: Data,
+        recipientCert: Blob,
+        key: KeyCtx,
+        asBase64String: boolean | null,
+    ): Promise<Uint8Array | String>;
+    function developDataCtx(data: Data, recipientCert: Blob, key: KeyCtx): Promise<Uint8Array>;
+    function unprotectReceipt(reportData: Data, key: KeyCtx): Promise<ReceiptResult>;
+    function readJksFile(keyFile: Blob): Promise<JksKey[]>;
+    function readJksKeyCtx(keyData: Uint8Array, certificates: Uint8Array[], password: string, caServerIdx: number): Promise<Key>;
+    function readKey(keyFile: Blob, password: string, caServerIdx: number, certificateFiles?: FileList): Promise<Key>;
+    function readKeyCtx(keyFile: Blob, password: string, caServerIdx: number, certificateFiles?: FileList): Promise<KeyCtx>;
+    function readPKKeyCtxWithCMP(keyFile: Blob, password: string): Promise<KeyCtxCAIdx>;
+    function signData(data: Data, keys: Key | Key[]): Promise<Signature | Signature[]>;
+    function signDataCtx(data: Data): Promise<Signature[]>;
+    function signDataInternal(data: Data, keys: Key | Key[]): Promise<[Signature | Signature[], Data]>;
+    function signDataInternalCtx(data: Data): Promise<[Signature[], Data]>;
+    function signDataInternalAppendedCtx(data: Data): Promise<[Signature[], Data]>;
+    function signHashCtx(data: string): Promise<Signature[]>;
+    function signDataDFS(data: Blob | ArrayBuffer, signKeys: Key[], cypherKey: Key[]): Promise<[Signature[], Data]>;
+    function unprotectData(data: string): Promise<string>;
+    function verifySign(data: Data, eSign: Signature): Promise<SignatureInfo>;
+    function verifySignInternal(p7s: Data, withData: boolean): Promise<SignatureInfo>;
+    function createClientSession(duration: number, certificate: Uint8Array): Promise<SessionData>;
+    function sessionEncrypt(data: Uint8Array | string, asBase64String?: boolean): Promise<Uint8Array | string>;
+    function sessionDecrypt(data: Uint8Array | string): Promise<Uint8Array>;
+    function hashData(data: Uint8Array | string, asBase64String?: boolean): Promise<Uint8Array | string>;
+}

package/justfile

@@ -0,0 +1,23 @@
+TAG := 'vchasno-signer'
+
+# Build the docker image
+docker-build-image:
+    docker build -t {{TAG}} . --target dev
+
+# Update certificates inside docker
+docker-generate-ca-servers:
+    wget --output-document ./scripts/rawCAs.json https://iit.com.ua/download/productfiles/CAs.json
+    wget --output-document ./src/files/CACertificates.p7b https://iit.com.ua/download/productfiles/CACertificates.p7b
+    docker run --rm -v $(pwd):/build {{TAG}} node /build/scripts/generateCAServers.js
+
+docker-update-ca-servers: docker-generate-ca-servers
+    docker run --rm -v $(pwd):/build {{TAG}} node /build/scripts/versionBump.js
+
+
+# Run the tests inside docker. Consider using docker-build-image first
+docker-test:
+    docker run --rm {{TAG}} npm run test
+
+# Run the linter inside docker. Consider using docker-build-image first
+docker-lint:
+    docker run --rm {{TAG}} npm run lint