raffel 1.1.89 → 1.1.90-next.3da3a67

package/dist/docs/ui/runtime/index.js

@@ -62,6 +62,11 @@ let searchQuery = '';
 let routeState = parseRouteHash();
 let activePagePath = resolveDocsAlias(routeState.pagePath);
 let activeHeadingId = routeState.headingId;
+// Authentication material is deliberately memory-only. Persisting API keys,
+// tokens, or OAuth client secrets in Web Storage makes them available to any
+// script running on the documentation origin.
+const credentialMemory = new Map();
+const pendingOAuthMemory = new Map();
 const docsPlugins = [];
 const themeStorageKey = 'raffel-docs-theme';
 const sidebarWidthStorageKey = 'raffel-docs-sidebar-width';
@@ -140,12 +145,22 @@ function unmountDocsComponents(root = doc) {
 function esc(value) {
     if (value === undefined || value === null)
         return '';
-    return String(value)
-        .replace(/&/g, '&')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#x27;');
+    let escaped = '';
+    for (const character of String(value)) {
+        if (character === '&')
+            escaped += '&amp;';
+        else if (character === '<')
+            escaped += '&lt;';
+        else if (character === '>')
+            escaped += '&gt;';
+        else if (character === '"')
+            escaped += '&quot;';
+        else if (character === "'")
+            escaped += '&#x27;';
+        else
+            escaped += character;
+    }
+    return escaped;
 }
 function slugifyHeading(value) {
     return String(value ?? '')
@@ -2288,6 +2303,19 @@ function renderEndpointDetails(endpoint) {
         left.className = 'endpoint-left';
         const right = doc.createElement('div');
         right.className = 'endpoint-right';
+        const longPoll = data['x-usd-long-poll'] ?? data['x-raffel-long-poll'];
+        if (longPoll) {
+            const section = doc.createElement('div');
+            section.className = 'endpoint-subsection long-poll-interaction';
+            section.innerHTML = '<div class="subsection-label">Long Poll Interaction</div>';
+            appendInfoGrid(section, [
+                ['Cursor', `${longPoll.cursor?.input ?? 'cursor'} → ${longPoll.cursor?.output ?? 'cursor'} (${longPoll.cursor?.semantics ?? 'exclusive'})`],
+                ['Maximum wait', longPoll.waitMs ? `${longPoll.waitMs} ms` : undefined],
+                ['Retry hint', longPoll.retryMs ? `${longPoll.retryMs} ms` : undefined],
+                ['Timeout outcome', longPoll.timeoutOutcome],
+            ]);
+            left.appendChild(section);
+        }
         const params = (data.parameters ?? []);
         if (params.length > 0) {
             const section = doc.createElement('div');
@@ -2395,7 +2423,15 @@ function renderEndpointDetails(endpoint) {
         appendMany([['Arguments', data.args], ['Input', data.input], ['Output', data.output], ['Schema', data.schema], ['Relations', data.relations], ['Authorize', data.authorize], ['Authorization', data.authz], ['Policies', data.policies]]);
     }
     if (activeProtocol === 'streams') {
-        appendInfoGrid(container, [['Direction', data.direction], ['Path', endpoint.path]]);
+        const resumable = data['x-usd-resumable'];
+        appendInfoGrid(container, [
+            ['Direction', data.direction],
+            ['Path', endpoint.path],
+            ['Delivery', resumable?.delivery],
+            ['Resume Cursor', resumable?.cursor?.header],
+            ['Snapshot event', resumable?.snapshot?.event],
+        ]);
+        appendStreamProjectionDiagnostics(container, resumable?.projections);
         appendMany([['Parameters', parameterMapToSchema(data.parameters)], ['Message Schema', resolveMessagePayload(data.message)]]);
     }
     if (activeProtocol === 'jsonrpc') {
@@ -2412,11 +2448,46 @@ function renderEndpointDetails(endpoint) {
         appendMany([['Framing', data.framing], ['Inbound Message', resolveMessagePayload(data.messages?.inbound)], ['Outbound Message', resolveMessagePayload(data.messages?.outbound)]]);
     }
     if (activeProtocol === 'udp') {
-        appendInfoGrid(container, [['Host', data.host ?? '0.0.0.0'], ['Port', data.port], ['Max Packet', data.maxPacketSize ? `${data.maxPacketSize} bytes` : undefined]]);
+        appendInfoGrid(container, [['Host', data.host ?? '127.0.0.1'], ['Port', data.port], ['Max Packet', data.maxPacketSize ? `${data.maxPacketSize} bytes` : undefined]]);
         appendMany([['Inbound Message', resolveMessagePayload(data.messages?.inbound)], ['Outbound Message', resolveMessagePayload(data.messages?.outbound)], ['Message Schema', resolveMessagePayload(data.message)]]);
     }
     return container;
 }
+function appendStreamProjectionDiagnostics(container, projections) {
+    if (!projections || typeof projections !== 'object')
+        return;
+    const labels = {
+        httpSse: 'HTTP / SSE',
+        websocket: 'WebSocket',
+        grpc: 'gRPC',
+    };
+    const entries = Object.entries(projections);
+    if (entries.length === 0)
+        return;
+    const section = doc.createElement('div');
+    section.className = 'endpoint-subsection stream-projection-diagnostics';
+    section.innerHTML = '<div class="subsection-label">Projection diagnostics</div>';
+    const grid = doc.createElement('div');
+    grid.className = 'projection-diagnostic-grid';
+    for (const [name, diagnostic] of entries) {
+        const declaredStatus = String(diagnostic?.status ?? '');
+        const status = ['preserved', 'adapted', 'unsupported'].includes(declaredStatus)
+            ? declaredStatus
+            : 'unsupported';
+        const card = doc.createElement('div');
+        card.className = `projection-diagnostic projection-${status}`;
+        const details = [
+            diagnostic?.transport,
+            diagnostic?.resumeCursor ? `resume: ${diagnostic.resumeCursor}` : undefined,
+            diagnostic?.recordCursor ? `records: ${diagnostic.recordCursor}` : undefined,
+            diagnostic?.snapshot ? `snapshot: ${diagnostic.snapshot}` : undefined,
+        ].filter(Boolean);
+        card.innerHTML = `<div class="projection-diagnostic-heading"><strong>${esc(labels[name] ?? name)}</strong><span>${esc(status)}</span></div>${details.length ? `<div class="projection-diagnostic-details">${details.map(esc).join(' · ')}</div>` : ''}${diagnostic?.reason ? `<div class="projection-diagnostic-reason">${esc(diagnostic.reason)}</div>` : ''}`;
+        grid.appendChild(card);
+    }
+    section.appendChild(grid);
+    container.appendChild(section);
+}
 function parameterMapToSchema(parameters) {
     if (!parameters || typeof parameters !== 'object' || Object.keys(parameters).length === 0)
         return null;
@@ -2485,19 +2556,10 @@ function credentialStorageKey(schemeName) {
     return `raffel-docs:auth:${encodeURIComponent(selectedEnvironmentUrl)}:${encodeURIComponent(schemeName)}`;
 }
 function readStoredCredential(schemeName) {
-    try {
-        const value = win.sessionStorage?.getItem?.(credentialStorageKey(schemeName));
-        return value ? JSON.parse(value) : {};
-    }
-    catch {
-        return {};
-    }
+    return { ...(credentialMemory.get(credentialStorageKey(schemeName)) ?? {}) };
 }
 function storeCredential(schemeName, value) {
-    try {
-        win.sessionStorage?.setItem?.(credentialStorageKey(schemeName), JSON.stringify(value));
-    }
-    catch { /* unavailable storage */ }
+    credentialMemory.set(credentialStorageKey(schemeName), { ...value });
 }
 function authSchemeKind(scheme) {
     if (scheme?.type === 'http' && String(scheme.scheme).toLowerCase() === 'bearer')
@@ -2718,6 +2780,9 @@ async function startOAuthAuthorization(schemeName, flowName, flow, fieldset) {
     const state = randomOAuthState();
     const authorization = new URL(flow.authorizationUrl);
     const popup = win.open?.('', 'raffel-oauth', 'popup,width=540,height=720');
+    if (!popup) {
+        throw new Error('OAuth authorization requires popups so credentials can remain memory-only.');
+    }
     authorization.searchParams.set('response_type', flowName === 'implicit' ? 'token' : 'code');
     authorization.searchParams.set('client_id', value('clientId'));
     authorization.searchParams.set('redirect_uri', redirectUri);
@@ -2731,23 +2796,15 @@ async function startOAuthAuthorization(schemeName, flowName, flow, fieldset) {
         authorization.searchParams.set('code_challenge', pkce.challenge);
         authorization.searchParams.set('code_challenge_method', pkce.method);
     }
-    try {
-        win.sessionStorage?.setItem?.(`${credentialStorageKey(schemeName)}:pending`, JSON.stringify({
-            schemeName, flowName, state, redirectUri, tokenUrl: flow.tokenUrl,
-            clientId: value('clientId'), clientSecret: value('clientSecret'), scopes: value('scopes'),
-            codeVerifier,
-        }));
-    }
-    catch { /* unavailable storage */ }
-    if (popup) {
-        if (typeof popup.location?.replace === 'function')
-            popup.location.replace(authorization.toString());
-        else
-            popup.location = authorization.toString();
-    }
-    else {
-        win.location?.assign?.(authorization.toString());
-    }
+    pendingOAuthMemory.set(state, {
+        schemeName, flowName, state, redirectUri, tokenUrl: flow.tokenUrl,
+        clientId: value('clientId'), clientSecret: value('clientSecret'), scopes: value('scopes'),
+        codeVerifier,
+    });
+    if (typeof popup.location?.replace === 'function')
+        popup.location.replace(authorization.toString());
+    else
+        popup.location = authorization.toString();
 }
 function appendOAuthFlowFields(form, schemeName, scheme, stored) {
     Object.entries(scheme.flows ?? {}).forEach(([flowName, flow]) => {
@@ -2843,19 +2900,8 @@ function oauthCallbackParams() {
 function findPendingOAuth(state) {
     if (!state)
         return null;
-    for (const schemeName of Object.keys(spec?.components?.securitySchemes ?? {})) {
-        try {
-            const key = `${credentialStorageKey(schemeName)}:pending`;
-            const raw = win.sessionStorage?.getItem?.(key);
-            if (!raw)
-                continue;
-            const pending = JSON.parse(raw);
-            if (pending.state === state)
-                return { ...pending, key };
-        }
-        catch { /* ignore malformed pending state */ }
-    }
-    return null;
+    const pending = pendingOAuthMemory.get(state);
+    return pending ? { ...pending } : null;
 }
 async function finishOAuthAuthorization(params) {
     const pending = findPendingOAuth(params.get('state'));
@@ -2898,10 +2944,7 @@ async function finishOAuthAuthorization(params) {
         scopes: pending.scopes,
         tokenUrl: pending.tokenUrl,
     });
-    try {
-        win.sessionStorage?.removeItem?.(pending.key);
-    }
-    catch { /* unavailable storage */ }
+    pendingOAuthMemory.delete(pending.state);
     render();
 }
 function clearOAuthCallbackLocation() {
@@ -3652,7 +3695,10 @@ async function renderMermaidDiagrams(root = doc) {
         const id = `raffel-mermaid-${Date.now()}-${index}`;
         Promise.resolve(mermaid.render(id, source))
             .then((result) => {
-            diagram.innerHTML = typeof result === 'string' ? result : result.svg;
+            const safeSvg = parseMermaidSvg(typeof result === 'string' ? result : result.svg);
+            if (!safeSvg)
+                throw new Error('Mermaid returned invalid SVG output.');
+            diagram.replaceChildren(safeSvg);
             result?.bindFunctions?.(diagram);
             diagram.dataset.mermaidRendered = 'true';
             diagram.classList.remove('mermaid-fallback', 'mermaid-error');
@@ -3666,6 +3712,26 @@ async function renderMermaidDiagrams(root = doc) {
         });
     });
 }
+function parseMermaidSvg(markup) {
+    const Parser = win.DOMParser;
+    if (typeof Parser !== 'function')
+        return null;
+    const parsed = new Parser().parseFromString(String(markup ?? ''), 'image/svg+xml');
+    const svg = parsed?.documentElement;
+    if (!svg || String(svg.localName).toLowerCase() !== 'svg')
+        return null;
+    svg.querySelectorAll?.('script, foreignObject, iframe, object, embed, link')?.forEach((node) => node.remove());
+    [svg, ...Array.from(svg.querySelectorAll?.('*') ?? [])].forEach((element) => {
+        for (const attribute of Array.from(element.attributes ?? [])) {
+            const name = String(attribute.name).toLowerCase();
+            const value = String(attribute.value).trim().toLowerCase();
+            if (name.startsWith('on') || ((name === 'href' || name === 'xlink:href') && !value.startsWith('#'))) {
+                element.removeAttribute(attribute.name);
+            }
+        }
+    });
+    return doc.importNode?.(svg, true) ?? svg.cloneNode(true);
+}
 /**
  * Wrap a freshly rendered Mermaid SVG in a viewer overlay:
  *   • toolbar (zoom in/out/reset/fullscreen) — fades in on hover