@estopia/shared 1.0.0

package/.github/workflows/tests.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Use Node.js
+      uses: actions/setup-node@v3
+      with:
+        node-version: '18'
+
+    - name: Install package dependencies
+      run: |
+        npm install
+      shell: bash
+
+    - name: Run tests
+      run: |
+        npm test
+    

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@estopia/shared",
+  "version": "1.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.d.ts",
+  "description": "",
+  "author": "",
+  "license": "ISC",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "db:types": "kysely-codegen --out-file ./src/database/dataTypes.ts"
+  },
+  "dependencies": {
+    "amqplib": "^0.10.9",
+    "axios": "^1.12.2",
+    "cassandra-driver": "^4.8.0",
+    "express": "^5.1.0",
+    "jsonwebtoken": "^9.0.2",
+    "kysely": "^0.28.8",
+    "pg": "^8.16.3",
+    "pino": "^10.0.0",
+    "vitest": "^3.2.4"
+  },
+  "devDependencies": {
+    "@types/amqplib": "^0.10.7",
+    "@types/express": "^5.0.3",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^24.7.1",
+    "@types/pg": "^8.15.5",
+    "kysely-codegen": "^0.19.0",
+    "pino-pretty": "^13.1.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  }
+}

package/scripts/migrations/1670000000000-initial.js

@@ -0,0 +1,107 @@
+/* eslint-disable no-unused-vars */
+'use strict';
+
+exports.up = (pgm) => {
+  // 1. Create Custom Enum Types
+  pgm.createType('verification_type', ['email', 'phone', 'password_reset']);
+  pgm.createType('factor_auth_type', ['whatsapp', 'email']);
+  pgm.createType('app_type', ['medIOS', 'medAndroid', 'web']);
+
+  // 2. Create Core User Table
+  pgm.createTable('users', {
+    id: 'id',
+    username: { type: 'varchar(50)', notNull: true, unique: true },
+    password_hash: { type: 'text', notNull: true },
+    disabled: { type: 'boolean', default: false },
+    is_admin: { type: 'boolean', default: false },
+    icon_url: { type: 'text' },
+    created_at: { type: 'timestamptz', notNull: true, default: pgm.func('now()') },
+  });
+
+  // 3. Create Related Authentication & Settings Tables
+  pgm.createTable('notification_settings', {
+    id: 'id',
+    user_id: { type: 'integer', notNull: true, references: 'users(id)', onDelete: 'CASCADE', unique: true },
+    direct_message: { type: 'boolean', default: true },
+    group_dm_message: { type: 'boolean', default: true },
+    group_dm_mention: { type: 'boolean', default: true },
+    added_to_dm: { type: 'boolean', default: true },
+    server_everyone_mention: { type: 'boolean', default: true },
+    server_mention: { type: 'boolean', default: true },
+    server_reply: { type: 'boolean', default: true },
+    direct_call: { type: 'boolean', default: true },
+  });
+
+  pgm.createTable('user_verifications', {
+    id: 'id',
+    user_id: { type: 'integer', notNull: true, references: 'users(id)', onDelete: 'CASCADE' },
+    ownership_code: { type: 'text', notNull: true },
+    is_verified: { type: 'boolean', default: false },
+    type: { type: 'verification_type', notNull: true },
+    data: { type: 'text' },
+    expiry_at: { type: 'timestamptz', notNull: true },
+    created_at: { type: 'timestamptz', notNull: true, default: pgm.func('now()') },
+  });
+
+  pgm.createTable('passkeys', {
+    id: 'id',
+    user_id: { type: 'integer', notNull: true, references: 'users(id)', onDelete: 'CASCADE' },
+    key_id: { type: 'bytea', notNull: true, unique: true },
+    public_key: { type: 'bytea', notNull: true },
+    counter: { type: 'bigint', notNull: true },
+    transports: { type: 'varchar(50)[]' },
+    name: { type: 'text' },
+  });
+
+  pgm.createTable('auth_apps', {
+    id: 'id',
+    user_id: { type: 'integer', notNull: true, references: 'users(id)', onDelete: 'CASCADE' },
+    secret: { type: 'text', notNull: true },
+    name: { type: 'varchar(100)', notNull: true },
+  });
+  
+  pgm.createTable('factor_authentication', {
+    id: 'id',
+    user_id: { type: 'integer', notNull: true, references: 'users(id)', onDelete: 'CASCADE' },
+    type: { type: 'factor_auth_type', notNull: true },
+    data: { type: 'text', notNull: true },
+    code: { type: 'text', notNull: true },
+    is_verified: { type: 'boolean', default: false },
+    expiry_at: { type: 'timestamptz', notNull: true },
+  });
+
+  pgm.createTable('tokens', {
+    id: 'id',
+    user_id: { type: 'integer', notNull: true, references: 'users(id)', onDelete: 'CASCADE' },
+    refresh_token: { type: 'uuid', notNull: true, unique: true },
+    fcm_token: { type: 'text' },
+    app: { type: 'app_type', notNull: false },
+    expiry_at: { type: 'timestamptz', notNull: true },
+    created_at: { type: 'timestamptz', notNull: true, default: pgm.func('now()') },
+  });
+
+  pgm.createTable('secure_tokens', {
+    id: 'id',
+    user_id: { type: 'integer', notNull: true, references: 'users(id)', onDelete: 'CASCADE' },
+    token_uuid: { type: 'uuid', notNull: true, unique: true },
+    expiry_at: { type: 'timestamptz', notNull: true },
+    created_at: { type: 'timestamptz', notNull: true, default: pgm.func('now()') },
+  });
+};
+
+exports.down = (pgm) => {
+  // Drop tables in reverse order of creation due to dependencies
+  pgm.dropTable('secure_tokens');
+  pgm.dropTable('tokens');
+  pgm.dropTable('factor_authentication');
+  pgm.dropTable('auth_apps');
+  pgm.dropTable('passkeys');
+  pgm.dropTable('user_verifications');
+  pgm.dropTable('notification_settings');
+  pgm.dropTable('users');
+
+  // Drop types
+  pgm.dropType('app_type');
+  pgm.dropType('factor_auth_type');
+  pgm.dropType('verification_type');
+};

