@elinpf/dsh-ops-access-ssh 0.1.7 → 0.2.1

package/README.i18n.yaml

@@ -1,4 +1,4 @@
 title: "@elinpf/dsh-ops-access-ssh"
 description:
-  zh: "ops access 接缝的 SSH 凭据 provider — 校验 ssh registry 条目并展开密钥路径"
-  en: "SSH credential provider for the ops access seam — validates ssh registry entries and expands key paths"
+  zh: "ops access 接缝的 SSH provider — ssh 主机条目 + ssh-cred 可复用凭证(密钥/密码),一份秘密多机共享"
+  en: "SSH provider for the ops access seam — ssh host entries + ssh-cred reusable credentials (key/password), one secret shared by many hosts"

package/README.md

@@ -1,21 +1,24 @@
 # @elinpf/dsh-ops-access-ssh
 
-SSH credential provider for the ops access seam — validates `ssh` registry entries (`{ host, user, key?, port? }`) and expands key paths for the ssh consumer tool.
+SSH provider for the ops access seam — two credential kinds: `ssh` (a HOST entry) and `ssh-cred` (a reusable CREDENTIAL entry), so one key or password is registered once and shared by any number of hosts.
 
 ## What it does
 
-One of three provider plugins behind `@elinpf/dsh-ops-access` (core). Core owns the YAML credential registry (`~/.dsh-ops/access.yaml`) and the `ctx.opsAccess` service; this package contributes exactly one credential kind, `ssh`, via `registerAccessProvider`:
+One of the provider plugins behind `@elinpf/dsh-ops-access` (core). Core owns the YAML credential registry (`~/.dsh-ops/access.yaml`) and the `ctx.opsAccess` service; this package contributes two credential kinds via `registerAccessProvider`:
 
-- **Entry schema** (zod): `host`, `user`, optional `key` (private-key path), optional `port`
-- **Field processing**: expands `~` in the key path so `ssh -i` sees an absolute path
-- **Save-time key validation** in two layers: a cheap PEM armor check, then a REAL parse via `ssh-keygen -y` — a structurally plausible but corrupt paste fails with a clear message instead of `error in libcrypto` mid-investigation, and a passphrase-protected key gets its BatchMode explanation up front
-- **Pasted key content**: when the admin UI receives key CONTENT (not a path), core writes it to a managed file under `~/.dsh-ops/credentials/`; the provider opts into trailing-newline normalization (a paste that lost the final newline of the END line failed in libcrypto at first use — 2026-08-27)
+- **`ssh` — the host**: `host`, optional `user` / `key` / `password` / `port`, and optional `cred` — a reference to an `ssh-cred` entry. The intended shape is host + `cred`; inline `key`/`password` still work (legacy / one-off). At resolve time core merges the referenced credential's fields UNDER the host entry's — a `user` set on the host overrides the credential's default.
+- **`ssh-cred` — the credential**: optional `user` (default login user), `key`, `password` — at least one of key/password required. Holds no host; it only resolves as the target of a `cred` reference. Register the secret once, point N hosts at it, rotate it in one place.
+- **Field processing**: expands `~` in the key/password paths so `ssh -i` / `sshpass -f` see absolute paths.
+- **Save-time validation**: key content gets a PEM armor check plus a REAL `ssh-keygen -y` parse (a structurally plausible but corrupt paste fails with a clear message instead of `error in libcrypto` mid-investigation; a passphrase-protected key gets its BatchMode explanation up front). Password content must be single-line — `sshpass -f` reads only the first line.
+- **Pasted content**: when the admin UI receives key/password CONTENT (not a path), core writes it to a managed 0600 file under `~/.dsh-ops/credentials/`; both kinds opt into trailing-newline normalization (a key paste that lost the final newline of the END line failed in libcrypto at first use — 2026-08-27).
 
 ## Why this shape
 
 The three-role rule (see the repo `AGENTS.md`): core owns the registry and the service, providers carry only a zod schema plus field processing, consumer tools resolve a profile and build the shell command. Keeping this package to schema + processing means no secret material ever passes through any service — profiles carry only paths and connection parameters.
 
