@every-app/sdk 0.2.0 → 0.3.0-rc.1

package/dist/internal/remoteMcp.d.ts

@@ -0,0 +1,188 @@
+import { type ToolRisk } from "./tools.js";
+export declare const REMOTE_MCP_AUTH_KINDS: readonly ["none", "bearer", "header", "basic", "oauth"];
+export type RemoteMcpAuthKind = (typeof REMOTE_MCP_AUTH_KINDS)[number];
+/**
+ * How the Gateway authenticates to the server. `secret` is the name of
+ * the Gateway setting holding the value ({@link remoteMcpSecretName}),
+ * never the value. `oauth` is recorded so the app can say what the server
+ * wants; it is not served (the design's section 10).
+ */
+export type RemoteMcpAuth = {
+    kind: "none";
+}
+/** `Authorization: Bearer <value>`. */
+ | {
+    kind: "bearer";
+    secret: string;
+}
+/** `<header>: <prefix><value>`. */
+ | {
+    kind: "header";
+    secret: string;
+    header: string;
+    prefix?: string;
+}
+/** The value is `user:password`; sent as `Authorization: Basic <base64>`. */
+ | {
+    kind: "basic";
+    secret: string;
+} | {
+    kind: "oauth";
+};
+/**
+ * How a tool's risk is decided for the app. `annotations`: from the
+ * server's hints ({@link remoteToolRisk}); `read` or `write`: every tool,
+ * whatever it says. A per-tool override wins over all three.
+ */
+export declare const REMOTE_MCP_RISK_DEFAULTS: readonly ["annotations", "read", "write"];
+export type RemoteMcpRiskDefault = (typeof REMOTE_MCP_RISK_DEFAULTS)[number];
+/** The operator's say about one tool, keyed by the server's own tool name. */
+export interface RemoteMcpToolOverride {
+    risk?: ToolRisk;
+    /** False: left out of the Gateway's catalog; a call answers Unknown tool. */
+    enabled?: boolean;
+}
+export interface RemoteMcpBlock {
+    /** The one address the Gateway fetches and sends the credential to. */
+    url: string;
+    auth: RemoteMcpAuth;
+    risk: RemoteMcpRiskDefault;
+    tools: Record<string, RemoteMcpToolOverride>;
+    /** Bumped on every change of the block, so the snapshot re-lists. */
+    rev: number;
+}
+/** The manifest a remote MCP app's row stores. */
+export interface RemoteMcpManifest {
+    id: string;
+    name: string;
+    description: string;
+    remote: RemoteMcpBlock;
+}
+/** The manifest fields the Gateway reads, as a stored manifest has them. */
+export interface RemoteMcpManifestLike {
+    readonly remote?: unknown;
+}
+/** The default credential name for an app id: `treg` → `TREG_MCP_TOKEN`. */
+export declare function remoteMcpSecretName(id: string): string;
+/** Whether `id` can be a remote MCP app's id (kebab-case, at most 32, not reserved, not a built-in's). */
+export declare function remoteMcpIdProblem(id: string): string | null;
+/**
+ * An app id from the server's URL: the host's registrable name, `www`,
+ * `mcp` and `api` dropped (`https://mcp.deepwiki.com/mcp` → `deepwiki`,
+ * `https://treg.to/mcp/` → `treg`); null when nothing usable is left (an
+ * IP, `localhost`), in which case the caller asks for `--name`.
+ */
+export declare function remoteMcpIdFromUrl(url: string): string | null;
+export interface RemoteMcpUrlEnv {
+    /** The Gateway's own URL (`GATEWAY_URL`): its origin is refused, and `http://` opens local dev. */
+    gatewayUrl: string;
+    /** The apps' domain (`APP_BASE_DOMAIN`): every host under it is refused. */
+    appBaseDomain?: string | null;
+    /** The hosted third-party apps' domain (`THIRD_PARTY_DOMAIN`): likewise. */
+    thirdPartyDomain?: string | null;
+}
+/** The hosts whose keys the Gateway holds: a remote server is never one of them. */
+export declare function reservedUpstreamHosts(): string[];
+/**
+ * Why `url` can't be a remote MCP server's address, or null when it can:
+ * `https:` (or `http:` and loopback hosts only while the Gateway itself
+ * runs on `http://`, local dev), a host name rather than an address, no
+ * credentials or fragment in it, not the Gateway's own origin or one of
+ * its app hosts, and not a provider whose key the Gateway holds. The
+ * Gateway checks the stored URL again before every fetch, so a row edited
+ * by hand is refused the same way.
+ */
+export declare function remoteMcpUrlProblem(url: string, env: RemoteMcpUrlEnv): string | null;
+/** The credential name's problem, or null: in the family, and bounded. */
+export declare function remoteMcpSecretProblem(name: unknown): string | null;
+/** The auth block's problem, or the block as typed. */
+export declare function parseRemoteMcpAuth(raw: unknown): {
+    ok: true;
+    auth: RemoteMcpAuth;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * The `remote` block of a stored manifest, checked field by field (a row
+ * edited by hand must not make the Gateway send a credential anywhere the
+ * rules refuse), or why it can't be read. The URL is checked against the
+ * Gateway's environment by the caller ({@link remoteMcpUrlProblem}).
+ */
+export declare function parseRemoteMcpBlock(raw: unknown): {
+    ok: true;
+    block: RemoteMcpBlock;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * The `remote` block of a stored manifest, or null when the manifest has
+ * none (a built-in provider app's, a deployed app's) or it can't be read
+ * (such a row is a provider row the Gateway serves nothing for and lists
+ * as needing setup, see app-setup).
+ */
+export declare function remoteMcpOf(manifest: unknown): RemoteMcpBlock | null;
+/** Whether a stored manifest declares a remote MCP server at all (well-formed or not). */
+export declare function hasRemoteMcpBlock(manifest: unknown): boolean;
+/** The credential's setting name the block declares, if its kind takes one. */
+export declare function remoteMcpSecretOf(auth: RemoteMcpAuth): string | null;
+/**
+ * A description for a row that gave none: the server's origin, read as a
+ * sentence. The origin only: a path or query may carry something the
+ * registrar meant for the server alone, and the description reaches every
+ * member with access and every AI client.
+ */
+export declare function remoteMcpDefaultDescription(name: string, url: string): string;
+/**
+ * The operator's override for a server tool: by the server's name, or by
+ * a name that becomes the same ToolBus name ({@link normalizeRemoteToolName}),
+ * so a server that renames `send-mail` to `send_mail` can't bring a tool the
+ * operator turned off back under the same listed name.
+ */
+export declare function remoteToolOverride(block: Pick<RemoteMcpBlock, "tools">, upstreamName: string): RemoteMcpToolOverride | undefined;
+/** Whether a server's tool name can travel in an HTTP header (`Mcp-Name`): visible ASCII, bounded. */
+export declare function isHeaderSafeToolName(name: string): boolean;
+/** The manifest a remote MCP app's row stores, from what the registrar gave. */
+export declare function remoteMcpAppManifest(input: {
+    id: string;
+    name?: string | null;
+    description?: string | null;
+    remote: RemoteMcpBlock;
+}): RemoteMcpManifest;
+/** How a tool got its risk: the server's hint, the app's default, the operator's override, or the fallback. */
+export type RemoteToolRiskSource = "hint" | "app" | "override" | "default";
+/**
+ * A tool's risk for the Gateway. An override wins; then the app's `read`
+ * or `write` default; then the server's hints, read conservatively: an
+ * explicit `readOnlyHint: true` is `read`, an explicit `destructiveHint:
+ * true` is `destructive` (hidden until approvals exist), and anything
+ * else, a missing hint included, is `write`. The spec's missing-means-true
+ * default for `destructiveHint` is not followed: it would hide every
+ * unhinted tool.
+ */
+export declare function remoteToolRisk(hints: {
+    readOnlyHint?: unknown;
+    destructiveHint?: unknown;
+} | undefined, block: Pick<RemoteMcpBlock, "risk" | "tools">, upstreamName: string): {
+    risk: ToolRisk;
+    source: RemoteToolRiskSource;
+};
+/** Whether the operator left the tool on (the default). */
+export declare function remoteToolEnabled(block: Pick<RemoteMcpBlock, "tools">, upstreamName: string): boolean;
+/**
+ * A server's tool name as the ToolBus lists it: lowercase snake_case, at
+ * most 48 characters (`TOOL_NAME_PATTERN`). camelCase is split
+ * (`getUser` → `get_user`), `-`, `.`, `/` and spaces become `_`, anything
+ * else is dropped, runs of `_` collapse, and a leading digit gets a `t_`
+ * in front. Null when nothing usable is left.
+ */
+export declare function normalizeRemoteToolName(name: string): string | null;
+/**
+ * The request headers that carry the credential for `auth`, from the
+ * setting's value. The value never appears anywhere else.
+ */
+export declare function remoteMcpAuthHeaders(auth: RemoteMcpAuth, value: string): Record<string, string>;
+/** Plain words for an auth kind, for lists and dialogs. */
+export declare function remoteMcpAuthLabel(auth: RemoteMcpAuth): string;
+//# sourceMappingURL=remoteMcp.d.ts.map

package/dist/internal/remoteMcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteMcp.d.ts","sourceRoot":"","sources":["../../src/internal/remoteMcp.ts"],"names":[],"mappings":"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"}