@superblocksteam/sdk 1.4.2 → 1.5.1

package/src/socket/handlers.ts

@@ -0,0 +1,248 @@
+import {
+  ApiToSign,
+  ApiToVerify,
+  AppToSign,
+  AppToVerify,
+  MethodHandlers,
+  RemoteCommitDto,
+  Signature,
+} from "../types";
+import { signResource, verifyResources } from "./signing";
+
+type MethodSchema<Params, Response> = (params: Params) => Promise<Response>;
+
+export interface ClientMethods {
+  v1: {
+    signing: {
+      signApplication: MethodSchema<
+        { branchName: string; toSign: AppToSign },
+        { signature: Signature }
+      >;
+      signApis: MethodSchema<
+        { branchName: string; toSign: ApiToSign[] },
+        { signatures: Signature[] }
+      >;
+      verifyApplication: MethodSchema<
+        { branchName: string; toVerify: AppToVerify },
+        { ok: boolean }
+      >;
+      verifyApi: MethodSchema<
+        { branchName: string; toVerify: ApiToVerify[] },
+        { ok: boolean }
+      >;
+    };
+  };
+}
+
+type ServerMethodSchema<Params, Response> = MethodSchema<
+  Params,
+  ResponseDto<Response>
+>;
+
+// This file contains the definition of the protocol used for communication between the SB server and clients
+
+type ResponseDto<T> = {
+  responseMeta: ResponseMeta;
+  data: T;
+};
+
+export type ResponseMeta = {
+  status: number;
+  success: boolean;
+  error?: APIResponseError;
+};
+
+type APIResponseError = {
+  code: number;
+  message: string;
+};
+
+export interface ServerMethods {
+  v1: {
+    echo: MethodSchema<{ message: string }, { message: string }>;
+    public: {
+      application: {
+        component: {
+          register: ServerMethodSchema<
+            {
+              applicationId: string;
+              branchName: string;
+              cliVersion: string;
+              componentEvent: string;
+              components: Record<string, unknown>;
+            },
+            { success: boolean }
+          >;
+          update: ServerMethodSchema<
+            {
+              applicationId: string;
+              branchName?: string;
+              srcFiles: string[];
+              buildFiles: string[];
+              registeredComponents: Record<string, unknown>;
+              cliVersion: string | undefined;
+              componentBaseUrl: string;
+              signingRequired: boolean;
+            },
+            { success: boolean }
+          >;
+        };
+        pushCommit: ServerMethodSchema<
+          {
+            applicationId: string;
+            branchName: string;
+            commitId: string;
+            commitMessage: string;
+            application: Record<string, unknown>;
+            page: Record<string, unknown>;
+            apis: Record<string, unknown>[];
+          },
+          RemoteCommitDto
+        >;
+      };
+      api: {
+        pushCommit: ServerMethodSchema<
+          {
+            apiId: string;
+            branchName: string;
+            commitId: string;
+            commitMessage: string;
+            apiPb: Record<string, unknown>;
+          },
+          RemoteCommitDto
+        >;
+      };
+    };
+  };
+}
+
+export function createRequestHandlers({
+  agentUrl,
+  token,
+}: {
+  token: string;
+  agentUrl?: string;
+}) {
+  const requestHandlers: MethodHandlers<ClientMethods, ServerMethods, unknown> =
+    {
+      v1: {
+        signing: {
+          signApplication: [
+            async ({
+              branchName,
+              toSign,
+            }: {
+              branchName: string;
+              toSign: AppToSign;
+            }) => {
+              if (!agentUrl) {
+                throw new Error(
+                  "Agent url not specified. This shouldn't happen."
+                );
+              }
+              const signature = await signResource({
+                agentUrl,
+                token: token,
+                branchName,
+                resource: {
+                  literal: {
+                    data: toSign.rootHash,
+                  },
+                },
+              });
+              return { signature: signature };
+            },
+          ],
+          signApis: [
+            async ({
+              branchName,
+              toSign,
+            }: {
+              branchName: string;
+              toSign: ApiToSign[];
+            }) => {
+              const signatures: Signature[] = [];
+              for (const { apiPb } of toSign) {
+                if (!agentUrl) {
+                  throw new Error(
+                    "Agent url not specified. This shouldn't happen."
+                  );
+                }
+                const signature = await signResource({
+                  agentUrl,
+                  token: token,
+                  branchName,
+                  resource: { api: apiPb },
+                });
+                signatures.push(signature);
+              }
+              return { signatures };
+            },
+          ],
+          verifyApplication: [
+            async ({
+              branchName,
+              toVerify,
+            }: {
+              branchName: string;
+              toVerify: AppToVerify;
+            }) => {
+              try {
+                if (!agentUrl) {
+                  throw new Error(
+                    "Agent url not specified. This shouldn't happen."
+                  );
+                }
+                await verifyResources({
+                  agentUrl,
+                  token,
+                  branchName,
+                  resources: [
+                    {
+                      literal: {
+                        data: toVerify.rootHash,
+                        signature: toVerify.signature,
+                      },
+                    },
+                  ],
+                });
+                return { ok: true };
+              } catch {
+                return { ok: false };
+              }
+            },
+          ],
+
+          verifyApi: [
+            async ({
+              branchName,
+              toVerify,
+            }: {
+              branchName: string;
+              toVerify: ApiToVerify[];
+            }) => {
+              try {
+                if (!agentUrl) {
+                  throw new Error(
+                    "Agent url not specified. This shouldn't happen."
+                  );
+                }
+                await verifyResources({
+                  agentUrl,
+                  token,
+                  branchName,
+                  resources: toVerify.map(({ apiPb }) => ({
+                    api: apiPb,
+                  })),
+                });
+                return { ok: true };
+              } catch {
+                return { ok: false };
+              }
+            },
+          ],
+        },
+      },
+    };
+  return requestHandlers;
+}

