dsh-zen-remote 1.1.16 → 2.0.0

package/lib/types/config.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Config resolution for dsh-zen-remote: one flat key space, four layers.
+ *
+ * 2.0.0 moved the settings surface to the DSH plugin row (the loader-owned
+ * `Config` schema below), while long-time users keep their
+ * `<DSH_HOME>/lan-gate.config.json`. The agreed contract is resolve-time
+ * fallback — nothing is ever written back — and per field the first LEGAL
+ * value wins in this order:
+ *
+ *   1. environment variables (`LAN_GATE_*` / `DSH_PUSH_*`, historic names)
+ *   2. the plugin row (what the loader hands `apply()`)
+ *   3. `lan-gate.config.json`
+ *   4. defaults
+ *
+ * A value that fails its field's check (type, range, enum) makes that layer
+ * transparent, as if it had never been set — a hand-edited `port: "abc"` in
+ * the row therefore surfaces the file's port, not an error. Legal ranges are
+ * enforced HERE and nowhere else. The loader's `Config` schema below is
+ * deliberately not a validator: every field is `z.any()` (secret/volatile
+ * markers aside), because a schemastery type mismatch makes the loader reject
+ * the WHOLE row and the plugin never loads at all — violating the T11 design
+ * that a botched `role` degrades to host instead of breaking the plugin.
+ * `Config` only tells the settings form WHICH fields exist, which one is a
+ * secret, and which are volatile; `resolveConfig` owns every legality rule.
+ *
+ * Pure logic: no writes, no `process.env` mutation. The one deliberate read
+ * is `os.hostname()` for the `serverName` default, which the DEFAULTS table
+ * is specified to embed.
+ */
+import z from '@deepseek-ai/schemastery';
+/** Where a resolved field value came from, in resolution order. */
+export type ConfigSource = 'env' | 'row' | 'file' | 'default';
+/** The effective configuration one resolved value set, defaults included. */
+export interface ZenRemoteConfig {
+    /** Which half of the plugin runs in this DSH process; anything the layers
+     * leave unresolved means `'host'` (see {@link resolveRole}). */
+    role: 'host' | 'client';
+    /** Port the gateway child listens on. */
+    port: number;
+    /** Bind address of the gateway child. */
+    host: string;
+    /** Port of the local DSH Web UI the gateway forwards to; undefined means
+     * "discover the host's real listening port at gateway start". */
+    targetPort: number | undefined;
+    /** Remote requests per minute per pairing before 429. */
+    rateLimit: number;
+    /** Comma-separated proxy IPs the gateway trusts for X-Forwarded-*. */
+    trustedProxies: string;
+    /** VAPID subject (a `mailto:` or `https:` URL identifying the push sender). */
+    vapidSubject: string;
+    /** Notification/UI language: `'auto'` defers to the requester's signal. */
+    lang: 'auto' | 'zh' | 'en';
+    /** Comma-separated session events the push leg treats as turn end. */
+    pushEvents: string;
+    /** Minimum milliseconds between two pushes (approval/question legs exempt). */
+    pushDebounceMs: number;
+    /** Include the turn's final text (or pending question) in push bodies. */
+    pushSummary: boolean;
+    /** Push when a top-level turn ends (opt-in: finishing is not an alarm). */
+    pushTurnEnd: boolean;
+    /** Register the model-facing `push_notify` tool. */
+    pushTool: boolean;
+    /** Server display name, at most {@link SERVER_NAME_MAX} characters. */
+    serverName: string;
+    /** Idle-sleep window of a remote-enabled session: after this many hours
+     * without new activity the remote connection closes on its own; running or
+     * waiting sessions never count. (0, 8760]. */
+    idleHours: number;
+    /** Auto-share every newly created session to the paired phone (T16). */
+    autoShareNewSessions: boolean;
+}
+/** Defaults, one per field — exactly what layer 4 hands back. */
+export declare const DEFAULTS: ZenRemoteConfig;
+/**
+ * Peel the loader's volatile wrapper off a row value. Schemastery hands
+ * `.volatile()` fields to apply() as cosmokit `{ get() }` reference objects,
+ * NOT as the value itself — a wrapper run through a validator unchecked would
+ * fail every check and the row layer would silently never win for those
+ * fields. Anything with a callable `get` is unwrapped; everything else passes
+ * through (the same duck-typing the verifier plugin's settingsOf uses, so no
+ * dependency on the wrapper's symbol protocol). Later tasks that read live
+ * settings at operation time use this too.
+ */
+export declare function unwrapVolatile(value: unknown): unknown;
+/**
+ * The effective configuration: every field resolved through the four layers.
+ * @param row - the plugin row config as `apply()` received it (loosely typed
+ *   because the loader's parsed shape and hand-edited YAML differ).
+ * @param file - the parsed `lan-gate.config.json`, `{}` when absent.
+ * @param env - environment carrying the optional `LAN_GATE_*` / `DSH_PUSH_*`
+ *   variables.
+ * @returns the merged values plus, per field, the layer it came from.
+ */
+export declare function resolveConfig(row: unknown, file: Record<string, unknown>, env: NodeJS.ProcessEnv): {
+    values: ZenRemoteConfig;
+    sources: Record<keyof ZenRemoteConfig, ConfigSource>;
+};
+/**
+ * Read `<DSH_HOME>/lan-gate.config.json` (DSH_HOME defaulting to `~/.dsh`).
+ * Missing file, unparsable JSON, or a non-object root (arrays included) all
+ * yield `{}` — a broken file must degrade to defaults, never take the host
+ * process down. Never writes.
+ * @param env - environment providing DSH_HOME; defaults to `process.env`.
+ */
+export declare function readFileConfig(env?: NodeJS.ProcessEnv): Record<string, unknown>;
+/**
+ * The normalized role behind a row's `role` knob. Anything but the exact
+ * string `'client'` means host, so a typo degrades to the full plugin rather
+ * than silently dropping the gateway and push halves. The value is read
+ * through {@link unwrapVolatile} first: since T17 every row field arrives as
+ * a `{ get() }` live reference, and comparing the wrapper itself against
+ * `'client'` would always answer host (T17b). Resolution-order note:
+ * {@link resolveConfig} validates each layer against the two-member enum
+ * first, so an invalid row role can still be rescued by the file layer; this
+ * function answers the final merged value. Kept on the main entry's export
+ * surface for test/role-wiring.test.cjs.
+ */
+export declare function resolveRole(row: unknown): 'host' | 'client';
+/**
+ * The DSH loader's config schema for the plugin row: what the settings form
+ * renders and what it hands `apply()`. Every field is `z.any()` on purpose —
+ * legality is entirely {@link resolveConfig}'s job. A schemastery type
+ * mismatch (`z.number()` meeting `port: "abc"`) makes the loader throw away
+ * the whole row and the plugin never loads, which would break the T11
+ * promise that a botched `role` degrades to host instead of killing the
+ * plugin. So this schema only declares: WHICH fields exist (the form's
+ * field list), WHICH one is a secret (`deviceToken`, redacted from every
+ * settings wire surface), and that every field is volatile (live).
+ *
+ * No `.default()` anywhere: a schema default would be written into every row
+ * at load and `lan-gate.config.json`'s fallback would never get a turn — the
+ * real defaults live in {@link DEFAULTS}.
+ *
+ * EVERY field is volatile, and that is not an optimization: DSH 0.2.0's
+ * settings service builds the form from volatile fields ONLY (its
+ * `volatileForm` drops non-volatile ones, and a `mutate` outside the volatile
+ * subtree is refused), so a non-volatile field is invisible in the settings
+ * page and unsaveable from it — T12 made the restart-required fields
+ * non-volatile and the whole settings surface went dark for them. The cost
+ * is that the loader hands every volatile field to `apply()` as a `{ get() }`
+ * wrapper instead of the value, so EVERY row read goes through
+ * {@link unwrapVolatile} at use time (or through {@link resolveConfig},
+ * which unwraps per field). "Changed value requires a restart" therefore
+ * cannot ride the volatility flag: the fields in `RESTART_FIELDS`
+ * (src/restart-fields.ts) are re-resolved the moment the loader announces a
+ * volatile-only change (`loader/volatile-update`, T17b) and on a 2-second
+ * poll besides, and reload the plugin row when their fingerprint moves — a
+ * row reload re-runs `apply()`, which restarts the gateway child and the
+ * push half.
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    role: z<any, any, "volatile">;
+    port: z<any, any, "volatile">;
+    host: z<any, any, "volatile">;
+    targetPort: z<any, any, "volatile">;
+    rateLimit: z<any, any, "volatile">;
+    trustedProxies: z<any, any, "volatile">;
+    vapidSubject: z<any, any, "volatile">;
+    lang: z<any, any, "volatile">;
+    pushEvents: z<any, any, "volatile">;
+    pushDebounceMs: z<any, any, "volatile">;
+    pushSummary: z<any, any, "volatile">;
+    pushTurnEnd: z<any, any, "volatile">;
+    pushTool: z<any, any, "volatile">;
+    serverName: z<any, any, "volatile">;
+    idleHours: z<any, any, "volatile">;
+    autoShareNewSessions: z<any, any, "volatile">;
+    serverUrl: z<any, any, "volatile">;
+    deviceToken: z<string, string, "volatile">;
+    turnFoldDesktop: z<any, any, "volatile">;
+    keyboardLiftRatio: z<any, any, "volatile">;
+    keyboardLiftMaxPx: z<any, any, "volatile">;
+    keyboardSafetyPadPx: z<any, any, "volatile">;
+    maxUploadBytes: z<any, any, "volatile">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    role: z<any, any, "volatile">;
+    port: z<any, any, "volatile">;
+    host: z<any, any, "volatile">;
+    targetPort: z<any, any, "volatile">;
+    rateLimit: z<any, any, "volatile">;
+    trustedProxies: z<any, any, "volatile">;
+    vapidSubject: z<any, any, "volatile">;
+    lang: z<any, any, "volatile">;
+    pushEvents: z<any, any, "volatile">;
+    pushDebounceMs: z<any, any, "volatile">;
+    pushSummary: z<any, any, "volatile">;
+    pushTurnEnd: z<any, any, "volatile">;
+    pushTool: z<any, any, "volatile">;
+    serverName: z<any, any, "volatile">;
+    idleHours: z<any, any, "volatile">;
+    autoShareNewSessions: z<any, any, "volatile">;
+    serverUrl: z<any, any, "volatile">;
+    deviceToken: z<string, string, "volatile">;
+    turnFoldDesktop: z<any, any, "volatile">;
+    keyboardLiftRatio: z<any, any, "volatile">;
+    keyboardLiftMaxPx: z<any, any, "volatile">;
+    keyboardSafetyPadPx: z<any, any, "volatile">;
+    maxUploadBytes: z<any, any, "volatile">;
+}>>, "plain">;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,mEAAmE;AACnE,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAA;AAK7D,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B;oEACgE;IAChE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAA;IACvB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ;qEACiE;IACjE,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAA;IACjB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAA;IACtB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAC1B,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAA;IACtB,0EAA0E;IAC1E,WAAW,EAAE,OAAO,CAAA;IACpB,2EAA2E;IAC3E,WAAW,EAAE,OAAO,CAAA;IACpB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAA;IACjB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAA;IAClB;;kDAE8C;IAC9C,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,oBAAoB,EAAE,OAAO,CAAA;CAC9B;AAMD,iEAAiE;AACjE,eAAO,MAAM,QAAQ,EAAE,eAiBtB,CAAA;AAOD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKtD;AA0LD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB;IACD,MAAM,EAAE,eAAe,CAAA;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,eAAe,EAAE,YAAY,CAAC,CAAA;CACrD,CAuBA;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ5F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAE3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aA6BjB,CAAA"}

package/lib/types/fetch-route-intercept.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The exact-fetch-route interception (T51): the sub-client's own DSH process
+ * keeps serving its local UI, but the two `/api` routes a REMOTE session's
+ * surface reaches must not run against local state:
+ *
+ * - `/api/session/uploadFileBinary` — a NON-image attachment enters through
+ *   dsh-client-file-upload's Web Worker (XHR for Blobs, worker-scoped fetch
+ *   for streams — RT dsh-client-file-upload lib/client.js:72-152), so
+ *   neither a `window.fetch` wrapper nor the typert interception sees it.
+ *   What the worker's request DOES hit is the host's shared fetch-handler
+ *   table: `HostConnectionService.fetchRoutes` is a plain Map the shared
+ *   handler re-reads per request (`fetchRoutes.get(pathname)` then
+ *   `route.fetch(request)`, RT dsh-client-connection lib/index.js:558 and
+ *   ~614-617), and the upload registers `requestBody: "streaming"` with a
+ *   closure `fetch` (RT dsh-client-file-upload lib/index.js:73, 171-176).
+ *   Replacing that entry's `fetch` intercepts every upload at the local
+ *   backend. A virtual `sessionId` rides the relay's binary channel to the
+ *   server (the staged receipt then resolves under the SAME session the
+ *   forwarded `session/prompt` runs against); anything else reaches the
+ *   original function untouched.
+ * - `/api/session.export` — a remote session's log lives on the SERVER, and
+ *   a virtual id on the local route could only fail; the wrap refuses it
+ *   with 403 `remote-unsupported` before the local route runs (the UI entry
+ *   is hidden remotely too, remote-session.css.ts).
+ *
+ * EVERY answer the UPLOAD wrapper produces is HTTP 200 + the failure
+ * envelope the browser half parses (T51-fix): dsh-client-file-upload's
+ * `FileUploadRuntime.upload` throws a bare English transport error on any
+ * non-200 status and never reaches `parseFileUploadResult` (RT
+ * lib/client.js:190 vs 272-297) — so offline, mismatch and the local
+ * oversize refusal all travel as the host's own failure shape, and the
+ * Chinese message lands on the attachment card. Only the EXPORT wrapper
+ * keeps a real 403: its UI (the export dialog) reads `response.ok` and
+ * prints the status.
+ *
+ * The wrap is gated on a structural shape check like the typert one
+ * (intercept-shape.ts): a future DSH without the fetchRoutes Map must leave
+ * this install OFF and local uploads exactly as they were. ENTRY-LEVEL facts
+ * attach per route (T51-fix): an entry that is absent at install time —
+ * session-log-export may register after us — is retried on a bounded timer
+ * and on each call of the OTHER wrapper; an entry that is present but
+ * misshaped is refused for ITS route only (present-but-wrong never fixes
+ * itself — `registerFetchRoute` throws on a duplicate path), and the rest
+ * of the install still runs. Uninstall restores an entry only while it
+ * still holds OUR wrapper — a later wrapper chained over us keeps working,
+ * and ours goes inert instead (the same posture as intercept.ts).
+ */
+import type { RelayClient } from './relay-client.js';
+/** The host's upload route, verbatim from its registration (RT
+ * dsh-client-file-upload lib/index.js:73). */
+export declare const FILE_UPLOAD_PATH = "/api/session/uploadFileBinary";
+/** The host's session-log export route (RT dsh-session-log-export
+ * lib/index.js:488). */
+export declare const SESSION_EXPORT_PATH = "/api/session.export";
+/** Verdict of {@link checkFetchRouteShape}. STRUCTURAL only: `ok` answers
+ * "is this a connection service with a fetch-route table at all"; each
+ * route's entry findings travel as `notes` — present/absent/misshaped — and
+ * the per-route attach decisions are the install's business (T51-fix). */
+export type FetchRouteShapeCheck = {
+    ok: true;
+    notes: string[];
+} | {
+    ok: false;
+    reasons: string[];
+};
+/** One exact-fetch route entry, as `registerFetchRoute` stores it (RT
+ * dsh-client-connection lib/index.js:627-631). */
+export interface FetchRouteEntry {
+    methods: Set<string>;
+    requestBody: string;
+    fetch: (request: Request) => Promise<Response>;
+}
+/**
+ * Check the RAW connection service instance against the shape the wrap
+ * depends on. Pure inspection — nothing is mutated, so a failed check
+ * leaves every route exactly as it was. Only the structural facts refuse;
+ * the two entries' facts are described in `notes` (they attach lazily).
+ */
+export declare function checkFetchRouteShape(connection: unknown): FetchRouteShapeCheck;
+/** One refusal the wrappers answered, in the diagnostics ring. */
+export interface FetchRouteFailureRecord {
+    /** ISO timestamp of the moment the refusal was answered. */
+    time: string;
+    /** Which wrapper answered it. */
+    route: 'upload' | 'export';
+    code: string;
+}
+/** What the client status route surfaces about this interception: flags,
+ * counters and codes only — never a token, never a server address. */
+export interface FetchRouteInterceptDiagnostics {
+    installed: boolean;
+    shape: FetchRouteShapeCheck;
+    /** The upload entry currently holds our wrapper. */
+    uploadWrapped: boolean;
+    /** The export entry currently holds our wrapper (false while absent or
+     * refused). */
+    exportWrapped: boolean;
+    /** The upload entry was absent at last check and the attach retry is
+     * still running (T51-fix). */
+    uploadPending: boolean;
+    /** The export entry was absent at last check and the attach retry is
+     * still running (T51-fix). */
+    exportPending: boolean;
+    /** The upload entry was present but misshaped — attach refused for THIS
+     * route only; the reason is stable diagnostics text (T51-fix). */
+    uploadAttachRefused: string | undefined;
+    /** Same, for the export entry. */
+    exportAttachRefused: string | undefined;
+    /** Every upload that entered the wrapper, local passthroughs included. */
+    uploadCalls: number;
+    /** Uploads forwarded through the relay (virtual ids only). */
+    uploadForwarded: number;
+    /** Uploads refused locally (oversize, offline, mismatch, relay
+     * refusals, relay transport death). */
+    uploadRefused: number;
+    /** Export requests blocked with `remote-unsupported`. */
+    exportBlocked: number;
+    /** The most recent refusals, oldest first, capped. */
+    recentFailures: FetchRouteFailureRecord[];
+}
+export interface InstallFetchRouteInterceptOptions {
+    /** The RAW connection service instance
+     * (`ctx.connection[symbols.original]`) — the one whose `fetchRoutes` Map
+     * the shared handler reads per request. */
+    connection: object;
+    /** The client relay client (T23a) the uploads travel through. */
+    relay: RelayClient;
+    /** The CURRENT handshake's server id, read live per call; `undefined`
+     * makes every remote upload a `remote-offline`. */
+    getServerId: () => string | undefined;
+    /** Progress logging, wired to the context logger by index.ts. */
+    log?: (format: string, ...args: unknown[]) => void;
+    /** The lazy-attach retry cadence (T51-fix): how often the table is
+     * re-probed for entries that were absent at install, and how many probes
+     * before giving up. Defaults 3000 ms × 10; tests shrink both. */
+    attachRetryMs?: number;
+    attachAttempts?: number;
+}
+export interface FetchRouteInterceptHandle {
+    /** Restore every attached entry — each ONLY while it still holds our
+     * wrapper — and stop the attach retry. Idempotent. After it ran, the
+     * wrappers stay installed-but-inert if someone had chained over them
+     * (same posture as intercept.ts). */
+    uninstall(): void;
+    /** The status-route view. */
+    diagnostics(): FetchRouteInterceptDiagnostics;
+}
+/**
+ * Install the wrappers over the two fetch-route entries. Assumes
+ * {@link checkFetchRouteShape} passed (the wiring gates on it — the gate is
+ * structural only); each entry attaches on its own facts, immediately when
+ * present and attachable, via the bounded retry when absent, never when
+ * present-but-misshaped.
+ */
+export declare function installFetchRouteIntercept(options: InstallFetchRouteInterceptOptions): FetchRouteInterceptHandle;
+//# sourceMappingURL=fetch-route-intercept.d.ts.map