package/scripts/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@estopia/scripts",
+  "version": "1.0.0",
+  "main": "index.ts",
+  "types": "src/index.d.ts",
+  "description": "",
+  "author": "",
+  "license": "ISC",
+  "scripts": {
+    "migrate:up": "dotenv -e .env -- node-pg-migrate up -u \"$DATABASE_URL\"",
+    "migrate:down": "dotenv -e .env -- node-pg-migrate down -u \"$DATABASE_URL\""
+  },
+  "dependencies": {
+    "dotenv": "^17.2.3",
+    "node-pg-migrate": "^8.0.3"
+  },
+  "devDependencies": {
+    "dotenv-cli": "^10.0.0"
+  }
+}

package/src/broker/eventTypes.ts

@@ -0,0 +1,23 @@
+export interface UserRegisteredEvent {
+  userId: string;
+  email: string;
+  verificationCode: string;
+}
+
+export interface PasswordResetEvent {
+  userId: string;
+  email: string;
+  resetToken: string;
+}
+
+export type EventPayloads = UserRegisteredEvent | PasswordResetEvent;
+
+export interface EventMap {
+  USER_REGISTERED: UserRegisteredEvent;
+  PASSWORD_RESET: PasswordResetEvent;
+}
+
+export const EVENTS = {
+  USER_REGISTERED: 'user.registered',
+  PASSWORD_RESET: 'password.reset',
+} as const;

package/src/broker/publisher.ts

@@ -0,0 +1,82 @@
+import * as amqplib from 'amqplib';
+import { EventPayloads, EventMap, EVENTS } from './eventTypes';
+
+export class EventPublisher {
+  private connection?: any;
+  private channel?: any;
+  private exchange = 'estopia.events';
+
+  constructor(private url: string) {}
+
+  async connect() {
+    if (this.connection && this.channel) return; // already connected
+    this.connection = await amqplib.connect(this.url);
+    this.channel = await this.connection.createChannel();
+    await this.channel.assertExchange(this.exchange, 'topic', { durable: true });
+  }
+
+  /**
+   * Publish an event. The payload type is keyed by the same keys used in your EventPayloads map.
+   * Ensures the routing key exists in EVENTS and that the publisher is connected.
+   */
+  async publish<K extends keyof EventMap>(eventName: K, payload: EventMap[K]) {
+    // Auto-connect if needed
+    if (!this.channel) {
+      await this.connect();
+    }
+
+    const routingKey = EVENTS[eventName as keyof typeof EVENTS];
+    if (!routingKey || typeof routingKey !== 'string') {
+      throw new Error(`No routing key configured for event ${String(eventName)}`);
+    }
+
+    let body: Buffer;
+    try {
+      body = Buffer.from(JSON.stringify(payload));
+    } catch (err) {
+      throw new Error('Failed to serialize payload for publish');
+    }
+
+    // Basic retry with exponential backoff
+    const maxRetries = 3;
+    const baseBackoffMs = 200;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        // channel.publish is synchronous; wrap in try/catch in case of closed channel
+        this.channel.publish(this.exchange, routingKey, body, { persistent: true });
+        return;
+      } catch (err) {
+        // if last attempt, rethrow
+        if (attempt === maxRetries) throw err;
+        // try reconnect + backoff
+        try {
+          // reset connection and attempt reconnect
+          await this.close();
+        } catch (_) {}
+        try {
+          await this.connect();
+        } catch (_) {
+          // failed to reconnect, will backoff and retry loop
+        }
+        const backoff = baseBackoffMs * Math.pow(2, attempt);
+        await new Promise((res) => setTimeout(res, backoff));
+      }
+    }
+  }
+
+  async close() {
+    try {
+      if (this.channel) await this.channel.close();
+    } catch (e) {
+      // ignore
+    }
+    try {
+      if (this.connection) await this.connection.close();
+    } catch (e) {
+      // ignore
+    }
+    this.channel = undefined;
+    this.connection = undefined;
+  }
+}

