@3sixty/vault-models 0.0.0-stage → 0.20.0-next.1

package/docs/examples.md

@@ -0,0 +1,141 @@
+# Vault Models Examples
+
+These examples show how to register vault connectors, use helper utilities for JWT workflows, and work with the shared key and encryption types.
+
+## VaultConnectorHelper
+
+```typescript
+import { Jwt, type IJwtHeader, type IJwtPayload } from '@3sixty/web';
+import {
+  VaultConnectorFactory,
+  VaultConnectorHelper,
+  VaultEncryptionType,
+  VaultKeyType,
+  type IVaultConnector
+} from '@3sixty/vault-models';
+
+class InMemoryVaultConnector implements IVaultConnector {
+  public className(): string {
+    return 'InMemoryVaultConnector';
+  }
+
+  public async createKey(name: string, type: VaultKeyType): Promise<Uint8Array> {
+    return Promise.resolve(new Uint8Array([type, name.length]));
+  }
+
+  public async addKey(
+    _name: string,
+    _type: VaultKeyType,
+    _privateKey: Uint8Array,
+    _publicKey?: Uint8Array
+  ): Promise<void> {
+    return Promise.resolve();
+  }
+
+  public async getKey(_name: string): Promise<{
+    type: VaultKeyType;
+    privateKey: Uint8Array;
+    publicKey?: Uint8Array;
+  }> {
+    return Promise.resolve({
+      type: VaultKeyType.Ed25519,
+      privateKey: new Uint8Array([1, 2, 3]),
+      publicKey: new Uint8Array([4, 5, 6])
+    });
+  }
+
+  public async getKeyType(_name: string): Promise<VaultKeyType> {
+    return Promise.resolve(VaultKeyType.Ed25519);
+  }
+
+  public async renameKey(_name: string, _newName: string): Promise<void> {
+    return Promise.resolve();
+  }
+
+  public async removeKey(_name: string): Promise<void> {
+    return Promise.resolve();
+  }
+
+  public async sign(_name: string, data: Uint8Array): Promise<Uint8Array> {
+    return Promise.resolve(data);
+  }
+
+  public async verify(_name: string, data: Uint8Array, signature: Uint8Array): Promise<boolean> {
+    return Promise.resolve(data.length === signature.length);
+  }
+
+  public async encrypt(
+    _name: string,
+    _encryptionType: VaultEncryptionType,
+    data: Uint8Array
+  ): Promise<Uint8Array> {
+    return Promise.resolve(data);
+  }
+
+  public async decrypt(
+    _name: string,
+    _encryptionType: VaultEncryptionType,
+    encryptedData: Uint8Array
+  ): Promise<Uint8Array> {
+    return Promise.resolve(encryptedData);
+  }
+
+  public async setSecret<T>(_name: string, _data: T): Promise<void> {
+    return Promise.resolve();
+  }
+
+  public async getSecret<T>(_name: string): Promise<T> {
+    throw new Error('Not implemented in this example');
+  }
+
+  public async removeSecret(_name: string): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+VaultConnectorFactory.register('in-memory', () => new InMemoryVaultConnector());
+
+const connector = VaultConnectorFactory.get('in-memory');
+
+const header: IJwtHeader = {
+  alg: 'EdDSA',
+  typ: 'JWT'
+};
+
+const payload: IJwtPayload = {
+  iss: 'example-service',
+  sub: 'user-123',
+  exp: Math.floor(Date.now() / 1000) + 600
+};
+
+const token = await VaultConnectorHelper.jwtSigner(connector, 'jwt-key', header, payload);
+console.log(token.length > 0); // true
+
+const decoded = Jwt.decode(token);
+console.log(decoded.payload.sub); // user-123
+
+const verified = await VaultConnectorHelper.jwtVerifier<IJwtHeader, IJwtPayload>(
+  connector,
+  'jwt-key',
+  token
+);
+
+console.log(verified.payload.iss); // example-service
+```
+
+## Types And Constants
+
+```typescript
+import { VaultEncryptionType, VaultKeyType } from '@3sixty/vault-models';
+
+const keyTypes: VaultKeyType[] = [
+  VaultKeyType.Ed25519,
+  VaultKeyType.Secp256k1,
+  VaultKeyType.ChaCha20Poly1305
+];
+
+const encryptionType: VaultEncryptionType = VaultEncryptionType.ChaCha20Poly1305;
+
+console.log(keyTypes.includes(VaultKeyType.Ed25519)); // true
+console.log(encryptionType === VaultEncryptionType.ChaCha20Poly1305); // true
+```

package/docs/reference/classes/VaultConnectorHelper.md

