@app-vitals/agent-admin 0.0.0-stage → 0.1.0

package/src/agent-tokens.integration.test.ts

@@ -0,0 +1,150 @@
+/**
+ * agent/src/agent-tokens.integration.test.ts
+ * Integration tests for AgentTokenService against a real PostgreSQL DB.
+ *
+ * Requires DATABASE_URL_ADMIN_TEST to be set; skips otherwise.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import type { PrismaClient } from "../prisma/client/client.ts";
+import { AgentTokenService } from "./agent-tokens.ts";
+import { UnprocessableEntityError } from "./errors.ts";
+import { createAdminPrismaClient } from "./prisma-client.ts";
+
+const TEST_DB = process.env.DATABASE_URL_ADMIN_TEST;
+
+const describeOrSkip = TEST_DB ? describe : describe.skip;
+
+function makePrisma(): PrismaClient {
+  // TEST_DB is guaranteed set — the describe block is skipped otherwise.
+  return createAdminPrismaClient(TEST_DB as string);
+}
+
+async function createAgent(
+  prisma: PrismaClient,
+  name = "Test Agent",
+): Promise<string> {
+  const agent = await prisma.agent.create({ data: { name } });
+  return agent.id;
+}
+
+describeOrSkip("AgentTokenService (integration)", () => {
+  let prisma: PrismaClient;
+  let service: AgentTokenService;
+
+  beforeEach(async () => {
+    prisma = makePrisma();
+    await prisma.agentToken.deleteMany();
+    await prisma.agentCronJob.deleteMany();
+    await prisma.agentTool.deleteMany();
+    await prisma.agentEnv.deleteMany();
+    await prisma.agent.deleteMany();
+    service = new AgentTokenService(prisma);
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  // ─── create ─────────────────────────────────────────────────────────────────
+
+  it("create() returns a token record and a raw token", async () => {
+    const agentId = await createAgent(prisma);
+    const { token, rawToken } = await service.create(agentId);
+    expect(token.agentId).toBe(agentId);
+    expect(typeof rawToken).toBe("string");
+    expect(rawToken).toHaveLength(64); // 32 bytes = 64 hex chars
+    expect(token.revokedAt).toBeNull();
+  });
+
+  it("create() stores only the SHA-256 hash (not raw token)", async () => {
+    const agentId = await createAgent(prisma);
+    const { token, rawToken } = await service.create(agentId);
+    // The stored token should NOT be the raw token
+    expect(token.token).not.toBe(rawToken);
+    // But should be a valid 64-char hex SHA-256 hash
+    expect(token.token).toHaveLength(64);
+  });
+
+  it("create() accepts an optional label", async () => {
+    const agentId = await createAgent(prisma);
+    const { token } = await service.create(agentId, "My CI Token");
+    expect(token.label).toBe("My CI Token");
+  });
+
+  it("create() throws UnprocessableEntityError for unknown agentId", async () => {
+    await expect(service.create("nonexistent-id")).rejects.toBeInstanceOf(
+      UnprocessableEntityError,
+    );
+  });
+
+  // ─── validate ───────────────────────────────────────────────────────────────
+
+  it("validate() returns agentId for a valid token", async () => {
+    const agentId = await createAgent(prisma);
+    const { rawToken } = await service.create(agentId);
+    const result = await service.validate(rawToken);
+    expect(result).not.toBeNull();
+    expect(result?.agentId).toBe(agentId);
+  });
+
+  it("validate() returns null for unknown token", async () => {
+    const result = await service.validate("0".repeat(64));
+    expect(result).toBeNull();
+  });
+
+  it("validate() returns null for a revoked token", async () => {
+    const agentId = await createAgent(prisma);
+    const { token, rawToken } = await service.create(agentId);
+    await service.revoke(token.id);
+    const result = await service.validate(rawToken);
+    expect(result).toBeNull();
+  });
+
+  // ─── revoke ─────────────────────────────────────────────────────────────────
+
+  it("revoke() sets revokedAt on the token", async () => {
+    const agentId = await createAgent(prisma);
+    const { token } = await service.create(agentId);
+    const revoked = await service.revoke(token.id);
+    expect(revoked).not.toBeNull();
+    expect(revoked?.revokedAt).not.toBeNull();
+  });
+
+  it("revoke() returns null for unknown tokenId (P2025)", async () => {
+    const result = await service.revoke("nonexistent-id");
+    expect(result).toBeNull();
+  });
+
+  // ─── listForAgent ────────────────────────────────────────────────────────────
+
+  it("listForAgent() returns all tokens for an agent", async () => {
+    const agentId = await createAgent(prisma);
+    await service.create(agentId, "Token 1");
+    await service.create(agentId, "Token 2");
+    const tokens = await service.listForAgent(agentId);
+    expect(tokens).toHaveLength(2);
+  });
+
+  it("listForAgent() does not return tokens from other agents", async () => {
+    const agentId1 = await createAgent(prisma, "Agent 1");
+    const agentId2 = await createAgent(prisma, "Agent 2");
+    await service.create(agentId1);
+    const tokens = await service.listForAgent(agentId2);
+    expect(tokens).toHaveLength(0);
+  });
+
+  // ─── getById ────────────────────────────────────────────────────────────────
+
+  it("getById() returns a token by ID", async () => {
+    const agentId = await createAgent(prisma);
+    const { token } = await service.create(agentId);
+    const fetched = await service.getById(token.id);
+    expect(fetched?.id).toBe(token.id);
+  });
+
+  it("getById() returns null for unknown tokenId", async () => {
+    const result = await service.getById("nonexistent");
+    expect(result).toBeNull();
+  });
+});

package/src/agent-tokens.ts

@@ -0,0 +1,112 @@
+/**
+ * agent/src/agent-tokens.ts
+ * AgentTokenService — scoped API tokens for agent authentication.
+ *
+ * The raw token (64-char hex) is returned once at creation; only the SHA-256
+ * hash is stored. Token validation is O(1) via the unique index on `token`.
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import type { AgentToken, PrismaClient } from "../prisma/client/client.ts";
+import { type Clock, SystemClock } from "./clock.ts";
+import { UnprocessableEntityError } from "./errors.ts";
+
+export type { AgentToken };
+
+export interface AgentTokenValidated {
+  agentId: string;
+}
+
+function hashToken(raw: string): string {
+  return createHash("sha256").update(raw).digest("hex");
+}
+
+function generateRawToken(): string {
+  return randomBytes(32).toString("hex");
+}
+
+export class AgentTokenService {
+  constructor(
+    private prisma: PrismaClient,
+    private clock: Clock = SystemClock(),
+  ) {}
+
+  /**
+   * Create a new token for an agent.
+   * Returns the token record plus the raw token — only opportunity to read it.
+   * Throws UnprocessableEntityError if agentId doesn't reference an existing Agent.
+   */
+  async create(
+    agentId: string,
+    label?: string,
+  ): Promise<{ token: AgentToken; rawToken: string }> {
+    const agent = await this.prisma.agent.findUnique({
+      where: { id: agentId },
+    });
+    if (!agent) {
+      throw new UnprocessableEntityError("agentId not found");
+    }
+
+    const rawToken = generateRawToken();
+    const hashed = hashToken(rawToken);
+
+    const token = await this.prisma.agentToken.create({
+      data: { agentId, token: hashed, label },
+    });
+
+    return { token, rawToken };
+  }
+
+  /**
+   * Validate a raw token. Returns { agentId } if valid and not revoked,
+   * or null if the token is unknown or revoked.
+   */
+  async validate(raw: string): Promise<AgentTokenValidated | null> {
+    const hashed = hashToken(raw);
+    const record = await this.prisma.agentToken.findUnique({
+      where: { token: hashed },
+    });
+    if (!record || record.revokedAt !== null) return null;
+    return { agentId: record.agentId };
+  }
+
+  /**
+   * Revoke a token by ID. Returns the updated record, or null if not found (P2025).
+   * Re-throws all other errors so real failures aren't silently swallowed.
+   */
+  async revoke(tokenId: string): Promise<AgentToken | null> {
+    try {
+      return await this.prisma.agentToken.update({
+        where: { id: tokenId },
+        data: { revokedAt: this.clock.now() },
+      });
+    } catch (err: unknown) {
+      if (
+        typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        (err as { code: string }).code === "P2025"
+      ) {
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * List tokens for a given agent (without the hashed token value).
+   */
+  async listForAgent(agentId: string): Promise<AgentToken[]> {
+    return this.prisma.agentToken.findMany({
+      where: { agentId },
+      orderBy: { createdAt: "asc" },
+    });
+  }
+
+  /**
+   * Get a single token by ID. Used for ownership checks before mutating.
+   */
+  async getById(tokenId: string): Promise<AgentToken | null> {
+    return this.prisma.agentToken.findUnique({ where: { id: tokenId } });
+  }
+}

package/src/agent-tools.integration.test.ts

@@ -0,0 +1,129 @@
+/**
+ * agent/src/agent-tools.integration.test.ts
+ * Integration tests for AgentToolService against a real PostgreSQL DB.
+ *
+ * Requires DATABASE_URL_ADMIN_TEST to be set; skips otherwise.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import type { PrismaClient } from "../prisma/client/client.ts";
+import { AgentToolService } from "./agent-tools.ts";
+import { NotFoundError } from "./errors.ts";
+import { createAdminPrismaClient } from "./prisma-client.ts";
+
+const TEST_DB = process.env.DATABASE_URL_ADMIN_TEST;
+
+const describeOrSkip = TEST_DB ? describe : describe.skip;
+
+function makePrisma(): PrismaClient {
+  // TEST_DB is guaranteed set — the describe block is skipped otherwise.
+  return createAdminPrismaClient(TEST_DB as string);
+}
+
+async function createAgent(
+  prisma: PrismaClient,
+  name = "Test Agent",
+): Promise<string> {
+  const agent = await prisma.agent.create({ data: { name } });
+  return agent.id;
+}
+
+describeOrSkip("AgentToolService (integration)", () => {
+  let prisma: PrismaClient;
+  let service: AgentToolService;
+
+  beforeEach(async () => {
+    prisma = makePrisma();
+    await prisma.agentToken.deleteMany();
+    await prisma.agentCronJob.deleteMany();
+    await prisma.agentTool.deleteMany();
+    await prisma.agentEnv.deleteMany();
+    await prisma.agent.deleteMany();
+    service = new AgentToolService(prisma);
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  it("add() creates a new tool pattern", async () => {
+    const agentId = await createAgent(prisma);
+    const tool = await service.add(agentId, "Read");
+    expect(tool.agentId).toBe(agentId);
+    expect(tool.pattern).toBe("Read");
+    expect(tool.enabled).toBe(true);
+  });
+
+  it("add() re-enables a disabled pattern (upsert behavior)", async () => {
+    const agentId = await createAgent(prisma);
+    const tool = await service.add(agentId, "Write");
+    await service.toggle(agentId, tool.id, false);
+    // Re-add should re-enable it
+    const reenabled = await service.add(agentId, "Write");
+    expect(reenabled.enabled).toBe(true);
+  });
+
+  it("list() returns all tools for an agent ordered by createdAt", async () => {
+    const agentId = await createAgent(prisma);
+    await service.add(agentId, "Read");
+    await service.add(agentId, "Write");
+    await service.add(agentId, "Bash");
+    const tools = await service.list(agentId);
+    expect(tools).toHaveLength(3);
+    expect(tools.map((t) => t.pattern)).toEqual(["Read", "Write", "Bash"]);
+  });
+
+  it("remove() deletes a tool pattern", async () => {
+    const agentId = await createAgent(prisma);
+    const tool = await service.add(agentId, "Bash");
+    await service.remove(agentId, tool.id);
+    const tools = await service.list(agentId);
+    expect(tools).toHaveLength(0);
+  });
+
+  it("remove() throws NotFoundError for unknown toolId", async () => {
+    const agentId = await createAgent(prisma);
+    await expect(service.remove(agentId, "nonexistent")).rejects.toBeInstanceOf(
+      NotFoundError,
+    );
+  });
+
+  it("remove() throws NotFoundError when toolId belongs to a different agent", async () => {
+    const agentId1 = await createAgent(prisma, "Agent 1");
+    const agentId2 = await createAgent(prisma, "Agent 2");
+    const tool = await service.add(agentId1, "Read");
+    await expect(service.remove(agentId2, tool.id)).rejects.toBeInstanceOf(
+      NotFoundError,
+    );
+  });
+
+  it("toggle() enables and disables a tool", async () => {
+    const agentId = await createAgent(prisma);
+    const tool = await service.add(agentId, "Write");
+    const disabled = await service.toggle(agentId, tool.id, false);
+    expect(disabled.enabled).toBe(false);
+    const enabled = await service.toggle(agentId, tool.id, true);
+    expect(enabled.enabled).toBe(true);
+  });
+
+  it("toggle() throws NotFoundError for unknown toolId", async () => {
+    const agentId = await createAgent(prisma);
+    await expect(
+      service.toggle(agentId, "nonexistent", true),
+    ).rejects.toBeInstanceOf(NotFoundError);
+  });
+
+  it("updatePattern() changes the pattern string", async () => {
+    const agentId = await createAgent(prisma);
+    const tool = await service.add(agentId, "OldPattern");
+    const updated = await service.updatePattern(agentId, tool.id, "NewPattern");
+    expect(updated.pattern).toBe("NewPattern");
+  });
+
+  it("updatePattern() throws NotFoundError for unknown toolId", async () => {
+    const agentId = await createAgent(prisma);
+    await expect(
+      service.updatePattern(agentId, "nonexistent", "Read"),
+    ).rejects.toBeInstanceOf(NotFoundError);
+  });
+});

package/src/agent-tools.ts

@@ -0,0 +1,111 @@
+/**
+ * agent/src/agent-tools.ts
+ * AgentToolService — CRUD for allowed tool patterns per agent.
+ *
+ * Each pattern grants an agent permission to use a specific tool (e.g. "Read",
+ * "Bash", "Write"). The unique constraint on [agentId, pattern] prevents
+ * duplicates; add() uses upsert so it re-enables a previously disabled pattern.
+ */
+
+import type { AgentTool, PrismaClient } from "../prisma/client/client.ts";
+import { NotFoundError } from "./errors.ts";
+import type { PrismaTransactionClient } from "./prisma-tx.ts";
+
+export type { AgentTool };
+
+export class AgentToolService {
+  constructor(private prisma: PrismaClient) {}
+
+  /**
+   * List all tool patterns for a given agent, ordered by createdAt.
+   */
+  async list(agentId: string): Promise<AgentTool[]> {
+    return this.prisma.agentTool.findMany({
+      where: { agentId },
+      orderBy: { createdAt: "asc" },
+    });
+  }
+
+  /**
+   * Add a tool pattern for the given agent.
+   * Uses upsert so re-adding a disabled pattern re-enables it.
+   *
+   * @param client - defaults to `this.prisma`; pass the `tx` argument from a
+   *   caller's `prisma.$transaction(async (tx) => ...)` to make this write
+   *   participate in that transaction (see createAgent() in agents.ts).
+   */
+  async add(
+    agentId: string,
+    pattern: string,
+    client: PrismaTransactionClient = this.prisma,
+  ): Promise<AgentTool> {
+    return client.agentTool.upsert({
+      where: { agentId_pattern: { agentId, pattern } },
+      create: { agentId, pattern, enabled: true },
+      update: { enabled: true },
+    });
+  }
+
+  /**
+   * Delete a tool pattern. Verifies agentId ownership before deleting.
+   * Throws NotFoundError if the toolId doesn't exist or belongs to a different agent.
+   */
+  async remove(agentId: string, toolId: string): Promise<void> {
+    const existing = await this.prisma.agentTool.findUnique({
+      where: { id: toolId },
+    });
+
+    if (!existing || existing.agentId !== agentId) {
+      throw new NotFoundError(`tool ${toolId} not found`);
+    }
+
+    await this.prisma.agentTool.delete({ where: { id: toolId } });
+  }
+
+  /**
+   * Enable or disable a tool pattern.
+   * Throws NotFoundError if the toolId doesn't exist or belongs to a different agent.
+   */
+  async toggle(
+    agentId: string,
+    toolId: string,
+    enabled: boolean,
+  ): Promise<AgentTool> {
+    const existing = await this.prisma.agentTool.findUnique({
+      where: { id: toolId },
+    });
+
+    if (!existing || existing.agentId !== agentId) {
+      throw new NotFoundError(`tool ${toolId} not found`);
+    }
+
+    return this.prisma.agentTool.update({
+      where: { id: toolId },
+      data: { enabled },
+    });
+  }
+
+  /**
+   * Update the pattern string for a tool.
+   * Verifies agentId ownership before updating.
+   * Throws NotFoundError if the toolId doesn't exist or belongs to a different agent.
+   */
+  async updatePattern(
+    agentId: string,
+    toolId: string,
+    pattern: string,
+  ): Promise<AgentTool> {
+    const existing = await this.prisma.agentTool.findUnique({
+      where: { id: toolId },
+    });
+
+    if (!existing || existing.agentId !== agentId) {
+      throw new NotFoundError(`tool ${toolId} not found`);
+    }
+
+    return this.prisma.agentTool.update({
+      where: { id: toolId },
+      data: { pattern },
+    });
+  }
+}