@77-zhike/app-sdk 0.2.0-d7b1.2 → 0.2.0-d7b1.20

package/src/cli/windows-credential-bridge.ps1

@@ -0,0 +1,131 @@
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+$PSModuleAutoLoadingPreference = 'None'
+
+try {
+    if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') {
+        [Console]::Out.Write('{"version":1,"ok":false,"code":"zhike_secure_store_unavailable"}')
+        exit 0
+    }
+    Import-Module "$PSHOME\Modules\Microsoft.PowerShell.Utility\Microsoft.PowerShell.Utility.psd1" -ErrorAction Stop
+    [Console]::InputEncoding = New-Object System.Text.UTF8Encoding($false)
+    [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+    $request = [Console]::In.ReadToEnd() | ConvertFrom-Json
+    $keys = @($request.PSObject.Properties.Name)
+    if ($request.version -ne 1 -or $request.operation -notin @('get', 'set', 'delete', 'probe') -or
+        @($keys | Where-Object { $_ -notin @('version', 'operation', 'origin', 'credential') }).Count -ne 0 -or
+        $request.origin -isnot [string] -or $request.origin.Length -gt 2048) { throw 'invalid request' }
+    $uri = New-Object System.Uri($request.origin, [System.UriKind]::Absolute)
+    if ($uri.Scheme -notin @('http', 'https') -or $uri.UserInfo -or $uri.AbsolutePath -ne '/' -or $uri.Query -or $uri.Fragment) { throw 'invalid origin' }
+    if ($request.operation -eq 'set') {
+        if ($request.credential -isnot [string] -or $request.credential.Length -lt 1 -or $request.credential.Length -gt 512) { throw 'invalid credential' }
+    } elseif ($keys -contains 'credential') { throw 'unexpected credential' }
+
+    # 仅绑定固定 Win32 API；全部在内存中构造，避免运行时编译器对 Unicode TEMP 的依赖。
+    $assembly = [AppDomain]::CurrentDomain.DefineDynamicAssembly(
+        (New-Object Reflection.AssemblyName('ZhikeCredentialBridge')), [Reflection.Emit.AssemblyBuilderAccess]::Run)
+    $module = $assembly.DefineDynamicModule('ZhikeCredentialBridge')
+    $layout = [Reflection.TypeAttributes]::Public -bor [Reflection.TypeAttributes]::SequentialLayout -bor [Reflection.TypeAttributes]::Sealed
+    $structure = $module.DefineType('ZhikeCredential', $layout, [ValueType])
+    # 字段顺序对应 CREDENTIALW；指针由当前进程位数决定，FILETIME 作为 64 位值对齐。
+    $fields = @(
+        @('Flags', [uint32]), @('Type', [uint32]), @('TargetName', [IntPtr]), @('Comment', [IntPtr]),
+        @('LastWritten', [long]), @('CredentialBlobSize', [uint32]), @('CredentialBlob', [IntPtr]),
+        @('Persist', [uint32]), @('AttributeCount', [uint32]), @('Attributes', [IntPtr]),
+        @('TargetAlias', [IntPtr]), @('UserName', [IntPtr]))
+    foreach ($field in $fields) { [void]$structure.DefineField($field[0], $field[1], [Reflection.FieldAttributes]::Public) }
+    $credentialType = $structure.CreateType()
+    $binding = $module.DefineType('ZhikeNativeCredential', [Reflection.TypeAttributes]::Public)
+    $dllImport = [Runtime.InteropServices.DllImportAttribute]
+    $importFields = [Reflection.FieldInfo[]]@($dllImport.GetField('EntryPoint'), $dllImport.GetField('CharSet'), $dllImport.GetField('SetLastError'))
+    $signatures = @(
+        @('Read', 'CredReadW', [bool], [type[]]@([string], [uint32], [uint32], [IntPtr].MakeByRefType())),
+        @('Write', 'CredWriteW', [bool], [type[]]@([IntPtr], [uint32])),
+        @('Delete', 'CredDeleteW', [bool], [type[]]@([string], [uint32], [uint32])),
+        @('Free', 'CredFree', [void], [type[]]@([IntPtr])))
+    foreach ($signature in $signatures) {
+        $method = $binding.DefineMethod($signature[0], [Reflection.MethodAttributes]'Public, Static, PinvokeImpl', $signature[2], $signature[3])
+        $attribute = New-Object Reflection.Emit.CustomAttributeBuilder(
+            $dllImport.GetConstructor([type[]]@([string])), [object[]]@('advapi32.dll'),
+            $importFields, [object[]]@($signature[1], [Runtime.InteropServices.CharSet]::Unicode, $true))
+        $method.SetCustomAttribute($attribute)
+        $method.SetImplementationFlags([Reflection.MethodImplAttributes]::PreserveSig)
+    }
+    $native = $binding.CreateType()
+    $hash = [Security.Cryptography.SHA256]::Create()
+    try { $digest = [BitConverter]::ToString($hash.ComputeHash([Text.Encoding]::UTF8.GetBytes($request.origin))).Replace('-', '').ToLowerInvariant() }
+    finally { $hash.Dispose() }
+    $target = 'com.77hub.zhike.developer-cli/v1/' + $digest
+    $value = $null
+    switch ($request.operation) {
+        { $_ -in @('get', 'probe') } {
+            $pointer = [IntPtr]::Zero
+            if (-not $native::Read($target, 1, 0, [ref]$pointer)) {
+                $errorCode = [Runtime.InteropServices.Marshal]::GetLastWin32Error()
+                if ($errorCode -ne 1168) { throw 'credential read failed' }
+            } else {
+                $blob = [IntPtr]::Zero
+                $blobSize = 0
+                try {
+                    # 按固定结构的实际偏移读取，避免 PowerShell 在 PtrToStructure 的 Type/Object 重载间歧义。
+                    $kind = [Runtime.InteropServices.Marshal]::ReadInt32($pointer, [Runtime.InteropServices.Marshal]::OffsetOf($credentialType, 'Type').ToInt32())
+                    $persist = [Runtime.InteropServices.Marshal]::ReadInt32($pointer, [Runtime.InteropServices.Marshal]::OffsetOf($credentialType, 'Persist').ToInt32())
+                    $blobSize = [Runtime.InteropServices.Marshal]::ReadInt32($pointer, [Runtime.InteropServices.Marshal]::OffsetOf($credentialType, 'CredentialBlobSize').ToInt32())
+                    $blob = [Runtime.InteropServices.Marshal]::ReadIntPtr($pointer, [Runtime.InteropServices.Marshal]::OffsetOf($credentialType, 'CredentialBlob').ToInt32())
+                    # Generic / 本用户本机跨登录持久化；BlobSize 单位为字节，内容为 UTF-16LE。
+                    if ($kind -ne 1 -or $persist -ne 2 -or $blobSize -lt 1 -or $blobSize -gt 1024 -or
+                        $blobSize % 2 -ne 0 -or $blob -eq [IntPtr]::Zero) { throw 'invalid credential metadata' }
+                    if ($request.operation -eq 'get') {
+                        $value = [Runtime.InteropServices.Marshal]::PtrToStringUni($blob, [int]($blobSize / 2))
+                    }
+                } finally {
+                    if ($blob -ne [IntPtr]::Zero -and $blobSize -gt 0 -and $blobSize -le 1024) {
+                        for ($i = 0; $i -lt $blobSize; $i++) { [Runtime.InteropServices.Marshal]::WriteByte($blob, $i, 0) }
+                    }
+                    $native::Free($pointer)
+                }
+            }
+        }
+        'set' {
+            $bytes = [Text.Encoding]::Unicode.GetBytes($request.credential)
+            $blob = [IntPtr]::Zero
+            $record = [IntPtr]::Zero
+            $namePointer = [IntPtr]::Zero
+            $userPointer = [IntPtr]::Zero
+            try {
+                $blob = [Runtime.InteropServices.Marshal]::AllocHGlobal($bytes.Length)
+                [Runtime.InteropServices.Marshal]::Copy($bytes, 0, $blob, $bytes.Length)
+                $namePointer = [Runtime.InteropServices.Marshal]::StringToHGlobalUni($target)
+                $userPointer = [Runtime.InteropServices.Marshal]::StringToHGlobalUni($request.origin)
+                $credential = [Activator]::CreateInstance($credentialType)
+                $credential.Type = 1
+                $credential.TargetName = $namePointer
+                $credential.UserName = $userPointer
+                $credential.CredentialBlob = $blob
+                $credential.CredentialBlobSize = $bytes.Length
+                $credential.Persist = 2
+                $record = [Runtime.InteropServices.Marshal]::AllocHGlobal([Runtime.InteropServices.Marshal]::SizeOf($credential))
+                [Runtime.InteropServices.Marshal]::StructureToPtr($credential, $record, $false)
+                if (-not $native::Write($record, 0)) { throw 'credential write failed' }
+            } finally {
+                [Array]::Clear($bytes, 0, $bytes.Length)
+                if ($blob -ne [IntPtr]::Zero) {
+                    [Runtime.InteropServices.Marshal]::Copy($bytes, 0, $blob, $bytes.Length)
+                    [Runtime.InteropServices.Marshal]::FreeHGlobal($blob)
+                }
+                foreach ($allocated in @($record, $namePointer, $userPointer)) {
+                    if ($allocated -ne [IntPtr]::Zero) { [Runtime.InteropServices.Marshal]::FreeHGlobal($allocated) }
+                }
+            }
+        }
+        'delete' {
+            if (-not $native::Delete($target, 1, 0)) {
+                $errorCode = [Runtime.InteropServices.Marshal]::GetLastWin32Error()
+                if ($errorCode -ne 1168) { throw 'credential delete failed' }
+            }
+        }
+    }
+    [Console]::Out.Write((@{ version = 1; ok = $true; value = $value } | ConvertTo-Json -Compress))
+} catch {
+    [Console]::Out.Write('{"version":1,"ok":false,"code":"zhike_secure_store_failed"}')
+}

