@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.4

package/lib/types/core/playwright-sessions/wire.d.ts

@@ -0,0 +1,78 @@
+/** Pure wire-protocol helpers for the agent-browser live-view WebSocket.
+ *
+ * One text protocol, two directions:
+ *
+ *   server -> client
+ *     { type: 'frame', data, deviceWidth, deviceHeight, pageScaleFactor }  CDP screencast JPEG
+ *     { type: 'status', state: 'no-page' | 'browser-closed' | 'error', message? }  lifecycle
+ *
+ *   client -> server (strict input whitelist, never arbitrary CDP methods)
+ *     { type: 'input', input: 'mouse', action: 'move'|'down'|'up'|'wheel', x, y, button?, buttons?, clickCount?, deltaX?, deltaY? }
+ *     { type: 'input', input: 'keyboard', action: 'down'|'up'|'type', key?, code?, text? }
+ *
+ * `x`/`y` are CSS-viewport coordinates already scaled by the client against
+ * the frame's device dimensions. These helpers are pure (no I/O) so the
+ * message building and input -> CDP mapping are unit-testable in isolation.
+ */
+/** One `Page.screencastFrame` CDP payload (structural subset we read). */
+export interface ScreencastFrame {
+    data: string;
+    metadata: {
+        deviceWidth: number;
+        deviceHeight: number;
+        pageScaleFactor: number;
+        [key: string]: unknown;
+    };
+    sessionId: number;
+}
+/** Serialize one screencast JPEG frame for the wire. */
+export declare function buildFrameMessage(frame: ScreencastFrame): string;
+/** Serialize a lifecycle status message for the wire. */
+export declare function buildStatusMessage(state: 'no-page' | 'browser-closed' | 'error', message?: string): string;
+/** A concrete CDP command ready to dispatch to the attached page session. */
+export interface CdpCommand {
+    method: string;
+    params: Record<string, unknown>;
+}
+/** Normalized mouse input accepted from the client. */
+export interface MouseInputMessage {
+    type: 'input';
+    input: 'mouse';
+    action: 'move' | 'down' | 'up' | 'wheel';
+    x: number;
+    y: number;
+    button?: string;
+    buttons?: number;
+    clickCount?: number;
+    deltaX?: number;
+    deltaY?: number;
+}
+/** Normalized keyboard input accepted from the client. */
+export interface KeyboardInputMessage {
+    type: 'input';
+    input: 'keyboard';
+    action: 'down' | 'up' | 'type';
+    key?: string;
+    code?: string;
+    text?: string;
+}
+export type InputMessage = MouseInputMessage | KeyboardInputMessage;
+/**
+ * Map a whitelisted mouse input into `Input.dispatchMouseEvent`. Returns
+ * null when the message is malformed (missing/non-finite x/y or an unknown
+ * action) so the caller silently ignores it rather than forwarding junk.
+ */
+export declare function mapMouseInput(msg: MouseInputMessage): CdpCommand | null;
+/**
+ * Map a whitelisted keyboard input into `Input.insertText` (action 'type')
+ * or `Input.dispatchKeyEvent` (action 'down'/'up'). Returns null for an
+ * unknown action or a 'type' without text.
+ */
+export declare function mapKeyboardInput(msg: KeyboardInputMessage): CdpCommand | null;
+/**
+ * The single input entry point. Only `type: 'input'` messages with a
+ * recognized `input` kind ever produce a command; every other shape
+ * (including any attempted raw CDP method name) is dropped here.
+ */
+export declare function mapInputMessage(raw: unknown): CdpCommand | null;
+//# sourceMappingURL=wire.d.ts.map

package/lib/types/core/playwright-sessions/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../../src/core/playwright-sessions/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE;QACR,WAAW,EAAE,MAAM,CAAA;QACnB,YAAY,EAAE,MAAM,CAAA;QACpB,eAAe,EAAE,MAAM,CAAA;QACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;IACD,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAQhE;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,gBAAgB,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAG1G;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAA;IACxC,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,0DAA0D;AAC1D,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,UAAU,CAAA;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAA;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,oBAAoB,CAAA;AAInE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,iBAAiB,GAAG,UAAU,GAAG,IAAI,CAoBvE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,oBAAoB,GAAG,UAAU,GAAG,IAAI,CAe7E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAO/D"}

