@owlmeans/basic-keys 0.1.2 → 0.1.4

package/README.md

@@ -1,474 +1,82 @@
 # @owlmeans/basic-keys
 
-A core cryptographic library for the OwlMeans Common ecosystem, providing key pair generation, digital signing, encryption, and authentication credential management.
+ED25519 and XChaCha20 cryptographic key operations: generation, signing, verification, and credential packing.
 
 ## Overview
 
-The `@owlmeans/basic-keys` package implements the core cryptographic subsystem used primarily by the OwlMeans Authentication Subsystem. It provides a unified API for working with different cryptographic algorithms through an extensible plugin system.
-
-## Features
-
-- **Key Pair Management**: Generate, import, and export cryptographic key pairs
-- **Digital Signatures**: Sign and verify data with ED25519 
-- **Encryption**: Encrypt and decrypt data with XChaCha20-Poly1305
-- **Authentication**: Pack and unpack authentication credentials
-- **Plugin System**: Extensible architecture for different cryptographic algorithms
-- **CLI Tool**: Command-line interface for key generation
-- **Multiple Export Formats**: Support for various key export formats
-
-## Supported Algorithms
-
-- **ED25519**: Digital signatures and key derivation
-- **XChaCha20-Poly1305**: Symmetric encryption and decryption
+- Generate ED25519 key pairs or import from existing public/private keys
+- Sign and verify arbitrary payloads
+- Pack/unpack `AuthCredentials` objects with cryptographic signatures
+- Address derivation from public keys
 
 ## Installation
 
 ```bash
-npm install @owlmeans/basic-keys
+bun add @owlmeans/basic-keys
 ```
 
-## Available Exports
+## Usage
 
-The package provides three main export paths:
+Generate a key pair and sign data:
 
 ```typescript
-// Main exports - core functionality
-import { makeKeyPairModel, KeyType, fromPubKey, matchAddress, inputToKeyPair, packAuthCredentials, unpackAuthCredentials } from '@owlmeans/basic-keys'
-
-// Plugin exports - cryptographic algorithm implementations  
-import { plugins, ed25519Plugin, xChahaPlugin, KeyPlugin } from '@owlmeans/basic-keys/plugins'
+import { makeKeyPairModel } from '@owlmeans/basic-keys'
 
-// Utility exports - low-level helper functions
-import { prepareData, prepareKey, toAddress, assertType } from '@owlmeans/basic-keys/utils'
+const pair = makeKeyPairModel()             // generates a new ED25519 keypair
+const exported = pair.export()              // string representation for storage
+const signature = await pair.sign(payload)  // sign arbitrary data
+const valid = await pair.verify(payload, signature)
+const address = pair.exportAddress()        // derive address from public key
 ```
 
-## Quick Start
+Load from an existing public key:
 
 ```typescript
-import { makeKeyPairModel, KeyType } from '@owlmeans/basic-keys'
+import { fromPubKey, matchAddress } from '@owlmeans/basic-keys'
 
-// Generate a new ED25519 key pair
-const keyPair = makeKeyPairModel()
-
-// Sign data
-const signature = await keyPair.sign("Hello, World!")
-
-// Verify signature
-const isValid = await keyPair.verify("Hello, World!", signature)
-
-// Export keys
-const privateKey = keyPair.export()          // "ed25519:base64privatekey"
-const publicKey = keyPair.exportPublic()     // "ed25519:base64publickey"
-const address = keyPair.exportAddress()      // "ed25519:base58address"
+const model = fromPubKey('ed25519:ABC123...')
+const isMatch = matchAddress(knownAddress, publicKeyStr)
 ```
 
-## API Reference
-
-### Core Types
-
-#### KeyPair
-
-Represents a cryptographic key pair with metadata.
+Pack authentication credentials for a request:
 
 ```typescript
-interface KeyPair {
-  privateKey: string  // Base64-encoded private key
-  publicKey: string   // Base64-encoded public key
-  address: string     // Algorithm-specific address
-  type: string        // Algorithm type (e.g., "ed25519", "xchacha")
-}
-```
-
-#### KeyPairModel
+import { packAuthCredentials, unpackAuthCredentials } from '@owlmeans/basic-keys'
 
-A model object that wraps a KeyPair with cryptographic operations.
-
-```typescript
-interface KeyPairModel {
-  keyPair?: KeyPair
-  sign: (data: unknown) => Promise<string>
-  verify: (data: unknown, signature: string) => Promise<boolean>
-  export: () => string
-  exportPublic: () => string
-  exportAddress: () => string
-  encrypt: (data: unknown) => Promise<string>
-  decrypt: (data: unknown) => Promise<string>
-  dcrpt: (data: unknown) => Promise<Uint8Array>
-}
+const signed = await packAuthCredentials(authObj, extraData, keyPairModel)
+const { isValid, extras } = await unpackAuthCredentials(signed, keyPairModel)
 ```
 
