@keemakr/agent-sdk 0.4.0 → 0.6.0

package/README.md

@@ -82,6 +82,28 @@ await kee.connections.get("hunter").call("email-finder", { ... }); // equivalent
 const { access_token } = await kee.connections.hunter.token();
 ```
 
+### Discover connectors + operations
+
+`@keemakr/agent-sdk/connectors` ships a generated, typed manifest of every connector keemakr-core exposes — provider slugs, `maturity`, and each operation's name + JSON-Schema arg contract. Use it to discover what's callable (and get autocomplete on provider + op names) **without** scanning a core checkout or hitting a running instance. It's **metadata only** — no credentials.
+
+```ts
+import { connectors, opNames, isReady } from "@keemakr/agent-sdk/connectors";
+
+opNames("hunter");                                  // → ["email-finder"]
+connectors.hunter.ops["email-finder"].inputSchema;  // JSON Schema for the args
+isReady("meta");                                     // false while a connector is coming_soon
+connectors.meta.maturity;                            // "coming_soon" | "ready"
+```
+
+A `coming_soon` connector is declarable in your `entry.json` `dependencies` today; its operations start callable (and `isReady` flips to `true`) once core ships them — **no change to your agent**.
+
+**Refresh the manifest** after core ships new connectors/operations (it's a committed snapshot of `GET /api/connections/catalog`):
+
+```bash
+curl -s "$KEE_CORE_URL/api/connections/catalog" > src/connectors.snapshot.json
+npm run gen:connectors    # or: npm run build (runs gen first)
+```
+
 ### Memory (cross-session, tenant-shared)
 
 ```ts
@@ -103,13 +125,29 @@ await kee.tools.run("current-time");    // run one in keemakr-core
 
 A call whose grant lacks the required scope returns a `KeeError` with `status: 403`; an expired/invalid grant returns `status: 401`.
 
