@heybox/hb-sdk 0.6.5 → 0.6.6-alpha.1

package/dist/cli-chunks/{dev-C3u5FXIy.cjs → dev-Bb4U965a.cjs}

@@ -7,10 +7,13 @@ var os = require('node:os');
 var path = require('node:path');
 var node_url = require('node:url');
 var net = require('node:net');
+var promises = require('node:dns/promises');
 var node_http = require('node:http');
+var node_crypto = require('node:crypto');
+var undici = require('undici');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-CKat0ExC.cjs');
-var context = require('./context-DjepdCaa.cjs');
+var index = require('./index-gP0K2xx1.cjs');
+var context = require('./context-D-cb_pNY.cjs');
 require('node:process');
 require('node:buffer');
 require('node:util');
@@ -24,8 +27,7 @@ require('events');
 require('stream');
 require('buffer');
 require('util');
-require('./session-DPEq__gB.cjs');
-require('node:crypto');
+require('./session-BRwveiW8.cjs');
 require('fs');
 require('constants');
 
@@ -191,6 +193,605 @@ async function getPorts(options) {
 	throw new Error('No available ports found');
 }
 
+const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
+/**
+ * 判断 permission key 是否由 Runtime 权限快照管理。
+ *
+ * @param key 待判断的 permission key。
+ * @returns 该 key 需要读取 Runtime 权限快照时返回 `true`。
+ */
+function isManagedMiniProgramRuntimePermissionKey(key) {
+    return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
+}
+/**
+ * 解析服务端权限快照；格式不完整时整份快照失效并 fail closed。
+ *
+ * @param snapshot 待校验的服务端权限快照。
+ * @returns 解析状态和通过校验的受管权限。
+ */
+function parseMiniProgramRuntimePermissions(snapshot) {
+    if (!isRecord$2(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false, permissions: {} };
+    }
+    if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
+        return { valid: false, permissions: {} };
+    }
+    const seenKeys = new Set();
+    const permissions = {};
+    for (const rawEntry of snapshot.entries) {
+        if (!isRecord$2(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+            return { valid: false, permissions: {} };
+        }
+        const key = rawEntry.key.trim();
+        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled') || !isRecord$2(rawEntry.config)) {
+            return { valid: false, permissions: {} };
+        }
+        seenKeys.add(key);
+        if (!isManagedMiniProgramRuntimePermissionKey(key)) {
+            continue;
+        }
+        if (key === 'network.request' && typeof rawEntry.config.useOfficialDomain !== 'boolean') {
+            return { valid: false, permissions: {} };
+        }
+        permissions[key] = {
+            key,
+            status: rawEntry.status,
+            config: { useOfficialDomain: rawEntry.config.useOfficialDomain },
+        };
+    }
+    return { valid: true, permissions };
+}
+function isRecord$2(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Dev Shell 读取局域网 Dev Session endpoint 的 query 参数。 */
+/** Mock Host 创建和读取 Dev Session 的固定路径。 */
+const MINI_PROGRAM_DEV_CONTEXT_PATH = '/__hb_sdk__/dev-context';
+/** Dev Session 当前使用的 schema 版本。 */
+const MINI_PROGRAM_DEV_SESSION_SCHEMA_VERSION = 1;
+
+const MOCK_HOST_JSON_BODY_LIMIT = 1024 * 1024;
+function readJsonRequestBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        request.on('data', (chunk) => {
+            const buffer = Buffer.from(chunk);
+            size += buffer.byteLength;
+            if (size > MOCK_HOST_JSON_BODY_LIMIT) {
+                reject(createMockHostError(413, 'REQUEST_ENTITY_TOO_LARGE', 'mock network proxy request body too large'));
+                request.destroy();
+                return;
+            }
+            chunks.push(buffer);
+        });
+        request.on('error', reject);
+        request.on('aborted', () => {
+            reject('mock network proxy request aborted');
+        });
+        request.on('end', () => {
+            const rawBody = Buffer.concat(chunks).toString('utf8');
+            if (!rawBody.trim()) {
+                resolve({});
+                return;
+            }
+            try {
+                resolve(JSON.parse(rawBody));
+            }
+            catch {
+                reject(createMockHostError(400, 'INVALID_JSON', 'mock network proxy received invalid JSON'));
+            }
+        });
+    });
+}
+function writeJsonResponse(response, status, body) {
+    response.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+    });
+    response.end(body === undefined ? '' : JSON.stringify(body));
+}
+function writeTokenNetworkJsonResponse(response, status, body) {
+    response.writeHead(status, {
+        'access-control-allow-headers': 'content-type',
+        'access-control-allow-methods': 'POST, OPTIONS',
+        'access-control-allow-origin': '*',
+        'access-control-allow-private-network': 'true',
+        'cache-control': 'no-store',
+        'content-type': 'application/json; charset=utf-8',
+    });
+    response.end(body === undefined ? '' : JSON.stringify(body));
+}
+function writeSerializedJsonResponse(response, status, body) {
+    response.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+    });
+    response.end(body);
+}
+function isRecord$1(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
+function isObjectLike(value) {
+    return (typeof value === 'object' || typeof value === 'function') && value !== null;
+}
+function createMockHostError(status, code, message) {
+    const error = new Error(message);
+    error.code = code;
+    error.status = status;
+    return error;
+}
+function readMockHostErrorStatus(error) {
+    return isObjectLike(error) && typeof error.status === 'number' ? error.status : 500;
+}
+function toMockHostErrorPayload(error) {
+    if (isObjectLike(error) && typeof error.code === 'string' && typeof error.message === 'string') {
+        return {
+            code: error.code,
+            message: error.message,
+        };
+    }
+    return {
+        code: 'MOCK_NETWORK_ERROR',
+        message: readErrorMessage(error),
+    };
+}
+function readErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+
+const MAX_MOCK_NETWORK_REDIRECTS = 5;
+const MAX_MOCK_NETWORK_REQUEST_BODY = 2 * 1024 * 1024;
+const MAX_MOCK_NETWORK_RESPONSE_BODY = 5 * 1024 * 1024;
+async function handleMockNetworkProxy(request, response, fetchImpl, lookupHostname, cors = false) {
+    if (request.method === 'OPTIONS') {
+        writeNetworkJsonResponse(response, 204, undefined, cors);
+        return;
+    }
+    if (request.method !== 'POST') {
+        writeNetworkJsonResponse(response, 405, {
+            code: 'METHOD_NOT_ALLOWED',
+            message: 'mock network proxy only supports POST',
+        }, cors);
+        return;
+    }
+    try {
+        const payload = await readJsonRequestBody(request);
+        const result = await requestMockNetwork(payload, fetchImpl, lookupHostname);
+        writeNetworkJsonResponse(response, 200, result, cors);
+    }
+    catch (error) {
+        writeNetworkJsonResponse(response, readMockHostErrorStatus(error), toMockHostErrorPayload(error), cors);
+    }
+}
+function writeNetworkJsonResponse(response, status, body, cors) {
+    if (cors) {
+        writeTokenNetworkJsonResponse(response, status, body);
+        return;
+    }
+    writeJsonResponse(response, status, body);
+}
+async function requestMockNetwork(payload, fetchImpl, lookupHostname) {
+    if (!isRecord$1(payload) || typeof payload.url !== 'string' || !payload.url.trim()) {
+        throw createMockHostError(400, 'INVALID_NETWORK_REQUEST', 'network.request url 必须是非空字符串');
+    }
+    const url = createMockNetworkUrl(payload.url, payload.params);
+    const method = typeof payload.method === 'string' && payload.method.trim() ? payload.method.trim().toUpperCase() : 'GET';
+    const headers = normalizeMockNetworkHeaders(payload.headers);
+    const body = createMockNetworkBody(method, payload.data, headers);
+    const controller = new AbortController();
+    const timeout = Number(payload.timeout) > 0 ? Number(payload.timeout) : 10000;
+    const timer = setTimeout(() => controller.abort(), timeout);
+    const pinnedTargets = new Map();
+    const dispatcher = createPinnedNetworkDispatcher(pinnedTargets);
+    try {
+        const response = await fetchMockNetworkWithRedirects({
+            body,
+            dispatcher,
+            fetchImpl,
+            headers,
+            lookupHostname,
+            method,
+            pinnedTargets,
+            signal: controller.signal,
+            url,
+        });
+        const contentType = response.headers.get('content-type') || '';
+        const text = await readLimitedMockNetworkResponse(response);
+        return {
+            data: contentType.includes('application/json') ? safeJsonParse(text) : text,
+            status: response.status,
+            statusText: response.statusText,
+            headers: Object.fromEntries(response.headers.entries()),
+        };
+    }
+    catch (error) {
+        if (isObjectLike(error) && typeof error.status === 'number') {
+            throw error;
+        }
+        throw createMockHostError(502, 'MOCK_NETWORK_REQUEST_FAILED', error instanceof Error && error.name === 'AbortError' ? `network.request timeout after ${timeout}ms` : readErrorMessage(error));
+    }
+    finally {
+        clearTimeout(timer);
+        await dispatcher.close();
+    }
+}
+async function fetchMockNetworkWithRedirects(options) {
+    let url = options.url;
+    let method = options.method;
+    let body = options.body;
+    for (let redirectCount = 0; redirectCount <= MAX_MOCK_NETWORK_REDIRECTS; redirectCount += 1) {
+        const pinnedTarget = await resolveMockNetworkTarget(url, options.lookupHostname);
+        options.pinnedTargets.set(createPinnedNetworkTargetKey(url), pinnedTarget);
+        const response = await options.fetchImpl(url.toString(), {
+            body,
+            dispatcher: options.dispatcher,
+            headers: options.headers,
+            method,
+            redirect: 'manual',
+            signal: options.signal,
+        });
+        if (![301, 302, 303, 307, 308].includes(response.status)) {
+            return response;
+        }
+        const location = response.headers.get('location');
+        if (!location) {
+            return response;
+        }
+        if (redirectCount === MAX_MOCK_NETWORK_REDIRECTS) {
+            throw createMockHostError(502, 'TOO_MANY_REDIRECTS', 'network.request redirect limit exceeded');
+        }
+        await response.body?.cancel();
+        url = new URL(location, url);
+        if (response.status === 303 || ((response.status === 301 || response.status === 302) && method === 'POST')) {
+            method = 'GET';
+            body = undefined;
+        }
+    }
+    throw createMockHostError(502, 'TOO_MANY_REDIRECTS', 'network.request redirect limit exceeded');
+}
+async function resolveMockNetworkTarget(url, lookupHostname) {
+    if (!['http:', 'https:'].includes(url.protocol)) {
+        throw createMockHostError(403, 'NETWORK_TARGET_DENIED', 'network.request redirect 仅支持 HTTP(S) URL');
+    }
+    if (url.username || url.password) {
+        throw createMockHostError(403, 'NETWORK_TARGET_DENIED', 'network.request URL 不允许包含凭据');
+    }
+    const hostname = normalizeNetworkHostname(url.hostname);
+    const addressFamily = net.isIP(hostname);
+    const addresses = addressFamily ? [{ address: hostname, family: addressFamily }] : await lookupHostname(hostname);
+    if (!addresses.length) {
+        throw new Error('network.request target DNS lookup returned no addresses');
+    }
+    return addresses[0];
+}
+function createPinnedNetworkDispatcher(pinnedTargets) {
+    const connect = undici.buildConnector({});
+    return new undici.Agent({
+        connect(options, callback) {
+            const hostname = normalizeNetworkHostname(options.hostname);
+            const target = pinnedTargets.get(`${options.protocol}//${hostname}:${options.port || (options.protocol === 'https:' ? '443' : '80')}`);
+            if (!target) {
+                callback(new Error('network.request target was not DNS-pinned'), null);
+                return;
+            }
+            connect({
+                ...options,
+                hostname: target.address,
+                servername: options.servername || hostname,
+            }, callback);
+        },
+    });
+}
+function createPinnedNetworkTargetKey(url) {
+    return `${url.protocol}//${normalizeNetworkHostname(url.hostname)}:${url.port || (url.protocol === 'https:' ? '443' : '80')}`;
+}
+function normalizeNetworkHostname(hostname) {
+    return hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+}
+async function readLimitedMockNetworkResponse(response) {
+    if (!response.body) {
+        return '';
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        size += value.byteLength;
+        if (size > MAX_MOCK_NETWORK_RESPONSE_BODY) {
+            await reader.cancel();
+            throw createMockHostError(502, 'NETWORK_RESPONSE_TOO_LARGE', 'network.request response body too large');
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString('utf8');
+}
+function createMockNetworkUrl(input, params) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw createMockHostError(400, 'INVALID_NETWORK_REQUEST', 'network.request url 必须是合法 URL');
+    }
+    if (!['http:', 'https:'].includes(url.protocol)) {
+        throw createMockHostError(400, 'INVALID_NETWORK_REQUEST', 'network.request 仅支持 HTTP(S) URL');
+    }
+    if (isRecord$1(params)) {
+        Object.entries(params).forEach(([key, value]) => {
+            if (value !== undefined && value !== null) {
+                url.searchParams.set(key, String(value));
+            }
+        });
+    }
+    return url;
+}
+function normalizeMockNetworkHeaders(headers) {
+    const normalized = new Headers();
+    if (!isRecord$1(headers)) {
+        return normalized;
+    }
+    Object.entries(headers).forEach(([key, value]) => {
+        if (isSensitiveMockNetworkHeader(key)) {
+            throw createMockHostError(400, 'INVALID_NETWORK_REQUEST', `network.request 不允许设置敏感请求头: ${key}`);
+        }
+        if (typeof value === 'string' && !isBlockedMockNetworkHeader(key)) {
+            normalized.set(key, value);
+        }
+    });
+    return normalized;
+}
+function isSensitiveMockNetworkHeader(key) {
+    return ['authorization', 'cookie', 'proxy-authorization'].includes(key.toLowerCase());
+}
+function isBlockedMockNetworkHeader(key) {
+    return [
+        'connection',
+        'content-length',
+        'host',
+        'keep-alive',
+        'proxy-authenticate',
+        'proxy-authorization',
+        'te',
+        'trailer',
+        'transfer-encoding',
+        'upgrade',
+    ].includes(key.toLowerCase());
+}
+function createMockNetworkBody(method, data, headers) {
+    if (data === undefined || method === 'GET' || method === 'HEAD') {
+        return undefined;
+    }
+    const body = typeof data === 'string' ? data : JSON.stringify(data);
+    if (Buffer.byteLength(body) > MAX_MOCK_NETWORK_REQUEST_BODY) {
+        throw createMockHostError(413, 'REQUEST_ENTITY_TOO_LARGE', 'network.request data exceeds 2097152 bytes');
+    }
+    if (typeof data === 'string') {
+        return body;
+    }
+    if (!headers.has('content-type')) {
+        headers.set('content-type', 'application/json');
+    }
+    return body;
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+
+const DEV_SESSION_TTL_MS = 5 * 60 * 1000;
+const MAX_ACTIVE_DEV_SESSIONS = 64;
+const MAX_EXPIRED_DEV_SESSION_TOMBSTONES = 128;
+function createDevSessionRoutes(options) {
+    const devSessions = new Map();
+    const expiredDevSessions = new Set();
+    let revision = 0;
+    return {
+        match(pathname) {
+            const match = pathname.match(/^\/__hb_sdk__\/dev-context\/([a-f0-9]{64})(\/network)?$/);
+            if (!match) {
+                return undefined;
+            }
+            return {
+                kind: match[2] ? 'network' : 'context',
+                token: match[1],
+            };
+        },
+        async create(request, response) {
+            if (!request.headers['content-type']?.toLowerCase().startsWith('application/json')) {
+                writeJsonResponse(response, 400, { code: 'INVALID_DEV_SESSION', message: 'Dev Session body must be JSON' });
+                return;
+            }
+            try {
+                const payload = await readJsonRequestBody(request);
+                const validated = validateDevSessionCreatePayload(payload, options.allowedMiniUrlOrigins);
+                reapExpiredDevSessions(devSessions, expiredDevSessions, options.now());
+                revokeDevSessionForOrigin(devSessions, validated.miniUrlOrigin);
+                if (devSessions.size >= MAX_ACTIVE_DEV_SESSIONS) {
+                    throw createMockHostError(429, 'DEV_SESSION_LIMIT_REACHED', 'active Dev Session limit reached');
+                }
+                const expiresAt = options.now() + DEV_SESSION_TTL_MS;
+                const token = createDevSessionToken(devSessions);
+                const snapshot = {
+                    schema_version: MINI_PROGRAM_DEV_SESSION_SCHEMA_VERSION,
+                    revision: ++revision,
+                    expires_at: expiresAt,
+                    mini_url_origin: validated.miniUrlOrigin,
+                    runtime_permissions: validated.runtimePermissions,
+                };
+                devSessions.set(token, {
+                    expiresAt,
+                    miniUrlOrigin: validated.miniUrlOrigin,
+                    networkRequestEnabled: validated.networkRequestEnabled,
+                    serialized: JSON.stringify(snapshot),
+                });
+                const result = { expires_at: expiresAt, token };
+                writeJsonResponse(response, 201, result);
+            }
+            catch (error) {
+                const status = readMockHostErrorStatus(error);
+                writeJsonResponse(response, status === 500 ? 400 : status, {
+                    code: 'INVALID_DEV_SESSION',
+                    message: readErrorMessage(error),
+                });
+            }
+        },
+        async handle(route, request, response) {
+            if (route.kind === 'network') {
+                await handleTokenNetworkProxy(request, response, route.token, {
+                    devSessions,
+                    expiredDevSessions,
+                    fetchImpl: options.fetchImpl,
+                    lookupHostname: options.lookupHostname,
+                    now: options.now,
+                });
+                return;
+            }
+            if (request.method !== 'OPTIONS' && request.method !== 'GET') {
+                response.writeHead(405, { allow: 'GET', 'cache-control': 'no-store' });
+                response.end();
+                return;
+            }
+            const resolved = resolveDevSession(route.token, devSessions, expiredDevSessions, options.now());
+            if (resolved.status !== 200) {
+                writeDevSessionCorsResponse(response, resolved.status);
+                return;
+            }
+            writeDevSessionCorsResponse(response, request.method === 'OPTIONS' ? 204 : 200, request.method === 'GET' ? resolved.session.serialized : undefined);
+        },
+    };
+}
+function validateDevSessionCreatePayload(payload, allowedMiniUrlOrigins) {
+    if (!isRecord$1(payload) || Object.keys(payload).some((key) => !['mini_url_origin', 'runtime_permissions'].includes(key))) {
+        throw new TypeError('Dev Session body is invalid');
+    }
+    if (typeof payload.mini_url_origin !== 'string') {
+        throw new TypeError('mini_url_origin is invalid');
+    }
+    let miniUrlOrigin;
+    try {
+        miniUrlOrigin = new URL(payload.mini_url_origin);
+    }
+    catch {
+        throw new TypeError('mini_url_origin is invalid');
+    }
+    if (miniUrlOrigin.protocol !== 'http:' ||
+        payload.mini_url_origin !== miniUrlOrigin.origin ||
+        !isPrivateLanIpv4(miniUrlOrigin.hostname) ||
+        !allowedMiniUrlOrigins.has(miniUrlOrigin.origin)) {
+        throw new TypeError('mini_url_origin must be an allowed LAN origin');
+    }
+    const parsedPermissions = parseMiniProgramRuntimePermissions(payload.runtime_permissions);
+    if (!parsedPermissions.valid) {
+        throw new TypeError('runtime_permissions is invalid');
+    }
+    const networkPermission = parsedPermissions.permissions['network.request'];
+    if (networkPermission?.config.useOfficialDomain !== false) {
+        throw new TypeError('Dev Session does not allow official domains');
+    }
+    return {
+        miniUrlOrigin: miniUrlOrigin.origin,
+        networkRequestEnabled: networkPermission.status === 'enabled',
+        runtimePermissions: JSON.parse(JSON.stringify(payload.runtime_permissions)),
+    };
+}
+async function handleTokenNetworkProxy(request, response, token, runtime) {
+    const resolved = resolveDevSession(token, runtime.devSessions, runtime.expiredDevSessions, runtime.now());
+    if (resolved.status !== 200) {
+        writeTokenNetworkJsonResponse(response, resolved.status, undefined);
+        return;
+    }
+    if (!resolved.session.networkRequestEnabled) {
+        writeTokenNetworkJsonResponse(response, 403, {
+            code: 'PERMISSION_DENIED',
+            message: 'network.request is disabled for this Dev Session',
+        });
+        return;
+    }
+    if (request.method === 'OPTIONS') {
+        writeTokenNetworkJsonResponse(response, 204, undefined);
+        return;
+    }
+    if (request.method !== 'POST') {
+        writeTokenNetworkJsonResponse(response, 405, {
+            code: 'METHOD_NOT_ALLOWED',
+            message: 'Dev Session network proxy only supports POST',
+        });
+        return;
+    }
+    await handleMockNetworkProxy(request, response, runtime.fetchImpl, runtime.lookupHostname, true);
+}
+function resolveDevSession(token, devSessions, expiredDevSessions, now) {
+    const session = devSessions.get(token);
+    if (!session) {
+        return { status: expiredDevSessions.has(token) ? 410 : 404 };
+    }
+    if (now >= session.expiresAt) {
+        devSessions.delete(token);
+        addExpiredDevSessionTombstone(expiredDevSessions, token);
+        return { status: 410 };
+    }
+    return { session, status: 200 };
+}
+function reapExpiredDevSessions(devSessions, expiredDevSessions, now) {
+    for (const [token, session] of devSessions) {
+        if (now >= session.expiresAt) {
+            devSessions.delete(token);
+            addExpiredDevSessionTombstone(expiredDevSessions, token);
+        }
+    }
+}
+function addExpiredDevSessionTombstone(expiredDevSessions, token) {
+    expiredDevSessions.add(token);
+    while (expiredDevSessions.size > MAX_EXPIRED_DEV_SESSION_TOMBSTONES) {
+        const oldest = expiredDevSessions.values().next().value;
+        if (!oldest) {
+            break;
+        }
+        expiredDevSessions.delete(oldest);
+    }
+}
+function revokeDevSessionForOrigin(devSessions, miniUrlOrigin) {
+    for (const [token, session] of devSessions) {
+        if (session.miniUrlOrigin === miniUrlOrigin) {
+            devSessions.delete(token);
+        }
+    }
+}
+function createDevSessionToken(devSessions) {
+    let token;
+    do {
+        token = node_crypto.randomBytes(32).toString('hex');
+    } while (devSessions.has(token));
+    return token;
+}
+function isPrivateLanIpv4(hostname) {
+    const octets = hostname.split('.').map(Number);
+    if (octets.length !== 4 || octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+        return false;
+    }
+    return octets[0] === 10 || (octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31) || (octets[0] === 192 && octets[1] === 168);
+}
+function writeDevSessionCorsResponse(response, status, serializedBody) {
+    response.writeHead(status, {
+        'access-control-allow-methods': 'GET',
+        'access-control-allow-origin': '*',
+        'access-control-allow-private-network': 'true',
+        'cache-control': 'no-store',
+        ...(serializedBody === undefined ? {} : { 'content-type': 'application/json; charset=utf-8' }),
+    });
+    response.end(serializedBody ?? '');
+}
+
 async function selectAvailablePort(options) {
     const maxAttempts = options.maxAttempts ?? 20;
     const port = await options.getPort({
@@ -209,7 +810,7 @@ function createPortCandidates(startPort, count) {
 const MINI_PROGRAM_URL_QUERY_PARAM$1 = 'mini_url';
 const MOCK_HOST_BOOTSTRAP_PATH = '/__hb_sdk_bootstrap__';
 const MOCK_NETWORK_PROXY_PATH = '/__hb_sdk_mock_network__';
-const MOCK_NETWORK_PROXY_BODY_LIMIT = 1024 * 1024;
+const DEV_PERMISSIONS_PATH = '/__hb_sdk__/dev-permissions';
 const DEV_LISTEN_HOST$1 = '0.0.0.0';
 const LOCAL_DEV_URL_HOST$1 = '127.0.0.1';
 const MOCK_HOST_ROOT_CANDIDATES = [
@@ -231,8 +832,13 @@ async function startMiniProgramMockHostServer(options) {
     });
     const server = createMiniProgramMockHostServer(root, {
         appUrl: options.appUrl,
+        allowedMiniUrlOrigins: new Set((options.lanAddresses ?? []).map(({ appUrl }) => new URL(appUrl).origin)),
         bootstrapJson,
         fetchImpl: options.fetchImpl ?? fetch,
+        isLoopbackPeer: options.isLoopbackPeer ?? isLoopbackAddress,
+        lookupHostname: options.lookupHostname ?? (async (hostname) => promises.lookup(hostname, { all: true, verbatim: true })),
+        now: options.now ?? Date.now,
+        permissionController: options.permissionController,
     });
     const port = await listenHttpServer(server, {
         port: options.port,
@@ -291,16 +897,27 @@ function serializeMockHostBootstrap(bootstrap) {
         throw new TypeError('Mock host bootstrap must be JSON serializable');
     }
     const serializedBootstrap = JSON.parse(serialized);
-    if (bootstrap.runtimePermissions !== undefined &&
-        !Object.prototype.hasOwnProperty.call(serializedBootstrap, 'runtimePermissions')) {
+    if (bootstrap.runtimePermissions !== undefined && !Object.prototype.hasOwnProperty.call(serializedBootstrap, 'runtimePermissions')) {
         throw new TypeError('Runtime permission snapshot must be JSON serializable');
     }
     return serialized;
 }
 function createMiniProgramMockHostServer(root, runtime) {
+    const devSessionRoutes = createDevSessionRoutes({
+        allowedMiniUrlOrigins: runtime.allowedMiniUrlOrigins,
+        fetchImpl: runtime.fetchImpl,
+        lookupHostname: runtime.lookupHostname,
+        now: runtime.now,
+    });
     return node_http.createServer(async (request, response) => {
         const requestUrl = new URL(request.url, 'http://localhost');
         const pathname = decodeURIComponent(requestUrl.pathname);
+        const devSessionRoute = devSessionRoutes.match(pathname);
+        const loopbackPeer = runtime.isLoopbackPeer(request.socket.remoteAddress);
+        if (!loopbackPeer && !devSessionRoute) {
+            writeForbidden(response);
+            return;
+        }
         if (isMockHostDocumentPath(pathname) && !requestUrl.searchParams.has(MINI_PROGRAM_URL_QUERY_PARAM$1)) {
             const targetUrl = new URL(requestUrl);
             targetUrl.pathname = '/';
@@ -312,12 +929,61 @@ function createMiniProgramMockHostServer(root, runtime) {
             response.end();
             return;
         }
-        if (pathname === MOCK_HOST_BOOTSTRAP_PATH) {
-            writeSerializedJsonResponse(response, 200, runtime.bootstrapJson);
+        if (pathname === MOCK_HOST_BOOTSTRAP_PATH) {
+            if (!loopbackPeer || !hasNumericLoopbackHost(request)) {
+                writeForbidden(response);
+                return;
+            }
+            if (request.method !== 'GET') {
+                writeMethodNotAllowed(response, 'GET');
+                return;
+            }
+            writeSerializedJsonResponse(response, 200, runtime.bootstrapJson);
+            return;
+        }
+        if (pathname === DEV_PERMISSIONS_PATH && runtime.permissionController) {
+            if (!loopbackPeer || !hasNumericLoopbackHost(request)) {
+                writeForbidden(response);
+                return;
+            }
+            if (request.method === 'GET') {
+                writeJsonResponse(response, 200, await runtime.permissionController.get());
+                return;
+            }
+            if ((request.method !== 'PUT' && request.method !== 'DELETE') || !hasValidMutationOrigin(request)) {
+                if (request.method !== 'PUT' && request.method !== 'DELETE') {
+                    writeMethodNotAllowed(response, 'GET, PUT, DELETE');
+                }
+                else {
+                    writeForbidden(response);
+                }
+                return;
+            }
+            await handleDevPermissionMutation(request, response, runtime.permissionController);
+            return;
+        }
+        if (pathname === MINI_PROGRAM_DEV_CONTEXT_PATH) {
+            if (!loopbackPeer || !hasNumericLoopbackHost(request) || !hasValidMutationOrigin(request)) {
+                writeForbidden(response);
+                return;
+            }
+            if (request.method !== 'POST') {
+                writeMethodNotAllowed(response, 'POST');
+                return;
+            }
+            await devSessionRoutes.create(request, response);
+            return;
+        }
+        if (devSessionRoute) {
+            await devSessionRoutes.handle(devSessionRoute, request, response);
             return;
         }
         if (pathname === MOCK_NETWORK_PROXY_PATH) {
-            await handleMockNetworkProxy(request, response, runtime.fetchImpl);
+            if (!loopbackPeer || !hasNumericLoopbackHost(request) || !hasValidMutationOrigin(request)) {
+                writeForbidden(response);
+                return;
+            }
+            await handleMockNetworkProxy(request, response, runtime.fetchImpl, runtime.lookupHostname);
             return;
         }
         const targetPath = resolveStaticPath(root, pathname);
@@ -345,204 +1011,90 @@ function createMiniProgramMockHostServer(root, runtime) {
         }
     });
 }
-function isMockHostDocumentPath(pathname) {
-    return pathname === '/' || pathname === '/index.html';
-}
-async function handleMockNetworkProxy(request, response, fetchImpl) {
-    if (request.method === 'OPTIONS') {
-        writeJsonResponse(response, 204, undefined);
-        return;
-    }
-    if (request.method !== 'POST') {
-        writeJsonResponse(response, 405, {
-            code: 'METHOD_NOT_ALLOWED',
-            message: 'mock network proxy only supports POST',
-        });
-        return;
-    }
+async function handleDevPermissionMutation(request, response, controller) {
     try {
+        if (request.method === 'DELETE') {
+            if (hasRequestBody(request)) {
+                if (!request.headers['content-type']?.toLowerCase().startsWith('application/json')) {
+                    throw createMockHostError(400, 'INVALID_DEV_PERMISSIONS', 'Dev permissions body must be JSON');
+                }
+                const payload = await readJsonRequestBody(request);
+                if (!isRecord$1(payload) || Object.keys(payload).length > 0) {
+                    throw createMockHostError(400, 'INVALID_DEV_PERMISSIONS', 'Dev permissions reset body is invalid');
+                }
+            }
+            writeJsonResponse(response, 200, await controller.reset());
+            return;
+        }
+        if (!request.headers['content-type']?.toLowerCase().startsWith('application/json')) {
+            throw createMockHostError(400, 'INVALID_DEV_PERMISSIONS', 'Dev permissions body must be JSON');
+        }
         const payload = await readJsonRequestBody(request);
-        const result = await requestMockNetwork(payload, fetchImpl);
-        writeJsonResponse(response, 200, result);
+        if (!isRecord$1(payload) || Object.keys(payload).length !== 1 || !Object.hasOwn(payload, 'runtime_permissions')) {
+            throw createMockHostError(400, 'INVALID_DEV_PERMISSIONS', 'Dev permissions update body is invalid');
+        }
+        const parsed = parseMiniProgramRuntimePermissions(payload.runtime_permissions);
+        if (!parsed.valid) {
+            throw createMockHostError(400, 'INVALID_DEV_PERMISSIONS', 'runtime_permissions is invalid');
+        }
+        const runtimePermissions = JSON.parse(JSON.stringify(payload.runtime_permissions));
+        writeJsonResponse(response, 200, await controller.save(runtimePermissions));
     }
     catch (error) {
-        writeJsonResponse(response, readMockNetworkErrorStatus(error), toMockNetworkErrorPayload(error));
-    }
-}
-async function requestMockNetwork(payload, fetchImpl) {
-    if (!isRecord(payload) || typeof payload.url !== 'string' || !payload.url.trim()) {
-        throw createMockNetworkError(400, 'INVALID_NETWORK_REQUEST', 'network.request url 必须是非空字符串');
-    }
-    const url = createMockNetworkUrl(payload.url, payload.params);
-    const method = typeof payload.method === 'string' && payload.method.trim() ? payload.method.trim().toUpperCase() : 'GET';
-    const headers = normalizeMockNetworkHeaders(payload.headers);
-    const controller = new AbortController();
-    const timeout = Number(payload.timeout) > 0 ? Number(payload.timeout) : 10000;
-    const timer = setTimeout(() => controller.abort(), timeout);
-    try {
-        const response = await fetchImpl(url.toString(), {
-            method,
-            headers,
-            body: createMockNetworkBody(method, payload.data, headers),
-            redirect: 'follow',
-            signal: controller.signal,
+        const errorStatus = readMockHostErrorStatus(error);
+        const status = request.method === 'DELETE' && errorStatus === 500 ? 502 : errorStatus;
+        writeJsonResponse(response, status, {
+            code: request.method === 'DELETE' ? 'DEV_PERMISSIONS_RESET_FAILED' : 'DEV_PERMISSIONS_UPDATE_FAILED',
+            message: readErrorMessage(error),
         });
-        const contentType = response.headers.get('content-type') || '';
-        const text = await response.text();
-        clearTimeout(timer);
-        return {
-            data: contentType.includes('application/json') ? safeJsonParse(text) : text,
-            status: response.status,
-            statusText: response.statusText,
-            headers: Object.fromEntries(response.headers.entries()),
-        };
-    }
-    catch (error) {
-        clearTimeout(timer);
-        throw createMockNetworkError(502, 'MOCK_NETWORK_REQUEST_FAILED', error instanceof Error && error.name === 'AbortError'
-            ? `network.request timeout after ${timeout}ms`
-            : readErrorMessage(error));
     }
 }
-function createMockNetworkUrl(input, params) {
-    let url;
-    try {
-        url = new URL(input);
-    }
-    catch {
-        throw createMockNetworkError(400, 'INVALID_NETWORK_REQUEST', 'network.request url 必须是合法 URL');
-    }
-    if (!['http:', 'https:'].includes(url.protocol)) {
-        throw createMockNetworkError(400, 'INVALID_NETWORK_REQUEST', 'network.request 仅支持 HTTP(S) URL');
-    }
-    if (isRecord(params)) {
-        Object.entries(params).forEach(([key, value]) => {
-            if (value !== undefined && value !== null) {
-                url.searchParams.set(key, String(value));
-            }
-        });
-    }
-    return url;
+function hasRequestBody(request) {
+    return request.headers['transfer-encoding'] !== undefined || Number(request.headers['content-length'] ?? 0) > 0;
 }
-function normalizeMockNetworkHeaders(headers) {
-    const normalized = new Headers();
-    if (!isRecord(headers)) {
-        return normalized;
-    }
-    Object.entries(headers).forEach(([key, value]) => {
-        if (typeof value === 'string' && !isBlockedMockNetworkHeader(key)) {
-            normalized.set(key, value);
-        }
+function writeMethodNotAllowed(response, allowedMethod) {
+    response.writeHead(405, {
+        allow: allowedMethod,
+        'cache-control': 'no-store',
     });
-    return normalized;
+    response.end();
 }
-function isBlockedMockNetworkHeader(key) {
-    return [
-        'connection',
-        'content-length',
-        'host',
-        'keep-alive',
-        'proxy-authenticate',
-        'proxy-authorization',
-        'te',
-        'trailer',
-        'transfer-encoding',
-        'upgrade',
-    ].includes(key.toLowerCase());
+function writeForbidden(response) {
+    response.writeHead(403, { 'cache-control': 'no-store' });
+    response.end();
 }
-function createMockNetworkBody(method, data, headers) {
-    if (data === undefined || method === 'GET' || method === 'HEAD') {
-        return undefined;
+function hasValidMutationOrigin(request) {
+    const origin = request.headers.origin;
+    const host = request.headers.host;
+    if (!host || !origin || origin === 'null') {
+        return false;
     }
-    if (typeof data === 'string') {
-        return data;
+    try {
+        return new URL(origin).origin === `http://${host}`;
     }
-    if (!headers.has('content-type')) {
-        headers.set('content-type', 'application/json');
+    catch {
+        return false;
     }
-    return JSON.stringify(data);
-}
-function readJsonRequestBody(request) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        let size = 0;
-        request.on('data', (chunk) => {
-            const buffer = Buffer.from(chunk);
-            size += buffer.byteLength;
-            if (size > MOCK_NETWORK_PROXY_BODY_LIMIT) {
-                reject(createMockNetworkError(413, 'REQUEST_ENTITY_TOO_LARGE', 'mock network proxy request body too large'));
-                request.destroy();
-                return;
-            }
-            chunks.push(buffer);
-        });
-        request.on('error', reject);
-        request.on('aborted', () => {
-            reject('mock network proxy request aborted');
-        });
-        request.on('end', () => {
-            const rawBody = Buffer.concat(chunks).toString('utf8');
-            if (!rawBody.trim()) {
-                resolve({});
-                return;
-            }
-            try {
-                resolve(JSON.parse(rawBody));
-            }
-            catch {
-                reject(createMockNetworkError(400, 'INVALID_JSON', 'mock network proxy received invalid JSON'));
-            }
-        });
-    });
-}
-function writeJsonResponse(response, status, body) {
-    response.writeHead(status, {
-        'content-type': 'application/json; charset=utf-8',
-        'cache-control': 'no-store',
-    });
-    response.end(body === undefined ? '' : JSON.stringify(body));
-}
-function writeSerializedJsonResponse(response, status, body) {
-    response.writeHead(status, {
-        'content-type': 'application/json; charset=utf-8',
-        'cache-control': 'no-store',
-    });
-    response.end(body);
 }
-function safeJsonParse(text) {
+function hasNumericLoopbackHost(request) {
+    const host = request.headers.host;
+    if (!host) {
+        return false;
+    }
     try {
-        return JSON.parse(text);
+        const hostname = new URL(`http://${host}`).hostname;
+        const normalized = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+        return net.isIP(normalized) !== 0 && isLoopbackAddress(normalized);
     }
     catch {
-        return text;
+        return false;
     }
 }
-function isRecord(value) {
-    return Object.prototype.toString.call(value) === '[object Object]';
-}
-function createMockNetworkError(status, code, message) {
-    const error = new Error(message);
-    error.code = code;
-    error.status = status;
-    return error;
-}
-function readMockNetworkErrorStatus(error) {
-    return isObjectLike(error) && typeof error.status === 'number' ? error.status : 500;
-}
-function toMockNetworkErrorPayload(error) {
-    if (isObjectLike(error) && typeof error.code === 'string' && typeof error.message === 'string') {
-        return {
-            code: error.code,
-            message: error.message,
-        };
-    }
-    return {
-        code: 'MOCK_NETWORK_ERROR',
-        message: readErrorMessage(error),
-    };
+function isLoopbackAddress(address) {
+    return address === '::1' || address === '127.0.0.1' || address?.startsWith('127.') === true || address?.startsWith('::ffff:127.') === true;
 }
-function isObjectLike(value) {
-    return (typeof value === 'object' || typeof value === 'function') && value !== null;
+function isMockHostDocumentPath(pathname) {
+    return pathname === '/' || pathname === '/index.html';
 }
 function resolveStaticPath(root, pathname) {
     const safePathname = pathname === '/' ? '/index.html' : pathname;
@@ -594,9 +1146,6 @@ async function listenHttpServer(server, options, getPortImpl) {
     const address = server.address();
     return address.port;
 }
-function readErrorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 
 const MINI_PROGRAM_URL_QUERY_PARAM = 'mini_url';
 const MINI_PROGRAM_RUNTIME_URL_QUERY_PARAM = 'runtime_url';
@@ -667,10 +1216,168 @@ function createHeyboxProtocol(payload) {
     return `heybox://${encodeURIComponent(JSON.stringify(payload))}`;
 }
 
+const DEFAULT_PERMISSION_STATE = {
+    networkRequest: {
+        status: 'disabled',
+        useOfficialDomain: false,
+    },
+};
+function createMiniProgramMockPermissionState(context) {
+    const parsed = parseMiniProgramRuntimePermissions(context.runtimePermissions);
+    const networkRequest = parsed.permissions['network.request'];
+    return parsed.valid && networkRequest
+        ? {
+            networkRequest: {
+                status: networkRequest.status,
+                useOfficialDomain: networkRequest.config.useOfficialDomain === true,
+            },
+        }
+        : cloneDefaultPermissionState();
+}
+function createMiniProgramMockRuntimePermissions(state) {
+    return {
+        schema_version: 1,
+        entries: [
+            {
+                key: 'network.request',
+                status: state.networkRequest.status,
+                config: {
+                    useOfficialDomain: state.networkRequest.useOfficialDomain,
+                },
+            },
+        ],
+    };
+}
+function cloneDefaultPermissionState() {
+    return {
+        networkRequest: { ...DEFAULT_PERMISSION_STATE.networkRequest },
+    };
+}
+
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.5';
+    : '0.6.6-alpha.1';
+
+class DevPermissionOverrideStoreError extends Error {
+    code;
+    constructor(message, code, options = {}) {
+        super(message, { cause: options.cause });
+        this.code = code;
+        this.name = 'DevPermissionOverrideStoreError';
+    }
+}
+const CACHE_VERSION = 1;
+const CACHE_DIRECTORY_NAME = 'dev-permission-overrides';
+const defaultPaths = index.envPaths('hb-sdk', { suffix: '' });
+function createDevPermissionOverrideStore(options = {}) {
+    const cacheDirectory = path.join(options.cacheRoot ?? defaultPaths.cache, CACHE_DIRECTORY_NAME);
+    return {
+        async read(scope) {
+            return readScopeFile(await getScopeFile(cacheDirectory, scope));
+        },
+        async remove(scope) {
+            const scopeFile = await getScopeFile(cacheDirectory, scope);
+            try {
+                await fs$1.unlink(scopeFile);
+            }
+            catch (error) {
+                if (isNodeError(error) && error.code === 'ENOENT') {
+                    return;
+                }
+                throw createWriteError(error);
+            }
+        },
+        async set(scope, overrides) {
+            const scopeFile = await getScopeFile(cacheDirectory, scope);
+            try {
+                await fs$1.mkdir(cacheDirectory, { recursive: true, mode: 0o700 });
+                await fs$1.chmod(cacheDirectory, 0o700);
+                await readScopeFile(scopeFile);
+                await writeScopeFileAtomically(scopeFile, {
+                    version: CACHE_VERSION,
+                    overrides: cloneOverrides(overrides),
+                });
+            }
+            catch (error) {
+                if (error instanceof DevPermissionOverrideStoreError) {
+                    throw error;
+                }
+                throw createWriteError(error);
+            }
+        },
+    };
+}
+async function getScopeFile(cacheDirectory, scope) {
+    const projectRoot = await fs$1.realpath(scope.projectRoot);
+    const miniProgramId = scope.miniProgramId ?? 'anonymous';
+    const scopeHash = node_crypto.createHash('sha256').update(`${projectRoot}\0${miniProgramId}`).digest('hex');
+    return path.join(cacheDirectory, `${scopeHash}.json`);
+}
+async function readScopeFile(scopeFile) {
+    let contents;
+    try {
+        contents = await fs$1.readFile(scopeFile, 'utf8');
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+    try {
+        const parsed = JSON.parse(contents);
+        if (!isPersistedOverride(parsed)) {
+            throw new TypeError('invalid cache schema');
+        }
+        return cloneOverrides(parsed.overrides);
+    }
+    catch (error) {
+        throw new DevPermissionOverrideStoreError('hb-sdk 本地权限覆盖缓存已损坏', 'DEV_PERMISSION_OVERRIDE_CACHE_CORRUPT', {
+            cause: error,
+        });
+    }
+}
+async function writeScopeFileAtomically(scopeFile, value) {
+    const tempFile = `${scopeFile}.${process.pid}.${node_crypto.randomBytes(8).toString('hex')}.tmp`;
+    let handle;
+    try {
+        handle = await fs$1.open(tempFile, 'wx', 0o600);
+        await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await fs$1.rename(tempFile, scopeFile);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await fs$1.unlink(tempFile).catch(() => undefined);
+    }
+}
+function createWriteError(cause) {
+    return new DevPermissionOverrideStoreError('无法写入 hb-sdk 本地权限覆盖缓存', 'DEV_PERMISSION_OVERRIDE_WRITE_FAILED', { cause });
+}
+function cloneOverrides(overrides) {
+    return {
+        networkRequest: { ...overrides.networkRequest },
+    };
+}
+function isPersistedOverride(value) {
+    return isRecord(value) && value.version === CACHE_VERSION && Object.keys(value).length === 2 && isPermissionState(value.overrides);
+}
+function isPermissionState(value) {
+    return (isRecord(value) &&
+        Object.keys(value).length === 1 &&
+        isRecord(value.networkRequest) &&
+        (value.networkRequest.status === 'enabled' || value.networkRequest.status === 'disabled') &&
+        typeof value.networkRequest.useOfficialDomain === 'boolean');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
 
 const DEFAULT_APP_PORT = 5173;
 const DEFAULT_MOCK_PORT = 5174;
@@ -706,6 +1413,20 @@ async function runDevCommand(options, runtime = {}) {
         projectRoot,
         timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
     });
+    const permissionController = createDevPermissionController({
+        boundMiniProgramId: await context.readBoundMiniProgramId(projectRoot),
+        cacheRoot: runtime.devPermissionCacheRoot,
+        devContext: devLaunchContext,
+        loadRemoteContext: () => loadDevLaunchContext({
+            env: runtime.env,
+            fetchImpl,
+            logger,
+            projectRoot,
+            requireRemote: true,
+            timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
+        }),
+        projectRoot,
+    });
     const vite = await logger.task('正在加载项目 Vite', () => loadProjectVite(projectRoot), { successText: '已加载项目 Vite' });
     const appServer = await logger.task('正在创建 Vite dev server', () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions)), runtime.env), { successText: '已创建 Vite dev server' });
     await logger.task('正在启动 Vite dev server', () => appServer.listen(appPort), {
@@ -733,11 +1454,13 @@ async function runDevCommand(options, runtime = {}) {
             getPort: getPortImpl,
             defaultLanAddressId: lanAddresses[0]?.id,
             lanAddresses,
+            lookupHostname: runtime.lookupHostname,
             macAppProtocol: createMacAppProtocol(appUrl, {
                 miniProgramId: devLaunchContext.miniProgramId,
                 runtimeUrl: options.runtimeUrl,
                 sdkVersion: HB_SDK_VERSION,
             }),
+            permissionController,
             port: options.mockPort ?? DEFAULT_MOCK_PORT,
             root: runtime.mockHostRoot,
             rootCandidates: runtime.mockHostRootCandidates,
@@ -767,6 +1490,9 @@ async function loadDevLaunchContext(options) {
     const miniProgramId = await context.readBoundMiniProgramId(options.projectRoot);
     if (!miniProgramId) {
         const anonymousReason = '当前项目未绑定小程序。请先运行 hb-sdk remote create 或 hb-sdk remote bind <mini-program-id>。';
+        if (options.requireRemote) {
+            throw new Error(anonymousReason);
+        }
         options.logger.warn(`未读取到远端 Runtime 权限，Mock runtime 将默认拒绝受管能力：${anonymousReason}`);
         return {
             source: 'anonymous',
@@ -793,6 +1519,9 @@ async function loadDevLaunchContext(options) {
         if (error instanceof context.MiniProgramProjectBindingError && error.code !== 'MINI_PROGRAM_UNBOUND') {
             throw error;
         }
+        if (options.requireRemote) {
+            throw error;
+        }
         options.logger.debug(`远端 dev context 失败详情：${index.readRedactedErrorMessage(error, { verbose: true })}`);
         options.logger.warn(`未读取到远端 Runtime 权限，Mock runtime 将默认拒绝受管能力：${DEV_CONTEXT_UNAVAILABLE_WARNING}`);
         return {
@@ -801,6 +1530,78 @@ async function loadDevLaunchContext(options) {
         };
     }
 }
+function createDevPermissionController(options) {
+    const store = createDevPermissionOverrideStore({ cacheRoot: options.cacheRoot });
+    let devContext = options.devContext;
+    let ephemeralOverride;
+    let persistenceError;
+    const readScope = () => ({
+        projectRoot: options.projectRoot,
+        ...(options.boundMiniProgramId ? { miniProgramId: options.boundMiniProgramId } : {}),
+    });
+    const createConfiguration = (overrides, error = persistenceError) => {
+        const miniProgramId = options.boundMiniProgramId ?? devContext.miniProgramId;
+        return {
+            source: devContext.source,
+            ...(miniProgramId ? { mini_program_id: miniProgramId } : {}),
+            ...(isRuntimePermissionsSnapshot(devContext.runtimePermissions) ? { remote_permissions: devContext.runtimePermissions } : {}),
+            ...(overrides ? { override_permissions: createMiniProgramMockRuntimePermissions(overrides) } : {}),
+            ...(error ? { persistence_error: error } : {}),
+        };
+    };
+    const get = async () => {
+        try {
+            const persistedOverride = await store.read(readScope());
+            return createConfiguration(ephemeralOverride ?? persistedOverride);
+        }
+        catch (error) {
+            persistenceError = index.readErrorMessage(error);
+            return createConfiguration(ephemeralOverride, persistenceError);
+        }
+    };
+    return {
+        get,
+        async reset() {
+            if (devContext.source === 'anonymous' && !options.boundMiniProgramId) {
+                await store.remove(readScope());
+                ephemeralOverride = undefined;
+                persistenceError = undefined;
+                return createConfiguration(undefined);
+            }
+            let refreshedContext;
+            try {
+                refreshedContext = await options.loadRemoteContext();
+            }
+            catch (error) {
+                throw new Error('远端权限读取失败，请检查 CLI 登录状态和网络后重试。', { cause: error });
+            }
+            await store.remove(readScope());
+            devContext = refreshedContext;
+            ephemeralOverride = undefined;
+            persistenceError = undefined;
+            return createConfiguration(undefined);
+        },
+        async save(runtimePermissions) {
+            const overrides = createMiniProgramMockPermissionState({
+                runtimePermissions,
+            });
+            try {
+                await store.set(readScope(), overrides);
+                ephemeralOverride = undefined;
+                persistenceError = undefined;
+                return createConfiguration(overrides);
+            }
+            catch {
+                ephemeralOverride = overrides;
+                persistenceError = '保存失败，当前页面仍会应用该权限，但刷新或重启后会丢失。';
+                return createConfiguration(overrides, persistenceError);
+            }
+        },
+    };
+}
+function isRuntimePermissionsSnapshot(value) {
+    return parseMiniProgramRuntimePermissions(value).valid;
+}
 async function loadRemoteDevContextWithTimeout(options) {
     const controller = new AbortController();
     const fetchImpl = ((input, init) => options.fetchImpl(input, { ...init, signal: controller.signal }));