package/src/cli/windows-credential-store.js

@@ -0,0 +1,112 @@
+import { execFile, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { win32 } from "node:path";
+
+import { normalizeOrigin } from "../config.js";
+import { ZhikeCliError } from "../errors.js";
+
+let script;
+const failure = () => new ZhikeCliError("zhike_secure_store_failed", "无法访问 Windows 安全凭据存储，请检查系统凭据库和 PowerShell 策略后重试");
+const unavailable = () => new ZhikeCliError("zhike_secure_store_unavailable", "Windows 安全凭据适配不可用，需要系统 Windows PowerShell 5.1 及允许的原生 API 调用");
+
+export class WindowsCredentialStore {
+  constructor({ runner = runWindowsCredentialBridge } = {}) {
+    this.runner = runner;
+  }
+
+  async get(environmentId) { return this.request("get", normalizeOrigin(environmentId, "Developer API")); }
+
+  async set(environmentId, refreshCredential) {
+    if (typeof refreshCredential !== "string" || !refreshCredential.length || refreshCredential.length > 512) throw failure();
+    await this.request("set", normalizeOrigin(environmentId, "Developer API"), refreshCredential);
+  }
+
+  async delete(environmentId) { await this.request("delete", normalizeOrigin(environmentId, "Developer API")); }
+
+  async probe() { await this.request("probe", `https://probe-${randomUUID()}.invalid`); }
+
+  async request(operation, origin, credential) {
+    try {
+      const result = await this.runner({ version: 1, operation, origin, ...(credential === undefined ? {} : { credential }) });
+      if (!result || result.version !== 1 || typeof result.ok !== "boolean" ||
+          Object.keys(result).some((key) => !["version", "ok", "value", "code"].includes(key))) throw failure();
+      if (!result.ok) {
+        if (result.code === "zhike_secure_store_unavailable") throw unavailable();
+        throw failure();
+      }
+      if (operation === "get") {
+        if (result.value !== null && (typeof result.value !== "string" || !result.value.length || result.value.length > 512)) throw failure();
+        return result.value;
+      }
+      if (result.value !== null) throw failure();
+    } catch (error) {
+      if (error instanceof ZhikeCliError) throw error;
+      throw failure();
+    }
+  }
+}
+
+/** 固定程序/脚本与秘密数据分离；子进程输出不得原文进入 CLI 错误。 */
+export async function runWindowsCredentialBridge(request, {
+  spawnImpl = spawn, systemRoot = process.env.SystemRoot, environment = process.env,
+  timeoutMs = 10_000, maxOutputBytes = 65_536,
+} = {}) {
+  if (!systemRoot || !win32.isAbsolute(systemRoot)) throw unavailable();
+  let source;
+  try { source = await (script ??= readFile(new URL("./windows-credential-bridge.ps1", import.meta.url), "utf8")); } catch { throw unavailable(); }
+  const executable = win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+  const encoded = Buffer.from(source, "utf16le").toString("base64");
+  const env = Object.fromEntries(Object.entries(environment).filter(([key]) =>
+    ["systemroot", "windir", "temp", "tmp", "path", "comspec", "systemdrive",
+      "userprofile", "appdata", "localappdata", "homedrive", "homepath", "username", "userdomain",
+      "programfiles", "programfiles(x86)", "programw6432", "programdata", "allusersprofile",
+      "pathext", "computername", "processor_architecture", "processor_identifier", "processor_level",
+      "processor_revision", "number_of_processors", "os"].includes(key.toLowerCase())));
+  // ConvertFrom-Json / Add-Type 的模块解析只使用系统目录，不加载项目或用户自定义模块。
+  // 固定子进程不需要持久化命令发现缓存；避免依赖 runner/用户的缓存路径或锁。
+  env.PSModuleAnalysisCachePath = "NUL";
+  env.PSModulePath = win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "Modules");
+  return new Promise((resolve, reject) => {
+    let child;
+    let output = "";
+    let outputSize = 0;
+    let settled = false;
+    let timer;
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      output = "";
+      if (error) reject(error); else resolve(result);
+    };
+    const terminate = () => {
+      if (Number.isInteger(child?.pid) && process.platform === "win32") {
+        execFile(win32.join(systemRoot, "System32", "taskkill.exe"), ["/PID", String(child.pid), "/T", "/F"],
+          { windowsHide: true, timeout: 3_000 }, () => child.kill());
+      } else child?.kill();
+    };
+    try {
+      child = spawnImpl(executable, ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", encoded],
+        { shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"], env });
+    } catch { finish(unavailable()); return; }
+    timer = setTimeout(() => { terminate(); finish(failure()); }, timeoutMs);
+    const collect = (bytes, keep) => {
+      if (settled) return;
+      outputSize += Buffer.byteLength(bytes);
+      if (outputSize > maxOutputBytes) { terminate(); finish(failure()); return; }
+      if (keep) output += bytes;
+    };
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (bytes) => collect(bytes, true));
+    child.stderr.on("data", (bytes) => collect(bytes, false));
+    child.on("error", () => finish(unavailable()));
+    child.stdin.on("error", () => { terminate(); finish(failure()); });
+    child.on("close", (code) => {
+      if (settled) return;
+      if (code !== 0) { finish(failure()); return; }
+      try { finish(null, JSON.parse(output)); } catch { finish(failure()); }
+    });
+    child.stdin.end(JSON.stringify(request), "utf8");
+  });
+}

