packages/sdk/src/index.ts · aryaamin/openclasp

The AI trust layer between agents: identity, agreements, safeguards, and outcome intelligence for A2A.
Viewing files at commit 89b58109a0e6Commit details View latest
packages/sdk/src/index.ts 639 lines · 22.4 KB · typescript
import {
  DEFAULT_EXTENSION_URI,
  canonicalHash,
  signObject,
  verifyRecordAttestation,
  type InteractionEvent,
  type KeyPair,
  type TrustEnvelope,
  type FederatedInteraction,
  type AgentResolution,
  type InteractionContract,
  LiveSessionActivationSchema,
  LiveSessionEventSchema,
  LiveSessionOfferSchema,
  type LiveSessionActivation,
  type LiveSessionEvent,
  type LiveSessionOffer,
  type PublicAgentCard,
} from '../../protocol/src/index.js';
import { createPublicKey, verify } from 'node:crypto';
export { createIdentity } from '../../core/src/index.js';
export * from '../../protocol/src/index.js';

export class OpenClaspClient {
  constructor(
    readonly baseUrl = 'http://localhost:3100/v0.1',
    readonly accessToken?: string,
  ) {}
  private async request<T>(path: string, init?: RequestInit): Promise<T> {
    const response = await fetch(`${this.baseUrl}${path}`, {
      ...init,
      headers: {
        ...(init?.body !== undefined && init.body !== null
          ? { 'content-type': 'application/json' }
          : {}),
        ...(this.accessToken ? { authorization: `Bearer ${this.accessToken}` } : {}),
        ...init?.headers,
      },
    });
    const body = (await response.json()) as any;
    if (!response.ok) throw new Error(body.error ?? `OpenClasp request failed: ${response.status}`);
    return body as T;
  }
  registerAgent(identity: unknown) {
    return this.request('/agents', { method: 'POST', body: JSON.stringify(identity) });
  }
  getProfile(agentId: string, version: string, taskCategory: string) {
    return this.request(
      `/profiles/${encodeURIComponent(agentId)}?version=${encodeURIComponent(version)}&taskCategory=${encodeURIComponent(taskCategory)}`,
    );
  }
  saveContract(contract: unknown) {
    return this.request('/interactions/contracts', {
      method: 'POST',
      body: JSON.stringify(contract),
    });
  }
  assess(input: unknown) {
    return this.request('/risk/assess', { method: 'POST', body: JSON.stringify(input) });
  }
  recordEvent(event: unknown) {
    return this.request('/events', { method: 'POST', body: JSON.stringify(event) });
  }
  checkClaim(claim: string) {
    return this.request('/claims/check', { method: 'POST', body: JSON.stringify({ claim }) });
  }
  submitReceipt(receipt: unknown) {
    return this.request('/receipts', { method: 'POST', body: JSON.stringify(receipt) });
  }
  verifyReceipt(receipt: unknown) {
    return this.request('/receipts/verify', { method: 'POST', body: JSON.stringify(receipt) });
  }
  submitFeedback(feedback: unknown) {
    return this.request('/feedback', { method: 'POST', body: JSON.stringify(feedback) });
  }
  setContributionConsent(agentId: string, enabled: boolean) {
    return this.request('/contributions/consent', {
      method: 'POST',
      body: JSON.stringify({ agentId, enabled }),
    });
  }
  getPublicAgentCard(agentId: string): Promise<PublicAgentCard> {
    const root = this.baseUrl.replace(/\/v0\.1\/?$/, '');
    return fetch(`${root}/agents/${encodeURIComponent(agentId)}/card.json`).then(
      async (response) => {
        const body = (await response.json()) as any;
        if (!response.ok)
          throw new Error(body.error ?? `OpenClasp request failed: ${response.status}`);
        return body as PublicAgentCard;
      },
    );
  }
  resolveAgent(reference: string): Promise<AgentResolution> {
    const root = this.baseUrl.replace(/\/v0\.1\/?$/, '');
    return fetch(`${root}/directory/resolve?reference=${encodeURIComponent(reference)}`).then(
      async (response) => {
        const body = (await response.json()) as any;
        if (!response.ok)
          throw new Error(body.error ?? `OpenClasp request failed: ${response.status}`);
        return body as AgentResolution;
      },
    );
  }
  searchAgents(input: { query?: string; capability?: string; limit?: number } = {}) {
    const root = this.baseUrl.replace(/\/v0\.1\/?$/, '');
    const search = new URLSearchParams();
    if (input.query) search.set('query', input.query);
    if (input.capability) search.set('capability', input.capability);
    if (input.limit) search.set('limit', String(input.limit));
    return fetch(`${root}/directory/search?${search}`).then(async (response) => {
      const body = (await response.json()) as any;
      if (!response.ok)
        throw new Error(body.error ?? `OpenClasp request failed: ${response.status}`);
      return body as PublicAgentCard[];
    });
  }
  getContextualIntelligence(input: { agentId?: string; taskCategory?: string } = {}) {
    const search = new URLSearchParams();
    if (input.agentId) search.set('agentId', input.agentId);
    if (input.taskCategory) search.set('taskCategory', input.taskCategory);
    return this.request(`/intelligence?${search}`);
  }
  recommendAgents(
    input: { agentId?: string; taskCategory?: string; query?: string; limit?: number } = {},
  ) {
    const search = new URLSearchParams();
    if (input.agentId) search.set('agentId', input.agentId);
    if (input.taskCategory) search.set('taskCategory', input.taskCategory);
    if (input.query) search.set('query', input.query);
    if (input.limit) search.set('limit', String(input.limit));
    return this.request(`/marketplace?${search}`);
  }
  async verifyPlatformRecord(value: Record<string, unknown>): Promise<boolean> {
    const root = this.baseUrl.replace(/\/v0\.1\/?$/, '');
    const keyUrl =
      typeof value.verification === 'object' &&
      value.verification !== null &&
      'verificationKeyUrl' in value.verification &&
      typeof value.verification.verificationKeyUrl === 'string'
        ? value.verification.verificationKeyUrl
        : `${root}/.well-known/openclasp-session-key`;
    const response = await fetch(keyUrl);
    if (!response.ok) return false;
    const key = (await response.json()) as { publicKey?: string };
    return typeof key.publicKey === 'string' && verifyRecordAttestation(value, key.publicKey);
  }
  createFederatedInteraction(value: FederatedInteraction) {
    return this.request<FederatedInteraction>('/federated-interactions', {
      method: 'POST',
      body: JSON.stringify(value),
    });
  }
  listFederatedInteractions() {
    return this.request<FederatedInteraction[]>('/federated-interactions');
  }
  getFederatedInteraction(interactionId: string) {
    return this.request<FederatedInteraction>(
      `/federated-interactions/${encodeURIComponent(interactionId)}`,
    );
  }
  getLiveSession(interactionId: string, agentId: string): Promise<LiveSessionActivation> {
    return this.request(
      `/federated-interactions/${encodeURIComponent(interactionId)}/session?agentId=${encodeURIComponent(agentId)}`,
    );
  }
  respondToFederatedInteraction(
    interactionId: string,
    agentId: string,
    decision: 'accept' | 'reject',
  ) {
    return this.request<FederatedInteraction>(
      `/federated-interactions/${encodeURIComponent(interactionId)}/respond`,
      { method: 'POST', body: JSON.stringify({ agentId, decision }) },
    );
  }
  proposeContractRevision(
    interactionId: string,
    agentId: string,
    contract: InteractionContract,
    expectedTermsHash?: string,
  ) {
    return this.request<FederatedInteraction>(
      `/federated-interactions/${encodeURIComponent(interactionId)}/contract-proposals`,
      {
        method: 'POST',
        body: JSON.stringify({ agentId, contract, expectedTermsHash }),
      },
    );
  }
  respondToContractRevision(
    interactionId: string,
    revisionId: string,
    agentId: string,
    decision: 'accept' | 'reject',
  ) {
    return this.request<FederatedInteraction>(
      `/federated-interactions/${encodeURIComponent(interactionId)}/contract-proposals/${encodeURIComponent(revisionId)}/respond`,
      { method: 'POST', body: JSON.stringify({ agentId, decision }) },
    );
  }
  getRuntimeBootstrap(): Promise<RuntimeBootstrap> {
    return this.request('/runtime/bootstrap');
  }
  connectRuntime(endpoint: string): Promise<RuntimeConnection> {
    return this.request('/runtime', {
      method: 'PUT',
      body: JSON.stringify({ endpoint }),
    });
  }
  disconnectRuntime(): Promise<{ agentId: string; status: 'disabled' }> {
    return this.request('/runtime', { method: 'DELETE' });
  }
  heartbeatRuntime(): Promise<{ status: 'online' | 'offline'; checkedAt: string }> {
    return this.request('/runtime/heartbeat', { method: 'POST' });
  }
}

