Skip to main content

ArcanContext Host Functions

The ArcanContext (called ctx in plugin code) is the plugin's ONLY interface to the outside world. It provides host functions that the core implements.

┌─────────────────────────────────────────────────────────────────┐
│                    ArcanContext Host Functions                   │
│                                                                 │
│  CONNECTION (requires host:sql or host:http capability):        │
│    ctx.SQL(query, args...)        → rows       Core connects    │
│    ctx.SQLExec(query, args...)    → affected   to the external  │
│    ctx.HTTP(method, url, body)    → response   system, plugin   │
│                                                never touches    │
│  DATA (requires host:store:read/write):        the network.     │
│    ctx.Store.Get(key)             → value                       │
│    ctx.Store.Put(key, value)      → error      Core encrypts    │
│    ctx.Store.Delete(key)          → error      before storage.  │
│    ctx.Store.List(prefix)         → keys                        │
│                                                                 │
│  CRYPTO (requires host:crypto):                                 │
│    ctx.Encrypt(plaintext)         → ciphertext                  │
│    ctx.Decrypt(ciphertext)        → plaintext                   │
│                                                                 │
│  AUDIT (requires host:audit):                                   │
│    ctx.Audit(event, data)         → error                       │
│                                                                 │
│  IDENTITY (always available):                                   │
│    ctx.RequestID()                → string                      │
│    ctx.UserID()                   → string                      │
│    ctx.RealmID()                  → string                      │
│    ctx.LeaseID()                  → string                      │
│    ctx.Role()                     → RoleInfo                    │
│                                                                 │
│  HELPERS (always available):                                    │
│    ctx.GenerateUsername()         → string     Derived from     │
│    ctx.GeneratePassword(bytes)   → string     lease ID, crypto │
│    ctx.Now()                      → time       random.          │
│    ctx.TTL()                      → duration                    │
│                                                                 │
│  WHAT PLUGINS CANNOT DO:                                        │
│    ✗ Open network connections directly                          │
│    ✗ Read/write filesystem                                      │
│    ✗ Access core memory or other plugins' data                  │
│    ✗ Import arbitrary libraries                                 │
│    ✗ Execute system commands                                    │
│    ✗ Spawn processes or threads                                 │
└─────────────────────────────────────────────────────────────────┘

CONNECTION​

Requires host:sql or host:http capability.

The core connects to the external system on behalf of the plugin. The plugin never touches the network directly. Root credentials are held by the core and never exposed to plugin code.

  • ctx.SQL(query, args...) -- Execute a SQL query and return rows
  • ctx.SQLExec(query, args...) -- Execute a SQL statement and return affected row count
  • ctx.HTTP(method, url, body) -- Make an HTTP request and return the response

DATA​

Requires host:store:read and/or host:store:write capability.

The core encrypts all values before storage using AES-256-GCM. Data is scoped to the plugin's engine_id + realm_id -- plugins cannot access other plugins' data.

  • ctx.Store.Get(key) -- Read a value from the plugin's scoped data store
  • ctx.Store.Put(key, value) -- Write a value (core encrypts before storage)
  • ctx.Store.Delete(key) -- Remove a value
  • ctx.Store.List(prefix) -- List keys matching a prefix

CRYPTO​

Requires host:crypto capability.

  • ctx.Encrypt(plaintext) -- Encrypt data using the core's encryption layer
  • ctx.Decrypt(ciphertext) -- Decrypt data using the core's encryption layer

AUDIT​

Requires host:audit capability.

  • ctx.Audit(event, data) -- Emit an audit event through the core's dispatcher

IDENTITY​

Always available to all plugins.

  • ctx.RequestID() -- The unique request ID for correlation
  • ctx.UserID() -- The authenticated user's UUID
  • ctx.RealmID() -- The resolved realm UUID
  • ctx.LeaseID() -- The lease UUID (for credential operations)
  • ctx.Role() -- The role information for the current operation

HELPERS​

Always available to all plugins.

  • ctx.GenerateUsername() -- Generate a safe username derived from the lease ID
  • ctx.GeneratePassword(bytes) -- Generate a crypto-random password
  • ctx.Now() -- Current UTC time
  • ctx.TTL() -- The requested TTL for the current operation

What Plugins Cannot Do​

Plugins are sandboxed and have no direct access to:

  • Network connections (all networking goes through host functions)
  • Filesystem (no reading or writing files)
  • Core memory or other plugins' data
  • Arbitrary library imports
  • System command execution
  • Process or thread spawning