@lornatang/dsh-frontgate 0.0.0-stage → 0.1.2

package/lib/types/auth.d.ts

@@ -0,0 +1,39 @@
+/** Name of the session cookie. */
+export declare const COOKIE = "dsh_gate";
+/** Version prefix of signed session tokens. */
+export declare const TOKEN_VERSION = "v1";
+/** Longest accepted token, in characters. */
+export declare const MAX_TOKEN_LENGTH = 256;
+/** Shortest accepted configured password, in characters. */
+export declare const MIN_PASSWORD_LENGTH = 12;
+/** Stored hash format: scrypt$N$r$p$saltHex$keyHex. */
+export declare const HASH_RE: RegExp;
+/** scrypt cost parameters used when a new hash is created. */
+export interface ScryptParams {
+    N?: number;
+    r?: number;
+    p?: number;
+    keylen?: number;
+}
+/** Reject configured passwords that are too short to survive guessing. */
+export declare function assertStrongPassword(password: string, source: string): string;
+/** Hash a password with scrypt; parameters travel with the hash. */
+export declare function hashPassword(password: string, params?: ScryptParams): string;
+/** Check the complete persisted format and its bounded scrypt parameters. */
+export declare function validPasswordHash(value: unknown): value is string;
+/** Async verification: the event loop stays free while scrypt runs. */
+export declare function verifyPassword(password: string, stored: unknown): Promise<boolean>;
+/** Synchronous verification, used only to reuse the persisted salt at startup. */
+export declare function verifyPasswordSync(password: string, stored: unknown): boolean;
+/** Random password shown once when no password is configured. */
+export declare function randomPassword(): string;
+/** Stable, non-reversible tag of the password hash; embedded in every session. */
+export declare const passwordVersion: (passwordHash: string) => string;
+/** Create a signed session token: v1.issuedAt.expiresAt.nonce.passwordVersion.mac. */
+export declare function signToken(secret: string, pv: string, ttlSeconds: number): string;
+/** Verify signature, version, password binding and expiry in constant time. */
+export declare function verifyToken(secret: string, pv: string, token: string | undefined): boolean;
+/** Session cookie attributes; Secure follows the browser-facing protocol. */
+export declare function sessionCookie(value: string, seconds: number, useTls: boolean): string;
+/** Expired session cookie. */
+export declare const clearCookie: (secure: boolean) => string;

package/lib/types/config.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Plugin configuration and its loader schema.
+ *
+ * The values are also the documented defaults, so a patch file that only sets
+ * one option behaves exactly like the README's configuration table.
+ */
+import z from '@deepseek-ai/schemastery';
+/** Configuration accepted through cordis.patch.yml or the loader. */
+export interface Config {
+    /** Interface the gate listens on. */
+    listenHost: string;
+    /** Port the gate listens on; 0 picks an ephemeral port. */
+    listenPort: number;
+    /** Session lifetime in days. */
+    sessionDays: number;
+    /** Title shown on the login page. */
+    title: string;
+    /** Plain-text password; hashed at startup and never written to disk as text. */
+    password: string;
+    /** scrypt password hash; takes precedence over password, environment and state file. */
+    passwordHash: string;
+    /** Optional TLS certificate; both files must be set to serve HTTPS. */
+    tlsCertFile: string;
+    /** Optional TLS key; both files must be set to serve HTTPS. */
+    tlsKeyFile: string;
+    /** Browser-facing origin, required when a reverse proxy terminates TLS. */
+    publicOrigin: string;
+    /** Honour X-Forwarded-For only when the listener is restricted to a trusted proxy. */
+    trustProxy: boolean;
+    /** Failed logins before a client is locked out. */
+    maxAttempts: number;
+    /** Lockout duration in minutes. */
+    lockMinutes: number;
+    /** Maximum time to exchange the harness launch token, in milliseconds. */
+    exchangeTimeoutMs: number;
+    /** Maximum simultaneous TCP connections from one peer; 0 disables this limit. */
+    maxConnectionsPerPeer: number;
+    /** Maximum login forms being received from one client IP. */
+    maxPendingLoginsPerIp: number;
+    /** Deadline for upstream response headers, including time queued for a socket; 0 disables. */
+    upstreamHeaderTimeoutMs: number;
+    /** Maximum idle time after upstream response headers; 0 disables. */
+    upstreamIdleTimeoutMs: number;
+    /** Optional CA certificate for a private HTTPS harness. */
+    upstreamCaFile: string;
+    /** Optional TLS identity when connecting to an HTTPS harness by IP. */
+    upstreamServerName: string;
+}
+/** Defaults applied by the loader and by direct calls to apply(). */
+export declare const DEFAULTS: Config;
+/** Schemastery schema; the loader validates and fills defaults before apply(). */
+export declare const Config: z<Config>;