export type RuntimeBootstrap = {
  agentId: string;
  openClaspUrl: string;
  runtimeRegistrationEndpoint: string;
  protocol: 'A2A/1.0';
  controlProtocol: 'OpenClasp/0.1';
};

export type RuntimeConnection = {
  agentId: string;
  endpoint: string;
  a2aEndpoint: string;
  status: 'verified';
  verifiedAt: string;
  verificationKey: string;
};

export function createSignedEvent(
  input: Omit<InteractionEvent, 'payloadHash' | 'signature'>,
  key: KeyPair,
): InteractionEvent {
  return signObject(
    { ...input, payloadHash: canonicalHash(input.payload) },
    key,
  ) as InteractionEvent;
}

export function createSignedEnvelope(
  input: Omit<TrustEnvelope, 'signature'>,
  key: KeyPair,
): TrustEnvelope {
  return signObject(input, key) as TrustEnvelope;
}

function validRuntimeSignature(
  publicKey: string,
  requestId: string,
  timestamp: string,
  body: string,
  signature: string,
) {
  if (Math.abs(Date.now() - Date.parse(timestamp)) > 5 * 60_000) return false;
  return verify(
    null,
    Buffer.from(`${timestamp}.${requestId}.${body}`),
    createPublicKey({ key: Buffer.from(publicKey, 'base64url'), type: 'spki', format: 'der' }),
    Buffer.from(signature.replace(/^v1=/, ''), 'base64url'),
  );
}

