CitrineOS Core

CitrineOS is a modular server runtime for managing Electric Vehicle (EV) charging infrastructure. It is built with TypeScript and runs on NodeJS using fastify and ws.

Key Features

• OCPP Support: Dynamic schema validation for OCPP 1.6 and 2.0.1 using AJV.
• API Surface:
  • Generates OpenAPIv3 specifications.
  • Uses @AsRequestHandler and @AsResponseHandler decorators to declare message handlers.
  • Provides an Api module with AbstractMessageEndpoint (for /ocpp/<version>/... routes to stations) and AbstractEndpoint (for /commands admin operations).
• Infrastructure:
  • Message Broker: Supports RabbitMQ for inter-module communication.
  • Caching: Supports In Memory and Redis.
  • Persistence: Uses PostgreSQL with the PostGIS extension.
  • Storage: Supports Amazon S3, Google Cloud Storage (GCS), and MinIO (for local development). Note that local development does not support GCS-compatible backends.
• Operator UI: A web interface built with Next.js and Refine for managing locations, stations, transactions, and authorizations.

The @citrineos/mock-msp package is a mock e-Mobility Service Provider (eMSP) designed to test CitrineOS's CPO-side OCPI implementation. It impersonates the seeded partner US/TST ("TestMobilitySolutions") and communicates via OCPI 2.2.1.

Key characteristics:

• Port: Listens on port 8083.
• Schema Fidelity: Reuses @citrineos/ocpi-base Zod schemas to ensure the mock and CitrineOS never disagree on data contracts.
• Internal Components:
  • Recorder: Creates an immutable, queryable trace of all inbound and outbound Exchange events.
  • Actor: Handles the credentials handshake, sends Commands to Citrine, hosts response_url callbacks, and pulls SENDER endpoints.
  • Adversary: A FaultEngine used to inject traffic perturbations (delays, aborts, malformed bodies, etc.) when a scenario is armed.
• Control API: A /_mock/* surface used to inspect traces, drive the Actor, arm faults, and run assertions.

Note: This is a private/dev tool. The package is marked private: true and is not intended for production release.

CitrineOS exposes three distinct REST API surfaces, each identified by a specific URL prefix. Depending on your goal (sending OCPP messages, executing system commands, or managing the router), you will target one of these three:

1. OCPP Surface (/ocpp/<version>/<module>/<action>): Used to send OCPP messages to charging stations. The <version> segment specifies the protocol (e.g., 1.6, 2.0.1), and <module> is determined by the configured endpointPrefix.
2. Commands Surface (/commands/<command>): Used for CitrineOS-native operations that are not direct OCPP messages (e.g., POST /commands/setStationPassword).
3. Router Administration Surface (/ocpprouter/<resource>): Used for managing the router, such as websocket configuration, tenant mappings, and TLS reloading (e.g., DELETE /ocpprouter/connection).

# Examples of API paths:
POST /ocpp/1.6/configuration/changeAvailability?identifier=cs001
POST /commands/setStationPassword
DELETE /ocpprouter/connection

The dashboard provides real-time health and state information through several key indicators:

Registration Status

Located in the header, this indicates the OCPI handshake state:

• Green registered: Handshake complete; tokens and endpoints are exchanged.
• Amber unregistered: Handshake not yet performed.
• Red server down: Connection to CitrineOS is lost.

Scenario Badge

Displays the currently loaded scenario file (e.g., preregistered). A scenario is a JSON file defining the starting state, fault configurations, and test assertions.

Summary Cards

• EXCHANGES: Count of complete HTTP conversations recorded.
• FINDINGS: Count of failed contract inspections. A single finding (one failed response) can contain multiple issues (individual broken fields).
• FAULTS ARMED: Number of active "misbehave on purpose" rules. Amber indicates faults are currently armed; check this before clicking to avoid unintended errors.
• AUTHORIZE: The standing answer to CitrineOS's authorization requests (e.g., ALLOWED or BLOCKED).

A scenario is a configuration file (located in apps/mock-msp/scenarios/*.json) that defines the adversary configuration, registration state, and assertion fixtures.

Scenarios can be loaded at boot using the MOCK_MSP_SCENARIO environment variable or hot-loaded at runtime via POST /_mock/scenario.

Scenario Schema

• name: String identifier.
• registration: Either preregistered (uses seed tokens) or unregistered (requires handshake).
• identity: Optional Partial<OcpiIdentity> override.
• authorize: Defines the tokens/{uid}/authorize policy. Supports a default (e.g., ALLOWED, BLOCKED) and byUid overrides.
• strictInbound: If true, schema-invalid inbound bodies return a 2001 error; otherwise, they are recorded and accepted.
• faults: An array of FaultRule objects.
• expect: An array of assertion oracles used with POST /_mock/scenarios/:id/evaluate.

{
  "name": "authorize-blocked",
  "registration": "preregistered",
  "identity": { /* optional override */ },
  "authorize": {
    "default": "ALLOWED",
    "byUid": { "04E7F5A2B37C80": "BLOCKED" }
  },
  "strictInbound": false,
  "faults": [ /* FaultRule[] */ ],
  "expect": [
    { "on": "tokens.authorize", "assert": "response.body.data.allowed == BLOCKED" }
  ]
}