Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
import { encodeDeviceProofMessage } from './device-key-proof'
import type { MobileE2EETransport } from './mobile-e2ee-v2-contract'
import type { PairedE2EEKeyPair, PairedE2EEPrimitives } from './paired-e2ee-primitives'
import { PairedE2EEV2ClientSession } from './paired-e2ee-v2-client-session'
export type PairedE2EEFraming = 'legacy' | 'v2'
// Device-key/ticket credentials signed over the v2 transcript join this union.
export type PairedE2EEAuthCredential = { kind: 'token'; deviceToken: string }
// Sign the v2 auth transcript proof asynchronously so non-extractable WebCrypto keys can participate.
export type PairedE2EEDeviceKeyCredential = {
kind: 'device-key'
deviceId: string
sign: (message: Uint8Array) => Promise<Uint8Array>
}
export type PairedE2EEReadyVerdict =
| 'accepted'
// Not JSON. Legacy clients treat this as an encrypted frame.
| 'invalid'
// JSON, but not a ready this hello accepts (wrong type, bad v2 transcript, re-keyed host).
| 'unexpected'
// A legacy ready from a host this client has seen speak v2.
| 'downgrade_refused'
export type PairedE2EEAuthReply =
| { kind: 'authenticated' }
// errorDeviceId: the device a sealed verdict names (device_revoked); a client acts only on its own.
| { kind: 'rejected'; type: string | null; errorCode: string | null; errorDeviceId?: string }
| { kind: 'invalid' }
export type PairedE2EEChannel = {
sealText: (plaintext: string) => string
// null = not authentic (or not yet keyed).
openText: (frame: string) => string | null
sealBinary: (plaintext: Uint8Array) => Uint8Array<ArrayBuffer>
openBinary: (frame: Uint8Array) => Uint8Array | null
}
// The client side of the per-host "v2 seen" latch. Only legacy framing consults it.
export type PairedE2EELegacyGate = {
mayUseLegacy: () => boolean
}
export class PairedE2EEDowngradeError extends Error {
constructor(stage: 'hello' | 'auth') {
super(`host is latched to E2EE v2; refusing legacy ${stage}`)
}
}
export type PairedE2EEClientHandshake = {
readonly framing: PairedE2EEFraming
// Valid once the ready is accepted (legacy: immediately).
readonly channel: PairedE2EEChannel
// Throws PairedE2EEDowngradeError for a legacy hello to a latched host.
helloText: () => string
acceptReadyText: (frame: string) => PairedE2EEReadyVerdict
// This v2 connection’s transcript hash after ready; null for legacy framing.
transcriptHashB64: () => string | null
sealAuth: (
credential: PairedE2EEAuthCredential | PairedE2EEDeviceKeyCredential,
options?: { clientCapabilities?: readonly string[] }
) => Promise<string>
classifyAuthReply: (plaintext: string) => PairedE2EEAuthReply
}
export type PairedE2EEClientHandshakeArgs = {
primitives: PairedE2EEPrimitives
hostPublicKeyB64: string
framing: PairedE2EEFraming
transport?: MobileE2EETransport
relayHostId?: string
legacyGate?: PairedE2EELegacyGate
// Runtime clients pass their structure-limited parser and size-limited serializer.
parseJson?: (text: string) => unknown
serializeJson?: (value: unknown) => string
clientKeyPair?: PairedE2EEKeyPair
clientNonce?: Uint8Array
}
export function createPairedE2EEClientHandshake(
args: PairedE2EEClientHandshakeArgs
): PairedE2EEClientHandshake {
return args.framing === 'v2' ? createV2Handshake(args) : createLegacyHandshake(args)
}
function createLegacyHandshake(args: PairedE2EEClientHandshakeArgs): PairedE2EEClientHandshake {
const { primitives } = args
const parseJson = args.parseJson ?? JSON.parse
const serializeJson = args.serializeJson ?? JSON.stringify
const mayUseLegacy = (): boolean => args.legacyGate?.mayUseLegacy() ?? true
const keyPair = args.clientKeyPair ?? primitives.generateKeyPair()
const channel = createPairedE2EELegacyChannel(
primitives,
primitives.deriveSharedKey(
keyPair.secretKey,
primitives.publicKeyFromBase64(args.hostPublicKeyB64)
)
)
return {
framing: 'legacy',
channel,
helloText: () => {
if (!mayUseLegacy()) {
throw new PairedE2EEDowngradeError('hello')
}
return JSON.stringify({
type: 'e2ee_hello',
publicKeyB64: primitives.publicKeyToBase64(keyPair.publicKey)
})
},
acceptReadyText: (frame) => {
const ready = parseJsonOrUndefined(frame, parseJson)
if (ready === undefined) {
return 'invalid'
}
if (readStringField(ready, 'type') !== 'e2ee_ready') {
return 'unexpected'
}
// Another socket may have latched v2 while this one dialed; recheck downgrade policy.
return mayUseLegacy() ? 'accepted' : 'downgrade_refused'
},
transcriptHashB64: () => null,
sealAuth: async (credential, options) => {
if (credential.kind !== 'token') {
throw new Error('device-key credentials need E2EE v2')
}
if (!mayUseLegacy()) {
throw new PairedE2EEDowngradeError('auth')
}
return channel.sealText(
serializeJson({
type: 'e2ee_auth',
deviceToken: credential.deviceToken,
...(options?.clientCapabilities ? { clientCapabilities: options.clientCapabilities } : {})
})
)
},
classifyAuthReply: (plaintext) => {
const reply = parseJsonOrUndefined(plaintext, parseJson)
if (reply === undefined) {
return { kind: 'invalid' }
}
const type = readStringField(reply, 'type')
return type === 'e2ee_authenticated' ? { kind: 'authenticated' } : rejectedReply(reply)
}
}
}
export function createPairedE2EELegacyChannel(
primitives: PairedE2EEPrimitives,
sharedKey: Uint8Array
): PairedE2EEChannel {
return {
sealText: (plaintext) => primitives.sealLegacyText(plaintext, sharedKey),
openText: (frame) => primitives.openLegacyText(frame, sharedKey),
sealBinary: (plaintext) => primitives.sealLegacyBinary(plaintext, sharedKey),
openBinary: (frame) => primitives.openLegacyBinary(frame, sharedKey)
}
}
function createV2Handshake(args: PairedE2EEClientHandshakeArgs): PairedE2EEClientHandshake {
const parseJson = args.parseJson ?? JSON.parse
const serializeJson = args.serializeJson ?? JSON.stringify
if (!args.transport) {
throw new Error('E2EE v2 handshake requires a transport context')
}
const session = PairedE2EEV2ClientSession.create({
primitives: args.primitives,
desktopPublicKeyB64: args.hostPublicKeyB64,
transport: args.transport,
relayHostId: args.relayHostId,
clientKeyPair: args.clientKeyPair,
clientNonce: args.clientNonce
})
return {
framing: 'v2',
channel: session,
helloText: () => JSON.stringify(session.hello),
acceptReadyText: (frame) => {
const ready = parseJsonOrUndefined(frame, parseJson)
if (ready === undefined) {
return 'invalid'
}
return session.acceptReady(ready) ? 'accepted' : 'unexpected'
},
transcriptHashB64: () => (session.isReady ? session.transcriptHashB64 : null),
sealAuth: async (credential, options) => {
// Why read first: throws before the ready, so nothing is signed without a transcript.
const transcriptHashB64 = session.transcriptHashB64
if (credential.kind === 'token') {
// Why no capabilities: v2 token auth is an exact key set on every host.
return session.sealText(
serializeJson(pairedE2EEV2TokenAuth(transcriptHashB64, credential.deviceToken))
)
}
const signature = await credential.sign(
encodeDeviceProofMessage('auth', args.primitives.decodeBase64(transcriptHashB64))
)
return session.sealText(
serializeJson({
type: 'e2ee_auth',
v: 2,
transcriptHashB64,
deviceId: credential.deviceId,
deviceProofB64: args.primitives.encodeBase64(signature),
...(options?.clientCapabilities ? { clientCapabilities: options.clientCapabilities } : {})
})
)
},
classifyAuthReply: (plaintext) => {
const reply = parseJsonOrUndefined(plaintext, parseJson)
return reply === undefined
? { kind: 'invalid' }
: classifyPairedE2EEV2AuthReply(reply, session.transcriptHashB64)
}
}
}
export function pairedE2EEV2TokenAuth(
transcriptHashB64: string,
deviceToken: string
): { type: 'e2ee_auth'; v: 2; transcriptHashB64: string; deviceToken: string } {
return { type: 'e2ee_auth', v: 2, transcriptHashB64, deviceToken }
}
export function classifyPairedE2EEV2AuthReply(
reply: unknown,
transcriptHashB64: string
): PairedE2EEAuthReply {
// Why exact: the authenticated reply must echo this session's transcript.
const authenticated =
isRecord(reply) &&
Object.keys(reply).sort().join(',') === 'transcriptHashB64,type,v' &&
reply.type === 'e2ee_authenticated' &&
reply.v === 2 &&
reply.transcriptHashB64 === transcriptHashB64
return authenticated ? { kind: 'authenticated' } : rejectedReply(reply)
}
function parseJsonOrUndefined(text: string, parseJson: (text: string) => unknown): unknown {
try {
return parseJson(text)
} catch {
return undefined
}
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null
}
function readStringField(value: unknown, field: string): string | null {
if (!isRecord(value)) {
return null
}
const fieldValue = value[field]
return typeof fieldValue === 'string' ? fieldValue : null
}
function rejectedReply(reply: unknown): PairedE2EEAuthReply {
const errorDeviceId = isRecord(reply) ? readStringField(reply.error, 'deviceId') : null
return {
kind: 'rejected',
type: readStringField(reply, 'type'),
errorCode: readErrorCode(reply),
...(errorDeviceId ? { errorDeviceId } : {})
}
}
function readErrorCode(value: unknown): string | null {
return isRecord(value) ? readStringField(value.error, 'code') : null
}