@fitzzero/quickdraw-core 0.1.0

package/dist/server/index.js

@@ -0,0 +1,707 @@
+import express from 'express';
+import { createServer } from 'http';
+import { Server } from 'socket.io';
+import * as jose from 'jose';
+
+// src/shared/types.ts
+var consoleLogger = {
+  info: (message, meta) => console.log(`[INFO] ${message}`, meta ?? ""),
+  warn: (message, meta) => console.warn(`[WARN] ${message}`, meta ?? ""),
+  error: (message, meta) => console.error(`[ERROR] ${message}`, meta ?? ""),
+  debug: (message, meta) => console.debug(`[DEBUG] ${message}`, meta ?? ""),
+  child: () => consoleLogger
+};
+
+// src/server/BaseService.ts
+var BaseService = class {
+  serviceName;
+  hasEntryACL;
+  defaultACL;
+  logger;
+  // Subscription tracking: entryId -> Set of sockets
+  subscribers = /* @__PURE__ */ new Map();
+  // Prisma delegate for DB operations
+  delegate;
+  // Collection of public methods for registry discovery
+  publicMethods = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.serviceName = options.serviceName;
+    this.hasEntryACL = options.hasEntryACL ?? false;
+    this.defaultACL = options.defaultACL ?? [];
+    this.logger = options.logger?.child({ service: this.serviceName }) ?? consoleLogger.child({ service: this.serviceName });
+  }
+  /**
+   * Set the Prisma delegate for this service.
+   * Must be called in the constructor of derived classes.
+   */
+  setDelegate(delegate) {
+    this.delegate = delegate;
+  }
+  /**
+   * Get the delegate, throwing if not set.
+   */
+  getDelegate() {
+    if (!this.delegate) {
+      throw new Error(
+        `Delegate not set for service ${this.serviceName}. Call setDelegate() in constructor.`
+      );
+    }
+    return this.delegate;
+  }
+  // ===========================================================================
+  // Subscription Management
+  // ===========================================================================
+  /**
+   * Subscribe a socket to an entity's updates.
+   * Returns the current entity data if access is granted, null otherwise.
+   */
+  async subscribe(entryId, socket, requiredLevel = "Read") {
+    if (!socket.userId) {
+      return null;
+    }
+    const allowed = await this.checkSubscriptionAccess(
+      socket.userId,
+      entryId,
+      requiredLevel,
+      socket
+    );
+    if (!allowed) {
+      return null;
+    }
+    if (!this.subscribers.has(entryId)) {
+      this.subscribers.set(entryId, /* @__PURE__ */ new Set());
+    }
+    this.subscribers.get(entryId).add(socket);
+    this.logger.debug(`User ${socket.userId} subscribed to ${entryId}`);
+    const entity = await this.findById(entryId);
+    return entity;
+  }
+  /**
+   * Unsubscribe a socket from an entity's updates.
+   */
+  unsubscribe(entryId, socket) {
+    const subs = this.subscribers.get(entryId);
+    if (subs) {
+      subs.delete(socket);
+      if (subs.size === 0) {
+        this.subscribers.delete(entryId);
+      }
+    }
+  }
+  /**
+   * Remove a socket from all subscriptions (called on disconnect).
+   */
+  unsubscribeSocket(socket) {
+    for (const [entryId, sockets] of this.subscribers.entries()) {
+      if (sockets.has(socket)) {
+        sockets.delete(socket);
+        if (sockets.size === 0) {
+          this.subscribers.delete(entryId);
+        }
+      }
+    }
+  }
+  /**
+   * Emit an update to all subscribers of an entity.
+   */
+  emitUpdate(entryId, data) {
+    const eventName = `${this.serviceName}:update:${entryId}`;
+    const subs = this.subscribers.get(entryId);
+    if (subs) {
+      for (const socket of subs) {
+        socket.emit(eventName, data);
+      }
+    }
+  }
+  // ===========================================================================
+  // Access Control
+  // ===========================================================================
+  /**
+   * Check if a user has access to subscribe to an entity.
+   * Override in derived classes for custom logic.
+   */
+  async checkSubscriptionAccess(userId, entryId, requiredLevel, socket) {
+    if (this.hasServiceAccess(socket, requiredLevel)) {
+      return true;
+    }
+    if (this.checkAccess(userId, entryId, requiredLevel, socket)) {
+      return true;
+    }
+    if (this.hasEntryACL) {
+      return await this.checkEntryACL(userId, entryId, requiredLevel);
+    }
+    return false;
+  }
+  /**
+   * Check if a socket has service-level access.
+   */
+  hasServiceAccess(socket, requiredLevel) {
+    const userLevel = socket.serviceAccess?.[this.serviceName];
+    if (!userLevel) return false;
+    return this.isLevelSufficient(userLevel, requiredLevel);
+  }
+  /**
+   * Check if a user has access to an entity.
+   * Override in derived classes for custom logic (e.g., self-access).
+   */
+  checkAccess(_userId, _entryId, _requiredLevel, _socket) {
+    return false;
+  }
+  /**
+   * Check entry-level ACL stored on the entity.
+   */
+  async checkEntryACL(userId, entryId, requiredLevel) {
+    try {
+      const entity = await this.getDelegate().findUnique({
+        where: { id: entryId },
+        select: { acl: true }
+      });
+      const acl = entity?.acl;
+      if (!acl || !Array.isArray(acl)) return false;
+      const ace = acl.find((a) => a.userId === userId);
+      if (!ace) return false;
+      return this.isLevelSufficient(ace.level, requiredLevel);
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Compare access levels.
+   */
+  isLevelSufficient(userLevel, requiredLevel) {
+    const order = {
+      Public: 0,
+      Read: 1,
+      Moderate: 2,
+      Admin: 3
+    };
+    return (order[userLevel] ?? 0) >= (order[requiredLevel] ?? 0);
+  }
+  /**
+   * Ensure access for a public method.
+   * Throws if access is denied.
+   */
+  async ensureAccessForMethod(requiredLevel, socket, entryId) {
+    if (requiredLevel === "Public") {
+      return;
+    }
+    if (!socket.userId) {
+      throw new Error("Authentication required");
+    }
+    if (this.hasServiceAccess(socket, requiredLevel)) {
+      return;
+    }
+    if (entryId) {
+      if (this.checkAccess(socket.userId, entryId, requiredLevel, socket)) {
+        return;
+      }
+      if (this.hasEntryACL && await this.checkEntryACL(socket.userId, entryId, requiredLevel)) {
+        return;
+      }
+      throw new Error("Insufficient permissions");
+    }
+    if (requiredLevel === "Read") {
+      return;
+    }
+    throw new Error("Insufficient permissions");
+  }
+  // ===========================================================================
+  // CRUD Operations
+  // ===========================================================================
+  /**
+   * Find an entity by ID.
+   */
+  async findById(id) {
+    return await this.getDelegate().findUnique({
+      where: { id }
+    });
+  }
+  /**
+   * Create an entity and emit to subscribers.
+   */
+  async create(data) {
+    const entity = await this.getDelegate().create({ data });
+    this.emitUpdate(entity.id, entity);
+    this.logger.info(`Created entity ${entity.id}`);
+    return entity;
+  }
+  /**
+   * Update an entity and emit to subscribers.
+   */
+  async update(id, data) {
+    try {
+      const entity = await this.getDelegate().update({
+        where: { id },
+        data
+      });
+      this.emitUpdate(id, entity);
+      this.logger.info(`Updated entity ${id}`);
+      return entity;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Delete an entity and emit deletion event to subscribers.
+   */
+  async delete(id) {
+    try {
+      await this.getDelegate().delete({
+        where: { id }
+      });
+      this.emitUpdate(id, { id, deleted: true });
+      this.logger.info(`Deleted entity ${id}`);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  // ===========================================================================
+  // Public Method Definition
+  // ===========================================================================
+  /**
+   * Define a public method that will be exposed via Socket.io.
+   *
+   * @typeParam K - Method name from the service methods map
+   */
+  defineMethod(name, access, handler, options) {
+    const definition = {
+      name,
+      access,
+      handler,
+      schema: options?.schema,
+      resolveEntryId: options?.resolveEntryId
+    };
+    this.publicMethods.set(
+      name,
+      definition
+    );
+    return definition;
+  }
+  /**
+   * Get all public methods for registry discovery.
+   */
+  getPublicMethods() {
+    return Array.from(this.publicMethods.values());
+  }
+  // ===========================================================================
+  // Admin Methods (Scaffolding)
+  // ===========================================================================
+  /**
+   * Install standard admin CRUD methods.
+   * Call this in derived class constructor to expose admin endpoints.
+   */
+  installAdminMethods(_options) {
+    this.logger.debug("Admin methods installation placeholder");
+  }
+  // ===========================================================================
+  // Utility Methods
+  // ===========================================================================
+  /**
+   * Fields that should never be exposed or editable via admin methods.
+   */
+  getDefaultDeniedFields() {
+    return ["id", "createdAt", "updatedAt", "acl", "serviceAccess"];
+  }
+};
+
+// src/server/ServiceRegistry.ts
+var ServiceRegistry = class {
+  io;
+  services = /* @__PURE__ */ new Map();
+  logger;
+  constructor(io, options) {
+    this.io = io;
+    this.logger = options?.logger?.child({ service: "ServiceRegistry" }) ?? consoleLogger.child({ service: "ServiceRegistry" });
+  }
+  /**
+   * Register a service and auto-discover its public methods.
+   */
+  registerService(serviceName, service) {
+    this.services.set(serviceName, service);
+    this.logger.info(`Registered service: ${serviceName}`);
+    this.discoverServiceMethods(serviceName, service);
+  }
+  /**
+   * Discover and register all public methods from a service.
+   */
+  discoverServiceMethods(serviceName, service) {
+    const methods = service.getPublicMethods();
+    for (const method of methods) {
+      const eventName = `${serviceName}:${method.name}`;
+      this.logger.info(`Registering socket event: ${eventName}`);
+      this.io.on("connection", (socket) => {
+        this.registerMethodListener(
+          socket,
+          eventName,
+          method,
+          service
+        );
+      });
+    }
+    this.io.on("connection", (socket) => {
+      this.registerSubscriptionListener(
+        socket,
+        `${serviceName}:subscribe`,
+        service
+      );
+      this.registerUnsubscriptionListener(
+        socket,
+        `${serviceName}:unsubscribe`,
+        service
+      );
+    });
+  }
+  /**
+   * Register a method as a socket event listener.
+   */
+  registerMethodListener(socket, eventName, method, service) {
+    socket.on(
+      eventName,
+      async (payload, callback) => {
+        const startedAt = Date.now();
+        const [serviceName, methodName] = eventName.split(":");
+        const userIdShort = socket.userId?.slice(0, 8) ?? "anon";
+        try {
+          if (!socket.userId && method.access !== "Public") {
+            const errorResponse = {
+              success: false,
+              error: "Authentication required",
+              code: 401
+            };
+            callback?.(errorResponse);
+            return;
+          }
+          let validatedPayload = payload;
+          if (method.schema) {
+            const result2 = method.schema.safeParse(payload);
+            if (!result2.success) {
+              const errorResponse = {
+                success: false,
+                error: `Validation error: ${result2.error.message}`,
+                code: 400
+              };
+              callback?.(errorResponse);
+              return;
+            }
+            validatedPayload = result2.data;
+          }
+          let entryId;
+          if (method.resolveEntryId) {
+            entryId = method.resolveEntryId(validatedPayload) ?? void 0;
+          } else if (validatedPayload && typeof validatedPayload === "object" && "id" in validatedPayload) {
+            const idValue = validatedPayload.id;
+            if (typeof idValue === "string") {
+              entryId = idValue;
+            }
+          }
+          await service.ensureAccessForMethod(method.access, socket, entryId);
+          this.logger.info(
+            `User ${userIdShort} ${serviceName}.${methodName} -> start`,
+            {
+              category: "request_processing",
+              serviceName,
+              methodName,
+              userId: socket.userId,
+              socketId: socket.id
+            }
+          );
+          const result = await method.handler(validatedPayload, {
+            userId: socket.userId,
+            socketId: socket.id,
+            serviceAccess: socket.serviceAccess ?? {}
+          });
+          const durationMs = Date.now() - startedAt;
+          this.logger.info(
+            `User ${userIdShort} ${serviceName}.${methodName} -> success`,
+            {
+              category: "request_processing",
+              outcome: "success",
+              durationMs,
+              serviceName,
+              methodName,
+              userId: socket.userId
+            }
+          );
+          const successResponse = {
+            success: true,
+            data: result
+          };
+          callback?.(successResponse);
+        } catch (error) {
+          const durationMs = Date.now() - startedAt;
+          this.logger.error(
+            `User ${userIdShort} ${serviceName}.${methodName} -> fail`,
+            {
+              category: "request_processing",
+              outcome: "fail",
+              durationMs,
+              error: error instanceof Error ? error.message : "Unknown error"
+            }
+          );
+          const errorResponse = {
+            success: false,
+            error: error instanceof Error ? error.message : "Internal error",
+            code: 500
+          };
+          callback?.(errorResponse);
+        }
+      }
+    );
+  }
+  /**
+   * Register subscription listener for a service.
+   */
+  registerSubscriptionListener(socket, eventName, service) {
+    socket.on(
+      eventName,
+      async (payload, callback) => {
+        try {
+          if (!socket.userId) {
+            callback?.({
+              success: false,
+              error: "Authentication required",
+              code: 401
+            });
+            return;
+          }
+          const data = await service.subscribe(
+            payload.entryId,
+            socket,
+            payload.requiredLevel ?? "Read"
+          );
+          if (data === null) {
+            callback?.({
+              success: false,
+              error: "Access denied or entry not found",
+              code: 403
+            });
+            return;
+          }
+          callback?.({ success: true, data });
+        } catch (error) {
+          this.logger.error(`Error in subscription ${eventName}:`, {
+            error: error instanceof Error ? error.message : "Unknown error"
+          });
+          callback?.({
+            success: false,
+            error: error instanceof Error ? error.message : "Subscription failed"
+          });
+        }
+      }
+    );
+  }
+  /**
+   * Register unsubscription listener for a service.
+   */
+  registerUnsubscriptionListener(socket, eventName, service) {
+    socket.on(
+      eventName,
+      (payload, callback) => {
+        try {
+          service.unsubscribe(payload.entryId, socket);
+          callback?.({
+            success: true,
+            data: { unsubscribed: true, entryId: payload.entryId }
+          });
+        } catch (error) {
+          this.logger.error(`Error in unsubscription ${eventName}:`, {
+            error: error instanceof Error ? error.message : "Unknown error"
+          });
+          callback?.({
+            success: false,
+            error: error instanceof Error ? error.message : "Unsubscription failed"
+          });
+        }
+      }
+    );
+  }
+  /**
+   * Get list of registered service names.
+   */
+  getServices() {
+    return Array.from(this.services.keys());
+  }
+  /**
+   * Get all service instances for lifecycle management.
+   */
+  getServiceInstances() {
+    return Array.from(this.services.values());
+  }
+};
+function createQuickdrawServer(options) {
+  const logger = options.logger ?? consoleLogger;
+  const serverLogger = logger.child({ service: "QuickdrawServer" });
+  const app = express();
+  app.use(express.json());
+  app.get("/health", (_req, res) => {
+    res.json({ status: "ok", timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+  });
+  const httpServer = createServer(app);
+  const io = new Server(httpServer, {
+    cors: {
+      origin: options.cors?.origin ?? "*",
+      methods: options.cors?.methods ?? ["GET", "POST"],
+      credentials: options.cors?.credentials ?? true
+    }
+  });
+  const registry = new ServiceRegistry(io, { logger });
+  io.use(async (socket, next) => {
+    const quickdrawSocket = socket;
+    try {
+      if (options.auth?.authenticate) {
+        const auth = socket.handshake.auth;
+        const userId = await options.auth.authenticate(quickdrawSocket, auth);
+        quickdrawSocket.userId = userId;
+        quickdrawSocket.serviceAccess = {};
+      }
+      next();
+    } catch (error) {
+      serverLogger.error("Authentication failed", {
+        error: error instanceof Error ? error.message : "Unknown error",
+        socketId: socket.id
+      });
+      next(new Error("Authentication failed"));
+    }
+  });
+  for (const [serviceName, service] of Object.entries(options.services)) {
+    registry.registerService(serviceName, service);
+  }
+  io.on("connection", (socket) => {
+    const quickdrawSocket = socket;
+    serverLogger.info("Socket connected", {
+      socketId: quickdrawSocket.id,
+      userId: quickdrawSocket.userId
+    });
+    quickdrawSocket.on("disconnect", () => {
+      serverLogger.info("Socket disconnected", {
+        socketId: quickdrawSocket.id,
+        userId: quickdrawSocket.userId
+      });
+      for (const service of registry.getServiceInstances()) {
+        try {
+          service.unsubscribeSocket(quickdrawSocket);
+        } catch {
+        }
+      }
+    });
+  });
+  httpServer.listen(options.port, "0.0.0.0", () => {
+    serverLogger.info(`Server listening on port ${options.port}`);
+    serverLogger.info(
+      `Registered services: ${registry.getServices().join(", ")}`
+    );
+  });
+  return { io, httpServer, registry };
+}
+var DEFAULT_EXPIRATION = "7d";
+async function createJWT(payload, secret, expiresIn = DEFAULT_EXPIRATION) {
+  const secretKey = new TextEncoder().encode(secret);
+  const jwt = await new jose.SignJWT(payload).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setExpirationTime(expiresIn).sign(secretKey);
+  return jwt;
+}
+async function verifyJWT(token, secret) {
+  try {
+    const secretKey = new TextEncoder().encode(secret);
+    const { payload } = await jose.jwtVerify(token, secretKey);
+    return {
+      userId: payload.userId,
+      email: payload.email,
+      exp: payload.exp,
+      iat: payload.iat
+    };
+  } catch {
+    return null;
+  }
+}
+
+// src/server/auth/oauth.ts
+function createOAuthURL(provider, config, state) {
+  const params = new URLSearchParams({
+    client_id: config.clientId,
+    redirect_uri: config.redirectUri,
+    response_type: "code",
+    scope: provider.scopes.join(" ")
+  });
+  if (state) {
+    params.set("state", state);
+  }
+  return `${provider.authorizationUrl}?${params.toString()}`;
+}
+async function exchangeOAuthCode(provider, config, code) {
+  const tokenResponse = await fetch(provider.tokenUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json"
+    },
+    body: new URLSearchParams({
+      client_id: config.clientId,
+      client_secret: config.clientSecret,
+      code,
+      grant_type: "authorization_code",
+      redirect_uri: config.redirectUri
+    })
+  });
+  if (!tokenResponse.ok) {
+    const error = await tokenResponse.text();
+    throw new Error(`Token exchange failed: ${error}`);
+  }
+  const tokens = await tokenResponse.json();
+  const userResponse = await fetch(provider.userInfoUrl, {
+    headers: {
+      Authorization: `Bearer ${tokens.access_token}`,
+      Accept: "application/json"
+    }
+  });
+  if (!userResponse.ok) {
+    const error = await userResponse.text();
+    throw new Error(`User info fetch failed: ${error}`);
+  }
+  const userData = await userResponse.json();
+  const user = provider.parseUserInfo(userData);
+  return { tokens, user };
+}
+
+// src/server/auth/discord.ts
+var discordProvider = {
+  name: "discord",
+  authorizationUrl: "https://discord.com/api/oauth2/authorize",
+  tokenUrl: "https://discord.com/api/oauth2/token",
+  userInfoUrl: "https://discord.com/api/users/@me",
+  scopes: ["identify", "email"],
+  parseUserInfo: (data) => {
+    const d = data;
+    return {
+      id: String(d.id),
+      username: String(d.username),
+      discriminator: String(d.discriminator ?? "0"),
+      email: d.email ? String(d.email) : null,
+      avatar: d.avatar ? String(d.avatar) : null,
+      verified: Boolean(d.verified)
+    };
+  }
+};
+
+// src/server/auth/google.ts
+var googleProvider = {
+  name: "google",
+  authorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+  tokenUrl: "https://oauth2.googleapis.com/token",
+  userInfoUrl: "https://www.googleapis.com/oauth2/v2/userinfo",
+  scopes: ["openid", "email", "profile"],
+  parseUserInfo: (data) => {
+    const d = data;
+    return {
+      id: String(d.id),
+      email: String(d.email),
+      name: String(d.name),
+      picture: d.picture ? String(d.picture) : null,
+      verified_email: Boolean(d.verified_email)
+    };
+  }
+};
+
+export { BaseService, ServiceRegistry, createJWT, createOAuthURL, createQuickdrawServer, discordProvider, exchangeOAuthCode, googleProvider, verifyJWT };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map