dsh-ssh-hub 0.0.0-stage → 0.1.9

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 (129) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +255 -2
  3. package/cordis.patch.yml +16 -0
  4. package/icon.svg +3 -0
  5. package/lib/client.js +13766 -0
  6. package/lib/index.js +6727 -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 +199 -0
  15. package/lib/types/client/index.d.ts +45 -0
  16. package/lib/types/client/locales.d.ts +309 -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/TunnelsTab.d.ts +27 -0
  28. package/lib/types/client/panel/controller.d.ts +253 -0
  29. package/lib/types/client/panel/helpers.d.ts +45 -0
  30. package/lib/types/client/panel/tabs.d.ts +62 -0
  31. package/lib/types/client/panel/xterm.css.d.ts +2 -0
  32. package/lib/types/client/settings-binding.d.ts +71 -0
  33. package/lib/types/deploy/orchestrator.d.ts +158 -0
  34. package/lib/types/deploy/tools.d.ts +14 -0
  35. package/lib/types/dsh-home.d.ts +16 -0
  36. package/lib/types/engine/cluster.d.ts +19 -0
  37. package/lib/types/engine/connection-pool.d.ts +183 -0
  38. package/lib/types/engine/proxy-command.d.ts +36 -0
  39. package/lib/types/engine/pty.d.ts +32 -0
  40. package/lib/types/engine/sftp.d.ts +20 -0
  41. package/lib/types/engine/terminal-sessions.d.ts +67 -0
  42. package/lib/types/engine/tunnel-discovery.d.ts +89 -0
  43. package/lib/types/engine/tunnel.d.ts +38 -0
  44. package/lib/types/engine.d.ts +98 -0
  45. package/lib/types/http.d.ts +59 -0
  46. package/lib/types/index.d.ts +128 -0
  47. package/lib/types/inspect/checks.d.ts +118 -0
  48. package/lib/types/inspect/inspection.d.ts +111 -0
  49. package/lib/types/inspect/tools.d.ts +50 -0
  50. package/lib/types/logs/search.d.ts +131 -0
  51. package/lib/types/logs/tools.d.ts +6 -0
  52. package/lib/types/loopback.d.ts +64 -0
  53. package/lib/types/monitor/loop.d.ts +133 -0
  54. package/lib/types/monitor/metrics.d.ts +151 -0
  55. package/lib/types/mount-once.d.ts +55 -0
  56. package/lib/types/protocol.d.ts +518 -0
  57. package/lib/types/routes.d.ts +82 -0
  58. package/lib/types/security/known-hosts.d.ts +153 -0
  59. package/lib/types/security/master-secret.d.ts +157 -0
  60. package/lib/types/security/redact.d.ts +44 -0
  61. package/lib/types/security/secrets.d.ts +70 -0
  62. package/lib/types/ssh-config.d.ts +42 -0
  63. package/lib/types/store.d.ts +183 -0
  64. package/lib/types/tool-surface.d.ts +72 -0
  65. package/lib/types/tools.d.ts +56 -0
  66. package/locale/en.json +6 -0
  67. package/locale/zh.json +6 -0
  68. package/package.json +126 -6
  69. package/src/activity/history.ts +117 -0
  70. package/src/alerting/notify.ts +212 -0
  71. package/src/alerting/prompt-summary.ts +71 -0
  72. package/src/alerting/rules.ts +281 -0
  73. package/src/alerting/tools.ts +263 -0
  74. package/src/audit/audit-log.ts +198 -0
  75. package/src/audit/recorder.ts +73 -0
  76. package/src/client/api.ts +752 -0
  77. package/src/client/css-modules.d.ts +5 -0
  78. package/src/client/index.ts +150 -0
  79. package/src/client/locales.ts +634 -0
  80. package/src/client/native-panel.tsx +141 -0
  81. package/src/client/panel/ClusterTab.tsx +141 -0
  82. package/src/client/panel/DeployTab.tsx +314 -0
  83. package/src/client/panel/FleetTab.tsx +494 -0
  84. package/src/client/panel/HostFormDialog.tsx +289 -0
  85. package/src/client/panel/HostsTab.tsx +395 -0
  86. package/src/client/panel/LogsTab.tsx +208 -0
  87. package/src/client/panel/SshPanel.tsx +105 -0
  88. package/src/client/panel/TerminalTab.tsx +550 -0
  89. package/src/client/panel/TransferTab.tsx +238 -0
  90. package/src/client/panel/TunnelsTab.tsx +306 -0
  91. package/src/client/panel/controller.ts +507 -0
  92. package/src/client/panel/helpers.ts +84 -0
  93. package/src/client/panel/panel.module.css +1712 -0
  94. package/src/client/panel/tabs.ts +52 -0
  95. package/src/client/panel/xterm.css.ts +2 -0
  96. package/src/client/settings-binding.ts +184 -0
  97. package/src/deploy/orchestrator.ts +326 -0
  98. package/src/deploy/tools.ts +225 -0
  99. package/src/dsh-home.ts +42 -0
  100. package/src/engine/cluster.ts +60 -0
  101. package/src/engine/connection-pool.ts +721 -0
  102. package/src/engine/proxy-command.ts +248 -0
  103. package/src/engine/pty.ts +78 -0
  104. package/src/engine/sftp.ts +229 -0
  105. package/src/engine/terminal-sessions.ts +280 -0
  106. package/src/engine/tunnel-discovery.ts +352 -0
  107. package/src/engine/tunnel.ts +205 -0
  108. package/src/engine.ts +187 -0
  109. package/src/http.ts +127 -0
  110. package/src/index.ts +690 -0
  111. package/src/inspect/checks.ts +251 -0
  112. package/src/inspect/inspection.ts +321 -0
  113. package/src/inspect/tools.ts +366 -0
  114. package/src/logs/search.ts +251 -0
  115. package/src/logs/tools.ts +160 -0
  116. package/src/loopback.ts +119 -0
  117. package/src/monitor/loop.ts +265 -0
  118. package/src/monitor/metrics.ts +333 -0
  119. package/src/mount-once.ts +142 -0
  120. package/src/protocol.ts +528 -0
  121. package/src/routes.ts +953 -0
  122. package/src/security/known-hosts.ts +342 -0
  123. package/src/security/master-secret.ts +334 -0
  124. package/src/security/redact.ts +119 -0
  125. package/src/security/secrets.ts +152 -0
  126. package/src/ssh-config.ts +182 -0
  127. package/src/store.ts +757 -0
  128. package/src/tool-surface.ts +96 -0
  129. package/src/tools.ts +517 -0