package/src/socket/index.ts

@@ -0,0 +1,164 @@
+import WebSocket from "isomorphic-ws";
+import {
+  ClientMethods,
+  createRequestHandlers,
+  ServerMethods,
+} from "./handlers";
+import { createISocketClient, ISocket } from "./socket";
+
+export type StdISocketRPCClient = ISocketClient<ServerMethods>;
+
+export async function connectToISocketRPCServer({
+  superblocksBaseUrl,
+  agentUrl,
+  token,
+}: {
+  superblocksBaseUrl: string;
+  token: string;
+  agentUrl?: string;
+}): Promise<StdISocketRPCClient> {
+  const requestHandlers = createRequestHandlers({
+    agentUrl,
+    token,
+  });
+  const authorization = `Bearer ${token}`;
+  const wsUrl = new URL("api/v1/rpc-ws", superblocksBaseUrl);
+  if (wsUrl.protocol === "http:") {
+    wsUrl.protocol = "ws:";
+  } else if (wsUrl.protocol === "https:") {
+    wsUrl.protocol = "wss:";
+  }
+
+  if (wsUrl.host === "localhost:3000") {
+    wsUrl.host = "127.0.0.1:8080";
+  } else if (wsUrl.hostname === "localhost") {
+    wsUrl.hostname = "127.0.0.1";
+  }
+  return await connectISocket<ServerMethods, ClientMethods, unknown>(
+    wsUrl.href,
+    authorization,
+    requestHandlers
+  );
+}
+
+// a subclass of ISocket that sends an auth token on the first request
+// this is useful for client-side sockets that need to authenticate
+// TODO(george): if we start using this for long-lived connections, we should add a way to refresh the token
+class ISocketWithClientAuth<
+  ImplementedMethods,
+  CallableMethods,
+  RequestContext = void
+> extends ISocket<ImplementedMethods, CallableMethods, RequestContext> {
+  private readonly authorization?: string;
+  private hasSentAuth = false;
+
+  constructor(
+    ws: WebSocket,
+    authorization: string | undefined,
+    requestHandlers: MethodHandlers<
+      ImplementedMethods,
+      CallableMethods,
+      RequestContext
+    >
+  ) {
+    super(ws, requestHandlers);
+    this.authorization = authorization;
+  }
+
+  // override `request` from the base class to send `authorization` when appropriate
+  async request<Params, Result>(
+    method: string,
+    params: Params
+  ): Promise<Result> {
+    // only send `authorization` on the first request
+    const authorization = this.hasSentAuth ? undefined : this.authorization;
+    const result = await super.request<Params, Result>(
+      method,
+      params,
+      authorization
+    );
+    this.hasSentAuth = true;
+    return result;
+  }
+}
+
+export async function connectISocket<
+  CallableMethods,
+  ImplementedMethods,
+  RequestContext = never
+>(
+  wsUrl: string,
+  authorization: string | undefined,
+  requestHandlers: MethodHandlers<
+    ImplementedMethods,
+    CallableMethods,
+    RequestContext
+  >
+): Promise<ISocketClient<CallableMethods>> {
+  const ws = await connectWebSocket(wsUrl);
+  const isocket = new ISocketWithClientAuth(ws, authorization, requestHandlers);
+  return createISocketClient(isocket);
+}
+
+export function connectWebSocket(wsUrl: string): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(wsUrl);
+
+    ws.addEventListener("open", () => {
+      // Resolve the promise with the WebSocket instance when the connection is open
+      resolve(ws);
+    });
+
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    ws.addEventListener("error", (error: Error) => {
+      // Reject the promise if there's an error
+      reject(error);
+    });
+  });
+}
+
+type MethodHandler<Params, Result, PeerMethods, RequestContext> = (
+  params: Params,
+  peer: ISocketClient<PeerMethods>,
+  ctx: RequestContext
+) => Promise<Result>;
+
+type MiddlewareHandler<Params, PeerMethods, RequestContext> = (
+  params: Params,
+  peerAuthorization: string | undefined,
+  peer: ISocketClient<PeerMethods>,
+  ctx: RequestContext
+) => Promise<void>;
+
+type MethodHandlers<Methods, PeerMethods, RequestContext> = {
+  [Key in keyof Methods]: Methods[Key] extends (
+    params: infer Params
+  ) => Promise<infer Result>
+    ? [
+        ...middlewareHandlers: MiddlewareHandler<
+          Params,
+          PeerMethods,
+          RequestContext
+        >[],
+        handler: MethodHandler<Params, Result, PeerMethods, RequestContext>
+      ]
+    : Methods[Key] extends Record<string, unknown>
+    ? MethodHandlers<Methods[Key], PeerMethods, RequestContext>
+    : never;
+};
+
+type ISocketClientMethodCall<Methods> = {
+  [Key in keyof Methods]: Methods[Key] extends (
+    params: infer P
+  ) => Promise<infer R>
+    ? (params: P) => Promise<R>
+    : Methods[Key] extends Record<string, unknown>
+    ? ISocketClientMethodCall<Methods[Key]>
+    : never;
+};
+
+type ISocketClient<Methods> = {
+  close: () => void;
+  call: ISocketClientMethodCall<Methods>;
+};

