@intutic/gate 2.4.0 → 2.5.1

package/dist/chaosGate.js

@@ -0,0 +1,372 @@
+/**
+ * Fault injection in the gates: the part of a chaos run (`chaos.ts`) a hook
+ * gate or an in-process gate SDK carries.
+ *
+ * A hook gate is a new process per tool call, and parallel gates share one
+ * run, so nothing here keeps state in memory: the plan comes from {@link CHAOS_PLAN_ENV}-style text each call,
+ * and every count lives in files beside the events file.
+ *
+ * - `<events>.gate-plan-loaded` — created once, with an exclusive create; the
+ *   gate that creates it reports `plan_loaded`, so separate gate processes do
+ *   not repeat it.
+ * - `<events>.gate-counters/<fault index>.seen.<n>` and `.hit.<n>` — one
+ *   empty file per matching call a fault saw and per call it hit. A call
+ *   claims the next number with an exclusive create (`open` with `wx`,
+ *   `O_CREAT | O_EXCL`), which the file system grants to exactly one process,
+ *   so two gates deciding at once can never both take the same number; the
+ *   claimed number is the call's 1-based index. A count is the number of
+ *   files, read once to start the search, so a claim costs one directory
+ *   read and usually one create. That is `FaultCounter`'s `after_calls` and
+ *   `times` across processes.
+ * - `<events>.gate-counters/<fault index>.held.<key>.<g>` — a call a
+ *   `permission.deny_or_delay` fault in `delay` or `hold_then_deny` mode
+ *   held; its modification time is when. `<key>` is the call's digest (the
+ *   tool and its input, as the gate keys an approval hold), `<g>` counts the
+ *   holds of that call, claimed like a call number. `.released.<key>.<g>`,
+ *   created with the same exclusive create, ends that hold: one retry, and
+ *   only one, is the one the hold lets through or denies.
+ *
+ * A permission fault never makes a gate wait. It holds the call the way an
+ * approval hold does: the call is refused as held, and the identical retry
+ * (same tool, same input) is refused as held again until `delay_s` seconds
+ * have passed since the first refusal. After that the retry is allowed
+ * (`delay`) or denied (`hold_then_deny`), and the hold is over: the next
+ * identical call is a new matching call. A held call's retries are the same
+ * call, so no fault counts them as matching calls. A test moves the clock by
+ * moving the `held` files' modification times back.
+ *
+ * Only a call governance allowed counts: a fault never applies to a call the
+ * gate refused, held or asked about, so such a call is not one of the
+ * fault's matching calls either. Every fault whose `match` covers an allowed
+ * call counts it as seen; the first one in plan order that is due injects,
+ * and the faults after it do not spend a hit on the same call. A `tool.error`
+ * on an `mcp__<server>__<tool>` call is the MCP proxy's to inject, so a gate
+ * leaves it alone; `permission.deny_or_delay` is the gate's on any tool.
+ *
+ * The functions are self-contained on purpose — no imports, no module state —
+ * because the JavaScript hook gates emit them as source
+ * ({@link CHAOS_GATE_JS_SOURCE}) and run them outside this package, and
+ * `@intutic/gate` carries a byte-identical copy of this file
+ * (`packages/gate-js/src/chaosGate.ts`). The bash gates and
+ * `intutic_clawde.gate` run the Python transliteration,
+ * `intutic_clawde/gate/chaos.py`, which the sync daemon emits verbatim. All
+ * of them run `fixtures/chaos-gate-vectors.json`. File access goes through
+ * the `fs` argument (Node's `fs` in a gate).
+ *
+ * @module
+ */
+/**
+ * Decodes and checks a plan: base64url JSON, version 1, with valid values in
+ * every field a gate reads. Returns the plan, or why it is not one.
+ */
+export function chaosGateDecode(raw) {
+    const ids = [
+        'llm.rate_limit', 'llm.upstream_5xx', 'llm.context_trim', 'llm.model_degrade', 'tool.error', 'tool.stale_data',
+        'mcp.toolset_change', 'permission.deny_or_delay', 'inject.tool_result', 'egress.dns_fail', 'egress.credential_401',
+    ];
+    const invalid = (why) => ({ plan: null, error: 'INTUTIC_CHAOS_PLAN is not a valid plan: ' + why });
+    const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+    const isInt = (v, min, max) => typeof v === 'number' && Number.isInteger(v) && v >= min && v <= max;
+    let json;
+    try {
+        if (typeof raw !== 'string' || !/^[A-Za-z0-9_-]+={0,2}$/.test(raw))
+            throw new Error('alphabet');
+        const b64 = raw.replace(/=+$/, '').replace(/-/g, '+').replace(/_/g, '/');
+        const binary = atob(b64 + '='.repeat((4 - (b64.length % 4)) % 4));
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++)
+            bytes[i] = binary.charCodeAt(i);
+        json = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        return { plan: null, error: 'INTUTIC_CHAOS_PLAN is not base64url-encoded JSON' };
+    }
+    if (!isObject(json))
+        return invalid('not a JSON object');
+    if (json.v !== 1)
+        return invalid('version ' + JSON.stringify(json.v) + ', and a gate reads only version 1');
+    if (typeof json.runId !== 'string' || !/^[A-Za-z0-9_-]{6,64}$/.test(json.runId))
+        return invalid('runId');
+    if (typeof json.canary !== 'string' || !/^E-INTUTIC-[0-9A-F]{4,16}$/.test(json.canary))
+        return invalid('canary');
+    if (!Array.isArray(json.faults) || json.faults.length > 50)
+        return invalid('faults');
+    const faults = [];
+    for (let i = 0; i < json.faults.length; i++) {
+        const f = json.faults[i];
+        const at = 'faults[' + i + ']';
+        if (!isObject(f) || typeof f.id !== 'string' || ids.indexOf(f.id) === -1)
+            return invalid(at + '.id');
+        if (f.id !== 'tool.error' && f.id !== 'permission.deny_or_delay')
+            continue;
+        let match = null;
+        if (f.match !== undefined) {
+            if (!isObject(f.match))
+                return invalid(at + '.match');
+            for (const k of Object.keys(f.match)) {
+                const v = f.match[k];
+                if ((k !== 'tool' && k !== 'host' && k !== 'model') || typeof v !== 'string' || v.length === 0) {
+                    return invalid(at + '.match.' + k);
+                }
+            }
+            match = f.match;
+        }
+        if (f.after_calls !== undefined && !isInt(f.after_calls, 0, 10000))
+            return invalid(at + '.after_calls');
+        if (f.times !== undefined && !isInt(f.times, 1, 10000))
+            return invalid(at + '.times');
+        const fault = {
+            index: i,
+            id: f.id,
+            match: match,
+            afterCalls: f.after_calls === undefined ? 0 : f.after_calls,
+            times: f.times === undefined ? null : f.times,
+            message: 'tool failed',
+            mode: 'deny',
+            delayS: 0,
+        };
+        if (f.id === 'tool.error' && f.message !== undefined) {
+            if (typeof f.message !== 'string' || f.message.length < 1 || f.message.length > 2000)
+                return invalid(at + '.message');
+            fault.message = f.message;
+        }
+        if (f.id === 'permission.deny_or_delay') {
+            if (f.mode !== undefined) {
+                if (f.mode !== 'deny' && f.mode !== 'delay' && f.mode !== 'hold_then_deny')
+                    return invalid(at + '.mode');
+                fault.mode = f.mode;
+            }
+            if (f.delay_s !== undefined) {
+                if (!isInt(f.delay_s, 0, 600))
+                    return invalid(at + '.delay_s');
+                fault.delayS = f.delay_s;
+            }
+        }
+        faults.push(fault);
+    }
+    return { plan: { runId: json.runId, canary: json.canary, faults: faults }, error: null };
+}
+/**
+ * Whether a fault's `match` covers a gate call. A gate call has a tool and
+ * nothing else, so a fault that names a host or a model never matches one.
+ * `tool` matches exactly, or by suffix when it starts with `*`.
+ */
+export function chaosGateMatches(match, tool) {
+    if (!match)
+        return true;
+    if (match.host !== undefined || match.model !== undefined)
+        return false;
+    const p = match.tool;
+    if (p === undefined)
+        return true;
+    return p.charAt(0) === '*' ? tool.endsWith(p.slice(1)) : tool === p;
+}
+/** One events-file line: `ts`, `runId`, `component`, `type`, then the fields that are set. */
+export function chaosGateEvent(plan, type, fields, now) {
+    const event = { ts: now, runId: plan.runId, component: 'gate', type: type };
+    for (const k of Object.keys(fields))
+        if (fields[k] !== undefined && fields[k] !== null)
+            event[k] = fields[k];
+    return JSON.stringify(event) + '\n';
+}
+/** Appends whole lines in one write. An I/O error is reported, never thrown: it must not decide the call. */
+export function chaosGateAppend(fs, eventsPath, lines) {
+    try {
+        fs.appendFileSync(eventsPath, lines);
+    }
+    catch (e) {
+        try {
+            console.error('[Intutic Governance] chaos: could not append to ' + eventsPath + ': ' + String((e && e.message) || e));
+        }
+        catch {
+            /* stderr gone too */
+        }
+    }
+}
+/**
+ * Claims the next numbered file `<dir>/<prefix><n>` with an exclusive create
+ * and returns n, or 0 when every number up to `limit` is taken. -1 on an I/O
+ * error, after saying so.
+ */
+export function chaosGateClaim(fs, dir, prefix, limit) {
+    try {
+        // Beside the events file, never creating its directory: the runner did.
+        try {
+            fs.mkdirSync(dir);
+        }
+        catch (e) {
+            if (!e || e.code !== 'EEXIST')
+                throw e;
+        }
+        const names = fs.readdirSync(dir);
+        let n = 0;
+        for (let i = 0; i < names.length; i++)
+            if (names[i].indexOf(prefix) === 0)
+                n++;
+        for (n = n + 1; limit === null || n <= limit; n++) {
+            try {
+                fs.closeSync(fs.openSync(dir + '/' + prefix + n, 'wx'));
+                return n;
+            }
+            catch (e) {
+                if (!e || e.code !== 'EEXIST')
+                    throw e;
+            }
+        }
+        return 0;
+    }
+    catch (e) {
+        try {
+            console.error('[Intutic Governance] chaos: could not count calls in ' + dir + ': ' + String((e && e.message) || e));
+        }
+        catch {
+            /* stderr gone too */
+        }
+        return -1;
+    }
+}
+/**
+ * The open hold of one fault on one call: the number of the newest
+ * `<fault>.held.<key>.<g>` file that has no `.released.` twin, and when it
+ * was created. Null when there is none or it cannot be read.
+ */
+export function chaosGateOpenHold(fs, dir, fault, key) {
+    try {
+        const held = fault + '.held.' + key + '.';
+        const names = fs.readdirSync(dir);
+        let g = 0;
+        for (let i = 0; i < names.length; i++) {
+            if (names[i].indexOf(held) !== 0)
+                continue;
+            const n = Number(names[i].slice(held.length));
+            if (n > g)
+                g = n;
+        }
+        if (g === 0 || names.indexOf(fault + '.released.' + key + '.' + g) !== -1)
+            return null;
+        // In whole milliseconds, as now is: a hold is never younger than the call that reads it.
+        return { g: g, sinceMs: Math.floor(fs.statSync(dir + '/' + held + g).mtimeMs) };
+    }
+    catch {
+        // No counters yet, or none readable: no hold to continue.
+        return null;
+    }
+}
+/** Ends hold g with an exclusive create: true for the one caller that does. */
+export function chaosGateRelease(fs, dir, fault, key, g) {
+    try {
+        fs.closeSync(fs.openSync(dir + '/' + fault + '.released.' + key + '.' + g, 'wx'));
+        return true;
+    }
+    catch {
+        // Another gate released it first, or it cannot be written.
+        return false;
+    }
+}
+/**
+ * Reports one call: `plan_loaded` the first time any gate reports to this
+ * events file, then `gate_decision`; for an allowed call, the fault that is
+ * due (`fault_injected`, once per held call however often it is retried),
+ * and `tool_call`: ok when the call goes ahead, not ok when it is held.
+ * Returns the fault the gate must apply, or null. `now` is the ISO-8601 time,
+ * and the clock a hold is timed by.
+ */
+export function chaosGateCall(fs, plan, eventsPath, call, now) {
+    let lines = '';
+    let first = true;
+    try {
+        fs.closeSync(fs.openSync(eventsPath + '.gate-plan-loaded', 'wx'));
+    }
+    catch (e) {
+        // Already reported. Any other error: report again rather than not at all.
+        if (e && e.code === 'EEXIST')
+            first = false;
+    }
+    if (first)
+        lines += chaosGateEvent(plan, 'plan_loaded', { faults: plan.faults.length }, now);
+    lines += chaosGateEvent(plan, 'gate_decision', {
+        tool: call.tool,
+        decision: call.decision,
+        ruleId: call.ruleId || null,
+        destructive: !!call.destructive,
+        policyHit: !!call.policyHit,
+    }, now);
+    let fault = null;
+    if (call.decision === 'allow') {
+        const dir = eventsPath + '.gate-counters';
+        const key = String(call.key || '').replace(/[^0-9A-Za-z]/g, '').slice(0, 128) || 'call';
+        let nowMs = Date.parse(now);
+        if (isNaN(nowMs))
+            nowMs = Date.now();
+        const tag = ' [' + plan.canary + ']';
+        const held = 'Permission held for approval; retrying this exact call passes once it is approved' + tag;
+        // The retry of a held call: still held until the delay has passed, then
+        // let through or denied by the one retry that releases it.
+        let retry = false;
+        for (let i = 0; i < plan.faults.length && !retry; i++) {
+            const f = plan.faults[i];
+            if (f.id !== 'permission.deny_or_delay' || f.mode === 'deny' || !chaosGateMatches(f.match, call.tool))
+                continue;
+            const open = chaosGateOpenHold(fs, dir, f.index, key);
+            if (!open)
+                continue;
+            retry = true;
+            if (f.delayS > 0 && nowMs - open.sinceMs < f.delayS * 1000) {
+                fault = { faultId: f.id, kind: 'hold', reason: held };
+            }
+            else if (chaosGateRelease(fs, dir, f.index, key, open.g)) {
+                if (f.mode === 'hold_then_deny') {
+                    fault = { faultId: f.id, kind: 'deny', reason: 'Permission held for approval, then denied by approver' + tag };
+                }
+            }
+            else {
+                // Another gate released it first: this call is a new one.
+                retry = false;
+            }
+        }
+        for (let i = 0; i < plan.faults.length && !retry; i++) {
+            const f = plan.faults[i];
+            if (!chaosGateMatches(f.match, call.tool))
+                continue;
+            // An MCP tool's error is the MCP proxy's to inject; a gate injects the built-in side.
+            if (f.id === 'tool.error' && call.tool.indexOf('mcp__') === 0)
+                continue;
+            const seen = chaosGateClaim(fs, dir, f.index + '.seen.', null);
+            if (fault || seen < 1 || seen <= f.afterCalls)
+                continue;
+            if (f.times !== null && chaosGateClaim(fs, dir, f.index + '.hit.', f.times) < 1)
+                continue;
+            if (f.id === 'tool.error') {
+                fault = { faultId: f.id, kind: 'deny', reason: f.message + tag };
+            }
+            else if (f.mode === 'deny') {
+                fault = { faultId: f.id, kind: 'deny', reason: 'Permission denied by approver' + tag };
+            }
+            else {
+                // Held from now: the hold's file is what its retries find.
+                if (chaosGateClaim(fs, dir, f.index + '.held.' + key + '.', null) < 1)
+                    continue;
+                fault = { faultId: f.id, kind: 'hold', reason: held };
+            }
+            lines += chaosGateEvent(plan, 'fault_injected', { faultId: f.id, call: seen, target: call.tool }, now);
+        }
+        if (!fault || fault.kind === 'hold')
+            lines += chaosGateEvent(plan, 'tool_call', { tool: call.tool, ok: !fault }, now);
+    }
+    chaosGateAppend(fs, eventsPath, lines);
+    return fault;
+}
+/** Every function above as JavaScript source, for a hook gate to emit. */
+export const CHAOS_GATE_JS_SOURCE = [
+    chaosGateDecode,
+    chaosGateMatches,
+    chaosGateEvent,
+    chaosGateAppend,
+    chaosGateClaim,
+    chaosGateOpenHold,
+    chaosGateRelease,
+    chaosGateCall,
+]
+    .map((f) => f.toString())
+    .join('\n');
+//# sourceMappingURL=chaosGate.js.map