export function createOpenClaspRuntimeHandler(input: {
  agentId: string;
  a2aEndpoint: string;
  openClaspUrl?: string;
  openClaspVerificationKey?: string;
  onSessionOffer: (
    offer: LiveSessionOffer,
  ) =>
    Promise<{ accepted: boolean; sessionId?: string }> | { accepted: boolean; sessionId?: string };
  onSessionActivated: (session: LiveSessionActivation) => Promise<void> | void;
  loadSession: (interactionId: string) => Promise<LiveSessionActivation | undefined>;
  onMessage: (input: {
    session: LiveSessionActivation;
    requestId: string | number;
    message: unknown;
  }) => Promise<unknown> | unknown;
}) {
  let verificationKeyPromise: Promise<string> | undefined;
  const verificationKey = () => {
    if (input.openClaspVerificationKey) return Promise.resolve(input.openClaspVerificationKey);
    return (verificationKeyPromise ??= fetch(
      `${(input.openClaspUrl ?? 'https://openclasp.vercel.app').replace(/\/$/, '')}/.well-known/openclasp-session-key`,
    )
      .then(async (response) => {
        if (!response.ok) throw new Error(`OpenClasp key discovery failed: ${response.status}`);
        const value = (await response.json()) as { publicKey?: unknown };
        if (typeof value.publicKey !== 'string')
          throw new Error('Invalid OpenClasp verification key');
        return value.publicKey;
      })
      .catch((error) => {
        verificationKeyPromise = undefined;
        throw error;
      }));
  };
  return async (request: Request): Promise<Response> => {
    const body = await request.text();
    let parsed: Record<string, unknown>;
    try {
      parsed = JSON.parse(body) as Record<string, unknown>;
    } catch {
      return Response.json({ error: 'invalid_json' }, { status: 400 });
    }
    if (parsed.type === 'openclasp.runtime.verify')
      return Response.json({
        type: 'openclasp.runtime.verified',
        version: '1',
        agentId: parsed.agentId,
        challenge: parsed.challenge,
        a2aEndpoint: input.a2aEndpoint,
      });
    if (parsed.type !== 'openclasp.session.offer' && parsed.type !== 'openclasp.session.activation')
      return handleDirectMessage(request, parsed, input);
    const requestId = request.headers.get('openclasp-request-id') ?? '';
    const timestamp = request.headers.get('openclasp-timestamp') ?? '';
    const signature = request.headers.get('openclasp-signature') ?? '';
    let signatureValid = false;
    try {
      signatureValid = Boolean(
        requestId &&
        timestamp &&
        signature &&
        validRuntimeSignature(await verificationKey(), requestId, timestamp, body, signature),
      );
    } catch {
      return Response.json({ error: 'openclasp_key_unavailable' }, { status: 503 });
    }
    if (!signatureValid)
      return Response.json({ error: 'invalid_openclasp_signature' }, { status: 401 });
    if (parsed.type === 'openclasp.session.offer') {
      const result = LiveSessionOfferSchema.safeParse(parsed);
      if (
        !result.success ||
        result.data.offerId !== requestId ||
        result.data.agentId !== input.agentId
      )
        return Response.json({ error: 'invalid_session_offer' }, { status: 400 });
      const decision = await input.onSessionOffer(result.data);
      if (!decision.accepted) return Response.json({ error: 'session_declined' }, { status: 409 });
      if (!decision.sessionId)
        return Response.json({ error: 'durable_session_id_required' }, { status: 500 });
      return Response.json({
        type: 'openclasp.session.accepted',
        version: '1',
        offerId: result.data.offerId,
        interactionId: result.data.interactionId,
        agentId: input.agentId,
        sessionId: decision.sessionId,
        a2aEndpoint: input.a2aEndpoint,
        expiresAt: result.data.expiresAt,
      });
    }
    const activation = LiveSessionActivationSchema.safeParse(parsed);
    if (
      !activation.success ||
      activation.data.activationId !== requestId ||
      activation.data.agentId !== input.agentId
    )
      return Response.json({ error: 'invalid_session_activation' }, { status: 400 });
    await input.onSessionActivated(activation.data);
    return Response.json({ accepted: true, activationId: activation.data.activationId });
  };
}

