@aurabx/jmix-js 0.1.0

package/.ai/security.md

@@ -0,0 +1,184 @@
+# JMIX Envelope Security White Paper
+
+Christopher Skene
+8th June 2025
+DRAFT - WORK IN PROGRESS
+
+## Abstract
+
+This paper presents the security encryption architecture for JMIX (JSON Medical Imaging Exchange) Envelopes, supporting secure, peer-to-peer exchange of identifiable imaging data. The model is designed to support interoperability between independent actors and optionally leverage the Aurabox directory and services for enhanced usability, policy enforcement, and auditability, without introducing any dependency on Aurabox for decryption or transmission.
+
+## 1. Introduction
+
+Healthcare imaging data exchange faces challenges around security, interoperability, and decentralisation. Traditional centralised exchange models introduce unnecessary dependencies and trust anchors, whereas pure peer-to-peer systems can lack usability or governance.
+
+JMIX aims to strike a balance: enabling direct, secure, peer-to-peer sharing, while allowing parties who choose to use a trusted directory (e.g. Aurabox) to gain benefits like key discovery, consent validation, and identity anchoring.
+
+Some of the features of this security model include:
+
+- Forward Secrecy: Ephemeral keys ensure compromise of long-term keys does not expose past data.
+- Authentication: GCM tag ensures ciphertext cannot be tampered with.
+- Minimal Trust: No dependency on Aurabox or any other service for basic operation.
+- Optional Governance: Aurabox can be used to anchor identities, resolve key IDs, or audit transfers
+- Non-repudiation: Proof of sender
+
+## 2. Design Principles
+
+Self-contained encryption: All JMIX envelopes must be decryptable using only what is contained inside the envelope, assuming the recipient possesses the correct private key.
+
+Ephemeral key use: All encryption must use ephemeral sender keys to provide forward secrecy.
+
+Fixed cryptographic stack: All payloads are encrypted using AES-256-GCM with ECDH key agreement and HKDF (SHA-256) for symmetric key derivation.
+
+Directory-optional context: Key discovery, identity mapping, and policy evaluation may optionally be facilitated by Aurabox or a compatible directory, but are not required for decryption.
+
+## 3. Cryptographic Foundations
+
+Algorithm:
+
+- Encryption: AES-256 in Galois/Counter Mode (GCM)
+- Key Exchange: Elliptic Curve Diffie-Hellman (ECDH) over Curve25519
+- Key Derivation: HKDF using SHA-256
+
+Each package is encrypted using a one-time symmetric key derived from ECDH, ensuring forward secrecy and resilience.
+
+## 4. Envelope Structure
+
+### a. Encryption (required when the package is encrypted)
+
+The Encryption block describes the encryption of the package directory. It is required when the package is encrypted, but not when the package is unencrypted (for example, if the envelope is being used as a download).
+
+```json
+"encryption": {
+  "algorithm": "AES-256-GCM",
+  "ephemeral_public_key": "<base64>",
+  "iv": "<base64>",
+  "auth_tag": "<base64>"
+}
+```
+
+These fields are all required for the recipient to decrypt the contents of the package directory.
+
+- algorithm: Always AES-256-GCM
+- ephemeral_public_key: The sender's one-time-use ECDH public key.
+- iv: 96-bit AES-GCM nonce.
+- auth_tag: 128-bit authentication tag generated during encryption.
+
+### b. Sender Assertion (optional, but recommended)
+
+The Sender Assertion block allows the sender to provide information about themselves, so that the receiver can verify the authenticity of the package. It serves as a mechanism for authenticating and verifying the identity of the sender of a JMIX envelope, especially in decentralised or federated environments.
+
+It helps guard against spoofing by cryptographically binding the claimed identity to the encrypted payload.
+Enables trust decisions in the absence of live infrastructure (e.g., offline environments).
+Supports forensic verification: recipients can prove to others who sent the data and that it hasn’t been altered.
+
+The sender_assertion block exists to:
+
+- Provide verifiable metadata about the sender, such as their claimed identity and the cryptographic evidence that supports that claim.
+- Enable trust and non-repudiation, by binding the sender’s claimed identity to the specific encrypted payload using a signature.
+- Support optional directory-based verification, such as through Aurabox or other compatible directories, without being dependent on them.
+
+This is crucial in peer-to-peer settings, where there is no central server to authenticate participants. It allows recipients and third parties (for example, auditors) to validate who sent a JMIX package, even offline. The Sender Assertion is foundational to JMIX's trust and governance model, acting as a decentralised and optionally third-party-verified sender identity proof, ensuring secure and accountable medical imaging exchange.
+
+```json
+{
+  "signing_key": {
+    "alg": "Ed25519",
+    "public_key": "<base64>",
+    "fingerprint": "SHA256:<hex>"
+  },
+  "key_reference": "aurabox://org/clinic-a#key-ed25519",
+  "signed_fields": [
+    "sender.id",
+    "sender.name",
+    "signatures.manifest.kid",
+    "manifest_hash"
+  ],
+  "signature": "<base64sig>",
+  "expires_at": "2025-07-07T00:00:00Z",
+  "directory_attestation": {
+    "provider": "aurabox",
+    "attestation_signature": "<JWS>",
+    "attestation_timestamp": "2025-06-07T14:01:00Z",
+    "attestation_public_key": "<base64>"
+  }
+}
+```
+
+The file is referenced in the sender block, as follows:
+
+```json
+"sender": {
+  "id": "org:au.gov.health.123456",
+  "name": "Clinic A",
+  "contact": "dicom@clinica.org.au",
+  "assertion": {
+    "...": "assertion goes here"
+  }
+}
+```
+
+While the attestation includes expiry, the receiver is not bound to reject the envelope if the expiry has passed. This is up to receivers to define.
+
+### c. Requester Assertion (optional)
+
+The requester assertion follows a similar pattern to the Sender Assertion and allows the receiver to validate the requester. This may be useful to determine that the receiver is receiving information it is allowed to hold, based on the requester's identity.
+
+The requester identity should be provided by the requester when requesting the data, either via a JMIX API or some other mechanism. The signature model is identical to the sender's.
+
+```json
+"requester": {
+  "name": "Dr. Michael Chen",
+  "email": "mchen@university-medical.edu",
+  "authentication_level": "directory_verified",
+  "assertion": {
+    "...": "assertion goes here"
+  }
+}
+```
+
+### Verification Workflow
+
+- Fetch signed_fields and corresponding values from the envelope.
+- Canonicalise the field-value structure.
+- Verify the signature using signing_key.public_key.
+- Optional: Validate directory_attestation.attestation_signature using attestation_public_key.
+- Check expires_at if present.
+
+## 5. Modes of Operation
+
+| Use Case                    | Description                                                                                              |
+| --------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Pure P2P                    | Sender and recipient exchange directly (email, file transfer, etc.). Only envelope metadata is required. |
+| P2P with Aurabox resolution | Recipient or sender uses Aurabox API to discover keys, validate sender IDs, or log consent.              |
+| Asymmetric P2P              | One user uses Aurabox for discovery, the other operates independently.                                   |
+
+## 6. Encryption Workflow
+
+- Sender generates a new ephemeral EC keypair.
+- Shared key is derived via ECDH (sender's ephemeral privkey plus recipient's pubkey).
+- Symmetric key is produced using HKDF with SHA-256.
+- Payload is encrypted with AES-256-GCM using the derived key, random IV, and the tag is retained.
+- Envelope is assembled with the encrypted payload and manifest.json.
+
+## 7. Recipient Key Management and Discovery
+
+JMIX assumes that each recipient maintains a stable, long-term asymmetric keypair (for example, Curve25519) for envelope decryption. The public component of this key must be made available to potential senders through one or more of the following mechanisms:
+
+- Out-of-Band Exchange: Recipients may distribute their public keys manually via QR codes, shared config files, or email. This is suitable for small, trusted collaborations.
+- Directory Lookup (optional): Aurabox and compatible directories may expose a public key endpoint, for example, aurabox://org/clinic-a#key-ed25519, to facilitate key discovery and resolution.
+- In-Envelope Reference: Senders may embed a key_reference URI in the sender assertion, indicating the expected recipient key. This does not impact decryption, but helps with auditing and debugging.
+
+For secure operation, recipients must safeguard their private key material. Rotation or revocation of keys should be managed via external policy or infrastructure and is not currently defined within the JMIX envelope format.
+
+## 8. Deployment Scenarios
+
+- Independent Users: Healthcare providers, researchers, or clinicians using custom tooling.
+- Integrated Aurabox Users: Those who opt-in for identity resolution, central consent records, or integration with Aurabox storage and viewing services.
+- Mixed Mode: One peer uses Aurabox to obtain the other’s public key, then sends a self-contained envelope.
+
+## 9. Conclusion
+
+The JMIX envelope encryption strategy strikes a balance between secure, verifiable data exchange and ecosystem flexibility. It provides robust default behaviour for independent users while allowing powerful enhancements when Aurabox services are available.
+
+This ensures imaging data can be safely exchanged, whether between two doctors, hospitals, or platforms, with confidence in its privacy, integrity, and interoperability.