package/src/broker/subscriber.ts

@@ -0,0 +1,51 @@
+const amqplib = require('amqplib');
+import { EVENTS, EventMap } from './eventTypes';
+
+type EventHandler<T> = (payload: T) => Promise<void> | void;
+
+export class EventSubscriber {
+  private connection?: any;
+  private channel?: any;
+  private exchange = 'estopia.events';
+
+  constructor(private url: string) {}
+
+  async connect() {
+    if (this.connection && this.channel) return;
+    this.connection = await amqplib.connect(this.url);
+    this.channel = await this.connection.createChannel();
+    await this.channel.assertExchange(this.exchange, 'topic', { durable: true });
+  }
+
+  async subscribe<K extends keyof EventMap>(eventName: K, handler: EventHandler<EventMap[K]>) {
+    if (!this.channel) throw new Error('Subscriber not connected');
+
+    const q = await this.channel.assertQueue('', { exclusive: true });
+  const routing = EVENTS[eventName as keyof typeof EVENTS];
+  await this.channel.bindQueue(q.queue, this.exchange, routing);
+
+    await this.channel.consume(q.queue, (msg: any | null) => {
+      if (msg) {
+        let payload: EventMap[K];
+        try {
+          payload = JSON.parse(msg.content.toString());
+        } catch (err) {
+          // malformed message -> nack and requeue false
+          this.channel?.nack(msg, false, false);
+          return;
+        }
+
+        Promise.resolve(handler(payload))
+          .then(() => this.channel?.ack(msg))
+          .catch(() => this.channel?.nack(msg, false, true));
+      }
+    });
+  }
+
+  async close() {
+    try { if (this.channel) await this.channel.close(); } catch (e) { }
+    try { if (this.connection) await this.connection.close(); } catch (e) { }
+    this.channel = undefined;
+    this.connection = undefined;
+  }
+}

package/src/database/cockroach.ts

@@ -0,0 +1,27 @@
+import { Pool } from 'pg';
+import { CockroachConfig } from './types';
+import { Kysely, PostgresDialect } from 'kysely';
+import { DB } from './dataTypes';
+
+/**
+ * Creates and tests a new connection pool for a CockroachDB cluster.
+ * * @param config - The connection configuration for CockroachDB.
+ * @returns A promise that resolves to a connected Pool instance.
+ * @throws Will throw an error if the connection fails.
+ */
+export async function createCockroachDBConnection(config: CockroachConfig): Promise<Kysely<DB>> {
+  try {
+
+    const db = new Kysely<DB>({
+      dialect: new PostgresDialect({
+        pool: new Pool(config)
+      })
+    });
+
+    console.log('Successfully connected to CockroachDB.');
+    return db;
+  } catch (error) {
+    console.error('Failed to connect to CockroachDB:', error);
+    throw error;
+  }
+}

package/src/database/dataTypes.ts

