dsh-ssh-hub 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +271 -2
  3. package/cordis.patch.yml +16 -0
  4. package/icon.svg +3 -0
  5. package/lib/client.js +13975 -0
  6. package/lib/index.js +6908 -0
  7. package/lib/types/activity/history.d.ts +50 -0
  8. package/lib/types/alerting/notify.d.ts +89 -0
  9. package/lib/types/alerting/prompt-summary.d.ts +28 -0
  10. package/lib/types/alerting/rules.d.ts +135 -0
  11. package/lib/types/alerting/tools.d.ts +30 -0
  12. package/lib/types/audit/audit-log.d.ts +84 -0
  13. package/lib/types/audit/recorder.d.ts +50 -0
  14. package/lib/types/client/api.d.ts +222 -0
  15. package/lib/types/client/index.d.ts +45 -0
  16. package/lib/types/client/locales.d.ts +319 -0
  17. package/lib/types/client/native-panel.d.ts +70 -0
  18. package/lib/types/client/panel/ClusterTab.d.ts +7 -0
  19. package/lib/types/client/panel/DeployTab.d.ts +10 -0
  20. package/lib/types/client/panel/FleetTab.d.ts +10 -0
  21. package/lib/types/client/panel/HostFormDialog.d.ts +12 -0
  22. package/lib/types/client/panel/HostsTab.d.ts +25 -0
  23. package/lib/types/client/panel/LogsTab.d.ts +10 -0
  24. package/lib/types/client/panel/SshPanel.d.ts +14 -0
  25. package/lib/types/client/panel/TerminalTab.d.ts +27 -0
  26. package/lib/types/client/panel/TransferTab.d.ts +7 -0
  27. package/lib/types/client/panel/TunnelEditDialog.d.ts +15 -0
  28. package/lib/types/client/panel/TunnelsTab.d.ts +27 -0
  29. package/lib/types/client/panel/controller.d.ts +253 -0
  30. package/lib/types/client/panel/helpers.d.ts +45 -0
  31. package/lib/types/client/panel/tabs.d.ts +62 -0
  32. package/lib/types/client/panel/xterm.css.d.ts +2 -0
  33. package/lib/types/client/settings-binding.d.ts +71 -0
  34. package/lib/types/deploy/orchestrator.d.ts +158 -0
  35. package/lib/types/deploy/tools.d.ts +14 -0
  36. package/lib/types/dsh-home.d.ts +16 -0
  37. package/lib/types/engine/cluster.d.ts +19 -0
  38. package/lib/types/engine/connection-pool.d.ts +183 -0
  39. package/lib/types/engine/proxy-command.d.ts +36 -0
  40. package/lib/types/engine/pty.d.ts +32 -0
  41. package/lib/types/engine/sftp.d.ts +20 -0
  42. package/lib/types/engine/terminal-sessions.d.ts +67 -0
  43. package/lib/types/engine/tunnel-discovery.d.ts +89 -0
  44. package/lib/types/engine/tunnel-remarks.d.ts +49 -0
  45. package/lib/types/engine/tunnel.d.ts +76 -0
  46. package/lib/types/engine.d.ts +103 -0
  47. package/lib/types/http.d.ts +59 -0
  48. package/lib/types/index.d.ts +128 -0
  49. package/lib/types/inspect/checks.d.ts +118 -0
  50. package/lib/types/inspect/inspection.d.ts +111 -0
  51. package/lib/types/inspect/tools.d.ts +50 -0
  52. package/lib/types/logs/search.d.ts +131 -0
  53. package/lib/types/logs/tools.d.ts +6 -0
  54. package/lib/types/loopback.d.ts +64 -0
  55. package/lib/types/monitor/loop.d.ts +133 -0
  56. package/lib/types/monitor/metrics.d.ts +151 -0
  57. package/lib/types/mount-once.d.ts +55 -0
  58. package/lib/types/protocol.d.ts +524 -0
  59. package/lib/types/routes.d.ts +82 -0
  60. package/lib/types/security/known-hosts.d.ts +153 -0
  61. package/lib/types/security/master-secret.d.ts +157 -0
  62. package/lib/types/security/redact.d.ts +44 -0
  63. package/lib/types/security/secrets.d.ts +70 -0
  64. package/lib/types/ssh-config.d.ts +42 -0
  65. package/lib/types/store.d.ts +183 -0
  66. package/lib/types/tool-surface.d.ts +72 -0
  67. package/lib/types/tools.d.ts +56 -0
  68. package/locale/en.json +6 -0
  69. package/locale/zh.json +6 -0
  70. package/package.json +126 -6
  71. package/src/activity/history.ts +117 -0
  72. package/src/alerting/notify.ts +212 -0
  73. package/src/alerting/prompt-summary.ts +71 -0
  74. package/src/alerting/rules.ts +281 -0
  75. package/src/alerting/tools.ts +263 -0
  76. package/src/audit/audit-log.ts +199 -0
  77. package/src/audit/recorder.ts +73 -0
  78. package/src/client/api.ts +782 -0
  79. package/src/client/css-modules.d.ts +5 -0
  80. package/src/client/index.ts +150 -0
  81. package/src/client/locales.ts +654 -0
  82. package/src/client/native-panel.tsx +141 -0
  83. package/src/client/panel/ClusterTab.tsx +141 -0
  84. package/src/client/panel/DeployTab.tsx +314 -0
  85. package/src/client/panel/FleetTab.tsx +494 -0
  86. package/src/client/panel/HostFormDialog.tsx +289 -0
  87. package/src/client/panel/HostsTab.tsx +395 -0
  88. package/src/client/panel/LogsTab.tsx +208 -0
  89. package/src/client/panel/SshPanel.tsx +105 -0
  90. package/src/client/panel/TerminalTab.tsx +550 -0
  91. package/src/client/panel/TransferTab.tsx +238 -0
  92. package/src/client/panel/TunnelEditDialog.tsx +174 -0
  93. package/src/client/panel/TunnelsTab.tsx +328 -0
  94. package/src/client/panel/controller.ts +507 -0
  95. package/src/client/panel/helpers.ts +84 -0
  96. package/src/client/panel/panel.module.css +1734 -0
  97. package/src/client/panel/tabs.ts +52 -0
  98. package/src/client/panel/xterm.css.ts +2 -0
  99. package/src/client/settings-binding.ts +184 -0
  100. package/src/deploy/orchestrator.ts +326 -0
  101. package/src/deploy/tools.ts +225 -0
  102. package/src/dsh-home.ts +42 -0
  103. package/src/engine/cluster.ts +60 -0
  104. package/src/engine/connection-pool.ts +721 -0
  105. package/src/engine/proxy-command.ts +248 -0
  106. package/src/engine/pty.ts +78 -0
  107. package/src/engine/sftp.ts +229 -0
  108. package/src/engine/terminal-sessions.ts +280 -0
  109. package/src/engine/tunnel-discovery.ts +353 -0
  110. package/src/engine/tunnel-remarks.ts +120 -0
  111. package/src/engine/tunnel.ts +300 -0
  112. package/src/engine.ts +195 -0
  113. package/src/http.ts +127 -0
  114. package/src/index.ts +690 -0
  115. package/src/inspect/checks.ts +251 -0
  116. package/src/inspect/inspection.ts +321 -0
  117. package/src/inspect/tools.ts +366 -0
  118. package/src/logs/search.ts +251 -0
  119. package/src/logs/tools.ts +160 -0
  120. package/src/loopback.ts +119 -0
  121. package/src/monitor/loop.ts +265 -0
  122. package/src/monitor/metrics.ts +333 -0
  123. package/src/mount-once.ts +142 -0
  124. package/src/protocol.ts +534 -0
  125. package/src/routes.ts +998 -0
  126. package/src/security/known-hosts.ts +342 -0
  127. package/src/security/master-secret.ts +334 -0
  128. package/src/security/redact.ts +119 -0
  129. package/src/security/secrets.ts +152 -0
  130. package/src/ssh-config.ts +182 -0
  131. package/src/store.ts +757 -0
  132. package/src/tool-surface.ts +96 -0
  133. package/src/tools.ts +550 -0