@@ -0,0 +1,127 @@
+# Class: VaultConnectorHelper
+
+Helpers for vault connectors.
+
+## Constructors
+
+### Constructor
+
+> **new VaultConnectorHelper**(): `VaultConnectorHelper`
+
+#### Returns
+
+`VaultConnectorHelper`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### jwtSigner() {#jwtsigner}
+
+> `static` **jwtSigner**(`vaultConnector`, `keyName`, `header`, `payload`): `Promise`\<`string`\>
+
+Sign a JWT using vault connector.
+
+#### Parameters
+
+##### vaultConnector
+
+[`IVaultConnector`](../interfaces/IVaultConnector.md)
+
+The vault connector to use.
+
+##### keyName
+
+`string`
+
+The name of the key to sign with.
+
+##### header
+
+`JWTHeaderParameters`
+
+The header to sign.
+
+##### payload
+
+`JWTPayload`
+
+The payload to sign.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The token.
+
+***
+
+### jwtVerifier() {#jwtverifier}
+
+> `static` **jwtVerifier**\<`T`, `U`\>(`vaultConnector`, `keyName`, `token`): `Promise`\<\{ `header`: `T`; `payload`: `U`; \}\>
+
+Verify a JWT using a vault connector.
+
+#### Type Parameters
+
+##### T {#t}
+
+`T` *extends* `JWTHeaderParameters`
+
+##### U {#u}
+
+`U` *extends* `JWTPayload`
+
+#### Parameters
+
+##### vaultConnector
+
+[`IVaultConnector`](../interfaces/IVaultConnector.md)
+
+The vault connector to use.
+
+##### keyName
+
+`string`
+
+The name of the key to verify with.
+
+##### token
+
+`string`
+
+The token to verify.
+
+#### Returns
+
+`Promise`\<\{ `header`: `T`; `payload`: `U`; \}\>
+
+The header and payload if verification successful.
+
+***
+
+### buildKeyName() {#buildkeyname}
+
+> `static` **buildKeyName**(...`keyParts`): `string`
+
+Build a key name from parts.
+
+#### Parameters
+
+##### keyParts
+
+...`string`[]
+
+The parts of the key.
+
+#### Returns
+
+`string`
+
+The constructed key name.

package/docs/reference/index.md

@@ -0,0 +1,20 @@
+# @3sixty/vault-models
+
+## Classes
+
+- [VaultConnectorHelper](classes/VaultConnectorHelper.md)
+
+## Interfaces
+
+- [IVaultConnector](interfaces/IVaultConnector.md)
+
+## Type Aliases
+
+- [VaultEncryptionType](type-aliases/VaultEncryptionType.md)
+- [VaultKeyType](type-aliases/VaultKeyType.md)
+
+## Variables
+
+- [VaultConnectorFactory](variables/VaultConnectorFactory.md)
+- [VaultEncryptionType](variables/VaultEncryptionType.md)
+- [VaultKeyType](variables/VaultKeyType.md)

package/docs/reference/interfaces/IVaultConnector.md