@@ -0,0 +1,117 @@
+/**
+ * This file was generated by kysely-codegen.
+ * Please do not edit it manually.
+ */
+
+import type { ColumnType } from "kysely";
+
+export type AppType = "medAndroid" | "medIOS" | "web";
+
+export type FactorAuthType = "email" | "whatsapp";
+
+export type Generated<T> = T extends ColumnType<infer S, infer I, infer U>
+  ? ColumnType<S, I | undefined, U>
+  : ColumnType<T, T | undefined, T>;
+
+export type Int8 = ColumnType<string, bigint | number | string, bigint | number | string>;
+
+export type Timestamp = ColumnType<Date, Date | string, Date | string>;
+
+export type VerificationType = "email" | "password_reset" | "phone";
+
+export interface AuthApps {
+  id: Generated<Int8>;
+  name: string;
+  secret: string;
+  user_id: Int8;
+}
+
+export interface FactorAuthentication {
+  code: string;
+  data: string;
+  expiry_at: Timestamp;
+  id: Generated<Int8>;
+  is_verified: Generated<boolean | null>;
+  type: FactorAuthType;
+  user_id: Int8;
+}
+
+export interface NotificationSettings {
+  added_to_dm: Generated<boolean | null>;
+  direct_call: Generated<boolean | null>;
+  direct_message: Generated<boolean | null>;
+  group_dm_mention: Generated<boolean | null>;
+  group_dm_message: Generated<boolean | null>;
+  id: Generated<Int8>;
+  server_everyone_mention: Generated<boolean | null>;
+  server_mention: Generated<boolean | null>;
+  server_reply: Generated<boolean | null>;
+  user_id: Int8;
+}
+
+export interface Passkeys {
+  counter: Int8;
+  id: Generated<Int8>;
+  key_id: Buffer;
+  name: string | null;
+  public_key: Buffer;
+  transports: string[] | null;
+  user_id: Int8;
+}
+
+export interface Pgmigrations {
+  id: Generated<Int8>;
+  name: string;
+  run_on: Timestamp;
+}
+
+export interface SecureTokens {
+  created_at: Generated<Timestamp>;
+  expiry_at: Timestamp;
+  id: Generated<Int8>;
+  token_uuid: string;
+  user_id: Int8;
+}
+
+export interface Tokens {
+  app: AppType | null;
+  created_at: Generated<Timestamp>;
+  expiry_at: Timestamp;
+  fcm_token: string | null;
+  id: Generated<Int8>;
+  refresh_token: string;
+  user_id: Int8;
+}
+
+export interface Users {
+  created_at: Generated<Timestamp>;
+  disabled: Generated<boolean | null>;
+  icon_url: string | null;
+  id: Generated<Int8>;
+  is_admin: Generated<boolean | null>;
+  password_hash: string;
+  username: string;
+}
+
+export interface UserVerifications {
+  created_at: Generated<Timestamp>;
+  data: string | null;
+  expiry_at: Timestamp;
+  id: Generated<Int8>;
+  is_verified: Generated<boolean | null>;
+  ownership_code: string;
+  type: VerificationType;
+  user_id: Int8;
+}
+
+export interface DB {
+  auth_apps: AuthApps;
+  factor_authentication: FactorAuthentication;
+  notification_settings: NotificationSettings;
+  passkeys: Passkeys;
+  pgmigrations: Pgmigrations;
+  secure_tokens: SecureTokens;
+  tokens: Tokens;
+  user_verifications: UserVerifications;
+  users: Users;
+}

package/src/database/types.ts

@@ -0,0 +1,9 @@
+import { PoolConfig as CockroachOptions } from 'pg';
+
+/**
+ * Configuration for connecting to a CockroachDB cluster.
+ * This extends the 'pg' PoolConfig type for full compatibility.
+ */
+export interface CockroachConfig extends CockroachOptions {
+  // You can add custom properties here if needed
+}

package/src/helpers/middlware/auth.ts

