@robodev-ai/runtime 0.1.0

package/src/openapi.ts

@@ -0,0 +1,396 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+import type { ApiDefinition, HttpMethod } from "@robodev-ai/sdk";
+import { openApiDocumentedPath, pathParamNames } from "./path-match.js";
+
+export type RuntimeRoute = {
+  method: HttpMethod;
+  path: string;
+  file: string;
+  def: ApiDefinition;
+  paramNames?: string[];
+};
+
+function ref(name: string) {
+  return { $ref: `#/components/schemas/${name}` };
+}
+
+function authComponents() {
+  return {
+    AuthnTokenResponse: {
+      type: "object",
+      properties: {
+        accessToken: { type: "string" },
+        refreshToken: { type: "string" },
+      },
+      required: ["accessToken", "refreshToken"],
+    },
+    AuthnTokenRequest: {
+      type: "object",
+      properties: { refreshToken: { type: "string" } },
+      required: ["refreshToken"],
+    },
+    StatusResponse: {
+      type: "object",
+      properties: {
+        status: { type: "string" },
+        message: { type: "string" },
+        code: { type: "string" },
+      },
+      required: ["status", "message", "code"],
+    },
+    UserMeResponse: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        name: { type: "string", nullable: true },
+        email: { type: "string" },
+      },
+      required: ["id", "email"],
+    },
+    UserMeUpdateRequest: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        email: { type: "string" },
+      },
+    },
+    UserAuthPasswordLoginRequest: {
+      type: "object",
+      properties: {
+        email: { type: "string" },
+        password: { type: "string" },
+      },
+      required: ["email", "password"],
+    },
+    UserAuthPasswordRegisterRequest: {
+      type: "object",
+      properties: {
+        email: { type: "string" },
+        password: { type: "string", minLength: 12 },
+        name: { type: "string" },
+      },
+      required: ["email", "password"],
+    },
+    UserAuthEmailGenerateRequest: {
+      type: "object",
+      properties: { email: { type: "string" } },
+      required: ["email"],
+    },
+    UserAuthMagicConsumeRequest: {
+      type: "object",
+      properties: { code: { type: "string" } },
+      required: ["code"],
+    },
+  };
+}
+
+function reservedStoragePaths(): Record<string, Record<string, unknown>> {
+  return {
+    "/storage/objects/{key}": {
+      get: {
+        operationId: "storage_get_object",
+        tags: ["robodev_storage"],
+        parameters: [
+          { name: "key", in: "path", required: true, schema: { type: "string" } },
+          { name: "exp", in: "query", schema: { type: "integer" } },
+          { name: "sig", in: "query", schema: { type: "string" } },
+        ],
+        responses: {
+          302: { description: "Redirect to object bytes" },
+          404: { description: "Not found" },
+        },
+      },
+    },
+  };
+}
+
+function jsonBody(schemaName: string) {
+  return {
+    required: true,
+    content: { "application/json": { schema: ref(schemaName) } },
+  };
+}
+
+function jsonOk(schemaName: string, status = "200") {
+  return {
+    [status]: {
+      description: "OK",
+      content: { "application/json": { schema: ref(schemaName) } },
+    },
+  };
+}
+
+function reservedAuthPaths(): Record<string, Record<string, unknown>> {
+  const userAuth = ["User Auth"];
+  const user = ["User"];
+  const bearer = { security: [{ bearerAuth: [] }] };
+  return {
+    "/api/user/auth/login": {
+      post: {
+        operationId: "UserAuthLocalPasswordController_login",
+        tags: userAuth,
+        requestBody: jsonBody("UserAuthPasswordLoginRequest"),
+        responses: {
+          ...jsonOk("AuthnTokenResponse"),
+          401: { description: "invalid-credentials" },
+        },
+      },
+    },
+    "/api/user/auth/register": {
+      post: {
+        operationId: "UserAuthLocalPasswordController_register",
+        tags: userAuth,
+        requestBody: jsonBody("UserAuthPasswordRegisterRequest"),
+        responses: {
+          ...jsonOk("AuthnTokenResponse", "201"),
+          409: { description: "identity-already-exists" },
+        },
+      },
+    },
+    "/api/user/auth/refresh": {
+      post: {
+        operationId: "UserAuthJwtController_accessToken",
+        tags: userAuth,
+        requestBody: jsonBody("AuthnTokenRequest"),
+        responses: {
+          ...jsonOk("AuthnTokenResponse"),
+          401: { description: "identity-not-found" },
+        },
+      },
+    },
+    "/api/user/auth/magic-link": {
+      get: {
+        operationId: "UserAuthMagicLinkController_generate",
+        tags: userAuth,
+        parameters: [
+          { name: "email", in: "query", required: true, schema: { type: "string" } },
+          { name: "redirect_uri", in: "query", schema: { type: "string" } },
+        ],
+        responses: jsonOk("StatusResponse"),
+      },
+    },
+    "/api/user/auth/magic-link/callback": {
+      get: {
+        operationId: "UserAuthMagicLinkController_consume",
+        tags: userAuth,
+        parameters: [{ name: "code", in: "query", required: true, schema: { type: "string" } }],
+        responses: {
+          ...jsonOk("AuthnTokenResponse"),
+          400: { description: "nonce-invalid" },
+        },
+      },
+    },
+    "/api/user/auth/forgot-password": {
+      post: {
+        operationId: "UserAuthForgotPasswordController_requestReset",
+        tags: userAuth,
+        requestBody: jsonBody("UserAuthEmailGenerateRequest"),
+        responses: jsonOk("StatusResponse"),
+      },
+    },
+    "/api/user/auth/forgot-password/callback": {
+      post: {
+        operationId: "UserAuthForgotPasswordController_consumeReset",
+        tags: userAuth,
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  code: { type: "string" },
+                  password: { type: "string", minLength: 12 },
+                },
+                required: ["code", "password"],
+              },
+            },
+          },
+        },
+        responses: {
+          ...jsonOk("StatusResponse"),
+          400: { description: "nonce-invalid" },
+        },
+      },
+    },
+    "/api/user/auth/google": {
+      get: {
+        operationId: "UserAuthGoogleController_login",
+        tags: userAuth,
+        parameters: [
+          { name: "redirect_uri", in: "query", required: true, schema: { type: "string" } },
+        ],
+        responses: {
+          302: { description: "Redirect to Google" },
+          400: { description: "invalid_redirect_uri" },
+          503: { description: "Google OAuth is not configured" },
+        },
+      },
+    },
+    "/api/user/auth/apple/callback": {
+      get: {
+        operationId: "UserAuthAppleController_login",
+        tags: userAuth,
+        responses: {
+          503: { description: "Apple sign-in is not available" },
+        },
+      },
+    },
+    "/api/user/me": {
+      get: {
+        operationId: "UserMeController_get",
+        tags: user,
+        ...bearer,
+        responses: {
+          ...jsonOk("UserMeResponse"),
+          401: { description: "identity-not-found" },
+        },
+      },
+      put: {
+        operationId: "UserMeController_update",
+        tags: user,
+        ...bearer,
+        requestBody: jsonBody("UserMeUpdateRequest"),
+        responses: {
+          ...jsonOk("UserMeResponse"),
+          401: { description: "identity-not-found" },
+          409: { description: "identity-already-exists" },
+        },
+      },
+    },
+  };
+}
+
+export function buildOpenApi(input: {
+  title: string;
+  projectId: string;
+  routes: RuntimeRoute[];
+}): Record<string, unknown> {
+  const paths: Record<string, Record<string, unknown>> = {
+    ...reservedAuthPaths(),
+    ...reservedStoragePaths(),
+  };
+
+  for (const route of input.routes) {
+    const documentedPath = openApiDocumentedPath(route.path);
+    const item = (paths[documentedPath] ??= {});
+    const op: Record<string, unknown> = {
+      operationId: `${route.method}_${route.path.replaceAll("/", "_") || "root"}`,
+      tags: [route.file],
+      responses: {
+        200: {
+          description: "OK",
+          content: route.def.response
+            ? {
+                "application/json": {
+                  schema: zodToJsonSchema(route.def.response, { $refStrategy: "none" }),
+                },
+              }
+            : { "application/json": { schema: {} } },
+        },
+      },
+    };
+
+    const auth = route.def.auth ?? false;
+    if (auth === "required" || typeof auth === "function") {
+      op.security = [{ bearerAuth: [] }];
+      (op.responses as Record<string, unknown>)[401] = { description: "Unauthorized" };
+    } else if (auth === "optional") {
+      op.security = [{}, { bearerAuth: [] }];
+    }
+
+    const parameters: Record<string, unknown>[] = pathParamNames(route.path).map((name) => ({
+      name,
+      in: "path",
+      required: true,
+      schema: { type: "string" },
+    }));
+    if (route.def.query) {
+      const schema = zodToJsonSchema(route.def.query, { $refStrategy: "none" }) as {
+        properties?: Record<string, unknown>;
+        required?: string[];
+      };
+      parameters.push(
+        ...Object.entries(schema.properties ?? {}).map(([name, prop]) => ({
+          name,
+          in: "query",
+          required: schema.required?.includes(name) ?? false,
+          schema: prop,
+        })),
+      );
+    }
+    if (parameters.length) op.parameters = parameters;
+
+    if (route.def.body && route.method !== "get") {
+      op.requestBody = {
+        required: true,
+        content: {
+          "application/json": {
+            schema: zodToJsonSchema(route.def.body, { $refStrategy: "none" }),
+          },
+        },
+      };
+    }
+
+    item[route.method] = op;
+  }
+
+  return {
+    openapi: "3.0.3",
+    info: {
+      title: input.title,
+      version: "1.0.0",
+      description: `Hosted APIs for ${input.projectId}`,
+    },
+    components: {
+      securitySchemes: {
+        bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
+      },
+      schemas: authComponents(),
+    },
+    paths,
+  };
+}
+
+export function swaggerHtml(openapiUrl: string): string {
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>Robodev API</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+    <style>body { margin: 0; }</style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script>
+      window.ui = SwaggerUIBundle({
+        url: ${JSON.stringify(openapiUrl)},
+        dom_id: '#swagger-ui',
+      });
+    </script>
+  </body>
+</html>`;
+}
+
+export function scalarHtml(openapiUrl: string): string {
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Robodev API</title>
+    <style>body { margin: 0; }</style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+    <script>
+      Scalar.createApiReference("#app", {
+        url: ${JSON.stringify(openapiUrl)},
+      });
+    </script>
+  </body>
+</html>`;
+}

