criptoe/dist/CripToe.ts

A simple wrapper for the crypto.subtle api. Focus on AES-GCM.

import * as _hexagon_base64 from '@hexagon/base64';

type Falsy = false | "" | 0 | null | undefined;
type False = Falsy;
type True = Truthy<true>;
declare const isTruthy: <T>(x: T | Falsy) => x is T;
type Truthy<T> = false extends T ? never : 0 extends T ? never : "" extends T ? never : null extends T ? never : undefined extends T ? never : unknown extends T ? never : T;
type Wraps<E, S, B> = E extends True ? S extends B ? S extends True ? never : ExportedWraps : S extends True ? ExportedWrapsSafeURL : B extends False ? ExportedWrapsSafeURL : S extends False ? ExportedWrapsBase64 : B extends False ? ExportedWrapsBase64 : never : E extends False ? ExportedWraps : never;
interface EncryptReturns {
    /**
     * Data encrypted and encoded to either base64, base64url or ArrayBuffer.
     **/
    readonly cipher: ArrayBuffer;
    /**
     * This is the only time the encryption key is returned.
     * It is always returned as an instance of CryptoKey.
     * If you don't want it to be available in scope, don't destructure it.
     **/
    readonly key: CryptoKey;
    /**
     * The Initial Vector, or nonce, used to salt the encryption.
     * Always returned as a Uint8Array.
     **/
    readonly initVector: BufferSource;
}
interface CripToeOptions {
    /**
     * Elicits whether the function should out put a URL safe base64 string or a regular base64 string.
     * {@see encodeUrlSafeBase64}
     * {@see decodeSafeURL}
     ***/
    export?: boolean;
    safeURL?: boolean;
    toBase64?: boolean;
}
interface EncryptReturnsSafeURL {
    /**
     * Data encrypted to Base64 with special URL characters replaced.
     **/
    readonly cipher: string;
    readonly initVector: string;
    /**
     * This is the only time the encryption key is returned.
     * It is always returned as an instance of CryptoKey.
     * If you don't want it to be available in scope, don't destructure it.
     **/
    readonly key: CryptoKey;
}
interface EncryptReturnsBase64 {
    /**
     * Data encrypted and encoded to Base64.
     **/
    readonly cipher: string;
    readonly initVector: string;
    /**
     * This is the only time the encryption key is returned.
     * It is always returned as an instance of CryptoKey.
     * If you don't want it to be available in scope, don't destructure it.
     **/
    readonly key: CryptoKey;
}
interface ExportedWraps {
    /**
     * The key used to wrap the secret key. Returned as a JSON Web Key (JWK)
     * exported and stringified.
     *
     * JWK's are shaped something like this:
     *{
     *  "crv": "P-384",
     *  "d": "wouCtU7Nw4E8_7n5C1-xBjB4xqSb_liZhYMsy8MGgxUny6Q8NCoH9xSiviwLFfK_",
     *  "ext": true,
     *  "key_ops": ["sign"],
     *  "kty": "EC",
     *  "x": "SzrRXmyI8VWFJg1dPUNbFcc9jZvjZEfH7ulKI1UkXAltd7RGWrcfFxqyGPcwu6AQ",
     *  "y": "hHUag3OvDzEr0uUQND4PXHQTXP5IDGdYhJhL-WLKjnGjQAw0rNGy5V29-aV-yseW"
     *};
     **/
    readonly wrappingKey: string;
    /**
     * The secret key returned as encrypted by the wrapping key.
     **/
    readonly wrappedKey: string | ArrayBuffer;
}
interface ExportedWrapsSafeURL extends ExportedWraps {
    /**
     * Secret key encrypted by wrapping key and converted to Base64 with special
     * URL characters replaced.
     **/
    readonly wrappedKey: Exclude<ExportedWraps["wrappedKey"], ArrayBuffer>;
}
interface ExportedWrapsBase64 extends ExportedWraps {
    /**
     * Secret Key encrypted and encoded to Base64.
     **/
    readonly wrappedKey: Exclude<ExportedWraps["wrappedKey"], ArrayBuffer>;
}

