@open-state/kit

The code embodiment of The Open State Constitution — the shared, constitution-compliant plumbing every Civic Access Protocol implementation uses, so conformance is inherited from working code rather than re-derived (and re-bugged) per project.

Every Open State implementation shares one lifecycle:

connect the citizen's account via on-device session capture → read/search → prepare a consequential action → the human confirms → execute up to the citizen's own final step (payment, submission) — never past it.

The kit is that lifecycle's constitutional core. Domain logic — the service's API, its bookings/trips/appointments — stays in each implementation.

Modules

| Module | Constitution | What it gives you | |---|---|---| | vault | Art. 1 (citizen sovereignty over credentials) | AES-256-GCM encrypted on-device session store. Key in a 0600 file beside the vault or a named env var. Tampering/corruption fails closed (reads as "no session"). No identity, no passwords — only cookies. | | confirm-gate | Art. 2 (the human decides) | prepare() holds nothing; the trusted MCP host shows its snapshotted preview directly to the citizen. Only explicit host-reported acceptance reaches execute(), which stops at the citizen's final step. | | capture | Arts. 1, 10 (assistive technology, not a bot) | Opens the citizen's own Chrome at the service's sign-in page; the citizen logs in themselves (and passes any human gate themselves, Art. 10.2). The implementation supplies only the service-specific "signed in" signal; the cookies go straight to the vault. |

Use

Install from npm (public, no auth):

npm install @open-state/kit       # or: pnpm add @open-state/kit

import {
  saveSession, loadSession, clearSession, cookieHeader, cookieValue,
  captureSession, confirmGated, createExclusiveRunner, previewFooter, text,
} from "@open-state/kit";

const sessionExclusive = createExclusiveRunner();

const VAULT = { dir: process.env.MY_HOME ?? defaultVaultDir("my-service"),
                keyEnvVar: "MY_SESSION_KEY" };

// connect_account: the citizen signs in themselves; we keep only the session.
const session = await captureSession({
  loginUrl: "https://service.example.gc.ca/login",
  cookieOrigin: "https://service.example.gc.ca",
  provider: "my_service",
  profileDir: join(VAULT.dir, "browser-profile"),
  isSignedIn: async (page) => page.evaluate(/* poll the app's own userInfo */),
});
saveSession(session, VAULT);

// A consequential action: one tool, two phases (Art. 2).
const handler = confirmGated(
  {
    async prepare(args) {
      // validate + assemble; hold/write/charge NOTHING
      return { summary: "Here's the booking I'll prepare: …",
               onConfirm: "confirm and I'll hold it and open your cart to pay yourself" };
    },
    async execute(args, prepared) {
      // args + prepared are the exact values retained from the preview
      return "Your cart is ready — review and pay yourself.";
    },
  },
  {
    // Return a non-secret digest identifying the current citizen/session.
    context: () => currentSessionFingerprint(),
    // Use a trusted host interaction such as MCP elicitation. Never ask the
    // model to assert that the citizen confirmed.
    approve: (preview) => requestCitizenApproval(preview),
    // The same runner must wrap every session save/clear in the implementation.
    exclusive: sessionExclusive,
  },
);

The approval callback is the security boundary. It must present summary and onConfirm through a trusted citizen-facing interaction such as MCP form elicitation. Tool arguments, model prose, and tool annotations are never proof of consent. The gate snapshots arguments and prepared data before approval and fails if the connected session changes while the citizen reviews the preview.

puppeteer-core is an optional peer dependency, loaded lazily — consumers that never capture a session never load it.

What does NOT belong here

Service clients, booking/trip/appointment models, provider constants, search logic. If you're unsure whether something is kit or domain, it's domain — promoting code later is cheap; pulling it back out from under three consumers is not. Promote only what is actually duplicated across ≥2 implementations.

Versioning

Strict semver, and consumers pin it. The kit's public API is a conformance surface: a breaking change here is a governance act (like amending the Constitution), released deliberately, never casually. It is published to npm as @open-state/kit (every Open State implementation — including the can-fed-camp-mcp reference implementation — installs the npm release). Each release is cut by pushing a kit-v* tag, which the publish-kit workflow publishes.

Tests

pnpm --filter @open-state/kit test

Offline and deterministic. The vault tests prove encryption-at-rest, fail-closed tampering, and key isolation; the gate tests prove nothing executes without explicit confirmation. Browser capture is exercised by the consuming implementations (it requires a real, citizen-driven Chrome — honestly outside what an offline test can claim, Art. 7.1).