@reposkein/mcp 0.4.0 → 0.6.0

package/dist/ads/slot.d.ts

@@ -0,0 +1,63 @@
+import { type SponsoredSlot, type SponsoredSource } from "./types.js";
+/** Minimal shape the hook needs from a tool result — structurally compatible
+ *  with `tools/readCypher.ts`'s `ToolResult` without importing it (the hook
+ *  must stay usable around any handler). */
+export interface AdResultLike {
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+    structuredContent?: unknown;
+}
+export interface AdsHookOptions {
+    /** The active repo root for `[ads] enabled`, resolved lazily so a disabled
+     *  integration costs nothing. */
+    resolveRepoPath: () => string | undefined;
+    env?: NodeJS.ProcessEnv;
+    /** Injected in tests. Omitted in production: the real source is built (and
+     *  the `lulu-ads` package first imported) only after the gating chain
+     *  passes. Pass `null` to guarantee no source can ever be built. */
+    source?: SponsoredSource | null;
+    isSupporter?: () => boolean;
+    timeoutMs?: number;
+    /** Test seam: `[ads] enabled` lookup. */
+    readOptIn?: (repoPath: string) => boolean | null;
+    /** Test seams for the local request audit (`.reposkein/local/ads-requests.jsonl`).
+     *  Defaults: the real appender, deferred with `setImmediate`. */
+    audit?: (repoPath: string, record: {
+        ts: string;
+        tool: string;
+    }) => void;
+    schedule?: (fn: () => void) => void;
+}
+export interface AdsHook {
+    /** Wraps a tool handler so its RESPONSE ENVELOPE may carry a sponsored slot.
+     *  Wrap OUTSIDE `withLog` (`withAds(name, withLog(name, handler))`): the
+     *  slot must not exist yet when the session logger captures the result, or
+     *  sponsored bytes would show up in `.reposkein/local/sessions` byte counts.
+     *  Attachment is copy-on-write for the same reason — the object the logger
+     *  holds by reference is never mutated. */
+    withAds<Args, R extends AdResultLike>(tool: string, cb: (args: Args) => Promise<R>): (args: Args) => Promise<R>;
+}
+/** Builds the sponsorship hook for ONE server connection (mirrors
+ *  `createToolLogger`: per-connection state, no module globals).
+ *
+ *  Everything about this is fail-open. A disabled integration, absent
+ *  credentials, a rejecting source, a hanging source, a hostile payload and an
+ *  outright bug all land in the same place: the tool's own result, returned
+ *  unchanged. There is no code path here that can make a tool call fail, and
+ *  none that can slow it by more than `timeoutMs`. */
+export declare function createAdsHook(opts: AdsHookOptions): AdsHook;
+/** Attaches the slot to the response ENVELOPE, copy-on-write.
+ *
+ *  `_meta` under a namespaced key — not `content`, and never a
+ *  `structuredContent` object invented for the purpose. Rationale: `content`
+ *  is the tool's answer and the one surface an agent reads as prose, so
+ *  sponsored data must never appear there in any form (concatenated or
+ *  appended); and materializing a `structuredContent` that only holds an ad
+ *  would let a host that prefers structured output over text render the ad
+ *  INSTEAD of the answer. When a tool already returns structuredContent, the
+ *  slot is mirrored there as a clearly separate `sponsored` key so hosts that
+ *  render structured fields can disclose it.
+ *
+ *  The `sponsored` label travels inside the slot object and the envelope key
+ *  itself is fixed: nothing here can rename, hide, or restyle the disclosure. */
+export declare function attachSponsored<R extends AdResultLike>(result: R, slot: SponsoredSlot): R;

package/dist/ads/slot.js

