Orbit Protocol – JavaScript Validator & CLI

Orbit is a minimal, fail-closed protocol for encoding single-action intents as JSON. This package provides the reference JavaScript (Node.js) validator for Orbit Protocol v1.0, plus a small CLI for validation in terminals and CI.

This library is deliberately boring:

• Deterministic
• Schema-locked
• No side effects
• No execution of intents
• Validation only

If an intent is invalid, it is rejected. There is no “best guess.”

What this package is

• A reference validator for Orbit Protocol v1.0
• A Node.js SDK for programmatic validation
• A CLI tool for validating JSON files
• A baseline for cross-language parity (Java, Kotlin, etc.)

What this package is NOT

• An intent executor
• A workflow engine
• A permission system
• A UI framework
• A smart interpreter

Orbit separates intent validation from intent execution by design.

Install

Global (CLI)

npm install -g @mnde/orbit-validator

Local (library)

npm install @mnde/orbit-validator

CLI Usage

Validate an intent file:

orbit validate intent.json

Exit codes

| Code | Meaning | |----|--------| | 0 | Valid Orbit v1.0 intent | | 1 | Invalid intent | | 2 | Usage, file, or JSON error |

Example

orbit validate valid.json
# VALID

orbit validate invalid.json
# INVALID: ERR_OPEN_URL_REQUIRED

Programmatic Usage

import { validateOrbitIntent } from "@mnde/orbit-validator";

const intent = {
  orbit: "1.0",
  id: "example-123",
  action: "open",
  payload: {
    url: "https://example.com"
  }
};

const result = validateOrbitIntent(intent);

if (result.valid) {
  console.log("Intent is valid");
} else {
  console.error("Invalid intent:", result.code);
}

Orbit v1.0 Validation Rules

Required fields

• orbit — must be exactly "1.0"
• id — non-empty string
• action — string from the allowed vocabulary
• payload — object

Allowed actions (v1.0)

| Action | Requirements | |------|-------------| | open | payload.url must be a non-empty string |

Unknown actions are rejected.

Error Codes

Error codes are stable and intentional. They are designed to match across all Orbit SDKs.

| Code | Meaning | |----|--------| | ERR_NOT_OBJECT | Root value is not an object | | ERR_ORBIT_VERSION | Missing or invalid Orbit version | | ERR_ID_INVALID | Missing or invalid id | | ERR_ACTION_INVALID | Missing or invalid action | | ERR_ACTION_UNKNOWN | Action not in v1.0 vocabulary | | ERR_PAYLOAD_INVALID | Missing or invalid payload | | ERR_OPEN_URL_REQUIRED | open action requires payload.url |

Design Guarantees

This validator guarantees:

• Fail-closed behavior
• No side effects
• No execution
• Deterministic results
• Protocol correctness over convenience

If the input is invalid, the output is invalid. Always.

Versioning

• This package implements Orbit Protocol v1.0
• Future protocol versions will be released as explicit updates
• Backward compatibility is never guessed

License

MIT

Project philosophy

Orbit is infrastructure. Infrastructure should be boring, predictable, and hard to misuse.

This validator exists to make incorrect behavior impossible.