File Format Specification
This document provides formal specifications for all Nexus and VM.ZERO file formats. These specifications are required for MIME-type registration with IANA and integration with editors, operating systems, and package managers.
Nexus Source Files (.nex / .nx)
| MIME Type | application/x-nexus |
| Encoding | UTF-8 text |
| Used By | Nexus compiler |
Source code files for the Nexus programming language. These files contain human-readable Nexus code that is compiled to bytecode or other target formats.
Features
- May include comments, imports, functions
- Shebang allowed: #!/usr/bin/env nexus
- Case-sensitive
- Line endings: LF, CRLF, or CR
Example File
#!/usr/bin/env nexus
// Nexus source file example
ffi js fetch(url: string): string;
func main(): void {
let data = fetch("https://api.example.com");
print(data);
}Security Considerations
Same security considerations as any executable script. Users should only execute .nex/.nx files from trusted sources. The compiler performs static analysis but does not prevent all security issues.
Interoperability Considerations
.nex and .nx files are text-based and can be edited with any text editor. They are designed to be version-control friendly.
VM.ZERO Encrypted Image (.vmz)
| MIME Type | application/x-vmzero |
| Purpose | Encrypted, signed VM.ZERO program |
Encrypted, signed VM.ZERO program image. This is the production-ready format for distributing Nexus programs.
Structure (High-Level)
- Header - Format version, metadata offsets
- Metadata block - Program information, dependencies
- Encrypted bytecode - AES-256-GCM or ChaCha20-Poly1305 encrypted
- Signature - Cryptographic signature for verification
Encryption Description
The bytecode is encrypted using either AES-256-GCM or ChaCha20-Poly1305. The encryption key is derived from the program's signature and metadata. The specific algorithm is determined by the VM.ZERO runtime version.
Security Considerations
MUST verify signature before execution. The VM.ZERO runtime will reject unsigned or tampered .vmz files. Only execute .vmz files from trusted sources with valid signatures.
Nexus Raw Bytecode (.nbc)
| MIME Type | application/x-nexus-bytecode |
| Purpose | Raw bytecode stream |
Unencrypted raw bytecode stream. This format is primarily used for debugging and development.
When to Use
Use .nbc for development, debugging, and bytecode inspection. Do not distribute .nbc files in production.
When Not to Use
Do not use .nbc for production distribution. Use .vmz for secure, signed distribution.
Nexus Package (.npack)
| MIME Type | application/x-nexus-package |
| Purpose | Package archive for Nexus projects |
Binary archive containing modules, metadata, and signatures. Used for package distribution and dependency management.
Package Structure
ZIP-like conceptual structure containing:
- manifest.json - Package metadata, dependencies, version
- modules/ - Compiled .vmz or .nbc modules
- signatures/ - Cryptographic signatures for integrity
- resources/ - Additional resources (optional)
Metadata Fields
- name - Package name
- version - Semantic version (e.g., 1.2.3)
- dependencies - List of required packages
- author - Package author
- license - License identifier
Integrity Checks
Each .npack file includes cryptographic signatures for all modules. The package manager verifies these signatures before installation.