@mstone6969/vault 0.2.0 → 0.5.0

package/docs/index/classes/Vault.md

@@ -0,0 +1,805 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / Vault
+
+# Class: Vault
+
+Defined in: cron/vault/src/vault.ts:265
+
+A write-only credential store: values go in, and only `open`, `read` and
+`resolve` take them out again.
+
+Every value is sealed under its own data key, and only that key is sealed
+under the master key. Changing the master key therefore re-seals a handful of
+bytes per entry rather than every value, and one exposed data key exposes one
+value rather than all of them.
+
+## Example
+
+**Storing a credential and handing it to the thing that needs it**
+
+```ts
+import { Vault, MemoryStore, generateKey } from "@mstone6969/vault"
+
+const vault = new Vault({ key: generateKey(), store: new MemoryStore() })
+
+await vault.put("alice", "stripe_key", "sk_live_x", {
+    metadata: { kind: "api" },
+})
+
+// Nothing but open, read and resolve gets the value back out.
+await vault.list("alice")   // name, metadata, dates — no value
+await vault.open("alice", "stripe_key")
+await vault.resolve("alice", { STRIPE_KEY: "@vault:stripe_key" })
+```
+
+## See
+
+[VaultOptions](../type-aliases/VaultOptions.md) for what it is built from, [VaultStore](../type-aliases/VaultStore.md) for
+  where the records go, and [VaultError](VaultError.md) for what it throws.
+
+## Constructors
+
+### Constructor
+
+> **new Vault**(`options`): `Vault`
+
+Defined in: cron/vault/src/vault.ts:285
+
+#### Parameters
+
+##### options
+
+[`VaultOptions`](../type-aliases/VaultOptions.md)
+
+The key, the store and the policies this vault applies.
+  Nothing is contacted here: the key is resolved on first use, so a vault
+  built from a provider that is slow or unreachable costs nothing until
+  something asks it for a value.
+
+#### Returns
+
+`Vault`
+
+## Properties
+
+### prefix
+
+> `readonly` **prefix**: `string`
+
+Defined in: cron/vault/src/vault.ts:277
+
+The prefix [Vault.resolve](#resolve) treats as a reference.
+
+## Methods
+
+### list()
+
+> **list**(`owner`): `Promise`\<[`SecretSummary`](../type-aliases/SecretSummary.md)[]\>
+
+Defined in: cron/vault/src/vault.ts:393
+
+Everything an owner holds, sorted by name. Never a sealed value.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entries to list.
+
+#### Returns
+
+`Promise`\<[`SecretSummary`](../type-aliases/SecretSummary.md)[]\>
+
+One summary per entry, in name order. A sealed value is absent
+  entirely; an entry stored in the open carries its value in `value`.
+
+#### Remarks
+
+Expiry hides nothing here: an entry past its `expiresAt` is still listed,
+and still refuses to open, until [Vault.purgeExpired](#purgeexpired) clears it.
+
+#### Example
+
+```ts
+await vault.put("alice", "stripe_key", "sk_live_x", {
+    metadata: { kind: "api" },
+})
+
+const [entry] = await vault.list("alice")
+entry.name      // "stripe_key"
+entry.metadata  // { kind: "api" }
+entry.versions  // 0
+```
+
+#### See
+
+[SecretSummary](../type-aliases/SecretSummary.md)
+
+***
+
+### put()
+
+> **put**(`owner`, `name`, `value`, `options?`): `Promise`\<[`SecretSummary`](../type-aliases/SecretSummary.md)\>
+
+Defined in: cron/vault/src/vault.ts:432
+
+Stores a value, replacing whatever was under that name.
+
+`metadata` is kept in the clear and comes back from `list`, so it must
+hold nothing secret — a credential's kind, or the username it belongs to,
+not the password.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry it is. Owners never see each other's entries.
+
+##### name
+
+`string`
+
+What to call it: 1-64 characters of letters, numbers, dot,
+  dash or underscore. Surrounding whitespace is trimmed.
+
+##### value
+
+`string`
+
+The value to store.
+
+##### options?
+
+[`PutOptions`](../type-aliases/PutOptions.md) = `{}`
+
+Metadata, expiry, rotation policy, and whether the entry
+  is sealed, final, or keeps what it replaces. An option left out is
+  inherited from the existing entry.
+
+#### Returns
+
+`Promise`\<[`SecretSummary`](../type-aliases/SecretSummary.md)\>
+
+The stored entry, summarised — never its sealed value.
+
+#### Throws
+
+[VaultError](VaultError.md) 422 when the name is not 1-64 characters of
+  letters, numbers, dot, dash or underscore, or the value is empty.
+
+#### Throws
+
+[VaultError](VaultError.md) 409 when the entry is already there and
+  `final`: it can be deleted, never replaced.
+
+#### Example
+
+**Replacing a value without restating what the entry is**
+
+```ts
+await vault.put("alice", "db", "first-password", {
+    metadata: { kind: "login", username: "ada" },
+    rotation: { kind: "random", length: 24 },
+})
+
+// Still a login, still rotatable at 24 characters, still sealed.
+await vault.put("alice", "db", "second-password")
+```
+
+#### See
+
+[Vault.rotate](#rotate) to replace a value and keep the old one,
+  [PutOptions](../type-aliases/PutOptions.md) for the rest of the options.
+
+***
+
+### rotate()
+
+> **rotate**(`owner`, `name`, `value?`, `options?`): `Promise`\<[`SecretSummary`](../type-aliases/SecretSummary.md)\>
+
+Defined in: cron/vault/src/vault.ts:535
+
+Replaces a value, keeping the one it replaces.
+
+Called without a value, the entry's rotation policy produces one — which
+is the point of storing a policy: whatever runs the rotation is told how
+to make the next password, never what the current one is.
+
+Previous values stay openable, so a job that read the credential moments
+before a rotation can still finish on what it was given.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry to rotate.
+
+##### name
+
+`string`
+
+The entry to rotate.
+
+##### value?
+
+`string`
+
+The new value. Left out, the entry's rotation policy makes
+  one.
+
+##### options?
+
+`Omit`\<[`PutOptions`](../type-aliases/PutOptions.md), `"keepHistory"`\> = `{}`
+
+As [Vault.put](#put), minus `keepHistory`: a rotation
+  always keeps what it replaced, up to [VaultOptions.historyLimit](../type-aliases/VaultOptions.md#historylimit).
+
+#### Returns
+
+`Promise`\<[`SecretSummary`](../type-aliases/SecretSummary.md)\>
+
+The rotated entry, summarised, with `rotatedAt` stamped.
+
+#### Throws
+
+[VaultError](VaultError.md) 404 when no value is given and there is no
+  such entry to take a policy from.
+
+#### Throws
+
+[VaultError](VaultError.md) 410 when no value is given and the entry has
+  expired.
+
+#### Throws
+
+[VaultError](VaultError.md) 422 when no value is given and the entry has
+  no rotation policy to make one with.
+
+#### Throws
+
+[VaultError](VaultError.md) 501 when the policy names a generator this
+  vault was not constructed with.
+
+#### Throws
+
+[VaultError](VaultError.md) 409 when the entry is final.
+
+#### Example
+
+```ts
+await vault.put("alice", "db", "first-password", {
+    rotation: { kind: "random", length: 24 },
+})
+
+const rotated = await vault.rotate("alice", "db")
+rotated.rotatedAt                    // stamped just now
+await vault.versions("alice", "db")  // ["first-password"]
+```
+
+#### See
+
+[Vault.rotationDue](#rotationdue) for which entries are asking for this.
+
+***
+
+### rotationDue()
+
+> **rotationDue**(`now?`): `Promise`\<[`SecretSummary`](../type-aliases/SecretSummary.md)[]\>
+
+Defined in: cron/vault/src/vault.ts:603
+
+Entries whose policy says how often they want rotating, and whose time
+has come. Nothing rotates them for you — schedule this and act on it.
+
+#### Parameters
+
+##### now?
+
+`Date` = `...`
+
+The moment to judge against. Pass a later one to ask what will
+  be due by then.
+
+#### Returns
+
+`Promise`\<[`SecretSummary`](../type-aliases/SecretSummary.md)[]\>
+
+Summaries of every entry, whoever owns it, whose
+  [RotationPolicy.every](../type-aliases/RotationPolicy.md#every) seconds have passed since it was last
+  rotated — or since it was stored, if it never has been.
+
+#### Remarks
+
+One of the three calls that reach across owners, so it belongs to
+whatever runs the schedule rather than to a request.
+
+#### Example
+
+```ts
+await vault.put("alice", "db", "x", {
+    rotation: { kind: "random", every: 86_400 },
+})
+
+for (const entry of await vault.rotationDue()) {
+    await vault.rotate(entry.owner, entry.name)
+}
+```
+
+***
+
+### versions()
+
+> **versions**(`owner`, `name`): `Promise`\<`string`[]\>
+
+Defined in: cron/vault/src/vault.ts:637
+
+Previous values of an entry, newest first, opened.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry it is.
+
+##### name
+
+`string`
+
+The entry to look back through.
+
+#### Returns
+
+`Promise`\<`string`[]\>
+
+The values it used to hold, newest first, in the clear. Empty
+  for an entry that has never been rotated.
+
+#### Throws
+
+[VaultError](VaultError.md) 404 when there is no such entry.
+
+#### Throws
+
+[VaultError](VaultError.md) 410 when the entry has expired.
+
+#### Throws
+
+[VaultError](VaultError.md) 422 when the name is not a legal one.
+
+#### Throws
+
+[VaultKeyError](VaultKeyError.md) 500 when a kept value will not open under
+  the master key or any of [VaultOptions.previousKeys](../type-aliases/VaultOptions.md#previouskeys).
+
+#### Example
+
+```ts
+await vault.put("alice", "deploy", "v1")
+await vault.rotate("alice", "deploy", "v2")
+await vault.rotate("alice", "deploy", "v3")
+
+await vault.versions("alice", "deploy")  // ["v2", "v1"]
+```
+
+***
+
+### has()
+
+> **has**(`owner`, `name`): `Promise`\<`boolean`\>
+
+Defined in: cron/vault/src/vault.ts:656
+
+True when the owner has a secret under that name, expired or not.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry to look for.
+
+##### name
+
+`string`
+
+The name to look for.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+Whether a record exists under it.
+
+#### Throws
+
+[VaultError](VaultError.md) 422 when the name is not a legal one.
+
+#### Remarks
+
+Opens nothing and is not stopped by expiry, so it answers "is this name
+taken" rather than "can this value still be used".
+
+***
+
+### remove()
+
+> **remove**(`owner`, `name`): `Promise`\<`boolean`\>
+
+Defined in: cron/vault/src/vault.ts:673
+
+Removes a secret, returning false if it wasn't there.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry to delete.
+
+##### name
+
+`string`
+
+The entry to delete.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True when something was deleted, false when there was nothing
+  under that name.
+
+#### Throws
+
+[VaultError](VaultError.md) 422 when the name is not a legal one.
+
+#### Remarks
+
+Deleting takes the kept previous values with it, and it is the one thing
+a `final` entry allows.
+
+***
+
+### open()
+
+> **open**(`owner`, `name`): `Promise`\<`string`\>
+
+Defined in: cron/vault/src/vault.ts:719
+
+Reads one value back. The only way plaintext leaves a sealed entry — keep
+it in memory and out of logs and responses.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry to open.
+
+##### name
+
+`string`
+
+The entry to open.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The value, sealed or not.
+
+#### Throws
+
+[VaultError](VaultError.md) 404 when there is no such entry.
+
+#### Throws
+
+[VaultError](VaultError.md) 410 when the entry has expired. The record is
+  still there; it just cannot be used.
+
+#### Throws
+
+[VaultError](VaultError.md) 422 when the name is not a legal one.
+
+#### Throws
+
+[VaultKeyError](VaultKeyError.md) 500 when the value will not open under the
+  master key or any of [VaultOptions.previousKeys](../type-aliases/VaultOptions.md#previouskeys) — a wrong key or
+  an altered value, which GCM cannot tell apart.
+
+#### Example
+
+```ts
+await vault.put("alice", "token", "shhh")
+await vault.open("alice", "token")  // "shhh"
+```
+
+#### See
+
+[Vault.read](#read) for entries stored in the open,
+  [Vault.resolve](#resolve) for substituting several at once.
+
+***
+
+### read()
+
+> **read**(`owner`, `name`): `Promise`\<`string`\>
+
+Defined in: cron/vault/src/vault.ts:751
+
+Reads an entry stored in the open. A sealed one refuses.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry to read.
+
+##### name
+
+`string`
+
+The entry to read.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The value, which was stored with `open: true` and was therefore
+  never secret.
+
+#### Throws
+
+[VaultError](VaultError.md) 403 when the entry is sealed.
+  [Vault.open](#open) is the only way a sealed value comes out.
+
+#### Throws
+
+[VaultError](VaultError.md) 404 when there is no such entry.
+
+#### Throws
+
+[VaultError](VaultError.md) 410 when the entry has expired.
+
+#### Throws
+
+[VaultError](VaultError.md) 422 when the name is not a legal one.
+
+#### Example
+
+```ts
+await vault.put("alice", "region", "eu-west-1", { open: true })
+await vault.read("alice", "region")  // "eu-west-1"
+
+await vault.put("alice", "token", "shhh")
+await vault.read("alice", "token")   // throws: 403, sealed
+```
+
+***
+
+### resolve()
+
+> **resolve**(`owner`, `values`): `Promise`\<`Record`\<`string`, `string`\>\>
+
+Defined in: cron/vault/src/vault.ts:794
+
+Substitutes `@vault:<name>` references in a set of values — an
+environment, a config object — leaving everything else alone.
+
+A reference to a secret that isn't there, or that has expired, throws:
+running with a blank credential is worse than not running.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entries the references name.
+
+##### values
+
+`Record`\<`string`, `string`\>
+
+The set to substitute into. Not modified.
+
+#### Returns
+
+`Promise`\<`Record`\<`string`, `string`\>\>
+
+A copy with every reference replaced by its value, or the same
+  object back when nothing in it is a reference.
+
+#### Throws
+
+[VaultError](VaultError.md) 404 when a reference names no entry.
+
+#### Throws
+
+[VaultError](VaultError.md) 410 when a referenced entry has expired.
+
+#### Throws
+
+[VaultError](VaultError.md) 422 when what follows the prefix is not a
+  legal name.
+
+#### Remarks
+
+Whitespace around the name is ignored, so `"@vault: token "` finds
+`token`. Sealed and open entries both resolve; the prefix comes from
+[Vault.prefix](#prefix).
+
+#### Example
+
+**Filling in an environment before spawning something**
+
+```ts
+await vault.put("alice", "token", "secret")
+
+await vault.resolve("alice", {
+    PLAIN: "kept",
+    API_TOKEN: "@vault:token",
+})
+// { PLAIN: "kept", API_TOKEN: "secret" }
+```
+
+***
+
+### reseal()
+
+> **reseal**(`owner?`): `Promise`\<`number`\>
+
+Defined in: cron/vault/src/vault.ts:830
+
+Re-seals values under fresh data keys, without changing the master key.
+
+Cheap hygiene: the ciphertext of an unchanged secret stops being
+comparable between two copies of the database taken at different times.
+
+#### Parameters
+
+##### owner?
+
+`string`
+
+Limit it to one owner's entries. Left out, it walks the
+  whole store, whoever owns it.
+
+#### Returns
+
+`Promise`\<`number`\>
+
+How many entries were re-sealed. Entries stored in the open hold
+  nothing to re-seal and are skipped.
+
+#### Throws
+
+[VaultKeyError](VaultKeyError.md) 500 when a value will not open. Unlike
+  [Vault.rekey](#rekey) this stops there, having already re-sealed the
+  entries it got to — those are unharmed, since the key did not change.
+
+#### Example
+
+```ts
+await vault.reseal("alice")  // just this owner
+await vault.reseal()         // the whole store
+```
+
+***
+
+### rekey()
+
+> **rekey**(`next`): `Promise`\<[`RekeyReport`](../type-aliases/RekeyReport.md)\>
+
+Defined in: cron/vault/src/vault.ts:879
+
+Re-seals every data key under a new master key.
+
+The old key is kept as a fallback for the rest of this vault's life, so a
+run that stops halfway leaves a mix that still opens. Construct the next
+vault with `key: next, previousKeys: [old]` until you are confident, then
+drop the old one.
+
+An entry that will not open is left untouched and named in the report,
+because re-sealing what you cannot read would only destroy it.
+
+#### Parameters
+
+##### next
+
+`string` \| `CryptoKey` \| [`KeyProvider`](../type-aliases/KeyProvider.md)
+
+The new master key: base64, already imported, or a provider
+  that finds one.
+
+#### Returns
+
+`Promise`\<[`RekeyReport`](../type-aliases/RekeyReport.md)\>
+
+How many entries moved, and which would not, by `owner/name`.
+
+#### Throws
+
+[VaultKeyError](VaultKeyError.md) 500 when `next` is not a usable key. It is
+  resolved before anything is written, so nothing has changed.
+
+#### Remarks
+
+Walks every owner, and changes this vault as it goes: from here on it
+seals under `next` and keeps the key it had as a fallback. An entry
+stored in the open holds no key and is skipped, and one written before
+envelope encryption is given a data key on the way past.
+
+#### Example
+
+```ts
+const next = generateKey()
+const report = await vault.rekey(next)
+report.rekeyed  // 2
+report.failed   // ["alice/stranger"] — left exactly as they were
+
+// Until the failures are dealt with, keep the old key readable.
+const moved = new Vault({ key: next, store, previousKeys: [old] })
+```
+
+#### See
+
+[RekeyReport](../type-aliases/RekeyReport.md), [VaultOptions.previousKeys](../type-aliases/VaultOptions.md#previouskeys)
+
+***
+
+### purgeExpired()
+
+> **purgeExpired**(`now?`): `Promise`\<`number`\>
+
+Defined in: cron/vault/src/vault.ts:968
+
+Deletes entries whose time is up. Returns how many went.
+
+#### Parameters
+
+##### now?
+
+`Date` = `...`
+
+The moment to judge against. Pass a later one to see what a
+  run then would take.
+
+#### Returns
+
+`Promise`\<`number`\>
+
+How many entries were deleted.
+
+#### Remarks
+
+Walks every owner. Expiry stops an entry being used, not being stored:
+until this runs, an expired entry is still there and still listed.
+
+#### Example
+
+```ts
+await vault.put("alice", "temporary", "x", {
+    expiresAt: new Date(Date.now() - 1),
+})
+
+await vault.open("alice", "temporary")  // throws: 410, expired
+await vault.purgeExpired()              // 1
+await vault.has("alice", "temporary")   // false
+```