package/src/client/analysis.d.ts

@@ -0,0 +1,4 @@
+import type { JsonValue } from '../ui/index.js';
+export interface AnalysisRequest { operation: 'list' | 'get' | 'execute'; input: { [key: string]: JsonValue } }
+export function assertAnalysisRequest(value: unknown): AnalysisRequest;
+export function createAnalysisClient(invoke: (operation: string, input: AnalysisRequest) => Promise<JsonValue>): (request: AnalysisRequest) => Promise<JsonValue>;

package/src/client/analysis.js

@@ -0,0 +1,12 @@
+import { assertJsonValue } from '../ui/validation.js';
+
+/** 当前成员的受控只读分析；不接受身份、URL 或任意执行代码。 */
+export function assertAnalysisRequest(request) {
+  assertJsonValue(request, { maxBytes: 64 * 1024, maxEntries: 4000 });
+  if (!request || Array.isArray(request) || typeof request !== 'object' || Object.keys(request).some(key => !['operation', 'input'].includes(key))
+      || !['list', 'get', 'execute'].includes(request.operation) || !request.input || Array.isArray(request.input) || typeof request.input !== 'object') throw new Error('runtime_analysis_request_invalid');
+  return request;
+}
+export function createAnalysisClient(invoke) {
+  return request => invoke('analysis', assertAnalysisRequest(request));
+}

