@aikdna/kdna-web-客户端

浏览器- 安全 KDNA 工具 .

状态 : 实验性出版的浏览器集成 : 坐标。 这不是一个稳定的浏览器 runtime 或一个完整的主机政策 .

文件选择、元数据检查、上传到服务器以及 负载计划国家管理——从未在 浏览器.

设计限制 : 此软件包从不解密任何东西。 写着 a 的公开元数据 .kdna 文档和代表全部敏感 操作到服务器运行 @aikdna/kdna-web-服务器。 。 。 .

新到KDNA吗 KDNA 核心

需要一个服务器侧适配器吗? → @aikdna/kdna-web-服务器

需要反应组件吗 ? → @aikdna/kdna-反应

安装

npm install @aikdna/kdna-web-client

无对等依存. 浏览器捆绑中的Node.js内置.

快开始

import { readKDNAMetadata, uploadKDNA, KDNALoadPlanManager } from '@aikdna/kdna-web-client'

// 1. Let the user pick a file
const input = document.createElement('input')
input.type = 'file'
input.accept = '.kdna'
input.onchange = async () => {
  const file = input.files[0]

  // 2. Read public metadata (no server round-trip, no decryption)
  const meta = await readKDNAMetadata(file)
  console.log(meta.domain, meta.version, meta.encrypted)

  // 3. Upload to your server and get a fileId
  const { fileId } = await uploadKDNA(file, '/api/kdna/inspect')

  // 4. Manage the load-plan flow
  const manager = new KDNALoadPlanManager('/api/kdna')
  const plan = await manager.planLoad(fileId)

  if (plan.canProceed) {
    const result = await manager.load(fileId, { profile: 'compact' })
    console.log(result.capsule.context)
  } else {
    console.log('Missing:', plan.missing)  // e.g. ['enter_password']
  }
}
input.click()

文件拾取器为此操作建立明确的用户选择. 若为 应用程序记得文件为附件, 它必须准确无误 身份、文摘、范围和理由可见,并提供禁用/开关/回滚 控制系统。 仅上传存储并不能授权未来的任务.

API 参考

readKDNAMetadata(file)

从 a 读取公共显示字段 .kdna File 没有对象 正在上传或执行任何解密.

const meta = await readKDNAMetadata(file)

回返情况:

{
  domain:      string         // e.g. "kdna:aikdna:laozi-wuwei"
  version:     string         // e.g. "1.2.0"
  title:       string | null
  description: string | null
  encrypted:   boolean
  profiles:    string[]       // available load profiles
  fileSize:    number         // bytes
}

默认 maxSizeBytes 是 10 MiB,与官方 Web 服务器对齐. 当应用程序需要更紧的内存时, 传递一个较小的正整数 预算。 公示单独立限定为一米B.

掷出 KDNAFileSizeError 如果文件太大. 掷出 KDNAFormatError 如果文件无效 .kdna 集装箱.

uploadKDNA(file, endpoint)

上传 a .kdna File 到终点( 通常为 /api/kdna/inspect并返回 fileId 由服务器指定.

const { fileId, inspect } = await uploadKDNA(file, '/api/kdna/inspect')

回返情况:

{
  fileId:   string    // opaque ID — pass to plan-load and load
  inspect:  object    // bounded public inspect fields only
}

客户只保留 fileId,公共资产元数据,默认配置, 可选配置文件, 以及公共负载计划 。 内部服务器存储元数据 路径和未知字段被丢弃.

掷出 KDNAUploadError 如果请求失败或服务器返回非200 状态。 公用错误包含一个固定的本地信件, HTTP 状态和 a 当服务器提供一个时, 语言学 KDNA 错误代码 。 服务器错误消息 和反应机构从未附加; 兼容性 response 属性 总是 null。 。 。 .

KDNALoadPlanManager

为单个文件驱动负载计划流的状态类.

const manager = new KDNALoadPlanManager(baseUrl)

planLoad(fileId, context?)

const plan = await manager.planLoad('abc123', {
  hasPassword: false,
  entitlementToken: null,
})

回返情况:

{
  canProceed:   boolean
  missing:      string[]    // e.g. ['enter_password']
  requirements: {
    password:   { required: boolean, hint: string | null }
    licenseKey: { required: boolean }
  }
}

load(fileId, options)

const result = await manager.load('abc123', {
  profile:          'compact',
  password:         '...',   // only if required
  entitlementToken: { status: 'active' }, // signed entitlement from /activate, only if required
})

返回来自 capsule 仅在 capsule 完成完全运行时间 Capsule 计划关闭 锁定在经审计的 KDNA 核心承诺。 未知的顶级服务器字段被丢弃 . 代理造型出品是跑步相机; content 是一个网络用户界面 方便别名 capsule.context数字 :

{
  domain: "kdna:aikdna:laozi-wuwei"
  version: "0.1.1"
  judgmentVersion: "0.1.0"
  profile: "compact"
  content: object
  capsule: {
    type: "kdna.runtime-capsule"
    contract_version: "0.1.0"
    asset: object
    digests: object
    signature: object
    access: "public" | "licensed" | "remote"
    profile: "index" | "compact" | "scenario" | "full"
    context: object
    trace: object
  }
}

KDNAFileSizeError

被丢弃 readKDNAMetadata 当文件超过配置时 最大尺寸.

KDNAFormatError

被丢弃 readKDNAMetadata 当文件无效时 .kdna 头曰.

KDNAUploadError

被丢弃 uploadKDNA 当 HTTP 请求失败时 .

KDNALoadError

在请求失败或返回时按装入计划投放并装入呼叫 运行时间 Capsule 无效 。 一样 KDNAUploadError上游反应机构 而信息永远不会被曝光.

安保模式

见 文件/安全模型.md。 。 。 .

短版本 :

• 此包只读取容器头和公开 kdna.json 显示 在记忆中。 它从不解析 解密 或暴露 payload.kdnab; 装入为 授权给官方服务器侧工具链.
• 密码和签名的权利记录或信使作为 参数到 manager.load() 并直接输入服务器 终点 它们不保存在任何对象属性或模块级别 变量。 原始许可密钥属于您的激活端点, 不是 /load。 。 。 .
• 这个软件包没有Node.js内建依赖性. 完全运行 在浏览器的安全模式内.
• JSON响应被读取为受限UTF-8,必须是JSON对象. 错误 有效载荷被降低到状态,并具有犬类编码;成功有效载荷是: 投射到有记录的公众表面.

消费痕迹

parseJudgmentTrace, (中文(简体) ), judgmentTraceView和无依赖性 JudgmentTraceViewer 验证完整的判决 Trace 计划关闭 对同一经审计的KDNA核心承诺,因未知或不一致而未结案 巢所证. 他们保留了Capsule交付,主机执行, 语义消耗, 和符合作为单独的证据。 一个相互关联的主机 答复不能证明一个模型对判断有敏锐的消耗,或 答案是符合它的.

浏览器客户端应当收到一个可信赖的应用程序端点的跟踪. 浏览器检查仅证明方案符合性; 加密和语义 符合性仍然是服务器方面的KDNA核心责任。 追踪是永远不会 允许读取受保护的有效载荷.

相关软件包

许可证

Apache 2.0 — 见 自由主义。 。 。 .