-## Security model
+## Autonomous / scheduled runs
+
+A cron/scheduled turn has no operator session, so it gets no session grant. keemakr-core can mint a **machine grant** for it (gated on the tenant's per-install `unattended_consent`). If your remote runs **outside** an eve channel, verify that grant directly:
 
-- **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"`).
+```ts
+import { verifyGrant } from "@keemakr/agent-sdk";
+
+const claims = await verifyGrant(grantToken, { audience: process.env.KEE_AGENT_AUDIENCE });
+if (!claims) throw new Error("invalid or expired grant");
+// claims.tenantId, claims.scopes, claims.aud, claims.exp
+```
+
+Inside an eve channel, `grantAuth()` already accepts machine grants (same token shape) — no extra work.
+
+## Credential & model contract
+
+- **Tenant/service credentials live in keemakr-core**, reached only via the proxy — the credential never crosses the wire. Tenant is always the verified grant, resolved server-side; never pass a tenant id from tool input.
+- **The token path is opt-in and scope-gated** (`conn:<provider>:token`), declared per dependency in `entry.json` (`"access": "token"`).
+- **You MAY hold your own model key.** There is no platform model gateway today, so an agent routing its own LLM calls (its own Anthropic/AI-Gateway key) is expected and fine — that is *not* a credential leak. A leak is a *tenant/service* credential read in agent code.
 - Every capability call re-verifies the grant and enforces scope on the server.
 
+Full contract: keemakr-core `docs/CONNECTOR-CONTRACT.md`.
+
 ## License
 
 MIT

package/dist/connectors.d.ts

@@ -0,0 +1,8 @@
+export { connectors, type ConnectorName, type ConnectorInfo, type ConnectorOp, type ConnectorOps, } from './connectors.generated.js';
+import { type ConnectorName } from './connectors.generated.js';
+/** All provider slugs in the manifest. */
+export declare function providerNames(): ConnectorName[];
+/** The operation names a provider exposes (empty for a coming_soon stub). */
+export declare function opNames(provider: ConnectorName): string[];
+/** True when the provider's connect path is proven and its operations are callable. */
+export declare function isReady(provider: ConnectorName): boolean;

package/dist/connectors.generated.d.ts

@@ -0,0 +1,276 @@
+export type ConnectorName = "agent-sessions" | "apify" | "apollo" | "cal-com" | "calendly" | "clearbit" | "drip" | "elevenlabs" | "facebook" | "fal" | "hubspot" | "hunter" | "instagram" | "instantly" | "mailchimp" | "meta" | "pagespeed" | "posthog" | "salesforce" | "sendgrid" | "slack" | "stripe" | "twilio" | "whatsapp" | "wordpress";
+/** Per-provider operation names (autocomplete for `.call(op)`). */
+export interface ConnectorOps {
+    "agent-sessions": never;
+    "apify": never;
+    "apollo": never;
+    "cal-com": never;
+    "calendly": never;
+    "clearbit": never;
+    "drip": never;
+    "elevenlabs": never;
+    "facebook": never;
+    "fal": never;
+    "hubspot": never;
+    "hunter": "email-finder";
+    "instagram": never;
+    "instantly": never;
+    "mailchimp": never;
+    "meta": never;
+    "pagespeed": never;
+    "posthog": never;
+    "salesforce": never;
+    "sendgrid": never;
+    "slack": never;
+    "stripe": never;
+    "twilio": never;
+    "whatsapp": never;
+    "wordpress": never;
+}
+export interface ConnectorOp {
+    description: string | null;
+    /** JSON Schema (draft 2020-12) for the operation's arguments. */
+    inputSchema: unknown;
+}
+export interface ConnectorInfo {
+    displayName: string;
+    authKind: string;
+    category: string | null;
+    /** 'ready' → connectable + operations callable; 'coming_soon' → declared, ops not yet wired. */
+    maturity: string;
+    docUrl: string | null;
+    ops: Record<string, ConnectorOp>;
+}
+/**
+ * The connector catalog as of the last snapshot refresh. Metadata only — no
+ * credentials. Keyed by provider slug; each entry lists its callable operations
+ * and their JSON-Schema arg contracts.
+ */
+export declare const connectors: {
+    readonly "agent-sessions": {
+        readonly displayName: "Agent Session Feed";
+        readonly authKind: "api_key";
+        readonly category: "voice";
+        readonly maturity: "ready";
+        readonly docUrl: null;
+        readonly ops: {};
+    };
+    readonly apify: {
+        readonly displayName: "Apify";
+        readonly authKind: "api_key";
+        readonly category: "scraping";
+        readonly maturity: "ready";
+        readonly docUrl: "https://docs.apify.com/api/v2";
+        readonly ops: {};
+    };
+    readonly apollo: {
+        readonly displayName: "Apollo.io";
+        readonly authKind: "api_key";
+        readonly category: "sales-intelligence";
+        readonly maturity: "ready";
+        readonly docUrl: "https://docs.apollo.io/reference/introduction";
+        readonly ops: {};
+    };
+    readonly "cal-com": {
+        readonly displayName: "Cal.com";
+        readonly authKind: "api_key";
+        readonly category: "scheduling";
+        readonly maturity: "ready";
+        readonly docUrl: "https://cal.com/docs/api-reference";
+        readonly ops: {};
+    };
+    readonly calendly: {
+        readonly displayName: "Calendly";
+        readonly authKind: "api_key";
+        readonly category: "scheduling";
+        readonly maturity: "coming_soon";
+        readonly docUrl: "https://developer.calendly.com/api-docs";
+        readonly ops: {};
+    };
+    readonly clearbit: {
+        readonly displayName: "Clearbit";
+        readonly authKind: "api_key";
+        readonly category: "sales-intelligence";
+        readonly maturity: "ready";
+        readonly docUrl: "https://dashboard.clearbit.com/docs";
+        readonly ops: {};
+    };
+    readonly drip: {
+        readonly displayName: "Drip";
+        readonly authKind: "api_key";
+        readonly category: "email";
+        readonly maturity: "ready";
+        readonly docUrl: "https://developer.drip.com/";
+        readonly ops: {};
+    };
+    readonly elevenlabs: {
+        readonly displayName: "ElevenLabs";
+        readonly authKind: "api_key";
+        readonly category: "voice";
+        readonly maturity: "ready";
+        readonly docUrl: "https://elevenlabs.io/docs/api-reference";
+        readonly ops: {};
+    };
+    readonly facebook: {
+        readonly displayName: "Facebook";
+        readonly authKind: "oauth2";
+        readonly category: "channel";
+        readonly maturity: "ready";
+        readonly docUrl: "https://developers.facebook.com/docs/pages-api";
+        readonly ops: {};
+    };
+    readonly fal: {
+        readonly displayName: "fal.ai";
+        readonly authKind: "api_key";
+        readonly category: "media";
+        readonly maturity: "coming_soon";
+        readonly docUrl: "https://fal.ai/docs";
+        readonly ops: {};
+    };
+    readonly hubspot: {
+        readonly displayName: "HubSpot";
+        readonly authKind: "api_key";
+        readonly category: "crm";
+        readonly maturity: "ready";
+        readonly docUrl: "https://developers.hubspot.com/docs/api/private-apps";
+        readonly ops: {};
+    };
+    readonly hunter: {
+        readonly displayName: "Hunter.io";
+        readonly authKind: "api_key";
+        readonly category: "email";
+        readonly maturity: "ready";
+        readonly docUrl: "https://hunter.io/api-documentation/v2";
+        readonly ops: {
+            readonly "email-finder": {
+                readonly description: "Find a person's email address at a company domain by their name. Returns the email, a confidence score, and verification status.";
+                readonly inputSchema: {
+                    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly domain: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly description: "Company domain, e.g. \"stripe.com\".";
+                        };
+                        readonly first_name: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly description: "The person first name.";
+                        };
+                        readonly last_name: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly description: "The person last name.";
+                        };
+                    };
+                    readonly required: readonly ["domain", "first_name", "last_name"];
+                };
+            };
+        };
+    };
+    readonly instagram: {
+        readonly displayName: "Instagram";
+        readonly authKind: "oauth2";
+        readonly category: "channel";
+        readonly maturity: "ready";
+        readonly docUrl: "https://developers.facebook.com/docs/instagram-platform";
+        readonly ops: {};
+    };
+    readonly instantly: {
+        readonly displayName: "Instantly.ai";
+        readonly authKind: "api_key";
+        readonly category: "email";
+        readonly maturity: "ready";
+        readonly docUrl: "https://developer.instantly.ai/";
+        readonly ops: {};
+    };
+    readonly mailchimp: {
+        readonly displayName: "Mailchimp";
+        readonly authKind: "api_key";
+        readonly category: "email";
+        readonly maturity: "ready";
+        readonly docUrl: "https://mailchimp.com/developer/marketing/api/";
+        readonly ops: {};
+    };
+    readonly meta: {
+        readonly displayName: "Meta Ads (Marketing API)";
+        readonly authKind: "api_key";
+        readonly category: "advertising";
+        readonly maturity: "coming_soon";
+        readonly docUrl: "https://developers.facebook.com/docs/marketing-apis";
+        readonly ops: {};
+    };
+    readonly pagespeed: {
+        readonly displayName: "PageSpeed Insights";
+        readonly authKind: "api_key";
+        readonly category: "analytics";
+        readonly maturity: "coming_soon";
+        readonly docUrl: "https://developers.google.com/speed/docs/insights/v5/get-started";
+        readonly ops: {};
+    };
+    readonly posthog: {
+        readonly displayName: "PostHog";
+        readonly authKind: "api_key";
+        readonly category: "analytics";
+        readonly maturity: "ready";
+        readonly docUrl: "https://posthog.com/docs/api";
+        readonly ops: {};
+    };
+    readonly salesforce: {
+        readonly displayName: "Salesforce";
+        readonly authKind: "api_key";
+        readonly category: "crm";
+        readonly maturity: "coming_soon";
+        readonly docUrl: "https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/";
+        readonly ops: {};
+    };
+    readonly sendgrid: {
+        readonly displayName: "SendGrid";
+        readonly authKind: "api_key";
+        readonly category: "email";
+        readonly maturity: "ready";
+        readonly docUrl: "https://docs.sendgrid.com/api-reference";
+        readonly ops: {};
+    };
+    readonly slack: {
+        readonly displayName: "Slack";
+        readonly authKind: "api_key";
+        readonly category: "messaging";
+        readonly maturity: "coming_soon";
+        readonly docUrl: "https://api.slack.com/methods/chat.postMessage";
+        readonly ops: {};
+    };
+    readonly stripe: {
+        readonly displayName: "Stripe";
+        readonly authKind: "oauth2";
+        readonly category: "payments";
+        readonly maturity: "coming_soon";
+        readonly docUrl: "https://docs.stripe.com/connect/oauth-reference";
+        readonly ops: {};
+    };
+    readonly twilio: {
+        readonly displayName: "Twilio";
+        readonly authKind: "api_key";
+        readonly category: "sms";
+        readonly maturity: "ready";
+        readonly docUrl: "https://www.twilio.com/docs/usage/api";
+        readonly ops: {};
+    };
+    readonly whatsapp: {
+        readonly displayName: "WhatsApp";
+        readonly authKind: "oauth2";
+        readonly category: "channel";
+        readonly maturity: "coming_soon";
+        readonly docUrl: "https://developers.facebook.com/docs/whatsapp";
+        readonly ops: {};
+    };
+    readonly wordpress: {
+        readonly displayName: "WordPress";
+        readonly authKind: "oauth2";
+        readonly category: "cms";
+        readonly maturity: "ready";
+        readonly docUrl: "https://developer.wordpress.com/docs/oauth2/";
+        readonly ops: {};
+    };
+};