package/src/client/destinations.d.ts

@@ -0,0 +1,25 @@
+/** 有界字符串业务参数；不包含宿主身份，不授予记录访问权。 */
+export type PageParams = Readonly<Record<string, string>>;
+
+export interface AppPageDestination {
+  readonly kind: 'app-page';
+  /** 当前 App 内的 Page slug。 */
+  readonly pageSlug: string;
+  readonly params?: PageParams;
+}
+
+export interface RecordDestination {
+  readonly kind: 'record';
+  /** 标准对象复数 slug，或当前 Workspace 可见的 custom_* 公开 API slug。 */
+  readonly object: string;
+  readonly recordId: string;
+}
+
+export type AppDestination = AppPageDestination | RecordDestination;
+
+export function assertAppDestination(value: unknown): Readonly<AppDestination>;
+export function assertPageParams(value: unknown): PageParams;
+export const Destinations: Readonly<{
+  appPage(pageSlug: string, options?: { params?: PageParams }): Readonly<AppPageDestination>;
+  record(input: { object: string; recordId: string }): Readonly<RecordDestination>;
+}>;

package/src/client/destinations.js

@@ -0,0 +1,70 @@
+const PAGE_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const OBJECT_SLUG = /^[a-z][a-z0-9_]{0,99}$/;
+const STANDARD_RECORD_OBJECTS = new Set([
+  'accounts',
+  'contacts',
+  'opportunities',
+  'tasks',
+  'activities',
+]);
+
+const fail = () => { throw new TypeError('runtime_destination_invalid'); };
+const only = (value, keys) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some(key => !keys.includes(key))) fail();
+};
+
+/** 参数是地址中的不可信业务输入，不承载宿主身份或授权。 */
+export function assertPageParams(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail();
+  const keys = Object.keys(value).sort();
+  if (keys.length > 16) fail();
+  const entries = keys.map(key => {
+    const item = value[key];
+    if (!/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key)
+      || ['__proto__', 'prototype', 'constructor'].includes(key)
+      || typeof item !== 'string' || [...item].length > 512
+      || /[\p{Cc}\p{Cs}]/u.test(item)) fail();
+    return [key, item];
+  });
+  const params = Object.fromEntries(entries);
+  if (new TextEncoder().encode(JSON.stringify(params)).byteLength > 2048) fail();
+  return Object.freeze(params);
+}
+
+export function assertAppDestination(value) {
+  only(value, value?.kind === 'app-page' ? ['kind', 'pageSlug', 'params'] : value?.kind === 'record'
+    ? ['kind', 'object', 'recordId'] : []);
+  if (value.kind === 'app-page') {
+    if (typeof value.pageSlug !== 'string' || value.pageSlug.length > 64 || !PAGE_SLUG.test(value.pageSlug)) fail();
+    const params = value.params === undefined ? undefined : assertPageParams(value.params);
+    return Object.freeze({ kind: 'app-page', pageSlug: value.pageSlug,
+      ...(params && Object.keys(params).length ? { params } : {}),
+    });
+  }
+  if (value.kind === 'record') {
+    const custom = typeof value.object === 'string' && value.object.startsWith('custom_');
+    if (
+      typeof value.object !== 'string'
+      || !OBJECT_SLUG.test(value.object)
+      || (!STANDARD_RECORD_OBJECTS.has(value.object) && !custom)
+      || typeof value.recordId !== 'string'
+      || value.recordId.length < 1
+      || value.recordId.length > 160
+    ) fail();
+    return Object.freeze({ kind: 'record', object: value.object, recordId: value.recordId });
+  }
+  fail();
+}
+
+export const Destinations = Object.freeze({
+  appPage(pageSlug, options) {
+    if (options !== undefined) only(options, ['params']);
+    return assertAppDestination({ kind: 'app-page', pageSlug, ...(options?.params === undefined ? {} : { params: options.params }) });
+  },
+  record(input) {
+    only(input, ['object', 'recordId']);
+    return assertAppDestination({ kind: 'record', object: input.object, recordId: input.recordId });
+  },
+});

