feat(route-management): add programmatic route management API with API tokens and admin UI

ts_interfaces/data/index.ts

@@ -1,3 +1,4 @@
 export * from './auth.js';
 export * from './stats.js';
-export * from './remoteingress.js';
+export * from './remoteingress.js';
+export * from './route-management.js';

ts_interfaces/data/route-management.ts

@@ -0,0 +1,83 @@
+import type { IRouteConfig } from '@push.rocks/smartproxy';
+
+// ============================================================================
+// Route Management Data Types
+// ============================================================================
+
+export type TApiTokenScope = 'routes:read' | 'routes:write' | 'config:read' | 'tokens:read' | 'tokens:manage';
+
+/**
+ * A merged route combining hardcoded and programmatic sources.
+ */
+export interface IMergedRoute {
+  route: IRouteConfig;
+  source: 'hardcoded' | 'programmatic';
+  enabled: boolean;
+  overridden: boolean;
+  storedRouteId?: string;
+  createdAt?: number;
+  updatedAt?: number;
+}
+
+/**
+ * A warning generated during route merge/startup.
+ */
+export interface IRouteWarning {
+  type: 'disabled-hardcoded' | 'disabled-programmatic' | 'orphaned-override';
+  routeName: string;
+  message: string;
+}
+
+/**
+ * Public info about an API token (never includes the hash).
+ */
+export interface IApiTokenInfo {
+  id: string;
+  name: string;
+  scopes: TApiTokenScope[];
+  createdAt: number;
+  expiresAt: number | null;
+  lastUsedAt: number | null;
+  enabled: boolean;
+}
+
+// ============================================================================
+// Storage Schemas (persisted via StorageManager)
+// ============================================================================
+
+/**
+ * A programmatic route stored in /config-api/routes/{id}.json
+ */
+export interface IStoredRoute {
+  id: string;
+  route: IRouteConfig;
+  enabled: boolean;
+  createdAt: number;
+  updatedAt: number;
+  createdBy: string;
+}
+
+/**
+ * An override for a hardcoded route, stored in /config-api/overrides/{routeName}.json
+ */
+export interface IRouteOverride {
+  routeName: string;
+  enabled: boolean;
+  updatedAt: number;
+  updatedBy: string;
+}
+
+/**
+ * A stored API token, stored in /config-api/tokens/{id}.json
+ */
+export interface IStoredApiToken {
+  id: string;
+  name: string;
+  tokenHash: string;
+  scopes: TApiTokenScope[];
+  createdAt: number;
+  expiresAt: number | null;
+  lastUsedAt: number | null;
+  createdBy: string;
+  enabled: boolean;
+}

ts_interfaces/requests/api-tokens.ts

@@ -0,0 +1,83 @@
+import * as plugins from '../plugins.js';
+import type * as authInterfaces from '../data/auth.js';
+import type { IApiTokenInfo, TApiTokenScope } from '../data/route-management.js';
+
+// ============================================================================
+// API Token Management Endpoints
+// ============================================================================
+
+/**
+ * Create a new API token. Returns the raw token value once (never shown again).
+ * Admin JWT only — tokens cannot create tokens.
+ */
+export interface IReq_CreateApiToken extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CreateApiToken
+> {
+  method: 'createApiToken';
+  request: {
+    identity?: authInterfaces.IIdentity;
+    name: string;
+    scopes: TApiTokenScope[];
+    expiresInDays?: number | null;
+  };
+  response: {
+    success: boolean;
+    tokenId?: string;
+    tokenValue?: string;
+    message?: string;
+  };
+}
+
+/**
+ * List all API tokens (without hashes).
+ */
+export interface IReq_ListApiTokens extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ListApiTokens
+> {
+  method: 'listApiTokens';
+  request: {
+    identity?: authInterfaces.IIdentity;
+  };
+  response: {
+    tokens: IApiTokenInfo[];
+  };
+}
+
+/**
+ * Revoke (delete) an API token.
+ */
+export interface IReq_RevokeApiToken extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_RevokeApiToken
+> {
+  method: 'revokeApiToken';
+  request: {
+    identity?: authInterfaces.IIdentity;
+    id: string;
+  };
+  response: {
+    success: boolean;
+    message?: string;
+  };
+}
+
+/**
+ * Enable or disable an API token.
+ */
+export interface IReq_ToggleApiToken extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ToggleApiToken
+> {
+  method: 'toggleApiToken';
+  request: {
+    identity?: authInterfaces.IIdentity;
+    id: string;
+    enabled: boolean;
+  };
+  response: {
+    success: boolean;
+    message?: string;
+  };
+}