package/lib/types/core/playwright-sessions/wire.js

@@ -0,0 +1,103 @@
+/** Pure wire-protocol helpers for the agent-browser live-view WebSocket.
+ *
+ * One text protocol, two directions:
+ *
+ *   server -> client
+ *     { type: 'frame', data, deviceWidth, deviceHeight, pageScaleFactor }  CDP screencast JPEG
+ *     { type: 'status', state: 'no-page' | 'browser-closed' | 'error', message? }  lifecycle
+ *
+ *   client -> server (strict input whitelist, never arbitrary CDP methods)
+ *     { type: 'input', input: 'mouse', action: 'move'|'down'|'up'|'wheel', x, y, button?, buttons?, clickCount?, deltaX?, deltaY? }
+ *     { type: 'input', input: 'keyboard', action: 'down'|'up'|'type', key?, code?, text? }
+ *
+ * `x`/`y` are CSS-viewport coordinates already scaled by the client against
+ * the frame's device dimensions. These helpers are pure (no I/O) so the
+ * message building and input -> CDP mapping are unit-testable in isolation.
+ */
+/** Serialize one screencast JPEG frame for the wire. */
+export function buildFrameMessage(frame) {
+    return JSON.stringify({
+        type: 'frame',
+        data: frame.data,
+        deviceWidth: frame.metadata.deviceWidth,
+        deviceHeight: frame.metadata.deviceHeight,
+        pageScaleFactor: frame.metadata.pageScaleFactor,
+    });
+}
+/** Serialize a lifecycle status message for the wire. */
+export function buildStatusMessage(state, message) {
+    if (message !== undefined)
+        return JSON.stringify({ type: 'status', state, message });
+    return JSON.stringify({ type: 'status', state });
+}
+const MOUSE_ACTIONS = new Set(['move', 'down', 'up', 'wheel']);
+/**
+ * Map a whitelisted mouse input into `Input.dispatchMouseEvent`. Returns
+ * null when the message is malformed (missing/non-finite x/y or an unknown
+ * action) so the caller silently ignores it rather than forwarding junk.
+ */
+export function mapMouseInput(msg) {
+    if (typeof msg.x !== 'number' || typeof msg.y !== 'number')
+        return null;
+    if (!Number.isFinite(msg.x) || !Number.isFinite(msg.y))
+        return null;
+    if (!MOUSE_ACTIONS.has(msg.action))
+        return null;
+    const type = msg.action === 'wheel' ? 'mouseWheel'
+        : msg.action === 'down' ? 'mousePressed'
+            : msg.action === 'up' ? 'mouseReleased'
+                : 'mouseMoved';
+    const params = {
+        type,
+        x: msg.x,
+        y: msg.y,
+        button: typeof msg.button === 'string' ? msg.button : 'none',
+        buttons: typeof msg.buttons === 'number' ? msg.buttons : 0,
+        clickCount: typeof msg.clickCount === 'number' ? msg.clickCount : 1,
+    };
+    if (typeof msg.deltaX === 'number')
+        params.deltaX = msg.deltaX;
+    if (typeof msg.deltaY === 'number')
+        params.deltaY = msg.deltaY;
+    return { method: 'Input.dispatchMouseEvent', params };
+}
+/**
+ * Map a whitelisted keyboard input into `Input.insertText` (action 'type')
+ * or `Input.dispatchKeyEvent` (action 'down'/'up'). Returns null for an
+ * unknown action or a 'type' without text.
+ */
+export function mapKeyboardInput(msg) {
+    if (msg.action === 'type') {
+        if (typeof msg.text !== 'string')
+            return null;
+        return { method: 'Input.insertText', params: { text: msg.text } };
+    }
+    if (msg.action === 'down' || msg.action === 'up') {
+        const params = {
+            type: msg.action === 'down' ? 'keyDown' : 'keyUp',
+            key: typeof msg.key === 'string' ? msg.key : '',
+            code: typeof msg.code === 'string' ? msg.code : '',
+        };
+        if (typeof msg.text === 'string')
+            params.text = msg.text;
+        return { method: 'Input.dispatchKeyEvent', params };
+    }
+    return null;
+}
+/**
+ * The single input entry point. Only `type: 'input'` messages with a
+ * recognized `input` kind ever produce a command; every other shape
+ * (including any attempted raw CDP method name) is dropped here.
+ */
+export function mapInputMessage(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const msg = raw;
+    if (msg.type !== 'input')
+        return null;
+    if (msg.input === 'mouse')
+        return mapMouseInput(msg);
+    if (msg.input === 'keyboard')
+        return mapKeyboardInput(msg);
+    return null;
+}

