@agenthippo-ai/agenthippo 0.2.3-dataplane → 1.110.11

package/out/pack/lease.js

@@ -0,0 +1,682 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_LEASE_ENVELOPE_TTL_SECONDS = exports.LEASE_JWS_TYP = exports.LeaseDeniedError = exports.LEASE_MAX_STALENESS_ENV = exports.DEFAULT_LEASE_MAX_STALENESS_SECONDS = exports.MIN_LEASE_POLL_SECONDS = exports.DEFAULT_LEASE_POLL_SECONDS = void 0;
+exports.resolveLeasePollSeconds = resolveLeasePollSeconds;
+exports.leaseCacheSecondsFor = leaseCacheSecondsFor;
+exports.effectiveKillLatencySeconds = effectiveKillLatencySeconds;
+exports.leaseMaxStalenessFromEnv = leaseMaxStalenessFromEnv;
+exports.resolveAllowServiceTurns = resolveAllowServiceTurns;
+exports.describeServiceTurnGate = describeServiceTurnGate;
+exports.denyVerdict = denyVerdict;
+exports.resolveFollowedUsers = resolveFollowedUsers;
+exports.leaseIsDead = leaseIsDead;
+exports.policyVersion = policyVersion;
+exports.assertAdmitted = assertAdmitted;
+exports.signLease = signLease;
+exports.verifySignedLease = verifySignedLease;
+exports.requireSignedLease = requireSignedLease;
+exports.createLeaseSource = createLeaseSource;
+/**
+ * Lease + pinned version — the kill switch and rollback (PLAN/serve-v4-clean.md §5).
+ *
+ * Deliberately ONE mechanism for two jobs: "may this artifact run here, now?" is the same
+ * question whether it is asked commercially (entitlement) or operationally (emergency stop).
+ * It is checked at **sandbox creation**, which is why kill and rollback need no new subsystem:
+ *
+ *   kill      — revoke the lease ⇒ every instance refuses NEW sandboxes immediately;
+ *               sandboxes already running are bounded by their TTL (eventual kill, no fleet loop),
+ *               and can be ended now with `SandboxDriver.destroy` on the instance that owns them.
+ *   rollback  — pin `version` ⇒ new sandboxes run the pinned pack; running sandboxes drain by TTL.
+ *               No hot-swap machinery: version convergence IS sandbox lifecycle.
+ *
+ * The lease is *fail-closed on expiry* but *fail-open on transport*: an unreachable control
+ * plane must not take a customer's fleet down, while an expired lease must not keep running.
+ * That asymmetry is deliberate and is the kind of thing that silently flips if unstated.
+ */
+const crypto_1 = require("crypto");
+const warrant_1 = require("../authority/warrant");
+const lease_schema_1 = require("./lease-schema");
+const signature_1 = require("./signature");
+/**
+ * The single source of truth for the lease poll interval.
+ *
+ * Kill latency is `poll + cache`, and those two numbers used to be written down in five places
+ * with two different defaults: the cache defaulted to 60s while every poll defaulted to 30s, so a
+ * fleet whose banner printed "lease poll 30s" actually took up to 90s to honour a kill switch —
+ * and the comment sitting next to the cache line warned about exactly that drift. Everything now
+ * derives from here.
+ */
+exports.DEFAULT_LEASE_POLL_SECONDS = 30;
+/** Below this, polling costs more than it buys. */
+exports.MIN_LEASE_POLL_SECONDS = 5;
+function resolveLeasePollSeconds(requested) {
+    const n = typeof requested === 'number' && Number.isFinite(requested) ? requested : exports.DEFAULT_LEASE_POLL_SECONDS;
+    return Math.max(exports.MIN_LEASE_POLL_SECONDS, Math.floor(n));
+}
+/**
+ * How long a fetched lease may be reused, derived from the poll interval.
+ *
+ * Equal to the poll: serve runs three independent timers on the poll cadence (policy provenance,
+ * pack convergence, the governor) and they must share one fetch rather than tripling load on the
+ * control plane. Because a cached copy can be up to `cache` seconds old when a poll reads it, the
+ * WORST-CASE latency from an operator hitting stop to this instance refusing a turn is
+ * `poll + cache`. That number is printed at boot rather than the poll interval alone —
+ * `effectiveKillLatencySeconds` exists so the banner cannot drift from the behaviour again.
+ *
+ * An operator who needs it faster does not lower the poll: `governor.refresh()` (wired to the
+ * admin endpoint / control-plane webhook) re-reads immediately.
+ */
+function leaseCacheSecondsFor(pollSeconds) {
+    return resolveLeasePollSeconds(pollSeconds);
+}
+/** Worst-case seconds between a control-plane change and this instance enforcing it. */
+function effectiveKillLatencySeconds(pollSeconds) {
+    const poll = resolveLeasePollSeconds(pollSeconds);
+    return poll + leaseCacheSecondsFor(poll);
+}
+/**
+ * Ceiling on how long a lease may go unrefreshed before this instance refuses turns.
+ *
+ * The kill switch failed OPEN under network denial with no ceiling at all: `createLeaseSource`
+ * keeps the last lease on any transport error, bounded only by that lease's own `expiresAt` —
+ * which a control plane typically sets days or weeks out. An attacker who can drop packets to the
+ * control plane (or a customer who firewalls it) therefore keeps a revoked fleet running until the
+ * entitlement expires, and "revoke the lease" stops meaning "stop the fleet".
+ *
+ * The default is deliberately generous. Too low and a real control-plane outage becomes a
+ * customer-visible outage — the fail-open-on-transport property exists for good reasons and this
+ * must not quietly delete it. 24 hours is far longer than any plausible planned outage and far
+ * shorter than a typical lease lifetime, so it converts "indefinite" into "bounded" without
+ * bricking a deployment that has ever successfully polled. Set 0 to disable the ceiling entirely
+ * (explicitly accepting the unbounded behaviour); set it lower for a tighter guarantee.
+ */
+exports.DEFAULT_LEASE_MAX_STALENESS_SECONDS = 24 * 60 * 60;
+exports.LEASE_MAX_STALENESS_ENV = 'AGENTHIPPO_LEASE_MAX_STALENESS_SECONDS';
+function leaseMaxStalenessFromEnv(env = process.env) {
+    const raw = env[exports.LEASE_MAX_STALENESS_ENV]?.trim();
+    if (raw === undefined || raw === '') {
+        return exports.DEFAULT_LEASE_MAX_STALENESS_SECONDS;
+    }
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0) {
+        return exports.DEFAULT_LEASE_MAX_STALENESS_SECONDS;
+    }
+    return Math.floor(n);
+}
+/**
+ * May this deployment run turns with no human behind them (PLAN/agent-identity.md §5.6)?
+ *
+ * **Polarity note, because it is the opposite of every other flag here.** `requireSignedPack` and
+ * friends are TIGHTEN-ONLY: absent means "nobody asked for the restriction", so absent is
+ * permissive and that is safe. This flag GRANTS a standing unattended identity, so the same
+ * treatment would be exactly backwards — a control plane that has not been taught the field would
+ * silently authorise unsupervised runs across the fleet. Absent therefore means DENY wherever a
+ * control plane exists to have said otherwise.
+ *
+ * Unmanaged deployments (no lease URL configured at all) keep the existing local-first philosophy:
+ * there is no control plane to ask, so the operator's env is the whole answer. serve says so at
+ * boot rather than leaving it implicit.
+ */
+function resolveAllowServiceTurns(opts) {
+    if (!opts.managed) {
+        return { allowed: true, gate: 'unmanaged_no_lease' };
+    }
+    if (opts.lease === true) {
+        return { allowed: true, gate: 'lease_allows' };
+    }
+    // `undefined` and `false` are deliberately NOT distinguished in the outcome, only in the
+    // reason: both deny, so a control plane too old to emit the field is exactly as safe as one
+    // that emitted `false`.
+    return { allowed: false, gate: opts.lease === false ? 'lease_denies' : 'lease_absent_field' };
+}
+/** Operator-facing explanation for a `service_turn_denied` audit row and the boot banner. */
+function describeServiceTurnGate(gate) {
+    switch (gate) {
+        case 'lease_allows':
+            return 'permitted by the control plane (lease.allowServiceTurns)';
+        case 'unmanaged_no_lease':
+            return 'permitted: no control plane configured, so AGENTHIPPO_SERVICE_USER is the only gate';
+        case 'lease_denies':
+            return 'refused: the control plane set lease.allowServiceTurns=false';
+        case 'lease_absent_field':
+            return 'refused: this is a managed deployment and the lease does not set allowServiceTurns '
+                + '(absent means deny — enable it in the console)';
+    }
+}
+/**
+ * Does any live rule name this session?
+ *
+ * Session matching accepts BOTH the full session key and the bare `session_id` the caller sent,
+ * because serve namespaces keys by verified user (`u<hash>--<id>`) and an operator reading a
+ * support ticket has the bare id, not the hash. Accepting only the full key would make the
+ * console's most obvious input silently match nothing.
+ *
+ * User matching prefers the RESOLVED user id when the caller knows it, and falls back to the
+ * `u<hash>--` key prefix otherwise. The prefix alone was not enough: a gateway sender with no
+ * explicit session id gets the key `gateway-<userId>`, which has no `u<hash>--` prefix, so
+ * "stop this user" matched nothing for every Telegram/Slack conversation while the console
+ * reported the rule applied — a stop order that silently covers only some of a user's sessions is
+ * worse than one that fails loudly.
+ */
+function denyVerdict(lease, req, nowSeconds) {
+    if (!lease?.deny?.length) {
+        return { denied: false };
+    }
+    const now = nowSeconds ?? Math.floor(Date.now() / 1000);
+    const sep = req.sessionKey.indexOf('--');
+    const bareSession = sep >= 0 ? req.sessionKey.slice(sep + 2) : req.sessionKey;
+    // `kill` outranks `drain` when both match, so a narrower emergency order is never softened
+    // by a broader routine one.
+    let verdict = { denied: false };
+    for (const rule of lease.deny) {
+        if (rule.until !== undefined && rule.until <= now) {
+            continue;
+        }
+        let hit = false;
+        if (rule.scope === 'pack') {
+            hit = rule.match === req.pack;
+        }
+        else if (rule.scope === 'session') {
+            hit = rule.match === req.sessionKey || rule.match === bareSession;
+            // Identity binding (mitigation 2 above): a rule naming a user matches only when the
+            // verified identity agrees, so the same session id presented by another account misses.
+            // When the caller resolved NO identity we cannot contradict the rule, so the id-only
+            // match stands — refusing there would let an unauthenticated shape silently ignore a
+            // stop order.
+            if (hit && rule.user !== undefined && req.userId !== undefined && rule.user !== req.userId) {
+                hit = false;
+            }
+            // Rotation escape (mitigation 3): the same user under a different session id.
+            if (!hit && rule.followUser !== false && req.userId !== undefined && deniedByFollowedUser(rule, req.userId, req.followedUsers)) {
+                hit = true;
+            }
+        }
+        else if (rule.scope === 'user') {
+            // Exact identity when we have it; the namespaced-key prefix as the fallback for call
+            // sites that only hold a session key (the lease watcher sweeping live sandboxes).
+            hit = (req.userId !== undefined && rule.match === req.userId)
+                || (req.userHash !== undefined && req.sessionKey.startsWith(`u${req.userHash(rule.match)}--`));
+        }
+        if (!hit) {
+            continue;
+        }
+        const reason = `${rule.mode === 'kill' ? 'stopped' : 'draining'} by the control plane${rule.reason ? `: ${rule.reason}` : ''}`;
+        if (rule.mode === 'kill') {
+            return { denied: true, mode: 'kill', reason };
+        }
+        if (!verdict.denied) {
+            verdict = { denied: true, mode: 'drain', reason };
+        }
+    }
+    return verdict;
+}
+const followKey = (rule) => `${rule.scope}:${rule.match}`;
+function deniedByFollowedUser(rule, userId, followed) {
+    return followed?.get(followKey(rule))?.has(userId) ?? false;
+}
+/**
+ * Which verified users a session-scoped rule reaches, given what we have learned about sessions.
+ *
+ * `sessionUsers` is the governor's sessionKey → verified user map, populated on the turn path.
+ * A session rule naming `s` therefore also covers every OTHER session belonging to whoever was
+ * last seen using `s` — which is what makes "stop this session" survive the caller simply sending
+ * a new `session_id`. Rules that set `followUser: false`, and rules for deployments where no
+ * identity was ever resolved, produce no entries and behave exactly as before.
+ */
+function resolveFollowedUsers(lease, sessionUsers, nowSeconds) {
+    const out = new Map();
+    if (!lease?.deny?.length) {
+        return out;
+    }
+    const now = nowSeconds ?? Math.floor(Date.now() / 1000);
+    for (const rule of lease.deny) {
+        if (rule.scope !== 'session' || rule.followUser === false) {
+            continue;
+        }
+        if (rule.until !== undefined && rule.until <= now) {
+            continue;
+        }
+        const users = new Set();
+        for (const [sessionKey, userId] of sessionUsers) {
+            const sep = sessionKey.indexOf('--');
+            const bare = sep >= 0 ? sessionKey.slice(sep + 2) : sessionKey;
+            if (rule.match !== sessionKey && rule.match !== bare) {
+                continue;
+            }
+            // An explicitly identity-bound rule must not widen itself to a different account.
+            if (rule.user !== undefined && rule.user !== userId) {
+                continue;
+            }
+            users.add(userId);
+        }
+        if (users.size > 0) {
+            out.set(followKey(rule), users);
+        }
+    }
+    return out;
+}
+/**
+ * True when the lease says "stop now" — revoked, disabled, or expired.
+ *
+ * `assertAdmitted` refuses NEW sandboxes; this is what a watcher uses to also end the ones already
+ * running. Without it an emergency stop takes up to a full sandbox TTL to take effect, which is not
+ * what an operator hitting a kill switch means by "stop".
+ */
+function leaseIsDead(lease, nowSeconds) {
+    // No lease ⇒ unmanaged deployment; nothing to kill. Same rule as admission.
+    if (!lease) {
+        return { dead: false };
+    }
+    const now = nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (!lease.enabled) {
+        return { dead: true, reason: `kill switch active${lease.reason ? `: ${lease.reason}` : ''}` };
+    }
+    if (lease.expiresAt <= now) {
+        return { dead: true, reason: `lease expired at ${new Date(lease.expiresAt * 1000).toISOString()}` };
+    }
+    return { dead: false };
+}
+/**
+ * Version of the policy in force — sha256 over the canonicalised lease (sorted keys,
+ * `expiresAt` excluded: it changes every poll and is not policy).
+ *
+ * This is what makes "was the cap enforced?" answerable after anyone edits a cap
+ * (PLAN/compliance.md §3.1, R-3 policy provenance): a turn stamped with this value can be tied
+ * to the exact rules that governed it, not to whatever the lease says at audit time.
+ */
+function policyVersion(lease) {
+    if (!lease) {
+        return undefined;
+    }
+    const { expiresAt: _ignored, ...policy } = lease;
+    const canonical = (v) => {
+        if (Array.isArray(v)) {
+            return v.map(canonical);
+        }
+        if (v && typeof v === 'object') {
+            return Object.fromEntries(Object.keys(v).sort()
+                .map((k) => [k, canonical(v[k])]));
+        }
+        return v;
+    };
+    return (0, crypto_1.createHash)('sha256').update(JSON.stringify(canonical(policy))).digest('hex');
+}
+class LeaseDeniedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LeaseDeniedError';
+    }
+}
+exports.LeaseDeniedError = LeaseDeniedError;
+/**
+ * The admission decision. Throws `LeaseDeniedError` — the caller (`createSandboxRunner.admit`)
+ * lets it propagate so no sandbox is ever created for refused work.
+ */
+function assertAdmitted(lease, req) {
+    // No lease configured at all ⇒ unlicensed/unmanaged deployment: allow. Self-hosted dev and
+    // the free tier must keep working without a control plane. Enforcement begins once an
+    // operator configures one.
+    if (!lease) {
+        return;
+    }
+    const now = req.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (!lease.enabled) {
+        throw new LeaseDeniedError(`kill switch active for pack ${req.pack}${lease.reason ? `: ${lease.reason}` : ''}`);
+    }
+    if (lease.pack !== req.pack) {
+        throw new LeaseDeniedError(`lease is for pack ${lease.pack}, not ${req.pack}`);
+    }
+    if (lease.expiresAt <= now) {
+        throw new LeaseDeniedError(`lease for ${req.pack} expired at ${new Date(lease.expiresAt * 1000).toISOString()}`);
+    }
+    // Rollback: the pinned version is the only one admitted. Running sandboxes drain on TTL.
+    if (lease.version && lease.version !== req.version) {
+        throw new LeaseDeniedError(`pack ${req.pack} is pinned to ${lease.version}; refusing to start ${req.version} (rollback in force)`);
+    }
+    // Supply-chain pin: the signed digest, not a mutable tag.
+    if (lease.imageDigest && req.image && !req.image.includes(lease.imageDigest)) {
+        throw new LeaseDeniedError(`image for ${req.pack} does not match the leased digest ${lease.imageDigest}`);
+    }
+    // Scoped stop orders. Both modes refuse a NEW sandbox — they differ only in what happens to one
+    // already running, which is the lease watcher's job, not admission's.
+    if (req.sessionKey) {
+        const verdict = denyVerdict(lease, {
+            sessionKey: req.sessionKey,
+            pack: req.pack,
+            userHash: req.userHash,
+            userId: req.userId,
+            followedUsers: req.followedUsers,
+        }, now);
+        if (verdict.denied) {
+            throw new LeaseDeniedError(verdict.reason ?? 'stopped by the control plane');
+        }
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// Signed leases
+// ---------------------------------------------------------------------------------------------
+/**
+ * WIRE FORMAT — signed lease.
+ *
+ * A **compact JWS (ES256)** whose payload is the `LeaseEnvelopeClaims` object above; identical
+ * machinery to `pack.sig` and to inference warrants, verified through the same
+ * `verifyCompactJws` (alg pinned to ES256, `kid` must already be known, raw R||S encoding) — but
+ * against its OWN JWKS trust root (`loadLeaseTrustRoot`, purpose `lease-signing`), not the pack
+ * one. A key that can vouch for a lease should not thereby be able to vouch for code, and the
+ * control plane will not register one kid under both purposes anyway.
+ *
+ *   header   { "alg": "ES256", "typ": "agenthippo-lease+jws", "kid": "<key id>" }
+ *   payload  { "lease": { …Lease… }, "aud": "<instance-id>" | "*", "sub": "<pack>",
+ *              "iat": <epoch s>, "exp": <epoch s>, "iss"?: "…", "jti"?: "…" }
+ *
+ * The endpoint may answer with any of:
+ *   1. the compact JWS as the response body (`text/plain` or a JSON string),
+ *   2. `{"lease": "<compact JWS>"}` — an envelope, so an endpoint can add unsigned metadata,
+ *   3. a bare `Lease` JSON object — LEGACY, unsigned, accepted only while signing is not required.
+ *
+ * `typ` prevents a pack signature (`typ: JWT`) from being replayed as a lease under the same key.
+ *
+ * Why each binding is present:
+ *
+ *   aud   the instance this lease was minted for. A lease captured from one instance cannot be
+ *         replayed at another. `*` is a legitimate fleet-wide lease and is accepted as such.
+ *   sub   the pack, cross-checked against `lease.pack`, so a lease for one product cannot be
+ *         re-labelled as another after signing.
+ *   iat   monotonic per instance: an envelope older than the newest one already accepted is
+ *         refused. This is the anti-ROLLBACK binding, and it is the one that matters most —
+ *         without it an on-path attacker replays yesterday's `enabled: true` lease forever and the
+ *         kill switch never lands. `governor.checkLease` treats a restored lease as "lease
+ *         restored — accepting turns again", so a replay does not merely delay a kill, it lifts
+ *         one that has already latched.
+ *   exp   the ENVELOPE's own expiry, separate from `lease.expiresAt` (an entitlement boundary that
+ *         is legitimately weeks out). Capped at `MAX_LEASE_ENVELOPE_TTL_SECONDS`, for the same
+ *         reason warrants are capped: there is no revocation list, so lifetime IS the revocation.
+ */
+exports.LEASE_JWS_TYP = 'agenthippo-lease+jws';
+/** Longer than this and the envelope is a credential, not a lease refresh. */
+exports.MAX_LEASE_ENVELOPE_TTL_SECONDS = 3600;
+/** Mint a signed lease. Used by the control plane and by tests; serve only ever verifies. */
+function signLease(lease, key, input) {
+    const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+    const ttl = Math.min(input.ttlSeconds ?? 300, exports.MAX_LEASE_ENVELOPE_TTL_SECONDS);
+    const claims = {
+        lease,
+        aud: input.instanceId ?? '*',
+        sub: lease.pack,
+        iat: now,
+        exp: now + ttl,
+        ...(input.iss ? { iss: input.iss } : {}),
+    };
+    return (0, warrant_1.signCompactJws)({ typ: exports.LEASE_JWS_TYP, kid: key.kid }, claims, key.privateKeyPem);
+}
+function verifySignedLease(token, publicKeysByKid, input = {}) {
+    if (Object.keys(publicKeysByKid).length === 0) {
+        return { ok: false, reason: 'no trusted lease-signing keys are configured on this instance' };
+    }
+    const jws = (0, warrant_1.verifyCompactJws)(token, publicKeysByKid, { typ: exports.LEASE_JWS_TYP });
+    if (!jws.ok) {
+        return { ok: false, reason: `lease signature: ${jws.reason}` };
+    }
+    const claims = jws.payload;
+    const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+    const skew = input.clockSkewSeconds ?? 60;
+    if (typeof claims.iat !== 'number' || !Number.isFinite(claims.iat)) {
+        return { ok: false, reason: 'lease envelope has no issued-at' };
+    }
+    if (typeof claims.exp !== 'number' || !Number.isFinite(claims.exp)) {
+        return { ok: false, reason: 'lease envelope has no expiry' };
+    }
+    if (claims.exp - claims.iat > exports.MAX_LEASE_ENVELOPE_TTL_SECONDS) {
+        return { ok: false, reason: `lease envelope lifetime ${claims.exp - claims.iat}s exceeds the ${exports.MAX_LEASE_ENVELOPE_TTL_SECONDS}s cap` };
+    }
+    if (claims.exp + skew <= now) {
+        return { ok: false, reason: `lease envelope expired at ${new Date(claims.exp * 1000).toISOString()}` };
+    }
+    if (claims.iat - skew > now) {
+        return { ok: false, reason: 'lease envelope is issued in the future' };
+    }
+    if (input.minIat !== undefined && claims.iat < input.minIat) {
+        return { ok: false, reason: `lease envelope is older than one already accepted (replay/rollback: iat ${claims.iat} < ${input.minIat})` };
+    }
+    if (input.instanceId !== undefined && claims.aud !== '*' && claims.aud !== input.instanceId) {
+        return { ok: false, reason: `lease envelope is for instance ${claims.aud}, not ${input.instanceId}` };
+    }
+    const parsed = (0, lease_schema_1.parseLease)(claims.lease);
+    if (!parsed.ok) {
+        return { ok: false, reason: `signed lease is malformed: ${parsed.reason}` };
+    }
+    if (claims.sub !== parsed.lease.pack) {
+        return { ok: false, reason: `lease envelope subject ${claims.sub} does not match lease.pack ${parsed.lease.pack}` };
+    }
+    return { ok: true, lease: parsed.lease, claims };
+}
+/** Tighten-only, exactly like `requireSignedPack`. Neither side may waive the other's demand. */
+function requireSignedLease(leaseValue, localValue) {
+    return Boolean(leaseValue) || Boolean(localValue);
+}
+const looksLikeCompactJws = (s) => /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(s);
+/**
+ * Caching lease source.
+ *
+ * Fail-OPEN on transport (network down ⇒ keep serving on the last known lease), fail-CLOSED on
+ * content (an expired or disabled lease refuses, cached or not). Three things changed:
+ *
+ *   1. The body is VALIDATED (`parseLease`), not cast. A document that does not parse is treated
+ *      exactly like a transport failure — the last good lease is kept and the failure is loud —
+ *      rather than being installed as policy with `NaN` caps and unreadable deny rules.
+ *   2. A SIGNED lease is verified against the LEASE trust root. Unsigned leases still work, and say
+ *      so loudly, unless signing is required — in which case they are refused.
+ *   3. Staleness is BOUNDED. Past `maxStalenessSeconds` without a successful refresh, `get`
+ *      returns a synthetic disabled lease so admission and the governor both fail closed. Network
+ *      denial can no longer hold a revoked fleet open indefinitely.
+ */
+function createLeaseSource(opts) {
+    let cached = opts.staticLease;
+    let fetchedAt = 0;
+    /** Wall-clock of the last SUCCESSFUL fetch. Distinct from `fetchedAt`, which drives the cache. */
+    let lastGoodAt;
+    let lastError;
+    let sawSignedLease = false;
+    /** Sticky: once the plane has demanded signed leases, an unsigned response cannot undo it. */
+    let leaseDemandsSignature = false;
+    let newestIat;
+    let staleWarned = false;
+    let unsignedWarned = false;
+    let urlChecked = false;
+    const ttl = opts.cacheSeconds ?? leaseCacheSecondsFor(exports.DEFAULT_LEASE_POLL_SECONDS);
+    const maxStaleness = opts.maxStalenessSeconds ?? leaseMaxStalenessFromEnv(opts.env);
+    const doFetch = opts.fetchImpl ?? fetch;
+    const signingRequired = () => requireSignedLease(leaseDemandsSignature, opts.requireSignedLease);
+    /**
+     * What `get` hands back once the ceiling is passed. A synthetic lease rather than `undefined`
+     * because `undefined` means "unmanaged, admit everything" everywhere in this file — returning it
+     * here would fail OPEN, which is the bug.
+     */
+    const staleLease = (staleFor) => ({
+        ...(cached ?? { pack: '', expiresAt: 0 }),
+        enabled: false,
+        reason: `the control plane has not been reachable for ${staleFor}s, past the ${maxStaleness}s staleness ceiling ` +
+            `(${exports.LEASE_MAX_STALENESS_ENV}). Refusing work rather than running on a lease that can no longer be revoked. ` +
+            `Set ${exports.LEASE_MAX_STALENESS_ENV}=0 to accept unbounded staleness.`,
+    });
+    const parseBody = (text, now) => {
+        const trimmed = text.trim();
+        let jws;
+        let jsonBody;
+        if (looksLikeCompactJws(trimmed)) {
+            jws = trimmed;
+        }
+        else {
+            try {
+                jsonBody = JSON.parse(trimmed);
+            }
+            catch (err) {
+                return { ok: false, reason: `lease body is not JSON: ${err instanceof Error ? err.message : String(err)}` };
+            }
+            if (typeof jsonBody === 'string' && looksLikeCompactJws(jsonBody.trim())) {
+                jws = jsonBody.trim();
+            }
+            else if (jsonBody && typeof jsonBody === 'object' && typeof jsonBody.lease === 'string') {
+                jws = (jsonBody.lease).trim();
+            }
+        }
+        if (jws) {
+            const verified = verifySignedLease(jws, opts.signingKeys?.() ?? {}, {
+                instanceId: opts.instanceId,
+                minIat: newestIat,
+                nowSeconds: now,
+            });
+            if (!verified.ok) {
+                return { ok: false, reason: verified.reason };
+            }
+            newestIat = verified.claims.iat;
+            return { ok: true, lease: verified.lease, signed: true };
+        }
+        if (signingRequired()) {
+            return {
+                ok: false,
+                reason: 'a signed lease is required but the control plane returned an unsigned one ' +
+                    '(expected a compact JWS body or {"lease":"<jws>"})',
+            };
+        }
+        const parsed = (0, lease_schema_1.parseLease)(jsonBody);
+        if (!parsed.ok) {
+            return { ok: false, reason: parsed.reason };
+        }
+        for (const w of parsed.warnings) {
+            opts.logger?.warn(`[Lease] ${w}`);
+        }
+        return { ok: true, lease: parsed.lease, signed: false };
+    };
+    return {
+        status(nowSeconds) {
+            const now = nowSeconds ?? Math.floor(Date.now() / 1000);
+            const staleFor = lastGoodAt === undefined ? undefined : now - lastGoodAt;
+            return {
+                signed: sawSignedLease,
+                requireSignedLease: signingRequired(),
+                lastGoodAt,
+                stalenessSeconds: staleFor,
+                maxStalenessSeconds: maxStaleness,
+                failClosed: maxStaleness > 0 && staleFor !== undefined && staleFor > maxStaleness,
+                lastError,
+            };
+        },
+        async get(nowSeconds) {
+            const now = nowSeconds ?? Math.floor(Date.now() / 1000);
+            if (!opts.url) {
+                return cached;
+            }
+            // The lease decides whether this instance may run at all, so the channel it arrives on is
+            // checked too — but WARNED about rather than refused, and the asymmetry with the trust
+            // root is deliberate. Refusing to poll a plaintext lease URL would stop the kill switch
+            // from arriving at all: it fails OPEN, which is strictly worse than polling an
+            // interceptable channel. The trust root refuses because refusing there fails CLOSED
+            // (packs stop verifying). The real fix for a plaintext lease is `requireSignedLease` —
+            // most of what an on-path device could do is undone once the signature, not the
+            // transport, is what is being trusted.
+            //
+            // There used to be a `leaseUrlRefused` flag here, declared and read but never assigned:
+            // its comment promised "we never poll it at all", which is precisely the refusal the
+            // paragraph above rules out. It has been deleted rather than wired up — a live flag that
+            // bricks a fleet's kill switch is worse than a dead one.
+            //
+            // The warning fires in EVERY insecure case. It used to be guarded by
+            // `else if (!signingRequired())`, so the case an operator most needs to hear about — one
+            // who has demanded signed leases and therefore believes the channel is accounted for —
+            // was the only silent one.
+            if (!urlChecked) {
+                urlChecked = true;
+                const secure = (0, signature_1.assertSecureTrustUrl)(opts.url, 'AGENTHIPPO_LEASE_URL', opts.env ?? process.env);
+                if (secure.ok) {
+                    for (const w of secure.warnings) {
+                        opts.logger?.warn(`[Lease] ${w}`);
+                    }
+                }
+                else if (signingRequired()) {
+                    // Signing covers the CONTENT, not the channel. What is left is still governance:
+                    // the poll carries this instance's id, pack and version in the clear, and an
+                    // on-path device can withhold a kill switch by replaying the last envelope until
+                    // its own `exp` runs out.
+                    opts.logger?.warn(`[Lease] INSECURE LEASE CHANNEL — ${secure.reason} Signed leases are required here, so the ` +
+                        'policy itself is still verified — but the channel is not: anyone on the path can read this ' +
+                        `instance's identity, pack and version, and can delay a kill switch by up to ` +
+                        `${exports.MAX_LEASE_ENVELOPE_TTL_SECONDS}s by replaying the last envelope. requireSignedLease is not a ` +
+                        'substitute for https; serve the lease over https.');
+                }
+                else {
+                    opts.logger?.warn(`[Lease] INSECURE LEASE CHANNEL — ${secure.reason} Anyone on the path can lift this instance's ` +
+                        'kill switch, widen its caps or change its version pin. Continuing to poll (refusing would ' +
+                        'disable the kill switch entirely), but this deployment is not governable until the lease is ' +
+                        'signed: set requireSignedLease and have the control plane sign leases.');
+                }
+            }
+            if (cached && now - fetchedAt < ttl) {
+                return cached;
+            }
+            try {
+                const headers = { accept: 'application/json, text/plain' };
+                for (const [key, value] of Object.entries(opts.identity?.() ?? {})) {
+                    if (value !== undefined && value !== '') {
+                        headers[`x-agenthippo-${key}`] = String(value);
+                    }
+                }
+                const res = await doFetch(opts.url, { headers });
+                if (!res.ok) {
+                    throw new Error(`lease fetch ${res.status}`);
+                }
+                const text = typeof res.text === 'function'
+                    ? await res.text()
+                    // Test doubles and older shims implement only `json()`.
+                    : JSON.stringify(await res.json());
+                const parsed = parseBody(text, now);
+                if (!parsed.ok) {
+                    // A garbled or unverifiable document is NOT installed as policy. It behaves like a
+                    // transport failure, which is the only reading that cannot be used to weaken
+                    // enforcement by publishing junk.
+                    throw new Error(parsed.reason);
+                }
+                if (parsed.signed) {
+                    sawSignedLease = true;
+                    if (parsed.lease.requireSignedLease) {
+                        leaseDemandsSignature = true;
+                    }
+                }
+                else if (!unsignedWarned) {
+                    unsignedWarned = true;
+                    opts.logger?.warn('[Lease] running on an UNSIGNED lease. Anyone who can answer or intercept ' +
+                        `${opts.url} can lift this instance's kill switch, widen its caps and change its version pin. ` +
+                        'Have the control plane sign leases (ES256 compact JWS) and set requireSignedLease.');
+                }
+                cached = parsed.lease;
+                fetchedAt = now;
+                lastGoodAt = now;
+                lastError = undefined;
+                staleWarned = false;
+                return cached;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err.message : String(err);
+                // Transport failure keeps the LAST lease, which still expires on its own clock —
+                // an outage cannot extend an entitlement, only preserve one already granted.
+                opts.logger?.warn(`[Lease] fetch failed, using cached lease: ${lastError}`);
+                if (lastGoodAt === undefined) {
+                    lastGoodAt = now;
+                }
+                const staleFor = now - lastGoodAt;
+                if (maxStaleness > 0 && staleFor > maxStaleness) {
+                    if (!staleWarned) {
+                        staleWarned = true;
+                        opts.logger?.warn(`[Lease] STALENESS CEILING PASSED — no successful lease refresh for ${staleFor}s ` +
+                            `(ceiling ${maxStaleness}s). Failing closed: turns are refused until the control plane is reachable.`);
+                    }
+                    return staleLease(staleFor);
+                }
+                return cached;
+            }
+        },
+    };
+}