@mstone6969/vault 0.2.0 → 0.5.0

package/docs/index/classes/FileStore.md

@@ -0,0 +1,341 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / FileStore
+
+# Class: FileStore
+
+Defined in: cron/vault/src/stores/file.ts:58
+
+Keeps every record in one encrypted file.
+
+The other stores seal values and leave the rest in the open: SQLite has an
+`owner` column and a `name` column, and anyone who can read the file learns
+what you keep even if they cannot read it. Here the whole index — owners,
+names, metadata, timestamps, everything — is inside a single AES-256-GCM
+envelope. What leaks from the file at rest is its size.
+
+The trade is that it is loaded and written whole, so it suits hundreds of
+secrets rather than millions, and one writer rather than several. Writes go
+to a temporary file and are renamed into place, so a crash mid-write leaves
+the previous file rather than half of a new one.
+
+## Remarks
+
+The store is encrypted under its own key, separate from the master key the
+[Vault](Vault.md) seals values with, so the file is two layers deep: the index
+under the store's key, each value under its own data key under the vault's.
+Handing both layers the same key is allowed and sometimes what you want, but
+then one key opens both.
+
+The key is resolved on the first read or write, not at construction, so a
+provider that reaches for a file or a network service is asked once and only
+when a record is actually wanted. A bad key surfaces from that first
+operation as a [VaultKeyError](VaultKeyError.md), not from `new`.
+
+Nothing here locks the file. Two stores writing the same path — two
+processes, or two instances in one — each hold their own copy of the index
+and write it whole, so the last save wins and the other's writes are gone.
+Keep one writer per file.
+
+## Example
+
+A vault whose names are as hidden as its values. The store's key opens the
+file; the vault's key seals what is inside it.
+```ts
+import { Vault, fileKey } from "@mstone6969/vault"
+import { FileStore } from "@mstone6969/vault/stores/file"
+
+const store = new FileStore("./secrets.vault", fileKey("/etc/vault-file.key"))
+const vault = new Vault({ key: fileKey("/etc/vault-master.key"), store })
+
+await vault.put("alice", "db", "hunter2") // the file is written here
+await vault.open("alice", "db") // "hunter2"
+```
+
+## See
+
+[VaultStore](../type-aliases/VaultStore.md) for what a store owes the vault, and `MemoryStore`
+  and `SqliteStore` for the two that keep their index in the open.
+
+## Implements
+
+- [`VaultStore`](../type-aliases/VaultStore.md)
+
+## Constructors
+
+### Constructor
+
+> **new FileStore**(`path`, `key`): `FileStore`
+
+Defined in: cron/vault/src/stores/file.ts:81
+
+#### Parameters
+
+##### path
+
+`string`
+
+Where to keep the file. Created on first write, so a path
+  that does not exist yet is an empty store rather than an error.
+
+##### key
+
+`string` \| `CryptoKey` \| [`KeyProvider`](../type-aliases/KeyProvider.md)
+
+The key the *file* is encrypted with: base64, already
+  imported, or a [KeyProvider](../type-aliases/KeyProvider.md) that finds one. Give it one of its
+  own, or hand it the vault's — sharing means one key opens both layers.
+
+#### Returns
+
+`FileStore`
+
+#### Example
+
+```ts
+import { generateKey } from "@mstone6969/vault"
+import { FileStore } from "@mstone6969/vault/stores/file"
+
+// Nothing is read or written until the first call.
+const store = new FileStore("./secrets.vault", generateKey())
+```
+
+## Methods
+
+### get()
+
+> **get**(`owner`, `name`): `Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md) \| `null`\>
+
+Defined in: cron/vault/src/stores/file.ts:192
+
+One record, or null when there is none under that name.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose record to look for.
+
+##### name
+
+`string`
+
+What it is called.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md) \| `null`\>
+
+The record, or null.
+
+#### Throws
+
+[VaultKeyError](VaultKeyError.md) on the first call if the file is not a vault file,
+  or the key does not open it.
+
+#### Implementation of
+
+`VaultStore.get`
+
+***
+
+### list()
+
+> **list**(`owner`): `Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md)[]\>
+
+Defined in: cron/vault/src/stores/file.ts:206
+
+Every record one owner holds.
+
+The filtering happens in memory, over the whole index — there is no
+per-owner slice of the file to read on its own.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose records to return.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md)[]\>
+
+That owner's records, in whatever order they were written.
+
+#### Throws
+
+[VaultKeyError](VaultKeyError.md) on the first call if the file cannot be opened.
+
+#### Implementation of
+
+`VaultStore.list`
+
+***
+
+### all()
+
+> **all**(): `Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md)[]\>
+
+Defined in: cron/vault/src/stores/file.ts:229
+
+Every record, whoever owns it.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md)[]\>
+
+All of them. Only `rekey` and `purgeExpired` need this.
+
+#### Throws
+
+[VaultKeyError](VaultKeyError.md) on the first call if the file cannot be opened.
+
+#### Example
+
+Check a file opens under the key you think it does, before trusting it.
+```ts
+import { VaultKeyError } from "@mstone6969/vault"
+import { FileStore } from "@mstone6969/vault/stores/file"
+
+try {
+    await new FileStore("./secrets.vault", process.env.VAULT_FILE_KEY!).all()
+} catch (error) {
+    if (error instanceof VaultKeyError) console.error(error.message)
+}
+```
+
+#### Implementation of
+
+`VaultStore.all`
+
+***
+
+### put()
+
+> **put**(`record`): `Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md)\>
+
+Defined in: cron/vault/src/stores/file.ts:245
+
+Writes a record, replacing any under the same owner and name.
+
+The whole file is re-sealed and rewritten, so writes cost the size of the
+store rather than of the record.
+
+#### Parameters
+
+##### record
+
+[`SecretRecord`](../type-aliases/SecretRecord.md)
+
+The record to keep. Stored as given: finality, expiry and
+  history are the vault's rules, not the store's.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md)\>
+
+The same record, so callers can chain.
+
+#### Throws
+
+[VaultKeyError](VaultKeyError.md) if the file cannot be opened, or the key cannot be
+  resolved.
+
+#### Implementation of
+
+`VaultStore.put`
+
+***
+
+### remove()
+
+> **remove**(`owner`, `name`): `Promise`\<`boolean`\>
+
+Defined in: cron/vault/src/stores/file.ts:272
+
+Deletes a record, returning false when there was nothing to delete.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose record to delete.
+
+##### name
+
+`string`
+
+What it is called.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+Whether a record was there to delete. The file is only rewritten
+  when one was.
+
+#### Throws
+
+[VaultKeyError](VaultKeyError.md) if the file cannot be opened.
+
+#### Implementation of
+
+`VaultStore.remove`
+
+***
+
+### forget()
+
+> **forget**(): `void`
+
+Defined in: cron/vault/src/stores/file.ts:306
+
+Forgets what it read, so the next call goes back to the file.
+
+The point of a store that holds its whole index in memory is that reads
+are free; the cost is that a file another process rewrote is invisible
+until you say this. It also drops the decrypted index, which is the only
+place the names live in the clear.
+
+#### Returns
+
+`void`
+
+#### Example
+
+```ts
+import { FileStore } from "@mstone6969/vault/stores/file"
+
+const store = new FileStore("./secrets.vault", process.env.VAULT_FILE_KEY!)
+await store.all() // reads and decrypts the file
+store.forget()
+await store.all() // reads it again
+```
+
+***
+
+### destroy()
+
+> **destroy**(): `Promise`\<`void`\>
+
+Defined in: cron/vault/src/stores/file.ts:319
+
+Deletes the file and everything in it.
+
+The in-memory index is emptied first, so a store that is used again
+writes a fresh file rather than resurrecting what was there.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing. A file that is already gone is the outcome wanted, not
+  an error.