-### Key Functions
+## API
 
-#### makeKeyPairModel(input?)
+### `makeKeyPairModel(input?): KeyPairModel`
 
-Creates a KeyPairModel instance.
+Creates a `KeyPairModel` from an existing `KeyPair` object, encoded private key string, or algorithm type string. Generates a new ED25519 key pair when called with no arguments.
 
-```typescript
-function makeKeyPairModel(input?: KeyPair | string): KeyPairModel
-```
+### `fromPubKey(pubKey, type?): KeyPairModel`
 
-**Parameters:**
-- `input` (optional): 
-  - `KeyPair` object
-  - Algorithm type string (e.g., "ed25519", "xchacha")
-  - Encoded private key string (e.g., "ed25519:base64key")
+Creates a verify-only `KeyPairModel` from a public key string. Supports `"type:key"` format.
 
-**Returns:** `KeyPairModel` instance
+### `matchAddress(address, pubKey): boolean`
 
-**Examples:**
+Returns true if `address` was derived from `pubKey`.
 
-```typescript
-// Generate new ED25519 key pair
-const keyPair1 = makeKeyPairModel()
+### `packAuthCredentials(auth, extra, signer): Promise<AuthCredentials>`
 
-// Generate new XChaCha20 key pair
-const keyPair2 = makeKeyPairModel(KeyType.XCHACHA)
+Signs auth credentials, optionally embedding extra data in the credential field.
 
-// Import from private key
-const keyPair3 = makeKeyPairModel("ed25519:abcd1234...")
-
-// Import from KeyPair object
-const keyPair4 = makeKeyPairModel({
-  privateKey: "abcd1234...",
-  publicKey: "efgh5678...",
-  address: "ijkl9012...",
-  type: "ed25519"
-})
-```
+### `unpackAuthCredentials(auth, verifier?): Promise<UnpackedAuthCredentials>`
 
-#### fromPubKey(pubKey, type?)
+Extracts and optionally verifies signed auth credentials. Returns `isValid` boolean when a verifier is provided.
 
-Creates a KeyPairModel from a public key (verification/encryption only).
+### `KeyType`
 
 ```typescript
-function fromPubKey(pubKey: string, type?: string): KeyPairModel
+enum KeyType { ED25519 = 'ed25519', XCHACHA = 'xchacha' }
 ```
 
