@graphorin/server 0.6.0 → 0.7.0

package/src/routes/index.ts

@@ -0,0 +1,16 @@
+/**
+ * REST route barrel.
+ *
+ * @packageDocumentation
+ */
+
+export { type AgentRoutesDeps, createAgentRoutes, createRunRoutes } from './agents.js';
+export { type AuditApi, type AuditRoutesDeps, createAuditRoutes } from './audit.js';
+export { type AuthRoutesDeps, createAuthRoutes } from './auth.js';
+export { createHealthRoutes, type HealthRoutesDeps } from './health.js';
+export { createMcpRoutes, type McpApi, type McpRoutesDeps } from './mcp.js';
+export { createMemoryRoutes, type MemoryApi, type MemoryRoutesDeps } from './memory.js';
+export { createSessionRoutes, type SessionApi, type SessionRoutesDeps } from './sessions.js';
+export { createSkillsRoutes, type SkillsApi, type SkillsRoutesDeps } from './skills.js';
+export { createTokensRoutes, type TokensRoutesDeps } from './tokens.js';
+export { createWorkflowRoutes, type WorkflowRoutesDeps } from './workflows.js';

package/src/routes/mcp.ts

@@ -0,0 +1,97 @@
+/**
+ * MCP server-management REST routes.
+ *
+ *   GET    /mcp/servers                (scope `mcp:admin`)
+ *   POST   /mcp/servers                (idempotent; scope `mcp:admin`)
+ *   DELETE /mcp/servers/:id            (scope `mcp:admin`)
+ *
+ * @packageDocumentation
+ */
+
+import type { Context } from 'hono';
+import { Hono } from 'hono';
+import { z } from 'zod';
+
+import type { ServerVariables } from '../internal/context.js';
+import { createScopeMiddleware } from '../middleware/scope.js';
+
+/**
+ * @stable
+ */
+export interface McpApi {
+  list(): Promise<ReadonlyArray<unknown>>;
+  register(input: {
+    readonly id: string;
+    readonly transport: string;
+    readonly url?: string;
+  }): Promise<unknown>;
+  remove(id: string): Promise<boolean>;
+}
+
+const RegisterBodySchema = z
+  .object({
+    id: z.string().min(1),
+    transport: z.enum(['stdio', 'streamable-http', 'sse']),
+    url: z.string().min(1).optional(),
+  })
+  .strict();
+
+/**
+ * @stable
+ */
+export interface McpRoutesDeps {
+  readonly mcp: McpApi;
+}
+
+/**
+ * @stable
+ */
+export function createMcpRoutes(deps: McpRoutesDeps): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+
+  app.get('/servers', createScopeMiddleware('mcp:admin'), async (c) => {
+    return c.json({ servers: await deps.mcp.list() });
+  });
+
+  app.post('/servers', createScopeMiddleware('mcp:admin'), async (c) => {
+    const parsed = RegisterBodySchema.safeParse(await safelyParseJson(c));
+    if (!parsed.success) {
+      return c.json(
+        {
+          error: 'config-invalid',
+          message: 'Invalid MCP server body.',
+          issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),
+        },
+        400,
+      );
+    }
+    const payload: { id: string; transport: string; url?: string } = {
+      id: parsed.data.id,
+      transport: parsed.data.transport,
+    };
+    if (parsed.data.url !== undefined) payload.url = parsed.data.url;
+    const out = await deps.mcp.register(payload);
+    return c.json({ server: out }, 201);
+  });
+
+  app.delete('/servers/:id', createScopeMiddleware('mcp:admin'), async (c) => {
+    const id = c.req.param('id');
+    const removed = await deps.mcp.remove(id);
+    if (!removed)
+      return c.json(
+        { error: 'mcp-server-not-found', message: `MCP server '${id}' not found.` },
+        404,
+      );
+    return c.body(null, 204);
+  });
+
+  return app;
+}
+
+async function safelyParseJson(c: Context<{ Variables: ServerVariables }>): Promise<unknown> {
+  try {
+    return await c.req.json();
+  } catch {
+    return {};
+  }
+}

package/src/routes/memory.ts

