@app-vitals/agent-admin 1.2.7 → 1.4.0

package/src/agents-api.ts

@@ -41,6 +41,7 @@ import {
 } from "./account-agent-create.ts";
 import {
   reconcileAgentAfterAccountChange,
+  reconcileAgentAfterSpecialtyChange,
   reconcileAgentAfterPodServiceAccountChange,
 } from "./agent-account-assignment.ts";
 import {
@@ -623,7 +624,7 @@ const patchAgentRoute = createRoute({
   path: "/agents/{id}",
   summary: "Update an agent",
   description:
-    "Admin-only. Updates `selfHosted`, `repos`, `reviewAuthorAllowlist`, `patchAuthorAllowlist`, `restrictSlackToMembers`, `slackId`, `trialExpiresAt`, `accountId` (platform admin only — 403 for session members; `null` clears it; reconciles the workload of in-cluster agents; does not move historical task-store rows), and/or `podServiceAccountName` (platform admin only — 403 otherwise; `null` clears it; 409 unless SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED is on; 422 for agents with a per-agent federated identity; reconciles the workload so the pod is recreated under the new ServiceAccount). `specialty` and `trialExpiryWarnedAt` are not updatable via this route. `repos` here REPLACES the whole list; for incremental changes use `POST /agents/{id}/repos` (add) and `DELETE /agents/{id}/repos/{owner}/{name}` (remove). Returns the updated agent, including a `warning` field when `restrictSlackToMembers` is set true on an agent with zero members.",
+    "Admin-only. Updates `selfHosted`, `repos`, `reviewAuthorAllowlist`, `patchAuthorAllowlist`, `restrictSlackToMembers`, `slackId`, `trialExpiresAt`, `accountId` (platform admin only — 403 for session members; `null` clears it; reconciles the workload of in-cluster agents; does not move historical task-store rows), and/or `podServiceAccountName` (platform admin only — 403 otherwise; `null` clears it; 409 unless SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED is on; 422 for agents with a per-agent federated identity; reconciles the workload so the pod is recreated under the new ServiceAccount). `specialty` (platform admin only — 403 otherwise; 422 when the type is unknown; a no-op when unchanged; otherwise persists the new type, reconciles the agent's system crons against it — system crons the new type does not declare are deleted, user crons survive — and reconciles the workload of in-cluster agents so the pod runs the image mapped to the new specialty). `trialExpiryWarnedAt` is not updatable via this route. `repos` here REPLACES the whole list; for incremental changes use `POST /agents/{id}/repos` (add) and `DELETE /agents/{id}/repos/{owner}/{name}` (remove). Returns the updated agent, including a `warning` field when `restrictSlackToMembers` is set true on an agent with zero members.",
   request: {
     params: AgentIdParamSchema,
     body: {
@@ -645,7 +646,7 @@ const patchAgentRoute = createRoute({
     },
     422: {
       description:
-        "podServiceAccountName supplied for an agent with a per-agent federated identity",
+        "podServiceAccountName supplied for an agent with a per-agent federated identity, or `specialty` naming an unknown type",
       ...jsonError,
     },
   },
@@ -1688,6 +1689,25 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
         throw new ForbiddenError("Admin access required to change accountId");
       }
     }
+    // SAL-1.2: specialty change — platform-admin only, known type only.
+    let previousSpecialty: string | undefined;
+    if (body.specialty !== undefined) {
+      if (c.get("isAdmin") !== true) {
+        throw new ForbiddenError("Admin access required to change specialty");
+      }
+      if (!specialtyRegistry.tryGetType(body.specialty)) {
+        throw new UnprocessableEntityError(
+          `unknown specialty "${body.specialty}"`,
+        );
+      }
+      const current = await agentService.getDetail(agentId);
+      if (!current) {
+        throw new NotFoundError(`agent ${agentId} not found`);
+      }
+      if (current.specialty !== body.specialty) {
+        previousSpecialty = current.specialty;
+      }
+    }
     // COS-49.1: pod ServiceAccount — platform-admin only, flag-gated, and not
     // for agents whose federated identity owns the ServiceAccount.
     let previousPodServiceAccountName: string | null = null;
@@ -1733,6 +1753,9 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
           ? { podServiceAccountName: body.podServiceAccountName }
           : {}),
         ...(body.accountId !== undefined ? { accountId: body.accountId } : {}),
+        ...(previousSpecialty !== undefined
+          ? { specialty: body.specialty }
+          : {}),
         ...(body.repos !== undefined ? { repos: body.repos } : {}),
         ...(body.reviewAuthorAllowlist !== undefined
           ? { reviewAuthorAllowlist: body.reviewAuthorAllowlist }
@@ -1786,6 +1809,28 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
       body.accountId !== undefined
         ? await reconcileAgentAfterAccountChange(provisioner, agent)
         : undefined;
+    let specialtyWarning: string | undefined;
+    if (previousSpecialty !== undefined) {
+      // Audit: ids and names only — never the caller's key.
+      console.info(
+        `[agents-api] specialty changed: agent=${agentId} old=${previousSpecialty} new=${agent.specialty} caller=${c.get("caller")?.name ?? "anonymous"}`,
+      );
+      const warnings: string[] = [];
+      try {
+        await agentCronJobService.reconcileSystemCrons(agentId);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        warnings.push(
+          `specialty updated, but reconciling system crons failed: ${message}`,
+        );
+      }
+      const workloadWarning = await reconcileAgentAfterSpecialtyChange(
+        provisioner,
+        agent,
+      );
+      if (workloadWarning) warnings.push(workloadWarning);
+      specialtyWarning = warnings.join("; ") || undefined;
+    }
     let podSaWarning: string | undefined;
     if (body.podServiceAccountName !== undefined) {
       // Audit: ids and names only — never the caller's key.
@@ -1801,7 +1846,7 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
       }
     }
     const warning =
-      [slackWarning, reconcileWarning, podSaWarning]
+      [slackWarning, reconcileWarning, specialtyWarning, podSaWarning]
         .filter(Boolean)
         .join("; ") || undefined;
     return c.json(serializeAgent(agent, warning), 200);

package/src/agents.ts

@@ -140,6 +140,8 @@ export interface AgentDetail extends Partial<AgentAnthropicIdentity> {
 }
 
 interface UpdateSelfHostedInput {
+  /** SAL-1.2: the agent's specialty; callers validate it against the registry. */
+  specialty?: string;
   /** COS-49.1: pod ServiceAccount; null clears it. */
   podServiceAccountName?: string | null;
   /** SSP-5.3: owning account; null clears it (unassigned/platform agent). */
@@ -475,6 +477,9 @@ export class AgentService {
       where: { id },
       data: {
         selfHosted: input.selfHosted,
+        ...(input.specialty !== undefined
+          ? { specialty: input.specialty }
+          : {}),
         ...(input.accountId !== undefined
           ? { accountId: input.accountId }
           : {}),

package/src/github-enterprise-apps.integration.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Integration tests for GitHubEnterpriseAppService 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 {
+  GitHubEnterpriseAppService,
+  PrivateKeyDecryptError,
+  PrivateKeyEncryptionUnavailableError,
+} from "./github-enterprise-apps.ts";
+import { createAdminPrismaClient } from "./prisma-client.ts";
+import { makeStrictTokenCrypto } from "./token-crypto.ts";
+
+const TEST_DB = process.env.DATABASE_URL_ADMIN_TEST;
+const describeOrSkip = TEST_DB ? describe : describe.skip;
+
+const KEY_A = "a".repeat(64);
+const KEY_B = "b".repeat(64);
+const PEM =
+  "-----BEGIN RSA PRIVATE KEY-----\nSUPERSECRETPEMBODY0123456789\n-----END RSA PRIVATE KEY-----";
+
+const installer = {
+  role: "installer" as const,
+  appId: "111",
+  slug: "inst-app",
+  enterpriseSlug: "acme",
+  privateKey: PEM,
+};
+
+describeOrSkip("GitHubEnterpriseAppService (integration)", () => {
+  let prisma: PrismaClient;
+  let service: GitHubEnterpriseAppService;
+
+  beforeEach(async () => {
+    prisma = createAdminPrismaClient(TEST_DB as string);
+    await prisma.gitHubEnterpriseApp.deleteMany();
+    service = new GitHubEnterpriseAppService(
+      prisma,
+      makeStrictTokenCrypto(KEY_A),
+    );
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  it("returns null when nothing is saved (feature off)", async () => {
+    expect(await service.get("installer")).toBeNull();
+    expect(await service.list()).toEqual([]);
+  });
+
+  it("saves and reads per role; metadata plus keySet only", async () => {
+    const saved = await service.save(installer);
+    expect(saved.keySet).toBe(true);
+    await service.save({
+      role: "lookup",
+      appId: "222",
+      slug: "look-app",
+      privateKey: PEM,
+    });
+    const got = await service.get("installer");
+    expect(got).toMatchObject({
+      role: "installer",
+      appId: "111",
+      slug: "inst-app",
+      enterpriseSlug: "acme",
+      keySet: true,
+    });
+    expect(JSON.stringify(got)).not.toContain("SUPERSECRETPEMBODY");
+    expect(JSON.stringify(await service.list())).not.toContain(
+      "SUPERSECRETPEMBODY",
+    );
+    expect((await service.list()).map((a) => a.role).sort()).toEqual([
+      "installer",
+      "lookup",
+    ]);
+  });
+
+  it("save again for the same role replaces the row (at most two rows)", async () => {
+    await service.save(installer);
+    await service.save({ ...installer, appId: "999" });
+    expect(await prisma.gitHubEnterpriseApp.count()).toBe(1);
+    expect((await service.get("installer"))?.appId).toBe("999");
+  });
+
+  it("stores the key encrypted and round-trips it via getPrivateKey", async () => {
+    await service.save(installer);
+    const row = await prisma.gitHubEnterpriseApp.findUnique({
+      where: { role: "installer" },
+    });
+    expect(row?.privateKeyEncrypted).not.toContain("SUPERSECRETPEMBODY");
+    expect(row?.privateKeyEncrypted.split(":")).toHaveLength(3);
+    expect(await service.getPrivateKey("installer")).toBe(PEM);
+  });
+
+  it("deletes per role", async () => {
+    await service.save(installer);
+    await service.delete("installer");
+    expect(await service.get("installer")).toBeNull();
+    await service.delete("installer"); // no-op
+  });
+
+  it("rejects an unknown role", async () => {
+    await expect(
+      service.save({ ...installer, role: "bogus" as never }),
+    ).rejects.toThrow(/role/);
+  });
+
+  it("refuses to save when no encryption key is configured, without echoing the PEM", async () => {
+    const noKey = new GitHubEnterpriseAppService(
+      prisma,
+      makeStrictTokenCrypto(undefined),
+    );
+    const err = await noKey.save(installer).catch((e) => e);
+    expect(err).toBeInstanceOf(PrivateKeyEncryptionUnavailableError);
+    expect(err.message).toContain("SHIPWRIGHT_ENCRYPTION_KEY");
+    expect(err.message).not.toContain("SUPERSECRETPEMBODY");
+    expect(await prisma.gitHubEnterpriseApp.count()).toBe(0);
+  });
+
+  it("strict decrypt: wrong key throws, never returning ciphertext or PEM", async () => {
+    await service.save(installer);
+    const wrong = new GitHubEnterpriseAppService(
+      prisma,
+      makeStrictTokenCrypto(KEY_B),
+    );
+    const err = await wrong.getPrivateKey("installer").catch((e) => e);
+    expect(err).toBeInstanceOf(PrivateKeyDecryptError);
+    expect(err.message).not.toContain("SUPERSECRETPEMBODY");
+  });
+
+  it("strict decrypt: tampered and legacy plain-text values throw", async () => {
+    await service.save(installer);
+    const row = await prisma.gitHubEnterpriseApp.findUnique({
+      where: { role: "installer" },
+    });
+    const [iv, ct, tag] = (row?.privateKeyEncrypted ?? "").split(":");
+    const flipped = (ct[0] === "0" ? "1" : "0") + ct.slice(1);
+    for (const bad of [`${iv}:${flipped}:${tag}`, PEM]) {
+      await prisma.gitHubEnterpriseApp.update({
+        where: { role: "installer" },
+        data: { privateKeyEncrypted: bad },
+      });
+      const err = await service.getPrivateKey("installer").catch((e) => e);
+      expect(err).toBeInstanceOf(PrivateKeyDecryptError);
+      expect(err.message).not.toContain("SUPERSECRETPEMBODY");
+    }
+  });
+});

package/src/github-enterprise-apps.ts

@@ -0,0 +1,204 @@
+/**
+ * admin/src/github-enterprise-apps.ts
+ * GitHubEnterpriseAppService — storage for the two optional admin-level GitHub
+ * Apps ('installer' and 'lookup'), at most one row per role. No rows means the
+ * feature is off.
+ *
+ * The private key is encrypted on write (AES-256-GCM via TokenCrypto) and is
+ * never returned by any read path: reads return metadata plus a `keySet` flag.
+ * Only getPrivateKey() decrypts, for server-side use by the app-token minter.
+ *
+ * Deliberate differences from AgentEnvService:
+ *  - save() refuses when no encryption key is configured (no plain-text fallback);
+ *  - decrypt is strict (failure throws; ciphertext is never passed on as a PEM);
+ *  - separate table, so the key can never reach the agent config bundle;
+ *  - no key rotation.
+ * Errors never include the PEM.
+ */
+
+import type { PrismaClient } from "../prisma/client/client.ts";
+import { type Clock, SystemClock } from "./clock.ts";
+import { ApiError, UnprocessableEntityError } from "./errors.ts";
+import type { TokenCrypto } from "./token-crypto.ts";
+
+export const GITHUB_ENTERPRISE_APP_ROLES = ["installer", "lookup"] as const;
+export type GitHubEnterpriseAppRole =
+  (typeof GITHUB_ENTERPRISE_APP_ROLES)[number];
+
+export interface GitHubEnterpriseAppMetadata {
+  role: string;
+  appId: string;
+  slug: string;
+  enterpriseSlug: string | null;
+  /** True when an encrypted private key is stored. The key itself is never returned. */
+  keySet: boolean;
+  lastValidationStatus: string | null;
+  lastValidatedAt: Date | null;
+  lastValidationError: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface SaveGitHubEnterpriseAppInput {
+  role: GitHubEnterpriseAppRole;
+  appId: string;
+  slug: string;
+  /** installer only */
+  enterpriseSlug?: string | null;
+  /** PEM; encrypted before it is stored. */
+  privateKey: string;
+}
+
+interface GitHubEnterpriseAppRow {
+  role: string;
+  appId: string;
+  slug: string;
+  enterpriseSlug: string | null;
+  privateKeyEncrypted: string;
+  lastValidationStatus: string | null;
+  lastValidatedAt: Date | null;
+  lastValidationError: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export class PrivateKeyEncryptionUnavailableError extends UnprocessableEntityError {
+  constructor() {
+    super(
+      "SHIPWRIGHT_ENCRYPTION_KEY is not configured; refusing to store a GitHub App private key unencrypted. Set it to a 64-character hex string (openssl rand -hex 32) and retry.",
+    );
+    this.name = "PrivateKeyEncryptionUnavailableError";
+  }
+}
+
+export class PrivateKeyDecryptError extends ApiError {
+  constructor(role: string) {
+    super(
+      500,
+      `failed to decrypt the stored private key for GitHub Enterprise App '${role}': the value is corrupt or SHIPWRIGHT_ENCRYPTION_KEY changed; re-save the key`,
+    );
+    this.name = "PrivateKeyDecryptError";
+  }
+}
+
+/** Serializer: metadata plus a keySet flag. Never includes key material. */
+export function toGitHubEnterpriseAppMetadata(
+  row: GitHubEnterpriseAppRow,
+): GitHubEnterpriseAppMetadata {
+  return {
+    role: row.role,
+    appId: row.appId,
+    slug: row.slug,
+    enterpriseSlug: row.enterpriseSlug,
+    keySet: row.privateKeyEncrypted.length > 0,
+    lastValidationStatus: row.lastValidationStatus,
+    lastValidatedAt: row.lastValidatedAt,
+    lastValidationError: row.lastValidationError,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function assertRole(role: string): asserts role is GitHubEnterpriseAppRole {
+  if (!(GITHUB_ENTERPRISE_APP_ROLES as readonly string[]).includes(role)) {
+    throw new UnprocessableEntityError(
+      `role must be one of: ${GITHUB_ENTERPRISE_APP_ROLES.join(", ")}`,
+    );
+  }
+}
+
+export class GitHubEnterpriseAppService {
+  constructor(
+    private prisma: PrismaClient,
+    /** Strict crypto (see makeStrictTokenCrypto); null when no encryption key is configured. */
+    private crypto: TokenCrypto | null,
+    private clock: Clock = SystemClock(),
+  ) {}
+
+  /** Create or replace the app for a role. Resets validation state. */
+  async save(
+    input: SaveGitHubEnterpriseAppInput,
+  ): Promise<GitHubEnterpriseAppMetadata> {
+    assertRole(input.role);
+    if (!this.crypto) throw new PrivateKeyEncryptionUnavailableError();
+    if (!input.privateKey) {
+      throw new UnprocessableEntityError("privateKey is required");
+    }
+    const data = {
+      appId: input.appId,
+      slug: input.slug,
+      enterpriseSlug:
+        input.role === "installer" ? (input.enterpriseSlug ?? null) : null,
+      privateKeyEncrypted: this.crypto.encrypt(input.privateKey),
+      lastValidationStatus: null,
+      lastValidatedAt: null,
+      lastValidationError: null,
+      updatedAt: this.clock.now(),
+    };
+    const row = await this.prisma.gitHubEnterpriseApp.upsert({
+      where: { role: input.role },
+      create: { role: input.role, ...data },
+      update: data,
+    });
+    return toGitHubEnterpriseAppMetadata(row);
+  }
+
+  async get(
+    role: GitHubEnterpriseAppRole,
+  ): Promise<GitHubEnterpriseAppMetadata | null> {
+    assertRole(role);
+    const row = await this.prisma.gitHubEnterpriseApp.findUnique({
+      where: { role },
+    });
+    return row ? toGitHubEnterpriseAppMetadata(row) : null;
+  }
+
+  async list(): Promise<GitHubEnterpriseAppMetadata[]> {
+    const rows = await this.prisma.gitHubEnterpriseApp.findMany({
+      orderBy: { role: "asc" },
+    });
+    return rows.map(toGitHubEnterpriseAppMetadata);
+  }
+
+  /** Delete the app for a role. No-ops if absent. */
+  async delete(role: GitHubEnterpriseAppRole): Promise<void> {
+    assertRole(role);
+    await this.prisma.gitHubEnterpriseApp.deleteMany({ where: { role } });
+  }
+
+  /**
+   * Server-side only: decrypt the stored PEM. Strict — any failure throws
+   * PrivateKeyDecryptError (never includes the PEM or ciphertext). Returns
+   * null when the role has no row.
+   */
+  async getPrivateKey(role: GitHubEnterpriseAppRole): Promise<string | null> {
+    assertRole(role);
+    if (!this.crypto) throw new PrivateKeyEncryptionUnavailableError();
+    const row = await this.prisma.gitHubEnterpriseApp.findUnique({
+      where: { role },
+    });
+    if (!row) return null;
+    try {
+      return this.crypto.decrypt(row.privateKeyEncrypted);
+    } catch {
+      throw new PrivateKeyDecryptError(role);
+    }
+  }
+
+  /** Record the outcome of a validation attempt. The error text must not contain key material. */
+  async recordValidation(
+    role: GitHubEnterpriseAppRole,
+    result: { status: string; error?: string | null },
+  ): Promise<void> {
+    assertRole(role);
+    await this.prisma.gitHubEnterpriseApp.updateMany({
+      where: { role },
+      data: {
+        lastValidationStatus: result.status,
+        lastValidatedAt: this.clock.now(),
+        lastValidationError: result.error ?? null,
+        updatedAt: this.clock.now(),
+      },
+    });
+  }
+}

package/src/github-enterprise-apps.unit.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Unit tests for the GitHubEnterpriseApp serializer: metadata plus a
+ * "key set" flag only, never the private key (plain or encrypted).
+ */
+
+import { describe, expect, it } from "bun:test";
+import { toGitHubEnterpriseAppMetadata } from "./github-enterprise-apps.ts";
+
+describe("toGitHubEnterpriseAppMetadata", () => {
+  const row = {
+    role: "installer",
+    appId: "123",
+    slug: "my-app",
+    enterpriseSlug: "acme",
+    privateKeyEncrypted: "aa:bb:cc",
+    lastValidationStatus: "ok",
+    lastValidatedAt: new Date("2026-01-01T00:00:00Z"),
+    lastValidationError: null,
+    createdAt: new Date("2026-01-01T00:00:00Z"),
+    updatedAt: new Date("2026-01-02T00:00:00Z"),
+  };
+
+  it("returns metadata and keySet, with no key material", () => {
+    const out = toGitHubEnterpriseAppMetadata(row);
+    expect(out.keySet).toBe(true);
+    expect(out).toMatchObject({
+      role: "installer",
+      appId: "123",
+      slug: "my-app",
+    });
+    expect(Object.keys(out).some((k) => /key/i.test(k) && k !== "keySet")).toBe(
+      false,
+    );
+    expect(JSON.stringify(out)).not.toContain("aa:bb:cc");
+  });
+
+  it("keySet is false when no ciphertext is stored", () => {
+    expect(
+      toGitHubEnterpriseAppMetadata({ ...row, privateKeyEncrypted: "" }).keySet,
+    ).toBe(false);
+  });
+});

package/src/openapi-schemas.ts

@@ -52,6 +52,10 @@ export const PatchAgentBodySchema = z
       .optional()
       .openapi({ example: "U0AALR8M69X" }),
     selfHosted: z.boolean().optional().openapi({ example: false }),
+    /**
+     * SAL-1.2: platform-admin only. Must name a known specialty type.
+     */
+    specialty: z.string().min(1).optional().openapi({ example: "specialist" }),
     repos: z
       .array(
         z.string().refine(isOrgRepo, {

package/src/token-crypto.ts

@@ -58,3 +58,28 @@ export function makeTokenCrypto(
     },
   };
 }
+
+/**
+ * Strict TokenCrypto for credentials that must never be stored or passed on as
+ * plain text (e.g. GitHub Enterprise App private keys).
+ *
+ * Differences from makeTokenCrypto(): returns null when no key is configured
+ * (callers must refuse to save, not fall back to identity), and decrypt()
+ * throws on any failure instead of returning the stored value as legacy
+ * plain text. A malformed key still throws at construction. Error messages
+ * never include the input value.
+ */
+export function makeStrictTokenCrypto(
+  key = process.env.SHIPWRIGHT_ENCRYPTION_KEY,
+): TokenCrypto | null {
+  if (!key) return null;
+  if (!isValidKeyHex(key)) {
+    throw new Error(
+      `SHIPWRIGHT_ENCRYPTION_KEY must be a 64-character hex string (32 bytes for AES-256-GCM), but got ${key.length} character(s). Generate one with: openssl rand -hex 32`,
+    );
+  }
+  return {
+    encrypt: (token) => encrypt(token, key),
+    decrypt: (encrypted) => decrypt(encrypted, key),
+  };
+}

package/src/token-crypto.unit.test.ts

@@ -6,7 +6,11 @@
 
 import { afterEach, describe, expect, it } from "bun:test";
 import { decrypt, encrypt, isValidKeyHex } from "./crypto.ts";
-import { identityCrypto, makeTokenCrypto } from "./token-crypto.ts";
+import {
+  identityCrypto,
+  makeStrictTokenCrypto,
+  makeTokenCrypto,
+} from "./token-crypto.ts";
 
 // ─── Test key ─────────────────────────────────────────────────────────────────
 // A known 64-char hex key (32 bytes) for deterministic tests.
@@ -180,3 +184,22 @@ describe("identityCrypto", () => {
     expect(identityCrypto.decrypt("hello")).toBe("hello");
   });
 });
+
+describe("makeStrictTokenCrypto", () => {
+  const KEY = "c".repeat(64);
+
+  it("returns null when no key is configured (no identity fallback)", () => {
+    expect(makeStrictTokenCrypto(undefined)).toBeNull();
+    expect(makeStrictTokenCrypto("")).toBeNull();
+  });
+
+  it("throws on a malformed key", () => {
+    expect(() => makeStrictTokenCrypto("short")).toThrow(/64-character/);
+  });
+
+  it("round-trips and throws on non-ciphertext instead of passing it through", () => {
+    const c = makeStrictTokenCrypto(KEY);
+    expect(c?.decrypt(c.encrypt("secret"))).toBe("secret");
+    expect(() => c?.decrypt("legacy-plain-text")).toThrow();
+  });
+});