dsh-zen-remote 2.0.3 → 2.2.0

package/lib/types/plugin-adapter-core.d.ts

@@ -0,0 +1,263 @@
+/**
+ * The plugin bridge's adapter core (PB-11) — the framework half of the
+ * pluggable adapters. A cooperative plugin registers its OWN bridge
+ * declaration (PB-1); an adapter is zen-remote-internal code, written
+ * against one third-party plugin's EXACT version, that locates the session
+ * ids in that plugin's requests and rewrites them both ways (GLOSSARY:
+ * 适配器). This module owns everything the framework needs to run one:
+ * the route/locator shapes, their validation, the locate → classify →
+ * rewrite pipeline, and the digest the adapter registers under.
+ *
+ * Deliberately OUTSIDE `src/adapters/`: the pluggability contract
+ * (test/adapters-pluggable.test.cjs) is that deleting that directory breaks
+ * ONLY the wiring import in src/index.ts. The adapter-author face — the
+ * `BridgeAdapter` interface — lives in `src/adapters/types.ts` ON TOP of
+ * the shapes defined here (it re-exports them), so the framework never
+ * imports a single thing from `src/adapters/`.
+ *
+ * Pure logic: no DSH, no I/O. The id semantics ride src/virtual-id.ts —
+ * a request counts as REMOTE exactly when every id the route's locator
+ * finds is a `zr~` virtual id, and the rewrite swaps each for its real
+ * half before the request leaves for the relay (docs/adr/0001: the
+ * sub-client never lets a remote session's request reach a local plugin).
+ */
+import { fromVirtual } from './virtual-id.js';
+import type { NormalizedDeclaration } from './plugin-bridge.js';
+export { fromVirtual };
+/** Where a route's session id lives in a request (`AdapterRoute.locator`).
+ * `query` names the search parameter; `path-segment` counts segments AFTER
+ * the declared path (a `prefix` route's variable part, already decoded once
+ * off the wire); `json-body` names TOP-LEVEL fields of the parsed JSON
+ * request body — every one of those fields that is present counts. */
+export type AdapterLocator = {
+    in: 'query';
+    name: string;
+} | {
+    in: 'path-segment';
+    index: number;
+} | {
+    in: 'json-body';
+    fields: readonly string[];
+};
+/** One adapter route as the adapter declares it. `match: 'prefix'` hits
+ * `pathname === path || pathname.startsWith(path + '/')` on the RAW
+ * undecoded pathname; `exact` is the equality alone. `local: true` marks a
+ * path that stays on the sub-client's own machine forever (static assets
+ * and the like) — it never forwards, in either direction.
+ *
+ * `deny` (optional) answers a reason string for requests that must refuse
+ * BEFORE any id locating happens — the better-sidebar adapter uses it to
+ * refuse `open.external` when the browser's CURRENT session is a remote
+ * one (the request itself carries no session field, so the classify step
+ * would otherwise read it as local) and the side-chat methods wholesale.
+ * A `deny` hit answers the bridge's uniform 503 with that reason; returning
+ * `undefined` falls through to the normal classify. */
+export interface AdapterRoute {
+    path: string;
+    match: 'exact' | 'prefix';
+    methods?: readonly string[];
+    maxBody?: number;
+    stream?: boolean;
+    upgrade?: boolean;
+    locator: AdapterLocator;
+    local?: boolean;
+    deny?: (info: {
+        pathname: string;
+        method: string;
+        currentSessionId: string | undefined;
+    }) => string | undefined;
+}
+/** One adapter route after validation: every scalar filled with its
+ * EFFECTIVE value (the adapters have no legacy-digest constraint, so
+ * unlike the cooperative {@link NormalizedBridgeRoute} the canonical form
+ * always carries the defaults). `deny` rides along by reference — a
+ * function cannot enter the digest, and it is client-half logic the
+ * server never needs. */
+export interface NormalizedAdapterRoute {
+    path: string;
+    match: 'exact' | 'prefix';
+    methods: string[];
+    maxBody: number;
+    stream: boolean;
+    upgrade: boolean;
+    locator: AdapterLocator;
+    local: boolean;
+    deny?: AdapterRoute['deny'];
+}
+/** The two hook faces an adapter may implement (both optional — an adapter
+ * that only relocates ids needs neither). `client.request` runs on the
+ * sub-client AFTER the ids are rewritten to their real halves and can
+ * refuse the forward outright or swap the parsed JSON body;
+ * `client.response` runs on the sub-client on a JSON answer and returns
+ * the rewritten body (real ids back to virtual form). `server.request`
+ * runs on the main server before the loopback and can strip fields (e.g.
+ * a `cwd`) the local machine must not receive. */
+export interface AdapterRequestContext {
+    method: string;
+    /** The full request pathname (RAW, undecoded) — a prefix route's
+     * tail segment is where better-sidebar carries its API method name. */
+    pathname: string;
+    /** The matched route, as declared. */
+    route: AdapterRoute;
+    /** The request's query, ids already in their REAL form. */
+    query: URLSearchParams;
+    /** The parsed JSON request body when the route locates in the body and a
+     * body arrived; `undefined` otherwise. */
+    body: unknown;
+}
+/** The verdict of a request hook: allow (optionally replacing the JSON
+ * body and/or the query — the better-sidebar adapter strips the `cwd`
+ * query field of the file/upload routes so the backend resolves it from
+ * the session), or refuse with a reason — the refusal travels the bridge's
+ * uniform 503 shape on the client half, a 403 on the server half. */
+export type AdapterVerdict = {
+    allow: true;
+    body?: unknown;
+    query?: URLSearchParams;
+} | {
+    allow: false;
+    reason: string;
+};
+/** The context of `client.response`: the parsed JSON answer plus the
+ * virtualizer for this device — an adapter maps server-real session ids
+ * back to THIS sub-client's virtual form with it. `pathname` names the
+ * request the answer belongs to (better-sidebar's response rewriting is
+ * per API method). */
+export interface AdapterResponseContext {
+    status: number;
+    pathname: string;
+    body: unknown;
+    /** Wrap one server-real session id into this device's virtual form. */
+    virtualize(id: string): string;
+    /** Whether a value already IS a virtual id (rewriters skip those). */
+    isVirtual(value: unknown): boolean;
+}
+/** The hook members the framework calls, structurally. `src/adapters/
+ * types.ts`'s `BridgeAdapter` conforms to this shape by construction. */
+export interface AdapterHooks {
+    client?: {
+        request?(ctx: AdapterRequestContext): AdapterVerdict;
+        response?(ctx: AdapterResponseContext): unknown;
+    };
+    server?: {
+        request?(ctx: AdapterRequestContext): AdapterVerdict;
+    };
+}
+/** One adapter after validation: the route table, the digest the registry
+ * entry carries, the registry-shaped declaration (server-scope routes —
+ * an adapter is whole-machine data by definition), and the hooks. */
+export interface NormalizedAdapter {
+    plugin: string;
+    /** The exact versions this adapter was written against; the INSTALLED
+     * version must be among them or the adapter does not register. */
+    versions: readonly string[];
+    routes: NormalizedAdapterRoute[];
+    /** The digest of the ROUTE TABLE (locator and match included) — the
+     * value the registry entry and the handshake both carry. */
+    digest: string;
+    /** What went into the registry: version = the INSTALLED version, digest
+     * = {@link digest}, routes = the forwardable (non-local) ones. */
+    declaration: NormalizedDeclaration;
+    hooks: AdapterHooks;
+}
+/** The body cap an ADAPTER route may declare: 100 MiB — the relay's own
+ * upload budget (lib/relay-server.js `MAX_UPLOAD_BYTES`), which the
+ * better-sidebar upload route rides. Wider than the cooperative
+ * declaration's 64 MiB because raw media uploads are exactly what an
+ * adapter exists to carry; test/adapter-better-sidebar.test.cjs pins the
+ * two numbers together. */
+export declare const MAX_ADAPTER_BODY_BYTES: number;
+/** Validate one adapter's route table and fold it, together with the
+ * INSTALLED plugin version, into the registry-ready form.
+ *
+ * Route paths follow the cooperative declaration's rules verbatim (plain
+ * absolute paths, off the host-owned `/_dsh/` and `/api` prefixes) — an
+ * adapter must not be able to reach anything a declaration cannot. The
+ * installed version must be listed EXACTLY (`versions` are what the
+ * adapter was written against); anything else refuses the adapter whole.
+ * @throws with a field-naming message on any illegal shape.
+ */
+export declare function normalizeAdapter(input: unknown, installedVersion: string): NormalizedAdapter;
+/** The digest of one adapter's route table: sha256 over a canonical JSON of
+ * `{plugin, version, routes}` — the locator and the match mode INCLUDED (a
+ * different locating rule is a different adapter), hex, first 16 chars.
+ * Routes arrive path-sorted, so order never moves the hash. */
+export declare function adapterDigestOf(plugin: string, version: string, routes: NormalizedAdapterRoute[]): string;
+/** The prefix-match rule, shared verbatim by both halves: equality or one
+ * path segment deeper, on the RAW undecoded pathname. */
+export declare function adapterPathMatches(route: NormalizedAdapterRoute, pathname: string): boolean;
+/** The adapter route a forwarded request hit, or `undefined`. `local`
+ * routes never match here — they stay on the sub-client's own machine in
+ * both directions, so the server half must never see (nor serve) them. */
+export declare function matchAdapterRoute(adapters: readonly NormalizedAdapter[] | undefined, pathname: string): {
+    adapter: NormalizedAdapter;
+    route: NormalizedAdapterRoute;
+} | undefined;
+/** One located session id: where it sat and the value as found. */
+export interface AdapterIdHit {
+    kind: 'query' | 'path-segment' | 'json-body';
+    /** The query parameter or JSON field name; undefined for a path segment. */
+    key: string | undefined;
+    value: string;
+}
+/** Thrown when a query parameter the locator reads appears with MORE than
+ * one value: the cooperative bridge refuses such requests as `bad-query`
+ * (a duplicated id is a shape violation, never a forward of whichever
+ * duplicate a parser happens to keep), and so does the adapter (PB-12
+ * review note — the old behavior silently collapsed to `set`, rewriting
+ * only one of the values). Callers catch this and answer 503/400
+ * `bad-query`. */
+export declare class AdapterMultiValueQueryError extends Error {
+    constructor(name: string);
+}
+/** Locate the session ids one request carries for one route. A query
+ * parameter counts once per value it appears with; a JSON body field counts
+ * when present with a non-empty string value; a path segment counts when
+ * the segment exists (decoded once off the wire). */
+export declare function locateAdapterIds(route: NormalizedAdapterRoute, pathname: string, search: URLSearchParams, body: unknown): AdapterIdHit[];
+/** The remote/local verdict of one request (the design's rule, verbatim):
+ * every located id virtual → remote; none located, or none virtual →
+ * local; a MIX of virtual and plain ids → the request is malformed for the
+ * bridge and refuses rather than guessing which half travels. */
+export type AdapterRemoteVerdict = {
+    kind: 'remote';
+    hits: AdapterIdHit[];
+} | {
+    kind: 'local';
+} | {
+    kind: 'mixed';
+};
+export declare function classifyAdapterRequest(route: NormalizedAdapterRoute, pathname: string, search: URLSearchParams, body: unknown): AdapterRemoteVerdict;
+/** What {@link rewriteAdapterRequest} produces: the request coordinates
+ * with every located virtual id swapped for its real half. */
+export interface AdapterRewrite {
+    pathname: string;
+    query: URLSearchParams;
+    /** The re-serialized JSON body for a body-locating route that arrived
+     * with a body; `undefined` when there is nothing to re-serialize. */
+    bodyText: string | undefined;
+}
+/** Swap every located virtual id for its real half (the pure client-half
+ * rewrite): the query is re-serialized, the path segment re-encoded, the
+ * JSON body re-serialized. The re-encode direction is the wire contract —
+ * `encodeURIComponent` of the real id is what the server decodes again. */
+export declare function rewriteAdapterRequest(route: NormalizedAdapterRoute, pathname: string, search: URLSearchParams, body: unknown, hits: AdapterIdHit[], realIdOf: (virtualId: string) => string): AdapterRewrite;
+/** Whether the adapter still owns its plugin's registry entry, or a
+ * cooperative declaration (the plugin's OWN `zenRemote.bridge(...)`, which
+ * always wins) has taken the seat since: an entry with a different digest
+ * means the adapter yielded. */
+export declare function adapterOwnsRegistryEntry(adapter: NormalizedAdapter, registryEntry: {
+    version: string;
+    digest: string;
+} | undefined): boolean;
+/** The largest JSON answer the client half will buffer for a response
+ * rewrite: past this the body passes through untouched (8 MB). */
+export declare const MAX_ADAPTER_RESPONSE_BUFFER_BYTES: number;
+/** Response headers an ADAPTER answer may carry through VERBATIM, beyond
+ * the three every bridged forward passes (content-type, content-length,
+ * cache-control): the better-sidebar HTML preview ships a `content-
+ * security-policy` sandbox and downloads carry `content-disposition` —
+ * stripping those breaks the very panels the adapter exists to serve.
+ * Cooperative declaration routes keep the three-header behavior. */
+export declare const ADAPTER_RESPONSE_HEADER_ALLOWLIST: readonly ["content-security-policy", "content-disposition", "etag", "last-modified", "accept-ranges", "content-range"];
+//# sourceMappingURL=plugin-adapter-core.d.ts.map

