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

package/lib/types/host/services/remote-web-ui/server-mode/external-auth.js

@@ -0,0 +1,242 @@
+/** External identity providers for integrated DSH WebAuth. */
+import { createHash, randomBytes } from 'node:crypto';
+import { createLocalJWKSet, jwtVerify } from 'jose';
+function base64url(buffer) {
+    return buffer.toString('base64url');
+}
+function form(body) {
+    const value = new URLSearchParams();
+    for (const [key, item] of Object.entries(body))
+        value.set(key, item);
+    return value;
+}
+function normalizeIssuer(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' && url.hostname !== 'localhost' && !url.hostname.startsWith('127.')) {
+        throw new Error('external auth issuer must use https');
+    }
+    url.hash = '';
+    url.search = '';
+    return url.href.replace(/\/$/, '');
+}
+function domainAllowed(email, allowed) {
+    if (allowed === undefined || allowed.length === 0)
+        return true;
+    if (email === undefined)
+        return false;
+    const at = email.lastIndexOf('@');
+    if (at < 0)
+        return false;
+    const domain = email.slice(at + 1).toLowerCase();
+    return allowed.some(candidate => candidate.toLowerCase() === domain);
+}
+function subjectAllowed(subject, allowed) {
+    return allowed === undefined || allowed.length === 0 || allowed.includes(subject);
+}
+async function jsonResponse(response, label) {
+    if (!response.ok)
+        throw new Error(`${label} failed with HTTP ${String(response.status)}`);
+    const value = await response.json();
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${label} returned malformed JSON`);
+    return value;
+}
+/** Short-lived, one-time authorization state plus provider protocol adapters. */
+export class ExternalAuthService {
+    pending = new Map();
+    discoveries = new Map();
+    oidc = new Map();
+    feishu = new Map();
+    now;
+    random;
+    fetchImpl;
+    maxPendingMs;
+    constructor(config, deps = {}) {
+        this.now = deps.now ?? (() => Date.now());
+        this.random = deps.randomBytes ?? randomBytes;
+        this.fetchImpl = deps.fetch ?? globalThis.fetch;
+        this.maxPendingMs = deps.maxPendingMs ?? 10 * 60 * 1000;
+        for (const provider of config.oidc ?? []) {
+            if (!/^[a-z][a-z0-9-]{1,31}$/.test(provider.id))
+                throw new Error(`invalid OIDC provider id: ${provider.id}`);
+            this.oidc.set(provider.id, { ...provider, issuer: normalizeIssuer(provider.issuer) });
+        }
+        if (config.feishu !== undefined && config.feishu.appId !== '' && config.feishu.appSecret !== '') {
+            const id = config.feishu.id ?? 'feishu';
+            if (!/^[a-z][a-z0-9-]{1,31}$/.test(id))
+                throw new Error(`invalid Feishu provider id: ${id}`);
+            this.feishu.set(id, { ...config.feishu, id });
+        }
+    }
+    list() {
+        return [
+            ...[...this.oidc.values()].map(provider => ({ id: provider.id, label: provider.label ?? provider.id, type: 'oidc' })),
+            ...[...this.feishu.entries()].map(([id, provider]) => ({ id, label: provider.label ?? '飞书', type: 'feishu' })),
+        ];
+    }
+    newPending(providerId, redirectUri, next) {
+        this.sweep();
+        const state = base64url(this.random(32));
+        const record = {
+            providerId,
+            state,
+            nonce: base64url(this.random(32)),
+            verifier: base64url(this.random(48)),
+            redirectUri,
+            next,
+            createdAt: this.now(),
+        };
+        this.pending.set(state, record);
+        return record;
+    }
+    take(state, providerId, redirectUri) {
+        const record = this.pending.get(state);
+        this.pending.delete(state);
+        if (record === undefined || record.providerId !== providerId || record.redirectUri !== redirectUri)
+            throw new Error('authorization state is invalid');
+        if (this.now() - record.createdAt > this.maxPendingMs)
+            throw new Error('authorization state expired');
+        return record;
+    }
+    sweep() {
+        const cutoff = this.now() - this.maxPendingMs;
+        for (const [state, record] of this.pending)
+            if (record.createdAt < cutoff)
+                this.pending.delete(state);
+    }
+    async discovery(provider) {
+        let current = this.discoveries.get(provider.id);
+        if (current !== undefined)
+            return current;
+        current = (async () => {
+            const response = await this.fetchImpl(`${provider.issuer}/.well-known/openid-configuration`, { headers: { accept: 'application/json' } });
+            const value = await jsonResponse(response, 'OIDC discovery');
+            const result = {
+                issuer: String(value.issuer ?? ''),
+                authorization_endpoint: String(value.authorization_endpoint ?? ''),
+                token_endpoint: String(value.token_endpoint ?? ''),
+                jwks_uri: String(value.jwks_uri ?? ''),
+            };
+            if (normalizeIssuer(result.issuer) !== provider.issuer)
+                throw new Error('OIDC discovery issuer mismatch');
+            for (const endpoint of [result.authorization_endpoint, result.token_endpoint, result.jwks_uri]) {
+                if (new URL(endpoint).protocol !== 'https:' && !endpoint.startsWith('http://127.') && !endpoint.startsWith('http://localhost'))
+                    throw new Error('OIDC endpoint must use https');
+            }
+            return result;
+        })();
+        this.discoveries.set(provider.id, current);
+        try {
+            return await current;
+        }
+        catch (error) {
+            this.discoveries.delete(provider.id);
+            throw error;
+        }
+    }
+    async begin(providerId, redirectUri, next) {
+        const oidc = this.oidc.get(providerId);
+        if (oidc !== undefined) {
+            const record = this.newPending(providerId, redirectUri, next);
+            const discovery = await this.discovery(oidc);
+            const url = new URL(discovery.authorization_endpoint);
+            url.searchParams.set('response_type', 'code');
+            url.searchParams.set('client_id', oidc.clientId);
+            url.searchParams.set('redirect_uri', redirectUri);
+            url.searchParams.set('scope', (oidc.scopes ?? ['openid', 'profile', 'email']).join(' '));
+            url.searchParams.set('state', record.state);
+            url.searchParams.set('nonce', record.nonce);
+            url.searchParams.set('code_challenge_method', 'S256');
+            url.searchParams.set('code_challenge', createHash('sha256').update(record.verifier).digest('base64url'));
+            return url;
+        }
+        const feishu = this.feishu.get(providerId);
+        if (feishu !== undefined) {
+            const record = this.newPending(providerId, redirectUri, next);
+            const url = new URL(feishu.authorizationUrl ?? 'https://accounts.feishu.cn/open-apis/authen/v1/authorize');
+            url.searchParams.set('client_id', feishu.appId);
+            url.searchParams.set('redirect_uri', redirectUri);
+            url.searchParams.set('state', record.state);
+            url.searchParams.set('scope', 'auth:user.id:read');
+            return url;
+        }
+        throw new Error('unknown authentication provider');
+    }
+    async callback(providerId, redirectUri, code, state) {
+        const record = this.take(state, providerId, redirectUri);
+        const oidc = this.oidc.get(providerId);
+        if (oidc !== undefined)
+            return { principal: await this.finishOidc(oidc, record, code), next: record.next };
+        const feishu = this.feishu.get(providerId);
+        if (feishu !== undefined)
+            return { principal: await this.finishFeishu(providerId, feishu, record, code), next: record.next };
+        throw new Error('unknown authentication provider');
+    }
+    async finishOidc(provider, record, code) {
+        const discovery = await this.discovery(provider);
+        const response = await this.fetchImpl(discovery.token_endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+            body: form({ grant_type: 'authorization_code', client_id: provider.clientId, client_secret: provider.clientSecret, code, redirect_uri: record.redirectUri, code_verifier: record.verifier }),
+        });
+        const token = await jsonResponse(response, 'OIDC token exchange');
+        const idToken = typeof token.id_token === 'string' ? token.id_token : undefined;
+        if (idToken === undefined)
+            throw new Error('OIDC token response has no id_token');
+        const jwksValue = await jsonResponse(await this.fetchImpl(discovery.jwks_uri, { headers: { accept: 'application/json' } }), 'OIDC JWKS');
+        if (!Array.isArray(jwksValue.keys))
+            throw new Error('OIDC JWKS has no keys array');
+        const jwks = createLocalJWKSet(jwksValue);
+        const verified = await jwtVerify(idToken, jwks, { issuer: discovery.issuer, audience: provider.clientId });
+        if (verified.payload.nonce !== record.nonce)
+            throw new Error('OIDC nonce mismatch');
+        if (Array.isArray(verified.payload.aud) && verified.payload.aud.length > 1 && verified.payload.azp !== provider.clientId) {
+            throw new Error('OIDC azp mismatch');
+        }
+        return this.oidcPrincipal(provider, verified.payload);
+    }
+    oidcPrincipal(provider, payload) {
+        const subject = payload.sub;
+        if (typeof subject !== 'string' || !subjectAllowed(subject, provider.allowedSubjects))
+            throw new Error('OIDC subject is not allowed');
+        const email = typeof payload.email === 'string' ? payload.email : undefined;
+        if (!domainAllowed(email, provider.allowedEmailDomains))
+            throw new Error('OIDC email domain is not allowed');
+        return {
+            providerId: provider.id,
+            subject,
+            issuer: provider.issuer,
+            ...(typeof payload.name === 'string' ? { displayName: payload.name } : {}),
+            ...(email !== undefined ? { email } : {}),
+            role: provider.defaultRole ?? 'user',
+        };
+    }
+    async finishFeishu(providerId, provider, record, code) {
+        const api = (provider.baseUrl ?? 'https://open.feishu.cn').replace(/\/$/, '');
+        const token = await jsonResponse(await this.fetchImpl(`${api}/open-apis/authen/v2/oauth/token`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json; charset=utf-8', accept: 'application/json' },
+            body: JSON.stringify({ grant_type: 'authorization_code', client_id: provider.appId, client_secret: provider.appSecret, code, redirect_uri: record.redirectUri, code_verifier: record.verifier }),
+        }), 'Feishu token exchange');
+        const accessToken = typeof token.access_token === 'string' ? token.access_token : undefined;
+        if (accessToken === undefined)
+            throw new Error('Feishu token response has no access_token');
+        const info = await jsonResponse(await this.fetchImpl(`${api}/open-apis/authen/v1/user_info`, { headers: { authorization: `Bearer ${accessToken}`, accept: 'application/json' } }), 'Feishu user info');
+        const data = info.data !== null && typeof info.data === 'object' ? info.data : info;
+        const subject = typeof data.union_id === 'string' && data.union_id !== '' ? data.union_id : typeof data.open_id === 'string' ? data.open_id : undefined;
+        if (subject === undefined || !subjectAllowed(subject, provider.allowedOpenIds))
+            throw new Error('Feishu subject is not allowed');
+        return {
+            providerId,
+            subject,
+            ...(typeof data.tenant_key === 'string' ? { tenant: data.tenant_key } : {}),
+            ...(typeof data.name === 'string' ? { displayName: data.name } : {}),
+            ...(typeof data.email === 'string' ? { email: data.email } : {}),
+            role: provider.defaultRole ?? 'user',
+        };
+    }
+}
+/** External identities are namespaced local account keys, never display names. */
+export function externalAccountName(principal) {
+    return `${principal.providerId}:${principal.issuer ?? principal.tenant ?? 'default'}:${principal.subject}`;
+}

package/lib/types/host/services/remote-web-ui/server-mode/fence.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Loopback fence for the server-mode plugin surfaces.
+ *
+ * The loopback webServer keeps privileged routes local-only - the public
+ * gateway listener is the only door for remote clients - and this predicate
+ * guards the admin account surface.
+ *
+ * It used to test the socket and the Host header alone. A web page satisfies
+ * both by itself: a cross-site simple request (no preflight) to
+ * `http://127.0.0.1:<port>` arrives on a loopback socket with a loopback Host,
+ * so any page a browser can be made to fetch could reach account management and
+ * create an admin. The rule therefore comes from the shared fence, which the
+ * deployment contract requires on every privileged surface: loopback socket,
+ * loopback Host, AND same-origin markers (see docs/remote-access.md, invariant
+ * 2, and access-trust/trust.ts).
+ */
+import type { IncomingMessage } from 'node:http';
+/**
+ * Whether a request may use the loopback admin surface (account management).
+ * Marker-aware on purpose: see the module comment.
+ */
+export declare function isLoopbackAdmin(request: IncomingMessage): boolean;
+//# sourceMappingURL=fence.d.ts.map

package/lib/types/host/services/remote-web-ui/server-mode/fence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fence.d.ts","sourceRoot":"","sources":["../../../../../../src/host/services/remote-web-ui/server-mode/fence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAGhD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAEjE"}

package/lib/types/host/services/remote-web-ui/server-mode/fence.js

@@ -0,0 +1,24 @@
+/**
+ * Loopback fence for the server-mode plugin surfaces.
+ *
+ * The loopback webServer keeps privileged routes local-only - the public
+ * gateway listener is the only door for remote clients - and this predicate
+ * guards the admin account surface.
+ *
+ * It used to test the socket and the Host header alone. A web page satisfies
+ * both by itself: a cross-site simple request (no preflight) to
+ * `http://127.0.0.1:<port>` arrives on a loopback socket with a loopback Host,
+ * so any page a browser can be made to fetch could reach account management and
+ * create an admin. The rule therefore comes from the shared fence, which the
+ * deployment contract requires on every privileged surface: loopback socket,
+ * loopback Host, AND same-origin markers (see docs/remote-access.md, invariant
+ * 2, and access-trust/trust.ts).
+ */
+import { isLoopbackRequest } from "../../access-trust/trust.js";
+/**
+ * Whether a request may use the loopback admin surface (account management).
+ * Marker-aware on purpose: see the module comment.
+ */
+export function isLoopbackAdmin(request) {
+    return isLoopbackRequest(request);
+}

package/lib/types/host/services/remote-web-ui/server-mode/gateway-routes.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Gateway HTTP surface: the login page, the pre-auth session/config/login
+ * endpoints, and the admin surface (accounts + sessions) — the endpoints
+ * the public listener and the loopback webServer both serve under
+ * `/api/gateway`. Login is rate-limited per (IP + username) with a generic
+ * failure message that never reveals whether a username exists.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type AccountRole, type AccountStore } from './accounts.ts';
+import type { SessionStore } from './sessions.ts';
+import { GATEWAY_API_PREFIX } from './roles.ts';
+export { GATEWAY_API_PREFIX };
+/** Pre-auth gateway paths any webServer front (nginx, trusted-host) must serve. */
+export declare function isPreAuthGatewayPath(method: string, pathname: string): boolean;
+/** Trust context of one /api/gateway invocation. */
+export type GatewayTrust = 'loopback' | 'session';
+/** The gateway's public pre-auth status. */
+export interface GatewayStatus {
+    loginRequired: boolean;
+    cookieName: string;
+    tls: boolean;
+    /** Whether the account store is empty (first-run bootstrap needed). */
+    noAccounts: boolean;
+    /** Listen host/port the admin surface shows as the access entry. */
+    host?: string;
+    port?: number;
+    /** Whether the listener serves HTTPS. */
+    secure?: boolean;
+    /** The live session of the requesting browser, when signed in. */
+    session?: {
+        username: string;
+        role: AccountRole;
+        lastSeenAt: number;
+    };
+}
+/**
+ * In-memory login limiter: a sliding failure window per (IP + username)
+ * plus a hard lockout after repeated failures.
+ */
+export declare class LoginLimiter {
+    private readonly failures;
+    private readonly lockouts;
+    private readonly options;
+    private readonly windowMs;
+    private readonly maxFailsPerWindow;
+    private readonly maxFailsBeforeLockout;
+    private readonly lockoutMs;
+    constructor(options?: {
+        windowMs?: number;
+        maxFailsPerWindow?: number;
+        maxFailsBeforeLockout?: number;
+        lockoutMs?: number;
+    });
+    private now;
+    /** Whether a login attempt from this key may proceed. */
+    check(key: string): {
+        allowed: boolean;
+        retryAfterMs?: number;
+    };
+    /** Record one failed attempt. */
+    recordFailure(key: string): void;
+    /** Record a successful login (reset the window for this key). */
+    recordSuccess(key: string): void;
+}
+/** All handler dependencies. */
+export interface GatewayRoutesDeps {
+    accounts: AccountStore;
+    sessions: SessionStore;
+    cookieName: string;
+    secure: boolean;
+    limiter: LoginLimiter;
+    /** Status payload the /api/gateway/session + config endpoints report. */
+    status: GatewayStatus;
+    /**
+     * Called after any successful account mutation (create / password / role /
+     * enabled / delete). The caller re-evaluates the fail-closed gateway state
+     * from it — creating the first admin must open the door.
+     */
+    onAccountsChanged?: () => void;
+}
+/**
+ * Handle one request under the gateway surface.
+ * @param trust - 'loopback' (webServer side; caller is already loopback) or
+ *   'session' (public listener; admin endpoints need an admin session).
+ * @param deps - accounts/sessions/cookie/limiter/status.
+ * @returns the handler.
+ */
+export declare function makeGatewayRequestHandler(trust: GatewayTrust, deps: GatewayRoutesDeps): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+//# sourceMappingURL=gateway-routes.d.ts.map