@@ -0,0 +1,159 @@
+import { AD_ELIGIBLE_TOOLS, SLOT_TIMEOUT_MS, resolveAdsVerdict, } from "./config.js";
+import { luluAdsSource } from "./luluSource.js";
+import { sanitizeSponsored } from "./sanitize.js";
+import { isSupporter as defaultIsSupporter } from "./supporter.js";
+import { readConfigBool } from "../store/teamConfig.js";
+import { appendAdsRequest } from "./auditLog.js";
+import { SPONSORED_META_KEY } from "./types.js";
+/** Builds the sponsorship hook for ONE server connection (mirrors
+ *  `createToolLogger`: per-connection state, no module globals).
+ *
+ *  Everything about this is fail-open. A disabled integration, absent
+ *  credentials, a rejecting source, a hanging source, a hostile payload and an
+ *  outright bug all land in the same place: the tool's own result, returned
+ *  unchanged. There is no code path here that can make a tool call fail, and
+ *  none that can slow it by more than `timeoutMs`. */
+export function createAdsHook(opts) {
+    const env = opts.env ?? process.env;
+    const timeoutMs = opts.timeoutMs ?? SLOT_TIMEOUT_MS;
+    // Bound to THIS hook's env so an injected environment reaches the
+    // entitlement-file lookup too (`REPOSKEIN_SUPPORTER_FILE`), rather than the
+    // supporter check silently reading the real `process.env` while everything
+    // else in the chain reads the injected one.
+    const isSupporter = opts.isSupporter ?? (() => defaultIsSupporter(env));
+    const audit = opts.audit ?? appendAdsRequest;
+    const schedule = opts.schedule ?? setImmediate;
+    // The config.toml opt-in is memoized for the connection's lifetime: one
+    // filesystem read per repo, never one per tool call. The env kill switch and
+    // the credential/supporter checks are re-evaluated on every call (they are
+    // pure reads of already-loaded state), so `REPOSKEIN_ADS=off` takes effect
+    // immediately while a config.toml edit needs a reconnect.
+    const optInMemo = new Map();
+    const readOptIn = (repoPath) => {
+        if (!optInMemo.has(repoPath)) {
+            const read = opts.readOptIn;
+            try {
+                optInMemo.set(repoPath, read ? read(repoPath) : resolveOptInFromDisk(repoPath));
+            }
+            catch {
+                optInMemo.set(repoPath, null);
+            }
+        }
+        return optInMemo.get(repoPath) ?? null;
+    };
+    let source = opts.source;
+    function sourceFor(verdict) {
+        if (source !== undefined)
+            return source;
+        source = luluAdsSource({
+            publisherId: verdict.publisherId,
+            apiKey: verdict.apiKey,
+            baseUrl: verdict.baseUrl,
+        });
+        return source;
+    }
+    /** One bounded slot request, or null. Never throws, never exceeds the
+     *  budget: an `AbortController` is signalled at the deadline and the race
+     *  resolves null regardless of what the source does afterwards, so even a
+     *  source that ignores the signal entirely cannot delay a tool result. */
+    async function requestSlot(src, ctx, clickHosts) {
+        const controller = new AbortController();
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                resolve(null);
+            }, timeoutMs);
+            timer.unref?.();
+        });
+        try {
+            const raw = await Promise.race([
+                src.requestSlot(ctx, { timeoutMs, signal: controller.signal }).catch(() => null),
+                deadline,
+            ]);
+            if (raw === null || raw === undefined)
+                return null;
+            return sanitizeSponsored(raw, { clickHosts });
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async function maybeSlot(tool) {
+        if (!AD_ELIGIBLE_TOOLS.includes(tool))
+            return null;
+        const repoPath = opts.resolveRepoPath();
+        const verdict = resolveAdsVerdict({
+            repoPath,
+            env,
+            isSupporter,
+            readOptIn,
+        });
+        if (!verdict.enabled)
+            return null;
+        const src = sourceFor(verdict);
+        if (!src)
+            return null;
+        // Audit BEFORE the call, deferred off the hot path (the instrumentTool
+        // pattern): the line records that a request left this machine, so it must
+        // be written even if the request then hangs, fails, or is aborted at the
+        // deadline. Never blocks and never throws.
+        if (repoPath) {
+            const ts = new Date().toISOString();
+            schedule(() => audit(repoPath, { ts, tool }));
+        }
+        return requestSlot(src, { tool }, verdict.clickHosts);
+    }
+    function withAds(tool, cb) {
+        return async (args) => {
+            const result = await cb(args);
+            try {
+                // Error results are off-limits: a failure is never a sales surface,
+                // and a caller debugging one should see nothing but the failure.
+                if (!result || typeof result !== "object" || result.isError === true)
+                    return result;
+                const slot = await maybeSlot(tool);
+                if (!slot)
+                    return result;
+                return attachSponsored(result, slot);
+            }
+            catch {
+                // A sponsorship bug must be invisible to the caller.
+                return result;
+            }
+        };
+    }
+    return { withAds };
+}
+/** `[ads] enabled` from `.reposkein/config.toml`. */
+function resolveOptInFromDisk(repoPath) {
+    return readConfigBool(repoPath, "ads", "enabled");
+}
+/** Attaches the slot to the response ENVELOPE, copy-on-write.
+ *
+ *  `_meta` under a namespaced key — not `content`, and never a
+ *  `structuredContent` object invented for the purpose. Rationale: `content`
+ *  is the tool's answer and the one surface an agent reads as prose, so
+ *  sponsored data must never appear there in any form (concatenated or
+ *  appended); and materializing a `structuredContent` that only holds an ad
+ *  would let a host that prefers structured output over text render the ad
+ *  INSTEAD of the answer. When a tool already returns structuredContent, the
+ *  slot is mirrored there as a clearly separate `sponsored` key so hosts that
+ *  render structured fields can disclose it.
+ *
+ *  The `sponsored` label travels inside the slot object and the envelope key
+ *  itself is fixed: nothing here can rename, hide, or restyle the disclosure. */
+export function attachSponsored(result, slot) {
+    const meta = { ...(result._meta ?? {}), [SPONSORED_META_KEY]: slot };
+    const out = { ...result, _meta: meta };
+    const structured = result.structuredContent;
+    if (structured && typeof structured === "object" && !Array.isArray(structured)) {
+        out.structuredContent = { ...structured, sponsored: slot };
+    }
+    return out;
+}
+//# sourceMappingURL=slot.js.map

