@owlmeans/basic-envelope 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,616 @@
+# @owlmeans/basic-envelope
+
+A lightweight cryptographic message envelope library for OwlMeans Common applications. This package provides secure message wrapping, signing, and verification capabilities using Ed25519 cryptographic signatures, designed as an alternative to JWT/JWE tokens with enhanced security and simplicity.
+
+## Overview
+
+The `@owlmeans/basic-envelope` package enables secure message transmission and storage by providing:
+
+- **Message Envelopes**: Lightweight containers for messages with built-in expiration and type identification
+- **Cryptographic Signing**: Ed25519 signature support for message authentication and integrity
+- **Flexible Serialization**: Multiple output formats including wrapped strings and tokenized representations
+- **TTL Support**: Time-to-live functionality for automatic message expiration
+- **Type Safety**: Full TypeScript support with generic message types
+
+This package is particularly useful for creating secure authentication tokens, signed API requests, and encrypted inter-service communication.
+
+## Installation
+
+```bash
+npm install @owlmeans/basic-envelope
+```
+
+## Core Concepts
+
+### Envelope Structure
+
+An envelope is a container that wraps a message with metadata including:
+- **Type identifier**: Categorizes the message purpose
+- **Message payload**: The actual data (string or object)
+- **Signature**: Optional cryptographic signature for verification
+- **Timestamp**: Creation time for ordering and TTL calculations
+- **TTL**: Time-to-live for automatic expiration
+
+### Envelope Kinds
+
+The package supports different serialization formats:
+- **Wrap**: Base64-encoded JSON representation
+- **Token**: Compact tokenized format for transmission
+
+## API Reference
+
+### Factory Functions
+
+The package uses factory functions for object creation following OwlMeans Common conventions:
+
+#### `makeEnvelopeModel<T>(type, kind?): EnvelopeModel<T>`
+
+Creates an envelope model for wrapping and managing messages with cryptographic capabilities.
+
+```typescript
+import { makeEnvelopeModel, EnvelopeKind } from '@owlmeans/basic-envelope'
+
+// Create a new envelope
+const envelope = makeEnvelopeModel<UserData>('user-session')
+
+// Create from existing wrapped envelope
+const wrappedEnvelope = makeEnvelopeModel('eyJ0IjoiZXhhbXBsZSIsLi4u', EnvelopeKind.Wrap)
+
+// Create from tokenized envelope
+const tokenizedEnvelope = makeEnvelopeModel('example:msg:signature', EnvelopeKind.Token)
+```
+
+**Parameters:**
+- `type`: string - Type identifier for new envelopes, or serialized envelope for reconstruction
+- `kind`: EnvelopeKind (optional) - Specifies format when reconstructing from serialized data
+
+**Returns:** EnvelopeModel<T> instance with methods for message management and cryptographic operations
+
+**Generic Type Parameter:**
+- `T`: Type of the message payload (defaults to string)
+
+### Core Interfaces
+
+#### `Envelope`
+Core envelope structure containing message and metadata.
+
+```typescript
+interface Envelope {
+  t: string           // Type identifier for categorizing messages
+  msg: string         // Base64-encoded message content
+  sig?: string        // Optional cryptographic signature
+  dt: number          // Creation timestamp (milliseconds)
+  ttl: number | null  // Time-to-live in milliseconds (null = no expiration)
+}
+```
+
+**Properties:**
+- `t`: Message type identifier used for categorization and routing  
+- `msg`: Base64-encoded message payload (automatically encoded by envelope methods)
+- `sig`: Optional Ed25519 signature for message authentication and integrity verification
+- `dt`: Creation timestamp used for ordering and TTL calculations (milliseconds since epoch)
+- `ttl`: Time-to-live for automatic expiration, null indicates no expiration
+
+#### `EnvelopeModel<T>`
+Factory-created envelope manager providing comprehensive message operations and cryptographic functions.
+
+```typescript
+interface EnvelopeModel<T extends {} | string = string> {
+  envelope: Envelope
+  
+  // Message management methods
+  send<M extends T>(msg: M, ttl?: number | null): EnvelopeModel
+  message<M extends T>(preserve?: boolean): M
+  type(): string
+  
+  // Serialization methods
+  wrap(): string
+  tokenize(): string
+  
+  // Cryptographic methods
+  sign(key: KeyPairModel, kind?: EnvelopeKind): Promise<string>
+  verify(key: KeyPairModel): Promise<boolean>
+}
+```
+
+### EnvelopeModel Methods Reference
+
+#### Message Management Methods
+
+**`send<M extends T>(msg: M, ttl?: number | null): EnvelopeModel`**
+
+Sets the message content and optional TTL, with automatic encoding based on message type.
+
+```typescript
+// Send a string message
+envelope.send('Hello, World!')
+
+// Send an object with 1-hour TTL
+envelope.send({ userId: '123', action: 'login' }, 3600000)
+
+// Send with no expiration
+envelope.send(messageData, null)
+```
+
+- **Purpose**: Encodes and stores message data in the envelope with optional expiration
+- **Behavior**: 
+  - String messages are stored directly
+  - Objects are JSON-serialized then Base64-encoded automatically
+  - Updates TTL if provided, maintains existing TTL if not specified
+- **Parameters**:
+  - `msg: M`: Message payload extending type T
+  - `ttl?: number | null`: Time-to-live in milliseconds, null for no expiration
+- **Returns**: The same EnvelopeModel instance for method chaining
+- **Throws**: No exceptions - handles all message types gracefully
+
+**`message<M extends T>(preserve?: boolean): M`**
+
+Retrieves and decodes the message content from the envelope.
+
+```typescript
+// Get decoded object message
+const userData = envelope.message<UserData>()
+
+// Get raw string message without decoding
+const rawMessage = envelope.message<string>(true)
+```
+
+- **Purpose**: Extracts the original message from the envelope with configurable decoding
+- **Behavior**:
+  - Default (`preserve` false): Attempts JSON parsing followed by Base64 decoding
+  - Preserve mode (`preserve` true): Returns raw message string without processing
+  - Gracefully falls back to string if JSON parsing fails
+- **Parameters**:
+  - `preserve?: boolean`: If true, returns raw message without decoding
+- **Returns**: Decoded message of type M
+- **Error Handling**: Silent fallback to string type on decode errors
+
+**`type(): string`**
+
+Returns the type identifier of the envelope for message categorization.
+
+```typescript
+const messageType = envelope.type() // e.g., 'user-session'
+```
+
+- **Purpose**: Provides access to the envelope's type identifier
+- **Returns**: String identifier used for message routing and categorization
+- **Use Cases**: Message dispatching, route determination, debugging
+
+#### Serialization Methods
+
+**`wrap(): string`**
+
+Serializes the envelope to a Base64-encoded JSON string for secure transmission.
+
+```typescript
+const wrappedEnvelope = envelope.wrap()
+// Returns: "eyJ0IjoiZXhhbXBsZSIsIm1zZyI6IkhlbGxvIiwiZHQiOjE2Mzk..."
+
+// Can be reconstructed later
+const restored = makeEnvelopeModel(wrappedEnvelope, EnvelopeKind.Wrap)
+```
+
+- **Purpose**: Creates a wrapped representation suitable for storage or secure transmission
+- **Behavior**: JSON-serializes the complete envelope then Base64-encodes the result
+- **Returns**: Base64-encoded envelope string
+- **Use Cases**: Database storage, HTTP headers, secure URL parameters
+- **Security**: Preserves all envelope data including signatures
+
+**`tokenize(): string`**
+
+Creates a compact token format for efficient transmission and parsing.
+
+```typescript
+const token = envelope.tokenize()
+// Returns: "user-session:SGVsbG8gV29ybGQ:signature_if_present"
+
+// Reconstruct from token
+const restored = makeEnvelopeModel(token, EnvelopeKind.Token)
+```
+
+- **Purpose**: Creates a human-readable, compact token representation
+- **Behavior**: Combines type, message, and signature with colon separators
+- **Format**: `type:base64_message:signature` (signature omitted if not present)
+- **Returns**: Compact token string
+- **Use Cases**: API tokens, authentication headers, URL fragments, debugging
+- **Advantages**: Easily parseable, more compact than wrapped format
+
+#### Cryptographic Methods
+
+**`sign(key: KeyPairModel, kind?: EnvelopeKind): Promise<string>`**
+
+Signs the envelope with Ed25519 cryptographic signature for authentication and integrity.
+
+```typescript
+import { makeKeyPairModel } from '@owlmeans/basic-keys'
+
+const keyPair = makeKeyPairModel()
+await keyPair.generate()
+
+// Sign and get signature only
+const signature = await envelope.sign(keyPair)
+
+// Sign and get wrapped envelope
+const signedWrapped = await envelope.sign(keyPair, EnvelopeKind.Wrap)
+
+// Sign and get tokenized envelope  
+const signedToken = await envelope.sign(keyPair, EnvelopeKind.Token)
+```
+
+- **Purpose**: Provides cryptographic authentication and tamper-detection
+- **Behavior**:
+  - Creates Ed25519 signature of envelope data (excluding existing signature field)
+  - Stores signature in `envelope.sig` property for future verification
+  - Returns formatted output based on `kind` parameter
+- **Parameters**:
+  - `key: KeyPairModel`: Ed25519 key pair instance for signing
+  - `kind?: EnvelopeKind`: Output format - Wrap, Token, or raw signature (default)
+- **Returns**: Promise resolving to signature string or formatted envelope
+- **Security**: Uses industry-standard Ed25519 signatures for cryptographic authenticity
+- **Error Handling**: Propagates key pair errors (e.g., missing private key)
+
+**`verify(key: KeyPairModel): Promise<boolean>`**
+
+Verifies envelope signature and validates TTL expiration for complete authenticity check.
+
+```typescript
+// Verify signature and TTL
+const isValid = await envelope.verify(keyPair)
+
+if (isValid) {
+  console.log('Envelope is authentic and not expired')
+  // Safe to process message
+} else {
+  console.log('Envelope is invalid or expired - reject')
+  // Handle invalid envelope
+}
+```
+
+- **Purpose**: Validates both cryptographic authenticity and temporal freshness
+- **Behavior**:
+  - Returns `false` immediately if no signature is present
+  - Checks TTL expiration if TTL is set (compares `dt + ttl` with current time)
+  - Verifies Ed25519 signature against envelope data (excluding signature field)
+  - All conditions must pass for `true` result
+- **Parameters**:
+  - `key: KeyPairModel`: Key pair instance with public key for verification
+- **Returns**: Promise resolving to boolean validation result
+- **Security**: Combines cryptographic verification with temporal validation
+- **Use Cases**: Authentication token validation, message integrity checking
+
+### Factory Functions
+
+#### `makeEnvelopeModel<T>(type: string, kind?: EnvelopeKind): EnvelopeModel<T>`
+
+Creates a new envelope model instance.
+
+**Parameters:**
+- `type`: Type identifier for the envelope
+- `kind`: Optional kind for deserializing existing envelopes
+
+**Returns:** EnvelopeModel instance
+
+**Example:**
+```typescript
+import { makeEnvelopeModel } from '@owlmeans/basic-envelope'
+
+// Create new envelope
+const envelope = makeEnvelopeModel<UserData>('user-profile')
+
+// Send message
+envelope.send({ userId: '123', name: 'John' }, 300000) // 5 minutes TTL
+
+// Get wrapped representation
+const wrapped = envelope.wrap()
+```
+
+### Constants and Enums
+
+#### `EnvelopeKind`
+Enumeration defining available envelope serialization formats.
+
+```typescript
+enum EnvelopeKind {
+  Wrap = 'wrap',      // Base64-encoded JSON format - secure, complete data preservation
+  Token = 'token'     // Compact colon-separated format - human-readable, efficient
+}
+```
+
+**Usage Guidelines:**
+- Use `Wrap` for secure storage, HTTP headers, or when preserving all metadata is critical
+- Use `Token` for API tokens, URLs, or when human readability and compactness are important
+
+#### `DEFAULT_TTL`
+Default time-to-live value applied to new envelopes.
+
+```typescript
+const DEFAULT_TTL = 5 * 60 * 1000  // 5 minutes in milliseconds
+```
+
+**Behavior**: Applied automatically when creating new envelopes unless explicitly overridden
+
+## Error Handling
+
+The basic-envelope package follows OwlMeans Common error handling patterns and integrates with cryptographic operations that may throw errors.
+
+### Common Error Scenarios
+
+#### Key-Related Errors
+```typescript
+import { makeKeyPairModel } from '@owlmeans/basic-keys'
+
+try {
+  const keyPair = makeKeyPairModel()
+  // Error: Attempting to sign without generating keys
+  await envelope.sign(keyPair)
+} catch (error) {
+  console.error('Key operation failed:', error.message)
+  // Handle missing private key or key generation errors
+}
+```
+
+#### TTL Validation Errors
+```typescript
+// Expired envelope verification
+const expiredEnvelope = makeEnvelopeModel('expired-message')
+expiredEnvelope.send('data', 1) // 1ms TTL
+await new Promise(resolve => setTimeout(resolve, 10)) // Wait for expiration
+
+const isValid = await expiredEnvelope.verify(keyPair)
+// Returns false - envelope has expired
+```
+
+#### Malformed Data Errors
+```typescript
+try {
+  // Invalid wrapped data
+  const malformed = makeEnvelopeModel('invalid-base64', EnvelopeKind.Wrap)
+} catch (error) {
+  console.error('Failed to parse envelope:', error.message)
+}
+```
+
+### Error Types and Handling
+
+The package gracefully handles various error conditions:
+
+1. **Silent Fallbacks**: Message decoding errors fall back to string representation
+2. **Validation Failures**: Verification methods return `false` rather than throwing
+3. **Key Errors**: Cryptographic errors are propagated from the key pair implementation
+4. **Parse Errors**: Malformed envelope data results in constructor exceptions
+
+## Advanced Usage Examples
+
+### Authentication Token System
+```typescript
+import { makeEnvelopeModel, EnvelopeKind } from '@owlmeans/basic-envelope'
+import { makeKeyPairModel } from '@owlmeans/basic-keys'
+
+// Setup authentication system
+const authKeys = makeKeyPairModel()
+await authKeys.generate()
+
+// Create authentication token
+const sessionEnvelope = makeEnvelopeModel<SessionData>('user-session')
+const sessionData = {
+  userId: 'user123',
+  permissions: ['read', 'write'],
+  loginTime: Date.now()
+}
+
+// Sign and create token with 1-hour expiration
+const authToken = await sessionEnvelope
+  .send(sessionData, 3600000)
+  .sign(authKeys, EnvelopeKind.Token)
+
+console.log('Auth token:', authToken)
+// user-session:eyJ1c2VySWQ...base64...:signature
+
+// Later: verify token
+const receivedEnvelope = makeEnvelopeModel(authToken, EnvelopeKind.Token)
+const isValidToken = await receivedEnvelope.verify(authKeys)
+
+if (isValidToken) {
+  const session = receivedEnvelope.message<SessionData>()
+  console.log('Valid session for user:', session.userId)
+} else {
+  console.log('Invalid or expired token')
+}
+```
+
+### Secure Message Transmission
+```typescript
+// Sender side
+const messageEnvelope = makeEnvelopeModel<ApiRequest>('api-request')
+const apiRequest = {
+  method: 'POST',
+  endpoint: '/users',
+  data: { name: 'John Doe', email: 'john@example.com' }
+}
+
+// Create signed message with 30-second TTL
+const signedMessage = await messageEnvelope
+  .send(apiRequest, 30000)
+  .sign(senderKeys, EnvelopeKind.Wrap)
+
+// Transmit wrapped message
+await sendToServer(signedMessage)
+
+// Receiver side
+const receivedEnvelope = makeEnvelopeModel(signedMessage, EnvelopeKind.Wrap)
+
+// Verify authenticity and freshness
+if (await receivedEnvelope.verify(senderKeys)) {
+  const request = receivedEnvelope.message<ApiRequest>()
+  // Process authenticated API request
+  console.log('Processing request:', request.method, request.endpoint)
+} else {
+  // Reject unauthenticated or expired request
+  throw new Error('Invalid request signature or expired')
+}
+```
+
+### Multi-Format Message Exchange
+```typescript
+// Create message once
+const dataEnvelope = makeEnvelopeModel<UserProfile>('user-profile')
+dataEnvelope.send({
+  id: '123',
+  name: 'Alice Smith',
+  preferences: { theme: 'dark', notifications: true }
+})
+
+// Generate multiple formats for different use cases
+const forDatabase = dataEnvelope.wrap()        // Secure storage
+const forUrl = dataEnvelope.tokenize()         // URL transmission
+const forHeaders = await dataEnvelope.sign(keys, EnvelopeKind.Wrap) // Signed secure
+
+// Each format can be reconstructed to the same data
+const fromDb = makeEnvelopeModel(forDatabase, EnvelopeKind.Wrap)
+const fromUrl = makeEnvelopeModel(forUrl, EnvelopeKind.Token)
+const fromHeaders = makeEnvelopeModel(forHeaders, EnvelopeKind.Wrap)
+
+// All contain the same user profile data
+console.log('Same data:', 
+  fromDb.message<UserProfile>().id === 
+  fromUrl.message<UserProfile>().id &&
+  fromHeaders.message<UserProfile>().id
+)
+```
+
+## Integration Patterns
+
+### Express.js Middleware
+```typescript
+import express from 'express'
+import { makeEnvelopeModel, EnvelopeKind } from '@owlmeans/basic-envelope'
+
+// Authentication middleware using envelope tokens
+const authenticateToken = (serverKeys) => async (req, res, next) => {
+  const authHeader = req.headers.authorization
+  if (!authHeader?.startsWith('Bearer ')) {
+    return res.status(401).json({ error: 'Missing auth token' })
+  }
+
+  try {
+    const token = authHeader.substring(7)
+    const envelope = makeEnvelopeModel(token, EnvelopeKind.Token)
+    
+    if (await envelope.verify(serverKeys)) {
+      req.user = envelope.message()
+      next()
+    } else {
+      res.status(401).json({ error: 'Invalid or expired token' })
+    }
+  } catch (error) {
+    res.status(400).json({ error: 'Malformed token' })
+  }
+}
+
+const app = express()
+app.use('/api', authenticateToken(serverKeys))
+```
+
+### React Hook Integration
+```typescript
+import { useState, useEffect } from 'react'
+import { makeEnvelopeModel, EnvelopeKind } from '@owlmeans/basic-envelope'
+
+// Custom hook for secure message handling
+function useSecureMessage<T>(initialMessage?: T) {
+  const [envelope] = useState(() => makeEnvelopeModel<T>('react-state'))
+  const [message, setMessage] = useState<T | null>(initialMessage || null)
+
+  const updateMessage = (newMessage: T, ttl?: number) => {
+    envelope.send(newMessage, ttl)
+    setMessage(newMessage)
+  }
+
+  const getSecureToken = async (keys) => {
+    return await envelope.sign(keys, EnvelopeKind.Token)
+  }
+
+  const verifyMessage = async (token: string, keys) => {
+    try {
+      const received = makeEnvelopeModel(token, EnvelopeKind.Token)
+      if (await received.verify(keys)) {
+        const data = received.message<T>()
+        setMessage(data)
+        return true
+      }
+    } catch (error) {
+      console.error('Message verification failed:', error)
+    }
+    return false
+  }
+
+  return { message, updateMessage, getSecureToken, verifyMessage }
+}
+```
+
+## Security Considerations
+
+### Cryptographic Security
+1. **Key Management**: Use `@owlmeans/basic-keys` for proper Ed25519 key generation and management
+2. **Signature Verification**: Always verify signatures before processing messages in production
+3. **TTL Usage**: Implement appropriate TTL values to prevent replay attacks
+4. **Key Rotation**: Regularly rotate signing keys and update verification keys
+
+### Data Protection
+1. **Sensitive Data**: Avoid including sensitive data in message types or identifiers
+2. **Message Encoding**: Automatic Base64 encoding provides basic obfuscation but not encryption
+3. **Transmission Security**: Use HTTPS/TLS for envelope transmission over networks
+4. **Storage Security**: Encrypt wrapped envelopes before database storage
+
+### Validation Best Practices
+1. **Input Validation**: Validate envelope data before processing messages
+2. **Type Safety**: Use TypeScript generics for compile-time message type checking
+3. **Error Handling**: Implement proper error handling for verification failures
+4. **Audit Logging**: Log envelope verification results for security monitoring
+
+## Performance Considerations
+
+### Memory Usage
+- **Large Messages**: Consider message size impact on memory usage
+- **Batch Operations**: Process multiple envelopes efficiently rather than individually
+- **Key Caching**: Cache key pairs to avoid repeated generation operations
+
+### Serialization Performance
+- **Format Selection**: Choose appropriate format (wrap vs token) based on use case
+- **Compression**: Consider compression for large messages before envelope wrapping
+- **JSON Parsing**: Message decoding involves JSON parsing - optimize for large objects
+
+## Best Practices
+
+1. **TTL Management**: Set appropriate TTL values based on use case security requirements
+2. **Type Safety**: Always use TypeScript generics for compile-time message validation
+3. **Error Handling**: Implement comprehensive error handling for all envelope operations
+4. **Key Management**: Use proper key generation and storage practices from `@owlmeans/basic-keys`
+5. **Format Selection**: Choose envelope format (wrap vs token) based on transmission requirements
+6. **Verification**: Always verify envelopes in production environments before processing
+7. **Logging**: Implement appropriate logging for debugging without exposing sensitive data
+
+## Package Structure
+
+Following OwlMeans Common library structure:
+
+- **types**: TypeScript interfaces (`Envelope`, `EnvelopeModel`)
+- **model**: Factory functions (`makeEnvelopeModel`)
+- **consts**: Constants and enumerations (`EnvelopeKind`, `DEFAULT_TTL`)
+- **helper**: Utility functions for envelope operations
+- **utils**: Internal utilities for serialization and parsing
+
+## Dependencies
+
+This package depends on:
+- `@owlmeans/basic-keys` - Ed25519 key pair management for cryptographic operations
+- `@scure/base` - Base64 and UTF-8 encoding utilities
+- `uuid` - UUID generation (if needed for message identification)
+
+## Related Packages
+
+- [`@owlmeans/basic-keys`](../basic-keys) - Cryptographic key management
+- [`@owlmeans/auth`](../auth) - Authentication system integration
+- [`@owlmeans/error`](../error) - Error handling system
+