package/src/password.ts

@@ -0,0 +1,20 @@
+import { randomBytes, scrypt as scryptCb, timingSafeEqual } from "node:crypto";
+import { promisify } from "node:util";
+
+const scrypt = promisify(scryptCb);
+
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(16);
+  const key = (await scrypt(password, salt, 64)) as Buffer;
+  return `${salt.toString("hex")}:${key.toString("hex")}`;
+}
+
+export async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const [saltHex, keyHex] = stored.split(":");
+  if (!saltHex || !keyHex) return false;
+  const salt = Buffer.from(saltHex, "hex");
+  const expected = Buffer.from(keyHex, "hex");
+  const actual = (await scrypt(password, salt, 64)) as Buffer;
+  if (actual.length !== expected.length) return false;
+  return timingSafeEqual(actual, expected);
+}

package/src/path-match.test.ts

@@ -0,0 +1,155 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  fileToRoute,
+  fileToSocketRoute,
+  isAuthHookFile,
+  jobNameFromFile,
+  matchProjectRoute,
+  matchSocketRoute,
+  openApiDocumentedPath,
+  socketNameFromFile,
+} from "./path-match.js";
+
+test("isAuthHookFile is hooks/auth.ts or robodev/hooks/auth.ts", () => {
+  assert.equal(isAuthHookFile("hooks/auth.ts"), true);
+  assert.equal(isAuthHookFile("robodev/hooks/auth.ts"), true);
+  assert.equal(isAuthHookFile("hooks/lib.ts"), false);
+  assert.equal(isAuthHookFile("jobs/auth.ts"), false);
+});
+
+test("jobNameFromFile strips robodev/", () => {
+  assert.equal(jobNameFromFile("jobs/resize.ts"), "resize");
+  assert.equal(jobNameFromFile("robodev/jobs/resize.ts"), "resize");
+});
+
+test("maps socket files to /sockets/... routes", () => {
+  assert.deepEqual(fileToSocketRoute("sockets/chat.ts"), {
+    path: "/sockets/chat",
+    paramNames: [],
+  });
+  assert.deepEqual(fileToSocketRoute("robodev/sockets/chat.ts"), {
+    path: "/sockets/chat",
+    paramNames: [],
+  });
+  assert.deepEqual(fileToSocketRoute("sockets/rooms/[roomId].ts"), {
+    path: "/sockets/rooms/:roomId",
+    paramNames: ["roomId"],
+  });
+  assert.equal(fileToSocketRoute("api/chat.ts"), null);
+  assert.equal(fileToSocketRoute("sockets/user.ts"), null);
+  assert.equal(fileToSocketRoute("sockets/api/user.ts"), null);
+  assert.equal(fileToSocketRoute("sockets/_robodev.ts"), null);
+  assert.equal(fileToSocketRoute("sockets/storage/objects.ts"), null);
+  assert.equal(socketNameFromFile("sockets/chat.ts"), "chat");
+  assert.equal(socketNameFromFile("robodev/sockets/rooms/[roomId].ts"), "rooms/[roomId]");
+});
+
+test("matchSocketRoute prefers exact paths over params", () => {
+  const sockets = [{ path: "/sockets/rooms/:roomId" }, { path: "/sockets/rooms/lobby" }];
+  assert.equal(
+    matchSocketRoute("/sockets/rooms/lobby", sockets)?.socket.path,
+    "/sockets/rooms/lobby",
+  );
+  assert.equal(matchSocketRoute("/sockets/rooms/abc", sockets)?.params.roomId, "abc");
+});
+
+test("maps robodev/api files the same as api/", () => {
+  assert.deepEqual(fileToRoute("robodev/api/planets.ts"), {
+    path: "/planets",
+    paramNames: [],
+  });
+  assert.deepEqual(fileToRoute("robodev/api/invoices/[id].ts"), {
+    path: "/invoices/:id",
+    paramNames: ["id"],
+  });
+});
+
+test("maps [id] files to parameterized routes", () => {
+  assert.deepEqual(fileToRoute("api/invoices/[id].ts"), {
+    path: "/invoices/:id",
+    paramNames: ["id"],
+  });
+  assert.deepEqual(fileToRoute("api/invoices/[id]/items.ts"), {
+    path: "/invoices/:id/items",
+    paramNames: ["id"],
+  });
+  assert.deepEqual(fileToRoute("api/invoices/[id]/items/[itemId].ts"), {
+    path: "/invoices/:id/items/:itemId",
+    paramNames: ["id", "itemId"],
+  });
+});
+
+test("maps nested api/api files to /api/...", () => {
+  assert.deepEqual(fileToRoute("api/api/planets.ts"), {
+    path: "/api/planets",
+    paramNames: [],
+  });
+});
+
+test("exact routes win over parameterized", () => {
+  const routes = [
+    { method: "get", path: "/invoices/:id" },
+    { method: "get", path: "/invoices/export" },
+  ];
+  const exact = matchProjectRoute("/api/invoices/export", "GET", routes);
+  assert.equal(exact?.route.path, "/invoices/export");
+  const param = matchProjectRoute("/api/invoices/abc", "GET", routes);
+  assert.equal(param?.route.path, "/invoices/:id");
+  assert.equal(param?.params.id, "abc");
+});
+
+test("serves file routes only under /api; exact /api/... wins over stripped", () => {
+  const routes = [
+    { method: "get", path: "/me" },
+    { method: "get", path: "/planets" },
+    { method: "get", path: "/api/planets" },
+  ];
+  assert.equal(matchProjectRoute("/api/me", "GET", routes)?.route.path, "/me");
+  assert.equal(matchProjectRoute("/planets", "GET", routes), null);
+  assert.equal(matchProjectRoute("/api/planets", "GET", routes)?.route.path, "/api/planets");
+  assert.equal(matchProjectRoute("/api/user/me", "GET", routes), null);
+});
+
+test("skips unsafe, reserved, and malformed paths", () => {
+  assert.equal(fileToRoute("api/../secret.ts"), null);
+  assert.deepEqual(fileToRoute("api/auth/login.ts"), {
+    path: "/auth/login",
+    paramNames: [],
+  });
+  assert.equal(fileToRoute("api/user.ts"), null);
+  assert.equal(fileToRoute("api/user/me.ts"), null);
+  assert.equal(fileToRoute("api/api/user.ts"), null);
+  assert.deepEqual(fileToRoute("api/storage.ts"), {
+    path: "/storage",
+    paramNames: [],
+  });
+  assert.equal(fileToRoute("api/storage/objects.ts"), null);
+  assert.equal(fileToRoute("api/storage/objects/[key].ts"), null);
+  assert.equal(fileToRoute("api/_robodev/ready.ts"), null);
+  assert.equal(fileToRoute("api/invoices/[id.ts"), null);
+  assert.equal(fileToRoute("api/invoices/[...id].ts"), null);
+  assert.equal(fileToRoute("api/invoices/[id]/[id].ts"), null);
+  assert.equal(fileToRoute("api/invoices/[123bad].ts"), null);
+});
+
+test("api/storage.ts is a normal defineApi at /api/storage", () => {
+  const routes = [{ method: "post", path: "/storage" }];
+  assert.equal(matchProjectRoute("/api/storage", "POST", routes)?.route.path, "/storage");
+});
+
+test("OpenAPI documents /api/... for defineApi routes", () => {
+  assert.equal(openApiDocumentedPath("/me"), "/api/me");
+  assert.equal(openApiDocumentedPath("/invoices/:id"), "/api/invoices/{id}");
+  assert.equal(openApiDocumentedPath("/api/planets"), "/api/planets");
+  assert.equal(openApiDocumentedPath("/"), "/api");
+});
+
+test("backend tests are not routes, jobs, or sockets", () => {
+  assert.equal(fileToRoute("robodev/api/_lib.seed.test.ts"), null);
+  assert.equal(fileToRoute("api/health.spec.ts"), null);
+  assert.equal(fileToSocketRoute("robodev/sockets/chat.test.ts"), null);
+  assert.equal(jobNameFromFile("robodev/jobs/resize.test.ts"), null);
+  assert.equal(socketNameFromFile("robodev/sockets/chat.spec.ts"), null);
+  assert.deepEqual(fileToRoute("robodev/api/latest.ts"), { path: "/latest", paramNames: [] });
+});