@aithos/sdk 0.1.0-alpha.44 → 0.1.0-alpha.45

package/dist/src/data.d.ts

@@ -1,3 +1,4 @@
+import { type SignedMandate } from "@aithos/protocol-client";
 export interface AithosSchemaLite {
     readonly schema: string;
     readonly indexable: ReadonlySet<string>;
@@ -45,12 +46,26 @@ export interface CreateDataClientArgs {
 export interface DataClient {
     /** Get / create a collection handle. */
     collection(name: string): DataCollection;
-    /** Initialize a new collection with an explicit schema. */
+    /** Initialize a new collection with an explicit schema. Throws
+     * `-32073 AITHOS_DATA_COLLECTION_EXISTS` if it already exists. */
     createCollection(args: {
         name: string;
         schema: string;
         forwardSecrecy?: "best_effort" | "strict";
     }): Promise<void>;
+    /**
+     * Get-or-create: create the collection if it doesn't exist, otherwise
+     * succeed silently. Idempotent — safe to call on every app boot before
+     * writing. Absorbs the `-32073 AITHOS_DATA_COLLECTION_EXISTS` conflict
+     * (and the concurrent-create race) so callers don't have to special-case
+     * "already there". Avoids the friction where `collection(name).insert(…)`
+     * on a never-created collection fails with `-32020`.
+     */
+    ensureCollection(args: {
+        name: string;
+        schema: string;
+        forwardSecrecy?: "best_effort" | "strict";
+    }): Promise<void>;
     /** List collections owned by this subject. */
     listCollections(): Promise<readonly {
         name: string;
@@ -102,9 +117,83 @@ export interface DataClient {
     getSchema(schemaId: string, opts?: {
         subjectDid?: string;
     }): Promise<object | null>;
+    /**
+     * Grant a mandate-holding delegate read access to one of this owner's
+     * collections, by re-wrapping the collection's CMK to the grantee's
+     * key and posting `aithos.data.authorize_app`.
+     *
+     * Owner-only. The CMK is unwrapped locally (the owner holds it), then
+     * re-wrapped X25519-HKDF-AEAD to the grantee's X25519 key (derived
+     * from `mandate.grantee.pubkey`). The platform never sees the CMK in
+     * clear — it only appends the wrap to the collection's envelope after
+     * verifying the mandate (data spec §4.5).
+     *
+     * Idempotent at the server: re-authorizing the same grantee on the
+     * same collection is a no-op. One wrap per grantee covers every record
+     * in the collection (O(1) authorization — the CMK is stable).
+     *
+     * The mandate must carry a `data.<collectionName>.{read|write|admin}`
+     * or `data.*.*` scope and a `grantee.pubkey`.
+     */
+    authorizeDelegate(args: {
+        collectionName: string;
+        mandate: SignedMandate;
+    }): Promise<void>;
+    /**
+     * Revoke a delegate's access to a collection (`aithos.data.revoke_app`).
+     * Owner-only, forward-only: after revocation the PDS refuses the
+     * delegate's reads (the mandate is marked revoked), and the delegate's
+     * wrap is dropped from the collection's authorization index. Already-read
+     * / cached plaintext on the delegate side is out of scope (a known limit
+     * of any key-sharing scheme — revocation blocks FUTURE access).
+     */
+    revokeDelegate(args: {
+        collectionName: string;
+        mandateId: string;
+        reason?: string;
+    }): Promise<void>;
+    /** Drop in-memory cache (CMK, collection metadata, …). */
+    reset(): void;
+}
+/**
+ * Read-only view over a subject's data collections, driven by a mandate
+ * the subject granted to a delegate (`data.<collection>.read`). Built by
+ * {@link createDelegateDataClient}.
+ *
+ * Mirror of {@link DataClient} minus every mutating verb: a delegate
+ * holding a read mandate can `get`/`list` and enumerate collections, but
+ * cannot insert, update, delete, create collections, register schemas, or
+ * re-delegate. Those throw `-32042` client-side (and the PDS rejects them
+ * server-side regardless).
+ */
+export interface ReadonlyDataClient {
+    /** Get a read-only collection handle. */
+    collection(name: string): ReadonlyDataCollection;
+    /** List collections the delegate's mandate scopes can reach. */
+    listCollections(): Promise<readonly {
+        name: string;
+        schema: string;
+        record_count: number;
+    }[]>;
+    /** List gamma audit entries (read). */
+    listGammaEntries(opts?: {
+        limit?: number;
+        opPrefix?: string;
+        verify?: boolean;
+    }): Promise<unknown>;
     /** Drop in-memory cache (CMK, collection metadata, …). */
     reset(): void;
 }
+export interface ReadonlyDataCollection {
+    readonly name: string;
+    /** Fetch one record by id (decrypted client-side via the re-wrapped CMK). */
+    get(recordId: string): Promise<Record<string, unknown> | null>;
+    /** List records, decrypted. Pagination via opaque cursor. */
+    list(opts?: ListOpts): Promise<{
+        items: Record<string, unknown>[];
+        nextCursor?: string;
+    }>;
+}
 export interface DataCollection {
     readonly name: string;
     /**
@@ -150,4 +239,42 @@ export interface ListOpts {
     readonly cursor?: string;
 }
 export declare function createDataClient(args: CreateDataClientArgs): DataClient;
+export interface CreateDelegateDataClientArgs {
+    /** PDS base URL (same endpoint the owner writes to). */
+    readonly pdsUrl: string;
+    /** DID of the SUBJECT whose data is being read (the mandate issuer). */
+    readonly subjectDid: string;
+    /**
+     * The full signed mandate the subject granted to this delegate. Must
+     * carry a `data.<collection>.read` (or wider) scope and a
+     * `grantee.pubkey` matching `delegateSeed`.
+     */
+    readonly mandate: SignedMandate;
+    /** The delegate's Ed25519 seed (32 bytes) — the grantee key the mandate
+     * is bound to. Used to sign envelopes AND to derive the X25519 key that
+     * unwraps the re-wrapped CMK. */
+    readonly delegateSeed: Uint8Array;
+    /**
+     * The delegate's Ed25519 public key, multibase-encoded. Defaults to
+     * `mandate.grantee.pubkey`. This is the bare verificationMethod the PDS
+     * binds the delegate envelope to.
+     */
+    readonly granteePubkeyMultibase?: string;
+    /** App-defined (vendor) schemas, as for {@link createDataClient}. */
+    readonly schemas?: readonly AithosSchemaLite[];
+    /** `fetch` override (tests). */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Build a read-only data client that reads a subject's collections under
+ * a mandate (delegate path). The returned {@link ReadonlyDataClient}
+ * signs every request as the delegate (bare-multibase verificationMethod
+ * + the mandate attached to the envelope), and decrypts records using the
+ * CMK the owner re-wrapped for this delegate via
+ * {@link DataClient.authorizeDelegate}.
+ *
+ * Writes are not available on the returned type and throw `-32042` if
+ * forced.
+ */
+export declare function createDelegateDataClient(args: CreateDelegateDataClientArgs): ReadonlyDataClient;
 //# sourceMappingURL=data.d.ts.map

package/dist/src/data.js

@@ -38,6 +38,7 @@ import { hkdf } from "@noble/hashes/hkdf.js";
 import { sha256, sha512 } from "@noble/hashes/sha2.js";
 import { XChaCha20Poly1305 } from "@stablelib/xchacha20poly1305";
 import * as ed from "@noble/ed25519";
+import { multibaseToEd25519PublicKey, edPubToX25519Pub, } from "@aithos/protocol-client";
 import { contactsV1 } from "./data-schema-contacts-v1.js";
 import { signOwnerEnvelope } from "./internal/envelope.js";
 // noble/ed25519 v2 needs sha512 wired in for sync sign/verify
@@ -57,15 +58,48 @@ const SCHEMAS = new Map([
 export function createDataClient(args) {
     return new DataClientImpl(args);
 }
-/* -------------------------------------------------------------------------- */
-/*  Implementation                                                            */
-/* -------------------------------------------------------------------------- */
+/**
+ * Build a read-only data client that reads a subject's collections under
+ * a mandate (delegate path). The returned {@link ReadonlyDataClient}
+ * signs every request as the delegate (bare-multibase verificationMethod
+ * + the mandate attached to the envelope), and decrypts records using the
+ * CMK the owner re-wrapped for this delegate via
+ * {@link DataClient.authorizeDelegate}.
+ *
+ * Writes are not available on the returned type and throw `-32042` if
+ * forced.
+ */
+export function createDelegateDataClient(args) {
+    const granteePubMb = args.granteePubkeyMultibase ??
+        args.mandate.grantee?.pubkey;
+    if (!granteePubMb) {
+        throw new Error("createDelegateDataClient: mandate.grantee.pubkey is missing; pass granteePubkeyMultibase explicitly");
+    }
+    return new DataClientImpl({
+        pdsUrl: args.pdsUrl,
+        did: args.subjectDid,
+        // In delegate mode the seed is used only to derive the X25519 key that
+        // unwraps the re-wrapped CMK; envelope signing goes through the
+        // delegate path (buildSignedEnvelope), never signOwnerEnvelope.
+        sphereSeed: args.delegateSeed,
+        verificationMethod: granteePubMb,
+        ...(args.schemas ? { schemas: args.schemas } : {}),
+        ...(args.fetch ? { fetch: args.fetch } : {}),
+        delegate: {
+            delegateSeed: args.delegateSeed,
+            granteePubkeyMultibase: granteePubMb,
+            mandate: args.mandate,
+        },
+    });
+}
 class DataClientImpl {
     #pdsUrl;
     #did;
     #seed;
     #vm;
     #fetch;
+    /** Delegate session, or undefined for the owner path. */
+    #delegate;
     /**
      * Per-client schema overrides, populated from `args.schemas` at
      * construction. Looked up BEFORE the bundled SCHEMAS map (so an app
@@ -82,8 +116,22 @@ class DataClientImpl {
         this.#seed = args.sphereSeed;
         this.#vm = args.verificationMethod;
         this.#fetch = args.fetch ?? globalThis.fetch.bind(globalThis);
+        if (args.delegate)
+            this.#delegate = args.delegate;
         this.#localSchemas = new Map((args.schemas ?? []).map((s) => [s.schema, s]));
     }
+    /** Throw a read-only error when a mutating verb is called on a delegate
+     * client. The PDS rejects these server-side too; this is the fast,
+     * local guard with a precise message. */
+    #assertOwner(op) {
+        if (this.#delegate) {
+            const e = new Error(`sdk.data: "${op}" is not permitted for a delegate client (read-only mandate). ` +
+                `A data.<collection>.read mandate grants get/list only; writes require the owner ` +
+                `or a data.<collection>.write mandate (not yet supported on the delegate path).`);
+            e.code = -32042;
+            throw e;
+        }
+    }
     /**
      * Resolve a schema id to its lite definition. App-supplied schemas
      * (via `createDataClient({ schemas })`) take precedence over the
@@ -95,7 +143,45 @@ class DataClientImpl {
     collection(name) {
         return new DataCollectionImpl(this, name);
     }
+    async authorizeDelegate(args) {
+        this.#assertOwner("authorizeDelegate");
+        const granteePubMb = args.mandate.grantee?.pubkey;
+        if (!granteePubMb) {
+            throw new Error("sdk.data.authorizeDelegate: mandate.grantee.pubkey is required (data read mandates bind to a grantee key).");
+        }
+        // Ensure we hold the collection's CMK (owner unwrap path).
+        const state = await this._ensureCollection(args.collectionName);
+        const cmk = this.#cmkCache.get(args.collectionName);
+        if (!cmk) {
+            throw new Error(`sdk.data.authorizeDelegate: CMK for "${args.collectionName}" not loaded`);
+        }
+        // Derive the grantee's X25519 wrap-recipient key from its Ed25519
+        // public key (the same birational map the owner uses for its own key).
+        const granteeEdPub = multibaseToEd25519PublicKey(granteePubMb);
+        const granteeX25519Pub = edPubToX25519Pub(granteeEdPub);
+        const recipientDidUrl = delegateRecipientDidUrl(granteePubMb);
+        const wrap = this.#wrapCmkForRecipient({
+            cmk,
+            recipientPublicKey: granteeX25519Pub,
+            recipientDidUrl,
+            collectionUrn: state.urn,
+        });
+        await this.#call("/mcp/primitives/write", "aithos.data.authorize_app", {
+            collection_urn: state.urn,
+            mandate: args.mandate,
+            wrap,
+        });
+    }
+    async revokeDelegate(args) {
+        this.#assertOwner("revokeDelegate");
+        await this.#call("/mcp/primitives/write", "aithos.data.revoke_app", {
+            collection_urn: this.#collectionUrn(args.collectionName),
+            mandate_id: args.mandateId,
+            ...(args.reason ? { revocation: { reason: args.reason } } : {}),
+        });
+    }
     async createCollection(args) {
+        this.#assertOwner("createCollection");
         const cmk = randomBytes32();
         const recipientDidUrl = `${this.#did}#data-kex`;
         const collectionUrn = this.#collectionUrn(args.name);
@@ -124,6 +210,20 @@ class DataClientImpl {
             // CMK is retained in cache, only zero the local var if we didn't cache.
         }
     }
+    async ensureCollection(args) {
+        this.#assertOwner("ensureCollection");
+        try {
+            await this.createCollection(args);
+        }
+        catch (e) {
+            // -32073 AITHOS_DATA_COLLECTION_EXISTS → already created (possibly by a
+            // concurrent caller). That's the success case for get-or-create. Any
+            // other error propagates.
+            if (e.code === -32073)
+                return;
+            throw e;
+        }
+    }
     async listCollections() {
         const r = await this.#call("/mcp/primitives/read", "aithos.data.list_collections", {
             subject_did: this.#did,
@@ -146,6 +246,7 @@ class DataClientImpl {
         return this.#call("/mcp/primitives/read", "aithos.data.list_gamma_entries", params);
     }
     async registerSchema(schemaDoc) {
+        this.#assertOwner("registerSchema");
         if (schemaDoc === null || typeof schemaDoc !== "object" || Array.isArray(schemaDoc)) {
             throw new Error("sdk.data.registerSchema: schemaDoc must be a JSON object");
         }
@@ -210,16 +311,27 @@ class DataClientImpl {
             err.code = -32020;
             throw err;
         }
-        // Look up our wrap and unwrap the CMK
-        const ourRecipient = `${this.#did}#data-kex`;
+        // Look up our wrap and unwrap the CMK. Owner: the wrap addressed to
+        // `${did}#data-kex`, unwrapped with the owner sphere seed. Delegate:
+        // the wrap the owner re-wrapped for this grantee
+        // (`did:key:${granteePubkeyMultibase}#data-kex`), unwrapped with the
+        // delegate's own X25519 key (derived from its grantee seed).
+        const ourRecipient = this.#delegate
+            ? delegateRecipientDidUrl(this.#delegate.granteePubkeyMultibase)
+            : `${this.#did}#data-kex`;
         const wrap = meta.cmk_envelope.wraps.find((w) => w.recipient === ourRecipient);
         if (!wrap) {
-            throw new Error(`sdk.data: no CMK wrap for ${ourRecipient} in collection ${name}. The collection was either created with a different recipient, or this client is not the owner.`);
+            throw new Error(this.#delegate
+                ? `sdk.data: no CMK wrap for ${ourRecipient} in collection "${name}". ` +
+                    `The owner has not authorized this delegate on the collection yet — ` +
+                    `ask them to call sdk.data...authorizeDelegate({ collectionName, mandate }).`
+                : `sdk.data: no CMK wrap for ${ourRecipient} in collection ${name}. The collection was either created with a different recipient, or this client is not the owner.`);
         }
+        const unwrapSeed = this.#delegate ? this.#delegate.delegateSeed : this.#seed;
         const cmk = this.#unwrapCmk({
             wrap,
             collectionUrn: meta.urn,
-            privateKey: ed25519SeedToX25519PrivateKey(this.#seed),
+            privateKey: ed25519SeedToX25519PrivateKey(unwrapSeed),
         });
         this.#cmkCache.set(name, cmk);
         const schema = this.#resolveSchema(meta.schema);
@@ -234,6 +346,7 @@ class DataClientImpl {
         return state;
     }
     async _insert(state, record) {
+        this.#assertOwner("insert");
         const cmk = this.#cmkCache.get(state.name);
         if (!cmk)
             throw new Error("CMK not loaded");
@@ -288,6 +401,7 @@ class DataClientImpl {
         };
     }
     async _update(state, recordId, record) {
+        this.#assertOwner("update");
         const cmk = this.#cmkCache.get(state.name);
         if (!cmk)
             throw new Error("CMK not loaded");
@@ -306,6 +420,7 @@ class DataClientImpl {
         });
     }
     async _delete(state, recordId) {
+        this.#assertOwner("delete");
         await this.#call("/mcp/primitives/write", "aithos.data.delete_record", {
             collection_urn: state.urn,
             record_id: recordId,
@@ -314,14 +429,31 @@ class DataClientImpl {
     /* -- JSON-RPC dispatch -- */
     async #call(path, method, params) {
         const aud = `${this.#pdsUrl}${path}`;
-        const envelope = await signOwnerEnvelope({
-            iss: this.#did,
-            aud,
-            method,
-            params,
-            verificationMethod: this.#vm,
-            signer: { sign: async (msg) => ed.sign(msg, this.#seed) },
-        });
+        // Both paths use the SAME §11.2 envelope scheme (the data PDS verifies
+        // with @aithos/protocol-core, which canonicalizes the full envelope
+        // INCLUDING `proof` with proofValue=""). Delegate path: sign with the
+        // grantee key, bare-multibase verificationMethod, and attach the mandate
+        // so the PDS resolves the delegation and enforces its scopes.
+        const envelope = this.#delegate
+            ? await signOwnerEnvelope({
+                iss: this.#did, // the SUBJECT DID (mandate issuer), not the delegate
+                aud,
+                method,
+                params,
+                verificationMethod: this.#delegate.granteePubkeyMultibase,
+                signer: {
+                    sign: async (msg) => ed.sign(msg, this.#delegate.delegateSeed),
+                },
+                mandate: this.#delegate.mandate,
+            })
+            : await signOwnerEnvelope({
+                iss: this.#did,
+                aud,
+                method,
+                params,
+                verificationMethod: this.#vm,
+                signer: { sign: async (msg) => ed.sign(msg, this.#seed) },
+            });
         const body = {
             jsonrpc: "2.0",
             id: makeUlid(),
@@ -508,6 +640,18 @@ function cryptoRandom(n) {
 function utf8(s) {
     return new TextEncoder().encode(s);
 }
+/**
+ * Recipient DID URL used for a delegate's CMK wrap. Built from the
+ * grantee's Ed25519 public-key multibase so that (a) the owner side
+ * (`authorizeDelegate`) and the delegate side (`_ensureCollection`)
+ * derive the EXACT same string — it's bound into the wrap AAD and the
+ * HKDF info, so any mismatch fails the unwrap — and (b) the string
+ * contains `mandate.grantee.pubkey`, which the PDS `authorize_app`
+ * handler requires (`wrap.recipient.includes(grantee.pubkey)`).
+ */
+function delegateRecipientDidUrl(granteePubkeyMultibase) {
+    return `did:key:${granteePubkeyMultibase}#data-kex`;
+}
 function aadCmkWrap(collectionUrn, recipient) {
     const p = utf8("aithos-data-cmk-v1\0");
     const c = utf8(collectionUrn);

package/dist/src/index.d.ts

@@ -27,6 +27,6 @@ export type { AudienceSet, AppCreditPackId, CreateAppTopupSessionArgs, CreateApp
 export * as onboarding from "./onboarding.js";
 export { createBrowserIdentity, browserIdentityFromStored, type BrowserIdentity, } from "@aithos/protocol-client";
 export type { Section } from "@aithos/protocol-client";
-export { createDataClient, type CreateDataClientArgs, type DataClient, type DataCollection, type ListOpts, type AithosSchemaLite, } from "./data.js";
+export { createDataClient, createDelegateDataClient, type CreateDataClientArgs, type CreateDelegateDataClientArgs, type DataClient, type DataCollection, type ReadonlyDataClient, type ReadonlyDataCollection, type ListOpts, type AithosSchemaLite, } from "./data.js";
 export { createAssetsClient, AssetsClient, type CreateAssetsClientArgs, type AttachedContext, type AssetUploadInput, type AssetUploadResult, type AssetFetchResult, type AssetBrief, type ListAssetsOpts, type ThumbnailUploadInput, type ThumbnailUploadResult, type RecipientResolver, type RecipientSet, } from "./assets.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -68,7 +68,7 @@ export { createBrowserIdentity, browserIdentityFromStored, } from "@aithos/proto
 // `sdk.data` namespace — Aithos data sub-protocol PDS client. Manages
 // the lifecycle of subject-owned, encrypted, schema-validated records.
 // See spec/data/ in the aithos-protocol repo.
-export { createDataClient, } from "./data.js";
+export { createDataClient, createDelegateDataClient, } from "./data.js";
 // `sdk.assets` — Aithos assets sub-protocol PDS client. Upload,
 // fetch, list, ref/unref binary content (images, PDFs, audio, video)
 // owned by a subject. AEAD-encrypted per-asset under AMKs wrapped for

package/dist/src/internal/envelope.d.ts

@@ -22,6 +22,15 @@ export interface SignedEnvelope {
     readonly exp: number;
     readonly nonce: string;
     readonly params_hash: string;
+    /**
+     * Full signed mandate — present ONLY for a delegate-signed envelope
+     * (§11.6). When present, `proof.verificationMethod` is the delegate's
+     * bare Ed25519 multibase (matching `mandate.grantee.pubkey`) and the
+     * server resolves the signer to that key after verifying the mandate.
+     * The field is part of the signed bytes (the signature commits to the
+     * delegation context), so it cannot be swapped out in transit.
+     */
+    readonly mandate?: unknown;
     readonly proof: {
         readonly type: "Ed25519Signature2020";
         readonly verificationMethod: string;
@@ -54,6 +63,13 @@ export interface SignOwnerEnvelopeArgs {
      * matching public key.
      */
     readonly verificationMethod: string;
+    /**
+     * Full signed mandate, attached to the envelope for a delegate-signed
+     * call (§11.6). When set, `verificationMethod` MUST be the delegate's
+     * bare Ed25519 multibase (matching `mandate.grantee.pubkey`) and
+     * `signer` MUST be the delegate's key. Omit for owner-path envelopes.
+     */
+    readonly mandate?: unknown;
     /** Envelope lifetime in seconds. Default 60. Server caps at 300. */
     readonly ttlSeconds?: number;
     /** Clock override for deterministic tests. Defaults to `new Date()`. */

package/dist/src/internal/envelope.js

@@ -47,6 +47,12 @@ export async function signOwnerEnvelope(args) {
         exp,
         nonce,
         params_hash: paramsHash,
+        // Attach the mandate (delegate path) so the signature commits to the
+        // delegation context. JCS sorts keys, so placement here is irrelevant
+        // to the canonical bytes — what matters is that the server (which
+        // canonicalizes the full envelope incl. mandate + proof/proofValue="")
+        // sees the exact same object.
+        ...(args.mandate !== undefined ? { mandate: args.mandate } : {}),
         proof: {
             type: "Ed25519Signature2020",
             verificationMethod: args.verificationMethod,

package/dist/src/mandates.d.ts

@@ -8,7 +8,28 @@ import type { AithosSdkEndpoints } from "./endpoints.js";
  * 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";
+export type Scope = "ethos.read.public" | "ethos.read.circle" | "ethos.read.self" | "ethos.write.public" | "ethos.write.circle" | "ethos.write.self" | DataScope;
+/** Action a data mandate may authorize on a collection. `write` implies
+ * `read`; `admin` implies `write`. Mirrors the data sub-protocol grammar
+ * `data.<collection>.<action>` (Aithos-protocol `spec/data/04-mandates.md`
+ * §4.2) and the server-side check `requireScope` in data-backend. */
+export type DataAction = "read" | "write" | "admin";
+/**
+ * A data-access scope: `data.<collection>.<action>`, or the cross-collection
+ * wildcard `data.*.<action>`. Examples: `data.contacts.read`,
+ * `data.depots.write`, `data.*.read`.
+ *
+ * Note on `actor_sphere`: data mandates are minted under `actor_sphere:
+ * "self"` (the owner's highest-authority sphere). The sphere is *not* the
+ * access axis for data — the collection is. `actor_sphere` is informative
+ * here; the cryptographic binding is the grantee's key + the CMK wrap, per
+ * spec §4.4. A dedicated `#data` sphere key (independent rotation) MAY be
+ * introduced later without changing this scope grammar.
+ *
+ * Collection names MUST NOT contain `.` (the server splits the scope on
+ * `.` and reads the first three segments).
+ */
+export type DataScope = `data.${string}.${DataAction}`;
 /**
  * The opt-in scope that authorizes a delegate to spend the subject's
  * compute credits via the Aithos compute proxy. Mirror of

package/dist/src/mandates.js

@@ -64,6 +64,17 @@ export class MandatesNamespace {
                 `not by adding "${COMPUTE_INVOKE_SCOPE}" to scopes[]. The namespace forces ` +
                 `an explicit budget and is what a consent UI reviews.`);
         }
+        // Fail fast on malformed data scopes so the misuse surfaces at the SDK
+        // boundary, not as an opaque server rejection at first delegate call.
+        // Accepts `data.<collection>.<action>` and the wildcard `data.*.<action>`.
+        for (const s of input.scopes) {
+            if (s.startsWith("data.") &&
+                !isWellFormedDataScope(s)) {
+                throw new AithosSDKError("mandates_invalid_scopes", `Malformed data scope "${s}". Expected data.<collection>.<action> ` +
+                    `(action = read | write | admin), e.g. "data.contacts.read" or ` +
+                    `"data.*.read". Collection names must not contain ".".`);
+            }
+        }
         // Validate + project the compute namespace if present, then derive
         // the final scopes/constraints to send to the protocol layer.
         const computeProjection = projectCompute(input.compute);
@@ -207,11 +218,41 @@ export class MandatesNamespace {
 /*  Helpers                                                                   */
 /* -------------------------------------------------------------------------- */
 function defaultSphereFromScopes(scopes) {
-    if (scopes.some((s) => s.endsWith(".self")))
+    // Data scopes are sphere-NEUTRAL: they're permitted under self & circle (and
+    // public once the allowlist includes them), and the data access axis is the
+    // collection, not the sphere (the sphere is informative — see {@link DataScope}).
+    // So the actor_sphere of a combined Ethos+data mandate is decided by the
+    // ETHOS scopes alone; data scopes neither raise nor lower it. This makes
+    // `ethos.read.public + data.X.read` default to `public`, `ethos.read.circle
+    // + data.X.read` to `circle`, etc. A caller can always override via
+    // `actorSphere`.
+    const ethos = scopes.filter((s) => !s.startsWith("data."));
+    // Ethos write scopes pin the sphere EXACTLY (a write mandate must be signed
+    // by the sphere it writes to — `validateScopesAgainstSphere`).
+    if (ethos.some((s) => s === "ethos.write.public"))
+        return "public";
+    if (ethos.some((s) => s === "ethos.write.circle"))
+        return "circle";
+    if (ethos.some((s) => s === "ethos.write.self"))
         return "self";
-    if (scopes.some((s) => s.endsWith(".circle")))
+    // Ethos read scopes: narrowest sphere that permits them.
+    if (ethos.some((s) => s.endsWith(".self")))
+        return "self";
+    if (ethos.some((s) => s.endsWith(".circle")))
         return "circle";
-    return "public";
+    // Remaining Ethos scopes (ethos.read.public / .all / gamma.read) → public.
+    if (ethos.length > 0)
+        return "public";
+    // Data-only mandate: sign under `self`. self is the owner's highest-trust
+    // sphere, always permits the scope at mint time (no dependency on the
+    // public-sphere allowlist), and keeps the data grant off the most-exposed
+    // #public key. (Override with `actorSphere` for a public/circle label.)
+    return "self";
+}
+/** `true` iff `s` is a well-formed data scope `data.<collection>.<action>`
+ * with no filter suffix and a non-empty, dot-free collection name. */
+function isWellFormedDataScope(s) {
+    return /^data\.[^.]+\.(read|write|admin)$/.test(s);
 }
 /**
  * Validate the SDK-side `compute` namespace and project it onto the

package/package.json

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