-Registration defers through `ctx.inject(['opsAccess'], ...)` inside `registerAccessProvider` and is tied to the plugin's effect lifecycle, so fiber disposal / HMR unload removes the provider from the registry.
+The host/credential split uses core's generic `references` mechanism (`references: { cred: 'ssh-cred' }`): one resolve consults the broker once on the HOST entry — the referenced credential is an implementation detail, not a separately gated profile. A dangling reference fails the referring resolve (and its `canResolve` precheck) with a pointer to both entries.
+
+Registration defers through `ctx.inject(['opsAccess'], ...)` inside `registerAccessProvider` and is tied to the plugin's effect lifecycle, so fiber disposal / HMR unload removes the providers from the registry.
 
 ## Installation
 
@@ -37,4 +40,4 @@ npm run build
 npx vitest run
 ```
 
-The spec covers schema accept/reject, `~` expansion, registration/disposal through a mock `opsAccess` context (including HMR unload), and the validateContent armor gate + real `ssh-keygen` parse (it generates throwaway ed25519 keys in a tmp dir).
+The spec covers schema accept/reject (both kinds), `~` expansion, the `cred → ssh-cred` reference declaration, post-merge user validation, registration/disposal through a mock `opsAccess` context (including HMR unload), and the validateContent armor gate + real `ssh-keygen` parse + single-line password rule (it generates throwaway ed25519 keys in a tmp dir).

package/README.zh.md

@@ -1,20 +1,23 @@
 # @elinpf/dsh-ops-access-ssh
 
-ops access 接缝的 SSH 凭据 provider — 校验 `ssh` registry 条目(`{ host, user, key?, port? }`)并为 ssh 消费端工具展开密钥路径。
+ops access 接缝的 SSH provider — 两个凭证种类:`ssh`(主机条目)和 `ssh-cred`(可复用凭证条目),一把密钥或一个密码只登记一次,任意多台主机共享。
 
 ## 功能
 
-`@elinpf/dsh-ops-access`(core) 下的三个 provider 插件之一。core 拥有 YAML 凭据 registry(`~/.dsh-ops/access.yaml`)和 `ctx.opsAccess` 服务;本包通过 `registerAccessProvider` 只贡献一个凭据种类 `ssh`:
+`@elinpf/dsh-ops-access`(core) 下的 provider 插件之一。core 拥有 YAML 凭据 registry(`~/.dsh-ops/access.yaml`)和 `ctx.opsAccess` 服务;本包通过 `registerAccessProvider` 贡献两个凭证种类:
 
-- **条目 schema**(zod):`host`、`user`,可选 `key`(私钥路径),可选 `port`
-- **字段处理**:展开 key 路径中的 `~`,让 `ssh -i` 拿到绝对路径
-- **保存时密钥校验**分两层:先做廉价的 PEM armor 检查,再用 `ssh-keygen -y` 做真实解析 — 结构看似合法但内容损坏的粘贴会在此刻得到清晰报错,而不是在排查中途撞上 `error in libcrypto`;带口令的密钥也会提前得到 BatchMode 说明
-- **粘贴密钥内容**:admin UI 收到的是密钥内容(而非路径)时,core 会写入 `~/.dsh-ops/credentials/` 下的受管文件;provider 声明尾随换行规范化(粘贴恰好丢了 END 行末尾换行时,首次使用会在 libcrypto 里失败 — 2026-08-27)
+- **`ssh` — 主机**:`host`,可选 `user` / `key` / `password` / `port`,以及可选 `cred` — 指向一个 `ssh-cred` 条目的引用。推荐形态是主机 + `cred`;内联 `key`/`password` 继续可用(遗留/一次性场景)。resolve 时 core 把被引用凭证的字段合并到主机条目**之下** — 主机上设的 `user` 覆盖凭证的默认登录用户。
+- **`ssh-cred` — 凭证**:可选 `user`(默认登录用户)、`key`、`password` — key/password 至少一个必填。不持有主机,只作为 `cred` 引用的目标被解析。秘密登记一次,N 台主机引用,轮换只改一处。
+- **字段处理**:展开 key/password 路径中的 `~`,让 `ssh -i` / `sshpass -f` 拿到绝对路径。
+- **保存时校验**:密钥内容先做廉价的 PEM armor 检查,再用 `ssh-keygen -y` 做真实解析(结构看似合法但内容损坏的粘贴会在此刻得到清晰报错,而不是在排查中途撞上 `error in libcrypto`;带口令的密钥也会提前得到 BatchMode 说明)。密码内容必须单行 — `sshpass -f` 只读文件第一行。
+- **粘贴内容**:admin UI 收到的是密钥/密码内容(而非路径)时,core 会写入 `~/.dsh-ops/credentials/` 下的 0600 受管文件;两个种类都声明尾随换行规范化(密钥粘贴恰好丢了 END 行末尾换行时,首次使用会在 libcrypto 里失败 — 2026-08-27)。
 
 ## 为什么这样拆
 
 三角色规则(见仓库 `AGENTS.md`):core 拥有 registry 和服务,provider 只带一个 zod schema 加字段处理,消费端工具解析 profile 并拼 shell 命令。本包保持 schema + 处理的最小形态,意味着任何服务都不经手秘密材料 — profile 里只有路径和连接参数。
 
+主机/凭证分离用的是 core 的通用 `references` 机制(`references: { cred: 'ssh-cred' }`):一次 resolve 只对**主机条目**咨询一次 broker — 被引用的凭证是实现细节,不是单独门控的 profile。悬挂引用会让引用方的 resolve(及其 `canResolve` 预检)失败,并报出两端条目名。
+
 注册在 `registerAccessProvider` 内部经 `ctx.inject(['opsAccess'], ...)` 延迟挂载,并绑定在插件的 effect 生命周期上,fiber 销毁 / HMR 卸载会把 provider 从 registry 移除。
 
 ## 安装
@@ -37,4 +40,4 @@ npm run build
 npx vitest run
 ```
 
