@parmanasystems/server

Deployable Fastify HTTP server that exposes the Parmana governance runtime as a REST API. On startup it loads signing keys, constructs the runtime security context, initializes the replay store and audit database, and registers routes for execution, verification, audit, runtime inspection, and health checking. OpenAPI documentation is served at /documentation.

HTTP API

Authentication: Authorization: Bearer <PARMANA_API_KEY> when PARMANA_API_KEY is set. All routes are rate-limited (key by API key hash or IP).

Public API (library)

/**
 * Create and configure the Fastify server instance.
 * Registers CORS, Helmet, rate limiting, Swagger, audit middleware, and all routes.
 * Returns { app: FastifyInstance, auditDb?: AuditDb }.
 */
async function createServer(config?: ServerConfig): Promise<ServerInstance>

interface ServerConfig {
  signer?: Signer;
  verifier?: Verifier;
  publicKey?: string;
  runtimeManifest?: {
    runtimeVersion: string;
    runtimeHash: string;
    capabilities: readonly string[];
    supportedSchemaVersions: readonly string[];
  };
  signingKeySource?: string;
  runtimeEnvironment?: RuntimeEnvironment;
  replayStore?: ReplayStore;
}

interface ServerInstance {
  app: FastifyInstance;
  auditDb?: AuditDb;
}

/**
 * Build the runtime security context from environment variables.
 * Calls createSigningAuthority(), constructs a LocalVerifier, and loads
 * the runtime manifest. Called by packages/server/src/start.ts on boot.
 */
function getRuntimeSecurityContext(): RuntimeSecurityContext

interface RuntimeSecurityContext {
  signingKeySource: "env";
  publicKey: string;
  signer: SigningAuthority;
  verifier: LocalVerifier;
  runtimeManifest: RuntimeManifest;
}

type SigningKeySource = "env"

Docker

Build

# Multi-stage: builder (node:20-alpine) compiles monorepo, runtime stage strips dev deps.
# Build with:
docker build -f packages/server/Dockerfile -t parmana-server .

The Dockerfile copies policies/, trust/, and artifacts/ from the build context into the image. Signing keys are not baked into the image — they are bind-mounted at runtime.

Required bind-mount

The docker-compose default:

volumes:
  - D:/secure/parmana:/secure/parmana:ro

Set PARMANA_SIGNING_PRIVATE_KEY_PATH and PARMANA_SIGNING_PUBLIC_KEY_PATH to point inside this mount.

Environment variables

Package wiring

@parmanasystems/server depends on:

• @parmanasystems/execution-runtime — executeFromSignals, RedisReplayStore
• @parmanasystems/execution — LocalVerifier, confirmExecution, types
• @parmanasystems/verifier — verifyAttestationGoverned
• @parmanasystems/audit-db — AuditDb
• @parmanasystems/signing — createSigningAuthority
• fastify 5.8.5, @fastify/cors, @fastify/helmet, @fastify/rate-limit, @fastify/swagger