@mstone6969/vault 0.2.0 → 0.5.0

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

@@ -0,0 +1,141 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / PutOptions
+
+# Type Alias: PutOptions
+
+> **PutOptions** = `object`
+
+Defined in: cron/vault/src/types.ts:275
+
+What `put` is allowed to say about an entry beyond its value.
+
+## Remarks
+
+Every field left out means "as it was" on a replacing `put`, so rotating a
+credential does not quietly forget what kind it is or when it expires. The
+exception is `final`, which must be asked for each time.
+
+## Example
+
+```ts
+await vault.put("alice", "db", "s3cret", {
+    metadata: { kind: "postgres", user: "app" },
+    rotation: { kind: "random", length: 40 },
+    expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+})
+```
+
+## Properties
+
+### metadata?
+
+> `optional` **metadata?**: `Record`\<`string`, `string`\>
+
+Defined in: cron/vault/src/types.ts:280
+
+Non-secret facts to keep beside the value, returned by `list`. Replaces
+whatever was there; leave it out to keep what the entry already has.
+
+***
+
+### rotation?
+
+> `optional` **rotation?**: [`RotationPolicy`](RotationPolicy.md) \| `null`
+
+Defined in: cron/vault/src/types.ts:289
+
+How to produce the next value when it is rotated.
+
+#### Remarks
+
+Pass null to drop a policy an entry already has; leaving it out keeps it.
+
+#### See
+
+[RotationPolicy](RotationPolicy.md)
+
+***
+
+### open?
+
+> `optional` **open?**: `boolean`
+
+Defined in: cron/vault/src/types.ts:299
+
+Store in the open, readable by `read`.
+
+#### Remarks
+
+For values that belong beside the secrets but are not secret — a host, an
+account id. Left out, the entry keeps how it was already stored.
+
+#### Default Value
+
+```ts
+false
+```
+
+***
+
+### final?
+
+> `optional` **final?**: `boolean`
+
+Defined in: cron/vault/src/types.ts:309
+
+Refuse every future replacement.
+
+#### Remarks
+
+Not sticky: it is taken from this call alone, so it must be repeated by
+anything rewriting the entry — which nothing can, once it is set.
+
+#### Default Value
+
+```ts
+false
+```
+
+***
+
+### expiresAt?
+
+> `optional` **expiresAt?**: `Date` \| `null`
+
+Defined in: cron/vault/src/types.ts:318
+
+When it should stop resolving.
+
+#### Remarks
+
+Pass null to make an expiring entry permanent again.
+
+#### Default Value
+
+```ts
+null
+```
+
+***
+
+### keepHistory?
+
+> `optional` **keepHistory?**: `boolean`
+
+Defined in: cron/vault/src/types.ts:328
+
+Keep the value being replaced, up to `historyLimit`.
+
+#### Remarks
+
+What `rotate` sets for you; set it by hand when replacing a value
+yourself and something may still be running on the old one.
+
+#### Default Value
+
+```ts
+false
+```

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