package/src/socket/signing.ts

@@ -0,0 +1,104 @@
+import axios, { AxiosRequestConfig, Method } from "axios";
+import {
+  ApiResource,
+  GenericResource,
+  Signature,
+  SignatureResponse,
+} from "../types";
+import { getSanitizedApi } from "../utils";
+
+export async function signResource({
+  token,
+  branchName,
+  resource,
+  agentUrl,
+}: {
+  token: string;
+  branchName: string;
+  resource: ApiResource | GenericResource;
+  agentUrl: string;
+}): Promise<Signature> {
+  const requestResource: Record<string, any> = {
+    branchName: branchName ?? "main",
+  };
+  if ((resource as ApiResource).api) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    requestResource.api = getSanitizedApi((resource as ApiResource).api);
+  } else {
+    requestResource.literal = (resource as GenericResource).literal;
+  }
+
+  const resp = await callAgent<SignatureResponse>({
+    baseUrl: agentUrl,
+    path: "v1/signature/sign",
+    method: "post",
+    token: token,
+    data: { resource: requestResource },
+  });
+  return resp.signature;
+}
+
+export async function verifyResources({
+  agentUrl,
+  token,
+  branchName,
+  resources,
+}: {
+  resources: Array<GenericResource | ApiResource>;
+  token: string;
+  branchName: string;
+  agentUrl: string;
+}): Promise<void> {
+  await callAgent<{ keyId: string }>({
+    baseUrl: agentUrl,
+    path: "v1/signature/verify",
+    method: "post",
+    token: token,
+    data: {
+      resources: resources.map((res) => {
+        if ((res as ApiResource).api) {
+          return {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            api: getSanitizedApi((res as ApiResource).api),
+            branchName: branchName ?? "main",
+          };
+        }
+        return {
+          ...res,
+          branchName: branchName ?? "main",
+        };
+      }),
+    },
+  });
+}
+
+async function callAgent<T>({
+  baseUrl,
+  path,
+  method,
+  token,
+  data,
+}: {
+  baseUrl: string;
+  path: string;
+  method: Method;
+  token: string;
+  data: any;
+}): Promise<T> {
+  try {
+    const url = new URL(path, baseUrl);
+    const config: AxiosRequestConfig = {
+      url: url.toString(),
+      method: method,
+      headers: {
+        Authorization: "Bearer " + token,
+      },
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      data: data,
+    };
+    const resp = await axios<T>(config);
+    return resp.data;
+  } catch (error) {
+    throw new Error(`Failed to request the agent ${baseUrl}. Error: ${error}`);
+  }
+}