-**Parameters:**
-- `pubKey`: Public key string (with or without type prefix)
-- `type` (optional): Algorithm type if not included in pubKey
-
-**Returns:** `KeyPairModel` instance (without private key operations)
-
-**Examples:**
-
-```typescript
-// With type prefix
-const publicKeyModel = fromPubKey("ed25519:abcd1234...")
-
-// Without type prefix (defaults to ED25519)
-const publicKeyModel2 = fromPubKey("abcd1234...")
-
-// Explicit type
-const publicKeyModel3 = fromPubKey("abcd1234...", KeyType.ED25519)
-```
-
-#### matchAddress(address, pubKey)
-
-Verifies if a public key matches an address.
-
-```typescript
-function matchAddress(address: string, pubKey: string): boolean
-```
-
-**Parameters:**
-- `address`: Address string to verify
-- `pubKey`: Public key string
-
-**Returns:** `boolean` - true if the public key matches the address
-
-#### inputToKeyPair(input?)
-
-Converts various input formats to a KeyPair object.
-
-```typescript
-function inputToKeyPair(input?: KeyPair | string): KeyPair
-```
-
-**Parameters:**
-- `input` (optional): 
-  - `KeyPair` object
-  - Algorithm type string (generates new key)
-  - Encoded private key string (e.g., "ed25519:base64key")
-
-**Returns:** `KeyPair` object
-
-**Examples:**
-
-```typescript
-// Generate new ED25519 key pair
-const keyPair1 = inputToKeyPair()
-
-// Generate new XChaCha20 key pair
-const keyPair2 = inputToKeyPair(KeyType.XCHACHA)
-
-// Import from private key
-const keyPair3 = inputToKeyPair("ed25519:abcd1234...")
-```
-
-### Authentication Helpers
-
-#### packAuthCredentials(auth, extra, signer)
-
-Packs authentication credentials with a signature.
-
-```typescript
-function packAuthCredentials<T>(
-  auth: UnsignedAuthCredentials,
-  extra: T,
-  signer: KeyPairModel | PayloadSigner
-): Promise<AuthCredentials>
-```
-
-**Parameters:**
-- `auth`: Unsigned authentication credentials
-- `extra`: Additional data to include in credentials
-- `signer`: KeyPairModel or custom signing function
-
-**Returns:** Promise resolving to signed `AuthCredentials`
-
-#### unpackAuthCredentials(auth, verifier?)
-
-Unpacks and optionally verifies authentication credentials.
-
-```typescript
-function unpackAuthCredentials<T>(
-  auth: AuthCredentials,
-  verifier?: KeyPairModel | PayloadVerifier
-): Promise<UnpackedAuthCredentials<T>>
-```
-
-**Parameters:**
-- `auth`: Signed authentication credentials
-- `verifier` (optional): KeyPairModel or custom verification function
-
-**Returns:** Promise resolving to `UnpackedAuthCredentials<T>`
-
-### Constants
-
-#### KeyType
-
-Enumeration of supported cryptographic algorithm types.
-
-```typescript
-enum KeyType {
-  ED25519 = 'ed25519',
-  XCHACHA = 'xchacha'
-}
-```
-
-### Utility Functions
-
-#### toAddress(publicKey)
-
-Converts a public key to its corresponding address.
-
-```typescript
-function toAddress(publicKey: Uint8Array): Uint8Array
-```
-
-**Parameters:**
-- `publicKey`: Public key as Uint8Array
-
-**Returns:** `Uint8Array` - Address bytes (last 20 bytes of Keccak-256 hash)
-
-#### prepareData(data)
-
-Converts various data types to Uint8Array for cryptographic operations.
-
-```typescript
-function prepareData(data: unknown): Uint8Array
-```
-
-#### prepareKey(key)
-
-Converts a base64-encoded key string to Uint8Array.
-
-```typescript
-function prepareKey(key: string): Uint8Array
-```
-
-#### assertType(type?)
-
-Validates that a cryptographic algorithm type is supported.
-
-```typescript
-function assertType(type?: string): void
-```
-
-## Plugin System
-
-The library uses a plugin architecture to support different cryptographic algorithms. Each plugin implements the `KeyPlugin` interface:
-
-```typescript
-interface KeyPlugin {
-  type: string
-  random: () => Uint8Array
-  fromSeed?: (seed: Uint8Array) => Uint8Array
-  derive?: (pk: Uint8Array, path: string) => Uint8Array
-  sign: (data: Uint8Array, pk: Uint8Array) => Uint8Array
-  verify: (data: Uint8Array, signature: Uint8Array, pub: Uint8Array) => boolean
-  toPublic: (pk: Uint8Array) => Uint8Array
-  toAdress: (pub: Uint8Array) => string
-  encrypt: (data: Uint8Array, pk: Uint8Array) => Uint8Array
-  decrypt: (data: Uint8Array, pk: Uint8Array) => Uint8Array
-}
-```
-
-### Built-in Plugins
-
-#### ED25519 Plugin
-
-- **Type**: `ed25519`
-- **Capabilities**: Digital signatures, key derivation
-- **Address Format**: Base58-encoded Keccak-256 hash
-- **Encryption**: Not supported (throws error)
-
-#### XChaCha20-Poly1305 Plugin
-
-- **Type**: `xchacha`
-- **Capabilities**: Symmetric encryption and decryption
-- **Address Format**: "no-address" (not applicable)
-- **Signing**: Not supported (throws error)
-
-### Using Plugins
-
-```typescript
-import { plugins } from '@owlmeans/basic-keys/plugins'
-// Or import individual plugins
-import { ed25519Plugin, xChahaPlugin } from '@owlmeans/basic-keys/plugins'
-
-// Access plugin directly
-const ed25519Plugin = plugins['ed25519']
-
-// Generate random private key
-const privateKey = ed25519Plugin.random()
-
-// Convert to public key
-const publicKey = ed25519Plugin.toPublic(privateKey)
-
-// Sign data
-const signature = ed25519Plugin.sign(data, privateKey)
-
-// Verify signature
-const isValid = ed25519Plugin.verify(data, signature, publicKey)
-```
-
-## CLI Tool
-
-The package includes a command-line tool for key generation:
-
-```bash
-# Generate keys
-npx owlkeys
-
-# Or if installed globally
-owlkeys
-```
-
-The CLI tool generates and displays:
-- ED25519 private key export
-- ED25519 public key export
-- ED25519 address (DID format)
-- XChaCha20 key export
-
-## Advanced Usage
-
-### Custom Signing and Verification
-
-```typescript
-import type { PayloadSigner, PayloadVerifier } from '@owlmeans/basic-keys'
-
-// Custom signer function
-const customSigner: PayloadSigner = async (payload) => {
-  // Custom signing logic
-  return signature
-}
-
-// Custom verifier function
-const customVerifier: PayloadVerifier = async (payload, signature) => {
-  // Custom verification logic
-  return isValid
-}
-
-// Use with authentication helpers
-const credentials = await packAuthCredentials(auth, extra, customSigner)
-const unpacked = await unpackAuthCredentials(credentials, customVerifier)
-```
-
-### Working with Raw Data
-
-```typescript
-import { prepareData, prepareKey, toAddress, assertType } from '@owlmeans/basic-keys/utils'
-
-// Prepare various data types for cryptographic operations
-const data1 = prepareData("string data")           // UTF-8 encoded
-const data2 = prepareData({ key: "value" })        // JSON canonicalized
-const data3 = prepareData(new Uint8Array([1, 2]))  // As-is
-
-// Prepare keys
-const keyBytes = prepareKey("base64KeyString")
-
-// Generate address from public key
-const address = toAddress(publicKeyBytes)
-
-// Assert algorithm type is supported
-assertType("ed25519") // No error
-assertType("unknown") // Throws error
-```
-
-### Encryption and Decryption
-
-```typescript
-// For encryption, use XChaCha20 keys
-const encryptionKey = makeKeyPairModel(KeyType.XCHACHA)
-
-// Encrypt data
-const encrypted = await encryptionKey.encrypt("sensitive data")
-
-// Decrypt data  
-const decrypted = await encryptionKey.decrypt(encrypted)
-
-// Decrypt to raw bytes
-const rawBytes = await encryptionKey.dcrpt(encrypted)
-```
-
-## Error Handling
-
-The library throws descriptive errors for various failure conditions:
-
-- `basic.keys:string-type-or-key` - Invalid key string format
-- `basic.keys:missing-keypair` - KeyPair not available
-- `basic.keys:missing-pk` - Private key not available
-- `basic.keys:sign-data-type` - Invalid data type for signing
-- `basic.keys:unknown-type` - Unsupported algorithm type
-- `ed25519:encryption-support` - ED25519 doesn't support encryption
-- `xchacha:signing` - XChaCha20 doesn't support signing
-- `xchacha:verification` - XChaCha20 doesn't support verification
-
-## Integration with OwlMeans Common
-
-This package is designed to integrate seamlessly with other OwlMeans Common libraries:
-
-- **@owlmeans/auth**: Authentication and authorization
-- **@owlmeans/client-auth**: Client-side authentication
-- **@owlmeans/server-auth**: Server-side authentication
-
-## TypeScript Support
-
-The library is written in TypeScript and provides comprehensive type definitions. All exports are properly typed for optimal developer experience.
-
-## Security Considerations
-
-- Private keys are stored as base64-encoded strings
-- All cryptographic operations use well-established libraries (@noble/curves, @noble/ciphers)
-- Data is canonicalized before signing to prevent signature malleability
-- Key generation uses cryptographically secure random number generation
-
-## Contributing
-
-This package is part of the OwlMeans Common ecosystem. Please refer to the main repository for contribution guidelines.
-
-## License
+## Related Packages
 
