Multiplayer agent harness for work.
import { promisify } from "node:util";
import { deflateRaw, inflateRaw } from "node:zlib";
import { orgId as configOrgId } from "../config.ts";
import type { CandidateDestination, Destination, EgressPolicy, Principal, ScopeId } from "../types.ts";
import { mintSignedPayload, verifySignedPayload } from "./signed-token.ts";
export const CAPABILITY_TTL_MS = 60 * 60_000;
export const DEPLOYMENT_CREDENTIAL_TTL_MS = 10 * 365 * 24 * 60 * 60_000;
const DEFAULT_SANDBOX_CAPABILITY_TTL_HOURS = 48;
export function parseSandboxCapabilityTtlMs(value: string | undefined): number {
const raw = value?.trim().toLowerCase();
if (!raw) return DEFAULT_SANDBOX_CAPABILITY_TTL_HOURS * 3_600_000;
if (raw === "none" || raw === "0") return 0;
const hours = Number(raw);
if (!Number.isFinite(hours) || hours <= 0 || !Number.isSafeInteger(hours * 3_600_000))
throw new Error(
`SANDBOX_CAPABILITY_TTL_HOURS=${JSON.stringify(value)} must be a positive number of hours, or 0/none for no expiry.`,
);
return hours * 3_600_000;
}
export const SANDBOX_CAPABILITY_TTL_MS = parseSandboxCapabilityTtlMs(undefined);
export const BROWSER_MODEL_AUD = "browser-model";
export const CONTROL_PLANE_AUD = "control-plane";
export const OAUTH_CONSENT_AUD = "oauth-consent";
export const CREDENTIAL_BROKER_AUD = "credential-broker";
export const EGRESS_PROXY_AUD = "egress-proxy";
export const BLOB_TRANSFER_AUD = "blob-transfer";
export const SECRET_DROP_AUD = "secret-drop";
interface BlobGrant {
dir: "read" | "write";
id?: string;
}
type BlobTransferClaims = CapabilityClaims & { aud: typeof BLOB_TRANSFER_AUD; blob: BlobGrant };
export interface CapabilityClaims {
externalSlack?: true;
actorId: string;
browserModel?: string;
browserAccount?: "company" | "personal" | "openai" | "anthropic";
aud?: string;
scopeId: ScopeId;
scopeVersion?: string;
timezone?: string;
destination?: Destination;
destinations?: CandidateDestination[];
defaultDestinationKey?: string;
credentials?: string[];
ownerConnections?: boolean;
members?: Principal[];
keychainMembers?: Principal[];
privateScope?: boolean;
egress?: EgressPolicy;
blob?: BlobGrant;
drop?: string;
memory?: { write?: ScopeId; orgWrite?: ScopeId; read: ScopeId[] };
liveActor?: boolean;
runId?: string;
sessionId?: string;
runAttempt?: number;
runLeaseToken?: string;
deployment?: string;
botActor?: boolean;
liveAuthor?: boolean;
triggered?: boolean;
grants?: string[];
threadRef?: string;
surface?: string;
exp: number;
}
const compress = promisify(deflateRaw);
const decompress = promisify(inflateRaw);
const MAX_CLAIMS_BYTES = 1024 * 1024;
export async function mintCapabilityToken(
claims: CapabilityClaims,
secret: string,
compressionEnabled = false,
): Promise<string> {
const value = { orgId: configOrgId(), ...claims };
const bytes = Buffer.from(JSON.stringify(value));
if (bytes.length > MAX_CLAIMS_BYTES) throw new Error("Capability claims exceed size limit");
return mintSignedPayload(
compressionEnabled && bytes.length > 4096
? { encoding: "deflate-raw", claims: (await compress(bytes)).toString("base64url") }
: value,
secret,
);
}
async function readCapabilityClaims(token: string, secret: string | string[]): Promise<CapabilityClaims | null> {
const value = await verifySignedPayload(token, secret);
if (!value || typeof value !== "object") return null;
if (!("encoding" in value)) return value as CapabilityClaims;
if (value.encoding !== "deflate-raw" || !("claims" in value) || typeof value.claims !== "string") return null;
try {
const bytes = await decompress(Buffer.from(value.claims, "base64url"), { maxOutputLength: MAX_CLAIMS_BYTES });
return JSON.parse(bytes.toString("utf8")) as CapabilityClaims;
} catch {
return null;
}
}
export function isValidCapabilityTimezone(timezone: unknown): timezone is string {
if (typeof timezone !== "string") return false;
if (timezone.length === 0 || timezone.length > 64 || timezone.trim() !== timezone) return false;
try {
new Intl.DateTimeFormat("en-US", { timeZone: timezone }).format(0);
return true;
} catch {
return false;
}
}
export async function verifyCapabilityToken(
token: string,
secret: string | string[],
now: number = Date.now(),
): Promise<CapabilityClaims | null> {
const claims = await readCapabilityClaims(token, secret);
if (
!claims ||
typeof claims.actorId !== "string" ||
typeof claims.scopeId !== "string" ||
typeof claims.exp !== "number"
) {
return null;
}
if (
claims.browserAccount !== undefined &&
!["company", "personal", "openai", "anthropic"].includes(claims.browserAccount)
)
return null;
if (claims.browserModel !== undefined && (typeof claims.browserModel !== "string" || !claims.browserModel))
return null;
if (claims.timezone !== undefined && !isValidCapabilityTimezone(claims.timezone)) return null;
if (claims.scopeVersion !== undefined && typeof claims.scopeVersion !== "string") return null;
if (claims.destinations !== undefined && !Array.isArray(claims.destinations)) return null;
if (claims.ownerConnections !== undefined && typeof claims.ownerConnections !== "boolean") return null;
if (claims.credentials !== undefined && !Array.isArray(claims.credentials)) return null;
if (
claims.grants !== undefined &&
(!Array.isArray(claims.grants) || !claims.grants.every((g) => typeof g === "string"))
)
return null;
if (claims.keychainMembers !== undefined && !Array.isArray(claims.keychainMembers)) return null;
if (claims.memory !== undefined && !Array.isArray(claims.memory?.read)) return null;
if (claims.liveActor !== undefined && typeof claims.liveActor !== "boolean") return null;
if (claims.botActor !== undefined && typeof claims.botActor !== "boolean") return null;
if (claims.liveAuthor !== undefined && typeof claims.liveAuthor !== "boolean") return null;
if (claims.blob !== undefined && claims.blob?.dir !== "read" && claims.blob?.dir !== "write") return null;
if (claims.drop !== undefined && typeof claims.drop !== "string") return null;
if (claims.runId !== undefined && typeof claims.runId !== "string") return null;
if (claims.sessionId !== undefined && (typeof claims.sessionId !== "string" || !claims.sessionId)) return null;
if (claims.runAttempt !== undefined && (!Number.isSafeInteger(claims.runAttempt) || claims.runAttempt < 1))
return null;
if (claims.runLeaseToken !== undefined && (typeof claims.runLeaseToken !== "string" || !claims.runLeaseToken))
return null;
if (claims.deployment !== undefined && (typeof claims.deployment !== "string" || !claims.deployment)) return null;
if (claims.exp === 0) {
if (![CONTROL_PLANE_AUD, OAUTH_CONSENT_AUD, CREDENTIAL_BROKER_AUD, EGRESS_PROXY_AUD].includes(claims.aud ?? ""))
return null;
} else if (!Number.isSafeInteger(claims.exp) || now >= claims.exp) return null;
return claims;
}
const BLOB_ID = /^[0-9a-f]{32}$/;
export async function verifyBlobTransferCapability(
token: string,
secret: string | string[],
expected: { dir: "read"; id: string } | { dir: "write" },
now: number = Date.now(),
): Promise<BlobTransferClaims | null> {
const claims = await verifyCapabilityToken(token, secret, now);
const grant = claims?.blob;
if (!claims || claims.aud !== BLOB_TRANSFER_AUD || !grant || grant.dir !== expected.dir) return null;
if (grant.id !== undefined && (typeof grant.id !== "string" || !BLOB_ID.test(grant.id))) return null;
if (expected.dir === "read" ? grant.id !== expected.id : grant.id !== undefined) return null;
return claims as BlobTransferClaims;
}