npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@kigenka/shokai

v0.6.0

Published

Agents, introduced properly. Reference TypeScript SDK for Shōkai, the open protocol that gives online places a door for agents: signed Shōkai cards, vouches and envelopes, door policy, visit reports, and a gate that puts a Shōkai door in front of any MCP

Readme

@kigenka/shokai

The reference TypeScript SDK for Shōkai, the agent introduction protocol (package 0.6.0; specification v0.5.0, wire tag shokai/0.5; the SDK's compiled code is unchanged from 0.5.1): signed Shōkai cards, mandates, vouches and envelopes; doors and representatives; visit reports; a gate that puts a Shōkai door in front of any MCP server; and the shokai-conformance runner.

Install: npm install @kigenka/[email protected]. The quickstart (spec/QUICKSTART.md in this package) walks through it.

The specification ships in this package, in spec/: SPEC.md, the types (protocol-shapes.ts), the conformance checklist and golden traces (conformance/golden-traces.md), the test vectors, the extensions, the threat model, the changelog and the patent and trademark policies. spec/docs/SPEC-DETAIL.md is the canonical normative text (every MUST and check id), and section numbers such as §3.1 refer to it. spec/SPEC.md is the 15-minute short core of the same rules; where they differ, SPEC-DETAIL wins.

See a visit first

npx @kigenka/[email protected] demo
                                # npx --package=./kigenka-shokai-0.6.0.tgz shokai demo

A door, with its host representative, and a visiting representative on 127.0.0.1, printed as the visit happens: the ritual, a pass, an order within a 10.00 USD mandate, an order past it refused (by the representative, and by the door when sent anyway), and the report home. A couple of seconds for the visit itself (the first npx run also downloads the package); fictional actors, keys made for the run, nothing leaves the machine.

Put a door in front of your site

Two ways in, one door. Both write the same shokai/house.json and run the same commands, so they make the same door with the same house digest.

By hand. Describe the place in shokai/house.json (npx --no-install shokai house new writes one to fill in), then:

npx --no-install shokai house check      # what's left to fix
npx --no-install shokai house preview    # the door and its leaflet, as you'll sign them
npx --no-install shokai init             # the door's files for your stack (express, hono, next, node or static)
npx --no-install shokai host-card request   # the Shōkai host card, for you to sign with your passkey on the signing page
npx --no-install shokai host-card verify    # after signing: the door can open

By your agent. Tell your agent "Add a Shōkai door to my site." The instruction set ships in this package (agent-install/v1/AGENT-INSTALL.md, and install-manifest.json for machines; npx --no-install shokai agent-guide prints it). The agent detects the stack, has a short setup conversation with you about your place, its rules and its leaflet, runs the same checks and init, and stops at the one step only you can do: signing the Shōkai host card with your passkey.

Or in code. One line in front of an app (these snippets run as written: examples/drop-in/snippets/check.mjs in the source repository):

import express from "express";
import { createDoor, shokaiDoor } from "@kigenka/shokai";

const door = createDoor({
  name: "kettle", displayName: "Kettle & Leaf", category: "store", baseUrl: "https://kettle.example/shokai",
  purposes: [{ code: "visitation", statement: "Looking at our teas and asking about them." }],
  actions: [{ action: "tea.browse", purposes: ["visitation"], level: "discover" }],
  leaflet: { about: "Kettle & Leaf is a small tea shop. We sell loose-leaf tea by the gram.", hostName: "Suzu" },
  preset: "standard",
  approvedBy: { name: "Mika Tanabe", role: "Owner" },
});
const app = express();
app.use(shokaiDoor(door));   // the door at /shokai, and /.well-known/shokai. Mount it BEFORE express.json()
app.use(express.json());     // your own parser comes after the door

The door checks the original request bytes (SPEC §11.3, C284: duplicate member names and non-canonical numbers are refused before any digest or signature). Mount shokaiDoor() before any JSON body parser. If a parser must run first, keep the bytes: app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } })). A body that was only parsed (no req.rawBody) is refused with ShokaiRawBodyError; it is never re-serialised.