package/lib/types/context.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Structural view of the harness services this plugin talks to.
+ *
+ * The gate only runs inside the web profile, so the web server and the
+ * connection service are always present. Declaring the two interfaces here
+ * keeps the plugin typed without depending on the host packages at build time.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Minimal surface of the harness web server used by the gate. */
+export interface WebServerView {
+    /** Host the harness listener is bound to, when the host service exposes it. */
+    config?: {
+        host?: unknown;
+    };
+    /** Origin the harness listener is reachable on, for example http://127.0.0.1:3080. */
+    getOrigin(): string;
+    /** Register an index.html transform; the returned function unregisters it. */
+    tapIndex(transform: (html: string) => string): () => void;
+}
+/** Minimal surface of the harness connection service used by the gate. */
+export interface ConnectionView {
+    /** Absolute URL of the entry document with the launch token attached. */
+    authenticatedUrl(baseUrl: string): string;
+}
+/** Profile location reported by the harness loader. */
+export interface ProfileContextView {
+    /** Absolute path of the profile patch file the plugin was loaded from. */
+    patchPath?: string;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        webServer: WebServerView;
+        connection: ConnectionView;
+        profileContext?: ProfileContextView;
+    }
+}
+/** Logger subset used by the gate; lines are written to stderr. */
+export interface LogSink {
+    info(message: string): void;
+    warn(message: string): void;
+}
+/**
+ * Report startup lines on stderr, which is the only channel a headless web
+ * profile leaves visible: the harness routes ctx.logger to its own exporters,
+ * and the web profile installs none of them, so a generated password or a
+ * listen address logged there would never reach the operator.
+ */
+export declare function resolveLogger(ctx: Context): LogSink;