package/lib/types/core/remote-access/paths.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Wire constants shared by the host and browser halves of remote access.
+ *
+ * They live in `core/` because the served boot row (host half) and the client
+ * trust patch (browser half) must agree byte-for-byte on the paths and on the
+ * provenance marker cookie; `src/client/trust.ts` cannot import the host half.
+ * @module dsh-web-all/core/remote-access/paths
+ */
+/** Parser-blocking boot script path; the host decides per request. */
+export declare const HOST_ACCESS_BOOT_PATH = "/web-all/remote-access/boot.js";
+/** Credential-free posture readout for one requesting Host. */
+export declare const HOST_ACCESS_SESSION_PATH = "/api/dsh-access/session";
+/** Browser-readable provenance marker: "this Host was an admitted entry". */
+export declare const HOST_ACCESS_MARKER_COOKIE = "dsh_access_host";
+/** The only value the marker carries; anything else means "not marked". */
+export declare const HOST_ACCESS_MARKER_VALUE = "1";
+/** Marker lifetime; mirrors the gateway marker. */
+export declare const HOST_ACCESS_MARKER_MAX_AGE_SECONDS: number;
+//# sourceMappingURL=paths.d.ts.map

package/lib/types/core/remote-access/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../../src/core/remote-access/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,mCAAmC,CAAA;AAErE,+DAA+D;AAC/D,eAAO,MAAM,wBAAwB,4BAA4B,CAAA;AAEjE,6EAA6E;AAC7E,eAAO,MAAM,yBAAyB,oBAAoB,CAAA;AAE1D,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAE3C,mDAAmD;AACnD,eAAO,MAAM,kCAAkC,QAAiB,CAAA"}

package/lib/types/core/remote-access/paths.js

@@ -0,0 +1,18 @@
+/**
+ * Wire constants shared by the host and browser halves of remote access.
+ *
+ * They live in `core/` because the served boot row (host half) and the client
+ * trust patch (browser half) must agree byte-for-byte on the paths and on the
+ * provenance marker cookie; `src/client/trust.ts` cannot import the host half.
+ * @module dsh-web-all/core/remote-access/paths
+ */
+/** Parser-blocking boot script path; the host decides per request. */
+export const HOST_ACCESS_BOOT_PATH = '/web-all/remote-access/boot.js';
+/** Credential-free posture readout for one requesting Host. */
+export const HOST_ACCESS_SESSION_PATH = '/api/dsh-access/session';
+/** Browser-readable provenance marker: "this Host was an admitted entry". */
+export const HOST_ACCESS_MARKER_COOKIE = 'dsh_access_host';
+/** The only value the marker carries; anything else means "not marked". */
+export const HOST_ACCESS_MARKER_VALUE = '1';
+/** Marker lifetime; mirrors the gateway marker. */
+export const HOST_ACCESS_MARKER_MAX_AGE_SECONDS = 30 * 24 * 3600;

package/lib/types/core/remote-web-ui/security.d.ts