-测试覆盖:schema 接受/拒绝、`~` 展开、经 mock `opsAccess` 上下文的注册/销毁(含 HMR 卸载),以及 validateContent 的 armor 闸门 + 真实 `ssh-keygen` 解析(在临时目录生成一次性 ed25519 密钥)。
+测试覆盖:两个种类的 schema 接受/拒绝、`~` 展开、`cred → ssh-cred` 引用声明、合并后用户校验、经 mock `opsAccess` 上下文的注册/销毁(含 HMR 卸载),以及 validateContent 的 armor 闸门 + 真实 `ssh-keygen` 解析 + 密码单行规则(在临时目录生成一次性 ed25519 密钥)。

package/lib/index.d.ts

@@ -1,12 +1,24 @@
 /**
  * Ops access provider for SSH.
  *
- * Validates `ssh` registry entries (`{ host, user, key?, port? }`). When the
- * admin UI receives private-key CONTENT (instead of a path), core writes it
- * to a managed file under ~/.dsh-ops/credentials/ and stores the path in the
- * registry. The provider expands ~ in the path for ssh -i. Pasted key
- * content is normalized to end with exactly one newline and deep-parsed at
- * save time (ssh-keygen -y) — both classic paste losses (2026-08-27).
+ * Two kinds live here:
+ *
+ * - `ssh` — a HOST entry: `{ host, user?, key?, password?, cred?, port? }`.
+ *   The credential (key or password) may be carried inline, but the intended
+ *   shape is a `cred` reference to a shared `ssh-cred` entry — register the
+ *   secret once, point N hosts at it, rotate it in one place. Fields set on
+ *   the host entry override the referenced credential's (core merges the
+ *   reference UNDER the entry; see `references` in the core seam).
+ * - `ssh-cred` — a reusable CREDENTIAL entry: `{ user?, key?, password? }`
+ *   (at least one of key/password). Holds no host; it only resolves as the
+ *   target of an ssh entry's `cred` reference.
+ *
+ * When the admin UI receives private-key / password CONTENT (instead of a
+ * path), core writes it to a managed file under ~/.dsh-ops/credentials/ and
+ * stores the path in the registry. The provider expands ~ in the path for
+ * ssh -i / sshpass -f. Pasted key content is normalized to end with exactly
+ * one newline and deep-parsed at save time (ssh-keygen -y) — both classic
+ * paste losses (2026-08-27).
  *
  * @module @elinpf/dsh-ops-access-ssh
  */