@@ -0,0 +1,152 @@
+/**
+ * Memory REST routes. The handlers delegate to a structurally-typed
+ * `MemoryApi` provided by the operator (in practice, a thin shim
+ * around `@graphorin/memory.createMemory({...})`).
+ *
+ *   POST   /memory/search              (scope `memory:read`)
+ *   POST   /memory/facts               (idempotent; scope `memory:write`)
+ *   DELETE /memory/facts/:id           (scope `memory:write`)
+ *   POST   /memory/blocks              (idempotent; scope `memory:write`)
+ *   DELETE /memory/blocks/:label       (scope `memory:write`)
+ *
+ * @packageDocumentation
+ */
+
+import type { Context } from 'hono';
+import { Hono } from 'hono';
+import { z } from 'zod';
+
+import type { ServerVariables } from '../internal/context.js';
+import { createScopeMiddleware } from '../middleware/scope.js';
+
+const ScopeSchema = z
+  .object({
+    userId: z.string().min(1),
+    agentId: z.string().min(1).optional(),
+    sessionId: z.string().min(1).optional(),
+  })
+  .strict();
+
+const SearchBodySchema = z
+  .object({
+    scope: ScopeSchema,
+    query: z.string().min(1),
+    topK: z.number().int().positive().max(200).optional(),
+  })
+  .strict();
+
+const RememberBodySchema = z
+  .object({
+    scope: ScopeSchema,
+    text: z.string().min(1),
+    sensitivity: z.enum(['public', 'internal', 'secret']).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+const BlockBodySchema = z
+  .object({
+    scope: ScopeSchema,
+    label: z.string().min(1),
+    body: z.string(),
+  })
+  .strict();
+
+/**
+ * @stable
+ */
+export interface MemoryApi {
+  search(input: z.infer<typeof SearchBodySchema>): Promise<ReadonlyArray<unknown>>;
+  remember(input: z.infer<typeof RememberBodySchema>): Promise<{ readonly factId: string }>;
+  forget(scope: { readonly userId: string }, factId: string): Promise<boolean>;
+  upsertBlock(input: z.infer<typeof BlockBodySchema>): Promise<{ readonly label: string }>;
+  deleteBlock(scope: { readonly userId: string }, label: string): Promise<boolean>;
+}
+
+/**
+ * @stable
+ */
+export interface MemoryRoutesDeps {
+  readonly memory: MemoryApi;
+}
+
+/**
+ * @stable
+ */
+export function createMemoryRoutes(deps: MemoryRoutesDeps): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+
+  app.post('/search', createScopeMiddleware('memory:read'), async (c) => {
+    const parsed = SearchBodySchema.safeParse(await safelyParseJson(c));
+    if (!parsed.success) {
+      return invalid(c, parsed.error.issues);
+    }
+    const hits = await deps.memory.search(parsed.data);
+    return c.json({ hits });
+  });
+
+  app.post('/facts', createScopeMiddleware('memory:write'), async (c) => {
+    const parsed = RememberBodySchema.safeParse(await safelyParseJson(c));
+    if (!parsed.success) return invalid(c, parsed.error.issues);
+    const out = await deps.memory.remember(parsed.data);
+    return c.json({ fact: out }, 201);
+  });
+
+  app.delete('/facts/:id', createScopeMiddleware('memory:write'), async (c) => {
+    const id = c.req.param('id');
+    const userId = c.req.query('userId');
+    if (userId === undefined || userId.length === 0) {
+      return c.json(
+        { error: 'config-invalid', message: 'Query parameter `userId` is required.' },
+        400,
+      );
+    }
+    const removed = await deps.memory.forget({ userId }, id);
+    if (!removed)
+      return c.json({ error: 'fact-not-found', message: `Fact '${id}' not found.` }, 404);
+    return c.body(null, 204);
+  });
+
+  app.post('/blocks', createScopeMiddleware('memory:write'), async (c) => {
+    const parsed = BlockBodySchema.safeParse(await safelyParseJson(c));
+    if (!parsed.success) return invalid(c, parsed.error.issues);
+    const out = await deps.memory.upsertBlock(parsed.data);
+    return c.json({ block: out }, 201);
+  });
+
+  app.delete('/blocks/:label', createScopeMiddleware('memory:write'), async (c) => {
+    const label = c.req.param('label');
+    const userId = c.req.query('userId');
+    if (userId === undefined || userId.length === 0) {
+      return c.json(
+        { error: 'config-invalid', message: 'Query parameter `userId` is required.' },
+        400,
+      );
+    }
+    const removed = await deps.memory.deleteBlock({ userId }, label);
+    if (!removed)
+      return c.json({ error: 'block-not-found', message: `Block '${label}' not found.` }, 404);
+    return c.body(null, 204);
+  });
+
+  return app;
+}
+
+function invalid(c: Context<{ Variables: ServerVariables }>, issues: ReadonlyArray<z.ZodIssue>) {
+  return c.json(
+    {
+      error: 'config-invalid',
+      message: 'Invalid request body.',
+      issues: issues.map((i) => ({ path: i.path, message: i.message })),
+    },
+    400,
+  );
+}
+
+async function safelyParseJson(c: Context<{ Variables: ServerVariables }>): Promise<unknown> {
+  try {
+    return await c.req.json();
+  } catch {
+    return {};
+  }
+}

package/src/routes/sessions.ts

@@ -0,0 +1,250 @@
+/**
+ * Session REST routes. Delegates to a structurally-typed `SessionApi`
+ * supplied by the operator (in practice, the `@graphorin/sessions`
+ * package's `SessionManager`); the contract is intentionally open so
+ * tests can stub it without dragging the full sessions facade in.
+ *
+ *   GET    /sessions                     (scope `sessions:read`)
+ *   GET    /sessions/:id                 (scope `sessions:read`)
+ *   POST   /sessions                     (idempotent; scope `sessions:write`)
+ *   DELETE /sessions/:id                 (scope `sessions:write`)
+ *   GET    /sessions/:id/messages        (scope `sessions:read`)
+ *   GET    /sessions/:id/handoffs        (scope `sessions:read`)
+ *   POST   /sessions/:id/export          (scope `sessions:export`)
+ *
+ * @packageDocumentation
+ */
+
+import type { Context } from 'hono';
+import { Hono } from 'hono';
+import { z } from 'zod';
+
+import type { ServerVariables } from '../internal/context.js';
+import { createScopeMiddleware } from '../middleware/scope.js';
+
+/**
+ * Minimal contract route handlers consume. Real deployments wire
+ * `@graphorin/sessions.SessionManager` in directly; tests pass a
+ * lighter stub.
+ *
+ * @stable
+ */
+export interface SessionApi {
+  list(opts: {
+    readonly userId?: string;
+    readonly agentId?: string;
+  }): Promise<ReadonlyArray<unknown>>;
+  get(sessionId: string): Promise<unknown | null>;
+  create(input: {
+    readonly userId: string;
+    readonly agentId: string;
+    readonly sessionId?: string;
+    readonly title?: string;
+    readonly tags?: ReadonlyArray<string>;
+  }): Promise<unknown>;
+  remove(sessionId: string): Promise<boolean>;
+  listMessages(
+    sessionId: string,
+    opts: { readonly limit?: number },
+  ): Promise<ReadonlyArray<unknown>>;
+  listHandoffs(sessionId: string): Promise<ReadonlyArray<unknown>>;
+  exportSession?(
+    sessionId: string,
+    opts: {
+      readonly includeAuditEntries?: boolean;
+      readonly hash?: boolean;
+    },
+  ): Promise<unknown>;
+  replaySession?(
+    sessionId: string,
+    opts: { readonly raw?: boolean; readonly fromMessageId?: string },
+  ): AsyncIterable<unknown>;
+}
+
+const CreateBodySchema = z
+  .object({
+    userId: z.string().min(1),
+    agentId: z.string().min(1),
+    sessionId: z.string().min(1).optional(),
+    title: z.string().min(1).optional(),
+    tags: z.array(z.string()).optional(),
+  })
+  .strict();
+
+const MessagesQuerySchema = z
+  .object({
+    limit: z.coerce.number().int().positive().max(1000).optional(),
+  })
+  .strict();
+
+const ExportBodySchema = z
+  .object({
+    includeAuditEntries: z.boolean().optional(),
+    hash: z.boolean().optional(),
+  })
+  .strict()
+  .default({});
+
+const _ReplayBodySchema = z
+  .object({
+    raw: z.boolean().optional(),
+    fromMessageId: z.string().min(1).optional(),
+  })
+  .strict()
+  .default({});
+
+/**
+ * @stable
+ */
+export interface SessionRoutesDeps {
+  readonly sessions: SessionApi;
+}
+
+/**
+ * @stable
+ */
+export function createSessionRoutes(deps: SessionRoutesDeps): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+
+  app.get('/', createScopeMiddleware('sessions:read'), async (c) => {
+    const userId = c.req.query('userId');
+    const agentId = c.req.query('agentId');
+    const filter: { userId?: string; agentId?: string } = {};
+    if (userId !== undefined && userId.length > 0) filter.userId = userId;
+    if (agentId !== undefined && agentId.length > 0) filter.agentId = agentId;
+    const list = await deps.sessions.list(filter);
+    return c.json({ sessions: list });
+  });
+
+  app.post('/', createScopeMiddleware('sessions:write'), async (c) => {
+    const parsed = CreateBodySchema.safeParse(await safelyParseJson(c));
+    if (!parsed.success) {
+      return c.json(
+        {
+          error: 'config-invalid',
+          message: 'Invalid session body.',
+          issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),
+        },
+        400,
+      );
+    }
+    const session = await deps.sessions.create({
+      userId: parsed.data.userId,
+      agentId: parsed.data.agentId,
+      ...(parsed.data.sessionId !== undefined ? { sessionId: parsed.data.sessionId } : {}),
+      ...(parsed.data.title !== undefined ? { title: parsed.data.title } : {}),
+      ...(parsed.data.tags !== undefined ? { tags: parsed.data.tags } : {}),
+    });
+    return c.json({ session }, 201);
+  });
+
+  // W-107: per-resource requirement - a token scoped to ONE session
+  // reads it on every surface (WS subjects already gated per-resource;
+  // wide two-segment grants keep covering three-segment requirements).
+  app.get(
+    '/:id',
+    createScopeMiddleware((_path, params) => `sessions:read:${params.id}`),
+    async (c) => {
+      const id = c.req.param('id');
+      const session = await deps.sessions.get(id);
+      if (session === null) {
+        return c.json({ error: 'session-not-found', message: `Session '${id}' not found.` }, 404);
+      }
+      return c.json({ session });
+    },
+  );
+
+  app.delete(
+    '/:id',
+    createScopeMiddleware((_path, params) => `sessions:write:${params.id}`),
+    async (c) => {
+      const id = c.req.param('id');
+      const removed = await deps.sessions.remove(id);
+      if (!removed) {
+        return c.json({ error: 'session-not-found', message: `Session '${id}' not found.` }, 404);
+      }
+      return c.body(null, 204);
+    },
+  );
+
+  app.get(
+    '/:id/messages',
+    createScopeMiddleware((_path, params) => `sessions:read:${params.id}`),
+    async (c) => {
+      const id = c.req.param('id');
+      const parsed = MessagesQuerySchema.safeParse({ limit: c.req.query('limit') });
+      if (!parsed.success) {
+        return c.json(
+          {
+            error: 'config-invalid',
+            message: 'Invalid messages query.',
+            issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),
+          },
+          400,
+        );
+      }
+      const opts: { limit?: number } = {};
+      if (parsed.data.limit !== undefined) opts.limit = parsed.data.limit;
+      const messages = await deps.sessions.listMessages(id, opts);
+      return c.json({ sessionId: id, messages });
+    },
+  );
+
+  app.get(
+    '/:id/handoffs',
+    createScopeMiddleware((_path, params) => `sessions:read:${params.id}`),
+    async (c) => {
+      const id = c.req.param('id');
+      const handoffs = await deps.sessions.listHandoffs(id);
+      return c.json({ sessionId: id, handoffs });
+    },
+  );
+
+  app.post(
+    '/:id/export',
+    createScopeMiddleware((_path, params) => `sessions:export:${params.id}`),
+    async (c) => {
+      const id = c.req.param('id');
+      if (deps.sessions.exportSession === undefined) {
+        return c.json(
+          { error: 'session-export-unsupported', message: 'Export is not enabled.' },
+          400,
+        );
+      }
+      const parsed = ExportBodySchema.safeParse(await safelyParseJson(c));
+      if (!parsed.success) {
+        return c.json(
+          {
+            error: 'config-invalid',
+            message: 'Invalid export body.',
+            issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),
+          },
+          400,
+        );
+      }
+      const exportOpts: { includeAuditEntries?: boolean; hash?: boolean } = {};
+      if (parsed.data.includeAuditEntries !== undefined) {
+        exportOpts.includeAuditEntries = parsed.data.includeAuditEntries;
+      }
+      if (parsed.data.hash !== undefined) exportOpts.hash = parsed.data.hash;
+      const result = await deps.sessions.exportSession(id, exportOpts);
+      return c.json({ sessionId: id, export: result });
+    },
+  );
+
+  // IP-14: the session-replay route lives in `replay/routes.ts` (the
+  // scope-laddered, audit-backed implementation). The Phase-14a stub
+  // that lived here SHADOWED it (mounted earlier on the same path)
+  // while advertising a `session:<id>/replay` subject the WS grammar
+  // cannot parse - deleted.
+
+  return app;
+}
+
+async function safelyParseJson(c: Context<{ Variables: ServerVariables }>): Promise<unknown> {
+  try {
+    return await c.req.json();
+  } catch {
+    return {};
+  }
+}

