@proof-holdings/delegation-self-refusal 0.1.0

package/dist/install.js

@@ -0,0 +1,123 @@
+import { DEFAULT_BASE_URL } from './poll.js';
+import { assertInstallableBeforeRegistration, assertNotAlreadyInstalled, markInstalled, wrapRegistrar, } from './registrar.js';
+import { resolveOptions } from './verdict.js';
+import { createBreaker } from './showcase/breaker.js';
+import { createLayerSurfaceFetch, createMarkedFetch } from './showcase/marked-fetch.js';
+import { registerShowcase, SHOWCASE_TOOL_NAMES } from './showcase/tools.js';
+import { showcaseInstructionsParagraph } from './showcase/instructions.js';
+/** Version reported in the `X-Proof-Surface` header. Kept in lockstep with package.json by a drift test. */
+export const SHOWCASE_VERSION = '0.1.0';
+/**
+ * Installs the self-refusal gate AND the three-tool Proof showcase in one call — the alternative
+ * to `guardDelegation` for a publisher who wants their users to see Proof inside the server they
+ * already have.
+ *
+ * The ORDER below is the whole reason this is a separate entry point rather than a flag, and it is
+ * not reproducible by composing the two halves from outside:
+ *
+ *   1. precondition — nothing registered yet, and this layer not already installed;
+ *   2. capture the ORIGINAL, un-gated registrars;
+ *   3. register the showcase through them;
+ *   4. append the Proof recognition paragraph to `server.server._instructions` — unconditionally,
+ *      on both the token and no-token paths, degrading silently on either failure class (the field
+ *      absent, or the read/write throwing) rather than aborting an otherwise-successful install;
+ *   5. only then patch `server.tool` / `server.registerTool` with the gate;
+ *   6. return the gating registrar.
+ *
+ * Registering the showcase BEFORE `guardDelegation` is impossible — it throws on any pre-existing
+ * tool (`registrar.ts`'s precondition), taking the publisher's server down at startup. Registering
+ * it AFTER means the gate covers it, and a revoked delegation kills `proof_check_this_server` —
+ * the one tool whose job is to report that revocation. Hence: inside, between capture and patch.
+ *
+ * The un-gated registrar captured at step 2 is never returned and never exported WHEN A TOKEN IS
+ * CONFIGURED. A publisher who got hold of it could route their own tool around the gate, silently
+ * nulling the self-enforcement while the installation still looked correct from the outside (SC-2).
+ * The one exception is the no-token path below, which returns exactly that registrar — correctly,
+ * since with no token nothing is gated at all and it is identical to `guardDelegation`'s opt-out.
+ * Stated rather than left as an absolute, because an unqualified claim beside a guard is the kind
+ * of sentence that stops being read once it is false.
+ *
+ * With no `opts.token` the showcase is still installed but NOTHING is gated — the same opt-out
+ * `guardDelegation` offers, and `proof_check_this_server` then reports `configured: false` rather
+ * than dressing the absence up as a positive verdict.
+ */
+/**
+ * Appends the Proof recognition paragraph to `server.server._instructions` (SC-1..6), the SDK's
+ * private field the `initialize` handler reads on every connection. Never throws: called between
+ * `markInstalled` (already committed) and the no-token early return, a throw here would abort an
+ * otherwise-successful install after the gate is already live.
+ *
+ * Two failure classes, one degradation: `server.server` may simply not exist (an unrecognized SDK
+ * shape, or a test double) — handled by the early return; or reading/building/writing
+ * `_instructions` may throw (a frozen object, a future getter-only field) — handled by the
+ * try/catch. Both leave the server exactly as capable as it was before this call, just without the
+ * paragraph.
+ *
+ * Truthy check, not `typeof === 'string'` (SC-1): the SDK itself treats an empty string as absent
+ * (`server/index.js`'s `...(this._instructions && {instructions: this._instructions})`), so
+ * appending after one would silently double as "replace nothing with the paragraph" — which is the
+ * outcome the truthy check already produces on its own, without a special case.
+ */
+function appendShowcaseInstructions(server, principal) {
+    const inner = server.server;
+    if (inner === undefined)
+        return;
+    try {
+        const existing = inner._instructions;
+        const paragraph = showcaseInstructionsParagraph(principal);
+        inner._instructions = existing ? `${existing}\n\n${paragraph}` : paragraph;
+    }
+    catch {
+        // Read or write threw — degrade silently, the gate above is already live.
+    }
+}
+export function installProofLayer(server, opts) {
+    assertNotAlreadyInstalled(server, 'installProofLayer');
+    assertInstallableBeforeRegistration(server, 'installProofLayer');
+    const baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;
+    const resolved = opts.token
+        ? resolveOptions({ ...opts, token: opts.token, fetchImpl: createLayerSurfaceFetch(SHOWCASE_VERSION) })
+        : null;
+    const originalTool = server.tool.bind(server);
+    const originalRegisterTool = typeof server.registerTool === 'function' ? server.registerTool.bind(server) : undefined;
+    try {
+        registerShowcase(originalTool, {
+            resolved,
+            principal: opts.principal,
+            baseUrl,
+            verifyBreaker: createBreaker(),
+            connectBreaker: createBreaker(),
+            markedFetch: createMarkedFetch(SHOWCASE_VERSION),
+        });
+    }
+    catch (error) {
+        // ALL-OR-NOTHING. A throw on the second or third registration would otherwise leave one or two
+        // Proof-named tools on a server whose `tool`/`registerTool` were never patched — so a
+        // publisher who defensively wraps this call in try/catch would run with ZERO self-refusal while
+        // advertising tools that imply otherwise. The trigger is not hypothetical: it is the duplicate
+        // `zod` instance SC-17 exists to prevent, failing inside the SDK's schema conversion. Rolling
+        // back also keeps a retry possible — otherwise the precondition check would see OUR tools and
+        // answer with the message written for a publisher who registered first.
+        for (const name of SHOWCASE_TOOL_NAMES) {
+            delete server._registeredTools[name];
+        }
+        throw error;
+    }
+    // The kind must match what actually happened: with no token this call installs NO gate and
+    // returns the RAW registrar below — which is the definition of `optout`, not `gated`. Recording
+    // it as gated made every later refusal on such a server assert a layer that is not there: the
+    // very defect the kind split was introduced to remove, surviving on the other entry point.
+    // The POSITION stays above the no-token return — a round-3 finding rests on it.
+    markInstalled(server, resolved ? 'gated' : 'optout');
+    appendShowcaseInstructions(server, opts.principal);
+    if (!resolved) {
+        return originalTool;
+    }
+    const wrappedTool = wrapRegistrar(originalTool, resolved);
+    server.tool = wrappedTool;
+    if (originalRegisterTool) {
+        server.registerTool = wrapRegistrar(originalRegisterTool, resolved);
+    }
+    return wrappedTool;
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"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"}

