xk-hy-transit-go/docs/FILEAUTH.md

# FileAuth 上传凭证（FileAuth.java）

生产与 [`docs/FileAuth.java`](FileAuth.java) 中 `createUploadToken` **完全一致**（HMAC 对 **policy JSON 明文**）。

## 生产 putPolicy

```json
{"scope":"<bucket>","deadline":<unix>}
```

- `scope`：**仅 bucket 名**（如 `other-doc`），**不要** `bucket:filename`
- **无** `returnBody`
- HTTP 上传为 **§2.3.4 表单上传**：`multipart/form-data`，字段名 **`file`**，请求头 `X-Authorization: <uploadToken>`

## 生成步骤

| 步 | 说明 |
|----|------|
| 1 | 构造 putPolicy JSON（字段顺序：`scope` → `deadline`） |
| 2 | `sign = urlsafe_base64( HMAC-SHA1(secret, UTF-8(policyJSON)) )` |
| 3 | `policyB64 = urlsafe_base64( UTF-8(policyJSON) )` |
| 4 | `uploadToken = AccessKey + ':' + sign + ':' + policyB64` |

## Base64 填充

| 环境变量 | 说明 |
|----------|------|
| `FILEAUTH_B64=padded`（默认） | URL-safe Base64 **含 `=`**（对应 Java `Base64.URL_SAFE \| NO_WRAP`） |
| `FILEAUTH_B64=raw` | 无填充（联调仍 403 时可试） |

## 错误对照

| HTTP body | 含义 |
|-----------|------|
| `forbidden` | forward-go（IP / `X-Forward-Token`） |
| **`404`（纯文本）+ 403** | 已过 forward，**政务云 token 验签失败** |

## Web 调试

- `/fileauth`：生成 upload profile token
- `/upload`：A=Runner 默认 token；B=本次上传 `tokenInfo`（`scope` 应为 bucket）

实现：[`internal/fileauth/upload.go`](../internal/fileauth/upload.go)

## 上传频率

见 [`internal/hyfile/throttle.go`](../internal/hyfile/throttle.go)，`FILE_UPLOAD_MIN_INTERVAL`（默认 `10s`）。