@rezwanul7/secret-vault 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,222 @@
+/** Options for building a {@link Vault}. */
+interface VaultOptions {
+    /**
+     * The current Vault secret, which seals every new value. At least 32
+     * characters of high-entropy key material, such as the output of
+     * `openssl rand -base64 32`.
+     */
+    secret: string;
+    /**
+     * Earlier Vault secrets, still accepted when opening Sealed values but never
+     * used to seal new ones. During a Rotation, move the old `secret` here until
+     * every value sealed with it has been re-sealed with {@link Vault.reseal}.
+     * Each must be at least 32 characters. A secret listed twice (here or
+     * alongside `secret`) is a {@link VaultConfigError}, reported by the first
+     * call that needs keys rather than by the constructor.
+     */
+    previousSecrets?: readonly string[];
+    /**
+     * The name of this Vault, such as `myapp:settings`. Vaults with the same
+     * Vault secret but different Purposes can't read each other's Sealed
+     * values. It must never change once values are stored.
+     */
+    purpose: string;
+}
+/**
+ * Turns Plaintexts into Sealed values and back, with AES-256-GCM on Web
+ * Crypto. Build one per Purpose, at module level, and reuse it.
+ *
+ * Every method that seals or opens takes a Context: where the Sealed value is
+ * stored, such as `settings:smtp_pass`. A Sealed value only opens under the
+ * Context it was sealed with. `""` is allowed and means no binding.
+ *
+ * @example
+ * const vault = new Vault({ secret: process.env.VAULT_SECRET!, purpose: "myapp:settings" });
+ * const sealed = await vault.encrypt("hunter2", "settings:smtp_pass");
+ * await vault.decrypt(sealed, "settings:smtp_pass"); // "hunter2"
+ */
+declare class Vault {
+    #private;
+    /**
+     * Checks the options right away; keys are derived on first use, so this
+     * needs no `await`.
+     *
+     * @param options - The Vault secrets and Purpose.
+     * @throws {@link VaultConfigError} when an option breaks a rule in
+     * {@link VaultOptions}, except a duplicated secret, which is reported on
+     * first use. The message never contains a secret.
+     */
+    constructor(options: VaultOptions);
+    /**
+     * True when `value` is a Sealed value: a string starting with `vault:`. Use
+     * it to tell Sealed values from plain text still stored in a column.
+     *
+     * @param value - Any value.
+     */
+    static isSealed(value: unknown): value is string;
+    /**
+     * Seals a string.
+     *
+     * @param plaintext - The string to seal. May be empty.
+     * @param context - Where the Sealed value is stored.
+     * @returns The Sealed value, `vault:v1:<keyId>:s:<iv>:<ciphertext>`.
+     */
+    encrypt(plaintext: string, context: string): Promise<string>;
+    /**
+     * Opens a Sealed value made by {@link Vault.encrypt}.
+     *
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under.
+     * @returns The Plaintext string.
+     * @throws {@link VaultDecryptError} when the value isn't a Sealed value, was
+     * sealed with an unknown Vault secret or another Purpose, was edited, or is
+     * opened under another Context, or `wrong_kind` when it isn't a string
+     * Sealed value. A string Sealed value that opens to bytes that aren't valid
+     * UTF-8 also rejects as `authentication_failed`, with the decoder's
+     * `TypeError` as its `cause`.
+     */
+    decrypt(sealed: string, context: string): Promise<string>;
+    /**
+     * Seals JSON data with plain `JSON.stringify`.
+     *
+     * @param value - Any value `JSON.stringify` can encode.
+     * @param context - Where the Sealed value is stored.
+     * @returns The Sealed value, `vault:v1:<keyId>:j:<iv>:<ciphertext>`.
+     * @throws The promise rejects with a `TypeError` when `JSON.stringify`
+     * can't encode `value`, such as `undefined`, a function, a `BigInt` or a
+     * cyclic object, before anything is encrypted. It never throws
+     * synchronously.
+     */
+    encryptJson(value: unknown, context: string): Promise<string>;
+    /**
+     * Opens a Sealed value made by {@link Vault.encryptJson}.
+     *
+     * @typeParam T - The type the caller expects. It is asserted, not validated.
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under.
+     * @returns The JSON data, parsed with plain `JSON.parse`.
+     * @throws {@link VaultDecryptError} for the same reasons as
+     * {@link Vault.decrypt}, `wrong_kind` when it isn't a JSON Sealed value, or
+     * `invalid_json` when it opens to text that isn't JSON.
+     */
+    decryptJson<T = unknown>(sealed: string, context: string): Promise<T>;
+    /**
+     * Seals bytes.
+     *
+     * @param plaintext - The bytes to seal. May be empty.
+     * @param context - Where the Sealed value is stored.
+     * @returns The Sealed value, `vault:v1:<keyId>:b:<iv>:<ciphertext>`.
+     */
+    encryptBytes(plaintext: Uint8Array, context: string): Promise<string>;
+    /**
+     * Opens a Sealed value made by {@link Vault.encryptBytes}.
+     *
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under.
+     * @returns The Plaintext bytes, as a plain `Uint8Array`.
+     * @throws {@link VaultDecryptError} for the same reasons as
+     * {@link Vault.decrypt}, or `wrong_kind` when it isn't a bytes Sealed value.
+     */
+    decryptBytes(sealed: string, context: string): Promise<Uint8Array>;
+    /**
+     * True when a Sealed value was made with a previous Vault secret, so it
+     * should be re-sealed with {@link Vault.reseal} before that secret is
+     * dropped. Reads only the key id; it doesn't open the value, so it needs no
+     * Context. It is async, unlike {@link Vault.isSealed}, because the current
+     * key id is derived on first use: `await` it.
+     *
+     * @param sealed - The Sealed value.
+     * @returns A promise of `true` when the key id isn't the current one.
+     * @throws The promise rejects with {@link VaultDecryptError} `not_sealed`
+     * (or `unsupported_version`) when the value isn't a Sealed value this
+     * package can read; its `context` is `undefined`. It never throws
+     * synchronously.
+     */
+    needsRotation(sealed: string): Promise<boolean>;
+    /**
+     * Opens a Sealed value with whichever Vault secret made it and seals it
+     * again with the current one, keeping its kind (string, JSON or bytes). Use
+     * it on values where {@link Vault.needsRotation} is true.
+     *
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under; the new Sealed value
+     * is bound to the same Context.
+     * @returns A new Sealed value with the current key id.
+     * @throws {@link VaultDecryptError} for the same reasons as
+     * {@link Vault.decrypt}.
+     */
+    reseal(sealed: string, context: string): Promise<string>;
+}
+
+/**
+ * Base class of every error the package throws, so `instanceof VaultError`
+ * catches them all. The underlying error, if any, is the native `cause`.
+ */
+declare class VaultError extends Error {
+    /** A stable, machine-readable code such as `VAULT_CONFIG_INVALID`. */
+    readonly code: string;
+    /**
+     * @param message - The error message.
+     * @param code - The stable error code.
+     * @param options - The underlying `cause`, if any.
+     */
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+/**
+ * The Vault's options break a rule in {@link VaultOptions}. Thrown by the
+ * `Vault` constructor, so a config mistake fails at startup, except a
+ * duplicated Vault secret: that is found when keys are derived, so the
+ * Vault's first keyed call, and every later one, rejects with this error. The
+ * message names the bad option, never its value.
+ */
+declare class VaultConfigError extends VaultError {
+    /** Always `VAULT_CONFIG_INVALID`. */
+    readonly code: "VAULT_CONFIG_INVALID";
+    /**
+     * @param message - What is wrong, naming the option but never its value.
+     * @param options - The underlying `cause`, if any.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Why a Sealed value couldn't be opened.
+ *
+ * - `not_sealed`: the value isn't a well-formed Sealed value, such as plain
+ *   text, a value with missing parts, or a part that isn't canonical
+ *   base64url.
+ * - `unsupported_version`: a well-formed Sealed value in a format version
+ *   this package can't read.
+ * - `unknown_key`: no configured Vault secret matches the Sealed value's key id.
+ * - `wrong_kind`: the Sealed value holds another kind of Plaintext than the method reads.
+ * - `authentication_failed`: the Sealed value was edited, or is opened under
+ *   another Context or Purpose, or a string Sealed value opened to bytes that
+ *   aren't valid UTF-8.
+ * - `invalid_json`: a JSON Sealed value opened to text that isn't JSON.
+ */
+type VaultDecryptReason = "not_sealed" | "unsupported_version" | "unknown_key" | "wrong_kind" | "authentication_failed" | "invalid_json";
+/** The code of a {@link VaultDecryptError}, one per {@link VaultDecryptReason}. */
+type VaultDecryptErrorCode = `VAULT_DECRYPT_${Uppercase<VaultDecryptReason>}`;
+/**
+ * A Sealed value couldn't be opened. The message names the reason and the
+ * Context, if there is one, never the Plaintext or the Sealed value.
+ */
+declare class VaultDecryptError extends VaultError {
+    /** Why the Sealed value couldn't be opened. */
+    readonly reason: VaultDecryptReason;
+    /**
+     * The Context the Sealed value was opened under, or `undefined` when the
+     * method takes no Context (`needsRotation`).
+     */
+    readonly context: string | undefined;
+    /** The code for {@link VaultDecryptError.reason}, such as `VAULT_DECRYPT_UNKNOWN_KEY`. */
+    readonly code: VaultDecryptErrorCode;
+    /**
+     * @param reason - Why the Sealed value couldn't be opened.
+     * @param context - The Context it was opened under, or `undefined` when
+     * there is none.
+     * @param options - The underlying `cause`, if any.
+     */
+    constructor(reason: VaultDecryptReason, context: string | undefined, options?: ErrorOptions);
+}
+
+export { Vault, VaultConfigError, VaultDecryptError, type VaultDecryptErrorCode, type VaultDecryptReason, VaultError, type VaultOptions };

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+/** Options for building a {@link Vault}. */
+interface VaultOptions {
+    /**
+     * The current Vault secret, which seals every new value. At least 32
+     * characters of high-entropy key material, such as the output of
+     * `openssl rand -base64 32`.
+     */
+    secret: string;
+    /**
+     * Earlier Vault secrets, still accepted when opening Sealed values but never
+     * used to seal new ones. During a Rotation, move the old `secret` here until
+     * every value sealed with it has been re-sealed with {@link Vault.reseal}.
+     * Each must be at least 32 characters. A secret listed twice (here or
+     * alongside `secret`) is a {@link VaultConfigError}, reported by the first
+     * call that needs keys rather than by the constructor.
+     */
+    previousSecrets?: readonly string[];
+    /**
+     * The name of this Vault, such as `myapp:settings`. Vaults with the same
+     * Vault secret but different Purposes can't read each other's Sealed
+     * values. It must never change once values are stored.
+     */
+    purpose: string;
+}
+/**
+ * Turns Plaintexts into Sealed values and back, with AES-256-GCM on Web
+ * Crypto. Build one per Purpose, at module level, and reuse it.
+ *
+ * Every method that seals or opens takes a Context: where the Sealed value is
+ * stored, such as `settings:smtp_pass`. A Sealed value only opens under the
+ * Context it was sealed with. `""` is allowed and means no binding.
+ *
+ * @example
+ * const vault = new Vault({ secret: process.env.VAULT_SECRET!, purpose: "myapp:settings" });
+ * const sealed = await vault.encrypt("hunter2", "settings:smtp_pass");
+ * await vault.decrypt(sealed, "settings:smtp_pass"); // "hunter2"
+ */
+declare class Vault {
+    #private;
+    /**
+     * Checks the options right away; keys are derived on first use, so this
+     * needs no `await`.
+     *
+     * @param options - The Vault secrets and Purpose.
+     * @throws {@link VaultConfigError} when an option breaks a rule in
+     * {@link VaultOptions}, except a duplicated secret, which is reported on
+     * first use. The message never contains a secret.
+     */
+    constructor(options: VaultOptions);
+    /**
+     * True when `value` is a Sealed value: a string starting with `vault:`. Use
+     * it to tell Sealed values from plain text still stored in a column.
+     *
+     * @param value - Any value.
+     */
+    static isSealed(value: unknown): value is string;
+    /**
+     * Seals a string.
+     *
+     * @param plaintext - The string to seal. May be empty.
+     * @param context - Where the Sealed value is stored.
+     * @returns The Sealed value, `vault:v1:<keyId>:s:<iv>:<ciphertext>`.
+     */
+    encrypt(plaintext: string, context: string): Promise<string>;
+    /**
+     * Opens a Sealed value made by {@link Vault.encrypt}.
+     *
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under.
+     * @returns The Plaintext string.
+     * @throws {@link VaultDecryptError} when the value isn't a Sealed value, was
+     * sealed with an unknown Vault secret or another Purpose, was edited, or is
+     * opened under another Context, or `wrong_kind` when it isn't a string
+     * Sealed value. A string Sealed value that opens to bytes that aren't valid
+     * UTF-8 also rejects as `authentication_failed`, with the decoder's
+     * `TypeError` as its `cause`.
+     */
+    decrypt(sealed: string, context: string): Promise<string>;
+    /**
+     * Seals JSON data with plain `JSON.stringify`.
+     *
+     * @param value - Any value `JSON.stringify` can encode.
+     * @param context - Where the Sealed value is stored.
+     * @returns The Sealed value, `vault:v1:<keyId>:j:<iv>:<ciphertext>`.
+     * @throws The promise rejects with a `TypeError` when `JSON.stringify`
+     * can't encode `value`, such as `undefined`, a function, a `BigInt` or a
+     * cyclic object, before anything is encrypted. It never throws
+     * synchronously.
+     */
+    encryptJson(value: unknown, context: string): Promise<string>;
+    /**
+     * Opens a Sealed value made by {@link Vault.encryptJson}.
+     *
+     * @typeParam T - The type the caller expects. It is asserted, not validated.
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under.
+     * @returns The JSON data, parsed with plain `JSON.parse`.
+     * @throws {@link VaultDecryptError} for the same reasons as
+     * {@link Vault.decrypt}, `wrong_kind` when it isn't a JSON Sealed value, or
+     * `invalid_json` when it opens to text that isn't JSON.
+     */
+    decryptJson<T = unknown>(sealed: string, context: string): Promise<T>;
+    /**
+     * Seals bytes.
+     *
+     * @param plaintext - The bytes to seal. May be empty.
+     * @param context - Where the Sealed value is stored.
+     * @returns The Sealed value, `vault:v1:<keyId>:b:<iv>:<ciphertext>`.
+     */
+    encryptBytes(plaintext: Uint8Array, context: string): Promise<string>;
+    /**
+     * Opens a Sealed value made by {@link Vault.encryptBytes}.
+     *
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under.
+     * @returns The Plaintext bytes, as a plain `Uint8Array`.
+     * @throws {@link VaultDecryptError} for the same reasons as
+     * {@link Vault.decrypt}, or `wrong_kind` when it isn't a bytes Sealed value.
+     */
+    decryptBytes(sealed: string, context: string): Promise<Uint8Array>;
+    /**
+     * True when a Sealed value was made with a previous Vault secret, so it
+     * should be re-sealed with {@link Vault.reseal} before that secret is
+     * dropped. Reads only the key id; it doesn't open the value, so it needs no
+     * Context. It is async, unlike {@link Vault.isSealed}, because the current
+     * key id is derived on first use: `await` it.
+     *
+     * @param sealed - The Sealed value.
+     * @returns A promise of `true` when the key id isn't the current one.
+     * @throws The promise rejects with {@link VaultDecryptError} `not_sealed`
+     * (or `unsupported_version`) when the value isn't a Sealed value this
+     * package can read; its `context` is `undefined`. It never throws
+     * synchronously.
+     */
+    needsRotation(sealed: string): Promise<boolean>;
+    /**
+     * Opens a Sealed value with whichever Vault secret made it and seals it
+     * again with the current one, keeping its kind (string, JSON or bytes). Use
+     * it on values where {@link Vault.needsRotation} is true.
+     *
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under; the new Sealed value
+     * is bound to the same Context.
+     * @returns A new Sealed value with the current key id.
+     * @throws {@link VaultDecryptError} for the same reasons as
+     * {@link Vault.decrypt}.
+     */
+    reseal(sealed: string, context: string): Promise<string>;
+}
+
+/**
+ * Base class of every error the package throws, so `instanceof VaultError`
+ * catches them all. The underlying error, if any, is the native `cause`.
+ */
+declare class VaultError extends Error {
+    /** A stable, machine-readable code such as `VAULT_CONFIG_INVALID`. */
+    readonly code: string;
+    /**
+     * @param message - The error message.
+     * @param code - The stable error code.
+     * @param options - The underlying `cause`, if any.
+     */
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+/**
+ * The Vault's options break a rule in {@link VaultOptions}. Thrown by the
+ * `Vault` constructor, so a config mistake fails at startup, except a
+ * duplicated Vault secret: that is found when keys are derived, so the
+ * Vault's first keyed call, and every later one, rejects with this error. The
+ * message names the bad option, never its value.
+ */
+declare class VaultConfigError extends VaultError {
+    /** Always `VAULT_CONFIG_INVALID`. */
+    readonly code: "VAULT_CONFIG_INVALID";
+    /**
+     * @param message - What is wrong, naming the option but never its value.
+     * @param options - The underlying `cause`, if any.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Why a Sealed value couldn't be opened.
+ *
+ * - `not_sealed`: the value isn't a well-formed Sealed value, such as plain
+ *   text, a value with missing parts, or a part that isn't canonical
+ *   base64url.
+ * - `unsupported_version`: a well-formed Sealed value in a format version
+ *   this package can't read.
+ * - `unknown_key`: no configured Vault secret matches the Sealed value's key id.
+ * - `wrong_kind`: the Sealed value holds another kind of Plaintext than the method reads.
+ * - `authentication_failed`: the Sealed value was edited, or is opened under
+ *   another Context or Purpose, or a string Sealed value opened to bytes that
+ *   aren't valid UTF-8.
+ * - `invalid_json`: a JSON Sealed value opened to text that isn't JSON.
+ */
+type VaultDecryptReason = "not_sealed" | "unsupported_version" | "unknown_key" | "wrong_kind" | "authentication_failed" | "invalid_json";
+/** The code of a {@link VaultDecryptError}, one per {@link VaultDecryptReason}. */
+type VaultDecryptErrorCode = `VAULT_DECRYPT_${Uppercase<VaultDecryptReason>}`;
+/**
+ * A Sealed value couldn't be opened. The message names the reason and the
+ * Context, if there is one, never the Plaintext or the Sealed value.
+ */
+declare class VaultDecryptError extends VaultError {
+    /** Why the Sealed value couldn't be opened. */
+    readonly reason: VaultDecryptReason;
+    /**
+     * The Context the Sealed value was opened under, or `undefined` when the
+     * method takes no Context (`needsRotation`).
+     */
+    readonly context: string | undefined;
+    /** The code for {@link VaultDecryptError.reason}, such as `VAULT_DECRYPT_UNKNOWN_KEY`. */
+    readonly code: VaultDecryptErrorCode;
+    /**
+     * @param reason - Why the Sealed value couldn't be opened.
+     * @param context - The Context it was opened under, or `undefined` when
+     * there is none.
+     * @param options - The underlying `cause`, if any.
+     */
+    constructor(reason: VaultDecryptReason, context: string | undefined, options?: ErrorOptions);
+}
+
+export { Vault, VaultConfigError, VaultDecryptError, type VaultDecryptErrorCode, type VaultDecryptReason, VaultError, type VaultOptions };