@qpjoy/mx-launcher-embed-sdk 0.2.0

package/README.md

@@ -0,0 +1,176 @@
+# @qpjoy/mx-launcher-embed-sdk
+
+`launcher-embed-sdk` is the role SDK for applications hosted by a standalone
+launcher. Embed apps are consumers. They do not own local networking, users,
+permissions, release policy, downloads, or rollout decisions.
+
+## Allowed Responsibilities
+
+Embed SDK may:
+
+- discover a running standalone broker.
+- connect and handshake with the broker.
+- request scoped capabilities.
+- subscribe to broker events.
+- request app install, launch, update check, or update apply when granted.
+- expose a safe preload bridge to renderer code.
+- read signed local binding cache only to find the required standalone channel.
+
+Embed SDK must not:
+
+- apply WireGuard.
+- write DNS, PAC, system proxy, or resolver state.
+- allocate or claim a ProductNetwork IP.
+- store long-lived Internal tokens.
+- make independent rollout decisions.
+- install or update itself without broker approval.
+
+## Bootstrap
+
+Embed app startup:
+
+1. Read the embed manifest.
+2. If launched by a standalone broker, trust the launch envelope after signature
+   and nonce validation.
+3. Otherwise read signed local binding cache to find
+   `standaloneChannelProductId`.
+4. Find a compatible running broker in the channel registry.
+5. Handshake and request capabilities.
+6. If no broker is available, return a typed state such as
+   `standalone-required`, with enough metadata for UI to prompt the user to open
+   MX-H2I or the configured standalone.
+
+Embed should not directly fetch privileged server policy before broker
+connection. The broker refreshes Internal policy and returns scoped results.
+
+## Minimal API Shape
+
+Future implementation should keep the public API small:
+
+```ts
+import { createEmbedLauncher } from '@qpjoy/mx-launcher-embed-sdk';
+
+const launcher = createEmbedLauncher({
+  productId: 'h2o',
+  standaloneChannelProductId: 'mx-h2i',
+  requiredCapabilities: ['user.session', 'network.proxy', 'network.status']
+});
+
+const connection = await launcher.connect();
+if (!connection.ok) {
+  console.warn(connection.state, connection.message);
+}
+
+launcher.on('auth.changed', (event) => {});
+launcher.on('release.available', (event) => {});
+
+await launcher.request('network.proxy', {
+  url: '/internal/v1/h2o/tasks'
+});
+```
+
+Renderer APIs should be exposed through preload with explicit allowlists. Do not
+expose a raw IPC or transport object to untrusted renderer code.
+
+## Runtime Contract v0.1
+
+The shared core package exposes `createLauncherEmbedManifest()` and
+`launcherEmbedRuntimeContractVersion`. AppCenter records, admin records, and
+embed apps should use this shape for the first product-grade contract:
+
+- `runtimeContractVersion`: `0.1`
+- `launcherMode`: `embed`
+- `network.scope`: `broker-session`
+- `embed.standaloneChannelProductId`: the owning standalone channel, for
+  example `mx-h2i`
+- `requiredCapabilities`: the broker-scoped API surface the app needs
+
+The first event vocabulary is intentionally small:
+
+- `embed.init`, `embed.ready`, `embed.error`, `embed.logs`
+- `auth.changed`, `network.changed`, `permission.changed`
+- `app.open`, `app.close`
+
+The first request vocabulary is also broker-owned:
+
+- `user.session`
+- `network.status`
+- `network.proxy`
+- `network.dns.policy`
+- `network.pac.policy`
+- `app.open`, `app.close`, `app.logs`, `app.update.check`
+
+An embed app receives state through the broker session or through a preload
+bridge owned by its Electron main process. It should not read WireGuard keys,
+touch routes, apply PAC, or write DNS directly.
+
+The high-level embed API is broker-session based. The package still exposes a
+`legacyNetwork` object for migration tests that need to call the old
+Internal lease APIs explicitly, but production embed apps should not allocate a
+runtime lease or apply WireGuard through that path.
+
+## State Model
+
+Use explicit states instead of a single `connected` boolean:
+
+```txt
+idle
+discovering-broker
+standalone-required
+broker-incompatible
+capability-denied
+connected
+network-ready
+blocked
+disconnected
+```
+
+`connected` means the broker handshake succeeded. It does not mean every
+capability is ready. For example, an embed app may be connected while
+`network.proxy` is blocked by policy or by standalone data-plane repair.
+
+## AppCenter And H2O
+
+AppCenter is an embed app with elevated capabilities such as `catalog.read`,
+`app.install`, `app.launch`, and `app.update.manage`. It still depends on the
+MX-H2I standalone broker for execution.
+
+H2O is **Home To Oversea**, an AppCenter built-in embed network plugin. It is a
+Clash-like user surface for proxy mode, PAC, Split DNS, and Internal/oversea
+status, but it should still use the same broker-session contract as other
+AppCenter applications. H2O should only request the capabilities it needs and
+should not know whether MX-H2I uses WireGuard, PAC, system proxy, or another
+future data-plane implementation.
+
+## Release Behavior
+
+Embed apps are distributed as signed bundles. The embed SDK can ask for update
+status, but installation and rollback are broker-owned:
+
+```txt
+embed app -> app.update.check -> standalone broker -> release policy -> OSS/CDN
+standalone broker -> verify signature/hash -> install cache -> launch envelope
+```
+
+The SDK npm version is not the user-facing app version. Embed manifests should
+record both:
+
+- `sdkVersion`: build-time SDK package version.
+- `appVersion`: user-facing embed application version.
+
+## K8s Admin Expectations
+
+K8s admin should show, for every embed app:
+
+- configured standalone channel.
+- required capabilities.
+- granted capabilities.
+- broker compatibility.
+- active install version.
+- latest eligible release.
+- rollout decision.
+- last launch error.
+- audit history.
+
+Admin operations should target the standalone broker, not the embed process, for
+privileged work such as install, update, rollback, and cache refresh.

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import { routePlanFromSnapshot, shouldRefreshNetwork, type AnonymousEnrollment, type AnonymousEnrollmentRequest, type LauncherBrokerCapabilitySession, type LauncherBrokerHandshakeDeniedReason, type LauncherCapability, type LauncherChannelRecord, type LauncherClient, type LauncherClientOptions, type LauncherEmbedConnectionState, type LauncherManifest, type LauncherNetworkLease, type LauncherNetworkLeaseInput, type LauncherNetworkSession, type LauncherNetworkSnapshot, type LauncherNetworkSnapshotInput, type LauncherProductNetwork, type LauncherRoutePlan, type LauncherWireGuardKeyPair, type LauncherWireGuardKeyProvider } from '@qpjoy/mx-launcher-core';
+export interface EmbedLauncherOptions extends LauncherClientOptions {
+    productId?: string;
+    appId?: string;
+    standaloneChannelProductId?: string;
+    requiredCapabilities?: LauncherCapability[];
+    sdkVersion?: string;
+    appVersion?: string;
+    displayName?: string;
+    description?: string;
+    packageName?: string;
+    category?: string;
+    protocolVersion?: string;
+    minBrokerAbiVersion?: string;
+    runtimeContractVersion?: string;
+    launchWithoutBroker?: 'blocked' | 'prompt-open-standalone';
+    channelRegistry?: LauncherChannelRegistrySource;
+    maxChannelHeartbeatAgeMs?: number;
+    requestImpl?: EmbedBrokerRequestHandler;
+    installId?: string;
+    deviceId?: string;
+    siteId?: string;
+    publicKey?: string;
+    privateKey?: string;
+    keyPair?: LauncherWireGuardKeyPair;
+    keyProvider?: LauncherWireGuardKeyProvider;
+    deviceLabel?: string;
+}
+export interface EmbedSnapshotOptions extends Omit<LauncherNetworkSnapshotInput, 'appId' | 'launcherMode' | 'installId' | 'deviceId' | 'siteId' | 'publicKey'> {
+    installId?: string;
+    deviceId?: string;
+    siteId?: string | null;
+    publicKey?: string | null;
+}
+export interface EmbedLeaseOptions extends Omit<LauncherNetworkLeaseInput, 'productId' | 'mode' | 'installId' | 'deviceId' | 'siteId' | 'publicKey'> {
+    installId?: string;
+    deviceId?: string;
+    siteId?: string | null;
+    publicKey?: string | null;
+}
+export interface EmbedNetworkSessionOptions extends EmbedLeaseOptions {
+    privateKey?: string | null;
+    keyPair?: LauncherWireGuardKeyPair | null;
+    keyProvider?: LauncherWireGuardKeyProvider | null;
+    snapshotRequestId?: string | null;
+}
+export type LauncherChannelRegistrySource = LauncherChannelRecord[] | (() => LauncherChannelRecord[] | Promise<LauncherChannelRecord[]>);
+export type EmbedBrokerRequestHandler = (session: LauncherBrokerCapabilitySession, requestName: string, payload?: unknown) => unknown | Promise<unknown>;
+export interface EmbedConnectOptions extends Omit<AnonymousEnrollmentRequest, 'productId' | 'platform' | 'installId' | 'deviceId' | 'siteId' | 'publicKey'> {
+    installId?: string;
+    deviceId?: string;
+    siteId?: string;
+    publicKey?: string;
+    platform?: string;
+}
+export interface EmbedConnectionResult {
+    enrollment: AnonymousEnrollment;
+    snapshot: LauncherNetworkSnapshot;
+    routePlan: LauncherRoutePlan;
+}
+export interface EmbedBrokerConnectOptions {
+    requestedCapabilities?: LauncherCapability[];
+    channelRegistry?: LauncherChannelRegistrySource;
+    installId?: string | null;
+    deviceId?: string | null;
+    userId?: string | null;
+    requestId?: string | null;
+}
+export interface EmbedLauncherConnection {
+    ok: boolean;
+    state: LauncherEmbedConnectionState;
+    session: LauncherBrokerCapabilitySession | null;
+    reason: LauncherBrokerHandshakeDeniedReason | null;
+    message: string;
+    channel: LauncherChannelRecord | null;
+    missingCapabilities: LauncherCapability[];
+}
+export type EmbedLauncherEventName = 'broker.connected' | 'broker.disconnected' | 'auth.changed' | 'capability.changed' | 'network.ready' | 'network.blocked' | 'release.available' | 'app.install.progress' | 'app.updated';
+export type EmbedLauncherEventHandler = (event: {
+    name: EmbedLauncherEventName;
+    state: LauncherEmbedConnectionState;
+    session: LauncherBrokerCapabilitySession | null;
+    payload?: unknown;
+}) => void;
+export interface EmbedLegacyNetworkApi {
+    getProduct(): Promise<LauncherProductNetwork>;
+    enrollLease(options?: EmbedLeaseOptions): Promise<LauncherNetworkLease>;
+    connectNetwork(options?: EmbedNetworkSessionOptions): Promise<LauncherNetworkSession>;
+    createSnapshot(options?: EmbedSnapshotOptions): Promise<LauncherNetworkSnapshot>;
+    createRoutePlan(options?: EmbedSnapshotOptions): Promise<LauncherRoutePlan>;
+    connectAnonymous(options?: EmbedConnectOptions): Promise<EmbedConnectionResult>;
+}
+export interface EmbedLauncher {
+    readonly mode: 'embed';
+    readonly productId: string;
+    readonly appId: string;
+    readonly standaloneChannelProductId: string;
+    readonly requiredCapabilities: LauncherCapability[];
+    readonly manifest: LauncherManifest;
+    readonly client: LauncherClient;
+    readonly legacyNetwork: EmbedLegacyNetworkApi;
+    connect(options?: EmbedBrokerConnectOptions): Promise<EmbedLauncherConnection>;
+    request<T = unknown>(requestName: string, payload?: unknown): Promise<T>;
+    on(eventName: EmbedLauncherEventName, handler: EmbedLauncherEventHandler): () => void;
+    off(eventName: EmbedLauncherEventName, handler: EmbedLauncherEventHandler): void;
+    shouldRefreshNetwork: typeof shouldRefreshNetwork;
+}
+export declare function createEmbedLauncher(options: EmbedLauncherOptions): EmbedLauncher;
+export { routePlanFromSnapshot, shouldRefreshNetwork };

