@haikeilabs/agentware 0.4.0 → 0.5.0

package/README.md

@@ -44,6 +44,50 @@ Keep channel ingress, identity verification, delegated credentials, and
 domain-specific authorization in the host application. Agentware is not a
 policy engine; a policy gate can wrap this same boundary later.
 
+## kei-proxy policy evaluator
+
+`KeiProxyEvaluator` runs `kei-proxy authorize` before each tool call and fails
+closed on anything other than an explicit `allow`/`permit` with exit 0.
+`evaluate` is asynchronous: the event loop keeps serving other requests while
+kei-proxy answers. Await the decision before running the tool.
+
+`KeiProxyAuthorizeClient` spawns the binary by absolute path (a bare name is
+resolved once against the parent `PATH`) with an allowlisted environment only:
+`KEI_RUNTIME_TOKEN`, `KEI_RUNTIME_CONTROL_PLANE_URL`, `KEI_RUNTIME_VERSION` and
+the other `AUTHORIZE_CHILD_ENV_ALLOWLIST` names. No `PATH`, no `HOME`, and the
+token never goes in argv. The child runs in its own process group, and a
+timeout SIGKILLs the whole group. Set `expectedSha256` to pin the binary: before
+every spawn it is opened with `O_NOFOLLOW` and re-hashed, and any drift denies
+with `kei-proxy pin_mismatch`.
+
+```typescript
+import { Action, KeiProxyAuthorizeClient, KeiProxyEvaluator } from "@haikeilabs/agentware";
+
+const evaluator = new KeiProxyEvaluator(
+  new KeiProxyAuthorizeClient({
+    executable: "/usr/local/bin/kei-proxy",
+    expectedSha256: process.env.KEI_PROXY_SHA256, // optional pin
+    timeoutMs: 10_000,
+  }),
+);
+
+const decision = await evaluator.evaluate(
+  "github.get_issue",
+  { owner: "acme", repo: "pipe" },
+  caller,
+);
+if (decision.enrollment) {
+  // deny + enrollment claim link: reply to the user privately; never log it.
+}
+if (decision.action !== Action.ALLOW) return;
+```
+
+Reasons read `kei-proxy <class>[: <detail>]` with a class from
+`KEI_PROXY_REASON_CLASSES`. Because `evaluate` returns a `Promise`, the
+evaluator is not a synchronous `PolicyEvaluator` and cannot be passed to
+`MiddlewareImpl.withPolicy`. The behaviour matches the Python and Go ports
+case for case; see `docs/kei-proxy-evaluator-parity.md`.
+
 ## Maintainer releases
 
 Releases are deliberately manual and use npm staged publishing. Do not run

package/dist/kei/authorizeClient.d.ts

@@ -0,0 +1,55 @@
+import { type KeiProxyAuthorizationClient, type KeiProxyAuthorizeRequest } from "./evaluator.js";
+/**
+ * Parent variables the kei-proxy child may inherit. PATH and HOME are
+ * deliberately absent, as are KEI_PROXY_* identity variables: identity
+ * travels as flags.
+ */
+export declare const AUTHORIZE_CHILD_ENV_ALLOWLIST: readonly ["TZ", "KEI_RUNTIME_TOKEN", "KEI_RUNTIME_CONTROL_PLANE_URL", "KEI_RUNTIME_VERSION", "KEI_API_URL", "KEI_PROXY_REGISTRY", "KEI_PROXY_AUDIT", "KEI_PROXY_AUDIT_MAX_BYTES", "KEI_PROXY_PROVIDER_USER", "KEI_CREDENTIAL_STORE_INSTALLATION_ID", "KEI_AWS_SECRETS_MANAGER_ENDPOINT"];
+export declare const DEFAULT_AUTHORIZE_TIMEOUT_MS = 10000;
+export interface KeiProxyAuthorizeClientOptions {
+    /**
+     * Path or name of the kei-proxy binary. Default `kei-proxy`. A bare name is
+     * resolved once against the parent PATH (`env.PATH`, else `process.env.PATH`);
+     * the child is always spawned by absolute path.
+     */
+    executable?: string;
+    /**
+     * Expected SHA-256 of the binary (64 hex digits). When set, `executable` must
+     * be an absolute, symlink-free path, and the binary is re-hashed before
+     * every spawn; a mismatch denies with `pin_mismatch`.
+     */
+    expectedSha256?: string;
+    /** Milliseconds to wait for one authorize call. Default 10s. */
+    timeoutMs?: number;
+    /** Parent environment to draw allowlisted variables from. Default `process.env`. */
+    env?: Readonly<Record<string, string | undefined>>;
+    /** Variables passed to the child verbatim, for settings outside the allowlist. */
+    extraEnv?: Readonly<Record<string, string>>;
+}
+/**
+ * Runs `kei-proxy authorize` once per call without blocking the event loop.
+ * The runtime token reaches the child only through its environment, never argv.
+ */
+export declare class KeiProxyAuthorizeClient implements KeiProxyAuthorizationClient {
+    /** Absolute path to spawn, or undefined when a bare name was not found. */
+    private readonly executable;
+    private readonly expectedDigest;
+    private readonly timeoutMs;
+    private readonly env?;
+    private readonly extraEnv;
+    constructor(options?: KeiProxyAuthorizeClientOptions);
+    /** The exact environment the kei-proxy child receives. */
+    childEnv(): Record<string, string>;
+    authorize(request: KeiProxyAuthorizeRequest): Promise<Record<string, unknown>>;
+    /** Spawn once in a new process group; resolve with stdout and exit code. */
+    private run;
+}
+/**
+ * The argv (after the executable) for one authorize call. `agentId` and
+ * `workspaceId` are not sent: kei-proxy (>= 0.1.11) resolves the agent from
+ * the runtime installation and workspace scope from the runtime token.
+ */
+export declare function keiProxyAuthorizeArgv(request: KeiProxyAuthorizeRequest): string[];
+/** Validate one authorize result against the exit-code contract. */
+export declare function parseKeiProxyAuthorizeOutput(stdout: string, exitCode: number): Record<string, unknown>;
+//# sourceMappingURL=authorizeClient.d.ts.map