-See the LICENSE file in the repository root for license information.
+- [`@owlmeans/basic-envelope`](../basic-envelope) — uses `KeyPairModel` for envelope signing
+- [`@owlmeans/auth`](../auth) — `AuthCredentials` type consumed by this package
+- [`@owlmeans/did`](../did) — DID documents built on top of key pairs

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/basic-keys",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 48 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "bin": {
     "owlkeys": "./build/bin.js"
@@ -38,15 +39,18 @@
     }
   },
   "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/test-auth": "^0.1.4",
+    "@types/bun": "^1.3.0",
     "nodemon": "^3.1.11",
     "npm-check": "^6.0.1",
-    "typescript": "^5.8.3"
+    "typescript": "^6.0.2"
   },
   "dependencies": {
     "@noble/ciphers": "^1.2.1",
     "@noble/curves": "^1.6.0",
     "@noble/hashes": "^1.5.0",
-    "@owlmeans/auth": "^0.1.2",
+    "@owlmeans/auth": "^0.1.4",
     "@scure/base": "^1.1.9",
     "canonicalize": "^2.0.0"
   },

package/tests/auth.spec.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from 'bun:test'
+import { packAuthCredentials, unpackAuthCredentials } from '@owlmeans/basic-keys'
+import { AuthRole, AuthenticationType } from '@owlmeans/auth'
+import type { AuthCredentials } from '@owlmeans/auth'
+import { fixtureKey } from './context.js'
+
+const baseCreds = (): Omit<AuthCredentials, 'credential'> => ({
+  type: AuthenticationType.BasicEd25519,
+  role: AuthRole.User,
+  userId: 'user-1',
+  challenge: 'challenge-string',
+  scopes: ['*'],
+})
+
+describe('@owlmeans/basic-keys — packAuthCredentials round-trip', () => {
+  test('signs and verifies credentials with extras attached', async () => {
+    const key = fixtureKey()
+    const signed = await packAuthCredentials(baseCreds(), { nonce: 'n-1' }, key)
+    const result = await unpackAuthCredentials<{ nonce: string }>(signed, key)
+    expect(result.isValid).toBe(true)
+    expect(result.extras?.nonce).toBe('n-1')
+  })
+
+  test('verification fails for a different keypair', async () => {
+    const signing = fixtureKey('alice')
+    const other = fixtureKey('bob')
+    const signed = await packAuthCredentials(baseCreds(), { nonce: 'n-1' }, signing)
+    const result = await unpackAuthCredentials(signed, other)
+    expect(result.isValid).toBe(false)
+  })
+})