/** Provides Sha256 hashing and AES-GCM encryption and decryption of strings. For Node.*/
declare class CripToe {
    #private;
    /**
     * The message originally provided to the instance encoded into a Uint8Array.
     **/
    encoded: Uint8Array;
    /**
     * @param message - String to be encrypted or hashed.
     **/
    constructor(message: string, opts?: {
        silenceWarnings?: boolean;
    });
    fromString: typeof _hexagon_base64.fromString;
    fromArrayBuffer: typeof _hexagon_base64.fromArrayBuffer;
    toString: typeof _hexagon_base64.toString;
    toArrayBuffer: typeof _hexagon_base64.toArrayBuffer;
    validate: typeof _hexagon_base64.validate;
    /**
     * Hashes any string into a Sha256 hash. By default will hash the mesage initially provided to the constructor.
     **/
    sha256(message?: string): Promise<string>;
    /**
     * Encrypts the message into AES-GCM.
     * AES-GCM as opposed to AES-CBC or AES-CTR includes checks that the ciphertext has not been modified.
     **/
    encrypt(options?: CripToeOptions): Promise<EncryptReturns | EncryptReturnsBase64 | EncryptReturnsSafeURL>;
    /**
     * Decrypts any AES-GCM encrypted data provided you have the necessary parameters.
     *
     * @param key - The Key used to initially encrypt. {@see CripToe.cripKey}
     * @param iv - The Initialization Vector or, nonce, used to salt the encryption. Provided as base64 string.
     * @param cipher - The encrypted data to be decrypted. Provided as base64 string.
     **/
    decrypt(cipher: EncryptReturns["cipher"] | EncryptReturnsBase64["cipher"] | EncryptReturnsSafeURL["cipher"], key: EncryptReturns["key"] | EncryptReturnsBase64["key"] | EncryptReturnsSafeURL["key"], initVector: EncryptReturns["initVector"] | EncryptReturnsBase64["initVector"] | EncryptReturnsSafeURL["initVector"]): Promise<string>;
    /**
     * Takes any given, (wrapped) key and unencrypts it with a provided wrapping key. The wrapping key is expected to be in JWK format. The unwrapped key then becomes the key used to encrypt and decrypt messages. NOTE: The unwrapped key and the wrapped key are stored in the instance and never returned out of it. Except for the first time a message is encrypted.
     * @param wrappedKeyString - The key to be unwrapped. Provided as a base64 string.
     * @param wrappingKeyString - The key used to wrap the secret key. Provided as a JSON Web Key (JWK) string.
     **/
    unwrapKey(wrappedKeyString: string, wrappingKeyString: string): Promise<boolean>;
    /**
     * Wraps the key in JWK (Json Web Key) format using AES-KW. The benefit of AES-KW is that it doesn't require an Initialization Vector. See: https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/wrapKey
     * Even if this function is called multiple times the wrapped key will only be generated once.
     * Subsequent calls will simply return the originally wrapped key.
     *
     * @param wrappingKey (JWK) - The key used to wrap the secret key. If not provided, a new key will be generated.
     * @param opts - Options for exporting the wrapped key:
     * - export: boolean - Whether to export the wrapped key. Will return the wrapped key and the wrapping key in an Object:
     *   {
     *   wrappingKey: string,
     *   wrappedKey: ArrayBuffer
     *   }
     *  - safeURL: boolean - Whether to return the properties in the returned object as a special base64 encoding with special characters removed. To convert them back to standard base64 {@see CripToe.decodeUrlSafeBase64.}
     *  - toBase64: boolean - Whether to return the properties in the returned object as a standard base64 encoding. to convert them back to an ArrayBuffer @see CripToe.base64ToArrayBuffer.
     **/
    wrapKey<E, S, B>(opts?: CripToeOptions, wrappingKeyBase64?: string): Promise<Wraps<E, S, B>>;
    /**
     * The message encrypted into base64.
     **/
    get encrypted(): string;
    /**
     * The Initial Vector, or nonce, used to salt the encryption.
     **/
    get initVector(): EncryptReturns["initVector"];
    /**
     * Converts the message from base64 to an array buffer.
     **/
    get messageBuf(): string | ArrayBuffer;
    /**
     * The message originally provided to the instance for encryption.
     **/
    get message(): string;
    private CRYP;
    get random(): Uint8Array;
    static random: () => Uint8Array;
    /**The key used to encrypt and decrypt the message.**/
    private genCripKey;
}

declare function isBase64(str: string): boolean;
declare function isBase64URL(str: string): boolean;

export { type CripToeOptions, type EncryptReturns, type EncryptReturnsBase64, type EncryptReturnsSafeURL, type ExportedWraps, type ExportedWrapsBase64, type ExportedWrapsSafeURL, type False, type Falsy, type True, type Truthy, type Wraps, CripToe as default, isBase64, isBase64URL, isTruthy };