ZZD public AI gateway · zzd_public_ai_gateway_v3
Resource: 12 · Authentication and safety / 风险边界
Canonical map: https://zzd.show/docs/ai/map.json
Full handbook: https://zzd.show/llms-full.txt
REST capabilities: https://zzd.show/api/v1/capabilities/

# Authentication and safety contract

## Available now: two authorization surfaces

A third-party coding agent may operate the normal ZZD UI in a browser
the user controls. If the user is already signed in, the browser
sends the existing session automatically. The model must not read,
export, print, copy, request, or store cookies, session IDs, CSRF
tokens, passwords, payment data, private keys, or unrelated personal
information.

If sign-in is needed, let the user complete it. Do not ask the user
to paste a password or cookie into chat. UI mutations remain subject
to CSRF, ownership, rate, quota, visibility, and audit checks.

Normal authenticated browser access stays signed in without a
recurring 14-day renewal. The account page exposes device activity,
risk observations, password options and explicit logout controls;
`/machines/` retains connection, worker and task histories. Ordinary
device or network changes produce risk information, not a new device
approval barrier. Logout, explicit revocation, account restriction and
validated password/security changes remain effective. Browser storage
clearing can remove a local login independently of server policy.
Short-lived CSRF, verification codes, runtime tickets and task leases
retain their separate security lifetimes.

The supported external automation surface is HTTPS REST v1 at
`/api/v1/`. It uses user-created, scoped, revocable
developer credentials. Fetch `/api/v1/capabilities/` before use and
send the credential only in the Authorization bearer header to
`https://zzd.show`. There is no session-cookie fallback for REST.

The exact canonical Host is a security boundary. API and credential
control-plane requests sent to `www`, `code.zzd.show`, an IP address,
an alternate port, a custom domain, or another Host receive a
featureless not-found response. Never forward the bearer across an
HTTP redirect or send it to asset/CDN/editor origins.

Reuse existing approved local access first. The normal signed-in
owner credential list exposes non-secret scopes and original saved ZIP
version IDs, not tokens or encrypted package contents. The exact existing
POST download requires owner session and CSRF; metadata is not proof of
local possession or successful download. Legacy manual tokens cannot be
recovered from hashes. Retired PEM/.zzdmcp generation remains410 and does
not revoke existing valid credentials. Only first access without usable
authorization uses the existing explicit creation flow; creating,
rotating or revoking a credential still requires its original approval.
Keep secrets in a local private store, never chat/source/logs/URLs.

REST scopes are narrow and enforced per operation. Request only what
is necessary: `identity:read`, `shows:read`, `shows:write`,
`shows:publish`, `assets:write`, `baas:write`, and
`collections:write` are the current deployment scopes described by
the live capability response. Ownership is checked on every private
operation; another user's resource is returned as not found.

Never treat ZZD's legacy CLI secret, a BaaS app/service credential,
browser cookie, CSRF token, public User ID, Space ID, or Show ID as a
developer bearer credential. If the agent has neither a signed-in
browser nor a valid platform-issued developer credential, it must
report the exact missing access and use the existing login/authorization
flow only when genuinely needed. Do not make each project or thread
restart credential creation; unknown local possession is not success.

This public gateway remains unauthenticated resource discovery and a
REST adoption specification. It does not itself accept mutations or
reveal credentials. Mutation requests go only to the advertised
scoped `/api/v1/` routes or the authenticated `/mcp/v1/` adapter.

## Require explicit confirmation

- publish, unpublish, or materially change access;
- submit, buy, remove, delete, or materially reprice a Sale;
- create, rotate, or revoke a credential;
- delete a Show, asset, BaaS collection, or user data;
- run a destructive BaaS migration;
- make a change that removes paid functionality or buyer access;
- send data to a new external party or enable sensitive permissions.

## Never expose or provide

- generic shell, SQL, staff, supervisor, container, or arbitrary
  target-binding access;
- ZZD deployment topology, keys, database schema/ORM recipes, worker
  queues, internal prompts, model routing, private evidence paths, or
  production algorithms;
- authentication bypass, privilege escalation, ownership bypass,
  rate-limit bypass, vulnerability exploitation, spam, scraping of
  private data, credential collection, or hidden beacons;
- raw private Piece/upload/prompt routes as a shortcut around access.

Operate only on resources the user owns or is authorized to change.
Use least privilege, redact tool output, return stable public IDs/URLs,
and keep an understandable change report.

## Reuse authorized access / 复用已有授权接入

用户提供项目和部署意图即可。AI先复用用户已经批准的本机连接/私有路径与原身份；新Demo或新线程不等于新token。不要搜索环境中的其它账号秘密，不借用其它worker/claim，不自动选择未知旧安装或扩大scope。

1. 读取 GET https://zzd.show/api/v1/capabilities/，使用实际已有本机凭据 GET https://zzd.show/api/v1/me/（identity:read）核对账号和当前权限。秘密留在0700私有目录/0600文件，不进入prompt、源码或输出。
2. 若已有正常本人网页登录，可 GET https://zzd.show/api/v1/developer-credentials/ 获取本人的非秘密metadata；保留旧credentials字段，并读取reuse.stored_zip_version。遵循pagination.next，has_more=true时不能把首100项称作全库。代理browser session不能管理凭据。
3. 根据已有scopes和用户批准的明确版本选择原ZIP：仅向返回的 /machines/versions/{version_id}/download/ 发送本人session+CSRF的POST，下载原保存字节，不调用create/generate。下载仍检验owner/active/package，metadata不证明本机持有秘密或包必然可下载。没有保存ZIP的旧手工token只可使用已保留的本机秘密，不能从哈希回取。
4. 具有shows:write的原凭据可 POST https://zzd.show/api/v1/shows/ 建立服务端强制visibility="private"草稿；维护使用已有作品及plan/CAS契约。tasks-only不能部署Show；原hightopo可读写本人私有Show/source/assets，但不含shows:publish或browser:login。公开发布仍需独立scope和既有明确发布授权，部署意图本身不等于公开意图。
5. 确无可用授权接入时才走现有登录/明确授权流程。缺少实际本机秘密或权限时准确说明这一缺口，不声称可部署、不为了每个项目重新创建连接。默认长期有效，可由本人单独撤销；显式有限期限凭据仍按本人所选期限，到期后由本人管理原连接，不由本文自动续权。

REST bearer只发精确canonical https://zzd.show/api/v1/（或获准的POST https://zzd.show/mcp/v1/），不跟随redirect转发；session/CSRF下载与bearer REST互不充当认证fallback。已有BaaS绑定仅按目标读取baas/space-sdk契约，不增加匿名BaaS、任意model/provider或外机/费用权利。