@uniquedivine/tg-sai 0.0.4 → 0.0.5

package/provisioningCli.ts

@@ -0,0 +1,140 @@
+import { randomUUID } from "node:crypto"
+import { readFile } from "node:fs/promises"
+import { hostname } from "node:os"
+import type { Command } from "commander"
+import {
+  creationMarker,
+  provisionSetup,
+  requestFingerprint,
+  validateRequest,
+} from "./provisioning"
+import type { ProvisionRequest } from "./provisioning"
+import { CliProvisionCloud } from "./provisioningCloud"
+import {
+  FileProvisionJournal,
+  withProvisionTelegram,
+} from "./provisioningRuntime"
+
+function print(value: unknown): void {
+  console.log(
+    JSON.stringify(
+      value,
+      (key, item) => (key === "claimToken" ? undefined : item),
+      2,
+    ),
+  )
+}
+function chatId(value: string): number {
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || parsed >= 0)
+    throw new Error("Explicit negative Telegram supergroup ID required")
+  return parsed
+}
+export function addProvisionCommands(program: Command): void {
+  const provision = program
+    .command("chat")
+    .description("Sai deal chat operations")
+    .command("provision")
+    .description(
+      "Prepare and resume custody-account setup through Deal Desk cloud jobs",
+    )
+  provision
+    .command("prepare")
+    .requiredOption("--file <path>", "Provisioning request JSON file")
+    .option("--run", "Persist the request to authoritative cloud state")
+    .action(async (options: { file: string; run?: boolean }) => {
+      const raw = JSON.parse(await readFile(options.file, "utf8"))
+      const request = validateRequest({
+        ...raw,
+        expectedUserId: Number(raw.expectedUserId),
+      } as ProvisionRequest)
+      if (!options.run)
+        return print({
+          dryRun: true,
+          request,
+          fingerprint: requestFingerprint(request),
+        })
+      print(await new CliProvisionCloud().prepare(request))
+    })
+  provision
+    .command("status")
+    .requiredOption("--request-id <id>", "Stable setup request ID")
+    .action(async (options: { requestId: string }) =>
+      print(await new CliProvisionCloud().view(options.requestId)),
+    )
+  for (const name of ["run", "resume"]) {
+    provision
+      .command(name)
+      .requiredOption("--request-id <id>", "Stable setup request ID")
+      .option(
+        "--run",
+        "Execute Telegram setup writes and authoritative cloud progress",
+      )
+      .action(async (options: { requestId: string; run?: boolean }) => {
+        const cloud = new CliProvisionCloud()
+        const setup = await cloud.view(options.requestId)
+        if (!options.run)
+          return print({
+            dryRun: true,
+            setup,
+            next: "Pass --run to execute this request with its explicit custody profile",
+          })
+        print(
+          await withProvisionTelegram(setup, (telegram) =>
+            provisionSetup({
+              setup,
+              telegram,
+              cloud,
+              journal: new FileProvisionJournal(),
+              workerId: `${hostname()}:${process.pid}:${randomUUID()}`,
+            }),
+          ),
+        )
+      })
+  }
+  provision
+    .command("resolve")
+    .requiredOption("--request-id <id>", "Stable setup request ID")
+    .requiredOption("--chat <id>", "Exact created supergroup ID", chatId)
+    .requiredOption(
+      "--reason <text>",
+      "Operator evidence for explicit adoption",
+    )
+    .option("--run", "Verify and adopt the exact group in cloud state")
+    .action(
+      async (options: {
+        requestId: string
+        chat: number
+        reason: string
+        run?: boolean
+      }) => {
+        const cloud = new CliProvisionCloud()
+        const setup = await cloud.view(options.requestId)
+        if (!options.reason.trim())
+          throw new Error("Resolution evidence required")
+        if (!options.run)
+          return print({
+            dryRun: true,
+            requestId: setup.requestId,
+            chatId: options.chat,
+            reason: options.reason,
+          })
+        if (!["creating", "creation_unknown"].includes(setup.state))
+          throw new Error("Only an unresolved creation can be adopted")
+        print(
+          await withProvisionTelegram(setup, async (telegram) => {
+            if (
+              !(await telegram.verifyMarker(
+                options.chat,
+                creationMarker(setup),
+              ))
+            )
+              throw new Error(
+                "Resolution chat does not match custody owner and request marker",
+              )
+            return cloud.resolve(setup.requestId, options.chat, options.reason)
+          }),
+        )
+      },
+    )
+}

package/provisioningCloud.ts

