slackhive 0.1.37 → 0.1.39

package/apps/web/src/app/api/agents/[id]/route.ts

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview REST API route for a single agent resource.
+ *
+ * GET    /api/agents/[id] — Get agent by ID
+ * PATCH  /api/agents/[id] — Update agent config
+ * DELETE /api/agents/[id] — Remove agent
+ *
+ * @module web/api/agents/[id]
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getAgentById, updateAgent, deleteAgent, publishAgentEvent } from '@/lib/db';
+import type { UpdateAgentRequest } from '@slackhive/shared';
+import { regenerateBossRegistry } from '@/lib/boss-registry';
+import { guardAgentWrite, guardUserAdmin } from '@/lib/api-guard';
+
+type RouteParams = { params: Promise<{ id: string }> };
+
+/**
+ * GET /api/agents/[id]
+ *
+ * @param {NextRequest} _req
+ * @param {RouteParams} ctx
+ * @returns {Promise<NextResponse>} Agent JSON or 404.
+ */
+export async function GET(_req: NextRequest, { params }: RouteParams): Promise<NextResponse> {
+  try {
+    const { id } = await params;
+    const agent = await getAgentById(id);
+    if (!agent) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+    return NextResponse.json(agent);
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}
+
+/**
+ * PATCH /api/agents/[id]
+ * Updates mutable agent fields and triggers a reload event.
+ *
+ * @param {NextRequest} req - Partial UpdateAgentRequest body.
+ * @param {RouteParams} ctx
+ * @returns {Promise<NextResponse>} Updated agent JSON or error.
+ */
+export async function PATCH(req: NextRequest, { params }: RouteParams): Promise<NextResponse> {
+  try {
+    const { id } = await params;
+    const denied = await guardAgentWrite(req, id);
+    if (denied) return denied;
+    const body = (await req.json()) as Partial<UpdateAgentRequest>;
+    const updated = await updateAgent(id, body);
+    if (!updated) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+    await publishAgentEvent({ type: 'reload', agentId: id });
+    await regenerateBossRegistry().catch(() => {});
+    return NextResponse.json(updated);
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}
+
+/**
+ * DELETE /api/agents/[id]
+ * Removes an agent and publishes a stop event before deletion.
+ *
+ * @param {NextRequest} _req
+ * @param {RouteParams} ctx
+ * @returns {Promise<NextResponse>} 204 No Content or error.
+ */
+export async function DELETE(req: NextRequest, { params }: RouteParams): Promise<NextResponse> {
+  try {
+    const { id } = await params;
+    const denied = guardUserAdmin(req);
+    if (denied) return denied;
+    await publishAgentEvent({ type: 'stop', agentId: id });
+    await deleteAgent(id);
+    await regenerateBossRegistry().catch(() => {});
+    return new NextResponse(null, { status: 204 });
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}

package/apps/web/src/app/api/agents/[id]/skills/[skillId]/route.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview DELETE /api/agents/[id]/skills/[skillId]
+ * Removes a skill file and triggers a reload event.
+ *
+ * @module web/api/agents/[id]/skills/[skillId]
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { deleteSkill, publishAgentEvent, getAgentById, getAgentSkills, getAgentPermissions, getAgentMcpServers, createSnapshot } from '@/lib/db';
+import { guardAgentWrite } from '@/lib/api-guard';
+import { getSessionFromRequest } from '@/lib/auth';
+import { skillToSnapshotSkill } from '@/lib/compile';
+
+type RouteParams = { params: Promise<{ id: string; skillId: string }> };
+
+/**
+ * DELETE /api/agents/[id]/skills/[skillId]
+ *
+ * @param {NextRequest} _req
+ * @param {RouteParams} ctx
+ * @returns {Promise<NextResponse>} 204 No Content or error.
+ */
+export async function DELETE(req: NextRequest, { params }: RouteParams): Promise<NextResponse> {
+  try {
+    const { id, skillId } = await params;
+    const denied = await guardAgentWrite(req, id);
+    if (denied) return denied;
+
+    // Snapshot before deletion
+    const session = getSessionFromRequest(req);
+    const [agent, currentSkills, perms, mcps] = await Promise.all([
+      getAgentById(id),
+      getAgentSkills(id),
+      getAgentPermissions(id),
+      getAgentMcpServers(id),
+    ]);
+    await createSnapshot(
+      id, 'skills', session?.username ?? 'system', null,
+      currentSkills.map(skillToSnapshotSkill),
+      perms?.allowedTools ?? [],
+      perms?.deniedTools ?? [],
+      mcps.map(m => m.id),
+      agent?.claudeMd ?? '',
+    ).catch(() => {});
+
+    await deleteSkill(skillId);
+    await publishAgentEvent({ type: 'reload', agentId: id });
+    return new NextResponse(null, { status: 204 });
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}

package/apps/web/src/app/api/agents/[id]/skills/route.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview REST API routes for agent skills.
+ *
+ * GET  /api/agents/[id]/skills — List all skills for an agent
+ * POST /api/agents/[id]/skills — Create or update a skill, then trigger reload
+ *
+ * @module web/api/agents/[id]/skills
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getAgentById, getAgentSkills, upsertSkill, publishAgentEvent, getAgentPermissions, getAgentMcpServers, createSnapshot } from '@/lib/db';
+import type { UpsertSkillRequest } from '@slackhive/shared';
+import { guardAgentWrite } from '@/lib/api-guard';
+import { getSessionFromRequest } from '@/lib/auth';
+import { skillToSnapshotSkill } from '@/lib/compile';
+
+type RouteParams = { params: Promise<{ id: string }> };
+
+/**
+ * GET /api/agents/[id]/skills
+ *
+ * @param {NextRequest} _req
+ * @param {RouteParams} ctx
+ * @returns {Promise<NextResponse>} JSON array of Skill objects.
+ */
+export async function GET(_req: NextRequest, { params }: RouteParams): Promise<NextResponse> {
+  try {
+    const { id } = await params;
+    const skills = await getAgentSkills(id);
+    return NextResponse.json(skills);
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}
+
+/**
+ * POST /api/agents/[id]/skills
+ * Creates or updates a skill file, then publishes a reload event.
+ *
+ * @param {NextRequest} req - Body: { category, filename, content, sortOrder? }
+ * @param {RouteParams} ctx
+ * @returns {Promise<NextResponse>} The upserted Skill or error.
+ */
+export async function POST(req: NextRequest, { params }: RouteParams): Promise<NextResponse> {
+  try {
+    const { id } = await params;
+    const denied = await guardAgentWrite(req, id);
+    if (denied) return denied;
+    const body = (await req.json()) as UpsertSkillRequest & { category: string; filename: string };
+    if (!body.category || !body.filename || body.content === undefined) {
+      return NextResponse.json({ error: 'category, filename, content are required' }, { status: 400 });
+    }
+
+    // Snapshot current state before mutation (skip during bulk import)
+    const noSnapshot = req.nextUrl.searchParams.get('noSnapshot') === '1';
+    if (!noSnapshot) {
+      const session = getSessionFromRequest(req);
+      const [agent, currentSkills, perms, mcps] = await Promise.all([
+        getAgentById(id),
+        getAgentSkills(id),
+        getAgentPermissions(id),
+        getAgentMcpServers(id),
+      ]);
+      await createSnapshot(
+        id, 'skills', session?.username ?? 'system', null,
+        currentSkills.map(skillToSnapshotSkill),
+        perms?.allowedTools ?? [],
+        perms?.deniedTools ?? [],
+        mcps.map(m => m.id),
+        agent?.claudeMd ?? '',
+      ).catch(() => {});
+    }
+
+    const skill = await upsertSkill(id, body.category, body.filename, body.content, body.sortOrder ?? 0);
+    await publishAgentEvent({ type: 'reload', agentId: id });
+    return NextResponse.json(skill, { status: 201 });
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}

package/apps/web/src/app/api/agents/[id]/slack-info/route.ts

@@ -0,0 +1,38 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getAgentById } from '@/lib/db';
+
+/**
+ * GET /api/agents/[id]/slack-info
+ * Fetches live bot display name and @handle from Slack using the agent's bot token.
+ */
+export async function GET(
+  _req: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+): Promise<NextResponse> {
+  try {
+    const { id } = await params;
+    const agent = await getAgentById(id);
+    if (!agent?.slackBotToken) return NextResponse.json({ error: 'No bot token' }, { status: 400 });
+
+    const authRes = await fetch('https://slack.com/api/auth.test', {
+      headers: { Authorization: `Bearer ${agent.slackBotToken}` },
+    });
+    const auth = await authRes.json();
+    if (!auth.ok) return NextResponse.json({ error: auth.error }, { status: 400 });
+
+    const userRes = await fetch(`https://slack.com/api/users.info?user=${auth.user_id}`, {
+      headers: { Authorization: `Bearer ${agent.slackBotToken}` },
+    });
+    const userData = await userRes.json();
+    const profile = userData?.user?.profile;
+
+    return NextResponse.json({
+      displayName: profile?.display_name || profile?.real_name || auth.user,
+      handle:      auth.user,
+      botId:       auth.bot_id,
+      teamName:    auth.team,
+    });
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}

package/apps/web/src/app/api/agents/[id]/snapshots/[sid]/restore/route.ts

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Restore an agent to a previous snapshot.
+ *
+ * POST /api/agents/[id]/snapshots/[sid]/restore
+ *
+ * Replaces the agent's current skills, permissions, and MCP assignments
+ * with the state captured in the snapshot, then triggers a runner reload.
+ *
+ * @module web/api/agents/[id]/snapshots/[sid]/restore
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  getSnapshotById,
+  deleteSkillsByAgent,
+  upsertSkill,
+  upsertPermissions,
+  setAgentMcps,
+  publishAgentEvent,
+} from '@/lib/db';
+import { guardAgentWrite } from '@/lib/api-guard';
+
+/**
+ * POST /api/agents/[id]/snapshots/[sid]/restore
+ * Restores an agent to the state captured in a snapshot.
+ *
+ * @returns {Promise<NextResponse>} 200 { ok: true } or error.
+ */
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string; sid: string }> }
+): Promise<NextResponse> {
+  try {
+    const { id, sid } = await params;
+    const denied = await guardAgentWrite(request, id);
+    if (denied) return denied;
+
+    const snapshot = await getSnapshotById(sid);
+    if (!snapshot) return NextResponse.json({ error: 'Snapshot not found' }, { status: 404 });
+    if (snapshot.agentId !== id) return NextResponse.json({ error: 'Snapshot does not belong to this agent' }, { status: 400 });
+
+    // Replace skills
+    await deleteSkillsByAgent(id);
+    for (const s of snapshot.skillsJson) {
+      await upsertSkill(id, s.category, s.filename, s.content, s.sort_order);
+    }
+
+    // Replace permissions
+    await upsertPermissions(id, snapshot.allowedTools, snapshot.deniedTools);
+
+    // Replace MCP assignments
+    await setAgentMcps(id, snapshot.mcpIds);
+
+    // Trigger runner reload
+    await publishAgentEvent({ type: 'reload', agentId: id });
+
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}

package/apps/web/src/app/api/agents/[id]/snapshots/[sid]/route.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview REST API routes for a single agent snapshot.
+ *
+ * GET    /api/agents/[id]/snapshots/[sid] — Get full snapshot (including compiledMd)
+ * DELETE /api/agents/[id]/snapshots/[sid] — Delete snapshot
+ *
+ * @module web/api/agents/[id]/snapshots/[sid]
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getSnapshotById, deleteSnapshot } from '@/lib/db';
+import { guardAgentWrite } from '@/lib/api-guard';
+
+/**
+ * GET /api/agents/[id]/snapshots/[sid]
+ * Returns the full snapshot including compiledMd.
+ *
+ * @returns {Promise<NextResponse>} AgentSnapshot or 404.
+ */
+export async function GET(
+  _req: NextRequest,
+  { params }: { params: Promise<{ id: string; sid: string }> }
+): Promise<NextResponse> {
+  try {
+    const { sid } = await params;
+    const snapshot = await getSnapshotById(sid);
+    if (!snapshot) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+    return NextResponse.json(snapshot);
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}
+
+/**
+ * DELETE /api/agents/[id]/snapshots/[sid]
+ * Permanently deletes a snapshot.
+ *
+ * @returns {Promise<NextResponse>} 204 No Content.
+ */
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string; sid: string }> }
+): Promise<NextResponse> {
+  try {
+    const { id, sid } = await params;
+    const denied = await guardAgentWrite(request, id);
+    if (denied) return denied;
+    await deleteSnapshot(sid);
+    return new NextResponse(null, { status: 204 });
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}

package/apps/web/src/app/api/agents/[id]/snapshots/route.ts

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview REST API routes for agent snapshot collection.
+ *
+ * GET  /api/agents/[id]/snapshots — List all snapshots for an agent
+ * POST /api/agents/[id]/snapshots — Create a manual snapshot
+ *
+ * @module web/api/agents/[id]/snapshots
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  getAgentById,
+  getAgentSkills,
+  getAgentPermissions,
+  getAgentMcpServers,
+  listSnapshots,
+  createSnapshot,
+} from '@/lib/db';
+import { guardAgentWrite } from '@/lib/api-guard';
+import { getSessionFromRequest } from '@/lib/auth';
+import { skillToSnapshotSkill } from '@/lib/compile';
+
+/**
+ * GET /api/agents/[id]/snapshots
+ * Returns all snapshots for an agent, newest first.
+ *
+ * @returns {Promise<NextResponse>} JSON array of AgentSnapshot objects.
+ */
+export async function GET(
+  _req: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+): Promise<NextResponse> {
+  try {
+    const { id } = await params;
+    const snapshots = await listSnapshots(id);
+    // Omit compiledMd from list view to keep payload small
+    return NextResponse.json(snapshots.map(s => ({ ...s, compiledMd: undefined })));
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}
+
+/**
+ * POST /api/agents/[id]/snapshots
+ * Creates a manual snapshot of the agent's current configuration.
+ *
+ * @param {NextRequest} request - Body: { label?: string }
+ * @returns {Promise<NextResponse>} The created AgentSnapshot (201).
+ */
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+): Promise<NextResponse> {
+  try {
+    const { id } = await params;
+    const denied = await guardAgentWrite(request, id);
+    if (denied) return denied;
+    const agent = await getAgentById(id);
+    if (!agent) return NextResponse.json({ error: 'Agent not found' }, { status: 404 });
+
+    const body = await request.json().catch(() => ({}));
+    const label: string | null = body.label ?? null;
+
+    const session = getSessionFromRequest(request);
+    const [skills, perms, mcps] = await Promise.all([
+      getAgentSkills(id),
+      getAgentPermissions(id),
+      getAgentMcpServers(id),
+    ]);
+
+    const snapshot = await createSnapshot(
+      id, 'manual', session?.username ?? 'system', label,
+      skills.map(skillToSnapshotSkill),
+      perms?.allowedTools ?? [],
+      perms?.deniedTools ?? [],
+      mcps.map(m => m.id),
+      agent?.claudeMd ?? '',
+    );
+
+    return NextResponse.json(snapshot, { status: 201 });
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}

package/apps/web/src/app/api/agents/[id]/start/route.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview POST /api/agents/[id]/start
+ * Publishes a start event so the runner spins up the agent's Bolt app.
+ *
+ * @module web/api/agents/[id]/start
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getAgentById, updateAgentStatus, updateAgentEnabled, publishAgentEvent } from '@/lib/db';
+import { guardAgentWrite } from '@/lib/api-guard';
+
+type RouteParams = { params: Promise<{ id: string }> };
+
+/**
+ * POST /api/agents/[id]/start
+ *
+ * @param {NextRequest} _req
+ * @param {RouteParams} ctx
+ * @returns {Promise<NextResponse>} 200 on success, 404 or 500 on error.
+ */
+export async function POST(req: NextRequest, { params }: RouteParams): Promise<NextResponse> {
+  try {
+    const { id } = await params;
+    const denied = await guardAgentWrite(req, id);
+    if (denied) return denied;
+    const agent = await getAgentById(id);
+    if (!agent) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+    await publishAgentEvent({ type: 'start', agentId: id });
+    await updateAgentStatus(id, 'running');
+    await updateAgentEnabled(id, true);
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}

package/apps/web/src/app/api/agents/[id]/stop/route.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview POST /api/agents/[id]/stop
+ * Publishes a stop event so the runner tears down the agent's Bolt app.
+ *
+ * @module web/api/agents/[id]/stop
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getAgentById, updateAgentStatus, updateAgentEnabled, publishAgentEvent } from '@/lib/db';
+import { guardAgentWrite } from '@/lib/api-guard';
+
+type RouteParams = { params: Promise<{ id: string }> };
+
+/**
+ * POST /api/agents/[id]/stop
+ *
+ * @param {NextRequest} _req
+ * @param {RouteParams} ctx
+ * @returns {Promise<NextResponse>} 200 on success, 404 or 500 on error.
+ */
+export async function POST(req: NextRequest, { params }: RouteParams): Promise<NextResponse> {
+  try {
+    const { id } = await params;
+    const denied = await guardAgentWrite(req, id);
+    if (denied) return denied;
+    const agent = await getAgentById(id);
+    if (!agent) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+    await publishAgentEvent({ type: 'stop', agentId: id });
+    await updateAgentStatus(id, 'stopped');
+    await updateAgentEnabled(id, false);
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}

package/apps/web/src/app/api/agents/route.ts

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview REST API route for agent collection operations.
+ *
+ * GET  /api/agents — List all agents
+ * POST /api/agents — Create a new agent
+ *
+ * @module web/api/agents
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  getAllAgents,
+  createAgent,
+  setAgentMcps,
+  upsertSkill,
+  upsertPermissions,
+  publishAgentEvent,
+} from '@/lib/db';
+import type { CreateAgentRequest } from '@slackhive/shared';
+import { SKILL_TEMPLATES } from '@/lib/skill-templates';
+import { regenerateBossRegistry } from '@/lib/boss-registry';
+import { guardAdmin } from '@/lib/api-guard';
+import { getSessionFromRequest } from '@/lib/auth';
+
+/**
+ * GET /api/agents
+ * Returns all registered agents ordered boss-first.
+ *
+ * @returns {Promise<NextResponse>} JSON array of Agent objects.
+ */
+export async function GET(): Promise<NextResponse> {
+  try {
+    const agents = await getAllAgents();
+    return NextResponse.json(agents);
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 });
+  }
+}
+
+/**
+ * POST /api/agents
+ * Creates a new agent with its initial configuration.
+ * Also bootstraps skills from a template and assigns MCPs.
+ * Publishes a start event so the runner picks it up immediately.
+ *
+ * @param {NextRequest} request - Request body matching CreateAgentRequest.
+ * @returns {Promise<NextResponse>} The created Agent (201), or error.
+ */
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  const denied = guardAdmin(request);
+  if (denied) return denied;
+  try {
+    const body = (await request.json()) as CreateAgentRequest;
+
+    // Validate required fields
+    if (!body.slug || !body.name || !body.slackBotToken || !body.slackAppToken || !body.slackSigningSecret) {
+      return NextResponse.json(
+        { error: 'slug, name, slackBotToken, slackAppToken, slackSigningSecret are required' },
+        { status: 400 }
+      );
+    }
+
+    // Create the agent record, tracking who created it
+    const session = getSessionFromRequest(request);
+    const agent = await createAgent(body, session?.username ?? 'system');
+
+    // Assign MCPs if provided
+    if (body.mcpServerIds?.length) {
+      await setAgentMcps(agent.id, body.mcpServerIds);
+    }
+
+    // Boss agents skip skill template — their CLAUDE.md is auto-generated by boss-registry
+    if (!agent.isBoss) {
+      const template = body.skillTemplate ?? 'blank';
+      const skills = SKILL_TEMPLATES[template](agent);
+      for (const skill of skills) {
+        await upsertSkill(agent.id, skill.category, skill.filename, skill.content, skill.sortOrder);
+      }
+    }
+
+    // Create default permissions (Read + selected MCP tools)
+    const allowedTools = ['Read'];
+    await upsertPermissions(agent.id, allowedTools, []);
+
+    // Signal the runner to start this agent
+    await publishAgentEvent({ type: 'start', agentId: agent.id });
+
+    // Regenerate boss registry now that team has a new member
+    await regenerateBossRegistry().catch(() => {});
+
+    return NextResponse.json(agent, { status: 201 });
+  } catch (err) {
+    const message = (err as Error).message;
+    if (message.includes('unique')) {
+      return NextResponse.json({ error: 'An agent with this slug already exists' }, { status: 409 });
+    }
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/apps/web/src/app/api/auth/login/route.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Login API — authenticates user and sets session cookie.
+ *
+ * POST /api/auth/login — accepts `{ username, password }`.
+ *
+ * @module web/api/auth/login
+ */
+
+import { NextResponse } from 'next/server';
+import { authenticateUser, signSession, COOKIE_NAME } from '@/lib/auth';
+
+/**
+ * Authenticates a user and sets an HMAC-signed session cookie.
+ *
+ * @param {Request} req - JSON body with `username` and `password`.
+ * @returns {Promise<NextResponse>} JSON response with role or 401.
+ */
+export async function POST(req: Request): Promise<NextResponse> {
+  const { username, password } = await req.json();
+
+  if (!username || !password) {
+    return NextResponse.json({ error: 'Username and password required' }, { status: 400 });
+  }
+
+  const session = await authenticateUser(username, password);
+  if (!session) {
+    return NextResponse.json({ error: 'Invalid credentials' }, { status: 401 });
+  }
+
+  const cookie = signSession(session);
+  const res = NextResponse.json({ ok: true, username: session.username, role: session.role });
+  res.cookies.set(COOKIE_NAME, cookie, {
+    httpOnly: true,
+    sameSite: 'lax',
+    path: '/',
+    maxAge: 60 * 60 * 24 * 7, // 7 days
+  });
+  return res;
+}

package/apps/web/src/app/api/auth/logout/route.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Logout API — clears the session cookie.
+ *
+ * POST /api/auth/logout
+ *
+ * @module web/api/auth/logout
+ */
+
+import { NextResponse } from 'next/server';
+import { COOKIE_NAME } from '@/lib/auth';
+
+/**
+ * Clears the auth session cookie.
+ *
+ * @returns {Promise<NextResponse>} JSON confirmation.
+ */
+export async function POST(): Promise<NextResponse> {
+  const res = NextResponse.json({ ok: true });
+  res.cookies.set(COOKIE_NAME, '', { httpOnly: true, path: '/', maxAge: 0 });
+  return res;
+}