package/docs/index/classes/MemoryStore.md

@@ -0,0 +1,240 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / MemoryStore
+
+# Class: MemoryStore
+
+Defined in: cron/vault/src/stores/memory.ts:24
+
+Keeps sealed values in a Map. Handy for tests and short-lived processes.
+
+Nothing is written anywhere: when the process ends every record goes with it.
+That is the point — a test gets a clean vault per run without a file to
+create and delete, and a short-lived worker holding a few credentials in
+memory leaves nothing behind on disk.
+
+## Remarks
+
+Like every [VaultStore](../type-aliases/VaultStore.md), this persists records exactly as given and
+enforces nothing: finality, expiry and history are rules the [Vault](Vault.md)
+applies before it calls [MemoryStore.put](#put).
+
+## Example
+
+```ts
+import { generateKey, MemoryStore, Vault } from "@mstone6969/vault"
+
+const vault = new Vault({ key: generateKey(), store: new MemoryStore() })
+await vault.put("alice", "db-password", "hunter2")
+```
+
+## See
+
+[FileStore](FileStore.md) for a store that survives the process.
+
+## Implements
+
+- [`VaultStore`](../type-aliases/VaultStore.md)
+
+## Constructors
+
+### Constructor
+
+> **new MemoryStore**(): `MemoryStore`
+
+Defined in: cron/vault/src/stores/memory.ts:41
+
+Makes an empty store.
+
+#### Returns
+
+`MemoryStore`
+
+#### Remarks
+
+Takes nothing: there is no file to name and no key to hand it, since
+records never leave the process.
+
+#### Example
+
+```ts
+import { MemoryStore } from "@mstone6969/vault"
+
+const store = new MemoryStore()
+```
+
+## Methods
+
+### get()
+
+> **get**(`owner`, `name`): `Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md) \| `null`\>
+
+Defined in: cron/vault/src/stores/memory.ts:73
+
+One record, or null when there is none under that name.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry to look for.
+
+##### name
+
+`string`
+
+What the entry is called.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md) \| `null`\>
+
+The stored record, or null if this owner has nothing by that
+  name. The record itself is returned, not a copy, so callers must not
+  mutate it.
+
+#### Example
+
+```ts
+import { MemoryStore } from "@mstone6969/vault"
+
+const store = new MemoryStore()
+const record = await store.get("alice", "db-password") // null
+```
+
+#### Implementation of
+
+`VaultStore.get`
+
+***
+
+### list()
+
+> **list**(`owner`): `Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md)[]\>
+
+Defined in: cron/vault/src/stores/memory.ts:85
+
+Every record one owner holds.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entries to return.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md)[]\>
+
+That owner's records, in no particular order — the vault's
+  `list` sorts them. Empty for an owner the store has never heard of.
+
+#### See
+
+[MemoryStore.all](#all) when the caller needs every owner's records.
+
+#### Implementation of
+
+`VaultStore.list`
+
+***
+
+### all()
+
+> **all**(): `Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md)[]\>
+
+Defined in: cron/vault/src/stores/memory.ts:99
+
+Every record, whoever owns it.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md)[]\>
+
+All records the store holds, in no particular order.
+
+#### Remarks
+
+This is the only place anything reaches across owners, and it exists for
+the vault-wide operations — `rekey`, `reseal` and `purgeExpired` — which
+have to touch every entry. Ordinary reads go through
+[MemoryStore.list](#list).
+
+#### Implementation of
+
+`VaultStore.all`
+
+***
+
+### put()
+
+> **put**(`record`): `Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md)\>
+
+Defined in: cron/vault/src/stores/memory.ts:113
+
+Writes a record, replacing any under the same owner and name.
+
+#### Parameters
+
+##### record
+
+[`SecretRecord`](../type-aliases/SecretRecord.md)
+
+The record to keep, stored as given.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](../type-aliases/SecretRecord.md)\>
+
+The same record, so a caller can write and use the result in one
+  step.
+
+#### Remarks
+
+An `isFinal` record is replaced here without complaint: refusing that is
+the vault's job, and it checks before it calls this.
+
+#### Implementation of
+
+`VaultStore.put`
+
+***
+
+### remove()
+
+> **remove**(`owner`, `name`): `Promise`\<`boolean`\>
+
+Defined in: cron/vault/src/stores/memory.ts:126
+
+Deletes a record, returning false when there was nothing to delete.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry to delete.
+
+##### name
+
+`string`
+
+What the entry is called.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True if a record was removed, false if there was none — so a
+  caller can tell a delete from a no-op.
+
+#### Implementation of
+
+`VaultStore.remove`