Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

23.8 KB
Raw Blame
import { and, desc, eq, isNull } from "drizzle-orm";
import { type AuditStore, recordAuditEvent } from "./audit";
import type { Database } from "./db/client";
import { reasonWithoutStatement } from "./db/query-failure";
import { type credentialKind, credentials } from "./db/schema";

type CredentialEnvelope = {
  version: 1;
  iv: string;
  ciphertext: string;
};

const encoder = new TextEncoder();
const decoder = new TextDecoder();

/**
 * Derived from the enum rather than written out again.
 *
 * These were two lists that had to agree, and nothing made them. A kind added to the schema and not
 * here fails at the point of use with a type error about an unrelated call site; a kind removed from
 * the schema and left here compiles and then violates a check constraint at runtime. One source now.
 */
export type CredentialKind = (typeof credentialKind.enumValues)[number];

export type CredentialStatus = {
  id: string;
  kind: CredentialKind;
  provider: string;
  keyId: string;
  metadata: Record<string, unknown>;
  revokedAt: Date | null;
};

type StoredCredential = {
  id: string;
  revokedAt: Date | null;
};

export type CredentialStoreValue = {
  kind: CredentialKind;
  provider: string;
  keyId: string;
  metadata: Record<string, unknown>;
  encryptedValue: string;
};

type Transaction = Parameters<Parameters<Database["transaction"]>[0]>[0];

/**
 * Where a credential write runs.
 *
 * A caller already inside a transaction passes it here, so the write joins that
 * transaction rather than opening one of its own on a second pooled connection.
 * Two connections would mean the credential committing separately from the
 * change that asked for it, and, since the caller is usually holding row locks
 * by then, a pool with nothing spare to hand out deadlocks instead. See the
 * note on `max` in `db/client.ts`.
 */
export type CredentialExecutor =
  | Pick<Database, "select" | "insert" | "update">
  | Pick<Transaction, "select" | "insert" | "update">;

export type CredentialStore = {
  create: (
    value: CredentialStoreValue,
    executor?: CredentialExecutor,
  ) => Promise<StoredCredential>;
  /**
   * Re-encrypt a live row in place, keeping the id everything already points at.
   *
   * A vendor whose refresh token ROTATES is the one caller. It has already killed the old token at
   * its end by the time it answers, so there is no second grant left to withdraw and nothing to
   * learn from a new row — only a row per tool call, forever. A person RECONNECTING still goes
   * through `rotate`, because that is the act that leaves a live grant behind for us to withdraw at
   * our side too.
   *
   * A revoked or missing row is refused rather than written through: a grant somebody withdrew must
   * not come back to life by being handed a fresh secret.
   *
   * Without an executor this writes on its own connection. With one it joins the caller's
   * transaction, which is how the caller that has locked this row spends the token under that lock:
   * the write has to commit with the lock rather than beside it.
   */
  updateSecret: (
    id: string,
    encryptedValue: string,
    executor?: CredentialExecutor,
  ) => Promise<void>;
  /**
   * Replace one credential with another, atomically.
   *
   * Retiring the old secret and storing the new one are one decision, so they
   * are one write. Two separate calls cannot be made safe from the outside:
   * an `UPDATE` can commit and still throw on the way back, and no compensating
   * revoke survives the process being killed between them.
   *
   * Without an executor this opens its own transaction. With one it runs inside
   * the caller's, and is atomic with whatever else that transaction is doing.
   */
  rotate: (
    input: CredentialStoreValue & { previousCredentialId: string },
    executor?: CredentialExecutor,
  ) => Promise<StoredCredential>;
  revoke: (id: string, executor?: CredentialExecutor) => Promise<Date>;
  /** Whether this credential exists and has not been revoked. */
  isLive: (id: string, executor?: CredentialExecutor) => Promise<boolean>;
  /**
   * The live credential for a key, if this deployment holds one.
   *
   * At most one can exist, which is what `credentials_active_key_idx`
   * enforces, so a caller about to store a secret for a key can ask whether it
   * is replacing something rather than finding out from a failed insert.
   */
  findLiveByKey: (
    key: { kind: CredentialKind; provider: string; keyId: string },
    executor?: CredentialExecutor,
  ) => Promise<{ id: string } | null>;
};

export type CredentialSecretReader = {
  readSecret: (id: string) => Promise<{
    encryptedValue: string;
    revokedAt: Date | null;
  } | null>;
};

