@mstone6969/vault 0.2.0 → 0.5.0

package/dist/index.js

@@ -46,47 +46,269 @@ async function open(key, sealed) {
   }
 }
 
+// src/providers.ts
+function staticKey(key) {
+  return { key: () => key };
+}
+function envKey(name) {
+  return {
+    key() {
+      const value = process.env[name];
+      if (!value) {
+        throw new VaultKeyError(`${name} is not set, so there is no key to open with.`);
+      }
+      return value;
+    }
+  };
+}
+function fileKey(path) {
+  return {
+    async key() {
+      const file = Bun.file(path);
+      if (!await file.exists()) {
+        throw new VaultKeyError(`No key file at ${path}.`);
+      }
+      const contents = (await file.text()).trim();
+      if (!contents)
+        throw new VaultKeyError(`The key file at ${path} is empty.`);
+      return contents;
+    }
+  };
+}
+function isKeyProvider(value) {
+  return typeof value?.key === "function";
+}
+
 // src/vault.ts
 var DEFAULT_PREFIX = "@vault:";
+var DEFAULT_HISTORY_LIMIT = 5;
 var NAME_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+var DEFAULT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+function randomValue(length = 32, alphabet = DEFAULT_ALPHABET) {
+  if (length < 1)
+    throw new VaultError("A generated value needs at least one character.");
+  if (alphabet.length < 2) {
+    throw new VaultError("A generated value needs an alphabet of at least two characters.");
+  }
+  const ceiling = Math.floor(256 / alphabet.length) * alphabet.length;
+  let value = "";
+  while (value.length < length) {
+    const bytes = crypto.getRandomValues(new Uint8Array(length));
+    for (const byte of bytes) {
+      if (byte >= ceiling)
+        continue;
+      value += alphabet[byte % alphabet.length];
+      if (value.length === length)
+        break;
+    }
+  }
+  return value;
+}
+function toKey(key) {
+  const provider = isKeyProvider(key) ? key : staticKey(key);
+  return Promise.resolve(provider.key()).then((resolved) => typeof resolved === "string" ? importKey(resolved) : resolved);
+}
+function summarise(record) {
+  const { sealed: _sealed, sealedKey: _key, plain, history, ...rest } = record;
+  const summary = { ...rest, versions: history.length };
+  if (!record.isSealed && plain !== null)
+    summary.value = plain;
+  return summary;
+}
+function isExpired(record, now) {
+  return record.expiresAt !== null && record.expiresAt.getTime() <= now.getTime();
+}
 
 class Vault {
-  key;
+  keySource;
+  previousSources;
+  keyCache = null;
+  previousCache = null;
   store;
+  historyLimit;
+  generators;
+  onAccess;
   prefix;
-  constructor({ key, store, prefix = DEFAULT_PREFIX }) {
-    this.key = typeof key === "string" ? importKey(key) : Promise.resolve(key);
+  constructor({
+    key,
+    store,
+    prefix = DEFAULT_PREFIX,
+    previousKeys = [],
+    historyLimit = DEFAULT_HISTORY_LIMIT,
+    generators = {},
+    onAccess
+  }) {
+    this.keySource = key;
+    this.previousSources = previousKeys;
     this.store = store;
     this.prefix = prefix;
+    this.historyLimit = historyLimit;
+    this.generators = generators;
+    this.onAccess = onAccess;
+  }
+  master() {
+    this.keyCache ??= toKey(this.keySource);
+    return this.keyCache;
+  }
+  retired() {
+    this.previousCache ??= this.previousSources.map(toKey);
+    return this.previousCache;
+  }
+  record(event) {
+    if (!this.onAccess)
+      return;
+    try {
+      this.onAccess({ ...event, at: new Date });
+    } catch {}
+  }
+  async unsealWithMaster(sealed) {
+    try {
+      return await open(await this.master(), sealed);
+    } catch (error) {
+      for (const previous of this.retired()) {
+        try {
+          return await open(await previous, sealed);
+        } catch {}
+      }
+      throw error;
+    }
+  }
+  async unseal(sealed, sealedKey) {
+    if (!sealedKey) {
+      return this.unsealWithMaster(sealed);
+    }
+    const dataKey = await importKey(await this.unsealWithMaster(sealedKey));
+    return open(dataKey, sealed);
+  }
+  async enseal(value) {
+    const material = generateKey();
+    const dataKey = await importKey(material);
+    return {
+      sealed: await seal(dataKey, value),
+      sealedKey: await seal(await this.master(), material)
+    };
+  }
+  checkName(name) {
+    const clean = String(name ?? "").trim();
+    if (!NAME_PATTERN.test(clean)) {
+      throw new VaultError("A name can be up to 64 characters: letters, numbers, dot, dash or underscore.");
+    }
+    return clean;
   }
   async list(owner) {
     const records = await this.store.list(owner);
-    return records.map(({ sealed: _sealed, ...summary }) => summary).sort((a, b) => a.name.localeCompare(b.name));
+    return records.map(summarise).sort((a, b) => a.name.localeCompare(b.name));
   }
-  async put(owner, name, value, metadata = {}) {
+  async put(owner, name, value, options = {}) {
     const clean = this.checkName(name);
     if (!value)
       throw new VaultError("A secret needs a value.");
-    const sealed = await seal(await this.key, value);
-    const { sealed: _sealed, ...summary } = await this.store.put({
+    const existing = await this.store.get(owner, clean);
+    if (existing?.isFinal) {
+      this.record({ action: "denied", owner, name: clean, detail: "final" });
+      throw new VaultError(`"${clean}" is final: it cannot be changed, only deleted.`, 409);
+    }
+    const now = new Date;
+    const isSealed = options.open === undefined ? existing?.isSealed ?? true : !options.open;
+    const history = options.keepHistory && existing && existing.sealed ? [
+      {
+        sealed: existing.sealed,
+        sealedKey: existing.sealedKey,
+        createdAt: existing.updatedAt
+      },
+      ...existing.history
+    ].slice(0, this.historyLimit) : existing?.history ?? [];
+    const body = isSealed ? { ...await this.enseal(value), plain: null } : { sealed: "", sealedKey: null, plain: value };
+    const stored = await this.store.put({
       owner,
       name: clean,
-      sealed,
-      metadata
+      ...body,
+      isSealed,
+      isFinal: options.final === true,
+      rotation: options.rotation === undefined ? existing?.rotation ?? null : options.rotation,
+      rotatedAt: existing?.rotatedAt ?? null,
+      expiresAt: options.expiresAt === undefined ? existing?.expiresAt ?? null : options.expiresAt,
+      history,
+      metadata: options.metadata ?? existing?.metadata ?? {},
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now
     });
-    return summary;
+    this.record({ action: "put", owner, name: clean });
+    return summarise(stored);
+  }
+  async rotate(owner, name, value, options = {}) {
+    const clean = this.checkName(name);
+    const next = value ?? await this.generate(owner, clean);
+    this.record({ action: "rotate", owner, name: clean });
+    const summary = await this.put(owner, clean, next, { ...options, keepHistory: true });
+    const stored = await this.store.get(owner, clean);
+    if (stored)
+      await this.store.put({ ...stored, rotatedAt: new Date });
+    return { ...summary, rotatedAt: new Date };
+  }
+  async generate(owner, name) {
+    const record = await this.require(owner, name);
+    const policy = record.rotation;
+    if (!policy) {
+      throw new VaultError(`"${name}" has no rotation policy, so there is nothing to make the next value with.`);
+    }
+    if (policy.kind === "random") {
+      return randomValue(policy.length, policy.alphabet);
+    }
+    const generator = policy.generator ? this.generators[policy.generator] : undefined;
+    if (!generator) {
+      throw new VaultError(`"${name}" wants the "${policy.generator ?? "unnamed"}" generator, which this vault does not have.`, 501);
+    }
+    return generator({ owner, name, arguments: policy.arguments ?? {} });
+  }
+  async rotationDue(now = new Date) {
+    const records = await this.store.all();
+    return records.filter((record) => {
+      const every = record.rotation?.every;
+      if (!every)
+        return false;
+      const last = (record.rotatedAt ?? record.createdAt).getTime();
+      return now.getTime() - last >= every * 1000;
+    }).map(summarise);
+  }
+  async versions(owner, name) {
+    const record = await this.require(owner, name);
+    return Promise.all(record.history.map((entry) => this.unseal(entry.sealed, entry.sealedKey)));
   }
   async has(owner, name) {
     return await this.store.get(owner, this.checkName(name)) !== null;
   }
-  remove(owner, name) {
-    return this.store.remove(owner, this.checkName(name));
+  async remove(owner, name) {
+    const removed = await this.store.remove(owner, this.checkName(name));
+    if (removed)
+      this.record({ action: "remove", owner, name });
+    return removed;
   }
-  async open(owner, name) {
-    const record = await this.store.get(owner, this.checkName(name));
+  async require(owner, name, now = new Date) {
+    const clean = this.checkName(name);
+    const record = await this.store.get(owner, clean);
     if (!record)
-      throw new VaultError(`No secret named "${name}" in the vault.`, 404);
-    return open(await this.key, record.sealed);
+      throw new VaultError(`No secret named "${clean}" in the vault.`, 404);
+    if (isExpired(record, now)) {
+      this.record({ action: "denied", owner, name: clean, detail: "expired" });
+      throw new VaultError(`"${clean}" expired and can no longer be used.`, 410);
+    }
+    return record;
+  }
+  async open(owner, name) {
+    const record = await this.require(owner, name);
+    const value = record.isSealed ? await this.unseal(record.sealed, record.sealedKey) : record.plain ?? "";
+    this.record({ action: "open", owner, name });
+    return value;
+  }
+  async read(owner, name) {
+    const record = await this.require(owner, name);
+    if (record.isSealed) {
+      this.record({ action: "denied", owner, name, detail: "sealed" });
+      throw new VaultError(`"${name}" is sealed and cannot be read back.`, 403);
+    }
+    this.record({ action: "read", owner, name });
+    return record.plain ?? "";
   }
   async resolve(owner, values) {
     const references = Object.entries(values).filter(([, value]) => value.startsWith(this.prefix));
@@ -98,17 +320,83 @@ class Vault {
     }
     return resolved;
   }
-  checkName(name) {
-    const clean = String(name ?? "").trim();
-    if (!NAME_PATTERN.test(clean)) {
-      throw new VaultError("A name can be up to 64 characters: letters, numbers, dot, dash or underscore.");
+  async reseal(owner) {
+    const records = owner ? await this.store.list(owner) : await this.store.all();
+    let resealed = 0;
+    for (const record of records) {
+      if (!record.isSealed || !record.sealed)
+        continue;
+      const value = await this.unseal(record.sealed, record.sealedKey);
+      await this.store.put({ ...record, ...await this.enseal(value) });
+      resealed += 1;
     }
-    return clean;
+    return resealed;
+  }
+  async rekey(next) {
+    const nextKey = await toKey(next);
+    const report = { rekeyed: 0, failed: [] };
+    for (const record of await this.store.all()) {
+      if (!record.isSealed)
+        continue;
+      try {
+        const history = await this.rekeyHistory(record, nextKey);
+        if (record.sealedKey) {
+          const material = await this.unsealWithMaster(record.sealedKey);
+          await this.store.put({
+            ...record,
+            sealedKey: await seal(nextKey, material),
+            history
+          });
+        } else {
+          const value = await this.unsealWithMaster(record.sealed);
+          const material = generateKey();
+          const dataKey = await importKey(material);
+          await this.store.put({
+            ...record,
+            sealed: await seal(dataKey, value),
+            sealedKey: await seal(nextKey, material),
+            history
+          });
+        }
+        report.rekeyed += 1;
+      } catch {
+        report.failed.push(`${record.owner}/${record.name}`);
+      }
+    }
+    this.previousSources = [this.keySource, ...this.previousSources];
+    this.keySource = nextKey;
+    this.keyCache = Promise.resolve(nextKey);
+    this.previousCache = null;
+    this.record({
+      action: "rekey",
+      owner: "",
+      name: null,
+      detail: `${report.rekeyed} re-sealed, ${report.failed.length} failed`
+    });
+    return report;
+  }
+  async rekeyHistory(record, nextKey) {
+    return Promise.all(record.history.map(async (entry) => {
+      if (!entry.sealedKey)
+        return entry;
+      const material = await this.unsealWithMaster(entry.sealedKey);
+      return { ...entry, sealedKey: await seal(nextKey, material) };
+    }));
+  }
+  async purgeExpired(now = new Date) {
+    const expired = (await this.store.all()).filter((record) => isExpired(record, now));
+    for (const record of expired) {
+      await this.store.remove(record.owner, record.name);
+    }
+    return expired.length;
   }
 }
 // src/stores/memory.ts
 class MemoryStore {
-  records = new Map;
+  records;
+  constructor() {
+    this.records = new Map;
+  }
   static key(owner, name) {
     return `${owner} ${name}`;
   }
@@ -118,32 +406,158 @@ class MemoryStore {
   async list(owner) {
     return [...this.records.values()].filter((record) => record.owner === owner);
   }
+  async all() {
+    return [...this.records.values()];
+  }
   async put(record) {
-    const key = MemoryStore.key(record.owner, record.name);
-    const now = new Date;
-    const stored = {
-      ...record,
-      createdAt: this.records.get(key)?.createdAt ?? now,
-      updatedAt: now
-    };
-    this.records.set(key, stored);
-    return stored;
+    this.records.set(MemoryStore.key(record.owner, record.name), record);
+    return record;
   }
   async remove(owner, name) {
     return this.records.delete(MemoryStore.key(owner, name));
   }
 }
+// src/stores/file.ts
+import { open as openFile, readFile, rename, unlink } from "node:fs/promises";
+var MAGIC = "VAULT1";
+
+class FileStore {
+  path;
+  keySource;
+  keyCache = null;
+  records = null;
+  constructor(path, key) {
+    this.path = path;
+    this.keySource = key;
+  }
+  key() {
+    this.keyCache ??= (async () => {
+      const provider = isKeyProvider(this.keySource) ? this.keySource : staticKey(this.keySource);
+      const resolved = await provider.key();
+      return typeof resolved === "string" ? importKey(resolved) : resolved;
+    })();
+    return this.keyCache;
+  }
+  static id(owner, name) {
+    return `${owner} ${name}`;
+  }
+  async load() {
+    if (this.records)
+      return this.records;
+    let contents;
+    try {
+      contents = (await readFile(this.path, "utf8")).trim();
+    } catch (error) {
+      if (error.code !== "ENOENT")
+        throw error;
+      this.records = new Map;
+      return this.records;
+    }
+    const [magic, payload] = contents.split(`
+`);
+    if (magic !== MAGIC || !payload) {
+      throw new VaultKeyError(`${this.path} is not a vault file.`);
+    }
+    const opened = await open(await this.key(), payload);
+    const parsed = JSON.parse(opened);
+    this.records = new Map(parsed.map((record) => [
+      FileStore.id(record.owner, record.name),
+      {
+        ...record,
+        expiresAt: record.expiresAt === null ? null : new Date(record.expiresAt),
+        history: record.history.map((entry) => ({
+          ...entry,
+          createdAt: new Date(entry.createdAt)
+        })),
+        rotatedAt: record.rotatedAt === null ? null : new Date(record.rotatedAt),
+        createdAt: new Date(record.createdAt),
+        updatedAt: new Date(record.updatedAt)
+      }
+    ]));
+    return this.records;
+  }
+  async save() {
+    const records = await this.load();
+    const sealed = await seal(await this.key(), JSON.stringify([...records.values()]));
+    const temporary = `${this.path}.${process.pid}.${Date.now()}.writing`;
+    const handle = await openFile(temporary, "w");
+    try {
+      await handle.writeFile(`${MAGIC}
+${sealed}
+`);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, this.path);
+  }
+  async get(owner, name) {
+    return (await this.load()).get(FileStore.id(owner, name)) ?? null;
+  }
+  async list(owner) {
+    return [...(await this.load()).values()].filter((record) => record.owner === owner);
+  }
+  async all() {
+    return [...(await this.load()).values()];
+  }
+  async put(record) {
+    const records = await this.load();
+    const id = FileStore.id(record.owner, record.name);
+    const displaced = records.get(id);
+    records.set(id, record);
+    try {
+      await this.save();
+    } catch (error) {
+      if (displaced)
+        records.set(id, displaced);
+      else
+        records.delete(id);
+      throw error;
+    }
+    return record;
+  }
+  async remove(owner, name) {
+    const records = await this.load();
+    const id = FileStore.id(owner, name);
+    const removed = records.get(id);
+    if (!removed)
+      return false;
+    records.delete(id);
+    try {
+      await this.save();
+    } catch (error) {
+      records.set(id, removed);
+      throw error;
+    }
+    return true;
+  }
+  forget() {
+    this.records = null;
+  }
+  async destroy() {
+    this.records = new Map;
+    await unlink(this.path).catch(() => {});
+  }
+}
 export {
+  staticKey,
   seal,
+  randomValue,
   open,
+  isKeyProvider,
   importKey,
   generateKey,
+  fileKey,
+  envKey,
   VaultKeyError,
   VaultError,
   Vault,
   MemoryStore,
-  DEFAULT_PREFIX
+  FileStore,
+  DEFAULT_PREFIX,
+  DEFAULT_HISTORY_LIMIT,
+  DEFAULT_ALPHABET
 };
 
-//# debugId=75E38B9D900E6BB164756E2164756E21
+//# debugId=D639A370455C926764756E2164756E21
 //# sourceMappingURL=index.js.map