@mstone6969/vault 0.2.0 → 0.5.0

package/docs/index/functions/envKey.md

@@ -0,0 +1,43 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / envKey
+
+# Function: envKey()
+
+> **envKey**(`name`): [`KeyProvider`](../type-aliases/KeyProvider.md)
+
+Defined in: cron/vault/src/providers.ts:92
+
+A key from an environment variable.
+
+## Parameters
+
+### name
+
+`string`
+
+The variable to read, at the moment the key is first needed —
+  so a process that loads its environment after building the vault still
+  works.
+
+## Returns
+
+[`KeyProvider`](../type-aliases/KeyProvider.md)
+
+A provider that reads `process.env[name]`.
+
+## Throws
+
+[VaultKeyError](../classes/VaultKeyError.md) when the variable is unset or empty, at the first
+  operation that needs a key rather than at construction.
+
+## Example
+
+```ts
+import { Vault, MemoryStore, envKey } from "@mstone6969/vault"
+
+const vault = new Vault({ key: envKey("VAULT_KEY"), store: new MemoryStore() })
+await vault.put("alice", "db", "hunter2") // throws here if VAULT_KEY is unset
+```

package/docs/index/functions/fileKey.md

@@ -0,0 +1,46 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / fileKey
+
+# Function: fileKey()
+
+> **fileKey**(`path`): [`KeyProvider`](../type-aliases/KeyProvider.md)
+
+Defined in: cron/vault/src/providers.ts:125
+
+A key from a file — the usual way to keep one off the process list and out
+of shell history. Whitespace around it is ignored, so a trailing newline
+from `openssl rand -base64 32 > key` does no harm.
+
+## Parameters
+
+### path
+
+`string`
+
+The key file, read at the moment the key is first needed. It is
+  read once and kept, so replacing the file later does not change the key a
+  running vault uses.
+
+## Returns
+
+[`KeyProvider`](../type-aliases/KeyProvider.md)
+
+A provider that reads and trims the file.
+
+## Throws
+
+[VaultKeyError](../classes/VaultKeyError.md) when the file is missing, or holds nothing but
+  whitespace.
+
+## Example
+
+```ts
+import { Vault, FileStore, fileKey } from "@mstone6969/vault"
+
+// The store's own key opens the file; the vault's key seals the values.
+const store = new FileStore("./secrets.vault", fileKey("/etc/vault.key"))
+const vault = new Vault({ key: fileKey("/etc/vault.key"), store })
+```

package/docs/index/functions/generateKey.md

@@ -0,0 +1,39 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / generateKey
+
+# Function: generateKey()
+
+> **generateKey**(): `string`
+
+Defined in: cron/vault/src/crypto.ts:47
+
+A new random key, base64 encoded — store it somewhere safe.
+
+## Returns
+
+`string`
+
+32 random bytes, base64. Nothing keeps a copy, so a key that is lost
+  takes every value sealed under it with it.
+
+## Remarks
+
+Used for master keys you generate once and keep, and — inside the vault — for
+the throwaway data key minted per written value.
+
+## Example
+
+```ts
+import { generateKey, importKey, seal } from "@mstone6969/vault"
+
+const material = generateKey()
+const key = await importKey(material)
+const sealed = await seal(key, "hunter2")
+```
+
+## See
+
+[importKey](importKey.md) to turn the string back into a usable key.

package/docs/index/functions/importKey.md

@@ -0,0 +1,49 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / importKey
+
+# Function: importKey()
+
+> **importKey**(`base64Key`): `Promise`\<`CryptoKey`\>
+
+Defined in: cron/vault/src/crypto.ts:72
+
+Imports a base64 key produced by [generateKey](generateKey.md).
+
+## Parameters
+
+### base64Key
+
+`string`
+
+The key material, base64 encoded, decoding to exactly 32
+  bytes.
+
+## Returns
+
+`Promise`\<`CryptoKey`\>
+
+A key usable with [seal](seal.md) and [open](open.md).
+
+## Throws
+
+[VaultKeyError](../classes/VaultKeyError.md) When the decoded material is not 32 bytes. Note
+  that base64 decoding is lenient: rubbish that is not base64 at all decodes
+  to too few bytes and surfaces here as a length complaint rather than a
+  parse error.
+
+## Remarks
+
+The imported key is not extractable, so the raw bytes cannot be read back out
+of it — a value only ever leaves via [open](open.md).
+
+## Example
+
+```ts
+import { importKey, MemoryStore, Vault } from "@mstone6969/vault"
+
+const key = await importKey(process.env.VAULT_KEY!)
+const vault = new Vault({ key, store: new MemoryStore() })
+```

