cognia-sdk 0.1.2 → 0.1.4

package/README.md

@@ -33,6 +33,22 @@ const proposals = await session.end();
 Injecting something never counts as using it. Only `outcome()` creates evidence, and only for items this context
 returned. Dogfood, canary and operator traffic is classified server-side and never counts.
 
+
+## Auth: key or delegated token
+
+```ts
+// a developer credential or an SDK credential (cognia_sk_…)
+new Cognia({ apiKey: process.env.COGNIA_API_KEY })
+
+// delegated auth: the host already holds a Cognia bearer (e.g. the MCP OAuth access token)
+new Cognia({ tokenProvider: async () => await getCogniaToken() })   // called on every request, never cached, never in errors
+```
+
+If your identity lives in a connected client (Claude, ChatGPT, OpenClaw…) and the host hides its token, ask the connected
+Cognia to run `sdk_link_start`: it shows a one-time code and a Cloud link; you approve on the website and receive an
+**SDK credential** — a separate, narrow credential that can read context and report outcomes only. Details:
+`docs/SDK_CREDENTIALS.md` in the Cognia repository.
+
 ## Scope
 
 `mine` = the identity's own memories and Skills. `organization` (default) = plus everything its organizations share

package/dist/cjs/client.js

@@ -59,12 +59,14 @@ class Cognia {
     budget;
     timeoutMs;
     key;
+    tokenProvider;
     f;
     onError;
     constructor(o) {
-        if (!o.apiKey)
-            throw new Error("Cognia: apiKey is required");
-        this.key = o.apiKey;
+        if (!o.apiKey && !o.tokenProvider)
+            throw new Error("Cognia: apiKey or tokenProvider is required");
+        this.key = o.apiKey ?? null;
+        this.tokenProvider = o.tokenProvider ?? null;
         this.baseUrl = (o.baseUrl ?? "https://api.cognia.fun").replace(/\/$/, "");
         this.scope = o.scope ?? "organization";
         this.budget = o.budget;
@@ -72,20 +74,59 @@ class Cognia {
         this.f = o.fetch ?? fetch;
         this.onError = o.onError;
     }
+    /** Every string that reaches the host through an error or a reason has the bearer removed first (independent E2E F28). */
+    scrub(v, token) {
+        if (!token || token.length < 8)
+            return v;
+        const re = new RegExp(token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
+        const walk = (x) => {
+            if (typeof x === "string")
+                return x.replace(re, "[redacted]");
+            if (Array.isArray(x))
+                return x.map(walk);
+            if (x && typeof x === "object") {
+                const o = {};
+                for (const [k, val] of Object.entries(x))
+                    o[k] = walk(val);
+                return o;
+            }
+            return x;
+        };
+        return walk(v);
+    }
     async call(method, path, body, timeoutMs) {
         const ac = new AbortController();
-        const t = timeoutMs ? setTimeout(() => ac.abort(), timeoutMs) : null;
+        let timedOut = false;
+        const t = timeoutMs ? setTimeout(() => { timedOut = true; ac.abort(); }, timeoutMs) : null;
+        let token = null;
         try {
-            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.1" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
+            // delegated auth: the provider is asked on EVERY request, INSIDE the same deadline as the request itself (independent
+            // E2E F27: a pending provider used to block the host model), and its answer is used once, never stored on the client
+            const deadline = new Promise((_, reject) => { if (timeoutMs)
+                setTimeout(() => reject(Object.assign(new Error("tokenProvider timed out"), { name: "AbortError" })), timeoutMs); });
+            token = this.tokenProvider ? await (timeoutMs ? Promise.race([Promise.resolve(this.tokenProvider()), deadline]) : this.tokenProvider()) : this.key;
+            if (!token)
+                throw new CogniaError(`Cognia ${method} ${path} → no credential`, 0, null);
+            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${token}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.4" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
             let j = null;
             try {
                 j = await r.json();
             }
             catch { /* no body */ }
             if (!r.ok)
-                throw new CogniaError(`Cognia ${method} ${path} → ${r.status}`, r.status, j);
+                throw new CogniaError(`Cognia ${method} ${path} → ${r.status}`, r.status, this.scrub(j, token));
             return j;
         }
+        catch (e) {
+            // whatever the transport or the provider threw: the bearer never travels inside the error. A fresh error is built
+            // (a DOMException's message is read-only), keeping the name, status and a scrubbed body.
+            const src = e instanceof Error ? e : new Error(String(e));
+            const msg = token ? this.scrub(src.message, token) : src.message;
+            const out = src instanceof CogniaError ? new CogniaError(msg, src.status, token ? this.scrub(src.body, token) : src.body) : Object.assign(new Error(msg), { name: src.name });
+            if (timedOut)
+                out.name = "AbortError";
+            throw out;
+        }
         finally {
             if (t)
                 clearTimeout(t);

package/dist/esm/client.d.ts

@@ -1,7 +1,10 @@
 import type { ContextRequest, ContextResponse, ContextResult, OutcomeInput, OutcomeResponse, ExtractResponse, Scope } from "./types.js";
 export interface CogniaOptions {
-    /** the agent's credential (cognia_sk_…); never logged, never put in a URL */
-    apiKey: string;
+    /** the agent's credential (cognia_sk_…, a developer or SDK credential); never logged, never put in a URL */
+    apiKey?: string;
+    /** Delegated auth: called at REQUEST time to obtain the bearer (e.g. an MCP OAuth access token the host already
+     *  holds); async so the host can refresh. The SDK never caches the token and never puts it in errors or onError. */
+    tokenProvider?: () => Promise<string> | string;
     baseUrl?: string;
     /** default scope for context(); the identity's grants decide what that means */
     scope?: Scope;
@@ -33,9 +36,12 @@ export declare class Cognia {
     } | undefined;
     readonly timeoutMs: number;
     private readonly key;
+    private readonly tokenProvider;
     private readonly f;
     private readonly onError;
     constructor(o: CogniaOptions);
+    /** Every string that reaches the host through an error or a reason has the bearer removed first (independent E2E F28). */
+    private scrub;
     private call;
     /**
      * The Memories and Skills this identity may use for `task`, or an explicit ABSTAIN. Never throws: on a timeout or a

package/dist/esm/client.js

@@ -54,12 +54,14 @@ export class Cognia {
     budget;
     timeoutMs;
     key;
+    tokenProvider;
     f;
     onError;
     constructor(o) {
-        if (!o.apiKey)
-            throw new Error("Cognia: apiKey is required");
-        this.key = o.apiKey;
+        if (!o.apiKey && !o.tokenProvider)
+            throw new Error("Cognia: apiKey or tokenProvider is required");
+        this.key = o.apiKey ?? null;
+        this.tokenProvider = o.tokenProvider ?? null;
         this.baseUrl = (o.baseUrl ?? "https://api.cognia.fun").replace(/\/$/, "");
         this.scope = o.scope ?? "organization";
         this.budget = o.budget;
@@ -67,20 +69,59 @@ export class Cognia {
         this.f = o.fetch ?? fetch;
         this.onError = o.onError;
     }
+    /** Every string that reaches the host through an error or a reason has the bearer removed first (independent E2E F28). */
+    scrub(v, token) {
+        if (!token || token.length < 8)
+            return v;
+        const re = new RegExp(token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
+        const walk = (x) => {
+            if (typeof x === "string")
+                return x.replace(re, "[redacted]");
+            if (Array.isArray(x))
+                return x.map(walk);
+            if (x && typeof x === "object") {
+                const o = {};
+                for (const [k, val] of Object.entries(x))
+                    o[k] = walk(val);
+                return o;
+            }
+            return x;
+        };
+        return walk(v);
+    }
     async call(method, path, body, timeoutMs) {
         const ac = new AbortController();
-        const t = timeoutMs ? setTimeout(() => ac.abort(), timeoutMs) : null;
+        let timedOut = false;
+        const t = timeoutMs ? setTimeout(() => { timedOut = true; ac.abort(); }, timeoutMs) : null;
+        let token = null;
         try {
-            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.1" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
+            // delegated auth: the provider is asked on EVERY request, INSIDE the same deadline as the request itself (independent
+            // E2E F27: a pending provider used to block the host model), and its answer is used once, never stored on the client
+            const deadline = new Promise((_, reject) => { if (timeoutMs)
+                setTimeout(() => reject(Object.assign(new Error("tokenProvider timed out"), { name: "AbortError" })), timeoutMs); });
+            token = this.tokenProvider ? await (timeoutMs ? Promise.race([Promise.resolve(this.tokenProvider()), deadline]) : this.tokenProvider()) : this.key;
+            if (!token)
+                throw new CogniaError(`Cognia ${method} ${path} → no credential`, 0, null);
+            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${token}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.4" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
             let j = null;
             try {
                 j = await r.json();
             }
             catch { /* no body */ }
             if (!r.ok)
-                throw new CogniaError(`Cognia ${method} ${path} → ${r.status}`, r.status, j);
+                throw new CogniaError(`Cognia ${method} ${path} → ${r.status}`, r.status, this.scrub(j, token));
             return j;
         }
+        catch (e) {
+            // whatever the transport or the provider threw: the bearer never travels inside the error. A fresh error is built
+            // (a DOMException's message is read-only), keeping the name, status and a scrubbed body.
+            const src = e instanceof Error ? e : new Error(String(e));
+            const msg = token ? this.scrub(src.message, token) : src.message;
+            const out = src instanceof CogniaError ? new CogniaError(msg, src.status, token ? this.scrub(src.body, token) : src.body) : Object.assign(new Error(msg), { name: src.name });
+            if (timedOut)
+                out.name = "AbortError";
+            throw out;
+        }
         finally {
             if (t)
                 clearTimeout(t);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognia-sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Cognia for your model calls: one line gives any agent the Memories and Skills it may use, with provenance and honest receipts. Fails open.",
   "license": "MIT",
   "author": "Cognia",