@@ -0,0 +1,55 @@
+import { EstopiaRequest } from '../../types/request';
+import { validateJWTToken } from '../validateJWTToken';
+
+/**
+ * Middleware to require authentication.
+ * - Supports Authorization: Bearer <token> header (case-insensitive)
+ * - Falls back to cookies.auth_token
+ * - On success: sets req.auth = { ...payload, token } and calls next()
+ * - On failure: responds with 401 and an appropriate error message
+ */
+export function requireAuth(req: EstopiaRequest, res: any, next: any) {
+  // Get Authorization header (many frameworks provide case-insensitive header lookup)
+  const authHeader = typeof req.header === 'function' ? req.header('Authorization') : undefined;
+
+  // Extract token from "Bearer <token>" or use header value directly
+  let token: string | undefined;
+  if (typeof authHeader === 'string' && authHeader.trim() !== '') {
+    const bearerMatch = authHeader.match(/^\s*Bearer\s+(.+)\s*$/i);
+    token = bearerMatch ? bearerMatch[1] : authHeader.trim();
+  }
+
+  // Fallback to cookie
+  if (!token && req && req.cookies && typeof req.cookies.auth_token === 'string') {
+    token = req.cookies.auth_token;
+  }
+
+  if (!token) {
+    return res.status(401).json({ error: 'Missing authorization token' });
+  }
+
+  try {
+    const payload = validateJWTToken(token);
+    if (!payload) {
+      return res.status(401).json({ error: 'Invalid token' });
+    }
+
+    // Attach auth info to request
+    req.auth = { ...payload, token };
+    return next();
+  } catch (err: any) {
+    // Log warning if logger available, otherwise fallback to console
+    try {
+      if (req && req.logger && typeof req.logger.warn === 'function') {
+        req.logger.warn('Auth verification failed', err);
+      } else {
+        // Keep message concise for logs
+        // eslint-disable-next-line no-console
+        console.warn('Auth verification failed', err);
+      }
+    } catch {
+      // swallow logging errors
+    }
+    return res.status(401).json({ error: 'Invalid authorization' });
+  }
+}

package/src/helpers/middlware/secure.ts

@@ -0,0 +1,48 @@
+import { Response } from 'express';
+import { EstopiaRequest } from '../../types/request';
+import type { Kysely } from 'kysely';
+import type { DB } from '../../database/dataTypes';
+
+/**
+ * Middleware to require authentication.
+ * - Supports Authorization: Bearer <token> header (case-insensitive)
+ * - Falls back to cookies.auth_token
+ * - On success: sets req.auth = { ...payload, token } and calls next()
+ * - On failure: responds with 401 and an appropriate error message
+ */
+export async function requireSecure(req: EstopiaRequest, res: Response, next: any) {
+  // This middleware only validates the Secure-Token cookie against the DB.
+  // It does NOT require a valid JWT — per request: "it doesn't matter if the JWT token exists".
+
+  // Read secure token from cookie
+  const secureToken = req && req.cookies['Secure-Token'];
+  if (!secureToken) {
+    return res.status(403).json({ error: 'Missing secure token' });
+  }
+
+  // Expect a Kysely DB instance to be available on app.locals.db
+  const cockroachPool = req.cockroachPool;
+
+  try {
+    const db = cockroachPool as Kysely<DB>;
+    // Query secure_tokens table by token_uuid
+    const row = await db.selectFrom('secure_tokens').selectAll().where('token_uuid', '=', secureToken).executeTakeFirst();
+
+    if (!row) {
+      return res.status(403).json({ error: 'Secure token not found' });
+    }
+
+    // expiry_at may be a Date or string depending on driver; normalize
+    const expiry = row.expiry_at ? new Date(row.expiry_at as any) : null;
+    if (!expiry || expiry.getTime() <= Date.now()) {
+      return res.status(403).json({ error: 'Secure token expired' });
+    }
+
+    // Attach minimal auth context to request (no JWT required)
+    req.auth = { secureToken, userId: row.user_id.toString() };
+    return next();
+  } catch (err: any) {
+    console.error('Failed to validate secure token', err?.message || err);
+    return res.status(500).json({ error: 'Failed to validate secure token' });
+  }
+}

package/src/helpers/validateJWTToken.ts

@@ -0,0 +1,38 @@
+import jwt from 'jsonwebtoken';
+
+export interface DecodedJWT {
+  userId: string;
+  jti?: string;
+  iat?: number;
+  exp?: number;
+}
+
+// Keep verification options minimal to allow tokens signed without an explicit issuer in tests.
+const jwtVerifyOptions = {};
+
+/**
+ * Verify a JWT and return the decoded payload. Throws on invalid/expired token.
+ */
+export function validateJWTToken(token: string): DecodedJWT {
+  const secret = process.env.JWT_SECRET;
+  if (!secret) throw new Error('JWT secret not configured');
+
+  const payload = jwt.verify(token, secret, jwtVerifyOptions) as any;
+  const userId = payload?.sub ?? payload?.userId ?? payload?.id ?? null;
+  if (!userId) throw new Error('token missing subject');
+
+  return { userId, jti: payload.jti ?? payload.jti ?? undefined, iat: payload.iat, exp: payload.exp } as DecodedJWT;
+}
+
+/**
+ * Try to verify a token and return the decoded payload, or null if invalid.
+ */
+export function tryValidateJWTToken(token: string): DecodedJWT | null {
+  try {
+    return validateJWTToken(token);
+  } catch (e) {
+    return null;
+  }
+}
+
+export default validateJWTToken;

package/src/index.ts

@@ -0,0 +1,24 @@
+export { createLogger } from './logging/logger';
+export type { LoggerOptions, LogMeta } from './logging/logger';
+
+export { createCockroachDBConnection } from './database/cockroach';
+
+// Export the configuration types so consuming services can use them
+export type { CockroachConfig } from './database/types';
+
+// Export the database clients for type hinting in other services
+export { Pool as CockroachDBClient } from 'pg';
+export { Client as ScyllaDBClient } from 'cassandra-driver';
+
+export { EventPublisher } from './broker/publisher';
+export { EventSubscriber } from './broker/subscriber';
+export type { EventPayloads } from './broker/eventTypes';
+
+export type { UserDto } from './types/user';
+export { validateJWTToken, tryValidateJWTToken } from './helpers/validateJWTToken';
+
+export type { DB } from './database/dataTypes';
+
+export type { EstopiaRequest } from './types/request';
+export { requireAuth } from './helpers/middlware/auth';
+export { requireSecure } from './helpers/middlware/secure';

package/src/logging/logger.ts

@@ -0,0 +1,103 @@
+import pino from 'pino';
+import axios from 'axios';
+import { Logger } from '../types/request';
+
+interface LoggerOptions {
+  serviceName: string;
+  logServiceUrl?: string;
+  environment?: "development" | "production";
+  sendLogs?: boolean; // default true
+}
+
+interface LogMeta {
+  [key: string]: any;
+}
+
+export function createLogger(options: LoggerOptions): Logger {
+  const {
+    serviceName,
+    logServiceUrl = process.env.LOG_SERVICE_URL || "http://localhost:4000/logs",
+    environment = process.env.NODE_ENV as "development" | "production" || "development",
+    sendLogs = true,
+  } = options;
+
+  let requestId: string | null = null;
+  let requestURL: string | null = null;
+  let requestMethod: string | null = null;
+  let requestUserId: string | null = null;
+  let requesterType: 'user' | 'internal' | null = null;
+
+  const logger =
+    environment === "development"
+      ? pino({ name: serviceName, level: 'debug' } as any)
+      : pino({
+          name: serviceName,
+          level: 'info',
+        });
+
+  const sendLog = async (level: string, message: string, meta: LogMeta = {}) => {
+    if (!sendLogs) return;
+    try {
+      if (requestId) {
+        meta.requestId = requestId;
+      }
+      if (requestURL) {
+        meta.requestURL = requestURL;
+      }
+      if (requestMethod) {
+        meta.requestMethod = requestMethod;
+      }
+      if (requestUserId) {
+        meta.requestUserId = requestUserId;
+      }
+      if (requesterType) {
+        meta.requesterType = requesterType;
+      }
+
+      await axios.post(
+        logServiceUrl,
+        {
+          service: serviceName,
+          level,
+          message,
+          meta,
+          timestamp: new Date().toISOString(),
+        },
+        { timeout: 2000 }
+      );
+    } catch (err) {
+      // Only warn locally, don’t crash
+      logger.warn({ err }, "Failed to send log to remote service");
+    }
+  };
+
+  const logWrapper: Logger = {
+    info: (msg: string, meta?: LogMeta) => {
+      logger.info(meta, msg);
+      sendLog("info", msg, meta);
+    },
+    error: (msg: string, meta?: LogMeta) => {
+      logger.error(meta, msg);
+      sendLog("error", msg, meta);
+    },
+    warn: (msg: string, meta?: LogMeta) => {
+      logger.warn(meta, msg);
+      sendLog("warn", msg, meta);
+    },
+    debug: (msg: string, meta?: LogMeta) => {
+      logger.debug(meta, msg);
+      sendLog("debug", msg, meta);
+    },
+    setRequest: (requesterId: string | null, url: string | null, method: string | null, userId: string | null, type: 'user' | 'internal' | null) => {
+      requestId = requesterId;
+      requestURL = url;
+      requestMethod = method;
+      requestUserId = userId;
+      requesterType = type;
+    }
+  };
+
+  return logWrapper;
+}
+
+export type { LoggerOptions, LogMeta };

package/src/types/ENUMS.ts

@@ -0,0 +1,45 @@
+// Enums
+enum UserRole {
+  Member = 'MEMBER',
+  Admin = 'ADMIN',
+}
+
+enum ReportStatus {
+  Open = 'OPEN',
+  Reviewed = 'REVIEWED',
+  Closed = 'CLOSED',
+}
+
+enum ReportEntityType {
+  User = 'USER',
+  Server = 'SERVER',
+  Channel = 'CHANNEL',
+  Message = 'MESSAGE',
+}
+
+enum TicketStatus {
+  Open = 'OPEN',
+  Assigned = 'ASSIGNED',
+  Closed = 'CLOSED',
+}
+
+enum DoseStatus {
+  Taken = 'TAKEN',
+  Skipped = 'SKIPPED',
+  Pending = 'PENDING',
+}
+
+enum messageType {
+    Channel = 'CHANNEL',
+    Direct = 'DIRECT',
+    Ticket = 'TICKET',
+}
+
+export {
+  UserRole,
+  ReportStatus,
+  ReportEntityType,
+  TicketStatus,
+  DoseStatus,
+  messageType
+};

package/src/types/directs.ts

@@ -0,0 +1,18 @@
+import type { UserRole } from "./ENUMS.js";
+
+// /directs
+export interface DirectMessageDto {
+  id: string;
+  isGroup: boolean;
+  name: string;
+  creatorId: number;
+}
+
+export interface DirectMessageMemberDto {
+  id: string;
+  userId: number;
+  role: UserRole;
+  isApproved: boolean;
+  joinedAt: Date;
+  directId: number;
+}

package/src/types/medical.ts

@@ -0,0 +1,36 @@
+import type { DoseStatus } from "./ENUMS.js";
+
+// /medical
+export interface MedicationDto {
+  id: string;
+  userId: number;
+  name: string;
+  dosage: string;
+  startDate: Date;
+  endDate?: Date;
+  notes?: string;
+  quantity?: number;
+}
+
+export interface MedicationRefillDto {
+  id: string;
+  medicationId: number;
+  amount: number;
+  date: Date;
+}
+
+export interface MedicationTimeDto {
+  id: string;
+  medicationId: number;
+  time: string; // e.g., "08:00"
+}
+
+export interface TakenDoseDto {
+  id: string;
+  userId: number;
+  medId: number;
+  scheduledTime: Date;
+  takenTime?: Date;
+  dosage: string;
+  status: DoseStatus;
+}

package/src/types/messages.ts

@@ -0,0 +1,27 @@
+import type { messageType } from "./ENUMS.js";
+
+// /messages
+export interface MessageDto {
+  id: string;
+  type: messageType;
+  directId?: number;
+  channelId?: number;
+  ticketId?: number;
+  userId: number;
+  content: string;
+  mentionEveryone: boolean;
+  replyTo?: number;
+}
+
+export interface MessageMediaDto {
+  id: string;
+  type: string; // e.g., "image/png"
+  size: number;
+  messageId: number;
+}
+
+export interface MessageMentionDto {
+  id: string;
+  userId: number;
+  messageId: number;
+}

package/src/types/request.ts

@@ -0,0 +1,23 @@
+import { Request } from 'express';
+import { Kysely } from "kysely";
+import { DB } from "../database/dataTypes";
+import { LogMeta } from '../logging/logger';
+
+export interface EstopiaRequest extends Request {
+    auth?: {
+        userId: string;
+        token?: string;
+        secureToken?: string;
+    },
+    logger: Logger;
+    cockroachPool?: Kysely<DB>;
+    publisher?: any;
+}
+
+export interface Logger {
+  info(msg: string, meta?: LogMeta): void;
+  error(msg: string, meta?: LogMeta): void;
+  warn(msg: string, meta?: LogMeta): void;
+  debug(msg: string, meta?: LogMeta): void;
+  setRequest(requesterId: string | null, url: string | null, method: string | null, userId: string | null, type: 'user' | 'internal' | null): void;
+}

package/src/types/servers.ts

@@ -0,0 +1,36 @@
+import type { UserRole } from "./ENUMS.js";
+
+// /servers
+export interface ServerDto {
+  id: string;
+  ownerId: number;
+  name: string;
+  description: string;
+  isPrivate: boolean;
+  isVerified: boolean;
+  icon: string;
+}
+
+export interface ServerMemberDto {
+  id: string;
+  userId: number;
+  serverId: number;
+  role: UserRole;
+}
+
+export interface ChannelDto {
+  id: string;
+  serverId: number;
+  name: string;
+  channelType: string;
+  isStaffViewOnly: boolean;
+  isStaffTextOnly: boolean;
+}
+
+export interface ServerBanDto {
+  id: string;
+  banningId: number;
+  bannedId: number;
+  note: string;
+  serverId: number;
+}