package/lib/types/gate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The gate's HTTP surface: health, login, logout, and the authenticated proxy.
+ *
+ * Unauthenticated API calls get 401 JSON so the UI can react; every other path
+ * is redirected to the login page. Authenticated requests are handed to the
+ * proxy with an exchanged harness cookie.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { LogSink } from './context.ts';
+/** Values the gate needs at request time. */
+export interface GateRuntime {
+    title: string;
+    passwordHash: string;
+    secret: string;
+    pv: string;
+    sessionSeconds: number;
+    maxAttempts: number;
+    maxPendingLoginsPerIp: number;
+    lockMs: number;
+    trustProxy: boolean;
+    useTls: boolean;
+    publicOrigin: string;
+    secureCookie: boolean;
+}
+/** Collaborators the handler delegates to. */
+export interface GateOptions {
+    runtime: GateRuntime;
+    harnessCookie(): Promise<string>;
+    validSession(token: string): boolean;
+    revokeSession(token: string): boolean;
+    forward(req: IncomingMessage, res: ServerResponse, cookie: string): void;
+    log: LogSink;
+}
+/** Build the request handler for one gate instance. */
+export declare function createHandler(options: GateOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/lib/types/http.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Request parsing and response helpers shared by the login page and the proxy.
+ *
+ * Everything here is deliberately small: bounded body reads, one origin check,
+ * one redirect sanitizer and one set of gate headers.
+ */
+import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'node:http';
+/** Largest accepted login form body. */
+export declare const MAX_FORM: number;
+/** Longest time a login body may take to arrive. */
+export declare const FORM_TIMEOUT: number;
+/** Parse an integer option and clamp it into range. */
+export declare const intOr: (value: unknown, fallback: number, min: number, max: number) => number;
+/** Read one cookie value from a Cookie header. */
+export declare function cookieValue(header: string | string[] | undefined, name: string): string;
+/** Client address used for lockout accounting. */
+export declare function clientIp(req: IncomingMessage, trustProxy: boolean): string;
+/** Normalize an explicitly configured, browser-facing HTTP(S) origin. */
+export declare function normalizePublicOrigin(value: string): string;
+/** The configured public authority must match the Host preserved by a proxy. */
+export declare const hostMatchesPublicOrigin: (req: IncomingMessage, publicOrigin: string, useTls: boolean) => boolean;
+/** Require a valid Host, and if present an Origin with identical scheme, host and port. */
+export declare function originMatchesHost(req: IncomingMessage, publicOrigin: string, useTls: boolean): boolean;
+/** Login check: Origin and Fetch-Site must both look same-origin. */
+export declare function sameOrigin(req: IncomingMessage, publicOrigin: string, useTls: boolean): boolean;
+/** Only same-site absolute paths; rejects //evil and backslash tricks. */
+export declare function safeNext(value: unknown): string;
+export declare const escapeHtml: (text: unknown) => string;
+/** Lock the login page and gate responses down to their own origin. */
+export declare const CSP = "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'";
+/** Headers attached to every response the gate writes itself. */
+export declare const GATE_HEADERS: OutgoingHttpHeaders;
+/** Keep cross-origin referrers private without suppressing the login form's Origin. */
+export declare const LOGIN_REFERRER_POLICY = "same-origin";
+/** Write a complete response. */
+export declare function send(res: ServerResponse, status: number, headers: OutgoingHttpHeaders, body: string | Buffer): void;
+export declare const html: (res: ServerResponse, status: number, body: string) => void;
+export declare const json: (res: ServerResponse, status: number, payload: unknown) => void;
+export declare const text: (res: ServerResponse, status: number, body: string, extra?: OutgoingHttpHeaders) => void;
+export declare const redirect: (res: ServerResponse, location: string, status?: number) => void;
+/** Read a bounded, form-encoded login body; never trust content-length alone. */
+export declare function readForm(req: IncomingMessage): Promise<string>;
+export declare const isLoopbackHost: (host: string) => boolean;
+/** Address form accepted by net.connect / tls.connect. */
+export declare const connectHost: (hostname: string) => string;

package/lib/types/index.d.ts

@@ -0,0 +1,25 @@
+import type { AddressInfo } from 'node:net';
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.ts';
+/** Cordis metadata: the plugin id shown in logs and the services it waits for. */
+export declare const name = "dsh-frontgate";
+export declare const inject: string[];
+/** Handle returned to tests and embedders; the loader ignores it. */
+export interface GateHandle {
+    /** Resolves once the gate is listening. */
+    ready(): Promise<void>;
+    /** Bound address of the gate listener. */
+    address(): AddressInfo | string | null;
+    /** Stop the listener and drop pooled upstream sockets. */
+    stop(): void;
+}
+/**
+ * Start the gate.
+ *
+ * The loader validates the configuration against Config before calling this;
+ * defaults are applied again here so direct calls behave the same way.
+ */
+export declare function apply(ctx: Context, config?: Partial<Config>): GateHandle;
+export { Config } from './config.ts';
+export { hashPassword, verifyPassword } from './auth.ts';
+export { injectPolyfill } from './polyfill.ts';

package/lib/types/page.d.ts

@@ -0,0 +1,2 @@
+/** Render the login page for a given title, post-login path and error message. */
+export declare function loginPage(title: string, next: string, error: string): string;

package/lib/types/polyfill.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser-side fallback for a secure-context API.
+ *
+ * The UI is commonly opened over plain http on a LAN address, which is not a
+ * secure context, so crypto.randomUUID is missing there. The transform is
+ * idempotent and only touches the harness index document.
+ */
+/** Insert the polyfill once, before the closing head tag. */
+export declare function injectPolyfill(htmlText: string): string;

package/lib/types/proxy.d.ts

@@ -0,0 +1,30 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { LogSink } from './context.ts';
+/** Options needed to reach and describe the harness listener. */
+export interface ProxyOptions {
+    /** Origin of the harness listener, for example http://127.0.0.1:3080. */
+    targetOrigin: string;
+    /** Protocol the gate serves to browsers. */
+    publicProto: 'http' | 'https';
+    /** Honour forwarded headers from a proxy in front of the gate. */
+    trustProxy: boolean;
+    /** Maximum time spent exchanging a launch token, including connection time. */
+    exchangeTimeoutMs: number;
+    upstreamHeaderTimeoutMs: number;
+    upstreamIdleTimeoutMs: number;
+    upstreamCa?: Buffer;
+    upstreamServerName: string;
+    /** Absolute entry URL with the harness launch token attached. */
+    authenticatedUrl(baseUrl: string): string;
+    log: LogSink;
+}
+/** Proxy surface used by the request and upgrade handlers. */
+export interface Proxy {
+    harnessCookie(): Promise<string>;
+    forward(req: IncomingMessage, res: ServerResponse, cookie: string): void;
+    forwardUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, cookie: string): void;
+    destroy(): void;
+}
+/** Build the proxy for one harness origin. */
+export declare function createProxy(options: ProxyOptions): Proxy;