package/build/consts.d.ts

@@ -0,0 +1,6 @@
+export declare enum EnvelopeKind {
+    Wrap = "wrap",
+    Token = "token"
+}
+export declare const DEFAULT_TTL: number;
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,oBAAY,YAAY;IACtB,IAAI,SAAS;IACb,KAAK,UAAU;CAChB;AAED,eAAO,MAAM,WAAW,QAAgB,CAAA"}

package/build/consts.js

@@ -0,0 +1,7 @@
+export var EnvelopeKind;
+(function (EnvelopeKind) {
+    EnvelopeKind["Wrap"] = "wrap";
+    EnvelopeKind["Token"] = "token";
+})(EnvelopeKind || (EnvelopeKind = {}));
+export const DEFAULT_TTL = 5 * 60 * 1000;
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAN,IAAY,YAGX;AAHD,WAAY,YAAY;IACtB,6BAAa,CAAA;IACb,+BAAe,CAAA;AACjB,CAAC,EAHW,YAAY,KAAZ,YAAY,QAGvB;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA"}

package/build/helper.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":""}

package/build/helper.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=helper.js.map

package/build/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":""}

package/build/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './model.js';
+export * from './consts.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA"}

package/build/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './model.js';
+export * from './consts.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA"}

package/build/model.d.ts