package/dist/poll.d.ts

@@ -0,0 +1,10 @@
+import type { PollResult } from './types.js';
+export declare const DEFAULT_BASE_URL = "https://api.proof.holdings";
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * Polls `POST {baseUrl}/api/v1/proofs/validate` with the delegation token and maps the response
+ * to a PollResult. Never sends `identifier` — a delegation has none to bind against
+ * (src/controllers/proofs.ts validateDelegationBranch rejects that combination outright).
+ */
+export declare function pollDelegationStatus(token: string, baseUrl?: string, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<PollResult>;
+//# sourceMappingURL=poll.d.ts.map

package/dist/poll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll.d.ts","sourceRoot":"","sources":["../src/poll.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,eAAO,MAAM,gBAAgB,+BAA+B,CAAC;AAC7D,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAUzC;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,MAAyB,EAClC,SAAS,GAAE,OAAO,KAAa,EAC/B,SAAS,GAAE,MAA2B,GACrC,OAAO,CAAC,UAAU,CAAC,CAkDrB"}

package/dist/poll.js

@@ -0,0 +1,60 @@
+export const DEFAULT_BASE_URL = 'https://api.proof.holdings';
+export const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * A `valid: false` reason the issuer can hand back that is NOT a definitive answer — it means
+ * the issuer's own registry lookup failed, not that the delegation was checked and rejected.
+ * Mirrors `packages/delegation-verifier/src/status.ts`, which fails the same way closed for the
+ * identical reason on the read-only verification side.
+ */
+const UNRESOLVED_REASON = 'status_unavailable';
+/**
+ * Polls `POST {baseUrl}/api/v1/proofs/validate` with the delegation token and maps the response
+ * to a PollResult. Never sends `identifier` — a delegation has none to bind against
+ * (src/controllers/proofs.ts validateDelegationBranch rejects that combination outright).
+ */
+export async function pollDelegationStatus(token, baseUrl = DEFAULT_BASE_URL, fetchImpl = fetch, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    let response;
+    try {
+        response = await fetchImpl(`${baseUrl}/api/v1/proofs/validate`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ proof_token: token }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch {
+        return { kind: 'unresolved' };
+    }
+    if (!response.ok) {
+        return { kind: 'unresolved' };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        return { kind: 'unresolved' };
+    }
+    if (typeof body !== 'object' || body === null) {
+        return { kind: 'unresolved' };
+    }
+    const parsed = body;
+    // Strict boolean check, not presence + truthy — mirrors
+    // packages/delegation-verifier/src/status.ts's `typeof body.valid !== 'boolean'` gate on the
+    // identical backend contract. A non-boolean `valid` is a response this package cannot trust.
+    if (typeof parsed.valid !== 'boolean') {
+        return { kind: 'unresolved' };
+    }
+    if (parsed.valid) {
+        return { kind: 'valid' };
+    }
+    if (parsed.reason === UNRESOLVED_REASON) {
+        return { kind: 'unresolved' };
+    }
+    return {
+        kind: 'refused',
+        reason: typeof parsed.reason === 'string' ? parsed.reason : 'invalid',
+        message: typeof parsed.message === 'string' ? parsed.message : 'This delegation is not valid',
+    };
+}
+//# sourceMappingURL=poll.js.map

package/dist/poll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll.js","sourceRoot":"","sources":["../src/poll.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,gBAAgB,GAAG,4BAA4B,CAAC;AAC7D,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAa,EACb,UAAkB,gBAAgB,EAClC,YAA0B,KAAK,EAC/B,YAAoB,kBAAkB;IAEtC,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,OAAO,yBAAyB,EAAE;YAC9D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;YAC5C,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;SACvC,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IAChC,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IAChC,CAAC;IAED,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IAChC,CAAC;IAED,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IAChC,CAAC;IAED,MAAM,MAAM,GAAG,IAA+D,CAAC;IAE/E,wDAAwD;IACxD,6FAA6F;IAC7F,6FAA6F;IAC7F,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IAChC,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,iBAAiB,EAAE,CAAC;QACxC,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IAChC,CAAC;IAED,OAAO;QACL,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;QACrE,OAAO,EAAE,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,8BAA8B;KAC9F,CAAC;AACJ,CAAC"}

package/dist/refusal.d.ts

@@ -0,0 +1,92 @@
+/**
+ * What a refused tool call says.
+ *
+ * This gate is SILENT on success and speaks only when it refuses. Under `guardDelegation` alone,
+ * that makes this string the first — often the only — thing a cold reader ever sees from Proof.
+ * Under `installProofLayer` it is not: the showcase's own tool descriptions already name Proof and
+ * the same revocation risk before any call is ever refused. Either way this string names Proof,
+ * names the publisher, gives one short link, and gives ONE action that can actually resolve the
+ * state it describes.
+ *
+ * The reason→phrase MAP is the load-bearing part, not decoration. `RefusedVerdict.reason` carries
+ * two categorically different classes of fact and one template cannot tell them apart:
+ *
+ *   - the issuer ANSWERED and said no (`poll.ts` maps the `/proofs/validate` body straight
+ *     through) — a decision, which retrying cannot change and which the publisher can explain;
+ *   - `verdict.ts` gave up asking (`unresolved_at_startup`, `grace_exhausted`) — WE COULD NOT ASK,
+ *     which is a connectivity failure wherever this server runs.
+ *
+ * Rendered identically, a publisher with blocked egress reads a message that looks exactly like a
+ * real revocation, and the one action offered ("contact the publisher") sends them to ask about a
+ * decision nobody made while the actual fault goes unmentioned.
+ */
+export declare const REFUSAL_DETAILS_URL = "proof.holdings/delegation";
+/**
+ * Where the definitive-refusal wording comes from — the issuer answered and the answer was no.
+ *
+ * The last two are DEFENSIVE rather than reachable: `poll.ts` never sends an `identifier` (a
+ * delegation has none to bind against), and the issuer emits `identifier_unverifiable` only when
+ * one was supplied, `identifier_mismatch` only from the proof branch. They are carried because the
+ * cost of a phrase is nothing and the cost of an unmapped reason is the fallback below, which is
+ * deliberately vaguer than a mapped one.
+ */
+export declare const PUBLISHER_DECISION_REASONS: readonly ["revoked", "suspended", "expired", "unknown_delegation", "invalid", "identifier_unverifiable", "identifier_mismatch"];
+/**
+ * Produced by `verdict.ts`, never by the issuer. Kept as its own list rather than as a `default`
+ * arm, because the branch is defined by what it must NOT say.
+ */
+export declare const UNREACHABLE_REASONS: readonly ["unresolved_at_startup", "grace_exhausted"];
+export declare function isUnreachableRefusal(reason: string): boolean;
+export declare const UNREACHABLE_LEADS: Record<string, (principal: string) => string>;
+/**
+ * The issuer may introduce a reason this version has never heard of — `poll.ts` passes
+ * `parsed.reason` through verbatim rather than validating it against a list, carving out exactly
+ * ONE string (`status_unavailable`) as non-definitive. Everything else arrives here as a refusal.
+ *
+ * So the call is refused — an unrecognized verdict fails CLOSED everywhere else in this package —
+ * but the SENTENCE claims less than a mapped one does. It deliberately omits "retrying will not fix
+ * this": that phrase is a statement about a state this version cannot classify, and if the issuer's
+ * new reason turns out to be transient, it is simply false. It names no act, and carries the reason
+ * through so an operator can look it up — TRUNCATED past `MAX_ISSUER_REASON`, comfortably above
+ * every code the issuer emits (the longest, `identifier_unverifiable`, is 23). ("raw" and "verbatim" stood here and in the README for one round after the bound
+ * landed, and the note written to record that claimed BOTH were fixed while the README still
+ * said verbatim — the same drift one file over, hidden by its own correction. Fixed the round
+ * after that, by a reviewer who read the document instead of the note about it.)
+ */
+/**
+ * Bounds on issuer-controlled text that reaches an agent's context, sized BY WHAT EACH BOUNDS.
+ *
+ * `poll.ts` accepts any string of any length for both `reason` and `message`, and whatever it
+ * accepts lands in the caller's context. `showcase/connect.ts` already caps and refuses redirects
+ * on its remote read for exactly the "this becomes instructions" reason; these paths had none.
+ *
+ * Two constants rather than one, and the split is not tidiness — one shared number was measured
+ * doing real damage. `reason` is a CODE (longest the issuer emits: `identifier_unverifiable`, 23),
+ * `message` is free-form PROSE, and `verdict.ts` writes its own 67-character sentence for
+ * `grace_exhausted`. A single code-sized cap therefore truncated the one string in the whole
+ * reachable set that is OURS, in the unreachable branch SC-6 exists to make legible. The package
+ * already separates budgets this way (`SHOWCASE_TIMEOUT_MS` vs `SHOWCASE_PER_REQUEST_TIMEOUT_MS`).
+ *
+ * Both numbers are stated against the reachable set rather than chosen. Longest reason the issuer
+ * emits: `identifier_unverifiable`, 23. Longest MESSAGE that can reach this package: 52
+ * (`Invalid delegation token: unsupported schema version`, from the token-validation catch arm in
+ * `controllers/proofs.ts` — an earlier version of this comment said 42, having enumerated only the
+ * registry branches and missed the arm that emits `invalid`/`expired`). Ours: `grace_exhausted` at
+ * 67, growing one character per 10× failure count. So the prose bound sits ~3× above anything
+ * reachable.
+ *
+ * Pinned on both sides, but not where this comment first claimed: below ~68 the grace case reddens;
+ * ABOVE, the ceiling is the whole-payload assertion (~450), not the per-field one — that field is a
+ * function of the reason bound, not this one. Measured after a reviewer mutated the constant.
+ */
+export declare const MAX_ISSUER_REASON = 64;
+export declare const MAX_ISSUER_MESSAGE = 200;
+/**
+ * Truncates by CODE POINT, not code unit: `slice` at a fixed index can cut a surrogate pair in half
+ * and leave a lone surrogate in the output. Unreachable against our own issuer (its codes are ASCII)
+ * — but this bound exists for the case of a hostile one, which is precisely the caller that would
+ * send such a string deliberately.
+ */
+export declare function boundIssuerText(value: string, limit: number): string;
+export declare function refusalMessage(principal: string, reason: string): string;
+//# sourceMappingURL=refusal.d.ts.map

package/dist/refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.d.ts","sourceRoot":"","sources":["../src/refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAE/D;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,iIAQ7B,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,mBAAmB,uDAAwD,CAAC;AAEzF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE5D;AAmCD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAS3E,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQpE;AAiCD,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA4BxE"}

package/dist/refusal.js

@@ -0,0 +1,188 @@
+/**
+ * What a refused tool call says.
+ *
+ * This gate is SILENT on success and speaks only when it refuses. Under `guardDelegation` alone,
+ * that makes this string the first — often the only — thing a cold reader ever sees from Proof.
+ * Under `installProofLayer` it is not: the showcase's own tool descriptions already name Proof and
+ * the same revocation risk before any call is ever refused. Either way this string names Proof,
+ * names the publisher, gives one short link, and gives ONE action that can actually resolve the
+ * state it describes.
+ *
+ * The reason→phrase MAP is the load-bearing part, not decoration. `RefusedVerdict.reason` carries
+ * two categorically different classes of fact and one template cannot tell them apart:
+ *
+ *   - the issuer ANSWERED and said no (`poll.ts` maps the `/proofs/validate` body straight
+ *     through) — a decision, which retrying cannot change and which the publisher can explain;
+ *   - `verdict.ts` gave up asking (`unresolved_at_startup`, `grace_exhausted`) — WE COULD NOT ASK,
+ *     which is a connectivity failure wherever this server runs.
+ *
+ * Rendered identically, a publisher with blocked egress reads a message that looks exactly like a
+ * real revocation, and the one action offered ("contact the publisher") sends them to ask about a
+ * decision nobody made while the actual fault goes unmentioned.
+ */
+export const REFUSAL_DETAILS_URL = 'proof.holdings/delegation';
+/**
+ * Where the definitive-refusal wording comes from — the issuer answered and the answer was no.
+ *
+ * The last two are DEFENSIVE rather than reachable: `poll.ts` never sends an `identifier` (a
+ * delegation has none to bind against), and the issuer emits `identifier_unverifiable` only when
+ * one was supplied, `identifier_mismatch` only from the proof branch. They are carried because the
+ * cost of a phrase is nothing and the cost of an unmapped reason is the fallback below, which is
+ * deliberately vaguer than a mapped one.
+ */
+export const PUBLISHER_DECISION_REASONS = [
+    'revoked',
+    'suspended',
+    'expired',
+    'unknown_delegation',
+    'invalid',
+    'identifier_unverifiable',
+    'identifier_mismatch',
+];
+/**
+ * Produced by `verdict.ts`, never by the issuer. Kept as its own list rather than as a `default`
+ * arm, because the branch is defined by what it must NOT say.
+ */
+export const UNREACHABLE_REASONS = ['unresolved_at_startup', 'grace_exhausted'];
+export function isUnreachableRefusal(reason) {
+    return UNREACHABLE_REASONS.includes(reason);
+}
+/**
+ * The lead sentence per reason. Each states WHAT happened in words a non-specialist reads
+ * correctly on the first pass, and each definitive one carries "retrying will not fix this" —
+ * the single instruction an agent needs in order to stop.
+ */
+const PUBLISHER_DECISION_LEADS = {
+    revoked: (principal) => `${principal}'s authorization to run this was revoked, and Proof (proof.holdings) cannot ` +
+        'confirm it as valid — retrying will not fix this.',
+    suspended: (principal) => `${principal}'s authorization to run this is paused, and Proof (proof.holdings) cannot ` +
+        'confirm it as valid while the pause holds — retrying will not fix this.',
+    expired: (principal) => `${principal}'s authorization to run this has expired, and Proof (proof.holdings) cannot ` +
+        'confirm it as valid — retrying will not fix this.',
+    unknown_delegation: (principal) => `Proof (proof.holdings) has no record of an authorization for ${principal} to run this, so ` +
+        'it cannot be confirmed as valid — retrying will not fix this.',
+    // Deliberately NOT "rejected … as invalid". `poll.ts` synthesises `reason: 'invalid'` when the
+    // issuer answers `valid: false` with no reason string at all, so an attributed act here would be
+    // manufactured from an absent field — the same over-claim the fallback below exists to avoid, one
+    // arm over. "does not consider valid" is true whether the issuer named the reason or not.
+    invalid: (principal) => `Proof (proof.holdings) does not consider ${principal}'s authorization to run this valid — ` +
+        'retrying will not fix this.',
+    identifier_unverifiable: (principal) => `Proof (proof.holdings) could not check ${principal}'s authorization to run this against the ` +
+        'identifier it was asked to bind, so it cannot confirm it — retrying will not fix this.',
+    identifier_mismatch: (principal) => `${principal}'s authorization to run this names a different subject than the one it was ` +
+        'checked against, so Proof (proof.holdings) cannot confirm it — retrying will not fix this.',
+};
+export const UNREACHABLE_LEADS = {
+    unresolved_at_startup: (principal) => `Proof (proof.holdings) could not be reached to confirm ${principal}'s authorization to run ` +
+        `this, so this call is refused rather than assumed — a connectivity failure here, not a ` +
+        `decision by ${principal}.`,
+    grace_exhausted: (principal) => 'Proof (proof.holdings) has been unreachable for several consecutive checks, so ' +
+        `${principal}'s authorization to run this can no longer be confirmed — a connectivity ` +
+        `failure here, not a decision by ${principal}.`,
+};
+/**
+ * The issuer may introduce a reason this version has never heard of — `poll.ts` passes
+ * `parsed.reason` through verbatim rather than validating it against a list, carving out exactly
+ * ONE string (`status_unavailable`) as non-definitive. Everything else arrives here as a refusal.
+ *
+ * So the call is refused — an unrecognized verdict fails CLOSED everywhere else in this package —
+ * but the SENTENCE claims less than a mapped one does. It deliberately omits "retrying will not fix
+ * this": that phrase is a statement about a state this version cannot classify, and if the issuer's
+ * new reason turns out to be transient, it is simply false. It names no act, and carries the reason
+ * through so an operator can look it up — TRUNCATED past `MAX_ISSUER_REASON`, comfortably above
+ * every code the issuer emits (the longest, `identifier_unverifiable`, is 23). ("raw" and "verbatim" stood here and in the README for one round after the bound
+ * landed, and the note written to record that claimed BOTH were fixed while the README still
+ * said verbatim — the same drift one file over, hidden by its own correction. Fixed the round
+ * after that, by a reviewer who read the document instead of the note about it.)
+ */
+/**
+ * Bounds on issuer-controlled text that reaches an agent's context, sized BY WHAT EACH BOUNDS.
+ *
+ * `poll.ts` accepts any string of any length for both `reason` and `message`, and whatever it
+ * accepts lands in the caller's context. `showcase/connect.ts` already caps and refuses redirects
+ * on its remote read for exactly the "this becomes instructions" reason; these paths had none.
+ *
+ * Two constants rather than one, and the split is not tidiness — one shared number was measured
+ * doing real damage. `reason` is a CODE (longest the issuer emits: `identifier_unverifiable`, 23),
+ * `message` is free-form PROSE, and `verdict.ts` writes its own 67-character sentence for
+ * `grace_exhausted`. A single code-sized cap therefore truncated the one string in the whole
+ * reachable set that is OURS, in the unreachable branch SC-6 exists to make legible. The package
+ * already separates budgets this way (`SHOWCASE_TIMEOUT_MS` vs `SHOWCASE_PER_REQUEST_TIMEOUT_MS`).
+ *
+ * Both numbers are stated against the reachable set rather than chosen. Longest reason the issuer
+ * emits: `identifier_unverifiable`, 23. Longest MESSAGE that can reach this package: 52
+ * (`Invalid delegation token: unsupported schema version`, from the token-validation catch arm in
+ * `controllers/proofs.ts` — an earlier version of this comment said 42, having enumerated only the
+ * registry branches and missed the arm that emits `invalid`/`expired`). Ours: `grace_exhausted` at
+ * 67, growing one character per 10× failure count. So the prose bound sits ~3× above anything
+ * reachable.
+ *
+ * Pinned on both sides, but not where this comment first claimed: below ~68 the grace case reddens;
+ * ABOVE, the ceiling is the whole-payload assertion (~450), not the per-field one — that field is a
+ * function of the reason bound, not this one. Measured after a reviewer mutated the constant.
+ */
+export const MAX_ISSUER_REASON = 64;
+export const MAX_ISSUER_MESSAGE = 200;
+/**
+ * Truncates by CODE POINT, not code unit: `slice` at a fixed index can cut a surrogate pair in half
+ * and leave a lone surrogate in the output. Unreachable against our own issuer (its codes are ASCII)
+ * — but this bound exists for the case of a hostile one, which is precisely the caller that would
+ * send such a string deliberately.
+ */
+export function boundIssuerText(value, limit) {
+    // `wrapRegistrar`'s dispatch is an ALLOW-list precisely so a shape the return type does not admit
+    // still refuses rather than runs — and that arm then calls through here. Spreading a non-string
+    // throws, which would turn the fail-closed path's own refusal into a thrown error inside a
+    // publisher's process: the defensive posture asserted in two places and implemented in one.
+    if (typeof value !== 'string')
+        return String(value);
+    const points = [...value];
+    return points.length > limit ? `${points.slice(0, limit).join('')}…` : value;
+}
+function fallbackLead(principal, reason) {
+    const echoed = boundIssuerText(reason, MAX_ISSUER_REASON);
+    return (`Proof (proof.holdings) cannot confirm ${principal}'s authorization to run this: it answered ` +
+        `with a reason this version of the check does not recognise (${echoed}).`);
+}
+/**
+ * Reads a lead WITHOUT inheriting one from `Object.prototype`.
+ *
+ * `reason` is network-derived and unvalidated — `poll.ts` passes the issuer's own string through
+ * for every value except `status_unavailable` — so a plain `map[reason]` answered EVERY
+ * `Object.prototype` member truthy. No count is written here: `refusal.test.ts` derives the set
+ * from `Object.getOwnPropertyNames(Object.prototype)` and covers all of it, so a number typed in
+ * this sentence could only ever disagree with the runtime. (It did: it read "eight".)
+ * `constructor` rendered the principal and nothing else, `toString` produced
+ * "[object Undefined] Details: …", and `valueOf` / `__proto__` threw a TypeError OUT of the gated
+ * handler, inside someone else's production process, from the one code path whose entire job is to
+ * say no gracefully. Measured against the built module, not reasoned about.
+ *
+ * `Object.hasOwn` is the same fix `web/src/app/(dashboard)/lookalike-watch/eligibility.ts` already
+ * carries for the same reason ("a code of `constructor` would otherwise resolve to a function").
+ */
+function ownLead(map, reason) {
+    return Object.hasOwn(map, reason) ? map[reason] : undefined;
+}
+export function refusalMessage(principal, reason) {
+    if (isUnreachableRefusal(reason)) {
+        // Read through a local, exactly like the decision branch below. `noUncheckedIndexedAccess` is
+        // off in this package, so a reason added to UNREACHABLE_REASONS without a lead would compile
+        // and then throw a TypeError out of a gated handler inside someone else's production process.
+        // `refusal.test.ts` pins the pairing (added after a reviewer measured that it did not — a
+        // third reason with no lead ran green), and this local is the runtime half of the same rule:
+        // a behavioural pin is not a reason to let a gated handler throw in someone else's process.
+        // Consequence worth knowing: this inline sentence is UNREACHABLE today, so it is the one piece
+        // of refusal copy no test reads and no review round judged. On the day it fires it ships
+        // unreviewed.
+        const lead = ownLead(UNREACHABLE_LEADS, reason);
+        return (`${lead
+            ? lead(principal)
+            : `Proof (proof.holdings) could not be reached to confirm ${principal}'s authorization ` +
+                `to run this — a connectivity failure here, not a decision by ${principal}.`} Details: ${REFUSAL_DETAILS_URL}. ` +
+            'Check outbound network access to proof.holdings from wherever this server runs.');
+    }
+    const lead = ownLead(PUBLISHER_DECISION_LEADS, reason);
+    return (`${lead ? lead(principal) : fallbackLead(principal, reason)} ` +
+        `Details: ${REFUSAL_DETAILS_URL}. If this is unexpected, contact ${principal}.`);
+}
+//# sourceMappingURL=refusal.js.map

package/dist/refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../src/refusal.ts"],"names":[],"mappings":"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"}

package/dist/registrar.d.ts

@@ -0,0 +1,77 @@
+import { type ResolvedOptions } from './verdict.js';
+export type ToolRegistrar = (...args: unknown[]) => unknown;
+/**
+ * Records that this package has already run on a server, and WHICH WAY.
+ *
+ * A registry-wide `Symbol.for` so a duplicated copy of this package in one process still sees it.
+ * Both entry points set it and both check it, because the dangerous combination is silent: after
+ * `guardDelegation` runs, nothing is registered and `server.tool` is already the gating wrapper, so
+ * `installProofLayer`'s precondition passes and it registers the showcase THROUGH the gate — and a
+ * revoked delegation then kills `proof_check_this_server`, the exact failure this package's second
+ * entry point exists to prevent. Measured in code review; it manifests only at revocation time.
+ *
+ * The KIND matters because the two states are not the same fact. `gated` means a gate is installed
+ * and a registrar was handed out. `optout` means only the second half: `guardDelegation` with no
+ * token returned the server's RAW registrar and gated nothing. Recording them identically made a
+ * benign repeat of the opt-out crash the publisher's startup with a message asserting a layer that
+ * is not there — introduced by the fix for the real hole, caught in the next review round.
+ */
+export type InstallKind = 'gated' | 'optout';
+export declare const INSTALLED_MARKER: unique symbol;
+export declare function readInstallKind(server: McpServerLike): InstallKind | undefined;
+export declare function markInstalled(server: McpServerLike, kind: InstallKind): void;
+/**
+ * Refuses a second call that cannot cover the registrar a first call already handed out.
+ *
+ * The two states fail for OPPOSITE reasons, which is why one summary cannot serve both. After
+ * `gated`, a second call would install over a working gate. After `optout`, the raw registrar stays
+ * perfectly VALID and simply bypasses whatever is installed next — nothing invalidated it. The
+ * message below is picked from the kind for that reason: claiming an installed layer where only a
+ * raw registrar was handed out sends the reader looking for something that does not exist.
+ */
+export declare function assertNotAlreadyInstalled(server: McpServerLike, entryPoint: string): void;
+/**
+ * The subset of `McpServer` this package touches, expressed structurally so no runtime import of
+ * `@modelcontextprotocol/sdk` is needed (it stays a dev-only dependency for typing tests).
+ * `_registeredTools` is undocumented SDK internal state — the only field that exposes "how many
+ * tools are registered" (mcp/node_modules/@modelcontextprotocol/sdk/dist/cjs/server/mcp.js:18-22).
+ * `registerTool` is optional because older SDK versions may not expose it, but when present it is
+ * a SECOND, independent public entry point that also populates `_registeredTools`
+ * (mcp.js:660,701) — both must be gated, or a publisher who calls it instead of `.tool()` gets a
+ * completely unguarded handler.
+ *
+ * `server` mirrors `McpServer.server` — a public field holding the underlying `Server` instance,
+ * whose private `_instructions` (`server/index.js:53`) is what `install.ts`'s showcase-recognition
+ * write targets. Optional for the same reason as `_registeredTools`: a stand-in in a test, or an
+ * SDK shape this package has never seen, may not carry it at all.
+ */
+export interface McpServerLike {
+    tool: ToolRegistrar;
+    registerTool?: ToolRegistrar;
+    _registeredTools?: Record<string, unknown>;
+    server?: {
+        _instructions?: unknown;
+    };
+}
+/**
+ * The shared precondition both entry points check: the SDK must expose `_registeredTools`, and
+ * nothing may be registered yet. Placed late, this package does nothing — `.bind()` snapshots the
+ * function value — so refusing to run is the only honest answer to "installed too late".
+ */
+export declare function assertInstallableBeforeRegistration(server: McpServerLike, entryPoint: string): void;
+/**
+ * Wraps a registrar (`server.tool` or `server.registerTool` — both take the handler as their
+ * final positional argument) so every call through it is gated on `currentVerdict`.
+ *
+ * The dispatch check is a deliberate ALLOW-LIST (`kind === 'valid'` runs the handler; anything
+ * else, including a shape `currentVerdict`'s return type does not admit but that could reach here
+ * through some future bug, refuses) rather than a deny-list keyed on `'refused'` — a security gate
+ * must default to denying what it does not positively recognize as authorized.
+ *
+ * The handler's own arguments are passed through OPAQUELY: never read, indexed, logged or
+ * serialized. This package runs inside someone else's production process, where those arguments
+ * are that publisher's user data — `src/__tests__/drift/mcp-showcase.test.ts` pins the property
+ * behaviourally rather than trusting this comment.
+ */
+export declare function wrapRegistrar(original: ToolRegistrar, opts: ResolvedOptions): ToolRegistrar;
+//# sourceMappingURL=registrar.d.ts.map

package/dist/registrar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registrar.d.ts","sourceRoot":"","sources":["../src/registrar.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpE,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;AAE5D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE7C,eAAO,MAAM,gBAAgB,eAAiE,CAAC;AAE/F,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,WAAW,GAAG,SAAS,CAgB9E;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAE5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAuBzF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,mCAAmC,CAAC,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAoBnG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,IAAI,EAAE,eAAe,GAAG,aAAa,CAiB3F"}