app/lib/agent-keys.server.ts

Functions

Imports

It imports no other module of this repo. Imported by app/lib/mcp/door.ts, app/lib/people-admin.server.ts, app/lib/people.server.ts.

Source

1// Named agent keys, for AI agents that cannot complete the door's OAuth sign-in (Grok Build could
2// not do CIMD as of 2026-09-07). The pattern is dustinedwards-mcp's: one Worker secret per agent,
3// and the secret's NAME is the agent. AGENT_KEY_GROK is the key for the agent "grok".
4//
5// The name is never taken from the request. It is a property of WHICH configured secret the
6// presented key matched, so a caller proves it holds a key and can never choose what it is called.
7//
8// This file decides who is knocking, and nothing more. What that agent may do comes from the
9// person row "agent:<name>" in Carrel's People table (people.server.ts, findAgentViewer), never
10// from the key, and the functions every tool calls refuse what the role does not allow.
11
12/** The prefix that makes a Worker secret an agent key. */
13const AGENT_KEY_PREFIX = "AGENT_KEY_";
14
15/** The shape of an agent's name: what follows the prefix, lower-cased. */
16const AGENT_NAME = /^[a-z0-9][a-z0-9_-]{0,31}$/;
17
18export function isAgentName(name: string): boolean {
19  return AGENT_NAME.test(name);
20}
21
22/** The email an agent's person row carries. Not an address: no mailbox, and Access can never present it. */
23export function agentEmail(name: string): string {
24  return `agent:${name}`;
25}
26
27/** What the audit trail credits an agent's writes to: the same text as its person row's email. */
28export function agentClient(name: string): string {
29  return agentEmail(name);
30}
31
32async function sha256(value: string): Promise<Uint8Array<ArrayBuffer>> {
33  return new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value)));
34}
35
36/**
37 * Constant-time equality over fixed-size SHA-256 digests, so the time taken says nothing about the
38 * key's length or how much of it was right. crypto.subtle.timingSafeEqual where the runtime has it
39 * (Workers does), else a byte loop over the two 32-byte digests.
40 */
41export async function keysMatch(presented: string, expected: string): Promise<boolean> {
42  const [a, b] = await Promise.all([sha256(presented), sha256(expected)]);
43  const native = (crypto.subtle as { timingSafeEqual?: (x: BufferSource, y: BufferSource) => boolean }).timingSafeEqual;
44  if (typeof native === "function") return native.call(crypto.subtle, a, b);
45  let diff = 0;
46  for (let i = 0; i < a.length; i += 1) diff |= a[i]! ^ b[i]!;
47  return diff === 0;
48}
49
50/**
51 * Which agent, if any, presented this Authorization header. Null for a missing or malformed header,
52 * for any key that matches no configured secret (an OAuth access token is one of these), and when no
53 * AGENT_KEY_* secret exists at all: the door is then exactly what it was. Null always means "fall
54 * through to OAuth", never "this is an agent".
55 *
56 * A secret that is blank, or whose name is not a valid agent name, is skipped, so an empty secret
57 * cannot become a master key. Every candidate is compared, with no early exit, so the time taken
58 * does not depend on which key matched or where it sat.
59 */
60export async function agentPrincipal(env: object, authorization: string | null): Promise<string | null> {
61  if (!authorization) return null;
62  const match = /^Bearer[ ]+(\S+)$/i.exec(authorization.trim());
63  if (!match) return null;
64  const presented = match[1]!;
65
66  let found: string | null = null;
67  for (const [secret, value] of Object.entries(env)) {
68    if (!secret.startsWith(AGENT_KEY_PREFIX)) continue;
69    const name = secret.slice(AGENT_KEY_PREFIX.length).toLowerCase();
70    if (!isAgentName(name) || typeof value !== "string" || !value.trim()) continue;
71    if (await keysMatch(presented, value.trim())) found = name;
72  }
73  return found;
74}