@@ -0,0 +1,449 @@
+# Interface: IVaultConnector
+
+Interface describing a vault securely storing data.
+
+## Extends
+
+- `IComponent`
+
+## Methods
+
+### createKey() {#createkey}
+
+> **createKey**(`name`, `type`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+Generate a new key and store it in the vault.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the key to generate and store in the vault.
+
+##### type
+
+[`VaultKeyType`](../type-aliases/VaultKeyType.md)
+
+The type of key to create.
+
+#### Returns
+
+`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+The public key for the key pair.
+
+***
+
+### addKey() {#addkey}
+
+> **addKey**(`name`, `type`, `privateKey`, `publicKey?`): `Promise`\<`void`\>
+
+Add an existing key to the vault.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the key to add to the vault.
+
+##### type
+
+[`VaultKeyType`](../type-aliases/VaultKeyType.md)
+
+The type of key to add.
+
+##### privateKey
+
+`Uint8Array`
+
+The private key.
+
+##### publicKey?
+
+`Uint8Array`\<`ArrayBufferLike`\>
+
+The public key, can be undefined if the key type is symmetric.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the key has been stored.
+
+***
+
+### getKey() {#getkey}
+
+> **getKey**(`name`, `components?`): `Promise`\<\{ `type`: [`VaultKeyType`](../type-aliases/VaultKeyType.md); `privateKey?`: `Uint8Array`\<`ArrayBufferLike`\>; `publicKey?`: `Uint8Array`\<`ArrayBufferLike`\>; \}\>
+
+Get a key from the vault.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the key to get from the vault.
+
+##### components?
+
+`"public"` \| `"private"` \| `"both"`
+
+Which key components to return, defaults to "both".
+
+#### Returns
+
+`Promise`\<\{ `type`: [`VaultKeyType`](../type-aliases/VaultKeyType.md); `privateKey?`: `Uint8Array`\<`ArrayBufferLike`\>; `publicKey?`: `Uint8Array`\<`ArrayBufferLike`\>; \}\>
+
+The key, publicKey can be undefined if key is symmetric, privateKey can be undefined if only public was requested.
+
+#### Throws
+
+GeneralError if "private" is requested for a symmetric key.
+
+***
+
+### keyExists() {#keyexists}
+
+> **keyExists**(`name`): `Promise`\<`boolean`\>
+
+Check if a key exists in the vault.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the key to check.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True if the key exists, false otherwise.
+
+***
+
+### getKeyType() {#getkeytype}
+
+> **getKeyType**(`name`): `Promise`\<[`VaultKeyType`](../type-aliases/VaultKeyType.md)\>
+
+Get the type of a key from the vault without retrieving the key material.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the key.
+
+#### Returns
+
+`Promise`\<[`VaultKeyType`](../type-aliases/VaultKeyType.md)\>
+
+The key type.
+
+#### Throws
+
+NotFoundError if the key does not exist.
+
+***
+
+### renameKey() {#renamekey}
+
+> **renameKey**(`name`, `newName`): `Promise`\<`void`\>
+
+Rename a key in the vault.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the key to rename.
+
+##### newName
+
+`string`
+
+The new name of the key.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the key has been renamed.
+
+***
+
+### removeKey() {#removekey}
+
+> **removeKey**(`name`): `Promise`\<`void`\>
+
+Remove a key from the vault.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the key to remove from the vault.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the key has been removed.
+
+***
+
+### sign() {#sign}
+
+> **sign**(`name`, `data`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+Sign the data using a key in the vault.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the key to use for signing.
+
+##### data
+
+`Uint8Array`
+
+The data to sign.
+
+#### Returns
+
+`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+The signature for the data.
+
+***
+
+### verify() {#verify}
+
+> **verify**(`name`, `data`, `signature`): `Promise`\<`boolean`\>
+
+Verify the signature of the data using a key in the vault.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the key to use for verification.
+
+##### data
+
+`Uint8Array`
+
+The data that was signed.
+
+##### signature
+
+`Uint8Array`
+
+The signature to verify.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True if the verification is successful.
+
+***
+
+### encrypt() {#encrypt}
+
+> **encrypt**(`name`, `encryptionType`, `data`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+Encrypt the data using a key in the vault.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the key to use for encryption.
+
+##### encryptionType
+
+`0`
+
+The type of encryption to use.
+
+##### data
+
+`Uint8Array`
+
+The data to encrypt.
+
+#### Returns
+
+`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+The encrypted data.
+
+***
+
+### decrypt() {#decrypt}
+
+> **decrypt**(`name`, `encryptionType`, `encryptedData`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+Decrypt the data using a key in the vault.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the key to use for decryption.
+
+##### encryptionType
+
+`0`
+
+The type of encryption to use.
+
+##### encryptedData
+
+`Uint8Array`
+
+The data to decrypt.
+
+#### Returns
+
+`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+The decrypted data.
+
+***
+
+### setSecret() {#setsecret}
+
+> **setSecret**\<`T`\>(`name`, `data`): `Promise`\<`void`\>
+
+Store a secret in the vault.
+
+#### Type Parameters
+
+##### T {#t}
+
+`T`
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the secret in the vault to set.
+
+##### data
+
+`T`
+
+The secret to add to the vault.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the secret has been stored.
+
+***
+
+### secretExists() {#secretexists}
+
+> **secretExists**(`name`): `Promise`\<`boolean`\>
+
+Check if a secret exists in the vault.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the secret to check.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True if the secret exists, false otherwise.
+
+***
+
+### getSecret() {#getsecret}
+
+> **getSecret**\<`T`\>(`name`): `Promise`\<`T`\>
+
+Get a secret from the vault.
+
+#### Type Parameters
+
+##### T {#t-1}
+
+`T`
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the secret in the vault to get.
+
+#### Returns
+
+`Promise`\<`T`\>
+
+The secret from the vault.
+
+#### Throws
+
+Error if the secret is not found.
+
+***
+
+### removeSecret() {#removesecret}
+
+> **removeSecret**(`name`): `Promise`\<`void`\>
+
+Remove a secret from the vault.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the secret in the vault to remove.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the secret has been removed.
+
+#### Throws
+
+Error if the secret is not found.