# 息壤

**Repository Path**: jianmu-dev/xirang

## Basic Information

- **Project Name**: 息壤
- **Description**: 息壤提供定义引用、普通参数解析、受控凭据使用和独立表达式计算的公共代码。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-03
- **Last Updated**: 2026-10-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 息壤 / Xirang

**源码公开，非商业使用免费，商业使用须另行授权。** 详见[完整许可协议](LICENSE)。

息壤是供产品在自身进程中使用的 Go 公共库，提供定义引用、普通参数解析、受控凭据使用和独立表达式计算。产品负责数据来源、授权、存储、审计和交付；本仓库不提供独立产品服务或数据库。

源码仓库：[Gitee / jianmu-dev/xirang](https://gitee.com/jianmu-dev/xirang)。Go 版本要求和依赖版本以 [go.mod](go.mod) 为准。

## 文档导航

| 文档 | 内容 |
|---|---|
| [整体设计](docs/design.md) | 包职责、调用过程、Credential / Envelope、限制与产品责任 |
| [参数设计](docs/parameter-design.md) | 数据类型、字段语义、绑定方式及完整 JSON 示例 |
| [表达式设计](docs/expression-design.md) | JS/TS 契约、使用示例、数据边界、取消和限额 |
| [表达式历史验证](docs/expression-validation/README.md) | 2026-10-07 的 Deno 对照、负载观察和原始证据 |

前三份文档描述本仓库的当前实现。历史验证只证明所记录版本和环境中的结果；其他产品的接入状态与验收结果以各自仓库为准。

## 公开包

| 包 | 职责 | 主要入口 |
|---|---|---|
| `xirang/definition` | 定义的精确引用、key/version 语法与内容摘要 | `Ref`、`Ref.Validate`、`Digest` |
| `xirang/parameter` | 普通参数绑定、默认值、Schema、字段语义和敏感标记 | `DefinitionVersion`、`NewParameterRuntime`、`Resolve`、`ValidateInstance` |
| `xirang/credential` | 凭据契约引用、授权后的短期明文使用与清理 | `ContractRefs`、`WithPlaintext` |
| `xirang/credential/envelope` | 显式 AAD 的 AES-256-GCM 信封加密 | `KeyProvider`、`Format`、`NewCipher`、`Encrypt/Decrypt/Rewrap` |
| `xirang/expression` | 同步表达式契约、敏感输入拒绝与结构化错误 | `Evaluator`、`Request`、`Input`、`Result`、`Error` |
| `xirang/expression/js` | 独立 Sobek VM 中的 JS/TS 求值 | `Options`、`NewEvaluator`、`Evaluate` |

普通 Parameter 不取密、不解密，继续拒绝 `expression` 绑定。Expression 单独接收已准备好的非敏感输入，产品负责前置授权、输入物化和结果的业务校验。Credential 的密码学接口不代替产品授权；`WithPlaintext` 依靠产品提供的授权回调。

## 本地接入

当前模块声明为 `module xirang`，通过本地 `replace` 消费。以调用方和息壤位于同一父目录为例，在调用方的 `go.mod` 中加入：

```go
require xirang v0.0.0

replace xirang => ../xirang
```

`v0.0.0` 是本地占位版本。替换路径必须相对调用方的 `go.mod` 调整；独立构建的子模块也要配置自己的替换，Go 不继承依赖模块里的 `replace`。当前模块路径不能直接用于远程 `go get`。

本地替换读取工作区当前文件，不能固定到某个 Git 提交。复现或验证时应同时记录息壤提交号与未提交差异。正式发布需另外确定可远程解析的模块路径和版本。

## 最小参数示例

下面是只使用合成受信测试契约的例子。真实产品应先解析受信定义，核对精确引用、checksum、当前可用状态和调用权限，再转换为 `DefinitionVersion`。收到对象或看到 `VersionPublished` 本身不代表契约已获得运行许可。

```go
package main

import (
    "context"
    "fmt"
    "time"

    "xirang/parameter"
)

func main() {
    // 固定的受信测试装配，不从用户输入获取契约。
    contract := parameter.DefinitionVersion{
        Version: "1.0.0",
        Status: parameter.VersionPublished,
        Schema: map[string]any{
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "additionalProperties": false,
            "required": []any{"name"},
            "properties": map[string]any{
                "name": map[string]any{"type": "string"},
                "limit": map[string]any{"type": "integer", "default": 3},
            },
        },
        Semantics: map[string]any{},
        AllowedBindingKinds: map[string][]string{
            "/name": {"literal"},
            "/limit": {"literal"},
        },
    }
    runtime, err := parameter.NewParameterRuntime(nil, nil)
    if err != nil {
        panic(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), time.Second)
    defer cancel()
    result := runtime.Resolve(ctx, contract, map[string]any{
        "/name": map[string]any{"kind": "literal", "value": "synthetic"},
    }, parameter.RuntimeContext{})
    if !result.Valid {
        panic("synthetic parameter validation failed")
    }
    // 仅展示本例已知的非敏感字段，不能直接记录整个 result。
    fmt.Println(result.Materialized["name"], result.Materialized["limit"])
}
```

`DefinitionVersion`、`Ref` 和 JSON 兼容值可以通过 `encoding/json` 完成编码/读取往返。它们不是新的持久化协议；产品自行拥有保存格式及精确契约来源。没有 Form 也可解析，默认值只补缺失字段，不替换显式 null 或显式绑定。

要解析本地引用，实现 `RefResolver` 的 `Scheme/Validate/Resolve` 并传给构造函数；selector 对应 `Source/Validate/Resolve`。resolver 由受信程序注册，负责上下文权限、允许的数据来源、返回限额及取消；不能将用户指定的任意路径或网络地址直接当成读取权限。`RuntimeContext` 应由产品装配，不把用户提交的身份当成已认证主体。

模拟输出用 `parameter.ValidateInstance(outputSchema, output)` 验证已物化的 JSON 数据；不要再次把输出对象传给 `Resolve` 当作 Binding。输出中的 `kind`、`value` 等键仍然只是数据。

## 使用边界

- `Ref.Validate` 只检查共性语法；定义来源、checksum、可用性和使用权限由产品核对。
- 参数结果的敏感标记不会删除 `Values` 或 `Materialized` 中的真实值。日志、API、持久化和展示必须由产品脱敏。
- `WithPlaintext` 先授权，再打开并消费 1～16,384 字节的明文，返回时清理打开的缓冲区；产品负责其他副本。
- `Rewrap` 认证 wrapped DEK 与 AAD，不认证业务 ciphertext；成功不代表凭据内容通过验证。
- JS/TS 只接受同步表达式和严格 JSON-like 结果。进程内超时和输入输出限额不提供独立的硬内存隔离，不适合作为不可信代码的进程隔离边界。

## 验证入口

在仓库根目录执行，需要满足 `go.mod` 的本地 Go 工具链和依赖：

```bash
export GOTOOLCHAIN=local GOWORK=off
export GOCACHE=/tmp/xirang-go-cache

go test -mod=readonly -count=1 ./...
go test -mod=readonly -race -count=1 ./...
go vet -mod=readonly ./...
go build -mod=readonly ./...
git diff --check
```

这些检查覆盖公共库和验证工具。Deno 真实对照、性能观察及其复验前提见[历史验证报告](docs/expression-validation/report.md)，产品授权与端到端业务流程须在相应产品中另行验证。