@@ -0,0 +1,37 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / RekeyReport
+
+# Type Alias: RekeyReport
+
+> **RekeyReport** = `object`
+
+Defined in: cron/vault/src/vault.ts:212
+
+What a `rekey` did, and to what it could not do it.
+
+## See
+
+[Vault.rekey](../classes/Vault.md#rekey)
+
+## Properties
+
+### rekeyed
+
+> **rekeyed**: `number`
+
+Defined in: cron/vault/src/vault.ts:214
+
+How many entries were re-sealed under the new key.
+
+***
+
+### failed
+
+> **failed**: `string`[]
+
+Defined in: cron/vault/src/vault.ts:216
+
+Entries that would not open, by `owner/name`, left exactly as they were.

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

@@ -0,0 +1,49 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / RotationContext
+
+# Type Alias: RotationContext
+
+> **RotationContext** = `object`
+
+Defined in: cron/vault/src/vault.ts:60
+
+Everything a generator is told: which entry is being rotated and the
+non-secret arguments its policy carries. Deliberately not the current value —
+a generator that needs it can ask the vault for it.
+
+## See
+
+[Generator](Generator.md), [RotationPolicy.arguments](RotationPolicy.md#arguments)
+
+## Properties
+
+### owner
+
+> **owner**: `string`
+
+Defined in: cron/vault/src/vault.ts:62
+
+Whose entry is being rotated.
+
+***
+
+### name
+
+> **name**: `string`
+
+Defined in: cron/vault/src/vault.ts:64
+
+Which entry is being rotated.
+
+***
+
+### arguments
+
+> **arguments**: `Record`\<`string`, `string`\>
+
+Defined in: cron/vault/src/vault.ts:66
+
+The non-secret arguments its policy carries.

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

@@ -0,0 +1,142 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / RotationPolicy
+
+# Type Alias: RotationPolicy
+
+> **RotationPolicy** = `object`
+
+Defined in: cron/vault/src/types.ts:57
+
+How an entry's next value is produced.
+
+This is a recipe, not a value: it says *how* to make the next password, never
+what the current one is. Storing it means an entry can be rotated by anything
+holding the vault, without that thing being told the secret it is replacing.
+
+## Example
+
+```ts
+// The vault mints the next value itself.
+await vault.put("alice", "db", "current", {
+    rotation: { kind: "random", length: 40, every: 60 * 60 * 24 * 30 },
+})
+
+// Or a function registered on the vault does, for a credential only the
+// far end can issue.
+await vault.put("alice", "aws", "current", {
+    rotation: { kind: "generator", generator: "aws", arguments: { user: "ci" } },
+})
+await vault.rotate("alice", "aws")
+```
+
+## See
+
+[PutOptions.rotation](PutOptions.md#rotation)
+
+## Properties
+
+### kind
+
+> **kind**: `"random"` \| `"generator"`
+
+Defined in: cron/vault/src/types.ts:66
+
+`random` has the vault generate one. `generator` calls a function you
+registered by name — for a credential only the far end can mint.
+
+#### Remarks
+
+`generator` names a function in the vault's `generators`; rotating with a
+name the vault does not have fails rather than inventing a value.
+
+***
+
+### length?
+
+> `optional` **length?**: `number`
+
+Defined in: cron/vault/src/types.ts:72
+
+random: how many characters. Default 32.
+
+#### Default Value
+
+```ts
+32
+```
+
+***
+
+### alphabet?
+
+> `optional` **alphabet?**: `string`
+
+Defined in: cron/vault/src/types.ts:82
+
+random: which characters to draw from.
+
+#### Remarks
+
+Sampling is unbiased whatever the length, so an alphabet trimmed to what
+a system accepts costs nothing. Needs at least two characters.
+
+#### Default Value
+
+`DEFAULT_ALPHABET` — the 62 ASCII letters and digits
+
+***
+
+### generator?
+
+> `optional` **generator?**: `string`
+
+Defined in: cron/vault/src/types.ts:91
+
+generator: which registered generator to call.
+
+#### Remarks
+
+A name, not a function. What is written down is that an entry can be
+rotated, not how to impersonate the thing that rotates it — the function
+stays in the process that built the vault.
+
+***
+
+### arguments?
+
+> `optional` **arguments?**: `Record`\<`string`, `string`\>
+
+Defined in: cron/vault/src/types.ts:99
+
+generator: non-secret arguments, e.g. which account to rotate.
+
+#### Remarks
+
+Stored in the clear beside the policy, so it must hold nothing secret.
+Reaches the generator as the `arguments` of its context.
+
+***
+
+### every?
+
+> `optional` **every?**: `number`
+
+Defined in: cron/vault/src/types.ts:114
+
+How often it wants rotating, in seconds. Nothing enforces it; `rotationDue` reports it.
+
+#### Remarks
+
+Measured from `rotatedAt`, or from `createdAt` for an entry never
+rotated. Left out, the entry is never reported as due.
+
+#### Example
+
+```ts
+for (const secret of await vault.rotationDue()) {
+    await vault.rotate(secret.owner, secret.name)
+}
+```

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

@@ -0,0 +1,214 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / SecretRecord
+
+# Type Alias: SecretRecord
+
+> **SecretRecord** = `object`
+
+Defined in: cron/vault/src/types.ts:127
+
+A stored secret, as the store keeps it.
+
+## Remarks
+
+The shape a [VaultStore](VaultStore.md) reads and writes, and the only place the
+sealed bytes appear. Callers of the vault get [SecretSummary](SecretSummary.md) instead.
+A store persists these fields as given: none of them mean anything to it.
+
+## See
+
+[SecretSummary](SecretSummary.md)
+
+## Properties
+
+### owner
+
+> **owner**: `string`
+
+Defined in: cron/vault/src/types.ts:129
+
+Whose it is. The vault never reaches across owners except to rekey.
+
+***
+
+### name
+
+> **name**: `string`
+
+Defined in: cron/vault/src/types.ts:137
+
+What it is called, and how a reference finds it.
+
+#### Remarks
+
+Up to 64 characters of letters, numbers, dot, dash or underscore —
+checked by the vault before it reaches a store. Unique per owner.
+
+***
+
+### sealed
+
+> **sealed**: `string`
+
+Defined in: cron/vault/src/types.ts:142
+
+The value, sealed under this entry's data key — `iv:payload`, base64.
+Empty when the entry is not sealed.
+
+***
+
+### sealedKey
+
+> **sealedKey**: `string` \| `null`
+
+Defined in: cron/vault/src/types.ts:153
+
+This entry's data key, sealed under the master key.
+
+Every value gets its own key, and only these are re-sealed when the
+master key changes: rekeying costs one small operation per entry rather
+than re-encrypting every byte, and one leaked data key exposes one value.
+
+Null on entries written before envelope encryption, whose value is sealed
+under the master key directly.
+
+***
+
+### plain
+
+> **plain**: `string` \| `null`
+
+Defined in: cron/vault/src/types.ts:161
+
+The value in the open. Only ever set when `isSealed` is false.
+
+#### Remarks
+
+This is the one field a store holds that is readable without a key, so an
+entry only lands here when `put` was told `open: true`.
+
+***
+
+### isSealed
+
+> **isSealed**: `boolean`
+
+Defined in: cron/vault/src/types.ts:171
+
+False for entries stored in the open, which can be read back.
+
+#### Remarks
+
+Left out of a replacing `put`, an entry keeps whatever it already was:
+rotating a credential should not quietly unseal it.
+
+#### Default Value
+
+```ts
+true for a new entry
+```
+
+***
+
+### isFinal
+
+> **isFinal**: `boolean`
+
+Defined in: cron/vault/src/types.ts:180
+
+Written once: a store must refuse to replace it.
+
+#### Remarks
+
+The refusing is the vault's — a store writes what it is given. `put` on a
+final entry throws and records a `denied` event with detail `"final"`.
+Removing it still works; finality is about change, not deletion.
+
+***
+
+### expiresAt
+
+> **expiresAt**: `Date` \| `null`
+
+Defined in: cron/vault/src/types.ts:188
+
+When the entry stops resolving, or null if it does not.
+
+#### Remarks
+
+The entry stays in the store past this moment, but `open`, `read` and
+`resolve` refuse it. `purgeExpired` is what actually deletes it.
+
+***
+
+### history
+
+> **history**: [`HistoryEntry`](HistoryEntry.md)[]
+
+Defined in: cron/vault/src/types.ts:196
+
+Previous values, newest first. Empty unless the entry keeps history.
+
+#### Remarks
+
+Filled by `rotate`, or by a `put` told `keepHistory: true`, and trimmed
+to the vault's `historyLimit`.
+
+***
+
+### rotation
+
+> **rotation**: [`RotationPolicy`](RotationPolicy.md) \| `null`
+
+Defined in: cron/vault/src/types.ts:198
+
+How to produce the next value, or null if nothing knows.
+
+***
+
+### rotatedAt
+
+> **rotatedAt**: `Date` \| `null`
+
+Defined in: cron/vault/src/types.ts:206
+
+When it was last rotated, as opposed to merely replaced.
+
+#### Remarks
+
+Null until the first rotation, which is why `rotationDue` falls back to
+`createdAt` when deciding whether `every` has elapsed.
+
+***
+
+### metadata
+
+> **metadata**: `Record`\<`string`, `string`\>
+
+Defined in: cron/vault/src/types.ts:211
+
+Non-secret facts, stored in the clear and returned by `list`: what kind
+of credential it is, which username it belongs to, a public key.
+
+***
+
+### createdAt
+
+> **createdAt**: `Date`
+
+Defined in: cron/vault/src/types.ts:213
+
+When the entry was first stored. Survives replacement.
+
+***
+
+### updatedAt
+
+> **updatedAt**: `Date`
+
+Defined in: cron/vault/src/types.ts:215
+
+When it last changed.

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

@@ -0,0 +1,56 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / SecretSummary
+
+# Type Alias: SecretSummary
+
+> **SecretSummary** = `Omit`\<[`SecretRecord`](SecretRecord.md), `"sealed"` \| `"sealedKey"` \| `"plain"` \| `"history"`\> & `object`
+
+Defined in: cron/vault/src/types.ts:236
+
+A stored secret, as callers are allowed to see it: no sealed value.
+
+## Type Declaration
+
+### value?
+
+> `optional` **value?**: `string`
+
+Present only for entries stored in the open.
+
+#### Remarks
+
+A sealed entry leaves this undefined however it is summarised; its value
+only comes out of `open`.
+
+### versions
+
+> **versions**: `number`
+
+How many previous values are kept.
+
+#### Remarks
+
+A count, not the values: `versions` on the vault opens those, one at a
+time and only for whoever holds the key.
+
+## Remarks
+
+What `put`, `rotate`, `list` and `rotationDue` hand back. The sealed bytes,
+the data key and the kept history are dropped rather than hidden, so a
+summary can be logged or returned from an API without leaking anything the
+master key protects.
+
+## Example
+
+```ts
+for (const secret of await vault.list("alice")) {
+    console.log(secret.name, secret.metadata.kind, secret.versions)
+}
+```
+
+## See
+
+[SecretRecord](SecretRecord.md)