@@ -0,0 +1,35 @@
+export declare const DEFAULT_PAIR_TOKEN_TTL_MS: number;
+export declare const DEFAULT_GATEWAY_MAX_BODY_BYTES: number;
+export declare const DEFAULT_GATEWAY_TIMEOUT_MS: number;
+export declare const DEFAULT_GATEWAY_TARGET_ORIGIN = "http://127.0.0.1:3080";
+export interface PairTokenSummary {
+    id: string;
+    label: string;
+    createdAt: number;
+    expiresAt: number;
+}
+export interface PairTokenStoreOptions {
+    ttlMs?: number;
+    now?: () => number;
+    randomToken?: () => string;
+    randomId?: () => string;
+}
+export declare class PairTokenStore {
+    private readonly records;
+    private readonly ttlMs;
+    private readonly now;
+    private readonly randomToken;
+    private readonly randomId;
+    constructor(options?: PairTokenStoreOptions);
+    issue(label: string): PairTokenSummary & {
+        token: string;
+    };
+    authenticate(token: string): PairTokenSummary | undefined;
+    list(): PairTokenSummary[];
+    revoke(id: string): boolean;
+    private pruneExpired;
+}
+export declare function bearerToken(value: string | string[] | undefined): string | undefined;
+export declare function resolveGatewayTarget(requestUrl: string | undefined, targetOrigin?: string): URL | undefined;
+export declare function isAllowedGatewayMethod(method: string | undefined): boolean;
+//# sourceMappingURL=security.d.ts.map

package/lib/types/core/remote-web-ui/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../../../src/core/remote-web-ui/security.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,yBAAyB,QAAiB,CAAA;AACvD,eAAO,MAAM,8BAA8B,QAAc,CAAA;AACzD,eAAO,MAAM,0BAA0B,QAAY,CAAA;AACnD,eAAO,MAAM,6BAA6B,0BAA0B,CAAA;AAKpE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAMD,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;IAC1B,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAA;CACxB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;gBAE3B,OAAO,GAAE,qBAA0B;IAQ/C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;IAmB1D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAYzD,IAAI,IAAI,gBAAgB,EAAE;IAO1B,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAW3B,OAAO,CAAC,YAAY;CAMrB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIpF;AAED,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,YAAY,SAAgC,GAC3C,GAAG,GAAG,SAAS,CA4BjB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE1E"}

package/lib/types/core/remote-web-ui/security.js

