@aithos/sdk 0.1.0-alpha.5 → 0.1.0-alpha.6

package/README.md

@@ -55,6 +55,51 @@ const reply = await sdk.compute.invokeBedrock({
 console.log(reply.content);
 ```
 
+## Delegating compute to an agent — opt-in token spending
+
+To let an agent (or another user, or a third-party app) invoke Bedrock
+**in your name**, with **your credits**, you mint a mandate. Token
+spending is its own opt-in capability — passing it is a separate,
+named, validated input that a consent UI can review. It is NEVER an
+implicit side-effect of an ethos read/write scope.
+
+```ts
+// Mint a mandate that lets agent Bob read your public ethos AND
+// spend up to 5 000 microcredits/day on Haiku, capped at 100 000
+// microcredits over the whole mandate lifetime.
+const mandate = await sdk.mandates.create({
+  granteeId: "urn:agent:bob",
+  scopes: ["ethos.read.public"],
+  ttlSeconds: 86_400,
+  compute: {
+    dailyCapMicrocredits: 5_000,
+    totalCapMicrocredits: 100_000,
+    maxCreditsPerCall: 500,
+    allowedModels: ["claude-haiku-4-5"],
+  },
+});
+
+// Hand `mandate.bundle` (a `.aithos-delegate.json` Blob) to Bob.
+// He imports it, then signs his own envelopes and calls
+// sdk.compute.invokeBedrock({ mandateId: mandate.mandateId, … })
+// — every invocation debits *your* wallet, capped per the budget
+// you set.
+```
+
+Three invariants the SDK enforces synchronously, before reaching the
+network — they fail fast with a precise `AithosSDKError`:
+
+- **No smuggling.** Adding `"compute.invoke"` directly to `scopes[]`
+  throws `mandates_invalid_scopes`. The `compute` namespace is the
+  only path, so a UI reviewing `compute` can never be bypassed.
+- **No bearer compute.** A `compute` namespace without at least one
+  of `dailyCapMicrocredits` or `totalCapMicrocredits` throws
+  `mandates_invalid_compute`. Unbounded compute mandates are forbidden
+  by construction.
+- **Compute-only is fine.** `scopes: []` is allowed when `compute` is
+  set — useful for agents that only consume tokens (e.g. creative
+  assistants) without seeing any of your data.
+
 ## What lives where
 
 | Namespace        | Purpose                                                                                    |

package/dist/src/auth.d.ts

@@ -4,8 +4,18 @@ import { DelegateActor } from "./internal/delegate-state.js";
 import { OwnerSigners } from "./internal/owner-signers.js";
 /** Default URL of the Aithos auth backend. */
 export declare const DEFAULT_AUTH_BASE_URL = "https://auth.aithos.be";
+/** Default URL of the Aithos primitives API (publish_identity, publish_ethos_edition, etc.). */
+export declare const DEFAULT_API_BASE_URL = "https://api.aithos.be";
 export interface AithosAuthConfig {
     readonly authBaseUrl?: string;
+    /**
+     * Base URL of the Aithos primitives API (`api.aithos.be`). Used by
+     * {@link AithosAuth.signUp} to bootstrap the user's Ethos via
+     * `aithos.publish_identity` after the auth account is created. Override
+     * for staging or self-hosted deployments. Defaults to
+     * {@link DEFAULT_API_BASE_URL}.
+     */
+    readonly apiBaseUrl?: string;
     readonly fetch?: typeof fetch;
     readonly window?: Pick<Window, "location" | "history">;
     /** Pluggable JWT-session storage. Defaults to {@link defaultSessionStore}. */
@@ -82,6 +92,7 @@ export interface ImportMandateInput {
 export declare class AithosAuth {
     #private;
     readonly authBaseUrl: string;
+    readonly apiBaseUrl: string;
     constructor(config?: AithosAuthConfig);
     /**
      * Reload signing material and JWT session from the configured stores.

package/dist/src/auth.js

@@ -20,7 +20,7 @@
 // JWT-less sessions (recovery / mandate sign-ins) are valid: the
 // keyStore is the source of truth for "is the user signed in", the
 // JWT is auxiliary for compute/wallet.
-import { buildBlobPlaintext, createBrowserIdentity, decryptBlob, DEFAULT_KDF, deriveAuthAndEncKeys, encryptBlob, parseBlob, randomNonce, randomSalt, serializeBlob, zeroize, } from "@aithos/protocol-client";
+import { buildBlobPlaintext, buildSignedEnvelope, createBrowserIdentity, decryptBlob, DEFAULT_KDF, deriveAuthAndEncKeys, encryptBlob, parseBlob, randomNonce, randomSalt, serializeBlob, signedDidDocument, zeroize, } from "@aithos/protocol-client";
 import { loginChallenge, loginVerify, registerAccount, } from "./auth-api.js";
 import { defaultSessionStore, } from "./session-store.js";
 import { defaultKeyStore, } from "./key-store.js";
@@ -31,11 +31,14 @@ import { parseRecoveryFile, readRecoveryFileText, serializeRecoveryFile, } from
 import { AithosSDKError } from "./types.js";
 /** Default URL of the Aithos auth backend. */
 export const DEFAULT_AUTH_BASE_URL = "https://auth.aithos.be";
+/** Default URL of the Aithos primitives API (publish_identity, publish_ethos_edition, etc.). */
+export const DEFAULT_API_BASE_URL = "https://api.aithos.be";
 /* -------------------------------------------------------------------------- */
 /*  AithosAuth                                                                */
 /* -------------------------------------------------------------------------- */
 export class AithosAuth {
     authBaseUrl;
+    apiBaseUrl;
     #fetchImpl;
     #win;
     #sessionStore;
@@ -46,6 +49,7 @@ export class AithosAuth {
     #delegates = new DelegateRegistry();
     constructor(config = {}) {
         this.authBaseUrl = trimSlash(config.authBaseUrl ?? DEFAULT_AUTH_BASE_URL);
+        this.apiBaseUrl = trimSlash(config.apiBaseUrl ?? DEFAULT_API_BASE_URL);
         this.#fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
         this.#win =
             config.window ??
@@ -306,6 +310,16 @@ export class AithosAuth {
             zeroize(authKey);
             zeroize(encKey);
         }
+        // Bootstrap the Ethos on api.aithos.be. Without this, every subsequent
+        // write (publish_ethos_edition, etc.) errors out with -32020
+        // "subject identity not published". We do this BEFORE hydrating local
+        // state so a bootstrap failure leaves the SDK in a clean
+        // "not signed in" state — the dev shows an error, the user retries.
+        // The auth account on auth.aithos.be DOES exist at this point, but
+        // without the local hydrate the user can't act on it. Self-heal on
+        // signIn (re-attempt publish_identity if missing) is planned for a
+        // follow-up release.
+        await this.#publishIdentity(identity);
         // Hydrate in-memory state from the fresh identity.
         if (this.#ownerSigners)
             this.#ownerSigners.destroy();
@@ -558,6 +572,83 @@ export class AithosAuth {
         await this.#keyStore.clearOwner().catch(() => { });
         await this.#keyStore.clearAllDelegates().catch(() => { });
     }
+    /* ------------------------------------------------------------------------ */
+    /*  Internal — Ethos bootstrap                                              */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Provision the user's Ethos on `api.aithos.be` by signing and POSTing an
+     * `aithos.publish_identity` envelope. Required after a fresh sign-up so
+     * subsequent edition publishes (`me.publish()`) don't fail with
+     * `-32020 subject identity not published`.
+     *
+     * Retries twice with exponential backoff on transient errors (network or
+     * 5xx). Throws {@link AithosSDKError} with code `ethos_bootstrap_failed`
+     * on definitive failure — the caller is expected to abort sign-up.
+     *
+     * @internal
+     */
+    async #publishIdentity(identity) {
+        const url = `${this.apiBaseUrl}/mcp/primitives/write`;
+        const signedDoc = signedDidDocument(identity);
+        const params = {
+            did_document: signedDoc,
+            handle: identity.handle,
+            display_name: identity.displayName,
+        };
+        const envelope = buildSignedEnvelope({
+            iss: identity.did,
+            aud: url,
+            method: "aithos.publish_identity",
+            verificationMethod: `${identity.did}#root`,
+            params,
+            signer: identity.root,
+        });
+        const body = JSON.stringify({
+            jsonrpc: "2.0",
+            id: "publish_identity",
+            method: "aithos.publish_identity",
+            params: { ...params, _envelope: envelope },
+        });
+        // Two retries with backoff (300ms, 1500ms). Idempotent on the server
+        // side — replaying the same publish_identity for an existing DID is a
+        // no-op, so retries are safe even if the first attempt actually
+        // succeeded but the response was lost.
+        const delays = [0, 300, 1500];
+        let lastError;
+        for (const delay of delays) {
+            if (delay > 0)
+                await sleep(delay);
+            try {
+                const res = await this.#fetchImpl(url, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body,
+                });
+                // Transport errors (5xx, no body) — retry. JSON-RPC errors come
+                // back with HTTP 200 and an `error` field.
+                if (!res.ok && res.status >= 500) {
+                    lastError = new Error(`HTTP ${res.status}`);
+                    continue;
+                }
+                const json = (await res.json());
+                if (json.error) {
+                    // JSON-RPC error: don't retry — these are deterministic
+                    // (validation, permission, identity-already-tombstoned, …).
+                    throw new AithosSDKError("ethos_bootstrap_failed", `publish_identity rejected: ${json.error.message}`, {
+                        status: res.status,
+                        data: { rpc_code: json.error.code, ...(json.error.data ?? {}) },
+                    });
+                }
+                return; // success
+            }
+            catch (e) {
+                if (e instanceof AithosSDKError)
+                    throw e;
+                lastError = e;
+            }
+        }
+        throw new AithosSDKError("ethos_bootstrap_failed", `publish_identity unreachable after ${delays.length} attempts: ${lastError?.message ?? "unknown"}`);
+    }
 }
 /* -------------------------------------------------------------------------- */
 /*  Helpers                                                                   */