type RuntimeHandlerInput = Parameters<typeof createOpenClaspRuntimeHandler>[0];

export interface RuntimeSessionStore {
  get(interactionId: string): Promise<LiveSessionActivation | undefined>;
  put(interactionId: string, session: LiveSessionActivation): Promise<void>;
}

export interface AgentRuntimeAdapter {
  readonly name: string;
  prepareSession(
    offer: LiveSessionOffer,
  ): Promise<{ accepted: boolean; sessionId?: string }> | { accepted: boolean; sessionId?: string };
  activateSession(session: LiveSessionActivation): Promise<void> | void;
  receiveMessage(input: {
    session: LiveSessionActivation;
    requestId: string | number;
    message: unknown;
  }): Promise<unknown> | unknown;
}

/** In-memory storage is useful for tests only. Production runtimes must use durable storage. */
export class MemoryRuntimeSessionStore implements RuntimeSessionStore {
  readonly sessions = new Map<string, LiveSessionActivation>();

  async get(interactionId: string) {
    return this.sessions.get(interactionId);
  }

  async put(interactionId: string, session: LiveSessionActivation) {
    this.sessions.set(interactionId, session);
  }
}

export function createAgentRuntimeConnector(input: {
  agentId: string;
  a2aEndpoint: string;
  adapter: AgentRuntimeAdapter;
  sessions: RuntimeSessionStore;
  openClaspUrl?: string;
  openClaspVerificationKey?: string;
}) {
  return createOpenClaspRuntimeHandler({
    agentId: input.agentId,
    a2aEndpoint: input.a2aEndpoint,
    ...(input.openClaspUrl ? { openClaspUrl: input.openClaspUrl } : {}),
    ...(input.openClaspVerificationKey
      ? { openClaspVerificationKey: input.openClaspVerificationKey }
      : {}),
    async onSessionOffer(offer) {
      const decision = await input.adapter.prepareSession(offer);
      return decision.accepted
        ? { accepted: true, sessionId: decision.sessionId ?? crypto.randomUUID() }
        : { accepted: false };
    },
    async onSessionActivated(session) {
      await input.sessions.put(session.interactionId, session);
      await input.adapter.activateSession(session);
    },
    loadSession: (interactionId) => input.sessions.get(interactionId),
    onMessage: (message) => input.adapter.receiveMessage(message),
  });
}

