> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 应用市场

> 发布应用，让其他 Space 发现并安装。

# 应用市场

将应用发布到应用市场后，其他 Kazzle Space 就可以发现并安装它。

## 发布的作用

发布使应用可被其他 Space 安装。用户会看到应用的名称、副标题、图标、发布者和可见性，然后将其安装到自己的 Space 中。发布需要在 `kazzle.config.ts` 中配置 `subtitle` — 应用名称下的单行标语。

已发布版本使用 `main` 分支上的最新提交。已发布应用没有单独的发布分支。

应用定义明确指定点击已安装应用时的行为：打开组件、打开嵌入式或外部 URL，或不提供启动界面。应用还可以要求 Kazzle 身份验证或接收生命周期 Webhook。

参见[发布应用](/apps/build-and-publish)了解如何发布应用。

## 安装

当用户安装已发布应用时，Kazzle 会在其 Space 中创建安装记录。安装 Space 拥有该安装及其关联的所有数据。

## 用户身份

当已登录的 Kazzle 用户打开已安装应用时，Kazzle 会向应用提供当前用户的信息。

Kazzle 附加一个短期 JWT 作为 Bearer 令牌。应用可以根据 Kazzle 的公开 JWKS 验证令牌，以读取用户、Space 和安装信息。

令牌包含以下声明：

| 声明        | 含义                       |
| --------- | ------------------------ |
| `aud`     | `kazzle:app`             |
| `iss`     | `https://api.kazzle.app` |
| `sub`     | Kazzle 用户 ID             |
| `user`    | 用户的 `{ id, email }`      |
| `space`   | 应用所在 Space 的 ID          |
| `install` | 此特定安装的 ID                |

验证示例：

```ts theme={"theme":"material-theme-darker"}
import { jwtVerify, createRemoteJWKSet } from 'jose';

const JWKS = createRemoteJWKSet(new URL('https://api.kazzle.app/auth/.well-known/jwks.json'));

async function getUserFromToken(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    audience: 'kazzle:app',
    issuer: 'https://api.kazzle.app',
  });
  return payload;
}
```

应用定义控制已发布应用的启动行为：

* `launch`：选择 `none`、命名应用组件或带有明确嵌入式或外部目标的 URL。
* `kazzleAuth`：`required` 表示仅已登录的 Kazzle 用户可打开应用；`optional` 允许在没有 Kazzle 身份的情况下打开应用。

## Webhook

如果应用定义包含 `webhookUrl`，Kazzle 会在应用被安装或卸载时向其发送 HTTP POST 请求。

`app.installed` 包含发布者后端可用于向按安装 API 进行身份验证的安装密钥：

```json theme={"theme":"material-theme-darker"}
{
  "event": "app.installed",
  "installId": "...",
  "appId": "...",
  "spaceId": "...",
  "apiUrl": "https://api.kazzle.app",
  "installKey": "kzl_inst_...",
  "user": { "id": "...", "email": "..." }
}
```

`app.uninstalled` 包含事件、安装 ID、应用 ID、Space ID 和 API URL。发布者在收到此事件后应停止使用安装密钥。

## 按安装 API

每个安装都可以调用 `https://api.kazzle.app` 上的作用域 API。调用使用安装密钥（来自发布者后端）或用户身份令牌（来自托管 UI）进行身份验证。所有操作都自动限定于该安装。

可用端点：

完整的请求和响应架构发布在 Kazzle OpenAPI 规范中，位于 `https://api.kazzle.app/openapi.json` 的以下路径下。

| 方法     | 路径                    | 描述            |
| ------ | --------------------- | ------------- |
| GET    | `/apps/secrets`       | 列出为安装存储的密钥名称  |
| GET    | `/apps/secrets/:name` | 读取密钥值         |
| PUT    | `/apps/secrets/:name` | 存储密钥值         |
| DELETE | `/apps/secrets/:name` | 删除密钥          |
| GET    | `/apps/metadata`      | 读取安装的非密钥元数据   |
| PUT    | `/apps/metadata`      | 将更新合并到安装的元数据中 |

通过此 API 写入的密钥在静止时加密，并隔离到特定安装。它们与存储在 Space 保险库中的密钥分开。

## 后续步骤

* [发布应用](/apps/build-and-publish) — 如何发布应用及之后会发生什么。