@noy-db/at-env 0.1.0-pre.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+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

@@ -0,0 +1,84 @@
+# @noy-db/at-env
+
+**Env-var sealing key provider for noy-db [managed-passphrase mode](https://github.com/vLannaAi/noy-db/issues/14).**
+
+The smallest production-shape provider in the `at-*` family. Reads a 32-byte AES-256-GCM key from an environment variable (base64-encoded) and uses it to seal the hub-generated random passphrase — so your users never see or type a passphrase, but the encryption keys are still under your control.
+
+## Install
+
+```bash
+pnpm add @noy-db/hub @noy-db/at-env
+# or: npm install @noy-db/hub @noy-db/at-env
+```
+
+## Setup
+
+```bash
+# 1. Generate a 256-bit key once. Store in your platform's secret manager
+#    (Kubernetes Secrets, Heroku env, Doppler, AWS Secrets Manager, etc.).
+export NOYDB_SEALING_KEY=$(openssl rand -base64 32)
+```
+
+```ts
+// 2. In your app:
+import { createNoydb } from '@noy-db/hub'
+import { envSealingProvider } from '@noy-db/at-env'
+
+const db = await createNoydb({
+  store,
+  user: 'alice',
+  passphraseMode: 'managed',
+  sealingKey: envSealingProvider(),  // reads NOYDB_SEALING_KEY by default
+})
+
+const vault = await db.openVault('acme')
+// Hub generated a 256-bit random on first open, sealed it under your env
+// key, and persisted to _meta/sealed-passphrase. The user never sees a
+// passphrase. On reopen, at-env unseals transparently.
+```
+
+## When to use this provider
+
+- ✅ Single-node SaaS where the env var comes from Kubernetes Secrets, Heroku env, Doppler, AWS Secrets Manager mounted at boot, systemd env, etc.
+- ✅ Local dev / CI where you want persistence across restarts (which `MemorySealingKeyProvider` can't do — it's in-process only).
+- ✅ Prototypes where setting up AWS KMS / GCP KMS isn't worth the effort.
+
+## When NOT to use this provider
+
+- ❌ Laptops or shared dev machines where other users have shell access. They can `echo $NOYDB_SEALING_KEY` and exfiltrate the key. Use [`@noy-db/at-macos-keychain`](../at-macos-keychain) / [`@noy-db/at-wincred`](../at-wincred) / [`@noy-db/at-libsecret`](../at-libsecret) for desktop apps. *(coming soon)*
+- ❌ Compliance regimes requiring auditable key access logs (FedRAMP, HIPAA with managed-encryption requirements). Use [`@noy-db/at-aws-kms`](../at-aws-kms) for KMS-backed key access auditing. *(coming soon)*
+
+## Key rotation
+
+Rotating the env-var key is currently manual:
+
+1. Open the vault under the OLD env key.
+2. Generate a new key: `NEW=$(openssl rand -base64 32)`.
+3. Read `_meta/sealed-passphrase` from the store.
+4. Unseal under the OLD provider, re-seal under a NEW provider (`envSealingProvider({ envVar: 'NOYDB_NEW_KEY' })`).
+5. Overwrite `_meta/sealed-passphrase`.
+6. Swap the env var to the new value.
+
+An automated `noydb seal rotate` CLI command is tracked as a follow-up. For lower-touch rotation, use `@noy-db/at-aws-kms` once it lands — KMS handles CMK rotation automatically.
+
+## Threat model
+
+The env var IS the security boundary. If an attacker gains read access to your process's environment, they can decrypt every record sealed under that key.
+
+This provider is suitable when your deployment platform's secret management is trusted (you trust Kubernetes Secrets, you trust Heroku's env injection, etc.) and unsuitable when the env var sits in a shell profile, a `.env` file in version control, or a multi-tenant host where other tenants can read your environment.
+
+## API
+
+```ts
+function envSealingProvider(opts?: {
+  envVar?: string  // default 'NOYDB_SEALING_KEY'
+}): SealingKeyProvider
+```
+
+Returns a [`SealingKeyProvider`](../hub/src/team/managed-passphrase.ts) — the contract `@noy-db/hub`'s managed-passphrase mode consumes. The provider validates the env var at construction time and caches the imported `CryptoKey` for the lifetime of the instance.
+
+Throws at construction when the env var is unset, not valid base64, or not 32 bytes.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,106 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  envSealingProvider: () => envSealingProvider
+});
+module.exports = __toCommonJS(index_exports);
+function envSealingProvider(opts = {}) {
+  const envVar = opts.envVar ?? "NOYDB_SEALING_KEY";
+  const raw = process.env[envVar];
+  if (!raw) {
+    throw new Error(
+      `@noy-db/at-env: env var "${envVar}" is not set. Generate a key via \`openssl rand -base64 32\` and export it before starting the process.`
+    );
+  }
+  let keyBytes;
+  try {
+    keyBytes = base64ToBytes(raw);
+  } catch (err) {
+    throw new Error(
+      `@noy-db/at-env: env var "${envVar}" is not valid base64 \u2014 ` + (err instanceof Error ? err.message : String(err))
+    );
+  }
+  if (keyBytes.length !== 32) {
+    throw new Error(
+      `@noy-db/at-env: env var "${envVar}" decodes to ${keyBytes.length} bytes; expected 32 bytes (256-bit AES key). Regenerate via \`openssl rand -base64 32\`.`
+    );
+  }
+  let cachedKey = null;
+  const getKey = () => {
+    if (!cachedKey) {
+      cachedKey = globalThis.crypto.subtle.importKey(
+        "raw",
+        keyBytes,
+        "AES-GCM",
+        false,
+        ["encrypt", "decrypt"]
+      );
+    }
+    return cachedKey;
+  };
+  return {
+    id: `env:${envVar}`,
+    async seal(passphrase) {
+      const key = await getKey();
+      const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
+      const ciphertext = await globalThis.crypto.subtle.encrypt(
+        { name: "AES-GCM", iv },
+        key,
+        passphrase
+      );
+      const out = new Uint8Array(12 + ciphertext.byteLength);
+      out.set(iv, 0);
+      out.set(new Uint8Array(ciphertext), 12);
+      return out;
+    },
+    async unseal(sealed) {
+      if (sealed.length < 12 + 16) {
+        throw new Error(
+          `@noy-db/at-env: sealed bytes too short (${sealed.length} < 28). Input is not a valid at-env-sealed envelope.`
+        );
+      }
+      const iv = sealed.subarray(0, 12);
+      const body = sealed.subarray(12);
+      const key = await getKey();
+      const plaintext = await globalThis.crypto.subtle.decrypt(
+        { name: "AES-GCM", iv },
+        key,
+        body
+      );
+      return new Uint8Array(plaintext);
+    }
+  };
+}
+function base64ToBytes(b64) {
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64.trim())) {
+    throw new Error("input contains characters outside the base64 alphabet");
+  }
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  envSealingProvider
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/at-env** — env-var sealing key provider for noy-db\n * managed-passphrase mode (#14).\n *\n * The smallest production-shape provider in the `at-*` family. Reads a\n * 32-byte AES-256-GCM key from an environment variable (base64-encoded)\n * and uses it to seal / unseal the hub-generated random passphrase.\n *\n * ## When to use\n *\n * - Single-node SaaS where the env var comes from Kubernetes Secrets,\n *   Heroku env, Doppler, AWS Secrets Manager (mounted at boot), systemd\n *   service env, etc. — anywhere your platform already manages secrets.\n * - Local dev / CI where you want persistence across process restarts\n *   (which `MemorySealingKeyProvider` from `@noy-db/hub` can't do).\n * - Prototypes where setting up AWS KMS / GCP KMS isn't worth the effort.\n *\n * ## When NOT to use\n *\n * - Laptops / shared dev machines where other users have shell access.\n *   They can `echo $NOYDB_SEALING_KEY` and exfiltrate the key. Use\n *   `@noy-db/at-macos-keychain` / `@noy-db/at-wincred` /\n *   `@noy-db/at-libsecret` for desktop apps.\n * - Compliance regimes requiring auditable key access (FedRAMP, HIPAA\n *   with managed-encryption requirements). Use `@noy-db/at-aws-kms` for\n *   KMS-backed key access logs.\n *\n * ## Setup\n *\n * ```bash\n * # 1. Generate a 256-bit key once. Store in your platform's secret manager.\n * export NOYDB_SEALING_KEY=$(openssl rand -base64 32)\n * ```\n *\n * ```ts\n * // 2. In your app:\n * import { createNoydb } from '@noy-db/hub'\n * import { envSealingProvider } from '@noy-db/at-env'\n *\n * const db = await createNoydb({\n *   store,\n *   user: 'alice',\n *   passphraseMode: 'managed',\n *   sealingKey: envSealingProvider(),  // reads NOYDB_SEALING_KEY by default\n * })\n * ```\n *\n * @packageDocumentation\n */\n\nimport type { SealingKeyProvider } from '@noy-db/hub'\n\n/** Options for {@link envSealingProvider}. */\nexport interface EnvSealingProviderOptions {\n  /**\n   * Environment variable name holding the base64-encoded 32-byte AES-256\n   * key. Default `'NOYDB_SEALING_KEY'`.\n   */\n  readonly envVar?: string\n}\n\n/**\n * Build a {@link SealingKeyProvider} backed by an environment variable.\n *\n * The env var must contain a base64-encoded 32-byte (256-bit) key. The\n * provider validates the value at construction time and caches the\n * imported `CryptoKey` for the lifetime of the instance.\n *\n * @throws Error when the env var is unset, not base64, or not 32 bytes.\n */\nexport function envSealingProvider(\n  opts: EnvSealingProviderOptions = {},\n): SealingKeyProvider {\n  const envVar = opts.envVar ?? 'NOYDB_SEALING_KEY'\n  const raw = process.env[envVar]\n  if (!raw) {\n    throw new Error(\n      `@noy-db/at-env: env var \"${envVar}\" is not set. Generate a key via `\n      + '`openssl rand -base64 32` and export it before starting the process.',\n    )\n  }\n\n  let keyBytes: Uint8Array\n  try {\n    keyBytes = base64ToBytes(raw)\n  } catch (err) {\n    throw new Error(\n      `@noy-db/at-env: env var \"${envVar}\" is not valid base64 — `\n      + (err instanceof Error ? err.message : String(err)),\n    )\n  }\n\n  if (keyBytes.length !== 32) {\n    throw new Error(\n      `@noy-db/at-env: env var \"${envVar}\" decodes to ${keyBytes.length} bytes; `\n      + 'expected 32 bytes (256-bit AES key). Regenerate via `openssl rand -base64 32`.',\n    )\n  }\n\n  // Lazy + cached import — the CryptoKey is created on first seal/unseal\n  // and reused for the lifetime of the provider instance.\n  let cachedKey: Promise<CryptoKey> | null = null\n  const getKey = (): Promise<CryptoKey> => {\n    if (!cachedKey) {\n      cachedKey = globalThis.crypto.subtle.importKey(\n        'raw',\n        keyBytes as unknown as BufferSource,\n        'AES-GCM',\n        false,\n        ['encrypt', 'decrypt'],\n      )\n    }\n    return cachedKey\n  }\n\n  return {\n    id: `env:${envVar}`,\n\n    async seal(passphrase: Uint8Array): Promise<Uint8Array> {\n      const key = await getKey()\n      const iv = globalThis.crypto.getRandomValues(new Uint8Array(12))\n      const ciphertext = await globalThis.crypto.subtle.encrypt(\n        { name: 'AES-GCM', iv: iv as BufferSource },\n        key,\n        passphrase as unknown as BufferSource,\n      )\n      // Output format: [12-byte IV][ciphertext + 16-byte GCM tag]\n      const out = new Uint8Array(12 + ciphertext.byteLength)\n      out.set(iv, 0)\n      out.set(new Uint8Array(ciphertext), 12)\n      return out\n    },\n\n    async unseal(sealed: Uint8Array): Promise<Uint8Array> {\n      // 12-byte IV + ≥ 16-byte GCM tag minimum.\n      if (sealed.length < 12 + 16) {\n        throw new Error(\n          `@noy-db/at-env: sealed bytes too short (${sealed.length} < 28). `\n          + 'Input is not a valid at-env-sealed envelope.',\n        )\n      }\n      const iv = sealed.subarray(0, 12)\n      const body = sealed.subarray(12)\n      const key = await getKey()\n      const plaintext = await globalThis.crypto.subtle.decrypt(\n        { name: 'AES-GCM', iv: iv as BufferSource },\n        key,\n        body as unknown as BufferSource,\n      )\n      return new Uint8Array(plaintext)\n    },\n  }\n}\n\n// ─── base64 helpers (browser + node + cf-workers compatible) ──────────\n\nfunction base64ToBytes(b64: string): Uint8Array {\n  // Reject obviously malformed strings before atob throws InvalidCharacterError,\n  // so the wrapping error message is informative.\n  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64.trim())) {\n    throw new Error('input contains characters outside the base64 alphabet')\n  }\n  const binary = atob(b64)\n  const out = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i)\n  return out\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAsEO,SAAS,mBACd,OAAkC,CAAC,GACf;AACpB,QAAM,SAAS,KAAK,UAAU;AAC9B,QAAM,MAAM,QAAQ,IAAI,MAAM;AAC9B,MAAI,CAAC,KAAK;AACR,UAAM,IAAI;AAAA,MACR,4BAA4B,MAAM;AAAA,IAEpC;AAAA,EACF;AAEA,MAAI;AACJ,MAAI;AACF,eAAW,cAAc,GAAG;AAAA,EAC9B,SAAS,KAAK;AACZ,UAAM,IAAI;AAAA,MACR,4BAA4B,MAAM,mCAC/B,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,IACpD;AAAA,EACF;AAEA,MAAI,SAAS,WAAW,IAAI;AAC1B,UAAM,IAAI;AAAA,MACR,4BAA4B,MAAM,gBAAgB,SAAS,MAAM;AAAA,IAEnE;AAAA,EACF;AAIA,MAAI,YAAuC;AAC3C,QAAM,SAAS,MAA0B;AACvC,QAAI,CAAC,WAAW;AACd,kBAAY,WAAW,OAAO,OAAO;AAAA,QACnC;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA,CAAC,WAAW,SAAS;AAAA,MACvB;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,IAAI,OAAO,MAAM;AAAA,IAEjB,MAAM,KAAK,YAA6C;AACtD,YAAM,MAAM,MAAM,OAAO;AACzB,YAAM,KAAK,WAAW,OAAO,gBAAgB,IAAI,WAAW,EAAE,CAAC;AAC/D,YAAM,aAAa,MAAM,WAAW,OAAO,OAAO;AAAA,QAChD,EAAE,MAAM,WAAW,GAAuB;AAAA,QAC1C;AAAA,QACA;AAAA,MACF;AAEA,YAAM,MAAM,IAAI,WAAW,KAAK,WAAW,UAAU;AACrD,UAAI,IAAI,IAAI,CAAC;AACb,UAAI,IAAI,IAAI,WAAW,UAAU,GAAG,EAAE;AACtC,aAAO;AAAA,IACT;AAAA,IAEA,MAAM,OAAO,QAAyC;AAEpD,UAAI,OAAO,SAAS,KAAK,IAAI;AAC3B,cAAM,IAAI;AAAA,UACR,2CAA2C,OAAO,MAAM;AAAA,QAE1D;AAAA,MACF;AACA,YAAM,KAAK,OAAO,SAAS,GAAG,EAAE;AAChC,YAAM,OAAO,OAAO,SAAS,EAAE;AAC/B,YAAM,MAAM,MAAM,OAAO;AACzB,YAAM,YAAY,MAAM,WAAW,OAAO,OAAO;AAAA,QAC/C,EAAE,MAAM,WAAW,GAAuB;AAAA,QAC1C;AAAA,QACA;AAAA,MACF;AACA,aAAO,IAAI,WAAW,SAAS;AAAA,IACjC;AAAA,EACF;AACF;AAIA,SAAS,cAAc,KAAyB;AAG9C,MAAI,CAAC,yBAAyB,KAAK,IAAI,KAAK,CAAC,GAAG;AAC9C,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACzE;AACA,QAAM,SAAS,KAAK,GAAG;AACvB,QAAM,MAAM,IAAI,WAAW,OAAO,MAAM;AACxC,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,IAAK,KAAI,CAAC,IAAI,OAAO,WAAW,CAAC;AACpE,SAAO;AACT;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,72 @@
+import { SealingKeyProvider } from '@noy-db/hub';
+
+/**
+ * **@noy-db/at-env** — env-var sealing key provider for noy-db
+ * managed-passphrase mode (#14).
+ *
+ * The smallest production-shape provider in the `at-*` family. Reads a
+ * 32-byte AES-256-GCM key from an environment variable (base64-encoded)
+ * and uses it to seal / unseal the hub-generated random passphrase.
+ *
+ * ## When to use
+ *
+ * - Single-node SaaS where the env var comes from Kubernetes Secrets,
+ *   Heroku env, Doppler, AWS Secrets Manager (mounted at boot), systemd
+ *   service env, etc. — anywhere your platform already manages secrets.
+ * - Local dev / CI where you want persistence across process restarts
+ *   (which `MemorySealingKeyProvider` from `@noy-db/hub` can't do).
+ * - Prototypes where setting up AWS KMS / GCP KMS isn't worth the effort.
+ *
+ * ## When NOT to use
+ *
+ * - Laptops / shared dev machines where other users have shell access.
+ *   They can `echo $NOYDB_SEALING_KEY` and exfiltrate the key. Use
+ *   `@noy-db/at-macos-keychain` / `@noy-db/at-wincred` /
+ *   `@noy-db/at-libsecret` for desktop apps.
+ * - Compliance regimes requiring auditable key access (FedRAMP, HIPAA
+ *   with managed-encryption requirements). Use `@noy-db/at-aws-kms` for
+ *   KMS-backed key access logs.
+ *
+ * ## Setup
+ *
+ * ```bash
+ * # 1. Generate a 256-bit key once. Store in your platform's secret manager.
+ * export NOYDB_SEALING_KEY=$(openssl rand -base64 32)
+ * ```
+ *
+ * ```ts
+ * // 2. In your app:
+ * import { createNoydb } from '@noy-db/hub'
+ * import { envSealingProvider } from '@noy-db/at-env'
+ *
+ * const db = await createNoydb({
+ *   store,
+ *   user: 'alice',
+ *   passphraseMode: 'managed',
+ *   sealingKey: envSealingProvider(),  // reads NOYDB_SEALING_KEY by default
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** Options for {@link envSealingProvider}. */
+interface EnvSealingProviderOptions {
+    /**
+     * Environment variable name holding the base64-encoded 32-byte AES-256
+     * key. Default `'NOYDB_SEALING_KEY'`.
+     */
+    readonly envVar?: string;
+}
+/**
+ * Build a {@link SealingKeyProvider} backed by an environment variable.
+ *
+ * The env var must contain a base64-encoded 32-byte (256-bit) key. The
+ * provider validates the value at construction time and caches the
+ * imported `CryptoKey` for the lifetime of the instance.
+ *
+ * @throws Error when the env var is unset, not base64, or not 32 bytes.
+ */
+declare function envSealingProvider(opts?: EnvSealingProviderOptions): SealingKeyProvider;
+
+export { type EnvSealingProviderOptions, envSealingProvider };

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { SealingKeyProvider } from '@noy-db/hub';
+
+/**
+ * **@noy-db/at-env** — env-var sealing key provider for noy-db
+ * managed-passphrase mode (#14).
+ *
+ * The smallest production-shape provider in the `at-*` family. Reads a
+ * 32-byte AES-256-GCM key from an environment variable (base64-encoded)
+ * and uses it to seal / unseal the hub-generated random passphrase.
+ *
+ * ## When to use
+ *
+ * - Single-node SaaS where the env var comes from Kubernetes Secrets,
+ *   Heroku env, Doppler, AWS Secrets Manager (mounted at boot), systemd
+ *   service env, etc. — anywhere your platform already manages secrets.
+ * - Local dev / CI where you want persistence across process restarts
+ *   (which `MemorySealingKeyProvider` from `@noy-db/hub` can't do).
+ * - Prototypes where setting up AWS KMS / GCP KMS isn't worth the effort.
+ *
+ * ## When NOT to use
+ *
+ * - Laptops / shared dev machines where other users have shell access.
+ *   They can `echo $NOYDB_SEALING_KEY` and exfiltrate the key. Use
+ *   `@noy-db/at-macos-keychain` / `@noy-db/at-wincred` /
+ *   `@noy-db/at-libsecret` for desktop apps.
+ * - Compliance regimes requiring auditable key access (FedRAMP, HIPAA
+ *   with managed-encryption requirements). Use `@noy-db/at-aws-kms` for
+ *   KMS-backed key access logs.
+ *
+ * ## Setup
+ *
+ * ```bash
+ * # 1. Generate a 256-bit key once. Store in your platform's secret manager.
+ * export NOYDB_SEALING_KEY=$(openssl rand -base64 32)
+ * ```
+ *
+ * ```ts
+ * // 2. In your app:
+ * import { createNoydb } from '@noy-db/hub'
+ * import { envSealingProvider } from '@noy-db/at-env'
+ *
+ * const db = await createNoydb({
+ *   store,
+ *   user: 'alice',
+ *   passphraseMode: 'managed',
+ *   sealingKey: envSealingProvider(),  // reads NOYDB_SEALING_KEY by default
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** Options for {@link envSealingProvider}. */
+interface EnvSealingProviderOptions {
+    /**
+     * Environment variable name holding the base64-encoded 32-byte AES-256
+     * key. Default `'NOYDB_SEALING_KEY'`.
+     */
+    readonly envVar?: string;
+}
+/**
+ * Build a {@link SealingKeyProvider} backed by an environment variable.
+ *
+ * The env var must contain a base64-encoded 32-byte (256-bit) key. The
+ * provider validates the value at construction time and caches the
+ * imported `CryptoKey` for the lifetime of the instance.
+ *
+ * @throws Error when the env var is unset, not base64, or not 32 bytes.
+ */
+declare function envSealingProvider(opts?: EnvSealingProviderOptions): SealingKeyProvider;
+
+export { type EnvSealingProviderOptions, envSealingProvider };

package/dist/index.js

@@ -0,0 +1,81 @@
+// src/index.ts
+function envSealingProvider(opts = {}) {
+  const envVar = opts.envVar ?? "NOYDB_SEALING_KEY";
+  const raw = process.env[envVar];
+  if (!raw) {
+    throw new Error(
+      `@noy-db/at-env: env var "${envVar}" is not set. Generate a key via \`openssl rand -base64 32\` and export it before starting the process.`
+    );
+  }
+  let keyBytes;
+  try {
+    keyBytes = base64ToBytes(raw);
+  } catch (err) {
+    throw new Error(
+      `@noy-db/at-env: env var "${envVar}" is not valid base64 \u2014 ` + (err instanceof Error ? err.message : String(err))
+    );
+  }
+  if (keyBytes.length !== 32) {
+    throw new Error(
+      `@noy-db/at-env: env var "${envVar}" decodes to ${keyBytes.length} bytes; expected 32 bytes (256-bit AES key). Regenerate via \`openssl rand -base64 32\`.`
+    );
+  }
+  let cachedKey = null;
+  const getKey = () => {
+    if (!cachedKey) {
+      cachedKey = globalThis.crypto.subtle.importKey(
+        "raw",
+        keyBytes,
+        "AES-GCM",
+        false,
+        ["encrypt", "decrypt"]
+      );
+    }
+    return cachedKey;
+  };
+  return {
+    id: `env:${envVar}`,
+    async seal(passphrase) {
+      const key = await getKey();
+      const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
+      const ciphertext = await globalThis.crypto.subtle.encrypt(
+        { name: "AES-GCM", iv },
+        key,
+        passphrase
+      );
+      const out = new Uint8Array(12 + ciphertext.byteLength);
+      out.set(iv, 0);
+      out.set(new Uint8Array(ciphertext), 12);
+      return out;
+    },
+    async unseal(sealed) {
+      if (sealed.length < 12 + 16) {
+        throw new Error(
+          `@noy-db/at-env: sealed bytes too short (${sealed.length} < 28). Input is not a valid at-env-sealed envelope.`
+        );
+      }
+      const iv = sealed.subarray(0, 12);
+      const body = sealed.subarray(12);
+      const key = await getKey();
+      const plaintext = await globalThis.crypto.subtle.decrypt(
+        { name: "AES-GCM", iv },
+        key,
+        body
+      );
+      return new Uint8Array(plaintext);
+    }
+  };
+}
+function base64ToBytes(b64) {
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64.trim())) {
+    throw new Error("input contains characters outside the base64 alphabet");
+  }
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+export {
+  envSealingProvider
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/at-env** — env-var sealing key provider for noy-db\n * managed-passphrase mode (#14).\n *\n * The smallest production-shape provider in the `at-*` family. Reads a\n * 32-byte AES-256-GCM key from an environment variable (base64-encoded)\n * and uses it to seal / unseal the hub-generated random passphrase.\n *\n * ## When to use\n *\n * - Single-node SaaS where the env var comes from Kubernetes Secrets,\n *   Heroku env, Doppler, AWS Secrets Manager (mounted at boot), systemd\n *   service env, etc. — anywhere your platform already manages secrets.\n * - Local dev / CI where you want persistence across process restarts\n *   (which `MemorySealingKeyProvider` from `@noy-db/hub` can't do).\n * - Prototypes where setting up AWS KMS / GCP KMS isn't worth the effort.\n *\n * ## When NOT to use\n *\n * - Laptops / shared dev machines where other users have shell access.\n *   They can `echo $NOYDB_SEALING_KEY` and exfiltrate the key. Use\n *   `@noy-db/at-macos-keychain` / `@noy-db/at-wincred` /\n *   `@noy-db/at-libsecret` for desktop apps.\n * - Compliance regimes requiring auditable key access (FedRAMP, HIPAA\n *   with managed-encryption requirements). Use `@noy-db/at-aws-kms` for\n *   KMS-backed key access logs.\n *\n * ## Setup\n *\n * ```bash\n * # 1. Generate a 256-bit key once. Store in your platform's secret manager.\n * export NOYDB_SEALING_KEY=$(openssl rand -base64 32)\n * ```\n *\n * ```ts\n * // 2. In your app:\n * import { createNoydb } from '@noy-db/hub'\n * import { envSealingProvider } from '@noy-db/at-env'\n *\n * const db = await createNoydb({\n *   store,\n *   user: 'alice',\n *   passphraseMode: 'managed',\n *   sealingKey: envSealingProvider(),  // reads NOYDB_SEALING_KEY by default\n * })\n * ```\n *\n * @packageDocumentation\n */\n\nimport type { SealingKeyProvider } from '@noy-db/hub'\n\n/** Options for {@link envSealingProvider}. */\nexport interface EnvSealingProviderOptions {\n  /**\n   * Environment variable name holding the base64-encoded 32-byte AES-256\n   * key. Default `'NOYDB_SEALING_KEY'`.\n   */\n  readonly envVar?: string\n}\n\n/**\n * Build a {@link SealingKeyProvider} backed by an environment variable.\n *\n * The env var must contain a base64-encoded 32-byte (256-bit) key. The\n * provider validates the value at construction time and caches the\n * imported `CryptoKey` for the lifetime of the instance.\n *\n * @throws Error when the env var is unset, not base64, or not 32 bytes.\n */\nexport function envSealingProvider(\n  opts: EnvSealingProviderOptions = {},\n): SealingKeyProvider {\n  const envVar = opts.envVar ?? 'NOYDB_SEALING_KEY'\n  const raw = process.env[envVar]\n  if (!raw) {\n    throw new Error(\n      `@noy-db/at-env: env var \"${envVar}\" is not set. Generate a key via `\n      + '`openssl rand -base64 32` and export it before starting the process.',\n    )\n  }\n\n  let keyBytes: Uint8Array\n  try {\n    keyBytes = base64ToBytes(raw)\n  } catch (err) {\n    throw new Error(\n      `@noy-db/at-env: env var \"${envVar}\" is not valid base64 — `\n      + (err instanceof Error ? err.message : String(err)),\n    )\n  }\n\n  if (keyBytes.length !== 32) {\n    throw new Error(\n      `@noy-db/at-env: env var \"${envVar}\" decodes to ${keyBytes.length} bytes; `\n      + 'expected 32 bytes (256-bit AES key). Regenerate via `openssl rand -base64 32`.',\n    )\n  }\n\n  // Lazy + cached import — the CryptoKey is created on first seal/unseal\n  // and reused for the lifetime of the provider instance.\n  let cachedKey: Promise<CryptoKey> | null = null\n  const getKey = (): Promise<CryptoKey> => {\n    if (!cachedKey) {\n      cachedKey = globalThis.crypto.subtle.importKey(\n        'raw',\n        keyBytes as unknown as BufferSource,\n        'AES-GCM',\n        false,\n        ['encrypt', 'decrypt'],\n      )\n    }\n    return cachedKey\n  }\n\n  return {\n    id: `env:${envVar}`,\n\n    async seal(passphrase: Uint8Array): Promise<Uint8Array> {\n      const key = await getKey()\n      const iv = globalThis.crypto.getRandomValues(new Uint8Array(12))\n      const ciphertext = await globalThis.crypto.subtle.encrypt(\n        { name: 'AES-GCM', iv: iv as BufferSource },\n        key,\n        passphrase as unknown as BufferSource,\n      )\n      // Output format: [12-byte IV][ciphertext + 16-byte GCM tag]\n      const out = new Uint8Array(12 + ciphertext.byteLength)\n      out.set(iv, 0)\n      out.set(new Uint8Array(ciphertext), 12)\n      return out\n    },\n\n    async unseal(sealed: Uint8Array): Promise<Uint8Array> {\n      // 12-byte IV + ≥ 16-byte GCM tag minimum.\n      if (sealed.length < 12 + 16) {\n        throw new Error(\n          `@noy-db/at-env: sealed bytes too short (${sealed.length} < 28). `\n          + 'Input is not a valid at-env-sealed envelope.',\n        )\n      }\n      const iv = sealed.subarray(0, 12)\n      const body = sealed.subarray(12)\n      const key = await getKey()\n      const plaintext = await globalThis.crypto.subtle.decrypt(\n        { name: 'AES-GCM', iv: iv as BufferSource },\n        key,\n        body as unknown as BufferSource,\n      )\n      return new Uint8Array(plaintext)\n    },\n  }\n}\n\n// ─── base64 helpers (browser + node + cf-workers compatible) ──────────\n\nfunction base64ToBytes(b64: string): Uint8Array {\n  // Reject obviously malformed strings before atob throws InvalidCharacterError,\n  // so the wrapping error message is informative.\n  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64.trim())) {\n    throw new Error('input contains characters outside the base64 alphabet')\n  }\n  const binary = atob(b64)\n  const out = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i)\n  return out\n}\n"],"mappings":";AAsEO,SAAS,mBACd,OAAkC,CAAC,GACf;AACpB,QAAM,SAAS,KAAK,UAAU;AAC9B,QAAM,MAAM,QAAQ,IAAI,MAAM;AAC9B,MAAI,CAAC,KAAK;AACR,UAAM,IAAI;AAAA,MACR,4BAA4B,MAAM;AAAA,IAEpC;AAAA,EACF;AAEA,MAAI;AACJ,MAAI;AACF,eAAW,cAAc,GAAG;AAAA,EAC9B,SAAS,KAAK;AACZ,UAAM,IAAI;AAAA,MACR,4BAA4B,MAAM,mCAC/B,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,IACpD;AAAA,EACF;AAEA,MAAI,SAAS,WAAW,IAAI;AAC1B,UAAM,IAAI;AAAA,MACR,4BAA4B,MAAM,gBAAgB,SAAS,MAAM;AAAA,IAEnE;AAAA,EACF;AAIA,MAAI,YAAuC;AAC3C,QAAM,SAAS,MAA0B;AACvC,QAAI,CAAC,WAAW;AACd,kBAAY,WAAW,OAAO,OAAO;AAAA,QACnC;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA,CAAC,WAAW,SAAS;AAAA,MACvB;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,IAAI,OAAO,MAAM;AAAA,IAEjB,MAAM,KAAK,YAA6C;AACtD,YAAM,MAAM,MAAM,OAAO;AACzB,YAAM,KAAK,WAAW,OAAO,gBAAgB,IAAI,WAAW,EAAE,CAAC;AAC/D,YAAM,aAAa,MAAM,WAAW,OAAO,OAAO;AAAA,QAChD,EAAE,MAAM,WAAW,GAAuB;AAAA,QAC1C;AAAA,QACA;AAAA,MACF;AAEA,YAAM,MAAM,IAAI,WAAW,KAAK,WAAW,UAAU;AACrD,UAAI,IAAI,IAAI,CAAC;AACb,UAAI,IAAI,IAAI,WAAW,UAAU,GAAG,EAAE;AACtC,aAAO;AAAA,IACT;AAAA,IAEA,MAAM,OAAO,QAAyC;AAEpD,UAAI,OAAO,SAAS,KAAK,IAAI;AAC3B,cAAM,IAAI;AAAA,UACR,2CAA2C,OAAO,MAAM;AAAA,QAE1D;AAAA,MACF;AACA,YAAM,KAAK,OAAO,SAAS,GAAG,EAAE;AAChC,YAAM,OAAO,OAAO,SAAS,EAAE;AAC/B,YAAM,MAAM,MAAM,OAAO;AACzB,YAAM,YAAY,MAAM,WAAW,OAAO,OAAO;AAAA,QAC/C,EAAE,MAAM,WAAW,GAAuB;AAAA,QAC1C;AAAA,QACA;AAAA,MACF;AACA,aAAO,IAAI,WAAW,SAAS;AAAA,IACjC;AAAA,EACF;AACF;AAIA,SAAS,cAAc,KAAyB;AAG9C,MAAI,CAAC,yBAAyB,KAAK,IAAI,KAAK,CAAC,GAAG;AAC9C,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACzE;AACA,QAAM,SAAS,KAAK,GAAG;AACvB,QAAM,MAAM,IAAI,WAAW,OAAO,MAAM;AACxC,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,IAAK,KAAI,CAAC,IAAI,OAAO,WAAW,CAAC;AACpE,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@noy-db/at-env",
+  "version": "0.1.0-pre.16",
+  "description": "Env-var sealing key provider for noy-db managed-passphrase mode — AES-256-GCM under a key from process.env. Smallest production-shape provider; pair with Kubernetes Secrets / Heroku env / AWS Secrets Manager.",
+  "license": "MIT",
+  "author": "vLannaAi <vicio@lanna.ai>",
+  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/at-env#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vLannaAi/noy-db.git",
+    "directory": "packages/at-env"
+  },
+  "bugs": {
+    "url": "https://github.com/vLannaAi/noy-db/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@noy-db/hub": "0.1.0-pre.16"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@noy-db/hub": "0.1.0-pre.16",
+    "@noy-db/to-memory": "0.1.0-pre.16"
+  },
+  "keywords": [
+    "noy-db",
+    "at-env",
+    "sealing-key-provider",
+    "managed-passphrase",
+    "env",
+    "rubber-hose-resistant",
+    "aes-256-gcm",
+    "encryption",
+    "zero-knowledge"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}