@memnox/interceptors 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,521 @@
+import { LocalGate, ActionRequest, DecisionEffect, Alternative, HoldService, LeaseGate, LeaseHolder, Overlay, BinaryVerdict, DaemonResponse, BrowserHosts, MemnoxEvent, EventSink, BreakerThresholds, SessionPause } from '@memnox/core';
+
+/** Policy files evaluated in-process — this is what sees the tool's arguments. */
+declare const ENV_POLICIES = "MEMNOX_POLICIES";
+/** Name the local rules match on `agents:`; defaults to the agent kind. */
+declare const ENV_AGENT_NAME = "MEMNOX_AGENT_NAME";
+/** The job it was enrolled under, matched by a rule's `roles:`. A workforce is
+ * several agents with different authority, and this is what tells them apart. */
+declare const ENV_AGENT_ROLE = "MEMNOX_AGENT_ROLE";
+declare const POLICY_PATH_SEPARATOR = ",";
+/** The agent kind this seam is installed into, used as the default policy identity. */
+declare const DEFAULT_AGENT_NAME = "claude-code";
+/** Actions that carry a payload somewhere this machine does not control. */
+declare const EGRESS_ACTIONS: readonly string[];
+/** Loopback only: a proxy reachable from the network is a hole, not a seam. */
+declare const EGRESS_DEFAULT_PORT = 8888;
+/** A body larger than this is not read, and is never treated as though it had been. */
+declare const EGRESS_MAX_BODY_BYTES = 1000000;
+
+interface HookVerdict {
+    effect: DecisionEffect;
+    reason: string;
+    /** What the agent may use instead, carried into the denial the model reads. */
+    alternative?: Alternative;
+    /** The rule that matched, so a reported verdict cites rather than asserts. */
+    rule?: string;
+    /** Present when a person has to answer; printed so the terminal can resolve it. */
+    approvalId?: string;
+    /** The verdict this came from, so a hooked call joins its decision in the ledger. */
+    decisionId?: string;
+    /**
+     * Set when nobody could be asked, rather than when somebody said no. A seam that
+     * can only ever subtract needs to tell those apart before it decides what to do.
+     */
+    unreachable?: true;
+}
+interface HookAuthorizerDeps {
+    /** Evaluated in-process against this machine's policy files; sees the arguments. */
+    gate?: LocalGate;
+    /** The runtime, which alone can resolve an alternative and raise an approval. */
+    /** Allow the tool when the runtime is unreachable. Default false — fail closed. */
+    failOpen?: boolean;
+    /** Which seam is reporting, so coverage and drift can tell them apart. */
+    seam?: string;
+    log: (message: string) => void;
+}
+/**
+ * Local first, runtime second, strictest wins — the same order the MCP seam uses. A
+ * local refusal never becomes a network request, so the arguments that produced it
+ * stay on this machine.
+ */
+declare class HookAuthorizer {
+    private readonly deps;
+    constructor(deps: HookAuthorizerDeps);
+    authorize(request: ActionRequest): Promise<HookVerdict>;
+    private egress;
+    /** Null when no policy files were configured, which leaves the runtime as the gate. */
+    private locally;
+}
+
+interface HookConfig {
+    policyFiles: string[];
+    agentName?: string;
+    /** The role a rule's `roles:` matches, when this agent was enrolled under one. */
+    agentRole?: string;
+}
+/**
+ * The environment first, then the registry on disk. An agent launched from a desktop
+ * icon inherits no shell, so reading only the environment would install cleanly and
+ * then govern nothing — which is worse than not installing.
+ */
+declare function readHookConfig(env: NodeJS.ProcessEnv, homeDir: string): Promise<HookConfig>;
+
+/** Null leaves the runtime as the only gate, which is what an unconfigured install has. */
+declare function loadHookGate(config: HookConfig, home?: string, now?: () => string): Promise<LocalGate | null>;
+
+declare const SHELL_ACTION = "shell.execute";
+interface ShellOutcome {
+    /** The command to run, present only when it may proceed. */
+    run?: readonly string[];
+    /** Printed on stderr. A refusal that explains nothing gets the wrapper removed. */
+    message?: string;
+    exitCode: number;
+}
+declare const SHELL_EXIT_OK = 0;
+declare const SHELL_EXIT_WITHHELD = 77;
+interface ShellSeamDeps {
+    authorizer: HookAuthorizer;
+    sessionId?: string;
+    workingDirectory?: string;
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Somebody to ask. Absent means an ASK is withheld and says so, which is right for
+     * a test and wrong for a shell an agent is typing into: without one, every `ask`
+     * rule the line hits is a refusal nobody was offered the chance to answer.
+     */
+    hold?: HoldService;
+    /**
+     * Two agents on one repository. Absent on a machine running one agent, which is the
+     * ordinary case and must stay free of every cost this adds.
+     */
+    leases?: {
+        gate: LeaseGate;
+        holder: LeaseHolder;
+        repositoryRoot: string;
+        isDirectory: (path: string) => boolean;
+    };
+}
+/**
+ * Gates a command and then gets out of the way. It never rewrites what was asked for:
+ * a modified command is a bug the person cannot see and the reader cannot audit.
+ *
+ * Every command in the line is resolved through the one resolver in core, so a rule
+ * named `gh.pr-merge` — which is what `protect --for gh` writes and what `explain`
+ * promises — fires here too. Ruling on the raw line alone would have made every screen
+ * that names a CLI verb describe a gate that never closes.
+ */
+declare class ShellSeam {
+    private readonly deps;
+    constructor(deps: ShellSeamDeps);
+    gate(command: readonly string[]): Promise<ShellOutcome>;
+    /**
+     * Puts an ASK to a person. Null when it was allowed and the line may proceed.
+     *
+     * Withheld rather than run when nobody answers: a walk-away must not become a yes,
+     * and a timeout is said differently from a refusal so the two read differently.
+     */
+    private askAbout;
+    /**
+     * Takes the paths this line writes, or answers with who is already on them. Reads
+     * never reach the register: `takesLease` decides that here, so there is no path
+     * through this seam that can make a reader wait.
+     */
+    private claim;
+    private requestFor;
+}
+
+/**
+ * What a shell was asked to do. `memnox run` sets this binary as `SHELL`, and an agent's
+ * Bash tool then calls it the way it calls any shell — `$SHELL -c "<line>"`. Reading
+ * argv as a command to spawn made that `spawn -c` and every command failed with ENOENT.
+ */
+declare const SHELL_MODE: {
+    /** `-c "<line>"`: the POSIX contract, and the only form an agent actually uses. */
+    readonly COMMAND: "command";
+    /** `-- cmd args`: how a person or a test drives the wrapper directly. */
+    readonly ARGV: "argv";
+    /** No command at all. Hand the terminal to the real shell rather than refuse it. */
+    readonly INTERACTIVE: "interactive";
+};
+type ShellMode = (typeof SHELL_MODE)[keyof typeof SHELL_MODE];
+interface ShellInvocation {
+    mode: ShellMode;
+    /** The line to gate and to hand on unchanged, for the `-c` form. */
+    line?: string;
+    /** The command to gate and to spawn, for the `--` form. */
+    argv?: string[];
+    /** Flags seen before `-c`, so the real shell is invoked as it was asked to be. */
+    flags: string[];
+}
+declare function shellInvocation(argv: readonly string[]): ShellInvocation;
+declare const REAL_SHELL_VAR = "MEMNOX_REAL_SHELL";
+/** The last shell that is not this one; `/bin/sh` exists on every machine this runs on. */
+declare const FALLBACK_SHELL = "/bin/sh";
+/**
+ * Never this binary. `memnox run` overwrites `SHELL`, so reading `SHELL` back here
+ * would make the wrapper exec itself for ever — the same shape as the interceptor
+ * fork bomb, and just as invisible until a terminal stops answering.
+ */
+declare function realShell(env: NodeJS.ProcessEnv, self: string): string;
+
+declare const GIT_CREDENTIAL_ACTION = "git.credential";
+interface GitCredentialOutcome {
+    /**
+     * What to write on stdout. Empty means "no opinion", and git asks the next helper;
+     * `quit=1` stops it asking anyone. A credential is never among the things it can say.
+     */
+    stdout: string;
+    message?: string;
+}
+interface GitCredentialSeamDeps {
+    authorizer: HookAuthorizer;
+    sessionId?: string;
+}
+/**
+ * Reads git's own key=value block, rules on the remote it names, and either stays
+ * silent or declines. It holds no secrets and can hand none out, which is the only
+ * shape of credential helper worth trusting inside a governance tool.
+ */
+declare class GitCredentialSeam {
+    private readonly deps;
+    constructor(deps: GitCredentialSeamDeps);
+    gate(input: string): Promise<GitCredentialOutcome>;
+}
+/** git writes one `key=value` per line, terminated by a blank line. */
+declare function parseGitInput(input: string): Record<string, string>;
+
+declare const EGRESS_REQUEST_ACTION = "http.request";
+/** A tunnel is a different question from a request: only the destination is knowable. */
+declare const EGRESS_CONNECT_ACTION = "http.connect";
+/**
+ * Declared, and the first one is the whole reason this seam is honest about itself.
+ * A governed agent with an unwatched side channel is worse than an ungoverned one.
+ */
+declare const EGRESS_BLIND_SPOTS: readonly string[];
+interface EgressOutcome {
+    allowed: boolean;
+    /** Returned to the client on a refusal, and logged either way. */
+    message?: string;
+}
+interface HttpAttempt {
+    method: string;
+    /** Absolute-form, as a forward proxy receives it. */
+    url: string;
+    headers?: Readonly<Record<string, string>>;
+    /** Read only for plain HTTP; a tunnelled body never reaches this seam. */
+    body?: string;
+}
+interface EgressSeamDeps {
+    authorizer: HookAuthorizer;
+    /**
+     * Somebody to ask. Absent means an ask does not go and says so, which is right for
+     * a test and wrong for a proxy an agent is reaching the network through.
+     */
+    hold?: HoldService;
+    sessionId?: string;
+}
+/**
+ * Destination and payload, both, where both are visible. An allowed host carrying a
+ * credential is still a refusal, and nothing is ever rewritten on the way through —
+ * modifying a payload and letting it pass is a bug the agent cannot see.
+ */
+declare class EgressSeam {
+    private readonly deps;
+    constructor(deps: EgressSeamDeps);
+    gateRequest(attempt: HttpAttempt): Promise<EgressOutcome>;
+    /**
+     * All that is knowable about a tunnel is where it goes. Ruling on the destination and
+     * saying plainly that the body is unseen beats pretending to inspect it.
+     */
+    gateConnect(authority: string): Promise<EgressOutcome>;
+    private rule;
+    /**
+     * Puts an ask to a person. Null when it was allowed and the request may go.
+     *
+     * Without this an `ask` rule refused the request outright and told the reader "you
+     * chose to be asked about this" while nobody had been asked — the rule's own words
+     * arguing with what had just happened to them.
+     */
+    private ask;
+}
+
+/** The directory that goes on the front of PATH. Every entry in it is this one binary. */
+declare const INTERCEPTOR_DIR = "bin";
+declare function interceptorDirFor(home: string): string;
+/**
+ * PATH with our directory removed, so the interceptor can find the binary it stands in front
+ * of. Without this the interceptor would exec itself, which is a fork bomb rather than a gate.
+ */
+declare function realPath(path: string, home: string): string;
+interface InterceptOutcome {
+    allowed: boolean;
+    /** What the interceptor should exec, once it is allowed to. */
+    binary: string;
+    args: string[];
+    action: string;
+    class: string;
+    target?: string;
+    /** Printed to stderr when the answer is no. Always names a way forward. */
+    message?: string;
+    /** Recorded against the decision. A digest, never the arguments. */
+    argsDigest: string;
+    /** What a person typed instead. The caller rules on it again; it is never trusted. */
+    edited?: string;
+    /** The rule's own reason, apart from the message a person reads. For the ledger. */
+    reason?: string;
+    /** The rule that decided, so `why` can name it rather than only quote it. */
+    rule?: {
+        name: string;
+        layer: string;
+        file: string;
+    };
+}
+interface InterceptDeps {
+    gate?: LocalGate;
+    /** Read for a database host only; nothing else here looks at the environment. */
+    env?: NodeJS.ProcessEnv;
+    hold?: HoldService;
+    /** What is in force, so the refusal can name the freeze rather than only the rule. */
+    overlays?: readonly Overlay[];
+    sessionId?: string;
+    agent?: string;
+    log: (message: string) => void;
+}
+/** Our own name. Nothing resolved to this may ever be exec'd — that is the fork bomb. */
+declare const INTERCEPT_BINARY = "memnox-intercept";
+/**
+ * The wrapper passes the binary it stands for as the first argument, so one executable
+ * serves every entry in the directory. Reading it from argv[1] instead would read our
+ * own path, classify us, and exec us again — which is a fork bomb, not a gate.
+ */
+declare function invokedFor(argv: readonly string[]): {
+    binary: string;
+    args: string[];
+} | null;
+/**
+ * Evaluate, then exec. Nothing here reads the file the command names or the output it
+ * produces: the interceptor sees argv and a verdict, and the real binary does the work.
+ */
+declare function ruleOnCommand(binary: string, args: readonly string[], deps: InterceptDeps): Promise<InterceptOutcome>;
+/** Where the real binary lives, found along PATH with our own directory removed. */
+declare function resolveReal(binary: string, path: string, exists: (p: string) => boolean): string | null;
+/** The one resolver in core, so every surface agrees on what a command line is. */
+declare function verdictFor(binary: string, args: readonly string[], env?: NodeJS.ProcessEnv): BinaryVerdict;
+
+interface InterceptorInstallReport {
+    directory: string;
+    installed: string[];
+    /** Known to the rules, absent from this machine. Named so the list is never a mystery. */
+    absent: string[];
+    /** What to add to PATH, printed rather than written into somebody's shell profile. */
+    pathLine: string;
+}
+interface InstallSeams {
+    path?: string;
+    exists?: (candidate: string) => boolean;
+}
+/**
+ * Only binaries this machine actually has. A shim for an absent `aws` would answer
+ * `command -v aws` and make every script that checks for it take the wrong branch —
+ * a governance tool that breaks a build is a governance tool somebody removes.
+ */
+declare function installInterceptors(home: string, interceptBinary: string, seams?: InstallSeams): Promise<InterceptorInstallReport>;
+/** Removes every interceptor and the directory, so a machine goes back exactly as it was. */
+declare function removeInterceptors(home: string): Promise<string[]>;
+
+/**
+ * Defence in depth. An interceptor is bypassed by anything that calls the real binary
+ * directly; a hook runs inside git itself, so a push that dodged PATH still meets a
+ * rule. Slower and narrower than the interceptor, which is why it is the second line.
+ */
+declare const HOOKS: readonly ["pre-push", "pre-commit"];
+type GitHook = (typeof HOOKS)[number];
+declare const HOOK_MARKER = "# installed by memnox";
+interface HookInstallReport {
+    installed: GitHook[];
+    /** Hooks somebody else wrote. Never overwritten; named so a person decides. */
+    skipped: {
+        hook: GitHook;
+        because: string;
+    }[];
+}
+/**
+ * Written with the path Memnox was actually run from, so the hook keeps working in a
+ * shell that has never heard of it — which is every shell, after `npx memnox`.
+ */
+declare function installGitHooks(repoDir: string, binary?: string): Promise<HookInstallReport>;
+/** Removes only hooks carrying our marker, so somebody else's survives. */
+declare function removeGitHooks(repoDir: string): Promise<GitHook[]>;
+
+/** Milliseconds. An interceptor runs on every command; a slow daemon must not be felt. */
+declare const DAEMON_TIMEOUT_MS = 250;
+interface AskOptions {
+    action: string;
+    target?: string;
+    sessionId?: string;
+    timeoutMs?: number;
+}
+interface ReportOptions {
+    action: string;
+    target?: string;
+    sessionId?: string;
+    /** How the command ended. The breaker's error and progress signals need this. */
+    exitCode?: number;
+    outOfScope?: boolean;
+    /** Reported, never estimated. Absent on every surface that cannot know it. */
+    costUsd?: number;
+    timeoutMs?: number;
+}
+/**
+ * Null on any failure at all — not running, too slow, garbled. The caller then
+ * evaluates in process, which is the same rules a little slower. A daemon that could
+ * fail open would be a gate that stops working when it is under load.
+ */
+declare function askDaemon(home: string, options: AskOptions): Promise<DaemonResponse | null>;
+/**
+ * What happened, after it happened.
+ *
+ * The breaker watches outcomes, so without this every one of its signals counts
+ * nothing: a request on its own cannot say whether the same command has now failed
+ * eleven times. Best effort, like everything else here — a daemon that is not running
+ * means the counters are not kept, not that the command is held up.
+ */
+declare function reportToDaemon(home: string, options: ReportOptions): Promise<DaemonResponse | null>;
+/** Whether this session is held. One connect, asked before anything runs. */
+declare function askStatus(home: string, sessionId: string, timeoutMs?: number): Promise<DaemonResponse | null>;
+
+/**
+ * A browser driver reaches sites the person is signed into, so the thing worth ruling
+ * on is the host — not the script, and not each navigation. One ask per host per
+ * session: asking on every page would train somebody to hold the key down, which is
+ * worse than not asking at all.
+ */
+declare const BROWSER_ACTION = "browser.navigate";
+interface BrowserGateDeps {
+    gate?: LocalGate;
+    hold?: HoldService;
+    hosts?: BrowserHosts;
+    sessionId?: string;
+    agent?: string;
+}
+interface BrowserOutcome {
+    allowed: boolean;
+    /** Null for a local target, which is nothing to rule on. */
+    host: string | null;
+    /** Set when this session had already answered for this host. */
+    remembered?: true;
+    message?: string;
+}
+declare class BrowserSeam {
+    private readonly deps;
+    private readonly hosts;
+    constructor(deps?: BrowserGateDeps);
+    navigate(url: string): Promise<BrowserOutcome>;
+}
+
+/**
+ * The row behind `why`, `timeline`, `trace`, `collisions` and every export. Without it
+ * the ledger has readers and no writer, and every one of those commands answers "nothing
+ * recorded yet" about a machine that has been governing commands all day.
+ */
+interface RecordInput {
+    outcome: InterceptOutcome;
+    effect: DecisionEffect;
+    reason: string;
+    at: string;
+    sessionId?: string;
+    agent?: string;
+    rule?: {
+        name: string;
+        layer: string;
+        file: string;
+        line?: number;
+    };
+    policyHash?: string;
+    bundleHash?: string;
+    conditionsInForce?: readonly string[];
+    exitCode?: number;
+    durationMs?: number;
+}
+declare function eventFor(input: RecordInput): MemnoxEvent;
+/**
+ * Best effort, and silent about failing. A ledger that cannot be written is a lost row;
+ * a ledger that stops the command is a tool somebody uninstalls. The gate has already
+ * decided by the time this runs, so nothing here can change the answer.
+ */
+declare function record(sink: EventSink | null, input: RecordInput): Promise<void>;
+
+/**
+ * The circuit breaker, in the seam rather than in a daemon.
+ *
+ * It lived only in the daemon, and no seam has ever spoken to the daemon on the hot
+ * path — so on an ordinary machine the breaker observed nothing and the loop it exists
+ * to stop ran until a person noticed the bill. Every seam already writes its outcome to
+ * the ledger, so this replays the session from there. No second process to install, no
+ * counter to keep, and it works in the default path rather than the optional one.
+ *
+ * Both halves are best effort. A ledger that will not open loses the breaker, never the
+ * command: a tool that stops somebody working because it could not read its own history
+ * is one they uninstall, and an uninstalled breaker stops nothing at all.
+ */
+interface BreakerSeamOptions {
+    home: string;
+    sessionId: string | undefined;
+    thresholds?: BreakerThresholds;
+}
+/** The pause holding this session, or null. Read before anything is allowed to run. */
+declare function pauseHolding(home: string, sessionId: string | undefined): Promise<SessionPause | null>;
+/** What a held session prints instead of running. Named so `resume` is discoverable. */
+declare function pauseMessage(pause: SessionPause): string;
+/**
+ * Replay what this session has done and hold it if the breaker trips.
+ *
+ * Called after the action, because the trip conditions need the outcome: "ran the same
+ * command eleven times" is only knowable once the eleventh has finished.
+ */
+declare function observeSession(options: BreakerSeamOptions): Promise<SessionPause | null>;
+
+/** stderr is the safe side channel — stdout belongs to whatever protocol is speaking. */
+declare const log: (message: string) => void;
+declare function buildAuthorizer(): Promise<HookAuthorizer>;
+declare function readStdin(): Promise<string>;
+interface SeamLeases {
+    gate: LeaseGate;
+    holder: LeaseHolder;
+    repositoryRoot: string;
+    isDirectory: (path: string) => boolean;
+}
+/**
+ * The register, when there is a repository to have one about.
+ *
+ * Undefined outside a checkout, and undefined is the right answer rather than a
+ * degraded one: a lease is repository-relative, and two machines cannot agree about a
+ * path that has no root. A single-agent laptop pays nothing for this either way — the
+ * register is only ever consulted for a write, and an empty one never refuses.
+ */
+declare function buildLeases(cwd?: string): SeamLeases | undefined;
+/**
+ * Somebody to ask.
+ *
+ * Every seam took an optional hold service and nothing ever built one, so an `ask`
+ * rule reached "nobody could be asked, so it was denied" — which made `ask` a synonym
+ * for `deny` and left no way to run an agent unattended at all.
+ *
+ * The question is written to `~/.memnox/pending` first and answered from wherever an
+ * answer turns up: this terminal when there is one, `memnox approve` in another, or
+ * the control plane reading the same directory.
+ */
+declare function buildHold(timeoutMs?: number): HoldService;
+
+export { type AskOptions, BROWSER_ACTION, type BreakerSeamOptions, type BrowserGateDeps, type BrowserOutcome, BrowserSeam, DAEMON_TIMEOUT_MS, DEFAULT_AGENT_NAME, EGRESS_ACTIONS, EGRESS_BLIND_SPOTS, EGRESS_CONNECT_ACTION, EGRESS_DEFAULT_PORT, EGRESS_MAX_BODY_BYTES, EGRESS_REQUEST_ACTION, ENV_AGENT_NAME, ENV_AGENT_ROLE, ENV_POLICIES, type EgressOutcome, EgressSeam, type EgressSeamDeps, FALLBACK_SHELL, GIT_CREDENTIAL_ACTION, type GitCredentialOutcome, GitCredentialSeam, type GitCredentialSeamDeps, type GitHook, HOOKS, HOOK_MARKER, HookAuthorizer, type HookAuthorizerDeps, type HookConfig, type HookInstallReport, type HookVerdict, type HttpAttempt, INTERCEPTOR_DIR, INTERCEPT_BINARY, type InstallSeams, type InterceptDeps, type InterceptOutcome, type InterceptorInstallReport, POLICY_PATH_SEPARATOR, REAL_SHELL_VAR, type RecordInput, type ReportOptions, SHELL_ACTION, SHELL_EXIT_OK, SHELL_EXIT_WITHHELD, SHELL_MODE, type ShellInvocation, type ShellMode, type ShellOutcome, ShellSeam, type ShellSeamDeps, askDaemon, askStatus, buildAuthorizer, buildHold, buildLeases, eventFor, installGitHooks, installInterceptors, interceptorDirFor, invokedFor, loadHookGate, log, observeSession, parseGitInput, pauseHolding, pauseMessage, readHookConfig, readStdin, realPath, realShell, record, removeGitHooks, removeInterceptors, reportToDaemon, resolveReal, ruleOnCommand, shellInvocation, verdictFor };