@rezwanul7/secret-vault 0.0.0 → 0.1.0

package/dist/index.cjs

@@ -0,0 +1,415 @@
+'use strict';
+
+// src/encoding.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder("utf-8", { fatal: true });
+function utf8Encode(text) {
+  return encoder.encode(text);
+}
+function utf8Decode(bytes) {
+  return decoder.decode(bytes);
+}
+function base64urlEncode(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64urlDecode(text) {
+  if (!/^[A-Za-z0-9_-]*$/.test(text) || text.length % 4 === 1) return void 0;
+  const binary = atob(text.replace(/-/g, "+").replace(/_/g, "/"));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return base64urlEncode(bytes) === text ? bytes : void 0;
+}
+
+// src/errors.ts
+var VaultError = class extends Error {
+  /** A stable, machine-readable code such as `VAULT_CONFIG_INVALID`. */
+  code;
+  /**
+   * @param message - The error message.
+   * @param code - The stable error code.
+   * @param options - The underlying `cause`, if any.
+   */
+  constructor(message, code, options) {
+    super(message, options);
+    this.name = "VaultError";
+    this.code = code;
+  }
+};
+var VaultConfigError = class extends VaultError {
+  /**
+   * @param message - What is wrong, naming the option but never its value.
+   * @param options - The underlying `cause`, if any.
+   */
+  constructor(message, options) {
+    super(message, "VAULT_CONFIG_INVALID", options);
+    this.name = "VaultConfigError";
+  }
+};
+var VaultDecryptError = class extends VaultError {
+  /** Why the Sealed value couldn't be opened. */
+  reason;
+  /**
+   * The Context the Sealed value was opened under, or `undefined` when the
+   * method takes no Context (`needsRotation`).
+   */
+  context;
+  /**
+   * @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, context, options) {
+    super(
+      context === void 0 ? `Could not read Sealed value: ${reason}` : `Could not open Sealed value (context "${context}"): ${reason}`,
+      `VAULT_DECRYPT_${reason.toUpperCase()}`,
+      options
+    );
+    this.name = "VaultDecryptError";
+    this.reason = reason;
+    this.context = context;
+  }
+};
+
+// src/format.ts
+var PREFIX = "vault";
+var FORMAT_VERSION = "v1";
+var KINDS = ["s", "j", "b"];
+function looksSealed(value) {
+  return typeof value === "string" && value.startsWith(`${PREFIX}:`);
+}
+function formatSealed(parts) {
+  return [
+    PREFIX,
+    FORMAT_VERSION,
+    parts.keyId,
+    parts.kind,
+    base64urlEncode(parts.iv),
+    base64urlEncode(parts.ciphertext)
+  ].join(":");
+}
+function parseSealed(value, context) {
+  if (!looksSealed(value)) throw new VaultDecryptError("not_sealed", context);
+  const parts = value.split(":");
+  const [, version, keyId, kind, iv, ciphertext] = parts;
+  if (parts.length !== 6 || !/^v[0-9]+$/.test(version)) {
+    throw new VaultDecryptError("not_sealed", context);
+  }
+  if (version !== FORMAT_VERSION) {
+    throw new VaultDecryptError("unsupported_version", context);
+  }
+  const ivBytes = base64urlDecode(iv);
+  const ciphertextBytes = base64urlDecode(ciphertext);
+  if (!/^[0-9a-f]{8}$/.test(keyId) || !isSealedKind(kind) || !ivBytes || !ciphertextBytes) {
+    throw new VaultDecryptError("not_sealed", context);
+  }
+  return { keyId, kind, iv: ivBytes, ciphertext: ciphertextBytes };
+}
+function isSealedKind(kind) {
+  return KINDS.includes(kind);
+}
+function additionalData(kind, context) {
+  return utf8Encode(`${FORMAT_VERSION}:${kind}:${context}`);
+}
+
+// src/keys.ts
+var SALT = utf8Encode("secret-vault/v1");
+var KEY_ID_BYTES = 4;
+async function deriveVaultKey(secret, purpose) {
+  const material = await crypto.subtle.importKey(
+    "raw",
+    utf8Encode(secret),
+    "HKDF",
+    false,
+    ["deriveKey", "deriveBits"]
+  );
+  const hkdf = (info) => ({
+    name: "HKDF",
+    hash: "SHA-256",
+    salt: SALT,
+    info: utf8Encode(info)
+  });
+  const [key, idBits] = await Promise.all([
+    crypto.subtle.deriveKey(
+      hkdf(purpose),
+      material,
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["encrypt", "decrypt"]
+    ),
+    crypto.subtle.deriveBits(
+      hkdf(`${purpose}:key-id`),
+      material,
+      KEY_ID_BYTES * 8
+    )
+  ]);
+  const id = Array.from(
+    new Uint8Array(idBits),
+    (byte) => byte.toString(16).padStart(2, "0")
+  ).join("");
+  return { id, key };
+}
+var KeyRing = class {
+  #secrets;
+  #purpose;
+  #loaded;
+  /**
+   * @param secrets - The current Vault secret first, then any previous ones.
+   * @param purpose - The Vault's Purpose.
+   */
+  constructor(secrets, purpose) {
+    this.#secrets = secrets;
+    this.#purpose = purpose;
+  }
+  /** Derives the keys, or returns the cached ones. */
+  load() {
+    this.#loaded ??= this.#derive().catch((error) => {
+      this.#loaded = void 0;
+      throw error;
+    });
+    return this.#loaded;
+  }
+  async #derive() {
+    const keys = await Promise.all(
+      this.#secrets.map((secret) => deriveVaultKey(secret, this.#purpose))
+    );
+    const byId = /* @__PURE__ */ new Map();
+    for (const key of keys) {
+      if (byId.has(key.id)) {
+        throw new VaultConfigError(
+          "Vault options `secret` and `previousSecrets` contain two Vault secrets with the same key id; remove the duplicate."
+        );
+      }
+      byId.set(key.id, key);
+    }
+    return { current: keys[0], byId };
+  }
+};
+
+// src/random.ts
+function randomBytes(length) {
+  return crypto.getRandomValues(new Uint8Array(length));
+}
+
+// src/vault.ts
+var MIN_SECRET_LENGTH = 32;
+var IV_BYTES = 12;
+var Vault = class {
+  #keys;
+  /**
+   * 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) {
+    assertSecret(options.secret, "secret");
+    const previousSecrets = options.previousSecrets ?? [];
+    if (!Array.isArray(previousSecrets)) {
+      throw new VaultConfigError(
+        "Vault option `previousSecrets` must be an array of strings."
+      );
+    }
+    previousSecrets.forEach(
+      (secret, index) => assertSecret(secret, `previousSecrets[${index}]`)
+    );
+    if (typeof options.purpose !== "string" || options.purpose === "") {
+      throw new VaultConfigError("Vault option `purpose` must not be empty.");
+    }
+    this.#keys = new KeyRing(
+      [options.secret, ...previousSecrets],
+      options.purpose
+    );
+  }
+  /**
+   * 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) {
+    return looksSealed(value);
+  }
+  /**
+   * 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, context) {
+    return this.#seal("s", utf8Encode(plaintext), context);
+  }
+  /**
+   * 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`.
+   */
+  async decrypt(sealed, context) {
+    const plaintext = await this.#openKind("s", sealed, context);
+    try {
+      return utf8Decode(plaintext);
+    } catch (cause) {
+      throw new VaultDecryptError("authentication_failed", context, { cause });
+    }
+  }
+  /**
+   * 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.
+   */
+  async encryptJson(value, context) {
+    const json = JSON.stringify(value);
+    if (typeof json !== "string") {
+      throw new TypeError("Vault.encryptJson: value can't be encoded as JSON.");
+    }
+    return this.#seal("j", utf8Encode(json), context);
+  }
+  /**
+   * 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.
+   */
+  async decryptJson(sealed, context) {
+    const plaintext = await this.#openKind("j", sealed, context);
+    try {
+      return JSON.parse(utf8Decode(plaintext));
+    } catch (cause) {
+      throw new VaultDecryptError("invalid_json", context, { cause });
+    }
+  }
+  /**
+   * 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, context) {
+    return this.#seal("b", Uint8Array.from(plaintext), context);
+  }
+  /**
+   * 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, context) {
+    return this.#openKind("b", sealed, context);
+  }
+  /** Opens a Sealed value, then checks it holds the `expected` kind. */
+  async #openKind(expected, sealed, context) {
+    const { kind, plaintext } = await this.#open(sealed, context);
+    if (kind !== expected) throw new VaultDecryptError("wrong_kind", context);
+    return plaintext;
+  }
+  /**
+   * 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.
+   */
+  async needsRotation(sealed) {
+    const { keyId } = parseSealed(sealed, void 0);
+    const { current } = await this.#keys.load();
+    return keyId !== current.id;
+  }
+  /**
+   * 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}.
+   */
+  async reseal(sealed, context) {
+    const { kind, plaintext } = await this.#open(sealed, context);
+    return this.#seal(kind, plaintext, context);
+  }
+  async #seal(kind, plaintext, context) {
+    const { current } = await this.#keys.load();
+    const iv = randomBytes(IV_BYTES);
+    const ciphertext = await crypto.subtle.encrypt(
+      aesGcmParams(iv, kind, context),
+      current.key,
+      plaintext
+    );
+    return formatSealed({
+      keyId: current.id,
+      kind,
+      iv,
+      ciphertext: new Uint8Array(ciphertext)
+    });
+  }
+  async #open(sealed, context) {
+    const { keyId, kind, iv, ciphertext } = parseSealed(sealed, context);
+    const { byId } = await this.#keys.load();
+    const vaultKey = byId.get(keyId);
+    if (!vaultKey) throw new VaultDecryptError("unknown_key", context);
+    try {
+      const plaintext = await crypto.subtle.decrypt(
+        aesGcmParams(iv, kind, context),
+        vaultKey.key,
+        ciphertext
+      );
+      return { kind, plaintext: new Uint8Array(plaintext) };
+    } catch (cause) {
+      throw new VaultDecryptError("authentication_failed", context, { cause });
+    }
+  }
+};
+function aesGcmParams(iv, kind, context) {
+  return { name: "AES-GCM", iv, additionalData: additionalData(kind, context) };
+}
+function assertSecret(secret, option) {
+  if (typeof secret !== "string" || secret.length < MIN_SECRET_LENGTH) {
+    throw new VaultConfigError(
+      `Vault option \`${option}\` must be a string of at least ${MIN_SECRET_LENGTH} characters.`
+    );
+  }
+}
+
+exports.Vault = Vault;
+exports.VaultConfigError = VaultConfigError;
+exports.VaultDecryptError = VaultDecryptError;
+exports.VaultError = VaultError;

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 };

