@keemakr/agent-sdk 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @keemakr/agent-sdk
+
+The floor for **keemakr marketplace agents** — separately deployed eve agents that the keemakr operator delegates to. The SDK gives your agent a stable, secure contract to:
+
+- **verify** the operator's capability grant on every inbound delegation, and
+- **reach tenant connections** (and, in later versions, memory and shared tools) through keemakr-core — **without holding raw secrets** and **without resolving the tenant yourself**.
+
+The tenant identity and scopes come from a short-lived signed grant the operator mints per delegation; keemakr-core re-verifies the grant and enforces scope on every capability call. Connection credentials never leave keemakr-core on the default (proxy) path.
+
+## Install
+
+```bash
+npm install @keemakr/agent-sdk
+```
+
+Peer dependencies (match your eve agent): `eve@0.13.0`, `jose@^6.2.3`.
+
+## Configure
+
+Set these in your deployed agent's environment:
+
+| Variable | Purpose |
+|---|---|
+| `KEE_CORE_JWKS_URL` | keemakr-core's JWKS endpoint, e.g. `https://app.keemakr.com/.well-known/jwks.json`. Enables grant verification. |
+| `KEE_AGENT_AUDIENCE` | This deployment's audience — your runtime URL's origin, e.g. `https://my-agent.example.com`. Must match the audience the operator mints. |
+| `KEE_CORE_URL` | keemakr-core's base URL for capability calls, e.g. `https://app.keemakr.com`. (Derived from `KEE_CORE_JWKS_URL` if unset.) |
+
+If `KEE_CORE_JWKS_URL` is unset, `grantAuth()` skips entirely — useful during local development.
+
+## 1. Verify the grant in your channel
+
+`grantAuth()` returns an eve `AuthFn`. Put it ahead of any fallback:
+
+```ts title="agent/channels/eve.ts"
+import { localDev, vercelOidc } from "eve/channels/auth";
+import { eveChannel } from "eve/channels/eve";
+import { grantAuth } from "@keemakr/agent-sdk";
+
+export default eveChannel({
+  auth: [localDev(), vercelOidc(), grantAuth()],
+});
+```
+
+On success the verified tenant id and scopes are attached to the session auth context, where `useKee` reads them.
+
+## 2. Reach tenant data from a tool
+
+```ts title="agent/tools/find_email.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { useKee } from "@keemakr/agent-sdk";
+
+export default defineTool({
+  description: "Find a lead's work email.",
+  inputSchema: z.object({
+    domain: z.string(),
+    first_name: z.string(),
+    last_name: z.string(),
+  }),
+  async execute(args, ctx) {
+    const kee = useKee(ctx);
+    // Proxy path: the credential stays in keemakr-core; you get the result.
+    const result = await kee.connections.hunter.call("email-finder", args);
+    return result; // { email, score, status }
+  },
+});
+```
+
+### Connections API
+
+```ts
+const kee = useKee(ctx);
+kee.tenantId;            // the tenant this delegation is for (from the grant)
+kee.scopes;              // the scopes the grant carries
+
+// Proxy (default): run a named operation; the secret never leaves core.
+await kee.connections.hunter.call("email-finder", { domain, first_name, last_name });
+await kee.connections.get("hunter").call("email-finder", { ... }); // equivalent
+
+// Token (opt-in): only if your entry.json declared `access: "token"` on the
+// dependency. Returns a short-lived credential you may use directly.
+const { access_token } = await kee.connections.hunter.token();
+```
+
+A call whose grant lacks the required scope returns a `KeeError` with `status: 403`; an expired/invalid grant returns `status: 401`.
+
+## Security model
+
+- **Tenant always comes from the verified grant**, resolved server-side. Never pass a tenant id from tool input.
+- **On the proxy path, credentials never leave keemakr-core.** You send operation args; core runs the third-party request with the tenant's credential and returns only the result.
+- **The token path is opt-in and scope-gated** (`conn:<provider>:token`), declared per dependency in your `entry.json` (`"access": "token"`).
+- Every capability call re-verifies the grant and enforces scope on the server.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,35 @@
+export interface KeeError extends Error {
+    status?: number;
+}
+export interface KeeContext {
+    session?: {
+        auth?: {
+            current?: {
+                attributes?: Record<string, string | readonly string[] | undefined> | null;
+            } | null;
+        } | null;
+    } | null;
+}
+/** Per-provider connection surface. */
+export interface KeeConnection {
+    /** Run a named proxy operation. The credential stays in core. */
+    call(op: string, args?: Record<string, unknown>): Promise<unknown>;
+    /** Request a short-lived scoped token (opt-in; requires the conn:<p>:token scope). */
+    token(): Promise<{
+        access_token: string;
+        account_label: string | null;
+    }>;
+}
+export interface Kee {
+    tenantId: string;
+    scopes: string[];
+    connections: Record<string, KeeConnection> & {
+        /** Explicit accessor (equivalent to kee.connections[provider]). */
+        get(provider: string): KeeConnection;
+    };
+}
+/**
+ * Build a tenant-scoped capability client from a tool's context. Call inside a
+ * tool's execute: `const kee = useKee(ctx)`.
+ */
+export declare function useKee(ctx: KeeContext): Kee;

