@keemakr/agent-sdk 0.10.0 → 0.12.0

package/dist/grant-auth.d.ts

@@ -6,12 +6,22 @@ import { type AuthFn } from 'eve/channels/auth';
  * 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_CORE_URL        core's origin, e.g. https://dash.<env>.keemakr.ai — the
+ *                       platform this agent was installed on. REQUIRED (unless
+ *                       KEE_CORE_JWKS_URL or `opts.jwksUrl` says the same thing):
+ *                       it names the keys this agent trusts, and there is no
+ *                       default, because a default would mean trusting whichever
+ *                       platform the SDK author picked. Without it, every grant is
+ *                       refused and the reason is logged once.
+ *   KEE_CORE_JWKS_URL   the JWKS endpoint directly, when it is not
+ *                       `<KEE_CORE_URL>/.well-known/jwks.json`.
  *   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).
+ *
+ * A missing configuration no longer switches grant verification off SILENTLY,
+ * which was the real defect: it used to return the same bare null as a bad token,
+ * so every capability call 401'd with nothing in the log to say why.
  */
 export declare function grantAuth(opts?: {
     jwksUrl?: string;

package/dist/grant-auth.js

@@ -8,16 +8,11 @@
 // 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 { jwtVerify } from 'jose';
 import { extractBearerToken } from 'eve/channels/auth';
+import { jwksFor, resolveJwksUrl, warnCoreUnconfigured, warnGrantVerifyFailed } from './jwks.js';
 // 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
@@ -25,21 +20,35 @@ function jwksFor(url) {
  * 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_CORE_URL        core's origin, e.g. https://dash.<env>.keemakr.ai — the
+ *                       platform this agent was installed on. REQUIRED (unless
+ *                       KEE_CORE_JWKS_URL or `opts.jwksUrl` says the same thing):
+ *                       it names the keys this agent trusts, and there is no
+ *                       default, because a default would mean trusting whichever
+ *                       platform the SDK author picked. Without it, every grant is
+ *                       refused and the reason is logged once.
+ *   KEE_CORE_JWKS_URL   the JWKS endpoint directly, when it is not
+ *                       `<KEE_CORE_URL>/.well-known/jwks.json`.
  *   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).
+ *
+ * A missing configuration no longer switches grant verification off SILENTLY,
+ * which was the real defect: it used to return the same bare null as a bad token,
+ * so every capability call 401'd with nothing in the log to say why.
  */
 export function grantAuth(opts) {
     return async (request) => {
-        const jwksUrl = opts?.jwksUrl ?? process.env.KEE_CORE_JWKS_URL;
-        if (!jwksUrl)
-            return null;
+        // Token first: an unconfigured deployment should complain about requests that
+        // actually carry a grant, not about every anonymous hit on the channel.
         const token = extractBearerToken(request.headers.get('authorization'));
         if (!token)
             return null;
+        const jwksUrl = resolveJwksUrl(opts?.jwksUrl);
+        if (!jwksUrl) {
+            warnCoreUnconfigured('verify the capability grant on this request');
+            return null;
+        }
         const expectedAud = opts?.audience ?? process.env.KEE_AGENT_AUDIENCE;
         try {
             const { payload } = await jwtVerify(token, jwksFor(jwksUrl), {
@@ -67,7 +76,11 @@ export function grantAuth(opts) {
                 },
             };
         }
-        catch {
+        catch (error) {
+            // Still returns null — an unverifiable token must not authenticate — but no
+            // longer silently. A wrong JWKS URL and a genuinely bad token produced the
+            // same nothing before, which is what made the redirect trap so expensive.
+            warnGrantVerifyFailed(jwksUrl, error);
             return null;
         }
     };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { grantAuth } from './grant-auth.js';
 export { verifyGrant, type VerifiedGrant } from './verify-grant.js';
-export { useKee, MemoryConflictError, RecordConflictError, RecordValidationError, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type KeeRecords, type KeeKb, type KBHit, type KeeTools, type MemoryEntry, type MemorySearchHit, type RecordEntry, } from './client.js';
+export { useKee, MemoryConflictError, RecordConflictError, RecordValidationError, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type KeeRecords, type KeeKb, type KBHit, type KeeTools, type KeeConfig, type MemoryEntry, type MemorySearchHit, type RecordEntry, } from './client.js';
 export { keemakrToolDirectory } from './tool-directory.js';
 export { refreshGrant, REFRESH_THRESHOLD_SECONDS } from './refresh.js';

package/dist/jwks.d.ts

@@ -0,0 +1,42 @@
+/**
+ * There is deliberately NO compiled-in default origin.
+ *
+ * This value is a TRUST ANCHOR: whatever it names gets to decide, for every
+ * tenant this agent serves, which grants are genuine. It cannot come from the
+ * token (a forged grant would name its own JWKS and verify against it), and it
+ * must not come from a constant baked into a published package either — this SDK
+ * ships to npm and is installed by agents on dev, staging and production alike,
+ * so ANY single origin compiled in here is the wrong one for at least two of
+ * them. A default pointing at a non-production platform is the worst case of all:
+ * an unconfigured production agent would accept grants signed by a platform
+ * anyone can get an account on.
+ *
+ * So an unconfigured deployment gets `null` and verifies nothing — but LOUDLY,
+ * via warnCoreUnconfigured(). That was the actual defect behind "every capability
+ * call 401s with nothing in the log": not the absence of a default, but the
+ * silence. One warning naming the two variables fixes that without inventing a
+ * trust anchor on the operator's behalf.
+ */
+/** `<origin>/.well-known/jwks.json`, tolerating a trailing slash. */
+export declare function jwksUrlFor(origin: string): string;
+/**
+ * Resolve core's JWKS endpoint, most specific first, or `null` when the
+ * deployment has said nothing about which platform it belongs to.
+ *
+ * `KEE_CORE_URL` counts as a source in its own right: the SDK already derives
+ * that base URL FROM the JWKS URL, and supporting only that direction meant an
+ * agent could be configured to reach the capability API yet unable to verify the
+ * grant authorizing it — two variables for one fact, with a silent 401 as the
+ * penalty for setting the wrong one.
+ */
+export declare function resolveJwksUrl(explicit?: string): string | null;
+export declare function jwksFor(url: string): {
+    (protectedHeader?: import("jose").JWSHeaderParameters, token?: import("jose").FlattenedJWSInput): Promise<import("jose").CryptoKey>;
+    coolingDown: boolean;
+    fresh: boolean;
+    reloading: boolean;
+    reload: () => Promise<void>;
+    jwks: () => import("jose").JSONWebKeySet | undefined;
+};
+export declare function warnGrantVerifyFailed(jwksUrl: string, error: unknown): void;
+export declare function warnCoreUnconfigured(attempting: string): void;

package/dist/jwks.js

@@ -0,0 +1,97 @@
+// Where a keemakr agent looks for core's signing keys, and the one cache of them.
+//
+// Shared by both verification paths — the inbound channel auth (grant-auth) and
+// the standalone machine-grant check (verify-grant) — because a deployment that
+// can verify one and not the other is a configuration bug waiting to be
+// diagnosed twice.
+import { createRemoteJWKSet } from 'jose';
+/**
+ * There is deliberately NO compiled-in default origin.
+ *
+ * This value is a TRUST ANCHOR: whatever it names gets to decide, for every
+ * tenant this agent serves, which grants are genuine. It cannot come from the
+ * token (a forged grant would name its own JWKS and verify against it), and it
+ * must not come from a constant baked into a published package either — this SDK
+ * ships to npm and is installed by agents on dev, staging and production alike,
+ * so ANY single origin compiled in here is the wrong one for at least two of
+ * them. A default pointing at a non-production platform is the worst case of all:
+ * an unconfigured production agent would accept grants signed by a platform
+ * anyone can get an account on.
+ *
+ * So an unconfigured deployment gets `null` and verifies nothing — but LOUDLY,
+ * via warnCoreUnconfigured(). That was the actual defect behind "every capability
+ * call 401s with nothing in the log": not the absence of a default, but the
+ * silence. One warning naming the two variables fixes that without inventing a
+ * trust anchor on the operator's behalf.
+ */
+/** `<origin>/.well-known/jwks.json`, tolerating a trailing slash. */
+export function jwksUrlFor(origin) {
+    return `${origin.replace(/\/$/, '')}/.well-known/jwks.json`;
+}
+/**
+ * Resolve core's JWKS endpoint, most specific first, or `null` when the
+ * deployment has said nothing about which platform it belongs to.
+ *
+ * `KEE_CORE_URL` counts as a source in its own right: the SDK already derives
+ * that base URL FROM the JWKS URL, and supporting only that direction meant an
+ * agent could be configured to reach the capability API yet unable to verify the
+ * grant authorizing it — two variables for one fact, with a silent 401 as the
+ * penalty for setting the wrong one.
+ */
+export function resolveJwksUrl(explicit) {
+    if (explicit)
+        return explicit;
+    if (process.env.KEE_CORE_JWKS_URL)
+        return process.env.KEE_CORE_JWKS_URL;
+    if (process.env.KEE_CORE_URL)
+        return jwksUrlFor(process.env.KEE_CORE_URL);
+    return null;
+}
+// Keyed by URL. The previous single-slot cache handed back the FIRST keyset it
+// ever built for every later call, so a process verifying against two cores used
+// the wrong keys for one of them and reported nothing.
+const jwksCache = new Map();
+export function jwksFor(url) {
+    let set = jwksCache.get(url);
+    if (!set) {
+        set = createRemoteJWKSet(new URL(url));
+        jwksCache.set(url, set);
+    }
+    return set;
+}
+// A misconfigured JWKS URL was indistinguishable from an unauthorized caller: the
+// verify threw, the caller returned null, and every capability call 401'd with
+// nothing said about why. The classic cause is an origin that REDIRECTS (e.g.
+// app.dev.keemakr.ai → dash.dev.keemakr.ai), where `jose` fetches HTML and finds
+// no keys. Warn once per URL: enough to diagnose, not enough to flood a hot path.
+const warned = new Set();
+export function warnGrantVerifyFailed(jwksUrl, error) {
+    if (warned.has(jwksUrl))
+        return;
+    warned.add(jwksUrl);
+    const reason = error instanceof Error ? error.message : String(error);
+    console.warn(`[keemakr] could not verify a capability grant against ${jwksUrl}: ${reason}. ` +
+        'If that URL redirects or serves no keys, set KEE_CORE_JWKS_URL (or KEE_CORE_URL) ' +
+        'to the origin serving /.well-known/jwks.json for the platform you installed on.');
+}
+/**
+ * The other half of the same diagnosis problem: a deployment that named no
+ * platform at all. It still refuses the token — an agent that does not know whose
+ * keys to trust must not decide that a grant is genuine — but it now says so
+ * instead of returning the same silent null a genuinely bad token gets.
+ *
+ * Warned once per process (not per request): this fires on a hot path, and after
+ * the first line the operator has everything they need.
+ */
+let warnedUnconfigured = false;
+export function warnCoreUnconfigured(attempting) {
+    if (warnedUnconfigured)
+        return;
+    warnedUnconfigured = true;
+    console.warn(`[keemakr] cannot ${attempting}: this deployment has not been told which keemakr ` +
+        'platform it belongs to, so there are no signing keys to trust and no capability ' +
+        'API to call. Set KEE_CORE_URL to the origin you installed on (e.g. ' +
+        'https://dash.<env>.keemakr.ai), or KEE_CORE_JWKS_URL to its ' +
+        '/.well-known/jwks.json directly. There is no default on purpose — guessing ' +
+        'would mean trusting a platform you did not choose.');
+}

package/dist/refresh.d.ts

@@ -1,6 +1,16 @@
 /** Refresh when the active token has less than this long left to live. */
 export declare const REFRESH_THRESHOLD_SECONDS = 120;
-/** Resolve core's base URL: KEE_CORE_URL, else derived from KEE_CORE_JWKS_URL. */
+/**
+ * Resolve core's base URL: KEE_CORE_URL, else the origin of KEE_CORE_JWKS_URL.
+ *
+ * Throws when neither is set, and that is the safe answer rather than the
+ * unhelpful one. This URL is where the SDK POSTs the tenant's grant token, so a
+ * guessed default is not a convenience — it is a live credential sent to a host
+ * nobody chose, which on an unconfigured production agent would mean handing a
+ * production grant to whatever environment the constant happened to name. Failing
+ * at the first capability call, with both variable names in the message, costs one
+ * deploy; the other failure mode costs a credential.
+ */
 export declare function coreBaseUrl(): string;
 /** The freshest token known for a delegation (the exchanged one, else the original). */
 export declare function activeGrantToken(originalToken: string): string;

package/dist/refresh.js

@@ -19,7 +19,17 @@ export const REFRESH_THRESHOLD_SECONDS = 120;
 const refreshed = new Map();
 // original grant token → in-flight refresh, so N concurrent tool calls share one POST.
 const inflight = new Map();
-/** Resolve core's base URL: KEE_CORE_URL, else derived from KEE_CORE_JWKS_URL. */
+/**
+ * Resolve core's base URL: KEE_CORE_URL, else the origin of KEE_CORE_JWKS_URL.
+ *
+ * Throws when neither is set, and that is the safe answer rather than the
+ * unhelpful one. This URL is where the SDK POSTs the tenant's grant token, so a
+ * guessed default is not a convenience — it is a live credential sent to a host
+ * nobody chose, which on an unconfigured production agent would mean handing a
+ * production grant to whatever environment the constant happened to name. Failing
+ * at the first capability call, with both variable names in the message, costs one
+ * deploy; the other failure mode costs a credential.
+ */
 export function coreBaseUrl() {
     const explicit = process.env.KEE_CORE_URL;
     if (explicit)
@@ -27,7 +37,10 @@ export function coreBaseUrl() {
     const jwks = process.env.KEE_CORE_JWKS_URL;
     if (jwks)
         return jwks.replace(/\/\.well-known\/jwks\.json\/?$/, '');
-    const e = new Error('KEE_CORE_URL (or KEE_CORE_JWKS_URL) must be set to reach the Capability API');
+    const e = new Error('KEE_CORE_URL (or KEE_CORE_JWKS_URL) must be set to reach the Capability API — ' +
+        'it names the keemakr platform this agent was installed on, e.g. ' +
+        'https://dash.<env>.keemakr.ai. There is no default: the grant token is sent ' +
+        'to this URL, so guessing would leak it to a platform you did not choose.');
     e.name = 'KeeError';
     throw e;
 }

package/dist/verify-grant.d.ts

@@ -10,9 +10,11 @@ export interface VerifiedGrant {
 /**
  * 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.
+ * issuer/audience, expired). `jwksUrl` falls back to KEE_CORE_JWKS_URL, then to
+ * KEE_CORE_URL's origin — and to nothing after that, so a deployment that has not
+ * named its platform refuses every grant rather than trusting a compiled-in
+ * default it did not choose. `audience` falls back to KEE_AGENT_AUDIENCE and is
+ * strongly recommended: a grant is only valid for the remote it was minted for.
  */
 export declare function verifyGrant(token: string, opts?: {
     jwksUrl?: string;

package/dist/verify-grant.js

@@ -10,25 +10,24 @@
 // 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';
+import { jwtVerify } from 'jose';
+import { jwksFor, resolveJwksUrl, warnCoreUnconfigured, warnGrantVerifyFailed } from './jwks.js';
 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.
+ * issuer/audience, expired). `jwksUrl` falls back to KEE_CORE_JWKS_URL, then to
+ * KEE_CORE_URL's origin — and to nothing after that, so a deployment that has not
+ * named its platform refuses every grant rather than trusting a compiled-in
+ * default it did not choose. `audience` falls back to KEE_AGENT_AUDIENCE and 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)
+    const jwksUrl = resolveJwksUrl(opts?.jwksUrl);
+    if (!jwksUrl) {
+        warnCoreUnconfigured('verify this capability grant');
         return null;
+    }
     const expectedAud = opts?.audience ?? process.env.KEE_AGENT_AUDIENCE;
     try {
         const { payload } = await jwtVerify(token, jwksFor(jwksUrl), {
@@ -46,7 +45,10 @@ export async function verifyGrant(token, opts) {
             exp: typeof payload.exp === 'number' ? payload.exp : null,
         };
     }
-    catch {
+    catch (error) {
+        // Null either way — an unverifiable grant must not pass — but say why once, so
+        // a misconfigured JWKS URL is distinguishable from a genuinely bad token.
+        warnGrantVerifyFailed(jwksUrl, error);
         return null;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/agent-sdk",
-  "version": "0.10.0",
+  "version": "0.12.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",