autogram-sdk
Version:
SDK for Autogram signer
404 lines (401 loc) • 20 kB
TypeScript
interface components {
schemas: {
Info: {
/** @example 1.2.3 */
version?: string;
/** @enum {string} */
status?: "READY";
};
SignRequestBody: {
/**
* @description Optional identifier of the batch.
* If not provided, document will be signed as single standalone document.
* If provided, document will be signed inside batch.
*
* @example 0c62536c-f43f-4302-b8f0-e2ad521c8175
*/
batchId?: string;
document: components["schemas"]["Document"];
parameters: components["schemas"]["SignatureParameters"];
/**
* @description MIME type for document content and signature parameters like transformation and schema.
* Binary files should be encoded using base64, e.g., `application/pdf;base64`.
* Text formats like XML can be optionally encoded using base64 but can be supplied as plain text as seen in the examples, in which case the type is `application/xml`.
*
* @example application/xml
*/
payloadMimeType: string;
};
Document: {
/**
* @description Filename of the original file to be signed. Is used to name the file inside ASiC container. If not provided with ASiC container, the file is named `detached-file` inside the container.
* @example document.xml
*/
filename?: string;
/**
* @description Content of the document to sign, format is dictated by `payloadMimeType`.
* @example <?xml version="1.0"?><Document><Title>Lorem Ipsum</Title></Document>
*/
content: string;
};
SignResponseBody: {
/**
* @description Signed content of the original document in Base64 format.
* @example TWFueSBoYW5kcyBtYWtlIGxpZ2h0IHdvQDSdd57FueSBoYW5kcyBtYWtlIGxpZ2h0IHdvsRWdaAeSBoYW5kcyBtYW==
*/
content: string;
/**
* @description Distinguished name of the certificate used/attempting to sign the document.
* @example SERIALNUMBER=PNOSK-1234567890, C=SK, L=Bratislava, SURNAME=Smith, GIVENNAME=John, CN=John Smith
*/
signedBy: string;
/**
* @description Distinguished name of the issuer of the certificate used/attempting to sign the document.
* @example CN=SVK eID ACA2, O=Disig a.s., OID.2.5.4.97=NTRSK-12345678, L=Bratislava, C=SK
*/
issuedBy: string;
};
BatchStartRequestBody: {
/**
* @description Total number of documents in the batch. Used to calculate the progress of the batch.
* @example 500
*/
totalNumberOfDocuments?: number;
};
BatchStartResponseBody: {
/**
* @description Identifier of the batch. Used to identify the batch for signing and ending batch.
* @example 0c62536c-f43f-4302-b8f0-e2ad521c8175
*/
batchId?: string;
};
BatchEndRequestBody: {
/**
* @description Identifier of the batch.
* @example 0c62536c-f43f-4302-b8f0-e2ad521c8175
*/
batchId?: string;
};
BatchEndResponseBody: {
/** @enum {enum} */
status?: "FINISHED" | "NOT_FINISHED";
};
SignatureParameters: {
/**
* @description Check for PDF/A compliance and show warning if not compliant.
* @default false
*/
checkPDFACompliance?: boolean;
/**
* @description Try to find XSD and XSLT for a given eForm and load them automatically. Useful for visualizing and signing eForms. If true, schema, transformation, conatinerXmlns, container, packaging, and identifier parameters are ignored. If resources are not found, the response is 422. If provided document is an ASiC_E container conatining XML Datacontainer or it is an XML Datacontainer itself, XSLT found is used for visualiztion of signing document. Also, XSD and XSLT hashes are compared with hashes of XSD and XSLT found in XML Data Container EForm. If they differ, the response is 422. If the provided document is an XML document, Autogram will try to parse xmlns from root element and find resources based on its value. If successful, XML Datacontainer with xmls="http://data.gov.sk/def/container/xmldatacontainer+xml/1.1" is created, the document is validated against the XSD and visualized using the XSLT. If XSD validation fails, the response is 422. The XSLT transformation is found based on transformationLanguage (defaults to user preferred), transformationMediaDestinationTypeDescription (default XHTML, then HTML, then TXT), and transformationTargetEnvironment. If multiple transformations meet the criteria, the first one found is used.
* @default false
*/
autoLoadEform?: boolean;
/**
* @description Signature format PAdES is usable only with documents of type `application/pdf`. Format XAdES is usable with XML or with any file type if using an ASiC container.
* @example XAdES_BASELINE_B
* @enum {string}
*/
level: "XAdES_BASELINE_B" | "PAdES_BASELINE_B" | "CAdES_BASELINE_B";
/**
* @description Optional container type that should be used to place the file with signature to. Defaults to null. Is ignored with autoLoadEform true.
* @example ASiC_E
* @enum {string}
*/
container?: "ASiC_E";
/**
* @description XML namespace for the XML Datacontainer. Specifies if xmldatacontainer should be created from XML. Doesn't create xmldatacontainer if payloadMimeType is application/vnd.gov.sk.xmldatacontainer+xml already. Accepts http://data.gov.sk/def/container/xmldatacontainer+xml/1.1 only. Defaults to null. Is ignored with autoLoadEform true.
* @example http://data.gov.sk/def/container/xmldatacontainer+xml/1.1
* @enum {string}
*/
containerXmlns?: "http://data.gov.sk/def/container/xmldatacontainer+xml/1.1";
/**
* @description When creating XML Datacontainer, parameter indicates whether to embed XSD and XML or reference them. Practically this should be only used for ORSR EForms in which case (when identifier contains "justice.gov.sk/Forms") this parameter is overridden to true.
* @example false
*/
embedUsedSchemas?: boolean;
/**
* @description Optional identifier of the document template. Required if containerXmlns is http://data.gov.sk/def/container/xmldatacontainer+xml/1.1. Defaults to null. Is ignored with autoLoadEform true.
* @example https://data.gov.sk/id/egov/eform/App.GeneralAgenda/1.9
*/
identifier?: string;
/**
* @description Optional form of packaging used with XML. ENVELOPED adds the signature as a child of the root element while ENVELOPING wraps the XML in a new element. Only applies to XAdES signatures. Must be ENVELOPING when used without ASiC container and with non XML documents. Is ignored with autoLoadEform true.
* @default ENVELOPED
* @enum {string}
*/
packaging?: "ENVELOPED" | "ENVELOPING";
/**
* @description Optional algorithm used to calculate digests.
* @default SHA256
* @enum {string}
*/
digestAlgorithm?: "SHA256" | "SHA384" | "SHA512";
/**
* @description Optional flag to control whether the signature should be made according to ETSI EN 319132 for XAdES and ETSI EN 319122 for CAdES and PAdES.
* @default false
*/
en319132?: boolean;
/**
* @description Optional info canonicalization method.
* @default INCLUSIVE
* @enum {string}
*/
infoCanonicalization?: "INCLUSIVE" | "EXCLUSIVE" | "INCLUSIVE_WITH_COMMENTS" | "EXCLUSIVE_WITH_COMMENTS" | "INCLUSIVE_11" | "INCLUSIVE_11_WITH_COMMENTS";
/**
* @description Optional properties canonicalization method.
* @default INCLUSIVE
* @enum {string}
*/
propertiesCanonicalization?: "INCLUSIVE" | "EXCLUSIVE" | "INCLUSIVE_WITH_COMMENTS" | "EXCLUSIVE_WITH_COMMENTS" | "INCLUSIVE_11" | "INCLUSIVE_11_WITH_COMMENTS";
/**
* @description Optional key info canonicalization method.
* @default INCLUSIVE
* @enum {string}
*/
keyInfoCanonicalization?: "INCLUSIVE" | "EXCLUSIVE" | "INCLUSIVE_WITH_COMMENTS" | "EXCLUSIVE_WITH_COMMENTS" | "INCLUSIVE_11" | "INCLUSIVE_11_WITH_COMMENTS";
/**
* @description Optional XML schema used to validate the signing document and to compute digest used in "UsedXSDReference" in "DigestValue" attribute inside created XML Datacontainer. Format (plaintext or base64) is dictated by `payloadMimeType`. Is ignored with autoLoadEform true.
* @example <?xml version="1.0"?><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"><xs:element name="Document"><xs:complexType><xs:sequence><xs:element name="Title" type="xs:string" /></xs:sequence></xs:complexType></xs:element></xs:schema>
*/
schema?: string;
/**
* @description Optional identifier of the XML schema. The value is used in "UsedXSDReference" field inside created XML Datacontainer. If provided with autoLoadEform true, Autogram will try to find such schema. Default value is "http://schemas.gov.sk/form/<form-idnetifier>/<version>/form.xsd".
* @example http://schemas.gov.sk/form/App.GeneralAgenda/1.9/form.xsd
*/
schemaIdentifier?: string;
/**
* @description Optional XML transformation used to present the signing document to user and to compute digest used in "UsedPresentationSchemaReference" in "DigestValue" attribute inside created XML Datacontainer. Format (plaintext or base64) is dictated by `payloadMimeType`. Is ignored with autoLoadEform true.
* @example <?xml version="1.0"?><xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"><xsl:template match = "/"><h1><xsl:value-of select="/Document/Title"/></h1></xsl:template></xsl:stylesheet>
*/
transformation?: string;
/**
* @description Optional identifier of the XML transformation. If provided with autoLoadEform true, Autogram will try to find such transformation. Default value is "http://schemas.gov.sk/form/<form-idnetifier>/<version>/form.xslt".
* @example http://schemas.gov.sk/form/App.GeneralAgenda/1.9/form.xslt
*/
transformationIdentifier?: string;
/**
* @description Optional language of the XML transformation. If autoLoadEform is true, Autogram will try to find signing XSLT with this language. Otherwise transformation must be provided. Default value is user preferred or "sk".
* @example sk
*/
transformationLanguage?: string;
/**
* @description Optional media destination type description of the XML transformation. If autoLoadEform is true, Autogram will try to find signing XSLT with this type. Otherwise transformation must be provided. Overrides value of the output method in provided or auto-loaded transformation which is used by default.
* @example HTML
* @enum {string}
*/
transformationMediaDestinationTypeDescription?: "XHTML" | "HTML" | "TXT";
/**
* @description Optional target environment of the XML transformation. If autoLoadEform is true, Autogram will try to find signing XSLT with this target. Otherwise transformation must be provided. Null and not used by default.
* @example example-value
*/
transformationTargetEnvironment?: string;
/**
* @description Optional width of the signing document visualization. Values are sm (640px), md (768px), lg (1024px), xl (1280px), xxl (1536px). The minimum visualization width is set to 640px. If the preferred visualization width is exceeds width of client's screen, the visualization width is set to the width of the client's screen.
* @default sm
* @enum {string}
*/
visualizationWidth?: "sm" | "md" | "lg" | "xl" | "xxl";
};
};
responses: never;
parameters: never;
requestBodies: never;
headers: never;
pathItems: never;
}
/**
* Octosign White Label API client for the app running in the server mode.
*
* ### Example (es module and async/await)
* ```js
* import { apiClient } from '@octosign/client';
* const client = apiClient();
*
* // Launch URL that should be used by user to launch the signer application
* console.log(client.getLaunchURL());
*
* await client.waitForStatus('READY');
*
* const content = '<?xml version="1.0"?><Document><Title>Lorem Ipsum</Title></Document>';
* console.log(await client.sign({ content }));
* // => { content: '<?xml version="1.0"?><Document><Title>Lorem Ipsum</Title>...</Document>' }
* ```
*
* All further examples use es module and async/await, but the library can be also used as commonjs module and using promises.
*
* ### Example (commonjs and promises)
* ```js
* var apiClient = require('@octosign/client').apiClient;
* var client = apiClient();
*
* console.log(client.getLaunchURL());
*
* client.waitForStatus('READY')
* .then(function() {
* var content = '<?xml version="1.0"?><Document><Title>Lorem Ipsum</Title></Document>';
* return client.sign({ content: content });
* })
* .then(function(signedDocument) {
* console.log(signedDocument);
* // => { content: '<?xml version="1.0"?><Document><Title>Lorem Ipsum</Title>...signature...</Document>' }
* });
* ```
*
* @returns An instance of API client.
*/
declare function apiClient(options?: ApiClientConfiguration): {
/**
* Construct custom protocol launch URI that can be opened by user to launch the application.
*
* ### Example
* ```js
* import { apiClient } from '@octosign/client';
* const client = apiClient();
* console.log(client.createLaunchURI());
* // => autogram://listen/37200/https%3A%2F%2Fexample.com/3a2bca8d73c62e75177fa877de283cc0c96cdf3ba08f8eb878a96da93de3d798/260372071
* ```
*
* @returns URL that can be opened by the user.
*/
getLaunchURL(command?: "listen"): string;
/**
* Retrieve server info with its current state.
*
* ### Example
* ```js
* import { apiClient } from '@octosign/client';
* const client = apiClient();
* console.log(await client.info());
* // => { version: '1.2.3', status: 'READY' }
* ```
*
* @returns Info about the server and its current state.
*/
info(): Promise<ServerInfo>;
/**
* Wait for server to be in the requested state.
*
* Repeatedly tries to get server info retrying
*
* ### Example
* ```js
* import { apiClient } from '@octosign/client';
* const client = apiClient();
* await client.waitForStatus('READY');
* // => { version: '1.2.3', status: 'READY' }
* ```
*
* @param status - Wanted status of the server.
* @param timeout - Timeout in seconds before giving up and rejecting with error.
* @param delay - Delay before making next attempt after failure.
* @returns Info about the server and its current state.
*/
waitForStatus(status: ServerInfo["status"], timeout?: number, delay?: number, abortController?: AbortController): Promise<ServerInfo>;
/**
* Sign a document.
*
* ### Example
* ```js
* import { apiClient } from '@octosign/client';
* const client = apiClient();
*
* console.log(await client.sign({ content: '<?xml version="1.0"?><Document><Title>Lorem Ipsum</Title></Document>' }));
* // => { content: '...signed document...' }
* ```
*
* @param signatureParameters - Optional signature parameters.
* @param payloadMimeType - Optional payload mime type, defaults to `'application/xml'` - plaintext XML. Must reflect document content type so should be changed if content is not a plaintext XML.
* @returns Signed document.
*/
sign(document: AutogramDocument, signatureParameters?: SignatureParameters, payloadMimeType?: string): Promise<SignResponseBody>;
};
/**
* Client configuration options.
*/
type ApiClientConfiguration = {
/**
* Protocol of the server - Octosign White Label
*
* Defaults to `'http'`
*/
readonly serverProtocol?: "http" | "https";
/**
* Host of the server - Octosign White Label
*
* Defaults to `'127.0.0.1'`
*/
readonly serverHost?: string;
/**
* Port of the server - Octosign White Label
*
* Influences also the URL generated to launch the application.
*
* Defaults to `37200`
*/
readonly serverPort?: number;
/**
* Custom protocol used with the application, e.g., to launch it - `signer://listen`.
*
* Defaults to `'signer'`.
*/
readonly customProtocol?: string;
/**
* Disables using of HMAC in messages and sets `requestsOrigin` to *
*
* Make sure you understand the implications on the security!
*
* Defaults to `false`.
*/
readonly disableSecurity?: boolean;
/**
* Origin the server will be asked to trust
*
* Influences generated launch URL that sets trusted origin
*
* Defaults to the current location origin, e.g. `'https://example.com'` if available, `'*'` otherwise.
*/
readonly requestsOrigin?: string;
/**
* Secret key used for the communication.
*
* Should be cryptographically secure random hex string generated separately for each session.
* You can generate this key on the server side and set it on the session so its reused across navigation.
* There is no need to configure this unless you know what you are doing.
*
* Defaults to random 64-char (256-bit) hex string generated on instantiation.
*/
readonly secretKey?: string;
/**
* Secret initial nonce used for the communication.
*
* Should be cryptographically secure random 32-bit integer generated separately for each session.
* You can generate this number on the server side and set it on the session so its reused across navigation.
* There is no need to configure this unless you know what you are doing.
*
* Defaults to random integer generated on instantiation.
*/
readonly secretInitialNonce?: number;
/**
*
* Language of interface used
*
*/
readonly language?: "sk";
};
/**
* Info about the server and its current state.
*/
type ServerInfo = components["schemas"]["Info"];
/**
* Document exchanged during the signing.
*/
type AutogramDocument = components["schemas"]["Document"];
/**
* Parameters used to create a signature.
*/
type SignatureParameters = components["schemas"]["SignatureParameters"];
type SignResponseBody = components["schemas"]["SignResponseBody"];
declare class UserCancelledSigningException {
}
export { type ApiClientConfiguration, type AutogramDocument, type ServerInfo, type SignResponseBody, type SignatureParameters, UserCancelledSigningException, apiClient };