package/dist/ads/slot.js.map

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

package/dist/ads/supporter.d.ts

@@ -0,0 +1,73 @@
+/** Supporter check — the "you already paid, you see no ads" gate.
+ *
+ *  REP-28 wired a stub of this into `resolveAdsVerdict` so the sponsorship
+ *  path could never ship without it. REP-29 filled it in. The signature is
+ *  unchanged: still synchronous, still consulted before any slot is
+ *  requested, still returning a plain boolean.
+ *
+ *  ## Entirely local
+ *
+ *  Verification is a signature check against a public key compiled into this
+ *  package (`supporterKey.ts`) over a file the user placed at
+ *  `~/.config/reposkein/supporter.jwt`. There is no licence server, no
+ *  activation, no revocation fetch, no telemetry — and the import graph
+ *  reachable from this module contains nothing that can open a socket, which
+ *  a test asserts statically rather than trusting this comment. Being a
+ *  supporter is therefore something you can be on a plane, behind a
+ *  corporate proxy, or on a machine that has never resolved DNS.
+ *
+ *  ## Staying off the hot path
+ *
+ *  This runs inside a tool call's gating chain, so the expensive parts are
+ *  cached for the process:
+ *
+ *  - The signature verification result is cached against the entitlement
+ *    file's (mtime, size). Editing or replacing the file invalidates it.
+ *  - The `statSync` that detects such an edit is THROTTLED: at most one every
+ *    `RECHECK_INTERVAL_MS`. Between probes the cached claims are reused, so a
+ *    steady stream of tool calls costs one integer comparison each, not one
+ *    syscall each.
+ *  - Expiry is re-evaluated on every call regardless, since it depends on the
+ *    clock rather than on the file. A token that lapses mid-session stops
+ *    entitling immediately, without waiting for a stat.
+ *
+ *  The bound this buys: a token added, renewed, or deleted mid-session takes
+ *  effect within `RECHECK_INTERVAL_MS` (five seconds) rather than instantly.
+ *  For a gate whose only job is to suppress an ad, that is the right trade. */
+import { type SupporterClaims, type SupporterRejection, type SupporterVerdict } from "./supporterToken.js";
+/** How often the entitlement file may be re-probed on the hot path. */
+export declare const RECHECK_INTERVAL_MS = 5000;
+/** What `support --status` (and `doctor`, later) needs to say something
+ *  useful. `state: "none"` means no entitlement file at all — the state of
+ *  every install that has not run `reposkein-mcp support`. */
+export type SupporterStatus = {
+    state: "none";
+    path: string;
+} | {
+    state: "valid" | "grace" | "expired";
+    path: string;
+    claims: SupporterClaims;
+    mode: number | null;
+} | {
+    state: "invalid";
+    path: string;
+    reason: SupporterRejection;
+    mode: number | null;
+};
+/** Drops the memoized verification. Tests call it; nothing in production
+ *  does — the mtime/size probe is what keeps the cache honest at runtime. */
+export declare function resetSupporterCache(): void;
+/** Reads + verifies with no caching and no clock-independent shortcuts. The
+ *  CLI path: correctness and detail matter, a syscall does not. */
+export declare function readSupporterStatus(env?: NodeJS.ProcessEnv, now?: number): SupporterStatus;
+/** The cached verdict used by the gating chain. Exported for tests and for
+ *  anything that wants the reason as well as the boolean. */
+export declare function supporterVerdict(env?: NodeJS.ProcessEnv, now?: number): SupporterVerdict;
+/** The gate itself. True only for a signed, untampered, correctly-tiered
+ *  token that is inside its validity window or its grace period.
+ *
+ *  Fail-CLOSED with respect to entitlement (any doubt → "not a supporter",
+ *  which merely means the normal, already-opt-in-gated ad path applies) and
+ *  fail-OPEN with respect to errors: nothing here can throw into a tool
+ *  call. */
+export declare function isSupporter(env?: NodeJS.ProcessEnv, now?: number): boolean;