export class HttpAgentRuntimeAdapter implements AgentRuntimeAdapter {
  readonly name = 'http-webhook';
  private readonly baseUrl: string;

  constructor(
    baseUrl: string,
    private readonly options: {
      bearerToken?: string;
      timeoutMs?: number;
    } = {},
  ) {
    this.baseUrl = baseUrl.replace(/\/$/, '');
  }

  private async post<T>(path: string, body: unknown): Promise<T> {
    const response = await fetch(`${this.baseUrl}${path}`, {
      method: 'POST',
      headers: {
        'content-type': 'application/json',
        ...(this.options.bearerToken
          ? { authorization: `Bearer ${this.options.bearerToken}` }
          : {}),
      },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(this.options.timeoutMs ?? 30_000),
    });
    const text = await response.text();
    let value: unknown = {};
    if (text) {
      try {
        value = JSON.parse(text);
      } catch {
        throw new Error(`Agent adapter returned non-JSON from ${path}`);
      }
    }
    if (!response.ok) {
      const error = value as { error?: unknown };
      throw new Error(
        typeof error.error === 'string'
          ? error.error
          : `Agent adapter ${path} returned HTTP ${response.status}`,
      );
    }
    return value as T;
  }

  async prepareSession(offer: LiveSessionOffer) {
    const decision = await this.post<{ accepted?: unknown; sessionId?: unknown }>(
      '/openclasp/session-offer',
      offer,
    );
    return {
      accepted: decision.accepted === true,
      ...(typeof decision.sessionId === 'string' ? { sessionId: decision.sessionId } : {}),
    };
  }

  async activateSession(session: LiveSessionActivation) {
    await this.post('/openclasp/session-activated', session);
  }

  receiveMessage(input: {
    session: LiveSessionActivation;
    requestId: string | number;
    message: unknown;
  }) {
    return this.post('/openclasp/message', input);
  }
}

function decodeSessionCredential(token: string) {
  const [payload, signature] = token.split('.');
  if (!payload || !signature) throw new Error('Invalid live-session credential');
  return {
    payload,
    signature,
    grant: JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as {
      interactionId?: unknown;
      senderAgentId?: unknown;
      recipientAgentId?: unknown;
      expiresAt?: unknown;
    },
  };
}

async function handleDirectMessage(
  request: Request,
  parsed: Record<string, unknown>,
  input: RuntimeHandlerInput,
) {
  const rpc = parsed as { jsonrpc?: unknown; id?: unknown; method?: unknown; params?: unknown };
  if (
    rpc.jsonrpc !== '2.0' ||
    (typeof rpc.id !== 'string' && typeof rpc.id !== 'number') ||
    rpc.method !== 'message/send'
  )
    return Response.json({ error: 'invalid_a2a_request' }, { status: 400 });
  const authorization = request.headers.get('authorization');
  if (!authorization?.startsWith('Bearer '))
    return Response.json({ error: 'session_credential_required' }, { status: 401 });
  let session: LiveSessionActivation;
  try {
    const credential = decodeSessionCredential(authorization.slice(7));
    if (typeof credential.grant.interactionId !== 'string')
      throw new Error('Invalid interaction credential');
    const loaded = await input.loadSession(credential.grant.interactionId);
    if (!loaded) return Response.json({ error: 'live_session_not_found' }, { status: 404 });
    session = loaded;
    const valid = verify(
      null,
      Buffer.from(credential.payload),
      createPublicKey({
        key: Buffer.from(session.peer.verificationKey, 'base64url'),
        type: 'spki',
        format: 'der',
      }),
      Buffer.from(credential.signature, 'base64url'),
    );
    if (
      !valid ||
      credential.grant.recipientAgentId !== input.agentId ||
      credential.grant.senderAgentId !== session.peer.agentId ||
      typeof credential.grant.expiresAt !== 'number' ||
      credential.grant.expiresAt <= Date.now() ||
      Date.parse(session.expiresAt) <= Date.now()
    )
      return Response.json({ error: 'invalid_session_credential' }, { status: 401 });
  } catch {
    return Response.json({ error: 'invalid_session_credential' }, { status: 401 });
  }
  try {
    const result = await input.onMessage({ session, requestId: rpc.id, message: rpc.params });
    return Response.json({ jsonrpc: '2.0', id: rpc.id, result });
  } catch (error) {
    return Response.json(
      {
        jsonrpc: '2.0',
        id: rpc.id,
        error: { code: -32000, message: error instanceof Error ? error.message : 'Agent failed' },
      },
      { status: 500 },
    );
  }
}