@@ -0,0 +1,214 @@
+import { createHash, randomUUID } from "node:crypto"
+import type {
+  Progress,
+  ProvisionCloud,
+  ProvisionRequest,
+  Setup,
+} from "./provisioning"
+import { validateRequest } from "./provisioning"
+
+export type CloudOperation =
+  | "prepare"
+  | "view"
+  | "list"
+  | "pending"
+  | "claim"
+  | "progress"
+  | "resolve"
+export type CloudCall = (
+  operation: CloudOperation,
+  input: Record<string, unknown>,
+) => Promise<unknown>
+
+export function cloudRequest(
+  request: ProvisionRequest,
+): Record<string, unknown> {
+  validateRequest(request)
+  return {
+    requestId: request.requestId,
+    custodyProfile: request.custodyProfile,
+    title: request.title,
+    botRightsProfile: request.botRightsProfile,
+    dealIds: request.dealIds,
+    expectedUserId: String(request.expectedUserId),
+    participants: request.participants.map(String),
+    ...(request.optionalParticipants === undefined
+      ? {}
+      : { optionalParticipants: request.optionalParticipants.map(String) }),
+    admins: request.admins.map((admin) => ({
+      userId: String(admin.userId),
+      rightsProfile: admin.rightsProfile,
+    })),
+  }
+}
+function numericId(value: unknown): number {
+  if (typeof value !== "string" && typeof value !== "number")
+    throw new Error("Cloud returned invalid Telegram identity")
+  const id = Number(value)
+  if (!Number.isSafeInteger(id) || id === 0)
+    throw new Error("Cloud returned invalid Telegram identity")
+  return id
+}
+export function setupFromCloud(raw: unknown): Setup {
+  if (!raw || typeof raw !== "object")
+    throw new Error("Cloud returned invalid setup")
+  const value = raw as Record<string, unknown>
+  const setup = {
+    ...value,
+    expectedUserId: numericId(value.expectedUserId),
+  } as unknown as Setup
+  if (value.chatId !== undefined && value.chatId !== null)
+    setup.chatId = numericId(value.chatId)
+  else delete setup.chatId
+  if (value.resolvedParticipants != null || value.resolvedAdmins != null) {
+    if (
+      !Array.isArray(value.resolvedParticipants) ||
+      !Array.isArray(value.resolvedAdmins)
+    )
+      throw new Error("Cloud returned incomplete identity bindings")
+    setup.binding = {
+      participants: value.resolvedParticipants.map(numericId),
+      admins: value.resolvedAdmins.map(numericId),
+      ...(value.resolvedOptionalParticipants == null
+        ? {}
+        : {
+            optionalParticipants: (
+              value.resolvedOptionalParticipants as unknown[]
+            ).map(numericId),
+          }),
+    }
+  }
+  validateRequest(setup)
+  if (
+    ![
+      "prepared",
+      "creating",
+      "creation_unknown",
+      "configuring",
+      "incomplete",
+      "ready",
+      "cancelled",
+    ].includes(setup.state)
+  )
+    throw new Error("Cloud returned invalid setup state")
+  return setup
+}
+export class CliProvisionCloud implements ProvisionCloud {
+  constructor(private call: CloudCall = callDealDesk) {}
+  async pending(input: {
+    expectedUserId: number
+    workerId: string
+    limit: number
+    after?: string
+  }): Promise<{
+    requests: Setup[]
+    nextAfter: string | null
+    blocked: { requestId: string; state: string; reason: string }[]
+  }> {
+    const raw = (await this.call("pending", {
+      ...input,
+      expectedUserId: String(input.expectedUserId),
+    })) as {
+      requests: unknown[]
+      nextAfter?: string | null
+      blocked?: { requestId: string; state: string; reason: string }[]
+    }
+    if (!Array.isArray(raw?.requests))
+      throw new Error("Cloud returned invalid pending queue")
+    return {
+      requests: raw.requests.map(setupFromCloud),
+      nextAfter: raw.nextAfter ?? null,
+      blocked: raw.blocked ?? [],
+    }
+  }
+  async prepare(request: ProvisionRequest): Promise<Setup> {
+    return setupFromCloud(await this.call("prepare", cloudRequest(request)))
+  }
+  async view(requestId: string): Promise<Setup> {
+    return setupFromCloud(await this.call("view", { requestId }))
+  }
+  async claim(requestId: string, workerId: string): Promise<Setup> {
+    return setupFromCloud(await this.call("claim", { requestId, workerId }))
+  }
+  async progress(
+    requestId: string,
+    claimToken: string,
+    progress: Progress,
+  ): Promise<Setup> {
+    const { binding, ...rest } = progress
+    return setupFromCloud(
+      await this.call("progress", {
+        requestId,
+        claimToken,
+        ...rest,
+        ...(progress.chatId === undefined
+          ? {}
+          : { chatId: String(progress.chatId) }),
+        ...(binding
+          ? {
+              resolvedParticipants: binding.participants.map(String),
+              resolvedAdmins: binding.admins.map(String),
+              ...(binding.optionalParticipants === undefined
+                ? {}
+                : {
+                    resolvedOptionalParticipants:
+                      binding.optionalParticipants.map(String),
+                  }),
+            }
+          : {}),
+      }),
+    )
+  }
+  async resolve(
+    requestId: string,
+    chatId: number,
+    reason: string,
+  ): Promise<Setup> {
+    return setupFromCloud(
+      await this.call("resolve", { requestId, chatId: String(chatId), reason }),
+    )
+  }
+}
+
+export function dealDeskRequestKey(
+  operation: CloudOperation,
+  input: Record<string, unknown>,
+): string {
+  // The same payload can be a new intent after operator recovery or an explicit
+  // creation rejection. Receipts must only deduplicate one invocation.
+  if (operation === "claim" || operation === "progress")
+    return `tg-provision:${operation}:${randomUUID()}`
+  return `tg-provision:${createHash("sha256").update(JSON.stringify({ operation, input })).digest("hex")}`
+}
+
+/** Spawn argv directly; credentials stay in the existing Deal Desk client environment. */
+export async function callDealDesk(
+  operation: CloudOperation,
+  input: Record<string, unknown>,
+): Promise<unknown> {
+  const key = dealDeskRequestKey(operation, input)
+  const command = ["sai-deal-desk", "chat-setups", operation, "--json-stdin"]
+  if (operation !== "view" && operation !== "list" && operation !== "pending")
+    command.push("--request-key", key)
+  const child = Bun.spawn(command, {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  child.stdin.write(JSON.stringify(input))
+  child.stdin.end()
+  const [stdout, , exit] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+  if (exit !== 0)
+    throw new Error(
+      `Deal Desk chat-setups ${operation} failed; inspect its operator status separately`,
+    )
+  try {
+    return JSON.parse(stdout)
+  } catch {
+    throw new Error("Deal Desk returned non-JSON setup response")
+  }
+}

package/provisioningGoldens.ts

@@ -0,0 +1,70 @@
+import type { ChatInviteLink, ChatMember, FullChat } from "@mtcute/bun"
+
+/** Numeric IDs need an access hash cached from an exact dialog readback. */
+export async function requireExactCaptureDialog(
+  dialogs: AsyncIterable<{ peer: { id: number } }>,
+  chatId: number,
+  limit = 1000,
+): Promise<void> {
+  let inspected = 0
+  for await (const dialog of dialogs) {
+    inspected++
+    if (dialog.peer.id === chatId) return
+    if (inspected >= limit) break
+  }
+  throw new Error("Exact capture group was not found in bounded custody dialogs")
+}
+
+export type MemberShape = Pick<ChatMember, "status" | "isMember" | "permissions">
+export type InviteShape = Pick<ChatInviteLink,
+  "isMyLink" | "isRevoked" | "approvalNeeded" | "isPrimary" | "endDate" |
+  "usageLimit" | "usage" | "pendingApprovals">
+
+/** Copy only fields consumed by the adapter. Never serialize Telegram objects. */
+export function memberShape(value: MemberShape | null): MemberShape | null {
+  if (!value) return null
+  return {
+    status: value.status,
+    isMember: value.isMember,
+    permissions: value.permissions === null ? null : {
+      _: "chatAdminRights",
+      ...Object.fromEntries(Object.entries(value.permissions).filter(
+        ([, v]) => typeof v === "boolean",
+      )),
+    },
+  }
+}
+
+export function sanitizedProvisioningGolden(input: {
+  capturedAt: string
+  chat: Pick<FullChat, "chatType" | "isForum" | "isCreator" | "bio">
+  expectedMarker: string
+  members: { subject: string; value: MemberShape | null }[]
+  invites: InviteShape[]
+}) {
+  return {
+    format: "tg-sai-provisioning-golden/v1" as const,
+    provenance: { kind: "live-readback" as const, capturedAt: input.capturedAt },
+    chat: {
+      chatType: input.chat.chatType,
+      isForum: input.chat.isForum,
+      isCreator: input.chat.isCreator,
+      markerMatches: input.chat.bio === input.expectedMarker,
+    },
+    members: input.members.map(({ subject, value }) => ({ subject, value: memberShape(value) })),
+    invitations: {
+      limit: 100,
+      mayHaveMore: input.invites.length === 100,
+      entries: input.invites.map(invite => ({
+        isMyLink: invite.isMyLink,
+        isRevoked: invite.isRevoked,
+        approvalNeeded: invite.approvalNeeded,
+        isPrimary: invite.isPrimary,
+        expiresAt: invite.endDate?.toISOString() ?? null,
+        usageLimit: Number.isFinite(invite.usageLimit) ? invite.usageLimit : null,
+        usage: invite.usage,
+        pendingApprovals: invite.pendingApprovals,
+      })),
+    },
+  }
+}