@tx5dr/contracts 1.7.12 → 2.5.0

package/src/schema/audio.schema.ts

@@ -1,5 +1,69 @@
 import { z } from 'zod';
 
+export const AudioDeviceBackendSchema = z.enum([
+  'rtaudio',
+  'android',
+  'icom-wlan',
+  'openwebrx',
+  'tci',
+  'network',
+]);
+
+export const AudioDeviceKindSchema = z.enum([
+  'usb',
+  'wired-headset',
+  'wired-headphones',
+  'analog-line',
+  'builtin-mic',
+  'builtin-speaker',
+  'network',
+  'virtual',
+  'unknown',
+]);
+
+export const AudioDeviceTransportSchema = z.enum([
+  'usb',
+  'analog',
+  'builtin',
+  'network',
+  'virtual',
+  'unknown',
+]);
+
+export const AudioDeviceConnectorSchema = z.enum([
+  'usb',
+  '3.5mm',
+  'builtin',
+  'network',
+  'virtual',
+  'unknown',
+]);
+
+export const AudioDeviceRouteStateSchema = z.enum([
+  'idle',
+  'opening',
+  'verified',
+  'lost',
+  'unavailable',
+  'failed',
+]);
+
+export const AudioDeviceCapabilitiesSchema = z.object({
+  sampleRates: z.array(z.number().int().positive()).optional(),
+  bufferSizes: z.array(z.number().int().positive()).optional(),
+  channelCounts: z.array(z.number().int().positive()).optional(),
+  sampleFormats: z.array(z.enum(['float32', 'int16'])).optional(),
+  channelModes: z.array(z.enum(['mono', 'left', 'right', 'both'])).optional(),
+  sampleRateConfigurable: z.boolean().optional(),
+  bufferSizeConfigurable: z.boolean().optional(),
+  sampleFormatConfigurable: z.boolean().optional(),
+  channelModeConfigurable: z.boolean().optional(),
+  outputRouteAck: z.boolean().optional(),
+  fixedSampleRate: z.number().int().positive().optional(),
+  fixedBufferSize: z.number().int().positive().optional(),
+  fixedChannelCount: z.number().int().positive().optional(),
+});
+
 // 音频设备信息
 export const AudioDeviceSchema = z.object({
   id: z.string(),
@@ -12,6 +76,26 @@ export const AudioDeviceSchema = z.object({
   availability: z.enum(['available', 'cached', 'active']).optional(),
   isActiveByTx5dr: z.boolean().optional(),
   lastSeenAt: z.number().int().positive().optional(),
+  backend: AudioDeviceBackendSchema.optional(),
+  kind: AudioDeviceKindSchema.optional(),
+  routeKey: z.string().min(1).optional(),
+  transport: AudioDeviceTransportSchema.optional(),
+  connector: AudioDeviceConnectorSchema.optional(),
+  clientConnected: z.boolean().optional(),
+  routeVerified: z.boolean().optional(),
+  routeState: AudioDeviceRouteStateSchema.optional(),
+  failureReason: z.string().min(1).optional(),
+  capabilities: AudioDeviceCapabilitiesSchema.optional(),
+  /** Human-readable secondary label (radio identity · VID:PID · USB path). */
+  detail: z.string().optional(),
+  /** Stable hardware identity when available (e.g. usb:1-7.2.4). */
+  hardwareId: z.string().optional(),
+  vendorId: z.string().optional(),
+  productId: z.string().optional(),
+  serialNumber: z.string().optional(),
+  usbPath: z.string().optional(),
+  alsaCard: z.number().int().nonnegative().optional(),
+  alsaCardId: z.string().optional(),
 });
 
 export const AudioDeviceResolutionStatusSchema = z.enum([
@@ -23,6 +107,9 @@ export const AudioDeviceResolutionStatusSchema = z.enum([
 
 export const AudioDeviceResolutionSchema = z.object({
   configuredDeviceName: z.string().nullable(),
+  configuredRouteKey: z.string().nullable().optional(),
+  configuredDeviceId: z.string().nullable().optional(),
+  configuredHardwareId: z.string().nullable().optional(),
   configuredDevice: AudioDeviceSchema.nullable(),
   effectiveDevice: AudioDeviceSchema.nullable(),
   status: AudioDeviceResolutionStatusSchema,
@@ -37,6 +124,13 @@ export const AudioDeviceResolutionSetSchema = z.object({
 export const AudioOutputSampleFormatSchema = z.enum(['float32', 'int16']);
 export const AudioOutputChannelModeSchema = z.enum(['mono', 'left', 'right', 'both']);
 
+/**
+ * How USB/ACC capture PCM should be interpreted before the internal 12 kHz AF ring.
+ * - af: already-demodulated SSB baseband (default)
+ * - icom-12k-if: Icom ACC/USB Output Select=IF (~12 kHz IF); software SSB demod required
+ */
+export const AudioInputSignalTypeSchema = z.enum(['af', 'icom-12k-if']);
+
 // 音频设备列表响应
 export const AudioDevicesResponseSchema = z.object({
   inputDevices: z.array(AudioDeviceSchema),
@@ -48,13 +142,25 @@ export const AudioDevicesResponseSchema = z.object({
 // 音频设备设置请求
 export const AudioDeviceSettingsSchema = z.object({
   inputDeviceName: z.string().optional(),  // 使用设备名称而非ID
-  outputDeviceName: z.string().optional(), // 使用设备名称而非ID  
+  outputDeviceName: z.string().optional(), // 使用设备名称而非ID
+  inputRouteKey: z.string().min(1).nullable().optional(),
+  outputRouteKey: z.string().min(1).nullable().optional(),
+  /** Runtime device id (e.g. input-130). Preferred over name when unique. */
+  inputDeviceId: z.string().optional(),
+  outputDeviceId: z.string().optional(),
+  /** Stable hardware id when available (e.g. usb:1-7.2.4). Preferred over runtime id. */
+  inputHardwareId: z.string().optional(),
+  outputHardwareId: z.string().optional(),
   inputSampleRate: z.number().optional(),
   outputSampleRate: z.number().optional(),
   inputBufferSize: z.number().optional(),
   outputBufferSize: z.number().optional(),
   outputSampleFormat: AudioOutputSampleFormatSchema.optional(),
   outputChannelMode: AudioOutputChannelModeSchema.optional(),
+  /** Capture signal interpretation. Defaults to demodulated AF baseband. */
+  inputSignalType: AudioInputSignalTypeSchema.optional(),
+  /** IF center frequency in Hz when inputSignalType is icom-12k-if (default 12000). */
+  ifCenterHz: z.number().positive().max(24000).optional(),
   sampleRate: z.number().optional(),
   bufferSize: z.number().optional(),
 });
@@ -69,7 +175,7 @@ export const AudioDeviceSettingsResponseSchema = z.object({
 
 export const AudioSettingsResolveRequestSchema = z.object({
   audio: AudioDeviceSettingsSchema,
-  radioType: z.enum(['none', 'network', 'serial', 'icom-wlan']).optional(),
+  radioType: z.enum(['none', 'network', 'serial', 'icom-wlan', 'tci']).optional(),
 });
 
 export const AudioSettingsResolveResponseSchema = z.object({
@@ -110,11 +216,18 @@ export const VolumeGainSchema = z.object({
 
 // 导出类型
 export type AudioDevice = z.infer<typeof AudioDeviceSchema>;
+export type AudioDeviceBackend = z.infer<typeof AudioDeviceBackendSchema>;
+export type AudioDeviceKind = z.infer<typeof AudioDeviceKindSchema>;
+export type AudioDeviceTransport = z.infer<typeof AudioDeviceTransportSchema>;
+export type AudioDeviceConnector = z.infer<typeof AudioDeviceConnectorSchema>;
+export type AudioDeviceRouteState = z.infer<typeof AudioDeviceRouteStateSchema>;
+export type AudioDeviceCapabilities = z.infer<typeof AudioDeviceCapabilitiesSchema>;
 export type AudioDeviceResolutionStatus = z.infer<typeof AudioDeviceResolutionStatusSchema>;
 export type AudioDeviceResolution = z.infer<typeof AudioDeviceResolutionSchema>;
 export type AudioDeviceResolutionSet = z.infer<typeof AudioDeviceResolutionSetSchema>;
 export type AudioOutputSampleFormat = z.infer<typeof AudioOutputSampleFormatSchema>;
 export type AudioOutputChannelMode = z.infer<typeof AudioOutputChannelModeSchema>;
+export type AudioInputSignalType = z.infer<typeof AudioInputSignalTypeSchema>;
 export type AudioDevicesResponse = z.infer<typeof AudioDevicesResponseSchema>;
 export type AudioDeviceSettings = z.infer<typeof AudioDeviceSettingsSchema>;
 export type AudioDeviceSettingsResponse = z.infer<typeof AudioDeviceSettingsResponseSchema>;

package/src/schema/auth.schema.ts

@@ -82,6 +82,19 @@ export const LoginResponseSchema = z.object({
 
 export type LoginResponse = z.infer<typeof LoginResponseSchema>;
 
+export const BrowserLoginCodeResponseSchema = z.object({
+  code: z.string().min(1),
+  expiresAt: z.number(),
+});
+
+export type BrowserLoginCodeResponse = z.infer<typeof BrowserLoginCodeResponseSchema>;
+
+export const ExchangeBrowserLoginCodeRequestSchema = z.object({
+  code: z.string().min(1),
+});
+
+export type ExchangeBrowserLoginCodeRequest = z.infer<typeof ExchangeBrowserLoginCodeRequestSchema>;
+
 // ===== Token 管理（Admin API） =====
 
 export const LoginCredentialSummarySchema = z.object({
@@ -211,11 +224,76 @@ export const UpdateAuthConfigRequestSchema = z.object({
 
 export type UpdateAuthConfigRequest = z.infer<typeof UpdateAuthConfigRequestSchema>;
 
+export const RemoteAccessPresetSchema = z.enum(['local', 'lan', 'public']);
+export type RemoteAccessPreset = z.infer<typeof RemoteAccessPresetSchema>;
+
+export function isPrivateRemoteAccessHostname(hostname: string): boolean {
+  if (['localhost', '127.0.0.1', '::1'].includes(hostname)) return true;
+  if (hostname.includes(':')) {
+    const normalized = hostname.toLowerCase();
+    return normalized.startsWith('fc') || normalized.startsWith('fd') || normalized.startsWith('fe8')
+      || normalized.startsWith('fe9') || normalized.startsWith('fea') || normalized.startsWith('feb');
+  }
+  const parts = hostname.split('.').map(Number);
+  if (parts.length !== 4 || parts.some(part => !Number.isInteger(part) || part < 0 || part > 255)) return false;
+  return parts[0] === 10
+    || (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31)
+    || (parts[0] === 192 && parts[1] === 168)
+    || (parts[0] === 100 && parts[1] >= 64 && parts[1] <= 127)
+    || (parts[0] === 169 && parts[1] === 254);
+}
+
+export function normalizeRemoteAccessOrigin(value: string): string | null {
+  try {
+    const parsed = new URL(value.trim());
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
+    if (parsed.username || parsed.password || parsed.pathname !== '/' || parsed.search || parsed.hash) return null;
+    return parsed.origin;
+  } catch {
+    return null;
+  }
+}
+
+export function isSecureRemoteAccessOrigin(value: string): boolean {
+  const normalized = normalizeRemoteAccessOrigin(value);
+  if (!normalized) return false;
+  const parsed = new URL(normalized);
+  return parsed.protocol === 'https:' || isPrivateRemoteAccessHostname(parsed.hostname);
+}
+
+export const RemoteAccessSecurityConfigSchema = z.object({
+  preset: RemoteAccessPresetSchema.default('lan'),
+  allowedOrigins: z.array(z.string().url().refine(
+    value => normalizeRemoteAccessOrigin(value) !== null,
+    'Expected a complete HTTP(S) origin without a path',
+  )).max(32).default([]),
+  maxConnections: z.number().int().min(1).max(512).default(32),
+  maxConnectionsPerIp: z.number().int().min(1).max(128).default(16),
+  maxPendingAuth: z.number().int().min(1).max(128).default(32),
+  authTimeoutMs: z.number().int().min(3_000).max(60_000).default(10_000),
+  handshakeTimeoutMs: z.number().int().min(3_000).max(60_000).default(10_000),
+});
+export type RemoteAccessSecurityConfig = z.infer<typeof RemoteAccessSecurityConfigSchema>;
+
+export const UpdateRemoteAccessSecurityRequestSchema = RemoteAccessSecurityConfigSchema.partial().extend({
+  allowPublicViewing: z.boolean().optional(),
+});
+export type UpdateRemoteAccessSecurityRequest = z.infer<typeof UpdateRemoteAccessSecurityRequestSchema>;
+
+export const RemoteAccessSecurityStatusSchema = RemoteAccessSecurityConfigSchema.extend({
+  allowPublicViewing: z.boolean(),
+  activeConnections: z.number().int().nonnegative(),
+  pendingConnections: z.number().int().nonnegative(),
+});
+export type RemoteAccessSecurityStatus = z.infer<typeof RemoteAccessSecurityStatusSchema>;
+
 // ===== 认证配置（持久化到 auth.json） =====
 
 export const AuthConfigSchema = z.object({
   enabled: z.boolean().default(true),
-  allowPublicViewing: z.boolean().default(true),
+  // Existing installations persist their explicit value; new installations opt in.
+  allowPublicViewing: z.boolean().default(false),
+  remoteAccess: RemoteAccessSecurityConfigSchema.default({}),
   jwtSecret: z.string().optional(),
   jwtExpiresInSeconds: z.number().default(7 * 24 * 3600), // 7 days
   tokens: z.array(AuthTokenSchema).default([]),

package/src/schema/cw-keyer.schema.ts

@@ -6,6 +6,9 @@ import { z } from 'zod';
 export const CWKeyerBackendSchema = z.enum(['cat', 'serial']);
 export type CWKeyerBackend = z.infer<typeof CWKeyerBackendSchema>;
 
+export const CWKeyActiveLevelSchema = z.enum(['high', 'low']);
+export type CWKeyActiveLevel = z.infer<typeof CWKeyActiveLevelSchema>;
+
 export const CWKeyerConfigSchema = z.object({
   /** CW 发报后端：cat=Hamlib 整报文，serial=DTR/RTS 时序键控 */
   backend: CWKeyerBackendSchema.default('cat'),
@@ -13,6 +16,8 @@ export const CWKeyerConfigSchema = z.object({
   keyPort: z.string(),
   /** CW 键控引脚类型 */
   keyMethod: z.enum(['dtr', 'rts']),
+  /** CW 键控有效电平：high=高电平按下，low=低电平按下 */
+  keyActiveLevel: CWKeyActiveLevelSchema.default('high'),
   /** 莫尔斯码速度 (WPM, 5-60) */
   wpm: z.number().int().min(5).max(60).default(20),
 });

package/src/schema/diagnostics.schema.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+
+export const DiagnosticLogSourceIdSchema = z.enum(['server', 'electron-main', 'client-tools']);
+export type DiagnosticLogSourceId = z.infer<typeof DiagnosticLogSourceIdSchema>;
+
+export const DiagnosticLogSourceSchema = z.object({
+  id: DiagnosticLogSourceIdSchema,
+  fileName: z.string().min(1),
+  fileCount: z.number().int().positive(),
+  totalBytes: z.number().int().nonnegative(),
+  availableFromMs: z.number().int().positive().nullable(),
+  availableToMs: z.number().int().positive().nullable(),
+});
+export type DiagnosticLogSource = z.infer<typeof DiagnosticLogSourceSchema>;
+
+export const DiagnosticLogSourcesResponseSchema = z.object({
+  sources: z.array(DiagnosticLogSourceSchema),
+  limits: z.object({
+    maxRangeMs: z.number().int().positive(),
+    maxUncompressedBytes: z.number().int().positive(),
+    maxCompressedBytes: z.number().int().positive(),
+    feedbackMaxCharacters: z.number().int().positive(),
+  }),
+});
+export type DiagnosticLogSourcesResponse = z.infer<typeof DiagnosticLogSourcesResponseSchema>;
+
+export const CreateDiagnosticUploadRequestSchema = z.object({
+  sourceId: DiagnosticLogSourceIdSchema,
+  fromMs: z.number().int().positive(),
+  toMs: z.number().int().positive(),
+  feedback: z.string().trim().max(2000).optional(),
+}).strict().superRefine((value, context) => {
+  if (value.toMs <= value.fromMs) {
+    context.addIssue({ code: z.ZodIssueCode.custom, path: ['toMs'], message: 'toMs must be later than fromMs' });
+  }
+  if (value.toMs - value.fromMs > 7 * 24 * 60 * 60 * 1000) {
+    context.addIssue({ code: z.ZodIssueCode.custom, path: ['toMs'], message: 'time range exceeds seven days' });
+  }
+});
+export type CreateDiagnosticUploadRequest = z.infer<typeof CreateDiagnosticUploadRequestSchema>;
+
+export const DiagnosticUploadReceiptSchema = z.object({
+  uploadId: z.string().uuid(),
+  sourceId: DiagnosticLogSourceIdSchema,
+  requestedFromMs: z.number().int().positive(),
+  requestedToMs: z.number().int().positive(),
+  includedFromMs: z.number().int().positive(),
+  includedToMs: z.number().int().positive(),
+  lineCount: z.number().int().positive(),
+  uncompressedBytes: z.number().int().positive(),
+  compressedBytes: z.number().int().positive(),
+  acceptedAt: z.string().datetime(),
+  retainedUntil: z.string().datetime(),
+});
+export type DiagnosticUploadReceipt = z.infer<typeof DiagnosticUploadReceiptSchema>;

package/src/schema/ft8.schema.ts

@@ -276,6 +276,9 @@ export const FT8MessageSchema = z.discriminatedUnion('type', [
  * This is the main plugin-facing FT8 payload. It combines RF metrics from the
  * decoder (`snr`, `dt`, `df`), the original unparsed text (`rawMessage`), the
  * normalized semantic form (`message`) and optional logbook enrichment.
+ * `snr` is dB, `dt` is seconds from the expected decode timing, `df` is audio
+ * offset in hertz, and `timestamp` is Unix epoch milliseconds. `slotId` ties
+ * the decode back to its `SlotInfo`/`SlotPack`.
  */
 export const ParsedFT8MessageSchema = z.object({
   snr: z.number(),
@@ -285,6 +288,11 @@ export const ParsedFT8MessageSchema = z.object({
   message: FT8MessageSchema,
   slotId: z.string(),
   timestamp: z.number(),
+  /**
+   * 标记该消息为 WSJT-X 部分解码（含 `<...>` 未解码呼号占位符）。
+   * 部分解码消息不得作为自动呼叫/回复目标，仅供监控与防御使用。
+   */
+  isPartialDecode: z.boolean().optional(),
   logbookAnalysis: LogbookAnalysisSchema.optional(),
 });