@theaiplatform/miniapp-sdk 0.3.2 → 0.4.0

package/dist/vscode-webview.js

@@ -0,0 +1,594 @@
+import { sdk } from "./sdk.js";
+import { resolvePackageAssetUrl } from "./surface.js";
+const BRIDGE_KIND = 'tap-vscode-webview-bridge';
+const BRIDGE_VERSION = 1;
+const BRIDGE_INIT_ELEMENT_ID = 'tap-vscode-webview-bridge-init';
+const FORBIDDEN_PATH_SEGMENTS = new Set([
+    '__proto__',
+    'constructor',
+    'prototype'
+]);
+const CONFLICT_PATTERN = /conflict|revision/iu;
+const HTTP_METHODS = new Set([
+    'DELETE',
+    'GET',
+    'HEAD',
+    'OPTIONS',
+    'PATCH',
+    'POST',
+    'PUT'
+]);
+function assertCanonicalPath(path, label) {
+    if (0 === path.length || path.some((segment)=>0 === segment.length || segment.trim() !== segment || FORBIDDEN_PATH_SEGMENTS.has(segment))) throw new Error(`${label} must be a non-empty canonical JSON path.`);
+}
+function readPath(value, path) {
+    let current = value;
+    for (const segment of path){
+        if (null === current || 'object' != typeof current || !Object.hasOwn(current, segment)) return;
+        current = Reflect.get(current, segment);
+    }
+    return current;
+}
+function writePath(value, path, nextValue) {
+    const cloned = cloneJson(value);
+    let current;
+    if (null === cloned || 'object' != typeof cloned || Array.isArray(cloned)) throw new Error('A bridge state path requires an object root.');
+    current = cloned;
+    for (const segment of path.slice(0, -1)){
+        const child = current[segment];
+        if (void 0 === child) {
+            const created = {};
+            current[segment] = created;
+            current = created;
+            continue;
+        }
+        if (null === child || 'object' != typeof child || Array.isArray(child)) throw new Error('A bridge state path crosses a non-object value.');
+        current = child;
+    }
+    current[path.at(-1)] = cloneJson(nextValue);
+    return cloned;
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function bytesToBase64(value) {
+    if (!Array.isArray(value) || value.some((byte)=>!Number.isInteger(byte) || byte < 0 || byte > 255)) throw new Error('Expected an array of unsigned bytes.');
+    let binary = '';
+    for(let offset = 0; offset < value.length; offset += 32768)binary += String.fromCharCode(...value.slice(offset, offset + 32768));
+    return btoa(binary);
+}
+function base64ToBytes(value) {
+    if ('string' != typeof value) throw new Error('Expected a base64 string.');
+    const binary = atob(value);
+    return Array.from(binary, (character)=>character.charCodeAt(0));
+}
+function transformValue(value, transform = 'identity') {
+    if ('byte-array-to-base64' === transform) return bytesToBase64(value);
+    if ('base64-to-byte-array' === transform) return base64ToBytes(value);
+    return cloneJson(value);
+}
+function encodeBase64Json(value) {
+    const bytes = new TextEncoder().encode(JSON.stringify(value));
+    let binary = '';
+    for(let offset = 0; offset < bytes.length; offset += 32768)binary += String.fromCharCode(...bytes.slice(offset, offset + 32768));
+    return btoa(binary);
+}
+function rebaseCssUrls(value, baseUrl) {
+    return value.replace(/url\(\s*(["']?)([^"')]+)\1\s*\)/giu, (match, quote, rawUrl)=>{
+        const candidate = rawUrl.trim();
+        if ('' === candidate || candidate.startsWith('#') || candidate.startsWith('data:') || candidate.startsWith('blob:')) return match;
+        const resolved = new URL(candidate, baseUrl).href;
+        return `url(${quote}${resolved}${quote})`;
+    });
+}
+function rebaseDocumentUrls(documentValue, entry) {
+    const resourceAttributes = [
+        [
+            "script[src]",
+            'src'
+        ],
+        [
+            'link[href]',
+            'href'
+        ],
+        [
+            'img[src]',
+            'src'
+        ],
+        [
+            'source[src]',
+            'src'
+        ],
+        [
+            'video[src]',
+            'src'
+        ],
+        [
+            'video[poster]',
+            'poster'
+        ],
+        [
+            'audio[src]',
+            'src'
+        ],
+        [
+            'track[src]',
+            'src'
+        ],
+        [
+            'input[src]',
+            'src'
+        ]
+    ];
+    for (const [selector, attribute] of resourceAttributes)for (const element of documentValue.querySelectorAll(selector)){
+        const value = element.getAttribute(attribute);
+        if (value) element.setAttribute(attribute, new URL(value, entry).href);
+    }
+    for (const element of documentValue.querySelectorAll('[style]')){
+        const value = element.getAttribute('style');
+        if (value) element.setAttribute('style', rebaseCssUrls(value, entry));
+    }
+    for (const element of documentValue.querySelectorAll('style'))element.textContent = rebaseCssUrls(element.textContent ?? '', entry);
+}
+function normalizeOrigins(origins) {
+    return (origins ?? []).map((value)=>{
+        const url = new URL(value);
+        if ('https:' !== url.protocol || url.origin !== value || '' !== url.username || '' !== url.password) throw new Error('VS Code webview network entries must be exact HTTPS origins.');
+        return url.origin;
+    });
+}
+function normalizeSessionNamespace(value) {
+    if (null === value || 'object' != typeof value || Array.isArray(value)) return {};
+    return Object.fromEntries(Object.entries(value).filter((entry)=>'string' == typeof entry[1]));
+}
+async function waitForHostAuthority(context) {
+    if (context.hostAuthority.getSnapshot()) return;
+    await new Promise((resolve)=>{
+        const unsubscribe = context.hostAuthority.subscribe(()=>{
+            if (!context.hostAuthority.getSnapshot()) return;
+            unsubscribe();
+            resolve();
+        });
+    });
+}
+async function loadStoredState(options) {
+    if (!options) return null;
+    const entry = await sdk.storage.get({
+        namespace: options.namespace,
+        key: options.key
+    });
+    return {
+        value: null === entry.value ? cloneJson(options.initialValue) : entry.value,
+        revision: entry.revision
+    };
+}
+function bridgeBootstrapValue(options, state) {
+    if (!options.bootstrap) return null;
+    let value = cloneJson(options.bootstrap.value);
+    for (const binding of options.storage?.bootstrapBindings ?? []){
+        assertCanonicalPath(binding.statePath, 'bootstrap statePath');
+        assertCanonicalPath(binding.bootstrapPath, 'bootstrap bootstrapPath');
+        const stored = readPath(state?.value, binding.statePath);
+        if (void 0 !== stored) value = writePath(value, binding.bootstrapPath, transformValue(stored, binding.transform));
+    }
+    return value;
+}
+function injectBridgeHtml(source, entry, runtime, options, bootstrap, session, vscodeState) {
+    const documentValue = new DOMParser().parseFromString(source, 'text/html');
+    const head = documentValue.head ?? documentValue.documentElement.insertBefore(documentValue.createElement('head'), documentValue.body);
+    documentValue.querySelectorAll('base').forEach((node)=>node.remove());
+    documentValue.querySelectorAll('meta[http-equiv]').forEach((node)=>{
+        if (node.getAttribute('http-equiv')?.toLowerCase() === 'content-security-policy') node.remove();
+    });
+    rebaseDocumentUrls(documentValue, entry);
+    const policy = documentValue.createElement('meta');
+    policy.httpEquiv = 'Content-Security-Policy';
+    policy.content = "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-src 'none'; worker-src 'self' blob:; object-src 'none'; base-uri 'none'; form-action 'none'";
+    const init = documentValue.createElement("script");
+    init.id = BRIDGE_INIT_ELEMENT_ID;
+    init.type = 'application/json';
+    init.textContent = JSON.stringify({
+        kind: BRIDGE_KIND,
+        version: BRIDGE_VERSION,
+        parentOrigin: window.location.origin,
+        assetOrigin: entry.origin,
+        assetBaseUrl: new URL('.', entry).href,
+        allowedOrigins: normalizeOrigins(options.network?.allowedOrigins),
+        session,
+        sessionEnabled: Boolean(options.session),
+        vscodeState
+    }).replaceAll('<', '\\u003c');
+    const runtimeScript = documentValue.createElement("script");
+    runtimeScript.src = runtime.href;
+    head.prepend(policy, init, runtimeScript);
+    if (options.bootstrap) {
+        const target = documentValue.querySelector(options.bootstrap.selector);
+        if (!target) throw new Error(`The VS Code webview bootstrap selector did not match: ${options.bootstrap.selector}`);
+        target.setAttribute(options.bootstrap.attribute, encodeBase64Json(bootstrap ?? null));
+    }
+    return `<!doctype html>\n${documentValue.documentElement.outerHTML}`;
+}
+function asBridgeEnvelope(value) {
+    if (null === value || 'object' != typeof value || Reflect.get(value, 'kind') !== BRIDGE_KIND || Reflect.get(value, 'version') !== BRIDGE_VERSION) return null;
+    const type = Reflect.get(value, 'type');
+    const method = Reflect.get(value, 'method');
+    if ('notification' !== type && 'request' !== type && 'response' !== type || 'string' != typeof method) return null;
+    return value;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function webviewHttpRequest(value, allowedOrigins) {
+    if (null === value || 'object' != typeof value || Array.isArray(value)) throw new Error('The webview supplied an invalid HTTP request.');
+    const method = Reflect.get(value, 'method');
+    const urlValue = Reflect.get(value, 'url');
+    if ('string' != typeof method || !HTTP_METHODS.has(method) || 'string' != typeof urlValue) throw new Error('The webview supplied an invalid HTTP request.');
+    const url = new URL(urlValue);
+    if ('https:' !== url.protocol || '' !== url.username || '' !== url.password || !allowedOrigins.has(url.origin)) throw new Error(`The webview HTTP origin is not declared: ${url.origin}`);
+    const rawHeaders = Reflect.get(value, 'headers');
+    if (void 0 !== rawHeaders && (!Array.isArray(rawHeaders) || rawHeaders.length > 128)) throw new Error('The webview supplied invalid HTTP headers.');
+    const headers = (rawHeaders ?? []).map((entry)=>{
+        if (null === entry || 'object' != typeof entry || 'string' != typeof Reflect.get(entry, 'name') || 'string' != typeof Reflect.get(entry, 'value')) throw new Error('The webview supplied invalid HTTP headers.');
+        const name = Reflect.get(entry, 'name');
+        const headerValue = Reflect.get(entry, 'value');
+        if (name.length > 128 || headerValue.length > 8192) throw new Error('The webview supplied invalid HTTP headers.');
+        new Headers([
+            [
+                name,
+                headerValue
+            ]
+        ]);
+        return {
+            name,
+            value: headerValue
+        };
+    });
+    const body = Reflect.get(value, 'body');
+    if (null != body && ('string' != typeof body || body.length > 10485760)) throw new Error('The webview supplied an invalid HTTP body.');
+    if (('GET' === method || 'HEAD' === method) && null != body) throw new Error(`The webview cannot send a body with ${method}.`);
+    return {
+        method,
+        url: url.href,
+        ...headers.length > 0 ? {
+            headers
+        } : {},
+        ...void 0 === body ? {} : {
+            body
+        },
+        timeoutMs: 30000,
+        responseBodyLimitBytes: 10485760,
+        followRedirects: false
+    };
+}
+function mountVsCodeWebview(container, context, options) {
+    const entry = resolvePackageAssetUrl(context, options.entryPath);
+    const runtime = resolvePackageAssetUrl(context, options.runtimePath);
+    const allowedOrigins = new Set(normalizeOrigins(options.network?.allowedOrigins));
+    const frame = document.createElement('iframe');
+    frame.title = options.title;
+    frame.loading = 'eager';
+    frame.referrerPolicy = 'no-referrer';
+    frame.setAttribute('sandbox', "allow-downloads allow-modals allow-scripts allow-same-origin");
+    frame.style.border = '0';
+    frame.style.display = 'block';
+    frame.style.height = '100%';
+    frame.style.width = '100%';
+    container.replaceChildren(frame);
+    let mounted = true;
+    let state = null;
+    let sessionValue = {};
+    let storageQueue = Promise.resolve();
+    let sessionQueue = Promise.resolve();
+    const reportError = (error)=>{
+        const normalized = error instanceof Error ? error : new Error(errorMessage(error));
+        if (options.onError) options.onError(normalized);
+        else window.dispatchEvent(new ErrorEvent('error', {
+            error: normalized,
+            message: normalized.message
+        }));
+    };
+    const send = (envelope)=>{
+        frame.contentWindow?.postMessage(envelope, window.location.origin);
+    };
+    const persistStateUpdate = (update)=>{
+        const storage = options.storage;
+        if (!storage || !state) return;
+        storageQueue = storageQueue.then(async ()=>{
+            if (!state) return;
+            for(let attempt = 0; attempt < 2; attempt += 1){
+                const current = state;
+                if (!current) return;
+                const next = update(current.value);
+                try {
+                    const result = await sdk.storage.set({
+                        namespace: storage.namespace,
+                        key: storage.key,
+                        expectedRevision: current.revision,
+                        value: next
+                    });
+                    state = {
+                        value: next,
+                        revision: result.revision
+                    };
+                    return;
+                } catch (error) {
+                    if (1 === attempt || !CONFLICT_PATTERN.test(errorMessage(error))) throw error;
+                    state = await loadStoredState(storage);
+                }
+            }
+        });
+        storageQueue.catch(reportError);
+    };
+    const handleWebviewMessage = async (message)=>{
+        const storage = options.storage;
+        if (storage) {
+            const typePath = storage.messageTypePath ?? [
+                'type'
+            ];
+            assertCanonicalPath(typePath, 'messageTypePath');
+            const messageType = readPath(message, typePath);
+            const binding = storage.messageBindings?.find((candidate)=>candidate.messageType === messageType);
+            if (binding) {
+                assertCanonicalPath(binding.messageValuePath, 'messageValuePath');
+                assertCanonicalPath(binding.statePath, 'statePath');
+                const incoming = readPath(message, binding.messageValuePath);
+                if (void 0 === incoming) throw new Error(`The ${binding.messageType} message did not contain its configured value.`);
+                const transformed = transformValue(incoming, binding.transform);
+                persistStateUpdate((value)=>writePath(value, binding.statePath, transformed));
+            }
+        }
+        await options.onMessage?.(message);
+    };
+    const handleSessionChange = (payload)=>{
+        const session = options.session;
+        if (!session) return;
+        const nextNamespace = normalizeSessionNamespace(payload);
+        sessionQueue = sessionQueue.then(async ()=>{
+            const current = await sdk.session.get();
+            sessionValue = current.value ?? {};
+            sessionValue = {
+                ...sessionValue,
+                [session.namespace]: nextNamespace
+            };
+            await sdk.session.set(sessionValue);
+        });
+        sessionQueue.catch(reportError);
+    };
+    const handleHttpRequest = async (envelope)=>{
+        if (!envelope.id) return;
+        try {
+            if (!sdk.http) throw new Error('The host does not provide sdk.http.');
+            const input = webviewHttpRequest(envelope.payload, allowedOrigins);
+            const response = await sdk.http.request(input);
+            send({
+                kind: BRIDGE_KIND,
+                version: BRIDGE_VERSION,
+                id: envelope.id,
+                type: 'response',
+                method: envelope.method,
+                payload: response
+            });
+        } catch (error) {
+            send({
+                kind: BRIDGE_KIND,
+                version: BRIDGE_VERSION,
+                id: envelope.id,
+                type: 'response',
+                method: envelope.method,
+                error: {
+                    message: errorMessage(error)
+                }
+            });
+        }
+    };
+    const onWindowMessage = (event)=>{
+        if (!mounted || event.source !== frame.contentWindow || event.origin !== window.location.origin) return;
+        const envelope = asBridgeEnvelope(event.data);
+        if (!envelope) return;
+        if ('request' === envelope.type && 'http.request' === envelope.method) return void handleHttpRequest(envelope);
+        if ('notification' === envelope.type && 'vscode.postMessage' === envelope.method) return void handleWebviewMessage(envelope.payload).catch(reportError);
+        if ('notification' === envelope.type && 'vscode.setState' === envelope.method) {
+            const statePath = options.storage?.vscodeStatePath;
+            if (statePath) {
+                assertCanonicalPath(statePath, 'vscodeStatePath');
+                const nextValue = transformValue(envelope.payload);
+                persistStateUpdate((value)=>writePath(value, statePath, nextValue));
+            }
+            return;
+        }
+        if ('notification' === envelope.type && 'session.replace' === envelope.method) handleSessionChange(envelope.payload);
+    };
+    window.addEventListener('message', onWindowMessage);
+    (async ()=>{
+        try {
+            await waitForHostAuthority(context);
+            if (!mounted) return;
+            const [sourceResponse, loadedState, loadedSession] = await Promise.all([
+                fetch(entry),
+                loadStoredState(options.storage),
+                options.session ? sdk.session.get() : Promise.resolve(null)
+            ]);
+            if (!sourceResponse.ok) throw new Error(`The VS Code webview entry failed to load (${sourceResponse.status}).`);
+            state = loadedState;
+            sessionValue = loadedSession?.value ?? {};
+            const sessionNamespace = options.session ? normalizeSessionNamespace(sessionValue[options.session.namespace]) : {};
+            const vscodeState = options.storage?.vscodeStatePath ? readPath(state?.value, options.storage.vscodeStatePath) : null;
+            frame.srcdoc = injectBridgeHtml(await sourceResponse.text(), entry, runtime, options, bridgeBootstrapValue(options, state), sessionNamespace, vscodeState);
+        } catch (error) {
+            reportError(error);
+        }
+    })();
+    return {
+        postMessage (message) {
+            send({
+                kind: BRIDGE_KIND,
+                version: BRIDGE_VERSION,
+                type: 'notification',
+                method: 'host.postMessage',
+                payload: message
+            });
+        },
+        unmount () {
+            if (!mounted) return;
+            mounted = false;
+            window.removeEventListener('message', onWindowMessage);
+            frame.remove();
+        }
+    };
+}
+const tapVsCodeWebviewRuntimeSource = String.raw`(() => {
+  "use strict";
+  const KIND = "tap-vscode-webview-bridge";
+  const VERSION = 1;
+  const initElement = document.getElementById("tap-vscode-webview-bridge-init");
+  if (!initElement) throw new Error("The TAP VS Code webview bridge init is missing.");
+  const init = JSON.parse(initElement.textContent || "{}");
+  if (init.kind !== KIND || init.version !== VERSION) {
+    throw new Error("The TAP VS Code webview bridge init is invalid.");
+  }
+  Object.defineProperty(window, "__TAP_VSCODE_WEBVIEW_ASSET_BASE_URL__", {
+    configurable: false,
+    enumerable: false,
+    value: init.assetBaseUrl,
+    writable: false,
+  });
+  const pending = new Map();
+  let requestCounter = 0;
+  let vscodeState = init.vscodeState ?? null;
+  const post = (envelope) => window.parent.postMessage(
+    { kind: KIND, version: VERSION, ...envelope },
+    init.parentOrigin,
+  );
+  const request = (method, payload) => new Promise((resolve, reject) => {
+    const id = "tap-vscode-" + (++requestCounter) + "-" + Date.now();
+    const timeout = window.setTimeout(() => {
+      pending.delete(id);
+      reject(new Error("The TAP VS Code webview request timed out: " + method));
+    }, 120000);
+    pending.set(id, { resolve, reject, timeout });
+    post({ id, type: "request", method, payload });
+  });
+  const vscodeApi = Object.freeze({
+    getState: () => vscodeState,
+    setState: (value) => {
+      vscodeState = value;
+      post({ type: "notification", method: "vscode.setState", payload: value });
+      return value;
+    },
+    postMessage: (message) => {
+      post({ type: "notification", method: "vscode.postMessage", payload: message });
+    },
+  });
+  Object.defineProperty(window, "acquireVsCodeApi", {
+    configurable: false,
+    enumerable: true,
+    value: () => vscodeApi,
+    writable: false,
+  });
+
+  if (init.sessionEnabled) {
+    const values = new Map(Object.entries(init.session || {}));
+    const snapshot = () => Object.fromEntries(values);
+    const notify = () => post({
+      type: "notification",
+      method: "session.replace",
+      payload: snapshot(),
+    });
+    const facade = {
+      get length() { return values.size; },
+      clear() { values.clear(); notify(); },
+      getItem(key) {
+        const normalized = String(key);
+        return values.has(normalized) ? values.get(normalized) : null;
+      },
+      key(index) { return [...values.keys()][Number(index)] ?? null; },
+      removeItem(key) { values.delete(String(key)); notify(); },
+      setItem(key, value) {
+        values.set(String(key), String(value));
+        notify();
+      },
+    };
+    Object.defineProperty(window, "localStorage", {
+      configurable: false,
+      enumerable: true,
+      value: facade,
+      writable: false,
+    });
+  }
+
+  const nativeFetch = window.fetch.bind(window);
+  const allowedOrigins = new Set(init.allowedOrigins || []);
+  const decodeBase64 = (value) => {
+    const binary = atob(value);
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+  };
+  window.fetch = async (input, requestInit) => {
+    const original = new Request(input, requestInit);
+    const url = new URL(original.url);
+    if (url.origin === init.assetOrigin) return nativeFetch(original);
+    if (!allowedOrigins.has(url.origin)) {
+      throw new Error("The webview HTTP origin is not declared: " + url.origin);
+    }
+    const contentType = original.headers.get("content-type") || "";
+    if (
+      original.body &&
+      (contentType.startsWith("multipart/") ||
+        contentType === "application/octet-stream")
+    ) {
+      throw new Error("Binary and multipart webview request bodies are unsupported.");
+    }
+    const headers = [];
+    original.headers.forEach((value, name) => headers.push({ name, value }));
+    const response = await request("http.request", {
+      method: original.method,
+      url: original.url,
+      headers,
+      ...(original.method === "GET" || original.method === "HEAD"
+        ? {}
+        : { body: await original.clone().text() }),
+      timeoutMs: 30000,
+      responseBodyLimitBytes: 10 * 1024 * 1024,
+      followRedirects: false,
+    });
+    const responseHeaders = new Headers();
+    for (const header of response.headers || []) {
+      responseHeaders.append(header.name, header.value);
+    }
+    const body = response.bodyKind === "binary" && response.bodyBase64
+      ? decodeBase64(response.bodyBase64)
+      : response.bodyText;
+    return new Response(body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: responseHeaders,
+    });
+  };
+
+  window.addEventListener("message", (event) => {
+    if (
+      event.source !== window.parent ||
+      event.origin !== init.parentOrigin ||
+      !event.data ||
+      event.data.kind !== KIND ||
+      event.data.version !== VERSION
+    ) return;
+    const envelope = event.data;
+    if (envelope.type === "response" && envelope.id) {
+      const waiter = pending.get(envelope.id);
+      if (!waiter) return;
+      pending.delete(envelope.id);
+      window.clearTimeout(waiter.timeout);
+      if (envelope.error) waiter.reject(new Error(envelope.error.message));
+      else waiter.resolve(envelope.payload);
+      return;
+    }
+    if (envelope.type === "notification" && envelope.method === "host.postMessage") {
+      window.dispatchEvent(new MessageEvent("message", {
+        data: envelope.payload,
+        origin: init.parentOrigin,
+        source: window.parent,
+      }));
+    }
+  });
+})();`;
+export { mountVsCodeWebview, tapVsCodeWebviewRuntimeSource };

package/dist/web.d.ts

@@ -136,6 +136,29 @@ declare type MiniAppAuthApi = {
     getUserProfile(): MiniAppMaybePromise<MiniAppUserProfile | null>;
 };
 
+/**
+ * Read-only authorization introspection for custom surface behavior.
+ *
+ * The host rejects action IDs that are not declared by the exact mounted
+ * surface. A declared action resolves to the current dynamic allow/deny
+ * decision without executing the action.
+ */
+declare type MiniAppAuthorizationApi = {
+    check(options: MiniAppAuthorizationCheckOptions): Promise<MiniAppAuthorizationCheckResult>;
+};
+
+/** Canonical autonomy requested for one descriptor-declared package action. */
+declare type MiniAppAuthorizationAutonomy = 'listen' | 'plan' | 'do';
+
+declare type MiniAppAuthorizationCheckOptions = {
+    actionId: string;
+    autonomy: MiniAppAuthorizationAutonomy;
+};
+
+declare type MiniAppAuthorizationCheckResult = {
+    allowed: boolean;
+};
+
 /**
  * @capability miniapp-platform
  */
@@ -358,8 +381,10 @@ export declare type MiniAppPlatformApi = {
     navigation: {
         open(options: OpenNavigationOptions): void | Promise<void>;
     };
+    authorization: MiniAppAuthorizationApi;
     chat: MiniAppChatApi;
     storage: MiniAppStorageApi;
+    session: MiniAppSessionApi;
     presence: MiniAppPresenceApi;
     /** Desktop host capability; feature-detect before use on portable targets. */
     http?: MiniAppHttpApi;
@@ -519,6 +544,31 @@ declare type MiniAppReceiptTextAlignment = 'left' | 'center' | 'right';
 
 declare type MiniAppReceiptTextWeight = 'normal' | 'bold';
 
+/**
+ * Secure session storage backed by the operating system credential store.
+ *
+ * The host derives the signed-in TAP account, active workspace, installation,
+ * and package from the authenticated frame. Channel, surface, document, and
+ * release are deliberately excluded, so every surface of one installed
+ * miniapp shares the same session only within a workspace and package updates
+ * retain it. Unlike host-managed HTTP credentials, values returned here enter
+ * miniapp JavaScript.
+ */
+declare type MiniAppSessionApi = {
+    get(): MiniAppMaybePromise<MiniAppSessionEntry>;
+    set(value: MiniAppSessionValue): MiniAppMaybePromise<void>;
+    clear(): MiniAppMaybePromise<void>;
+};
+
+declare type MiniAppSessionEntry = {
+    /** Null means that no session value currently exists for this installation. */
+    value: MiniAppSessionValue | null;
+};
+
+declare type MiniAppSessionValue = {
+    [key: string]: MiniAppJsonValue;
+};
+
 declare type MiniAppSpecialistApi = {
     joinToChannel(channelId: string, specialistId: string): MiniAppMaybePromise<string>;
     listWorkspace(workspaceId: string): MiniAppMaybePromise<MiniAppSpecialistSummary[]>;