@nekro-nxt/contracts 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './domain.js'
+export * from './config-schema.js'
+export * from './extension-ui.js'
+export * from './host-api.js'
+export * from './management-api.js'
+export * from './runtime-compatibility.js'
+export * from './extension-capabilities.js'
+export * from './community.js'

package/src/management-api.ts

@@ -0,0 +1,168 @@
+import { z } from 'zod'
+
+const NonEmptyStringSchema = z.string().trim().min(1)
+const Base64UrlSchema = z.string().regex(/^[A-Za-z0-9_-]+$/u)
+
+export const ServerInstanceIdSchema = z
+  .string()
+  .regex(/^nxt_instance_[0-9A-HJKMNP-TV-Z]{26}$/u)
+  .brand<'ServerInstanceId'>()
+export type ServerInstanceId = z.output<typeof ServerInstanceIdSchema>
+
+export const ManagementDeviceIdSchema = z
+  .string()
+  .regex(/^nxt_device_[0-9A-HJKMNP-TV-Z]{26}$/u)
+  .brand<'ManagementDeviceId'>()
+export type ManagementDeviceId = z.output<typeof ManagementDeviceIdSchema>
+
+export const InstanceDescriptorWireSchema = z
+  .object({
+    format: z.literal('nxt.instance-descriptor'),
+    descriptorVersion: z.number().int().positive(),
+    instanceId: ServerInstanceIdSchema,
+    releaseId: NonEmptyStringSchema.max(256),
+    productVersion: NonEmptyStringSchema.max(64),
+    managementProtocol: z.number().int().positive(),
+    desktopChromeProtocol: z.number().int().positive(),
+    transport: NonEmptyStringSchema.max(80),
+  })
+  .passthrough()
+export type InstanceDescriptorWire = z.output<typeof InstanceDescriptorWireSchema>
+
+export const InstanceDescriptorSchema = z
+  .object({
+    format: z.literal('nxt.instance-descriptor'),
+    descriptorVersion: z.literal(1),
+    instanceId: ServerInstanceIdSchema,
+    releaseId: NonEmptyStringSchema.max(256),
+    productVersion: NonEmptyStringSchema.max(64),
+    managementProtocol: z.union([z.literal(1), z.literal(2)]),
+    desktopChromeProtocol: z.literal(1),
+    transport: z.enum(['loopback-http', 'auto-tls-pinned-v1', 'explicit-http-v1']),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const valid =
+      (value.managementProtocol === 1 &&
+        (value.transport === 'loopback-http' || value.transport === 'auto-tls-pinned-v1')) ||
+      (value.managementProtocol === 2 && value.transport === 'explicit-http-v1')
+    if (!valid) context.addIssue({ code: 'custom', message: 'management protocol 与 transport 不匹配。' })
+  })
+export type InstanceDescriptor = z.output<typeof InstanceDescriptorSchema>
+
+export const ManagementChallengeResponseSchema = z
+  .object({
+    challengeId: Base64UrlSchema,
+    serverNonce: Base64UrlSchema,
+    instanceId: ServerInstanceIdSchema,
+    spkiSha256: Base64UrlSchema,
+    expiresAt: z.number().int().positive(),
+  })
+  .strict()
+export type ManagementChallengeResponse = z.output<typeof ManagementChallengeResponseSchema>
+
+export const InsecureHttpManagementChallengeResponseSchema = z
+  .object({
+    challengeId: Base64UrlSchema,
+    serverNonce: Base64UrlSchema,
+    instanceId: ServerInstanceIdSchema,
+    transportBinding: Base64UrlSchema,
+    expiresAt: z.number().int().positive(),
+  })
+  .strict()
+export type InsecureHttpManagementChallengeResponse = z.output<typeof InsecureHttpManagementChallengeResponseSchema>
+
+export const ManagementDeviceEnrollmentRequestSchema = z
+  .object({
+    challengeId: Base64UrlSchema,
+    clientNonce: Base64UrlSchema,
+    proof: Base64UrlSchema,
+    label: z.string().trim().min(1).max(80),
+    clientReleaseId: NonEmptyStringSchema.max(256),
+  })
+  .strict()
+export type ManagementDeviceEnrollmentRequest = z.input<typeof ManagementDeviceEnrollmentRequestSchema>
+
+export const ManagementDeviceEnrollmentResponseSchema = z
+  .object({
+    deviceId: ManagementDeviceIdSchema,
+    deviceSecret: Base64UrlSchema,
+  })
+  .strict()
+export type ManagementDeviceEnrollmentResponse = z.output<typeof ManagementDeviceEnrollmentResponseSchema>
+
+export const ManagementSessionRequestSchema = z
+  .object({ deviceId: ManagementDeviceIdSchema, deviceSecret: Base64UrlSchema })
+  .strict()
+export type ManagementSessionRequest = z.input<typeof ManagementSessionRequestSchema>
+
+export const ManagementSessionResponseSchema = z
+  .object({ authenticated: z.literal(true), deviceId: ManagementDeviceIdSchema, csrfToken: Base64UrlSchema })
+  .strict()
+export type ManagementSessionResponse = z.output<typeof ManagementSessionResponseSchema>
+
+export const ManagementDeviceViewSchema = z
+  .object({
+    id: ManagementDeviceIdSchema,
+    label: z.string().trim().min(1).max(80),
+    createdAt: z.number().int().nonnegative(),
+    lastUsedAt: z.number().int().nonnegative().optional(),
+    revokedAt: z.number().int().nonnegative().optional(),
+    /** The device this request is signed in with. */
+    current: z.boolean().optional(),
+  })
+  .strict()
+export type ManagementDeviceView = z.output<typeof ManagementDeviceViewSchema>
+
+export const ClientNotificationSchema = z
+  .object({
+    id: z.string().trim().min(1).max(160),
+    kind: z.enum(['action-required']),
+    title: z.string().trim().min(1).max(80),
+    body: z.string().trim().min(1).max(240),
+    occurredAt: z.number().int().nonnegative(),
+    route: z
+      .string()
+      .regex(
+        /^\/(?:(?:live|channels|agents|workshop|wiring|settings|apps|work|connections|users|extensions)(?:\/[^?#]*)?)?$/u,
+      )
+      .optional(),
+  })
+  .strict()
+export type ClientNotification = z.output<typeof ClientNotificationSchema>
+
+export const MANAGEMENT_PAIR_PROOF_PREFIX = 'nxt-management-pair-v1' as const
+
+export const managementPairProofMessage = (input: {
+  readonly challengeId: string
+  readonly serverNonce: string
+  readonly clientNonce: string
+  readonly instanceId: ServerInstanceId
+  readonly spkiSha256: string
+}): string =>
+  [
+    MANAGEMENT_PAIR_PROOF_PREFIX,
+    input.challengeId,
+    input.serverNonce,
+    input.clientNonce,
+    input.instanceId,
+    input.spkiSha256,
+  ].join('\n')
+
+export const INSECURE_HTTP_MANAGEMENT_PAIR_PROOF_PREFIX = 'nxt-management-pair-insecure-http-v1' as const
+
+export const insecureHttpManagementPairProofMessage = (input: {
+  readonly challengeId: string
+  readonly serverNonce: string
+  readonly clientNonce: string
+  readonly instanceId: ServerInstanceId
+  readonly transportBinding: string
+}): string =>
+  [
+    INSECURE_HTTP_MANAGEMENT_PAIR_PROOF_PREFIX,
+    input.challengeId,
+    input.serverNonce,
+    input.clientNonce,
+    input.instanceId,
+    input.transportBinding,
+  ].join('\n')

package/src/runtime-compatibility.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod'
+
+export const RuntimeCompatibilityDiagnosticSchema = z
+  .object({
+    objectKind: z.enum(['agent', 'model-provider', 'extension', 'dsh-plugin', 'adapter', 'client-page']),
+    objectId: z.string().min(1),
+    objectVersion: z.string().min(1),
+    configurationRevision: z.string(),
+    runtimeFingerprint: z.string().min(1),
+    status: z.enum(['checking', 'compatible', 'isolated']),
+    phase: z.enum(['configuration', 'dependency', 'build', 'load', 'render', 'restore', 'dispose']),
+    reason: z.string().max(2048).optional(),
+    retryable: z.boolean(),
+    checkedAt: z.number().int().nonnegative(),
+  })
+  .strict()
+export type RuntimeCompatibilityDiagnostic = z.infer<typeof RuntimeCompatibilityDiagnosticSchema>
+
+export const HostUpgradeSummarySchema = z
+  .object({
+    runtimeVersion: z.string().min(1),
+    sessionCompatibilityId: z.string().min(1),
+    backupId: z.string().optional(),
+    resetContexts: z.boolean(),
+    diagnostics: z.array(RuntimeCompatibilityDiagnosticSchema),
+  })
+  .strict()
+export type HostUpgradeSummary = z.infer<typeof HostUpgradeSummarySchema>