@mstone6969/vault 0.2.0 → 0.5.0

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

@@ -0,0 +1,95 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / VaultEvent
+
+# Type Alias: VaultEvent
+
+> **VaultEvent** = `object`
+
+Defined in: cron/vault/src/types.ts:410
+
+Something a vault did, for whoever is keeping an audit trail.
+
+## Remarks
+
+Handed to the vault's `onAccess`, which is never awaited and whose failures
+are ignored — logging must not break a vault. Events carry names, never
+values, so the trail is safe to keep wherever logs go.
+
+## Example
+
+```ts
+const vault = new Vault({
+    key,
+    store,
+    onAccess: (event) => {
+        if (event.action === "denied") {
+            console.warn(`refused ${event.owner}/${event.name}: ${event.detail}`)
+        }
+    },
+})
+```
+
+## Properties
+
+### action
+
+> **action**: `"put"` \| `"open"` \| `"read"` \| `"remove"` \| `"rotate"` \| `"rekey"` \| `"denied"`
+
+Defined in: cron/vault/src/types.ts:418
+
+What was attempted. `denied` means the vault refused; see `detail`.
+
+#### Remarks
+
+`open` is a sealed value coming out, `read` an entry stored in the open.
+A `rotate` is also recorded as the `put` that carries it out.
+
+***
+
+### owner
+
+> **owner**: `string`
+
+Defined in: cron/vault/src/types.ts:420
+
+Whose entry it was. Empty for vault-wide actions.
+
+***
+
+### name
+
+> **name**: `string` \| `null`
+
+Defined in: cron/vault/src/types.ts:422
+
+The entry involved, or null for vault-wide actions like `rekey`.
+
+***
+
+### at
+
+> **at**: `Date`
+
+Defined in: cron/vault/src/types.ts:424
+
+When it happened.
+
+***
+
+### detail?
+
+> `optional` **detail?**: `string`
+
+Defined in: cron/vault/src/types.ts:434
+
+Why a `denied` happened, or what a vault-wide action touched.
+
+#### Remarks
+
+On a `denied`: `"final"` for a replacement of an entry written once,
+`"sealed"` for a `read` of a value only `open` returns, `"expired"` for
+an entry past `expiresAt`. On a `rekey`, how many entries moved and how
+many would not open.

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

@@ -0,0 +1,142 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / VaultOptions
+
+# Type Alias: VaultOptions
+
+> **VaultOptions** = `object`
+
+Defined in: cron/vault/src/vault.ts:159
+
+Everything a [Vault](../classes/Vault.md) is built from.
+
+## Example
+
+```ts
+import { Vault, MemoryStore, envKey } from "@mstone6969/vault"
+
+const vault = new Vault({
+    key: envKey("VAULT_KEY"),
+    store: new MemoryStore(),
+    historyLimit: 2,
+    onAccess: (event) => console.log(event.action, event.owner, event.name),
+})
+```
+
+## Properties
+
+### key
+
+> **key**: `string` \| `CryptoKey` \| [`KeyProvider`](KeyProvider.md)
+
+Defined in: cron/vault/src/vault.ts:161
+
+The master key: base64, already imported, or a provider that finds one.
+
+***
+
+### store
+
+> **store**: [`VaultStore`](VaultStore.md)
+
+Defined in: cron/vault/src/vault.ts:163
+
+Where records are kept.
+
+***
+
+### prefix?
+
+> `optional` **prefix?**: `string`
+
+Defined in: cron/vault/src/vault.ts:169
+
+Reference prefix, `@vault:` unless you say otherwise.
+
+#### Default Value
+
+[DEFAULT\_PREFIX](../variables/DEFAULT_PREFIX.md)
+
+***
+
+### previousKeys?
+
+> `optional` **previousKeys?**: (`string` \| `CryptoKey` \| [`KeyProvider`](KeyProvider.md))[]
+
+Defined in: cron/vault/src/vault.ts:180
+
+Keys this vault will still open values with, but never seal under.
+
+Keep the old key here while a `rekey` is in flight, or after one that did
+not finish: values left under it stay readable instead of becoming
+unopenable the moment the primary key changes.
+
+#### Default Value
+
+```ts
+none
+```
+
+#### See
+
+[Vault.rekey](../classes/Vault.md#rekey)
+
+***
+
+### historyLimit?
+
+> `optional` **historyLimit?**: `number`
+
+Defined in: cron/vault/src/vault.ts:186
+
+How many previous values `rotate` keeps.
+
+#### Default Value
+
+[DEFAULT\_HISTORY\_LIMIT](../variables/DEFAULT_HISTORY_LIMIT.md)
+
+***
+
+### generators?
+
+> `optional` **generators?**: `Record`\<`string`, [`Generator`](Generator.md)\>
+
+Defined in: cron/vault/src/vault.ts:196
+
+Functions that mint new values, by the name a rotation policy uses.
+
+The vault stores the *name*, never the function — so what is written down
+is that an entry can be rotated, not how to impersonate the thing that
+rotates it.
+
+#### Default Value
+
+none, so a `generator` policy fails with 501
+
+***
+
+### onAccess?
+
+> `optional` **onAccess?**: (`event`) => `void`
+
+Defined in: cron/vault/src/vault.ts:204
+
+Called after everything the vault does, for an audit trail. It is never
+awaited and its failures are ignored — logging must not break a vault.
+
+#### Parameters
+
+##### event
+
+[`VaultEvent`](VaultEvent.md)
+
+#### Returns
+
+`void`
+
+#### See
+
+[VaultEvent](VaultEvent.md) for what it is told, including the refusals,
+  which arrive as `denied` with a `detail` saying which rule was hit.

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

@@ -0,0 +1,156 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / VaultStore
+
+# Type Alias: VaultStore
+
+> **VaultStore** = `object`
+
+Defined in: cron/vault/src/types.ts:348
+
+Where records live. Implement this to keep secrets in whatever database you
+already run; `MemoryStore`, `SqliteStore` and `FileStore` ship with the
+package.
+
+A store persists records as given and enforces nothing: the rules about
+finality, expiry and history are the vault's.
+
+## Example
+
+```ts
+import { Vault, MemoryStore } from "@mstone6969/vault"
+
+const vault = new Vault({ key, store: new MemoryStore() })
+```
+
+## See
+
+[SecretRecord](SecretRecord.md)
+
+## Methods
+
+### get()
+
+> **get**(`owner`, `name`): `Promise`\<[`SecretRecord`](SecretRecord.md) \| `null`\>
+
+Defined in: cron/vault/src/types.ts:356
+
+One record, or null when there is none under that name.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry to look for.
+
+##### name
+
+`string`
+
+The entry's name, already checked by the vault.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](SecretRecord.md) \| `null`\>
+
+The record as it was written, or null.
+
+***
+
+### list()
+
+> **list**(`owner`): `Promise`\<[`SecretRecord`](SecretRecord.md)[]\>
+
+Defined in: cron/vault/src/types.ts:363
+
+Every record one owner holds, in any order.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entries to return.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](SecretRecord.md)[]\>
+
+The owner's records; the vault sorts them by name itself.
+
+***
+
+### all()
+
+> **all**(): `Promise`\<[`SecretRecord`](SecretRecord.md)[]\>
+
+Defined in: cron/vault/src/types.ts:370
+
+Every record the store holds, whoever owns it. Only `rekey` and
+`purgeExpired` need this — nothing else reaches across owners.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](SecretRecord.md)[]\>
+
+Every record, in any order.
+
+***
+
+### put()
+
+> **put**(`record`): `Promise`\<[`SecretRecord`](SecretRecord.md)\>
+
+Defined in: cron/vault/src/types.ts:378
+
+Writes a record, replacing any under the same owner and name.
+
+#### Parameters
+
+##### record
+
+[`SecretRecord`](SecretRecord.md)
+
+The record to write. Store it as given: `isFinal` is the
+  vault's rule to enforce, not the store's.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](SecretRecord.md)\>
+
+The record as stored, which is what the caller sees.
+
+***
+
+### remove()
+
+> **remove**(`owner`, `name`): `Promise`\<`boolean`\>
+
+Defined in: cron/vault/src/types.ts:386
+
+Deletes a record, returning false when there was nothing to delete.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry to delete.
+
+##### name
+
+`string`
+
+The entry to delete.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True when a record went, false when there was none.

