@elinpf/dsh-ops-access-ssh 0.1.0

package/README.i18n.yaml

@@ -0,0 +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"

package/README.md

@@ -0,0 +1,40 @@
+# @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.
+
+## 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`:
+
+- **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)
+
+## 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.
+
+## Installation
+
+Add to `dsh-web-app` dependencies and reference in the ops preset's `agent.cordis.yml`:
+
+```yaml
+- id: ops-access-ssh
+  name: '@elinpf/dsh-ops-access-ssh'
+```
+
+## Configuration
+
+- `validateTimeoutMs` (number, default `5000`) — timeout for the save-time `ssh-keygen -y` parse.
+
+## Testing
+
+```sh
+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).

package/README.zh.md

@@ -0,0 +1,40 @@
+# @elinpf/dsh-ops-access-ssh
+
+ops access 接缝的 SSH 凭据 provider — 校验 `ssh` registry 条目(`{ host, user, key?, port? }`)并为 ssh 消费端工具展开密钥路径。
+
+## 功能
+
+`@elinpf/dsh-ops-access`(core) 下的三个 provider 插件之一。core 拥有 YAML 凭据 registry(`~/.dsh-ops/access.yaml`)和 `ctx.opsAccess` 服务;本包通过 `registerAccessProvider` 只贡献一个凭据种类 `ssh`:
+
+- **条目 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)
+
+## 为什么这样拆
+
+三角色规则(见仓库 `AGENTS.md`):core 拥有 registry 和服务,provider 只带一个 zod schema 加字段处理,消费端工具解析 profile 并拼 shell 命令。本包保持 schema + 处理的最小形态,意味着任何服务都不经手秘密材料 — profile 里只有路径和连接参数。
+
+注册在 `registerAccessProvider` 内部经 `ctx.inject(['opsAccess'], ...)` 延迟挂载,并绑定在插件的 effect 生命周期上,fiber 销毁 / HMR 卸载会把 provider 从 registry 移除。
+
+## 安装
+
+加入 `dsh-web-app` 依赖,并在 ops preset 的 `agent.cordis.yml` 中引用:
+
+```yaml
+- id: ops-access-ssh
+  name: '@elinpf/dsh-ops-access-ssh'
+```
+
+## 配置项
+
+- `validateTimeoutMs`(数字,默认 `5000`)— 保存时 `ssh-keygen -y` 解析的超时时间。
+
+## 测试
+
+```sh
+npm run build
+npx vitest run
+```
+
+测试覆盖:schema 接受/拒绝、`~` 展开、经 mock `opsAccess` 上下文的注册/销毁(含 HMR 卸载),以及 validateContent 的 armor 闸门 + 真实 `ssh-keygen` 解析(在临时目录生成一次性 ed25519 密钥)。

package/cordis.patch.yml

@@ -0,0 +1 @@
+[]

package/lib/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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).
+ *
+ * @module @elinpf/dsh-ops-access-ssh
+ */
+import type { Context } from '@deepseek-ai/cordis';
+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 declare const name = "ops-access-ssh";
+export declare const inject: string[];
+export declare const Config: z<Schemastery.ObjectS<{
+    /** Save-time validation: timeout for the `ssh-keygen -y` parse (ms). */
+    validateTimeoutMs: z<number, number>;
+}>, Schemastery.ObjectT<{
+    /** 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). */
+export declare const entrySchema: zod.ZodObject<{
+    host: zod.ZodString;
+    user: zod.ZodString;
+    key: zod.ZodOptional<zod.ZodString>;
+    port: zod.ZodOptional<zod.ZodNumber>;
+}, zod.core.$strip>;
+export declare const provider: AccessProvider;
+export declare function apply(ctx: Context, config: SshProviderConfig): void;

package/lib/index.js

@@ -0,0 +1,101 @@
+/**
+ * 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).
+ *
+ * @module @elinpf/dsh-ops-access-ssh
+ */
+import z from '@deepseek-ai/schemastery';
+import { z as zod } from 'zod';
+import { expandHome, registerAccessProvider } from '@elinpf/dsh-ops-access';
+import { execFile } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+// ── Plugin identity ───────────────────────────────────────────────────────────
+export const name = 'ops-access-ssh';
+export const inject = [];
+export const Config = z.object({
+    /** Save-time validation: timeout for the `ssh-keygen -y` parse (ms). */
+    validateTimeoutMs: z.number().default(5000),
+});
+// ── Provider ─────────────────────────────────────────────────────────────────
+/** Zod schema for one ssh registry entry (excluding name and envelope fields). */
+export const entrySchema = zod.object({
+    host: zod.string(),
+    user: zod.string(),
+    key: zod.string().optional(),
+    port: zod.number().optional(),
+});
+// 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;
+    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)';
+    }
+    const dir = await mkdtemp(join(tmpdir(), 'ops-ssh-key-'));
+    try {
+        const keyPath = join(dir, 'key');
+        await writeFile(keyPath, content, { mode: 0o600 });
+        try {
+            await execFileAsync('ssh-keygen', ['-y', '-P', '', '-f', keyPath], { timeout: keygenTimeoutMs });
+            return null;
+        }
+        catch (err) {
+            const e = err;
+            // No ssh-keygen on this host: fall back to the armor gate above —
+            // the deep parse is a bonus, not a new hard dependency.
+            if (e.code === 'ENOENT')
+                return null;
+            const stderr = typeof e.stderr === 'string' && e.stderr.length > 0 ? e.stderr : String(e.message ?? err);
+            if (/passphrase/i.test(stderr) || content.includes('ENCRYPTED')) {
+                return 'the private key is passphrase-protected — the ssh tool runs BatchMode=yes and cannot answer prompts; remove the passphrase first (ssh-keygen -p)';
+            }
+            const detail = stderr.split('\n').map((l) => l.trim()).filter((l) => l.length > 0).pop() ?? 'unknown parse error';
+            return 'ssh-keygen cannot parse this key (' + detail + ') — the paste is corrupt; re-copy the key file verbatim';
+        }
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+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'],
+    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 };
+        if (key !== undefined)
+            fields.key = expandHome(key);
+        if (port !== undefined)
+            fields.port = port;
+        return fields;
+    },
+    // Core normalizes the trailing newline before this hook (PEM requires
+    // 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),
+};
+// ── Plugin apply ─────────────────────────────────────────────────────────────
+export function apply(ctx, config) {
+    registerAccessProvider(ctx, {
+        ...provider,
+        validateContent: (field, content) => validateKeyContent(field, content, config.validateTimeoutMs),
+    });
+}

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-access-ssh.
+ *
+ * @module @elinpf/dsh-ops-access-ssh/invariant
+ */
+/** Cordis companion plugin name. */
+declare const name = "ops-access-ssh-invariant";
+/** Service required before the companion can reserve package ownership. */
+declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Context carrying the invariant service.
+ * @returns a promise resolving after registration.
+ */
+declare const apply: (ctx: any) => Promise<void>;
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,26 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-access-ssh.
+ *
+ * @module @elinpf/dsh-ops-access-ssh/invariant
+ */
+const PACKAGE_NAME = '@elinpf/dsh-ops-access-ssh';
+/** Cordis companion plugin name. */
+const name = 'ops-access-ssh-invariant';
+/** Service required before the companion can reserve package ownership. */
+const inject = ['invariants'];
+/**
+ * No runtime invariant: this provider owns no session events and no durable
+ * shape of its own — it only contributes a zod schema plus field processing
+ * to the ops-access registry, and entry validation happens at save time in
+ * core (schema parse + validateContent), before anything is persisted.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Context carrying the invariant service.
+ * @returns a promise resolving after registration.
+ */
+const apply = async (ctx) => {
+    ctx.invariants.register(PACKAGE_NAME, install);
+};
+export { apply, inject, name };

package/lib/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Type definitions for the ops-access SSH provider.
+ *
+ * @module @elinpf/dsh-ops-access-ssh
+ */
+/**
+ * One ssh registry entry (excluding name and the envelope fields).
+ *
+ * This is the hand-written mirror of the runtime `entrySchema` in index.ts —
+ * keep the two in sync when fields change.
+ */
+export interface SshEntry {
+    /** Hostname or IP of the target. */
+    host: string;
+    /** Login user. */
+    user: string;
+    /** Path to the private key file (`~` is expanded by the provider). */
+    key?: string;
+    /** SSH port (default 22). */
+    port?: number;
+}
+/** Plugin configuration (see `Config` in index.ts). */
+export interface SshProviderConfig {
+    /** Save-time validation: timeout for the `ssh-keygen -y` parse (ms). */
+    validateTimeoutMs: number;
+}

package/lib/types.js

@@ -0,0 +1,6 @@
+/**
+ * Type definitions for the ops-access SSH provider.
+ *
+ * @module @elinpf/dsh-ops-access-ssh
+ */
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@elinpf/dsh-ops-access-ssh",
+  "version": "0.1.0",
+  "description": "Ops access provider for SSH — validates ssh registry entries and expands key paths.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@elinpf/dsh-ops-access": "^0.1.0"
+  },
+  "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.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}