package/dist/index.js

@@ -0,0 +1,410 @@
+// src/encoding.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder("utf-8", { fatal: true });
+function utf8Encode(text) {
+  return encoder.encode(text);
+}
+function utf8Decode(bytes) {
+  return decoder.decode(bytes);
+}
+function base64urlEncode(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64urlDecode(text) {
+  if (!/^[A-Za-z0-9_-]*$/.test(text) || text.length % 4 === 1) return void 0;
+  const binary = atob(text.replace(/-/g, "+").replace(/_/g, "/"));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return base64urlEncode(bytes) === text ? bytes : void 0;
+}
+
+// src/errors.ts
+var VaultError = class extends Error {
+  /** A stable, machine-readable code such as `VAULT_CONFIG_INVALID`. */
+  code;
+  /**
+   * @param message - The error message.
+   * @param code - The stable error code.
+   * @param options - The underlying `cause`, if any.
+   */
+  constructor(message, code, options) {
+    super(message, options);
+    this.name = "VaultError";
+    this.code = code;
+  }
+};
+var VaultConfigError = class extends VaultError {
+  /**
+   * @param message - What is wrong, naming the option but never its value.
+   * @param options - The underlying `cause`, if any.
+   */
+  constructor(message, options) {
+    super(message, "VAULT_CONFIG_INVALID", options);
+    this.name = "VaultConfigError";
+  }
+};
+var VaultDecryptError = class extends VaultError {
+  /** Why the Sealed value couldn't be opened. */
+  reason;
+  /**
+   * The Context the Sealed value was opened under, or `undefined` when the
+   * method takes no Context (`needsRotation`).
+   */
+  context;
+  /**
+   * @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, context, options) {
+    super(
+      context === void 0 ? `Could not read Sealed value: ${reason}` : `Could not open Sealed value (context "${context}"): ${reason}`,
+      `VAULT_DECRYPT_${reason.toUpperCase()}`,
+      options
+    );
+    this.name = "VaultDecryptError";
+    this.reason = reason;
+    this.context = context;
+  }
+};
+
+// src/format.ts
+var PREFIX = "vault";
+var FORMAT_VERSION = "v1";
+var KINDS = ["s", "j", "b"];
+function looksSealed(value) {
+  return typeof value === "string" && value.startsWith(`${PREFIX}:`);
+}
+function formatSealed(parts) {
+  return [
+    PREFIX,
+    FORMAT_VERSION,
+    parts.keyId,
+    parts.kind,
+    base64urlEncode(parts.iv),
+    base64urlEncode(parts.ciphertext)
+  ].join(":");
+}
+function parseSealed(value, context) {
+  if (!looksSealed(value)) throw new VaultDecryptError("not_sealed", context);
+  const parts = value.split(":");
+  const [, version, keyId, kind, iv, ciphertext] = parts;
+  if (parts.length !== 6 || !/^v[0-9]+$/.test(version)) {
+    throw new VaultDecryptError("not_sealed", context);
+  }
+  if (version !== FORMAT_VERSION) {
+    throw new VaultDecryptError("unsupported_version", context);
+  }
+  const ivBytes = base64urlDecode(iv);
+  const ciphertextBytes = base64urlDecode(ciphertext);
+  if (!/^[0-9a-f]{8}$/.test(keyId) || !isSealedKind(kind) || !ivBytes || !ciphertextBytes) {
+    throw new VaultDecryptError("not_sealed", context);
+  }
+  return { keyId, kind, iv: ivBytes, ciphertext: ciphertextBytes };
+}
+function isSealedKind(kind) {
+  return KINDS.includes(kind);
+}
+function additionalData(kind, context) {
+  return utf8Encode(`${FORMAT_VERSION}:${kind}:${context}`);
+}
+
+// src/keys.ts
+var SALT = utf8Encode("secret-vault/v1");
+var KEY_ID_BYTES = 4;
+async function deriveVaultKey(secret, purpose) {
+  const material = await crypto.subtle.importKey(
+    "raw",
+    utf8Encode(secret),
+    "HKDF",
+    false,
+    ["deriveKey", "deriveBits"]
+  );
+  const hkdf = (info) => ({
+    name: "HKDF",
+    hash: "SHA-256",
+    salt: SALT,
+    info: utf8Encode(info)
+  });
+  const [key, idBits] = await Promise.all([
+    crypto.subtle.deriveKey(
+      hkdf(purpose),
+      material,
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["encrypt", "decrypt"]
+    ),
+    crypto.subtle.deriveBits(
+      hkdf(`${purpose}:key-id`),
+      material,
+      KEY_ID_BYTES * 8
+    )
+  ]);
+  const id = Array.from(
+    new Uint8Array(idBits),
+    (byte) => byte.toString(16).padStart(2, "0")
+  ).join("");
+  return { id, key };
+}
+var KeyRing = class {
+  #secrets;
+  #purpose;
+  #loaded;
+  /**
+   * @param secrets - The current Vault secret first, then any previous ones.
+   * @param purpose - The Vault's Purpose.
+   */
+  constructor(secrets, purpose) {
+    this.#secrets = secrets;
+    this.#purpose = purpose;
+  }
+  /** Derives the keys, or returns the cached ones. */
+  load() {
+    this.#loaded ??= this.#derive().catch((error) => {
+      this.#loaded = void 0;
+      throw error;
+    });
+    return this.#loaded;
+  }
+  async #derive() {
+    const keys = await Promise.all(
+      this.#secrets.map((secret) => deriveVaultKey(secret, this.#purpose))
+    );
+    const byId = /* @__PURE__ */ new Map();
+    for (const key of keys) {
+      if (byId.has(key.id)) {
+        throw new VaultConfigError(
+          "Vault options `secret` and `previousSecrets` contain two Vault secrets with the same key id; remove the duplicate."
+        );
+      }
+      byId.set(key.id, key);
+    }
+    return { current: keys[0], byId };
+  }
+};
+
+// src/random.ts
+function randomBytes(length) {
+  return crypto.getRandomValues(new Uint8Array(length));
+}
+
+// src/vault.ts
+var MIN_SECRET_LENGTH = 32;
+var IV_BYTES = 12;
+var Vault = class {
+  #keys;
+  /**
+   * 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) {
+    assertSecret(options.secret, "secret");
+    const previousSecrets = options.previousSecrets ?? [];
+    if (!Array.isArray(previousSecrets)) {
+      throw new VaultConfigError(
+        "Vault option `previousSecrets` must be an array of strings."
+      );
+    }
+    previousSecrets.forEach(
+      (secret, index) => assertSecret(secret, `previousSecrets[${index}]`)
+    );
+    if (typeof options.purpose !== "string" || options.purpose === "") {
+      throw new VaultConfigError("Vault option `purpose` must not be empty.");
+    }
+    this.#keys = new KeyRing(
+      [options.secret, ...previousSecrets],
+      options.purpose
+    );
+  }
+  /**
+   * 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) {
+    return looksSealed(value);
+  }
+  /**
+   * 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, context) {
+    return this.#seal("s", utf8Encode(plaintext), context);
+  }
+  /**
+   * 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`.
+   */
+  async decrypt(sealed, context) {
+    const plaintext = await this.#openKind("s", sealed, context);
+    try {
+      return utf8Decode(plaintext);
+    } catch (cause) {
+      throw new VaultDecryptError("authentication_failed", context, { cause });
+    }
+  }
+  /**
+   * 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.
+   */
+  async encryptJson(value, context) {
+    const json = JSON.stringify(value);
+    if (typeof json !== "string") {
+      throw new TypeError("Vault.encryptJson: value can't be encoded as JSON.");
+    }
+    return this.#seal("j", utf8Encode(json), context);
+  }
+  /**
+   * 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.
+   */
+  async decryptJson(sealed, context) {
+    const plaintext = await this.#openKind("j", sealed, context);
+    try {
+      return JSON.parse(utf8Decode(plaintext));
+    } catch (cause) {
+      throw new VaultDecryptError("invalid_json", context, { cause });
+    }
+  }
+  /**
+   * 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, context) {
+    return this.#seal("b", Uint8Array.from(plaintext), context);
+  }
+  /**
+   * 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, context) {
+    return this.#openKind("b", sealed, context);
+  }
+  /** Opens a Sealed value, then checks it holds the `expected` kind. */
+  async #openKind(expected, sealed, context) {
+    const { kind, plaintext } = await this.#open(sealed, context);
+    if (kind !== expected) throw new VaultDecryptError("wrong_kind", context);
+    return plaintext;
+  }
+  /**
+   * 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.
+   */
+  async needsRotation(sealed) {
+    const { keyId } = parseSealed(sealed, void 0);
+    const { current } = await this.#keys.load();
+    return keyId !== current.id;
+  }
+  /**
+   * 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}.
+   */
+  async reseal(sealed, context) {
+    const { kind, plaintext } = await this.#open(sealed, context);
+    return this.#seal(kind, plaintext, context);
+  }
+  async #seal(kind, plaintext, context) {
+    const { current } = await this.#keys.load();
+    const iv = randomBytes(IV_BYTES);
+    const ciphertext = await crypto.subtle.encrypt(
+      aesGcmParams(iv, kind, context),
+      current.key,
+      plaintext
+    );
+    return formatSealed({
+      keyId: current.id,
+      kind,
+      iv,
+      ciphertext: new Uint8Array(ciphertext)
+    });
+  }
+  async #open(sealed, context) {
+    const { keyId, kind, iv, ciphertext } = parseSealed(sealed, context);
+    const { byId } = await this.#keys.load();
+    const vaultKey = byId.get(keyId);
+    if (!vaultKey) throw new VaultDecryptError("unknown_key", context);
+    try {
+      const plaintext = await crypto.subtle.decrypt(
+        aesGcmParams(iv, kind, context),
+        vaultKey.key,
+        ciphertext
+      );
+      return { kind, plaintext: new Uint8Array(plaintext) };
+    } catch (cause) {
+      throw new VaultDecryptError("authentication_failed", context, { cause });
+    }
+  }
+};
+function aesGcmParams(iv, kind, context) {
+  return { name: "AES-GCM", iv, additionalData: additionalData(kind, context) };
+}
+function assertSecret(secret, option) {
+  if (typeof secret !== "string" || secret.length < MIN_SECRET_LENGTH) {
+    throw new VaultConfigError(
+      `Vault option \`${option}\` must be a string of at least ${MIN_SECRET_LENGTH} characters.`
+    );
+  }
+}
+
+export { Vault, VaultConfigError, VaultDecryptError, VaultError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rezwanul7/secret-vault",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",