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

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/ethos.js

@@ -25,7 +25,7 @@
 // actor and forwards all real work into protocol-client's
 // `loadEditSnapshot` / `publishZoneEdit` / `publishPublicZoneAsDelegate`
 // / `publishPrivateZoneAsDelegate`.
-import { addSectionToList, deleteSectionFromList, loadEditSnapshot, modifySectionInList, publishPrivateZoneAsDelegate, publishPublicZoneAsDelegate, publishZoneEdit, } from "@aithos/protocol-client";
+import { addSectionToList, AithosRpcError, browserIdentityFromStored, buildSignedEnvelope, buildSignedFirstEditionFromSections, deleteSectionFromList, loadEditSnapshot, modifySectionInList, publishPrivateZoneAsDelegate, publishPublicZoneAsDelegate, publishZoneEdit, signedDidDocument, writeEndpoint, } from "@aithos/protocol-client";
 import { delegateKeyPair } from "./internal/protocol-client-bridge.js";
 import { AithosSDKError } from "./types.js";
 export const ZONE_NAMES = ["public", "circle", "self"];
@@ -38,6 +38,15 @@ export class EthosClient {
     #actor;
     #snapshots = new Map();
     #mutations = [];
+    /**
+     * Set to `true` when the server reports that no edition has been
+     * published yet for this subject (JSON-RPC code -32020 with the message
+     * `not found: edition for <did>`). Toggled lazily on the first read /
+     * publish attempt and cleared again after a successful first-edition
+     * publish so subsequent operations take the regular `publishZoneEdit`
+     * path.
+     */
+    #ethosHasNoEditionYet = false;
     constructor(actor) {
         this.#actor = actor;
         this.subjectDid = actor.subjectDid;
@@ -80,8 +89,15 @@ export class EthosClient {
         // have staged mutations for. Build everything we need then call
         // publishZoneEdit once.
         if (this.#actor.kind === "owner") {
-            // Need the snapshot regardless — we read base sections + zoneBytes.
-            const snap = await this.#ensureSnapshotOwner();
+            // First-edition path: no prior edition exists. Detected when the
+            // tolerant snapshot wrapper returned null on a previous read OR
+            // when this is the first network touch and the server responds
+            // with "not found: edition". Skip the snapshot fetch entirely and
+            // build a height=1 manifest from the staged mutations.
+            const snap = await this.#tryEnsureSnapshotOwner();
+            if (snap === null) {
+                return this.#publishFirstEditionOwner();
+            }
             const newPublic = touched.has("public")
                 ? this.#applyMutations("public", snap.publicSections)
                 : undefined;
@@ -175,12 +191,18 @@ export class EthosClient {
             if (zone !== "public") {
                 throw new AithosSDKError("ethos_anonymous_private_zone", `anonymous reader cannot access the "${zone}" zone`);
             }
-            const snap = await this.#ensureSnapshotAnonymous();
-            const base = snap.publicSections;
+            const snap = await this.#tryEnsureSnapshotAnonymous();
+            // No edition yet → no base sections; only staged mutations contribute.
+            const base = snap === null ? [] : snap.publicSections;
             return this.#applyMutations(zone, base);
         }
         if (this.#actor.kind === "owner") {
-            const snap = await this.#ensureSnapshotOwner();
+            const snap = await this.#tryEnsureSnapshotOwner();
+            if (snap === null) {
+                // No edition yet for this owner — base sections are empty in every
+                // zone. Staged mutations apply on top of an empty list.
+                return this.#applyMutations(zone, []);
+            }
             const base = baseSectionsFromSnapshot(snap, zone);
             // Surface decryption errors clearly (if reading a private zone we
             // can't unwrap, the snapshot has it in zoneDecryptErrors).
@@ -190,7 +212,10 @@ export class EthosClient {
             return this.#applyMutations(zone, base);
         }
         // Delegate
-        const snap = await this.#ensureSnapshotDelegate();
+        const snap = await this.#tryEnsureSnapshotDelegate();
+        if (snap === null) {
+            return this.#applyMutations(zone, []);
+        }
         const base = baseSectionsFromSnapshot(snap, zone);
         if (zone !== "public" && snap.zoneDecryptErrors?.[zone]) {
             throw new AithosSDKError("ethos_zone_unreadable", `cannot read ${zone}: ${snap.zoneDecryptErrors[zone]}`);
@@ -283,6 +308,57 @@ export class EthosClient {
         this.#cacheSnapshotAllZones(snap);
         return snap;
     }
+    /**
+     * Wrap {@link #ensureSnapshotOwner} so the "no edition published yet"
+     * server response (-32020 with message `not found: edition for <did>`)
+     * is converted into `null`. Once converted, {@link #ethosHasNoEditionYet}
+     * is set to short-circuit subsequent reads without re-hitting the network.
+     *
+     * Returns `null` to mean "subject has an identity but no editions yet —
+     * treat all zones as empty". Any other error is re-thrown.
+     */
+    async #tryEnsureSnapshotOwner() {
+        if (this.#ethosHasNoEditionYet)
+            return null;
+        try {
+            return await this.#ensureSnapshotOwner();
+        }
+        catch (e) {
+            if (isNoEditionYetError(e)) {
+                this.#ethosHasNoEditionYet = true;
+                return null;
+            }
+            throw e;
+        }
+    }
+    async #tryEnsureSnapshotDelegate() {
+        if (this.#ethosHasNoEditionYet)
+            return null;
+        try {
+            return await this.#ensureSnapshotDelegate();
+        }
+        catch (e) {
+            if (isNoEditionYetError(e)) {
+                this.#ethosHasNoEditionYet = true;
+                return null;
+            }
+            throw e;
+        }
+    }
+    async #tryEnsureSnapshotAnonymous() {
+        if (this.#ethosHasNoEditionYet)
+            return null;
+        try {
+            return await this.#ensureSnapshotAnonymous();
+        }
+        catch (e) {
+            if (isNoEditionYetError(e)) {
+                this.#ethosHasNoEditionYet = true;
+                return null;
+            }
+            throw e;
+        }
+    }
     #cacheSnapshotAllZones(snap) {
         for (const z of ZONE_NAMES)
             this.#snapshots.set(z, snap);
@@ -291,6 +367,110 @@ export class EthosClient {
         this.#mutations = [];
         this.#snapshots.clear();
     }
+    /* ------------------------------------------------------------------------ */
+    /*  First-edition publish (owner)                                           */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Publish height=1 for an owner whose Ethos identity exists on
+     * `api.aithos.be` (provisioned by `auth.signUp()` in alpha.6+) but who
+     * has no editions yet. Builds the manifest from the staged ADD
+     * mutations on the public zone and POSTs `aithos.publish_ethos_edition`.
+     *
+     * Limitations of the alpha.7 cut:
+     *   - Public zone only. Staged mutations on circle/self are rejected
+     *     with `ethos_first_edition_public_only` — those zones can be
+     *     populated in subsequent editions via the regular
+     *     `publishZoneEdit` path once the public zone has been seeded.
+     *   - First-edition publishes don't accept update/delete mutations
+     *     (there's nothing to update or delete yet) — those are rejected
+     *     with `ethos_first_edition_invalid_op`.
+     */
+    async #publishFirstEditionOwner() {
+        if (this.#actor.kind !== "owner") {
+            // Defensive — caller already checked this branch.
+            throw new AithosSDKError("ethos_invalid_actor", "expected owner actor");
+        }
+        // Validate the staged operation set. First edition = ADDs on public
+        // zone only.
+        const publicAdds = [];
+        for (const m of this.#mutations) {
+            if (m.kind !== "add") {
+                throw new AithosSDKError("ethos_first_edition_invalid_op", `first edition: cannot ${m.kind} a section before any edition exists; only addSection is supported on a fresh Ethos`, { data: { mutation: m } });
+            }
+            if (m.zone !== "public") {
+                throw new AithosSDKError("ethos_first_edition_public_only", `first edition: only the "public" zone is supported on a fresh Ethos; "${m.zone}" sections can be added after the first publish`, { data: { zone: m.zone } });
+            }
+            publicAdds.push({ section: m.section });
+        }
+        if (publicAdds.length === 0) {
+            // Should never reach here — publish() short-circuits on empty
+            // mutations. Belt-and-braces in case the contract drifts.
+            throw new AithosSDKError("ethos_first_edition_empty", "first edition: stage at least one public-zone section before publishing");
+        }
+        const identity = this.#actor.signers._unsafeStoredIdentity();
+        const browserId = browserIdentityFromStored(identity);
+        const signedDoc = signedDidDocument(browserId);
+        const built = buildSignedFirstEditionFromSections({
+            identity: browserId,
+            signedDidDoc: signedDoc,
+            publicSections: publicAdds.map((a) => a.section),
+        });
+        const url = writeEndpoint();
+        const params = {
+            manifest: built.manifest,
+            zones: {
+                public: { bytes_base64: bytesToBase64Padded(built.publicMarkdownBytes) },
+            },
+        };
+        const envelope = buildSignedEnvelope({
+            iss: browserId.did,
+            aud: url,
+            method: "aithos.publish_ethos_edition",
+            verificationMethod: `${browserId.did}#public`,
+            params,
+            signer: browserId.public,
+        });
+        const body = JSON.stringify({
+            jsonrpc: "2.0",
+            id: "publish_ethos_edition",
+            method: "aithos.publish_ethos_edition",
+            params: { ...params, _envelope: envelope },
+        });
+        let res;
+        try {
+            res = await fetch(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body,
+            });
+        }
+        catch (e) {
+            throw new AithosSDKError("ethos_publish_network", `publish_ethos_edition (first edition): network error: ${e.message ?? "unknown"}`);
+        }
+        let json;
+        try {
+            json = (await res.json());
+        }
+        catch {
+            throw new AithosSDKError("ethos_publish_invalid_response", `publish_ethos_edition (first edition): server returned non-JSON (HTTP ${res.status})`);
+        }
+        if (json.error) {
+            throw new AithosSDKError("ethos_first_edition_rejected", `publish_ethos_edition (first edition) rejected: ${json.error.message}`, {
+                status: res.status,
+                data: { rpc_code: json.error.code, ...(json.error.data ?? {}) },
+            });
+        }
+        // Success: clear the no-edition flag so subsequent reads/publishes
+        // take the regular next-edition path.
+        this.#ethosHasNoEditionYet = false;
+        this.#afterPublish();
+        return {
+            editionHeight: 1,
+            manifestHash: "", // protocol-client surfaces this on later editions; not on first
+            subjectDid: browserId.did,
+            zonesPublished: ["public"],
+        };
+    }
 }
 /* -------------------------------------------------------------------------- */
 /*  EthosZone — per-zone proxy                                                */
@@ -410,6 +590,36 @@ function projectPublishResult(manifest, subjectDid, zones) {
         zonesPublished: zones,
     };
 }
+/**
+ * Detect the server-side "no edition published yet" response. Matches the
+ * exact error shape emitted by primitives-read's `notFound("edition for
+ * <did>")` helper: JSON-RPC code -32020 + message starting with `not
+ * found: edition for `. Other -32020 cases (e.g. "not found: manifest
+ * <did>@<height>" raised when the index advertises an edition the S3
+ * bucket can't serve) deliberately fall through — they're symptoms, not
+ * the "fresh subject" case we're trying to swallow.
+ */
+function isNoEditionYetError(e) {
+    if (!(e instanceof AithosRpcError))
+        return false;
+    if (e.code !== -32020)
+        return false;
+    return typeof e.message === "string"
+        && e.message.startsWith("not found: edition for ");
+}
+/**
+ * Standard base64 with `=` padding — matches what protocol-client's
+ * publishZoneEdit uses for `zones.<zone>.bytes_base64`. The server is
+ * tolerant of either padded or unpadded variants per the API contract,
+ * but we mirror the existing wire to keep payloads byte-identical for
+ * easy diffing in dev tools.
+ */
+function bytesToBase64Padded(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
 function randomHex(n) {
     const bytes = new Uint8Array(Math.ceil(n / 2));
     crypto.getRandomValues(bytes);

package/dist/src/index.d.ts

@@ -2,20 +2,21 @@ export declare const VERSION = "0.1.0-alpha.5";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 export { AithosSDKError } from "./types.js";
+export { AithosRpcError } from "@aithos/protocol-client";
 export type { AithosSdkEndpoints } from "./endpoints.js";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
 export type { ComputeMessage, InvokeBedrockArgs, InvokeBedrockResult, StopReason, } from "./compute.js";
 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

@@ -20,6 +20,10 @@
 export const VERSION = "0.1.0-alpha.5";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
+// Re-export protocol-client's JSON-RPC error type so consumers can
+// `instanceof`-check server-side errors and inspect the JSON-RPC code
+// without taking a direct dependency on @aithos/protocol-client.
+export { AithosRpcError } from "@aithos/protocol-client";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
 export { ComputeNamespace } from "./compute.js";
 export { WalletNamespace } from "./wallet.js";
@@ -28,7 +32,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 +50,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/ethos-first-edition.test.d.ts

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

package/dist/test/ethos-first-edition.test.js

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Tests for the alpha.7 first-edition path in EthosClient — the case
+// where an Ethos identity exists on api.aithos.be (provisioned by
+// auth.signUp() since alpha.6) but no edition has been published yet.
+//
+// Two flows must work:
+//   1. Reading any zone returns an empty list (instead of throwing
+//      "not found: edition").
+//   2. Publishing for the first time builds height=1 from staged
+//      mutations and POSTs publish_ethos_edition directly, instead
+//      of going through publishZoneEdit (which requires a previous
+//      manifest).
+//
+// We mock global fetch end-to-end so the tests run offline.
+import { strict as assert } from "node:assert";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { createBrowserIdentity } from "@aithos/protocol-client";
+import { AithosAuth, AithosSDKError, EthosNamespace, memoryKeyStore, noopStore, } from "../src/index.js";
+import { serializeRecoveryFile } from "../src/internal/recovery-file.js";
+import { DEFAULT_SDK_ENDPOINTS } from "../src/endpoints.js";
+let fetchCalls = [];
+let savedFetch;
+function installFetchMock(handlers) {
+    savedFetch = globalThis.fetch;
+    fetchCalls = [];
+    globalThis.fetch = (async (input, init) => {
+        const url = String(input);
+        const method = init?.method ?? "GET";
+        const bodyText = typeof init?.body === "string"
+            ? init.body
+            : init?.body == null
+                ? null
+                : String(init.body);
+        const body = bodyText ? JSON.parse(bodyText) : null;
+        const call = { url, method, body };
+        fetchCalls.push(call);
+        for (const h of handlers) {
+            if (!url.includes(h.url))
+                continue;
+            if (h.rpcMethod && body?.method !== h.rpcMethod)
+                continue;
+            const out = h.respond(call);
+            const status = out.status ?? 200;
+            return new Response(JSON.stringify(out.json), {
+                status,
+                headers: { "content-type": "application/json" },
+            });
+        }
+        throw new Error(`unhandled fetch: ${method} ${url} (rpc: ${body?.method ?? "n/a"})`);
+    });
+}
+function uninstallFetchMock() {
+    if (savedFetch) {
+        globalThis.fetch = savedFetch;
+        savedFetch = undefined;
+    }
+    fetchCalls = [];
+}
+function makeAuth() {
+    return new AithosAuth({
+        authBaseUrl: "https://auth.test",
+        apiBaseUrl: "https://api.test",
+        fetch: (() => {
+            throw new Error("AithosAuth.fetch must not be called in these tests");
+        }),
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+}
+function makeNamespace(auth) {
+    return new EthosNamespace({
+        auth,
+        endpoints: DEFAULT_SDK_ENDPOINTS,
+        // EthosNamespace itself doesn't read fetch from this slot today;
+        // protocol-client uses the global fetch we mock above.
+        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 { did: info.did };
+}
+function noEditionYetResponse() {
+    // Mirrors the server's primitives-read `notFound("edition for <did>")`:
+    // JSON-RPC error code -32020, message starts with "not found: edition for ".
+    return {
+        json: {
+            jsonrpc: "2.0",
+            id: "aithos.get_ethos_manifest",
+            error: {
+                code: -32020,
+                message: "not found: edition for did:aithos:zSomething",
+            },
+        },
+    };
+}
+function publishOkResponse() {
+    return {
+        json: {
+            jsonrpc: "2.0",
+            id: "publish_ethos_edition",
+            result: { ok: true, height: 1, manifest_uri: "s3://aithos/.../manifest.json" },
+        },
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  Tests                                                                     */
+/* -------------------------------------------------------------------------- */
+describe("EthosClient — fresh Ethos (no edition published yet)", () => {
+    beforeEach(() => {
+        fetchCalls = [];
+    });
+    afterEach(() => {
+        uninstallFetchMock();
+    });
+    it("zone(public).sections() returns [] when server says 'not found: edition'", async () => {
+        installFetchMock([
+            {
+                url: "/mcp/primitives/read",
+                rpcMethod: "aithos.get_ethos_manifest",
+                respond: noEditionYetResponse,
+            },
+        ]);
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        const sections = await me.zone("public").sections();
+        assert.deepEqual(sections, []);
+    });
+    it("zone(public).sections() reflects locally staged adds even when no edition exists", async () => {
+        installFetchMock([
+            {
+                url: "/mcp/primitives/read",
+                rpcMethod: "aithos.get_ethos_manifest",
+                respond: noEditionYetResponse,
+            },
+        ]);
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        me.zone("public").addSection({ title: "Hello", body: "World" });
+        const sections = await me.zone("public").sections();
+        assert.equal(sections.length, 1);
+        assert.equal(sections[0].title, "Hello");
+    });
+    it("publish() routes to publish_ethos_edition with height=1 on first publish", async () => {
+        let publishBody = null;
+        installFetchMock([
+            {
+                url: "/mcp/primitives/read",
+                rpcMethod: "aithos.get_ethos_manifest",
+                respond: noEditionYetResponse,
+            },
+            {
+                url: "/mcp/primitives/write",
+                rpcMethod: "aithos.publish_ethos_edition",
+                respond: (call) => {
+                    publishBody = call.body;
+                    return publishOkResponse();
+                },
+            },
+        ]);
+        const auth = makeAuth();
+        const alice = await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        me.zone("public").addSection({ title: "First", body: "Hello." });
+        me.zone("public").addSection({ title: "Second", body: "World." });
+        const r = await me.publish();
+        assert.equal(r.editionHeight, 1);
+        assert.equal(r.subjectDid, alice.did);
+        assert.deepEqual(r.zonesPublished, ["public"]);
+        // Verify the wire shape: JSON-RPC publish_ethos_edition with a height=1
+        // manifest containing both staged sections.
+        assert.equal(publishBody.method, "aithos.publish_ethos_edition");
+        const manifest = publishBody.params.manifest;
+        assert.equal(manifest.edition.height, 1);
+        assert.equal(manifest.edition.prev_hash, null);
+        assert.equal(manifest.edition.supersedes, null);
+        assert.deepEqual(manifest.zones.public.section_titles, ["First", "Second"]);
+        // Envelope is signed under #public.
+        const env = publishBody.params._envelope;
+        assert.equal(env.method, "aithos.publish_ethos_edition");
+        assert.match(env.proof.verificationMethod, /#public$/);
+    });
+    it("publish() rejects circle/self mutations on first edition", async () => {
+        installFetchMock([
+            {
+                url: "/mcp/primitives/read",
+                rpcMethod: "aithos.get_ethos_manifest",
+                respond: noEditionYetResponse,
+            },
+        ]);
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        me.zone("circle").addSection({ title: "Private", body: "..." });
+        await assert.rejects(() => me.publish(), (e) => e instanceof AithosSDKError && e.code === "ethos_first_edition_public_only");
+    });
+    it("publish() rejects update/delete operations on a fresh Ethos", async () => {
+        installFetchMock([
+            {
+                url: "/mcp/primitives/read",
+                rpcMethod: "aithos.get_ethos_manifest",
+                respond: noEditionYetResponse,
+            },
+        ]);
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        // Stage a delete for a section that doesn't exist (no edition exists at all).
+        me.zone("public")["_parent"]; // type-safety placeholder; we use the public API
+        // EthosZone exposes deleteSection — go via that.
+        me.zone("public").deleteSection("sec_doesnotexist000");
+        await assert.rejects(() => me.publish(), (e) => e instanceof AithosSDKError && e.code === "ethos_first_edition_invalid_op");
+    });
+    it("publish() surfaces server JSON-RPC errors as ethos_first_edition_rejected", async () => {
+        installFetchMock([
+            {
+                url: "/mcp/primitives/read",
+                rpcMethod: "aithos.get_ethos_manifest",
+                respond: noEditionYetResponse,
+            },
+            {
+                url: "/mcp/primitives/write",
+                rpcMethod: "aithos.publish_ethos_edition",
+                respond: () => ({
+                    json: {
+                        jsonrpc: "2.0",
+                        id: "publish_ethos_edition",
+                        error: {
+                            code: -32020,
+                            message: "subject identity not published (call publish_identity first)",
+                        },
+                    },
+                }),
+            },
+        ]);
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        me.zone("public").addSection({ title: "Hi", body: "There." });
+        await assert.rejects(() => me.publish(), (e) => e instanceof AithosSDKError && e.code === "ethos_first_edition_rejected");
+    });
+});
+//# sourceMappingURL=ethos-first-edition.test.js.map

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.7",
   "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.11 <0.2.0"
+    "@aithos/protocol-client": ">=0.1.0-alpha.12 <0.2.0"
   },
   "devDependencies": {
-    "@aithos/protocol-client": "^0.1.0-alpha.11",
+    "@aithos/protocol-client": "^0.1.0-alpha.12",
     "@types/node": "^24.12.2",
     "fake-indexeddb": "^6.2.5",
     "typescript": "^5.9.2"