@@ -0,0 +1,146 @@
+import { createHash, randomBytes } from 'node:crypto';
+export const DEFAULT_PAIR_TOKEN_TTL_MS = 15 * 60 * 1000;
+export const DEFAULT_GATEWAY_MAX_BODY_BYTES = 1024 * 1024;
+export const DEFAULT_GATEWAY_TIMEOUT_MS = 15 * 1000;
+export const DEFAULT_GATEWAY_TARGET_ORIGIN = 'http://127.0.0.1:3080';
+const ALLOWED_GATEWAY_METHODS = new Set(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']);
+const FORBIDDEN_GATEWAY_PREFIXES = ['/api/pair', '/api/gateway'];
+export class PairTokenStore {
+    records = new Map();
+    ttlMs;
+    now;
+    randomToken;
+    randomId;
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? DEFAULT_PAIR_TOKEN_TTL_MS;
+        this.now = options.now ?? Date.now;
+        this.randomToken = options.randomToken ?? defaultSecret;
+        this.randomId = options.randomId ?? defaultId;
+        if (!Number.isFinite(this.ttlMs) || this.ttlMs <= 0)
+            throw new Error('pair token ttl must be positive');
+    }
+    issue(label) {
+        this.pruneExpired();
+        const token = this.randomToken();
+        const digest = digestToken(token);
+        const now = this.now();
+        const id = this.randomId();
+        if (token.length === 0 || this.records.has(digest))
+            throw new Error('pair token generator produced a duplicate token');
+        if (!/^[a-f\d]{24}$/i.test(id) || [...this.records.values()].some(record => record.id === id))
+            throw new Error('pair token generator produced an invalid id');
+        const record = {
+            id,
+            label,
+            createdAt: now,
+            expiresAt: now + this.ttlMs,
+            digest,
+        };
+        this.records.set(digest, record);
+        return { id: record.id, label: record.label, createdAt: record.createdAt, expiresAt: record.expiresAt, token };
+    }
+    authenticate(token) {
+        if (token.length === 0)
+            return undefined;
+        const digest = digestToken(token);
+        const record = this.records.get(digest);
+        if (record === undefined)
+            return undefined;
+        if (record.expiresAt <= this.now()) {
+            this.records.delete(digest);
+            return undefined;
+        }
+        return summarize(record);
+    }
+    list() {
+        this.pruneExpired();
+        return [...this.records.values()]
+            .map(summarize)
+            .sort((left, right) => left.createdAt - right.createdAt);
+    }
+    revoke(id) {
+        this.pruneExpired();
+        for (const [digest, record] of this.records) {
+            if (record.id === id) {
+                this.records.delete(digest);
+                return true;
+            }
+        }
+        return false;
+    }
+    pruneExpired() {
+        const now = this.now();
+        for (const [digest, record] of this.records) {
+            if (record.expiresAt <= now)
+                this.records.delete(digest);
+        }
+    }
+}
+export function bearerToken(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const match = /^Bearer[ \t]+([^\s,]+)[ \t]*$/i.exec(value);
+    return match?.[1];
+}
+export function resolveGatewayTarget(requestUrl, targetOrigin = DEFAULT_GATEWAY_TARGET_ORIGIN) {
+    if (typeof requestUrl !== 'string' || requestUrl === '' || /^[a-z][a-z\d+.-]*:/i.test(requestUrl) || requestUrl.startsWith('//')) {
+        return undefined;
+    }
+    let outer;
+    let origin;
+    try {
+        outer = new URL(requestUrl, 'http://gateway.invalid');
+        origin = new URL(targetOrigin);
+    }
+    catch {
+        return undefined;
+    }
+    if (origin.protocol !== 'http:' && origin.protocol !== 'https:')
+        return undefined;
+    if (origin.username !== '' || origin.password !== '' || origin.pathname !== '/' || origin.search !== '' || origin.hash !== '')
+        return undefined;
+    const pathname = outer.pathname;
+    const gatewayPrefix = '/api/gateway';
+    if (pathname !== gatewayPrefix && !pathname.startsWith(`${gatewayPrefix}/`))
+        return undefined;
+    const innerPath = pathname.slice(gatewayPrefix.length);
+    if (innerPath === '' || !isSafeApiPath(innerPath))
+        return undefined;
+    const target = new URL(origin.href);
+    target.pathname = innerPath;
+    target.search = outer.search;
+    target.hash = '';
+    return target;
+}
+export function isAllowedGatewayMethod(method) {
+    return ALLOWED_GATEWAY_METHODS.has(method ?? 'GET');
+}
+function isSafeApiPath(pathname) {
+    if (!pathname.startsWith('/api/') || pathname.includes('\\') || pathname.includes('\0'))
+        return false;
+    if (FORBIDDEN_GATEWAY_PREFIXES.some(prefix => pathname === prefix || pathname.startsWith(`${prefix}/`)))
+        return false;
+    const rawSegments = pathname.slice(1).split('/');
+    if (rawSegments.length < 2 || rawSegments.some(segment => segment.length === 0))
+        return false;
+    for (const rawSegment of rawSegments) {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(rawSegment);
+        }
+        catch {
+            return false;
+        }
+        if (decoded === '.' || decoded === '..' || decoded.includes('/') || decoded.includes('\\') || decoded.includes('\0'))
+            return false;
+    }
+    return true;
+}
+function defaultSecret() { return randomBytes(32).toString('base64url'); }
+function defaultId() { return randomBytes(12).toString('hex'); }
+function digestToken(token) {
+    return createHash('sha256').update(token).digest('hex');
+}
+function summarize(record) {
+    return { id: record.id, label: record.label, createdAt: record.createdAt, expiresAt: record.expiresAt };
+}

package/lib/types/core/right-pane/protocol.d.ts

