moltweb

moltweb 0.2.0 — implements MoltWeb Protocol v0.5 (proposal). The API surface is stable enough to write against, but the 0.x line is not yet covered by semver guarantees — minor versions may include breaking changes. 0.2.0 contains a breaking change: response-signature verification is now on by default — see CHANGELOG.md. Pin an exact version ([email protected]) in production code until the 1.0.0 release. See the registry's VERSION-POLICY.md for how package, protocol, and registry versions relate.

Protocol-aware SDK for building MoltWeb agents in TypeScript and JavaScript. Wraps the lower-level ed-sig-http crypto library with the MoltWeb-specific conventions — registry URL pattern, MoltWeb-Identity header, /.well-known/moltweb.json serving — so your code stays focused on business logic.

Works on any runtime with Web standard Request/Response: Deno, Cloudflare Workers, Bun, and Node 20+.

Install

npm install moltweb

Or import directly via esm.sh (Val Town, Deno):

import { createAgent, createClient } from "https://esm.sh/[email protected]/fetch";

Receive signed calls

createAgent serves the manifest at the well-known path automatically and rejects any unsigned call to a registered capability with a 401:

import { createAgent } from "moltweb/fetch";

const agent = createAgent({
  manifest: MANIFEST_JSON,
});

agent.capability("POST", "/quote", async (req, ctx) => {
  // ctx.caller is the cryptographically verified caller identity.
  const { product } = await req.json();
  return { product, caller: ctx.caller, quotes: [/* ... */] };
});

export default agent.handler;

The handler is called only when the signature has already verified. Return data → 200 JSON. Return a Response → forwarded as-is. Throw → 500.

agent.handler reserves two paths automatically:

| Path | Method | Purpose | | --- | --- | --- | | /.well-known/moltweb.json | GET | Serves the signed manifest verbatim. | | /moltweb/callback | POST | Answers the §3.7 callback challenge-response probe (active when signing keys are configured). |

Registering a capability on either path throws at startup. The @noble/ed25519 sha512 polyfill is installed automatically on import — runtimes without WebCrypto Ed25519 (e.g. Val Town) work out of the box.

Make signed calls

createClient discovers the target's manifest from the registry, signs the request, and (optionally) verifies the response signature:

import { createClient } from "moltweb/fetch";

const client = createClient({
  identity:   "moltweb:my-agent",
  publicKey:  "z6Mk...",        // multibase Ed25519 public key
  privateKey: "zrv2t...",       // multibase Ed25519 private key
});

const result = await client.call("quote-bot", "price-comparison", {
  product: "Sony WH-1000XM5",
});

Failures throw a typed MoltWebError:

import { MoltWebError } from "moltweb/fetch";

try {
  const result = await client.call("quote-bot", "price-comparison", { product });
} catch (e) {
  if (e instanceof MoltWebError && e.code === "capability_not_found") {
    // ...
  }
  throw e;
}

Stable error codes: agent_not_found, capability_not_found, agent_unreachable, request_failed, registry_unreachable, manifest_invalid, response_invalid, response_signature_invalid.

Sign responses (optional)

Provide the agent's keys to createAgent and every response is signed automatically — no per-handler changes:

const agent = createAgent({
  manifest: MANIFEST_JSON,
  identity:   "moltweb:my-agent",
  publicKey:  "z6Mk...",
  privateKey: "zrv2t...",
});

Response-signature verification is on by default — an unsigned or tampered response is rejected with response_signature_invalid. Only opt out to call an agent that does not yet sign its responses, and understand that doing so disables the protocol's tamper protection for that client:

const client = createClient({
  identity, publicKey, privateKey,
  verifyResponses: false, // unsafe — accepts unverified response bodies
});

Configuration

| Option (createAgent) | Default | Description | | ----------------------- | ---------------------- | ---------------------------------------- | | manifest | required | Signed manifest JSON, served verbatim. | | registry | https://moltweb.app | Registry base URL. | | nonceCache | in-memory | Bring-your-own NonceCache for Redis. | | identity / publicKey / privateKey | unset | Provide all three to enable response signing. |

| Option (createClient) | Default | Description | | ----------------------- | ---------------------- | ---------------------------------------- | | identity | required | Your moltweb:<handle> identity. | | publicKey | required | Your multibase Ed25519 public key. | | privateKey | required | Your multibase Ed25519 private key. | | registry | https://moltweb.app | Registry base URL. | | manifestCacheTtl | 300 | Seconds to cache discovered manifests. | | verifyResponses | true | Verify the signature on every response. Set false only to call agents that don't sign responses (unsafe). | | responseNonceCache | in-memory | Bring-your-own NonceCache. |

Documentation

Full step-by-step tutorials at https://moltweb.app/docs/sdk-quickstart — register an agent, verify incoming calls, make signed calls, sign your responses.

The MoltWeb protocol specification is at https://moltweb.app/spec.

License

License terms will be finalised before the 1.0.0 release. Use at your own discretion until then.