package/docs/index/functions/isKeyProvider.md

@@ -0,0 +1,43 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / isKeyProvider
+
+# Function: isKeyProvider()
+
+> **isKeyProvider**(`value`): `value is KeyProvider`
+
+Defined in: cron/vault/src/providers.ts:160
+
+True when something is a provider rather than a key.
+
+[Vault](../classes/Vault.md) and [FileStore](../classes/FileStore.md) accept either, and use this to tell them
+apart: anything with a callable `key` is a provider, everything else is key
+material to be wrapped in [staticKey](staticKey.md). A `CryptoKey` has no `key`
+method, so it never matches.
+
+## Parameters
+
+### value
+
+`unknown`
+
+Anything — key material, a provider, or neither.
+
+## Returns
+
+`value is KeyProvider`
+
+Whether `value` has a callable `key`, narrowing it to
+  [KeyProvider](../type-aliases/KeyProvider.md).
+
+## Example
+
+```ts
+import { envKey, isKeyProvider, staticKey } from "@mstone6969/vault"
+
+isKeyProvider(envKey("VAULT_KEY")) // true
+isKeyProvider(staticKey("...")) // true
+isKeyProvider("base64-key-material") // false
+```

package/docs/index/functions/open.md

@@ -0,0 +1,67 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / open
+
+# Function: open()
+
+> **open**(`key`, `sealed`): `Promise`\<`string`\>
+
+Defined in: cron/vault/src/crypto.ts:152
+
+Opens a value sealed by [seal](seal.md).
+
+## Parameters
+
+### key
+
+`CryptoKey`
+
+The key it was sealed under.
+
+### sealed
+
+`string`
+
+The `iv:payload` string to open.
+
+## Returns
+
+`Promise`\<`string`\>
+
+The plaintext.
+
+## Throws
+
+[VaultKeyError](../classes/VaultKeyError.md) When the key is wrong, the value has been
+  altered, or it is not in `iv:payload` form. A wrong key fails rather than
+  returning nonsense, because GCM authenticates what it decrypts.
+
+## Remarks
+
+That failure mode is worth relying on. A caller does not need to check
+whether what came back looks plausible: if this returns at all, the value is
+byte for byte what was sealed, under the key that sealed it. It is also why
+[Vault.rekey](../classes/Vault.md#rekey) can try each key in turn and know which one was right,
+and why a store that silently corrupts a record produces an error rather
+than a credential that fails somewhere far away.
+
+The error deliberately does not say which of the three went wrong: telling
+an attacker apart from a typo is not worth telling an attacker anything.
+
+## Example
+
+```ts
+import { generateKey, importKey, open, seal, VaultKeyError } from "@mstone6969/vault"
+
+const key = await importKey(generateKey())
+const other = await importKey(generateKey())
+const sealed = await seal(key, "s3cret")
+
+try {
+    await open(other, sealed)
+} catch (error) {
+    error instanceof VaultKeyError // true — never a wrong plaintext
+}
+```

package/docs/index/functions/randomValue.md

@@ -0,0 +1,53 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / randomValue
+
+# Function: randomValue()
+
+> **randomValue**(`length?`, `alphabet?`): `string`
+
+Defined in: cron/vault/src/vault.ts:125
+
+A random string of `length` characters drawn from `alphabet`.
+
+Sampling is rejected rather than folded with `%`, so every character is
+equally likely however odd the alphabet's length.
+
+## Parameters
+
+### length?
+
+`number` = `32`
+
+How many characters to produce. Defaults to 32.
+
+### alphabet?
+
+`string` = `DEFAULT_ALPHABET`
+
+The characters to draw from. Defaults to
+  [DEFAULT\_ALPHABET](../variables/DEFAULT_ALPHABET.md).
+
+## Returns
+
+`string`
+
+A fresh string of exactly `length` characters.
+
+## Throws
+
+[VaultError](../classes/VaultError.md) 422 when `length` is below one, or `alphabet` has
+  fewer than two characters — neither can produce anything unguessable.
+
+## Example
+
+```ts
+randomValue()                        // 32 characters of A-Z, a-z, 0-9
+randomValue(16, "0123456789abcdef")  // 16 hex characters
+```
+
+## See
+
+[RotationPolicy](../type-aliases/RotationPolicy.md) to have the vault call this during a rotation.

package/docs/index/functions/seal.md

@@ -0,0 +1,56 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / seal
+
+# Function: seal()
+
+> **seal**(`key`, `plaintext`): `Promise`\<`string`\>
+
+Defined in: cron/vault/src/crypto.ts:108
+
+Seals a value under a key.
+
+## Parameters
+
+### key
+
+`CryptoKey`
+
+The key to seal under.
+
+### plaintext
+
+`string`
+
+What to seal.
+
+## Returns
+
+`Promise`\<`string`\>
+
+`iv:payload`, both base64. A fresh IV every time, so the same value
+  sealed twice gives two different results.
+
+## Remarks
+
+That the output differs every time is the point: an observer with the store
+in front of them cannot tell that two entries hold the same password, nor
+that a value was replaced with itself. It also means a sealed string is no
+good as a cache key or an equality check.
+
+Nothing about the key is written into the output, so the caller must
+remember which key sealed what — the vault does that by keeping each value's
+data key beside it in [SecretRecord.sealedKey](../type-aliases/SecretRecord.md#sealedkey).
+
+## Example
+
+```ts
+import { generateKey, importKey, open, seal } from "@mstone6969/vault"
+
+const key = await importKey(generateKey())
+const sealed = await seal(key, "s3cret")
+sealed.split(":").length // 2
+await open(key, sealed) // "s3cret"
+```

package/docs/index/functions/staticKey.md

@@ -0,0 +1,39 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / staticKey
+
+# Function: staticKey()
+
+> **staticKey**(`key`): [`KeyProvider`](../type-aliases/KeyProvider.md)
+
+Defined in: cron/vault/src/providers.ts:70
+
+A key you already have.
+
+Mostly for handing a key to something that wants a provider —
+[Vault.rekey](../classes/Vault.md#rekey), or a `previousKeys` entry — without wrapping it
+yourself. Passing raw key material as `key` does this for you.
+
+## Parameters
+
+### key
+
+`string` \| `CryptoKey`
+
+The master key: base64, or already imported.
+
+## Returns
+
+[`KeyProvider`](../type-aliases/KeyProvider.md)
+
+A provider that hands back `key` every time.
+
+## Example
+
+```ts
+import { Vault, MemoryStore, generateKey, staticKey } from "@mstone6969/vault"
+
+const vault = new Vault({ key: staticKey(generateKey()), store: new MemoryStore() })
+```

package/docs/index/type-aliases/Generator.md

@@ -0,0 +1,58 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / Generator
+
+# Type Alias: Generator
+
+> **Generator** = (`context`) => `Promise`\<`string`\> \| `string`
+
+Defined in: cron/vault/src/vault.ts:102
+
+Produces the next value for an entry whose policy names it.
+
+## Parameters
+
+### context
+
+[`RotationContext`](RotationContext.md)
+
+Which entry is being rotated and its policy's arguments. Not
+  the value being replaced.
+
+## Returns
+
+`Promise`\<`string`\> \| `string`
+
+The next value, or a promise of it.
+
+## Remarks
+
+Registered under a name in [VaultOptions.generators](VaultOptions.md#generators) and asked for by
+[RotationPolicy.generator](RotationPolicy.md#generator). Use one where the vault cannot invent the
+value itself — a key only the far end can mint, or a password that has to be
+set on a database before it means anything.
+
+## Example
+
+**Minting a key at the provider that issues it**
+
+```ts
+const vault = new Vault({
+    key: generateKey(),
+    store: new MemoryStore(),
+    generators: {
+        provider: async ({ arguments: args }) => mintKeyFor(args.account),
+    },
+})
+
+await vault.put("alice", "api", "old-key", {
+    rotation: {
+        kind: "generator",
+        generator: "provider",
+        arguments: { account: "acct_123" },
+    },
+})
+await vault.rotate("alice", "api")
+```

package/docs/index/type-aliases/HistoryEntry.md

@@ -0,0 +1,65 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / HistoryEntry
+
+# Type Alias: HistoryEntry
+
+> **HistoryEntry** = `object`
+
+Defined in: cron/vault/src/types.ts:18
+
+A value a rotatable entry used to hold.
+
+## Remarks
+
+Kept sealed, exactly as the live value is, so history costs no more trust
+than the entry itself. A job that read the credential moments before a
+rotation can still finish on what it was given.
+
+## Example
+
+```ts
+await vault.rotate("alice", "db")
+// The value that was live until the rotation, opened:
+const [previous] = await vault.versions("alice", "db")
+```
+
+## See
+
+[SecretRecord.history](SecretRecord.md#history)
+
+## Properties
+
+### sealed
+
+> **sealed**: `string`
+
+Defined in: cron/vault/src/types.ts:20
+
+The value, sealed exactly as the live one is.
+
+***
+
+### sealedKey
+
+> **sealedKey**: `string` \| `null`
+
+Defined in: cron/vault/src/types.ts:28
+
+The data key that opens it, itself sealed under the master key.
+
+Null on values kept before envelope encryption, which are sealed under
+the master key directly. A `rekey` moves the non-null ones onto the new
+master key and leaves the rest alone.
+
+***
+
+### createdAt
+
+> **createdAt**: `Date`
+
+Defined in: cron/vault/src/types.ts:30
+
+When this value was replaced.

package/docs/index/type-aliases/KeyProvider.md

@@ -0,0 +1,74 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / KeyProvider
+
+# Type Alias: KeyProvider
+
+> **KeyProvider** = `object`
+
+Defined in: cron/vault/src/providers.ts:41
+
+Where the master key comes from.
+
+A vault takes a provider rather than a string so the key can live wherever
+you keep such things — the environment, a file with tight permissions, or a
+service that hands one over. Write your own for anything else; it is one
+method.
+
+## Remarks
+
+Whoever holds the provider — [Vault](../classes/Vault.md) or [FileStore](../classes/FileStore.md) — calls
+`key` the first time a key is actually needed and keeps the promise, so a
+provider that reaches over the network is asked once and a vault nobody uses
+never asks at all. Anything thrown surfaces from that first operation, not
+from the constructor.
+
+## Example
+
+A provider for something this package does not ship — here a KMS, but the
+shape is the same for 1Password, age, or a file on a smartcard.
+```ts
+import { Vault, MemoryStore, type KeyProvider } from "@mstone6969/vault"
+
+function kmsKey(id: string): KeyProvider {
+    return {
+        async key() {
+            const response = await fetch(`https://kms.internal/keys/${id}`)
+            if (!response.ok) throw new Error(`KMS refused key ${id}.`)
+            return (await response.text()).trim() // base64
+        },
+    }
+}
+
+const vault = new Vault({ key: kmsKey("vault-master"), store: new MemoryStore() })
+await vault.put("alice", "db", "hunter2") // the KMS is called here, once
+```
+
+## See
+
+[staticKey](../functions/staticKey.md), [envKey](../functions/envKey.md) and [fileKey](../functions/fileKey.md) for the ones that
+  ship.
+
+## Methods
+
+### key()
+
+> **key**(): `string` \| `CryptoKey` \| `Promise`\<`string` \| `CryptoKey`\>
+
+Defined in: cron/vault/src/providers.ts:50
+
+The key, base64 or already imported. Called once, when first needed.
+
+#### Returns
+
+`string` \| `CryptoKey` \| `Promise`\<`string` \| `CryptoKey`\>
+
+The master key: a base64 string of 32 bytes, or a `CryptoKey`
+  already imported for AES-GCM. May be a promise.
+
+#### Throws
+
+Whatever the source of the key throws when it cannot produce
+  one. The ones here throw [VaultKeyError](../classes/VaultKeyError.md).