ts_interfaces/requests/index.ts

@@ -6,4 +6,6 @@ export * from './combined.stats.js';
 export * from './radius.js';
 export * from './email-ops.js';
 export * from './certificate.js';
-export * from './remoteingress.js';
+export * from './remoteingress.js';
+export * from './route-management.js';
+export * from './api-tokens.js';

ts_interfaces/requests/route-management.ts

@@ -0,0 +1,146 @@
+import * as plugins from '../plugins.js';
+import type * as authInterfaces from '../data/auth.js';
+import type { IMergedRoute, IRouteWarning } from '../data/route-management.js';
+import type { IRouteConfig } from '@push.rocks/smartproxy';
+
+// ============================================================================
+// Route Management Endpoints
+// ============================================================================
+
+/**
+ * Get all merged routes (hardcoded + programmatic) with warnings.
+ */
+export interface IReq_GetMergedRoutes extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetMergedRoutes
+> {
+  method: 'getMergedRoutes';
+  request: {
+    identity?: authInterfaces.IIdentity;
+    apiToken?: string;
+  };
+  response: {
+    routes: IMergedRoute[];
+    warnings: IRouteWarning[];
+  };
+}
+
+/**
+ * Create a new programmatic route.
+ */
+export interface IReq_CreateRoute extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CreateRoute
+> {
+  method: 'createRoute';
+  request: {
+    identity?: authInterfaces.IIdentity;
+    apiToken?: string;
+    route: IRouteConfig;
+    enabled?: boolean;
+  };
+  response: {
+    success: boolean;
+    storedRouteId?: string;
+    message?: string;
+  };
+}
+
+/**
+ * Update a programmatic route.
+ */
+export interface IReq_UpdateRoute extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_UpdateRoute
+> {
+  method: 'updateRoute';
+  request: {
+    identity?: authInterfaces.IIdentity;
+    apiToken?: string;
+    id: string;
+    route?: Partial<IRouteConfig>;
+    enabled?: boolean;
+  };
+  response: {
+    success: boolean;
+    message?: string;
+  };
+}
+
+/**
+ * Delete a programmatic route.
+ */
+export interface IReq_DeleteRoute extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_DeleteRoute
+> {
+  method: 'deleteRoute';
+  request: {
+    identity?: authInterfaces.IIdentity;
+    apiToken?: string;
+    id: string;
+  };
+  response: {
+    success: boolean;
+    message?: string;
+  };
+}
+
+/**
+ * Set an override on a hardcoded route (disable/enable by name).
+ */
+export interface IReq_SetRouteOverride extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SetRouteOverride
+> {
+  method: 'setRouteOverride';
+  request: {
+    identity?: authInterfaces.IIdentity;
+    apiToken?: string;
+    routeName: string;
+    enabled: boolean;
+  };
+  response: {
+    success: boolean;
+    message?: string;
+  };
+}
+
+/**
+ * Remove an override from a hardcoded route (restore default behavior).
+ */
+export interface IReq_RemoveRouteOverride extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_RemoveRouteOverride
+> {
+  method: 'removeRouteOverride';
+  request: {
+    identity?: authInterfaces.IIdentity;
+    apiToken?: string;
+    routeName: string;
+  };
+  response: {
+    success: boolean;
+    message?: string;
+  };
+}
+
+/**
+ * Toggle a programmatic route on/off by id.
+ */
+export interface IReq_ToggleRoute extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ToggleRoute
+> {
+  method: 'toggleRoute';
+  request: {
+    identity?: authInterfaces.IIdentity;
+    apiToken?: string;
+    id: string;
+    enabled: boolean;
+  };
+  response: {
+    success: boolean;
+    message?: string;
+  };
+}