export type CredentialStatusReader = {
  list: () => Promise<CredentialStatus[]>;
};

export type ModelCredentialSecretReader = {
  readModelSecret: (input: {
    provider: "openai" | "anthropic";
    keyId: string;
  }) => Promise<{ encryptedValue: string } | null>;
};

type CredentialService = {
  encryptionKey: string;
  store: CredentialStore;
  auditStore: AuditStore;
};

async function aesKey(encodedKey: string) {
  return crypto.subtle.importKey(
    "raw",
    Buffer.from(encodedKey, "base64"),
    { name: "AES-GCM" },
    false,
    ["encrypt", "decrypt"],
  );
}

function parseEnvelope(value: string): CredentialEnvelope {
  try {
    const envelope = JSON.parse(value) as CredentialEnvelope;
    if (
      envelope.version !== 1 ||
      typeof envelope.iv !== "string" ||
      typeof envelope.ciphertext !== "string"
    ) {
      throw new Error("invalid envelope");
    }
    return envelope;
  } catch {
    throw new Error("Credential envelope is invalid");
  }
}

export async function encryptSecret(encodedKey: string, plaintext: string) {
  const iv = crypto.getRandomValues(new Uint8Array(12));
  const ciphertext = await crypto.subtle.encrypt(
    { name: "AES-GCM", iv },
    await aesKey(encodedKey),
    encoder.encode(plaintext),
  );

  return JSON.stringify({
    version: 1,
    iv: Buffer.from(iv).toString("base64"),
    ciphertext: Buffer.from(ciphertext).toString("base64"),
  } satisfies CredentialEnvelope);
}

export async function decryptSecret(encodedKey: string, value: string) {
  const envelope = parseEnvelope(value);
  const plaintext = await crypto.subtle.decrypt(
    { name: "AES-GCM", iv: Buffer.from(envelope.iv, "base64") },
    await aesKey(encodedKey),
    Buffer.from(envelope.ciphertext, "base64"),
  );

  return decoder.decode(plaintext);
}

/**
 * The vault answered, and what it holds cannot be spent: the row is gone, or it is revoked.
 *
 * CRITERION. This is the ONLY thing {@link decryptCredentialForUse} raises that means "access was
 * withdrawn". Everything else it can raise — a query this database refused, a connection it could
 * not open, an envelope that would not decrypt — is a fault, and a caller must be able to tell the
 * two apart without reading either message.
 *
 * REASON. The two used to be plain `Error`s and the only thing separating them from a fault was
 * their wording, which `plugins/store.ts` matched on: a message containing "revoked" or "not found"
 * was a withdrawal, anything else was an error. drizzle reports a failed query as a message that
 * BEGINS `Failed query: select "encrypted_value", "revoked_at" from "credentials" …`, so the column
 * this function reads put the substring into every database fault on this very read — Postgres
 * down, a wrong address, a cancelled statement — and each was announced to the person, the model and
 * the operator as an administrator having taken the credential away. A class cannot be produced by
 * accident that way, and it survives a reworded sentence, which is the same argument
 * `TokenRefusedError` carries a `code` for rather than a phrase in its prose.
 *
 * ONE CLASS FOR BOTH STATES, because no caller acts on the difference: the row being absent and the
 * row being retired are both "this credential is not available and will not become available", and
 * the step is the same. The messages stay distinct for whoever is reading a log.
 */
export class CredentialUnusableError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "CredentialUnusableError";
  }
}

/**
 * An administrator asked to revoke or rotate a credential that cannot be revoked or rotated as asked.
 *
 * The id names no credential, or one already revoked, or one that is not what the input describes.
 * It carries the status the route answers with. As a plain `Error` it left the route as a bare 500,
 * so a second click on Revoke read as the deployment being broken rather than the credential being
 * gone already.
 */
export class CredentialRefusedError extends Error {
  readonly status: 404 | 409;

  constructor(message: string, status: 404 | 409) {
    super(message);
    this.name = "CredentialRefusedError";
    this.status = status;
  }
}

export async function decryptCredentialForUse(
  encodedKey: string,
  reader: CredentialSecretReader,
  credentialId: string,
) {
  const credential = await reader.readSecret(credentialId);
  if (!credential) {
    throw new CredentialUnusableError("Credential was not found");
  }
  if (credential.revokedAt) {
    throw new CredentialUnusableError("Credential is revoked");
  }

  return decryptSecret(encodedKey, credential.encryptedValue);
}