package/lib/types/fetch-route-intercept.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-route-intercept.d.ts","sourceRoot":"","sources":["../../src/fetch-route-intercept.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAIpD;8CAC8C;AAC9C,eAAO,MAAM,gBAAgB,kCAAkC,CAAA;AAE/D;wBACwB;AACxB,eAAO,MAAM,mBAAmB,wBAAwB,CAAA;AAgBxD;;;0EAG0E;AAC1E,MAAM,MAAM,oBAAoB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEnG;kDACkD;AAClD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC/C;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,OAAO,GAAG,oBAAoB,CAe9E;AA0BD,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;CACb;AAED;sEACsE;AACtE,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,oBAAoB,CAAA;IAC3B,oDAAoD;IACpD,aAAa,EAAE,OAAO,CAAA;IACtB;mBACe;IACf,aAAa,EAAE,OAAO,CAAA;IACtB;kCAC8B;IAC9B,aAAa,EAAE,OAAO,CAAA;IACtB;kCAC8B;IAC9B,aAAa,EAAE,OAAO,CAAA;IACtB;sEACkE;IAClE,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,kCAAkC;IAClC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAA;IACnB,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAA;IACvB;2CACuC;IACvC,aAAa,EAAE,MAAM,CAAA;IACrB,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAA;IACrB,sDAAsD;IACtD,cAAc,EAAE,uBAAuB,EAAE,CAAA;CAC1C;AAED,MAAM,WAAW,iCAAiC;IAChD;;+CAE2C;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,iEAAiE;IACjE,KAAK,EAAE,WAAW,CAAA;IAClB;uDACmD;IACnD,WAAW,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IACrC,iEAAiE;IACjE,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;IAClD;;qEAEiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;yCAGqC;IACrC,SAAS,IAAI,IAAI,CAAA;IACjB,6BAA6B;IAC7B,WAAW,IAAI,8BAA8B,CAAA;CAC9C;AAkDD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,iCAAiC,GAAG,yBAAyB,CAkPhH"}