@@ -0,0 +1,25 @@
+/** Shared wire vocabulary for the web-all right-pane additions (git, browser). */
+export type BrowserNavigateResult = {
+    kind: 'ok';
+    url: string;
+} | {
+    kind: 'blocked';
+    reason: 'scheme' | 'loopback' | 'self-origin';
+} | {
+    kind: 'invalid';
+};
+export declare function isLoopbackHostname(value: string): boolean;
+/** Detailed secure navigation verdict for the sidebar browser. */
+export declare function evaluateBrowserUrl(value: string, selfOrigin?: string): BrowserNavigateResult;
+/** Compatibility normalizer retained for existing contract consumers. */
+export declare function normalizeBrowserUrl(value: string): string | undefined;
+export interface GitStatusEntry {
+    path: string;
+    xy: string;
+}
+export declare function parsePorcelainStatus(output: string): GitStatusEntry[];
+/** The address of a file read through one session, mirroring the official encoder. */
+export declare function sessionFileAddress(sessionId: string, path: string): string;
+/** Map a caller-held path to its session-scoped resource address (official semantics). */
+export declare function fileAddressFor(sessionId: string, cwd: string | undefined, path: string): string;
+//# sourceMappingURL=protocol.d.ts.map

package/lib/types/core/right-pane/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../../src/core/right-pane/protocol.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,aAAa,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAA;AAIvB,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,qBAAqB,CAa5F;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGrE;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;CACX;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,CAWrE;AAyBD,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG1E;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAO/F"}

package/lib/types/core/right-pane/protocol.js