package/.eslintrc.cjs

@@ -0,0 +1,23 @@
+module.exports = {
+  env: {
+    node: true,
+    es2022: true,
+    jest: true,
+  },
+  extends: ['eslint:recommended'],
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+  },
+  rules: {
+    'no-console': 'warn',
+  },
+  ignorePatterns: [
+    'dist/',
+    'coverage/',
+    'node_modules/',
+    '*.js',
+    '**/*.d.ts',
+    'src/**/*.ts', // Skip TypeScript files for now
+  ],
+};

package/.idea/jmix-ts.iml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/tests" isTestSource="true" />
+      <excludeFolder url="file://$MODULE_DIR$/.tmp" />
+      <excludeFolder url="file://$MODULE_DIR$/temp" />
+      <excludeFolder url="file://$MODULE_DIR$/tmp" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/jmix-ts.iml" filepath="$PROJECT_DIR$/.idea/jmix-ts.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

package/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "endOfLine": "lf"
+}

package/README.md

@@ -0,0 +1,335 @@
+# JMIX TypeScript Library
+
+TypeScript implementation of the JMIX (JSON Medical Interchange) format for secure medical data exchange.
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Prerequisites
+
+- Node.js 20+ LTS
+- npm
+- TypeScript 5+
+
+## Quick Start
+
+```typescript
+import { JmixBuilder } from 'jmix-ts';
+
+// Create a builder
+const builder = new JmixBuilder({
+  outputPath: './tmp'
+});
+
+// Create or load configuration
+const config = await JmixBuilder.loadConfig('./samples/sample_config.json');
+
+// Build envelope from DICOM directory
+const envelope = await builder.buildFromDicom('./samples/study_1', config);
+
+// Save to files
+await builder.saveToFiles(envelope, './output');
+```
+
+## Demo
+
+Run the demo to see the library in action:
+
+```bash
+npm run build
+node demo-no-validation.js
+```
+
+This creates a complete JMIX envelope with:
+- `manifest.json` - Security, routing, and patient information
+- `metadata.json` - Clinical data and DICOM metadata
+- `audit.json` - Audit trail and transmission details
+ckaging (folder-based JMIX envelope)
+
+Create a proper JMIX folder that includes the original DICOM files under `payload/dicom` and computes a deterministic SHA-256 payload hash stored at `manifest.security.payload_hash`.
+
+CLI-like demo:
+
+```sh
+node demo-package.js ./samples/study_1 ./tmp
+```
+
+Programmatic API:
+
+```ts
+import { JmixBuilder } from './dist/index.js';
+
+const builder = new JmixBuilder();
+const config = await JmixBuilder.loadConfig('./samples/sample_config.json');
+const packagePath = await builder.packageToDirectory('./samples/study_1', config, './tmp');
+console.log(packagePath); // => ./tmp/<envelope_id>.JMIX
+```
+
+Resulting layout:
+
+```text
+<outputRoot>/<envelope_id>.JMIX/
+├── manifest.json
+├── audit.json
+└── payload/
+    ├── metadata.json
+    └── dicom/
+        └── ... (original DICOM files, structure preserved)
+```
+
+### Encryption (AES-256-GCM with X25519 + HKDF)
+
+The library can produce an encrypted JMIX envelope. It tars the plaintext `payload/` directory, encrypts it with AES-256-GCM using a key derived from X25519 ECDH and HKDF-SHA256, then writes `payload.encrypted` and removes the plaintext `payload/`.
+
+- Key agreement: Curve25519 (X25519)
+- KDF: HKDF-SHA256 (info = "JMIX-Payload-Encryption")
+- Cipher: AES-256-GCM
+- Manifest fields:
+  - `manifest.security.payload_hash` — SHA-256 over the plaintext `payload/` (deterministic, path+newline+bytes per file)
+  - `manifest.security.encryption`:
+    - `algorithm`: "AES-256-GCM"
+    - `ephemeral_public_key`: base64
+    - `iv`: base64 (12 bytes)
+    - `auth_tag`: base64 (16 bytes)
+
+Demo:
+
+```sh
+# recipientPublicKeyBase64 must be a 32-byte Curve25519 key in base64
+node demo-package-encrypted.js <recipientPublicKeyBase64> ./samples/study_1 ./tmp
+```
+
+Programmatic API:
+
+```ts
+import { JmixBuilder } from './dist/index.js';
+
+const builder = new JmixBuilder();
+const config = await JmixBuilder.loadConfig('./samples/sample_config.json');
+const packagePath = await builder.packageEncryptedToDirectory(
+  './samples/study_1',
+  config,
+  './tmp',
+  '<recipientPublicKeyBase64>'
+);
+console.log(packagePath);
+```
+
+Encrypted layout:
+
+```text
+<outputRoot>/<envelope_id>.JMIX/
+├── manifest.json               # includes security.payload_hash and security.encryption
+├── audit.json
+└── payload.encrypted           # AES-256-GCM encrypted TAR of plaintext payload/
+```
+
+### Decryption
+
+You can decrypt an encrypted JMIX envelope and restore a plaintext `payload/` directory. The payload hash is verified against `manifest.security.payload_hash`.
+
+Self-contained demo (encrypt + decrypt with a fresh keypair):
+
+```sh
+node demo-decrypt.js ./samples/study_1 ./tmp
+```
+
+Decrypt an existing folder (requires the matching Curve25519 private key in base64):
+
+```sh
+node demo-decrypt-existing.js ./tmp/<envelope_id>.JMIX <recipientPrivateKeyBase64>
+```
+
+Programmatic API:
+
+```ts
+import { JmixBuilder } from './dist/index.js';
+
+const builder = new JmixBuilder();
+const payloadPath = await builder.decryptEnvelope(
+  './tmp/<envelope_id>.JMIX',
+  '<recipientPrivateKeyBase64>'
+);
+console.log(payloadPath);
+```
+
+### Verify Payload Hash
+
+Verify the payload hash listed in `manifest.security.payload_hash`.
+
+- Plaintext payload/: compare directly
+- Encrypted payload.encrypted: requires the recipient private key to decrypt to a temp dir before verifying
+
+CLI demo:
+
+```sh
+# Plaintext envelope
+npm run demo:verify:hash -- ./tmp/<envelope_id>.JMIX
+
+# Encrypted envelope (requires private key)
+npm run demo:verify:hash -- ./tmp/<envelope_id>.JMIX <recipientPrivateKeyBase64>
+```
+
+Programmatic API:
+
+```ts
+import { JmixBuilder } from './dist/index.js';
+
+const builder = new JmixBuilder();
+const result = await builder.verifyPayloadHash(
+  './tmp/<envelope_id>.JMIX',
+  { recipientPrivateKeyBase64: '<privKey-if-encrypted>' }
+);
+console.log(result.ok, result.expected, result.computed);
+```
+
+## Scripts
+
+```bash
+# Development
+npm run build          # Compile TypeScript
+npm run typecheck      # Type checking only
+npm test               # Run all tests
+npm run test:watch     # Run tests in watch mode
+npm run test:coverage  # Generate coverage report
+
+# Code Quality
+npm run format         # Check code formatting
+npm run format:fix     # Fix code formatting
+npm run clean          # Clean build artifacts
+```
+
+## Architecture
+
+```
+src/
+├── JmixBuilder.ts           # Main orchestrator
+├── types/index.ts           # TypeScript interfaces
+├── validation/              # Ajv schema validation
+├── dicom/                   # DICOM file processing
+├── crypto/                  # AES-256-GCM encryption (future)
+└── errors/                  # Error types
+
+tests/                       # Jest test suite
+samples/                     # Sample JSON files
+```
+
+## Configuration
+
+### Schema Validation
+
+** This is Alpha quality code and has not yet been fully tested **
+
+The library uses configurable schema validation:
+
+```typescript
+const builder = new JmixBuilder({
+  schemaValidatorOptions: {
+    schemaPath: '../jmix/schemas',  // Default: ../jmix/schemas
+    strictMode: true                // Default: true
+  }
+});
+
+// Or via environment variable
+process.env.JMIX_SCHEMA_PATH = '/path/to/schemas';
+```
+
+### Output Directory
+
+Follows user rules for temp file output:
+
+```typescript
+const builder = new JmixBuilder({
+  outputPath: './tmp'  // Default: ./tmp (not /tmp)
+});
+```
+
+## DICOM Processing
+
+The library automatically:
+
+1. Recursively scans directories for DICOM files
+2. Validates files using DICM magic number at byte offset 128
+3. Extracts metadata (patient info, study details, series information)
+4. Falls back gracefully to configuration data when DICOM parsing fails
+5. Supports empty directories for testing
+
+## Schema Validation
+
+- **Default**: Looks for schemas in `../jmix/schemas`
+- **Configurable**: Override via constructor or environment variable
+- **Graceful Degradation**: Skips validation when schemas not found
+- **Comprehensive**: Validates manifest, metadata, and audit components
+
+## Testing
+
+Run the comprehensive test suite:
+
+```bash
+# All tests
+npm test
+
+# Specific test files
+npm test JmixBuilder.test.ts
+npm test SchemaValidator.test.ts
+
+# With coverage
+npm run test:coverage
+```
+
+The test suite includes:
+- ✅ JmixBuilder integration tests
+- ✅ Schema validator tests
+- ✅ Type definition tests
+- ✅ DICOM processing tests
+- ✅ Configuration loading tests
+- ✅ File I/O tests
+
+All tests use the `/samples` directory for realistic test data and output to `./tmp` for temporary files.
+
+## Security Model
+
+Implements the JMIX security whitepaper specifications:
+- **AES-256-GCM** encryption with ephemeral public keys
+- **Base64 encoding** for all cryptographic material (ephemeral_public_key, iv, auth_tag)
+- **Forward secrecy** through ephemeral key usage
+- **Optional governance** via Aurabox directory services
+
+See `.ai/security.md` for the complete security model.
+
+## Development
+
+The library follows TypeScript best practices:
+- **ESM modules** with .js imports in source
+- **Strict TypeScript** configuration
+- **Comprehensive type definitions** for all JMIX components
+- **Jest testing** with ts-jest for ESM support
+- **Prettier formatting** for consistent code style
+
+## Files Generated
+
+A complete JMIX envelope consists of:
+
+- **`manifest.json`** - Routing, security classification, patient info, sender/receiver details
+- **`metadata.json`** - Clinical metadata, DICOM study information, custom metadata
+- **`audit.json`** - Audit trail, status, and events timeline
+- **`files.json`** - (Optional) File manifest with hashes and sizes
+
+## Compatibility
+
+- **JMIX Specification**: Implements JMIX v1.0 format
+- **Schema Compatibility**: Works with JMIX JSON Schema Draft 2020-12
+- **DICOM Support**: Basic DICOM file detection and metadata extraction
+- **Framework Agnostic**: Pure TypeScript, works with any Node.js framework
+
+## License
+
+Matches the licensing of the JMIX specification and related implementations.
+
+---
+
+For detailed API documentation, see the TypeScript declarations in `dist/` after building.