@app-vitals/agent-admin 1.3.0 → 1.4.0

package/prisma/client/models.ts

@@ -14,6 +14,7 @@ export type * from './models/SessionFollow.ts'
 export type * from './models/SessionAlertState.ts'
 export type * from './models/Agent.ts'
 export type * from './models/AgentEnv.ts'
+export type * from './models/GitHubEnterpriseApp.ts'
 export type * from './models/AgentCronJob.ts'
 export type * from './models/AgentTool.ts'
 export type * from './models/AgentToken.ts'
@@ -34,4 +35,5 @@ export type * from './models/AgentGitHubInstallationsSnapshot.ts'
 export type * from './models/PushSubscription.ts'
 export type * from './models/ChatThreadWatch.ts'
 export type * from './models/UserNotificationPrefs.ts'
+export type * from './models/AgentMarketplace.ts'
 export type * from './commonInputTypes.ts'

package/prisma/migrations/20261101000000_add_agent_marketplace/migration.sql

@@ -0,0 +1,19 @@
+-- PMK-1.1: AgentMarketplace table for per-agent plugin marketplaces (additive only).
+-- CreateTable
+CREATE TABLE "AgentMarketplace" (
+    "id" TEXT NOT NULL,
+    "agentId" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "source" TEXT NOT NULL,
+    "ref" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "AgentMarketplace_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "AgentMarketplace_agentId_name_key" ON "AgentMarketplace"("agentId", "name");
+
+-- AddForeignKey
+ALTER TABLE "AgentMarketplace" ADD CONSTRAINT "AgentMarketplace_agentId_fkey" FOREIGN KEY ("agentId") REFERENCES "Agent"("id") ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/migrations/20261109000000_add_github_enterprise_app/migration.sql

@@ -0,0 +1,16 @@
+-- GHE-1.1: optional admin-level GitHub Apps (installer / lookup). Additive only: new table.
+-- CreateTable
+CREATE TABLE "GitHubEnterpriseApp" (
+    "role" TEXT NOT NULL,
+    "appId" TEXT NOT NULL,
+    "slug" TEXT NOT NULL,
+    "enterpriseSlug" TEXT,
+    "privateKeyEncrypted" TEXT NOT NULL,
+    "lastValidationStatus" TEXT,
+    "lastValidatedAt" TIMESTAMP(3),
+    "lastValidationError" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "GitHubEnterpriseApp_pkey" PRIMARY KEY ("role")
+);

package/prisma/schema/schema.prisma

@@ -1,5 +1,6 @@
 // Shipwright — Admin Service Schema
 // Owns: Agent, AgentEnv, AgentCronJob, AgentTool, AgentToken, AgentPlugin,
+// AgentMarketplace,
 // plus the coding-owned models in coding.prisma (AgentWorkQueueSnapshot,
 // AgentPhaseMethodology, SessionFollow, SessionAlertState).
 // Agent is a first-class model (standalone, not embedded in a User model).
@@ -88,6 +89,7 @@ model Agent {
   tools            AgentTool[]
   tokens           AgentToken[]
   plugins          AgentPlugin[]
+  marketplaces     AgentMarketplace[]
   members          AgentMember[]
   chatTokenUsage   AgentChatTokenUsageDailyByModel[]
   workQueueSnapshot AgentWorkQueueSnapshot?
@@ -114,6 +116,24 @@ model AgentEnv {
   @@unique([agentId, key])
 }
 
+// ─── GitHub Enterprise Apps ───────────────────────────────────────────────────
+// Optional admin-level GitHub Apps, one per role ('installer' | 'lookup'), at most
+// two rows per deployment; no rows means the feature is off. Deliberately NOT in
+// AgentEnv so the private key can never reach the agent config bundle.
+
+model GitHubEnterpriseApp {
+  role                  String    @id // 'installer' | 'lookup'
+  appId                 String
+  slug                  String
+  enterpriseSlug        String?   // installer only
+  privateKeyEncrypted   String    // AES-256-GCM (iv:ciphertext:authTag); never returned by any read path
+  lastValidationStatus  String?
+  lastValidatedAt       DateTime?
+  lastValidationError   String?
+  createdAt             DateTime  @default(now())
+  updatedAt             DateTime  @updatedAt
+}
+
 // ─── Agent Cron Jobs ──────────────────────────────────────────────────────────
 // Scheduled prompts per agent.
 // Delivery target is either a Slack channel ID or a Slack user ID (DM).
@@ -569,3 +589,20 @@ model UserNotificationPrefs {
   updatedAt          DateTime  @updatedAt
 }
 
+
+// ─── AgentMarketplace ─────────────────────────────────────────────────────────
+// Plugin marketplaces registered per agent. `name` is the marketplace name that
+// AgentPlugin specs reference after the `@` (e.g. "plugin@<name>").
+
+model AgentMarketplace {
+  id        String   @id @default(cuid())
+  agentId   String
+  agent     Agent    @relation(fields: [agentId], references: [id], onDelete: Cascade)
+  name      String
+  source    String
+  ref       String?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([agentId, name])
+}

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

@@ -0,0 +1,82 @@
+/**
+ * admin/src/agent-marketplaces.integration.test.ts
+ * Integration tests for the AgentMarketplace model 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 { createAdminPrismaClient } from "./prisma-client.ts";
+
+const TEST_DB = process.env.DATABASE_URL_ADMIN_TEST;
+
+const describeOrSkip = TEST_DB ? describe : describe.skip;
+
+describeOrSkip("AgentMarketplace (integration)", () => {
+  let prisma: PrismaClient;
+
+  beforeEach(async () => {
+    prisma = createAdminPrismaClient(TEST_DB as string);
+    await prisma.agentMarketplace.deleteMany();
+    await prisma.agentPlugin.deleteMany();
+    await prisma.agentToken.deleteMany();
+    await prisma.agentCronJob.deleteMany();
+    await prisma.agentTool.deleteMany();
+    await prisma.agentEnv.deleteMany();
+    await prisma.agent.deleteMany();
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  async function createAgent(): Promise<string> {
+    return (await prisma.agent.create({ data: { name: "Test Agent" } })).id;
+  }
+
+  it("inserts a row and reads it back", async () => {
+    const agentId = await createAgent();
+    const created = await prisma.agentMarketplace.create({
+      data: {
+        agentId,
+        name: "shipwright",
+        source: "github:app-vitals/shipwright",
+      },
+    });
+    const found = await prisma.agentMarketplace.findUnique({
+      where: { id: created.id },
+    });
+    expect(found?.agentId).toBe(agentId);
+    expect(found?.name).toBe("shipwright");
+    expect(found?.source).toBe("github:app-vitals/shipwright");
+    expect(found?.ref).toBeNull();
+    expect(found?.createdAt).toBeInstanceOf(Date);
+    expect(found?.updatedAt).toBeInstanceOf(Date);
+  });
+
+  it("rejects a duplicate (agentId, name)", async () => {
+    const agentId = await createAgent();
+    await prisma.agentMarketplace.create({
+      data: { agentId, name: "dup", source: "a" },
+    });
+    await expect(
+      (async () =>
+        prisma.agentMarketplace.create({
+          data: { agentId, name: "dup", source: "b", ref: "main" },
+        }))(),
+    ).rejects.toThrow();
+  });
+
+  it("cascades when the agent is deleted", async () => {
+    const agentId = await createAgent();
+    await prisma.agentMarketplace.create({
+      data: { agentId, name: "m1", source: "a" },
+    });
+    await prisma.agentMarketplace.create({
+      data: { agentId, name: "m2", source: "b", ref: "v1" },
+    });
+    await prisma.agent.delete({ where: { id: agentId } });
+    expect(await prisma.agentMarketplace.count({ where: { agentId } })).toBe(0);
+  });
+});

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/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();
+  });
+});