package/docs/index/variables/DEFAULT_ALPHABET.md

@@ -0,0 +1,29 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / DEFAULT\_ALPHABET
+
+# Variable: DEFAULT\_ALPHABET
+
+> `const` **DEFAULT\_ALPHABET**: `"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"` = `"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"`
+
+Defined in: cron/vault/src/vault.ts:50
+
+What a random rotation draws from unless the policy says otherwise.
+
+## Remarks
+
+Letters and digits only, so a generated value survives being pasted into a
+shell command or a connection string without quoting. Set
+[RotationPolicy.alphabet](../type-aliases/RotationPolicy.md#alphabet) for anything narrower or wider.
+
+## Default Value
+
+```ts
+A-Z, a-z and 0-9: 62 characters
+```
+
+## See
+
+[randomValue](../functions/randomValue.md)

package/docs/index/variables/DEFAULT_HISTORY_LIMIT.md

@@ -0,0 +1,28 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / DEFAULT\_HISTORY\_LIMIT
+
+# Variable: DEFAULT\_HISTORY\_LIMIT
+
+> `const` **DEFAULT\_HISTORY\_LIMIT**: `5` = `5`
+
+Defined in: cron/vault/src/vault.ts:35
+
+How many previous values an entry keeps, unless you say otherwise.
+
+## Remarks
+
+Only [Vault.rotate](../classes/Vault.md#rotate) adds to history, so this is how many superseded
+values [Vault.versions](../classes/Vault.md#versions) can still hand back.
+
+## Default Value
+
+```ts
+5
+```
+
+## See
+
+[VaultOptions.historyLimit](../type-aliases/VaultOptions.md#historylimit)

package/docs/index/variables/DEFAULT_PREFIX.md

@@ -0,0 +1,23 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / DEFAULT\_PREFIX
+
+# Variable: DEFAULT\_PREFIX
+
+> `const` **DEFAULT\_PREFIX**: `"@vault:"` = `"@vault:"`
+
+Defined in: cron/vault/src/vault.ts:23
+
+How a stored value is referenced from configuration.
+
+## Remarks
+
+[Vault.resolve](../classes/Vault.md#resolve) substitutes any value that starts with this. Give a
+vault its own [VaultOptions.prefix](../type-aliases/VaultOptions.md#prefix) when `@vault:` already means
+something else in the configuration you are resolving.
+
+## Default Value
+
+`"@vault:"`

package/docs/stores/sqlite/README.md

@@ -0,0 +1,11 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / stores/sqlite
+
+# stores/sqlite
+
+## Classes
+
+- [SqliteStore](classes/SqliteStore.md)