package/src/client/documents.d.ts

@@ -0,0 +1,21 @@
+import type { JsonValue } from '../ui/index.js';
+/** 受限JSON Schema；服务端校验完整白名单、数组/字符串上限与绑定。 */
+export type RestrictedInputSchema = Readonly<Record<string, JsonValue>>;
+export interface PreparePdfTemplateInput {
+  inputSchema: RestrictedInputSchema;
+  /** 本次制作的有界、已授权试填数据，不保存到App模板配置。 */
+  sampleData: Readonly<Record<string, JsonValue>>;
+}
+export interface OpenPdfDocumentInput {
+  /** opaque Job用途引用；不能传URL、附件ID或PDF字节。 */
+  documentRef: string;
+  action: 'open' | 'download';
+}
+export type PreparedPdfTemplate = Readonly<{templateFileRef: string}>;
+export type OpenPdfDocumentResult = Readonly<{status: 'opened' | 'started' | 'cancelled'}>;
+export function assertDocumentInput(operation: string, input: unknown): PreparePdfTemplateInput | OpenPdfDocumentInput;
+export function assertDocumentResult(operation: string, value: unknown): PreparedPdfTemplate | OpenPdfDocumentResult | null;
+export function createDocumentClient(invoke: (operation: string, input: unknown) => Promise<unknown>): {
+  preparePdfTemplate(input: PreparePdfTemplateInput): Promise<PreparedPdfTemplate | null>;
+  openPdfDocument(input: OpenPdfDocumentInput): Promise<OpenPdfDocumentResult>;
+};

