@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

| Method | Path | Description | |--------|------|-------------| | POST | /execute | Run deterministic governance execution. Returns a signed ExecutionAttestation. | | POST | /verify | Independently verify an ExecutionAttestation. Returns VerificationResult. | | POST | /confirm-execution | Prove that a real action matched its governance authorization. Returns ExecutionIntegrityProof. | | POST | /evaluate | Dry-run policy evaluation — no attestation, no replay entry, no side effects. | | POST | /simulate | Full pipeline dry-run with attestation preview. | | GET | /health | Runtime health, signing mode, capabilities, audit DB status. | | GET | /runtime/manifest | Current runtime manifest (version, hash, capabilities). | | GET | /runtime/capabilities | Runtime capability list. | | GET | /audit/decisions | Paginated governance decision timeline (requires AUDIT_DATABASE_URL). | | GET | /audit/decisions/:id | Single decision detail by execution ID. | | GET | /audit/stats | Aggregate decision/verification/event counts. | | GET | /audit/security | Security event dashboard. | | GET | /documentation | Swagger UI (OpenAPI 3.0.3). |

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

| Variable | Required | Description | |---|---|---| | PARMANA_SIGNING_PRIVATE_KEY_PATH | Yes | Ed25519 PKCS8 private key PEM path (in container). | | PARMANA_SIGNING_PUBLIC_KEY_PATH | Yes | Ed25519 SPKI public key PEM path (in container). | | PARMANA_SIGNING_PROVIDER | No | local (default). | | PARMANA_POLICIES_ROOT | Yes | Policy bundles root directory. | | PARMANA_TRUST_ROOT | Yes | Path to trust-root.json. | | PARMANA_TRUST_PUBLIC_KEY | Yes | Path to trust root public key PEM. | | PARMANA_RELEASE_MANIFEST | Yes | Path to release-manifest.json. | | PARMANA_RELEASE_SIGNATURE | Yes | Path to release-manifest.sig. | | REDIS_URL | Yes | Redis connection string for replay protection. | | AUDIT_DATABASE_URL | No | PostgreSQL DSN. If unset, audit routes are absent. | | PARMANA_API_KEY | No | Bearer token for API auth. Omit for dev mode. | | PORT | No | Listen port. Default: 3000. | | HOST | No | Bind address. Default: 0.0.0.0. | | CORS_ORIGIN | No | Allowed CORS origins. Default: http://localhost:5173,http://localhost:8080. | | LOG_LEVEL | No | Pino log level. Default: info in production, debug otherwise. | | NODE_ENV | No | production tightens defaults (log level, etc.). |

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