@unbrained/pm-cli 2026.8.25 → 2026.8.27

package/dist/sdk/mcp/apps.js

@@ -0,0 +1,154 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e6c49c89-781e-59a3-9c19-6a1c40424587")}catch(e){}}();
+import { PM_MCP_ERROR_CODES, PmMcpProtocolError, isMcpRecord, } from "./protocol.js";
+/** Stable MCP Apps extension identifier. */
+export const PM_MCP_APPS_EXTENSION = "io.modelcontextprotocol/ui";
+/** Stable MCP Apps specification revision implemented by pm. */
+export const PM_MCP_APPS_SPEC_VERSION = "2026-01-26";
+/** Official MIME type for MCP App HTML resources. */
+export const PM_MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+/** Server-side MCP Apps capability advertised through discovery. */
+export const PM_MCP_APPS_SERVER_CAPABILITY = Object.freeze({
+    specVersion: PM_MCP_APPS_SPEC_VERSION,
+    mimeTypes: [PM_MCP_APP_MIME_TYPE],
+});
+/**
+ * Resolve whether a request negotiated MCP Apps, rejecting malformed explicit
+ * declarations instead of silently serving a different extension revision.
+ */
+export function hasPmMcpAppsCapability(context) {
+    const extensions = context.clientCapabilities.extensions;
+    if (!isMcpRecord(extensions))
+        return false;
+    const declaration = extensions[PM_MCP_APPS_EXTENSION];
+    if (declaration === undefined)
+        return false;
+    if (!isMcpRecord(declaration)) {
+        throw new PmMcpProtocolError("Invalid MCP Apps client capability", PM_MCP_ERROR_CODES.missingRequiredClientCapability, { requiredCapabilities: { extensions: { [PM_MCP_APPS_EXTENSION]: PM_MCP_APPS_SERVER_CAPABILITY } } });
+    }
+    const mimeTypes = declaration.mimeTypes;
+    const specVersion = declaration.specVersion;
+    if (!Array.isArray(mimeTypes) ||
+        !mimeTypes.includes(PM_MCP_APP_MIME_TYPE) ||
+        (specVersion !== undefined && specVersion !== PM_MCP_APPS_SPEC_VERSION)) {
+        throw new PmMcpProtocolError("Unsupported MCP Apps client capability", PM_MCP_ERROR_CODES.missingRequiredClientCapability, { requiredCapabilities: { extensions: { [PM_MCP_APPS_EXTENSION]: PM_MCP_APPS_SERVER_CAPABILITY } } });
+    }
+    return true;
+}
+const PRIVATE_APP_RESOURCE_META = {
+    csp: { connectDomains: [], resourceDomains: [], frameDomains: [] },
+    permissions: {},
+    prefersBorder: true,
+};
+/** Canonical optional pm MCP Apps. */
+export const PM_MCP_APP_CONTRACTS = Object.freeze([
+    {
+        id: "context",
+        name: "Context explorer",
+        description: "Inspect bounded project context, provenance, omissions, and token accounting.",
+        toolName: "pm_context",
+        uri: "ui://pm/context.html",
+    },
+    {
+        id: "graph",
+        name: "Relationship graph",
+        description: "Explore typed relationships, explaining paths, and graph-governance evidence.",
+        toolName: "pm_graph",
+        uri: "ui://pm/graph.html",
+    },
+    {
+        id: "plan",
+        name: "Plan and milestone view",
+        description: "Review durable plan steps, dependencies, decisions, discoveries, and validation state.",
+        toolName: "pm_plan",
+        uri: "ui://pm/plan.html",
+    },
+    {
+        id: "assurance",
+        name: "Assurance dashboard",
+        description: "Inspect validation verdicts, evidence, omissions, and actionable recovery paths.",
+        toolName: "pm_validate",
+        uri: "ui://pm/assurance.html",
+    },
+    {
+        id: "operations",
+        name: "Long-operation view",
+        description: "Inspect durable test and operation results without creating a second task store.",
+        toolName: "pm_test",
+        uri: "ui://pm/operations.html",
+    },
+].map((contract) => ({
+    ...contract,
+    toolMeta: {
+        resourceUri: contract.uri,
+        visibility: ["model", "app"],
+    },
+    resourceMeta: PRIVATE_APP_RESOURCE_META,
+})));
+/** Return the app contract for a resource URI. */
+export function findPmMcpAppByUri(uri) {
+    return PM_MCP_APP_CONTRACTS.find((contract) => contract.uri === uri);
+}
+/** Attach negotiated MCP App metadata to matching tool definitions. */
+export function decoratePmMcpToolsWithApps(tools) {
+    const appsByTool = new Map(PM_MCP_APP_CONTRACTS.map((contract) => [contract.toolName, contract]));
+    return tools.map((tool) => {
+        const app = appsByTool.get(tool.name);
+        return app
+            ? {
+                ...tool,
+                _meta: { ...tool._meta, ui: app.toolMeta },
+            }
+            : { ...tool };
+    });
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+/**
+ * Render a self-contained, sandbox-compatible MCP App document.
+ *
+ * The view keeps no durable state and exposes no mutation control. It receives
+ * the authoritative tool input/result from the host, bounds large rendering,
+ * and presents the text fallback when structured content is unavailable.
+ */
+export function renderPmMcpAppHtml(contract) {
+    const title = escapeHtml(contract.name);
+    const description = escapeHtml(contract.description);
+    const appInfo = JSON.stringify({
+        name: `pm-${contract.id}-view`,
+        version: PM_MCP_APPS_SPEC_VERSION,
+    });
+    const protocolVersion = JSON.stringify(PM_MCP_APPS_SPEC_VERSION);
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>${title}</title>
+  <style>
+    :root{color-scheme:light dark;--ink:#172554;--muted:#526078;--panel:#f8fafc;--line:#cbd5e1;--signal:#0f766e;--accent:#4338ca;--danger:#b91c1c;font-family:Inter,ui-sans-serif,system-ui,sans-serif}
+    @media(prefers-color-scheme:dark){:root{--ink:#e0e7ff;--muted:#a8b3c7;--panel:#111827;--line:#334155;--signal:#5eead4;--accent:#a5b4fc;--danger:#fca5a5}}
+    *{box-sizing:border-box}body{margin:0;background:var(--panel);color:var(--ink)}main{display:grid;gap:1rem;padding:clamp(.9rem,3vw,1.5rem);max-width:76rem;margin:auto}header{display:grid;gap:.35rem;border-bottom:1px solid var(--line);padding-bottom:.8rem}h1{font-size:clamp(1.2rem,3vw,1.75rem);line-height:1.1;margin:0;letter-spacing:-.02em}p{margin:0;color:var(--muted);line-height:1.5}.status{display:flex;align-items:center;gap:.5rem;font:600 .75rem ui-monospace,monospace;text-transform:uppercase;letter-spacing:.06em}.status::before{content:"";width:.55rem;height:.55rem;border-radius:50%;background:var(--signal)}section{border:1px solid var(--line);border-radius:.8rem;padding:1rem;background:color-mix(in srgb,var(--panel) 92%,var(--accent) 8%)}h2{font-size:.75rem;text-transform:uppercase;letter-spacing:.08em;margin:0 0 .7rem;color:var(--accent)}pre{white-space:pre-wrap;overflow-wrap:anywhere;max-height:34rem;overflow:auto;margin:0;font:500 .78rem/1.55 ui-monospace,SFMono-Regular,monospace;tab-size:2}button{justify-self:start;border:1px solid var(--accent);border-radius:.45rem;background:transparent;color:var(--accent);padding:.55rem .75rem;font:600 .78rem inherit;cursor:pointer}button:focus-visible{outline:3px solid var(--signal);outline-offset:2px}.notice{color:var(--danger)}@media(max-width:40rem){main{padding:.75rem}section{padding:.8rem}pre{max-height:24rem}}@media(prefers-reduced-motion:reduce){*{scroll-behavior:auto!important;transition:none!important}}
+  </style>
+</head>
+<body>
+<main>
+  <header><div class="status" id="status" role="status" aria-live="polite">Connecting to host</div><h1>${title}</h1><p>${description}</p></header>
+  <section aria-labelledby="summary-title"><h2 id="summary-title">Authoritative result</h2><pre id="result" tabindex="0">Waiting for the host tool result…</pre></section>
+  <section aria-labelledby="input-title"><h2 id="input-title">Invocation context</h2><pre id="input" tabindex="0">No tool input received.</pre></section>
+  <button type="button" id="copy">Copy visible evidence</button>
+</main>
+<script>
+(()=>{"use strict";const MAX=24000,status=document.querySelector("#status"),result=document.querySelector("#result"),input=document.querySelector("#input"),pending=new Map();let nextId=1;const render=(node,value)=>{let text;try{text=typeof value==="string"?value:JSON.stringify(value,null,2)}catch{text="Result could not be serialized."}if(text.length>MAX)text=text.slice(0,MAX)+"\\n\\n[View truncated at "+MAX+" characters; use the authoritative pm tool with a cursor or narrower projection.]";node.textContent=text};const send=(message)=>window.parent.postMessage(message,"*");window.addEventListener("message",event=>{if(event.source!==window.parent||!event.data||event.data.jsonrpc!=="2.0")return;const message=event.data;if(message.id!==undefined&&pending.has(message.id)){pending.get(message.id)(message);pending.delete(message.id);return}if(message.method==="ui/notifications/tool-input"||message.method==="ui/notifications/tool-input-partial"){render(input,message.params?.arguments??message.params);status.textContent="Input received"}else if(message.method==="ui/notifications/tool-result"){render(result,message.params);status.textContent="Current tool result"}else if(message.method==="ui/notifications/tool-cancelled"){status.textContent="Tool call cancelled";status.classList.add("notice")}else if(message.method==="ui/notifications/host-context-changed"&&message.params?.theme){document.documentElement.style.colorScheme=message.params.theme}});const request=(method,params)=>new Promise(resolve=>{const id=nextId++;pending.set(id,resolve);send({jsonrpc:"2.0",id,method,params})});document.querySelector("#copy").addEventListener("click",async()=>{const text=result.textContent+"\\n\\n"+input.textContent;try{await navigator.clipboard.writeText(text);status.textContent="Visible evidence copied"}catch{status.textContent="Clipboard permission unavailable";status.classList.add("notice")}});request("ui/initialize",{appInfo:${appInfo},appCapabilities:{},protocolVersion:${protocolVersion}}).then(message=>{if(message.error){status.textContent="Host rejected MCP App initialization";status.classList.add("notice");return}send({jsonrpc:"2.0",method:"ui/notifications/initialized"});status.textContent="Connected — awaiting authoritative result"})})();
+</script>
+</body>
+</html>`;
+}
+//# sourceMappingURL=apps.js.map
+//# debugId=e6c49c89-781e-59a3-9c19-6a1c40424587

package/dist/sdk/mcp/authorization.d.ts

@@ -0,0 +1,134 @@
+import type { PmMcpHttpHeaders } from "./transport.js";
+/** Authorization failure with an HTTP status and disclosure-safe context. */
+export declare class PmMcpAuthorizationError extends Error {
+    /** HTTP status required at the remote MCP boundary. */
+    readonly httpStatus: 401 | 403;
+    /** Optional RFC 6750 challenge safe to send to an unauthenticated client. */
+    readonly challenge?: string;
+    /** Create one remote authorization refusal. */
+    constructor(message: string, httpStatus: 401 | 403, challenge?: string);
+}
+/** RFC 9728 metadata served by a protected pm MCP resource. */
+export interface PmMcpProtectedResourceMetadata {
+    /** Canonical MCP resource URI used for token audience binding. */
+    resource: string;
+    /** Independent authorization-server issuers accepted by this resource. */
+    authorization_servers: string[];
+    /** Minimal scopes used for initial least-privilege authorization. */
+    scopes_supported?: string[];
+}
+/** Validated authorization-server discovery fields needed by MCP clients. */
+export interface PmMcpAuthorizationServerMetadata {
+    /** Exact issuer identifier. */
+    issuer: string;
+    /** Authorization endpoint for code flows. */
+    authorization_endpoint?: string;
+    /** Token endpoint used to redeem authorization codes. */
+    token_endpoint?: string;
+    /** PKCE methods advertised by the authorization server. */
+    code_challenge_methods_supported: string[];
+    /** Whether URL-form Client ID Metadata Documents are supported. */
+    client_id_metadata_document_supported?: boolean;
+    /** Deprecated dynamic-registration fallback endpoint. */
+    registration_endpoint?: string;
+}
+/** Discovery metadata after endpoint and PKCE validation succeeds. */
+export interface PmMcpValidatedAuthorizationServerMetadata extends PmMcpAuthorizationServerMetadata {
+    /** Validated HTTPS authorization endpoint for code flows. */
+    authorization_endpoint: string;
+    /** Validated HTTPS token endpoint used to redeem authorization codes. */
+    token_endpoint: string;
+}
+/** Client registration strategy ordered by current MCP preference. */
+export type PmMcpClientRegistrationMode = "pre_registered" | "client_id_metadata_document" | "dynamic" | "user_supplied";
+/** Bound access-token facts returned by a host-provided verifier. */
+export interface PmMcpAccessTokenClaims {
+    /** Stable authenticated principal without raw token material. */
+    principal: string;
+    /** Issuer that minted the token. */
+    issuer: string;
+    /** Intended resource audiences. */
+    audience: string | string[];
+    /** Granted OAuth scopes. */
+    scopes: string[];
+}
+/** Policy a Streamable HTTP adapter enforces before dispatching MCP. */
+export interface PmMcpHttpAuthorizationPolicy {
+    /** Exact accepted issuer. */
+    issuer: string;
+    /** Exact canonical MCP resource audience. */
+    resource: string;
+    /** Scopes required for this endpoint or operation. */
+    requiredScopes?: string[];
+    /** Protected-resource metadata location for RFC 6750 challenges. */
+    resourceMetadataUrl: string;
+    /** Validate an opaque or structured access token without passing it onward. */
+    verifyAccessToken: (token: string) => PmMcpAccessTokenClaims | Promise<PmMcpAccessTokenClaims>;
+}
+/** W3C trace context accepted from request `_meta`. */
+export interface PmMcpTraceContext {
+    /** W3C trace-parent value. */
+    traceparent?: string;
+    /** W3C trace-state value. */
+    tracestate?: string;
+    /** Allowlisted W3C baggage members only. */
+    baggage?: string;
+}
+/** Build and validate protected-resource metadata for a remote pm endpoint. */
+export declare function buildMcpProtectedResourceMetadata(input: {
+    resource: string;
+    authorizationServers: readonly string[];
+    scopes?: readonly string[];
+}): PmMcpProtectedResourceMetadata;
+/** Construct OAuth and OIDC discovery URLs in the MCP-required order. */
+export declare function buildMcpAuthorizationDiscoveryUrls(issuer: string): string[];
+/** Validate authorization-server metadata, exact issuer binding, and S256 PKCE. */
+export declare function validateMcpAuthorizationServerMetadata(value: unknown, expectedIssuer: string): PmMcpValidatedAuthorizationServerMetadata;
+/** Apply the current pre-registration, metadata-document, dynamic, prompt order. */
+export declare function selectMcpClientRegistrationMode(input: {
+    hasPreRegisteredClient: boolean;
+    metadata: Pick<PmMcpAuthorizationServerMetadata, "client_id_metadata_document_supported" | "registration_endpoint">;
+}): PmMcpClientRegistrationMode;
+/** Validate a present authorization-response issuer before code redemption. */
+export declare function validateMcpAuthorizationResponseIssuer(input: {
+    expectedIssuer: string;
+    responseIssuer?: string;
+    issuerParameterSupported?: boolean;
+}): void;
+/** Validate a self-hosted Client ID Metadata Document and exact redirect set. */
+export declare function validateMcpClientMetadataDocument(value: unknown, documentUrl: string): Record<string, unknown>;
+/** Build bounded dynamic-registration metadata for explicit legacy fallback. */
+export declare function buildMcpDynamicRegistrationMetadata(input: {
+    redirectUris: readonly string[];
+    applicationType: "native" | "web";
+    clientName: string;
+}): Record<string, unknown>;
+/** In-memory issuer-keyed credential primitive that never reuses cross-issuer state. */
+export declare class PmMcpIssuerCredentialStore<Credential extends Record<string, unknown>> {
+    #private;
+    /** Persist a cloned credential under the exact validated issuer. */
+    set(issuer: string, credential: Credential): void;
+    /** Read a cloned credential only for the exact issuer. */
+    get(issuer: string): Credential | undefined;
+    /** Remove credentials for one issuer during revocation or re-registration. */
+    delete(issuer: string): boolean;
+}
+/** Extract W3C trace context with strict syntax, size, and baggage allowlists. */
+export declare function extractMcpTraceContext(params: unknown, options?: {
+    baggageAllowlist?: readonly string[];
+}): PmMcpTraceContext;
+/** Run one request with trace context isolated from every concurrent request. */
+export declare function runWithMcpTraceContext<Result>(context: PmMcpTraceContext, callback: () => Result): Result;
+/** Read a defensive copy of the current request's trace context. */
+export declare function getActiveMcpTraceContext(): PmMcpTraceContext | undefined;
+/** Enforce bearer location, issuer, audience, and least-privilege scopes. */
+export declare function authorizeMcpHttpRequest(input: {
+    headers: PmMcpHttpHeaders;
+    requestUrl: string;
+    policy: PmMcpHttpAuthorizationPolicy;
+}): Promise<PmMcpAccessTokenClaims>;
+/** Create an exact opaque-token verifier without exposing token values in results. */
+export declare function createMcpStaticBearerVerifier(input: {
+    token: string;
+    claims: PmMcpAccessTokenClaims;
+}): (token: string) => PmMcpAccessTokenClaims;