package/dist/chaosGate.js.map

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

package/dist/client.d.ts

@@ -5,44 +5,88 @@
  *
  * Endpoints used:
  *
- *   POST /api/v1/hook-gate       synchronous allow/deny  -> {allowed, reason, incidentId?, code?}
+ *   POST /api/v1/hook-gate       synchronous allow/deny  -> {allowed, reason, incidentId?, code?, degraded?, decisionId?}
  *   POST /api/v1/hook-events     batched telemetry       -> creates governance_incidents rows
  *   POST /api/v1/decisions       record a hold           -> joins the review queue (hold.ts)
  *   GET  /api/v1/decisions/approved-bypasses             -> approvals that let a held call through
  *
  * Two behaviours that must not be "improved":
  *
- *   * The hook-gate SERVER fails OPEN on its own error paths — it returns
- *     `{allowed:true}` on malformed input, schema mismatch, or DB error,
- *     because blocking a developer over a bad payload teaches people to
- *     disable the hook. This CLIENT, by contrast, defaults to FAIL-CLOSED
- *     (`failClosed=true`) for blocking decisions: a transport error or
- *     non-2xx response means we have no verdict at all to defer to, so
- *     `hookGate` reports `allowed=false`. Set `failClosed=false` to treat the
- *     tier as advisory, mirroring the server's own posture.
+ *   * The hook gate fails CLOSED, on both sides. The server refuses a call
+ *     whose checks could not run (403 `GOVERNANCE_UNAVAILABLE`; a shadow-mode
+ *     workspace gets a degraded allow instead) and a body it cannot read
+ *     (400 `INVALID_REQUEST`). This client treats `GOVERNANCE_UNAVAILABLE`
+ *     exactly as it treats a control plane it cannot reach, a non-2xx answer,
+ *     or an answer with no boolean `allowed`: there is no verdict to defer to,
+ *     and `failClosed` (default true) decides, reporting `allowed=false`. Set
+ *     `failClosed=false` to treat the tier as advisory during an outage. A 400
+ *     is refused whatever `failClosed` says: it is this client's request that
+ *     is wrong, not the control plane that is down, and allowing would hide it.
  *   * `emit` NEVER throws. Telemetry that can break a run is worse than no
  *     telemetry.
