@rezwanul7/secret-vault 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rezwanul Islam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,243 @@
-# Temporary Holding Version
+# @rezwanul7/secret-vault
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Seals values an app stores, such as API keys, passwords and settings objects, so they can sit in a database and be
+read back only by an app holding the right Vault secret. It uses AES-256-GCM on Web Crypto, so the same code runs on
+Node, Edge routes, middleware and Workers, and it has no runtime dependencies. The terms used here are defined in the
+package [glossary](./GLOSSARY.md).
+
+## Installation
+
+```bash
+npm install @rezwanul7/secret-vault
+# or
+pnpm add @rezwanul7/secret-vault
+```
+
+Everything is imported from the package root; the exports are listed in the [API reference](./docs/api/README.md).
+
+## Building a Vault
+
+Build one Vault per Purpose, at module level, and export it. The constructor is synchronous and checks its options
+straight away, so invalid options throw `VaultConfigError` at startup instead of on the first request. The rules for
+each option are in [`VaultOptions`](./docs/api/README.md#vaultoptions). Keys are derived on first use, so no top-level
+`await` is needed.
+
+```ts
+// src/server/vault.ts
+import "server-only";
+import { Vault } from "@rezwanul7/secret-vault";
+
+export const vault = new Vault({
+  secret: process.env.VAULT_SECRET!,
+  purpose: "myapp:settings",
+});
+```
+
+### Keep it on the server
+
+The package has no `server-only` directive, so it works in any framework. A Vault holds your Vault secret, so it must
+never reach a browser bundle. In a Next.js app, put `import "server-only";` at the top of the module that builds the
+Vault, as above, and import the Vault only from there. The build then fails if a client component imports it.
+
+### Generating a Vault secret
+
+A Vault secret is high-entropy key material with a minimum length (see [`VaultOptions`](./docs/api/README.md#secret)).
+It is not a password, and nothing stretches it, so don't type one by hand. Generate it:
+
+```bash
+openssl rand -base64 32
+```
+
+Keep it wherever the app keeps its other secrets, such as an environment variable. Anyone with the Vault secret, the
+Purpose and the database can read every Sealed value.
+
+### Choosing a Purpose
+
+The Purpose names the Vault, such as `myapp:settings`. It goes into key derivation, so two Vaults with the same Vault
+secret but different Purposes can't read each other's Sealed values. That keeps one app's leaked database from
+opening another's, even if they share a secret.
+
+The Purpose must never change once values are stored. Changing it changes every key, and every stored Sealed value then
+fails to open with reason `unknown_key`. To change Vault secrets, do a [Rotation](#rotation) instead.
+
+## Sealing and opening
+
+Every call is async. A Sealed value is a plain string, `vault:v1:<keyId>:<kind>:<iv>:<ciphertext>`, so it fits a text
+column in any database. Each kind of Plaintext has its own pair of methods: `encrypt` and `decrypt` for strings,
+`encryptJson` and `decryptJson` for JSON data, and `encryptBytes` and `decryptBytes` for bytes. Each takes the
+[Context](#choosing-a-context) as its second argument; the [API reference](./docs/api/README.md#vault) has the full
+signatures.
+
+```ts
+const smtpPass = await vault.encrypt("hunter2", "settings:smtp_pass");
+await vault.decrypt(smtpPass, "settings:smtp_pass"); // "hunter2"
+
+const smtp = await vault.encryptJson(
+  { host: "smtp.example.com", port: 587, user: "mailer" },
+  "settings:smtp",
+);
+const config = await vault.decryptJson<SmtpConfig>(smtp, "settings:smtp");
+
+const key = await vault.encryptBytes(
+  privateKeyBytes,
+  "signing_keys:private_key",
+);
+await vault.decryptBytes(key, "signing_keys:private_key"); // Uint8Array
+```
+
+Opening a Sealed value with the method for another kind, such as `decrypt` on a bytes Sealed value, throws
+`VaultDecryptError` with reason `wrong_kind`, so you never get garbled data back.
+
+`encryptJson` uses plain `JSON.stringify`, and `decryptJson` plain `JSON.parse`, so `Date`, `Map` and class instances
+come back as whatever JSON makes of them. The `T` in `decryptJson<T>` is asserted, not checked; validate the result
+with your own schema if it matters. A value `JSON.stringify` can't encode, such as `undefined`, a function, a `BigInt`
+or a cyclic object, rejects with a `TypeError` before anything is encrypted.
+
+### Size of bytes
+
+A Sealed value is base64url text, so it is about 1.33 times the size of the Plaintext, plus about 60 characters for
+the prefix, key id, IV and authentication tag. A 1 MB file becomes a Sealed value of about 1.33 MB. The whole value is
+also held in memory while it is sealed and opened; there is no streaming. Seal small binary values such as keys or
+certificates, and keep large files in object storage.
+
+## Choosing a Context
+
+Every method that seals or opens takes a Context: a string naming where the Sealed value is stored. It is bound into
+the authentication tag, so a Sealed value only opens under the Context it was sealed with. If someone copies a Sealed
+value into another column or row, it fails to open with reason `authentication_failed`.
+
+The package doesn't format or check the Context; pick a convention and keep to it:
+
+| Context                    | Use when                                                                                   |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| `<table>:<column>`         | The value belongs to a column, such as `settings:smtp_pass`.                               |
+| `<table>:<column>:<rowId>` | The value belongs to one row, such as `users:totp_secret:42`. A copy to another row fails. |
+| `""`                       | You deliberately don't want any binding. The value opens wherever it is moved.             |
+
+Use the row form for per-user secrets, so one user's Sealed value pasted into another user's row won't open. Use a
+stable row id, because a Sealed value can't be opened once its row id changes. Pass `""` only as a deliberate choice,
+never as a default.
+
+Like the Purpose, a Context must not change while values are stored under it. Renaming a table or column means
+re-sealing its values: open each under the old Context and seal it under the new one.
+
+## Rotation
+
+A Rotation replaces the Vault secret without downtime. The Vault seals new values with `secret` and still opens values
+made with any of `previousSecrets`.
+
+1. Generate a new Vault secret with `openssl rand -base64 32`.
+2. Make it the `secret`, and move the old one into `previousSecrets`. Deploy. Every value still opens, and every new
+   value is sealed with the new secret.
+
+   ```ts
+   export const vault = new Vault({
+     secret: process.env.VAULT_SECRET!, // the new one
+     previousSecrets: [process.env.VAULT_SECRET_PREVIOUS!], // the old one
+     purpose: "myapp:settings",
+   });
+   ```
+
+3. Find the Sealed values made with the old secret and re-seal them with the current one:
+
+   ```ts
+   for (const row of await db.settings.findMany()) {
+     if (!(await vault.needsRotation(row.smtpPass))) continue;
+     const smtpPass = await vault.reseal(row.smtpPass, "settings:smtp_pass");
+     await db.settings.update({ where: { id: row.id }, data: { smtpPass } });
+   }
+   ```
+
+   `reseal` opens a value with whichever Vault secret made it and seals it again with the current one, keeping its
+   kind (string, JSON or bytes) and its Context. Do this for every column holding Sealed values.
+
+4. When `needsRotation` is false for every stored value, remove the old secret from `previousSecrets` and deploy.
+   A value you missed then fails to open with reason `unknown_key`.
+
+`needsRotation` reads only the key id, so it takes no Context. Unlike `isSealed` it is async, because the current key
+id is derived on first use, so `await` it. For a value that isn't a Sealed value it rejects with `VaultDecryptError`
+reason `not_sealed`; it never throws synchronously.
+
+The secrets in `previousSecrets` follow the same rules as `secret`, and listing one Vault secret twice is reported only
+on first use; see [`previousSecrets`](./docs/api/README.md#previoussecrets).
+
+## Migrating plain-text columns
+
+`Vault.isSealed(value)` is true for a string starting with `vault:`. Use it to seal a column that still holds plain text,
+one row at a time:
+
+```ts
+if (!Vault.isSealed(row.apiKey)) {
+  const apiKey = await vault.encrypt(row.apiKey, "integrations:api_key");
+  await db.integrations.update({ where: { id: row.id }, data: { apiKey } });
+}
+```
+
+`isSealed` checks only the prefix. A value that passes can still fail to open.
+
+## Errors
+
+Every error the package throws extends `VaultError`, which has a stable `code` and the underlying error as the native
+`cause`. Messages name the bad option or the Context, never a Vault secret, a Plaintext or a Sealed value, so they are
+safe to log.
+
+- `VaultConfigError` (`VAULT_CONFIG_INVALID`) means the Vault's options are wrong. It is a deploy problem: fix the
+  config.
+- `VaultDecryptError` means a Sealed value couldn't be opened. Its `reason` says why, and its `code` is
+  `VAULT_DECRYPT_<REASON>`, such as `VAULT_DECRYPT_UNKNOWN_KEY`. It also carries the `context`.
+
+| `reason`                | What happened                                                         | Typical app response                                      |
+| ----------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
+| `not_sealed`            | The value isn't a Sealed value, such as plain text still in a column. | Data problem: migrate it, or ask the user to re-enter it. |
+| `unsupported_version`   | The Sealed value uses a format version this package can't read.       | Upgrade the package.                                      |
+| `unknown_key`           | No configured Vault secret made it, or the Purpose changed.           | Config problem: a secret was dropped too early.           |
+| `wrong_kind`            | It holds another kind than the method reads.                          | Bug in the app: call the matching method.                 |
+| `authentication_failed` | It was edited, or is opened under another Context or Purpose.         | Treat as tampered: ask the user to re-enter the secret.   |
+| `invalid_json`          | A JSON Sealed value opened to text that isn't JSON.                   | Treat as corrupt: ask the user to re-enter it.            |
+
+Map them onto your app's own errors at one place:
+
+```ts
+import { VaultConfigError, VaultDecryptError } from "@rezwanul7/secret-vault";
+
+export async function readSmtpPass(sealed: string): Promise<string> {
+  try {
+    return await vault.decrypt(sealed, "settings:smtp_pass");
+  } catch (error) {
+    if (error instanceof VaultDecryptError) {
+      switch (error.reason) {
+        case "not_sealed":
+        case "authentication_failed":
+        case "invalid_json":
+          throw new AppError(
+            "The saved SMTP password is unreadable; enter it again.",
+            {
+              status: 422,
+              cause: error,
+            },
+          );
+        default:
+          throw new AppError("Secret storage is misconfigured.", {
+            status: 500,
+            cause: error,
+          });
+      }
+    }
+    if (error instanceof VaultConfigError) {
+      throw new AppError("Secret storage is misconfigured.", {
+        status: 500,
+        cause: error,
+      });
+    }
+    throw error;
+  }
+}
+```
+
+## API reference
+
+Every export, parameter, and default is listed in the [API reference](./docs/api/README.md), generated from the source.
+
+## License
+
+MIT License. See [LICENSE](./LICENSE) for details.

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;