@@ -565,6 +656,9 @@ export class AithosAuth {
 function trimSlash(url) {
     return url.endsWith("/") ? url.slice(0, -1) : url;
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function cleanCallbackParams(win, url) {
     url.searchParams.delete("aithos_code");
     url.searchParams.delete("aithos_error");

package/dist/src/index.d.ts

@@ -8,14 +8,14 @@ export type { ComputeMessage, InvokeBedrockArgs, InvokeBedrockResult, StopReason
 export { ComputeNamespace } from "./compute.js";
 export type { CreditPackId, CreateTopupSessionArgs, CreateTopupSessionResult, GetBalanceArgs, GetBalanceResult, } from "./wallet.js";
 export { WalletNamespace } from "./wallet.js";
-export { AithosAuth, DEFAULT_AUTH_BASE_URL } from "./auth.js";
+export { AithosAuth, DEFAULT_API_BASE_URL, DEFAULT_AUTH_BASE_URL, } from "./auth.js";
 export type { AithosAuthConfig, AithosSession, DelegateInfo, ImportMandateInput, OwnerInfo, SignInInput, SignInWithGoogleOptions, SignInWithRecoveryInput, SignUpInput, SignUpResult, } from "./auth.js";
 export { DEFAULT_SESSION_STORAGE_KEY, defaultSessionStore, localStorageStore, noopStore, sessionStorageStore, type AithosSessionStore, } from "./session-store.js";
 export { DEFAULT_KEYSTORE_DB_NAME, defaultKeyStore, indexedDbKeyStore, memoryKeyStore, type AithosKeyStore, type StoredDelegateKeys, type StoredOwnerKeys, } from "./key-store.js";
 export { EthosClient, EthosNamespace, EthosZone, ZONE_NAMES, } from "./ethos.js";
 export type { AddSectionInput, PublishResult, StagedChange, UpdateSectionPatch, ZoneName, } from "./ethos.js";
-export { MandatesNamespace } from "./mandates.js";
-export type { ActorSphere, CreateMandateInput, MintedMandate, OwnedMandate, Scope, } from "./mandates.js";
+export { COMPUTE_INVOKE_SCOPE, MandatesNamespace } from "./mandates.js";
+export type { ActorSphere, CreateMandateComputeInput, CreateMandateInput, MintedMandate, OwnedMandate, Scope, } from "./mandates.js";
 export * as onboarding from "./onboarding.js";
 export { createBrowserIdentity, browserIdentityFromStored, type BrowserIdentity, } from "@aithos/protocol-client";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -28,7 +28,7 @@ export { WalletNamespace } from "./wallet.js";
 // BrowserIdentity (sign-up creates one, sign-in restores it from the
 // server). The class also owns the session store — see
 // ./session-store.ts for pluggable persistence.
-export { AithosAuth, DEFAULT_AUTH_BASE_URL } from "./auth.js";
+export { AithosAuth, DEFAULT_API_BASE_URL, DEFAULT_AUTH_BASE_URL, } from "./auth.js";
 // Session storage backends used by AithosAuth. `sessionStorageStore` is
 // the default in browser environments ; pass another store at construction
 // time if you need different persistence.
@@ -46,7 +46,7 @@ export { DEFAULT_KEYSTORE_DB_NAME, defaultKeyStore, indexedDbKeyStore, memoryKey
 // the entry points.
 export { EthosClient, EthosNamespace, EthosZone, ZONE_NAMES, } from "./ethos.js";
 // `sdk.mandates` namespace — owner-side mandate lifecycle.
-export { MandatesNamespace } from "./mandates.js";
+export { COMPUTE_INVOKE_SCOPE, MandatesNamespace } from "./mandates.js";
 // Onboarding re-exports kept for advanced callers — the curated API
 // for first-run flows is `auth.signUp` (already shipped in J3).
 export * as onboarding from "./onboarding.js";

package/dist/src/mandates.d.ts

@@ -1,12 +1,65 @@
 import type { AithosAuth } from "./auth.js";
 import type { AithosSdkEndpoints } from "./endpoints.js";
-/** Capability scope the SDK accepts. Server-side ultimately decides. */
+/** Capability scope the SDK accepts. Server-side ultimately decides.
+ *
+ * Note: `compute.invoke` is intentionally NOT in this union. The token-
+ * spending capability is opt-in via the dedicated {@link CreateMandateInput.compute}
+ * namespace — see {@link MandatesNamespace.create}. Passing `compute.invoke`
+ * directly in `scopes` is rejected at runtime; the compiler can't enforce
+ * it (callers who up-cast to string[] would slip through), so the runtime
+ * check is the real gate. */
 export type Scope = "ethos.read.public" | "ethos.read.circle" | "ethos.read.self" | "ethos.write.public" | "ethos.write.circle" | "ethos.write.self";
+/**
+ * The opt-in scope that authorizes a delegate to spend the subject's
+ * compute credits via the Aithos compute proxy. Mirror of
+ * `COMPUTE_INVOKE_SCOPE` in `@aithos/protocol-core` v0.4.0.
+ *
+ * The SDK's `mandates.create()` injects this scope automatically when
+ * the caller passes a `compute` namespace, and refuses to mint a
+ * mandate where the caller put it directly into `scopes` — this is
+ * what makes "compute is a separate, conscious decision" hold at the
+ * API surface.
+ */
+export declare const COMPUTE_INVOKE_SCOPE: "compute.invoke";
 /**
  * Which sphere of the owner signs the mandate. Bounds the upper-most
  * scope set the mandate can carry.
  */
 export type ActorSphere = "public" | "circle" | "self";
+/**
+ * Compute-spending capability — opt-in only, never implied by ethos
+ * scopes.
+ *
+ * When `compute` is set on {@link CreateMandateInput}, the SDK:
+ *   1. Adds the `compute.invoke` scope to the minted mandate.
+ *   2. Maps the caller's caps onto `constraints.compute` in the
+ *      protocol's snake_case shape (= what the verifier reads).
+ *   3. Forbids the caller from passing `compute.invoke` in `scopes`
+ *      directly — that would let an app slip the scope past a
+ *      consent UI that only reviews `compute`.
+ *
+ * At least one of `dailyCapMicrocredits` or `totalCapMicrocredits` MUST
+ * be set: an unbounded compute mandate is the kind of bearer-token
+ * footgun this whole namespace exists to prevent. Validation happens
+ * at the SDK boundary (here) AND at the protocol layer (the
+ * server-side verifier rejects capless 0.4.0 mandates), so a bug in
+ * either tier still fails closed.
+ *
+ * `maxCreditsPerCall` is a per-invocation safety net for runaway
+ * single requests. `allowedModels`, when set, restricts which Bedrock
+ * model ids the delegate may target (the proxy's own allowlist still
+ * applies on top).
+ */
+export interface CreateMandateComputeInput {
+    /** Hard cap on credits debited per UTC day under this mandate. */
+    readonly dailyCapMicrocredits?: number;
+    /** Hard cap on credits debited over the whole mandate lifetime. */
+    readonly totalCapMicrocredits?: number;
+    /** Hard cap on credits debited by any single invocation. */
+    readonly maxCreditsPerCall?: number;
+    /** Allowlist of Bedrock model ids the delegate may invoke. */
+    readonly allowedModels?: readonly string[];
+}
 export interface CreateMandateInput {
     /** Grantee URN — usually `urn:aithos:agent:<extension-id>` or similar. */
     readonly granteeId: string;
@@ -23,6 +76,16 @@ export interface CreateMandateInput {
     readonly scopes: readonly Scope[];
     /** Lifetime in seconds. */
     readonly ttlSeconds: number;
+    /**
+     * Opt-in compute (token-spending) capability — adds the
+     * `compute.invoke` scope and a bounded `constraints.compute` budget
+     * to the mandate. See {@link CreateMandateComputeInput}.
+     *
+     * NEVER add `compute.invoke` to `scopes` directly — the SDK rejects
+     * that path so the caller has to pass through this typed namespace,
+     * which is what a consent UI can review.
+     */
+    readonly compute?: CreateMandateComputeInput;
 }
 export interface MintedMandate {
     /** Unique mandate id (matches `mandate.id` inside the bundle). */

package/dist/src/mandates.js

@@ -16,6 +16,18 @@
 import { buildSignedEnvelope, mintDelegateBundle, readRpc, } from "@aithos/protocol-client";
 import { ownerKeyPair } from "./internal/protocol-client-bridge.js";
 import { AithosSDKError } from "./types.js";
+/**
+ * The opt-in scope that authorizes a delegate to spend the subject's
+ * compute credits via the Aithos compute proxy. Mirror of
+ * `COMPUTE_INVOKE_SCOPE` in `@aithos/protocol-core` v0.4.0.
+ *
+ * The SDK's `mandates.create()` injects this scope automatically when
+ * the caller passes a `compute` namespace, and refuses to mint a
+ * mandate where the caller put it directly into `scopes` — this is
+ * what makes "compute is a separate, conscious decision" hold at the
+ * API surface.
+ */
+export const COMPUTE_INVOKE_SCOPE = "compute.invoke";
 export class MandatesNamespace {
     #deps;
     constructor(deps) {
@@ -29,12 +41,36 @@ export class MandatesNamespace {
      */
     async create(input) {
         const owner = this.#requireOwner();
-        if (input.scopes.length === 0) {
-            throw new AithosSDKError("mandates_invalid_scopes", "scopes must be a non-empty list");
+        // A mandate must carry at least one capability — either ethos
+        // scopes, the compute namespace, or both. A "compute-only" mandate
+        // (`scopes: []` + `compute: { ... }`) is legitimate: it gives the
+        // grantee no access to the subject's ethos data, only the right
+        // to spend a bounded amount of compute credits in their name.
+        // Useful for creative assistants, brainstorming agents, etc.
+        if (input.scopes.length === 0 && input.compute === undefined) {
+            throw new AithosSDKError("mandates_invalid_scopes", "scopes must be a non-empty list (or pass `compute` for a compute-only mandate)");
         }
         if (input.ttlSeconds <= 0) {
             throw new AithosSDKError("mandates_invalid_ttl", "ttlSeconds must be > 0");
         }
+        // Forbid `compute.invoke` smuggled in via `scopes[]`. The whole
+        // point of the dedicated `compute` namespace is that adding token-
+        // spending capability requires a typed, named, reviewable input —
+        // not a string lost in a generic list. Type-checking can't catch
+        // this (the union doesn't include the literal, but callers can
+        // up-cast); the runtime check is what holds.
+        if (input.scopes.some((s) => s === COMPUTE_INVOKE_SCOPE)) {
+            throw new AithosSDKError("mandates_invalid_scopes", `Pass token-spending capability via the dedicated 'compute' namespace, ` +
+                `not by adding "${COMPUTE_INVOKE_SCOPE}" to scopes[]. The namespace forces ` +
+                `an explicit budget and is what a consent UI reviews.`);
+        }
+        // Validate + project the compute namespace if present, then derive
+        // the final scopes/constraints to send to the protocol layer.
+        const computeProjection = projectCompute(input.compute);
+        const projectedScopes = [...input.scopes];
+        if (computeProjection) {
+            projectedScopes.push(COMPUTE_INVOKE_SCOPE);
+        }
         const actorSphere = input.actorSphere ?? defaultSphereFromScopes(input.scopes);
         const ownerStored = owner._unsafeStoredIdentity();
         const result = await mintDelegateBundle({
@@ -42,15 +78,27 @@ export class MandatesNamespace {
             granteeId: input.granteeId,
             ...(input.granteeLabel ? { granteeLabel: input.granteeLabel } : {}),
             actorSphere,
-            scopes: [...input.scopes],
+            scopes: projectedScopes,
             ttlSeconds: input.ttlSeconds,
+            // protocol-client v0.1.0-alpha.11 ships MandateConstraints without
+            // the `compute` field; the wire format accepts it though (the
+            // canonicalizer just serializes whatever's in the object). We
+            // up-cast through `unknown` to bypass the structural check until
+            // protocol-client picks up protocol-core 0.4.0 types.
+            ...(computeProjection
+                ? {
+                    constraints: {
+                        compute: computeProjection,
+                    },
+                }
+                : {}),
         });
         const mandate = result.mandate;
         return {
             mandateId: mandate.id,
             subjectDid: mandate.subject_did,
             granteeId: input.granteeId,
-            scopes: input.scopes,
+            scopes: projectedScopes,
             expiresAt: mandate.not_after ?? null,
             bundle: result.bundleBlob,
             filename: `aithos-delegate-${mandate.id}.json`,
@@ -164,6 +212,58 @@ function defaultSphereFromScopes(scopes) {
         return "circle";
     return "public";
 }
+/**
+ * Validate the SDK-side `compute` namespace and project it onto the
+ * snake_case shape the protocol layer canonicalizes into the mandate.
+ *
+ * Returns `null` if the caller passed nothing — that's the "no compute
+ * authorization" path. Throws {@link AithosSDKError} on any structural
+ * problem (camelCase mirror of the rules `validateComputeAuthorization`
+ * enforces server-side; we duplicate them here so a misuse fails at the
+ * SDK boundary with a precise error rather than only blowing up at mint).
+ */
+function projectCompute(c) {
+    if (c === undefined)
+        return null;
+    const hasDaily = typeof c.dailyCapMicrocredits === "number";
+    const hasTotal = typeof c.totalCapMicrocredits === "number";
+    if (!hasDaily && !hasTotal) {
+        throw new AithosSDKError("mandates_invalid_compute", "compute namespace requires at least one of dailyCapMicrocredits " +
+            "or totalCapMicrocredits — an unbounded compute mandate is a bearer " +
+            "token to drain the subject's wallet.");
+    }
+    for (const [field, value] of [
+        ["dailyCapMicrocredits", c.dailyCapMicrocredits],
+        ["totalCapMicrocredits", c.totalCapMicrocredits],
+        ["maxCreditsPerCall", c.maxCreditsPerCall],
+    ]) {
+        if (value === undefined)
+            continue;
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new AithosSDKError("mandates_invalid_compute", `compute.${field} must be a positive integer (got ${value}).`);
+        }
+    }
+    if (c.allowedModels !== undefined) {
+        if (!Array.isArray(c.allowedModels)) {
+            throw new AithosSDKError("mandates_invalid_compute", "compute.allowedModels must be an array of strings.");
+        }
+        for (const m of c.allowedModels) {
+            if (typeof m !== "string" || m.length === 0) {
+                throw new AithosSDKError("mandates_invalid_compute", `compute.allowedModels entries must be non-empty strings (got ${JSON.stringify(m)}).`);
+            }
+        }
+    }
+    const wire = {};
+    if (hasDaily)
+        wire.daily_cap_microcredits = c.dailyCapMicrocredits;
+    if (hasTotal)
+        wire.total_cap_microcredits = c.totalCapMicrocredits;
+    if (c.maxCreditsPerCall !== undefined)
+        wire.max_credits_per_call = c.maxCreditsPerCall;
+    if (c.allowedModels !== undefined)
+        wire.allowed_models = [...c.allowedModels];
+    return wire;
+}
 function toOwnedMandate(it) {
     return {
         mandateId: requireString(it, "mandate_id"),

package/dist/test/mandates-compute.test.d.ts

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

package/dist/test/mandates-compute.test.js

@@ -0,0 +1,256 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * Tests for the `compute` namespace on `MandatesNamespace.create`.
+ *
+ * Invariants under test (mirror of the protocol-core v0.4.0 invariants,
+ * enforced at the SDK boundary so callers fail fast with a precise
+ * error rather than only blowing up server-side):
+ *
+ *   1. Passing `compute.invoke` directly in `scopes[]` is rejected.
+ *      The opt-in must go through the typed `compute` namespace, which
+ *      is what a consent UI can review.
+ *   2. The `compute` namespace requires at least one of
+ *      `dailyCapMicrocredits` or `totalCapMicrocredits` — an unbounded
+ *      compute mandate is the bearer-token footgun this whole namespace
+ *      exists to prevent.
+ *   3. Numeric caps must be positive integers.
+ *   4. `allowedModels`, when present, must be an array of non-empty
+ *      strings.
+ *   5. A compute-only mandate (`scopes: []` + `compute: {…}`) is
+ *      legitimate and accepted — the grantee gets no ethos data
+ *      access, only bounded compute spending. Empty scopes WITHOUT
+ *      compute is still rejected.
+ *
+ * Network-dependent paths (real mint, list, revoke) ride on the same
+ * integration suite as the rest of the namespace — see the note in
+ * `mandates.test.ts`. We intentionally don't go through `mintDelegateBundle`
+ * here; failures fire BEFORE that boundary.
+ */
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { createBrowserIdentity } from "@aithos/protocol-client";
+import { AithosAuth, AithosSDKError, COMPUTE_INVOKE_SCOPE, MandatesNamespace, memoryKeyStore, noopStore, } from "../src/index.js";
+import { DEFAULT_SDK_ENDPOINTS } from "../src/endpoints.js";
+import { serializeRecoveryFile } from "../src/internal/recovery-file.js";
+function makeAuth() {
+    return new AithosAuth({
+        authBaseUrl: "https://auth.test",
+        fetch: (() => {
+            throw new Error("network not expected");
+        }),
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+}
+function makeMandates(auth) {
+    return new MandatesNamespace({
+        auth,
+        endpoints: DEFAULT_SDK_ENDPOINTS,
+        fetch: globalThis.fetch.bind(globalThis),
+    });
+}
+async function signInAsAlice(auth) {
+    const id = createBrowserIdentity("alice", "Alice");
+    const { text } = serializeRecoveryFile(id);
+    const info = await auth.signInWithRecovery({ file: text });
+    return info.did;
+}
+/* -------------------------------------------------------------------------- */
+/*  Constant export sanity                                                    */
+/* -------------------------------------------------------------------------- */
+describe("COMPUTE_INVOKE_SCOPE constant", () => {
+    it("is the canonical 'compute.invoke' string", () => {
+        assert.equal(COMPUTE_INVOKE_SCOPE, "compute.invoke");
+    });
+});
+/* -------------------------------------------------------------------------- */
+/*  Smuggling guard: compute.invoke in scopes[] is rejected                   */
+/* -------------------------------------------------------------------------- */
+describe("MandatesNamespace.create — compute.invoke smuggling guard", () => {
+    it("rejects a mandate that smuggles compute.invoke into scopes[]", async () => {
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const m = makeMandates(auth);
+        await assert.rejects(() => m.create({
+            granteeId: "urn:agent:bob",
+            // Up-cast through string[] — this is exactly the path the
+            // runtime check has to catch. Type-checking can't (the union
+            // doesn't include "compute.invoke", but cast slips through).
+            scopes: ["ethos.read.public", "compute.invoke"],
+            ttlSeconds: 3600,
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "mandates_invalid_scopes" &&
+            /compute' namespace/.test(e.message));
+    });
+    it("rejects even when 'compute.invoke' is the ONLY scope passed", async () => {
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const m = makeMandates(auth);
+        await assert.rejects(() => m.create({
+            granteeId: "urn:agent:bob",
+            scopes: ["compute.invoke"],
+            ttlSeconds: 3600,
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "mandates_invalid_scopes");
+    });
+});
+/* -------------------------------------------------------------------------- */
+/*  Compute namespace — input validation                                      */
+/* -------------------------------------------------------------------------- */
+describe("MandatesNamespace.create — compute namespace validation", () => {
+    it("rejects compute namespace with no caps at all", async () => {
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const m = makeMandates(auth);
+        await assert.rejects(() => m.create({
+            granteeId: "urn:agent:bob",
+            scopes: ["ethos.read.public"],
+            ttlSeconds: 3600,
+            compute: {}, // empty — neither daily nor total cap
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "mandates_invalid_compute" &&
+            /at least one of dailyCapMicrocredits or totalCapMicrocredits/.test(e.message));
+    });
+    it("rejects compute namespace with only allowedModels (no cap)", async () => {
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const m = makeMandates(auth);
+        await assert.rejects(() => m.create({
+            granteeId: "urn:agent:bob",
+            scopes: ["ethos.read.public"],
+            ttlSeconds: 3600,
+            compute: { allowedModels: ["claude-haiku-4-5"] },
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "mandates_invalid_compute");
+    });
+    it("rejects non-positive caps", async () => {
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const m = makeMandates(auth);
+        for (const bad of [0, -1, 3.14]) {
+            await assert.rejects(() => m.create({
+                granteeId: "urn:agent:bob",
+                scopes: ["ethos.read.public"],
+                ttlSeconds: 3600,
+                compute: { dailyCapMicrocredits: bad },
+            }), (e) => e instanceof AithosSDKError &&
+                e.code === "mandates_invalid_compute" &&
+                /must be a positive integer/.test(e.message), `expected rejection for dailyCapMicrocredits=${bad}`);
+        }
+    });
+    it("rejects malformed allowedModels (empty string entry)", async () => {
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const m = makeMandates(auth);
+        await assert.rejects(() => m.create({
+            granteeId: "urn:agent:bob",
+            scopes: ["ethos.read.public"],
+            ttlSeconds: 3600,
+            compute: {
+                dailyCapMicrocredits: 5_000,
+                allowedModels: ["claude-haiku-4-5", ""],
+            },
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "mandates_invalid_compute" &&
+            /allowedModels entries must be non-empty strings/.test(e.message));
+    });
+    it("rejects allowedModels that is not an array", async () => {
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const m = makeMandates(auth);
+        await assert.rejects(() => m.create({
+            granteeId: "urn:agent:bob",
+            scopes: ["ethos.read.public"],
+            ttlSeconds: 3600,
+            compute: {
+                dailyCapMicrocredits: 5_000,
+                // @ts-expect-error — runtime check guards against bad casts
+                allowedModels: "claude-haiku-4-5",
+            },
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "mandates_invalid_compute");
+    });
+});
+/* -------------------------------------------------------------------------- */
+/*  Read-only mandate is unaffected                                           */
+/* -------------------------------------------------------------------------- */
+describe("MandatesNamespace.create — read-only mandates unaffected", () => {
+    it("does NOT reject a clean read-only mandate (no compute, no smuggling)", async () => {
+        // We can't run the full mint here because the installed
+        // @aithos/protocol-core (0.5.1, pre-0.4.0-mandate) doesn't yet
+        // accept compute.invoke on the public sphere whitelist — the real
+        // mint would still succeed for a read-only mandate, but it goes
+        // out to S3 etc. Instead we check the synchronous validation
+        // surface: passing a clean read-only input must not throw before
+        // the mint call.
+        //
+        // (The async `m.create(...)` would still error later on the
+        // network path — that's the integration suite's job.)
+        //
+        // What we ARE asserting here: no SDK-side validation rejection.
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const m = makeMandates(auth);
+        // The mint will fail with a network error (fetch throws), but
+        // crucially NOT with a validation error — that proves our compute
+        // guard is precisely scoped to compute-related inputs.
+        await assert.rejects(() => m.create({
+            granteeId: "urn:viewer:bob",
+            scopes: ["ethos.read.public"],
+            ttlSeconds: 3600,
+        }), (e) => {
+            if (!(e instanceof AithosSDKError))
+                return true; // any non-validation error fine
+            const code = e.code;
+            // Anything except a validation rejection is fine — the network
+            // is not wired up in this fake auth.
+            return (code !== "mandates_invalid_scopes" &&
+                code !== "mandates_invalid_compute");
+        });
+    });
+});
+/* -------------------------------------------------------------------------- */
+/*  Compute-only mandate (scopes: [] + compute namespace)                     */
+/* -------------------------------------------------------------------------- */
+describe("MandatesNamespace.create — compute-only mandate", () => {
+    it("accepts an empty scopes[] when compute is provided (no ethos data access, just bounded spending)", async () => {
+        // Same caveat as the "read-only unaffected" suite: the installed
+        // @aithos/protocol-core does not yet whitelist compute.invoke on
+        // the public sphere, so the real `mintDelegateBundle` call would
+        // still reject downstream. What this test proves is that the
+        // SDK validation layer (a) does NOT throw `mandates_invalid_scopes`
+        // for the empty list when compute is set, and (b) does NOT throw
+        // `mandates_invalid_compute` for a properly-capped budget. The
+        // request is allowed to proceed past validation.
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const m = makeMandates(auth);
+        await assert.rejects(() => m.create({
+            granteeId: "urn:agent:creative",
+            scopes: [], // no ethos data access
+            ttlSeconds: 3600,
+            compute: { dailyCapMicrocredits: 1_000 },
+        }), (e) => {
+            if (!(e instanceof AithosSDKError))
+                return true;
+            const code = e.code;
+            // Validation must NOT have rejected this input.
+            return (code !== "mandates_invalid_scopes" &&
+                code !== "mandates_invalid_compute");
+        });
+    });
+    it("STILL rejects empty scopes[] when compute is NOT provided", async () => {
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const m = makeMandates(auth);
+        await assert.rejects(() => m.create({
+            granteeId: "urn:agent:bob",
+            scopes: [],
+            ttlSeconds: 3600,
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "mandates_invalid_scopes" &&
+            /compute-only mandate/.test(e.message));
+    });
+});
+//# sourceMappingURL=mandates-compute.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "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",