@rezwanul7/secret-vault 0.0.0-stage → 0.0.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/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.0.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"
+  }
 }