package/src/routes/skills.ts

@@ -0,0 +1,91 @@
+/**
+ * Skill REST routes.
+ *
+ *   GET    /skills                     (scope `skills:read`)
+ *   POST   /skills/install             (idempotent; scope `skills:install`)
+ *   GET    /skills/:name               (scope `skills:read`)
+ *
+ * @packageDocumentation
+ */
+
+import type { Context } from 'hono';
+import { Hono } from 'hono';
+import { z } from 'zod';
+
+import type { ServerVariables } from '../internal/context.js';
+import { createScopeMiddleware } from '../middleware/scope.js';
+
+/**
+ * @stable
+ */
+export interface SkillsApi {
+  list(): Promise<ReadonlyArray<{ readonly name: string; readonly version?: string }>>;
+  get(name: string): Promise<unknown | null>;
+  install(input: {
+    readonly source: string;
+    readonly trust?: 'verified' | 'unverified';
+  }): Promise<unknown>;
+}
+
+const InstallBodySchema = z
+  .object({
+    source: z.string().min(1),
+    trust: z.enum(['verified', 'unverified']).optional(),
+  })
+  .strict();
+
+/**
+ * @stable
+ */
+export interface SkillsRoutesDeps {
+  readonly skills: SkillsApi;
+}
+
+/**
+ * @stable
+ */
+export function createSkillsRoutes(deps: SkillsRoutesDeps): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+
+  app.get('/', createScopeMiddleware('skills:read'), async (c) => {
+    return c.json({ skills: await deps.skills.list() });
+  });
+
+  app.get('/:name', createScopeMiddleware('skills:read'), async (c) => {
+    const name = c.req.param('name');
+    const skill = await deps.skills.get(name);
+    if (skill === null)
+      return c.json({ error: 'skill-not-found', message: `Skill '${name}' not found.` }, 404);
+    return c.json({ skill });
+  });
+
+  app.post('/install', createScopeMiddleware('skills:install'), async (c) => {
+    const parsed = InstallBodySchema.safeParse(await safelyParseJson(c));
+    if (!parsed.success) {
+      return c.json(
+        {
+          error: 'config-invalid',
+          message: 'Invalid install body.',
+          issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),
+        },
+        400,
+      );
+    }
+    const installInput: { source: string; trust?: 'verified' | 'unverified' } = {
+      source: parsed.data.source,
+    };
+    if (parsed.data.trust !== undefined) installInput.trust = parsed.data.trust;
+    const out = await deps.skills.install(installInput);
+    return c.json({ skill: out }, 201);
+  });
+
+  return app;
+}
+
+async function safelyParseJson(c: Context<{ Variables: ServerVariables }>): Promise<unknown> {
+  try {
+    return await c.req.json();
+  } catch {
+    return {};
+  }
+}