@heybox/hb-sdk-protocol 0.9.1-alpha.1 → 0.9.1-alpha.11

package/src/index.ts

@@ -1,9 +0,0 @@
-export * from './bridge';
-export * from './capabilities';
-export * from './constants';
-export * from './guards';
-export * from './local-dev-grant';
-export * from './native-host';
-export * from './payloads';
-export * from './permission-catalog';
-export * from './permissions';

package/src/local-dev-grant.ts

@@ -1,141 +0,0 @@
-import { MINI_PROGRAM_PERMISSION_KEYS, type MiniProgramPermissionKey } from './permission-catalog';
-import { parseMiniProgramRuntimePermissions, type MiniProgramRuntimePermissionsSnapshot } from './permissions';
-
-/** 仅供开发工具和 Host 使用；新增权限必须单独评估，不能从平台审批目录自动推导。 */
-export const LOCAL_DEV_GRANT_PERMISSION_KEYS = ['network', 'companion'] as const;
-export type MiniProgramLocalDevPermissionKey = (typeof LOCAL_DEV_GRANT_PERMISSION_KEYS)[number];
-export type MiniProgramLocalDevGrantEntry =
-  | { key: 'network'; status: 'enabled'; config: { useOfficialDomain: false } }
-  | { key: 'companion'; status: 'enabled'; config: Record<string, never> };
-
-/** CLI-owned Dev Context 合同，不属于小程序业务 API 或线上批准快照。 */
-export interface MiniProgramLocalDevGrant {
-  schema_version: 1;
-  revision: number;
-  entries: MiniProgramLocalDevGrantEntry[];
-}
-
-/** 调用方已校验的本地声明；不存在的权限不会从 grant 获得授权。 */
-export type MiniProgramLocalDevPermissionDeclarations = Partial<
-  Record<MiniProgramPermissionKey, { enabled: boolean; useOfficialDomain?: boolean }>
->;
-
-export type ParsedMiniProgramLocalDevGrant =
-  | { valid: true; grant: MiniProgramLocalDevGrant }
-  | { valid: false; grant?: undefined };
-
-/**
- * 严格解析本地 grant。任何未知字段、重复权限或非法配置都拒绝整份输入。
- * 只校验数据合同；票据、身份、摘要、过期时间和 CLI lease 必须由 Host 另行验证。
- */
-export function parseMiniProgramLocalDevGrant(value: unknown): ParsedMiniProgramLocalDevGrant {
-  if (
-    !hasExactFields(value, ['schema_version', 'revision', 'entries']) ||
-    value.schema_version !== 1 ||
-    typeof value.revision !== 'number' ||
-    !Number.isSafeInteger(value.revision) ||
-    value.revision < 0 ||
-    !Array.isArray(value.entries) ||
-    value.entries.length > LOCAL_DEV_GRANT_PERMISSION_KEYS.length
-  ) return { valid: false };
-
-  const entries: MiniProgramLocalDevGrantEntry[] = [];
-  const seen = new Set<string>();
-  for (const entry of value.entries) {
-    if (!hasExactFields(entry, ['key', 'status', 'config']) || entry.status !== 'enabled') return { valid: false };
-    if (typeof entry.key !== 'string' || seen.has(entry.key)) return { valid: false };
-    seen.add(entry.key);
-    if (entry.key === 'network') {
-      if (!hasExactFields(entry.config, ['useOfficialDomain']) || entry.config.useOfficialDomain !== false) return { valid: false };
-      entries.push({ key: 'network', status: 'enabled', config: { useOfficialDomain: false } });
-    } else if (entry.key === 'companion') {
-      if (!hasExactFields(entry.config, [])) return { valid: false };
-      entries.push({ key: 'companion', status: 'enabled', config: {} });
-    } else {
-      return { valid: false };
-    }
-  }
-  entries.sort((a, b) => LOCAL_DEV_GRANT_PERMISSION_KEYS.indexOf(a.key) - LOCAL_DEV_GRANT_PERMISSION_KEYS.indexOf(b.key));
-  return { valid: true, grant: { schema_version: 1, revision: value.revision, entries } };
-}
-
-/**
- * 从已校验声明生成批准缺口。Companion 默认不符合资格，由 CLI 确认平台、产物与摘要后显式加入。
- * 空 entries 可保留 revision，不能作为存在临时权限的判断依据。
- */
-export function createMiniProgramLocalDevGrant(options: {
-  declaredPermissions: MiniProgramLocalDevPermissionDeclarations;
-  runtimePermissions: unknown;
-  revision: number;
-  eligiblePermissionKeys?: readonly MiniProgramLocalDevPermissionKey[];
-}): MiniProgramLocalDevGrant {
-  if (!Number.isSafeInteger(options.revision) || options.revision < 0) throw new Error('本地调试权限 revision 必须是非负安全整数');
-  const approvals = parseMiniProgramRuntimePermissions(options.runtimePermissions);
-  const eligible = new Set(options.eligiblePermissionKeys ?? ['network']);
-  const entries: MiniProgramLocalDevGrantEntry[] = [];
-  for (const key of LOCAL_DEV_GRANT_PERMISSION_KEYS) {
-    if (!eligible.has(key) || options.declaredPermissions[key]?.enabled !== true) continue;
-    if (approvals.valid && approvals.permissions[key]?.status === 'enabled') continue;
-    entries.push(key === 'network'
-      ? { key, status: 'enabled', config: { useOfficialDomain: false } }
-      : { key, status: 'enabled', config: {} });
-  }
-  return { schema_version: 1, revision: options.revision, entries };
-}
-
-/**
- * 线上基线先与本地声明求交，再补齐临时权限，返回与输入脱离的普通 Runtime 快照。
- * 调用方只可在当前 Dev Session 已验证且用户接受后传入 grant；本函数不证明其可信来源。
- * 非法 grant 整体降权到基线，已批准配置不会被临时配置覆盖。
- */
-export function composeLocalDevRuntimePermissions(options: {
-  declaredPermissions: MiniProgramLocalDevPermissionDeclarations;
-  runtimePermissions: unknown;
-  localDevGrant?: unknown;
-}): {
-  runtimePermissions: MiniProgramRuntimePermissionsSnapshot;
-  temporaryPermissionKeys: MiniProgramLocalDevPermissionKey[];
-  grantValid: boolean;
-} {
-  const baseline = parseMiniProgramRuntimePermissions(options.runtimePermissions);
-  const parsed = parseMiniProgramLocalDevGrant(options.localDevGrant);
-  const permissions = baseline.valid ? baseline.permissions : {};
-  for (const key of MINI_PROGRAM_PERMISSION_KEYS) {
-    if (options.declaredPermissions[key]?.enabled !== true) {
-      delete permissions[key];
-    } else if (key === 'network' && permissions.network) {
-      permissions.network.config.useOfficialDomain = permissions.network.status === 'enabled'
-        && permissions.network.config.useOfficialDomain === true
-        && options.declaredPermissions.network?.useOfficialDomain === true;
-    }
-  }
-  const temporaryPermissionKeys: MiniProgramLocalDevPermissionKey[] = [];
-  if (parsed.valid) {
-    for (const entry of parsed.grant.entries) {
-      if (options.declaredPermissions[entry.key]?.enabled !== true || permissions[entry.key]?.status === 'enabled') continue;
-      permissions[entry.key] = entry;
-      temporaryPermissionKeys.push(entry.key);
-    }
-  }
-  const revision = isRecord(options.runtimePermissions) && typeof options.runtimePermissions.revision === 'number'
-    && Number.isSafeInteger(options.runtimePermissions.revision) && options.runtimePermissions.revision >= 0
-    ? options.runtimePermissions.revision : undefined;
-  return {
-    runtimePermissions: {
-      schema_version: 1,
-      ...(revision === undefined ? {} : { revision }),
-      entries: MINI_PROGRAM_PERMISSION_KEYS.flatMap((key) => permissions[key] ? [permissions[key]!] : []),
-    },
-    temporaryPermissionKeys,
-    grantValid: parsed.valid,
-  };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function hasExactFields(value: unknown, fields: readonly string[]): value is Record<string, unknown> {
-  return isRecord(value) && Object.keys(value).length === fields.length
-    && fields.every((field) => Object.prototype.hasOwnProperty.call(value, field));
-}

package/src/native-host-contract.generated.ts

@@ -1,60 +0,0 @@
-/** 由 scripts/generate-native-host-contract.mjs 生成，请勿手改。 */
-export const MINI_PROGRAM_NATIVE_HOST_PROTOCOL_VERSION = 1 as const;
-export const MINI_PROGRAM_NATIVE_HOST_CONTRACT_REVISION = 1 as const;
-export const MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES = 65536 as const;
-export const MINI_PROGRAM_NATIVE_OPERATIONS = {
-  "system": [
-    "describe"
-  ],
-  "network": [
-    "open",
-    "read",
-    "release",
-    "transfer"
-  ],
-  "files": [
-    "create",
-    "remove",
-    "exists",
-    "openRead",
-    "openWrite",
-    "read",
-    "release",
-    "write",
-    "stat",
-    "list",
-    "pickFiles",
-    "pickDirectory",
-    "saveFile"
-  ]
-} as const;
-export const MINI_PROGRAM_NATIVE_HOST_DESCRIPTION = {
-  "protocolVersion": 1,
-  "contractRevision": 1,
-  "operations": {
-    "system": [
-      "describe"
-    ],
-    "network": [
-      "open",
-      "read",
-      "release",
-      "transfer"
-    ],
-    "files": [
-      "create",
-      "remove",
-      "exists",
-      "openRead",
-      "openWrite",
-      "read",
-      "release",
-      "write",
-      "stat",
-      "list",
-      "pickFiles",
-      "pickDirectory",
-      "saveFile"
-    ]
-  }
-} as const;

package/src/native-host-contract.source.json

@@ -1,479 +0,0 @@
-{
-  "schema": "heybox-mini-program-native-host",
-  "protocolVersion": 1,
-  "contractRevision": 1,
-  "chunkMaxBytes": 65536,
-  "operations": {
-    "system": [
-      "describe"
-    ],
-    "network": [
-      "open",
-      "read",
-      "release",
-      "transfer"
-    ],
-    "files": [
-      "create",
-      "remove",
-      "exists",
-      "openRead",
-      "openWrite",
-      "read",
-      "release",
-      "write",
-      "stat",
-      "list",
-      "pickFiles",
-      "pickDirectory",
-      "saveFile"
-    ]
-  },
-  "cases": [
-    {
-      "name": "system-describe",
-      "valid": true,
-      "request": {
-        "requestId": "req_describe",
-        "domain": "system",
-        "operation": "describe"
-      },
-      "messages": [
-        {
-          "requestId": "req_describe",
-          "type": "result",
-          "payload": {
-            "protocolVersion": 1,
-            "contractRevision": 1,
-            "operations": {
-              "system": [
-                "describe"
-              ],
-              "network": [
-                "open",
-                "read",
-                "release",
-                "transfer"
-              ],
-              "files": [
-                "create",
-                "remove",
-                "exists",
-                "openRead",
-                "openWrite",
-                "read",
-                "release",
-                "write",
-                "stat",
-                "list",
-                "pickFiles",
-                "pickDirectory",
-                "saveFile"
-              ]
-            }
-          }
-        }
-      ]
-    },
-    {
-      "name": "network-open",
-      "valid": true,
-      "request": {
-        "requestId": "req_open",
-        "domain": "network",
-        "operation": "open",
-        "payload": {
-          "purpose": "download",
-          "url": "https://cdn.example.test/file.zip",
-          "method": "GET",
-          "timeoutMs": 30000
-        }
-      },
-      "messages": [
-        {
-          "requestId": "req_open",
-          "type": "result",
-          "payload": {
-            "status": 200,
-            "statusText": "OK",
-            "headers": {
-              "content-length": [
-                "4"
-              ]
-            },
-            "resourceId": "resource_1"
-          }
-        }
-      ]
-    },
-    {
-      "name": "network-read-chunk",
-      "valid": true,
-      "request": {
-        "requestId": "req_read",
-        "domain": "network",
-        "operation": "read",
-        "payload": {
-          "resourceId": "resource_1",
-          "maxBytes": 65536
-        }
-      },
-      "messages": [
-        {
-          "requestId": "req_read",
-          "type": "result",
-          "payload": {
-            "resourceId": "resource_1",
-            "data": "dGVzdA==",
-            "byteLength": 4,
-            "eof": true
-          }
-        }
-      ]
-    },
-    {
-      "name": "network-transfer-progress",
-      "valid": true,
-      "request": {
-        "requestId": "req_transfer",
-        "domain": "network",
-        "operation": "transfer",
-        "payload": {
-          "resourceId": "resource_1",
-          "target": {
-            "scope": "sandbox",
-            "kind": "file",
-            "relativePath": "downloads/file.zip"
-          },
-          "mode": "upsert",
-          "maxBytes": 2147483648,
-          "expectedBytes": 4
-        }
-      },
-      "messages": [
-        {
-          "requestId": "req_transfer",
-          "type": "progress",
-          "payload": {
-            "resourceId": "resource_1",
-            "loaded": 4
-          }
-        },
-        {
-          "requestId": "req_transfer",
-          "type": "result",
-          "payload": {
-            "committedBytes": 4
-          }
-        }
-      ]
-    },
-    {
-      "name": "files-open-read",
-      "valid": true,
-      "request": {
-        "requestId": "req_file_open",
-        "domain": "files",
-        "operation": "openRead",
-        "payload": {
-          "ref": {
-            "scope": "sandbox",
-            "kind": "file",
-            "relativePath": "data.bin"
-          },
-          "maxBytes": 8388608
-        }
-      },
-      "messages": [
-        {
-          "requestId": "req_file_open",
-          "type": "result",
-          "payload": {
-            "resourceId": "file_resource_1"
-          }
-        }
-      ]
-    },
-    {
-      "name": "files-create",
-      "valid": true,
-      "request": {
-        "requestId": "req_create",
-        "domain": "files",
-        "operation": "create",
-        "payload": {
-          "ref": {
-            "scope": "sandbox",
-            "kind": "file",
-            "relativePath": "data.bin"
-          },
-          "recursive": false,
-          "exclusive": true
-        }
-      },
-      "messages": [
-        {
-          "requestId": "req_create",
-          "type": "result"
-        }
-      ]
-    },
-    {
-      "name": "files-open-write",
-      "valid": true,
-      "request": {
-        "requestId": "req_write_open",
-        "domain": "files",
-        "operation": "openWrite",
-        "payload": {
-          "ref": {
-            "scope": "sandbox",
-            "kind": "file",
-            "relativePath": "data.bin"
-          },
-          "maxBytes": 8388608
-        }
-      },
-      "messages": [
-        {
-          "requestId": "req_write_open",
-          "type": "result",
-          "payload": {
-            "resourceId": "file_write_1"
-          }
-        }
-      ]
-    },
-    {
-      "name": "files-write-chunk",
-      "valid": true,
-      "request": {
-        "requestId": "req_write",
-        "domain": "files",
-        "operation": "write",
-        "payload": {
-          "resourceId": "file_write_1",
-          "data": "AAE=",
-          "byteLength": 2,
-          "eof": true
-        }
-      },
-      "messages": [
-        {
-          "requestId": "req_write",
-          "type": "result"
-        }
-      ]
-    },
-    {
-      "name": "files-list",
-      "valid": true,
-      "request": {
-        "requestId": "req_list",
-        "domain": "files",
-        "operation": "list",
-        "payload": {
-          "ref": {
-            "scope": "sandbox",
-            "kind": "directory",
-            "relativePath": ""
-          },
-          "limit": 1000
-        }
-      },
-      "messages": [
-        {
-          "requestId": "req_list",
-          "type": "result",
-          "payload": [
-            {
-              "kind": "file",
-              "mode": "readwrite",
-              "name": "data.bin",
-              "ref": {
-                "scope": "sandbox",
-                "kind": "file",
-                "relativePath": "data.bin"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "name": "files-read-chunk",
-      "valid": true,
-      "request": {
-        "requestId": "req_file_read",
-        "domain": "files",
-        "operation": "read",
-        "payload": {
-          "resourceId": "file_resource_1",
-          "maxBytes": 65536
-        }
-      },
-      "messages": [
-        {
-          "requestId": "req_file_read",
-          "type": "result",
-          "payload": {
-            "resourceId": "file_resource_1",
-            "data": "AAE=",
-            "byteLength": 2,
-            "eof": true
-          }
-        }
-      ]
-    },
-    {
-      "name": "cancel-race",
-      "valid": true,
-      "request": {
-        "requestId": "req_cancel",
-        "domain": "network",
-        "operation": "open",
-        "payload": {
-          "purpose": "request",
-          "url": "https://api.example.test/data",
-          "method": "GET",
-          "timeoutMs": 30000
-        }
-      },
-      "cancel": {
-        "type": "cancel",
-        "requestId": "req_cancel"
-      },
-      "messages": [
-        {
-          "requestId": "req_cancel",
-          "type": "error",
-          "error": {
-            "code": "REQUEST_FAILED",
-            "message": "请求已取消"
-          }
-        }
-      ]
-    },
-    {
-      "name": "unsupported-operation",
-      "valid": true,
-      "request": {
-        "requestId": "req_missing",
-        "domain": "files",
-        "operation": "unknown"
-      },
-      "messages": [
-        {
-          "requestId": "req_missing",
-          "type": "error",
-          "error": {
-            "code": "METHOD_FORBIDDEN",
-            "message": "当前客户端不支持该能力"
-          }
-        }
-      ]
-    },
-    {
-      "name": "invalid-shape",
-      "valid": false,
-      "request": {
-        "requestId": "",
-        "domain": "network",
-        "operation": "open"
-      }
-    },
-    {
-      "name": "oversized-chunk",
-      "valid": false,
-      "message": {
-        "requestId": "req_big",
-        "type": "result",
-        "payload": {
-          "resourceId": "resource_1",
-          "data": "",
-          "byteLength": 65537,
-          "eof": false
-        }
-      }
-    },
-    {
-      "name": "zero-nonterminal-chunk",
-      "valid": false,
-      "message": {
-        "requestId": "req_zero",
-        "type": "result",
-        "payload": {
-          "resourceId": "resource_1",
-          "data": "",
-          "byteLength": 0,
-          "eof": false
-        }
-      }
-    },
-    {
-      "name": "duplicate-terminal",
-      "valid": false,
-      "messages": [
-        {
-          "requestId": "req_dup",
-          "type": "result"
-        },
-        {
-          "requestId": "req_dup",
-          "type": "error",
-          "error": {
-            "code": "REQUEST_FAILED",
-            "message": "重复终态"
-          }
-        }
-      ]
-    },
-    {
-      "name": "late-progress",
-      "valid": false,
-      "messages": [
-        {
-          "requestId": "req_late",
-          "type": "result"
-        },
-        {
-          "requestId": "req_late",
-          "type": "progress",
-          "payload": {
-            "resourceId": "resource_1",
-            "loaded": 1
-          }
-        }
-      ]
-    },
-    {
-      "name": "cross-session-handle",
-      "valid": false,
-      "request": {
-        "requestId": "req_cross",
-        "domain": "files",
-        "operation": "stat",
-        "payload": {
-          "ref": {
-            "scope": "grant",
-            "id": "other_session_handle",
-            "kind": "file",
-            "relativePath": ""
-          }
-        }
-      }
-    },
-    {
-      "name": "redacted-error",
-      "valid": true,
-      "message": {
-        "requestId": "req_error",
-        "type": "error",
-        "error": {
-          "code": "FILE_ACCESS_DENIED",
-          "message": "文件访问被拒绝"
-        }
-      }
-    }
-  ]
-}