package/dist/kei/authorizeClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorizeClient.d.ts","sourceRoot":"","sources":["../../src/kei/authorizeClient.ts"],"names":[],"mappings":"AAgCA,OAAO,EAGL,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC9B,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,0RAYhC,CAAC;AAEX,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAWnD,MAAM,WAAW,8BAA8B;IAC7C;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACnD,kFAAkF;IAClF,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C;AAED;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,2BAA2B;IACzE,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAA+C;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;gBAEhD,OAAO,GAAE,8BAAmC;IAoBxD,0DAA0D;IAC1D,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAU5B,SAAS,CACb,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAyBnC,4EAA4E;IAC5E,OAAO,CAAC,GAAG;CAgGZ;AAyFD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,wBAAwB,GAChC,MAAM,EAAE,CA6BV;AAED,oEAAoE;AACpE,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+CzB"}

package/dist/kei/authorizeClient.js

@@ -0,0 +1,349 @@
+/**
+ * `KeiProxyAuthorizeClient`: runs `kei-proxy authorize` for `KeiProxyEvaluator`.
+ *
+ * TypeScript port of `pedro_agentware.kei.authorize_client`. The kei-proxy
+ * contract (kei-connector-runtime `authorize.go`): stdout is one JSON object;
+ * exit 0 for allow / enrollment_required, exit 1 for deny, and exit 1 with
+ * nothing on stdout for every error.
+ *
+ * Security contract (`fixtures/kei/authorize-cases.v1.json`):
+ *
+ * - The child is spawned asynchronously, so the harness's event loop keeps
+ *   running while kei-proxy answers.
+ * - The child environment is exactly the allowlisted parent variables plus
+ *   explicit `extraEnv`: no PATH, no HOME. The executable is resolved to an
+ *   absolute path in the parent, once, at construction.
+ * - With `expectedSha256` the binary is re-proved before every spawn: the
+ *   path must equal its realpath, it is opened with O_NOFOLLOW, must be a
+ *   regular file, and its SHA-256 is streamed from that descriptor and compared
+ *   in constant time. Any drift denies (`pin_mismatch`) without spawning. What
+ *   remains is the hash-then-exec race; close it by making the binary's
+ *   directory and its ancestors writable only by the deploy owner.
+ * - The child runs in its own process group; a timeout or oversized stdout
+ *   SIGKILLs the whole group.
+ * - Proxy stdout can carry a credential or an enrollment claim link and stderr
+ *   is free-form, so stderr is never read and neither is ever logged or copied
+ *   into an error message.
+ */
+import { spawn } from "node:child_process";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { accessSync, constants as fsConstants, statSync } from "node:fs";
+import { open, realpath } from "node:fs/promises";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { KEI_PROXY_AFFIRMATIVE_DECISIONS, KeiProxyAuthorizeError, } from "./evaluator.js";
+/**
+ * Parent variables the kei-proxy child may inherit. PATH and HOME are
+ * deliberately absent, as are KEI_PROXY_* identity variables: identity
+ * travels as flags.
+ */
+export const AUTHORIZE_CHILD_ENV_ALLOWLIST = [
+    "TZ",
+    "KEI_RUNTIME_TOKEN",
+    "KEI_RUNTIME_CONTROL_PLANE_URL",
+    "KEI_RUNTIME_VERSION",
+    "KEI_API_URL",
+    "KEI_PROXY_REGISTRY",
+    "KEI_PROXY_AUDIT",
+    "KEI_PROXY_AUDIT_MAX_BYTES",
+    "KEI_PROXY_PROVIDER_USER",
+    "KEI_CREDENTIAL_STORE_INSTALLATION_ID",
+    "KEI_AWS_SECRETS_MANAGER_ENDPOINT",
+];
+export const DEFAULT_AUTHORIZE_TIMEOUT_MS = 10_000;
+/** Upper bound on captured stdout. */
+const MAX_STDOUT_BYTES = 1024 * 1024;
+/** Upper bound on the executable's size when digesting it. */
+const MAX_EXECUTABLE_BYTES = 256 * 1024 * 1024;
+const HASH_CHUNK_BYTES = 64 * 1024;
+const SHA256_HEX = /^[0-9a-fA-F]{64}$/;
+const RUNTIME_TOKEN_ENV = "KEI_RUNTIME_TOKEN";
+/**
+ * Runs `kei-proxy authorize` once per call without blocking the event loop.
+ * The runtime token reaches the child only through its environment, never argv.
+ */
+export class KeiProxyAuthorizeClient {
+    /** Absolute path to spawn, or undefined when a bare name was not found. */
+    executable;
+    expectedDigest;
+    timeoutMs;
+    env;
+    extraEnv;
+    constructor(options = {}) {
+        const executable = options.executable ?? "kei-proxy";
+        if (options.expectedSha256 !== undefined) {
+            if (!SHA256_HEX.test(options.expectedSha256)) {
+                throw new TypeError("expectedSha256 must be 64 hex digits");
+            }
+            if (!isAbsolute(executable)) {
+                throw new TypeError("a pinned executable must be an absolute path");
+            }
+            this.expectedDigest = Buffer.from(options.expectedSha256, "hex");
+        }
+        this.env = options.env;
+        this.executable = resolveExecutable(executable, (this.env ?? process.env).PATH);
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_AUTHORIZE_TIMEOUT_MS;
+        this.extraEnv = options.extraEnv ?? {};
+    }
+    /** The exact environment the kei-proxy child receives. */
+    childEnv() {
+        const source = this.env ?? process.env;
+        const out = {};
+        for (const key of AUTHORIZE_CHILD_ENV_ALLOWLIST) {
+            const value = source[key];
+            if (value !== undefined)
+                out[key] = value;
+        }
+        return { ...out, ...this.extraEnv };
+    }
+    async authorize(request) {
+        const env = this.childEnv();
+        if (!env[RUNTIME_TOKEN_ENV]) {
+            throw new KeiProxyAuthorizeError("missing_token", `${RUNTIME_TOKEN_ENV} is not set`);
+        }
+        if (this.executable === undefined) {
+            throw new KeiProxyAuthorizeError("proxy_unavailable", "kei-proxy was not found on PATH");
+        }
+        if (this.expectedDigest !== undefined) {
+            await proveExecutable(this.executable, this.expectedDigest);
+        }
+        const { stdout, exitCode } = await this.run(this.executable, keiProxyAuthorizeArgv(request), env);
+        return parseKeiProxyAuthorizeOutput(stdout, exitCode);
+    }
+    /** Spawn once in a new process group; resolve with stdout and exit code. */
+    run(executable, argv, env) {
+        return new Promise((resolvePromise, rejectPromise) => {
+            let child;
+            try {
+                child = spawn(executable, argv, {
+                    env,
+                    stdio: ["ignore", "pipe", "ignore"],
+                    detached: process.platform !== "win32",
+                    shell: false,
+                    windowsHide: true,
+                });
+            }
+            catch (err) {
+                rejectPromise(unavailable(err));
+                return;
+            }
+            let settled = false;
+            const chunks = [];
+            let total = 0;
+            const killGroup = () => {
+                const pid = child.pid;
+                if (pid === undefined)
+                    return;
+                try {
+                    process.kill(process.platform === "win32" ? pid : -pid, "SIGKILL");
+                }
+                catch {
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                        // Already gone.
+                    }
+                }
+            };
+            const fail = (error, kill) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (kill)
+                    killGroup();
+                rejectPromise(error);
+            };
+            const timer = setTimeout(() => {
+                fail(new KeiProxyAuthorizeError("proxy_timeout", `no answer within ${this.timeoutMs}ms`), true);
+            }, this.timeoutMs);
+            child.on("error", (err) => {
+                if (child.pid === undefined) {
+                    fail(unavailable(err), false);
+                }
+                else {
+                    fail(new KeiProxyAuthorizeError("proxy_error", "kei-proxy failed"), true);
+                }
+            });
+            child.stdout?.on("data", (chunk) => {
+                if (settled)
+                    return;
+                total += chunk.length;
+                if (total > MAX_STDOUT_BYTES) {
+                    fail(new KeiProxyAuthorizeError("malformed_response", "stdout exceeded the size limit"), true);
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            child.on("close", (code, signal) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (code === null) {
+                    rejectPromise(new KeiProxyAuthorizeError("proxy_error", `kei-proxy terminated by ${signal ?? "signal"}`));
+                    return;
+                }
+                resolvePromise({
+                    stdout: Buffer.concat(chunks).toString("utf8"),
+                    exitCode: code,
+                });
+            });
+        });
+    }
+}
+function unavailable(err) {
+    const code = err?.code;
+    return new KeiProxyAuthorizeError("proxy_unavailable", `could not start kei-proxy (${code ?? "error"})`);
+}
+/**
+ * An absolute path for `executable`. Names containing a separator resolve
+ * against the working directory; bare names are looked up in the absolute
+ * entries of `pathVar` (relative entries are skipped).
+ */
+function resolveExecutable(executable, pathVar) {
+    if (isAbsolute(executable))
+        return executable;
+    if (executable.includes("/") || executable.includes("\\")) {
+        return resolve(executable);
+    }
+    for (const dir of (pathVar ?? "").split(delimiter)) {
+        if (!dir || !isAbsolute(dir))
+            continue;
+        const candidate = join(dir, executable);
+        try {
+            if (!statSync(candidate).isFile())
+                continue;
+            accessSync(candidate, fsConstants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Not here; keep looking.
+        }
+    }
+    return undefined;
+}
+function pinMismatch(detail) {
+    return new KeiProxyAuthorizeError("pin_mismatch", detail);
+}
+/** Re-prove the pinned executable immediately before a spawn. */
+async function proveExecutable(path, expected) {
+    let real;
+    try {
+        real = await realpath(path);
+    }
+    catch {
+        throw pinMismatch("executable is missing");
+    }
+    if (real !== path)
+        throw pinMismatch("executable path is not canonical");
+    const noFollow = fsConstants.O_NOFOLLOW;
+    if (noFollow === undefined)
+        throw pinMismatch("O_NOFOLLOW is unavailable");
+    let handle;
+    try {
+        handle = await open(path, fsConstants.O_RDONLY | noFollow);
+    }
+    catch {
+        throw pinMismatch("executable could not be opened without following links");
+    }
+    let actual;
+    try {
+        if (!(await handle.stat()).isFile()) {
+            throw pinMismatch("executable is not a regular file");
+        }
+        actual = await digestOfHandle(handle);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+        throw pinMismatch("executable digest does not match the pin");
+    }
+}
+/** SHA-256 streamed off an already-open descriptor by explicit position. */
+async function digestOfHandle(handle) {
+    const hash = createHash("sha256");
+    const buffer = Buffer.allocUnsafe(HASH_CHUNK_BYTES);
+    let position = 0;
+    for (;;) {
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+        if (bytesRead === 0)
+            break;
+        position += bytesRead;
+        if (position > MAX_EXECUTABLE_BYTES) {
+            throw pinMismatch("executable exceeds the size limit");
+        }
+        hash.update(buffer.subarray(0, bytesRead));
+    }
+    return hash.digest();
+}
+/**
+ * The argv (after the executable) for one authorize call. `agentId` and
+ * `workspaceId` are not sent: kei-proxy (>= 0.1.11) resolves the agent from
+ * the runtime installation and workspace scope from the runtime token.
+ */
+export function keiProxyAuthorizeArgv(request) {
+    const argv = [
+        "authorize",
+        "--user",
+        request.userId,
+        "--tool",
+        request.tool,
+        "--action",
+        request.action,
+        "--resource",
+        request.resource,
+    ];
+    const optional = [
+        ["--span-id", request.spanId],
+        ["--invoking-subject", request.invokingSubject],
+        ["--parent-span", request.parentSpan],
+        [
+            "--delegation-depth",
+            request.delegationDepth > 0 ? String(request.delegationDepth) : "",
+        ],
+        ["--agent-version", request.agentVersion],
+        ["--framework", request.framework],
+        ["--tool-args-digest", request.toolArgsDigest],
+        ["--resources", request.resources.join(",")],
+    ];
+    for (const [flag, value] of optional) {
+        if (value)
+            argv.push(flag, value);
+    }
+    return argv;
+}
+/** Validate one authorize result against the exit-code contract. */
+export function parseKeiProxyAuthorizeOutput(stdout, exitCode) {
+    if (exitCode !== 0 && exitCode !== 1) {
+        throw new KeiProxyAuthorizeError("proxy_error", `kei-proxy exited ${exitCode}`);
+    }
+    const text = stdout.trim();
+    if (!text) {
+        if (exitCode !== 0) {
+            throw new KeiProxyAuthorizeError("proxy_error", `kei-proxy exited ${exitCode}`);
+        }
+        throw new KeiProxyAuthorizeError("empty_response", "kei-proxy printed nothing");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new KeiProxyAuthorizeError("malformed_response", "stdout is not JSON");
+    }
+    if (!isPlainObject(parsed)) {
+        throw new KeiProxyAuthorizeError("malformed_response", "stdout is not a JSON object");
+    }
+    const decision = parsed.decision;
+    if (exitCode !== 0 &&
+        typeof decision === "string" &&
+        KEI_PROXY_AFFIRMATIVE_DECISIONS.has(decision.trim().toLowerCase())) {
+        throw new KeiProxyAuthorizeError("exit_mismatch", `${decision} with exit ${exitCode}`);
+    }
+    return parsed;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/kei/evaluator.d.ts

@@ -0,0 +1,74 @@
+import { type CallerContext, type Decision } from "../middleware/types.js";
+/** kei-proxy's affirmative decisions. Everything else denies. */
+export declare const KEI_PROXY_AFFIRMATIVE_DECISIONS: ReadonlySet<string>;
+/** Every reason reads `kei-proxy <class>` or `kei-proxy <class>: <detail>`. */
+export declare const KEI_PROXY_REASON_CLASSES: readonly ["allow", "deny", "enrollment_required", "unknown_decision", "no_decision", "malformed_response", "empty_response", "proxy_error", "exit_mismatch", "proxy_unavailable", "proxy_timeout", "missing_token", "pin_mismatch"];
+export type KeiProxyReasonClass = (typeof KEI_PROXY_REASON_CLASSES)[number];
+/**
+ * An authorize call that produced no usable answer. The message is built by
+ * this library and never contains proxy stdout or stderr.
+ */
+export declare class KeiProxyAuthorizeError extends Error {
+    readonly reasonClass: KeiProxyReasonClass;
+    readonly detail: string;
+    constructor(reasonClass: KeiProxyReasonClass, detail: string);
+}
+/** The canonical audit context sent with one authorize call. */
+export interface KeiProxyAuthorizeRequest {
+    userId: string;
+    tool: string;
+    action: string;
+    resource: string;
+    spanId: string;
+    invokingSubject: string;
+    parentSpan: string;
+    delegationDepth: number;
+    agentId: string;
+    agentVersion: string;
+    framework: string;
+    toolArgsDigest: string;
+    resources: string[];
+    /** Accepted for parity; kei-proxy derives workspace scope from the runtime token. */
+    workspaceId: string;
+}
+/**
+ * The single call the evaluator needs. Return (or resolve to) the parsed
+ * authorize object; throw or reject with `KeiProxyAuthorizeError` (or
+ * anything) to deny.
+ */
+export interface KeiProxyAuthorizationClient {
+    authorize(request: KeiProxyAuthorizeRequest): unknown;
+}
+/**
+ * Derive `type:kind:id` resource identifiers from a tool call's arguments.
+ * Only resources named in the arguments are knowable before the call.
+ */
+export declare function keiProxyResourcesTouched(toolName: string, args: Record<string, unknown>): string[];
+/**
+ * SHA-256 of the args as compact, sorted-key, ASCII-escaped JSON: byte-for-byte
+ * Python's `json.dumps(args, sort_keys=True, separators=(",", ":"))` for
+ * strings, integers, booleans, null, arrays and objects.
+ */
+export declare function keiProxyToolArgsDigest(args: Record<string, unknown>): string;
+export type KeiProxyLogger = (level: "debug" | "warn", message: string) => void;
+export interface KeiProxyEvaluatorOptions {
+    /** Action verb sent when a tool call names none in `args.action`. Default `execute`. */
+    defaultAction?: string;
+    /** Receives class-level diagnostics only. Default: `console.warn` for warnings. */
+    logger?: KeiProxyLogger;
+}
+/**
+ * A policy evaluator over kei-proxy. Translates the proxy's decision into an
+ * agentware Decision and fails closed on every path that is not an explicit
+ * affirmative. See `docs/kei-proxy-evaluator-parity.md` for the table.
+ */
+export declare class KeiProxyEvaluator {
+    static readonly RULE = "kei-proxy";
+    private readonly client;
+    private readonly defaultAction;
+    private readonly logger;
+    constructor(client: KeiProxyAuthorizationClient, options?: KeiProxyEvaluatorOptions);
+    evaluate(toolName: string, args: Record<string, unknown>, caller: CallerContext): Promise<Decision>;
+    private decision;
+}
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/kei/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/kei/evaluator.ts"],"names":[],"mappings":"AAiBA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,QAAQ,EACd,MAAM,wBAAwB,CAAC;AAEhC,iEAAiE;AACjE,eAAO,MAAM,+BAA+B,EAAE,WAAW,CAAC,MAAM,CAG9D,CAAC;AAEH,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,qOAc3B,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,WAAW,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM;CAM7D;AAED,gEAAgE;AAChE,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,SAAS,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC;CACvD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,EAAE,CAoBV;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAE5E;AAwBD,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAEhF,MAAM,WAAW,wBAAwB;IACvC,wFAAwF;IACxF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAMD;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,MAAM,CAAC,QAAQ,CAAC,IAAI,eAAe;IAEnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;gBAGtC,MAAM,EAAE,2BAA2B,EACnC,OAAO,GAAE,wBAA6B;IAOlC,QAAQ,CACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,QAAQ,CAAC;IA2FpB,OAAO,CAAC,QAAQ;CAejB"}

package/dist/kei/evaluator.js

@@ -0,0 +1,222 @@
+/**
+ * Policy evaluation backed by `kei-proxy authorize`.
+ *
+ * TypeScript port of `pedro_agentware.kei.evaluator`. All three SDK languages
+ * are held to the parity table in `fixtures/kei/authorize-cases.v1.json`
+ * (see `docs/kei-proxy-evaluator-parity.md`): the same proxy output yields the
+ * same Decision, reason class and enrollment everywhere.
+ *
+ * Fail closed: only an explicit `allow`/`permit` with exit 0 allows. This
+ * module never spawns the proxy: `KeiProxyAuthorizeClient`
+ * (`authorizeClient.ts`) does, behind the `KeiProxyAuthorizationClient` seam.
+ *
+ * `evaluate` is asynchronous so a harness's event loop keeps running while
+ * kei-proxy answers. It therefore does not implement the synchronous
+ * `PolicyEvaluator`; await it before running the tool.
+ */
+import { createHash } from "node:crypto";
+import { Action, } from "../middleware/types.js";
+/** kei-proxy's affirmative decisions. Everything else denies. */
+export const KEI_PROXY_AFFIRMATIVE_DECISIONS = new Set([
+    "permit",
+    "allow",
+]);
+/** Every reason reads `kei-proxy <class>` or `kei-proxy <class>: <detail>`. */
+export const KEI_PROXY_REASON_CLASSES = [
+    "allow",
+    "deny",
+    "enrollment_required",
+    "unknown_decision",
+    "no_decision",
+    "malformed_response",
+    "empty_response",
+    "proxy_error",
+    "exit_mismatch",
+    "proxy_unavailable",
+    "proxy_timeout",
+    "missing_token",
+    "pin_mismatch",
+];
+/**
+ * An authorize call that produced no usable answer. The message is built by
+ * this library and never contains proxy stdout or stderr.
+ */
+export class KeiProxyAuthorizeError extends Error {
+    reasonClass;
+    detail;
+    constructor(reasonClass, detail) {
+        super(detail);
+        this.name = "KeiProxyAuthorizeError";
+        this.reasonClass = reasonClass;
+        this.detail = detail;
+    }
+}
+/**
+ * Derive `type:kind:id` resource identifiers from a tool call's arguments.
+ * Only resources named in the arguments are knowable before the call.
+ */
+export function keiProxyResourcesTouched(toolName, args) {
+    const resourceType = toolName.split(".", 1)[0].split("_", 1)[0].toLowerCase();
+    if (!resourceType)
+        return [];
+    const touched = [];
+    const add = (kind, identifier) => {
+        if (identifier === undefined || identifier === null)
+            return;
+        const value = String(identifier).trim();
+        if (!value)
+            return;
+        const entry = `${resourceType}:${kind}:${value}`;
+        if (!touched.includes(entry))
+            touched.push(entry);
+    };
+    const owner = args.owner;
+    const repo = args.repo || args.repository;
+    if (owner && repo)
+        add("repo", `${String(owner)}/${String(repo)}`);
+    else if (repo)
+        add("repo", repo);
+    add("issue", args.issue_number);
+    add("pull_request", args.pull_number || args.pr_number);
+    add("branch", args.branch || args.ref);
+    add("file", args.path || args.file_path);
+    return touched;
+}
+/**
+ * SHA-256 of the args as compact, sorted-key, ASCII-escaped JSON: byte-for-byte
+ * Python's `json.dumps(args, sort_keys=True, separators=(",", ":"))` for
+ * strings, integers, booleans, null, arrays and objects.
+ */
+export function keiProxyToolArgsDigest(args) {
+    return createHash("sha256").update(canonicalJson(args), "utf8").digest("hex");
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (isPlainObject(value)) {
+        const keys = Object.keys(value).sort();
+        return `{${keys.map((k) => `${asciiJson(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+    }
+    if (typeof value === "string")
+        return asciiJson(value);
+    if (value === undefined)
+        return "null";
+    return JSON.stringify(value) ?? "null";
+}
+function asciiJson(text) {
+    return JSON.stringify(text).replace(/[\u0080-\uffff]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const defaultLogger = (level, message) => {
+    if (level === "warn")
+        console.warn(message);
+};
+/**
+ * A policy evaluator over kei-proxy. Translates the proxy's decision into an
+ * agentware Decision and fails closed on every path that is not an explicit
+ * affirmative. See `docs/kei-proxy-evaluator-parity.md` for the table.
+ */
+export class KeiProxyEvaluator {
+    static RULE = "kei-proxy";
+    client;
+    defaultAction;
+    logger;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.defaultAction = options.defaultAction ?? "execute";
+        this.logger = options.logger ?? defaultLogger;
+    }
+    async evaluate(toolName, args, caller) {
+        const resources = keiProxyResourcesTouched(toolName, args);
+        const userId = caller.invoking_subject || caller.user_id || "";
+        const meta = caller.metadata ?? {};
+        const request = {
+            userId,
+            tool: toolName,
+            action: String(args.action || this.defaultAction),
+            resource: resources[0] ?? toolName,
+            spanId: meta.span_id ?? "",
+            invokingSubject: userId,
+            parentSpan: caller.parent_span ?? "",
+            delegationDepth: caller.delegation_depth ?? 0,
+            agentId: meta.agent_id ?? "",
+            agentVersion: meta.agent_version ?? "",
+            framework: meta.framework || caller.source || "",
+            toolArgsDigest: keiProxyToolArgsDigest(args),
+            resources,
+            workspaceId: meta.workspace_id ?? "",
+        };
+        let raw;
+        try {
+            raw = await this.client.authorize(request);
+        }
+        catch (err) {
+            if (err instanceof KeiProxyAuthorizeError) {
+                this.logger("warn", `kei-proxy authorize for ${toolName} denied: ${err.reasonClass}`);
+                return this.decision(Action.DENY, reason(err.reasonClass, err.detail));
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            this.logger("warn", `kei-proxy authorize failed for ${toolName}, denying: ${message}`);
+            return this.decision(Action.DENY, reason("proxy_error", `authorize failed: ${message}`));
+        }
+        const response = isPlainObject(raw) ? raw : {};
+        const rawDecision = response.decision;
+        const decision = rawDecision === undefined || rawDecision === null
+            ? ""
+            : String(rawDecision).trim().toLowerCase();
+        const proxyReason = optionalString(response.reason);
+        const policyId = optionalString(response.policy_id) ?? optionalString(response.policy);
+        if (KEI_PROXY_AFFIRMATIVE_DECISIONS.has(decision)) {
+            return this.decision(Action.ALLOW, reason("allow", proxyReason), policyId);
+        }
+        let reasonClass;
+        let detail;
+        let enrollment;
+        const carried = isPlainObject(response.enrollment)
+            ? response.enrollment
+            : undefined;
+        if (!decision) {
+            reasonClass = "no_decision";
+        }
+        else if (decision === "deny") {
+            reasonClass = "deny";
+            detail = proxyReason;
+            enrollment = carried;
+        }
+        else if (decision === "enrollment_required") {
+            reasonClass = "enrollment_required";
+            detail = proxyReason ?? "enrollment is required before this call";
+            enrollment = carried;
+        }
+        else {
+            reasonClass = "unknown_decision";
+            detail = `'${decision}'` + (proxyReason ? ` (${proxyReason})` : "");
+        }
+        this.logger("debug", `kei-proxy ${reasonClass} for ${toolName}`);
+        return this.decision(Action.DENY, reason(reasonClass, detail), policyId, enrollment);
+    }
+    decision(action, reasonText, policyId, enrollment) {
+        const out = {
+            action,
+            rule: policyId ?? KeiProxyEvaluator.RULE,
+            reason: reasonText,
+            timestamp: new Date(),
+        };
+        if (enrollment !== undefined)
+            out.enrollment = enrollment;
+        return out;
+    }
+}
+function reason(reasonClass, detail) {
+    return detail
+        ? `kei-proxy ${reasonClass}: ${detail}`
+        : `kei-proxy ${reasonClass}`;
+}
+function optionalString(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = String(value);
+    return text ? text : undefined;
+}

package/dist/kei/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./runtimeLink.js";
 export * from "./runtimeLinkRuntime.js";
+export * from "./evaluator.js";
+export * from "./authorizeClient.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/kei/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/kei/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/kei/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC"}

package/dist/kei/index.js

@@ -1,2 +1,4 @@
 export * from "./runtimeLink.js";
 export * from "./runtimeLinkRuntime.js";
+export * from "./evaluator.js";
+export * from "./authorizeClient.js";

package/dist/middleware/types.d.ts

@@ -29,12 +29,24 @@ export interface CallerContext {
     source?: string;
     trusted: boolean;
     metadata?: Record<string, string>;
+    /** The human who originated the request; carried unchanged across delegation hops. */
+    invoking_subject?: string;
+    /** Span of the delegating caller, when this call was made by a subagent. */
+    parent_span?: string;
+    /** 0 for a direct call; incremented at each delegation hop. */
+    delegation_depth?: number;
 }
 export interface Decision {
     action: Action;
     rule: string;
     reason: string;
     redacted_args?: Record<string, unknown>;
+    /**
+     * Opaque enrollment object from kei-proxy on a DENY (provider,
+     * provider_user_id, org_id, workspace_id, and optionally url/expires_at).
+     * The url is a one-time claim link: surface it to the user, never log it.
+     */
+    enrollment?: Record<string, unknown>;
     timestamp: Date;
 }
 export declare function createAllowDecision(reason?: string): Decision;

package/dist/middleware/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":"AAAA,oBAAY,WAAW;IACrB,aAAa,kBAAkB;IAC/B,UAAU,eAAe;IACzB,SAAS,cAAc;IACvB,WAAW,gBAAgB;IAC3B,SAAS,cAAc;IACvB,aAAa,kBAAkB;IAC/B,UAAU,eAAe;IACzB,kBAAkB,uBAAuB;IACzC,WAAW,gBAAgB;IAC3B,eAAe,oBAAoB;IACnC,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,WAAW,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,oBAAY,MAAM;IAChB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,SAAY,GAAG,QAAQ,CAOhE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAO3D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":"AAAA,oBAAY,WAAW;IACrB,aAAa,kBAAkB;IAC/B,UAAU,eAAe;IACzB,SAAS,cAAc;IACvB,WAAW,gBAAgB;IAC3B,SAAS,cAAc;IACvB,aAAa,kBAAkB;IAC/B,UAAU,eAAe;IACzB,kBAAkB,uBAAuB;IACzC,WAAW,gBAAgB;IAC3B,eAAe,oBAAoB;IACnC,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,WAAW,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,oBAAY,MAAM;IAChB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,SAAY,GAAG,QAAQ,CAOhE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAO3D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haikeilabs/agentware",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Agent middleware and tooling for LLM tool calling",
   "repository": {
     "type": "git",