@aithos/sdk 0.1.0-alpha.7 → 0.1.0-alpha.9

package/dist/src/compute.d.ts

@@ -63,10 +63,29 @@ export declare class ComputeNamespace {
      * Invoke a Bedrock model through the compute proxy. See
      * {@link InvokeBedrockArgs} and {@link InvokeBedrockResult}.
      *
+     * Two signer paths are supported:
+     *
+     *   - **Owner**: when the caller is signed in as an owner, the
+     *     envelope is signed with the owner's `#public` sphere key and
+     *     no mandate is attached (the proxy resolves the mandate
+     *     server-side from `params.mandate_id`).
+     *   - **Delegate**: when the caller is delegate-only (mandate
+     *     imported via `auth.importMandate`), the envelope is signed
+     *     with the delegate's bound keypair and the full SignedMandate
+     *     is attached so the proxy can verify both signature and
+     *     authorisation in one pass. The mandate must carry the
+     *     `compute.invoke` scope and the proxy enforces its constraints
+     *     (caps, allowed models, …) at server-side.
+     *
+     * Owner takes precedence: if a session has BOTH an owner and a
+     * matching delegate session, we use the owner key (more flexible —
+     * the mandate is dereferenced via `mandate_id` and there's no
+     * lifetime cliff if the delegate seed has been wiped).
+     *
      * @throws {AithosSDKError} on protocol errors. The `code` field is one of
-     *   `sdk_no_owner`, `network`, `http`, `empty`, or any code returned by
-     *   the proxy (`quota_exceeded`, `mandate_revoked`, `insufficient_credits`,
-     *   …).
+     *   `sdk_no_signer`, `sdk_no_delegate_for_mandate`, `network`, `http`,
+     *   `empty`, or any code returned by the proxy (`quota_exceeded`,
+     *   `mandate_revoked`, `insufficient_credits`, …).
      */
     invokeBedrock(args: InvokeBedrockArgs): Promise<InvokeBedrockResult>;
 }

package/dist/src/compute.js

@@ -16,9 +16,9 @@
 //
 // MVP scope: single-shot invocation. Multi-turn agentic loops (with native
 // tool calling on the proxy) will land in a follow-up.
-import { buildSignedEnvelope } from "@aithos/protocol-client";
+import { buildSignedEnvelope, } from "@aithos/protocol-client";
 import { computeInvokeUrl, } from "./endpoints.js";
