@appport/sdk
The curated TypeScript API for the AppPort protocol.
It exposes application contracts, capability handlers, manifests, clients, servers, authorization primitives, and supported transports without coupling application code to a URL, process, transport, storage engine, or platform.
import { createClient, createHttpTransport } from "@appport/sdk";
const app = createClient({
transport: createHttpTransport({ url: "/appport" })
});
Node-only hosting helpers are exported from @appport/sdk/node.
@appport/sdk is the convenience façade: it aggregates lower-level protocol,
client, server, and transport packages, and it keeps AppPort.discover() wired to
the built-in HTTP and WebSocket transports. It is not the foundational architecture
layer; lower-level packages do not depend on the SDK.
Secure discovery (1.2.0)
import { AppPort } from "@appport/sdk";
// Inspect what an application publishes and verify its references. Connects to nothing, sends no credentials, invokes nothing.
const found = await AppPort.discoverApplication({ origin: "https://app.example.com", pins: recordedPins, timeoutMs: 10_000 });
found.state; // "not-published" | "unavailable" | "malformed" | "unresolved" | "reference-verified"
found.established; // { publisherTrust: false, authorization: false, approval: false, invoked: false } always
// Connect a client to a host you chose.
const client = await AppPort.discover({ origin: "https://app.example.com", sessionId });
reference-verified means the published references are consistent with the authoritative manifest. It does not mean the publisher is
trusted, that you are authorized, that an approval was obtained, or that an operation is safe. AppPort defines no signature for application
manifests, and it neither collects nor checks approvals. Mapping-signature trust (@appport/integration) is not production-ready.
Behavior change in 1.2.0: redirects and origins are refused by default
AppPort.discover and the HTTP transport used to follow redirects and to use any transport endpoint a discovery document advertised, so a
307 or a document naming another origin sent the session id and request body there. They now refuse both:
| You need | Do |
|---|---|
| The old redirect-following behavior, for an origin you operate | redirects: "follow" |
| A transport endpoint on another origin | allowOrigins: ["https://api.example.com"] |
| A larger discovery document than 1 MiB | maxDocumentBytes |
| A deadline or cancellation | timeoutMs, signal |
An http to https redirect is a different origin: connect to the https origin directly.
Canonical capabilities (1.3.0)
defineCapability({ fulfills: [claimFor(contract, "order.hold", 1)] }) declares that a capability fulfils a canonical capability, and an
application's requirements may name one with canonical: { contract }. A claim is evaluated before it is used and grants no authority.
Registering canonical contracts, discovering providers, resolving canonical requirements and binding them are @appport/core APIs; see its
README and spec/fulfillment-1.md.
Node-only TypeScript
The root @appport/sdk and @appport/sdk/node type-check in a Node-only project (lib: ["ES2023"], no DOM, skipLibCheck: false).
The MCP bridge exports (createMcpBridge, toMcpTools, ...) stay available from the root. The MCP server is not part of the SDK;
import it from @appport/mcp, and note that the MCP SDK it uses needs the DOM HeadersInit type (see that package's README).
Agent Skill
This package carries the official AppPort Agent Skill at skills/appport, matching this SDK version. The skill is optional, so the SDK does
not install what only the skill needs: the skill imports @appport/protocol and @appport/integration directly, and your project must
depend on them itself (a package manager that does not hoist, such as pnpm, will not expose a transitive copy). To install it for Claude Code:
npm install @appport/sdk @appport/protocol @appport/integration
mkdir -p .claude/skills && cp -R node_modules/@appport/sdk/skills/appport .claude/skills/appport # one project
mkdir -p ~/.claude/skills && cp -R node_modules/@appport/sdk/skills/appport ~/.claude/skills/appport # your user
node .claude/skills/appport/scripts/check-requirements.mjs
If the check reports a package as (not installed), its output includes an install command that fixes it.
Only Claude Code is verified. The skill is guidance, not enforcement. It needs @appport/sdk 1.2.0+, @appport/protocol 1.1.0+ and
@appport/integration 1.1.0+ (the first releases containing secure discovery).