@mstone6969/vault 0.2.0 → 0.5.0

package/docs/index/classes/VaultError.md

@@ -0,0 +1,371 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / VaultError
+
+# Class: VaultError
+
+Defined in: cron/vault/src/errors.ts:27
+
+A caller mistake: a bad name, an empty value, a missing secret.
+
+## Remarks
+
+Everything the vault throws on purpose is a `VaultError`, so a caller can
+tell "you asked for something that cannot be done" apart from a bug, and
+answer accordingly, with one `instanceof`.
+
+## Example
+
+**Turning a vault call into an HTTP response**
+
+```ts
+import { Vault, VaultError, MemoryStore, generateKey } from "@mstone6969/vault"
+
+const vault = new Vault({ key: generateKey(), store: new MemoryStore() })
+
+try {
+    return new Response(await vault.open("alice", "stripe"))
+} catch (error) {
+    if (error instanceof VaultError) {
+        return new Response(error.message, { status: error.status })
+    }
+    throw error
+}
+```
+
+## See
+
+[VaultKeyError](VaultKeyError.md) for the key and ciphertext failures.
+
+## Extends
+
+- `Error`
+
+## Extended by
+
+- [`VaultKeyError`](VaultKeyError.md)
+
+## Constructors
+
+### Constructor
+
+> **new VaultError**(`message`, `status?`): `VaultError`
+
+Defined in: cron/vault/src/errors.ts:33
+
+#### Parameters
+
+##### message
+
+`string`
+
+What the caller did that the vault would not do. Names
+  and owners appear in it; secret values never do, so it is safe to log.
+
+##### status?
+
+`number` = `422`
+
+Suggested HTTP status. See [VaultError.status](#status).
+
+#### Returns
+
+`VaultError`
+
+#### Overrides
+
+`Error.constructor`
+
+## Properties
+
+### status
+
+> `readonly` **status**: `number` = `422`
+
+Defined in: cron/vault/src/errors.ts:63
+
+Suggested HTTP status, for callers putting this behind an API.
+
+#### Remarks
+
+It is a suggestion, not a promise about transport: nothing in the
+vault speaks HTTP. It exists so a handler can map a failure to a
+response without knowing which check inside the vault failed.
+
+The statuses actually thrown:
+
+- `422` — bad input: a name that is not 1–64 characters of letters,
+  numbers, dot, dash or underscore; an empty value; a `randomValue`
+  length below one or an alphabet under two characters; a rotation
+  asked of an entry with no rotation policy.
+- `404` — no secret under that name for that owner.
+- `409` — the entry is `final`, so it can be deleted but not
+  replaced.
+- `403` — the entry is sealed, so `read` will not hand it back.
+  `open` is the only way out.
+- `410` — the entry's `expiresAt` has passed. The record is still
+  there; it just cannot be used.
+- `501` — the entry's rotation policy names a generator this vault
+  was not constructed with.
+- `500` — [VaultKeyError](VaultKeyError.md)'s default: a key or ciphertext
+  problem, which is the operator's fault rather than the caller's.
+
+#### Default Value
+
+```ts
+422
+```
+
+***
+
+### stackTraceLimit
+
+> `static` **stackTraceLimit**: `number`
+
+Defined in: node\_modules/@types/node/globals.d.ts:67
+
+The `Error.stackTraceLimit` property specifies the number of stack frames
+collected by a stack trace (whether generated by `new Error().stack` or
+`Error.captureStackTrace(obj)`).
+
+The default value is `10` but may be set to any valid JavaScript number. Changes
+will affect any stack trace captured _after_ the value has been changed.
+
+If set to a non-number value, or set to a negative number, stack traces will
+not capture any frames.
+
+#### Inherited from
+
+`Error.stackTraceLimit`
+
+***
+
+### cause?
+
+> `optional` **cause?**: `unknown`
+
+Defined in: cron/node\_modules/.bun/typescript@6.0.3/node\_modules/typescript/lib/lib.es2022.error.d.ts:24
+
+The cause of the error.
+
+#### Inherited from
+
+`Error.cause`
+
+***
+
+### name
+
+> **name**: `string`
+
+Defined in: cron/node\_modules/.bun/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1074
+
+#### Inherited from
+
+`Error.name`
+
+***
+
+### message
+
+> **message**: `string`
+
+Defined in: cron/node\_modules/.bun/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1075
+
+#### Inherited from
+
+`Error.message`
+
+***
+
+### stack?
+
+> `optional` **stack?**: `string`
+
+Defined in: cron/node\_modules/.bun/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1076
+
+#### Inherited from
+
+`Error.stack`
+
+## Methods
+
+### captureStackTrace()
+
+#### Call Signature
+
+> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
+
+Defined in: node\_modules/@types/node/globals.d.ts:51
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack;  // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+  b();
+}
+
+function b() {
+  c();
+}
+
+function c() {
+  // Create an error without stack trace to avoid calculating the stack trace twice.
+  const { stackTraceLimit } = Error;
+  Error.stackTraceLimit = 0;
+  const error = new Error();
+  Error.stackTraceLimit = stackTraceLimit;
+
+  // Capture the stack trace above function b
+  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+  throw error;
+}
+
+a();
+```
+
+##### Parameters
+
+###### targetObject
+
+`object`
+
+###### constructorOpt?
+
+`Function`
+
+##### Returns
+
+`void`
+
+##### Inherited from
+
+`Error.captureStackTrace`
+
+#### Call Signature
+
+> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
+
+Defined in: cron/node\_modules/.bun/bun-types@1.4.0/node\_modules/bun-types/globals.d.ts:1062
+
+Create .stack property on a target object
+
+##### Parameters
+
+###### targetObject
+
+`object`
+
+###### constructorOpt?
+
+`Function`
+
+##### Returns
+
+`void`
+
+##### Inherited from
+
+`Error.captureStackTrace`
+
+***
+
+### prepareStackTrace()
+
+> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
+
+Defined in: node\_modules/@types/node/globals.d.ts:55
+
+#### Parameters
+
+##### err
+
+`Error`
+
+##### stackTraces
+
+`CallSite`[]
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+`Error.prepareStackTrace`
+
+***
+
+### isError()
+
+#### Call Signature
+
+> `static` **isError**(`error`): `error is Error`
+
+Defined in: cron/node\_modules/.bun/typescript@6.0.3/node\_modules/typescript/lib/lib.esnext.error.d.ts:21
+
+Indicates whether the argument provided is a built-in Error instance or not.
+
+##### Parameters
+
+###### error
+
+`unknown`
+
+##### Returns
+
+`error is Error`
+
+##### Inherited from
+
+`Error.isError`
+
+#### Call Signature
+
+> `static` **isError**(`value`): `value is Error`
+
+Defined in: cron/node\_modules/.bun/bun-types@1.4.0/node\_modules/bun-types/globals.d.ts:1057
+
+Check if a value is an instance of Error
+
+##### Parameters
+
+###### value
+
+`unknown`
+
+The value to check
+
+##### Returns
+
+`value is Error`
+
+True if the value is an instance of Error, false otherwise
+
+##### Inherited from
+
+`Error.isError`

package/docs/index/classes/VaultKeyError.md

@@ -0,0 +1,370 @@
+[**@mstone6969/vault**](../../README.md)
+
+***
+
+[@mstone6969/vault](../../README.md) / [index](../README.md) / VaultKeyError
+
+# Class: VaultKeyError
+
+Defined in: cron/vault/src/errors.ts:101
+
+The key is the wrong shape, or cannot open what it was given.
+
+## Remarks
+
+Thrown for a base64 key that is not 32 bytes, a sealed value not in
+`iv:payload` form, and a value that will not open — which covers both the
+wrong key and a value someone has altered, since GCM authenticates what it
+decrypts and cannot tell you which it was. The key providers throw it too,
+when the environment variable is unset or the key file is missing or empty.
+
+Its status is 500 rather than a 4xx because a request that reaches this did
+nothing wrong: the vault is misconfigured, or its data no longer matches its
+key.
+
+## Example
+
+**Distinguishing a key problem from a caller problem**
+
+```ts
+import { importKey, VaultKeyError } from "@mstone6969/vault"
+
+try {
+    await importKey(process.env.VAULT_KEY!)
+} catch (error) {
+    if (error instanceof VaultKeyError) {
+        console.error("vault key is unusable:", error.message)
+        process.exit(1)
+    }
+    throw error
+}
+```
+
+## See
+
+[VaultError](VaultError.md) for the mistakes callers can fix themselves.
+
+## Extends
+
+- [`VaultError`](VaultError.md)
+
+## Constructors
+
+### Constructor
+
+> **new VaultKeyError**(`message`): `VaultKeyError`
+
+Defined in: cron/vault/src/errors.ts:106
+
+#### Parameters
+
+##### message
+
+`string`
+
+What was wrong with the key or the sealed value. It never
+  says which key was tried or what the value held.
+
+#### Returns
+
+`VaultKeyError`
+
+#### Overrides
+
+[`VaultError`](VaultError.md).[`constructor`](VaultError.md#constructor)
+
+## Properties
+
+### status
+
+> `readonly` **status**: `number` = `422`
+
+Defined in: cron/vault/src/errors.ts:63
+
+Suggested HTTP status, for callers putting this behind an API.
+
+#### Remarks
+
+It is a suggestion, not a promise about transport: nothing in the
+vault speaks HTTP. It exists so a handler can map a failure to a
+response without knowing which check inside the vault failed.
+
+The statuses actually thrown:
+
+- `422` — bad input: a name that is not 1–64 characters of letters,
+  numbers, dot, dash or underscore; an empty value; a `randomValue`
+  length below one or an alphabet under two characters; a rotation
+  asked of an entry with no rotation policy.
+- `404` — no secret under that name for that owner.
+- `409` — the entry is `final`, so it can be deleted but not
+  replaced.
+- `403` — the entry is sealed, so `read` will not hand it back.
+  `open` is the only way out.
+- `410` — the entry's `expiresAt` has passed. The record is still
+  there; it just cannot be used.
+- `501` — the entry's rotation policy names a generator this vault
+  was not constructed with.
+- `500` — VaultKeyError's default: a key or ciphertext
+  problem, which is the operator's fault rather than the caller's.
+
+#### Default Value
+
+```ts
+422
+```
+
+#### Inherited from
+
+[`VaultError`](VaultError.md).[`status`](VaultError.md#status)
+
+***
+
+### stackTraceLimit
+
+> `static` **stackTraceLimit**: `number`
+
+Defined in: node\_modules/@types/node/globals.d.ts:67
+
+The `Error.stackTraceLimit` property specifies the number of stack frames
+collected by a stack trace (whether generated by `new Error().stack` or
+`Error.captureStackTrace(obj)`).
+
+The default value is `10` but may be set to any valid JavaScript number. Changes
+will affect any stack trace captured _after_ the value has been changed.
+
+If set to a non-number value, or set to a negative number, stack traces will
+not capture any frames.
+
+#### Inherited from
+
+[`VaultError`](VaultError.md).[`stackTraceLimit`](VaultError.md#stacktracelimit)
+
+***
+
+### cause?
+
+> `optional` **cause?**: `unknown`
+
+Defined in: cron/node\_modules/.bun/typescript@6.0.3/node\_modules/typescript/lib/lib.es2022.error.d.ts:24
+
+The cause of the error.
+
+#### Inherited from
+
+[`VaultError`](VaultError.md).[`cause`](VaultError.md#cause)
+
+***
+
+### name
+
+> **name**: `string`
+
+Defined in: cron/node\_modules/.bun/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1074
+
+#### Inherited from
+
+[`VaultError`](VaultError.md).[`name`](VaultError.md#name)
+
+***
+
+### message
+
+> **message**: `string`
+
+Defined in: cron/node\_modules/.bun/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1075
+
+#### Inherited from
+
+[`VaultError`](VaultError.md).[`message`](VaultError.md#message)
+
+***
+
+### stack?
+
+> `optional` **stack?**: `string`
+
+Defined in: cron/node\_modules/.bun/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1076
+
+#### Inherited from
+
+[`VaultError`](VaultError.md).[`stack`](VaultError.md#stack)
+
+## Methods
+
+### captureStackTrace()
+
+#### Call Signature
+
+> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
+
+Defined in: node\_modules/@types/node/globals.d.ts:51
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack;  // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+  b();
+}
+
+function b() {
+  c();
+}
+
+function c() {
+  // Create an error without stack trace to avoid calculating the stack trace twice.
+  const { stackTraceLimit } = Error;
+  Error.stackTraceLimit = 0;
+  const error = new Error();
+  Error.stackTraceLimit = stackTraceLimit;
+
+  // Capture the stack trace above function b
+  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+  throw error;
+}
+
+a();
+```
+
+##### Parameters
+
+###### targetObject
+
+`object`
+
+###### constructorOpt?
+
+`Function`
+
+##### Returns
+
+`void`
+
+##### Inherited from
+
+[`VaultError`](VaultError.md).[`captureStackTrace`](VaultError.md#capturestacktrace)
+
+#### Call Signature
+
+> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
+
+Defined in: cron/node\_modules/.bun/bun-types@1.4.0/node\_modules/bun-types/globals.d.ts:1062
+
+Create .stack property on a target object
+
+##### Parameters
+
+###### targetObject
+
+`object`
+
+###### constructorOpt?
+
+`Function`
+
+##### Returns
+
+`void`
+
+##### Inherited from
+
+[`VaultError`](VaultError.md).[`captureStackTrace`](VaultError.md#capturestacktrace)
+
+***
+
+### prepareStackTrace()
+
+> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
+
+Defined in: node\_modules/@types/node/globals.d.ts:55
+
+#### Parameters
+
+##### err
+
+`Error`
+
+##### stackTraces
+
+`CallSite`[]
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+[`VaultError`](VaultError.md).[`prepareStackTrace`](VaultError.md#preparestacktrace)
+
+***
+
+### isError()
+
+#### Call Signature
+
+> `static` **isError**(`error`): `error is Error`
+
+Defined in: cron/node\_modules/.bun/typescript@6.0.3/node\_modules/typescript/lib/lib.esnext.error.d.ts:21
+
+Indicates whether the argument provided is a built-in Error instance or not.
+
+##### Parameters
+
+###### error
+
+`unknown`
+
+##### Returns
+
+`error is Error`
+
+##### Inherited from
+
+[`VaultError`](VaultError.md).[`isError`](VaultError.md#iserror)
+
+#### Call Signature
+
+> `static` **isError**(`value`): `value is Error`
+
+Defined in: cron/node\_modules/.bun/bun-types@1.4.0/node\_modules/bun-types/globals.d.ts:1057
+
+Check if a value is an instance of Error
+
+##### Parameters
+
+###### value
+
+`unknown`
+
+The value to check
+
+##### Returns
+
+`value is Error`
+
+True if the value is an instance of Error, false otherwise
+
+##### Inherited from
+
+[`VaultError`](VaultError.md).[`isError`](VaultError.md#iserror)