-import { ownerKeyPair } from "./internal/protocol-client-bridge.js";
+import { delegateKeyPair, ownerKeyPair, } from "./internal/protocol-client-bridge.js";
 import { AithosSDKError } from "./types.js";
 /**
  * `sdk.compute` namespace. Constructed once by the {@link AithosSDK}
@@ -35,18 +35,66 @@ export class ComputeNamespace {
      * Invoke a Bedrock model through the compute proxy. See
      * {@link InvokeBedrockArgs} and {@link InvokeBedrockResult}.
      *
+     * Two signer paths are supported:
+     *
+     *   - **Owner**: when the caller is signed in as an owner, the
+     *     envelope is signed with the owner's `#public` sphere key and
+     *     no mandate is attached (the proxy resolves the mandate
+     *     server-side from `params.mandate_id`).
+     *   - **Delegate**: when the caller is delegate-only (mandate
+     *     imported via `auth.importMandate`), the envelope is signed
+     *     with the delegate's bound keypair and the full SignedMandate
+     *     is attached so the proxy can verify both signature and
+     *     authorisation in one pass. The mandate must carry the
+     *     `compute.invoke` scope and the proxy enforces its constraints
+     *     (caps, allowed models, …) at server-side.
+     *
+     * Owner takes precedence: if a session has BOTH an owner and a
+     * matching delegate session, we use the owner key (more flexible —
+     * the mandate is dereferenced via `mandate_id` and there's no
+     * lifetime cliff if the delegate seed has been wiped).
+     *
      * @throws {AithosSDKError} on protocol errors. The `code` field is one of
-     *   `sdk_no_owner`, `network`, `http`, `empty`, or any code returned by
-     *   the proxy (`quota_exceeded`, `mandate_revoked`, `insufficient_credits`,
-     *   …).
+     *   `sdk_no_signer`, `sdk_no_delegate_for_mandate`, `network`, `http`,
+     *   `empty`, or any code returned by the proxy (`quota_exceeded`,
+     *   `mandate_revoked`, `insufficient_credits`, …).
      */
     async invokeBedrock(args) {
         const { auth, appDid, endpoints, fetch: fetchImpl } = this.#deps;
         const owner = auth._getOwnerSigners();
-        if (!owner || owner.destroyed) {
-            throw new AithosSDKError("sdk_no_owner", "no owner signed in; sign in via auth.signIn / signUp / signInWithGoogle / signInWithRecovery first");
+        const ownerLoaded = owner !== null && !owner.destroyed;
+        let choice;
+        if (ownerLoaded) {
+            const publicKp = ownerKeyPair(owner, "public");
+            choice = {
+                kind: "owner",
+                iss: owner.did,
+                verificationMethod: `${owner.did}#public`,
+                signer: publicKp,
+                mandate: undefined,
+            };
+        }
+        else {
+            // Delegate-only path. Find a session whose mandate id matches.
+            const actor = auth._getDelegateActor(args.mandateId);
+            if (!actor || actor.destroyed) {
+                throw new AithosSDKError("sdk_no_delegate_for_mandate", `no owner signed in and no imported delegate mandate matches '${args.mandateId}'. Sign in as an owner, or import a delegate bundle for that mandate via auth.importMandate.`);
+            }
+            const kp = delegateKeyPair(actor);
+            choice = {
+                kind: "delegate",
+                iss: actor.subjectDid,
+                verificationMethod: actor.granteePubkeyMultibase,
+                signer: kp,
+                // The DelegateActor stores the SignedMandate as a structurally
+                // opaque object so the SDK doesn't have to import the
+                // protocol-client type at the storage boundary. Round-trip
+                // through `unknown` for the TS cast — at runtime the bytes are
+                // the canonical SignedMandate the bundle parser already
+                // validated.
+                mandate: actor.mandate,
+            };
         }
-        const publicKp = ownerKeyPair(owner, "public");
         const url = computeInvokeUrl(endpoints);
         const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
         const params = {
@@ -63,12 +111,13 @@ export class ComputeNamespace {
         if (args.temperature !== undefined)
             params.temperature = args.temperature;
         const envelope = buildSignedEnvelope({
-            iss: owner.did,
+            iss: choice.iss,
             aud: url,
             method: "aithos.compute_invoke",
-            verificationMethod: `${owner.did}#public`,
+            verificationMethod: choice.verificationMethod,
             params,
-            signer: publicKp,
+            signer: choice.signer,
+            ...(choice.kind === "delegate" ? { mandate: choice.mandate } : {}),
         });
         let res;
         try {

package/dist/src/internal/delegate-bundle.js

@@ -50,13 +50,18 @@ export function parseDelegateBundle(text) {
     }
     const m = mandate;
     const mandateId = m["id"];
-    const subjectDid = m["subject_did"] ?? m["subjectDid"];
+    // The mandate subject's DID is carried by `issuer` in the wire format
+    // emitted by `mintDelegateBundle()` (cf. SignedMandate.issuer in
+    // protocol-client). We accept the legacy `subject_did` / camelCase
+    // variants too so older test fixtures and any externally-minted
+    // bundles using the older shape keep working.
+    const subjectDid = m["issuer"] ?? m["subject_did"] ?? m["subjectDid"];
     const grantee = m["grantee"];
     if (typeof mandateId !== "string" || !mandateId) {
         throw bad("mandate.id missing");
     }
     if (typeof subjectDid !== "string" || !subjectDid.startsWith("did:")) {
-        throw bad("mandate.subject_did missing or malformed");
+        throw bad("mandate.issuer missing or malformed (expected a `did:` URL)");
     }
     if (typeof grantee !== "object" || grantee === null) {
         throw bad("mandate.grantee missing");

package/dist/src/mandates.d.ts

@@ -86,6 +86,18 @@ export interface CreateMandateInput {
      * which is what a consent UI can review.
      */
     readonly compute?: CreateMandateComputeInput;
+    /**
+     * When the mandate becomes valid. Optional — when omitted, the
+     * underlying mint helper signs with `not_before = now - 30s` (see
+     * `MANDATE_NOTBEFORE_OFFSET_SECONDS_DEFAULT` in
+     * `@aithos/protocol-client`) so a server whose clock runs slightly
+     * behind the client doesn't reject the freshly-minted mandate as
+     * `not yet valid`.
+     *
+     * Pass an explicit `Date` only for advanced flows (delayed-activation
+     * mandates, deterministic tests).
+     */
+    readonly notBefore?: Date;
 }
 export interface MintedMandate {
     /** Unique mandate id (matches `mandate.id` inside the bundle). */

package/dist/src/mandates.js

@@ -92,6 +92,7 @@ export class MandatesNamespace {
                     },
                 }
                 : {}),
+            ...(input.notBefore ? { notBefore: input.notBefore } : {}),
         });
         const mandate = result.mandate;
         return {

package/dist/test/auth-j3.test.js

@@ -90,7 +90,7 @@ describe("recovery file: parse + serialize", () => {
 /*  parseDelegateBundle                                                       */
 /* -------------------------------------------------------------------------- */
 describe("delegate bundle: parse", () => {
-    it("parses a well-formed bundle", () => {
+    it("parses a well-formed bundle (legacy subject_did field)", () => {
         const text = delegateBundleText({
             mandateId: "mandate:01H8XYZ",
             subjectDid: "did:aithos:zCarol",
@@ -103,6 +103,37 @@ describe("delegate bundle: parse", () => {
         assert.equal(parsed.granteeId, "urn:aithos:agent:bob1");
         assert.equal(parsed.delegateSeedHex.length, 64);
     });
+    it("parses a bundle minted by mintDelegateBundle (issuer field)", () => {
+        // Real wire shape emitted by `mintDelegateBundle` in protocol-client:
+        // SignedMandate carries the subject's DID under `issuer`, NOT
+        // `subject_did`. Regression test for the import flow that broke
+        // every freshly-minted mandate before this fix.
+        const text = JSON.stringify({
+            aithos_delegate_version: "0.1.0",
+            mandate: {
+                "aithos-mandate": "0.1",
+                id: "mandate:01H8ISSUER",
+                issuer: "did:aithos:zCarol",
+                issued_by_key: "did:aithos:zCarol#root",
+                grantee: {
+                    id: "urn:aithos:agent:bob1",
+                    pubkey: "z6MkqGenericPubKey",
+                },
+                actor_sphere: "self",
+                scopes: ["ethos.read.public", "ethos.write.public"],
+                not_before: "2026-05-10T00:00:00Z",
+                not_after: "2026-05-11T00:00:00Z",
+                issued_at: "2026-05-10T00:00:00Z",
+                nonce: "abc",
+                signature: { alg: "ed25519", key: "...", value: "..." },
+            },
+            delegate_seed_hex: "11".repeat(32),
+        });
+        const parsed = parseDelegateBundle(text);
+        assert.equal(parsed.subjectDid, "did:aithos:zCarol");
+        assert.equal(parsed.mandateId, "mandate:01H8ISSUER");
+        assert.equal(parsed.granteeId, "urn:aithos:agent:bob1");
+    });
     it("readDelegateBundleText accepts string passthrough", async () => {
         const text = delegateBundleText({
             mandateId: "m",

package/dist/test/compute-delegate-path.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compute-delegate-path.test.d.ts.map

package/dist/test/compute-delegate-path.test.js

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Tests for the delegate signing path on sdk.compute.invokeBedrock.
+// Until alpha.9 the method ALWAYS required an owner — a session that
+// only held a mandate (no owner signers) failed with sdk_no_owner
+// before any network call. From alpha.9 onward, when no owner is
+// loaded but a delegate matches the requested mandate id, the SDK
+// signs the envelope with the delegate's keypair and attaches the
+// SignedMandate.
+import { strict as assert } from "node:assert";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { createBrowserIdentity } from "@aithos/protocol-client";
+import { AithosAuth, AithosSDKError, ComputeNamespace, memoryKeyStore, noopStore, } from "../src/index.js";
+import { DEFAULT_SDK_ENDPOINTS } from "../src/endpoints.js";
+/* -------------------------------------------------------------------------- */
+/*  Test plumbing                                                             */
+/* -------------------------------------------------------------------------- */
+let savedFetch;
+let lastRequestBody = null;
+function installFetchMock(response) {
+    savedFetch = globalThis.fetch;
+    lastRequestBody = null;
+    globalThis.fetch = (async (_input, init) => {
+        lastRequestBody = JSON.parse(init?.body);
+        return new Response(JSON.stringify(response.json), {
+            status: response.status ?? 200,
+            headers: { "content-type": "application/json" },
+        });
+    });
+}
+function uninstallFetchMock() {
+    if (savedFetch)
+        globalThis.fetch = savedFetch;
+    savedFetch = undefined;
+    lastRequestBody = null;
+}
+const okResponse = {
+    json: {
+        jsonrpc: "2.0",
+        id: "x",
+        result: {
+            content: "ok",
+            stopReason: "end_turn",
+            usage: { inputTokens: 1, outputTokens: 1 },
+            creditsCharged: 1,
+            walletBalance: 999,
+            auditId: "audit-test",
+        },
+    },
+};
+function freshAuth() {
+    return new AithosAuth({
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+}
+function freshCompute(auth) {
+    return new ComputeNamespace({
+        auth,
+        appDid: "did:aithos:app:example-placeholder",
+        endpoints: DEFAULT_SDK_ENDPOINTS,
+        fetch: globalThis.fetch.bind(globalThis),
+    });
+}
+/**
+ * Build a delegate bundle JSON that matches the wire shape importMandate
+ * accepts. Uses a real SignedMandate-like object minted from a fresh
+ * issuer so signature verification on import succeeds.
+ */
+function makeDelegateBundleText(args) {
+    const issuer = createBrowserIdentity("alice", "Alice");
+    return JSON.stringify({
+        aithos_delegate_version: "0.1.0",
+        mandate: {
+            "aithos-mandate": "0.4.0",
+            id: args.mandateId,
+            issuer: issuer.did,
+            issued_by_key: `${issuer.did}#self`,
+            grantee: {
+                id: args.granteeId ?? "urn:aithos:agent:test",
+                pubkey: "z6MkqGenericPubKey",
+            },
+            actor_sphere: "self",
+            scopes: args.scopes,
+            not_before: "2026-05-10T00:00:00Z",
+            not_after: "2026-05-11T00:00:00Z",
+            issued_at: "2026-05-10T00:00:00Z",
+            nonce: "abc",
+            signature: { alg: "ed25519", key: `${issuer.did}#self`, value: "..." },
+        },
+        delegate_seed_hex: "11".repeat(32),
+    });
+}
+/* -------------------------------------------------------------------------- */
+/*  Tests                                                                     */
+/* -------------------------------------------------------------------------- */
+describe("ComputeNamespace.invokeBedrock — delegate path", () => {
+    beforeEach(() => {
+        installFetchMock(okResponse);
+    });
+    afterEach(() => {
+        uninstallFetchMock();
+    });
+    it("rejects with sdk_no_delegate_for_mandate when delegate-only and mandateId doesn't match", async () => {
+        const auth = freshAuth();
+        const compute = freshCompute(auth);
+        // Import a delegate with a DIFFERENT mandate id than the one the call
+        // requests. Should error with the new code (NOT sdk_no_owner anymore).
+        await auth.importMandate({
+            bundle: makeDelegateBundleText({
+                mandateId: "mandate:held",
+                scopes: ["compute.invoke"],
+            }),
+        });
+        await assert.rejects(() => compute.invokeBedrock({
+            mandateId: "mandate:other-not-held",
+            model: "claude-haiku-4-5",
+            messages: [{ role: "user", content: "Hi" }],
+            maxTokens: 1,
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "sdk_no_delegate_for_mandate");
+    });
+    it("signs with the delegate keypair + attaches the mandate when delegate-only matches", async () => {
+        const auth = freshAuth();
+        const compute = freshCompute(auth);
+        const mandateId = "mandate:matching";
+        await auth.importMandate({
+            bundle: makeDelegateBundleText({
+                mandateId,
+                scopes: ["compute.invoke"],
+            }),
+        });
+        await compute.invokeBedrock({
+            mandateId,
+            model: "claude-haiku-4-5",
+            messages: [{ role: "user", content: "Hi" }],
+            maxTokens: 1,
+        });
+        const env = lastRequestBody?.params?._envelope;
+        assert.ok(env, "envelope must be present");
+        // verificationMethod must be the delegate's bare multibase pubkey
+        // (NOT a `#sphere` DID URL). And the SignedMandate must be inside.
+        assert.match(env.proof.verificationMethod, /^z[1-9A-HJ-NP-Za-km-z]+$/, `expected multibase pubkey, got ${env.proof.verificationMethod}`);
+        assert.ok(env.mandate, "delegate envelopes must attach the SignedMandate");
+        assert.equal(env.mandate.id, mandateId);
+    });
+    it("still works the owner path when an owner is signed in", async () => {
+        const auth = freshAuth();
+        const compute = freshCompute(auth);
+        // Owner sign-in via recovery — picks up four sphere keys from the
+        // recovery file format. Build one inline.
+        const issuer = createBrowserIdentity("owner", "Owner");
+        const seedHex = (b) => Array.from(b).map((x) => x.toString(16).padStart(2, "0")).join("");
+        const recoveryText = JSON.stringify({
+            aithos_recovery_version: "0.1.0-plaintext",
+            handle: issuer.handle,
+            display_name: issuer.displayName,
+            did: issuer.did,
+            created_at: new Date().toISOString(),
+            seeds_hex: {
+                root: seedHex(issuer.root.seed),
+                public: seedHex(issuer.public.seed),
+                circle: seedHex(issuer.circle.seed),
+                self: seedHex(issuer.self.seed),
+            },
+        });
+        await auth.signInWithRecovery({ file: recoveryText });
+        await compute.invokeBedrock({
+            mandateId: "mandate:owner-managed",
+            model: "claude-haiku-4-5",
+            messages: [{ role: "user", content: "Hi" }],
+            maxTokens: 1,
+        });
+        const env = lastRequestBody?.params?._envelope;
+        assert.ok(env, "envelope must be present");
+        // Owner path: verificationMethod is a `#public` DID URL, and the
+        // envelope MUST NOT carry a mandate (server resolves from
+        // params.mandate_id).
+        assert.match(env.proof.verificationMethod, /#public$/);
+        assert.equal(env.mandate, undefined, "owner-signed envelopes should not attach a mandate");
+    });
+});
+//# sourceMappingURL=compute-delegate-path.test.js.map

package/dist/test/sdk.test.js

@@ -101,7 +101,12 @@ describe("AithosSDK constructor", () => {
         assert.equal(typeof sdk.ethos.me, "function");
         assert.equal(typeof sdk.mandates.create, "function");
     });
-    it("compute.invokeBedrock rejects when no owner is signed in", async () => {
+    it("compute.invokeBedrock rejects when no owner AND no delegate matches the mandate", async () => {
+        // Since alpha.9, invokeBedrock supports a delegate signing path. The
+        // failure mode here (no owner loaded AND no imported mandate matching
+        // the requested id) returns code `sdk_no_delegate_for_mandate`.
+        // The previous `sdk_no_owner` code now applies only to other entry
+        // points where there's no delegate fallback.
         const auth = makeAuth();
         const sdk = new AithosSDK({
             auth,
@@ -114,7 +119,8 @@ describe("AithosSDK constructor", () => {
             mandateId: "mandate:x",
             model: "claude-sonnet-4-6",
             messages: [{ role: "user", content: "hi" }],
-        }), (e) => e instanceof AithosSDKError && e.code === "sdk_no_owner");
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "sdk_no_delegate_for_mandate");
     });
 });
 //# sourceMappingURL=sdk.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.9",
   "description": "Aithos SDK — high-level TypeScript developer kit for building agentic apps on the Aithos protocol. Wraps @aithos/protocol-client and exposes the Aithos compute proxy and wallet (Stripe top-up) endpoints.",
   "keywords": [
     "aithos",
@@ -52,10 +52,10 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@aithos/protocol-client": ">=0.1.0-alpha.12 <0.2.0"
+    "@aithos/protocol-client": ">=0.1.0-alpha.13 <0.2.0"
   },
   "devDependencies": {
-    "@aithos/protocol-client": "^0.1.0-alpha.12",
+    "@aithos/protocol-client": "^0.1.0-alpha.13",
     "@types/node": "^24.12.2",
     "fake-indexeddb": "^6.2.5",
     "typescript": "^5.9.2"