+ *
+ * A client with no API key is LOCAL-ONLY ({@link GateClient.localOnly}): it
+ * cannot authenticate, so it makes no request at all. Its hook gate answers
+ * allow with code `LOCAL_ONLY` and says why, its events and holds are not
+ * sent, and the `Gate` skips the SOP register. The local tiers (policy
+ * snapshot, SSO groups from the snapshot, MCP registry, image integrity) are
+ * unaffected. A client WITH a key that the control plane refuses (401) is not
+ * local-only: that is an authentication fault, and fails closed as above.
  */
 export interface GateResponse {
     allowed: boolean;
     reason: string;
     incidentId?: string | undefined;
-    /** The refusal code the hook gate names, when it names one (the MCP registry's). */
+    /**
+     * The code the hook gate names, when it names one: the MCP registry's on its
+     * refusals, `GOVERNANCE_UNAVAILABLE` when its checks could not run, and
+     * `INVALID_REQUEST` when it could not read the request.
+     */
     code?: string | undefined;
-    /** False when the call failed and `failClosed` decided the verdict. */
+    /** False when the hook gate gave no verdict and `failClosed` decided it. */
     reached: boolean;
+    /**
+     * The hook gate's id for this decision, when this answer is its own verdict:
+     * every verdict it gives names one, and a `GOVERNANCE_UNAVAILABLE` refusal
+     * keeps it only while `failClosed` refuses too. The gate reports the call
+     * with it (`gateDecisionId`), so the control plane exports the decision to
+     * SIEM once and files its incident once.
+     */
+    decisionId?: string | undefined;
 }