export async function sendOpenClaspDirectMessage(
  session: LiveSessionActivation,
  payload: unknown,
  requestId = crypto.randomUUID(),
) {
  const message =
    payload && typeof payload === 'object'
      ? {
          ...(payload as Record<string, unknown>),
          metadata: {
            ...(((payload as Record<string, unknown>).metadata as Record<string, unknown>) ?? {}),
            [DEFAULT_EXTENSION_URI]: {
              interactionId: session.interactionId,
              termsHash: session.contractHash,
              initiatorAgentId:
                session.role === 'initiator' ? session.agentId : session.peer.agentId,
              responderAgentId:
                session.role === 'responder' ? session.agentId : session.peer.agentId,
            },
          },
        }
      : payload;
  const response = await fetch(session.peer.endpoint, {
    method: 'POST',
    headers: {
      authorization: `Bearer ${session.peer.bearerToken}`,
      'content-type': 'application/json',
      'A2A-Extensions': DEFAULT_EXTENSION_URI,
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: requestId,
      method: 'message/send',
      params: { message },
    }),
  });
  const result = (await response.json()) as unknown;
  if (!response.ok) throw new Error(`Direct agent request failed with HTTP ${response.status}`);
  return result;
}

export async function reportOpenClaspSessionEvent(
  session: LiveSessionActivation,
  event: LiveSessionEvent,
) {
  const value = LiveSessionEventSchema.parse(event);
  if (value.interactionId !== session.interactionId || value.agentId !== session.agentId)
    throw new Error('Session event does not match the active session');
  const response = await fetch(session.reporting.endpoint, {
    method: 'POST',
    headers: {
      authorization: `Bearer ${session.reporting.bearerToken}`,
      'content-type': 'application/json',
    },
    body: JSON.stringify(value),
  });
  const result = (await response.json()) as unknown;
  if (!response.ok) throw new Error(`OpenClasp event report failed with HTTP ${response.status}`);
  return result;
}
1	`import {`
2	`DEFAULT_EXTENSION_URI,`
3	`canonicalHash,`
4	`signObject,`
5	`verifyRecordAttestation,`
6	`type InteractionEvent,`
7	`type KeyPair,`
8	`type TrustEnvelope,`
9	`type FederatedInteraction,`
10	`type AgentResolution,`
11	`type InteractionContract,`
12	`LiveSessionActivationSchema,`
13	`LiveSessionEventSchema,`
14	`LiveSessionOfferSchema,`
15	`type LiveSessionActivation,`
16	`type LiveSessionEvent,`
17	`type LiveSessionOffer,`
18	`type PublicAgentCard,`
19	`} from '../../protocol/src/index.js';`
20	`import { createPublicKey, verify } from 'node:crypto';`
21	`export { createIdentity } from '../../core/src/index.js';`
22	`export * from '../../protocol/src/index.js';`
23
24	`export class OpenClaspClient {`
25	`constructor(`
26	`readonly baseUrl = 'http://localhost:3100/v0.1',`
27	`readonly accessToken?: string,`
28	`) {}`
29	`private async request<T>(path: string, init?: RequestInit): Promise<T> {`
30	const response = await fetch(`${this.baseUrl}${path}`, {
31	`...init,`
32	`headers: {`
33	`...(init?.body !== undefined && init.body !== null`
34	`? { 'content-type': 'application/json' }`
35	`: {}),`
36	...(this.accessToken ? { authorization: `Bearer ${this.accessToken}` } : {}),
37	`...init?.headers,`
38	`},`
39	`});`
40	`const body = (await response.json()) as any;`