@tiertwo/shared 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,15 @@
+# @tiertwo/shared
+
+Internal shared types and pure, zero-dependency helpers for the `@tiertwo/*` packages —
+the single source of truth for token/claim/request shapes (so the backend, SDK, and MCP
+server never drift), the device-auth header constants, and `canonicalJSON` (the
+deterministic serialization the device signs and the backend verifies over).
+
+**This is not a stable public API.** It's published only because
+[`@tiertwo/sdk`](https://www.npmjs.com/package/@tiertwo/sdk) and
+[`@tiertwo/mcp`](https://www.npmjs.com/package/@tiertwo/mcp) depend on it at runtime.
+Use those packages; import from `@tiertwo/shared` directly at your own risk — its
+surface may change without a major-version bump.
+
+See [`docs/ARCHITECTURE.md`](https://github.com/Jordan-M/verified-human/blob/master/docs/ARCHITECTURE.md)
+§6 (token) and §7 (request flow).

package/dist/clientMeta.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clientMeta.test.js

@@ -0,0 +1,45 @@
+// Unit suite for the client-metadata sanitizer (Stage 4.9) — the single
+// validator for the client-claimed X-VH-Client / pair-init `client` payloads
+// that web, mcp, and the gateway all import.
+import { describe, it, expect } from "vitest";
+import { CLIENT_META_MAX, sanitizeClientMeta } from "./index.js";
+describe("sanitizeClientMeta", () => {
+    it("keeps well-typed, length-capped fields and trims whitespace", () => {
+        expect(sanitizeClientMeta({
+            product: " claude-code ",
+            productVersion: "2.1.3",
+            runtime: "local",
+            platform: "darwin 25.5.0",
+        })).toEqual({
+            product: "claude-code",
+            productVersion: "2.1.3",
+            runtime: "local",
+            platform: "darwin 25.5.0",
+        });
+    });
+    it("drops invalid fields field-wise, keeping the valid remainder", () => {
+        expect(sanitizeClientMeta({
+            product: "tiertwo-gateway",
+            productVersion: 42, // wrong type — dropped
+            runtime: "docker", // outside the sanitized set — dropped
+            platform: "p".repeat(CLIENT_META_MAX.platform + 1), // oversized — dropped
+        })).toEqual({ product: "tiertwo-gateway" });
+    });
+    it("drops oversized strings rather than truncating", () => {
+        expect(sanitizeClientMeta({ product: "a".repeat(CLIENT_META_MAX.product + 1) })).toBeNull();
+        expect(sanitizeClientMeta({ product: "a".repeat(CLIENT_META_MAX.product) })).toEqual({ product: "a".repeat(CLIENT_META_MAX.product) });
+    });
+    it("ignores unknown keys — only the four known fields survive", () => {
+        expect(sanitizeClientMeta({ runtime: "cloud", attested: true, extra: "x" })).toEqual({ runtime: "cloud" });
+    });
+    it("returns null on garbage, empties, and non-objects", () => {
+        expect(sanitizeClientMeta(null)).toBeNull();
+        expect(sanitizeClientMeta(undefined)).toBeNull();
+        expect(sanitizeClientMeta("claude-code")).toBeNull();
+        expect(sanitizeClientMeta(42)).toBeNull();
+        expect(sanitizeClientMeta([{ product: "x" }])).toBeNull(); // arrays rejected
+        expect(sanitizeClientMeta({})).toBeNull();
+        expect(sanitizeClientMeta({ product: "   " })).toBeNull(); // whitespace-only
+        expect(sanitizeClientMeta({ runtime: "LOCAL" })).toBeNull(); // case-sensitive set
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Action — an arbitrary scoped capability an agent may be authorized for (an open
+ * validated string, not a closed enum). `isValidAction` is the single source of
+ * truth for validity; `WELL_KNOWN_ACTIONS` is a discoverability hint only (e.g. for
+ * MCP tool descriptions), never an allow-list.
+ */
+export type Action = string;
+export declare const WELL_KNOWN_ACTIONS: readonly ["create_account", "deploy"];
+export declare function isValidAction(s: unknown): s is Action;
+/**
+ * Resource — an optional scope qualifier for an action (a service name, repo,
+ * path, …). Present only for scoped actions. Case-insensitive.
+ */
+export type Resource = string;
+export declare function isValidResource(s: unknown): s is Resource;
+/**
+ * Assurance tier of the human behind an action, ordered weakest → strongest:
+ * - "sso": an authenticated org employee (SSO); identity not independently proofed.
+ * - "identity_proofed": a Stripe-Identity-verified real human (the consumer bar).
+ * `meetsAuthLevel` enforces an "at least this tier" requirement.
+ */
+export declare const AUTH_LEVELS: readonly ["sso", "identity_proofed"];
+export type AuthLevel = (typeof AUTH_LEVELS)[number];
+export declare function authLevelRank(l: AuthLevel): number;
+export declare function meetsAuthLevel(have: unknown, need: AuthLevel): boolean;
+export declare function isAuthLevel(s: unknown): s is AuthLevel;
+/**
+ * Device-trust ladder (Stage 4.12), ordered weakest → strongest. LINEAR:
+ * - "paired": the device authenticated (exists, not revoked) — key possession,
+ *   the floor every caller clears.
+ * - "managed": + the device belongs to an organization (admins can see, gate,
+ *   and revoke it).
+ * - "verified": + the owning human is identity-proofed (Stripe Identity).
+ * A consumer device with a verified owner is still just "paired" — the ladder
+ * measures how GOVERNED the worker is, and an ungoverned device tops out at the
+ * bottom rung by design. Distinct axis from AUTH_LEVELS ("how proofed is the
+ * human") — see agent-directory-roadmap §4e; do not conflate them.
+ */
+export declare const DEVICE_TRUST_LEVELS: readonly ["paired", "managed", "verified"];
+export type DeviceTrustLevel = (typeof DEVICE_TRUST_LEVELS)[number];
+export declare function deviceTrustRank(l: DeviceTrustLevel): number;
+export declare function meetsDeviceTrust(have: unknown, need: DeviceTrustLevel): boolean;
+export declare function isDeviceTrustLevel(s: unknown): s is DeviceTrustLevel;
+/**
+ * Why a call was refused (Stage 4.10) — the SignEvent.denyReason vocabulary.
+ * The server adjudicates the first three (authorize route); the last three are
+ * gateway-local policy results that reach the ledger via /api/gateway/telemetry.
+ * That split is load-bearing: a gateway may only CLAIM the local subset, so deny
+ * provenance stays derivable with no extra column.
+ */
+export declare const DENY_REASONS: readonly ["access_required", "not_verified", "insufficient_auth_level", "policy_deny", "no_rule", "unresolved_resource", "insufficient_device_trust", "approval_required"];
+export type DenyReason = (typeof DENY_REASONS)[number];
+export declare function isDenyReason(s: unknown): s is DenyReason;
+/** The subset a gateway may claim via telemetry — server-adjudicated reasons are
+ * not claimable (the telemetry narrower rejects them). */
+export declare const GATEWAY_LOCAL_DENY_REASONS: readonly ["no_rule", "unresolved_resource", "policy_deny"];
+export type GatewayLocalDenyReason = (typeof GATEWAY_LOCAL_DENY_REASONS)[number];
+export declare function isGatewayLocalDenyReason(s: unknown): s is GatewayLocalDenyReason;
+/**
+ * SignEvent.action sentinel for denied calls that no rule mapped to a capability
+ * (no_rule / unresolved_resource) — self-describing, and never fabricates a
+ * capability name an admin might have authored. Display/filter only; appears on
+ * deny rows exclusively.
+ */
+export declare function unmappedToolAction(tool: string): string;
+/** Derived identity claims surfaced to the merchant + MCP get_identity. (§6, §11) */
+export type Claims = {
+    verified_human: boolean;
+    /** ISO-3166 alpha-2, derived; null when unknown. */
+    country: string | null;
+    age_over_18: boolean;
+};
+/** Full merchant-facing JWT payload. (ARCHITECTURE §6) */
+export type TokenPayload = {
+    /** Issuer, e.g. "https://trytiertwo.com". */
+    iss: string;
+    /** PAIRWISE/directed subject: base64url(HMAC(userId+aud)). (§18.3) */
+    sub: string;
+    /** DERIVED from auth_level === "identity_proofed"; kept for merchant convenience. */
+    verified_human: boolean;
+    country: string | null;
+    age_over_18: boolean;
+    device_id: string;
+    /** Merchant domain — SDK MUST validate. */
+    aud: string;
+    /** Validated string (isValidAction) — SDK MUST match its expected action. */
+    action: Action;
+    /** Present only for scoped actions — SDK matches it when it expects a resource. */
+    resource?: Resource;
+    /** Assurance tier — SDK MAY require a minimum via meetsAuthLevel. */
+    auth_level: AuthLevel;
+    /** UUID — merchant SHOULD dedupe (SDK ships a helper). */
+    jti: string;
+    /** Issued-at, unix seconds. */
+    iat: number;
+    /** Expiry, unix seconds (iat + 300). */
+    exp: number;
+};
+/** Endpoint class each device-signed body is bound to (checked by lib/deviceAuth). */
+export type DevicePurpose = "identity" | "approve" | "approve_request" | "sign" | "access_request" | "gateway" | "gateway_credential" | "gateway_policy" | "gateway_telemetry" | "gateway_proxy";
+/** Transport envelope present on EVERY device-signed body. */
+export type DeviceAuthEnvelope = {
+    purpose: DevicePurpose;
+    /** Random 16B, base64url — one-time nonce. */
+    nonce: string;
+    /** Unix milliseconds. */
+    ts: number;
+};
+/** Application payload for the action-scoped endpoints. */
+export type ScopedAction = {
+    domain: string;
+    action: Action;
+    resource?: Resource;
+};
+export type IdentityRequest = DeviceAuthEnvelope & {
+    purpose: "identity";
+};
+export type ApproveRequest = DeviceAuthEnvelope & {
+    purpose: "approve";
+} & ScopedAction;
+export type ApproveOOBRequest = DeviceAuthEnvelope & {
+    purpose: "approve_request";
+} & ScopedAction;
+export type SignTokenRequest = DeviceAuthEnvelope & {
+    purpose: "sign";
+} & ScopedAction;
+export type AccessRequest = DeviceAuthEnvelope & {
+    purpose: "access_request";
+} & ScopedAction & {
+    reason?: string;
+};
+/**
+ * Application payload for a governed gateway tool call (agent-governance Stage 3a).
+ * Its OWN type — deliberately NOT ScopedAction: `backend`/`tool` are gateway-only
+ * routing/audit context (never part of the shared action-scoped payload), and the
+ * gateway — not the agent — sets `action`/`resource` from policy applied to the
+ * observed call. `reason` justifies the pending grant opened on access_required.
+ */
+export type GatewayCall = {
+    /** Config backend id → SignEvent.domain (audit). */
+    backend: string;
+    /** Un-namespaced downstream tool name (audit context). */
+    tool: string;
+    action: Action;
+    resource?: Resource;
+    /** ≤500 chars — justification for the pending grant on access_required. */
+    reason?: string;
+    /**
+     * Set by the GATEWAY (never the agent) from its own policy `effect: "audit_only"`
+     * rule (agent-governance Stage 3b): record a SignEvent for this call and forward it
+     * WITHOUT requiring a grant/tier — reads are audited, never blocked. Absent ⇒ the
+     * normal gated authorizeMint path.
+     */
+    auditOnly?: boolean;
+    /**
+     * Set by the GATEWAY (never the agent) from the matched rule when its effect is
+     * "gate" (Stage 4.10) — mirrors auditOnly exactly. The server enforces
+     * meetsAuthLevel AFTER authorizeMint allows and BEFORE the allow SignEvent is
+     * written, so a tier-blocked call records a deny and never an allow. Same trust
+     * class as auditOnly/action/resource: the server cannot re-derive it (rule
+     * selection needs the observed call args, which never leave the data plane).
+     * Illegal in combination with auditOnly (audit_only rules carry no tier gate).
+     */
+    requiredAuthLevel?: AuthLevel;
+    /**
+     * Set by the GATEWAY (never the agent) from the matched gate rule (Stage 4.12) —
+     * mirrors requiredAuthLevel exactly, same trust class. The server enforces
+     * meetsDeviceTrust against facts it already holds (device org, owner
+     * verification) BEFORE authorizeMint, so a trust-blocked call never opens a
+     * pending Grant that could be approved yet never take effect. Illegal in
+     * combination with auditOnly.
+     */
+    requiredDeviceTrust?: DeviceTrustLevel;
+    /**
+     * Set by the GATEWAY (never the agent) from the matched gate rule (Stage 4.13) —
+     * same trust class and threading as requiredAuthLevel/requiredDeviceTrust.
+     * True ⇒ authorizeMint SKIPS the standing-grant arm: only a fresh ad-hoc
+     * Approval satisfies the call; without one the deny is approval_required and
+     * opens an ApprovalRequest. Illegal in combination with auditOnly.
+     */
+    requireFreshApproval?: boolean;
+};
+export type GatewayRequest = DeviceAuthEnvelope & {
+    purpose: "gateway";
+} & GatewayCall;
+/**
+ * A gateway-local deny, reported best-effort to POST /api/gateway/telemetry
+ * (Stage 4.10). action/resource are legal ONLY for policy_deny (the denying rule
+ * names them — action is required there); for no_rule / unresolved_resource no
+ * capability mapping exists and the server records the unmappedToolAction
+ * sentinel instead. Since Stage 4.11 telemetry bodies are a discriminated
+ * union — `kind` selects the report class.
+ */
+export type GatewayDenyReport = {
+    kind: "deny";
+    /** Route-table backend id → SignEvent.domain. */
+    backend: string;
+    /** Raw un-namespaced downstream tool name. */
+    tool: string;
+    denyReason: GatewayLocalDenyReason;
+    action?: Action;
+    resource?: Resource;
+};
+/**
+ * Cumulative session totals (Stage 4.11) — MONOTONE within one session: every
+ * report carries the running totals since session start, so open, heartbeat,
+ * flush, and end are ONE message shape and a lost report costs nothing once the
+ * next arrives. All non-negative integers ≤ SESSION_COUNTER_MAX. Invariants the
+ * gateway maintains (the server does NOT cross-check — counters are claims):
+ * toolCalls = allowed + denied; errors ⊆ allowed (only forwarded calls can
+ * error); latency is measured around connection.callTool only.
+ */
+export type GatewaySessionCounters = {
+    /** Decided governed calls = allowed + denied (unknown_tool is protocol misuse, not counted). */
+    toolCalls: number;
+    allowed: number;
+    denied: number;
+    /** Failed FORWARDS: downstream isError results (incl. repair-flips), link_required, backend_unavailable. */
+    errors: number;
+    /** Wall-clock ms around connection.callTool, forwarded calls only. */
+    latencyMsSum: number;
+    latencyMsMax: number;
+};
+/** The only STORED end reason. "lost" is derived read-side from a stale
+ * heartbeat (lib/agentSessions.sessionStatusOf) and is never on the wire. */
+export type GatewaySessionEndReason = "shutdown";
+/**
+ * Self-reported device posture (Stage 4.12), carried on session reports.
+ * AFFIRMATIVE KNOWLEDGE ONLY: a fact the collector can't determine is ABSENT,
+ * never "unknown" — the server and UI treat absence as "not reported". Every
+ * field is CLAIMED (a compromised host lies about its own posture); the value
+ * is inventory/compliance visibility, never a security control, and it is
+ * NEVER an authorization input. Rendered with an explicit "self-reported"
+ * label — no attestation theater (agent-directory-roadmap §4e).
+ */
+export type PostureFlag = "enabled" | "disabled";
+export type GatewayPosture = {
+    /** os.version() (e.g. "Darwin Kernel Version 25.5.0: …"), trimmed + capped. */
+    osVersion?: string;
+    /** FileVault (darwin, fdesetup) / dm-crypt device present (linux, lsblk). */
+    diskEncryption?: PostureFlag;
+    /** UEFI SecureBoot efivar (linux). Absent on darwin/win32 in the v1 matrix. */
+    secureBoot?: PostureFlag;
+};
+export declare const POSTURE_MAX: {
+    readonly osVersion: 64;
+};
+/**
+ * A gateway session report (Stage 4.11) — one shape for open/heartbeat/flush/
+ * end. The server upserts by (deviceId, sessionId): the first report creates
+ * the row, later reports overwrite counters (refusing regressions — two
+ * in-flight POSTs may land out of order), a report carrying `endedReason`
+ * closes it (sticky). Everything here is device-CLAIMED except what the server
+ * stamps itself (lastHeartbeatAt = receive time; startedAt is clamped to it).
+ */
+export type GatewaySessionReport = {
+    kind: "session";
+    /** Gateway-generated UUID (crypto.randomUUID); scoped to the device by the upsert key. */
+    sessionId: string;
+    /** Unix ms, client-claimed — the server clamps future skew to receive time. */
+    startedAt: number;
+    /** Connected MCP host per clientInfo (e.g. "claude-code") — the per-connection
+     * attribution that fixes the 4.9 metadata flap; Device.product stays the gateway. */
+    clientProduct?: string;
+    clientProductVersion?: string;
+    /** Self-reported device posture (Stage 4.12) — collected once at gateway
+     * startup, absent until collection completes (the clientProduct lazy-capture
+     * pattern; the idempotent overwrite absorbs the gap). */
+    posture?: GatewayPosture;
+    /** Present ⇒ this report closes the session. */
+    endedReason?: GatewaySessionEndReason;
+} & GatewaySessionCounters;
+/** Postgres Int4 ceiling — the gateway accumulator saturates here and the
+ * server-side narrower rejects beyond it, so the DB column can never overflow. */
+export declare const SESSION_COUNTER_MAX = 2147483647;
+export type GatewayTelemetryReport = GatewayDenyReport | GatewaySessionReport;
+export type GatewayTelemetryRequest = DeviceAuthEnvelope & {
+    purpose: "gateway_telemetry";
+} & GatewayTelemetryReport;
+/** HTTP header names for device-authed requests. (§7) */
+export declare const DEVICE_HEADER: "X-VH-Device";
+export declare const SIGNATURE_HEADER: "X-VH-Signature";
+/** Client-reported agent metadata (Stage 4.9). INFORMATIONAL ONLY — the values
+ * originate from the client and are never an authorization input. */
+export type DeviceClientMeta = {
+    product?: string;
+    productVersion?: string;
+    runtime?: "local" | "cloud";
+    platform?: string;
+};
+/** Unsigned metadata header on device-signed requests. Deliberately NOT part of
+ * the canonical signed body: the metadata is client-claimed either way — a
+ * signature by the device key proves only "the key holder asserts this", and the
+ * key holder is exactly the party who could lie — so signing it adds zero trust
+ * while growing the envelope surface (see stage-4.9 §3.3). */
+export declare const CLIENT_META_HEADER: "X-VH-Client";
+export declare const CLIENT_META_MAX: {
+    readonly product: 64;
+    readonly productVersion: 32;
+    readonly platform: 64;
+    readonly raw: 512;
+};
+/** Field-wise sanitizer: keeps only well-typed, length-capped fields; anything
+ * else is DROPPED, never fatal — metadata must never break pairing or a mint.
+ * Returns null when nothing valid remains. */
+export declare function sanitizeClientMeta(value: unknown): DeviceClientMeta | null;
+/** Parsed device-auth headers. */
+export type DeviceAuthHeader = {
+    /** Value of X-VH-Device. */
+    deviceId: string;
+    /** Value of X-VH-Signature — base64url Ed25519 signature over canonicalJSON(body). */
+    signature: string;
+};
+/**
+ * Deterministic JSON with stably-sorted object keys. The device signs the bytes
+ * of canonicalJSON(body) and the backend verifies over the same bytes, so signer
+ * (MCP) and verifier (backend) must use this identical function.
+ */
+export declare function canonicalJSON(value: unknown): string;
+export * from "./policy.js";

package/dist/index.js

@@ -0,0 +1,168 @@
+// @tiertwo/shared — shared types + pure helpers (zero runtime deps).
+// Single source of truth for token/claim/envelope/payload shapes AND their
+// validators, so web, sdk, and mcp never drift. See docs/ARCHITECTURE.md §6
+// (token), §7 (request flow) and docs/plans/agent-governance/CLEAN-ARCHITECTURE.md
+// §2 (the signed-request model this file implements).
+export const WELL_KNOWN_ACTIONS = ["create_account", "deploy"];
+const ACTION_RE = /^[a-z][a-z0-9_.:-]{0,63}$/;
+export function isValidAction(s) {
+    return typeof s === "string" && ACTION_RE.test(s);
+}
+const RESOURCE_RE = /^[a-z0-9][a-z0-9_.:/-]{0,127}$/i;
+export function isValidResource(s) {
+    return typeof s === "string" && RESOURCE_RE.test(s);
+}
+/**
+ * Assurance tier of the human behind an action, ordered weakest → strongest:
+ * - "sso": an authenticated org employee (SSO); identity not independently proofed.
+ * - "identity_proofed": a Stripe-Identity-verified real human (the consumer bar).
+ * `meetsAuthLevel` enforces an "at least this tier" requirement.
+ */
+export const AUTH_LEVELS = ["sso", "identity_proofed"];
+export function authLevelRank(l) {
+    return AUTH_LEVELS.indexOf(l);
+}
+export function meetsAuthLevel(have, need) {
+    return (typeof have === "string" &&
+        AUTH_LEVELS.includes(have) &&
+        authLevelRank(have) >= authLevelRank(need));
+}
+export function isAuthLevel(s) {
+    return typeof s === "string" && AUTH_LEVELS.includes(s);
+}
+/**
+ * Device-trust ladder (Stage 4.12), ordered weakest → strongest. LINEAR:
+ * - "paired": the device authenticated (exists, not revoked) — key possession,
+ *   the floor every caller clears.
+ * - "managed": + the device belongs to an organization (admins can see, gate,
+ *   and revoke it).
+ * - "verified": + the owning human is identity-proofed (Stripe Identity).
+ * A consumer device with a verified owner is still just "paired" — the ladder
+ * measures how GOVERNED the worker is, and an ungoverned device tops out at the
+ * bottom rung by design. Distinct axis from AUTH_LEVELS ("how proofed is the
+ * human") — see agent-directory-roadmap §4e; do not conflate them.
+ */
+export const DEVICE_TRUST_LEVELS = ["paired", "managed", "verified"];
+export function deviceTrustRank(l) {
+    return DEVICE_TRUST_LEVELS.indexOf(l);
+}
+export function meetsDeviceTrust(have, need) {
+    return (typeof have === "string" &&
+        DEVICE_TRUST_LEVELS.includes(have) &&
+        deviceTrustRank(have) >= deviceTrustRank(need));
+}
+export function isDeviceTrustLevel(s) {
+    return typeof s === "string" && DEVICE_TRUST_LEVELS.includes(s);
+}
+/**
+ * Why a call was refused (Stage 4.10) — the SignEvent.denyReason vocabulary.
+ * The server adjudicates the first three (authorize route); the last three are
+ * gateway-local policy results that reach the ledger via /api/gateway/telemetry.
+ * That split is load-bearing: a gateway may only CLAIM the local subset, so deny
+ * provenance stays derivable with no extra column.
+ */
+export const DENY_REASONS = [
+    "access_required",
+    "not_verified",
+    "insufficient_auth_level",
+    "policy_deny",
+    "no_rule",
+    "unresolved_resource",
+    "insufficient_device_trust", // Stage 4.12 — server-adjudicated, like the tier check
+    // Stage 4.13 — a requireFreshApproval rule matched but no consumable ad-hoc
+    // Approval existed. Server-adjudicated; distinct from access_required on purpose:
+    // this deny opens an ApprovalRequest (fresh per-call confirmation), never a
+    // pending Grant (a standing grant can't satisfy a step-up rule by design).
+    "approval_required",
+];
+export function isDenyReason(s) {
+    return typeof s === "string" && DENY_REASONS.includes(s);
+}
+/** The subset a gateway may claim via telemetry — server-adjudicated reasons are
+ * not claimable (the telemetry narrower rejects them). */
+export const GATEWAY_LOCAL_DENY_REASONS = [
+    "no_rule",
+    "unresolved_resource",
+    "policy_deny",
+];
+export function isGatewayLocalDenyReason(s) {
+    return (typeof s === "string" &&
+        GATEWAY_LOCAL_DENY_REASONS.includes(s));
+}
+/**
+ * SignEvent.action sentinel for denied calls that no rule mapped to a capability
+ * (no_rule / unresolved_resource) — self-describing, and never fabricates a
+ * capability name an admin might have authored. Display/filter only; appears on
+ * deny rows exclusively.
+ */
+export function unmappedToolAction(tool) {
+    return `tool:${tool}`;
+}
+export const POSTURE_MAX = { osVersion: 64 };
+/** Postgres Int4 ceiling — the gateway accumulator saturates here and the
+ * server-side narrower rejects beyond it, so the DB column can never overflow. */
+export const SESSION_COUNTER_MAX = 2_147_483_647;
+/** HTTP header names for device-authed requests. (§7) */
+export const DEVICE_HEADER = "X-VH-Device";
+export const SIGNATURE_HEADER = "X-VH-Signature";
+/** Unsigned metadata header on device-signed requests. Deliberately NOT part of
+ * the canonical signed body: the metadata is client-claimed either way — a
+ * signature by the device key proves only "the key holder asserts this", and the
+ * key holder is exactly the party who could lie — so signing it adds zero trust
+ * while growing the envelope surface (see stage-4.9 §3.3). */
+export const CLIENT_META_HEADER = "X-VH-Client";
+export const CLIENT_META_MAX = {
+    product: 64,
+    productVersion: 32,
+    platform: 64,
+    raw: 512,
+};
+const RUNTIMES = new Set(["local", "cloud"]);
+/** Field-wise sanitizer: keeps only well-typed, length-capped fields; anything
+ * else is DROPPED, never fatal — metadata must never break pairing or a mint.
+ * Returns null when nothing valid remains. */
+export function sanitizeClientMeta(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const v = value;
+    const out = {};
+    const str = (x, max) => typeof x === "string" && x.trim().length > 0 && x.length <= max ? x.trim() : undefined;
+    const product = str(v.product, CLIENT_META_MAX.product);
+    const productVersion = str(v.productVersion, CLIENT_META_MAX.productVersion);
+    const platform = str(v.platform, CLIENT_META_MAX.platform);
+    const runtime = typeof v.runtime === "string" && RUNTIMES.has(v.runtime)
+        ? v.runtime
+        : undefined;
+    if (product)
+        out.product = product;
+    if (productVersion)
+        out.productVersion = productVersion;
+    if (runtime)
+        out.runtime = runtime;
+    if (platform)
+        out.platform = platform;
+    return Object.keys(out).length > 0 ? out : null;
+}
+/**
+ * Deterministic JSON with stably-sorted object keys. The device signs the bytes
+ * of canonicalJSON(body) and the backend verifies over the same bytes, so signer
+ * (MCP) and verifier (backend) must use this identical function.
+ */
+export function canonicalJSON(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value && typeof value === "object") {
+        const obj = value;
+        return Object.fromEntries(Object.keys(obj)
+            .sort()
+            .map((key) => [key, sortKeys(obj[key])]));
+    }
+    return value;
+}
+// The pure policy evaluator + the policy-bundle wire contract (Stage 4). A separate
+// module so the engine's tests live beside it; re-exported here so every consumer
+// (gateway enforcement, apps/web dry-run simulator) imports "@tiertwo/shared".
+export * from "./policy.js";

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,115 @@
+// Unit suite for the shared validators — the single source of truth for
+// action/resource/tier validity that web, sdk, and mcp all import.
+import { describe, it, expect } from "vitest";
+import { authLevelRank, deviceTrustRank, isAuthLevel, isDenyReason, isDeviceTrustLevel, isGatewayLocalDenyReason, isValidAction, isValidResource, meetsAuthLevel, meetsDeviceTrust, unmappedToolAction, } from "./index.js";
+describe("isValidAction", () => {
+    it("accepts well-known and custom lowercase actions", () => {
+        expect(isValidAction("create_account")).toBe(true);
+        expect(isValidAction("deploy")).toBe(true);
+        expect(isValidAction("db.migrate")).toBe(true);
+        expect(isValidAction("scope:read")).toBe(true);
+    });
+    it("rejects malformed actions and non-strings", () => {
+        expect(isValidAction("Bad Action!")).toBe(false); // uppercase + space + punctuation
+        expect(isValidAction("")).toBe(false);
+        expect(isValidAction("1leading_digit")).toBe(false); // must start [a-z]
+        expect(isValidAction("a".repeat(65))).toBe(false); // too long
+        expect(isValidAction(42)).toBe(false);
+        expect(isValidAction(undefined)).toBe(false);
+    });
+});
+describe("isValidResource", () => {
+    it("accepts service names and paths, case-insensitively", () => {
+        expect(isValidResource("svc-x")).toBe(true);
+        expect(isValidResource("Repo/Path")).toBe(true);
+        expect(isValidResource("a.b:c/d-e")).toBe(true);
+    });
+    it("rejects malformed resources and non-strings", () => {
+        expect(isValidResource("has space")).toBe(false);
+        expect(isValidResource("")).toBe(false);
+        expect(isValidResource("-leading-dash")).toBe(false); // must start alnum
+        expect(isValidResource(123)).toBe(false);
+    });
+});
+describe("meetsAuthLevel", () => {
+    it("enforces at-least ordering", () => {
+        expect(meetsAuthLevel("identity_proofed", "sso")).toBe(true);
+        expect(meetsAuthLevel("identity_proofed", "identity_proofed")).toBe(true);
+        expect(meetsAuthLevel("sso", "sso")).toBe(true);
+        expect(meetsAuthLevel("sso", "identity_proofed")).toBe(false);
+    });
+    it("fails closed on unknown / garbage values", () => {
+        expect(meetsAuthLevel("nonsense", "sso")).toBe(false);
+        expect(meetsAuthLevel(undefined, "sso")).toBe(false);
+        expect(meetsAuthLevel(null, "identity_proofed")).toBe(false);
+    });
+    it("ranks tiers weakest → strongest", () => {
+        expect(authLevelRank("sso")).toBeLessThan(authLevelRank("identity_proofed"));
+    });
+});
+describe("isAuthLevel", () => {
+    it("accepts exactly the two tiers, fails closed otherwise", () => {
+        expect(isAuthLevel("sso")).toBe(true);
+        expect(isAuthLevel("identity_proofed")).toBe(true);
+        expect(isAuthLevel("root")).toBe(false);
+        expect(isAuthLevel("")).toBe(false);
+        expect(isAuthLevel(undefined)).toBe(false);
+    });
+});
+describe("meetsDeviceTrust (Stage 4.12)", () => {
+    it("enforces at-least ordering on the linear ladder", () => {
+        expect(meetsDeviceTrust("verified", "paired")).toBe(true);
+        expect(meetsDeviceTrust("verified", "managed")).toBe(true);
+        expect(meetsDeviceTrust("managed", "managed")).toBe(true);
+        expect(meetsDeviceTrust("managed", "verified")).toBe(false);
+        expect(meetsDeviceTrust("paired", "managed")).toBe(false);
+    });
+    it("fails closed on unknown / garbage values", () => {
+        expect(meetsDeviceTrust("root", "paired")).toBe(false);
+        expect(meetsDeviceTrust(undefined, "paired")).toBe(false);
+        expect(meetsDeviceTrust(null, "verified")).toBe(false);
+    });
+    it("ranks rungs weakest → strongest", () => {
+        expect(deviceTrustRank("paired")).toBeLessThan(deviceTrustRank("managed"));
+        expect(deviceTrustRank("managed")).toBeLessThan(deviceTrustRank("verified"));
+    });
+});
+describe("isDeviceTrustLevel", () => {
+    it("accepts exactly the three rungs, fails closed otherwise", () => {
+        expect(isDeviceTrustLevel("paired")).toBe(true);
+        expect(isDeviceTrustLevel("managed")).toBe(true);
+        expect(isDeviceTrustLevel("verified")).toBe(true);
+        expect(isDeviceTrustLevel("attested")).toBe(false);
+        expect(isDeviceTrustLevel("")).toBe(false);
+        expect(isDeviceTrustLevel(undefined)).toBe(false);
+    });
+});
+describe("deny-reason vocabulary (Stage 4.10; grown in 4.12)", () => {
+    it("isDenyReason covers all seven reasons and rejects garbage", () => {
+        for (const r of [
+            "access_required",
+            "not_verified",
+            "insufficient_auth_level",
+            "policy_deny",
+            "no_rule",
+            "unresolved_resource",
+            "insufficient_device_trust",
+        ]) {
+            expect(isDenyReason(r)).toBe(true);
+        }
+        expect(isDenyReason("denied")).toBe(false);
+        expect(isDenyReason(null)).toBe(false);
+    });
+    it("the gateway-claimable subset excludes server-adjudicated reasons", () => {
+        expect(isGatewayLocalDenyReason("no_rule")).toBe(true);
+        expect(isGatewayLocalDenyReason("unresolved_resource")).toBe(true);
+        expect(isGatewayLocalDenyReason("policy_deny")).toBe(true);
+        expect(isGatewayLocalDenyReason("access_required")).toBe(false);
+        expect(isGatewayLocalDenyReason("not_verified")).toBe(false);
+        expect(isGatewayLocalDenyReason("insufficient_auth_level")).toBe(false);
+        expect(isGatewayLocalDenyReason("insufficient_device_trust")).toBe(false);
+    });
+    it("unmappedToolAction prefixes the raw tool name, self-describing", () => {
+        expect(unmappedToolAction("drop_table")).toBe("tool:drop_table");
+    });
+});

package/dist/policy.d.ts

@@ -0,0 +1,106 @@
+import { type Action, type AuthLevel, type DeviceTrustLevel, type Resource } from "./index.js";
+/**
+ * One policy rule, as the evaluator consumes it. The gateway's config type and the
+ * wire `SerializedPolicyRule` are both structurally assignable to this. `resource`
+ * and `resourceFrom` combine into three match shapes per (backend, tool):
+ *  - pinned      (resourceFrom + resource): matches ONE observed value — an exception row;
+ *  - static      (resource only):           a fixed scope, matches every call;
+ *  - wildcard    (resourceFrom only, or neither): covers all values of the tool.
+ */
+export type PolicyRuleInput = {
+    backend: string;
+    /** Exact downstream tool name (un-namespaced). */
+    tool: string;
+    /** The capability this tool exercises → SignEvent.action + Grant.action. */
+    action: Action;
+    /** Pinned match value (with resourceFrom) or static scope; absent = wildcard. */
+    resource?: Resource;
+    /** Dotted path into the call args the observed resource is extracted from. */
+    resourceFrom?: string;
+    requiredAuthLevel?: AuthLevel;
+    /** Minimum device-trust rung for gate rules (Stage 4.12); absent = no gate. */
+    requiredDeviceTrust?: DeviceTrustLevel;
+    /** Assurance step-up (Stage 4.13): a matching call needs a FRESH ad-hoc approval
+     * even under a standing grant. Gate rules only (write-validated upstream). */
+    requireFreshApproval?: boolean;
+    /** Default "gate". "deny" = explicit block (a per-resource exception over a wildcard). */
+    effect?: "gate" | "audit_only" | "deny";
+};
+/** What a matched rule resolves the observed call to. */
+export type PolicyMatch = {
+    action: string;
+    resource: string | null;
+    requiredAuthLevel: AuthLevel | null;
+    /** Carried, never enforced here — the authorize route enforces (Stage 4.12). */
+    requiredDeviceTrust: DeviceTrustLevel | null;
+    /** Carried, never enforced here — authorizeMint enforces (Stage 4.13). */
+    requireFreshApproval: boolean;
+    effect: "gate" | "audit_only";
+};
+/**
+ * Why evaluate() refused (Stage 4.10). Discriminated on the SAME `effect` field
+ * PolicyMatch uses ("gate" | "audit_only" there), so callers narrow with one
+ * check. The policy_deny arm carries the denying rule's real capability so
+ * ledger rows and the simulator never fabricate an action name.
+ */
+export type PolicyDeny = {
+    effect: "deny";
+    reason: "no_rule";
+} | {
+    effect: "deny";
+    reason: "unresolved_resource";
+} | {
+    effect: "deny";
+    reason: "policy_deny";
+    action: string;
+    resource: string | null;
+};
+export type PolicyDecision = PolicyMatch | PolicyDeny;
+/**
+ * Default-deny allowlist with most-specific-(backend, tool, resource) selection
+ * (Stage 4 §4.1). For a call (backend, tool, args):
+ *
+ *  1. Candidates = rules matching (backend, tool). None ⇒ deny.
+ *  2. Resolve the OBSERVED resource once, from the candidates' shared resourceFrom
+ *     (the write side — apps/web lib/policy — enforces that all rules for one
+ *     (backend, tool) agree on it; the first declared wins here). A declared but
+ *     unresolvable/invalid resourceFrom ⇒ deny — never guess, even when a wildcard
+ *     rule also matches. Finite numbers coerce to their string form (real backends
+ *     use integer ids); other non-strings are not guessed.
+ *  3. Select the most specific rule: pinned (resource === observed) beats static
+ *     (fixed resource, no resourceFrom) beats dynamic wildcard (resourceFrom only)
+ *     beats unscoped wildcard (neither).
+ *  4. Selected rule's effect "deny" ⇒ a discriminated policy_deny. Otherwise
+ *     resolve the match.
+ *
+ * Backward-compatible with the Stage 3a/3b single-rule shape: with one candidate,
+ * most-specific ≡ first-match. NOTE one deliberate semantics change: a rule with
+ * BOTH resource and resourceFrom used to resolve as static (resourceFrom ignored);
+ * it is now a pinned exception that only matches its exact observed value.
+ */
+export declare function evaluate(policy: PolicyRuleInput[], backend: string, tool: string, args: Record<string, unknown>): PolicyDecision;
+export type SerializedBackend = {
+    /** Namespace prefix + SignEvent.domain, e.g. "metabase". */
+    name: string;
+    /** Remote MCP endpoint (streamable-HTTP). */
+    url: string;
+    /**
+     * How credentials are minted. Per-user kinds (Stage 4.6) ride the gateway's
+     * brokerTokenSource → /api/gateway/credential: "oauth-broker" = each user links,
+     * "api-key" = each user pastes a personal key into the vault. "org-api-key"
+     * (Stage 4.13) is ORG-provisioned: the admin pastes one service key, and calls
+     * are forwarded server-side via /api/gateway/proxy — the credential never
+     * reaches a device. Nothing secret here.
+     */
+    authKind: "oauth-broker" | "api-key" | "org-api-key";
+    /** Pinned tools/list (array of MCP Tool), served without a per-user token. */
+    toolsSchema: unknown[];
+};
+/** A PolicyRuleInput with `effect` made explicit on the wire (no implicit default). */
+export type SerializedPolicyRule = PolicyRuleInput & {
+    effect: "gate" | "audit_only" | "deny";
+};
+export type PolicyBundle = {
+    backends: SerializedBackend[];
+    policy: SerializedPolicyRule[];
+};

package/dist/policy.js

@@ -0,0 +1,87 @@
+// The pure, default-deny policy evaluator (agent-governance Stage 3a; per-resource
+// selection + `deny` effect added in Stage 4; discriminated deny in Stage 4.10).
+// Lives in @tiertwo/shared — NOT the gateway — because two consumers must run the
+// IDENTICAL function: the gateway's enforcement path (apps/gateway/src/handler.ts)
+// and the dashboard's dry-run simulator (apps/web /api/policy/simulate), which must
+// never drift from what the data plane enforces. Zero I/O; shares the resource
+// grammar via isValidResource.
+//
+// The single most important behavior in the whole gateway: a decision with
+// `effect: "deny"` MUST be treated as "refuse, do NOT forward". Read tools are
+// gated too unless an explicit rule allows them. Since Stage 4.10 the deny is
+// discriminated (no_rule vs unresolved_resource vs policy_deny) so the refusal is
+// reportable to the decision ledger — evaluate() never returns null.
+// See stage-4-governance-control-plane.md §4 and stage-4.10-decision-ledger.md §3.2.
+import { isValidResource, } from "./index.js";
+/** Safe dotted lookup into the call arguments. Returns unknown; never throws. */
+function extractPath(args, path) {
+    return path.split(".").reduce((acc, k) => acc && typeof acc === "object"
+        ? acc[k]
+        : undefined, args);
+}
+/**
+ * Default-deny allowlist with most-specific-(backend, tool, resource) selection
+ * (Stage 4 §4.1). For a call (backend, tool, args):
+ *
+ *  1. Candidates = rules matching (backend, tool). None ⇒ deny.
+ *  2. Resolve the OBSERVED resource once, from the candidates' shared resourceFrom
+ *     (the write side — apps/web lib/policy — enforces that all rules for one
+ *     (backend, tool) agree on it; the first declared wins here). A declared but
+ *     unresolvable/invalid resourceFrom ⇒ deny — never guess, even when a wildcard
+ *     rule also matches. Finite numbers coerce to their string form (real backends
+ *     use integer ids); other non-strings are not guessed.
+ *  3. Select the most specific rule: pinned (resource === observed) beats static
+ *     (fixed resource, no resourceFrom) beats dynamic wildcard (resourceFrom only)
+ *     beats unscoped wildcard (neither).
+ *  4. Selected rule's effect "deny" ⇒ a discriminated policy_deny. Otherwise
+ *     resolve the match.
+ *
+ * Backward-compatible with the Stage 3a/3b single-rule shape: with one candidate,
+ * most-specific ≡ first-match. NOTE one deliberate semantics change: a rule with
+ * BOTH resource and resourceFrom used to resolve as static (resourceFrom ignored);
+ * it is now a pinned exception that only matches its exact observed value.
+ */
+export function evaluate(policy, backend, tool, args) {
+    const candidates = policy.filter((r) => r.backend === backend && r.tool === tool);
+    if (candidates.length === 0) {
+        return { effect: "deny", reason: "no_rule" }; // default-deny
+    }
+    const from = candidates.find((r) => r.resourceFrom !== undefined)?.resourceFrom;
+    let observed = null;
+    if (from !== undefined) {
+        const v = extractPath(args, from);
+        const s = typeof v === "number" && Number.isFinite(v) ? String(v) : v;
+        if (!isValidResource(s)) {
+            // Declared but unresolvable/invalid → deny, don't guess. A DISTINCT reason
+            // from no_rule (Stage 4.10): "a rule governs this tool but the args
+            // couldn't be scoped" is a different — and more suspicious — signal.
+            return { effect: "deny", reason: "unresolved_resource" };
+        }
+        observed = s;
+    }
+    const pinned = candidates.find((r) => r.resourceFrom !== undefined && r.resource === observed);
+    const staticRule = candidates.find((r) => r.resource !== undefined && r.resourceFrom === undefined);
+    const dynamicWildcard = candidates.find((r) => r.resourceFrom !== undefined && r.resource === undefined);
+    const unscopedWildcard = candidates.find((r) => r.resource === undefined && r.resourceFrom === undefined);
+    const rule = pinned ?? staticRule ?? dynamicWildcard ?? unscopedWildcard;
+    // Candidates exist but none selected (e.g. only a pinned exception for a
+    // different resource): honestly "no rule allows THIS call".
+    if (!rule)
+        return { effect: "deny", reason: "no_rule" };
+    if (rule.effect === "deny") {
+        return {
+            effect: "deny",
+            reason: "policy_deny",
+            action: rule.action,
+            resource: rule.resourceFrom !== undefined ? observed : (rule.resource ?? null),
+        };
+    }
+    return {
+        action: rule.action,
+        resource: rule.resourceFrom !== undefined ? observed : (rule.resource ?? null),
+        requiredAuthLevel: rule.requiredAuthLevel ?? null,
+        requiredDeviceTrust: rule.requiredDeviceTrust ?? null,
+        requireFreshApproval: rule.requireFreshApproval === true,
+        effect: rule.effect === "audit_only" ? "audit_only" : "gate",
+    };
+}

package/dist/policy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/policy.test.js

@@ -0,0 +1,204 @@
+// Pure unit tests for the most-specific-match policy evaluator (Stage 4 §4;
+// discriminated deny in Stage 4.10). The load-bearing assertions: default-deny
+// holds (no candidates ⇒ deny no_rule), a pinned rule beats every wildcard, a
+// selected `deny` returns a policy_deny CARRYING the denying rule's action (and
+// only for ITS resource — the wildcard still governs the rest), and a
+// declared-but-unresolvable resourceFrom denies with the DISTINCT
+// unresolved_resource reason even when a wildcard rule would otherwise match.
+import { describe, it, expect } from "vitest";
+import { evaluate } from "./policy.js";
+const NO_RULE = { effect: "deny", reason: "no_rule" };
+const UNRESOLVED = { effect: "deny", reason: "unresolved_resource" };
+describe("evaluate — most-specific (backend, tool, resource) selection", () => {
+    it("denies an unmatched (backend, tool) with no_rule — default-deny holds", () => {
+        const rules = [
+            { backend: "wh", tool: "read", action: "wh.read" },
+        ];
+        expect(evaluate(rules, "wh", "drop_table", {})).toEqual(NO_RULE);
+        expect(evaluate(rules, "other", "read", {})).toEqual(NO_RULE);
+        expect(evaluate([], "wh", "read", {})).toEqual(NO_RULE);
+    });
+    it("selects a pinned rule over the dynamic wildcard for its exact resource", () => {
+        const rules = [
+            { backend: "wh", tool: "sql", action: "wh.sql", resourceFrom: "db" },
+            {
+                backend: "wh",
+                tool: "sql",
+                action: "wh.sql_billing",
+                resourceFrom: "db",
+                resource: "billing",
+                requiredAuthLevel: "identity_proofed",
+            },
+        ];
+        expect(evaluate(rules, "wh", "sql", { db: "billing" })).toEqual({
+            action: "wh.sql_billing",
+            resource: "billing",
+            requiredAuthLevel: "identity_proofed",
+            requiredDeviceTrust: null,
+            requireFreshApproval: false,
+            effect: "gate",
+        });
+        // Any other observed value falls through to the wildcard.
+        expect(evaluate(rules, "wh", "sql", { db: "sales" })).toEqual({
+            action: "wh.sql",
+            resource: "sales",
+            requiredAuthLevel: null,
+            requiredDeviceTrust: null,
+            requireFreshApproval: false,
+            effect: "gate",
+        });
+    });
+    it("a pinned deny carves out one resource while the wildcard still allows others", () => {
+        const rules = [
+            { backend: "wh", tool: "sql", action: "wh.sql", resourceFrom: "db" },
+            { backend: "wh", tool: "sql", action: "wh.sql", resourceFrom: "db", resource: "5", effect: "deny" },
+        ];
+        // The policy_deny carries the denying rule's real action + observed resource.
+        const denied = { effect: "deny", reason: "policy_deny", action: "wh.sql", resource: "5" };
+        expect(evaluate(rules, "wh", "sql", { db: 5 })).toEqual(denied); // numeric id coerces, then denies
+        expect(evaluate(rules, "wh", "sql", { db: "5" })).toEqual(denied);
+        expect(evaluate(rules, "wh", "sql", { db: "6" })).toEqual({
+            action: "wh.sql",
+            resource: "6",
+            requiredAuthLevel: null,
+            requiredDeviceTrust: null,
+            requireFreshApproval: false,
+            effect: "gate",
+        });
+    });
+    it("denies with policy_deny when the only matching rule is a deny", () => {
+        const rules = [
+            { backend: "wh", tool: "wipe", action: "wh.wipe", effect: "deny" },
+        ];
+        expect(evaluate(rules, "wh", "wipe", {})).toEqual({
+            effect: "deny",
+            reason: "policy_deny",
+            action: "wh.wipe",
+            resource: null,
+        });
+    });
+    it("selects a static rule over wildcards, but under a pinned rule", () => {
+        const rules = [
+            { backend: "wh", tool: "cfg", action: "wh.cfg_any" }, // unscoped wildcard
+            { backend: "wh", tool: "cfg", action: "wh.cfg_fixed", resource: "prod" }, // static
+        ];
+        expect(evaluate(rules, "wh", "cfg", {})).toEqual({
+            action: "wh.cfg_fixed",
+            resource: "prod",
+            requiredAuthLevel: null,
+            requiredDeviceTrust: null,
+            requireFreshApproval: false,
+            effect: "gate",
+        });
+    });
+    it("selects the dynamic wildcard over the unscoped wildcard", () => {
+        const rules = [
+            { backend: "wh", tool: "sql", action: "wh.sql_unscoped" },
+            { backend: "wh", tool: "sql", action: "wh.sql_scoped", resourceFrom: "db" },
+        ];
+        expect(evaluate(rules, "wh", "sql", { db: "sales" })).toEqual({
+            action: "wh.sql_scoped",
+            resource: "sales",
+            requiredAuthLevel: null,
+            requiredDeviceTrust: null,
+            requireFreshApproval: false,
+            effect: "gate",
+        });
+    });
+    it("denies an unresolvable resourceFrom (unresolved_resource) even when an unscoped wildcard exists", () => {
+        // Once any candidate declares resourceFrom, an unresolvable observed resource
+        // denies the call — falling back to a coarser rule would guess at scope. The
+        // reason is DISTINCT from no_rule: a rule governs this tool.
+        const rules = [
+            { backend: "wh", tool: "sql", action: "wh.sql", resourceFrom: "db" },
+            { backend: "wh", tool: "sql", action: "wh.sql_any" },
+        ];
+        expect(evaluate(rules, "wh", "sql", {})).toEqual(UNRESOLVED); // missing
+        expect(evaluate(rules, "wh", "sql", { db: {} })).toEqual(UNRESOLVED); // non-coercible
+        expect(evaluate(rules, "wh", "sql", { db: true })).toEqual(UNRESOLVED); // boolean
+        expect(evaluate(rules, "wh", "sql", { db: "" })).toEqual(UNRESOLVED); // invalid string
+    });
+    it("backward-compat: the migrated Metabase execute_sql rule resolves exactly as 3b (§4.2)", () => {
+        const rules = [
+            {
+                backend: "metabase",
+                tool: "execute_sql",
+                action: "metabase.execute_sql",
+                resourceFrom: "database_id",
+                requiredAuthLevel: "identity_proofed",
+            },
+        ];
+        expect(evaluate(rules, "metabase", "execute_sql", { database_id: 5, sql: "select 1" })).toEqual({
+            action: "metabase.execute_sql",
+            resource: "5",
+            requiredAuthLevel: "identity_proofed",
+            requiredDeviceTrust: null,
+            requireFreshApproval: false,
+            effect: "gate",
+        });
+    });
+    it("resolves audit_only and defaults effect to gate (unchanged from 3b)", () => {
+        const rules = [
+            { backend: "mb", tool: "search", action: "mb.read", effect: "audit_only" },
+            { backend: "mb", tool: "ping", action: "mb.ping" },
+        ];
+        expect(evaluate(rules, "mb", "search", {}).effect).toBe("audit_only");
+        expect(evaluate(rules, "mb", "ping", {}).effect).toBe("gate");
+    });
+    it("extracts a dotted resourceFrom path", () => {
+        const rules = [
+            { backend: "deep", tool: "nested", action: "deep.read", resourceFrom: "params.db" },
+        ];
+        expect(evaluate(rules, "deep", "nested", { params: { db: "warehouse" } })).toMatchObject({
+            resource: "warehouse",
+        });
+        expect(evaluate(rules, "deep", "nested", { params: {} })).toEqual(UNRESOLVED);
+    });
+    it("carries requiredDeviceTrust in the match without enforcing it (Stage 4.12)", () => {
+        const rules = [
+            {
+                backend: "wh",
+                tool: "deploy",
+                action: "wh.deploy",
+                requiredDeviceTrust: "verified",
+            },
+        ];
+        // Carried, never enforced here — the authorize route enforces.
+        expect(evaluate(rules, "wh", "deploy", {})).toEqual({
+            action: "wh.deploy",
+            resource: null,
+            requiredAuthLevel: null,
+            requiredDeviceTrust: "verified",
+            requireFreshApproval: false,
+            effect: "gate",
+        });
+    });
+    it("carries requireFreshApproval in the match without enforcing it (Stage 4.13)", () => {
+        const rules = [
+            {
+                backend: "wh",
+                tool: "deploy",
+                action: "wh.deploy",
+                requireFreshApproval: true,
+            },
+        ];
+        // Carried, never enforced here — authorizeMint skips the standing-grant arm.
+        expect(evaluate(rules, "wh", "deploy", {})).toEqual({
+            action: "wh.deploy",
+            resource: null,
+            requiredAuthLevel: null,
+            requiredDeviceTrust: null,
+            requireFreshApproval: true,
+            effect: "gate",
+        });
+    });
+    it("a pinned-only candidate set denies OTHER resources as no_rule, not policy_deny", () => {
+        // The only rule is a pinned exception for resource "5"; an observed "7" selects
+        // nothing — honestly "no rule allows THIS call" (a distinct fact from an
+        // explicit deny rule matching it).
+        const rules = [
+            { backend: "wh", tool: "sql", action: "wh.sql", resourceFrom: "db", resource: "5" },
+        ];
+        expect(evaluate(rules, "wh", "sql", { db: "7" })).toEqual(NO_RULE);
+    });
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@tiertwo/shared",
+  "version": "0.1.0",
+  "description": "Internal shared types and pure helpers for @tiertwo/* — token/claim shapes, canonicalJSON, and device-auth header constants. Not a stable public API.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Tier Two",
+  "homepage": "https://github.com/Jordan-M/verified-human/tree/master/packages/shared#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jordan-M/verified-human.git",
+    "directory": "packages/shared"
+  },
+  "bugs": {
+    "url": "https://github.com/Jordan-M/verified-human/issues"
+  },
+  "keywords": [
+    "tiertwo",
+    "verified-human"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "echo no-op",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}