Hono, Bun, Deno and Workers take door.fetch (a (Request) => Promise<Response> handler); Next.js takes export const { GET, POST, HEAD } = nextDoor(door) in app/shokai/[[...path]]/route.js; plain node:http takes door.handleHttp(req, res).

  • The leaflet. Agents without a Shōkai visitor card get a leaflet to take home to their owner: the shared Shōkai text (LEAFLET_SHARED, template shokai-leaflet/3) and the place's own words (about, up to three optional questions, a closing line, the host representative's name). It travels in the lobby's about and how, inside the house config, so the owner's Shōkai host card covers every word (house_digest, SPEC §2.3); <base>/start shows it as a page.
  • Presets. open (introductions welcome, never needed; anyone's vouch counts, never for money), standard (the default: only introducers you name count) and strict (an introduction from a named introducer for every purpose, purchases held for the visitor's owner, one-hour passes). Each maps to policy fields the protocol already has; policy still overrides.
  • Finding the door. discover(siteUrl) reads /.well-known/shokai (exact path, no query, https) or a <link rel="shokai"> in the page's head; door.wellKnown() is that document. bindToSite(site, discovery, hostCard) says whether a door is that site's own door: the site's file lists it and its Shōkai host card names the site. Both follow proposal P26 and its draft amendment A (proposals/P26-drop-in-door.md); neither is part of the v0.5.0 core.
  • State on serverless hosts. store: memoryStore() | fileStore(path) | kvStore({ get, set, cas }) keeps the durable state (§3.6) with a version check: if another instance wrote first, the answer is withheld (429, retry) and an MCP call is refused with a retry, never let through on stale counts. The store also holds the door's visits in progress (encounters, passes, held purchases, the MCP gate's single-use acts), so any instance can answer any message of a visit: no sticky sessions. fileStore takes a lock file for each write, so several processes may share one file; across machines, use kvStore with your service's compare-and-set. The whole state is one JSON value written after every message, so a very busy door wants a fast key-value store. Finished visits are pruned an hour after their pass ends (retainFinishedVisitsS, default 3600), so the state stays the size of recent traffic; greeting nonces (up to 7 days) and each mandate's use (until it expires) are kept as §3.6 says, and signed messages more than 900 s old are discarded (maxMessageAgeS), so nothing forgotten can be replayed.
  • Events. onEvent: (e) => … gets arrival, leaflet, decision, pass, act, farewell, closed and busy, with machine fields only: no names, no owner or representative identifiers.

Put a door in front of an MCP server

The gate implements the MCP binding of the specification (SPEC §11.3): the Shokai-Act and Shokai-Seat headers, tools/list filtered to the pass, -32012 refusals with data.shokai, and the mcp-server link it adds to the place's listing. Any MCP server built with @modelcontextprotocol/sdk keeps working as it is. The gate adds a Shōkai door at /shokai: a representative arrives, presents its owner-signed Shōkai card and mandate, and gets a pass. Tool calls without a pass are refused with directions to the door, and each tools/call must carry a signed act for that exact tool and arguments. initialize and tools/list are part of the agent front, open to anyone like the listing (an admitted caller's tools/list is narrowed to its pass); to require a pass for listings too, pass the gate an open function that lets fewer methods through, e.g. shokaiGate(door, mcp, { open: (m) => m === "initialize" || m === "ping" || m.startsWith("notifications/") }).

import http from "node:http";
import { createDoor } from "@kigenka/shokai";
import { shokaiGate, statelessMcp } from "@kigenka/shokai/mcp";
import { buildNotesServer } from "./notes-server.js"; // returns your McpServer

const door = createDoor({ approvedBy: { name: "Ren Okabe", role: "Owner" }, name: "notes", displayName: "Lantern Notes", category: "x-tools",
  purposes: [{ code: "visitation", statement: "Reading and searching notes." }],
  actions: [{ action: "notes.search", purposes: ["visitation"], level: "discover", data_asks: [] },
            { action: "notes.read", purposes: ["visitation"], level: "discover", data_asks: [] }] });