@@ -15,7 +27,7 @@ import z from '@deepseek-ai/schemastery';
 import { z as zod } from 'zod';
 import type { AccessProvider } from '@elinpf/dsh-ops-access';
 import type { SshProviderConfig } from './types.js';
-export type { SshEntry, SshProviderConfig } from './types.js';
+export type { SshCredEntry, SshEntry, SshProviderConfig } from './types.js';
 export declare const name = "ops-access-ssh";
 export declare const inject: string[];
 export declare const Config: z<Schemastery.ObjectS<{
@@ -25,12 +37,26 @@ export declare const Config: z<Schemastery.ObjectS<{
     /** Save-time validation: timeout for the `ssh-keygen -y` parse (ms). */
     validateTimeoutMs: z<number, number>;
 }>>;
-/** Zod schema for one ssh registry entry (excluding name and envelope fields). */
+/** Zod schema for one ssh HOST registry entry (excluding name and the envelope fields). */
 export declare const entrySchema: zod.ZodObject<{
     host: zod.ZodString;
-    user: zod.ZodString;
+    user: zod.ZodOptional<zod.ZodString>;
     key: zod.ZodOptional<zod.ZodString>;
+    password: zod.ZodOptional<zod.ZodString>;
+    cred: zod.ZodOptional<zod.ZodString>;
     port: zod.ZodOptional<zod.ZodNumber>;
 }, zod.core.$strip>;
+/**
+ * Zod schema for one ssh-cred CREDENTIAL entry: the shared secret half of the
+ * host/credential split. At least one auth method (key or password) is
+ * required — an empty credential resolves for every host that references it
+ * and fails them all at connection time, so reject it at save time.
+ */
+export declare const credEntrySchema: zod.ZodObject<{
+    user: zod.ZodOptional<zod.ZodString>;
+    key: zod.ZodOptional<zod.ZodString>;
+    password: zod.ZodOptional<zod.ZodString>;
+}, zod.core.$strip>;
 export declare const provider: AccessProvider;
+export declare const credProvider: AccessProvider;
 export declare function apply(ctx: Context, config: SshProviderConfig): void;

package/lib/index.js

@@ -1,12 +1,24 @@
 /**
  * Ops access provider for SSH.
  *
- * Validates `ssh` registry entries (`{ host, user, key?, port? }`). When the
- * admin UI receives private-key CONTENT (instead of a path), core writes it
- * to a managed file under ~/.dsh-ops/credentials/ and stores the path in the
- * registry. The provider expands ~ in the path for ssh -i. Pasted key
- * content is normalized to end with exactly one newline and deep-parsed at
- * save time (ssh-keygen -y) — both classic paste losses (2026-08-27).
+ * Two kinds live here:
+ *
+ * - `ssh` — a HOST entry: `{ host, user?, key?, password?, cred?, port? }`.
+ *   The credential (key or password) may be carried inline, but the intended
+ *   shape is a `cred` reference to a shared `ssh-cred` entry — register the
+ *   secret once, point N hosts at it, rotate it in one place. Fields set on
+ *   the host entry override the referenced credential's (core merges the
+ *   reference UNDER the entry; see `references` in the core seam).
+ * - `ssh-cred` — a reusable CREDENTIAL entry: `{ user?, key?, password? }`
+ *   (at least one of key/password). Holds no host; it only resolves as the
+ *   target of an ssh entry's `cred` reference.
+ *
+ * When the admin UI receives private-key / password CONTENT (instead of a
+ * path), core writes it to a managed file under ~/.dsh-ops/credentials/ and
+ * stores the path in the registry. The provider expands ~ in the path for
+ * ssh -i / sshpass -f. Pasted key content is normalized to end with exactly
+ * one newline and deep-parsed at save time (ssh-keygen -y) — both classic
+ * paste losses (2026-08-27).
  *
  * @module @elinpf/dsh-ops-access-ssh
  */
@@ -27,21 +39,34 @@ export const Config = z.object({
     validateTimeoutMs: z.number().default(5000),
 });
 // ── Provider ─────────────────────────────────────────────────────────────────
-/** Zod schema for one ssh registry entry (excluding name and envelope fields). */
+/** Zod schema for one ssh HOST registry entry (excluding name and the envelope fields). */
 export const entrySchema = zod.object({
     host: zod.string(),
-    user: zod.string(),
+    user: zod.string().optional(),
     key: zod.string().optional(),
+    password: zod.string().optional(),
+    cred: zod.string().optional(),
     port: zod.number().optional(),
 });
+/**
+ * Zod schema for one ssh-cred CREDENTIAL entry: the shared secret half of the
+ * host/credential split. At least one auth method (key or password) is
+ * required — an empty credential resolves for every host that references it
+ * and fails them all at connection time, so reject it at save time.
+ */
+export const credEntrySchema = zod.object({
+    user: zod.string().optional(),
+    key: zod.string().optional(),
+    password: zod.string().optional(),
+}).refine((e) => e.key !== undefined || e.password !== undefined, {
+    message: 'an ssh-cred entry needs at least one auth method: key or password',
+});
 // Save-time guard in two layers: a cheap armor check, then a REAL parse —
 // ssh-keygen -y derives the public key with the same parser ssh runs at
 // connection time. A structurally plausible but corrupt paste fails here
 // with a clear message instead of 'error in libcrypto' mid-investigation,
 // and a passphrase-protected key gets its BatchMode explanation up front.
-async function validateKeyContent(field, content, keygenTimeoutMs) {
-    if (field !== 'key')
-        return null;
+async function validateKeyContent(content, keygenTimeoutMs) {
     if (!/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/.test(content) || !/-----END [A-Z0-9 ]*PRIVATE KEY-----/.test(content)) {
         return 'not a private key — expected a -----BEGIN ... PRIVATE KEY----- block (paste the full key file)';
     }
@@ -71,17 +96,54 @@ async function validateKeyContent(field, content, keygenTimeoutMs) {
         await rm(dir, { recursive: true, force: true });
     }
 }
+/**
+ * Save-time validator for file-field content, shared by both kinds: `key`
+ * goes through the ssh-keygen deep parse; `password` must be single-line —
+ * sshpass -f reads only the FIRST line, so an interior newline would
+ * silently truncate the password at connection time. (Core's trailing-newline
+ * normalization has already run, so any newline before the final one is
+ * interior.)
+ */
+function validateContent(keygenTimeoutMs) {
+    return (field, content) => {
+        if (field === 'key')
+            return validateKeyContent(content, keygenTimeoutMs);
+        if (field === 'password') {
+            const body = content.endsWith('\n') ? content.slice(0, -1) : content;
+            if (body.includes('\n') || body.includes('\r')) {
+                return 'a password must be a single line — sshpass -f reads only the first line of the file';
+            }
+            return null;
+        }
+        return null;
+    };
+}
+/** ssh needs a login user; with the host/credential split it may come from either side of the merge. */
+function validateResolvedUser(fields) {
+    if (typeof fields.user !== 'string' || fields.user.length === 0) {
+        return 'no login user — set user on the host entry, or on the ssh-cred entry its cred field references';
+    }
+    return null;
+}
 export const provider = {
     kind: 'ssh',
     schema: entrySchema,
-    fieldsDoc: 'host: hostname or IP; user: login user; key: optional private-key content; port: optional, default 22',
-    fileFields: ['key'],
+    fieldsDoc: 'host: hostname or IP; user: optional login user (overrides the credential\'s); key: optional private-key content; password: optional password content (sshpass must be installed on the dsh host); cred: optional ssh-cred profile name — the shared credential, fields here override it; port: optional, default 22',
+    fileFields: ['key', 'password'],
+    references: { cred: 'ssh-cred' },
+    validateResolved: validateResolvedUser,
     derivationDoc: 'ssh has no read-only shell — the credential lives in the ro tier and every use is grant-gated; to provision a dedicated key during an approved session: generate a fresh keypair (ssh-keygen -t ed25519), append the public key to the target user\'s authorized_keys, then register the private key via register_access',
     process(entry) {
-        const { host, user, key, port } = entry;
-        const fields = { host, user };
+        const { host, user, key, password, cred, port } = entry;
+        const fields = { host };
+        if (user !== undefined)
+            fields.user = user;
         if (key !== undefined)
             fields.key = expandHome(key);
+        if (password !== undefined)
+            fields.password = expandHome(password);
+        if (cred !== undefined)
+            fields.cred = cred;
         if (port !== undefined)
             fields.port = port;
         return fields;
@@ -90,12 +152,35 @@ export const provider = {
     // the END line newline-terminated; a paste that lost exactly that byte
     // failed in libcrypto at first use — 2026-08-27).
     normalizeTrailingNewline: true,
-    validateContent: (field, content) => validateKeyContent(field, content, 5000),
+    validateContent: validateContent(5000),
+};
+export const credProvider = {
+    kind: 'ssh-cred',
+    schema: credEntrySchema,
+    fieldsDoc: 'user: optional default login user (hosts may override); key: optional private-key content; password: optional password content (sshpass must be installed on the dsh host). At least one of key/password is required. Referenced by ssh entries via their cred field — register the secret once, point many hosts at it',
+    fileFields: ['key', 'password'],
+    process(entry) {
+        const { user, key, password } = entry;
+        const fields = {};
+        if (user !== undefined)
+            fields.user = user;
+        if (key !== undefined)
+            fields.key = expandHome(key);
+        if (password !== undefined)
+            fields.password = expandHome(password);
+        return fields;
+    },
+    normalizeTrailingNewline: true,
+    validateContent: validateContent(5000),
 };
 // ── Plugin apply ─────────────────────────────────────────────────────────────
 export function apply(ctx, config) {
     registerAccessProvider(ctx, {
         ...provider,
-        validateContent: (field, content) => validateKeyContent(field, content, config.validateTimeoutMs),
+        validateContent: validateContent(config.validateTimeoutMs),
+    });
+    registerAccessProvider(ctx, {
+        ...credProvider,
+        validateContent: validateContent(config.validateTimeoutMs),
     });
 }

package/lib/types.d.ts

@@ -12,13 +12,38 @@
 export interface SshEntry {
     /** Hostname or IP of the target. */
     host: string;
-    /** Login user. */
-    user: string;
+    /**
+     * Login user. Optional on the entry when `cred` is set — the referenced
+     * credential's user applies; a user set HERE overrides it for this host.
+     * The resolved profile must end up with a user from one of the two.
+     */
+    user?: string;
     /** Path to the private key file (`~` is expanded by the provider). */
     key?: string;
+    /** Path to a password file (0600, first line is the password) for sshpass. */
+    password?: string;
+    /**
+     * Reference to an `ssh-cred` entry holding the shared credential (key or
+     * password, and optionally the default user). Fields set on the host entry
+     * itself override the referenced credential's.
+     */
+    cred?: string;
     /** SSH port (default 22). */
     port?: number;
 }
+/**
+ * One ssh-cred registry entry: a reusable SSH credential, registered once and
+ * referenced by any number of ssh host entries via their `cred` field.
+ * Mirror of `credEntrySchema` in index.ts — keep the two in sync.
+ */
+export interface SshCredEntry {
+    /** Default login user for hosts referencing this credential. */
+    user?: string;
+    /** Path to the private key file (`~` is expanded by the provider). */
+    key?: string;
+    /** Path to a password file (0600, first line is the password) for sshpass. */
+    password?: string;
+}
 /** Plugin configuration (see `Config` in index.ts). */
 export interface SshProviderConfig {
     /** Save-time validation: timeout for the `ssh-keygen -y` parse (ms). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elinpf/dsh-ops-access-ssh",
-  "version": "0.1.7",
+  "version": "0.2.1",
   "description": "Ops access provider for SSH — validates ssh registry entries and expands key paths.",
   "type": "module",
   "main": "lib/index.js",
@@ -38,14 +38,14 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@elinpf/dsh-ops-access": "^0.1.7"
+    "@elinpf/dsh-ops-access": "^0.2.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.1",
     "@types/node": "^22.0.0",
     "typescript": "^5.4.0",
     "vitest": "^4.1.11",
-    "@elinpf/dsh-ops-access": "0.1.7"
+    "@elinpf/dsh-ops-access": "0.2.1"
   },
   "license": "MIT",
   "publishConfig": {