export async function resolveModelApiKey(input: {
  encryptionKey: string;
  reader: ModelCredentialSecretReader;
  provider: "openai" | "anthropic";
  keyId: string;
  environment: Record<string, string | undefined>;
}) {
  const stored = await input.reader.readModelSecret({
    provider: input.provider,
    keyId: input.keyId,
  });
  if (stored) {
    return decryptSecret(input.encryptionKey, stored.encryptedValue);
  }

  const environmentKey =
    input.environment[
      input.provider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY"
    ]?.trim();
  return environmentKey || null;
}

export function createCredentialStore(
  database: Database,
): CredentialStore &
  CredentialSecretReader &
  CredentialStatusReader &
  ModelCredentialSecretReader {
  return {
    create: async (value, executor = database) => {
      const [credential] = await executor
        .insert(credentials)
        .values(value)
        .returning({ id: credentials.id, revokedAt: credentials.revokedAt });

      if (!credential) {
        throw new Error("Credential could not be stored");
      }
      return credential;
    },
    updateSecret: async (id, encryptedValue, executor = database) => {
      const [credential] = await executor
        .update(credentials)
        .set({ encryptedValue, updatedAt: new Date() })
        .where(and(eq(credentials.id, id), isNull(credentials.revokedAt)))
        .returning({ id: credentials.id });

      /*
       * One statement, so nothing can revoke the row between a check and the write.
       *
       * The cost is that "no such row" and "revoked" arrive as the same answer, hence the one
       * message naming both. The caller acts identically on either: it refuses its call.
       */
      if (!credential) {
        throw new Error("Credential was not found or is revoked");
      }
    },
    rotate: async (input, executor) => {
      const write = async (transaction: CredentialExecutor) => {
        /**
         * The previous credential, locked for the rest of the transaction.
         *
         * Two replicas rotating the same secret would otherwise both read it
         * as live and both act; the second waits here and then finds it
         * revoked. Its identity is read alongside its state so a rotation
         * aimed at the wrong id is refused rather than silently retiring a
         * secret the caller never named.
         */
        const [previous] = await transaction
          .select({
            revokedAt: credentials.revokedAt,
            kind: credentials.kind,
            provider: credentials.provider,
            keyId: credentials.keyId,
          })
          .from(credentials)
          .where(eq(credentials.id, input.previousCredentialId))
          .for("update");
        if (!previous) {
          throw new CredentialRefusedError(
            "Previous credential was not found",
            404,
          );
        }
        if (previous.revokedAt) {
          throw new CredentialRefusedError(
            "Previous credential is already revoked",
            409,
          );
        }
        if (
          previous.kind !== input.kind ||
          previous.provider !== input.provider ||
          previous.keyId !== input.keyId
        ) {
          throw new CredentialRefusedError(
            "Previous credential does not match the input's kind, provider or keyId",
            409,
          );
        }

        // Revoke, then insert. Both orders are invisible from outside the
        // transaction, and this one never holds two live rows for one key even
        // in the middle of it, which is the invariant a uniqueness constraint
        // on live credentials would later depend on.
        const revokedAt = new Date();
        const [revoked] = await transaction
          .update(credentials)
          .set({ revokedAt, updatedAt: revokedAt })
          .where(
            and(
              eq(credentials.id, input.previousCredentialId),
              isNull(credentials.revokedAt),
            ),
          )
          .returning({ revokedAt: credentials.revokedAt });
        if (!revoked?.revokedAt) {
          // Ruled out by the lock above under contention; reaching here means
          // the row was deleted outright between the two statements, which
          // aborts the transaction and leaves nothing committed.
          throw new Error("Previous credential was not found");
        }

        const [inserted] = await transaction
          .insert(credentials)
          .values({
            kind: input.kind,
            provider: input.provider,
            keyId: input.keyId,
            metadata: input.metadata,
            encryptedValue: input.encryptedValue,
          })
          .returning({
            id: credentials.id,
            revokedAt: credentials.revokedAt,
          });
        if (!inserted) {
          throw new Error("Credential could not be stored");
        }

        return inserted;
      };

      // A caller already in a transaction has its own atomicity to keep, and
      // the credential belongs to it rather than to a transaction of its own.
      return executor ? write(executor) : database.transaction(write);
    },
    revoke: async (id, executor = database) => {
      const revokedAt = new Date();
      const [credential] = await executor
        .update(credentials)
        .set({ revokedAt, updatedAt: revokedAt })
        // Only a live row is stamped. Without the guard a second revoke would
        // overwrite the first one's timestamp and report success, so a caller
        // could not tell retiring a credential from finding it already gone.
        .where(and(eq(credentials.id, id), isNull(credentials.revokedAt)))
        .returning({ revokedAt: credentials.revokedAt });

      if (!credential?.revokedAt) {
        throw new CredentialRefusedError(
          "Credential was not found or already revoked",
          404,
        );
      }
      return credential.revokedAt;
    },
    isLive: async (id, executor = database) => {
      const [credential] = await executor
        .select({ id: credentials.id })
        .from(credentials)
        .where(and(eq(credentials.id, id), isNull(credentials.revokedAt)));

      return credential !== undefined;
    },
    findLiveByKey: async ({ kind, provider, keyId }, executor = database) => {
      const [credential] = await executor
        .select({ id: credentials.id })
        .from(credentials)
        .where(
          and(
            eq(credentials.kind, kind),
            eq(credentials.provider, provider),
            eq(credentials.keyId, keyId),
            isNull(credentials.revokedAt),
          ),
        );

      return credential ?? null;
    },
    readSecret: async (id) => {
      const [credential] = await database
        .select({
          encryptedValue: credentials.encryptedValue,
          revokedAt: credentials.revokedAt,
        })
        .from(credentials)
        .where(eq(credentials.id, id));

      return credential ?? null;
    },
    readModelSecret: async ({ provider, keyId }) => {
      const [credential] = await database
        .select({ encryptedValue: credentials.encryptedValue })
        .from(credentials)
        .where(
          and(
            eq(credentials.kind, "model"),
            eq(credentials.provider, provider),
            eq(credentials.keyId, keyId),
            isNull(credentials.revokedAt),
          ),
        )
        .orderBy(
          desc(credentials.createdAt),
          // UUID descending selects the lexicographically greatest ID on a timestamp tie.
          desc(credentials.id),
        )
        .limit(1);

      return credential ?? null;
    },
    list: async () => {
      const records = await database
        .select({
          id: credentials.id,
          kind: credentials.kind,
          provider: credentials.provider,
          keyId: credentials.keyId,
          metadata: credentials.metadata,
          revokedAt: credentials.revokedAt,
        })
        .from(credentials)
        .orderBy(credentials.createdAt);

      return records.map((credential) => ({
        ...credential,
        metadata: credential.metadata as Record<string, unknown>,
      }));
    },
  };
}