package/lib/types/fingerprint.d.ts

@@ -0,0 +1,164 @@
+/**
+ * DSH interface fingerprints (T42, the second of the three version-tolerance
+ * layers). The sub-client's UI code comes from ITS OWN App while the data
+ * comes from the relay server's DSH — when the two DSH versions disagree
+ * about an interface shape, individual calls fail at runtime. The fingerprint
+ * lets both ends NOTICE without refusing the link (that is the relay
+ * protocol's job, layer one): each side hashes a few groups of interface
+ * definitions, the server puts its map into the handshake, the client
+ * compares group by group, and the settings page lists the differing groups.
+ * Identical maps mean fully compatible — the DSH version numbers themselves
+ * are deliberately NOT compared (docs/spike-relay.md §2.3: 0.1.7 and 0.2.0
+ * share byte-identical remote interfaces, so a version gate would misreject).
+ *
+ * What is hashed, per group, in priority order:
+ *
+ * 1. REGISTRY TIER — `ctx.typert.local.list()`, the descriptors the running
+ *    DSH actually registered (dsh-typert-registry's `TypertRegistry.local`:
+ *    `list()` returns the committed descriptor objects; shape verified against
+ *    dsh-typert-registry 0.1.7-rc.2 / 0.1.0-rc.6 `DescriptorStore.list`).
+ *    Descriptors are grouped by their `id` prefix `@deepseek-ai/<package>#`,
+ *    then canonicalized exactly like the spike's fp.mjs prototype:
+ *    `sourceLocation` keys are dropped (their line/column drift with unrelated
+ *    edits), every `create` field (the generated descriptors' codec/result
+ *    schema producers — the ONLY functions ever called) is projected to JSON
+ *    Schema with `unrepresentable: 'any'`, object keys are sorted recursively
+ *    (the schema's `required` arrays alphabetically too — see below), and the
+ *    JSON is sha256'd. The instance form
+ *    `schema.toJSONSchema({ unrepresentable: 'any' })` is used instead of
+ *    importing zod — verified byte-identical to `z.toJSONSchema(schema, …)`,
+ *    and it spares this package a zod dependency hunt through the host
+ *    closure. Reproducing the spike's recorded values with the
+ *    key-sorting-only precursor of this normalization matched exactly
+ *    (session-controller `be9ab393695a`, 21 endpoints); the recursive schema
+ *    canonicalization below only makes that equality stronger — field
+ *    declaration order can no longer move a hash.
+ * 2. FILE TIER — the task's documented fallback when no usable typert service
+ *    (or schema projection) exists: sha256 over the package's
+ *    `lib/typert.remote-client.js` with every `sourceLocation: {…}` fragment
+ *    stripped. The file is located through `createRequire` resolving
+ *    `@deepseek-ai/<package>/package.json`.
+ * 3. `FINGERPRINT_UNAVAILABLE` — the group could not be computed here, OR the
+ *    registry answered with zero descriptors for the group: the typert
+ *    loader registers package by package asynchronously, so a client that
+ *    handshakes a just-restarted server would otherwise read a half-empty
+ *    registry as "this DSH really runs no such interfaces" and publish
+ *    throwaway hashes. Unavailable is NOT a difference — it only feeds the
+ *    diagnostics.
+ *
+ * Every registry value is prefixed `r:`, every file-tier value `f:`. The
+ * two tiers hash different material, so a group whose ends normalized
+ * through DIFFERENT tiers compares as unavailable — never as a difference.
+ *
+ * Every group is computed inside its own try/catch, so one broken group never
+ * costs the others; the whole map is meant to be recomputed per handshake
+ * (~7 ms measured on a full registry — cheap enough to never go stale) and
+ * NOT cached: the registry assembles asynchronously, and a cached map would
+ * pin whatever a first handshake happened to see. The `events` group has no
+ * generated definitions; its input is `dsh-api-remotes`'s exported
+ * `API_REMOTE_FORWARDED_EVENTS` (event name + mode, sorted), resolved through
+ * the same anchors — unresolvable means unavailable.
+ */
+/** The value a group carries when its fingerprint could not be computed. */
+export declare const FINGERPRINT_UNAVAILABLE = "unavailable";
+/** Group name of the forwarded-events fingerprint (no generated definitions). */
+export declare const EVENTS_GROUP = "events";
+/**
+ * The interface groups the relay actually exercises, mapped to the DSH
+ * package whose descriptors define them (docs/spike-relay.md §4.4). Keys are
+ * the wire names both ends exchange — stable ASCII, rendered verbatim by the
+ * settings page.
+ */
+export declare const FINGERPRINT_GROUP_PACKAGES: Readonly<Record<string, string>>;
+/**
+ * The piece of cordis this module needs: the reflection layer's service
+ * lookup, used to read `typert` without declaring an inject (a context
+ * without the service answers undefined, same as the shares routes' reads).
+ * Structural on purpose: the fingerprints compute in compositions this
+ * package cannot type against.
+ */
+export interface FingerprintContext {
+    reflect?: {
+        get(name: string): unknown;
+    };
+}
+/** Injectable knobs — the resolution anchors, for tests. */
+export interface FingerprintOptions {
+    /**
+     * Package-resolution anchors, HIGHEST priority first. Each anchor seeds a
+     * `createRequire` that walks node_modules upward from it. The default puts
+     * the host process entry first (`process.argv[1]`, realpath'd — under the
+     * npm CLI it is a symlink into the real install) and this plugin second:
+     * a link-installed plugin carries devDependency copies of the DSH
+     * packages, and reading those would fingerprint a version the host is not
+     * actually running.
+     */
+    anchors?: readonly string[];
+}
+/** The group-by-group comparison result the relay client stores. */
+export interface RelayCompatVerdict {
+    /** Groups whose fingerprints match exactly. */
+    identical: string[];
+    /** Groups whose fingerprints differ — the yellow-hint material. */
+    different: string[];
+    /** Groups at least one end could not compute — or whose values came out
+     * of different normalization tiers and are therefore not comparable.
+     * Never a difference. */
+    unavailable: string[];
+}
+/**
+ * The canonicalization from the spike's fp.mjs prototype, kept faithful
+ * where the spike proved it (sourceLocation dropped, keys sorted, schemas
+ * projected with `unrepresentable: 'any'`), tightened in two places: only a
+ * field NAMED `create` is treated as a schema producer — the generated
+ * descriptors project schemas there and nowhere else, so any other function
+ * (`decode`, `encode`, …) collapses to the stable marker `'fn'` WITHOUT
+ * being called; and the projection is recursively key-sorted (see
+ * {@link canonicalizeJsonSchema}).
+ */
+export declare function normalizeDescriptorValue(value: unknown, key?: string): unknown;
+/**
+ * One package group's registry-tier fingerprint over its descriptors, shown
+ * as a pure helper (the empty-set decision belongs to
+ * {@link groupFingerprint}, which turns an empty subset into
+ * `unavailable` instead of a hash of nothing).
+ */
+export declare function fingerprintDescriptors(descriptors: readonly unknown[]): string;
+/**
+ * The file-tier fallback: sha256 over the package's generated remote-client
+ * definitions with every `sourceLocation: {…}` fragment stripped. The
+ * fragments are flat JSON objects (file/line/column), so the brace-bounded
+ * match cannot overeat. Throws when the package is not resolvable — the
+ * group degrades instead of guessing.
+ */
+export declare function fingerprintPackageFile(packageName: string, anchors?: readonly string[]): string;
+/**
+ * The events group's fingerprint over `dsh-api-remotes`'s forwarded-events
+ * whitelist: `{event, mode}` rows, sorted by event then mode, hashed. A
+ * shape that is not an array of named+moded rows throws — the caller
+ * degrades the group rather than hashing a guess.
+ */
+export declare function fingerprintForwardedEvents(events: unknown): string;
+/**
+ * Compute every group's fingerprint for the DSH this context runs in.
+ * Per-group try/catch throughout: a group that cannot be computed carries
+ * {@link FINGERPRINT_UNAVAILABLE} and never costs the others. The result is
+ * cheap enough (~7 ms against a full registry) to recompute per handshake —
+ * deliberately NOT cached, because the typert registry assembles
+ * asynchronously and a cached map would pin whatever a first handshake
+ * happened to see.
+ */
+export declare function computeFingerprints(ctx: FingerprintContext, options?: FingerprintOptions): Promise<Record<string, string>>;
+/**
+ * Compare the server's handshake fingerprints against this side's own,
+ * group by group over the union of both maps. A group either side could
+ * not compute (`FINGERPRINT_UNAVAILABLE`, a missing key, a non-string a
+ * hostile server substituted) lands in `unavailable` — never in
+ * `different`, so a half-blind comparison stays silent instead of crying
+ * wolf. The same goes for a group whose two values carry DIFFERENT
+ * algorithm prefixes (`r:` vs `f:`): they were normalized from different
+ * material and must not be diffed against each other. Pure; unit-tested
+ * against injected maps.
+ */
+export declare function compareFingerprints(server: unknown, own: unknown): RelayCompatVerdict;
+//# sourceMappingURL=fingerprint.d.ts.map