package/tests/context.ts

@@ -0,0 +1,10 @@
+import { makeFixtureKeyPair } from '@owlmeans/test-auth'
+import type { KeyPairModel } from '@owlmeans/basic-keys'
+
+/**
+ * Per-suite fixture: deterministic Ed25519 keypair from `@owlmeans/test-auth`.
+ * Category-B packages reuse the same fixture across specs so signatures
+ * stay stable run-to-run.
+ */
+export const fixtureKey = (seed: string = 'basic-keys-pilot'): KeyPairModel =>
+  makeFixtureKeyPair(seed)

package/tests/keys.spec.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from 'bun:test'
+import { fromPubKey, makeKeyPairModel, matchAddress } from '@owlmeans/basic-keys'
+import { fixtureKey } from './context.js'
+
+describe('@owlmeans/basic-keys — KeyPairModel sign/verify', () => {
+  // viable-agent/packages/template/packages/backend/src/owlmeans.ts:63 builds a key
+  // via `makeKeyPairModel(process.env.TRUSTED_PK)` and signs/verifies through it.
+  test('round-trips a signature with the same keypair', async () => {
+    const key = fixtureKey('keys-spec')
+    const sig = await key.sign({ payload: 'hello' })
+    expect(await key.verify({ payload: 'hello' }, sig)).toBe(true)
+  })
+
+  test('verification fails when the payload is tampered', async () => {
+    const key = fixtureKey('keys-spec')
+    const sig = await key.sign({ payload: 'hello' })
+    expect(await key.verify({ payload: 'goodbye' }, sig)).toBe(false)
+  })
+})
+
+describe('@owlmeans/basic-keys — public-key-only verification (fromPubKey)', () => {
+  // Mirrors viable/sources/backend/src/config.ts which loads peer public keys
+  // (`master-pub`, `auth-pub`, etc.) into trusted records — the reading service
+  // never holds the private key but must still verify those peers' signatures.
+  test('fromPubKey produces a model that verifies signatures from the original key', async () => {
+    const signing = fixtureKey('peer-keys-spec')
+    const sig = await signing.sign({ event: 'check' })
+
+    const verifying = fromPubKey(signing.exportPublic())
+    expect(await verifying.verify({ event: 'check' }, sig)).toBe(true)
+  })
+
+  test('matchAddress agrees with exportAddress() on the same keypair', () => {
+    const key = fixtureKey('addr-spec')
+    expect(matchAddress(key.exportAddress(), key.exportPublic())).toBe(true)
+  })
+
+  test('export() round-trips into a new model that produces the same public key', async () => {
+    const key = fixtureKey('export-spec')
+    const reimported = makeKeyPairModel(key.export())
+    expect(reimported.exportPublic()).toBe(key.exportPublic())
+    expect(reimported.exportAddress()).toBe(key.exportAddress())
+  })
+})

package/tsconfig.json

@@ -1,14 +1,10 @@
 {
   "extends": [
-    "../tsconfig.default.json",
+    "@owlmeans/dep-config/tsconfig.base.json"
   ],
   "compilerOptions": {
-    "rootDir": "./src/", /* Specify the root folder within your source files. */
-    "outDir": "./build/", /* Specify an output folder for all emitted files. */
+    "rootDir": "./src/",
+    "outDir": "./build/"
   },
-  "exclude": [
-    "./dist/**/*",
-    "./build/**/*",
-    "./*.ts"
-  ]
-}
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
+}