export type CredentialInput = {
  kind: CredentialKind;
  provider: string;
  keyId: string;
  metadata: Record<string, unknown>;
  plaintext: string;
  actorUserId?: string;
};

export type CredentialAdminService = CredentialStatusReader & {
  create: (input: CredentialInput) => Promise<CredentialStatus>;
  rotate: (
    input: CredentialInput & { previousCredentialId: string },
  ) => Promise<CredentialStatus>;
  revoke: (
    credentialId: string,
    actorUserId?: string,
  ) => Promise<{
    id: string;
    revokedAt: Date;
  }>;
};

async function persistCredential(
  service: CredentialService,
  input: CredentialInput,
): Promise<CredentialStatus> {
  const stored = await service.store.create({
    kind: input.kind,
    provider: input.provider,
    keyId: input.keyId,
    metadata: input.metadata,
    encryptedValue: await encryptSecret(service.encryptionKey, input.plaintext),
  });

  return {
    id: stored.id,
    kind: input.kind,
    provider: input.provider,
    keyId: input.keyId,
    metadata: input.metadata,
    revokedAt: stored.revokedAt,
  };
}

/**
 * Store a credential for a key.
 *
 * A key holds one live credential, so storing a second one for a key that
 * already has one is a replacement rather than an addition, and it is carried
 * out as a rotation: the two writes are atomic and the trail records
 * `credential.rotated` naming what was replaced.
 *
 * This is the shape the product asks for. The Credentials page offers Add and
 * Revoke and has no rotate control, so replacing a model key is done by adding
 * one for the same provider and keyId. Refusing that would leave no way to
 * replace a key at all, and inserting it would raise a bare unique violation
 * from `credentials_active_key_idx`.
 */