package/lib/types/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAQH,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,gBAAgB,CAAA;AAQpD,iFAAiF;AACjF,eAAO,MAAM,YAAY,WAAW,CAAA;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOvE,CAAA;AAKD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAA;CACzC;AAED,4DAA4D;AAC5D,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC5B;AAED,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,mEAAmE;IACnE,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB;;6BAEyB;IACzB,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AA+CD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAqB9E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAE9E;AA0CD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAK/F;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAYlE;AAyDD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAShI;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAwBrF"}

package/lib/types/http.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared HTTP plumbing for the host-side route modules: the one JSON response
+ * envelope and the one same-origin gate every state-changing browser route
+ * applies. Both lived in the main entry until the admin routes (T14) needed
+ * the exact same pair; importing the entry from a route module would be an
+ * import cycle, so the definitions live here and the entry re-exports the
+ * same-origin gate its public surface has carried since S7.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** The one JSON response envelope every host route speaks: no-store (admin
+ * surfaces and pairing codes must never sit in a shared cache), nosniff, and
+ * a default-src 'none' CSP since no route serves executable content. */
+export declare function responseJson(res: ServerResponse, status: number, body: unknown): void;
+/**
+ * Accept a state-changing request only from this DSH Web application's origin.
+ *
+ * The gateway half rewrites `Origin`/`Host` to the upstream origin
+ * before forwarding (lan-gate-server.cjs `cleanHeaders`), so a phone request
+ * that already cleared the pairing wall presents here as same-origin; a
+ * request with neither header falls back to the Fetch metadata.
+ *
+ * When BOTH `Origin` and `Sec-Fetch-Site` are absent the request is ACCEPTED
+ * (T16-fix): the DSH desktop app's main process forwards window requests to
+ * the local backend after verifying `Origin: dsh-app://app` itself, and
+ * strips `host`, `origin`, `cookie` and `sec-fetch-site` on the way (its
+ * `forwardWebRequest`), so such requests arrive with neither header. A
+ * curl-style local tool sends neither either. Neither shape is a
+ * browser-direct cross-site POST. What stands in front of an accepted
+ * headerless request depends on the route module: the admin routes (T14) and
+ * the client routes (T16) run `connection.admit` FIRST, so such a request has
+ * still cleared DSH's login wall before this check runs; since T17 the
+ * upload and share-export routes run the same `connection.admit` first, so
+ * every state-changing route this gate fronts is admission-covered and this
+ * acceptance never stands alone. Everything
+ * identifiable as cross-site (`Sec-Fetch-Site: cross-site`, or an `Origin`
+ * that disagrees with `Host`) is still refused.
+ * @param req - the inbound request.
+ * @returns true when the request may mutate the workspace.
+ */
+export declare function sameOriginPost(req: IncomingMessage): boolean;
+//# sourceMappingURL=http.d.ts.map

package/lib/types/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE;;wEAEwE;AACxE,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CASrF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAgB5D"}