package/dist/client.js

@@ -0,0 +1,78 @@
+// useKee(ctx) — the tenant-scoped capability client a marketplace agent's tools
+// use to reach tenant data through keemakr-core. It reads the verified grant off
+// the session auth context (put there by grantAuth) and calls back into core's
+// /api/capability/* endpoints, forwarding the grant. Core re-verifies the grant
+// and enforces scope on every call; the SDK never sees a raw credential on the
+// proxy path.
+function keeError(message, status) {
+    const e = new Error(message);
+    e.name = 'KeeError';
+    e.status = status;
+    return e;
+}
+function readGrant(ctx) {
+    const attrs = ctx?.session?.auth?.current?.attributes ?? {};
+    const token = typeof attrs.grant_token === 'string' ? attrs.grant_token : undefined;
+    const tenantId = typeof attrs.tenant_id === 'string' ? attrs.tenant_id : undefined;
+    const scopes = Array.isArray(attrs.scopes) ? [...attrs.scopes] : [];
+    const traceId = typeof attrs.trace_id === 'string' ? attrs.trace_id : undefined;
+    if (!token || !tenantId) {
+        throw keeError('no capability grant on the session — was the request authenticated with grantAuth()?', 401);
+    }
+    return { token, tenantId, scopes, traceId };
+}
+// Resolve core's base URL. Prefer KEE_CORE_URL; otherwise derive it from the
+// JWKS URL by stripping the well-known path.
+function coreBaseUrl() {
+    const explicit = process.env.KEE_CORE_URL;
+    if (explicit)
+        return explicit.replace(/\/$/, '');
+    const jwks = process.env.KEE_CORE_JWKS_URL;
+    if (jwks)
+        return jwks.replace(/\/\.well-known\/jwks\.json\/?$/, '');
+    throw keeError('KEE_CORE_URL (or KEE_CORE_JWKS_URL) must be set to reach the Capability API');
+}
+async function capabilityFetch(grant, path, body) {
+    const url = `${coreBaseUrl()}/api/capability/${path}`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            authorization: `Bearer ${grant.token}`,
+            ...(grant.traceId ? { 'x-keemakr-trace-id': grant.traceId } : {}),
+        },
+        body: JSON.stringify(body ?? {}),
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        throw keeError(json.error ?? `capability request failed (${res.status})`, res.status);
+    }
+    return json;
+}
+/**
+ * Build a tenant-scoped capability client from a tool's context. Call inside a
+ * tool's execute: `const kee = useKee(ctx)`.
+ */
+export function useKee(ctx) {
+    const grant = readGrant(ctx);
+    const connectionFor = (provider) => ({
+        async call(op, args) {
+            const json = (await capabilityFetch(grant, `conn/${provider}/${op}`, {
+                args: args ?? {},
+            }));
+            return json.result;
+        },
+        async token() {
+            const json = (await capabilityFetch(grant, `conn/${provider}/token`, {}));
+            return { access_token: json.access_token, account_label: json.account_label };
+        },
+    });
+    const connections = new Proxy({ get: connectionFor }, {
+        get(target, prop) {
+            if (prop === 'get')
+                return connectionFor;
+            return connectionFor(prop);
+        },
+    });
+    return { tenantId: grant.tenantId, scopes: grant.scopes, connections };
+}

package/dist/grant-auth.d.ts

@@ -0,0 +1,19 @@
+import { type AuthFn } from 'eve/channels/auth';
+/**
+ * An eve AuthFn that accepts a keemakr capability grant. Returns a principal
+ * carrying `tenant_id`, `scopes`, and the raw `grant_token` in attributes on
+ * success, or `null` to skip to the next auth entry (so it composes before any
+ * fallback).
+ *
+ * Environment:
+ *   KEE_CORE_JWKS_URL   keemakr-core's JWKS endpoint
+ *                       (e.g. https://app.keemakr.com/.well-known/jwks.json).
+ *                       If unset, this AuthFn skips entirely (grant path off).
+ *   KEE_AGENT_AUDIENCE  this deployment's audience — the runtime URL's origin —
+ *                       matching the `aud` the operator mints. If unset, the
+ *                       audience check is skipped (dev convenience only).
+ */
+export declare function grantAuth(opts?: {
+    jwksUrl?: string;
+    audience?: string;
+}): AuthFn<Request>;