package/lib/types/plugin-adapter-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-adapter-core.d.ts","sourceRoot":"","sources":["../../src/plugin-adapter-core.ts"],"names":[],"mappings":"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"}

package/lib/types/plugin-bridge.d.ts

@@ -0,0 +1,187 @@
+/**
+ * The plugin bridge's registration and comparison half (PB-1).
+ *
+ * Other DSH plugins can hand zen-remote a "bridge declaration": the list of
+ * THEIR OWN HTTP routes that may be forwarded to the main server inside a
+ * remote session (docs/adr/0001). A plugin counts as "bridged" only when
+ * BOTH ends agree on the plugin name, the exact version AND the declaration
+ * digest — everything here is the pure logic behind that agreement: the
+ * declaration shape and its validation ({@link normalizeDeclaration}), the
+ * per-process registry backing the `zenRemote` service
+ * ({@link createBridgeRegistry}), and the local-vs-server comparison that a
+ * later task feeds handshake data into ({@link compareBridges}).
+ *
+ * Pure logic by design: no DSH imports, no I/O, no clocks — the digest is
+ * the only place node:crypto appears, which is fine because this module only
+ * ever runs in the backend process. Nothing here talks to the relay or the
+ * network; the handshake side and the request rewrite side are later tasks
+ * that consume a {@link BridgeRegistry} through src/index.ts.
+ */
+/** Where a bridged route's caller supplies the session id. `'session'` — the
+ * data is scoped to one session, forwarded after the server checks the share.
+ * `'server'` — whole-machine data (e.g. every zcode task), which the server
+ * owner must consent to per plugin (the `pluginBridgeConsent` row knob). */
+export type BridgeScope = 'session' | 'server';
+/** The HTTP methods a bridged route may forward (PB-9). 2.1 accepted GET
+ * only; the write methods arrived with the `methods` field. */
+export declare const BRIDGE_METHODS: readonly ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"];
+/** The body cap a route may declare (`maxBody`), in bytes: 64 MiB. */
+export declare const MAX_ROUTE_BODY_BYTES: number;
+/** The body cap a route gets when it declares none: 1 MiB. */
+export declare const DEFAULT_ROUTE_BODY_BYTES: number;
+/** One forwardable route as a plugin declares it. `sessionParam` names the
+ * URL query parameter carrying the session id (default `'sessionId'`);
+ * `stream` marks routes answered as an event stream rather than one JSON
+ * body. `methods` (PB-9) lists the forwardable HTTP methods — uppercase
+ * members of {@link BRIDGE_METHODS}, deduplicated and sorted at
+ * normalization; omitted means `['GET']` (the 2.1 behavior). `maxBody`
+ * (PB-9) caps the forwarded request body in bytes; omitted means
+ * {@link DEFAULT_ROUTE_BODY_BYTES}. `upgrade` (PB-10) marks the route as a
+ * WebSocket endpoint carried over the byte tunnel — GET-only, mutually
+ * exclusive with `stream`. */
+export interface BridgeRoute {
+    path: string;
+    scope: BridgeScope;
+    sessionParam?: string;
+    stream?: boolean;
+    methods?: readonly string[];
+    maxBody?: number;
+    upgrade?: boolean;
+}
+/** What a plugin hands `zenRemote.bridge(...)` — the raw, unvalidated shape. */
+export interface BridgeDeclaration {
+    plugin: string;
+    version: string;
+    routes: BridgeRoute[];
+}
+/** A route after validation: every scalar field filled, `methods`,
+ * `maxBody` and `upgrade` present ONLY when the plugin declared them
+ * explicitly — the distinction is load-bearing for the digest (see the
+ * canonical form in {@link normalizeDeclaration}), while consumers read the
+ * EFFECTIVE values through {@link routeMethodsOf} / {@link routeMaxBodyOf}
+ * / {@link routeUpgradesOf}. */
+export interface NormalizedBridgeRoute {
+    path: string;
+    scope: BridgeScope;
+    sessionParam: string;
+    stream: boolean;
+    methods: string[] | undefined;
+    maxBody: number | undefined;
+    upgrade: boolean | undefined;
+}
+/** The effective upgrade mark of one normalized route. */
+export declare function routeUpgradesOf(route: NormalizedBridgeRoute): boolean;
+/** The effective forwardable methods of one normalized route. */
+export declare function routeMethodsOf(route: NormalizedBridgeRoute): string[];
+/** The effective body cap of one normalized route, in bytes. */
+export declare function routeMaxBodyOf(route: NormalizedBridgeRoute): number;
+/** A declaration after validation: every route field filled, routes sorted
+ * by path, and the 16-hex-char digest both ends will compare. */
+export interface NormalizedDeclaration {
+    plugin: string;
+    version: string;
+    routes: NormalizedBridgeRoute[];
+    digest: string;
+}
+/**
+ * Validate one declaration and fold it into its comparable form.
+ *
+ * Route paths must be plain absolute paths (start with `/`, no `?`, `#`,
+ * `..` or whitespace) and must stay off the two prefixes zen-remote does not
+ * own: `/_dsh/` (the plugin's own surface) and `/api` (the host's shared
+ * fetch channel) — bridging either would let a third plugin put words in the
+ * host's mouth. The `/api` check is the literal string prefix, so a plugin
+ * route like `/apifoo` is refused too; that overreach is deliberate, the
+ * rule must stay trivially predictable on both ends.
+ *
+ * The digest is sha256 over a canonical JSON of `{plugin, version, routes}`
+ * with a fixed key order, hex, first 16 characters — route ORDER is not part
+ * of it (two ends listing the same routes in different orders still match),
+ * any field VALUE is.
+ * @throws with a field-naming message on any illegal shape.
+ */
+export declare function normalizeDeclaration(input: unknown): NormalizedDeclaration;
+/** The service provided on the row context as `zenRemote`, both roles. Other
+ * plugins reach it with `ctx.inject(['zenRemote'], (c) => …)`; when
+ * zen-remote is not installed the inject never fires, so dependents need no
+ * conditional code. Exported as a TYPE only — no Context augmentation, so
+ * nothing here leaks into compositions without this plugin. */
+export interface ZenRemoteService {
+    /** Register this process's bridge declaration. Throws on an illegal
+     * declaration (nothing is registered); on success returns the dispose that
+     * removes exactly this registration. */
+    bridge(declaration: BridgeDeclaration): () => void;
+}
+/** How `register` reports a same-plugin overwrite. Injectable so tests (and
+ * src/index.ts, via the context logger) can observe it; absent = silent. */
+export interface CreateBridgeRegistryOptions {
+    warn?: (message: string) => void;
+}
+/** The per-process declaration table behind the `zenRemote` service. */
+export interface BridgeRegistry {
+    /** Validate and record one declaration (throws pass through, nothing is
+     * registered). A same-plugin registration REPLACES the earlier one and
+     * reports through `warn`. The returned dispose removes only the
+     * registration it came from — after an overwrite the STALE dispose is a
+     * no-op and must not remove the replacement. */
+    register(input: unknown): () => void;
+    /** Record an ALREADY-normalized declaration verbatim — no validation, no
+     * re-digest (PB-11). This is the adapter registration door: an adapter
+     * arrives with its own digest (over its route table, locator included)
+     * and its own normalized routes, shapes the cooperative validator cannot
+     * produce. The same-plugin replace/report/dispose semantics of
+     * {@link register} apply unchanged — which is exactly the yielding rule:
+     * a plugin's own later `zenRemote.bridge(...)` call replaces the adapter's
+     * entry and a warn notes the takeover. */
+    registerNormalized(normalized: NormalizedDeclaration): () => void;
+    /** All live declarations, sorted by plugin name. */
+    list(): NormalizedDeclaration[];
+    get(plugin: string): NormalizedDeclaration | undefined;
+    /** Fires once per successful register and per effective removal (an
+     * overwritten stale dispose fires nothing). Returns the unsubscribe. */
+    onChange(listener: () => void): () => void;
+}
+/**
+ * Create the registry one DSH process (one plugin row) owns.
+ *
+ * Overwrite bookkeeping is identity-based, not flag-based: each dispose
+ * closes over the exact declaration object it registered and only deletes
+ * the table entry while it is STILL that object — a stale dispose meeting a
+ * newer registration finds someone else's identity and does nothing.
+ */
+export declare function createBridgeRegistry(options?: CreateBridgeRegistryOptions): BridgeRegistry;
+/** Why a plugin is NOT bridged. The order of the cases below is the order
+ * {@link compareBridges} judges them in. */
+export type BridgeReason = 'not-on-server' | 'version-mismatch' | 'declaration-mismatch' | 'consent-off' | 'offline' | 'server-too-old';
+/** One plugin's bridge verdict on this device. */
+export interface BridgeStatus {
+    plugin: string;
+    bridged: boolean;
+    reason?: BridgeReason;
+    localVersion: string;
+    serverVersion?: string;
+}
+/** What the server reports about one plugin at handshake time (a later task
+ * carries it in the relay handshake). `serverScopeConsent` records whether
+ * the server owner consented to this plugin's whole-machine-data routes. */
+export interface ServerPluginEntry {
+    version: string;
+    digest: string;
+    serverScopeConsent: boolean;
+}
+/**
+ * Compare the local registry against the server's handshake table — one
+ * {@link BridgeStatus} per LOCAL declaration, in the input order.
+ *
+ * Judged in this order, first hit wins: offline → the server predates the
+ * plugins handshake field (`undefined`, so nothing can match) → the plugin
+ * is absent server-side → version differs → version equal but digest
+ * differs (same release, different declaration — a skew worth naming) → a
+ * `scope:'server'` route without the server owner's consent → bridged.
+ *
+ * Consent is judged `!== true` on purpose, not `=== false`: an entry without
+ * the field (an older server that learned the field later) means UNKNOWN
+ * consent, and whole-machine data must stay home until the server says yes.
+ */
+export declare function compareBridges(local: NormalizedDeclaration[], server: Record<string, ServerPluginEntry> | undefined, online: boolean): BridgeStatus[];
+//# sourceMappingURL=plugin-bridge.d.ts.map

package/lib/types/plugin-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-bridge.d.ts","sourceRoot":"","sources":["../../src/plugin-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;4EAG4E;AAC5E,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE9C;+DAC+D;AAC/D,eAAO,MAAM,cAAc,4DAA6D,CAAA;AAExF,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,QAAmB,CAAA;AAEpD,8DAA8D;AAC9D,eAAO,MAAM,wBAAwB,QAAc,CAAA;AAEnD;;;;;;;;;8BAS8B;AAC9B,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,WAAW,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,WAAW,EAAE,CAAA;CACtB;AAED;;;;;gCAKgC;AAChC,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,WAAW,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,OAAO,CAAA;IACf,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC7B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,OAAO,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7B;AAED,0DAA0D;AAC1D,wBAAgB,eAAe,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAErE;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,EAAE,CAErE;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAEnE;AAED;iEACiE;AACjE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,qBAAqB,EAAE,CAAA;IAC/B,MAAM,EAAE,MAAM,CAAA;CACf;AA2BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAoH1E;AAED;;;;+DAI+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B;;4CAEwC;IACxC,MAAM,CAAC,WAAW,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAAA;CACnD;AAED;4EAC4E;AAC5E,MAAM,WAAW,2BAA2B;IAC1C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B;;;;oDAIgD;IAChD,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,IAAI,CAAA;IACpC;;;;;;;8CAO0C;IAC1C,kBAAkB,CAAC,UAAU,EAAE,qBAAqB,GAAG,MAAM,IAAI,CAAA;IACjE,oDAAoD;IACpD,IAAI,IAAI,qBAAqB,EAAE,CAAA;IAC/B,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAA;IACtD;4EACwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAC3C;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,2BAAgC,GAAG,cAAc,CAqD9F;AAED;4CAC4C;AAC5C,MAAM,MAAM,YAAY,GACpB,eAAe,GACf,kBAAkB,GAClB,sBAAsB,GACtB,aAAa,GACb,SAAS,GACT,gBAAgB,CAAA;AAEpB,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;4EAE4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,kBAAkB,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,qBAAqB,EAAE,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,SAAS,EACrD,MAAM,EAAE,OAAO,GACd,YAAY,EAAE,CAiBhB"}

