@tiertwo/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tier Two
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @tiertwo/mcp
+
+The **Tier Two** MCP server. It gives an AI agent the ability to create accounts on
+merchant sites *as a specific, verified human* — after that human has paired the agent's
+device to their [Tier Two](https://trytiertwo.com) account and approves each signup.
+
+It runs as a stdio MCP server you launch with `npx`, exposes three tools, and mints
+short-lived signed signup tokens that merchants verify with
+[`@tiertwo/sdk`](https://www.npmjs.com/package/@tiertwo/sdk).
+
+## Add it to your agent
+
+Add the server to your host's MCP config. For Claude (Desktop / Code), in `mcpServers`:
+
+```jsonc
+{
+  "mcpServers": {
+    "tiertwo": {
+      "command": "npx",
+      "args": ["-y", "@tiertwo/mcp@0.1.0"],
+      "env": {
+        "VH_API_URL": "https://trytiertwo.com"
+      }
+    }
+  }
+}
+```
+
+- **`VH_API_URL`** points the server at the Tier Two backend. It defaults to
+  `https://trytiertwo.com`; set `http://localhost:3000` to run against a local backend.
+- **Pin the version** (`@tiertwo/mcp@0.1.0`), don't float `latest` — see
+  [Supply-chain hygiene](#supply-chain-hygiene) below.
+
+## First run: pairing
+
+To pair right away, run:
+
+```sh
+npx -y @tiertwo/mcp pair
+```
+
+It generates the device keypair, prints the pairing code + a pre-filled dashboard
+link, and waits until you confirm in the browser.
+
+Otherwise pairing happens lazily: the first time the agent uses a tool, the server
+generates a device keypair (the
+private key is stored in your **OS keychain**; only a non-secret device id lands in
+`$XDG_CONFIG_HOME/tiertwo/config.json`) and pairs it to your account:
+
+1. It surfaces a **pairing code**, a pre-filled **`/dashboard/pair` URL**, and a
+   6-digit **verification number** — inline through the host (MCP elicitation) where
+   supported, otherwise on stderr.
+2. You open the dashboard (signed in to your verified Tier Two account), confirm the
+   **device name** and that the **verification number matches**, and approve.
+3. The server polls until confirmed, then persists the device id. Pairing happens once
+   per machine + backend.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `get_identity` | Returns the paired human's verified status and claims (`verified`, `country`, `age_over_18`). The agent uses this to reason about eligibility before a signup. |
+| `request_human_approval` | Asks the human to approve a `(domain, action)` through the host. Never auto-approves; the approval is one-time and short-lived. |
+| `sign_signup_request` | Mints a short-lived verified-human signup token for `(domain, action)`. **Independently requires a fresh approval** — if none is held it triggers the prompt first, so signing can never skip human approval. Returns `{ token }` for the merchant to verify. |
+
+The approval gate is **host-mediated and un-skippable**: approval is collected through
+the host (elicitation, with an out-of-band browser fallback), and the backend's
+`/api/sign` independently requires a fresh approval. A model that calls
+`sign_signup_request` directly still triggers the human prompt.
+
+## Supply-chain hygiene
+
+`npx @tiertwo/mcp` runs whatever is `latest` each time, which means a compromised
+release would run on your machine automatically. Two mitigations:
+
+- **Pin a version** in your config (`@tiertwo/mcp@0.1.0`) rather than floating `latest`,
+  and bump deliberately.
+- Releases are published from CI with **npm provenance** (a signed, verifiable link from
+  the published tarball back to the exact GitHub commit + workflow), so a release that
+  didn't come from the real pipeline is detectable on the
+  [npm package page](https://www.npmjs.com/package/@tiertwo/mcp).
+
+See [`docs/ARCHITECTURE.md`](https://github.com/Jordan-M/verified-human/blob/master/docs/ARCHITECTURE.md)
+§11 (MCP) and §18.1 (un-skippable approval) for the design.

package/dist/api.d.ts

@@ -0,0 +1,126 @@
+import { type KeyObject } from "node:crypto";
+import { type DeviceAuthEnvelope, type DeviceClientMeta, type DevicePurpose, type ScopedAction } from "@tiertwo/shared";
+/** A fresh transport envelope: purpose + random 16B nonce (base64url) + current ts. */
+export declare function freshEnvelope(purpose: DevicePurpose): DeviceAuthEnvelope;
+/** A fresh envelope + a ScopedAction payload for the action-scoped endpoints. */
+export declare function freshScopedAction(purpose: DevicePurpose, domain: string, action: string, resource?: string): DeviceAuthEnvelope & ScopedAction;
+/** base64url Ed25519 signature over canonicalJSON(body) — the X-VH-Signature value. */
+export declare function signBody(privateKey: KeyObject, body: unknown): string;
+export type PairInit = {
+    publicKey: string;
+    name: string;
+    /** Client-claimed directory metadata (Stage 4.9) — informational only. */
+    client?: DeviceClientMeta;
+};
+export type PairInitResult = {
+    ok: true;
+    code: string;
+    verificationNumber: string;
+    url: string;
+    expiresAt: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export type PairStatus = {
+    status: "pending";
+} | {
+    status: "confirmed";
+    deviceId: string;
+} | {
+    status: "expired";
+} | {
+    status: "not_found";
+} | {
+    status: "error";
+};
+export type IdentityResult = {
+    ok: true;
+    verified: boolean;
+    country: string | null;
+    age_over_18: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+export type ApprovalResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type OOBRequestResult = {
+    ok: true;
+    requestId: string;
+    code: string;
+    url: string;
+    expiresAt: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export type ApprovalRequestStatus = {
+    status: "pending";
+} | {
+    status: "confirmed";
+} | {
+    status: "expired";
+} | {
+    status: "not_found";
+} | {
+    status: "error";
+};
+/** Outcome of opening a standing-access request (Stage 2b). */
+export type AccessRequestResult = {
+    ok: true;
+    requestId: string;
+    status: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Token mint outcome. `reason` mirrors /api/sign's documented failures. */
+export type SignResult = {
+    ok: true;
+    token: string;
+} | {
+    ok: false;
+    reason: "not_verified" | "access_required" | "unauthorized" | "bad_request" | "server_error" | "network";
+};
+export type ApiClientOptions = {
+    apiUrl: string;
+    privateKey: KeyObject;
+    deviceId?: string;
+    fetchImpl?: typeof fetch;
+    /** Client-claimed directory metadata (Stage 4.9), attached as the UNSIGNED
+     * X-VH-Client header on signed calls (informational only — see shared). */
+    clientMeta?: DeviceClientMeta;
+};
+export declare class ApiClient {
+    readonly apiUrl: string;
+    private readonly privateKey;
+    private readonly deviceId?;
+    private readonly fetchImpl;
+    private readonly clientMeta?;
+    constructor(opts: ApiClientOptions);
+    /** A copy bound to a paired deviceId, for signed calls after pairing. */
+    withDevice(deviceId: string): ApiClient;
+    private url;
+    /** POST a device-signed body. Returns the raw status + parsed JSON (or null). */
+    private postSigned;
+    pairInit(input: PairInit): Promise<PairInitResult>;
+    pairStatus(code: string): Promise<PairStatus>;
+    getIdentity(): Promise<IdentityResult>;
+    createApproval(domain: string, action: string, resource?: string): Promise<ApprovalResult>;
+    requestApprovalOOB(domain: string, action: string, resource?: string): Promise<OOBRequestResult>;
+    pollApprovalRequest(code: string): Promise<ApprovalRequestStatus>;
+    sign(domain: string, action: string, resource?: string): Promise<SignResult>;
+    /**
+     * Open a standing-access request (Stage 2b): ask an org admin to grant this agent
+     * lasting authorization for (domain, action, optional resource), with an optional
+     * reason. Enterprise-only — a consumer/no-org device gets `no_org`.
+     */
+    requestAccess(domain: string, action: string, resource?: string, reason?: string): Promise<AccessRequestResult>;
+    /** Map a raw response to a stable reason string (network, http_NNN, or backend reason). */
+    private reasonOf;
+}

package/dist/api.js

@@ -0,0 +1,227 @@
+// Signed HTTP client to the Tier Two backend. This is the device role: it builds a
+// device-signed body (a transport ENVELOPE — purpose/nonce/ts — plus, for scoped
+// endpoints, a ScopedAction payload), signs canonicalJSON(body) with the device's
+// Ed25519 key, and sends X-VH-Device + X-VH-Signature exactly as lib/deviceAuth.ts
+// verifies them (see apps/web/scripts/sign-e2e.ts — the proven reference). Every
+// signed call carries a fresh one-time nonce + current ts and a `purpose` that binds
+// it to one endpoint. All methods return discriminated unions and never throw on
+// HTTP/network failure (fail-closed).
+import { randomBytes, sign } from "node:crypto";
+import { canonicalJSON, CLIENT_META_HEADER, DEVICE_HEADER, SIGNATURE_HEADER, } from "@tiertwo/shared";
+/** A fresh transport envelope: purpose + random 16B nonce (base64url) + current ts. */
+export function freshEnvelope(purpose) {
+    return {
+        purpose,
+        nonce: randomBytes(16).toString("base64url"),
+        ts: Date.now(),
+    };
+}
+/** A fresh envelope + a ScopedAction payload for the action-scoped endpoints. */
+export function freshScopedAction(purpose, domain, action, resource) {
+    return {
+        ...freshEnvelope(purpose),
+        domain,
+        action,
+        ...(resource !== undefined ? { resource } : {}),
+    };
+}
+/** base64url Ed25519 signature over canonicalJSON(body) — the X-VH-Signature value. */
+export function signBody(privateKey, body) {
+    return sign(null, Buffer.from(canonicalJSON(body), "utf8"), privateKey).toString("base64url");
+}
+export class ApiClient {
+    apiUrl;
+    privateKey;
+    deviceId;
+    fetchImpl;
+    clientMeta;
+    constructor(opts) {
+        this.apiUrl = opts.apiUrl.replace(/\/$/, "");
+        this.privateKey = opts.privateKey;
+        this.deviceId = opts.deviceId;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.clientMeta = opts.clientMeta;
+    }
+    /** A copy bound to a paired deviceId, for signed calls after pairing. */
+    withDevice(deviceId) {
+        return new ApiClient({
+            apiUrl: this.apiUrl,
+            privateKey: this.privateKey,
+            deviceId,
+            fetchImpl: this.fetchImpl,
+            clientMeta: this.clientMeta,
+        });
+    }
+    url(path) {
+        return `${this.apiUrl}${path}`;
+    }
+    /** POST a device-signed body. Returns the raw status + parsed JSON (or null). */
+    async postSigned(path, 
+    // `reason` rides only on the access-request body (Stage 2b); it never touches the
+    // shared ScopedAction type. deviceAuth verifies the signature over the full body
+    // and asAccessRequest permits it, so the signed reason survives.
+    body) {
+        if (!this.deviceId)
+            throw new Error("postSigned requires a paired deviceId");
+        try {
+            const res = await this.fetchImpl(this.url(path), {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    [DEVICE_HEADER]: this.deviceId,
+                    [SIGNATURE_HEADER]: signBody(this.privateKey, body),
+                    // Unsigned, informational (Stage 4.9) — the signed body stays
+                    // byte-identical whether or not metadata rides along.
+                    ...(this.clientMeta
+                        ? { [CLIENT_META_HEADER]: JSON.stringify(this.clientMeta) }
+                        : {}),
+                },
+                body: JSON.stringify(body),
+            });
+            const json = (await res.json().catch(() => null));
+            return { status: res.status, json };
+        }
+        catch {
+            return { status: 0 }; // network/transport failure
+        }
+    }
+    // --- Pairing (public, unsigned — no deviceId yet) -----------------------------
+    async pairInit(input) {
+        try {
+            const res = await this.fetchImpl(this.url("/api/devices/pair/init"), {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(input),
+            });
+            const json = (await res.json().catch(() => null));
+            if (res.status === 201 && json) {
+                return {
+                    ok: true,
+                    code: String(json.code),
+                    verificationNumber: String(json.verificationNumber),
+                    url: String(json.url),
+                    expiresAt: String(json.expiresAt),
+                };
+            }
+            return { ok: false, reason: String(json?.reason ?? `http_${res.status}`) };
+        }
+        catch {
+            return { ok: false, reason: "network" };
+        }
+    }
+    async pairStatus(code) {
+        try {
+            const res = await this.fetchImpl(this.url(`/api/devices/pair/status?code=${encodeURIComponent(code)}`));
+            const json = (await res.json().catch(() => null));
+            if (json?.status === "confirmed" && json.deviceId) {
+                return { status: "confirmed", deviceId: json.deviceId };
+            }
+            if (json?.status === "pending" || json?.status === "expired" || json?.status === "not_found") {
+                return { status: json.status };
+            }
+            return { status: "error" };
+        }
+        catch {
+            return { status: "error" };
+        }
+    }
+    // --- Signed calls (require a paired deviceId) ---------------------------------
+    async getIdentity() {
+        // /api/identity takes an envelope-only signed body (purpose:"identity") — no
+        // domain/action, since the read carries no application payload.
+        const res = await this.postSigned("/api/identity", freshEnvelope("identity"));
+        if (res.status === 200 && "json" in res && res.json) {
+            const j = res.json;
+            return {
+                ok: true,
+                verified: Boolean(j.verified),
+                country: j.country ?? null,
+                age_over_18: Boolean(j.age_over_18),
+            };
+        }
+        return { ok: false, reason: this.reasonOf(res) };
+    }
+    async createApproval(domain, action, resource) {
+        const res = await this.postSigned("/api/approvals", freshScopedAction("approve", domain, action, resource));
+        if (res.status === 201)
+            return { ok: true };
+        return { ok: false, reason: this.reasonOf(res) };
+    }
+    async requestApprovalOOB(domain, action, resource) {
+        const res = await this.postSigned("/api/approvals/request", freshScopedAction("approve_request", domain, action, resource));
+        if (res.status === 201 && "json" in res && res.json) {
+            const j = res.json;
+            return {
+                ok: true,
+                requestId: String(j.requestId),
+                code: String(j.code),
+                url: String(j.url),
+                expiresAt: String(j.expiresAt),
+            };
+        }
+        return { ok: false, reason: this.reasonOf(res) };
+    }
+    async pollApprovalRequest(code) {
+        try {
+            const res = await this.fetchImpl(this.url(`/api/approvals/request/status?code=${encodeURIComponent(code)}`));
+            const json = (await res.json().catch(() => null));
+            if (json?.status === "pending" ||
+                json?.status === "confirmed" ||
+                json?.status === "expired" ||
+                json?.status === "not_found") {
+                return { status: json.status };
+            }
+            return { status: "error" };
+        }
+        catch {
+            return { status: "error" };
+        }
+    }
+    async sign(domain, action, resource) {
+        const res = await this.postSigned("/api/sign", freshScopedAction("sign", domain, action, resource));
+        if (res.status === 200 && "json" in res && res.json && typeof res.json.token === "string") {
+            return { ok: true, token: res.json.token };
+        }
+        const reason = this.reasonOf(res);
+        if (reason === "not_verified" ||
+            reason === "access_required" ||
+            reason === "unauthorized" ||
+            reason === "bad_request" ||
+            reason === "server_error" ||
+            reason === "network") {
+            return { ok: false, reason };
+        }
+        return { ok: false, reason: "server_error" };
+    }
+    /**
+     * Open a standing-access request (Stage 2b): ask an org admin to grant this agent
+     * lasting authorization for (domain, action, optional resource), with an optional
+     * reason. Enterprise-only — a consumer/no-org device gets `no_org`.
+     */
+    async requestAccess(domain, action, resource, reason) {
+        const body = {
+            ...freshScopedAction("access_request", domain, action, resource),
+            ...(reason !== undefined ? { reason } : {}),
+        };
+        const res = await this.postSigned("/api/access/request", body);
+        if (res.status === 201 && "json" in res && res.json) {
+            return {
+                ok: true,
+                requestId: String(res.json.requestId),
+                status: String(res.json.status),
+            };
+        }
+        return { ok: false, reason: this.reasonOf(res) };
+    }
+    /** Map a raw response to a stable reason string (network, http_NNN, or backend reason). */
+    reasonOf(res) {
+        if (res.status === 0)
+            return "network";
+        if (res.status === 401)
+            return "unauthorized";
+        if (res.status === 500)
+            return "server_error";
+        const reason = res.json?.reason;
+        return typeof reason === "string" ? reason : `http_${res.status}`;
+    }
+}

package/dist/approval.d.ts

@@ -0,0 +1,52 @@
+import type { ApiClient } from "./api.js";
+/** A scoped capability the human is asked to authorize. `resource` is optional. */
+export type ScopedInput = {
+    domain: string;
+    action: string;
+    resource?: string;
+};
+/** The slice of the MCP host we use — kept small so it's trivial to mock. */
+export type ElicitFormRequest = {
+    message: string;
+    requestedSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+};
+export type ElicitOutcome = {
+    action: string;
+    content?: Record<string, unknown>;
+};
+export type ApprovalHost = {
+    getClientCapabilities(): {
+        elicitation?: unknown;
+    } | undefined;
+    elicitInput(params: ElicitFormRequest): Promise<ElicitOutcome>;
+};
+export type Notify = (message: string) => void;
+export type ApprovalOutcome = {
+    approved: true;
+    channel: "elicitation" | "oob";
+} | {
+    approved: false;
+    reason: string;
+    oobUrl?: string;
+};
+export type EnsureApprovalDeps = {
+    notify?: Notify;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+};
+/** Does the connected host support MCP elicitation? */
+export declare function detectElicitation(host: ApprovalHost): boolean;
+/** Ask the host for a yes/no. Returns true only on an explicit accept+approve. */
+export declare function elicitApproval(host: ApprovalHost, input: ScopedInput): Promise<boolean>;
+/**
+ * Obtain a fresh, backend-held approval for (domain, action) through the host.
+ * Both request_human_approval and sign_signup_request call this independently, so
+ * neither can be skipped — calling sign directly still triggers the prompt.
+ */
+export declare function ensureApproval(host: ApprovalHost, api: ApiClient, input: ScopedInput, deps?: EnsureApprovalDeps): Promise<ApprovalOutcome>;

package/dist/approval.js

@@ -0,0 +1,89 @@
+const ACTION_PHRASE = {
+    create_account: "create an account",
+};
+function describeAction(action) {
+    return ACTION_PHRASE[action] ?? action;
+}
+/** "deploy" → "deploy", "deploy (svc-x)" when a resource scopes it. */
+function describeScope(input) {
+    const verb = describeAction(input.action);
+    return input.resource ? `${verb} (${input.resource})` : verb;
+}
+/** Does the connected host support MCP elicitation? */
+export function detectElicitation(host) {
+    try {
+        return Boolean(host.getClientCapabilities()?.elicitation);
+    }
+    catch {
+        return false;
+    }
+}
+/** Ask the host for a yes/no. Returns true only on an explicit accept+approve. */
+export async function elicitApproval(host, input) {
+    const scope = describeScope(input);
+    const result = await host.elicitInput({
+        message: `Allow your agent to ${scope} on ${input.domain}? This authorizes one short-lived Tier Two token for ${input.domain}.`,
+        requestedSchema: {
+            type: "object",
+            properties: {
+                approve: {
+                    type: "boolean",
+                    title: "Approve",
+                    description: `Approve ${scope} on ${input.domain}`,
+                },
+            },
+            required: ["approve"],
+        },
+    });
+    // accept + approve===true is the only yes; decline/cancel (or approve:false) is no.
+    return result.action === "accept" && result.content?.approve === true;
+}
+/**
+ * Obtain a fresh, backend-held approval for (domain, action) through the host.
+ * Both request_human_approval and sign_signup_request call this independently, so
+ * neither can be skipped — calling sign directly still triggers the prompt.
+ */
+export async function ensureApproval(host, api, input, deps = {}) {
+    if (detectElicitation(host)) {
+        let accepted;
+        try {
+            accepted = await elicitApproval(host, input);
+        }
+        catch {
+            // A host that mis-declares elicitation: fall through to OOB rather than crash.
+            return ensureViaOOB(api, input, { ...deps, forced: true });
+        }
+        if (!accepted)
+            return { approved: false, reason: "declined" };
+        const created = await api.createApproval(input.domain, input.action, input.resource);
+        if (!created.ok)
+            return { approved: false, reason: created.reason };
+        return { approved: true, channel: "elicitation" };
+    }
+    return ensureViaOOB(api, input, deps);
+}
+async function ensureViaOOB(api, input, deps) {
+    const notify = deps.notify ?? (() => { });
+    const intervalMs = deps.pollIntervalMs ?? 2000;
+    const timeoutMs = deps.pollTimeoutMs ?? 120_000;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = deps.now ?? Date.now;
+    const req = await api.requestApprovalOOB(input.domain, input.action, input.resource);
+    if (!req.ok)
+        return { approved: false, reason: req.reason };
+    notify(`Approve this request in your browser, then your agent will continue:\n  ${req.url}`);
+    const deadline = now() + timeoutMs;
+    // Poll the NON-consuming status endpoint until the human confirms or it expires.
+    for (;;) {
+        const status = await api.pollApprovalRequest(req.code);
+        if (status.status === "confirmed")
+            return { approved: true, channel: "oob" };
+        if (status.status === "expired" || status.status === "not_found") {
+            return { approved: false, reason: "expired", oobUrl: req.url };
+        }
+        if (now() >= deadline) {
+            return { approved: false, reason: "timeout", oobUrl: req.url };
+        }
+        await sleep(intervalMs);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+import type { DeviceClientMeta } from "@tiertwo/shared";
+import { ApiClient } from "./api.js";
+import { type PairDeps } from "./pairing.js";
+import { type DeviceKey, type KeystoreDeps } from "./keystore.js";
+export type PairCommandDeps = {
+    out?: (line: string) => void;
+    keystore?: KeystoreDeps;
+    /** Test seam: build the ApiClient (the real one signs with the device key). */
+    makeApi?: (apiUrl: string, key: DeviceKey, client: DeviceClientMeta) => ApiClient;
+    /** Poll timing overrides, passed through to pairDevice. */
+    pairDeps?: Partial<PairDeps>;
+};
+/** Run the `pair` subcommand. Returns the process exit code. */
+export declare function runPairCommand(apiUrl: string, deps?: PairCommandDeps): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,60 @@
+// `npx -y @tiertwo/mcp pair` — start the device-pairing ceremony directly from a
+// terminal, without waiting for an agent host to invoke a tool. Unlike the MCP
+// server path, stdout here is a real terminal (not the JSON-RPC channel), so
+// instructions print straight to it. Reuses the exact same pairDevice ceremony;
+// the no-capabilities host below just means the elicitation branch never fires.
+import { hostname, release } from "node:os";
+import { ApiClient } from "./api.js";
+import { pairDevice } from "./pairing.js";
+import { defaultDeps, getDeviceRecord, loadOrCreateKeypair, saveDeviceRecord, } from "./keystore.js";
+const NO_HOST = {
+    getClientCapabilities: () => undefined,
+    elicitInput: () => Promise.reject(new Error("no MCP host in CLI mode")),
+};
+/** Run the `pair` subcommand. Returns the process exit code. */
+export async function runPairCommand(apiUrl, deps = {}) {
+    const out = deps.out ?? ((line) => process.stdout.write(`${line}\n`));
+    const keystore = deps.keystore ?? defaultDeps();
+    const key = loadOrCreateKeypair(apiUrl, keystore);
+    const client = {
+        product: "tiertwo-mcp",
+        runtime: "local",
+        platform: `${process.platform} ${release()}`,
+    };
+    const api = deps.makeApi
+        ? deps.makeApi(apiUrl, key, client)
+        : new ApiClient({ apiUrl, privateKey: key.privateKey, clientMeta: client });
+    // A local record only proves we paired once — the device may since have been
+    // revoked on the dashboard. Probe with a device-signed call: `unauthorized` is
+    // the backend's uniform answer for a revoked/unknown device, so on that we
+    // fall through and pair fresh (same keypair, new Device row).
+    const existing = getDeviceRecord(apiUrl, keystore);
+    if (existing) {
+        const probe = await api.withDevice(existing.deviceId).getIdentity();
+        if (probe.ok) {
+            out(`This machine is already paired (device ${existing.deviceId}, since ${existing.pairedAt}).`);
+            out(`Manage or revoke it from the dashboard: ${apiUrl}/dashboard`);
+            return 0;
+        }
+        if (probe.reason !== "unauthorized") {
+            out(`Couldn't verify the existing pairing (${probe.reason}) — is ${apiUrl} reachable?`);
+            return 1;
+        }
+        out(`The previous pairing (device ${existing.deviceId}) is no longer valid — it was probably revoked. Starting a fresh pairing…`);
+    }
+    try {
+        const { deviceId } = await pairDevice(NO_HOST, api, key.publicKeyB64url, {
+            hostname: hostname(),
+            client,
+            notify: out,
+            ...deps.pairDeps,
+        });
+        saveDeviceRecord(apiUrl, { deviceId, pairedAt: new Date().toISOString() }, keystore);
+        out(`Paired as device ${deviceId}. Your agent can now use Tier Two tools from this machine.`);
+        return 0;
+    }
+    catch (e) {
+        out(`Pairing failed: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// @tiertwo/mcp — the `npx @tiertwo/mcp` stdio MCP server (ARCHITECTURE §11). Gives an
+// AI agent three tools — get_identity, request_human_approval, sign_request — after
+// pairing the device to a verified human's account on first run (§8,
+// poll-until-confirmed). The signing flow is un-skippable: approval is collected
+// through the host and /api/sign independently requires a fresh one (§18.1).
+//
+// stdout IS the JSON-RPC channel — every human-facing line goes to stderr (and, best
+// effort, an MCP logging notification). NEVER console.log here. (The one exception is
+// `tiertwo-mcp pair`, which never starts the server — see cli.ts.)
+import { hostname, release } from "node:os";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { isValidAction, isValidResource, WELL_KNOWN_ACTIONS, } from "@tiertwo/shared";
+import { ApiClient } from "./api.js";
+import { runPairCommand } from "./cli.js";
+import { pairDevice } from "./pairing.js";
+import { getDeviceRecord, loadOrCreateKeypair, saveDeviceRecord, } from "./keystore.js";
+import { getIdentityTool, requestAccessTool, requestHumanApprovalTool, signRequestTool, } from "./tools.js";
+// Common actions surfaced as a hint (not an allow-list — any valid action works).
+const ACTION_HINT = `Common actions: ${WELL_KNOWN_ACTIONS.join(", ")} (any valid action string is accepted).`;
+const VH_API_URL = (process.env.VH_API_URL ?? "https://trytiertwo.com").replace(/\/$/, "");
+function toResult(o) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(o.data) }],
+        isError: o.isError ?? false,
+        structuredContent: o.data,
+    };
+}
+async function main() {
+    // `npx -y @tiertwo/mcp pair` — pair this machine from a terminal right now,
+    // instead of waiting for the first tool call from an agent host.
+    if (process.argv[2] === "pair") {
+        process.exitCode = await runPairCommand(VH_API_URL);
+        return;
+    }
+    const server = new McpServer({ name: "tiertwo-mcp", version: "0.1.0" }, { capabilities: { logging: {}, tools: {} } });
+    const notify = (message) => {
+        process.stderr.write(`[tiertwo-mcp] ${message}\n`);
+        void server.server.sendLoggingMessage({ level: "info", data: message }).catch(() => { });
+    };
+    // Adapter: the small slice of the connected host that approval.ts needs.
+    const host = {
+        getClientCapabilities: () => server.server.getClientCapabilities(),
+        elicitInput: (params) => server.server.elicitInput(params),
+    };
+    const key = loadOrCreateKeypair(VH_API_URL);
+    let pairedClient = null;
+    /** Client-claimed directory metadata (Stage 4.9): the connected MCP HOST
+     * (claude-code, cursor…) from the initialize handshake, falling back to
+     * ourselves; a stdio child process runs on the user's machine by
+     * construction → runtime "local". Informational only. */
+    function clientMeta() {
+        const hostInfo = server.server.getClientVersion();
+        return {
+            product: hostInfo?.name ?? "tiertwo-mcp",
+            ...(hostInfo?.version ? { productVersion: hostInfo.version } : {}),
+            runtime: "local",
+            platform: `${process.platform} ${release()}`,
+        };
+    }
+    // Resolve a device-bound client, pairing first (poll-until-confirmed) if needed.
+    // ensurePaired runs inside tool handlers — i.e. after initialize — so the host's
+    // clientInfo is available for the metadata at both pairing and refresh time.
+    async function ensurePaired() {
+        if (pairedClient)
+            return pairedClient;
+        const meta = clientMeta();
+        const base = new ApiClient({
+            apiUrl: VH_API_URL,
+            privateKey: key.privateKey,
+            clientMeta: meta,
+        });
+        const existing = getDeviceRecord(VH_API_URL);
+        if (existing) {
+            pairedClient = base.withDevice(existing.deviceId);
+            return pairedClient;
+        }
+        const { deviceId } = await pairDevice(host, base, key.publicKeyB64url, {
+            hostname: hostname(),
+            client: meta,
+            notify,
+        });
+        saveDeviceRecord(VH_API_URL, { deviceId, pairedAt: new Date().toISOString() });
+        pairedClient = base.withDevice(deviceId);
+        return pairedClient;
+    }
+    // Every tool ensures pairing first and converts thrown errors into tool errors.
+    async function guarded(run) {
+        try {
+            const api = await ensurePaired();
+            return toResult(await run(api));
+        }
+        catch (e) {
+            return toResult({
+                data: { error: e instanceof Error ? e.message : "internal_error" },
+                isError: true,
+            });
+        }
+    }
+    server.registerTool("get_identity", {
+        title: "Get verified-human identity",
+        description: "Return the paired human's verified status and identity claims (verified, country, age_over_18). Use this to reason about eligibility before requesting a signup.",
+    }, () => guarded((api) => getIdentityTool(api)));
+    server.registerTool("request_human_approval", {
+        title: "Request human approval",
+        description: `Ask the human to approve a scoped capability (domain, action, optional resource) through the host. Returns whether they approved. Never auto-approves; the approval is one-time and short-lived. ${ACTION_HINT}`,
+        inputSchema: {
+            domain: z.string().min(1),
+            action: z.string().refine(isValidAction, "invalid action"),
+            resource: z.string().refine(isValidResource, "invalid resource").optional(),
+        },
+    }, ({ domain, action, resource }) => guarded((api) => requestHumanApprovalTool(host, api, { domain, action, resource }, { notify })));
+    server.registerTool("sign_request", {
+        title: "Sign a verified-human action request",
+        description: `Mint a short-lived token proving a verified human authorized a scoped capability (domain, action, optional resource). If an org admin has granted standing access for it, this mints with no prompt; otherwise it requires a fresh human approval first, so signing can never skip authorization. If it returns access_required, call request_access to ask an admin for a standing grant. Returns { token } for the merchant/enforcer to verify. Consumer signup is action:"create_account". ${ACTION_HINT}`,
+        inputSchema: {
+            domain: z.string().min(1),
+            action: z.string().refine(isValidAction, "invalid action"),
+            resource: z.string().refine(isValidResource, "invalid resource").optional(),
+        },
+    }, ({ domain, action, resource }) => guarded((api) => signRequestTool(host, api, { domain, action, resource }, { notify })));
+    server.registerTool("request_access", {
+        title: "Request standing access for an action",
+        description: `Ask an org admin to grant this agent STANDING authorization for a scoped capability (domain, action, optional resource), with an optional reason. Once granted, sign_request mints tokens for it with no per-action prompt until the grant expires or is revoked. Use this when sign_request returns access_required. Enterprise-only: a consumer/no-org device gets no_org. ${ACTION_HINT}`,
+        inputSchema: {
+            domain: z.string().min(1),
+            action: z.string().refine(isValidAction, "invalid action"),
+            resource: z.string().refine(isValidResource, "invalid resource").optional(),
+            reason: z.string().max(500).optional(),
+        },
+    }, ({ domain, action, resource, reason }) => guarded((api) => requestAccessTool(api, { domain, action, resource, reason })));
+    await server.connect(new StdioServerTransport());
+    notify(`tiertwo-mcp ready (API ${VH_API_URL})`);
+}
+main().catch((e) => {
+    process.stderr.write(`[tiertwo-mcp] fatal: ${e instanceof Error ? (e.stack ?? e.message) : String(e)}\n`);
+    process.exit(1);
+});

package/dist/keystore.d.ts

@@ -0,0 +1,33 @@
+import { type KeyObject } from "node:crypto";
+/** A keychain entry — the minimal surface keystore needs (real or mocked in tests). */
+export type KeyringEntry = {
+    getPassword(): string | null;
+    setPassword(password: string): void;
+};
+export type KeyringFactory = (service: string, account: string) => KeyringEntry;
+export type KeystoreDeps = {
+    keyring: KeyringFactory;
+    configDir: string;
+};
+export type DeviceKey = {
+    privateKey: KeyObject;
+    /** JWK `x`: base64url raw Ed25519 public key, as stored in Device.publicKey. */
+    publicKeyB64url: string;
+};
+export type DeviceRecord = {
+    deviceId: string;
+    pairedAt: string;
+};
+/** Real OS keychain + real config dir. Tests pass their own deps. */
+export declare function defaultDeps(): KeystoreDeps;
+/** Derive the JWK `x` (base64url raw 32B) the backend verifies against. */
+export declare function publicKeyB64url(privateKey: KeyObject): string;
+/**
+ * Load the device private key from the keychain, generating + persisting a fresh
+ * Ed25519 keypair on first run. The public key is always derived, never stored.
+ */
+export declare function loadOrCreateKeypair(apiUrl: string, deps?: KeystoreDeps): DeviceKey;
+/** The persisted device record for this API host, or null if not yet paired. */
+export declare function getDeviceRecord(apiUrl: string, deps?: KeystoreDeps): DeviceRecord | null;
+/** Persist (merge) the device record for this API host after pairing. */
+export declare function saveDeviceRecord(apiUrl: string, record: DeviceRecord, deps?: KeystoreDeps): void;

package/dist/keystore.js

@@ -0,0 +1,89 @@
+// Local key + device state for the MCP. The Ed25519 PRIVATE KEY lives in the OS
+// keychain (macOS Keychain / Windows Credential Manager / Linux Secret Service via
+// @napi-rs/keyring) as a PKCS8 PEM — the one secret. The non-secret pointers
+// (deviceId, pairedAt) live in a JSON config file under $XDG_CONFIG_HOME/tiertwo.
+//
+// Both keychain account and config record are namespaced by the API host, so a prod
+// install and a local-dev VH_API_URL on the same machine never collide. The public
+// key is always DERIVED from the private key as the JWK `x` (base64url raw 32B) —
+// exactly what the backend stores in Device.publicKey and verifies in
+// lib/deviceAuth.ts — so it can never drift from what was paired.
+import { createPrivateKey, createPublicKey, generateKeyPairSync, } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Entry } from "@napi-rs/keyring";
+const KEYRING_SERVICE = "tiertwo-mcp";
+const KEY_ACCOUNT_BASE = "device-private-key";
+function defaultConfigDir() {
+    const base = process.env.XDG_CONFIG_HOME ||
+        (process.platform === "win32" ? process.env.APPDATA : undefined) ||
+        join(homedir(), ".config");
+    return join(base, "tiertwo");
+}
+/** Real OS keychain + real config dir. Tests pass their own deps. */
+export function defaultDeps() {
+    return {
+        keyring: (service, account) => new Entry(service, account),
+        configDir: defaultConfigDir(),
+    };
+}
+/** Stable per-API-host namespace so prod + local-dev installs don't collide. */
+function apiHost(apiUrl) {
+    try {
+        return new URL(apiUrl).host || "default";
+    }
+    catch {
+        return "default";
+    }
+}
+/** Derive the JWK `x` (base64url raw 32B) the backend verifies against. */
+export function publicKeyB64url(privateKey) {
+    const jwk = createPublicKey(privateKey).export({ format: "jwk" });
+    return jwk.x;
+}
+/**
+ * Load the device private key from the keychain, generating + persisting a fresh
+ * Ed25519 keypair on first run. The public key is always derived, never stored.
+ */
+export function loadOrCreateKeypair(apiUrl, deps = defaultDeps()) {
+    const entry = deps.keyring(KEYRING_SERVICE, `${KEY_ACCOUNT_BASE}:${apiHost(apiUrl)}`);
+    let pem = null;
+    try {
+        pem = entry.getPassword();
+    }
+    catch {
+        pem = null; // locked/unavailable keychain → treat as no key (will regenerate)
+    }
+    if (pem) {
+        const privateKey = createPrivateKey(pem);
+        return { privateKey, publicKeyB64url: publicKeyB64url(privateKey) };
+    }
+    const { privateKey } = generateKeyPairSync("ed25519");
+    entry.setPassword(privateKey.export({ type: "pkcs8", format: "pem" }));
+    return { privateKey, publicKeyB64url: publicKeyB64url(privateKey) };
+}
+function configPath(deps) {
+    return join(deps.configDir, "config.json");
+}
+function readConfigFile(deps) {
+    try {
+        return JSON.parse(readFileSync(configPath(deps), "utf8"));
+    }
+    catch {
+        return {}; // missing or corrupt → empty config
+    }
+}
+/** The persisted device record for this API host, or null if not yet paired. */
+export function getDeviceRecord(apiUrl, deps = defaultDeps()) {
+    return readConfigFile(deps).byHost?.[apiHost(apiUrl)] ?? null;
+}
+/** Persist (merge) the device record for this API host after pairing. */
+export function saveDeviceRecord(apiUrl, record, deps = defaultDeps()) {
+    const cfg = readConfigFile(deps);
+    const byHost = { ...(cfg.byHost ?? {}), [apiHost(apiUrl)]: record };
+    mkdirSync(deps.configDir, { recursive: true });
+    writeFileSync(configPath(deps), JSON.stringify({ ...cfg, byHost }, null, 2), {
+        mode: 0o600,
+    });
+}

package/dist/pairing.d.ts

@@ -0,0 +1,17 @@
+import type { DeviceClientMeta } from "@tiertwo/shared";
+import type { ApiClient } from "./api.js";
+import { type ApprovalHost, type Notify } from "./approval.js";
+export type PairDeps = {
+    hostname: string;
+    /** Client-claimed directory metadata (Stage 4.9), sent in the pair/init body. */
+    client?: DeviceClientMeta;
+    notify?: Notify;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+};
+export type PairResult = {
+    deviceId: string;
+};
+export declare function pairDevice(host: ApprovalHost, base: ApiClient, publicKeyB64url: string, deps: PairDeps): Promise<PairResult>;

package/dist/pairing.js

@@ -0,0 +1,63 @@
+import { detectElicitation } from "./approval.js";
+function instructionsFor(pairUrl, code, verificationNumber) {
+    return (`This device isn't paired with Tier Two yet. To authorize it:\n` +
+        `  1. Open ${pairUrl}\n` +
+        `  2. Check the verification number shows ${verificationNumber}\n` +
+        `  3. Click "Confirm & pair" (your code ${code} is pre-filled).`);
+}
+export async function pairDevice(host, base, publicKeyB64url, deps) {
+    const notify = deps.notify ?? (() => { });
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = deps.now ?? Date.now;
+    const intervalMs = deps.pollIntervalMs ?? 2000;
+    const timeoutMs = deps.pollTimeoutMs ?? 10 * 60_000;
+    const init = await base.pairInit({
+        publicKey: publicKeyB64url,
+        name: deps.hostname,
+        ...(deps.client ? { client: deps.client } : {}),
+    });
+    if (!init.ok)
+        throw new Error(`pairing init failed: ${init.reason}`);
+    const pairUrl = `${init.url}?code=${encodeURIComponent(init.code)}`;
+    const instructions = instructionsFor(pairUrl, init.code, init.verificationNumber);
+    // Always emit to stderr + logging (fallback for hosts without elicitation).
+    notify(instructions);
+    // Inline dialog so the human actually sees the code (not just in the server log).
+    if (detectElicitation(host)) {
+        const res = await host
+            .elicitInput({
+            message: instructions,
+            requestedSchema: {
+                type: "object",
+                properties: {
+                    paired: {
+                        type: "boolean",
+                        title: "I've paired this device",
+                        description: "Confirm on the dashboard, then check this to continue.",
+                    },
+                },
+                required: ["paired"],
+            },
+        })
+            .catch(() => ({ action: "cancel" }));
+        if (res.action !== "accept") {
+            throw new Error("pairing was cancelled — ask again to retry");
+        }
+    }
+    // The dashboard confirm binds the device; poll until it does (the click above is
+    // only a hint — we never trust it, we verify via status).
+    const deadline = now() + timeoutMs;
+    for (;;) {
+        const status = await base.pairStatus(init.code);
+        if (status.status === "confirmed") {
+            notify("Device paired. Continuing…");
+            return { deviceId: status.deviceId };
+        }
+        if (status.status === "expired" || status.status === "not_found") {
+            throw new Error("pairing code expired before confirmation — ask again to retry");
+        }
+        if (now() >= deadline)
+            throw new Error("pairing timed out — ask again to retry");
+        await sleep(intervalMs);
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,23 @@
+import type { ApiClient } from "./api.js";
+import { type ApprovalHost, type EnsureApprovalDeps, type ScopedInput } from "./approval.js";
+export type ToolOutcome = {
+    data: Record<string, unknown>;
+    isError?: boolean;
+};
+export declare function getIdentityTool(api: ApiClient): Promise<ToolOutcome>;
+export declare function requestHumanApprovalTool(host: ApprovalHost, api: ApiClient, input: ScopedInput, deps?: EnsureApprovalDeps): Promise<ToolOutcome>;
+export declare function signRequestTool(host: ApprovalHost, api: ApiClient, input: ScopedInput, deps?: EnsureApprovalDeps): Promise<ToolOutcome>;
+export type AccessRequestInput = {
+    domain: string;
+    action: string;
+    resource?: string;
+    reason?: string;
+};
+/**
+ * Open a standing-access request (Stage 2b): ask an org admin to grant this agent
+ * lasting authorization for a scoped capability. Unlike request_human_approval (a
+ * one-time yes for a single mint), a granted request lets sign_request mint with no
+ * prompt until it expires or is revoked. No host elicitation — the human decision
+ * happens later in the org's dashboard.
+ */
+export declare function requestAccessTool(api: ApiClient, input: AccessRequestInput): Promise<ToolOutcome>;

package/dist/tools.js

@@ -0,0 +1,81 @@
+import { ensureApproval, } from "./approval.js";
+// Surfaced when no standing grant or approval authorizes the action, steering the
+// agent to the standing-access path instead of retrying blindly.
+const ACCESS_REQUIRED_HINT = "No standing grant or approval authorizes this action. Run request_access(domain, action, resource) and ask an org admin to grant it.";
+/** "deploy (svc-x)" / "create_account" — for the standing-grant notify line. */
+function scopeLabel(input) {
+    return input.resource ? `${input.action} (${input.resource})` : input.action;
+}
+export async function getIdentityTool(api) {
+    const res = await api.getIdentity();
+    if (!res.ok)
+        return { data: { error: res.reason }, isError: true };
+    return {
+        data: { verified: res.verified, country: res.country, age_over_18: res.age_over_18 },
+    };
+}
+export async function requestHumanApprovalTool(host, api, input, deps = {}) {
+    const outcome = await ensureApproval(host, api, input, deps);
+    if (!outcome.approved) {
+        return {
+            data: { approved: false, reason: outcome.reason, ...(outcome.oobUrl ? { url: outcome.oobUrl } : {}) },
+        };
+    }
+    return { data: { approved: true, channel: outcome.channel } };
+}
+export async function signRequestTool(host, api, input, deps = {}) {
+    // 1. Sign-first: a standing grant authorizes the mint with no prompt. This is the
+    //    headline of Stage 2b — a covered action just works. The call consumes nothing
+    //    when it fails closed, so it's a safe probe.
+    const first = await api.sign(input.domain, input.action, input.resource);
+    if (first.ok) {
+        // A 200 means the backend already held authorization — a standing grant, or a
+        // still-valid prior approval — so no new prompt was needed. The token alone can't
+        // say which (the audit row records grantId), so keep the notice neutral.
+        deps.notify?.(`Signed ${scopeLabel(input)} on ${input.domain} — already authorized, no new approval prompt needed.`);
+        return { data: { token: first.token } };
+    }
+    // A non-authorization failure (not_verified, unauthorized, …) won't be fixed by
+    // asking for approval — surface it as-is.
+    if (first.reason !== "access_required") {
+        return { data: { error: first.reason }, isError: true };
+    }
+    // 2. No standing grant → obtain a fresh, one-time human approval through the host,
+    //    then sign once more (§18.1: signing can never skip the prompt).
+    const outcome = await ensureApproval(host, api, input, deps);
+    if (!outcome.approved) {
+        return {
+            data: {
+                error: "approval_required",
+                reason: outcome.reason,
+                hint: ACCESS_REQUIRED_HINT,
+                ...(outcome.oobUrl ? { url: outcome.oobUrl } : {}),
+            },
+            isError: true,
+        };
+    }
+    const signed = await api.sign(input.domain, input.action, input.resource);
+    if (!signed.ok) {
+        return {
+            data: {
+                error: signed.reason,
+                ...(signed.reason === "access_required" ? { hint: ACCESS_REQUIRED_HINT } : {}),
+            },
+            isError: true,
+        };
+    }
+    return { data: { token: signed.token } };
+}
+/**
+ * Open a standing-access request (Stage 2b): ask an org admin to grant this agent
+ * lasting authorization for a scoped capability. Unlike request_human_approval (a
+ * one-time yes for a single mint), a granted request lets sign_request mint with no
+ * prompt until it expires or is revoked. No host elicitation — the human decision
+ * happens later in the org's dashboard.
+ */
+export async function requestAccessTool(api, input) {
+    const res = await api.requestAccess(input.domain, input.action, input.resource, input.reason);
+    if (!res.ok)
+        return { data: { error: res.reason }, isError: true };
+    return { data: { requestId: res.requestId, status: res.status } };
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@tiertwo/mcp",
+  "version": "0.1.0",
+  "description": "MCP server (npx @tiertwo/mcp) that lets an AI agent create accounts as a verified human — first-run device pairing, host-mediated approval, and short-lived signed signup tokens.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Tier Two",
+  "homepage": "https://github.com/Jordan-M/verified-human/tree/master/packages/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jordan-M/verified-human.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/Jordan-M/verified-human/issues"
+  },
+  "keywords": [
+    "tiertwo",
+    "verified-human",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ai-agent"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "tiertwo-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./keystore": {
+      "types": "./dist/keystore.d.ts",
+      "import": "./dist/keystore.js"
+    },
+    "./pairing": {
+      "types": "./dist/pairing.d.ts",
+      "import": "./dist/pairing.js"
+    },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "import": "./dist/api.js"
+    },
+    "./approval": {
+      "types": "./dist/approval.d.ts",
+      "import": "./dist/approval.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@napi-rs/keyring": "1.3.0",
+    "zod": "^4.4.3",
+    "@tiertwo/shared": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.22.4",
+    "typescript": "^5",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "echo no-op",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}