package/dist/connectors.generated.js

@@ -0,0 +1,240 @@
+// AUTO-GENERATED by scripts/gen-connectors.mjs — DO NOT EDIT BY HAND.
+// Source: src/connectors.snapshot.json (a committed copy of keemakr-core's
+// GET /api/connections/catalog). Refresh: see scripts/gen-connectors.mjs header.
+/**
+ * The connector catalog as of the last snapshot refresh. Metadata only — no
+ * credentials. Keyed by provider slug; each entry lists its callable operations
+ * and their JSON-Schema arg contracts.
+ */
+export const connectors = {
+    "agent-sessions": {
+        "displayName": "Agent Session Feed",
+        "authKind": "api_key",
+        "category": "voice",
+        "maturity": "ready",
+        "docUrl": null,
+        "ops": {}
+    },
+    "apify": {
+        "displayName": "Apify",
+        "authKind": "api_key",
+        "category": "scraping",
+        "maturity": "ready",
+        "docUrl": "https://docs.apify.com/api/v2",
+        "ops": {}
+    },
+    "apollo": {
+        "displayName": "Apollo.io",
+        "authKind": "api_key",
+        "category": "sales-intelligence",
+        "maturity": "ready",
+        "docUrl": "https://docs.apollo.io/reference/introduction",
+        "ops": {}
+    },
+    "cal-com": {
+        "displayName": "Cal.com",
+        "authKind": "api_key",
+        "category": "scheduling",
+        "maturity": "ready",
+        "docUrl": "https://cal.com/docs/api-reference",
+        "ops": {}
+    },
+    "calendly": {
+        "displayName": "Calendly",
+        "authKind": "api_key",
+        "category": "scheduling",
+        "maturity": "coming_soon",
+        "docUrl": "https://developer.calendly.com/api-docs",
+        "ops": {}
+    },
+    "clearbit": {
+        "displayName": "Clearbit",
+        "authKind": "api_key",
+        "category": "sales-intelligence",
+        "maturity": "ready",
+        "docUrl": "https://dashboard.clearbit.com/docs",
+        "ops": {}
+    },
+    "drip": {
+        "displayName": "Drip",
+        "authKind": "api_key",
+        "category": "email",
+        "maturity": "ready",
+        "docUrl": "https://developer.drip.com/",
+        "ops": {}
+    },
+    "elevenlabs": {
+        "displayName": "ElevenLabs",
+        "authKind": "api_key",
+        "category": "voice",
+        "maturity": "ready",
+        "docUrl": "https://elevenlabs.io/docs/api-reference",
+        "ops": {}
+    },
+    "facebook": {
+        "displayName": "Facebook",
+        "authKind": "oauth2",
+        "category": "channel",
+        "maturity": "ready",
+        "docUrl": "https://developers.facebook.com/docs/pages-api",
+        "ops": {}
+    },
+    "fal": {
+        "displayName": "fal.ai",
+        "authKind": "api_key",
+        "category": "media",
+        "maturity": "coming_soon",
+        "docUrl": "https://fal.ai/docs",
+        "ops": {}
+    },
+    "hubspot": {
+        "displayName": "HubSpot",
+        "authKind": "api_key",
+        "category": "crm",
+        "maturity": "ready",
+        "docUrl": "https://developers.hubspot.com/docs/api/private-apps",
+        "ops": {}
+    },
+    "hunter": {
+        "displayName": "Hunter.io",
+        "authKind": "api_key",
+        "category": "email",
+        "maturity": "ready",
+        "docUrl": "https://hunter.io/api-documentation/v2",
+        "ops": {
+            "email-finder": {
+                "description": "Find a person's email address at a company domain by their name. Returns the email, a confidence score, and verification status.",
+                "inputSchema": {
+                    "$schema": "https://json-schema.org/draft/2020-12/schema",
+                    "type": "object",
+                    "properties": {
+                        "domain": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "Company domain, e.g. \"stripe.com\"."
+                        },
+                        "first_name": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "The person first name."
+                        },
+                        "last_name": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "The person last name."
+                        }
+                    },
+                    "required": [
+                        "domain",
+                        "first_name",
+                        "last_name"
+                    ]
+                }
+            }
+        }
+    },
+    "instagram": {
+        "displayName": "Instagram",
+        "authKind": "oauth2",
+        "category": "channel",
+        "maturity": "ready",
+        "docUrl": "https://developers.facebook.com/docs/instagram-platform",
+        "ops": {}
+    },
+    "instantly": {
+        "displayName": "Instantly.ai",
+        "authKind": "api_key",
+        "category": "email",
+        "maturity": "ready",
+        "docUrl": "https://developer.instantly.ai/",
+        "ops": {}
+    },
+    "mailchimp": {
+        "displayName": "Mailchimp",
+        "authKind": "api_key",
+        "category": "email",
+        "maturity": "ready",
+        "docUrl": "https://mailchimp.com/developer/marketing/api/",
+        "ops": {}
+    },
+    "meta": {
+        "displayName": "Meta Ads (Marketing API)",
+        "authKind": "api_key",
+        "category": "advertising",
+        "maturity": "coming_soon",
+        "docUrl": "https://developers.facebook.com/docs/marketing-apis",
+        "ops": {}
+    },
+    "pagespeed": {
+        "displayName": "PageSpeed Insights",
+        "authKind": "api_key",
+        "category": "analytics",
+        "maturity": "coming_soon",
+        "docUrl": "https://developers.google.com/speed/docs/insights/v5/get-started",
+        "ops": {}
+    },
+    "posthog": {
+        "displayName": "PostHog",
+        "authKind": "api_key",
+        "category": "analytics",
+        "maturity": "ready",
+        "docUrl": "https://posthog.com/docs/api",
+        "ops": {}
+    },
+    "salesforce": {
+        "displayName": "Salesforce",
+        "authKind": "api_key",
+        "category": "crm",
+        "maturity": "coming_soon",
+        "docUrl": "https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/",
+        "ops": {}
+    },
+    "sendgrid": {
+        "displayName": "SendGrid",
+        "authKind": "api_key",
+        "category": "email",
+        "maturity": "ready",
+        "docUrl": "https://docs.sendgrid.com/api-reference",
+        "ops": {}
+    },
+    "slack": {
+        "displayName": "Slack",
+        "authKind": "api_key",
+        "category": "messaging",
+        "maturity": "coming_soon",
+        "docUrl": "https://api.slack.com/methods/chat.postMessage",
+        "ops": {}
+    },
+    "stripe": {
+        "displayName": "Stripe",
+        "authKind": "oauth2",
+        "category": "payments",
+        "maturity": "coming_soon",
+        "docUrl": "https://docs.stripe.com/connect/oauth-reference",
+        "ops": {}
+    },
+    "twilio": {
+        "displayName": "Twilio",
+        "authKind": "api_key",
+        "category": "sms",
+        "maturity": "ready",
+        "docUrl": "https://www.twilio.com/docs/usage/api",
+        "ops": {}
+    },
+    "whatsapp": {
+        "displayName": "WhatsApp",
+        "authKind": "oauth2",
+        "category": "channel",
+        "maturity": "coming_soon",
+        "docUrl": "https://developers.facebook.com/docs/whatsapp",
+        "ops": {}
+    },
+    "wordpress": {
+        "displayName": "WordPress",
+        "authKind": "oauth2",
+        "category": "cms",
+        "maturity": "ready",
+        "docUrl": "https://developer.wordpress.com/docs/oauth2/",
+        "ops": {}
+    }
+};