package/lib/types/host/services/remote-web-ui/server-mode/gateway-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-routes.d.ts","sourceRoot":"","sources":["../../../../../../src/host/services/remote-web-ui/server-mode/gateway-routes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAIhE,OAAO,EAAwB,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAA;AACzF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAE/C,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAE7B,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAO9E;AAKD,oDAAoD;AACpD,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,SAAS,CAAA;AAEjD,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,OAAO,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,GAAG,EAAE,OAAO,CAAA;IACZ,uEAAuE;IACvE,UAAU,EAAE,OAAO,CAAA;IACnB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yCAAyC;IACzC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kEAAkE;IAClE,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,WAAW,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;CACtE;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwD;IACjF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAKvB;IACD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;gBAEtB,OAAO,GAAE;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;QAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAA;QAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;KACd;IAQN,OAAO,CAAC,GAAG;IAIX,yDAAyD;IACzD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAc/D,iCAAiC;IACjC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAchC,iEAAiE;IACjE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGjC;AAED,gCAAgC;AAChC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,YAAY,CAAA;IACtB,QAAQ,EAAE,YAAY,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,OAAO,CAAA;IACf,OAAO,EAAE,YAAY,CAAA;IACrB,yEAAyE;IACzE,MAAM,EAAE,aAAa,CAAA;IACrB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAA;CAC/B;AAkZD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,iBAAiB,SAuCpC,eAAe,OAAO,cAAc,KAAG,OAAO,CAAC,IAAI,CAAC,CAmNrG"}