@graphorin/server 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @graphorin/server
+
+## 0.1.0
+
+Initial release. See the workspace root `CHANGELOG.md` for the full
+release notes; the per-package changelog is generated by Changesets
+and tracks subsequent updates.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# @graphorin/server
+
+> Standalone server runtime for the [Graphorin](https://github.com/o-stepper/graphorin) framework.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node.js: 22+](https://img.shields.io/badge/Node.js-22%2B-43853d.svg)](https://nodejs.org)
+
+- **Version:** v0.5.0
+- **License:** [MIT](./LICENSE) (© 2026 Oleksiy Stepurenko)
+- **Repository:** <https://github.com/o-stepper/graphorin/tree/main/packages/server>
+- **Issues:** <https://github.com/o-stepper/graphorin/issues>
+
+## What ships in v0.1 (Phases 14a + 14b + 14c)
+
+`@graphorin/server` is the optional, first-class server runtime. Phase 14 is feature-complete: it ships the full HTTP surface, the lifecycle plumbing, the auth + scope + idempotency + audit middleware stack, the programmatic `createServer({...})` factory consumed by the `graphorin start` CLI binary in [`@graphorin/cli`](../cli/README.md), the `graphorin.protocol.v1` WebSocket transport with single-use ticket flow + per-subject replay buffer + delivery-layer commentary-phase trace sanitization, the Server-Sent-Events fallback for proxy-restricted clients, the durable triggers + consolidator daemon integration, the per-subsystem health rollup + `/v1/health/secrets` admin endpoint, the Prometheus `/v1/metrics` exposition, and the scope-enforced replay + audit verification endpoints.
+
+| Capability | Detail |
+|---|---|
+| **HTTP server** | Built on [`hono@^4.12.0`](https://hono.dev/) and [`@hono/node-server@^1.19.0`](https://github.com/honojs/node-server). |
+| **WebSocket** | Built on [`@hono/node-ws@^1.3.0`](https://github.com/honojs/middleware/tree/main/packages/node-ws); subprotocol `graphorin.protocol.v1`; bearer + ticket auth; per-subject replay buffer (default 1000 events / 5 min TTL); delivery-layer commentary-phase trace sanitization. Schemas live in [`@graphorin/protocol`](../protocol/README.md). |
+| **SSE fallback** | `GET /v1/sessions/:id/events` for non-WebSocket-friendly clients (corporate proxies, restricted networks). Same sanitization, same `Last-Event-ID` resume semantics. |
+| **Lifecycle hooks** | `beforeStart` → pre-bind validation → storage migrations → bind → triggers / consolidator daemons start → `onReady`; `SIGTERM` → `beforeShutdown` → daemons stop → drain → exit. |
+| **Pre-bind validation** | Resolves every `*Ref` field via `@graphorin/security` resolvers before binding the listener; missing pepper / unresolvable `SecretRef` / missing encryption peer fail fast with typed errors. |
+| **REST endpoints** | Agents (`run`, `stream`, `state`, `abort`, `resume`), workflows (`execute`, `resume`, `state`, `checkpoints`, `fork`), sessions, memory, skills, MCP, tokens, audit (`list`, `export`, `verify`), the `POST /v1/session/ws-ticket` browser ticket route, triggers (`list`, `get`, `fire`, `disable`, `prune`), replay (`runs/:runId/replay`, `sessions/:id/replay`), `/health`, `/health/secrets`, `/metrics`. Every side-effecting endpoint honours an `Idempotency-Key` per IETF draft-07. |
+| **Auth / scope** | `Authorization: Bearer kru_<env>_v1_<...>` (HMAC-SHA256 + pepper) wired through `TokenVerifier` from `@graphorin/security`. Per-route scope grammar `<resource>:<action>[:<id>]`. WebSocket upgrade honours both bearer and the single-use ticket flow. |
+| **Idempotency** | SQLite-backed `idempotency_records` + LRU read cache. Replays cached responses with `Idempotency-Replayed: true`; mismatched payloads return `409`. |
+| **CORS / CSRF / rate limit** | Deny-by-default CORS; double-submit CSRF for browser flows; sliding-window per-IP rate limit. |
+| **Audit middleware** | Forwards every authenticated request through `appendAudit` (`@graphorin/security/audit`) with attribution, route, status, and duration. `POST /v1/audit/verify` walks the SHA-256 hash chain and surfaces the integrity status. |
+| **Triggers daemon** | Wraps `@graphorin/triggers` `Scheduler`; `beforeStart` loads every persisted `trigger_state` row + applies the per-trigger `catchupPolicy`; `beforeShutdown` stops the scheduler. Cron / interval / idle / event triggers survive process restarts. |
+| **Consolidator daemon** | Lifecycle adapter for the `@graphorin/memory` consolidator runtime. Hard 10-second stop timeout so the daemon never hangs on a stuck phase. |
+| **Health rollup** | `/v1/health` returns `{ status, version, uptimeSeconds, checks: { storage, embedder, secrets, encryption, consolidator, triggers, replayBuffer } }`. HTTP 200 on `'degraded'` (warn); HTTP 503 on `'failing'`. |
+| **Secrets health** | `/v1/health/secrets` (scope `secrets:read`) returns the active store + fallback chain + downgrade reason per the secrets capability matrix. |
+| **Prometheus metrics** | `/v1/metrics` text exposition v0.0.4 with `graphorin_*` prefix discipline. The canonical inventory covers agent runs, tool calls, provider tokens / cost, WAL size, idempotency hit ratio, trigger fires, redaction drops, consolidator queue depth / DLQ / budget, OAuth token freshness, replay buffer size, in-flight runs, server uptime, and a static `graphorin_build_info` gauge. |
+| **Replay endpoints** | `POST /v1/runs/:runId/replay` and `POST /v1/sessions/:id/replay` enforce `traces:read:sanitized` (default) or `traces:read:raw` (admin); every invocation appends an audit chain entry. |
+| **Graceful shutdown** | Drains in-flight runs within the configured timeout (default 30 s), preserves run state via `RunStateTracker`, propagates `AbortSignal` cancellation to handlers, tears down WebSocket subscriptions cleanly. |
+| **No phone home** | Zero implicit network calls — verified by the repository-wide `pnpm run check-no-network` CI check. |
+
+## Out of scope for Phase 14
+
+- Multi-tenant runtime — **v0.3+**.
+- OpenTelemetry metrics export (in addition to Prometheus) — post-MVP.
+
+## Install
+
+```bash
+pnpm add @graphorin/server @graphorin/security @graphorin/store-sqlite \
+  @graphorin/protocol @graphorin/triggers hono @hono/node-server @hono/node-ws
+```
+
+> Other npm-registry-compatible package managers (`npm`, `yarn`, `bun`) work identically; the project itself is developed with [pnpm](https://pnpm.io/).
+
+## Programmatic usage
+
+```ts
+import { createServer, defineConfig } from '@graphorin/server';
+
+const server = await createServer({
+  config: defineConfig({
+    server: { host: '127.0.0.1', port: 8080 },
+    auth: { kind: 'token', pepperRef: 'keyring:graphorin_server_pepper' },
+    storage: { path: './.graphorin/data.db', mode: 'server' },
+  }),
+});
+
+server.agents.register({
+  id: 'echo',
+  description: 'Echoes its input back to the caller.',
+  agent: {
+    id: 'echo',
+    async run(input) {
+      return { input };
+    },
+  },
+});
+
+const { host, port } = await server.start();
+console.error(`graphorin listening on http://${host}:${port}/v1`);
+```
+
+## CLI
+
+The `graphorin start` / `graphorin init` / `graphorin migrate` CLI ships from [`@graphorin/cli`](../cli/README.md).
+
+## Configuration
+
+Every field in `defineConfig({...})` is optional and falls back to a documented production-ready default. The full schema (Zod) is exported as `ServerConfigSchema` from `@graphorin/server/config` so operators can compose validation pipelines on top of the framework.
+
+The most-frequently-touched options:
+
+| Field | Default | Notes |
+|---|---|---|
+| `server.host` | `127.0.0.1` | Bind to `0.0.0.0` only behind a reverse proxy. |
+| `server.port` | `8080` | |
+| `server.basePath` | `/v1` | |
+| `server.idempotency.requireKey` | `'warn'` | `'enforce'` is opt-in for production. |
+| `server.idempotency.ttlSeconds` | `86400` | 24 hours. |
+| `server.cors.allowOrigins` | `[]` | Deny by default; pass an explicit allowlist (or `['*']`). |
+| `server.csrf.enabled` | `true` | Bearer-token requests are exempt. |
+| `server.rateLimit.perIpRequests` | `60` | Per minute. |
+| `server.shutdown.drainTimeoutMs` | `30000` | |
+| `auth.kind` | `'token'` | Set to `'none'` only for trusted loopback environments. |
+| `auth.pepperRef` | _(required for token auth)_ | A `SecretRef` pointing at the HMAC pepper. |
+| `storage.path` | `'./.graphorin/data.db'` | |
+| `storage.encryption.enabled` | `false` | Opt-in SQLCipher v4 via the `better-sqlite3-multiple-ciphers` peer. |
+| `audit.enabled` | `false` | Opt-in mandatory-encrypted audit log per DEC-124. |
+| `metrics.enabled` | `true` | Mounts `/v1/metrics` for Prometheus scraping. |
+| `metrics.requireAuth` | `false` | Opt into the `admin:metrics:read` scope for stricter deployments. |
+| `health.walWarnThresholdBytes` | `52428800` | 50 MB; storage check flips to `'warn'` above this. |
+
+## Status
+
+`@graphorin/server` is part of the Graphorin framework's `v0.5.0` pre-release. Once published, the package follows the lockstep release cadence shared by every `@graphorin/*` package on the `0.x` line.
+
+---
+
+**Project Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/app.d.ts

@@ -0,0 +1,174 @@
+import { ServerConfigInput, ServerConfigSpec } from "./config.js";
+import { ConsolidatorDaemon, ConsolidatorLike } from "./consolidator/daemon.js";
+import { TriggersDaemon } from "./triggers/daemon.js";
+import { HealthCheckOptions } from "./health/checks.js";
+import { ServerVariables } from "./internal/context.js";
+import { MetricRegistry } from "./metrics/registry.js";
+import "./health/index.js";
+import { LifecycleHooks } from "./lifecycle/hooks.js";
+import "./lifecycle/index.js";
+import { AgentRegistry, WorkflowRegistry } from "./registry/index.js";
+import { ReplayApi } from "./replay/routes.js";
+import "./replay/index.js";
+import { WsDispatcher } from "./ws/dispatcher.js";
+import { RunStateTracker } from "./runtime/run-state.js";
+import { AuditApi } from "./routes/audit.js";
+import { WsTicketStore } from "./ws/ticket.js";
+import { McpApi } from "./routes/mcp.js";
+import { MemoryApi } from "./routes/memory.js";
+import { SessionApi } from "./routes/sessions.js";
+import { SkillsApi } from "./routes/skills.js";
+import "./routes/index.js";
+import "./ws/index.js";
+import { GraphorinSqliteStore } from "@graphorin/store-sqlite";
+import { Hono } from "hono";
+import * as _graphorin_triggers0 from "@graphorin/triggers";
+
+//#region src/app.d.ts
+
+declare function ensureStoreAuditBinding(): void;
+/**
+ * Public surface returned by {@link createServer}.
+ *
+ * @stable
+ */
+interface GraphorinServer {
+  readonly version: string;
+  readonly config: ServerConfigSpec;
+  readonly app: Hono<{
+    Variables: ServerVariables;
+  }>;
+  readonly agents: AgentRegistry;
+  readonly workflows: WorkflowRegistry;
+  readonly runs: RunStateTracker;
+  readonly listeningOn: {
+    readonly host: string;
+    readonly port: number;
+  } | undefined;
+  /**
+   * Optional WebSocket dispatcher exposed when `server.ws.enabled =
+   * true`. Route handlers + the agent / workflow runtimes call
+   * `dispatcher.emit(subject, event)` to fan out events to subscribed
+   * clients. Returns `undefined` when WS is disabled.
+   */
+  readonly wsDispatcher: WsDispatcher | undefined;
+  /**
+   * Optional WebSocket ticket store exposed when `server.ws.enabled
+   * = true`. Surfaced primarily for tests; the
+   * `POST /v1/session/ws-ticket` route uses it transparently.
+   */
+  readonly wsTickets: WsTicketStore | undefined;
+  /**
+   * Optional triggers daemon — populated when the operator wired a
+   * scheduler (or an in-process trigger surface) at construction
+   * time. Phase 14c integration.
+   */
+  readonly triggers: TriggersDaemon | undefined;
+  /**
+   * Optional consolidator daemon — populated when the operator
+   * supplied a `Consolidator` instance via `createServer({
+   * consolidator })`. Phase 14c integration.
+   */
+  readonly consolidator: ConsolidatorDaemon | undefined;
+  /**
+   * Phase 14c Prometheus registry. Always present; sample updates
+   * are observable via `metrics.snapshot()`.
+   */
+  readonly metrics: MetricRegistry;
+  start(): Promise<{
+    readonly host: string;
+    readonly port: number;
+  }>;
+  stop(options?: {
+    readonly force?: boolean;
+  }): Promise<void>;
+}
+/**
+ * Discriminated union accepted by `CreateServerOptions.triggers`. A
+ * caller may either supply a fully-built daemon (e.g. constructed
+ * around a custom `Scheduler`) or just the underlying scheduler — the
+ * server wraps it with {@link createTriggersDaemon} automatically.
+ *
+ * @stable
+ */
+type TriggersDaemonInput = {
+  readonly daemon: TriggersDaemon;
+} | {
+  readonly scheduler: _graphorin_triggers0.Scheduler;
+};
+/**
+ * @stable
+ */
+interface CreateServerOptions {
+  /** Loaded `graphorin.config.ts` payload — see `defineConfig({...})`. */
+  readonly config?: ServerConfigInput;
+  /**
+   * Optional pre-validated config. When supplied, `config` is ignored
+   * and the schema validation step is skipped. Useful for tests + the
+   * `graphorin migrate` CLI command which bypasses the listener.
+   */
+  readonly validatedConfig?: ServerConfigSpec;
+  /** Pre-built SQLite store. Tests inject an in-memory store. */
+  readonly store?: GraphorinSqliteStore;
+  /** Optional pre-built tracker. Tests inject deterministic timing. */
+  readonly runs?: RunStateTracker;
+  /** Optional pre-built registries. */
+  readonly agents?: AgentRegistry;
+  readonly workflows?: WorkflowRegistry;
+  /** Optional in-process domain adapters wired into REST routes. */
+  readonly sessions?: SessionApi;
+  readonly memory?: MemoryApi;
+  readonly skills?: SkillsApi;
+  readonly mcp?: McpApi;
+  readonly audit?: AuditApi;
+  /**
+   * Optional consolidator surface (`@graphorin/memory`). Phase 14c
+   * starts/stops the runtime alongside the server lifecycle and
+   * surfaces its status through `/v1/health`.
+   */
+  readonly consolidator?: ConsolidatorLike;
+  /**
+   * Optional triggers daemon — pass an existing one (e.g. built
+   * from `createScheduler`) or a triggers configuration the server
+   * should wrap with the daemon adapter.
+   */
+  readonly triggers?: TriggersDaemonInput;
+  /**
+   * Optional replay API consumed by the scope-enforced replay
+   * endpoints. Phase 14c.
+   */
+  readonly replay?: ReplayApi;
+  /**
+   * Optional probes that augment `/v1/health`. Provided by consumer
+   * code (e.g. `embedder` provides `embedderLoaded`).
+   */
+  readonly healthProbes?: () => HealthCheckOptions | Promise<HealthCheckOptions>;
+  /**
+   * Optional Prometheus metric registry override. When omitted, the
+   * server constructs the canonical registry from
+   * {@link createServerMetricRegistry}.
+   */
+  readonly metricRegistry?: MetricRegistry;
+  /** Lifecycle hook overrides. */
+  readonly hooks?: LifecycleHooks;
+  /** Wall-clock provider for tests. */
+  readonly now?: () => number;
+  /** Override the cipher peer probe. Tests inject a stub. */
+  readonly probeCipherPeer?: () => Promise<void>;
+  /** Override the package version reported on `/v1/health`. */
+  readonly version?: string;
+  /** Skip `applyProcessHardening` (tests). */
+  readonly skipHardening?: boolean;
+  /** Skip starting the actual listener (tests). */
+  readonly skipListen?: boolean;
+}
+/**
+ * Build a fully-wired Graphorin server. The returned handle is
+ * inert until `start()` is awaited.
+ *
+ * @stable
+ */
+declare function createServer(options?: CreateServerOptions): Promise<GraphorinServer>;
+//#endregion
+export { CreateServerOptions, GraphorinServer, TriggersDaemonInput, createServer, ensureStoreAuditBinding };
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","names":[],"sources":["../src/app.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmQiB,iBAxJD,uBAAA,CAAA,CAwJgB,EAAA,IAAA;;;;;;AAMf,UANA,eAAA,CAMA;EAQQ,SAAA,OAAA,EAAA,MAAA;EAMH,SAAA,MAAA,EAlBH,gBAkBG;EAMD,SAAA,GAAA,EAvBL,IAuBK,CAAA;IAMI,SAAA,EA7BS,eA6BT;EAKL,CAAA,CAAA;EACT,SAAA,MAAA,EAlCQ,aAkCR;EACqC,SAAA,SAAA,EAlC1B,gBAkC0B;EAAO,SAAA,IAAA,EAjCtC,eAiCsC;EAW3C,SAAA,WAAA,EAAmB;IAOd,SAAA,IAAA,EAAA,MAAmB;IAEhB,SAAA,IAAA,EAAA,MAAA;EAMS,CAAA,GAAA,SAAA;EAEV;;;;;;EASC,SAAA,YAAA,EA9DK,YA8DL,GAAA,SAAA;EACH;;;;;EAuBe,SAAA,SAAA,EAhFV,aAgFU,GAAA,SAAA;EAA6B;;;;;EAYnB,SAAA,QAAA,EAtFrB,cAsFqB,GAAA,SAAA;EAoBpB;;;;;yBApGG;;;;;oBAKL;WACT;;;;;;MACqC;;;;;;;;;;KAWpC,mBAAA;mBACW;;sBAAc,oBAAA,CACmB;;;;;UAKvC,mBAAA;;oBAEG;;;;;;6BAMS;;mBAEV;;kBAED;;oBAEE;uBACG;;sBAED;oBACF;oBACA;iBACH;mBACE;;;;;;0BAMO;;;;;;sBAMJ;;;;;oBAKF;;;;;gCAKY,qBAAqB,QAAQ;;;;;;4BAMjC;;mBAET;;;;mCAIgB;;;;;;;;;;;;;;iBAoBb,YAAA,WAAsB,sBAA2B,QAAQ"}