@@ -0,0 +1,4 @@
+import { EnvelopeKind } from './consts.js';
+import type { EnvelopeModel } from './types.js';
+export declare const makeEnvelopeModel: <T extends {} | string = string>(type: string, kind?: EnvelopeKind) => EnvelopeModel<T>;
+//# sourceMappingURL=model.d.ts.map

package/build/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,YAAY,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG/C,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,EAAE,GAAG,MAAM,iBAC/C,MAAM,SAAS,YAAY,KAChC,aAAa,CAAC,CAAC,CAkEjB,CAAA"}

package/build/model.js

@@ -0,0 +1,61 @@
+import { base64, utf8 } from '@scure/base';
+import { DEFAULT_TTL, EnvelopeKind } from './consts.js';
+import { tokenize, untokenize, unwrap, wrap } from './utils/model.js';
+export const makeEnvelopeModel = (type, kind) => {
+    const model = {
+        envelope: kind == null ? {
+            t: type,
+            msg: '',
+            dt: new Date().getTime(),
+            ttl: DEFAULT_TTL
+        } : kind === EnvelopeKind.Wrap
+            ? unwrap(type) : untokenize(type),
+        send: (msg, ttl) => {
+            model.envelope.msg = typeof msg == 'string' ? msg : base64.encode(utf8.decode(JSON.stringify(msg)));
+            if (typeof ttl !== 'undefined') {
+                model.envelope.ttl = ttl;
+            }
+            return model;
+        },
+        message: (preserve) => {
+            if (preserve === true) {
+                return model.envelope.msg;
+            }
+            try {
+                return JSON.parse(utf8.encode(base64.decode(model.envelope.msg)));
+            }
+            catch (e) {
+                return model.envelope.msg;
+            }
+        },
+        type: () => model.envelope.t,
+        wrap: () => wrap(model.envelope),
+        tokenize: () => tokenize(model.envelope),
+        sign: async (key, kind) => {
+            model.envelope.sig = await key.sign(model.envelope);
+            switch (kind) {
+                case EnvelopeKind.Wrap:
+                    return model.wrap();
+                case EnvelopeKind.Token:
+                    return model.tokenize();
+                default:
+                    return model.envelope.sig;
+            }
+        },
+        verify: async (key) => {
+            const signature = model.envelope.sig;
+            if (signature == null) {
+                return false;
+            }
+            if (model.envelope.ttl != null
+                && model.envelope.dt + model.envelope.ttl < new Date().getTime()) {
+                return false;
+            }
+            const data = { ...model.envelope };
+            delete data.sig;
+            return await key.verify(data, signature);
+        }
+    };
+    return model;
+};
+//# sourceMappingURL=model.js.map