package/dist/connectors.js

@@ -0,0 +1,28 @@
+// @keemakr/agent-sdk/connectors — the generated connector manifest.
+//
+// A typed, metadata-only view of keemakr-core's connector catalog so an agent
+// author (and the port kit) can discover providers + operation names + their arg
+// schemas WITHOUT scanning a core checkout or hitting a running instance. Credential-
+// free by construction — this is the same data GET /api/connections/catalog serves,
+// committed as a snapshot (src/connectors.snapshot.json) and codegen'd into
+// connectors.generated.ts. Refresh: see scripts/gen-connectors.mjs.
+//
+// Usage:
+//   import { connectors, opNames } from '@keemakr/agent-sdk/connectors';
+//   connectors.hunter.ops['email-finder'].inputSchema; // JSON Schema for the args
+//   opNames('meta');                                    // string[] of meta's op names
+//   isReady('meta');                                    // false while coming_soon
+export { connectors, } from './connectors.generated.js';
+import { connectors } from './connectors.generated.js';
+/** All provider slugs in the manifest. */
+export function providerNames() {
+    return Object.keys(connectors);
+}
+/** The operation names a provider exposes (empty for a coming_soon stub). */
+export function opNames(provider) {
+    return Object.keys(connectors[provider]?.ops ?? {});
+}
+/** True when the provider's connect path is proven and its operations are callable. */
+export function isReady(provider) {
+    return connectors[provider]?.maturity === 'ready';
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { grantAuth } from './grant-auth.js';
+export { verifyGrant, type VerifiedGrant } from './verify-grant.js';
 export { useKee, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type KeeTools, type MemoryEntry, type MemorySearchHit, } from './client.js';
 export { keemakrToolDirectory } from './tool-directory.js';

package/dist/index.js

@@ -9,5 +9,6 @@
 //   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 { verifyGrant } from './verify-grant.js';
 export { useKee, } from './client.js';
 export { keemakrToolDirectory } from './tool-directory.js';

package/dist/verify-grant.d.ts

@@ -0,0 +1,20 @@
+/** Trusted claims after verifyGrant() succeeds. */
+export interface VerifiedGrant {
+    tenantId: string;
+    installedAgent: string | null;
+    scopes: string[];
+    traceId: string | null;
+    aud: string | null;
+    exp: number | null;
+}
+/**
+ * Verify a capability grant (session OR machine) against keemakr-core's JWKS.
+ * Returns the trusted claims, or `null` on any failure (bad signature, wrong
+ * issuer/audience, expired). Both `jwksUrl` and `audience` fall back to
+ * KEE_CORE_JWKS_URL / KEE_AGENT_AUDIENCE. `audience` is strongly recommended: a
+ * grant is only valid for the remote it was minted for.
+ */
+export declare function verifyGrant(token: string, opts?: {
+    jwksUrl?: string;
+    audience?: string;
+}): Promise<VerifiedGrant | null>;

package/dist/verify-grant.js

@@ -0,0 +1,52 @@
+// Standalone capability-grant verification — for a scheduled/headless remote.
+//
+// grantAuth() (grant-auth.ts) is the right entry point for an eve CHANNEL: it
+// returns an AuthFn. But an autonomous/machine turn may run OUTSIDE a channel (a
+// cron worker that received a machine grant from core's machine-grant endpoint
+// and wants to verify it before acting). verifyGrant() is that path: give it the
+// token, get back the trusted claims (or null), verifying signature + issuer +
+// audience against core's JWKS.
+//
+// A machine grant is the SAME token shape as a session grant (same issuer, aud,
+// tenant_id, scopes) — only the TTL and the mint path differ — so this one
+// verifier covers both.
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+const GRANT_ISSUER = 'keemakr';
+let jwks = null;
+function jwksFor(url) {
+    if (!jwks)
+        jwks = createRemoteJWKSet(new URL(url));
+    return jwks;
+}
+/**
+ * Verify a capability grant (session OR machine) against keemakr-core's JWKS.
+ * Returns the trusted claims, or `null` on any failure (bad signature, wrong
+ * issuer/audience, expired). Both `jwksUrl` and `audience` fall back to
+ * KEE_CORE_JWKS_URL / KEE_AGENT_AUDIENCE. `audience` is strongly recommended: a
+ * grant is only valid for the remote it was minted for.
+ */
+export async function verifyGrant(token, opts) {
+    const jwksUrl = opts?.jwksUrl ?? process.env.KEE_CORE_JWKS_URL;
+    if (!jwksUrl)
+        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 } : {}),
+        });
+        if (typeof payload.tenant_id !== 'string' || !Array.isArray(payload.scopes))
+            return null;
+        return {
+            tenantId: payload.tenant_id,
+            installedAgent: typeof payload.installed_agent === 'string' ? payload.installed_agent : null,
+            scopes: payload.scopes.map(String),
+            traceId: typeof payload.trace_id === 'string' ? payload.trace_id : null,
+            aud: typeof payload.aud === 'string' ? payload.aud : null,
+            exp: typeof payload.exp === 'number' ? payload.exp : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/agent-sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "The floor for keemakr marketplace agents: verify the capability grant and reach tenant connections, memory, and shared platform tools through keemakr-core — without holding raw secrets or resolving the tenant yourself.",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,10 @@
     "./tool-directory": {
       "types": "./dist/tool-directory.d.ts",
       "import": "./dist/tool-directory.js"
+    },
+    "./connectors": {
+      "types": "./dist/connectors.d.ts",
+      "import": "./dist/connectors.js"
     }
   },
   "files": [
@@ -25,11 +29,13 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/fsztpartners/keemakr-agent-sdk.git"
+    "url": "git+https://github.com/fsztpartners/keemakr.git",
+    "directory": "packages/agent-sdk"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc --noEmit",
+    "gen:connectors": "node scripts/gen-connectors.mjs",
+    "build": "npm run gen:connectors && tsc -p tsconfig.json",
+    "typecheck": "npm run gen:connectors && tsc --noEmit",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {