@tumbaland/backend-core 1.17.0 → 1.19.0

package/src/tracing/index.ts

@@ -1,4 +1,15 @@
-import { context, propagation, trace, SpanKind, Tracer } from '@opentelemetry/api';
+import {
+  context,
+  propagation,
+  trace,
+  SpanKind,
+  Tracer,
+  Span,
+  Context,
+  Attributes,
+  AttributeValue,
+} from '@opentelemetry/api';
+import { Request, Response, NextFunction } from 'express';
 import { NodeTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 import { resourceFromAttributes } from '@opentelemetry/resources';
@@ -36,19 +47,19 @@ export const getTracer = (): Tracer => {
 };
 
 // Start a new span. `parent` may be a Span or a Context (e.g. from extractSpanContext).
-export const startSpan = (operationName: string, parentSpan?: any) => {
-  if (!parentSpan) {
+export const startSpan = (operationName: string, parent?: Span | Context) => {
+  if (!parent) {
     return getTracer().startSpan(operationName);
   }
+  // A Span exposes `spanContext()`; a Context does not — use that to decide
+  // whether we need to wrap the parent span into an active context first.
   const parentContext =
-    typeof parentSpan.spanContext === 'function'
-      ? trace.setSpan(context.active(), parentSpan)
-      : parentSpan;
+    'spanContext' in parent ? trace.setSpan(context.active(), parent) : parent;
   return getTracer().startSpan(operationName, undefined, parentContext);
 };
 
 // Middleware for Express to create spans for requests
-export const tracingMiddleware = (req: any, res: any, next: any) => {
+export const tracingMiddleware = (req: Request, res: Response, next: NextFunction) => {
   const parentContext = propagation.extract(context.active(), req.headers);
   const span = getTracer().startSpan(
     `${req.method} ${req.path}`,
@@ -70,28 +81,30 @@ export const tracingMiddleware = (req: any, res: any, next: any) => {
 };
 
 // Helper to create child spans
-export const createChildSpan = (operationName: string, parentSpan: any) => {
-  return startSpan(operationName, parentSpan);
+export const createChildSpan = (operationName: string, parent: Span | Context) => {
+  return startSpan(operationName, parent);
 };
 
 // Helper to log events to spans
-export const logToSpan = (span: any, event: string, data?: any) => {
+export const logToSpan = (span: Span, event: string, data?: Attributes) => {
   span.addEvent(event, data);
 };
 
 // Helper to set tags on spans
-export const setSpanTag = (span: any, key: string, value: any) => {
+export const setSpanTag = (span: Span, key: string, value: AttributeValue) => {
   span.setAttribute(key, value);
 };
 
 // Helper to inject tracing headers (W3C traceparent) for downstream calls
-export const injectHeaders = (span: any) => {
+export const injectHeaders = (span: Span) => {
   const headers: { [key: string]: string } = {};
   propagation.inject(trace.setSpan(context.active(), span), headers);
   return headers;
 };
 
 // Helper to extract span context from incoming headers; pass the result to startSpan as parent
-export const extractSpanContext = (headers: any) => {
+export const extractSpanContext = (
+  headers: Record<string, string | string[] | undefined>
+): Context => {
   return propagation.extract(context.active(), headers);
 };

package/src/types/auth.ts

@@ -1,9 +1,12 @@
+import type { Span } from '@opentelemetry/api';
+
 export interface UserPayload {
   id: string;
   email: string;
   name: string;
   picture?: string;
   groups?: string[];
+  roles?: string[];
 }
 
 /**
@@ -12,12 +15,18 @@ export interface UserPayload {
  * service's own divergent local augmentation. Individual services may still
  * carry additional request-scoped fields (e.g. auth-service's `dbUser`) —
  * those stay local since they aren't meaningful outside that service.
+ *
+ * `correlationId` is set by `correlationMiddleware`, `span` by
+ * `tracingMiddleware`; both are declared here so the observability middleware
+ * and downstream handlers can read them without a `(req as any)` cast.
  */
 declare global {
   namespace Express {
     interface Request {
       user?: UserPayload;
       userGroups?: string[];
+      correlationId?: string;
+      span?: Span;
     }
   }
 }
@@ -29,5 +38,5 @@ export interface ServiceHealth {
   timestamp: string;
   version: string;
   description: string;
-  dependencies?: Record<string, any>;
+  dependencies?: Record<string, unknown>;
 }

package/src/utils/correlation.ts

@@ -15,7 +15,7 @@ export function generateCorrelationId(): string {
 export const correlationMiddleware: RequestHandler = (req: Request, res: Response, next: NextFunction) => {
   const correlationId = req.headers['x-correlation-id'] as string || generateCorrelationId();
 
-  (req as any).correlationId = correlationId;
+  req.correlationId = correlationId;
   res.setHeader('x-correlation-id', correlationId);
 
   next();

package/src/utils/permissionUtils.test.ts

@@ -0,0 +1,47 @@
+import { buildAccessQuery, canAccessResource } from './permissionUtils';
+
+describe('buildAccessQuery', () => {
+  it('always includes the user\'s own resources', () => {
+    expect(buildAccessQuery('user-1')).toEqual({ $or: [{ userId: 'user-1' }] });
+  });
+
+  it('adds a group-membership condition when groupIds are provided', () => {
+    expect(buildAccessQuery('user-1', ['g1', 'g2'])).toEqual({
+      $or: [{ userId: 'user-1' }, { groupId: { $in: ['g1', 'g2'] } }]
+    });
+  });
+
+  it('adds a public-resource condition when includePublic is true', () => {
+    expect(buildAccessQuery('user-1', [], true)).toEqual({
+      $or: [{ userId: 'user-1' }, { isPublic: true }]
+    });
+  });
+
+  it('combines group and public conditions', () => {
+    expect(buildAccessQuery('user-1', ['g1'], true)).toEqual({
+      $or: [{ userId: 'user-1' }, { groupId: { $in: ['g1'] } }, { isPublic: true }]
+    });
+  });
+});
+
+describe('canAccessResource', () => {
+  it('allows the owner', () => {
+    expect(canAccessResource('user-1', 'user-1')).toBe(true);
+  });
+
+  it('allows anyone when the resource is public', () => {
+    expect(canAccessResource('user-1', 'user-2', undefined, [], true)).toBe(true);
+  });
+
+  it('allows a member of the resource\'s group', () => {
+    expect(canAccessResource('user-1', 'user-2', 'g1', ['g1'])).toBe(true);
+  });
+
+  it('denies a non-member with no public flag', () => {
+    expect(canAccessResource('user-1', 'user-2', 'g1', ['g2'])).toBe(false);
+  });
+
+  it('denies when the resource has no group and belongs to someone else', () => {
+    expect(canAccessResource('user-1', 'user-2')).toBe(false);
+  });
+});

package/src/utils/permissionUtils.ts

@@ -0,0 +1,68 @@
+/**
+ * Simple permission helper that builds query filters for group-based access
+ * This avoids external API calls and can be used in database queries directly
+ */
+
+/**
+ * Build a MongoDB query for resources accessible by a user
+ * @param userId - The user's ID
+ * @param groupIds - Array of group IDs the user belongs to (optional)
+ * @param includePublic - Whether to include public resources
+ */
+export function buildAccessQuery(
+  userId: string,
+  groupIds: string[] = [],
+  includePublic: boolean = false
+) {
+  const conditions: Array<
+    { userId: string } | { groupId: { $in: string[] } } | { isPublic: boolean }
+  > = [
+    { userId } // User's own resources
+  ];
+
+  // Add group-based access
+  if (groupIds.length > 0) {
+    conditions.push({ groupId: { $in: groupIds } });
+  }
+
+  // Add public resources if requested
+  if (includePublic) {
+    conditions.push({ isPublic: true });
+  }
+
+  return { $or: conditions };
+}
+
+/**
+ * Check if a user can access a specific resource
+ * @param userId - The requesting user's ID
+ * @param resourceUserId - The resource owner's ID
+ * @param resourceGroupId - The resource's group ID (if any)
+ * @param userGroupIds - Array of group IDs the user belongs to
+ * @param isResourcePublic - Whether the resource is public
+ */
+export function canAccessResource(
+  userId: string,
+  resourceUserId: string,
+  resourceGroupId?: string,
+  userGroupIds: string[] = [],
+  isResourcePublic: boolean = false
+): boolean {
+  // Owner can always access their own resources
+  if (userId === resourceUserId) {
+    return true;
+  }
+
+  // Public resources are accessible to anyone
+  if (isResourcePublic) {
+    return true;
+  }
+
+  // If resource is associated with a group, check if user is in that group
+  if (resourceGroupId && userGroupIds.includes(resourceGroupId)) {
+    return true;
+  }
+
+  // No access
+  return false;
+}

package/src/utils/response.ts

@@ -3,7 +3,7 @@ import { Response } from 'express';
 /**
  * Standard API response format
  */
-export interface ApiResponse<T = any> {
+export interface ApiResponse<T = unknown> {
   success: boolean;
   data?: T;
   message?: string;
@@ -14,7 +14,7 @@ export interface ApiResponse<T = any> {
 /**
  * Create a standardized API response
  */
-export function createApiResponse<T = any>(
+export function createApiResponse<T = unknown>(
   success: boolean,
   data?: T,
   message?: string,
@@ -34,7 +34,7 @@ export function createApiResponse<T = any>(
 /**
  * Send a success response
  */
-export function sendSuccess<T = any>(
+export function sendSuccess<T = unknown>(
   res: Response,
   data?: T,
   message?: string,