package/build/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"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"}

package/build/types.d.ts

@@ -0,0 +1,20 @@
+import type { KeyPairModel } from '@owlmeans/basic-keys';
+import type { EnvelopeKind } from './consts';
+export interface Envelope {
+    t: string;
+    msg: string;
+    sig?: string;
+    dt: number;
+    ttl: number | null;
+}
+export interface EnvelopeModel<T extends {} | string = string> {
+    envelope: Envelope;
+    send: <M extends T>(msg: M, ttl?: number | null) => EnvelopeModel;
+    wrap: () => string;
+    tokenize: () => string;
+    message: <M extends T>(preserve?: boolean) => M;
+    type: () => string;
+    sign: (key: KeyPairModel, kind?: EnvelopeKind) => Promise<string>;
+    verify: (key: KeyPairModel) => Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE5C,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAA;IACT,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CACnB;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,EAAE,GAAG,MAAM,GAAG,MAAM;IAC3D,QAAQ,EAAE,QAAQ,CAAA;IAClB,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,KAAK,aAAa,CAAA;IACjE,IAAI,EAAE,MAAM,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,CAAC,CAAA;IAC/C,IAAI,EAAE,MAAM,MAAM,CAAA;IAClB,IAAI,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACjE,MAAM,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAChD"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/build/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './model.js';
+//# sourceMappingURL=index.d.ts.map

package/build/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA"}

package/build/utils/index.js

@@ -0,0 +1,2 @@
+export * from './model.js';
+//# sourceMappingURL=index.js.map

package/build/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA"}

package/build/utils/model.d.ts

@@ -0,0 +1,6 @@
+import type { Envelope } from '../types.js';
+export declare const wrap: (object: Envelope) => string;
+export declare const tokenize: (object: Envelope) => string;
+export declare const untokenize: (token: string) => Envelope;
+export declare const unwrap: (envelope: string) => Envelope;
+//# sourceMappingURL=model.d.ts.map

package/build/utils/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/utils/model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,eAAO,MAAM,IAAI,WAAY,QAAQ,KAAG,MACY,CAAA;AAEpD,eAAO,MAAM,QAAQ,WAAY,QAAQ,KAAG,MACgB,CAAA;AAE5D,eAAO,MAAM,UAAU,UAAW,MAAM,KAAG,QACY,CAAA;AAEvD,eAAO,MAAM,MAAM,aAAc,MAAM,KAAG,QACQ,CAAA"}

package/build/utils/model.js

@@ -0,0 +1,6 @@
+import { base64, base64urlnopad, utf8 } from '@scure/base';
+export const wrap = (object) => base64.encode(utf8.decode(JSON.stringify(object)));
+export const tokenize = (object) => base64urlnopad.encode(utf8.decode(JSON.stringify(object)));
+export const untokenize = (token) => JSON.parse(utf8.encode(base64urlnopad.decode(token)));
+export const unwrap = (envelope) => JSON.parse(utf8.encode(base64.decode(envelope)));
+//# sourceMappingURL=model.js.map

package/build/utils/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/utils/model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAG1D,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,MAAgB,EAAU,EAAE,CAC/C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;AAEpD,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAgB,EAAU,EAAE,CACnD,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;AAE5D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAa,EAAY,EAAE,CACpD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;AAEvD,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,QAAgB,EAAY,EAAE,CACnD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@owlmeans/basic-envelope",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 36 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "bin": {
+    "owlkeys": "./build/bin.js"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.7",
+    "typescript": "^5.6.3"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.6.0",
+    "@noble/hashes": "^1.5.0",
+    "@owlmeans/basic-keys": "^0.1.0",
+    "@scure/base": "^1.1.9"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,8 @@
+
+export enum EnvelopeKind {
+  Wrap = 'wrap',
+  Token = 'token'
+}
+
+export const DEFAULT_TTL = 5 * 60 * 1000
+

package/src/index.ts

@@ -0,0 +1,4 @@
+
+export * from './types.js'
+export * from './model.js'
+export * from './consts.js'

package/src/model.ts

@@ -0,0 +1,74 @@
+import { base64, utf8 } from '@scure/base'
+import { DEFAULT_TTL, EnvelopeKind } from './consts.js'
+import type { EnvelopeModel } from './types.js'
+import { tokenize, untokenize, unwrap, wrap } from './utils/model.js'
+
+export const makeEnvelopeModel = <T extends {} | string = string>(
+  type: string, kind?: EnvelopeKind
+): EnvelopeModel<T> => {
+  const model: EnvelopeModel = {
+    envelope: kind == null ? {
+      t: type,
+      msg: '',
+      dt: new Date().getTime(),
+      ttl: DEFAULT_TTL
+    } : kind === EnvelopeKind.Wrap
+      ? unwrap(type) : untokenize(type),
+
+    send: (msg, ttl) => {
+      model.envelope.msg = typeof msg == 'string' ? msg : base64.encode(utf8.decode(JSON.stringify(msg)))
+      if (typeof ttl !== 'undefined') {
+        model.envelope.ttl = ttl
+      }
+
+      return model
+    },
+
+    message: <T>(preserve?: boolean) => {
+      if (preserve === true) {
+        return model.envelope.msg as T
+      }
+      try {
+        return JSON.parse(utf8.encode(base64.decode(model.envelope.msg))) as T
+      } catch (e) {
+        return model.envelope.msg as T
+      }
+    },
+
+    type: () => model.envelope.t,
+
+    wrap: () => wrap(model.envelope),
+
+    tokenize: () => tokenize(model.envelope),
+
+    sign: async (key, kind) => {
+      model.envelope.sig = await key.sign(model.envelope)
+      switch (kind) {
+        case EnvelopeKind.Wrap:
+          return model.wrap()
+        case EnvelopeKind.Token:
+          return model.tokenize()
+        default:
+          return model.envelope.sig
+      }
+    },
+
+    verify: async key => {
+      const signature = model.envelope.sig
+      if (signature == null) {
+        return false
+      }
+      if (model.envelope.ttl != null
+        && model.envelope.dt + model.envelope.ttl < new Date().getTime()) {
+        return false
+      }
+
+      const data = { ...model.envelope }
+      delete data.sig
+
+      return await key.verify(data, signature)
+    }
+  }
+
+  return model
+}

package/src/types.ts

@@ -0,0 +1,21 @@
+import type { KeyPairModel } from '@owlmeans/basic-keys'
+import type { EnvelopeKind } from './consts'
+
+export interface Envelope {
+  t: string
+  msg: string
+  sig?: string
+  dt: number
+  ttl: number | null
+}
+
+export interface EnvelopeModel<T extends {} | string = string> {
+  envelope: Envelope
+  send: <M extends T>(msg: M, ttl?: number | null) => EnvelopeModel
+  wrap: () => string
+  tokenize: () => string
+  message: <M extends T>(preserve?: boolean) => M
+  type: () => string
+  sign: (key: KeyPairModel, kind?: EnvelopeKind) => Promise<string>
+  verify: (key: KeyPairModel) => Promise<boolean>
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+
+export * from './model.js'

package/src/utils/model.ts

@@ -0,0 +1,14 @@
+import { base64, base64urlnopad, utf8 } from '@scure/base'
+import type { Envelope } from '../types.js'
+
+export const wrap = (object: Envelope): string => 
+  base64.encode(utf8.decode(JSON.stringify(object)))
+
+export const tokenize = (object: Envelope): string =>
+  base64urlnopad.encode(utf8.decode(JSON.stringify(object)))
+
+export const untokenize = (token: string): Envelope =>
+  JSON.parse(utf8.encode(base64urlnopad.decode(token)))
+
+export const unwrap = (envelope: string): Envelope =>
+  JSON.parse(utf8.encode(base64.decode(envelope)))

package/tsconfig.json

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

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/consts.ts","./src/helper.ts","./src/index.ts","./src/model.ts","./src/types.ts","./src/utils/index.ts","./src/utils/model.ts"],"version":"5.6.3"}