package/dist/ads/supporter.js

@@ -0,0 +1,119 @@
+/** Supporter check — the "you already paid, you see no ads" gate.
+ *
+ *  REP-28 wired a stub of this into `resolveAdsVerdict` so the sponsorship
+ *  path could never ship without it. REP-29 filled it in. The signature is
+ *  unchanged: still synchronous, still consulted before any slot is
+ *  requested, still returning a plain boolean.
+ *
+ *  ## Entirely local
+ *
+ *  Verification is a signature check against a public key compiled into this
+ *  package (`supporterKey.ts`) over a file the user placed at
+ *  `~/.config/reposkein/supporter.jwt`. There is no licence server, no
+ *  activation, no revocation fetch, no telemetry — and the import graph
+ *  reachable from this module contains nothing that can open a socket, which
+ *  a test asserts statically rather than trusting this comment. Being a
+ *  supporter is therefore something you can be on a plane, behind a
+ *  corporate proxy, or on a machine that has never resolved DNS.
+ *
+ *  ## Staying off the hot path
+ *
+ *  This runs inside a tool call's gating chain, so the expensive parts are
+ *  cached for the process:
+ *
+ *  - The signature verification result is cached against the entitlement
+ *    file's (mtime, size). Editing or replacing the file invalidates it.
+ *  - The `statSync` that detects such an edit is THROTTLED: at most one every
+ *    `RECHECK_INTERVAL_MS`. Between probes the cached claims are reused, so a
+ *    steady stream of tool calls costs one integer comparison each, not one
+ *    syscall each.
+ *  - Expiry is re-evaluated on every call regardless, since it depends on the
+ *    clock rather than on the file. A token that lapses mid-session stops
+ *    entitling immediately, without waiting for a stat.
+ *
+ *  The bound this buys: a token added, renewed, or deleted mid-session takes
+ *  effect within `RECHECK_INTERVAL_MS` (five seconds) rather than instantly.
+ *  For a gate whose only job is to suppress an ad, that is the right trade. */
+import { classifyClaims, isEntitled, verifySupporterTokenClaims, } from "./supporterToken.js";
+import { readSupporterTokenFile, statSupporterTokenFile, supporterTokenPath } from "./supporterStore.js";
+/** How often the entitlement file may be re-probed on the hot path. */
+export const RECHECK_INTERVAL_MS = 5_000;
+/** Module-level and deliberately so: the entitlement is a property of the
+ *  machine, not of a server connection, and re-verifying an Ed25519 signature
+ *  per connection would be pure waste. Reset in tests via
+ *  `resetSupporterCache()`. */
+let cache = null;
+/** Drops the memoized verification. Tests call it; nothing in production
+ *  does — the mtime/size probe is what keeps the cache honest at runtime. */
+export function resetSupporterCache() {
+    cache = null;
+}
+/** Reads + verifies with no caching and no clock-independent shortcuts. The
+ *  CLI path: correctness and detail matter, a syscall does not. */
+export function readSupporterStatus(env = process.env, now = Date.now()) {
+    const path = supporterTokenPath(env);
+    const st = statSupporterTokenFile(env);
+    if (!st)
+        return { state: "none", path };
+    const text = readSupporterTokenFile(env);
+    if (text === null)
+        return { state: "invalid", path, reason: "empty", mode: st.mode };
+    const parsed = verifySupporterTokenClaims(text);
+    if (!parsed.ok)
+        return { state: "invalid", path, reason: parsed.reason, mode: st.mode };
+    const verdict = classifyClaims(parsed.claims, now);
+    if (verdict.state === "invalid")
+        return { state: "invalid", path, reason: verdict.reason, mode: st.mode };
+    return { state: verdict.state, path, claims: verdict.claims, mode: st.mode };
+}
+/** The cached verdict used by the gating chain. Exported for tests and for
+ *  anything that wants the reason as well as the boolean. */
+export function supporterVerdict(env = process.env, now = Date.now()) {
+    const path = supporterTokenPath(env);
+    // Reuse the cached claims without touching the filesystem while the
+    // throttle window is open and the path has not changed under us.
+    if (cache && cache.path === path && now - cache.probedAt < RECHECK_INTERVAL_MS) {
+        return fromCache(cache, now);
+    }
+    const st = statSupporterTokenFile(env);
+    if (!st) {
+        cache = { mtimeMs: -1, size: -1, path, claims: null, reason: "empty", probedAt: now };
+        return { state: "invalid", reason: "empty" };
+    }
+    if (cache && cache.path === path && cache.mtimeMs === st.mtimeMs && cache.size === st.size) {
+        cache.probedAt = now;
+        return fromCache(cache, now);
+    }
+    const text = readSupporterTokenFile(env);
+    const parsed = text === null ? { ok: false, reason: "empty" } : verifySupporterTokenClaims(text);
+    cache = {
+        mtimeMs: st.mtimeMs,
+        size: st.size,
+        path,
+        claims: parsed.ok ? parsed.claims : null,
+        reason: parsed.ok ? null : parsed.reason,
+        probedAt: now,
+    };
+    return fromCache(cache, now);
+}
+function fromCache(entry, now) {
+    if (!entry.claims)
+        return { state: "invalid", reason: entry.reason ?? "empty" };
+    return classifyClaims(entry.claims, now);
+}
+/** The gate itself. True only for a signed, untampered, correctly-tiered
+ *  token that is inside its validity window or its grace period.
+ *
+ *  Fail-CLOSED with respect to entitlement (any doubt → "not a supporter",
+ *  which merely means the normal, already-opt-in-gated ad path applies) and
+ *  fail-OPEN with respect to errors: nothing here can throw into a tool
+ *  call. */
+export function isSupporter(env = process.env, now = Date.now()) {
+    try {
+        return isEntitled(supporterVerdict(env, now));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=supporter.js.map

package/dist/ads/supporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supporter.js","sourceRoot":"","sources":["../../src/ads/supporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+EAmC+E;AAE/E,OAAO,EACL,cAAc,EACd,UAAU,EACV,0BAA0B,GAI3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzG,uEAAuE;AACvE,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAsBzC;;;+BAG+B;AAC/B,IAAI,KAAK,GAAsB,IAAI,CAAC;AAEpC;6EAC6E;AAC7E,MAAM,UAAU,mBAAmB;IACjC,KAAK,GAAG,IAAI,CAAC;AACf,CAAC;AAED;mEACmE;AACnE,MAAM,UAAU,mBAAmB,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IAChG,MAAM,IAAI,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,EAAE,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACxC,MAAM,IAAI,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IACrF,MAAM,MAAM,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IACxF,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IAC1G,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;AAC/E,CAAC;AAED;6DAC6D;AAC7D,MAAM,UAAU,gBAAgB,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IAC7F,MAAM,IAAI,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAErC,oEAAoE;IACpE,iEAAiE;IACjE,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,GAAG,GAAG,KAAK,CAAC,QAAQ,GAAG,mBAAmB,EAAE,CAAC;QAC/E,OAAO,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,EAAE,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,KAAK,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;QACtF,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC/C,CAAC;IAED,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,KAAK,EAAE,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC;QAC3F,KAAK,CAAC,QAAQ,GAAG,GAAG,CAAC;QACrB,OAAO,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,IAAI,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC,CAAC,CAAE,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAY,CAAC,CAAC,CAAC,0BAA0B,CAAC,IAAI,CAAC,CAAC;IAC5G,KAAK,GAAG;QACN,OAAO,EAAE,EAAE,CAAC,OAAO;QACnB,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,IAAI;QACJ,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI;QACxC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM;QACxC,QAAQ,EAAE,GAAG;KACd,CAAC;IACF,OAAO,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,SAAS,CAAC,KAAiB,EAAE,GAAW;IAC/C,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,OAAO,EAAE,CAAC;IAChF,OAAO,cAAc,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;YAMY;AACZ,MAAM,UAAU,WAAW,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IACxF,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/ads/supporterKey.d.ts

@@ -0,0 +1,45 @@
+/** The public half of the supporter-entitlement signing key (REP-29).
+ *
+ *  Baked into the published package on purpose. Verification of a supporter
+ *  token is a purely local operation — signature, tier, expiry — and this
+ *  constant is the whole trust root for it. Nothing about entitlement needs a
+ *  server, so nothing about entitlement contacts one: no licence check, no
+ *  activation call, no heartbeat, no way for us to learn that you ran the
+ *  tool. That property is only achievable if the verifier ships with the key.
+ *
+ *  ## Provenance
+ *
+ *  - Algorithm: Ed25519 (RFC 8032), SPKI/PEM encoding.
+ *  - Generated 2026-08-21 with `node:crypto` `generateKeyPairSync("ed25519")`
+ *    on the maintainer's machine, during the REP-29 implementation.
+ *  - The PRIVATE half was never committed and never left that machine except
+ *    into a secret store. Its only consumer is the Ko-fi fulfilment worker
+ *    (`workers/kofi-fulfillment/`), which holds it as the Cloudflare secret
+ *    `SUPPORTER_SIGNING_KEY`. No developer workflow, no test, and no part of
+ *    the published package needs it: tests that must sign generate their own
+ *    throwaway keypair.
+ *
+ *  ## What this key can and cannot do for us
+ *
+ *  Publishing the public half means anyone can *verify* a token; only the
+ *  holder of the private half can *mint* one. It also means a supporter can
+ *  read their own token's payload — which is deliberate, and why the payload
+ *  contains nothing but an opaque subject hash, a tier name, and two
+ *  timestamps (see `supporterToken.ts`). There is nothing in it to hide,
+ *  because there is nothing in it about you.
+ *
+ *  ## Rotation
+ *
+ *  Tokens carry a `kid`. To rotate: add the new public key here alongside the
+ *  old one, keep verifying both until every issued token has expired, then
+ *  drop the old entry. Removing a key invalidates every token signed with it,
+ *  so a rotation that is not additive-then-subtractive will strand paying
+ *  supporters. The verifier already selects by `kid`, so the only change a
+ *  rotation needs is to this map. */
+/** Key id → SPKI PEM. Every entry is a key tokens may legitimately be signed
+ *  with; a token naming a `kid` absent from this map is rejected before any
+ *  signature check happens. */
+export declare const SUPPORTER_PUBLIC_KEYS: Readonly<Record<string, string>>;
+/** The key the minter should be signing with today. Only the fulfilment
+ *  worker cares; the verifier accepts anything in `SUPPORTER_PUBLIC_KEYS`. */
+export declare const CURRENT_SUPPORTER_KID = "skein-2026-08";

package/dist/ads/supporterKey.js

@@ -0,0 +1,51 @@
+/** The public half of the supporter-entitlement signing key (REP-29).
+ *
+ *  Baked into the published package on purpose. Verification of a supporter
+ *  token is a purely local operation — signature, tier, expiry — and this
+ *  constant is the whole trust root for it. Nothing about entitlement needs a
+ *  server, so nothing about entitlement contacts one: no licence check, no
+ *  activation call, no heartbeat, no way for us to learn that you ran the
+ *  tool. That property is only achievable if the verifier ships with the key.
+ *
+ *  ## Provenance
+ *
+ *  - Algorithm: Ed25519 (RFC 8032), SPKI/PEM encoding.
+ *  - Generated 2026-08-21 with `node:crypto` `generateKeyPairSync("ed25519")`
+ *    on the maintainer's machine, during the REP-29 implementation.
+ *  - The PRIVATE half was never committed and never left that machine except
+ *    into a secret store. Its only consumer is the Ko-fi fulfilment worker
+ *    (`workers/kofi-fulfillment/`), which holds it as the Cloudflare secret
+ *    `SUPPORTER_SIGNING_KEY`. No developer workflow, no test, and no part of
+ *    the published package needs it: tests that must sign generate their own
+ *    throwaway keypair.
+ *
+ *  ## What this key can and cannot do for us
+ *
+ *  Publishing the public half means anyone can *verify* a token; only the
+ *  holder of the private half can *mint* one. It also means a supporter can
+ *  read their own token's payload — which is deliberate, and why the payload
+ *  contains nothing but an opaque subject hash, a tier name, and two
+ *  timestamps (see `supporterToken.ts`). There is nothing in it to hide,
+ *  because there is nothing in it about you.
+ *
+ *  ## Rotation
+ *
+ *  Tokens carry a `kid`. To rotate: add the new public key here alongside the
+ *  old one, keep verifying both until every issued token has expired, then
+ *  drop the old entry. Removing a key invalidates every token signed with it,
+ *  so a rotation that is not additive-then-subtractive will strand paying
+ *  supporters. The verifier already selects by `kid`, so the only change a
+ *  rotation needs is to this map. */
+/** Key id → SPKI PEM. Every entry is a key tokens may legitimately be signed
+ *  with; a token naming a `kid` absent from this map is rejected before any
+ *  signature check happens. */
+export const SUPPORTER_PUBLIC_KEYS = Object.freeze({
+    "skein-2026-08": `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAV7vHvsTIlioxm9pWOJ83/sEZW/ps8ymd2I+LZeucnOk=
+-----END PUBLIC KEY-----
+`,
+});
+/** The key the minter should be signing with today. Only the fulfilment
+ *  worker cares; the verifier accepts anything in `SUPPORTER_PUBLIC_KEYS`. */
+export const CURRENT_SUPPORTER_KID = "skein-2026-08";
+//# sourceMappingURL=supporterKey.js.map

package/dist/ads/supporterKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supporterKey.js","sourceRoot":"","sources":["../../src/ads/supporterKey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCAqCqC;AAErC;;+BAE+B;AAC/B,MAAM,CAAC,MAAM,qBAAqB,GAAqC,MAAM,CAAC,MAAM,CAAC;IACnF,eAAe,EAAE;;;CAGlB;CACA,CAAC,CAAC;AAEH;8EAC8E;AAC9E,MAAM,CAAC,MAAM,qBAAqB,GAAG,eAAe,CAAC"}

package/dist/ads/supporterStore.d.ts

@@ -0,0 +1,61 @@
+/** Where a supporter token lives on disk, and the only code that puts it
+ *  there.
+ *
+ *  ## User-level, never repo-level
+ *
+ *  Entitlement belongs to a PERSON, not to a checkout. Storing it under
+ *  `.reposkein/` would be wrong three times over: it would ride into git (or
+ *  need yet another ignore rule to stop it), it would be shared with everyone
+ *  who clones the repo — handing them a token they did not pay for — and it
+ *  would have to be re-supplied in every working copy by the one person who
+ *  did. So it lives under the user's config directory and nothing in this
+ *  package ever writes an entitlement byte inside a repository. There is a
+ *  test that asserts exactly that by byte-comparing a repo tree across a
+ *  `support` invocation.
+ *
+ *  ## Permissions
+ *
+ *  Directory 0700, file 0600, and the file mode is re-applied with an
+ *  explicit `chmodSync` after every write: `writeFileSync`'s `mode` option is
+ *  honoured only when the file is CREATED, so overwriting an existing
+ *  world-readable token would otherwise silently leave it world-readable.
+ *  The token is not a password — the worst a thief gets is no ads — but a
+ *  paid entitlement is still the holder's to keep, and 0600 costs nothing.
+ *
+ *  On Windows these modes are approximated by the runtime; `--status` reports
+ *  the mode it actually observes rather than asserting a POSIX guarantee the
+ *  platform does not offer. */
+/** Overrides the entitlement file location. Exists for tests and for anyone
+ *  running with an unusual HOME; it is NOT a bypass — the file it points at
+ *  still has to contain a validly signed token, so redirecting it cannot
+ *  manufacture entitlement. */
+export declare const SUPPORTER_FILE_ENV = "REPOSKEIN_SUPPORTER_FILE";
+/** Resolves the entitlement file path, in order:
+ *
+ *   1. `REPOSKEIN_SUPPORTER_FILE`, if absolute.
+ *   2. `$XDG_CONFIG_HOME/reposkein/supporter.jwt`, if absolute.
+ *   3. `~/.config/reposkein/supporter.jwt` — the documented location. */
+export declare function supporterTokenPath(env?: NodeJS.ProcessEnv): string;
+export interface SupporterFileStat {
+    mtimeMs: number;
+    size: number;
+    /** POSIX permission bits (`mode & 0o777`). */
+    mode: number;
+}
+/** Cheap existence + identity probe. Returns null for "no file" and for any
+ *  error reading it — an unreadable entitlement file is indistinguishable
+ *  from an absent one as far as entitlement goes, and this runs on a tool
+ *  call's hot path, so it must never throw. */
+export declare function statSupporterTokenFile(env?: NodeJS.ProcessEnv): SupporterFileStat | null;
+/** Reads the token text, or null if there is nothing readable there. Never
+ *  throws. Size is bounded by the caller's own token-length limit; a file
+ *  larger than that fails verification rather than being read into memory
+ *  blindly, so the read is capped here too. */
+export declare function readSupporterTokenFile(env?: NodeJS.ProcessEnv, maxBytes?: number): string | null;
+/** Writes the token, creating `~/.config/reposkein/` as 0700 if needed, and
+ *  returns the path written. Throws on failure — this one is called from the
+ *  CLI, where a failure must be reported, not swallowed. */
+export declare function writeSupporterTokenFile(token: string, env?: NodeJS.ProcessEnv): string;
+/** Deletes the entitlement file. Returns true if a file was removed, false if
+ *  there was nothing to remove. */
+export declare function removeSupporterTokenFile(env?: NodeJS.ProcessEnv): boolean;