@geoly-ai/skills-hub 0.1.0 → 0.2.0

package/README.md

@@ -6,18 +6,66 @@
 `geoly-ai` 的 skill 分发中心：一条命令装单个 skill、装矩阵包，
 并支持外部投稿与过审。
 
-> ⚠️ **M0 规格已封版，M1 实现刚起步** —— 目前只有基础模块和埋点子系统，
-> 装 skill 的主流程还没接通。
+## 安装
+
+```sh
+npm i -g @geoly-ai/skills-hub     # 或 npx @geoly-ai/skills-hub <命令>
+skills-hub --help
+```
+
+**已发布**：[`@geoly-ai/skills-hub@0.1.0`](https://www.npmjs.com/package/@geoly-ai/skills-hub)
+（46 个文件，带 npm provenance；发布 workflow 会用**本包自带的验签器 + 内置信任根**
+自验一遍它自己签的 tarball）。
+
+平台：**macOS / Linux / WSL**，**Node ≥ 22.13**。
+
+### 当前能装到哪几端
+
+| client | 全局 | 项目级 | 说明 |
+|---|:--:|:--:|---|
+| `claude` | ✅ | ✅ | |
+| `codex` | ✅ | ✅ | |
+| `agents` | ✅ | ✅ | **present-only**：`.agents` 已存在才加入，**不会被创建** |
+| `cursor` | ❌ | ❌ | 无运行时证据，且静态读其加载器**预判会失败**（R-8） |
+
+⚠️ `codex` 与 `agents` 同时装时，同一个 skill 会在 codex 的 catalog 里出现两次 ——
+这两个位置本身重叠，CLI 会告警但不拦截。
 
 ## 现在在哪一步
 
 | 阶段 | 状态 |
 |---|---|
-| **M0 · 制品与信任模型** | ✅ **已通过**（v45，2026-08-25） |
-| M1 · 只读分发（单 skill 的 resolve / install / list / check） | 🚧 进行中 —— 信任链与 adapter 已就绪，事务内核在做 |
-| M2 · pack 与受控 catalog | — |
+| **M0 · 制品与信任模型** | ✅ 已通过（v45，2026-08-25） |
+| **M1 · 只读分发** | ✅ **已完成并发布 0.1.0** —— resolve / install / recover / check / list-search-why / sync-lock |
+| **M2 · pack 与受控 catalog** | 🚧 进行中 —— 命令面已齐（`vendor` / `install pack:` / `install --all`）；promotion 的**派生**那一半已就绪（`scripts/build-snapshot.mjs`），元数据来源待 M3 |
 | M3 · 投稿与审核 | — |
-| M4 · update / remove / 正式发包 | — |
+| M4 · update / remove | — |
+
+**930 个测试**在 Node 22.13.0 / 24.19.0 双版本全绿；穷举崩溃注入（真内核 51 个注入点
+逐个反向命中）是 CI 的合并门。
+
+### 🔴 0.1.0 明确**没有**做到的
+
+不写清楚就等于默认承诺了，所以逐条列出：
+
+- **制品（skill tar.gz）与快照的签发链不存在** —— packer 是 M2。
+  这一版签的是 **npm 包本身**（provenance + cosign 对 `.tgz` 的签名），不是 skill 制品。
+  ⚠️ M2 进行中：`scripts/build-snapshot.mjs` 已能从 `artifacts/**` 确定性地**构建**
+  快照与资产（打包、摘要、pack 的 clients 交集 / capabilities 并集、`degraded` 重算、
+  `latest` 投影），但**它不签名** —— 签名仍是 release workflow 的事，尚未接上。
+  且 record 必填的 `owner` / `review`（以及 pack 的 `provenance`，`pack.json` 里没有
+  这个字段）目前由显式的 `--inputs` 提供，M3 的投稿流水线接上后才自动产出。
+- **registry 是纯缓存，没有网络客户端** —— `resolveCurrent()` 是同步的，接不进 `fetch`。
+- **`--from-generation` 只做到编译计划**，接成正向事务的入口还没写。
+- **`--release-frozen` 如实拒绝**（没有按 label 解冻 attic 的导出），不提供假装成功的路径。
+- `cursor` 未验证；`search` 搜不了 description（快照 record 里没有这个字段）。
+
+已知且**明确接受**的残余风险见 [`docs/m1/01-residual-risks.md`](docs/m1/01-residual-risks.md)（R-1 … R-11）
+与 [`docs/m2/01-residual-risks.md`](docs/m2/01-residual-risks.md)（R-12 … R-16），
+M0 正文的勘误见 [`docs/m0/ERRATA.md`](docs/m0/ERRATA.md)（E-1 … E-8）。
+
+M2 交出了什么、**明确没做到什么**、以及三条待拍板项，见
+[`docs/m2/00-delivery.md`](docs/m2/00-delivery.md)。
 
 ## 从哪读起
 
@@ -79,13 +127,23 @@ client 生成，`test/adapters.test.mjs` 用真 git 仓库验证过它确实忽
 
 ## 埋点与面板
 
-规格：[`docs/telemetry/00-spec.md`](docs/telemetry/00-spec.md)（v2，已过 Codex 评审）。
+规格：[`docs/telemetry/00-spec.md`](docs/telemetry/00-spec.md)（v6，已过六轮 Codex 评审）。
+端点实现见 [`server/`](server/)。
+
+🔴 **上报默认开**（2026-09-01 起，规格 §4.2）—— CLI 有内置默认端点。
+首次运行会打印一次告知（收什么、发到哪、怎么关），**这段告知一定先于第一次出网**。
+🔴 **一次 `install` 成功收尾后会静默上报一次**（规格 §5.1.1，2026-09-01 起）：
+24 小时最多一次，网络那一段超时 1 秒，发不出去就留在本地等下次，不影响安装结果、
+也不改退出码。`install` 失败（含部分失败）不发；`check` / `list` / `stats` 等命令
+只写本地，不出网。也可以随时 `skills-hub telemetry flush` 手动发。
 
-🔴 **默认不向任何地方发数据** —— 没有内置端点，不配 `GEOLY_TELEMETRY_ENDPOINT`
-就是纯本地。事件只含制品坐标、客户端、操作、结果、耗时，**不含路径、目录清单、
-文件内容、用户名**；这条契约由 `assertValidEvent()` 在落盘/读回/上报/导出四个边界执行。
+事件只含制品坐标、客户端、操作、结果、耗时、CLI/OS/Node 版本和一个本机随机 ID，
+**不含路径、目录清单、文件内容、用户名、命令行原文、异常栈**；
+这条契约由 `assertValidEvent()` 在落盘/读回/上报/导出四个边界执行，
+**端点侧跑的是同一个校验器**（不另写一份，两份必然分叉）。
 
 - 关掉：`GEOLY_TELEMETRY=0`　只留本地：`GEOLY_TELEMETRY_UPLOAD=0`　断网：`--offline`
+  （⚠️ `GEOLY_TELEMETRY_ENDPOINT=` 空值是**配置错误**，不是关闭开关）
 - 面板：[`docs/dashboard/`](docs/dashboard/)（零依赖静态页，
   `skills-hub stats --export` 出的 JSON 拖进去即可）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geoly-ai/skills-hub",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "geoly-ai 的 skill 分发中心 —— 安装、校验、审计",
   "type": "module",
   "bin": {

package/src/artifact.mjs

@@ -190,6 +190,44 @@ const PACK_MANIFEST_KEYS = {
 };
 
 /** 最小 YAML frontmatter 子集：`---` 包围、单行 `key: value`。其余一律拒绝。 */
+/**
+ * SKILL.md frontmatter 的全部检查 —— **投稿门与建快照必须调同一个**。
+ *
+ * 🔴 2026-09-02：投稿侧的结构门**根本没解析过 frontmatter**，于是 11 个投稿
+ *    全绿合并进 main，promote 建快照时才红在 `E_FRONTMATTER`（10 个用了 YAML
+ *    折叠标量 `>`，而这里的解析器是刻意最小化的、只认单行 `key: value`）。
+ *    那正是本仓库反复警告的「**PR 时绿、promote 时红**」——
+ *    投稿已经在 main 上了，改起来要走一整轮。
+ *
+ * ⚠️ 所以这段逻辑抽成一个函数、两处调用，而**不是**在投稿门里另写一份：
+ *    另写一份就是又一处会分叉的实现。
+ *
+ * @param {object} a
+ * @param {string} a.payloadDir
+ * @param {string} a.name              期望的 name（来自 record / 目录名）
+ * @param {(code:string,msg:string)=>void} a.viol  报错回调
+ * @returns {object|null} 解析出来的 frontmatter
+ */
+export function assertSkillFrontmatter({ payloadDir, name, viol }) {
+  const sp = join(payloadDir, 'SKILL.md');
+  if (!existsSync(sp) || !statSync(sp).isFile()) {
+    viol('E_MANIFEST_MISSING', '载荷根缺少 SKILL.md（§5.1）');
+    return null;
+  }
+  const frontmatter = parseFrontmatter(readFileSync(sp, 'utf8'));
+  if (frontmatter.name !== name) {
+    viol('E_MANIFEST_BINDING', `⑦ SKILL.md frontmatter 的 name 是 ${JSON.stringify(frontmatter.name)}，应为 ${name}`);
+  }
+  if (typeof frontmatter.description !== 'string' || frontmatter.description === '') {
+    viol('E_MANIFEST_BINDING', 'SKILL.md frontmatter 缺少 description（§5.1）');
+  }
+  // 🔴 版本只放 skill.json；SKILL.md frontmatter 只承担运行时语义（§5.1 末段）
+  if (Object.hasOwn(frontmatter, 'version')) {
+    viol('E_MANIFEST_BINDING', 'SKILL.md frontmatter 不得带 version —— 版本只放 skill.json（§5.1）');
+  }
+  return frontmatter;
+}
+
 export function parseFrontmatter(text) {
   if (!text.startsWith('---\n')) throw new WireError('E_FRONTMATTER', 'SKILL.md 必须以 --- 开头的 YAML frontmatter 起始');
   const end = text.indexOf('\n---\n', 3);
@@ -301,21 +339,7 @@ export function assertManifestBinding(record, payloadDir) {
 
   // ⑦ skill 的第七项：SKILL.md frontmatter 的 name
   let frontmatter = null;
-  if (isSkill) {
-    const sp = join(payloadDir, 'SKILL.md');
-    if (!existsSync(sp) || !statSync(sp).isFile()) viol('E_MANIFEST_MISSING', '载荷根缺少 SKILL.md（§5.1）');
-    frontmatter = parseFrontmatter(readFileSync(sp, 'utf8'));
-    if (frontmatter.name !== record.name) {
-      viol('E_MANIFEST_BINDING', `⑦ SKILL.md frontmatter 的 name 是 ${JSON.stringify(frontmatter.name)}，应为 ${record.name}`);
-    }
-    if (typeof frontmatter.description !== 'string' || frontmatter.description === '') {
-      viol('E_MANIFEST_BINDING', 'SKILL.md frontmatter 缺少 description（§5.1）');
-    }
-    // 🔴 版本只放 skill.json；SKILL.md frontmatter 只承担运行时语义（§5.1 末段）
-    if (Object.hasOwn(frontmatter, 'version')) {
-      viol('E_MANIFEST_BINDING', 'SKILL.md frontmatter 不得带 version —— 版本只放 skill.json（§5.1）');
-    }
-  }
+  if (isSkill) frontmatter = assertSkillFrontmatter({ payloadDir, name: record.name, viol });
 
   return { manifest: doc, frontmatter };
 }

package/src/attestation.mjs

@@ -14,6 +14,34 @@ import {
 export const DSSE_PAYLOAD_TYPE = 'application/vnd.in-toto+json';
 export const PREDICATE_TYPE = 'https://geoly.ai/skills-hub/release/v1';
 export const BUILD_TYPE = 'geoly-skills/release/v1';
+/**
+ * 🔴 **两个精确值的枚举，不是前缀、不是正则、不是「未知版本放行」。**
+ *
+ * 2026-09-02 第一次真跑 release（dry_run）时，`check-attestation-bundle.mjs`
+ * 解析 cosign **实际写出来的** envelope，报 `_type` 是 `Statement/v0.1` 而不是 v1。
+ * ⚠️ 那道双重检查正是为此设的：`build-attestation.mjs` 的自检用的是我们自己拼的
+ *    **占位** envelope，它证明不了 cosign 最后产出的东西也满足契约。它抓到了。
+ *
+ * **不存在能让 cosign v2.4.3 输出 v1 的参数**（Codex 2026-09-02 核实）：
+ * `--type https://geoly.ai/...` 设的是 `predicateType`，**不是 `_type`**；
+ * cosign 自己包装 Statement，固定 v0.1。
+ *
+ * **为什么接受 v0.1 的安全代价很低**：`_type` 位于 DSSE payload **内部**，
+ * 已被 PAE 签名覆盖 —— 攻击者不能把一份已签的 v0.1 改标成 v1。
+ * 我们真正依赖的属性一条都没松：DSSE payloadType、固定 predicateType、
+ * 唯一 subject、唯一 sha256 digest、snapshot 交叉绑定、固定 sourceRepo、
+ * 以及 E-2 绑定（workflowRef 钉的 sha === sourceCommit）。
+ * **放宽的是「允许的证据方言」，不是「允许的证据内容」。**
+ *
+ * ⚠️ 代价是互操作性：只认 v1 的外部工具会拒绝我们（cosign v2）的实际产物。
+ * 📌 当前 producer 输出 v0.1；本验证器接受 v0.1 / v1 两个**精确字符串**。
+ *    🔴 不要改成前缀匹配或正则 —— 那等于给未来任何一个没审过的版本发通行证。
+ */
+export const STATEMENT_TYPES = Object.freeze([
+  'https://in-toto.io/Statement/v0.1',
+  'https://in-toto.io/Statement/v1',
+]);
+/** @deprecated 保留给只需要「我们首选哪个」的调用方；判定一律用 STATEMENT_TYPES。 */
 export const STATEMENT_TYPE = 'https://in-toto.io/Statement/v1';
 
 const RE_COMMIT = /^[0-9a-f]{40}$/;
@@ -72,8 +100,9 @@ export function parseAttestationForForensics(bytes, { expectSnapshotSha256, expe
   const payload = decodeB64Strict(env.payload, 'attestation.payload');
   const stmt = parseWireJson(payload, 'attestation.payload');
   assertExactKeys(stmt, STATEMENT_KEYS, 'attestation.payload');
-  if (stmt._type !== STATEMENT_TYPE) {
-    throw new WireError('E_STATEMENT_TYPE', `_type 必须是 ${STATEMENT_TYPE}，得到 ${JSON.stringify(stmt._type)}`);
+  if (!STATEMENT_TYPES.includes(stmt._type)) {
+    throw new WireError('E_STATEMENT_TYPE',
+      `_type 必须是 ${STATEMENT_TYPES.join(' 或 ')}，得到 ${JSON.stringify(stmt._type)}`);
   }
   if (stmt.predicateType !== PREDICATE_TYPE) {
     throw new WireError('E_PREDICATE_TYPE', `predicateType 必须是固定字符串 ${PREDICATE_TYPE}（变更即升版本）`);

package/src/auth.mjs

@@ -0,0 +1,290 @@
+// `publish` 的 token 存储与来源判定 —— 06-submission.md §9。
+//
+// §9 的四条：
+//   · `login`：GitHub device flow，scope 只要 `public_repo`；
+//   · 存储：**优先 OS keychain**；不可用时落 `~/.local/state/geoly-skills/auth.json`，
+//     `0600`，父目录 `0700`；
+//   · token 只在 `publish` / `logout` / `status` 三条命令里读；
+//   · 🔴 CLI 以 `npx github:` 运行时，`login` / `publish` **拒绝执行**。
+//
+// ── 🔴 最后那一条挡的是什么 ─────────────────────────────────────────────
+// `npx github:<owner>/<repo>` 从**一个 git ref** 装并直接跑，没有版本号、
+// 没有 registry 的不可变性、也没有签名 —— ref 指向的内容随时可以被换掉。
+// 让这种形态的进程拿到用户的 GitHub token，等于把「谁能改那个 ref」
+// 变成「谁能拿到 token」。装 skill（只读）容忍这种形态，
+// **发凭据不容忍**。
+//
+// ⚠️ 这是一条**尽力**的门，不是安全边界：能改 ref 的人也能改这段判定。
+//    它挡的是「用户自己图省事用 npx github: 跑 publish」，
+//    不是「攻击者已经控制了代码」——后者早就赢了。
+
+import {
+  readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync, existsSync, statSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, sep } from 'node:path';
+
+export class AuthError extends Error {
+  constructor(code, msg) { super(msg); this.name = 'AuthError'; this.code = code; }
+}
+const bad = (code, msg) => { throw new AuthError(code, msg); };
+
+/** §9：`login` 只要这一个 scope。 */
+export const REQUIRED_SCOPE = 'public_repo';
+
+/**
+ * 🔴 **`login` 时必须把权限面说清楚**（10-open-questions Q4 的落点）：
+ *    `public_repo` 能改用户**所有**公开仓，远大于「给 skills-hub 投稿」所需。
+ *    Q4 的收窄方案（GitHub App）没赶上 M3，按 Q4 自己写的兜底走：
+ *    用 `public_repo` 上线，但**说清楚**，并列为已知残余风险。
+ */
+export const SCOPE_DISCLOSURE = `⚠️ 这次授权的 scope 是 \`${REQUIRED_SCOPE}\`。
+
+它的权限面**大于**你要做的事：
+  你要做的：往 geoly-ai/skills-hub 开一张投稿 PR。
+  它实际能做的：读写你**所有**公开仓库。
+
+之所以还是它：GitHub 的 device flow 没有更细的 scope 可选；
+收窄方案（GitHub App，权限细到单仓）还没做完 —— 见 10-open-questions.md Q4。
+
+不想给这个权限的话，**不用 \`login\`**：
+fork + 手动开 PR 走的是同一条流水线，一模一样的门，只是要你自己点几下。`;
+
+// ── 存放位置 ───────────────────────────────────────────────────────────────
+
+/**
+ * `~/.local/state/geoly-skills/auth.json`。
+ * 🔴 认 `XDG_STATE_HOME`：用户把 state 挪到别处（加密卷、tmpfs）是常见做法，
+ *    忽略它等于把凭据写回一个用户以为不会有凭据的地方。
+ */
+export function authFilePath({ env = process.env, home = homedir() } = {}) {
+  const base = env.XDG_STATE_HOME && env.XDG_STATE_HOME.startsWith('/')
+    ? env.XDG_STATE_HOME
+    : join(home, '.local', 'state');
+  return join(base, 'geoly-skills', 'auth.json');
+}
+
+/**
+ * 落盘：文件 `0600`、父目录 `0700`（§9 明写）。
+ *
+ * 🔴 **先建目录并 chmod，再写文件**。反过来的话，文件在一个 `0755` 的目录里
+ *    短暂存在过 —— 同机器上的其他用户在那个窗口内能读到它。
+ * 🔴 **写之前先 chmod 到 0600**：`writeFileSync` 的 mode 参数只在**新建**时生效，
+ *    文件已存在时它一声不吭地沿用旧权限。一个之前被 chmod 成 0644 的
+ *    auth.json 会一直是 0644。
+ */
+export function writeTokenFile(token, {
+  path = authFilePath(), now = () => new Date(), warn = null,
+} = {}) {
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // 🔴 目录已存在时 mkdir 的 mode 不生效，所以要显式 chmod。
+  //    ⚠️ 但**不能因为 chmod 失败就不存 token**：目录可能不归我们所有
+  //    （用户把路径指到了一个共享目录），那时 chmod 抛 EPERM。
+  //    文件本身的 0600 才是保护内容的那一道 —— 目录权限管的是能不能列目录。
+  //    所以这里降级成告警。
+  try {
+    chmodSync(dir, 0o700);
+  } catch (e) {
+    if (warn !== null) {
+      warn(`⚠️ 收紧 ${dir} 的权限失败（${e.code}）—— 它可能不归你所有。\n`
+        + '   token 文件本身仍然是 0600，别人读不到内容，但能看到这个文件存在。');
+    }
+  }
+  const body = `${JSON.stringify({
+    schema: 'geoly.skills.auth/1',
+    token,
+    scope: REQUIRED_SCOPE,
+    created_at: now().toISOString(),
+  }, null, 2)}\n`;
+  writeFileSync(path, body, { mode: 0o600 });
+  // 🔴 文件已存在时 writeFileSync 的 mode 不生效 —— 这一处**不降级**：
+  //    收紧不了文件权限就等于把明文 token 摊开，宁可失败。
+  chmodSync(path, 0o600);
+  return path;
+}
+
+/** @returns {{token:string, scope:string, created_at:string}|null} */
+export function readTokenFile({ path = authFilePath(), warn = null } = {}) {
+  if (!existsSync(path)) return null;
+  // 🔴 权限变宽了要**说出来**，但不要因此拒绝读 —— 用户此刻多半正在
+  //    `logout`，而拒绝读会让他连撤销都做不了。
+  const mode = statSync(path).mode & 0o777;
+  if (mode !== 0o600 && warn !== null) {
+    warn(`⚠️ ${path} 的权限是 ${mode.toString(8)}，应为 600 —— 同机器上的其他用户可能读得到。`
+      + '\n   建议 `geoly-skills logout` 之后重新 login。');
+  }
+  let doc;
+  try { doc = JSON.parse(readFileSync(path, 'utf8')); } catch (e) {
+    bad('E_AUTH_CORRUPT', `${path} 读不出来：${e.message}\n  删掉它再 login。`);
+  }
+  if (doc === null || typeof doc !== 'object' || typeof doc.token !== 'string' || doc.token === '') {
+    bad('E_AUTH_CORRUPT', `${path} 里没有 token —— 删掉它再 login。`);
+  }
+  return doc;
+}
+
+export function deleteTokenFile({ path = authFilePath() } = {}) {
+  if (!existsSync(path)) return false;
+  rmSync(path, { force: true });
+  return true;
+}
+
+// ── npx github: 判定 ───────────────────────────────────────────────────────
+
+// npm ≥ 7 的 npx 把包装进 `~/.npm/_npx/<hash>/node_modules/<name>`，
+// 并在 `~/.npm/_npx/<hash>/package.json` 里记下**用户当初写的那个 spec**。
+// 那份 spec 才是判据 —— 装完之后的目录长得都一样。
+const NPX_DIR = `${sep}_npx${sep}`;
+
+/** 一个依赖 spec 是不是「从 git ref 装」。 */
+export function isGitSpec(spec) {
+  if (typeof spec !== 'string') return false;
+  const s = spec.trim();
+  return /^(github|gitlab|bitbucket|gist):/i.test(s)
+    || /^git(\+(ssh|https?|file))?:/i.test(s)
+    || /^(https?:\/\/|git@)[^\s]*\.git($|#)/i.test(s)
+    // `npx owner/repo` 这种裸写法 npm 也当 GitHub 处理
+    || /^[\w.-]+\/[\w.-]+(#.*)?$/.test(s);
+}
+
+/**
+ * 本进程是不是「`npx <git spec>` 跑起来的」。
+ *
+ * @param {string} moduleDir  本模块所在目录（生产上传 `import.meta.dirname`）
+ * @returns {{isNpxGit:boolean, spec:string|null, manifest:string|null}}
+ */
+export function detectNpxGit(moduleDir) {
+  const idx = moduleDir.indexOf(NPX_DIR);
+  if (idx === -1) return { isNpxGit: false, spec: null, manifest: null };
+  // `<...>/_npx/<hash>/` —— hash 那一层就是 npx 的临时安装根
+  const rest = moduleDir.slice(idx + NPX_DIR.length);
+  const hash = rest.split(sep)[0];
+  if (!hash) return { isNpxGit: false, spec: null, manifest: null };
+  const manifest = join(moduleDir.slice(0, idx), '_npx', hash, 'package.json');
+  if (!existsSync(manifest)) return { isNpxGit: false, spec: null, manifest };
+  let doc;
+  try { doc = JSON.parse(readFileSync(manifest, 'utf8')); } catch {
+    // 读不出来就**不**断言它是 git spec —— 这道门是尽力性质的，
+    // 误拒一个正常的 `npx skills-hub` 比放过一个 `npx github:` 更常见。
+    return { isNpxGit: false, spec: null, manifest };
+  }
+  for (const spec of Object.values(doc?.dependencies ?? {})) {
+    if (isGitSpec(spec)) return { isNpxGit: true, spec, manifest };
+  }
+  return { isNpxGit: false, spec: null, manifest };
+}
+
+/**
+ * §9 最后一条的断言形态。`login` / `publish` 开头就调它。
+ * 退出码 7（认证），见 09-cli.md §6。
+ */
+export function assertNotNpxGit(moduleDir, command) {
+  const d = detectNpxGit(moduleDir);
+  if (!d.isNpxGit) return false;
+  bad('E_NPX_GIT',
+    `\`${command}\` 拒绝在 \`npx ${d.spec}\` 下运行（06-submission.md §9）。\n`
+    + '  🔴 从一个 git ref 装并直接跑：没有版本号、没有 registry 的不可变性、\n'
+    + '     也没有签名 —— ref 指向的内容随时可以被换掉。\n'
+    + '  让这种形态的进程拿到你的 GitHub token，等于把「谁能改那个 ref」\n'
+    + '  变成「谁能拿到你的 token」。装 skill（只读）容忍它，发凭据不容忍。\n'
+    + `  改用装好的 CLI：\`npm i -g skills-hub && geoly-skills ${command}\`。`);
+}
+
+// ── OS keychain（§9：**优先** keychain，不可用才落文件）────────────────────
+
+/**
+ * 每个平台的 keychain 命令。
+ *
+ * 🔴 **token 一律走 stdin，不进 argv。** 进程的命令行参数在同机器上是可见的
+ *    （Linux 的 `/proc/<pid>/cmdline` 全用户可读；macOS 上同用户可见），
+ *    把 token 写进 argv 等于让它出现在任何一次 `ps` 里，
+ *    还会进 shell 历史。这是「用 keychain 存」这件事的第一个前提 ——
+ *    存得再安全，取的路上漏了也白搭。
+ *
+ * ⚠️ macOS 的 `security add-generic-password` **没有**从 stdin 读密码的选项，
+ *    只有 `-w <value>`。所以那一条只能走 argv —— 这是平台限制，不是选择。
+ *    缓解：macOS 上非 root 用户看不到**别的用户**的进程参数；
+ *    同用户的进程本来就能直接读 keychain。**如实记在这里，不假装没有。**
+ */
+const KEYCHAIN = {
+  darwin: {
+    // -U：已存在就更新，否则 add 会以 45 号错误失败
+    set: (service, account, token) =>
+      ({ cmd: 'security', args: ['add-generic-password', '-U', '-s', service, '-a', account, '-w', token] }),
+    get: (service, account) =>
+      ({ cmd: 'security', args: ['find-generic-password', '-s', service, '-a', account, '-w'] }),
+    del: (service, account) =>
+      ({ cmd: 'security', args: ['delete-generic-password', '-s', service, '-a', account] }),
+  },
+  linux: {
+    // secret-tool 从 stdin 读值 —— token 不进 argv
+    set: (service, account) =>
+      ({ cmd: 'secret-tool', args: ['store', '--label', service, 'service', service, 'account', account], stdin: true }),
+    get: (service, account) =>
+      ({ cmd: 'secret-tool', args: ['lookup', 'service', service, 'account', account] }),
+    del: (service, account) =>
+      ({ cmd: 'secret-tool', args: ['clear', 'service', service, 'account', account] }),
+  },
+};
+
+export const KEYCHAIN_SERVICE = 'geoly-skills';
+export const KEYCHAIN_ACCOUNT = 'github-token';
+
+/**
+ * 统一的存取。**keychain 优先，失败就落文件** —— 两条路都要能用：
+ * CI、容器、没有 keyring 的服务器上 keychain 根本不存在。
+ *
+ * 🔴 **keychain 不可用是「换一条路」，不是「报错」。** 但要**说出来** ——
+ *    用户有权知道自己的 token 是躺在 keychain 里还是躺在一个文件里。
+ *
+ * @param {object} deps
+ * @param {(cmd:string, args:string[], input:string|null) => {status:number, stdout:string, stderr:string}} deps.run
+ */
+export function makeAuthStore({ run, platform = process.platform, path = null, warn = null } = {}) {
+  const kc = KEYCHAIN[platform] ?? null;
+  const file = path ?? authFilePath();
+  const note = (s) => { if (warn !== null) warn(s); };
+
+  const tryKeychain = (make, input = null) => {
+    if (kc === null || typeof run !== 'function') return null;
+    const spec = make(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT, input);
+    let r;
+    try { r = run(spec.cmd, spec.args, spec.stdin ? input : null); } catch { return null; }
+    // 命令不存在 / 没有 keyring daemon：status 非 0 或抛错，一律当「不可用」
+    if (r === null || r === undefined || r.status !== 0) return null;
+    return r;
+  };
+
+  return {
+    /** @returns {'keychain'|'file'} 实际存到了哪儿 */
+    save(token) {
+      if (tryKeychain((s, a) => kc.set(s, a, token), token) !== null) return 'keychain';
+      note(`⚠️ 系统 keychain 不可用，token 落在 ${file}（0600）。`
+        + '\n   它是一个明文文件 —— 这台机器上能读它的人就能用你的身份投稿。');
+      writeTokenFile(token, { path: file, warn });
+      return 'file';
+    },
+    /** @returns {{token:string, from:'keychain'|'file'}|null} */
+    load() {
+      const r = tryKeychain((s, a) => kc.get(s, a));
+      if (r !== null) {
+        const token = r.stdout.replace(/\n$/, '');
+        if (token !== '') return { token, from: 'keychain' };
+      }
+      const d = readTokenFile({ path: file, warn });
+      return d === null ? null : { token: d.token, from: 'file' };
+    },
+    /**
+     * 🔴 **两处都要清。** 只清 keychain 的话，一个早先落过盘的 auth.json
+     *    会留在原地 —— 用户以为 logout 了，token 还躺在那儿。
+     * @returns {string[]} 实际清掉了哪几处
+     */
+    clear() {
+      const cleared = [];
+      if (tryKeychain((s, a) => kc.del(s, a)) !== null) cleared.push('keychain');
+      if (deleteTokenFile({ path: file })) cleared.push('file');
+      return cleared;
+    },
+  };
+}