package/src/client/documents.js

@@ -0,0 +1,39 @@
+const invalid = () => { throw new Error('runtime_document_input_invalid'); };
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const ref = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,79}$/.test(value);
+function bounded(value, depth = 0) {
+  if (depth > 12) invalid();
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number' && Number.isFinite(value)) return;
+  if (Array.isArray(value)) { if (value.length > 1000) invalid(); for (const item of value) bounded(item, depth + 1); return; }
+  if (!object(value)) invalid();
+  for (const [key, item] of Object.entries(value)) {
+    if (['__proto__', 'prototype', 'constructor'].includes(key)) invalid();
+    bounded(item, depth + 1);
+  }
+}
+export function assertDocumentInput(operation, input) {
+  if (!object(input)) invalid();
+  if (operation === 'openPdfDocument') {
+    if (Object.keys(input).some(key => !['documentRef', 'action'].includes(key)) || !ref(input.documentRef)
+      || !['open', 'download'].includes(input.action)) invalid();
+  } else if (operation === 'preparePdfTemplate') {
+    if (Object.keys(input).some(key => !['inputSchema', 'sampleData'].includes(key)) || !object(input.inputSchema)
+      || input.inputSchema.type !== 'object' || input.inputSchema.additionalProperties !== false || !object(input.sampleData)) invalid();
+    bounded(input);
+    if (new TextEncoder().encode(JSON.stringify(input)).length > 512 * 1024) invalid();
+  } else invalid();
+  // 快照避免App在异步交互期间原位改动请求。
+  return JSON.parse(JSON.stringify(input));
+}
+export function assertDocumentResult(operation, value) {
+  if (operation === 'preparePdfTemplate' && value === null) return null;
+  if (!object(value) || Object.keys(value).length !== 1) invalid();
+  if (operation === 'preparePdfTemplate' ? !ref(value.templateFileRef) : !['opened', 'started', 'cancelled'].includes(value.status)) invalid();
+  return Object.freeze({ ...value });
+}
+export function createDocumentClient(invoke) {
+  return Object.freeze(Object.fromEntries(['preparePdfTemplate', 'openPdfDocument'].map(operation => [operation,
+    input => invoke(operation, assertDocumentInput(operation, input)).then(value => assertDocumentResult(operation, value)),
+  ])));
+}

package/src/client/external-url.js

@@ -0,0 +1,9 @@
+/** SDK 与 Host 重复验证同一有界 HTTPS 合同，不接受浏览器自动纠正的危险写法。 */
+export function assertExternalUrl(value) {
+  if (typeof value !== 'string' || !value.length || value.length > 2048 || value !== value.trim()
+    || /[\p{Cc}\\]/u.test(value) || !/^https:\/\//i.test(value)) throw new Error('runtime_external_url_invalid');
+  let url;
+  try { url = new URL(value); } catch { throw new Error('runtime_external_url_invalid'); }
+  if (url.protocol !== 'https:' || !url.hostname || url.username || url.password) throw new Error('runtime_external_url_invalid');
+  return url.href;
+}