+/** Options for a {@link GateClient}. Every field is optional. */
 export interface GateClientOptions {
+    /**
+     * The control plane's address.
+     * @defaultValue `INTUTIC_CONTROL_PLANE_URL`, then Intutic's hosted control plane
+     */
     baseUrl?: string;
+    /**
+     * The API key. Without one the client is {@link GateClient.localOnly | local-only}.
+     * @defaultValue `''`
+     */
     apiKey?: string;
+    /** @defaultValue `''` */
     workspaceId?: string;
+    /** @defaultValue `''` */
     sessionId?: string;
     /**
      * Attributes incidents to the right adapter. Sent as `harnessType` on every
      * gate call and event.
+     * @defaultValue `'generic'`
      */
     harness?: string;
+    /**
+     * Block a call when the hook gate gives no verdict: the control plane
+     * cannot be reached, answers without one, or answers
+     * `GOVERNANCE_UNAVAILABLE`. `false` lets such a call go ahead.
+     * @defaultValue `true`
+     */
     failClosed?: boolean;
+    /**
+     * How long one control-plane request may take.
+     * @defaultValue `2000`
+     */
     timeoutMs?: number;
 }
 /**
@@ -62,6 +106,12 @@ export declare class GateClient {
     readonly failClosed: boolean;
     readonly timeoutMs: number;
     constructor(opts?: GateClientOptions);
+    /**
+     * True when there is no API key. Such a client cannot authenticate, so it
+     * sends nothing: the control-plane tiers (SOP register, hook gate) are
+     * skipped, events and holds are not reported, and the local tiers decide.
+     */
+    get localOnly(): boolean;
     private post;
     private request;
     /**
@@ -71,19 +121,36 @@ export declare class GateClient {
      * plus SOP rules. It is defence in depth on top of the local tiers, not a
      * replacement for them.
      *
-     * When the call itself fails (transport error, non-2xx), the verdict is
-     * decided by `failClosed`: true (the default) reports BLOCK, because a
-     * client with no verdict has nothing to defer to; false reports allow,
-     * mirroring the server's own fail-open error paths.
+     * When there is no verdict (the control plane cannot be reached, answers
+     * non-2xx or without a boolean `allowed`, or answers
+     * `GOVERNANCE_UNAVAILABLE` because its own checks could not run), the
+     * verdict is decided by `failClosed`: true (the default) reports BLOCK,
+     * because a client with no verdict has nothing to defer to; false reports
+     * allow. A 400 `INVALID_REQUEST` is a BLOCK whatever `failClosed` says. A
+     * shadow-mode workspace's `{allowed: true, degraded: true}` is an allow.
+     *
+     * A {@link localOnly} client makes no call and answers allow with code
+     * `LOCAL_ONLY`, whatever `failClosed` says: with no key there is no
+     * control-plane tier to fail, only local ones, which have already run.
      */
     hookGate(toolName: string, toolInput: unknown): Promise<GateResponse>;
