Communication Framework

Actors

EXTERNAL                          ARCAN CORE                           EXTERNAL
────────                          ──────────                           ────────
Human (CLI)          ──→    HTTPS Server
Human (API client)   ──→      │
SDK (Go/TS/Python)   ──→      ├── Middleware Stack
CI/CD pipeline       ──→      │     (guardian layer)
K8s service account  ──→      │
                              ├── Handlers
                              │     (business logic)
                              │
                              ├── Store                        ──→  SQLite / PostgreSQL
                              │
                              ├── Crypto                       ──→  KMS (AWS/GCP/Azure)
                              │
                              ├── Engine Registry
                              │     ├── KV (built-in)
                              │     └── Plugin Runtime ─host fn─→  Connection Mgr ──→ External System
                              │           (sandboxed)                (SQL, HTTP)
                              │
                              ├── Audit Dispatcher     ──→  Webhook Sink  ──→  SIEM
                              │                        ──→  Syslog Sink   ──→  Log Aggregator
                              │                        ──→  Store (async)
                              │
                              ├── Reaper (background)
                              │
                              └── Registry Client      ──→  registry.getarcan.dev

Communication Paths

Path 1: Client to Core (HTTPS)

┌──────────┐         ┌──────────────────┐
│  Client  │──HTTPS──→  HTTPS Listener  │  TLS required in ALL modes
└──────────┘         └────────┬─────────┘
                              │
                     ┌────────▼─────────┐
                     │  Request ID MW   │  Assigns/extracts X-Request-Id
                     ├──────────────────┤
                     │  Rate Limit MW   │  Guards: per-IP and per-token limits
                     ├──────────────────┤
                     │  Auth MW         │  Guardian #1: validates token, sets UserID
                     ├──────────────────┤
                     │  Policy MW       │  Guardian #2: evaluates RBAC permissions
                     ├──────────────────┤
                     │  Logging MW      │  Observer: structured request/response log
                     └────────┬─────────┘
                              │
                     ┌────────▼─────────┐
                     │    Handler       │  Guardian #3: ResolveRealm (tenant boundary)
                     └──────────────────┘

Path 2: Handler to Store (Go function call)

Handler calls store methods directly. Store enforces realm scoping on every query. Handlers can only access data within the resolved realm.

Path 3: Handler to Engine to Plugin Runtime to External System

┌──────────┐       ┌──────────┐       ┌─────────────┐       ┌───────────────┐       ┌────────────┐
│ Handler  │─call─→│ Registry │─call─→│ Plugin      │─host ─→│ Connection   │─proto─→│ External   │
│          │       │          │       │ Runtime     │  fn    │ Manager      │       │ System     │
│          │       │          │       │ (sandboxed) │       │ (SQL, HTTP)  │       │ (PG, AWS)  │
└──────────┘       └──────────┘       └─────────────┘       └───────────────┘       └────────────┘

The plugin code runs sandboxed inside the core process. It calls ctx.SQL() or ctx.HTTP(). These are host functions implemented by the core. The core's connection manager holds the actual database connections and HTTP clients. Root credentials never leave the core -- the plugin never sees them.

Path 4: Handler to Audit Dispatcher (Go channel, async)

Fire-and-forget via buffered channel. Uses context.Background(), not request context. Each sink (webhook, syslog, store) runs in its own goroutine.

Path 5: Core to Registry Service (HTTPS)

Registry client downloads packages and verifies signatures. No write access to registry from the core. Activation tokens sent for enterprise downloads.

The Six Guardians

#	Guardian	Location	What It Guards	Failure Mode
1	Auth Middleware	`internal/middleware/auth.go`	Identity -- is this a valid user?	401 Unauthorized
2	Policy Middleware	`internal/middleware/policy.go`	Authorization -- can this user do this action?	403 Forbidden
3	ResolveRealm	`internal/handler/realm_resolve.go`	Tenant boundary -- which realm?	404 Not Found
4	Plugin Runtime	`internal/plugin/runtime.go`	Sandbox -- plugin can only call declared host functions	501/502
5	Signature Verifier	`internal/plugin/signature.go`	Supply chain -- is this package authentic?	Plugin not loaded
6	Store Layer	`internal/store/*/`	Data boundary -- queries scoped to realm	No cross-realm leaks

Rule: No request path bypasses all six guardians. Every data-modifying operation passes through at least guardians 1, 2, 3, and 6. Engine operations add 4 and 5.

Entitlement Chain

Human/Client
  │
  ├── Authenticates with token
  │     Guardian: Auth Middleware
  │     Grants: identity (user_id, auth_method)
  │
  ├── Authorized by RBAC policy
  │     Guardian: Policy Middleware
  │     Grants: capabilities (secrets:read, leases:create, etc.)
  │
  ├── Scoped to realm
  │     Guardian: ResolveRealm
  │     Grants: realm_id (data boundary)
  │
  ├── Request reaches handler
  │     Guardian: Handler validation
  │     Grants: validated input → store/engine call
  │
  ├── Handler calls store
  │     Guardian: Store layer (realm scoping)
  │     Grants: CRUD within realm
  │
  ├── Handler calls engine registry
  │     Guardian: Plugin runtime (sandbox + capabilities)
  │     Grants: only declared host functions available
  │
  └── Plugin calls host function (ctx.SQL, ctx.HTTP)
        Guardian: Connection Manager
        Grants: connection to configured external system only
        Root credentials held by core, never exposed to plugin

SYSTEM ACTORS (no human identity):
  ├── Reaper: system-level, all realms, cleanup only
  └── Audit dispatcher: append-only, fire-and-forget

Communication Rights Matrix

From	To	Protocol	Auth	Entitlement	Guardian
Client	HTTPS Server	HTTPS (TLS always)	Bearer token	Identity	Auth MW
Auth MW	Store	Go call	System	Token lookup	Trusted path
Policy MW	Store	Go call	System	Role/binding lookup	Trusted path
Handler	Store	Go call	Authorized	CRUD within realm	Store scoping
Handler	Engine Registry	Go call	Authorized	Engine lookup	Registry
Handler	Audit Dispatcher	Go channel	Authorized	Emit events	Dispatcher
Registry	Plugin Runtime	Go call	Authorized	Sandboxed execution	Runtime sandbox
Plugin	Connection Mgr	Host function	Declared capability	SQL/HTTP to external system	Connection Mgr
Plugin	Store (plugin_data)	Host function	Declared capability	Scoped to engine_id + realm_id	Store scoping
Plugin	Audit	Host function	Declared capability	Emit events (tagged with plugin name)	Dispatcher
Reaper	Store	Go call	System	Cleanup expired data	Trusted path
Reaper	Engine Registry	Go call	System	Revoke expired leases	Runtime sandbox
Registry Client	Registry API	HTTPS	None / activation token	Download + verify	Signature verifier
Audit Dispatcher	Webhook Sink	HTTPS	HMAC signature	Deliver events	Sink retry
Audit Dispatcher	Syslog Sink	TCP/UDP	Network trust	Deliver events	Sink retry

Actors​

Communication Paths​

Path 1: Client to Core (HTTPS)​

Path 2: Handler to Store (Go function call)​

Path 3: Handler to Engine to Plugin Runtime to External System​

Path 4: Handler to Audit Dispatcher (Go channel, async)​

Path 5: Core to Registry Service (HTTPS)​

The Six Guardians​

Entitlement Chain​

Communication Rights Matrix​