@@ -0,0 +1,50 @@
1
+ /**
2
+ * Activity history for the two surfaces that produce it: deployment runs and
3
+ * cross-host log searches.
4
+ *
5
+ * Both are append-only NDJSON files under the plugin's home, bounded the same
6
+ * way the metric tiers are: a hard cap on retained records, oldest dropped
7
+ * first. The panel reads them as history; nothing in the host half depends on
8
+ * them, so a missing or corrupt file degrades to "no history yet" rather than
9
+ * failing a route.
10
+ *
11
+ * Why persist at all: a deployment or a log search is an operator action with
12
+ * an outcome they need to look at *after* the panel has moved on. Keeping only
13
+ * the in-memory result would lose it on the next panel switch — and this is
14
+ * exactly the kind of record someone asks about a day later.
15
+ */
16
+ /** One of the history files. */
17
+ export type HistoryKind = 'deploys' | 'logs';
18
+ /**
19
+ * Append-only JSON-lines history with a fixed retention window.
20
+ *
21
+ * Every write is a single `appendFileSync` of one line, so a crash mid-write
22
+ * can at worst truncate the newest record; `read()` skips unparsable lines
23
+ * instead of throwing, which keeps one bad line from hiding all the others.
24
+ */
25
+ export declare class ActivityHistory<T> {
26
+ private readonly kind;
27
+ private readonly file;
28
+ /**
29
+ * @param root - the plugin's home directory.
30
+ * @param kind - which history file this instance owns.
31
+ */
32
+ constructor(root: string, kind: HistoryKind);
33
+ /** The file this history writes to. */
34
+ get path(): string;
35
+ /**
36
+ * Append one record, trimming the file when it exceeds the cap.
37
+ * @param record - the record to store.
38
+ */
39
+ append(record: T): void;
40
+ /**
41
+ * Read the newest records first.
42
+ * @param limit - maximum records to return.
43
+ * @returns the records, newest first.
44
+ */
45
+ read(limit?: number): T[];
46
+ /** Drop the oldest records once the file holds more than the cap. */
47
+ private trim;
48
+ /** Forget every record (the panel's "clear history"). */
49
+ clear(): void;
50
+ }
@@ -0,0 +1,89 @@
1
+ /**
2
+ * Outbound notification: a template-driven HTTP sender.
3
+ *
4
+ * A generic HTTP template with named placeholders covers Bark, Telegram,
5
+ * Lark/Feishu and WeCom without the plugin growing a dependency on each of
6
+ * them — the operator supplies the URL and the body shape, and the plugin
7
+ * substitutes the values.
8
+ *
9
+ * The template placeholders are the ones the operator actually reads:
10
+ * `#SERVER.NAME#`, `#SERVER.ALIAS#`, `#RULE.NAME#`, `#RULE.ID#`,
11
+ * `#VALUE#`, `#MESSAGE#`, `#STATE#`, `#TIME#`.
12
+ *
13
+ * An unknown placeholder is left AS IS rather than replaced with an empty
14
+ * string: a typo in a template must be visible, not silently blank.
15
+ */
16
+ import type { AlertNotification } from './rules.ts';
17
+ /** One notification channel. */
18
+ export interface NotifyChannel {
19
+ /** A stable name for the channel. */
20
+ id: string;
21
+ /** The target URL. */
22
+ url: string;
23
+ /** The HTTP method (default POST). */
24
+ method?: string;
25
+ /** The body template, with placeholders. */
26
+ body?: string;
27
+ /** Extra headers. */
28
+ headers?: Record<string, string>;
29
+ /** The content type (default application/json). */
30
+ contentType?: string;
31
+ }
32
+ /** The outcome of one delivery attempt. */
33
+ export interface NotifyOutcome {
34
+ channelId: string;
35
+ ok: boolean;
36
+ /** The HTTP status, when a response arrived. */
37
+ status?: number;
38
+ /** The error message, when the attempt failed. */
39
+ error?: string;
40
+ }
41
+ /**
42
+ * The placeholders a template may use.
43
+ *
44
+ * @param notification - the event to describe.
45
+ * @param extra - additional key/value pairs (a rule title, a value).
46
+ * @returns the placeholder map.
47
+ */
48
+ export declare function placeholders(notification: AlertNotification, extra?: Record<string, string>): Record<string, string>;
49
+ /**
50
+ * Substitute the placeholders in a template.
51
+ *
52
+ * @param template - the template text.
53
+ * @param values - the placeholder values.
54
+ * @returns the substituted text; unknown placeholders are left as they are.
55
+ */
56
+ export declare function renderTemplate(template: string, values: Record<string, string>): string;
57
+ /**
58
+ * The built-in channel presets.
59
+ *
60
+ * Each preset is a starting point, not a fixed format: the operator can
61
+ * edit the URL and body to match their deployment.
62
+ */
63
+ export declare const NOTIFY_PRESETS: ReadonlyArray<{
64
+ id: string;
65
+ title: string;
66
+ channel: NotifyChannel;
67
+ }>;
68
+ /**
69
+ * Send one notification to one channel.
70
+ *
71
+ * The fetch is deliberately fire-and-forget from the caller's point of
72
+ * view: a failing notification channel must not stop the inspection loop,
73
+ * but its failure IS reported so a broken channel is visible.
74
+ *
75
+ * @param channel - the channel to send to.
76
+ * @param notification - the event.
77
+ * @param extra - extra placeholder values.
78
+ * @returns the delivery outcome.
79
+ */
80
+ export declare function notify(channel: NotifyChannel, notification: AlertNotification, extra?: Record<string, string>): Promise<NotifyOutcome>;
81
+ /**
82
+ * Send one notification to every channel.
83
+ *
84
+ * @param channels - the channels.
85
+ * @param notification - the event.
86
+ * @param extra - extra placeholder values.
87
+ * @returns one outcome per channel.
88
+ */
89
+ export declare function notifyAll(channels: NotifyChannel[], notification: AlertNotification, extra?: Record<string, string>): Promise<NotifyOutcome[]>;
@@ -0,0 +1,28 @@
1
+ /**
2
+ * The alert summary the agent sees in its own prompt.
3
+ *
4
+ * A monitoring loop whose only output is a webhook is invisible to the agent
5
+ * working in this session: it can list hosts and run commands, but it has no
6
+ * way to know the fleet is already on fire unless it thinks to ask. This
7
+ * renders the current alert state into the plugin's prompt section, so a
8
+ * conversation that touches the fleet starts from the same picture the
9
+ * operator has.
10
+ *
11
+ * Deliberately quiet:
12
+ * - nothing firing, and the loop armed → one short line saying so;
13
+ * - nothing firing, loop NOT armed → a line that says the silence means
14
+ * nothing, because "no alerts" and "nothing is checking" are opposite
15
+ * facts that look identical in an empty list;
16
+ * - firing → the rule, the host and the value, newest first, bounded so a
17
+ * fleet-wide outage cannot flood the prompt.
18
+ */
19
+ import type { AlertEngine } from './rules.ts';
20
+ import type { Monitor } from '../monitor/loop.ts';
21
+ /**
22
+ * Render the live alert state for the system prompt.
23
+ *
24
+ * @param alerts - the alert engine holding the per-rule state.
25
+ * @param monitor - the loop, consulted only to say whether the state is being advanced.
26
+ * @returns the summary text, or an empty string when there is nothing to say.
27
+ */
28
+ export declare function renderAlertSummary(alerts: AlertEngine, monitor: Monitor): string;
@@ -0,0 +1,135 @@
1
+ /**
2
+ * Alert rule engine.
3
+ *
4
+ * The state machine here is deliberately conservative, because the failure
5
+ * mode of a monitoring tool is a crying wolf, and a crying wolf gets
6
+ * muted — at which point the tool is worthless.
7
+ *
8
+ * Three rules carry that conservatism:
9
+ *
10
+ * 1. **Consecutive rounds.** A breach must persist for N consecutive
11
+ * rounds before it fires. One spike is noise; a trend is a problem.
12
+ * The operator expresses the requirement in seconds ("3 minutes")
13
+ * and the engine converts it using the poll interval.
14
+ *
15
+ * 2. **null freezes the state.** When a probe cannot read a value (the
16
+ * host timed out, the command failed), the alert state is FROZEN, not
17
+ * cleared. A monitoring probe that goes blind must not report
18
+ * "recovered" — that is how a dead machine ends up looking healthy.
19
+ *
20
+ * 3. **Cooldown blocks re-entry, not recovery.** While an alert is
21
+ * cooling down, a continued breach does not re-notify. But when the
22
+ * value comes back under the threshold, the recovery is ALWAYS
23
+ * notified — an operator who was told "disk full" and never told
24
+ * "disk fine" still has a page open.
25
+ */
26
+ import type { CheckResult } from '../inspect/checks.ts';
27
+ /** The lifecycle state of one alert. */
28
+ export type AlertState =
29
+ /** Healthy: under the threshold. */
30
+ 'ok'
31
+ /** Breaching, but not yet for long enough to fire. */
32
+ | 'pending'
33
+ /** Breaching and fired. */
34
+ | 'firing'
35
+ /** The value could not be read; the previous state is held. */
36
+ | 'frozen';
37
+ /** One alert rule. */
38
+ export interface AlertRule {
39
+ /** Stable identifier. */
40
+ id: string;
41
+ /** The check this rule watches. */
42
+ checkId: string;
43
+ /** Which hosts it covers (empty means every host). */
44
+ hosts?: string[];
45
+ /** How long the breach must persist before it fires, in seconds. */
46
+ forSeconds: number;
47
+ /** How long to wait before re-notifying a continued breach, in seconds. */
48
+ cooldownSeconds: number;
49
+ /** Whether the rule is active. */
50
+ enabled: boolean;
51
+ }
52
+ /** The persisted state of one (rule, host) pair. */
53
+ export interface AlertState_ {
54
+ /** The current state. */
55
+ state: AlertState;
56
+ /**
57
+ * The state held across a blackout.
58
+ *
59
+ * While the probe is blind the state is 'frozen'; this keeps the
60
+ * pre-blackout state so the recovery that follows it is still reported.
61
+ */
62
+ heldState?: 'pending' | 'firing';
63
+ /** Consecutive breaching rounds so far. */
64
+ consecutiveBreaches: number;
65
+ /** When the current breach streak started (epoch ms). */
66
+ breachStartedAt?: number;
67
+ /** When the alert last fired (epoch ms). */
68
+ lastFiredAt?: number;
69
+ /** The value that last fired it. */
70
+ lastValue?: number | boolean | string | null;
71
+ }
72
+ /** A notification the engine wants to send. */
73
+ export interface AlertNotification {
74
+ /** The rule id. */
75
+ ruleId: string;
76
+ /** The host alias. */
77
+ alias: string;
78
+ /** 'trigger' for a new breach, 'recover' for a recovery. */
79
+ kind: 'trigger' | 'recover';
80
+ /** The check title. */
81
+ title: string;
82
+ /** The value that breached (or returned to normal). */
83
+ value: string;
84
+ /** When the event happened. */
85
+ at: number;
86
+ }
87
+ /** The engine's persisted state file. */
88
+ export declare function alertStatePath(): string;
89
+ /**
90
+ * The alert state machine.
91
+ *
92
+ * One instance per plugin apply. The state survives a restart, so an alert
93
+ * that was firing when DSH stopped is still firing when it comes back.
94
+ */
95
+ export declare class AlertEngine {
96
+ /** The state file. */
97
+ readonly path: string;
98
+ /** The state, keyed by `ruleId|alias`. */
99
+ private states;
100
+ constructor(path?: string);
101
+ /**
102
+ * Evaluate one round of inspection results against the rules.
103
+ *
104
+ * @param rules - the rules to apply.
105
+ * @param results - the round's results.
106
+ * @param pollIntervalMs - the poll interval, used to convert the rule's
107
+ * "for" duration into a number of consecutive rounds.
108
+ * @returns the notifications to send.
109
+ */
110
+ evaluate(rules: AlertRule[], results: CheckResult[], pollIntervalMs: number): AlertNotification[];
111
+ /**
112
+ * Evaluate one result against one rule.
113
+ *
114
+ * @param rule - the rule.
115
+ * @param result - the check result.
116
+ * @param pollIntervalMs - the poll interval.
117
+ * @param now - the current time.
118
+ * @returns a notification when the state changed in a way that must be
119
+ * reported, otherwise undefined.
120
+ */
121
+ private evaluateOne;
122
+ /**
123
+ * The current state of every (rule, host) pair.
124
+ *
125
+ * @returns the states.
126
+ */
127
+ list(): Array<{
128
+ ruleId: string;
129
+ alias: string;
130
+ } & AlertState_>;
131
+ /** Load the persisted state. */
132
+ private load;
133
+ /** Persist the state. */
134
+ private save;
135
+ }
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Agent tools for the alerting layer.
3
+ *
4
+ * Three tools:
5
+ * - `hub_alerts` — the current alert states and the recent events
6
+ * - `hub_alert_rules` — list and update the rules
7
+ * - `hub_alert_test` — send a test notification to the configured channels
8
+ *
9
+ * The test tool matters more than it looks: an operator who configured a
10
+ * webhook and never received a message does not know whether the rule
11
+ * never fired or the channel is broken. One call tells them.
12
+ */
13
+ import { AlertEngine, type AlertRule } from './rules.ts';
14
+ import { type NotifyChannel } from './notify.ts';
15
+ /** The default rule set: the checks whose thresholds matter most. */
16
+ export declare function defaultRules(): AlertRule[];
17
+ /** The alerts tool: the current state and the recent events. */
18
+ export declare function hubAlertsTool(engine: AlertEngine, events: AlertEvent[]): import("@deepseek-ai/dsh-tools").ToolDefinition;
19
+ /** The rules tool: list and update the rules. */
20
+ export declare function hubAlertRulesTool(rules: AlertRule[]): import("@deepseek-ai/dsh-tools").ToolDefinition;
21
+ /** The notification test tool. */
22
+ export declare function hubAlertTestTool(channels: NotifyChannel[]): import("@deepseek-ai/dsh-tools").ToolDefinition;
23
+ /** One alert event, as the tools see it. */
24
+ export interface AlertEvent {
25
+ ruleId: string;
26
+ alias: string;
27
+ kind: 'trigger' | 'recover';
28
+ value: string;
29
+ at: number;
30
+ }
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Operation audit log.
3
+ *
4
+ * Every consequential action (exec, cluster, transfer, tunnel, deploy,
5
+ * credential change) is recorded: what happened, against which hosts, with
6
+ * which outcome, and who triggered it.
7
+ *
8
+ * The log is append-only JSON Lines — one record per line — so it can be
9
+ * tailed, grepped and shipped without a database. It lives beside the
10
+ * host store under `$DSH_HOME`, owner-readable only.
11
+ *
12
+ * Two rules the log must never break:
13
+ * 1. No secret ever reaches it. Commands are recorded, but a command that
14
+ * embeds a password is redacted before it is written.
15
+ * 2. A record is written AFTER the outcome is known, so the log says what
16
+ * happened rather than what was attempted.
17
+ */
18
+ /** What kind of action was performed. */
19
+ export type AuditAction = 'host.create' | 'host.update' | 'host.delete' | 'host.test' | 'exec' | 'cluster' | 'upload' | 'download' | 'tunnel.start' | 'tunnel.stop' | 'deploy' | 'rollback' | 'inspect.run' | 'credential.rotate' | 'security.policy';
20
+ /** How the action was triggered. */
21
+ export type AuditActor = 'user' | 'agent' | 'system';
22
+ /** One audit record. */
23
+ export interface AuditRecord {
24
+ /** Epoch milliseconds. */
25
+ ts: number;
26
+ /** What happened. */
27
+ action: AuditAction;
28
+ /** Who triggered it. */
29
+ actor: AuditActor;
30
+ /** The hosts the action touched. */
31
+ targets: string[];
32
+ /** Whether it succeeded. */
33
+ ok: boolean;
34
+ /** A short, human-readable summary (never contains secrets). */
35
+ summary: string;
36
+ /** Free-form details: exit codes, durations, counts. */
37
+ detail?: Record<string, unknown>;
38
+ }
39
+ /** The audit log file path. */
40
+ export declare function auditLogPath(): string;
41
+ /**
42
+ * Redact secrets from a string before it is recorded.
43
+ *
44
+ * @param text - the text to redact.
45
+ * @returns the redacted text.
46
+ */
47
+ export declare function redact(text: string): string;
48
+ /**
49
+ * The audit log writer.
50
+ *
51
+ * Writes are best-effort: a failure to audit must not fail the operation
52
+ * the user asked for (an unwritable log directory should not block a
53
+ * deployment), but the failure is reported so it is not silent.
54
+ */
55
+ export declare class AuditLog {
56
+ /** The file this log writes to. */
57
+ readonly path: string;
58
+ /** The last write error, if any. */
59
+ lastError: string | undefined;
60
+ constructor(path?: string);
61
+ /**
62
+ * Append one record.
63
+ *
64
+ * @param record - the record to write.
65
+ */
66
+ append(record: AuditRecord): void;
67
+ /**
68
+ * Read the most recent records, newest last.
69
+ *
70
+ * @param limit - the maximum number of records to return.
71
+ * @returns the records, oldest first.
72
+ */
73
+ read(limit?: number): AuditRecord[];
74
+ }
75
+ /**
76
+ * A short, stable summary of an exec/cluster outcome.
77
+ *
78
+ * @param alias - the host alias.
79
+ * @param command - the command (redacted by the writer).
80
+ * @param exitCode - the remote exit code.
81
+ * @param durationMs - how long it took.
82
+ * @returns the summary text.
83
+ */
84
+ export declare function execSummary(alias: string, command: string, exitCode: number | null, durationMs: number): string;
@@ -0,0 +1,50 @@
1
+ /**
2
+ * Audit recording for the fleet tools.
3
+ *
4
+ * The audit log answers "who changed this machine, when, and what did they
5
+ * run". That answer is only complete if EVERY mutating operation is
6
+ * recorded — a log that covers some operations is worse than no log,
7
+ * because the operator trusts the gaps to mean "nothing happened".
8
+ *
9
+ * So the recorder wraps the mutating tools at the point where they are
10
+ * registered, and the read-only tools are deliberately not recorded: an
11
+ * audit log full of `ssh_list` calls buries the entries that matter.
12
+ */
13
+ import type { AuditAction, AuditActor, AuditLog } from './audit-log.ts';
14
+ /** The outcome of a tool call, as the recorder sees it. */
15
+ export interface CallOutcome {
16
+ /** Whether the call succeeded. */
17
+ ok: boolean;
18
+ /** The hosts the call touched. */
19
+ targets?: string[];
20
+ /** A short summary (secrets are redacted on write). */
21
+ summary?: string;
22
+ /** Extra structured detail. */
23
+ detail?: Record<string, unknown>;
24
+ }
25
+ /**
26
+ * A recorder bound to one audit log and one actor.
27
+ *
28
+ * The actor matters: an operator running a command from the panel and an
29
+ * agent running the same command are different actors, and an audit trail
30
+ * that cannot tell them apart does not answer "who did this".
31
+ */
32
+ export declare class AuditRecorder {
33
+ /** The log to write to. */
34
+ private readonly log;
35
+ /** Who is performing the actions. */
36
+ private readonly actor;
37
+ constructor(log: AuditLog | undefined, actor?: AuditActor);
38
+ /**
39
+ * Record one action.
40
+ *
41
+ * A missing log means auditing is disabled, which is a configuration
42
+ * choice — the call is then a no-op, not an error.
43
+ *
44
+ * @param action - what happened.
45
+ * @param outcome - the outcome of the call.
46
+ */
47
+ record(action: AuditAction, outcome: CallOutcome): void;
48
+ /** Whether this recorder writes anything. */
49
+ get enabled(): boolean;
50
+ }
@@ -0,0 +1,199 @@
1
+ /**
2
+ * Browser-side API client for the /api/dsh-ssh route family. The only data
3
+ * access path the panel components use — plain fetch/WebSocket, same origin.
4
+ */
5
+ import { type AlertEventRow, type AlertStateRow, type DeployPlanPayload, type DeployRunRow, type LogSearchPayload, type LogSearchRow, type MasterSecretPayload, type MasterSecretResult, type ClusterResult, type ExecResult, type HostChange, type HostPayload, type ImportResult, type InspectionRound, type LocalConfigHost, type MetricBucketRow, type MonitorStatus, type MonitorTickResult, type RemoteDirEntry, type SecurityStatus, type SshHostSummary, type TestResult, type TransferProgress, type TunnelInfo } from '../protocol.ts';
6
+ /** Error carrying the route's JSON error message. */
7
+ export declare class SshApiError extends Error {
8
+ constructor(message: string);
9
+ }
10
+ /** The location facts a terminal socket URL is built from. */
11
+ interface PageLocation {
12
+ /** Page scheme with its colon (for example `https:` or `dsh-app:`). */
13
+ protocol: string;
14
+ /** Page authority, empty for a scheme that carries none. */
15
+ host: string;
16
+ }
17
+ /**
18
+ * The WebSocket URL the terminal route is reached at, or undefined when this
19
+ * page cannot carry one.
20
+ *
21
+ * A web page resolves the socket against its own origin, exactly as before.
22
+ *
23
+ * A page delivered by an application on this machine (the official DSH Desktop
24
+ * shell serves its Web GUI from `dsh-app://app/`) cannot carry a socket on its
25
+ * own scheme: the protocol handler forwards HTTP to the local Host but has no
26
+ * upgrade to forward. That is exactly the case the official transport hook
27
+ * covers - the shell publishes `__DSH_TRANSPORT__.streamBaseUrl`, the loopback
28
+ * authority of the Host it owns and already forwards every other request to
29
+ * (issue #1744). The socket is therefore dialed there instead, with the `ws`/
30
+ * `wss` scheme derived from that base, which is what the shell's
31
+ * `onBeforeSendHeaders` hook expects to see before it attaches its
32
+ * authority-bound credential.
33
+ *
34
+ * The base is used only on an application-delivered page. A web page that
35
+ * somehow carries the hook (the remote channel grants `ownsHost` to a paired
36
+ * LAN page, and that page is fenced behind a pairing channel) keeps resolving
37
+ * against its own origin, so this cannot reroute gated traffic onto a host the
38
+ * page is not entitled to reach. A blank authority is treated the same as an
39
+ * application scheme with no base: there is nothing to dial, and the caller
40
+ * gets the actionable reason instead of a socket that can only fail.
41
+ *
42
+ * @param location - the page location to read.
43
+ * @param search - the query string carrying `alias` or `session`.
44
+ * @param streamBaseUrl - `__DSH_TRANSPORT__.streamBaseUrl`, when the shell published one.
45
+ * @returns the absolute `ws:`/`wss:` URL, or undefined when the page cannot carry one.
46
+ */
47
+ export declare function terminalSocketUrl(location: PageLocation, search: string, streamBaseUrl?: string | undefined): string | undefined;
48
+ /** One open terminal connection (WebSocket JSON frames). */
49
+ export interface TerminalConnection {
50
+ /** Fired on the ready frame (shell is up); carries the host session id and alias. */
51
+ onReady: ((sessionId: string, alias: string) => void) | undefined;
52
+ /** Fired on every output frame. */
53
+ onOutput: ((data: string) => void) | undefined;
54
+ /** Fired on the exit frame (or transport error). */
55
+ onExit: ((code: number | null, error?: string) => void) | undefined;
56
+ /** Fired when the server requests keyboard-interactive 2FA. */
57
+ onAuthPrompt: ((name: string, instructions: string, prompts: Array<{
58
+ prompt: string;
59
+ echo: boolean;
60
+ }>) => void) | undefined;
61
+ /** Send raw input to the remote shell. */
62
+ send(data: string): void;
63
+ /** Resize the remote PTY. */
64
+ resize(cols: number, rows: number): void;
65
+ /** Send interactive 2FA response codes to the remote server. */
66
+ sendAuthResponse(responses: string[]): void;
67
+ /**
68
+ * Leave the socket while the host keeps the remote shell alive, so a later
69
+ * {@link SshApi.attachTerminal} picks the session up where it left off.
70
+ * This is what a view does on unmount; it is not a disconnect.
71
+ */
72
+ detach(): void;
73
+ /** Close the socket and end the remote session. */
74
+ close(): void;
75
+ }
76
+ /** The browser half's only data entry point. */
77
+ export declare class SshApi {
78
+ listHosts(queryText?: string): Promise<SshHostSummary[]>;
79
+ createHost(payload: HostPayload): Promise<SshHostSummary>;
80
+ updateHost(alias: string, patch: HostPayload): Promise<SshHostSummary>;
81
+ deleteHost(alias: string): Promise<void>;
82
+ importSshConfig(): Promise<ImportResult>;
83
+ /** ssh_config hosts that are not in the store yet (read-only preview). */
84
+ listLocalConfigHosts(): Promise<LocalConfigHost[]>;
85
+ testHost(alias: string): Promise<TestResult>;
86
+ exec(alias: string, command: string, timeoutMs?: number): Promise<ExecResult>;
87
+ cluster(options: {
88
+ command: string;
89
+ aliases?: string[];
90
+ environment?: string;
91
+ tags?: string[];
92
+ timeoutMs?: number;
93
+ maxWorkers?: number;
94
+ }): Promise<ClusterResult[]>;
95
+ /** The loop's health: armed, interval, host count, last tick. */
96
+ monitorStatus(): Promise<MonitorStatus>;
97
+ /** Run one round now, through the same path the timer takes. */
98
+ monitorTick(): Promise<MonitorTickResult>;
99
+ /** The retained inspection rounds, newest first. */
100
+ inspectionRounds(limit?: number): Promise<InspectionRound[]>;
101
+ /** What changed between the two most recent rounds. */
102
+ inspectionDiff(): Promise<HostChange[]>;
103
+ /** Alert states plus the recent event feed. */
104
+ alerts(): Promise<{
105
+ states: AlertStateRow[];
106
+ events: AlertEventRow[];
107
+ }>;
108
+ /** A metric series for one host and tier. */
109
+ metrics(alias: string, tier: string, metric?: string, limit?: number): Promise<MetricBucketRow[]>;
110
+ /** Whether credentials are actually encrypted, and why not when they are not. */
111
+ security(): Promise<SecurityStatus>;
112
+ /**
113
+ * Store or clear the master secret.
114
+ *
115
+ * The host decides whether a rotation is needed and refuses a change that
116
+ * would strand encrypted credentials, so the caller must surface `error`
117
+ * rather than assume success from a 200.
118
+ */
119
+ setSecret(payload: MasterSecretPayload): Promise<MasterSecretResult>;
120
+ /** Recorded deployment runs, newest first. */
121
+ deployHistory(limit?: number): Promise<DeployRunRow[]>;
122
+ /** Run a deployment plan and receive the recorded run. */
123
+ deploy(plan: DeployPlanPayload, targets?: string[]): Promise<DeployRunRow>;
124
+ /** Recent cross-host log searches, newest first. */
125
+ logHistory(limit?: number): Promise<LogSearchRow[]>;
126
+ /** Run a cross-host log search. */
127
+ searchLogs(request: LogSearchPayload, targets?: string[]): Promise<LogSearchRow>;
128
+ ls(alias: string, path: string): Promise<RemoteDirEntry[]>;
129
+ listTunnels(): Promise<TunnelInfo[]>;
130
+ startTunnel(options: {
131
+ alias: string;
132
+ remotePort: number;
133
+ remoteHost?: string;
134
+ localPort?: number;
135
+ name?: string;
136
+ description?: string;
137
+ }): Promise<TunnelInfo>;
138
+ stopTunnel(tunnelId: string): Promise<boolean>;
139
+ stopAllTunnels(alias?: string): Promise<number>;
140
+ /**
141
+ * Upload one file (raw bytes) to a remote path. Progress arrives through
142
+ * the NDJSON response stream; resolves when the result frame lands.
143
+ */
144
+ uploadFile(file: File, alias: string, remotePath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
145
+ transferredBytes: number;
146
+ }>;
147
+ /**
148
+ * Download a remote file with client-side progress. Streams straight to
149
+ * disk when the File System Access API is available (no full-file RAM
150
+ * copy); otherwise falls back to an in-memory Blob.
151
+ */
152
+ downloadFile(alias: string, remotePath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
153
+ blob?: Blob;
154
+ filename: string;
155
+ streamed: boolean;
156
+ bytes: number;
157
+ }>;
158
+ /**
159
+ * Open a new host terminal session for the alias.
160
+ * @param alias - the configured host alias.
161
+ * @param cols - initial PTY width.
162
+ * @param rows - initial PTY height.
163
+ * @returns the live connection; its ready callback carries the session id
164
+ * {@link attachTerminal} uses after a view detach.
165
+ */
166
+ openTerminal(alias: string, cols: number, rows: number): TerminalConnection;
167
+ /**
168
+ * Reattach to a host-side session that outlived its view (a panel switch, a
169
+ * page navigation). The host replays its scrollback before the ready frame.
170
+ * @param sessionId - the id the previous connection reported on ready.
171
+ * @param cols - the view's current width.
172
+ * @param rows - the view's current height.
173
+ */
174
+ attachTerminal(sessionId: string, cols: number, rows: number): TerminalConnection;
175
+ /**
176
+ * End a host session this view is not attached to (closing a background
177
+ * tab). The session has no other handle from the browser: giving it a
178
+ * dedicated HTTP route would widen the host's surface for one frame, so this
179
+ * opens one short-lived attach instead and sends the close frame as soon as
180
+ * the socket is open.
181
+ *
182
+ * The answer is "is this session no longer running", which has three
183
+ * truthful answers and one lie to avoid:
184
+ * - the frame went out on an open socket: the host ends the session;
185
+ * - the host answered with an exit frame: an unknown id is reported as
186
+ * `terminal session expired` and an ended shell also exits, and in both
187
+ * cases nothing is running, so the tab really is closed;
188
+ * - the socket errored, closed before opening, or never settled inside
189
+ * `timeoutMs`: delivery is unproven, so the session may still be alive and
190
+ * the caller must keep the tab instead of claiming it closed.
191
+ * @param sessionId - the session id the host reported on its ready frame.
192
+ * @param timeoutMs - bounded wait for the delivery signal (default 5000).
193
+ * @returns true when the session is known to be gone.
194
+ */
195
+ closeTerminalSession(sessionId: string, timeoutMs?: number): Promise<boolean>;
196
+ /** One terminal socket over either an alias (open) or a session id (attach). */
197
+ private terminalSocket;
198
+ }
199
+ export {};