dsh-lan-guard 0.1.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.
- package/CHANGELOG.md +363 -0
- package/LICENSE +21 -0
- package/README.md +107 -0
- package/README.zh.md +111 -0
- package/cordis.patch.yml +11 -0
- package/lib/client.js +875 -0
- package/lib/client.js.map +1 -0
- package/lib/index.d.ts +517 -0
- package/lib/index.js +3343 -0
- package/package.json +103 -0
package/lib/index.d.ts
ADDED
|
@@ -0,0 +1,517 @@
|
|
|
1
|
+
import z from "@deepseek-ai/schemastery";
|
|
2
|
+
import { IncomingMessage } from "node:http";
|
|
3
|
+
import { Context } from "@deepseek-ai/cordis";
|
|
4
|
+
//#region src/config.d.ts
|
|
5
|
+
/** Gate mode (docs/SPEC.md F3). `scope` is deliberately absent — this project has one LAN channel. */
|
|
6
|
+
type AuthMode = 'password' | 'token' | 'token_and_password';
|
|
7
|
+
/** Who may reach the management surface (docs/SPEC.md F3). */
|
|
8
|
+
type AdminPolicy = 'password_unlock' | 'local_only' | 'open';
|
|
9
|
+
/** Certificate source (docs/SPEC.md F4). */
|
|
10
|
+
type TlsMode = 'self-signed' | 'provided' | 'off';
|
|
11
|
+
/** The `auth` block of the config. */
|
|
12
|
+
interface AuthConfigShape {
|
|
13
|
+
/** Master switch for the visitor-side gate. `false` is only legal on a loopback listener. */
|
|
14
|
+
enabled: boolean;
|
|
15
|
+
/** Which visitor credentials are accepted. */
|
|
16
|
+
mode: AuthMode;
|
|
17
|
+
/** How the management surface unlocks. */
|
|
18
|
+
adminPolicy: AdminPolicy;
|
|
19
|
+
/** Whether management operations need an explicit admin unlock on top of a session. */
|
|
20
|
+
adminProtection: boolean;
|
|
21
|
+
/** Whether loopback visitors skip the gate (the local user already has direct DSH access). */
|
|
22
|
+
allowLoopback: boolean;
|
|
23
|
+
/** Whether a new device must name itself once before it is let in (P4-g). */
|
|
24
|
+
requirePairing: boolean;
|
|
25
|
+
/** Visitor session lifetime in milliseconds. */
|
|
26
|
+
sessionMaxAgeMs: number;
|
|
27
|
+
/** Admin session lifetime in milliseconds (in-memory only, so it is deliberately short). */
|
|
28
|
+
adminSessionMaxAgeMs: number;
|
|
29
|
+
/** Failed attempts per IP before the lockout window opens. */
|
|
30
|
+
maxFailedAttempts: number;
|
|
31
|
+
/** Lockout window in milliseconds. */
|
|
32
|
+
lockoutMs: number;
|
|
33
|
+
}
|
|
34
|
+
/** The `tls` block of the config. */
|
|
35
|
+
interface TlsConfigShape {
|
|
36
|
+
/** Certificate source; `self-signed` is the default. */
|
|
37
|
+
mode: TlsMode;
|
|
38
|
+
/** PEM CA certificate for `mode: 'provided'`. */
|
|
39
|
+
caCertFile: string | null;
|
|
40
|
+
/** PEM CA private key for `mode: 'provided'`. */
|
|
41
|
+
caKeyFile: string | null;
|
|
42
|
+
/** PEM leaf certificate for `mode: 'provided'`. */
|
|
43
|
+
certFile: string | null;
|
|
44
|
+
/** PEM leaf private key for `mode: 'provided'`. */
|
|
45
|
+
keyFile: string | null;
|
|
46
|
+
/**
|
|
47
|
+
* Explicit acknowledgement required to serve plain HTTP on a NON-loopback
|
|
48
|
+
* listener (P4-e). Defaults to false: the gate password and the upstream
|
|
49
|
+
* cookie would travel the LAN in clear text (docs/SPEC.md §6.2).
|
|
50
|
+
*/
|
|
51
|
+
allowInsecureLan: boolean;
|
|
52
|
+
}
|
|
53
|
+
/** The full non-sensitive config shape (docs/SPEC.md §5). */
|
|
54
|
+
interface MdnsConfigShape {
|
|
55
|
+
/** Whether to advertise the console over mDNS/DNS-SD (off by default). */
|
|
56
|
+
enabled: boolean;
|
|
57
|
+
}
|
|
58
|
+
interface LanGuardConfigShape {
|
|
59
|
+
/** Plugin master switch; `false` registers nothing and opens no listener. */
|
|
60
|
+
enabled: boolean;
|
|
61
|
+
/** Bind address: loopback, all interfaces, or one NIC literal. */
|
|
62
|
+
listenHost: string;
|
|
63
|
+
/** Proxy port; `0` asks the OS for a free port (tests only). */
|
|
64
|
+
listenPort: number;
|
|
65
|
+
/** The loopback origin requests are forwarded to. */
|
|
66
|
+
upstreamOrigin: string;
|
|
67
|
+
/** Optional NIC selector (docs/SPEC.md F5). */
|
|
68
|
+
networkInterface: string | null;
|
|
69
|
+
/** Private directory for sensitive state; required, never guessed. */
|
|
70
|
+
dataDir: string | null;
|
|
71
|
+
/** Visitor-side gate configuration. */
|
|
72
|
+
auth: AuthConfigShape;
|
|
73
|
+
/** Transport security configuration. */
|
|
74
|
+
tls: TlsConfigShape;
|
|
75
|
+
/** Optional mDNS advertisement (P4-d). */
|
|
76
|
+
mdns: MdnsConfigShape;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* The entry's config schema. Also the `dsh-lan-guard` settings form on DSH
|
|
80
|
+
* 0.1.7 — the Loader entry id is the form namespace, so this object must stay
|
|
81
|
+
* the documented field set.
|
|
82
|
+
*
|
|
83
|
+
* The five NON-SENSITIVE switches (docs/SPEC.md F6, PLAN §5 工作项 9) are
|
|
84
|
+
* `.volatile()`: an edit commits into the running references and emits a
|
|
85
|
+
* volatile update instead of remounting the plugin, and the host `settings`
|
|
86
|
+
* service refuses to write any path that is not volatile
|
|
87
|
+
* (docs/RESEARCH.md §4.1). A volatile field's runtime value is a stable
|
|
88
|
+
* reference with `get()`, not the bare value — {@link parseConfig} unwraps it,
|
|
89
|
+
* and {@link liveSwitches} keeps the reference so later edits are visible
|
|
90
|
+
* without a restart.
|
|
91
|
+
*
|
|
92
|
+
* NOTE on the nullable fields: Schemastery treats a `null` default as "no
|
|
93
|
+
* fallback" (`if (isNullable(fallback)) return [data]`), so a field declared
|
|
94
|
+
* `.default(null)` stays `undefined` when omitted. The documented `null`
|
|
95
|
+
* defaults are therefore expressed as an empty string in the schema and
|
|
96
|
+
* normalized back to `null` in {@link parseConfig} — an explicit `null` in a
|
|
97
|
+
* patch file is accepted and normalized the same way.
|
|
98
|
+
*/
|
|
99
|
+
declare const Config: z<LanGuardConfigShape, Record<string, unknown>>;
|
|
100
|
+
/** The live, non-sensitive switches. */
|
|
101
|
+
interface LiveSwitches {
|
|
102
|
+
/** Plugin master switch. */
|
|
103
|
+
enabled(): boolean;
|
|
104
|
+
/** Selected NIC / address, or `null` for "pick automatically". */
|
|
105
|
+
networkInterface(): string | null;
|
|
106
|
+
/** Configured listen port (applies on the next start). */
|
|
107
|
+
listenPort(): number;
|
|
108
|
+
/** Visitor credential mode. */
|
|
109
|
+
mode(): AuthMode;
|
|
110
|
+
/** Management unlock policy. */
|
|
111
|
+
adminPolicy(): AdminPolicy;
|
|
112
|
+
/** Whether management operations need an explicit unlock. */
|
|
113
|
+
adminProtection(): boolean;
|
|
114
|
+
/** Whether loopback visitors skip the gate. */
|
|
115
|
+
allowLoopback(): boolean;
|
|
116
|
+
/** Whether an unnamed device must pair before it is let in. */
|
|
117
|
+
requirePairing(): boolean;
|
|
118
|
+
}
|
|
119
|
+
//#endregion
|
|
120
|
+
//#region src/log.d.ts
|
|
121
|
+
/**
|
|
122
|
+
* dsh-lan-guard — the logger surface this plugin uses.
|
|
123
|
+
*
|
|
124
|
+
* DSH hands a Cordis logger to `ctx.logger(...)`, which already satisfies this
|
|
125
|
+
* shape. Declaring the narrow interface here keeps the rest of the plugin
|
|
126
|
+
* testable with a stub, and keeps every call site honest about the one rule
|
|
127
|
+
* that matters: NO credential is ever passed to a log call
|
|
128
|
+
* (docs/GUARDRAILS.md §4).
|
|
129
|
+
*/
|
|
130
|
+
interface LanGuardLogger {
|
|
131
|
+
/** Routine lifecycle and request information. */
|
|
132
|
+
info(message: string, ...args: unknown[]): void;
|
|
133
|
+
/** Recoverable problems (upstream unavailable, session re-exchange). */
|
|
134
|
+
warn(message: string, ...args: unknown[]): void;
|
|
135
|
+
/** Optional verbose diagnostics. */
|
|
136
|
+
debug?(message: string, ...args: unknown[]): void;
|
|
137
|
+
}
|
|
138
|
+
//#endregion
|
|
139
|
+
//#region src/store/secrets.d.ts
|
|
140
|
+
/** The persisted secrets document. */
|
|
141
|
+
interface SecretsFile {
|
|
142
|
+
version: 1;
|
|
143
|
+
/** `pbkdf2-sha256$<iterations>$<hex>`, or a legacy bare hex digest. */
|
|
144
|
+
passwordHash: string | null;
|
|
145
|
+
/** Salt as hex. */
|
|
146
|
+
passwordSalt: string | null;
|
|
147
|
+
/** Independent admin password hash, same format. */
|
|
148
|
+
adminPasswordHash: string | null;
|
|
149
|
+
/** Admin salt as hex. */
|
|
150
|
+
adminPasswordSalt: string | null;
|
|
151
|
+
/** Passwordless-link token: `dsh_` + 36 hex characters. */
|
|
152
|
+
secretToken: string | null;
|
|
153
|
+
}
|
|
154
|
+
/** One paired device. The plaintext token is NEVER stored — only its hash. */
|
|
155
|
+
interface DeviceRecord {
|
|
156
|
+
/** Short opaque id used by the UI. */
|
|
157
|
+
id: string;
|
|
158
|
+
/** Operator-supplied label ("iPhone", "iPad"…). */
|
|
159
|
+
label: string;
|
|
160
|
+
/** SHA-256 (hex) of the device token. */
|
|
161
|
+
tokenHash: string;
|
|
162
|
+
/** Creation time. */
|
|
163
|
+
createdAtMs: number;
|
|
164
|
+
/** Last time this device used its link. */
|
|
165
|
+
lastSeenAtMs: number | null;
|
|
166
|
+
/** Address the device last came from. */
|
|
167
|
+
lastIp: string | null;
|
|
168
|
+
/** Revocation time, or `null` while active. */
|
|
169
|
+
revokedAtMs: number | null;
|
|
170
|
+
}
|
|
171
|
+
/** One persisted visitor session. */
|
|
172
|
+
interface SessionRecord {
|
|
173
|
+
/** Opaque session token (the cookie value). */
|
|
174
|
+
token: string;
|
|
175
|
+
/** Absolute expiry in epoch milliseconds. */
|
|
176
|
+
expiresAtMs: number;
|
|
177
|
+
/** When it was created, for diagnostics. */
|
|
178
|
+
createdAtMs: number;
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* Owns the plugin's private data directory.
|
|
182
|
+
*/
|
|
183
|
+
declare class SecretsStore {
|
|
184
|
+
#private;
|
|
185
|
+
constructor(dataDir: string, logger?: LanGuardLogger);
|
|
186
|
+
/** Absolute path of the secrets document. */
|
|
187
|
+
get secretsPath(): string;
|
|
188
|
+
/** Absolute path of the persistent session document. */
|
|
189
|
+
get sessionsPath(): string;
|
|
190
|
+
/** Absolute path of the paired-device document. */
|
|
191
|
+
get devicesPath(): string;
|
|
192
|
+
/** Create the private directory if needed. */
|
|
193
|
+
ensureDir(): Promise<void>;
|
|
194
|
+
/**
|
|
195
|
+
* Load the secrets document.
|
|
196
|
+
*
|
|
197
|
+
* @returns the stored secrets, or an empty document when none exists yet.
|
|
198
|
+
* @throws when the file exists but is unreadable — refusing to start beats
|
|
199
|
+
* starting with an empty password (the "any password works" failure).
|
|
200
|
+
*/
|
|
201
|
+
loadSecrets(): Promise<SecretsFile>;
|
|
202
|
+
/** Persist the secrets document with mode 600. */
|
|
203
|
+
saveSecrets(secrets: SecretsFile): Promise<void>;
|
|
204
|
+
/** Load persisted visitor sessions; a corrupt file yields an empty list (sessions are renewable). */
|
|
205
|
+
loadSessions(): Promise<SessionRecord[]>;
|
|
206
|
+
/** Persist visitor sessions with mode 600. */
|
|
207
|
+
saveSessions(records: readonly SessionRecord[]): Promise<void>;
|
|
208
|
+
/** Load paired devices; a corrupt file yields an empty list (no device is trusted by default). */
|
|
209
|
+
loadDevices(): Promise<DeviceRecord[]>;
|
|
210
|
+
/** Persist paired devices with mode 600. */
|
|
211
|
+
saveDevices(devices: readonly DeviceRecord[]): Promise<void>;
|
|
212
|
+
}
|
|
213
|
+
//#endregion
|
|
214
|
+
//#region src/auth/manager.d.ts
|
|
215
|
+
/** Why a request was refused. */
|
|
216
|
+
type DenyReason = 'unauthorized' | 'locked';
|
|
217
|
+
/** The gate's verdict for one request. */
|
|
218
|
+
type VerifyResult = {
|
|
219
|
+
ok: true;
|
|
220
|
+
via: 'disabled' | 'loopback' | 'session';
|
|
221
|
+
} | {
|
|
222
|
+
ok: false;
|
|
223
|
+
reason: DenyReason;
|
|
224
|
+
lockedUntilMs?: number;
|
|
225
|
+
};
|
|
226
|
+
/** Result of one password attempt. */
|
|
227
|
+
type LoginResult = {
|
|
228
|
+
ok: true;
|
|
229
|
+
cookie: string;
|
|
230
|
+
expiresAtMs: number;
|
|
231
|
+
} | {
|
|
232
|
+
ok: false;
|
|
233
|
+
reason: 'invalid' | 'locked' | 'no-password';
|
|
234
|
+
lockedUntilMs?: number;
|
|
235
|
+
};
|
|
236
|
+
/** Options for {@link AuthManager}. */
|
|
237
|
+
interface AuthManagerOptions {
|
|
238
|
+
store: SecretsStore;
|
|
239
|
+
/** Static knobs (session lifetimes, lockout budget). */
|
|
240
|
+
auth: AuthConfigShape;
|
|
241
|
+
/** The five live switches; defaults to the static values in `auth`. */
|
|
242
|
+
switches?: LiveSwitches;
|
|
243
|
+
logger?: LanGuardLogger;
|
|
244
|
+
/** Clock injection for tests. */
|
|
245
|
+
now?: () => number;
|
|
246
|
+
}
|
|
247
|
+
/** The visitor gate. */
|
|
248
|
+
declare class AuthManager {
|
|
249
|
+
#private;
|
|
250
|
+
constructor(options: AuthManagerOptions);
|
|
251
|
+
/** Load persisted secrets and sessions, then start the expiry sweeper. */
|
|
252
|
+
init(): Promise<void>;
|
|
253
|
+
/** Stop the sweeper. */
|
|
254
|
+
dispose(): void;
|
|
255
|
+
/** Whether an access password is configured at all. */
|
|
256
|
+
get hasPassword(): boolean;
|
|
257
|
+
/** Whether an independent admin password is configured. */
|
|
258
|
+
get hasAdminPassword(): boolean;
|
|
259
|
+
/** Whether a passwordless-link token exists. */
|
|
260
|
+
get hasSecretToken(): boolean;
|
|
261
|
+
/** The live visitor credential mode (drives the login page). */
|
|
262
|
+
get mode(): AuthMode;
|
|
263
|
+
/** Whether the gate is switched on. */
|
|
264
|
+
get enabled(): boolean;
|
|
265
|
+
/** The passwordless-link token, for the admin-unlocked settings view only. */
|
|
266
|
+
secretToken(): string | undefined;
|
|
267
|
+
/** Set (or replace) the access password. */
|
|
268
|
+
setPassword(password: string): Promise<void>;
|
|
269
|
+
/** Set (or replace) the independent admin password. */
|
|
270
|
+
setAdminPassword(password: string): Promise<void>;
|
|
271
|
+
/** Ensure a passwordless-link token exists, returning it. */
|
|
272
|
+
ensureSecretToken(): Promise<string>;
|
|
273
|
+
/** Replace the passwordless-link token with a fresh one. */
|
|
274
|
+
rotateSecretToken(): Promise<string>;
|
|
275
|
+
/** Per-IP failure state, for the login page's honest lockout display. */
|
|
276
|
+
lockoutFor(ip: string): {
|
|
277
|
+
failures: number;
|
|
278
|
+
lockedUntilMs: number;
|
|
279
|
+
};
|
|
280
|
+
/**
|
|
281
|
+
* Decide whether one request may proceed.
|
|
282
|
+
*
|
|
283
|
+
* @param req - the incoming request (HTTP or upgrade).
|
|
284
|
+
* @returns the verdict; `ok: false` carries why.
|
|
285
|
+
*/
|
|
286
|
+
verifyRequest(req: IncomingMessage): VerifyResult;
|
|
287
|
+
/**
|
|
288
|
+
* Validate one visitor password and, on success, mint a session.
|
|
289
|
+
*
|
|
290
|
+
* @param req - the login request (for the client IP).
|
|
291
|
+
* @param password - the submitted password.
|
|
292
|
+
* @returns the session cookie to send, or why it failed.
|
|
293
|
+
*/
|
|
294
|
+
login(req: IncomingMessage, password: string): Promise<LoginResult>;
|
|
295
|
+
/** Verify a candidate against the access password (the "change password" flow). */
|
|
296
|
+
verifyAccessPassword(candidate: string): Promise<boolean>;
|
|
297
|
+
/** Verify a candidate against the admin password, falling back to the access password when unset. */
|
|
298
|
+
verifyAdminPassword(candidate: string): Promise<boolean>;
|
|
299
|
+
/** Validate the passwordless-link token. */
|
|
300
|
+
verifySecretToken(candidate: string): Promise<boolean>;
|
|
301
|
+
/** Mint a session without a password (a validated passwordless link). */
|
|
302
|
+
issueSession(): Promise<{
|
|
303
|
+
cookie: string;
|
|
304
|
+
expiresAtMs: number;
|
|
305
|
+
}>;
|
|
306
|
+
/**
|
|
307
|
+
* Validate the admin password and unlock the management surface.
|
|
308
|
+
*
|
|
309
|
+
* Deliberately independent of any visitor session: the researched
|
|
310
|
+
* dsh-bridge deadlock was an unlock that required a valid visitor session,
|
|
311
|
+
* so an expired session made the management console permanently unlockable
|
|
312
|
+
* (docs/RESEARCH.md §5.5).
|
|
313
|
+
*
|
|
314
|
+
* @param password - the submitted admin password (falls back to the access password when unset).
|
|
315
|
+
* @returns the admin cookie, or `undefined` when the password is wrong.
|
|
316
|
+
*/
|
|
317
|
+
unlockAdmin(password: string): Promise<{
|
|
318
|
+
cookie: string;
|
|
319
|
+
expiresAtMs: number;
|
|
320
|
+
} | undefined>;
|
|
321
|
+
/** Lock the management surface again. */
|
|
322
|
+
lockAdmin(req: IncomingMessage): void;
|
|
323
|
+
/** Whether this request carries a live admin session. */
|
|
324
|
+
isAdminUnlocked(req: IncomingMessage): boolean;
|
|
325
|
+
/** Whether the admin surface should be shown locked, given the policy. */
|
|
326
|
+
requiresAdminUnlock(req: IncomingMessage): boolean;
|
|
327
|
+
/**
|
|
328
|
+
* Drop every visitor session.
|
|
329
|
+
*
|
|
330
|
+
* Called when the access password or the auth mode changes: otherwise a phone
|
|
331
|
+
* that already logged in keeps its 30-day session and never sees the new
|
|
332
|
+
* requirement (user report 2026-09-24: "我改成了需要密码,但用户却不需要输入").
|
|
333
|
+
*
|
|
334
|
+
* @returns how many sessions were dropped.
|
|
335
|
+
*/
|
|
336
|
+
revokeAllSessions(): Promise<number>;
|
|
337
|
+
}
|
|
338
|
+
//#endregion
|
|
339
|
+
//#region src/store/devices.d.ts
|
|
340
|
+
/** Options for {@link DeviceRegistry}. */
|
|
341
|
+
interface DeviceRegistryOptions {
|
|
342
|
+
store: SecretsStore;
|
|
343
|
+
logger?: LanGuardLogger;
|
|
344
|
+
now?: () => number;
|
|
345
|
+
}
|
|
346
|
+
/** The paired-device registry. */
|
|
347
|
+
declare class DeviceRegistry {
|
|
348
|
+
#private;
|
|
349
|
+
constructor(options: DeviceRegistryOptions);
|
|
350
|
+
/** Load the persisted device list. */
|
|
351
|
+
init(): Promise<void>;
|
|
352
|
+
/** Active and revoked devices, newest first. */
|
|
353
|
+
list(): DeviceRecord[];
|
|
354
|
+
/** Number of active (non-revoked) devices. */
|
|
355
|
+
get activeCount(): number;
|
|
356
|
+
/**
|
|
357
|
+
* Create a device and return its token ONCE.
|
|
358
|
+
*
|
|
359
|
+
* @param label - operator-facing name.
|
|
360
|
+
* @returns the stored record plus the plaintext token.
|
|
361
|
+
*/
|
|
362
|
+
add(label: string): Promise<{
|
|
363
|
+
device: DeviceRecord;
|
|
364
|
+
token: string;
|
|
365
|
+
}>;
|
|
366
|
+
/**
|
|
367
|
+
* Revoke a device.
|
|
368
|
+
*
|
|
369
|
+
* @param id - device id.
|
|
370
|
+
* @returns whether a device was revoked.
|
|
371
|
+
*/
|
|
372
|
+
revoke(id: string): Promise<boolean>;
|
|
373
|
+
/**
|
|
374
|
+
* Delete a device record entirely, so the device may pair again.
|
|
375
|
+
*
|
|
376
|
+
* @param id - device id.
|
|
377
|
+
* @returns whether a record was removed.
|
|
378
|
+
*/
|
|
379
|
+
remove(id: string): Promise<boolean>;
|
|
380
|
+
/**
|
|
381
|
+
* Verify a presented device token.
|
|
382
|
+
*
|
|
383
|
+
* @param token - the `?auth=` value.
|
|
384
|
+
* @returns the matching active device, or `undefined`.
|
|
385
|
+
*/
|
|
386
|
+
verify(token: string): DeviceRecord | undefined;
|
|
387
|
+
/**
|
|
388
|
+
* Record that a device just used its link.
|
|
389
|
+
*
|
|
390
|
+
* Throttled: a loaded page issues dozens of requests, and rewriting the file
|
|
391
|
+
* on each one is both wasteful and a crash risk (see {@link writeJson}).
|
|
392
|
+
*
|
|
393
|
+
* @param id - device id.
|
|
394
|
+
* @param ip - the address the request came from.
|
|
395
|
+
*/
|
|
396
|
+
touch(id: string, ip: string): Promise<void>;
|
|
397
|
+
}
|
|
398
|
+
//#endregion
|
|
399
|
+
//#region src/proxy.d.ts
|
|
400
|
+
/** A running proxy listener. */
|
|
401
|
+
interface RunningProxy {
|
|
402
|
+
/** The address actually bound. */
|
|
403
|
+
readonly host: string;
|
|
404
|
+
/** The port actually bound (resolved when `listenPort` was 0). */
|
|
405
|
+
readonly port: number;
|
|
406
|
+
/** The port that was configured (differs from `port` after a fallback). */
|
|
407
|
+
readonly requestedPort: number;
|
|
408
|
+
/** Whether the configured port was taken and a later one was used instead. */
|
|
409
|
+
readonly portFallback: boolean;
|
|
410
|
+
/** Stop listening and drop every live connection. */
|
|
411
|
+
close(): Promise<void>;
|
|
412
|
+
}
|
|
413
|
+
//#endregion
|
|
414
|
+
//#region src/qrcode.d.ts
|
|
415
|
+
/** One address offered to the settings page. */
|
|
416
|
+
interface AccessAddress {
|
|
417
|
+
/** Interface name. */
|
|
418
|
+
interface: string;
|
|
419
|
+
/** IPv4 literal. */
|
|
420
|
+
address: string;
|
|
421
|
+
/** The URL a phone would open. */
|
|
422
|
+
url: string;
|
|
423
|
+
/** Whether this looks like a virtual/tunnel adapter. */
|
|
424
|
+
virtual: boolean;
|
|
425
|
+
/** Why it was classified as virtual. */
|
|
426
|
+
virtualReason?: string;
|
|
427
|
+
/** Whether this is the address currently advertised. */
|
|
428
|
+
selected: boolean;
|
|
429
|
+
}
|
|
430
|
+
/** Everything the settings page needs to show a scannable link. */
|
|
431
|
+
interface AccessInfo {
|
|
432
|
+
/** Proxy port. */
|
|
433
|
+
port: number;
|
|
434
|
+
/** The configured port, when the listener had to fall back to another one. */
|
|
435
|
+
portFallbackFrom: number | null;
|
|
436
|
+
/** Whether the listener serves TLS. */
|
|
437
|
+
secure: boolean;
|
|
438
|
+
/** The configured TLS mode. */
|
|
439
|
+
tlsMode: TlsMode;
|
|
440
|
+
/** SHA-256 fingerprint of the CA, when a self-signed CA is in use. */
|
|
441
|
+
caFingerprint: string | null;
|
|
442
|
+
/** Every candidate address, best first. */
|
|
443
|
+
addresses: AccessAddress[];
|
|
444
|
+
/** The advertised URL, or `null` when no address is usable. */
|
|
445
|
+
selectedUrl: string | null;
|
|
446
|
+
/** QR for the advertised URL. */
|
|
447
|
+
qrSvg: string | null;
|
|
448
|
+
/** The passwordless URL (admin-unlocked callers only). */
|
|
449
|
+
tokenUrl?: string;
|
|
450
|
+
/** QR for the passwordless URL (admin-unlocked callers only). */
|
|
451
|
+
tokenQrSvg?: string;
|
|
452
|
+
/** Why no URL is available, when that is the case. */
|
|
453
|
+
unavailableReason?: string;
|
|
454
|
+
/** Whether the listener is loopback-only, so no LAN device can reach it. */
|
|
455
|
+
loopbackOnly: boolean;
|
|
456
|
+
}
|
|
457
|
+
//#endregion
|
|
458
|
+
//#region src/index.d.ts
|
|
459
|
+
/** Stable Cordis plugin name; also the Loader entry id and the settings namespace. */
|
|
460
|
+
declare const name = "dsh-lan-guard";
|
|
461
|
+
/** `connection` supplies the launch-token seam and the native fence; `webServer` hosts the management routes. */
|
|
462
|
+
declare const inject: string[];
|
|
463
|
+
/** What the management-route registration needs from the plugin. */
|
|
464
|
+
interface ManagementDeps {
|
|
465
|
+
auth: AuthManager;
|
|
466
|
+
switches: LiveSwitches;
|
|
467
|
+
config: LanGuardConfigShape;
|
|
468
|
+
logger: LanGuardLogger;
|
|
469
|
+
/** Build the current access URL set and QR codes. */
|
|
470
|
+
access: (secretToken?: string | null) => Promise<AccessInfo>;
|
|
471
|
+
/** The live listener facts (actual port + whether a fallback happened). */
|
|
472
|
+
listener: {
|
|
473
|
+
port: () => number;
|
|
474
|
+
portFallback: () => boolean;
|
|
475
|
+
};
|
|
476
|
+
/** Paired devices (P4-g). */
|
|
477
|
+
devices: DeviceRegistry;
|
|
478
|
+
}
|
|
479
|
+
/** The host capabilities this plugin needs, narrowed so it is testable without a real Context. */
|
|
480
|
+
interface LanGuardHost {
|
|
481
|
+
/** `ctx.connection.authenticatedUrl` — the public token seam (route A). */
|
|
482
|
+
authenticatedUrl: (baseUrl: string) => string;
|
|
483
|
+
/** DSH's own web server port, used to refuse a self-conflicting listener. */
|
|
484
|
+
webServerPort?: number | undefined;
|
|
485
|
+
/** Logger; credentials are never passed to it. */
|
|
486
|
+
logger?: LanGuardLogger;
|
|
487
|
+
/** Register the management surface; omitted when no DSH seams are available (unit tests). */
|
|
488
|
+
registerManagement?: ((deps: ManagementDeps) => () => void) | undefined;
|
|
489
|
+
}
|
|
490
|
+
/** A running plugin instance. */
|
|
491
|
+
interface LanGuardRuntime {
|
|
492
|
+
/** The visitor-facing proxy listener. */
|
|
493
|
+
readonly proxy: RunningProxy;
|
|
494
|
+
/** The gate, exposed for tests and diagnostics. */
|
|
495
|
+
readonly auth: AuthManager;
|
|
496
|
+
/** Paired devices (P4-g), exposed for tests and diagnostics. */
|
|
497
|
+
readonly devices: DeviceRegistry;
|
|
498
|
+
/** Stop the listener, the gate and the management routes. */
|
|
499
|
+
close(): Promise<void>;
|
|
500
|
+
}
|
|
501
|
+
/**
|
|
502
|
+
* Validate config and bring the plugin up.
|
|
503
|
+
*
|
|
504
|
+
* @param host - the host capabilities above.
|
|
505
|
+
* @param rawConfig - the Loader config for this entry.
|
|
506
|
+
* @returns the running runtime, or `undefined` when the plugin is switched off.
|
|
507
|
+
*/
|
|
508
|
+
declare function startLanGuard(host: LanGuardHost, rawConfig: unknown): Promise<LanGuardRuntime | undefined>;
|
|
509
|
+
/**
|
|
510
|
+
* Cordis entry point.
|
|
511
|
+
*
|
|
512
|
+
* @param ctx - the plugin's context (injects `webServer` and `connection`).
|
|
513
|
+
* @param rawConfig - the Loader config for this entry.
|
|
514
|
+
*/
|
|
515
|
+
declare function apply(ctx: Context, rawConfig: unknown): Promise<void>;
|
|
516
|
+
//#endregion
|
|
517
|
+
export { Config, type LanGuardConfigShape, LanGuardHost, LanGuardRuntime, ManagementDeps, apply, inject, name, startLanGuard };
|