package/lib/types/sessions.d.ts

@@ -0,0 +1,9 @@
+import type { State } from './state.ts';
+/** Store only a digest, never the bearer token itself. */
+export declare const sessionDigest: (token: string) => string;
+export interface SessionStore {
+    valid(token: string): boolean;
+    /** Persist revocation before reporting logout success. */
+    revoke(token: string): boolean;
+}
+export declare function createSessionStore(path: string, state: State, pv: string, onRevoke: (digest: string) => void): SessionStore;

package/lib/types/state.d.ts

@@ -0,0 +1,23 @@
+/** Bound persistent logout revocations; expired entries are pruned on logout. */
+export declare const MAX_REVOKED_SESSIONS = 10000;
+export interface RevokedSession {
+    digest: string;
+    expires: number;
+}
+/** Persisted state file contents. */
+export interface State {
+    passwordHash?: string;
+    secret?: string;
+    createdAt?: string;
+    revokedSessions?: RevokedSession[];
+}
+/** Read existing state without replacing malformed or inaccessible credentials. */
+export declare function readState(path: string, mustExist?: boolean): State;
+/** Fail closed when a state file is a symlink or cannot be made owner-only. */
+export declare function tightenState(path: string): boolean;
+/** Write a complete owner-only temporary file, then replace the old state. */
+export declare function writeState(path: string, value: State): void;
+/** Resolve the state path for the profile the plugin was loaded from. */
+export declare function statePathFor(patchPath: string | undefined): string;
+/** Reuse the persisted salt while the same password keeps being configured. */
+export declare function hashFor(plain: string, state: State): string;

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@lornatang/dsh-frontgate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Password protection and reverse proxy for the DeepSeek Harness Web UI.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": ">=22.19",
+    "dsh": ">=0.2.2-rc.1"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "prepack": "npm run build && node --test tests/*.test.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.1.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.19.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.1.0",
+    "@types/node": "^22.18.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.9.0"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "password",
+    "auth",
+    "login",
+    "reverse-proxy",
+    "websocket",
+    "self-hosted"
+  ],
+  "license": "Apache-2.0",
+  "author": "Lornatang",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lornatang/dsh-frontgate.git"
+  },
+  "homepage": "https://github.com/Lornatang/dsh-frontgate#readme",
+  "bugs": {
+    "url": "https://github.com/Lornatang/dsh-frontgate/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}