export async function createCredential(
  service: CredentialService,
  input: CredentialInput,
): Promise<CredentialStatus> {
  const existing = await service.store.findLiveByKey({
    kind: input.kind,
    provider: input.provider,
    keyId: input.keyId,
  });
  if (existing) {
    return rotateCredential(service, {
      ...input,
      previousCredentialId: existing.id,
    });
  }

  const credential = await persistCredential(service, input);

  await recordAuditEvent(service.auditStore, {
    eventType: "credential.created",
    targetType: "credential",
    targetId: credential.id,
    actorUserId: input.actorUserId,
    payload: {
      kind: input.kind,
      provider: input.provider,
      keyId: input.keyId,
    },
  });

  return credential;
}

export async function rotateCredential(
  service: CredentialService,
  input: CredentialInput & { previousCredentialId: string },
): Promise<CredentialStatus> {
  // Encryption happens before the transaction opens, so no database connection
  // is held while it runs. The store then performs both writes atomically, and
  // a failure leaves the vault as it was, which is why the success event below
  // is written only once that has returned.
  let stored: StoredCredential;
  try {
    stored = await service.store.rotate({
      previousCredentialId: input.previousCredentialId,
      kind: input.kind,
      provider: input.provider,
      keyId: input.keyId,
      metadata: input.metadata,
      encryptedValue: await encryptSecret(
        service.encryptionKey,
        input.plaintext,
      ),
    });
  } catch (error) {
    /*
     * A refused rotation is worth a row of its own.
     *
     * The vault refuses one aimed at a credential that is already revoked, one aimed at a credential
     * that does not exist, and one whose key does not match the credential it names. Each of those is
     * either a caller with a bug or an attempt to retire a key the caller was not asked to retire,
     * and each of them left nothing behind while only successes were recorded.
     *
     * Written outside the transaction that has just rolled back, so the row survives the failure it
     * describes.
     *
     * THE REASON IS ASKED FOR THROUGH {@link reasonWithoutStatement}, and the sentence this comment
     * used to carry — "the vault's own message and never the secret, which never left this
     * function" — was false. Not every throw caught here is the vault's own: the rotation runs
     * three statements, and a `DrizzleQueryError` from any of them has `Failed query: <the
     * statement>` and `params: <every bound value>` for a message. The insert binds
     * `encryptedValue`, so the values in that message include the credential envelope this function
     * had just built — and `audit_events` is append-only by trigger, exported, and kept for the
     * deployment's whole retention window, so a secret landing there is not one anybody can take
     * back out. A refusal the vault itself wrote still arrives here word for word; only the shape
     * that carries a statement is answered with the driver's complaint instead.
     */
    await recordAuditEvent(service.auditStore, {
      eventType: "credential.rotation_refused",
      targetType: "credential",
      targetId: input.previousCredentialId,
      actorUserId: input.actorUserId,
      payload: {
        kind: input.kind,
        provider: input.provider,
        keyId: input.keyId,
        reason: reasonWithoutStatement(error),
      },
    });
    throw error;
  }

  await recordAuditEvent(service.auditStore, {
    eventType: "credential.rotated",
    targetType: "credential",
    targetId: stored.id,
    actorUserId: input.actorUserId,
    payload: {
      previousCredentialId: input.previousCredentialId,
      kind: input.kind,
      provider: input.provider,
      keyId: input.keyId,
    },
  });

  return {
    id: stored.id,
    kind: input.kind,
    provider: input.provider,
    keyId: input.keyId,
    metadata: input.metadata,
    revokedAt: stored.revokedAt,
  };
}

export async function revokeCredential(
  service: CredentialService,
  credentialId: string,
  actorUserId?: string,
) {
  const revokedAt = await service.store.revoke(credentialId);

  await recordAuditEvent(service.auditStore, {
    eventType: "credential.revoked",
    targetType: "credential",
    targetId: credentialId,
    actorUserId,
    payload: {},
  });

  return { id: credentialId, revokedAt };
}

export function createCredentialAdminService(
  encryptionKey: string,
  store: CredentialStore & CredentialStatusReader,
  auditStore: AuditStore,
): CredentialAdminService {
  const service = { encryptionKey, store, auditStore };

  return {
    list: store.list,
    create: (input) => createCredential(service, input),
    rotate: (input) => rotateCredential(service, input),
    revoke: (credentialId, actorUserId) =>
      revokeCredential(service, credentialId, actorUserId),
  };
}