Skip to main content

Engine Standard

Design Principles​

Three principles drive the plugin architecture:

  1. Core executes, plugin provides logic. Plugins define WHAT to do (SQL queries, API calls). The core does it (manages connections, holds credentials, encrypts data). Plugins never directly access the network, filesystem, or core memory.

  2. Language-agnostic SDK. Plugin authors write in their preferred language. Go is the first SDK, TypeScript and Python follow. The plugin is compiled into a package format (.arcanpkg) that the core loads and executes in a sandboxed runtime.

  3. 10 minutes from idea to working engine. Write ~10 lines of code, pack, publish, install. No gRPC boilerplate, no process management, no protocol knowledge needed.

Three Layers​

┌─────────────────────────────┐
│     Engine Standard         │  The contract (what an engine MUST implement)
├─────────────────────────────┤
│     Engine Runtime          │  The sandbox (how core loads and executes plugins)
├─────────────────────────────┤
│     Engine SDK              │  The helper (multi-language libraries for authors)
└─────────────────────────────┘

Engine Standard Contract​

Every engine implements a subset of operations based on its declared capabilities.

Required (all engines)​

Describe()                    → EngineDescriptor
Ping(ctx)                     → error
Bootstrap(ctx, config)        → error
Shutdown()                    → error

Dynamic credential engines (engine:dynamic_credentials)​

CreateCredentials(ctx, role, ttl) → Credentials
RevokeCredentials(ctx, ref)       → error
RenewCredentials(ctx, ref, ttl)   → Credentials
ListRoles(ctx)                    → []RoleInfo
CreateRole(ctx, name, config)     → error
DeleteRole(ctx, name)             → error

Root rotation engines (engine:root_rotation)​

RotateRoot(ctx)                   → error

Crypto engines (engine:crypto)​

Encrypt(ctx, plaintext, keyName)  → ciphertext
Decrypt(ctx, ciphertext, keyName) → plaintext
GenerateKey(ctx, name, keyType)   → error
ListKeys(ctx)                     → []KeyInfo

Certificate engines (engine:certificates)​

SignCertificate(ctx, csr, role, ttl) → Certificate
GetCACertificate(ctx)                → Certificate
RevokeCertificate(ctx, serial)       → error

Calling an unimplemented method returns 501 Not Implemented with a helpful message.

Engine Descriptor​

Every plugin package includes a descriptor -- the engine's identity card:

{
    "name": "postgres",
    "version": "0.1.0",
    "display_name": "PostgreSQL",
    "description": "Dynamic credentials for PostgreSQL databases",
    "sdk_version": 1,
    "min_core_version": "0.1.0",
    "capabilities": [
        "host:sql",
        "host:store:read",
        "host:store:write",
        "host:audit",
        "engine:dynamic_credentials",
        "engine:root_rotation"
    ],
    "tier": "official",
    "config_schema": { ... },
    "default_roles": [
        { "name": "readonly", "config": { "grants": "SELECT" } },
        { "name": "readwrite", "config": { "grants": "SELECT, INSERT, UPDATE, DELETE" } }
    ]
}

config_schema Wizard Example​

The config_schema field is a JSON Schema that describes what config the engine needs during Bootstrap(). The core CLI parses this schema to generate interactive setup wizards dynamically -- no hardcoded wizards in the core:

$ arcan plugin setup postgres

  PostgreSQL Dynamic Credentials Setup

  Connection string (DSN): postgres://admin:****@db.example.com:5432/mydb
  Max connections per lease [5]:
  Default TTL [1h]:

  ✓ Connected to PostgreSQL 15.2
  ✓ Created arcan_admin role
  ✓ Engine "postgres" bootstrapped in realm "default"