Multiplayer agent harness for work.
import type { AdvisoryLock } from "../persistence/advisory-lock.ts";
import { orgId as configOrgId } from "../config.ts";
import { randomBytes } from "node:crypto";
import { validateHeaderName, validateHeaderValue } from "node:http";
import { HOP_BY_HOP } from "../util/http-proxy.ts";
import { scopeId as toScopeId, parseScopeId, type Destination, type ScopeId } from "../types.ts";
import type { DurableMap } from "../persistence/durable-map.ts";
import { encryptSecret, decryptSecret, type SecretKey } from "../connectors/connector-client-store.ts";
import { errMessage } from "../util/errors.ts";
import { canonicalPerson, personIds, personKey, samePerson } from "../directory/person.ts";
import { cronIdOf } from "../sessions/session-store.ts";
import { hashId } from "../util/crypto.ts";
import { shq } from "../util/shell.ts";
import { homeRelativePath } from "./paths.ts";
import { connectorTokenNote, envKey } from "./connector-token.ts";
const COMPOSIO_ENV_KEY = "COMPOSIO_API_KEY";
export function isBackendCredential(c: { envKey?: string; fields?: ReadonlyArray<{ envKey: string }> }): boolean {
return c.envKey === COMPOSIO_ENV_KEY || c.fields?.some((f) => f.envKey === COMPOSIO_ENV_KEY) === true;
}
export function isComposioHost(host: string): boolean {
const normalized = host.toLowerCase().replace(/\.$/, "");
return normalized === "composio.dev" || normalized.endsWith(".composio.dev");
}
type CredentialKind = "env" | "file" | "broker";
export interface CredentialInjection {
header?: string;
scheme?: string;
actor?: boolean;
headers?: Record<string, string>;
}
const DEFAULT_AUTH_HEADER = "Authorization";
const RESERVED_FIXED_HEADERS = new Set([
...HOP_BY_HOP,
"authorization",
"content-encoding",
"content-length",
"content-type",
"cookie",
"expect",
"host",
"x-qm-actor",
]);
const headerError = (validate: () => void): boolean => {
try {
validate();
return false;
} catch {
return true;
}
};
function fixedHeadersError(headers: unknown, authHeader: string): string | undefined {
if (headers === undefined) return undefined;
if (!headers || typeof headers !== "object" || Array.isArray(headers)) return "injection.headers must be an object";
const seen = new Set<string>();
for (const [name, value] of Object.entries(headers)) {
const lower = name.toLowerCase();
if (headerError(() => validateHeaderName(name)))
return `injection.headers: "${name}" is not a valid HTTP header name`;
if (RESERVED_FIXED_HEADERS.has(lower) || lower === authHeader) return `injection.headers cannot set ${lower}`;
if (seen.has(lower)) return `injection.headers lists ${lower} more than once`;
seen.add(lower);
if (typeof value !== "string" || !value || headerError(() => validateHeaderValue(name, value)))
return `injection.headers.${name} must be a non-empty valid HTTP header value`;
}
return undefined;
}
export function credentialRequestHeaders(rec: {
injection?: CredentialInjection;
secret: string;
}): Record<string, string> {
const header = rec.injection?.header || DEFAULT_AUTH_HEADER;
const rawScheme = rec.injection?.scheme ?? "Bearer ";
const scheme = rawScheme && !/\s$/.test(rawScheme) ? `${rawScheme} ` : rawScheme;
return { ...rec.injection?.headers, [header]: `${scheme}${rec.secret}` };
}
export function credentialInjectionError(value: unknown): string | undefined {
if (value === undefined) return undefined;
if (!value || typeof value !== "object" || Array.isArray(value)) return "injection must be an object";
const injection = value as CredentialInjection;
if (injection.actor !== undefined && typeof injection.actor !== "boolean") return "injection.actor must be boolean";
if (
injection.header !== undefined &&
(typeof injection.header !== "string" || headerError(() => validateHeaderName(injection.header!)))
)
return "authentication header must be a valid HTTP header name";
if (injection.header?.toLowerCase() === "x-qm-actor") return "x-qm-actor is reserved for broker actor attestation";
if (injection.scheme !== undefined && (typeof injection.scheme !== "string" || /[\r\n]/.test(injection.scheme)))
return "authentication value prefix must be a single line";
return fixedHeadersError(injection.headers, (injection.header || DEFAULT_AUTH_HEADER).toLowerCase());
}
interface BrokerDelivery {
name: string;
delivery?: "broker" | "env";
envKey?: string;
injection?: CredentialInjection;
allowedMethods?: string[];
allowedPathPrefixes?: string[];
deployments?: boolean;
enabled: boolean;
updatedBy?: string;
}
interface CredentialRefresh {
refreshTokenEnc?: string;
idTokenEnc?: string;
accountId?: string;
accountType?: string;
clientRef?: string;
grantedScopes?: string[];
refreshFailedAt?: number;
refreshError?: string;
orgId?: string;
}
export interface CredentialFile {
path: string;
contentBase64: string;
mode?: number;
}
export function restoredFileMode(mode?: number): number {
return ((mode ?? 0o600) & 0o700) | 0o600;
}
interface CredentialFieldMeta {
envKey: string;
secret: boolean;
}
export interface CredentialFieldInput {
envKey: string;
value: string;
secret?: boolean;
}
export interface KeychainCredential {
id: string;
ownerId: string;
orgId?: string;
service: string;
kind: CredentialKind;
envKey?: string;
target?: string;
targets?: string[];
host?: string;
accountLabel?: string;
fields?: CredentialFieldMeta[];
broker?: BrokerDelivery;
refresh?: CredentialRefresh;
managed?: "connector";
secretEnc: string;
fingerprint: string;
origin?: string;
expiresAt?: number;
createdAt: number;
updatedAt: number;
}
export type KeychainCredentialMeta = Omit<KeychainCredential, "secretEnc"> & { credentialHandle?: string };
export type GrantMode = "once" | "standing";
export interface KeychainGrant {
id: string;
credentialId: string;
ownerId: string;
orgId?: string;
audienceScopeId: ScopeId;
mode: GrantMode;
purpose: string;
status: "active" | "revoked" | "used";
createdAt: number;
expiresAt?: number;
revokedAt?: number;
usedAt?: number;
usedBy?: string;
askId?: string;
}
type AskStatus = "pending" | "approved" | "declined" | "expired";
export interface KeychainAsk {
id: string;
credentialId: string;
ownerId: string;
requesterId: string;
orgId?: string;
requesterScopeId: ScopeId;
requesterDestination?: Destination;
requesterThreadRef?: string;
requesterSeq?: number;
requesterMessageTs?: string;
purpose: string;
requestedMode?: GrantMode;
status: AskStatus;
createdAt: number;
expiresAt: number;
resolvedAt?: number;
grantId?: string;
note?: string;
notifiedAt?: number;
}
export const ASK_TTL_MS = 24 * 60 * 60_000;
export const ASK_PRUNE_AFTER_MS = 14 * 24 * 60 * 60_000;
export interface ServiceCredentialInput {
slug: string;
name: string;
secret?: string;
delivery?: "broker" | "env";
envKey?: string;
host: string;
injection?: CredentialInjection;
allowedMethods?: string[];
allowedPathPrefixes?: string[];
deployments?: boolean;
enabled?: boolean;
updatedBy?: string;
}
export interface PublicServiceCredential {
slug: string;
name: string;
delivery: "broker" | "env";
envKey?: string;
host: string;
injection?: CredentialInjection;
allowedMethods?: string[];
allowedPathPrefixes?: string[];
deployments: boolean;
enabled: boolean;
hasSecret: boolean;
maxRequestsPerDay?: number;
source?: "deployment";
updatedBy?: string;
updatedAt: number;
}
export interface DecryptedServiceCredential {
slug: string;
name: string;
secret: string;
delivery: "broker" | "env";
envKey?: string;
host: string;
injection?: CredentialInjection;
allowedMethods?: string[];
allowedPathPrefixes?: string[];
deployments: boolean;
enabled: boolean;
maxRequestsPerDay?: number;
source?: "deployment";
}
export function isValidCredentialSlug(slug: string): boolean {
return /^[a-z0-9][a-z0-9-]{0,62}$/.test(slug);
}
export function isValidServiceCredentialEnvKey(envKey: string): boolean {
return /^[A-Z][A-Z0-9_]*$/.test(envKey) && !envKey.startsWith("AGENT_");
}
export function isValidBrokerHost(host: string): boolean {
return Boolean(host) && host === host.toLowerCase() && !/[/:\s]/.test(host);
}
export function isValidBrokerMethod(method: string): boolean {
return /^[A-Z]+$/.test(method);
}
export function isValidBrokerPathPrefix(path: string): boolean {
return path.startsWith("/") && !/[\r\n]/.test(path);
}
export interface ServiceCredentialReader {
getServiceCredentialSecret(orgScopeId: ScopeId, slug: string): Promise<DecryptedServiceCredential | null>;
}
export interface ServiceCredentialStore extends ServiceCredentialReader {
setServiceCredential(orgScopeId: ScopeId, input: ServiceCredentialInput): Promise<void>;
setServiceCredentialIfAbsent(orgScopeId: ScopeId, input: ServiceCredentialInput): Promise<number | null>;
setServiceCredentialIfCurrent(
orgScopeId: ScopeId,
input: ServiceCredentialInput,
expectedUpdatedAt: number,
): Promise<number | null>;
listServiceCredentials(orgScopeId: ScopeId): Promise<PublicServiceCredential[]>;
deleteServiceCredential(orgScopeId: ScopeId, slug: string): Promise<void>;
deleteServiceCredentialIfCurrent(orgScopeId: ScopeId, slug: string, expectedUpdatedAt: number): Promise<boolean>;
}
export interface OAuthToken {
accessToken: string;
refreshToken?: string;
expiresAt?: number;
grantedScopes?: string[];
clientRef?: string;
accountType?: string;
orgId?: string;
/** OIDC id token, for providers whose API needs it alongside the access token (e.g. Codex). */
idToken?: string;
/** Provider-side account identifier carried with the token (e.g. ChatGPT account id). */
accountId?: string;
}
/** Derived, sandbox-safe view of a connector token: never carries the refresh token. */
export interface DerivedOAuthAuth {
accessToken: string;
idToken?: string;
accountId?: string;
expiresAt?: number;
}
export interface OAuthTokenStatus {
connected: boolean;
expiresAt?: number;
hasRefreshToken?: boolean;
needsReconnect?: boolean;
refreshFailedAt?: number;
refreshError?: string;
accountType?: string;
grantedScopes?: string[];
}
export type OAuthRefresh = (
host: string,
token: OAuthToken,
ctx?: { accountType?: string; clientRef?: string },
) => Promise<OAuthToken>;
interface ConnectorMeta {
credentialId: string;
ownerId: string;
host: string;
accountType?: string;
expiresAt?: number;
connected: boolean;
needsReconnect?: boolean;
}
export interface ConnectorTokenStore {
operatorFallbackHosts?: readonly string[];
listConnectorsByOwners?(ownerIds: string[]): Promise<Map<string, ConnectorMeta[]>>;
setConnectorToken(host: string, principalId: string, token: OAuthToken, accountType?: string): Promise<void>;
deleteConnectorToken(host: string, principalId: string, accountType?: string): Promise<void>;
connectorTokenStatus(host: string, principalId: string, accountType?: string): Promise<OAuthTokenStatus>;
connectorAccessToken(host: string, principalId: string, accountType?: string): Promise<string | null>;
/**
* Fresh derived material for the connector token (access + id token +
* account id), refreshing single-flight if stale. The refresh token never
* leaves the keychain record.
*/
connectorDerivedAuth(host: string, principalId: string, accountType?: string): Promise<DerivedOAuthAuth | null>;
}
interface SaveCredentialInput {
ownerId: string;
service: string;
secret?: string;
envKey?: string;
fields?: CredentialFieldInput[];
target?: string;
files?: CredentialFile[];
host?: string;
accountLabel?: string;
origin?: string;
expiresAt?: number;
}
interface CreateGrantInput {
credentialId: string;
ownerId: string;
audienceScopeId: ScopeId;
mode: GrantMode;
purpose: string;
expiresAt?: number;
askId?: string;
}
interface CreateAskInput {
triggered?: boolean;
credentialId: string;
requesterId: string;
requesterScopeId: ScopeId;
requesterDestination?: Destination;
requesterThreadRef?: string;
requesterSeq?: number;
requesterMessageTs?: string;
purpose: string;
requestedMode?: GrantMode;
expiresAt?: number;
}
interface ApproveAskInput {
askId: string;
ownerId: string;
mode: GrantMode;
purpose: string;
expiresAt?: number;
}
interface AskListFilter {
requesterId?: string;
ownerId?: string;
requesterScopeId?: ScopeId;
}
interface MaterializedEnvCred {
credentialId: string;
ownerId: string;
service: string;
env: Array<{ key: string; value: string; secret?: boolean }>;
grantId?: string;
purpose?: string;
}
interface MaterializedFileCred {
credentialId: string;
ownerId: string;
service: string;
files: CredentialFile[];
origin?: string;
grantId?: string;
purpose?: string;
}
export type MaterializedCred = ({ kind: "env" } & MaterializedEnvCred) | ({ kind: "file" } & MaterializedFileCred);
export class KeychainError extends Error {
readonly status: number;
constructor(status: number, message: string) {
super(message);
this.name = "KeychainError";
this.status = status;
}
}
interface GrantListFilter {
ownerId?: string;
audienceScopeId?: ScopeId;
}
export interface Keychain extends ServiceCredentialStore, ConnectorTokenStore {
save(input: SaveCredentialInput): Promise<KeychainCredentialMeta>;
updateFiles(materialized: Extract<MaterializedCred, { kind: "file" }>, files: CredentialFile[]): Promise<void>;
writebackBaseline(
source: FileCredentialSource,
fingerprint: string,
): Promise<Extract<MaterializedCred, { kind: "file" }>>;
listAllMetadata(): Promise<KeychainCredentialMeta[]>;
listByOwner(ownerId: string): Promise<KeychainCredentialMeta[]>;
listByOwners(ownerIds: string[]): Promise<Map<string, KeychainCredentialMeta[]>>;
listConnectorsByOwners(ownerIds: string[]): Promise<Map<string, ConnectorMeta[]>>;
getCredential(id: string): Promise<KeychainCredentialMeta | null>;
/** Decrypt an env credential the caller OWNS — no grant machinery, never someone else's. */
readOwnSecret(ownerId: string, credentialId: string): Promise<string | null>;
remove(ownerId: string, id: string): Promise<boolean>;
createGrant(input: CreateGrantInput): Promise<KeychainGrant>;
grantConnectorToScope(input: {
host: string;
principalId: string;
accountType?: string;
audienceScopeId: ScopeId;
purpose: string;
}): Promise<KeychainGrant | null>;
getGrant(id: string): Promise<KeychainGrant | null>;
listGrants(filter: GrantListFilter): Promise<KeychainGrant[]>;
revokeGrant(ownerId: string, grantId: string): Promise<boolean>;
grantsForScope(scopeId: ScopeId): Promise<Array<{ grant: KeychainGrant; credential: KeychainCredentialMeta }>>;
createAsk(input: CreateAskInput): Promise<{ ask: KeychainAsk; existing: boolean }>;
getAsk(id: string): Promise<KeychainAsk | null>;
listAsks(filter: AskListFilter): Promise<KeychainAsk[]>;
approveAsk(input: ApproveAskInput): Promise<{ ask: KeychainAsk; grant: KeychainGrant }>;
declineAsk(input: { askId: string; ownerId: string; note?: string }): Promise<KeychainAsk>;
unnotifiedResolvedAsks(now: number): Promise<KeychainAsk[]>;
markAskNotified(id: string, status: KeychainAsk["status"]): Promise<void>;
composioKey(ownerId: string, credentialId: string): Promise<string | null>;
prepareMaterialize(
grantId: string,
scopeId: ScopeId,
usedBy: string,
): Promise<{
materialized: MaterializedCred;
singleUse: boolean;
commit(): Promise<void>;
}>;
materializeOwnById(ownerId: string, credentialId: string, scopeId: ScopeId): Promise<MaterializedCred>;
materializeOwn(ownerId: string): Promise<MaterializedEnvCred[]>;
materializeOwnFiles(ownerId: string): Promise<MaterializedFileCred[]>;
materializeStanding(scopeId: ScopeId): Promise<MaterializedEnvCred[]>;
}
function fingerprintOf(secret: string): string {
return hashId([secret]);
}
export function credentialHandle(credential: Pick<KeychainCredential, "id" | "service">): string {
return `${encodeURIComponent(credential.service)}:${credential.id}`;
}
export interface FileCredentialSource {
credentialId: string;
ownerId: string;
service: string;
grantId?: string;
}
export function credentialFilesFingerprint(files: CredentialFile[]): string {
return fileCredentialFingerprint(
files
.map((file) => ({ ...file, mode: restoredFileMode(file.mode) }))
.sort((a, b) => homeRelativePath(a.path).localeCompare(homeRelativePath(b.path))),
);
}
function fileCredentialFingerprint(files: CredentialFile[]): string {
return fingerprintOf(JSON.stringify(files.map((f) => ({ ...f, path: homeRelativePath(f.path) }))));
}
function keychainFilePath(path: string): string {
if (/[\n\r]/.test(path))
throw new KeychainError(400, `file path may not contain line breaks: ${JSON.stringify(path)}`);
try {
return homeRelativePath(path);
} catch {
throw new KeychainError(400, `file path must be home-relative: ${path}`);
}
}
function credId(ownerId: string, service: string, slot: string): string {
return hashId([ownerId, service, slot]);
}
function defaultEnvKey(service: string): string {
return `${service.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_TOKEN`;
}
const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
function legacyUsernameEnvKey(passwordEnvKey: string): string {
const base = passwordEnvKey.replace(/_(PASSWORD|PASS|TOKEN|SECRET|API_KEY|KEY)$/i, "");
return `${base || passwordEnvKey}_USERNAME`;
}
function consumedGrant(grant: KeychainGrant): boolean {
return grant.status === "used" || (grant.mode === "once" && grant.usedAt !== undefined);
}
function expired(rec: { expiresAt?: number }, now: number): boolean {
return typeof rec.expiresAt === "number" && rec.expiresAt < now;
}
function credExpired(rec: { kind: CredentialKind; expiresAt?: number }, now: number): boolean {
return rec.kind !== "file" && expired(rec, now);
}
function toMeta(rec: Omit<KeychainCredential, "secretEnc"> & { secretEnc?: string }): KeychainCredentialMeta {
const { secretEnc: _, ...meta } = rec;
return {
...meta,
...((rec.kind === "env" || rec.kind === "file") && !isBackendCredential(rec)
? { credentialHandle: credentialHandle(rec) }
: {}),
};
}
function byOwners(ownerIds: string[]): { field: "ownerId"; anyOfFold: string[] } {
return { field: "ownerId", anyOfFold: ownerIds.flatMap((id) => personIds(id)) };
}
function bucketByOwner<C extends { ownerId: string }, T>(
creds: Iterable<C>,
ownerIds: string[],
include: (c: C) => boolean,
item: (c: C) => T,
): Map<string, T[]> {
const byKey = new Map(ownerIds.map((id) => [personKey(id), id]));
const out = new Map<string, T[]>();
for (const c of creds) {
if (!include(c)) continue;
const owner = byKey.get(personKey(c.ownerId));
if (owner === undefined) continue;
const list = out.get(owner) ?? [];
list.push(item(c));
out.set(owner, list);
}
return out;
}
export function createKeychain(deps: {
creds: DurableMap<KeychainCredential>;
grants: DurableMap<KeychainGrant>;
asks: DurableMap<KeychainAsk>;
key: SecretKey;
lock: AdvisoryLock;
refreshConnector?: OAuthRefresh;
oauthSkewMs?: number;
oauthRefreshMarginMs?: number;
now?: () => number;
}): Keychain {
const now = deps.now ?? Date.now;
const lock = deps.lock;
const oauthSkew = deps.oauthSkewMs ?? 60_000;
const oauthRefreshMargin = Math.max(deps.oauthRefreshMarginMs ?? 10 * 60_000, oauthSkew);
async function getOwned(ownerId: string, id: string): Promise<KeychainCredential | null> {
const rec = await deps.creds.get(id);
return rec && samePerson(rec.ownerId, ownerId) ? rec : null;
}
function decryptToEnv(rec: KeychainCredential, extra?: { grantId: string; purpose: string }): MaterializedEnvCred {
const raw = decryptSecret(rec.secretEnc, deps.key);
let env: Array<{ key: string; value: string; secret?: boolean }>;
if (rec.fields) {
const values = JSON.parse(raw) as Record<string, string>;
env = rec.fields.map((f) => ({ key: f.envKey, value: values[f.envKey] ?? "", secret: f.secret }));
} else {
const envKey = rec.envKey ?? defaultEnvKey(rec.service);
env = [{ key: envKey, value: raw }];
const legacyUsername = (rec as { username?: string }).username;
if (legacyUsername) env.push({ key: legacyUsernameEnvKey(envKey), value: legacyUsername, secret: false });
}
return {
credentialId: rec.id,
ownerId: rec.ownerId,
service: rec.service,
env,
...extra,
};
}
function decryptToFiles(rec: KeychainCredential, extra?: { grantId: string; purpose: string }): MaterializedFileCred {
const raw = decryptSecret(rec.secretEnc, deps.key);
const files: CredentialFile[] = rec.targets
? (JSON.parse(raw) as CredentialFile[])
: [{ path: keychainFilePath(rec.target ?? ""), contentBase64: Buffer.from(raw, "utf8").toString("base64") }];
return {
credentialId: rec.id,
ownerId: rec.ownerId,
service: rec.service,
files,
...(rec.origin ? { origin: rec.origin } : {}),
...extra,
};
}
function tryDecrypt<T>(rec: KeychainCredential, fn: (rec: KeychainCredential) => T): T | null {
try {
return fn(rec);
} catch (err) {
console.error(
`[keychain] credential ${rec.id} (${rec.service}, owner ${rec.ownerId}) does not decrypt under the current key — skipped: ${errMessage(err)}`,
);
return null;
}
}
async function activeGrantsFor(scopeId: ScopeId): Promise<KeychainGrant[]> {
const t = now();
return (await deps.grants.all()).filter(
(g) => g.audienceScopeId === scopeId && g.status === "active" && !consumedGrant(g) && !expired(g, t),
);
}
async function freshAsk(rec: KeychainAsk, t: number): Promise<KeychainAsk> {
if (rec.status !== "pending" && rec.status !== "expired") return rec;
const grant = await deps.grants.get(hashId([rec.credentialId, "ask", rec.id]));
if (grant?.askId === rec.id) {
if (!deps.asks.update) throw new KeychainError(503, "ask store does not support atomic resolution");
return (
(await deps.asks.update(rec.id, (current) =>
current.status === "pending" || current.status === "expired"
? { ...current, status: "approved", resolvedAt: grant.createdAt, grantId: grant.id, notifiedAt: undefined }
: current,
)) ?? rec
);
}
if (rec.status !== "pending" || rec.expiresAt >= t) return rec;
if (!deps.asks.update) throw new KeychainError(503, "ask store does not support atomic expiry");
return (
(await deps.asks.update(rec.id, (current) =>
current.status === "pending" && current.expiresAt < t
? { ...current, status: "expired", resolvedAt: t }
: current,
)) ?? rec
);
}
const brokerId = (orgScopeId: string, slug: string) => credId(orgScopeId, slug, "broker");
const orgIdOf = (orgScopeId: string) => orgScopeId.replace(/^org:/, "");
function brokerToPublic(rec: KeychainCredential): PublicServiceCredential {
const b = rec.broker ?? { name: rec.service, enabled: true };
return {
slug: rec.service,
name: b.name,
delivery: b.delivery ?? "broker",
...(b.envKey ? { envKey: b.envKey } : {}),
host: rec.host ?? "",
...(b.injection ? { injection: b.injection } : {}),
...(b.allowedMethods ? { allowedMethods: b.allowedMethods } : {}),
...(b.allowedPathPrefixes ? { allowedPathPrefixes: b.allowedPathPrefixes } : {}),
deployments: b.deployments !== false,
enabled: b.enabled,
hasSecret: !!rec.secretEnc,
...(b.updatedBy ? { updatedBy: b.updatedBy } : {}),
updatedAt: rec.updatedAt,
};
}
async function brokerRecord(orgScopeId: string, slug: string): Promise<KeychainCredential | null> {
return deps.creds.get(brokerId(orgScopeId, slug));
}
function serviceCredentialRecord(
orgScopeId: string,
input: ServiceCredentialInput,
prior: KeychainCredential | null,
): KeychainCredential {
const injectionError = credentialInjectionError(input.injection);
if (injectionError) throw new Error(injectionError);
const trimmedSecret = input.secret?.trim();
const t = Math.max(now(), (prior?.updatedAt ?? 0) + 1);
const delivery = input.delivery ?? "broker";
if (delivery === "env") {
if (!input.envKey || !isValidServiceCredentialEnvKey(input.envKey)) {
throw new Error(
`env-delivery credential ${input.slug} needs an UPPER_SNAKE_CASE envKey outside AGENT_* (got ${JSON.stringify(input.envKey ?? null)})`,
);
}
} else if (input.envKey) {
throw new Error(`broker-delivery credential ${input.slug} must not carry an envKey`);
}
return {
id: brokerId(orgScopeId, input.slug),
ownerId: orgScopeId,
orgId: orgIdOf(orgScopeId),
service: input.slug,
kind: "broker",
host: input.host,
broker: {
name: input.name,
...(delivery === "env" ? { delivery, envKey: input.envKey! } : {}),
...(input.injection ? { injection: input.injection } : {}),
...(input.allowedMethods ? { allowedMethods: input.allowedMethods.map((m) => m.toUpperCase()) } : {}),
...(input.allowedPathPrefixes ? { allowedPathPrefixes: input.allowedPathPrefixes } : {}),
...(input.deployments === false ? { deployments: false } : {}),
enabled: input.enabled !== false,
...(input.updatedBy ? { updatedBy: input.updatedBy } : {}),
},
secretEnc: trimmedSecret ? encryptSecret(trimmedSecret, deps.key) : (prior?.secretEnc ?? ""),
fingerprint: trimmedSecret ? fingerprintOf(trimmedSecret) : (prior?.fingerprint ?? ""),
createdAt: prior?.createdAt ?? t,
updatedAt: t,
};
}
const oauthSlot = (accountType?: string) => `oauth:${accountType && accountType !== "default" ? accountType : ""}`;
const oauthId = (host: string, principalId: string, accountType?: string) =>
credId(principalId, host.toLowerCase(), oauthSlot(accountType));
const inflightRefreshes = new Map<string, Promise<string | null>>();
async function putConnectorToken(
host: string,
principalId: string,
token: OAuthToken,
accountType?: string,
): Promise<KeychainCredential> {
const t = now();
const id = oauthId(host, principalId, accountType);
const prior = await deps.creds.get(id);
const at = token.accountType ?? accountType;
const rec: KeychainCredential = {
id,
ownerId: principalId,
orgId: token.orgId ?? configOrgId(),
service: host.toLowerCase(),
kind: "env",
host: host.toLowerCase(),
managed: "connector",
secretEnc: encryptSecret(token.accessToken, deps.key),
fingerprint: fingerprintOf(token.accessToken),
origin: "connector-oauth",
...(token.expiresAt !== undefined ? { expiresAt: token.expiresAt } : {}),
refresh: {
...(token.refreshToken ? { refreshTokenEnc: encryptSecret(token.refreshToken, deps.key) } : {}),
...(token.idToken ? { idTokenEnc: encryptSecret(token.idToken, deps.key) } : {}),
...(token.accountId ? { accountId: token.accountId } : {}),
...(at ? { accountType: at } : {}),
...(token.clientRef ? { clientRef: token.clientRef } : {}),
...(token.grantedScopes ? { grantedScopes: token.grantedScopes } : {}),
...(token.orgId ? { orgId: token.orgId } : {}),
},
createdAt: prior?.createdAt ?? t,
updatedAt: t,
};
await deps.creds.put(id, rec);
return rec;
}
async function connectorRecord(
host: string,
principalId: string,
accountType?: string,
): Promise<KeychainCredential | null> {
return deps.creds.get(oauthId(host, principalId, accountType));
}
function recToOAuthToken(rec: KeychainCredential): OAuthToken {
return {
accessToken: decryptSecret(rec.secretEnc, deps.key),
...(rec.refresh?.refreshTokenEnc ? { refreshToken: decryptSecret(rec.refresh.refreshTokenEnc, deps.key) } : {}),
...(rec.refresh?.idTokenEnc ? { idToken: decryptSecret(rec.refresh.idTokenEnc, deps.key) } : {}),
...(rec.refresh?.accountId ? { accountId: rec.refresh.accountId } : {}),
...(rec.expiresAt !== undefined ? { expiresAt: rec.expiresAt } : {}),
...(rec.refresh?.grantedScopes ? { grantedScopes: rec.refresh.grantedScopes } : {}),
...(rec.refresh?.clientRef ? { clientRef: rec.refresh.clientRef } : {}),
...(rec.refresh?.accountType ? { accountType: rec.refresh.accountType } : {}),
...(rec.refresh?.orgId ? { orgId: rec.refresh.orgId } : {}),
};
}
function storedRefreshError(e: unknown): string {
const msg = errMessage(e).replace(/\s+/g, " ").trim();
return msg.length > 500 ? `${msg.slice(0, 497)}...` : msg;
}
async function markConnectorRefreshFailure(rec: KeychainCredential, message: string): Promise<void> {
const t = now();
const current = await deps.creds.get(rec.id);
if (!current || current.updatedAt !== rec.updatedAt || current.fingerprint !== rec.fingerprint) return;
await deps.creds.merge(rec.id, {
refresh: { ...current.refresh, refreshFailedAt: t, refreshError: message },
updatedAt: t,
});
}
async function refreshAndStore(
host: string,
principalId: string,
accountType: string | undefined,
rec: KeychainCredential,
): Promise<string | null> {
if (!deps.refreshConnector) return null;
const stored = tryDecrypt(rec, recToOAuthToken);
if (!stored) return null;
try {
const fresh = await deps.refreshConnector(host, stored, {
...(stored.accountType ? { accountType: stored.accountType } : {}),
...(stored.clientRef ? { clientRef: stored.clientRef } : {}),
});
if (!fresh.accessToken) throw new Error("refresh returned an empty access token");
const merged: OAuthToken = {
...(stored.clientRef ? { clientRef: stored.clientRef } : {}),
...(stored.accountType ? { accountType: stored.accountType } : {}),
...(stored.orgId ? { orgId: stored.orgId } : {}),
...(stored.idToken ? { idToken: stored.idToken } : {}),
...(stored.accountId ? { accountId: stored.accountId } : {}),
...fresh,
};
// Compare-and-set: if another flight already rotated this credential,
// keep its result rather than clobbering a newer refresh token.
const current = await deps.creds.get(rec.id);
if (current && (current.updatedAt !== rec.updatedAt || current.fingerprint !== rec.fingerprint)) {
const latest = tryDecrypt(current, recToOAuthToken);
return latest?.accessToken ?? null;
}
await putConnectorToken(host, principalId, merged, accountType);
return merged.accessToken;
} catch (e) {
const message = storedRefreshError(e);
console.error(`[keychain] connector token refresh failed for ${host}: ${message}`);
try {
await markConnectorRefreshFailure(rec, message);
} catch (writeErr) {
console.error(
`[keychain] connector token refresh failure metadata write failed for ${host}: ${errMessage(writeErr)}`,
);
}
return null;
}
}
async function connectorTokenForRecord(rec: KeychainCredential): Promise<string | null> {
const t = now();
const refreshable = rec.refresh?.refreshTokenEnc && deps.refreshConnector && rec.host ? rec.host : null;
if (refreshable && rec.expiresAt !== undefined && t >= rec.expiresAt - oauthRefreshMargin) {
let pending = inflightRefreshes.get(rec.id);
if (!pending) {
pending = refreshAndStore(refreshable, rec.ownerId, rec.refresh?.accountType, rec);
inflightRefreshes.set(rec.id, pending);
void pending.finally(() => inflightRefreshes.delete(rec.id));
}
return pending;
}
if (oauthExpired(rec, t, oauthSkew) && !refreshable) return null;
return tryDecrypt(rec, (r) => decryptSecret(r.secretEnc, deps.key));
}
async function saveCredential(input: SaveCredentialInput): Promise<KeychainCredentialMeta> {
const service = input.service.trim().toLowerCase();
if (!service) throw new KeychainError(400, "service required");
let files: CredentialFile[] | undefined;
if (input.files?.length) {
files = checkedFiles(input.files.map((f) => ({ ...f, path: keychainFilePath(f.path) })));
} else if (input.target && input.secret) {
files = [
{
path: keychainFilePath(input.target),
contentBase64: Buffer.from(input.secret, "utf8").toString("base64"),
},
];
}
const kind: CredentialKind = files ? "file" : "env";
const fields =
!files && input.fields?.length
? input.fields.map((f) => ({ envKey: f.envKey.trim(), value: f.value, secret: f.secret !== false }))
: undefined;
if (fields) {
if (fields.some((f) => !ENV_KEY_RE.test(f.envKey)))
throw new KeychainError(400, "each credential field needs a valid environment-variable envKey");
if (fields.some((f) => !f.value || !f.value.trim()))
throw new KeychainError(400, "each credential field needs a value");
if (new Set(fields.map((f) => f.envKey)).size !== fields.length)
throw new KeychainError(400, "credential field envKeys must be unique");
}
let secret = input.secret;
if (files) secret = JSON.stringify(files);
else if (fields) secret = JSON.stringify(Object.fromEntries(fields.map((f) => [f.envKey, f.value])));
if (!secret || !secret.trim()) throw new KeychainError(400, "empty secret");
const envKey = kind === "env" && !fields ? input.envKey?.trim() || defaultEnvKey(service) : undefined;
if (envKey && !ENV_KEY_RE.test(envKey))
throw new KeychainError(400, "envKey must be a valid environment-variable name");
const fieldsMeta = fields?.map((f) => ({ envKey: f.envKey, secret: f.secret }));
const targets = files?.map((f) => f.path);
const t = now();
let slot = `env:${envKey}`;
if (kind === "file") slot = "file";
else if (fields)
slot = `env:${fields
.map((f) => f.envKey)
.sort()
.join(",")}`;
const ownerId = canonicalPerson(input.ownerId);
const id = credId(ownerId, service, slot);
const buildRec = (prior?: KeychainCredential | null): KeychainCredential => {
return {
id,
ownerId,
orgId: configOrgId(),
service,
kind,
...(envKey ? { envKey } : {}),
...(fieldsMeta ? { fields: fieldsMeta } : {}),
...(targets ? { targets } : {}),
...(input.host ? { host: input.host } : {}),
...(input.accountLabel ? { accountLabel: input.accountLabel } : {}),
secretEnc: encryptSecret(secret, deps.key),
fingerprint: fingerprintOf(secret),
...(input.origin ? { origin: input.origin } : {}),
...(input.expiresAt !== undefined ? { expiresAt: input.expiresAt } : {}),
createdAt: prior?.createdAt ?? t,
updatedAt: t,
};
};
const rec = buildRec(await deps.creds.get(id));
await deps.creds.put(id, rec);
return toMeta(rec);
}
async function materializeConnectorEnv(
cred: KeychainCredential,
extra?: { grantId: string; purpose: string },
): Promise<MaterializedCred> {
const value = cred.host ? await connectorTokenForRecord(cred) : null;
if (!value || !cred.host) {
throw new KeychainError(
410,
"connector token expired and could not be refreshed — its owner must reconnect the app",
);
}
return {
kind: "env",
credentialId: cred.id,
ownerId: cred.ownerId,
service: cred.service,
env: [{ key: envKey(cred.host), value }],
...extra,
};
}
function materializeDecrypted(
cred: KeychainCredential,
extra?: { grantId: string; purpose: string },
): MaterializedCred {
if (isBackendCredential(cred))
throw new KeychainError(403, "Composio keys stay in the backend; use /v1/composio through the agent API");
const materialized = tryDecrypt(cred, (c) =>
c.kind === "file"
? { kind: "file" as const, ...decryptToFiles(c, extra) }
: { kind: "env" as const, ...decryptToEnv(c, extra) },
);
if (!materialized) {
throw new KeychainError(422, "credential does not decrypt under the current key");
}
return materialized;
}
async function claimOnceGrant(grant: KeychainGrant, scopeId: ScopeId, usedBy: string): Promise<void> {
if (grant.mode !== "once") return;
if (!deps.grants.update) throw new KeychainError(503, "grant store does not support atomic one-time use");
const usedAt = now();
const claimed = await deps.grants.update(grant.id, (current) => {
if (current.audienceScopeId !== scopeId) throw new KeychainError(403, "grant is for a different conversation");
if (current.status === "revoked") throw new KeychainError(410, "grant was revoked");
if (consumedGrant(current)) throw new KeychainError(410, "one-time grant already used");
if (expired(current, usedAt)) throw new KeychainError(410, "grant is expired");
return { ...current, status: "used", usedAt, usedBy };
});
if (!claimed) throw new KeychainError(404, "unknown grant");
}
async function authorizedGrant(grantId: string, scopeId: ScopeId) {
const grant = await deps.grants.get(grantId);
if (!grant) throw new KeychainError(404, "unknown grant");
if (grant.audienceScopeId !== scopeId) throw new KeychainError(403, "grant is for a different conversation");
if (grant.status === "revoked") throw new KeychainError(410, "grant was revoked");
if (consumedGrant(grant)) throw new KeychainError(410, "one-time grant already used");
if (expired(grant, now())) throw new KeychainError(410, "grant is expired");
const cred = await deps.creds.get(grant.credentialId);
if (!cred) throw new KeychainError(404, "credential no longer exists");
if (cred.kind === "broker") {
throw new KeychainError(403, "broker credentials are not grantable — they are used via the credential broker");
}
if (cred.managed !== "connector" && credExpired(cred, now())) {
throw new KeychainError(410, "credential is expired");
}
return { grant, cred };
}
async function prepareMaterialize(grantId: string, scopeId: ScopeId, usedBy: string) {
const { grant, cred } = await authorizedGrant(grantId, scopeId);
const extra = { grantId: grant.id, purpose: grant.purpose };
const materialized =
cred.managed === "connector" ? await materializeConnectorEnv(cred, extra) : materializeDecrypted(cred, extra);
const version = cred.managed === "connector" ? await deps.creds.get(cred.id) : cred;
if (
!version ||
(cred.managed === "connector" &&
(materialized.kind !== "env" || version.fingerprint !== fingerprintOf(materialized.env[0]!.value)))
)
throw new KeychainError(409, "credential changed while preparing execution; request it again");
return {
materialized,
singleUse: grant.mode === "once",
commit: async () => {
const current = await authorizedGrant(grantId, scopeId);
if (current.cred.updatedAt !== version.updatedAt || current.cred.secretEnc !== version.secretEnc) {
throw new KeychainError(409, "credential changed while preparing execution; request it again");
}
await claimOnceGrant(current.grant, scopeId, usedBy);
},
};
}
async function mintGrant(input: CreateGrantInput): Promise<KeychainGrant> {
const cred = await deps.creds.get(input.credentialId);
if (!cred) throw new KeychainError(404, "unknown credential");
if (cred.kind === "broker") {
throw new KeychainError(400, "broker credentials are org-owned and used via the credential broker, not grants");
}
if (!samePerson(cred.ownerId, input.ownerId)) {
throw new KeychainError(
403,
"only the credential's owner can grant it — and only on a turn the owner themself sent",
);
}
const purpose = input.purpose.trim();
if (!purpose) throw new KeychainError(400, "purpose required — record the owner's approval verbatim");
const t = now();
if (!cred.managed && credExpired(cred, t)) throw new KeychainError(410, "credential is expired");
const grant: KeychainGrant = {
id: input.askId
? hashId([cred.id, "ask", input.askId])
: hashId([cred.id, input.audienceScopeId, String(t), purpose]),
credentialId: cred.id,
ownerId: cred.ownerId,
orgId: cred.orgId,
audienceScopeId: input.audienceScopeId,
mode: input.mode,
purpose,
status: "active",
createdAt: t,
...(input.expiresAt !== undefined ? { expiresAt: input.expiresAt } : {}),
...(input.askId ? { askId: input.askId } : {}),
};
if (input.askId) return deps.grants.putIfAbsent(grant.id, grant);
await deps.grants.put(grant.id, grant);
return grant;
}
async function deleteCredential(id: string): Promise<void> {
for (const grant of await deps.grants.all()) {
if (grant.credentialId === id && grant.status === "active") {
await deps.grants.merge(grant.id, { status: "revoked", revokedAt: now() });
}
}
await deps.creds.delete(id);
}
return {
save: saveCredential,
async updateFiles(materialized, files) {
if (materialized.grantId) return;
const normalized = checkedFiles(files.map((file) => ({ ...file, path: keychainFilePath(file.path) })));
if (!normalized.length) throw new KeychainError(409, "Refreshed credential files are missing");
const fingerprint = credentialFilesFingerprint;
if (fingerprint(normalized) === fingerprint(materialized.files)) return;
if (!deps.creds.update) throw new Error("credential store does not support atomic file refresh");
const updated = await deps.creds.update(materialized.credentialId, (current) => {
if (current.kind !== "file" || !samePerson(current.ownerId, materialized.ownerId))
throw new KeychainError(409, "Credential changed during execution");
const currentFiles = decryptToFiles(current).files;
if (fingerprint(currentFiles) === fingerprint(normalized)) return current;
if (fingerprint(currentFiles) !== fingerprint(materialized.files))
throw new KeychainError(409, "Credential changed during execution; refreshed files were not saved");
const secret = JSON.stringify(normalized);
return {
...current,
targets: normalized.map((file) => file.path),
secretEnc: encryptSecret(secret, deps.key),
fingerprint: fingerprintOf(secret),
updatedAt: now(),
};
});
if (!updated) throw new KeychainError(410, "Credential was removed during execution");
},
async writebackBaseline(source, fingerprint) {
const current = await deps.creds.get(source.credentialId);
if (!current || current.kind !== "file" || !samePerson(current.ownerId, source.ownerId))
throw new KeychainError(410, "Credential was removed during execution");
const files = decryptToFiles(current).files;
if (credentialFilesFingerprint(files) !== fingerprint)
throw new KeychainError(409, "Credential changed during execution; refreshed files were not saved");
return {
kind: "file",
credentialId: current.id,
ownerId: current.ownerId,
service: current.service,
files,
...(source.grantId ? { grantId: source.grantId } : {}),
};
},
async listAllMetadata() {
return (await deps.creds.select({ omit: ["secretEnc"] })).filter(listed).map(toMeta);
},
async listByOwner(ownerId) {
return (await deps.creds.select({ omit: ["secretEnc"], where: byOwners([ownerId]) }))
.filter((c) => samePerson(c.ownerId, ownerId) && listed(c))
.map(toMeta);
},
async listByOwners(ownerIds) {
return bucketByOwner(
await deps.creds.select({ omit: ["secretEnc"], where: byOwners(ownerIds) }),
ownerIds,
listed,
toMeta,
);
},
async getCredential(id) {
const rec = await deps.creds.get(id);
return rec ? toMeta(rec) : null;
},
async readOwnSecret(ownerId, id) {
const rec = await getOwned(ownerId, id);
if (!rec || rec.kind !== "env") return null;
return tryDecrypt(rec, (r) => decryptSecret(r.secretEnc, deps.key));
},
async remove(ownerId, id) {
const rec = await getOwned(ownerId, id);
if (!rec) return false;
if (rec.managed || rec.kind === "broker") return false;
await deleteCredential(id);
return true;
},
createGrant: mintGrant,
async grantConnectorToScope({ host, principalId, accountType, audienceScopeId, purpose }) {
const id = oauthId(host, principalId, accountType);
const cred = await deps.creds.get(id);
if (!cred) return null;
for (const g of await deps.grants.all()) {
if (
g.credentialId === id &&
g.audienceScopeId === audienceScopeId &&
g.mode === "standing" &&
g.status === "active"
) {
return g;
}
}
return mintGrant({ credentialId: id, ownerId: principalId, audienceScopeId, mode: "standing", purpose });
},
async getGrant(id) {
return (await deps.grants.get(id)) ?? null;
},
async listGrants(filter) {
const grants =
filter.ownerId === undefined
? await deps.grants.all()
: await deps.grants.select({ where: byOwners([filter.ownerId]) });
return grants.filter(
(g) =>
(filter.ownerId === undefined || samePerson(g.ownerId, filter.ownerId)) &&
(filter.audienceScopeId === undefined || g.audienceScopeId === filter.audienceScopeId),
);
},
async revokeGrant(ownerId, grantId) {
const g = await deps.grants.get(grantId);
if (!g || !samePerson(g.ownerId, ownerId)) return false;
if (g.status === "active") await deps.grants.merge(grantId, { status: "revoked", revokedAt: now() });
return true;
},
async grantsForScope(scopeId) {
const out: Array<{ grant: KeychainGrant; credential: KeychainCredentialMeta }> = [];
for (const grant of await activeGrantsFor(scopeId)) {
const cred = await deps.creds.get(grant.credentialId);
if (cred && (cred.managed === "connector" || !credExpired(cred, now())))
out.push({ grant, credential: toMeta(cred) });
}
return out;
},
async createAsk(input) {
const purpose = input.purpose.trim();
if (!purpose)
throw new KeychainError(400, "purpose required — describe the specific task requiring this credential");
const cred = await deps.creds.get(input.credentialId);
if (!cred || cred.kind === "broker") throw new KeychainError(404, "unknown credential");
const t = now();
if (!cred.managed && credExpired(cred, t))
throw new KeychainError(410, "credential is expired — its owner must re-auth before it can be asked for");
const scope = parseScopeId(input.requesterScopeId);
if (
scope.kind === "personal" &&
(!samePerson(scope.ref, input.requesterId) || !samePerson(cred.ownerId, input.requesterId))
) {
throw new KeychainError(403, "personal requests require the credential owner's own conversation");
}
const origin = cronIdOf(input.requesterThreadRef) ?? input.requesterThreadRef;
for (const rec of (await deps.asks.all()).reverse().sort((a, b) => b.createdAt - a.createdAt)) {
const a = await freshAsk(rec, t);
const sameOrigin = (cronIdOf(a.requesterThreadRef) ?? a.requesterThreadRef) === origin;
if (a.credentialId !== cred.id || a.requesterScopeId !== input.requesterScopeId || !sameOrigin) continue;
if (a.status === "pending") return { ask: a, existing: true };
if (a.status === "approved") break;
if (input.triggered && (a.status === "declined" || a.status === "expired")) {
throw new KeychainError(
409,
"the owner declined or did not answer this task's request — wait for a live owner turn instead of asking again",
);
}
}
const ask: KeychainAsk = {
id: randomBytes(6).toString("hex"),
credentialId: cred.id,
ownerId: cred.ownerId,
requesterId: input.requesterId,
orgId: configOrgId(),
requesterScopeId: input.requesterScopeId,
...(input.requesterDestination ? { requesterDestination: input.requesterDestination } : {}),
...(input.requesterThreadRef ? { requesterThreadRef: input.requesterThreadRef } : {}),
...(input.requesterSeq !== undefined ? { requesterSeq: input.requesterSeq } : {}),
...(input.requesterMessageTs ? { requesterMessageTs: input.requesterMessageTs } : {}),
purpose,
...(input.requestedMode ? { requestedMode: input.requestedMode } : {}),
status: "pending",
createdAt: t,
expiresAt: input.expiresAt ?? t + ASK_TTL_MS,
};
await deps.asks.put(ask.id, ask);
return { ask, existing: false };
},
async getAsk(id) {
const rec = await deps.asks.get(id);
return rec ? freshAsk(rec, now()) : null;
},
async listAsks(filter) {
const t = now();
const out: KeychainAsk[] = [];
for (const rec of await deps.asks.all()) {
const a = await freshAsk(rec, t);
if (filter.requesterId !== undefined && !samePerson(a.requesterId, filter.requesterId)) continue;
if (filter.ownerId !== undefined && !samePerson(a.ownerId, filter.ownerId)) continue;
if (filter.requesterScopeId !== undefined && a.requesterScopeId !== filter.requesterScopeId) continue;
out.push(a);
}
return out.sort((x, y) => x.createdAt - y.createdAt);
},
async approveAsk(input) {
return lock.withLock(`keychain-ask:${input.askId}`, async () => {
const rec = await deps.asks.get(input.askId);
if (!rec) throw new KeychainError(404, "unknown ask");
const t = now();
const ask = await freshAsk(rec, t);
if (ask.status !== "pending") throw new KeychainError(410, `ask already ${ask.status}`);
const grant = await mintGrant({
credentialId: ask.credentialId,
ownerId: input.ownerId,
audienceScopeId: ask.requesterScopeId,
mode: input.mode,
purpose: input.purpose,
...(input.expiresAt !== undefined ? { expiresAt: input.expiresAt } : {}),
askId: ask.id,
});
const patch = { status: "approved" as const, resolvedAt: t, grantId: grant.id, notifiedAt: undefined };
await deps.asks.merge(ask.id, patch);
return { ask: { ...ask, ...patch }, grant };
});
},
async declineAsk(input) {
return lock.withLock(`keychain-ask:${input.askId}`, async () => {
const rec = await deps.asks.get(input.askId);
if (!rec) throw new KeychainError(404, "unknown ask");
if (!samePerson(rec.ownerId, input.ownerId))
throw new KeychainError(403, "only the credential's owner can decline an ask");
const t = now();
const ask = await freshAsk(rec, t);
if (ask.status !== "pending") throw new KeychainError(410, `ask already ${ask.status}`);
const note = input.note?.trim();
const patch = { status: "declined" as const, resolvedAt: t, ...(note ? { note } : {}) };
await deps.asks.merge(ask.id, patch);
return { ...ask, ...patch };
});
},
async unnotifiedResolvedAsks(nowAt) {
const out: KeychainAsk[] = [];
const taskDecisions = new Set<string>();
for (const rec of (await deps.asks.all()).reverse().sort((a, b) => b.createdAt - a.createdAt)) {
const a = await freshAsk(rec, nowAt);
const origin = cronIdOf(a.requesterThreadRef) ?? a.requesterThreadRef;
const task = JSON.stringify([a.credentialId, a.requesterScopeId, origin]);
const retainDecision =
origin !== undefined && !taskDecisions.has(task) && !!(await deps.creds.get(a.credentialId));
taskDecisions.add(task);
if (a.status === "pending") continue;
if (a.notifiedAt === undefined) out.push(a);
else if (!retainDecision && a.notifiedAt < nowAt - ASK_PRUNE_AFTER_MS) await deps.asks.delete(a.id);
}
return out;
},
async markAskNotified(id, status) {
if (!deps.asks.update) throw new KeychainError(503, "ask store does not support atomic notification");
await deps.asks.update(id, (current) =>
current.status === status ? { ...current, notifiedAt: now() } : current,
);
},
async setServiceCredential(orgScopeId, input) {
const prior = await brokerRecord(orgScopeId, input.slug);
const rec = serviceCredentialRecord(orgScopeId, input, prior);
await deps.creds.put(rec.id, rec);
},
async setServiceCredentialIfAbsent(orgScopeId, input) {
if (!deps.creds.insertIfAbsent) throw new Error("credential store does not support atomic inserts");
const rec = serviceCredentialRecord(orgScopeId, input, null);
return (await deps.creds.insertIfAbsent(rec.id, rec)) ? rec.updatedAt : null;
},
async setServiceCredentialIfCurrent(orgScopeId, input, expectedUpdatedAt) {
if (!deps.creds.update) throw new Error("credential store does not support atomic updates");
let updatedAt: number | null = null;
await deps.creds.update(brokerId(orgScopeId, input.slug), (prior) => {
if (prior.kind !== "broker" || prior.ownerId !== orgScopeId || prior.updatedAt !== expectedUpdatedAt)
return prior;
const next = serviceCredentialRecord(orgScopeId, input, prior);
updatedAt = next.updatedAt;
return next;
});
return updatedAt;
},
async listServiceCredentials(orgScopeId) {
return (await deps.creds.select({ where: byOwners([orgScopeId]) }))
.filter((c) => c.kind === "broker" && c.ownerId === orgScopeId)
.map(brokerToPublic);
},
async deleteServiceCredential(orgScopeId, slug) {
await deps.creds.delete(brokerId(orgScopeId, slug));
},
async deleteServiceCredentialIfCurrent(orgScopeId, slug, expectedUpdatedAt) {
if (!deps.creds.deleteIf) throw new Error("credential store does not support atomic deletes");
return deps.creds.deleteIf(
brokerId(orgScopeId, slug),
(prior) => prior.kind === "broker" && prior.ownerId === orgScopeId && prior.updatedAt === expectedUpdatedAt,
);
},
async getServiceCredentialSecret(orgScopeId, slug) {
const rec = await brokerRecord(orgScopeId, slug);
if (!rec?.secretEnc) return null;
const b = rec.broker ?? { name: rec.service, enabled: true };
return {
slug: rec.service,
name: b.name,
secret: decryptSecret(rec.secretEnc, deps.key),
delivery: b.delivery ?? "broker",
...(b.envKey ? { envKey: b.envKey } : {}),
host: rec.host ?? "",
...(b.injection ? { injection: b.injection } : {}),
...(b.allowedMethods ? { allowedMethods: b.allowedMethods } : {}),
...(b.allowedPathPrefixes ? { allowedPathPrefixes: b.allowedPathPrefixes } : {}),
deployments: b.deployments !== false,
enabled: b.enabled,
};
},
async setConnectorToken(host, principalId, token, accountType) {
await putConnectorToken(host, principalId, token, accountType);
},
async deleteConnectorToken(host, principalId, accountType) {
await deleteCredential(oauthId(host, principalId, accountType));
},
async connectorTokenStatus(host, principalId, accountType) {
const rec = await connectorRecord(host, principalId, accountType);
if (!rec) return { connected: false };
const hasRefresh = !!rec.refresh?.refreshTokenEnc;
const refreshFailedAt = rec.refresh?.refreshFailedAt;
const refreshFailed = typeof refreshFailedAt === "number";
const tokenExpired = oauthExpired(rec, now(), oauthSkew);
return {
connected: true,
...(rec.expiresAt !== undefined ? { expiresAt: rec.expiresAt } : {}),
...(hasRefresh ? { hasRefreshToken: true } : {}),
...(tokenExpired && (!hasRefresh || refreshFailed) ? { needsReconnect: true } : {}),
...(refreshFailed ? { refreshFailedAt } : {}),
...(refreshFailed && rec.refresh?.refreshError ? { refreshError: rec.refresh.refreshError } : {}),
...(rec.refresh?.accountType ? { accountType: rec.refresh.accountType } : {}),
...(rec.refresh?.grantedScopes ? { grantedScopes: rec.refresh.grantedScopes } : {}),
};
},
async connectorAccessToken(host, principalId, accountType) {
const rec = await connectorRecord(host, principalId, accountType);
if (!rec) return null;
return connectorTokenForRecord(rec);
},
async connectorDerivedAuth(host, principalId, accountType) {
const rec = await connectorRecord(host, principalId, accountType);
if (!rec) return null;
const accessToken = await connectorTokenForRecord(rec);
if (accessToken === null) return null;
// Re-read: a refresh inside connectorTokenForRecord may have rotated the record.
const fresh = (await connectorRecord(host, principalId, accountType)) ?? rec;
const token = tryDecrypt(fresh, recToOAuthToken);
if (!token) return null;
return {
accessToken: token.accessToken,
...(token.idToken ? { idToken: token.idToken } : {}),
...(token.accountId ? { accountId: token.accountId } : {}),
...(token.expiresAt !== undefined ? { expiresAt: token.expiresAt } : {}),
};
},
async listConnectorsByOwners(ownerIds) {
const t = now();
return bucketByOwner(
await deps.creds.select({ omit: ["secretEnc"], where: byOwners(ownerIds) }),
ownerIds,
(c) => c.managed === "connector",
(c) => connectorMeta(c, t, oauthSkew),
);
},
async composioKey(ownerId, credentialId) {
const cred = await getOwned(ownerId, credentialId);
if (!cred || cred.kind !== "env" || !isBackendCredential(cred) || credExpired(cred, now())) return null;
return tryDecrypt(cred, decryptToEnv)?.env.find((e) => e.key === COMPOSIO_ENV_KEY)?.value ?? null;
},
prepareMaterialize,
async materializeOwnById(ownerId, credentialId, scopeId) {
if (scopeId !== toScopeId("personal", ownerId)) {
throw new KeychainError(
403,
"a credential id loads only in its owner's own personal conversation — anywhere else needs a grant from the owner",
);
}
const cred = await deps.creds.get(credentialId);
if (!cred || !samePerson(cred.ownerId, ownerId)) throw new KeychainError(404, "unknown credential");
if (cred.kind === "broker") {
throw new KeychainError(403, "broker credentials are used via the credential broker, never materialized");
}
if (cred.managed === "connector") return materializeConnectorEnv(cred);
if (credExpired(cred, now())) throw new KeychainError(410, "credential is expired");
return materializeDecrypted(cred);
},
async materializeOwn(ownerId) {
const t = now();
return (await deps.creds.select({ where: byOwners([ownerId]) }))
.filter(
(c) =>
samePerson(c.ownerId, ownerId) &&
c.kind === "env" &&
!c.managed &&
!isBackendCredential(c) &&
!expired(c, t),
)
.map((c) => tryDecrypt(c, decryptToEnv))
.filter((c): c is MaterializedEnvCred => c !== null);
},
async materializeOwnFiles(ownerId) {
return (await deps.creds.select({ where: byOwners([ownerId]) }))
.filter((c) => samePerson(c.ownerId, ownerId) && c.kind === "file" && listed(c))
.map((c) => tryDecrypt(c, decryptToFiles))
.filter((c): c is MaterializedFileCred => c !== null);
},
async materializeStanding(scopeId) {
const out: MaterializedEnvCred[] = [];
for (const grant of await activeGrantsFor(scopeId)) {
if (grant.mode !== "standing") continue;
const cred = await deps.creds.get(grant.credentialId);
if (!cred || cred.kind !== "env" || isBackendCredential(cred)) continue;
if (cred.managed === "connector") {
const value = cred.host ? await connectorTokenForRecord(cred) : null;
if (value && cred.host) {
out.push({
credentialId: cred.id,
ownerId: cred.ownerId,
service: cred.service,
env: [{ key: envKey(cred.host), value }],
grantId: grant.id,
purpose: grant.purpose,
});
}
continue;
}
if (cred.managed || credExpired(cred, now())) continue;
const mat = tryDecrypt(cred, (c) => decryptToEnv(c, { grantId: grant.id, purpose: grant.purpose }));
if (mat) out.push(mat);
}
return out;
},
};
}
export function fileCredentialEnvironment(files: CredentialFile[], home: string): Record<string, string> {
const env: Record<string, string> = { HOME: home };
const pointers: Array<[RegExp, string, boolean?]> = [
[/^\.aws\/credentials$/, "AWS_SHARED_CREDENTIALS_FILE"],
[/^\.aws\/config$/, "AWS_CONFIG_FILE"],
[/^\.kube\/config$/, "KUBECONFIG"],
[/^\.config\/gh\/hosts\.yml$/, "GH_CONFIG_DIR", true],
[/^(?:\.config\/(?:glab-cli|glab)|Library\/Application Support\/glab-cli)\/config\.yml$/, "GLAB_CONFIG_DIR", true],
[/^\.docker\/config\.json$/, "DOCKER_CONFIG", true],
[/^\.npmrc$/, "NPM_CONFIG_USERCONFIG"],
[/^\.netrc$/, "NETRC"],
];
for (const file of files) {
const rel = homeRelativePath(file.path);
for (const [pattern, key, directory] of pointers) {
if (pattern.test(rel) && !(key in env)) env[key] = `${home}/${directory ? rel.replace(/\/[^/]*$/, "") : rel}`;
}
if (/^\.ssh\/[^/]*(id_|key)[^/]*$/.test(rel) && !env.GIT_SSH_COMMAND)
env.GIT_SSH_COMMAND = `ssh -i ${shq(`${home}/${rel}`)} -o IdentitiesOnly=yes`;
}
return env;
}
function hoursLeft(expiresAt: number, now: number): number {
return Math.max(1, Math.round((expiresAt - now) / 3_600_000));
}
export function renderAskNotice(
input: {
ask: KeychainAsk;
credential: KeychainCredentialMeta;
requesterName?: string;
channelName?: string;
scopeName?: string;
taskTitle?: string;
},
now: number = Date.now(),
): string {
const { ask, credential } = input;
const who = input.requesterName ? `${input.requesterName} (${ask.requesterId})` : ask.requesterId;
// Never surface a raw Slack scope id to a person — describe the place instead.
let where: string;
if (input.channelName) where = `**#${input.channelName.replace(/^#/, "")}**`;
else if (input.scopeName) where = `**${input.scopeName}**`;
else if (ask.requesterScopeId.startsWith("group:")) where = "a group conversation";
else if (ask.requesterScopeId.startsWith("channel:")) where = "a Slack channel";
else if (ask.requesterScopeId.startsWith("personal:")) where = "their own conversation";
else where = "a shared conversation";
const task = input.taskTitle ? `Scheduled task "${input.taskTitle}": ` : "";
const account = credential.accountLabel ? ` (${credential.accountLabel})` : "";
const self = ask.requesterScopeId.startsWith("personal:") && samePerson(ask.ownerId, ask.requesterId);
return (
`${task}${self ? "A task in your personal conversation" : `${who} in ${where}`} wants to use your **${credential.service}** credential${account}. ` +
`Approve or deny on the card (expires in ${hoursLeft(ask.expiresAt, now)}h).`
);
}
export interface KeychainManifestInput {
scopeId: ScopeId;
conversationKind: "dm" | "channel" | "group";
openSpeakerKeychain?: boolean;
actorId: string;
members: Array<{ id: string; displayName?: string }>;
entriesByOwner: Map<string, KeychainCredentialMeta[]>;
connectorsByOwner?: Map<string, ConnectorMeta[]>;
scopeGrants: Array<{ grant: KeychainGrant; credential: KeychainCredentialMeta }>;
execution?: Array<{
handle: string;
ownerId: string;
credentialId?: string;
description: string;
scope: "scoped" | "owner";
}>;
detectedByOwner?: Map<string, string[]>;
scopeAsks?: KeychainAsk[];
}
function expiryNote(c: KeychainCredentialMeta, now: number, own: boolean): string {
if (c.kind === "file" || typeof c.expiresAt !== "number") return "";
if (c.expiresAt < now) {
return own
? ", EXPIRED — they must re-auth before it can be used"
: ", EXPIRED — ask the owner to re-auth before requesting a grant";
}
return `, expires at ${new Date(c.expiresAt).toISOString()}`;
}
function credentialDescription(c: KeychainCredentialMeta, now: number, own: boolean): string {
if (c.managed === "connector") return connectorDescription(connectorMeta(c, now));
if (isBackendCredential(c))
return "Composio backend access — use the composio skill; cannot be loaded into a computer";
const slot =
c.kind === "env"
? (c.fields?.map((f) => f.envKey) ?? [c.envKey])
.filter(Boolean)
.sort()
.map((key) => `\`${key}\``)
.join(" + ")
: `files ${(c.targets ?? [c.target]).filter(Boolean).sort().join(", ")}`;
return `${c.service} (${slot}${c.accountLabel ? `, account ${c.accountLabel}` : ""}${expiryNote(c, now, own)})`;
}
const oauthExpired = (rec: KeychainCredentialMeta, t: number, oauthSkew: number) =>
rec.expiresAt !== undefined && t >= rec.expiresAt - oauthSkew;
function connectorMeta(rec: KeychainCredentialMeta, t: number, oauthSkew = 60_000): ConnectorMeta {
const hasRefresh = !!rec.refresh?.refreshTokenEnc;
const refreshFailed = typeof rec.refresh?.refreshFailedAt === "number";
const tokenExpired = oauthExpired(rec, t, oauthSkew);
return {
credentialId: rec.id,
ownerId: rec.ownerId,
host: rec.host ?? rec.service,
...(rec.refresh?.accountType ? { accountType: rec.refresh.accountType } : {}),
...(rec.expiresAt !== undefined ? { expiresAt: rec.expiresAt } : {}),
connected: true,
...(tokenExpired && (!hasRefresh || refreshFailed) ? { needsReconnect: true } : {}),
};
}
function connectorDescription(cm: ConnectorMeta): string {
return `connected app ${cm.host}, account ${cm.accountType ?? "default"}${
cm.needsReconnect ? ", NEEDS RECONNECT — owner must reconnect the app before use" : ""
}${typeof cm.expiresAt === "number" ? `, token expires at ${new Date(cm.expiresAt).toISOString()}` : ""}; ${connectorTokenNote(cm.host)}`;
}
export const MAX_CREDENTIAL_FILES = 500;
export const MAX_CREDENTIAL_BYTES = 8 * 1024 * 1024;
function checkedFiles(files: CredentialFile[]): CredentialFile[] {
const bytes = files.reduce((sum, file) => sum + Buffer.byteLength(file.contentBase64, "base64"), 0);
if (files.length > MAX_CREDENTIAL_FILES || bytes > MAX_CREDENTIAL_BYTES)
throw new KeychainError(
413,
`A saved login is limited to ${MAX_CREDENTIAL_FILES} files and ${MAX_CREDENTIAL_BYTES} bytes`,
);
return files;
}
function listed(c: Pick<KeychainCredential, "managed" | "kind">): boolean {
return !c.managed && c.kind !== "broker";
}
export function renderKeychainManifest(input: KeychainManifestInput, now: number = Date.now()): string {
const groups = new Map<string, Map<string, { text: string; note: string; purpose?: string }>>();
const put = (ownerId: string, id: string, text: string, note = "", purpose?: string): void => {
const owner = personKey(ownerId);
let rows = groups.get(owner);
if (!rows) groups.set(owner, (rows = new Map()));
rows.set(id, { text, note, ...(purpose ? { purpose } : {}) });
};
const ownPersonal = input.scopeId === toScopeId("personal", input.actorId);
const openSpeaker = input.openSpeakerKeychain === true && input.conversationKind !== "dm";
const isOwn = (ownerId: string): boolean => (ownPersonal || openSpeaker) && samePerson(ownerId, input.actorId);
const grants = new Map(input.scopeGrants.map(({ grant, credential }) => [credential.id, grant]));
const execution = input.execution ?? [];
const scopeCounts = new Map<string, number>();
for (const entry of execution) scopeCounts.set(entry.scope, (scopeCounts.get(entry.scope) ?? 0) + 1);
const common = [...scopeCounts].sort(([a, x], [b, y]) => y - x || a.localeCompare(b))[0]?.[0];
const handle = (entry: (typeof execution)[number]): string =>
`\`${entry.handle}\`${entry.scope === common ? "" : ` (execute scope \`${entry.scope}\`)`}`;
const access = (ownerId: string, id: string): [string, string?] => {
const grant = grants.get(id);
if (grant)
return [
`${grant.mode === "standing" ? "STANDING" : "one-time"} grant \`${grant.id}\`${
grant.expiresAt === undefined ? "" : `, expires at ${new Date(grant.expiresAt).toISOString()}`
}`,
grant.purpose,
];
if (!isOwn(ownerId)) return ["no grant for this conversation"];
return [
openSpeaker
? "own; Open live turn only, isolated owner execution"
: "own; no grant needed (including background turns)",
];
};
const handles = (credentialId: string): string =>
execution
.filter((entry) => entry.credentialId === credentialId)
.map(handle)
.sort()
.join(", ") || `credential id \`${credentialId}\``;
const entries = new Map(input.scopeGrants.map(({ credential }) => [credential.id, credential]));
for (const member of input.members)
for (const credential of input.entriesByOwner.get(member.id) ?? []) entries.set(credential.id, credential);
for (const credential of entries.values())
put(
credential.ownerId,
credential.id,
`- ${handles(credential.id)} — ${credentialDescription(credential, now, isOwn(credential.ownerId))}`,
...access(credential.ownerId, credential.id),
);
for (const member of input.members) {
for (const connector of input.connectorsByOwner?.get(member.id) ?? [])
put(
member.id,
connector.credentialId,
`- ${handles(connector.credentialId)} — ${connectorDescription(connector)}`,
...access(member.id, connector.credentialId),
);
const registered = new Set((input.entriesByOwner.get(member.id) ?? []).map((c) => c.service.toLowerCase()));
for (const service of input.detectedByOwner?.get(member.id) ?? [])
if (!registered.has(service.toLowerCase()))
put(member.id, `detected:${service}`, `- ${service} — detected on their computer, NOT registered or grantable`);
}
for (const entry of execution) {
if (entry.credentialId && groups.get(personKey(entry.ownerId))?.has(entry.credentialId)) continue;
put(entry.ownerId, entry.handle, `- ${handle(entry)} — ${entry.description}`);
}
const lines = [
"## Credentials",
`Execution handles are shown in backticks${common ? ` and run in execute scope \`${common}\` unless marked` : ""}; select them in execute.credentials. Credential IDs identify entries for access requests, not execution handles.`,
];
for (const [ownerId, group] of [...groups].sort(([a], [b]) => a.localeCompare(b))) {
const member = input.members.find((member) => personKey(member.id) === ownerId);
const rows = [...group.values()].sort((a, b) => a.text.localeCompare(b.text));
const notes = new Set(rows.map((row) => row.note));
const shared = notes.size === 1 && rows.every((row) => !row.purpose) ? rows[0]!.note : "";
const purposes = new Set<string>();
lines.push(
"",
`### ${member?.displayName ? `${member.displayName} (${ownerId})` : ownerId}${shared ? ` — ${shared}` : ""}`,
...rows.map((row) => {
const said = row.purpose !== undefined && purposes.has(row.purpose);
if (row.purpose) purposes.add(row.purpose);
const purpose = row.purpose ? ` (purpose: ${said ? "as above" : `"${row.purpose}"`})` : "";
return `${row.text}${row.note && !shared ? `; ${row.note}` : ""}${purpose}`;
}),
);
}
if (!groups.size) lines.push("", "No credentials available.");
const asks = (input.scopeAsks ?? []).flatMap((ask) => {
if (ask.status === "pending") return [`- waiting on ${ask.ownerId}'s approval card`];
if (ask.resolvedAt !== undefined && now - ask.resolvedAt < 24 * 3_600_000)
return [`- request to ${ask.ownerId}: ${ask.status}`];
return [];
});
if (asks.length) lines.push("", "Asks sent from this conversation:", ...asks.sort());
lines.push(
"",
"Grants: Use of private credentials outside of a 1:1 DM with that person requires an explicit grant. The exception is the live speaker's isolated owner execution in an Open shared conversation, not continuing room or background access. Otherwise use the `request-access` skill; consider whether one-time, standing or time-bound access fits the request.",
"Secret drop: for a credential nobody has saved, mint a one-time link with the `secret-drop` skill; never collect secrets in chat or send people to the keychain page. Keys enter the submitter's private keychain; in a shared channel they are shared for use in that channel alone.",
"Device code or CLI logins: read the `interactive-login` skill from the first step. It logs in under a temporary home and saves the result. Never log in against this computer's $HOME; only keychain entries are durable and grantable.",
);
return lines.join("\n");
}