http.createServer(shokaiGate(door, statelessMcp(buildNotesServer)))
  .listen(3000, () => door.setBaseUrl("http://127.0.0.1:3000/shokai"));

On the client side, the visiting representative visits the door, then uses the ordinary MCP client with a fetch that signs each act:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { createRepresentative, findPlace } from "@kigenka/shokai";
import { shokaiFetch } from "@kigenka/shokai/mcp";

const aya = createRepresentative({ ownerName: "Aya Linden", purposes: ["visitation"], actions: ["notes.search", "notes.read"] });
const visit = await aya.visit(await findPlace("http://127.0.0.1:3000/shokai", "notes"),
  { purpose: "visitation", actions: ["notes.search", "notes.read"], why: "Looking up my tea notes." });
const client = new Client({ name: "aya-representative", version: "1.0.0" });
await client.connect(new StreamableHTTPClientTransport(new URL("http://127.0.0.1:3000/mcp"), { fetch: shokaiFetch(visit) }));
await client.callTool({ name: "notes.read", arguments: { id: "tea" } });
await visit.farewell();
console.log(visit.report("en-US", { timeZone: "Europe/Lisbon" }).outcome_rendered.text); // the report home, from machine fields only

Before it sends any request, visit() checks the place against the listing entry it followed (§3.1): every reply must be signed by the listed representative and carry the encounter id the visit named (§2.2), and the place's Shōkai host card must be signed by the listed principal_id, name that representative, and prove possession over this visit's nonce. On a mismatch the visit ends with nothing asked; visit.placeCheck says why. When the place answers before it shows its Shōkai card (an early deny), nothing could be checked: placeCheck.ok is false and placeCheck.unchecked is true.

Spending within a limit

A visit that spends asks for purpose purchase with a max_amount. The limit goes into the mandate the owner signs and into the request, and the pass is never wider than either. Each spending act states its amount; the door counts it against the cap and refuses a spending act without one (REQUEST_INCOMPLETE).

const door = createDoor({ approvedBy: { name: "Ren Okabe", role: "Owner" }, /* … */ spendingActions: ["order.place"] }); // listed as spends: true

const visit = await aya.visit(place, { purpose: "purchase", actions: ["order.place"],
  limits: { max_amount: { value: "10.00", currency: "USD" }, max_operations: 3 },
  mandate: { statement: "Buy one tea, up to 10 USD.", validSeconds: 3600 } }); // the mandate's own scope and lifetime (default 1 day)
await client.callTool({ name: "order.place", arguments: { tea: "sencha", amount: { value: "6.00", currency: "USD" } } });
visit.report().spent; // [{ value: "6.00", currency: "USD" }]

A mandate's limits are for the whole errand, across visits (§5.1). The representative keeps a ledger per mandate (rep.ledger): a second visit() with the same purpose, actions and limits presents the mandate it already holds, so what's left carries over; an act beyond what's left isn't sent (the MCP call fails with data.shokai.refused_by: "representative"), and the door refuses it anyway (SEAT_SCOPE_EXCEEDED, C175). Each report covers every visit under its mandate (report().under_mandate, C176). Options: useMandate (one the owner signed on their device), mandate: { fresh: true } (a new allowance), and createRepresentative({ ledger: fileLedger("ledger.json"), owner, key, card }) to continue across runs.