package/dist/grant-auth.js

@@ -0,0 +1,74 @@
+// Capability-grant verification for a remote keemakr agent.
+//
+// The keemakr operator attaches a short-lived signed JWT — a "capability grant" —
+// on every delegation. It carries a VERIFIABLE tenant id + scopes (+ a trace id),
+// signed with keemakr-core's RS256 key and verifiable against the JWKS it
+// publishes at /.well-known/jwks.json.
+//
+// grantAuth() returns an eve AuthFn that verifies the grant against core's JWKS
+// and surfaces the tenant + scopes (and the raw grant, for useKee to forward) on
+// the session auth context. Use it as the PRIMARY inbound auth in your channel.
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { extractBearerToken } from 'eve/channels/auth';
+// The issuer keemakr-core mints grants with.
+const GRANT_ISSUER = 'keemakr';
+let jwks = null;
+function jwksFor(url) {
+    if (!jwks)
+        jwks = createRemoteJWKSet(new URL(url));
+    return jwks;
+}
+/**
+ * An eve AuthFn that accepts a keemakr capability grant. Returns a principal
+ * carrying `tenant_id`, `scopes`, and the raw `grant_token` in attributes on
+ * success, or `null` to skip to the next auth entry (so it composes before any
+ * fallback).
+ *
+ * Environment:
+ *   KEE_CORE_JWKS_URL   keemakr-core's JWKS endpoint
+ *                       (e.g. https://app.keemakr.com/.well-known/jwks.json).
+ *                       If unset, this AuthFn skips entirely (grant path off).
+ *   KEE_AGENT_AUDIENCE  this deployment's audience — the runtime URL's origin —
+ *                       matching the `aud` the operator mints. If unset, the
+ *                       audience check is skipped (dev convenience only).
+ */
+export function grantAuth(opts) {
+    return async (request) => {
+        const jwksUrl = opts?.jwksUrl ?? process.env.KEE_CORE_JWKS_URL;
+        if (!jwksUrl)
+            return null;
+        const token = extractBearerToken(request.headers.get('authorization'));
+        if (!token)
+            return null;
+        const expectedAud = opts?.audience ?? process.env.KEE_AGENT_AUDIENCE;
+        try {
+            const { payload } = await jwtVerify(token, jwksFor(jwksUrl), {
+                issuer: GRANT_ISSUER,
+                ...(expectedAud ? { audience: expectedAud } : {}),
+            });
+            const tenantId = payload.tenant_id;
+            const scopes = payload.scopes;
+            const installedAgent = payload.installed_agent;
+            const traceId = payload.trace_id;
+            if (typeof tenantId !== 'string' || !Array.isArray(scopes))
+                return null;
+            return {
+                authenticator: 'keemakr-grant',
+                issuer: GRANT_ISSUER,
+                principalId: typeof installedAgent === 'string' ? installedAgent : 'keemakr-agent',
+                principalType: 'service',
+                subject: typeof payload.sub === 'string' ? payload.sub : undefined,
+                attributes: {
+                    via: 'grant',
+                    tenant_id: tenantId,
+                    scopes: scopes.map(String),
+                    grant_token: token,
+                    ...(typeof traceId === 'string' ? { trace_id: traceId } : {}),
+                },
+            };
+        }
+        catch {
+            return null;
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { grantAuth } from './grant-auth.js';
+export { useKee, type Kee, type KeeConnection, type KeeContext, type KeeError } from './client.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+// @keemakr/agent-sdk — the floor for keemakr marketplace agents.
+//
+// Inbound: verify the operator's capability grant in your channel.
+//   import { grantAuth } from '@keemakr/agent-sdk';
+//   export default eveChannel({ auth: [localDev(), grantAuth()] });
+//
+// Inside a tool: reach tenant data through keemakr-core, without holding secrets.
+//   import { useKee } from '@keemakr/agent-sdk';
+//   const kee = useKee(ctx);
+//   const r = await kee.connections.hunter.call('email-finder', { domain, first_name, last_name });
+export { grantAuth } from './grant-auth.js';
+export { useKee } from './client.js';

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@keemakr/agent-sdk",
+  "version": "0.1.0",
+  "description": "The floor for keemakr marketplace agents: verify the capability grant and reach tenant connections (and, soon, memory and shared tools) through keemakr-core — without holding raw secrets or resolving the tenant yourself.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fsztpartners/keemakr-agent-sdk.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "eve": "0.13.0",
+    "jose": "^6.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "eve": "0.13.0",
+    "jose": "^6.2.3",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=20.9"
+  }
+}