package/src/types/servicePayloads.ts

@@ -0,0 +1,40 @@
+export interface SendPushNotificationRequest {
+  userId: string;
+  title: string;
+  body: string;
+  appType: 'medical' | 'chat';
+  // Optional data to send with the notification,
+  // e.g., { channelId: 123 }
+  data?: Record<string, any>;
+}
+
+export enum EmailTemplate {
+  AccountVerification = 'ACCOUNT_VERIFICATION',
+  PasswordReset = 'PASSWORD_RESET',
+  FactorVerifcation = 'FACTOR_VERIFICATION',
+}
+
+export interface SendEmailRequest {
+  to: string; // The recipient's email address
+  template: EmailTemplate;
+  // Dynamic data for the template, e.g., { verificationLink: '...' }
+  context: Record<string, any>;
+}
+
+export interface RequestUploadUrlRequest {
+  // e.g., 'image/png' or 'video/mp4'
+  mimeType: string;
+  // Where the file will be used
+  context: 'profile-icon' | 'chat-attachment' | 'server-icon';
+}
+
+export interface RequestUploadUrlResponse {
+  /**
+   * The secure, pre-signed URL where the client should upload the file.
+   */
+  uploadUrl: string;
+  /**
+   * The final URL to access the file after the upload is complete.
+   */
+  accessUrl: string;
+}

package/src/types/ticketsAndReporting.ts

@@ -0,0 +1,32 @@
+import type { ReportEntityType, ReportStatus, TicketStatus } from "./ENUMS.js";
+
+// /tickets & /reports
+export interface TicketDto {
+  id: string;
+  discordId?: number;
+  status: TicketStatus;
+  title: string;
+  assignedTo?: number;
+  assignedBy?: number;
+  closedBy?: number;
+}
+
+export interface TicketMessageDto {
+  id: string;
+  userId: number;
+  ticketId: number;
+  message: string;
+}
+
+export interface ReportDto {
+  id: string;
+  reporterId: number;
+  entityType: ReportEntityType;
+  entityId: number;
+  reason: string; // ENUM
+  description: string;
+  status: ReportStatus;
+  reviewedBy?: number;
+  reviewedAt?: Date;
+  reportedAt: Date;
+}

package/src/types/user.ts

@@ -0,0 +1,34 @@
+// /user
+export interface UserDto {
+  id: string;
+  username: string;
+  password: string | null;
+  icon: string;
+  isAdmin: boolean;
+}
+
+export interface PasskeyDto {
+  id: string;
+  name: string;
+  transports: number;
+  // Note: keyid, publicKey, and counter are omitted for security.
+}
+
+export interface AuthAppDto {
+  id: string;
+  name: string;
+  // Note: secret is omitted for security.
+}
+
+export interface NotificationSettingsDto {
+  id: string;
+  userId: number;
+  directMessage: boolean;
+  groupDMMessage: boolean;
+  groupDMMention: boolean;
+  addedToDM: boolean;
+  serverEveryoneMention: boolean;
+  serverMention: boolean;
+  serverReply: boolean;
+  directCall: boolean;
+}

package/tests/verifyJWTToken.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import jwt from 'jsonwebtoken';
+import { validateJWTToken, tryValidateJWTToken } from '../src/helpers/validateJWTToken';
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('verifyJWTToken helper', () => {
+  it('verifies a valid token and returns payload', () => {
+    process.env.JWT_SECRET = 'test_jwt_secret';
+    const token = jwt.sign({ sub: 'user-1' }, process.env.JWT_SECRET!, { issuer: 'estopia-auth' });
+    const decoded = validateJWTToken(token);
+    expect(decoded).toHaveProperty('userId', 'user-1');
+  });
+
+  it('tryValidateJWTToken returns null for invalid token', () => {
+    process.env.JWT_SECRET = 'test_jwt_secret';
+    const decoded = tryValidateJWTToken('not-a-token');
+    expect(decoded).toBeNull();
+  });
+
+  it('validateJWTToken throws when secret not configured', () => {
+    delete process.env.JWT_SECRET;
+    expect(() => validateJWTToken('anything')).toThrow(/JWT secret not configured/);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,48 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    // "rootDir": "./src",
+    // "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "nodenext",
+    "target": "esnext",
+    "types": [
+      "node"
+    ],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+  "verbatimModuleSyntax": false,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+  },
+});