package/dist/index.js

@@ -0,0 +1,284 @@
+import { brokerAbiVersion, createLauncherEmbedManifest, createLauncherClient, createLauncherNetworkSession, launcherEmbedRuntimeContractVersion, launcherBrokerCompatibility, launcherProtocolVersion, routePlanFromSnapshot, shouldRefreshNetwork } from '@qpjoy/mx-launcher-core';
+export function createEmbedLauncher(options) {
+    const productId = requiredProductId(options.productId ?? options.appId);
+    const appId = requiredProductId(options.appId ?? options.productId);
+    const standaloneChannelProductId = normalizeProductId(options.standaloneChannelProductId ?? 'mx-h2i');
+    const requiredCapabilities = uniqueCapabilities(options.requiredCapabilities ?? ['user.session']);
+    const client = createLauncherClient(options);
+    const manifest = createLauncherEmbedManifest({
+        appId,
+        productId,
+        displayName: options.displayName,
+        description: options.description,
+        packageName: options.packageName,
+        category: options.category,
+        sdkVersion: options.sdkVersion,
+        appVersion: options.appVersion,
+        protocolVersion: options.protocolVersion,
+        sdkAbiVersion: options.minBrokerAbiVersion ?? brokerAbiVersion,
+        runtimeContractVersion: options.runtimeContractVersion ?? launcherEmbedRuntimeContractVersion,
+        standaloneChannelProductId,
+        launchWithoutBroker: options.launchWithoutBroker,
+        requiredCapabilities
+    });
+    const handlers = new Map();
+    let currentState = 'idle';
+    let currentSession = null;
+    async function createSnapshot(input = {}) {
+        return client.createSnapshot({
+            ...input,
+            appId: productId,
+            launcherMode: 'embed',
+            installId: input.installId ?? options.installId,
+            deviceId: input.deviceId ?? options.deviceId,
+            siteId: input.siteId ?? options.siteId,
+            publicKey: input.publicKey ?? options.publicKey
+        });
+    }
+    async function enrollLease(input = {}) {
+        return client.enrollLease({
+            ...input,
+            appId: input.appId ?? productId,
+            productId,
+            mode: 'embed',
+            installId: input.installId ?? options.installId,
+            deviceId: input.deviceId ?? options.deviceId,
+            siteId: input.siteId ?? options.siteId,
+            publicKey: input.publicKey ?? options.publicKey,
+            deviceLabel: input.deviceLabel ?? options.deviceLabel,
+            requestedBy: input.requestedBy ?? 'embed-sdk'
+        });
+    }
+    async function connectNetwork(input = {}) {
+        return createLauncherNetworkSession(client, {
+            ...input,
+            productId,
+            appId: productId,
+            mode: 'embed',
+            launcherMode: 'embed',
+            installId: input.installId ?? options.installId,
+            deviceId: input.deviceId ?? options.deviceId,
+            siteId: input.siteId ?? options.siteId,
+            publicKey: input.publicKey ?? options.publicKey,
+            privateKey: input.privateKey ?? options.privateKey,
+            keyPair: input.keyPair ?? options.keyPair,
+            keyProvider: input.keyProvider ?? options.keyProvider,
+            deviceLabel: input.deviceLabel ?? options.deviceLabel,
+            requestedBy: input.requestedBy ?? 'embed-sdk'
+        });
+    }
+    function setState(state, eventName, payload) {
+        currentState = state;
+        emit(eventName, payload);
+    }
+    function emit(name, payload) {
+        const event = { name, state: currentState, session: currentSession, payload };
+        for (const handler of handlers.get(name) ?? [])
+            handler(event);
+    }
+    const legacyNetwork = {
+        getProduct() {
+            return client.getProduct(productId);
+        },
+        enrollLease,
+        connectNetwork,
+        createSnapshot,
+        async createRoutePlan(input) {
+            return routePlanFromSnapshot(await createSnapshot(input));
+        },
+        async connectAnonymous(input = {}) {
+            const enrollment = await client.enrollAnonymous({
+                ...input,
+                productId,
+                platform: input.platform ?? 'embed',
+                installId: input.installId ?? options.installId,
+                deviceId: input.deviceId ?? options.deviceId,
+                siteId: input.siteId ?? options.siteId,
+                publicKey: input.publicKey ?? options.publicKey,
+                deviceLabel: input.deviceLabel ?? options.deviceLabel,
+                relayMode: input.relayMode ?? 'h2i'
+            });
+            const snapshot = await createSnapshot({
+                installId: enrollment.installId,
+                deviceId: enrollment.deviceId,
+                siteId: enrollment.siteId,
+                publicKey: enrollment.publicKey ?? input.publicKey ?? options.publicKey,
+                requestId: input.requestId
+            });
+            return {
+                enrollment,
+                snapshot,
+                routePlan: routePlanFromSnapshot(snapshot)
+            };
+        }
+    };
+    const launcher = {
+        mode: 'embed',
+        productId,
+        appId,
+        standaloneChannelProductId,
+        requiredCapabilities,
+        manifest,
+        client,
+        legacyNetwork,
+        async connect(input = {}) {
+            setState('discovering-broker', 'broker.disconnected');
+            const requestedCapabilities = uniqueCapabilities(input.requestedCapabilities ?? requiredCapabilities);
+            const registry = await resolveChannelRegistry(input.channelRegistry ?? options.channelRegistry);
+            const channel = registry.find((record) => normalizeProductId(record.productId) === standaloneChannelProductId && channelIsFresh(record, options.maxChannelHeartbeatAgeMs)) ?? null;
+            if (!channel) {
+                currentSession = null;
+                setState('standalone-required', 'network.blocked', { standaloneChannelProductId });
+                return deniedConnection('standalone-required', `Open ${standaloneChannelProductId} before launching ${appId}.`, null, []);
+            }
+            const request = buildHandshakeRequest({
+                appId,
+                productId,
+                standaloneChannelProductId,
+                requestedCapabilities,
+                options,
+                input
+            });
+            const compatibility = launcherBrokerCompatibility({
+                embedProtocolVersion: request.protocolVersion,
+                brokerProtocolVersion: channel.protocolVersion,
+                minBrokerAbiVersion: request.minBrokerAbiVersion,
+                brokerAbiVersion: channel.brokerAbiVersion
+            });
+            if (!compatibility.compatible) {
+                currentSession = null;
+                setState('broker-incompatible', 'network.blocked', compatibility);
+                return deniedConnection('broker-incompatible', compatibility.message, channel, []);
+            }
+            const missingCapabilities = requestedCapabilities.filter((capability) => !channel.capabilities.includes(capability));
+            if (missingCapabilities.length) {
+                currentSession = null;
+                setState('capability-denied', 'capability.changed', { missingCapabilities });
+                return deniedConnection('capability-denied', `Broker channel ${channel.productId} does not grant: ${missingCapabilities.join(', ')}.`, channel, missingCapabilities);
+            }
+            const session = buildBrokerSession({
+                appId,
+                productId,
+                standaloneChannelProductId,
+                channel,
+                grantedCapabilities: requestedCapabilities,
+                installId: input.installId ?? options.installId ?? null,
+                deviceId: input.deviceId ?? options.deviceId ?? null,
+                userId: input.userId ?? null
+            });
+            currentSession = session;
+            setState('connected', 'broker.connected', session);
+            if (requestedCapabilities.includes('network.status') || requestedCapabilities.includes('network.proxy')) {
+                setState('network-ready', 'network.ready', session);
+            }
+            return {
+                ok: true,
+                state: currentState,
+                session,
+                reason: null,
+                message: 'Connected to standalone broker channel.',
+                channel,
+                missingCapabilities: []
+            };
+        },
+        async request(requestName, payload) {
+            if (!currentSession) {
+                throw new Error('Embed launcher is not connected to a standalone broker');
+            }
+            if (!currentSession.grantedCapabilities.includes(requestName)) {
+                throw new Error(`Capability is not granted for embed broker session: ${requestName}`);
+            }
+            if (!options.requestImpl) {
+                throw new Error('No embed broker request transport is configured');
+            }
+            return options.requestImpl(currentSession, requestName, payload);
+        },
+        on(eventName, handler) {
+            const set = handlers.get(eventName) ?? new Set();
+            set.add(handler);
+            handlers.set(eventName, set);
+            return () => launcher.off(eventName, handler);
+        },
+        off(eventName, handler) {
+            handlers.get(eventName)?.delete(handler);
+        },
+        shouldRefreshNetwork
+    };
+    return launcher;
+}
+export { routePlanFromSnapshot, shouldRefreshNetwork };
+function requiredProductId(productId) {
+    const trimmed = productId?.trim();
+    if (!trimmed)
+        throw new Error('Embed launcher productId is required');
+    return trimmed;
+}
+function normalizeProductId(productId) {
+    const normalized = productId.trim().toLowerCase();
+    if (!normalized)
+        throw new Error('Launcher productId is required');
+    return normalized;
+}
+function uniqueCapabilities(capabilities) {
+    return [...new Set(capabilities.map((capability) => String(capability || '').trim()).filter(Boolean))];
+}
+async function resolveChannelRegistry(source) {
+    if (!source)
+        return [];
+    const records = typeof source === 'function' ? await source() : source;
+    return records.filter((record) => record && record.productId && record.socketPath);
+}
+function channelIsFresh(record, maxAgeMs) {
+    if (!maxAgeMs || maxAgeMs <= 0)
+        return true;
+    const heartbeat = Date.parse(record.heartbeatAt);
+    if (!Number.isFinite(heartbeat))
+        return false;
+    return Date.now() - heartbeat <= maxAgeMs;
+}
+function buildHandshakeRequest(input) {
+    return {
+        appId: input.appId,
+        productId: input.productId,
+        launcherMode: 'embed',
+        sdkVersion: input.options.sdkVersion,
+        appVersion: input.options.appVersion,
+        protocolVersion: input.options.protocolVersion ?? launcherProtocolVersion,
+        minBrokerAbiVersion: input.options.minBrokerAbiVersion ?? brokerAbiVersion,
+        standaloneChannelProductId: input.standaloneChannelProductId,
+        requestedCapabilities: input.requestedCapabilities,
+        installId: input.input.installId ?? input.options.installId ?? null,
+        deviceId: input.input.deviceId ?? input.options.deviceId ?? null,
+        userId: input.input.userId ?? null,
+        requestId: input.input.requestId ?? null
+    };
+}
+function buildBrokerSession(input) {
+    return {
+        sessionId: `embed_${input.appId}_${input.channel.instanceId}`,
+        appId: input.appId,
+        productId: input.productId,
+        launcherMode: 'embed',
+        networkScope: 'broker-session',
+        standaloneChannelProductId: input.standaloneChannelProductId,
+        channel: input.channel,
+        grantedCapabilities: input.grantedCapabilities,
+        deniedCapabilities: [],
+        userId: input.userId,
+        installId: input.installId,
+        deviceId: input.deviceId,
+        issuedAt: new Date().toISOString(),
+        expiresAt: null
+    };
+}
+function deniedConnection(reason, message, channel, missingCapabilities) {
+    return {
+        ok: false,
+        state: reason === 'broker-incompatible' ? 'broker-incompatible' : reason === 'capability-denied' ? 'capability-denied' : 'standalone-required',
+        session: null,
+        reason,
+        message,
+        channel,
+        missingCapabilities
+    };
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@qpjoy/mx-launcher-embed-sdk",
+  "version": "0.2.0",
+  "description": "Embed SDK shell for products that carry MX Launcher network capability inside the app.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@qpjoy/mx-launcher-core": "^0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}