@@ -0,0 +1,153 @@
1
+ /**
2
+ * Host-key verification against the user's OpenSSH `known_hosts` file.
3
+ *
4
+ * The base plugin never set ssh2's `hostVerifier`, so every connection
5
+ * accepted whatever key the server presented — a real MITM surface on a
6
+ * fleet where one forged connection reaches every host.
7
+ *
8
+ * This module parses `known_hosts` the way OpenSSH does (plain, bracket,
9
+ * wildcard and `@revoked` entries; SHA256 fingerprints) and turns that into
10
+ * the verifier ssh2 calls for each connection.
11
+ *
12
+ * Three policies, selected by configuration:
13
+ * - `off` — no verification (the base plugin's behaviour; the default so
14
+ * an upgrade never locks an existing user out)
15
+ * - `tofu` — trust on first use: an unknown host is recorded and the
16
+ * connection proceeds; a CHANGED key is always refused
17
+ * - `strict` — an unknown host is refused; the user must accept it first
18
+ *
19
+ * A refused connection must explain itself: the message carries the expected
20
+ * fingerprint, the presented one, and the file path, so the user can decide
21
+ * without reading source.
22
+ */
23
+ /** How a host key is treated when it is not (or is no longer) trusted. */
24
+ export type HostKeyPolicy = 'off' | 'tofu' | 'strict';
25
+ /** One known_hosts entry, after parsing. */
26
+ interface KnownHostEntry {
27
+ /** Host patterns this entry covers (unhashed). */
28
+ patterns: string[];
29
+ /** True when the original entry used a hashed host name. */
30
+ hashed: boolean;
31
+ /** The key type, e.g. `ssh-ed25519`. */
32
+ keyType: string;
33
+ /** The base64 key blob — the whole blob, exactly as OpenSSH stores it. */
34
+ key: string;
35
+ /** True when the entry was marked `@revoked`. */
36
+ revoked: boolean;
37
+ }
38
+ /** A parsed known_hosts file plus the path it came from. */
39
+ export interface KnownHostsFile {
40
+ path: string;
41
+ entries: KnownHostEntry[];
42
+ /** True when the file exists and was read. */
43
+ present: boolean;
44
+ }
45
+ /** The default known_hosts path: `~/.ssh/known_hosts`. */
46
+ export declare function defaultKnownHostsPath(): string;
47
+ /**
48
+ * Parse a known_hosts file.
49
+ *
50
+ * Supported forms:
51
+ * - `host-patterns key-type base64 [comment]`
52
+ * - `[host]:port key-type base64 [comment]` (bracket form for non-22 ports)
53
+ * - `@revoked host-patterns key-type base64 [comment]`
54
+ * - hashed host names (`|1|base64|base64`)
55
+ *
56
+ * Lines that do not parse are skipped: OpenSSH itself ignores them, and a
57
+ * single malformed line must not make every other entry unusable.
58
+ *
59
+ * @param path - the file to read.
60
+ * @returns the parsed entries and whether the file was present.
61
+ */
62
+ export declare function parseKnownHosts(path: string): KnownHostsFile;
63
+ /**
64
+ * The SHA256 fingerprint OpenSSH and ssh2 display for a key.
65
+ *
66
+ * OpenSSH hashes the **whole key blob** — the same bytes base64-encoded in
67
+ * a known_hosts line — so this hashes the decoded blob directly.
68
+ *
69
+ * @param key - the base64 key blob.
70
+ * @returns the `SHA256:...` fingerprint, base64 without padding.
71
+ */
72
+ export declare function fingerprint(key: string): string;
73
+ /**
74
+ * Find the known_hosts entries that cover one host:port.
75
+ *
76
+ * @param file - the parsed file.
77
+ * @param host - the hostname or address.
78
+ * @param port - the SSH port.
79
+ * @returns every covering entry, revoked ones included.
80
+ */
81
+ export declare function entriesFor(file: KnownHostsFile, host: string, port: number): KnownHostEntry[];
82
+ /** The outcome of a host-key check. */
83
+ export type HostKeyDecision =
84
+ /** The key matches a trusted entry. */
85
+ {
86
+ action: 'accept';
87
+ }
88
+ /** The key is unknown; `fingerprint` is the one the server presented. */
89
+ | {
90
+ action: 'unknown';
91
+ fingerprint: string;
92
+ }
93
+ /** The key differs from the trusted one — a possible MITM. */
94
+ | {
95
+ action: 'mismatch';
96
+ expected: string;
97
+ received: string;
98
+ path: string;
99
+ }
100
+ /** The trusted entry is marked `@revoked`. */
101
+ | {
102
+ action: 'revoked';
103
+ fingerprint: string;
104
+ path: string;
105
+ };
106
+ /**
107
+ * Decide what to do with a presented host key.
108
+ *
109
+ * @param file - the parsed known_hosts file.
110
+ * @param host - the hostname or address.
111
+ * @param port - the SSH port.
112
+ * @param keyType - the presented key type.
113
+ * @param presentedKey - the presented key blob (base64).
114
+ * @returns the decision.
115
+ */
116
+ export declare function decide(file: KnownHostsFile, host: string, port: number, keyType: string, presentedKey: string): HostKeyDecision;
117
+ /** The host-key verification state handed to ssh2. */
118
+ export interface HostKeyVerifierOptions {
119
+ /** The policy in force. */
120
+ policy: HostKeyPolicy;
121
+ /** The known_hosts file path. */
122
+ path: string;
123
+ /** The host this verifier is bound to (ssh2 passes only the key). */
124
+ host: string;
125
+ /** The port this verifier is bound to. */
126
+ port: number;
127
+ /** Called when an unknown host must be recorded (TOFU). */
128
+ onRecord?: (host: string, port: number, keyType: string, key: string) => void;
129
+ }
130
+ /**
131
+ * Build the ssh2 `hostVerifier` callback for one connection.
132
+ *
133
+ * ssh2 calls it with the server's key blob; returning a boolean accepts or
134
+ * denies the key (ssh2 also accepts the callback form, but a synchronous
135
+ * verdict cannot half-apply). The verifier reads the file on every call so
136
+ * an edit made outside this plugin — a manual `ssh` session, another tool —
137
+ * takes effect on the next connection.
138
+ *
139
+ * @param options - the policy, file path and the connection's host/port.
140
+ * @returns the verifier callback.
141
+ */
142
+ export declare function createHostVerifier(options: HostKeyVerifierOptions): (key: Buffer) => boolean;
143
+ /**
144
+ * Record a trusted host key in the known_hosts file.
145
+ *
146
+ * @param path - the file to append to.
147
+ * @param host - the hostname or address.
148
+ * @param port - the SSH port.
149
+ * @param keyType - the key type.
150
+ * @param key - the base64 key blob.
151
+ */
152
+ export declare function recordKnownHost(path: string, host: string, port: number, keyType: string, key: string): void;
153
+ export {};
@@ -0,0 +1,157 @@
1
+ /**
2
+ * Master-secret management for the credential envelope.
3
+ *
4
+ * The secret itself lives outside the store on purpose: `DSH_SSH_HUB_SECRET`
5
+ * (environment) or a key file, never inside `dsh-ssh.json`. That means the
6
+ * panel cannot "just set" it — it has to write a file with the right
7
+ * permissions and then re-encrypt every stored entry that was sealed with the
8
+ * previous secret, because a secret change without rotation silently locks
9
+ * the operator out of their own credentials.
10
+ *
11
+ * Three operations, each with the failure mode it refuses:
12
+ *
13
+ * - `status()` — where the secret comes from, if at all.
14
+ * - `setKey()` — write the key file. Refuses to overwrite an existing file
15
+ * that this plugin did not create (a foreign file may be the
16
+ * operator's own keystore), and refuses a weak secret.
17
+ * - `rotate()` — re-seal every entry with the new secret. Runs as one
18
+ * rewrite: entries are re-sealed in memory and written
19
+ * together, so a failure never leaves a half-rotated store.
20
+ *
21
+ * The plaintext side of the tradeoff is explicit: encryption activates only
22
+ * when a secret exists. There is no default, because a default key is a
23
+ * backdoor and every installation would share it.
24
+ */
25
+ import type { HostStore } from '../store.ts';
26
+ /** Environment variable that carries the master secret directly. */
27
+ export declare const SECRET_ENV = "DSH_SSH_HUB_SECRET";
28
+ /** Environment variable naming a file that carries the master secret. */
29
+ export declare const SECRET_FILE_ENV = "DSH_SSH_HUB_SECRET_FILE";
30
+ /** Minimum master-secret length. Short secrets are the whole weakness. */
31
+ export declare const MIN_SECRET_LENGTH = 16;
32
+ /** Where the secret came from. */
33
+ export type SecretSource = 'env' | 'file' | 'none';
34
+ /** The key-file location this plugin owns. */
35
+ export declare function defaultKeyPath(dshHome: string): string;
36
+ /**
37
+ * Read the master secret.
38
+ *
39
+ * A file-provided value is trimmed of exactly one trailing newline (a file
40
+ * written by `echo` would otherwise carry an invisible `\n` into the derived
41
+ * key, producing a secret nobody can reproduce by typing it).
42
+ *
43
+ * @param keyPath - the key file to read when the env vars are absent.
44
+ * @returns the secret, or undefined when none is configured.
45
+ */
46
+ export declare function readMasterSecret(keyPath: string): string | undefined;
47
+ /**
48
+ * Report where the secret comes from.
49
+ * @param keyPath - the key file to check.
50
+ * @returns the source label.
51
+ */
52
+ export declare function masterSecretSource(keyPath: string): SecretSource;
53
+ /** One entry whose stored secrets are still plaintext. */
54
+ export interface PlaintextReport {
55
+ /** Aliases holding a readable plaintext password or passphrase. */
56
+ aliases: string[];
57
+ }
58
+ /**
59
+ * Find entries whose secrets would still be readable without the master key.
60
+ *
61
+ * This reads the store file directly, because `HostStore.list()` returns
62
+ * decrypted entries and therefore cannot tell plaintext from ciphertext. The
63
+ * distinction is the whole point: an operator enabling encryption needs to
64
+ * know whether anything is still exposed on disk.
65
+ *
66
+ * @param storePath - the store file path.
67
+ * @returns the aliases whose stored secrets are plaintext.
68
+ */
69
+ export declare function findPlaintextEntries(storePath: string): PlaintextReport;
70
+ /** What a key-file write did. */
71
+ export interface KeyWriteResult {
72
+ ok: boolean;
73
+ path: string;
74
+ /** Set when the write was refused or failed. */
75
+ error?: string;
76
+ }
77
+ /**
78
+ * Write the master secret to the key file with owner-only permissions.
79
+ *
80
+ * Refusals are deliberate:
81
+ * - a secret shorter than MIN_SECRET_LENGTH is rejected (it would be the only
82
+ * thing standing between a file copy and every credential in it),
83
+ * - an existing file the caller did not create is never overwritten, because
84
+ * it may hold a key the operator is still using,
85
+ * - a file is never left behind half-written.
86
+ *
87
+ * @param keyPath - destination path.
88
+ * @param secret - the new secret.
89
+ * @param overwrite - replace an existing key file (the panel's "rotate").
90
+ * @returns the outcome.
91
+ */
92
+ export declare function writeMasterKey(keyPath: string, secret: string, overwrite: boolean): KeyWriteResult;
93
+ /**
94
+ * Generate a secret strong enough to be worth using.
95
+ * @returns 32 random bytes, base64url-encoded.
96
+ */
97
+ export declare function generateSecret(): string;
98
+ /** Outcome of a rotation. */
99
+ export interface RotateResult {
100
+ ok: boolean;
101
+ /** Entries whose secrets were re-sealed. */
102
+ rotated: number;
103
+ /** Entries that could not be re-sealed with the previous secret. */
104
+ unreadable: string[];
105
+ error?: string;
106
+ }
107
+ /**
108
+ * Re-encrypt every stored entry under a new master secret.
109
+ *
110
+ * Rotation is the step that makes a secret change safe: entries sealed with
111
+ * the old secret become unreadable the moment the key file changes, so the
112
+ * new key must be in place before the entries are re-sealed, and the entries
113
+ * must have been read while the old key was still live.
114
+ *
115
+ * The order is therefore: read and verify with the old secret → commit the new
116
+ * secret → re-seal in one pass. On a failed re-seal the old key is restored,
117
+ * so the store never ends up sealed under a key that is not on disk.
118
+ *
119
+ * This deliberately does NOT install a protector of its own. The store's
120
+ * protector resolves the secret from disk on every call, so a rotation that
121
+ * handed it a captured secret would pin the store to that secret for the life
122
+ * of the process — after which deleting or rotating the key file would change
123
+ * nothing, and new credentials would be sealed with a key nothing on disk can
124
+ * reproduce.
125
+ *
126
+ * An entry that cannot be decrypted with the old secret is reported, not
127
+ * dropped: it is evidence of a wrong key or a tampered file, and silently
128
+ * deleting it would destroy the operator's only record of that host.
129
+ *
130
+ * @param store - the host store (its protector reads the live secret).
131
+ * @param oldSecret - the secret currently protecting the store.
132
+ * @param newSecret - the secret to protect it with from now on.
133
+ * @param commit - writes the new secret to wherever the protector reads it.
134
+ * @returns the rotation outcome.
135
+ */
136
+ export declare function rotateSecrets(store: HostStore, oldSecret: string, newSecret: string, commit: (secret: string) => KeyWriteResult): RotateResult;
137
+ /**
138
+ * Read one entry's stored (still encrypted or plaintext) auth block.
139
+ * @param storePath - the store file.
140
+ * @param alias - the entry to read.
141
+ * @returns the stored auth block, or undefined when absent.
142
+ */
143
+ export declare function readStoredAuth(storePath: string, alias: string): {
144
+ password?: unknown;
145
+ passphrase?: unknown;
146
+ } | undefined;
147
+ /**
148
+ * Remove the key file this plugin manages.
149
+ *
150
+ * Refuses when the active secret comes from the environment: deleting a file
151
+ * the environment only *names* would not change the active secret, so the
152
+ * caller would believe encryption was off while it stayed on.
153
+ *
154
+ * @param keyPath - the key file.
155
+ * @returns the outcome.
156
+ */
157
+ export declare function removeMasterKey(keyPath: string): KeyWriteResult;
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Output redaction for remote command results.
3
+ *
4
+ * The base plugin returns exec and cluster output verbatim. That output is
5
+ * the model's context AND, in DSH, part of the session log — so a command
6
+ * like `env` or `cat /etc/redis.conf` writes the remote secrets into a
7
+ * transcript that outlives the session and lands in every backup of it.
8
+ *
9
+ * This module redacts the shapes a secret actually takes in command
10
+ * output. It is a safety net, not a guarantee: the tool cannot know every
11
+ * secret on the remote host. The tool description says so, so the model
12
+ * does not treat the redacted output as safe to reason about freely.
13
+ *
14
+ * Redaction is deliberately conservative about what it hides — a false
15
+ * positive costs a little context, a false negative costs a credential.
16
+ */
17
+ /**
18
+ * Redact secrets from command output.
19
+ *
20
+ * @param text - the output to redact.
21
+ * @returns the redacted text.
22
+ */
23
+ export declare function redactOutput(text: string): string;
24
+ /**
25
+ * Redact a command line before it is logged or displayed.
26
+ *
27
+ * A command may itself carry a secret as an argument (`mysql -p hunter2`,
28
+ * `curl -H 'Authorization: Bearer ...'`), which the output rules would
29
+ * never see.
30
+ *
31
+ * @param command - the command line.
32
+ * @returns the redacted command.
33
+ */
34
+ export declare function redactCommand(command: string): string;
35
+ /**
36
+ * Which rules matched an output.
37
+ *
38
+ * Useful for the audit log: the operator can see that a result was
39
+ * redacted without seeing what was hidden.
40
+ *
41
+ * @param text - the original text.
42
+ * @returns the ids of the rules that matched.
43
+ */
44
+ export declare function matchedRules(text: string): string[];
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Credential encryption: an encrypted envelope for the secrets that live
3
+ * alongside a host entry (passwords, key passphrases).
4
+ *
5
+ * The base plugin stored those in plaintext inside `dsh-ssh.json` — a
6
+ * user-owned file, but plaintext means every backup, every accidental
7
+ * copy and every process running as the same user can read them.
8
+ *
9
+ * The envelope here is deliberately simple and auditable:
10
+ * - a random 32-byte data key encrypts the payload (AES-256-GCM)
11
+ * - the data key is itself wrapped with a key derived from a master secret
12
+ * (scrypt, with a per-file random salt)
13
+ * - authentication is GCM's, so a tampered file fails to decrypt rather
14
+ * than yielding garbage
15
+ *
16
+ * The master secret comes from the environment (`DSH_SSH_HUB_SECRET`), a
17
+ * key file, or the DSH credentials service. There is deliberately NO
18
+ * default: a default master secret would be a backdoor, and silently
19
+ * falling back to plaintext would defeat the point of encrypting at all.
20
+ * When no secret is configured, `secretsEnabled` is false and the store
21
+ * keeps the base plugin's plaintext behaviour.
22
+ */
23
+ /** The envelope version, so a future format change can be detected. */
24
+ export declare const ENVELOPE_VERSION = 1;
25
+ /** The encrypted form of one secret. */
26
+ export interface SealedSecret {
27
+ /** Envelope version. */
28
+ v: number;
29
+ /** Algorithm tag ('aes-256-gcm'). */
30
+ alg: string;
31
+ /** Base64 salt for the key derivation. */
32
+ salt: string;
33
+ /** Base64 initialisation vector. */
34
+ iv: string;
35
+ /** Base64 authentication tag. */
36
+ tag: string;
37
+ /** Base64 ciphertext. */
38
+ data: string;
39
+ }
40
+ /**
41
+ * Encrypt one secret value.
42
+ *
43
+ * Two layers, each with its own IV — GCM requires a unique nonce per key,
44
+ * so the payload cipher and the key-wrap cipher must never share one.
45
+ *
46
+ * @param plaintext - the secret to protect.
47
+ * @param masterSecret - the master secret.
48
+ * @returns the sealed envelope.
49
+ */
50
+ export declare function seal(plaintext: string, masterSecret: string): SealedSecret;
51
+ /**
52
+ * Decrypt one sealed secret.
53
+ *
54
+ * @param envelope - the sealed envelope.
55
+ * @param masterSecret - the master secret.
56
+ * @returns the plaintext.
57
+ * @throws when the envelope is malformed, tampered with, or was sealed with
58
+ * a different master secret.
59
+ */
60
+ export declare function open(envelope: SealedSecret, masterSecret: string): string;
61
+ /**
62
+ * Is a value already a sealed envelope?
63
+ *
64
+ * Used when reading a store that may hold either form (a store written
65
+ * before encryption was enabled still holds plaintext).
66
+ *
67
+ * @param value - the value to inspect.
68
+ * @returns true when the value is an envelope.
69
+ */
70
+ export declare function isSealed(value: unknown): value is SealedSecret;
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Minimal `~/.ssh/config` reader for the one-shot host import: Host blocks with
3
+ * `Include` expansion and explicit skip reasons. Values stay raw strings; the
4
+ * store maps them onto a HostPayload.
5
+ *
6
+ * Deliberate simplifications (documented in the package README):
7
+ * - `Match` blocks are skipped — their options are conditional and must never
8
+ * merge into the Host block above them.
9
+ * - A multi-pattern `Host a b` line only exposes its first pattern.
10
+ * - Include pathnames accept `~`, globs, and several whitespace-separated
11
+ * pathnames, but not environment variables, `%` tokens, or quoting.
12
+ * - Relative Include pathnames resolve against the directory of the config
13
+ * file the import started from (OpenSSH: `~/.ssh` for a user config).
14
+ * - A file that already contributed lines is never read twice, which doubles
15
+ * as the Include cycle guard.
16
+ */
17
+ import type { ImportSkipBlock } from './protocol.ts';
18
+ /** One parsed Host block. */
19
+ export interface SshBlock {
20
+ /** Raw Host line value (may hold several whitespace-separated patterns). */
21
+ pattern: string;
22
+ /** Lowercased option key/value pairs; the last occurrence of a key wins. */
23
+ props: Record<string, string>;
24
+ /**
25
+ * Every value seen for a key that legitimately repeats, in file order.
26
+ * `IdentityFile` may appear several times and OpenSSH tries each one, so
27
+ * keeping only the last occurrence silently breaks a host that relies on a
28
+ * second key — `ssh <alias>` works while this plugin reports "All configured
29
+ * authentication methods failed".
30
+ */
31
+ repeated: Record<string, string[]>;
32
+ }
33
+ /** One config file read, with every Include expanded in place. */
34
+ export interface SshConfigRead {
35
+ blocks: SshBlock[];
36
+ skipped: ImportSkipBlock[];
37
+ }
38
+ /**
39
+ * Parse one ssh_config file (Include expanded) into Host blocks plus the
40
+ * `Match` blocks that were deliberately skipped.
41
+ */
42
+ export declare function readSshConfigBlocks(configPath: string): SshConfigRead;
@@ -0,0 +1,183 @@
1
+ /**
2
+ * Host config store: one JSON file (`$DSH_HOME/dsh-ssh.json`, defaulting
3
+ * to `~/.dsh`) holding every
4
+ * SSH host entry, written atomically (tmp + rename). Also parses the user's
5
+ * standard `~/.ssh/config` for one-shot import.
6
+ *
7
+ * Secrets (passwords, passphrases) are protected by a `SecretProtector`
8
+ * when one is configured: the stored value is then an encrypted envelope
9
+ * instead of plaintext. Without a protector the store keeps the base
10
+ * plugin's plaintext behaviour, so an existing installation is never
11
+ * locked out by enabling encryption.
12
+ */
13
+ import type { HostPayload, ImportResult, LocalConfigHost, SshHostEntry, SshHostSummary } from './protocol.ts';
14
+ /**
15
+ * Encrypts and decrypts the secrets stored alongside a host entry.
16
+ *
17
+ * A protector is optional on purpose: with no master secret configured the
18
+ * store writes plaintext exactly as the base plugin did, so switching
19
+ * encryption on is a deliberate act by the operator.
20
+ */
21
+ export interface SecretProtector {
22
+ /** Encrypt one secret for storage. */
23
+ seal(plaintext: string): unknown;
24
+ /** Decrypt a stored secret; returns undefined when it is not a sealed value. */
25
+ open(stored: unknown): string | undefined;
26
+ }
27
+ /** Store file location: $DSH_HOME/dsh-ssh.json (defaults to ~/.dsh). */
28
+ export declare function storePath(): string;
29
+ /** The user's standard OpenSSH config path. */
30
+ export declare function sshConfigPath(): string;
31
+ /** Validate the wire shape of a host payload; returns a message or undefined. */
32
+ export declare function validateHostPayload(payload: unknown): string | undefined;
33
+ /** Validate an alias for creation. */
34
+ export declare function validateAlias(alias: string): string | undefined;
35
+ /**
36
+ * The host store. Pure file I/O — no cordis dependency, unit-testable.
37
+ */
38
+ export declare class HostStore {
39
+ /** The JSON file path. */
40
+ readonly path: string;
41
+ /** Optional override of the ~/.ssh/config path (tests). */
42
+ private readonly sshConfigOverride;
43
+ /** Optional encryptor for the stored secrets. */
44
+ private readonly protector;
45
+ /**
46
+ * @param path - store file path (defaults to the standard location).
47
+ * @param sshConfigOverride - ssh config path override (tests only).
48
+ * @param protector - encryptor for stored secrets (tests / production).
49
+ */
50
+ constructor(path?: string, sshConfigOverride?: string, protector?: SecretProtector);
51
+ /** Load all entries (empty store when the file is absent). */
52
+ list(): SshHostEntry[];
53
+ /** Find one entry by alias. */
54
+ find(alias: string): SshHostEntry | undefined;
55
+ /**
56
+ * Decrypt one stored entry's secrets.
57
+ *
58
+ * A value that is not a sealed envelope is passed through unchanged, so
59
+ * a store written before encryption was enabled keeps working.
60
+ *
61
+ * @param entry - the stored entry.
62
+ * @returns the entry with plaintext secrets.
63
+ */
64
+ private decryptEntry;
65
+ /**
66
+ * Encrypt one entry's secrets for storage.
67
+ *
68
+ * @param entry - the entry with plaintext secrets.
69
+ * @returns the entry as it is written to disk.
70
+ */
71
+ private encryptEntry;
72
+ /** Secret-free projection for the browser and agent surfaces. */
73
+ summarize(entry: SshHostEntry): SshHostSummary;
74
+ /** Create one entry. Throws on alias collision or invalid payload. */
75
+ create(payload: HostPayload): SshHostEntry;
76
+ /** Update the fields present in `patch`; unknown aliases throw. */
77
+ update(alias: string, patch: Partial<HostPayload>): SshHostEntry;
78
+ /** Remove one entry. */
79
+ delete(alias: string): void;
80
+ /**
81
+ * Import hosts from `~/.ssh/config`: Host blocks with a single non-wildcard
82
+ * pattern become entries (a missing HostName falls back to the pattern
83
+ * itself; key auth via IdentityFile; jump hosts via ProxyJump; ProxyCommand
84
+ * kept verbatim). `Include` files are expanded, and `Match` blocks,
85
+ * wildcard patterns, and aliases that already exist are skipped with a
86
+ * reason instead of silently disappearing.
87
+ * @returns import statistics.
88
+ */
89
+ importFromSshConfig(): ImportResult;
90
+ /**
91
+ * ssh_config hosts that this store does not contain yet.
92
+ *
93
+ * The import button used to be the only signal that local config exists, and
94
+ * its only feedback was a count in a notice. Listing the candidates makes the
95
+ * gap visible before the click, which is the difference between "the panel
96
+ * cannot read my SSH config" and "these three hosts are waiting to be added".
97
+ * @returns unimported hosts in file order, with what the import would use.
98
+ */
99
+ listLocalConfigHosts(): LocalConfigHost[];
100
+ /**
101
+ * Correct an already-stored host from its ssh_config block.
102
+ *
103
+ * Only the shapes that silently break a working `ssh <alias>` or strictly
104
+ * missing documentation are repaired, and only when the stored value is strictly
105
+ * missing information — never to undo a deliberate user edit:
106
+ * 1. a host with no description when the config provides one;
107
+ * 2. a key host that the config gives more candidate keys than it stores;
108
+ * 3. a host that stores `password` with no password while the config asks
109
+ * for the `none` method.
110
+ * @param existing - the stored entry.
111
+ * @param identityFiles - every IdentityFile from the block, in order.
112
+ * @param prefersNone - whether the block asks for the `none` method.
113
+ * @param description - optional description from the config block.
114
+ * @returns true when the entry was changed.
115
+ */
116
+ private reconcileExisting;
117
+ private skippedBlocks;
118
+ /**
119
+ * Last parsed store keyed by file identity. list/find ride every acquire
120
+ * and GUI refresh; re-reading and re-parsing the whole file each call is
121
+ * wasted work when the file has not changed. Any save invalidates.
122
+ */
123
+ private cache;
124
+ private load;
125
+ private save;
126
+ /**
127
+ * Rewrite every entry's stored secrets under this store's protector.
128
+ *
129
+ * Rotation needs one write that changes the sealing key for the WHOLE file.
130
+ * Calling `update()` per entry cannot do that: `update` reads the stored
131
+ * file, decrypts it with the current protector, and re-seals with the same
132
+ * one — so it would rewrite each entry under the old key and the operator's
133
+ * new key would open nothing.
134
+ *
135
+ * This method takes the entries already decrypted (by `list()` under the
136
+ * previous protector) and re-seals them in a single `save()`, so there is no
137
+ * window where half the file is sealed with one key and half with another.
138
+ *
139
+ * @param entries - the entries with plaintext secrets.
140
+ */
141
+ resealAll(entries: SshHostEntry[]): void;
142
+ }
143
+ /** Normalize an agent endpoint for storage: trim, expand `~`, and resolve the SSH_AUTH_SOCK token. */
144
+ export declare function normalizeAgentPath(agentPath: string | undefined): string | undefined;
145
+ /**
146
+ * Normalize a ProxyCommand for storage: trim, and treat an empty value or
147
+ * OpenSSH's `none` keyword as "no proxy command" (an explicit clear).
148
+ */
149
+ export declare function normalizeProxyCommand(raw: string | undefined): string | undefined;
150
+ /**
151
+ * Read an ssh_config `ForwardAgent` value into the stored boolean flag. Only
152
+ * an explicit yes/true/on enables forwarding; an absent value, no/false/off,
153
+ * and anything unrecognized leave it off instead of failing the import — an
154
+ * unknown keyword must never cost the user the whole Host block.
155
+ */
156
+ export declare function parseForwardAgentValue(raw: string | undefined): boolean;
157
+ /**
158
+ * Every private key this entry may authenticate with, in try order.
159
+ *
160
+ * `keyPaths` (the whole IdentityFile list) wins when present; older entries
161
+ * store only `keyPath`. Duplicates are dropped so a config that repeats the
162
+ * same path does not pay for a second handshake.
163
+ * @param entry - a stored host entry (secrets irrelevant).
164
+ * @returns candidate key paths, possibly empty.
165
+ */
166
+ export declare function keyCandidates(entry: {
167
+ auth: {
168
+ keyPath?: string;
169
+ keyPaths?: string[];
170
+ };
171
+ }): string[];
172
+ /**
173
+ * Whether an ssh_config `PreferredAuthentications` list offers `none`.
174
+ *
175
+ * `none` is a real method: the client asks the server to accept the username
176
+ * with no credential, which some sandboxes do. An absent value means `none` was
177
+ * not requested, so callers must not infer it.
178
+ * @param raw - the raw option value, if any.
179
+ * @returns true when the method list contains `none`.
180
+ */
181
+ export declare function prefersNone(raw: string | undefined): boolean;
182
+ /** Expand a leading `~` in a filesystem path. */
183
+ export declare function expandHome(path: string): string;