+    /**
+     * The answer when the hook gate gave no verdict: `failClosed` decides. A
+     * `GOVERNANCE_UNAVAILABLE` refusal's `decisionId` is kept when failing
+     * closed, which refuses as the hook gate did, and dropped when failing open:
+     * the call then runs, and its report must not stand for the refusal.
+     */
+    private noVerdict;
     /**
      * Fire-and-forget telemetry. Never throws.
      *
      * A `tool_blocked` event creates a `governance_incidents` row whose
-     * description embeds the reason verbatim.
+     * description embeds the reason verbatim. `gateDecisionId` is the hook
+     * gate's `decisionId` for the call this event reports: the control plane
+     * then files the decision's incident once and does not export it to SIEM a
+     * second time.
      */
-    emit(event: string, toolName: string, reason?: string, toolInput?: unknown, incidentId?: string, filePath?: string): Promise<boolean>;
+    emit(event: string, toolName: string, reason?: string, toolInput?: unknown, incidentId?: string, filePath?: string, gateDecisionId?: string): Promise<boolean>;
     /**
      * Records one hold in the review queue (`POST /api/v1/decisions`), the way
      * the hook gates' records reach it. Never throws; `false` when the control
@@ -102,6 +169,7 @@ export declare class GateClient {
      *
      * Reading `~/.intutic/credentials.json` means the gate works with whatever
      * workspace `intutic login` already bound, instead of duplicating the key.
+     * With no key in either place the client is {@link localOnly}.
      */
     static fromEnv(opts?: {
         sessionId?: string;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA4BH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;gBAEd,IAAI,GAAE,iBAAsB;YAa1B,IAAI;YAIJ,OAAO;IA2BrB;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;IAqC3E;;;;;OAKG;IACG,IAAI,CACR,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,SAAK,EACX,SAAS,CAAC,EAAE,OAAO,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;IA4BnB;;;;;OAKG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IASjE;;;;OAIG;IACG,gBAAgB,IAAI,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;IASnD;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,UAAU;CAoCtG"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA4BH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAA;IAChB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAChC;AA4BD,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yBAAyB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;gBAEd,IAAI,GAAE,iBAAsB;IAaxC;;;;OAIG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;YAEa,IAAI;YAIJ,OAAO;IAoCrB;;;;;;;;;;;;;;;;;;OAkBG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;IAuD3E;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IASjB;;;;;;;;OAQG;IACG,IAAI,CACR,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,SAAK,EACX,SAAS,CAAC,EAAE,OAAO,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,OAAO,CAAC;IA6BnB;;;;;OAKG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IASjE;;;;OAIG;IACG,gBAAgB,IAAI,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;IASnD;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,UAAU;CAoCtG"}