@@ -0,0 +1,91 @@
+/** Shared wire vocabulary for the web-all right-pane additions (git, browser). */
+const FORBIDDEN_BROWSER_SCHEMES = /^(?:javascript|data|file|about|blob|vbscript|mailto|tel|ftp|ws|wss):/iu;
+export function isLoopbackHostname(value) {
+    const hostname = value.replace(/^\[|\]$/gu, '').toLowerCase();
+    if (hostname === 'localhost' || hostname === '::1' || hostname === '0.0.0.0')
+        return true;
+    const octets = hostname.split('.');
+    return octets.length === 4 && octets[0] === '127' && octets.every(part => /^\d{1,3}$/u.test(part) && Number(part) <= 255);
+}
+/** Detailed secure navigation verdict for the sidebar browser. */
+export function evaluateBrowserUrl(value, selfOrigin) {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return { kind: 'invalid' };
+    if (FORBIDDEN_BROWSER_SCHEMES.test(trimmed))
+        return { kind: 'blocked', reason: 'scheme' };
+    const candidate = /^https?:\/\//iu.test(trimmed) ? trimmed : `https://${trimmed}`;
+    let url;
+    try {
+        url = new URL(candidate);
+    }
+    catch {
+        return { kind: 'invalid' };
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return { kind: 'blocked', reason: 'scheme' };
+    if (selfOrigin) {
+        try {
+            if (url.origin === new URL(selfOrigin).origin)
+                return { kind: 'blocked', reason: 'self-origin' };
+        }
+        catch { /* ignore malformed owner origin */ }
+    }
+    if (isLoopbackHostname(url.hostname))
+        return { kind: 'blocked', reason: 'loopback' };
+    return { kind: 'ok', url: url.href };
+}
+/** Compatibility normalizer retained for existing contract consumers. */
+export function normalizeBrowserUrl(value) {
+    const verdict = evaluateBrowserUrl(value);
+    return verdict.kind === 'ok' ? verdict.url : undefined;
+}
+export function parsePorcelainStatus(output) {
+    const tokens = output.split('\0');
+    const entries = [];
+    for (let index = 0; index < tokens.length;) {
+        const token = tokens[index++];
+        if (token === '')
+            continue;
+        const xy = token.slice(0, 2);
+        entries.push({ xy, path: token.slice(3) });
+        if ((xy[0] === 'R' || xy[0] === 'C') && tokens[index] !== undefined && tokens[index] !== '')
+            index += 1;
+    }
+    return entries;
+}
+/**
+ * Native `dsh-resource://file/...` address builder mirroring the official
+ * sidebar-files vocabulary, so produced files open in the DSH document
+ * preview instead of a plugin file window.
+ */
+const FILE_ADDRESS_PREFIX = 'dsh-resource://file/session/';
+function encodeSegment(segment) {
+    return encodeURIComponent(segment).replace(/%3A/gi, ':');
+}
+function encodePath(path) {
+    return path.split('/').map(encodeSegment).join('/');
+}
+function isWindowsStylePath(value) {
+    return /^[A-Za-z]:[/\\]/.test(value) || value.startsWith('\\\\');
+}
+function isAbsoluteWorkspacePath(value) {
+    return value.startsWith('/') || isWindowsStylePath(value);
+}
+/** The address of a file read through one session, mirroring the official encoder. */
+export function sessionFileAddress(sessionId, path) {
+    const normalized = path.replace(/\\/gu, '/').replace(/^(?:\.\/)+/u, '');
+    return `${FILE_ADDRESS_PREFIX}${encodeSegment(sessionId)}/${encodePath(normalized)}`;
+}
+/** Map a caller-held path to its session-scoped resource address (official semantics). */
+export function fileAddressFor(sessionId, cwd, path) {
+    const normalized = path.replace(/\\/gu, '/');
+    if (!isAbsoluteWorkspacePath(normalized))
+        return sessionFileAddress(sessionId, normalized);
+    const root = cwd === undefined ? '' : cwd.replace(/\\/gu, '/').replace(/\/+$/u, '');
+    if (root !== '' && normalized === root)
+        return sessionFileAddress(sessionId, '');
+    if (root !== '' && normalized.startsWith(`${root}/`))
+        return sessionFileAddress(sessionId, normalized.slice(root.length + 1));
+    return sessionFileAddress(sessionId, normalized);
+}

package/lib/types/core/schedule-mode/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * schedule-mode 共享纯逻辑出口（host + client 双 program 编译）。
+ */
+export * from './types.ts';
+export * from './native.ts';
+export * from './view.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/core/schedule-mode/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/schedule-mode/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA"}

package/lib/types/core/schedule-mode/index.js

@@ -0,0 +1,6 @@
+/**
+ * schedule-mode 共享纯逻辑出口（host + client 双 program 编译）。
+ */
+export * from "./types.js";
+export * from "./native.js";
+export * from "./view.js";

package/lib/types/core/schedule-mode/native.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 原生 schedule 任务结构的**容忍解码**与归一化（host + client 共享）。
+ *
+ * 本层只依赖原生任务记录的公开字段（`kind` / `scheduledAt` / 各 selector 字段），
+ * 不 import 原生包：原生 schedule bundle 是可选的实验 bundle，值导入会让
+ * web-all 在没装它的 profile 里直接加载失败。记录形状来自
+ * `@deepseek-ai/dsh-schedule` 的公开 `types.d.ts`。
+ */
+import type { ScheduleModeRule } from './types.ts';
+/** 原生目录条目中本能力需要的最小事实。 */
+export interface NativeTaskView {
+    /** 任务绑定的会话（轮转后即运行会话）。 */
+    readonly sessionId: string;
+    readonly id: string;
+    readonly status: 'active' | 'inactive';
+    readonly title: string;
+    readonly prompt: string;
+    /** 已提交的下一次（或最后一次）时点。 */
+    readonly scheduledAt: string;
+    readonly rule: ScheduleModeRule;
+    /** 最近一次确认投递；缺省表示尚未投递过。 */
+    readonly lastDelivery?: {
+        readonly scheduledAt: string;
+        readonly deliveredAt: string;
+    };
+}
+/** 从一条原生任务记录解出计时规则；无法识别返回 undefined（调用方跳过该条）。 */
+export declare function ruleFromRecord(record: unknown): ScheduleModeRule | undefined;
+/**
+ * 把原生 `catalog()` 条目解码成 `NativeTaskView`。
+ * 结构不符的条目（例如未来新增的规则种类）返回 undefined，由调用方忽略，
+ * 保证本能力不会因为原生形态演进整块失效。
+ */
+export declare function nativeTaskView(entry: unknown): NativeTaskView | undefined;
+//# sourceMappingURL=native.d.ts.map

package/lib/types/core/schedule-mode/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../../../../src/core/schedule-mode/native.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,yBAAyB;AACzB,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAA;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,wBAAwB;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAC/B,0BAA0B;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;CACvF;AAUD,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAsC5E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAyBzE"}