dcrouter/ts_interfaces/data/route-management.ts

import type { IRouteConfig } from '@push.rocks/smartproxy';
import type { IDcRouterRouteConfig } from './remoteingress.js';

// Derive IRouteSecurity from IRouteConfig since it's not directly exported
export type IRouteSecurity = NonNullable<IRouteConfig['security']>;

// ============================================================================
// Route Management Data Types
// ============================================================================

export const apiTokenScopes = [
  '*',
  'routes:read',
  'routes:write',
  'config:read',
  'stats:read',
  'logs:read',
  'security:read',
  'security:write',
  'emails:read',
  'emails:write',
  'certificates:read',
  'certificates:write',
  'tokens:read',
  'tokens:manage',
  'users:read',
  'users:manage',
  'source-profiles:read',
  'source-profiles:write',
  'target-profiles:read',
  'target-profiles:write',
  'targets:read',
  'targets:write',
  'dns-providers:read',
  'dns-providers:write',
  'domains:read',
  'domains:write',
  'dns-records:read',
  'dns-records:write',
  'acme-config:read',
  'acme-config:write',
  'email-domains:read',
  'email-domains:write',
  'remote-ingress:read',
  'remote-ingress:write',
  'vpn:read',
  'vpn:write',
  'radius:read',
  'radius:write',
  'gateway-clients:read',
  'gateway-clients:write',
  'workhosters:read',
  'workhosters:write',
] as const;

export type TApiTokenScope = typeof apiTokenScopes[number];

export type TGatewayClientType = 'onebox' | 'cloudly' | 'custom';
/** @deprecated Use TGatewayClientType. */
export type TWorkHosterType = TGatewayClientType;

export interface IApiTokenPolicy {
  role: 'admin' | 'gatewayClient' | 'operator';
  scopes?: TApiTokenScope[];
  gatewayClient?: {
    type: TGatewayClientType;
    id: string;
  };
  hostnamePatterns?: string[];
  allowedRouteTargets?: Array<{
    host: string;
    ports: number[];
  }>;
  capabilities?: {
    readDomains?: boolean;
    readDnsRecords?: boolean;
    syncRoutes?: boolean;
    syncDnsRecords?: boolean;
    requestCertificates?: boolean;
  };
}

// ============================================================================
// Source Profile Types (source-side: who can access)
// ============================================================================

/**
 * A reusable, named source profile that can be referenced by routes.
 * Stores the full IRouteSecurity shape from SmartProxy.
 *
 * SourceProfile = source-side (who can access: ipAllowList, rateLimit, auth)
 * TargetProfile = target-side (what can be accessed: domains, IP:port targets, route refs)
 */
export interface ISourceProfile {
  id: string;
  name: string;
  description?: string;
  /** The security configuration — mirrors SmartProxy's IRouteSecurity. */
  security: IRouteSecurity;
  /** IDs of profiles this one extends (resolved top-down, later overrides earlier). */
  extendsProfiles?: string[];
  createdAt: number;
  updatedAt: number;
  createdBy: string;
}

// ============================================================================
// Network Target Types
// ============================================================================

/**
 * A reusable, named network target (host + port) that can be referenced by routes.
 */
export interface INetworkTarget {
  id: string;
  name: string;
  description?: string;
  host: string | string[];
  port: number;
  createdAt: number;
  updatedAt: number;
  createdBy: string;
}

// ============================================================================
// Route Metadata Types
// ============================================================================

/**
 * Metadata on a stored route tracking where its resolved values came from.
 */
export interface IRouteMetadata {
  /** ID of the SourceProfileDoc used to resolve this route's security. */
  sourceProfileRef?: string;
  /** ID of the NetworkTargetDoc used to resolve this route's targets. */
  networkTargetRef?: string;
  /** Snapshot of the profile name at resolution time, for display. */
  sourceProfileName?: string;
  /** Snapshot of the target name at resolution time, for display. */
  networkTargetName?: string;
  /** Timestamp of last reference resolution. */
  lastResolvedAt?: number;
  /** External route ownership, used by WorkHoster reconciliation. */
  ownerType?: 'gatewayClient' | 'workhoster' | 'operator' | 'system';
  gatewayClientType?: TGatewayClientType;
  gatewayClientId?: string;
  gatewayClientAppId?: string;
  /** @deprecated Use gatewayClientType. */
  workHosterType?: TGatewayClientType;
  /** @deprecated Use gatewayClientId. */
  workHosterId?: string;
  /** @deprecated Use gatewayClientAppId. */
  workAppId?: string;
  externalKey?: string;
}

/**
 * A route entry returned by the route management API.
 */
export interface IMergedRoute {
  route: IDcRouterRouteConfig;
  id: string;
  enabled: boolean;
  origin: 'config' | 'email' | 'dns' | 'api';
  systemKey?: string;
  createdAt?: number;
  updatedAt?: number;
  metadata?: IRouteMetadata;
}

/**
 * A warning generated during route startup/apply.
 */
export interface IRouteWarning {
  type: 'disabled-route';
  routeName: string;
  message: string;
}

/**
 * Public info about an API token (never includes the hash).
 */
export interface IApiTokenInfo {
  id: string;
  name: string;
  scopes: TApiTokenScope[];
  policy?: IApiTokenPolicy;
  createdAt: number;
  expiresAt: number | null;
  lastUsedAt: number | null;
  enabled: boolean;
}

// ============================================================================
// Storage Schemas (persisted via StorageManager)
// ============================================================================

/**
 * A route persisted in the database.
 */
export interface IRoute {
  id: string;
  route: IDcRouterRouteConfig;
  enabled: boolean;
  createdAt: number;
  updatedAt: number;
  createdBy: string;
  origin: 'config' | 'email' | 'dns' | 'api';
  systemKey?: string;
  metadata?: IRouteMetadata;
}

/**
 * A stored API token, stored in /config-api/tokens/{id}.json
 */
export interface IStoredApiToken {
  id: string;
  name: string;
  tokenHash: string;
  scopes: TApiTokenScope[];
  policy?: IApiTokenPolicy;
  createdAt: number;
  expiresAt: number | null;
  lastUsedAt: number | null;
  createdBy: string;
  enabled: boolean;
}