Before sending, refusals, and what comes home

  • Checked before sending. Before each act the representative checks the pass's tool_allowlist (visit.checkSeatLocally, default on) and what remains of the mandate (visit.checkMandateLocally, default on). An act that doesn't fit isn't sent: visit.act() returns { refused_by: "representative", by: "seat" | "mandate", why }, and through shokaiFetch the MCP call fails with not sent: …. Turn either off only to test a door's own enforcement.
  • Each refusal says what it is. Every refused tools/call is JSON-RPC -32012 (SHOKAI_REFUSED, also exported as SHOKAI_NOT_SEATED). The message is specific (no pass: "get a pass first"; a tool outside the pass, with what it allows; a spending act with no amount; an amount in another currency; past what's left; an act that doesn't fit a live visit), and data.shokai carries refused_by (representative, door or gate), reason_code and, from the door, its act_decision. actRefusalMessage(tool, decision, seat, args) gives the same wording for your own gate.
  • What comes home. A signed object a tool returns (a visit stamp, a receipt) is kept in visit.broughtBack, verified against the listing's principal_id, and reported as report().brought_back with its envelope (report(locale, { broughtBack: "reference" }) for only the digest); the readable report says what was brought back and whether it verified (§8.2, C178). visit.keep(envelope) adds one by hand; visit.keepSigned = false turns it off.

Finding a place

findPlace(base, name?) takes the door's base URL, ending in /shokai (a trailing slash is fine), and the place's name (a machine slug like "notes"), not its display_name ("Lantern Notes"). It reads the listing at base + "/places"; without a name it returns the first place.

A full runnable example ships compiled in the package: node node_modules/@kigenka/shokai/dist/examples/toy-mcp/run.js. Its source is examples/toy-mcp/ in the source repository (npm run example there).

What's in the box

| Import | What | |---|---| | @kigenka/shokai | createDoor (listing, entry, lobby, inbox, passes, handleHttp; an owner-signed card, verifyDoorCard, withdrawCard, fromSigningPage), createRepresentative and Visit (the ritual, acts, farewell, report()), findPlace, sign / verifySigned, signCard (validDays, default 180; the skills use 90), signMandate, signVouch, generateRepresentativeKey, exportRepresentativeKey / importRepresentativeKey (the key as one line for a keyring), developmentPasskey | | @kigenka/shokai (owner helpers) | signCardRevocation (now, or standby: true to keep for a lost key, §2.6) and cardRevocationMessage, signOwnerLink (join two per-place identities for one place, both passkeys, ≤ 400 days, §2.8), passkeyRequest and signedFromPasskeyAssertion (server side of signing with a real passkey, A.1) | | @kigenka/shokai/browser | signWithPasskey(payload, { rpId }) in the owner's browser (WebCrypto and navigator.credentials, no Node built-ins), plus jcs and digestOf | | @kigenka/shokai/mcp | shokaiGate, statelessMcp, shokaiFetch, ShokaiGate (the adapter), actRefusalMessage, SHOKAI_REFUSED / SHOKAI_NOT_SEATED (JSON-RPC error −32012 for every refusal) |

When the MCP server doesn't carry out a call the gate let through (a JSON-RPC error, a tool result with isError, or a 4xx/5xx with no result), the gate releases what the act counted, its operation and amount together (§7.2, C187, C194). Pass releaseOn: "rpc-error" for tools that may act in part before reporting isError, or "never". Only JSON responses are inspected; with SSE responses the act stays counted. | @kigenka/shokai/core | The protocol core shared with the reference place server: verification, the deterministic gate, policy, the host, the inbound door, protocol types (import { Host, RealVerifier, SPEC_VERSION } from "@kigenka/shokai/core") | | @kigenka/shokai/conformance | The conformance runner as a library |

developmentPasskey() makes a software stand-in for an owner's passkey so examples and tests run without a device. createRepresentative() without owner or card uses one and signs its own Shōkai card (rep.isDevelopmentOwner is then true): never present that as the owner's signature. A real owner signs with a WebAuthn passkey (ES256, did:jwk); see SPEC Appendix A.1 and SIGNING.md.

The signing page isn't in this package. It lives in the source repository at reference/signing-page/ (a small dependency-free Node server). To try it without a phone, run its own test, node test/e2e.mjs, where a software authenticator stands in for the phone, on loopback only.

Keeping the representative's key. exportRepresentativeKey(key) gives one line of text; keep it in the system keyring (Linux secret-tool store, macOS security add-generic-password) or, failing that, in a file only the representative can read (chmod 600). Load it with importRepresentativeKey(text), which gives back the same did:key. Never print it or put it in chat or memory notes.

