@rezwanul7/secret-vault 0.0.0-stage → 0.1.0

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,57 @@
 {
   "name": "@rezwanul7/secret-vault",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rezwanul7/turbopack-package-development.git",
+    "directory": "packages/secret-vault"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "devDependencies": {
+    "@edge-runtime/vm": "^5.0.0",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0",
+    "@vitest/coverage-v8": "4.0.18",
+    "eslint": "^9.39.1",
+    "tsup": "^8.5.1",
+    "typedoc-plugin-markdown": "4.14.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "check-types": "tsc --noEmit",
+    "check-docs": "typedoc --readme none --disableSources",
+    "check-package": "publint && attw --pack . --profile node16",
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
 }