@btonasse/suitescript-types/types/N/pgp.d.ts

Typings for SuiteScript 2.1

/**
 * Use the N/pgp module to enable secure messaging, file encryption, and document signing. Based on OpenPGP encryption standards.
 * PGP stands for Pretty Good Privacy and is most commonly used for encrypting emails.
 */

import type { Signer } from "./crypto/certificate";

/** Stores general configuration options that can be used for message decryption. Use the pgp.createConfig(options) method to create a new configuration object. */
interface Config {
    /** Enables decryption that is not secured with signing keys. */
    readonly allowInsecureDecryptionWithSigningKeys: boolean;
    /** Allows messages without integrity protection. */
    readonly allowMessagesWithoutIntegrityProtection: boolean;
    /** Allows relaxed signature parsing for configuration objects. */
    readonly useRelaxedSignatureParsing: boolean;
}

/**
 * Stores multiple cryptographic keys and metadata.
 * You can use this object in the Message.decrypt(options) and MessageData.encrypt(options) methods.
 */
interface Key {
    // TODO: Nothing in the documentation?
}

/** Stores an octet scalar that identifies a (sub)key. This object is used for verification signatures. */
interface KeyId {
    /** Returns the Key ID as a hexadecimal string. */
    asHex: () => string;
}

/**
 * Stores processed PGP data. Responsible for enabling message serialization and providing a set of single-step processors to covert to a readable message.
 * Use the MessageData.toMessage() and MessageData.encrypt(options) to create a Message object.
 */
interface Message {
    /** Message type that specifies how a message is processed. Enables you to pick the appropriate method to process a message. */
    readonly type: boolean;
    /** Converts a message to ASCII armored format. */
    asArmored: () => string;
    /** Converts a pgp.Message object to message data without any processing. This method only works if the message is not encrypted. */
    toMessageData: () => MessageData;
    /** Decrypts a message and optionally verifies the signatures. */
    decrypt: (options: DecryptMessageOptions) => MessageData;
}

/**
 * Stores message data. The responsibilities of this object includes:
 * - Store message contents with meta data.
 * - Enable reading message contents and metadata.
 * - For further processing, determines whether data is text or binary.
 * - Provides a set of single-step processors for various PGP use cases.
 * Use the pgp.createMessageData(options) method to create a message data object.
 */
interface MessageData {
    readonly filename: string;
    readonly date: Date;
    readonly format: Format;
    /** Extracts the contents of the message as text. */
    getText: () => string;
    /** Creates a message with no signature, compression, or encryption. */
    toMessage: () => Message;
    /** Creates an encrypted message that is optionally signed. */
    encrypt: (options: EncryptMessageDataOptions) => Message;
}

/** Stores verification results. Use the pgp.createVerification() method to create a Verification object. */
interface Verification {
    /** Indicates whether the message verification was successful. */
    readonly verified: null | boolean;
    /** List of individual verifications, one per each signature. */
    readonly signatures: null | VerificationSignature[];
}

/** Stores a verification result for single signature. */
interface VerificationSignature {
    /** ID of the (sub)key that was used for signing. */
    readonly keyId: KeyId;
    /** Date when the message was signed. */
    readonly dateSigned: Date;
    /** Indicates whether verification was successful. */
    readonly verified: boolean;
    /** List of problems for more fine-grained decision making. */
    readonly problems: string[];
}

/** Creates a new pgp.Config object. A configuration object stores general configuration options that can be used for message decryption. */
export function createConfig(options: CreateConfigOptions): Config;

/** Creates a new pgp.MessageData object. A message data object stores message content with metadata. */
export function createMessageData(options: CreateMessageDataOptions): MessageData;

/**
 * Creates a certificate.Signer object for signing plain strings.
 * If the given PGP key contains multiple valid signing sub keys, the most recently added will be used.
 * This behavior is consistent with MessageData.encrypt(options) method.
 */
export function createSigner(options: { key: Key; algorithm: string }): Signer;

/** Creates an empty verification object. */
export function createVerification(): Verification;

/** Loads a key contents that are securely stored in a secret. */
export function loadKeyFromSecret(options: LoadKeyFromSecretOptions): Key;

/** Parses an existing PGP key. Use pgp.loadKeyFromSecret(options) to load private keys. */
export function parseKey(options: ParseKeyOptions): Key;

/** Parses a PGP message. Parameter value is ASCII armored representation of the message. */
export function parseMessage(options: { value: string }): Message;

export enum CompressionAlgorithm {
    ZLIB,
}

export enum Format {
    UTF8,
    BINARY,
}

interface CreateConfigOptions {
    /** Enables decryption that is not secured with signing keys. Default value is false. */
    allowInsecureDecryptionWithSigningKeys?: boolean;
    /** Allows messages without integrity protection. Default value is false. */
    allowMessagesWithoutIntegrityProtection?: boolean;
    /** Allows relaxed signature parsing for configuration objects. Default value is false. */
    useRelaxedSignatureParsing?: boolean;
}

interface CreateMessageDataOptions {
    /** Content of the message. */
    content: string;
    /** File name if the message represents a file, empty string otherwise. */
    filename?: string;
    /** Date of the message or modification date of the file. Default value = new Date(). */
    date?: Date;
    /** Literal data packet type. Default value = Format.UTF8, if content is a string. Format.BINARY otherwise. */
    format?: Format;
}

interface DecryptMessageOptions {
    /** Uses one or more keys to attempt message decryption. */
    decryptionKeys: Key | Key[];
    /**
     * Uses zero or more keys to attempt message signature verification. If you do not provide a verification key, the message's signature (if any) will be ignored.
     * If you do provide a verification key, at least one signature must be verifiable by one of the provided keys, otherwise an error will be thrown.
     * An expired key works if the signature was made before the expiration. Default value = [].
     */
    verificationKeys?: Key | Key[];
    /** An empty verification object. If you provide a value for this parameter, the verification results will be flushed instead of throwing an error for invalid signature. Default value = null. */
    verification?: Verification;
    /** If set to true, the verification errors will not be thrown. This value is implicitly set to true when the verification parameter is provided. Default value = false. */
    suppressVerificationErrors?: boolean;
    /** The configuration. Default value is pgp.createConfig(options). */
    config?: Config;
}

interface EncryptMessageDataOptions {
    /** One or more keys used to encrypt a message. If a key contains multiple valid encryption (sub)keys, the most recent key added will be used. */
    encryptionKeys: Key | Key[];
    /** Zero or more keys used for signing. If a key contains multiple valid signing (sub)keys, the most recent key added will be used. Default value = []. */
    signingKeys?: Key | Key[];
    /** The compression algorithm to use. Default value = CompressionAlgorithm.ZLIB. */
    compressionAlgorithm?: CompressionAlgorithm;
}

interface LoadKeyFromSecretOptions {
    /** Secret that contains a PGP key in ASCII armored format. */
    secret: { scriptId: string };
    /** Secret that contains a password to unlock the key. Applicable for private keys. */
    password?: { scriptId: string };
}

interface ParseKeyOptions {
    /** ASCII armored key */
    value: string;
    /** Password to unlock the key. Applicable for private keys. */
    password?: string;
}