A door Shōkai card the owner signed (a person's door). By default createDoor() signs the door's Shōkai host card with a place key it makes (or the keys.principal you pass), which suits a shop or a service. For a person's own door, have the owner sign the "my door" Shōkai card on the signing page, then pass the file it wrote:

const door = createDoor({ name: "door-ines", displayName: "Ines's door", purposes, actions,
  keys: { rep: importRepresentativeKey(keyFromKeyring) },          // the representative key the card names
  card: JSON.parse(readFileSync("signed/1-door-card.json", "utf8")), // the signing page's file as is (one tap or one by one)
  ownerRpId: "sign.example.com",                                     // the signing origin you expect
  cardRevocations: [] });                                            // any withdrawal the owner signed

createDoor() verifies the Shōkai card as a door verifies a visiting representative's (verifyDoorCard()). It checks the owner's passkey signature against the Shōkai card's rp_id, including one-tap batches, plus the owner binding, the protocol, the dates, the representative key, and that the Shōkai card covers the door's purposes and actions. It throws SHOKAI_DOOR_CARD_INVALID for a tampered or mismatched Shōkai card, or SHOKAI_DOOR_CARD_REVOKED when one of cardRevocations withdraws it. The door's principal is then the owner (door.principalId). If the owner's signed revocation reaches the running door, delivered by anyone in a visit or handed over with door.withdrawCard(slip), the door stops answering (HTTP 503, an empty envelope) and lists nothing until it's started with a new Shōkai card. fromSigningPage() reads any item the page wrote.

Implementation and scaling

Simple core first, opt-in richness, and an in-process microbenchmark (not a load test): see docs/implementation-and-scaling.md and docs/benchmarks/core-vs-rich.md. Richness does not by itself guarantee performance.

Conformance runner

npx --no-install shokai-conformance http://127.0.0.1:3000/shokai             # core checks against a running door
npx --no-install shokai-conformance http://127.0.0.1:3000/shokai --ext all   # plus Visit receipts and Signed place listings
npx --no-install shokai-conformance http://127.0.0.1:3000/shokai --vectors   # plus the test vectors, run on the runner's own crypto (a URL can't reach a door's)
npx --no-install shokai-conformance ./my-door.js --vectors                   # a module exporting door / handler / createDoor and `implementation`: the vectors run on your crypto
npx --no-install shokai-conformance --self-test                              # the test vectors against the SDK's own crypto
npx --no-install shokai-conformance http://127.0.0.1:3000/shokai --mcp http://127.0.0.1:3000/mcp   # test the MCP binding even if the listing doesn't advertise it
npx --no-install shokai-conformance http://127.0.0.1:3000/shokai --spend 6.00 --spend-args '{"tea":"sencha"}'   # plus the money totals: a conformant door admits exactly ONE such order (use mock money)
npx --no-install shokai-conformance http://127.0.0.1:3000/shokai --place my-shop --hold-grace 2   # a v0.5.0 place: C231 checks just inside and outside its stated hold_grace_s
npx --no-install shokai-conformance https://example.com/shokai --visitor-fixtures ./signed-visitor \
    --place my-shop --spend 6.00 --spend-args '{"tea":"sencha"}'   # present a passkey-signed card and mandates; see below

A public door will refuse the runner's usual development-passkey visitor (reserved rp_id, CREDENTIAL_REQUIRED). To measure such a door with real owner signatures, pass a visitor card and mandates the owner already signed, plus the representative's key (never printed):

  • --card <file> --key <file> and one or more --mandate <role>=<file>, or
  • --visitor-fixtures <dir> containing visitor-card.json, visitor.key, and mandate-<role>.json (or a manifest.json). Optional probe files (or a probes map in the manifest) supply owner-signed material for mandate.cross, card.revoked, card.revoked_seat, neg.probing, and a closed-template card. The runner never re-signs them. neg.probing runs last: a pass bindNevers that principal for 180 days, and a pre-signed probe card is usually the same owner as the sitting card.

Known mandate roles: browse (non-spending ritual), purchase, c300 (well-signed min_protocol the literal string "0.5"), c301 (well-signed min_protocol shokai/0.6), ops1 (max_operations: 1 for C175), cap001 (a 0.01 spend cap), under_two (just under two --spend orders), overcap. The runner presents these as-is. It does not mint a development stand-in owner, does not re-sign a mandate, and does not mutate a signature to look well-signed. Checks that need a fresh owner signature the runner cannot produce (a card revocation, a re-signed mutated mandate, a live hold raise or decline, a deletion request, a second visitor card, a probing card) are reported SKIP with that reason. A SKIP is not a pass; it is not official evidence for that check. The default path (no these flags) is unchanged: the runner still mints a development owner, which is fine on loopback and against a door that allows reserved rp_ids.

For a place whose spec_ref is 0.5.0, the v050 checks (C230–C255) run too and count in the core verdict: wire tags, the house summary and its digest, conduct rules and structured classifier entries, idempotent repeats, payment card numbers, one Shōkai visitor card per encounter, farewells, deletion requests and receipts, and, where the Shōkai host card has the hold_purchases duty, over-limit holds and the one-purchase raise (C230–C232). Nothing is released without --spend; checks that need a fixture the door doesn't show (a start hook, a recording classifier, a full revocation store) are reported as skipped with the reason. The reference server's fernwood-v05 place is such a fixture.

The hold checks act with {amount, payment_ref}, or with --spend-args plus amount when you give it (then it is the action's whole argument set). An ok: false result (the action refused those arguments) skips a hold check rather than failing it. The place's own limit for the action is the highest offers[].max_amount for it in the house summary, capped by limits.max_amount. For C239, an HTTP 413 or 400 at the front (no ReplyEnvelope) counts as a bounded refusal.

The verdict is the core's (the MCP binding included where a place serves MCP); extension results are reported on their own and never make a door "NOT CONFORMANT". Exit status: 0 conformant, 1 a core check failed, 3 only a requested extension failed. --help lists the implementation functions --vectors calls.

Each check names the SPEC section and scenario it tests. The runner covers the core from the door's side (including checking the place against its listing, ritual.place_id, and that it answers in the visiting representative's encounter, ritual.encounter) and the Visit receipts and Signed place listings levels; the other extensions are tested by the reference implementation's suites. The exit code is non-zero if any check that ran fails.

API stability

The supported API is what this README documents: createDoor, createRepresentative, the owner helpers, shokaiGate/shokaiFetch/statelessMcp, the adapters, stores, discover, the house tools and the CLI. The root entry also exports about 150 other names (constant tables, ClaimGuard, runSystem1, toCents, ledgers and other building blocks) for the reference implementation, the conformance runner and the tests. Treat those as internal: some are marked @internal, none are covered by semver before 1.0, and they move under @kigenka/shokai/core in 0.6. The protocol core itself is @kigenka/shokai/core.

npm test runs only in the source repository (it syncs the core from reference/engawa/src and runs examples/traces/university.mjs). From the installed package, check it with npx --no-install shokai-conformance --self-test.

Development

The protocol core in src/core/ is generated from the reference place server (reference/engawa/src): don't edit it by hand. npm run sync regenerates it, and npm test fails if it drifts.

"private": true in this package's package.json is an intentional safety catch so a casual npm publish from the source tree cannot ship. The published tarball is built only by tools/pack-release.sh, which copies the package, strips private (and prepack) in that temporary copy, and packs; the repository file keeps private: true. See the repository's RELEASING.md.

npm ci
npm test   # sync check, typecheck, SDK, MCP gate and runner tests, conformance self-test

License

Apache-2.0 (see LICENSE and NOTICE, both shipped in the package). The Shōkai specification is also under Apache-2.0; a royalty-free patent commitment for final specification versions is drafted in the repository's PATENTS.md, and the use of the Shōkai name is covered by TRADEMARKS.md. The MCP SDK is an optional peer dependency, needed only for @kigenka/shokai/mcp.