package/lib/types/plugin-loopback.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The plugin bridge's loopback executor (PB-3): performs one GET against one
+ * of THIS server's own plugin routes, over real loopback HTTP, so the
+ * plugin's own handler — its authentication, its req/res semantics — runs
+ * exactly as it would for a local browser (docs/adr/0001). The relay route
+ * hands this module a validated path + query and gets the plugin's answer
+ * back as a status code plus a byte stream to pump at the sub-client.
+ *
+ * Why the cookie dance: DSH 0.1.2+ requires a signed cookie on EVERY route.
+ * The gateway half solved this for browsers by "playing courier" — one
+ * `GET /?token=…` (the only URL that accepts a token), then the 303's
+ * `set-cookie` straight onto the client (lib/lan-gate-server.cjs
+ * attemptAuthExchange). This module is the same courier for the relay: it
+ * keeps ONE cookie in memory for the process, exchanges it once on first
+ * use, and re-exchanges exactly once when the plugin route answers 401 (a
+ * rotated signing key). The exchange is the lan-gate.mjs wiring's shape:
+ * `connection.authenticatedUrl(protocol//127.0.0.1:port)` builds the token
+ * URL — absent on 0.1.1 hosts, where there is nothing to exchange and every
+ * bridged call fails `loopback-auth` honestly.
+ *
+ * The cookie never leaves this module: no log, no state file, no response —
+ * it exists only as the `cookie` request header on the loopback hop.
+ *
+ * Transport is node:http / node:https on purpose: the plugin's answer must
+ * stream (chunk after chunk, with real backpressure) and must die the
+ * moment the sub-client hangs up (an AbortSignal reaches the socket), and
+ * 0.2.1's self-signed https needs `rejectUnauthorized: false` — a per-
+ * request knob fetch cannot express. The loosened verification is safe BY
+ * CONSTRUCTION: the connection is dialed to the literal 127.0.0.1 the
+ * wiring pinned, never to a name that could be spoofed; the worst an
+ * on-path attacker could forge is data from the machine's own web server
+ * to itself.
+ */
+import type { IncomingMessage } from 'node:http';
+/** The loopback bind info, re-read live per request by the wiring. */
+export interface PluginLoopbackTarget {
+    protocol: 'http:' | 'https:';
+    port: number;
+}
+/** The request headers this bridge passes through to the plugin. */
+export interface PluginLoopbackHeaders {
+    accept?: string;
+    range?: string;
+    /** PB-9: a forwarded request body's content type. */
+    contentType?: string;
+}
+/** The plugin route's answer, headers whitelisted to what the relay may
+ * forward. `stream` is the RAW IncomingMessage: the caller reads it (and
+ * only it) — the module has already drained every other outcome.
+ * `extraHeaders` (PB-12) carries the ADAPTER allowlist — the headers an
+ * adapter's answer may hand the browser verbatim (the HTML preview's CSP
+ * sandbox, download dispositions, range headers); the cooperative relay
+ * branch ignores it. */
+export interface PluginLoopbackResponse {
+    status: number;
+    contentType: string | undefined;
+    contentLength: string | undefined;
+    cacheControl: string | undefined;
+    extraHeaders: Record<string, string>;
+    stream: IncomingMessage;
+}
+/** The one failure the relay maps onto 502 `loopback-auth`: the cookie
+ * exchange could not run (no token URL on this host) or did not yield a
+ * cookie (wrong token, a non-redirect answer, a network error). */
+export declare class LoopbackAuthError extends Error {
+    constructor(message: string);
+}
+declare function isLoopbackAuthError(error: unknown): error is LoopbackAuthError;
+export interface CreatePluginLoopbackOptions {
+    /** The loopback bind, read live per request (a restarted web server may
+     * have moved; a snapshot would keep dialing the old port). */
+    getTarget: () => PluginLoopbackTarget;
+    /** The authenticated token URL (the lan-gate wiring's
+     * `connection.authenticatedUrl(protocol//127.0.0.1:port)` shape), read
+     * live per exchange; `undefined` — a host without the method — means the
+     * cookie can never be obtained and every bridged call fails
+     * `loopback-auth`. */
+    getTokenUrl: () => string | undefined;
+}
+export interface PluginLoopback {
+    /** The cookie the tunnel executor (PB-10) needs to write its OWN upgrade
+     * request — a raw socket dial, which cannot ride this module's `request`
+     * (it owns the cookie internally). Resolves the current pair, exchanging
+     * once when none is cached; empty string means the host has no token URL
+     * and the tunnel cannot authenticate. The cookie stays in memory. */
+    cookieHeader(): Promise<string>;
+    /** One validated request against the local plugin route. `path` arrives
+     * undecoded and `query` is the RELAY-CHECKED serialization (the caller
+     * never passes raw wire input — the parse-once discipline). `body` (PB-9)
+     * is the relay request's body streamed verbatim (an IncomingMessage or a
+     * byte stream), `null` for bodyless methods; it is pumped into the
+     * loopback request as-is — sizing it is the ROUTE's job, transport is
+     * this module's. Throws {@link LoopbackAuthError} when the cookie cannot
+     * be obtained; every other failure (target unreachable, the signal
+     * aborted, the body dying mid-flight) rejects with the underlying error
+     * and is the caller's `internal`/hang-up case. */
+    request(method: string, path: string, query: string, headers: PluginLoopbackHeaders, body: import('node:http').IncomingMessage | import('node:stream').Readable | null, signal: AbortSignal): Promise<PluginLoopbackResponse>;
+}
+/**
+ * Build the loopback executor. The cookie lives only in this closure.
+ */
+export declare function createPluginLoopback(options: CreatePluginLoopbackOptions): PluginLoopback;
+export { isLoopbackAuthError };
+//# sourceMappingURL=plugin-loopback.d.ts.map

package/lib/types/plugin-loopback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-loopback.d.ts","sourceRoot":"","sources":["../../src/plugin-loopback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAahD,sEAAsE;AACtE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,OAAO,GAAG,QAAQ,CAAA;IAC5B,IAAI,EAAE,MAAM,CAAA;CACb;AAED,oEAAoE;AACpE,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;wBAMwB;AACxB,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACpC,MAAM,EAAE,eAAe,CAAA;CACxB;AAED;;mEAEmE;AACnE,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,iBAAS,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAEvE;AAED,MAAM,WAAW,2BAA2B;IAC1C;kEAC8D;IAC9D,SAAS,EAAE,MAAM,oBAAoB,CAAA;IACrC;;;;0BAIsB;IACtB,WAAW,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B;;;;yEAIqE;IACrE,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAC/B;;;;;;;;;sDASkD;IAClD,OAAO,CACL,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,qBAAqB,EAC9B,IAAI,EAAE,OAAO,WAAW,EAAE,eAAe,GAAG,OAAO,aAAa,EAAE,QAAQ,GAAG,IAAI,EACjF,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,sBAAsB,CAAC,CAAA;CACnC;AA+DD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,cAAc,CAoGzF;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAA"}