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

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,95 @@ 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,
+        },
+    });
+}
+/**
+ * Build an **append-only** data client from a `data.<collection>.append`
+ * mandate. The returned {@link AppendOnlyDataClient} can ONLY `insert`: it
+ * seals each record's DEK to the owner's public key (never the CMK), so it
+ * holds no read capability — it cannot decrypt anything in the collection,
+ * not even its own deposit. The PDS additionally enforces the append scope
+ * (insert allowed; get/list/update/delete refused).
+ */
+export function createAppendDataClient(args) {
+    const granteePubMb = args.granteePubkeyMultibase ??
+        args.mandate.grantee?.pubkey;
+    if (!granteePubMb) {
+        throw new Error("createAppendDataClient: mandate.grantee.pubkey is missing; pass granteePubkeyMultibase explicitly");
+    }
+    const ownerKexPublicKey = edPubToX25519Pub(multibaseToEd25519PublicKey(args.ownerDataPubkeyMultibase));
+    const impl = new DataClientImpl({
+        pdsUrl: args.pdsUrl,
+        did: args.subjectDid,
+        // In deposit mode the seed signs envelopes; it is NEVER used to unwrap a
+        // CMK (the deposit client has none).
+        sphereSeed: args.delegateSeed,
+        verificationMethod: granteePubMb,
+        schemas: [args.schema, ...(args.schemas ?? [])],
+        ...(args.fetch ? { fetch: args.fetch } : {}),
+        deposit: {
+            delegateSeed: args.delegateSeed,
+            granteePubkeyMultibase: granteePubMb,
+            mandate: args.mandate,
+            ownerKexPublicKey,
+            ownerKexDidUrl: `${args.subjectDid}#data-kex`,
+        },
+    });
+    const defaultSchema = args.schema;
+    return {
+        collection(name) {
+            const state = impl._depositCollectionState(name, defaultSchema);
+            return {
+                name,
+                insert: (record) => impl._insertDeposit(state, record),
+            };
+        },
+        reset: () => impl.reset(),
+    };
+}
 class DataClientImpl {
     #pdsUrl;
     #did;
     #seed;
     #vm;
     #fetch;
+    /** Delegate session, or undefined for the owner path. */
+    #delegate;
+    /** Deposit (append-only) session, or undefined. Mutually exclusive with
+     * {@link DataClientImpl.#delegate}. */
+    #deposit;
     /**
      * Per-client schema overrides, populated from `args.schemas` at
      * construction. Looked up BEFORE the bundled SCHEMAS map (so an app
@@ -82,8 +163,24 @@ 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;
+        if (args.deposit)
+            this.#deposit = args.deposit;
         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 +192,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 +259,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 +295,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 +360,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 +395,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");
@@ -281,13 +443,28 @@ class DataClientImpl {
         if (opts.cursor)
             params.cursor = opts.cursor;
         const r = (await this.#call("/mcp/primitives/read", "aithos.data.list_records", params));
-        const items = r.items.map((it) => this.#decryptRecord(state, it));
+        // A read/write delegate (CMK-holder) cannot decrypt append-only deposits
+        // (sealed to the owner key). Skip them rather than crash the whole list —
+        // the owner reading the same collection decrypts everything. -32044 is the
+        // client-side "deposit unreadable by this session" marker.
+        const items = [];
+        for (const it of r.items) {
+            try {
+                items.push(this.#decryptRecord(state, it));
+            }
+            catch (e) {
+                if (e.code === -32044)
+                    continue;
+                throw e;
+            }
+        }
         return {
             items,
             ...(r.next_cursor ? { nextCursor: r.next_cursor } : {}),
         };
     }
     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 +483,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 +492,35 @@ 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.
+        // A mandate-bearing session (read-delegate OR append-deposit) signs as
+        // the grantee with the bare-multibase verificationMethod and attaches the
+        // mandate so the PDS resolves the delegation and enforces its scopes.
+        const mandateSession = this.#delegate ?? this.#deposit;
+        const envelope = mandateSession
+            ? await signOwnerEnvelope({
+                iss: this.#did, // the SUBJECT DID (mandate issuer), not the delegate
+                aud,
+                method,
+                params,
+                verificationMethod: mandateSession.granteePubkeyMultibase,
+                signer: {
+                    sign: async (msg) => ed.sign(msg, mandateSession.delegateSeed),
+                },
+                mandate: mandateSession.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(),
@@ -406,24 +605,95 @@ class DataClientImpl {
             dek.fill(0);
         }
     }
+    /**
+     * Seal a record's payload for the append-only deposit path: encrypt under a
+     * fresh DEK, then seal that DEK to the OWNER's X25519 public key (never the
+     * CMK). Mirrors `@aithos/data-crypto` `wrapDEKForRecipient` byte-for-byte so
+     * the owner (SDK or CLI) can unwrap it. The depositor keeps no key material.
+     */
+    #encryptPayloadForOwner(args) {
+        const dek = randomBytes32();
+        try {
+            const plaintext = new TextEncoder().encode(jcsCanonicalize(args.payload));
+            const nonce = randomBytes24();
+            const aad = aadRecord(this.#did, args.collectionName, args.recordId);
+            const ciphertext = new XChaCha20Poly1305(dek).seal(nonce, plaintext, aad);
+            // Seal the DEK to the owner's X25519 key (ECIES, fresh ephemeral).
+            const ephSk = x25519.utils.randomSecretKey();
+            const ephPk = x25519.getPublicKey(ephSk);
+            const shared = x25519.getSharedSecret(ephSk, args.ownerKexPublicKey);
+            const wrapKey = hkdf(sha256, shared, DEPOSIT_WRAP_SALT, utf8(args.ownerKexDidUrl), 32);
+            const wrapNonce = randomBytes24();
+            const wrapAad = aadDepositWrap(this.#did, args.collectionName, args.recordId, args.ownerKexDidUrl);
+            const wrappedKey = new XChaCha20Poly1305(wrapKey).seal(wrapNonce, dek, wrapAad);
+            wrapKey.fill(0);
+            shared.fill(0);
+            return {
+                alg: "xchacha20poly1305-ietf",
+                nonce: base64Std(nonce),
+                ciphertext: base64Std(ciphertext),
+                dek_wrapped_for_owner: {
+                    recipient: args.ownerKexDidUrl,
+                    alg: "x25519-hkdf-sha256-aead",
+                    ephemeral_public: base64Std(ephPk),
+                    wrap_nonce: base64Std(wrapNonce),
+                    wrapped_key: base64Std(wrappedKey),
+                },
+            };
+        }
+        finally {
+            dek.fill(0);
+        }
+    }
     #decryptRecord(state, raw) {
         if (raw.deleted) {
             // Soft-deleted record — payload was cleared.
             return { ...raw.metadata, _deleted: true };
         }
-        const cmk = this.#cmkCache.get(state.name);
-        if (!cmk) {
-            throw new Error("sdk.data: CMK not loaded — call ensureCollection first");
-        }
-        // Unwrap DEK
-        const wrapBuf = fromBase64(raw.payload.dek_wrapped_for_cmk);
-        const wrapNonce = wrapBuf.slice(0, 24);
-        const wrapped = wrapBuf.slice(24);
-        const dekAad = aadDekWrap(this.#did, state.name, raw.record_id);
-        const dekAead = new XChaCha20Poly1305(cmk);
-        const dek = dekAead.open(wrapNonce, wrapped, dekAad);
-        if (!dek)
-            throw new Error("sdk.data: DEK unwrap failed");
+        let dek;
+        if (raw.payload.dek_wrapped_for_owner) {
+            // Append-only deposit: the DEK is sealed to the OWNER's #data-kex key.
+            // Only the owner (no delegate/deposit session) can open it. A read
+            // delegate holds the CMK, not the owner key, so it must skip deposits.
+            if (this.#delegate || this.#deposit) {
+                const e = new Error("sdk.data: record is an append-only deposit — only the collection owner can decrypt it (this client holds a delegate/deposit mandate, not the owner key).");
+                e.code = -32044; // AITHOS_DATA_DEPOSIT_UNREADABLE (client-side)
+                throw e;
+            }
+            const w = raw.payload.dek_wrapped_for_owner;
+            const ownerKexSk = ed25519SeedToX25519PrivateKey(this.#seed);
+            try {
+                const ephPk = fromBase64(w.ephemeral_public);
+                const shared = x25519.getSharedSecret(ownerKexSk, ephPk);
+                const wrapKey = hkdf(sha256, shared, DEPOSIT_WRAP_SALT, utf8(w.recipient), 32);
+                const wrapAad = aadDepositWrap(this.#did, state.name, raw.record_id, w.recipient);
+                dek = new XChaCha20Poly1305(wrapKey).open(fromBase64(w.wrap_nonce), fromBase64(w.wrapped_key), wrapAad);
+                wrapKey.fill(0);
+                shared.fill(0);
+            }
+            finally {
+                ownerKexSk.fill(0);
+            }
+            if (!dek)
+                throw new Error("sdk.data: deposit DEK unwrap failed (wrong owner key or AAD mismatch)");
+        }
+        else {
+            // CMK path (owner / read-write delegate).
+            const cmk = this.#cmkCache.get(state.name);
+            if (!cmk) {
+                throw new Error("sdk.data: CMK not loaded — call ensureCollection first");
+            }
+            if (raw.payload.dek_wrapped_for_cmk === undefined) {
+                throw new Error("sdk.data: record payload has neither dek_wrapped_for_cmk nor dek_wrapped_for_owner");
+            }
+            const wrapBuf = fromBase64(raw.payload.dek_wrapped_for_cmk);
+            const wrapNonce = wrapBuf.slice(0, 24);
+            const wrapped = wrapBuf.slice(24);
+            const dekAad = aadDekWrap(this.#did, state.name, raw.record_id);
+            dek = new XChaCha20Poly1305(cmk).open(wrapNonce, wrapped, dekAad);
+            if (!dek)
+                throw new Error("sdk.data: DEK unwrap failed");
+        }
         try {
             const nonce = fromBase64(raw.payload.nonce);
             const ciphertext = fromBase64(raw.payload.ciphertext);
@@ -439,6 +709,38 @@ class DataClientImpl {
             dek.fill(0);
         }
     }
+    /**
+     * Append-only deposit insert. Used by the {@link createAppendDataClient}
+     * path: builds the record locally (no CMK, no server schema fetch — the
+     * caller supplies the schema), seals the DEK to the owner key, and POSTs
+     * `insert_record`. The PDS enforces the `data.<col>.append` scope.
+     */
+    async _insertDeposit(state, record) {
+        if (!this.#deposit) {
+            throw new Error("sdk.data: _insertDeposit called without a deposit session");
+        }
+        const { metadata, payload } = splitRecord(record, state.schema);
+        const recordId = `record_${makeUlid()}`;
+        const encrypted = this.#encryptPayloadForOwner({
+            collectionName: state.name,
+            recordId,
+            payload,
+            ownerKexPublicKey: this.#deposit.ownerKexPublicKey,
+            ownerKexDidUrl: this.#deposit.ownerKexDidUrl,
+        });
+        const r = (await this.#call("/mcp/primitives/write", "aithos.data.insert_record", {
+            collection_urn: state.urn,
+            record_id: recordId,
+            metadata,
+            payload: encrypted,
+        }));
+        return r.record_id;
+    }
+    /** Build a local collection state for the deposit path (no server fetch:
+     * append clients are not authorized to read collection metadata). */
+    _depositCollectionState(name, schema) {
+        return { name, urn: this.#collectionUrn(name), schema };
+    }
 }
 class DataCollectionImpl {
     client;
@@ -508,6 +810,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);
@@ -532,6 +846,40 @@ function aadRecord(subjectDid, collectionName, recordId) {
     const p = utf8("aithos-data-record-v1\0");
     return concat3WithSeps(p, subjectDid, collectionName, recordId);
 }
+/**
+ * HKDF salt for the append-only deposit DEK wrap. Distinct from the CMK wrap
+ * salt so the two key-derivation domains never collide. MUST match
+ * `@aithos/data-crypto` `DEPOSIT_WRAP_SALT`.
+ */
+const DEPOSIT_WRAP_SALT = utf8("aithos-data-dek-deposit-wrap-v1");
+/**
+ * AAD for the deposit DEK wrap:
+ *   "aithos-data-dek-deposit-v1\0" ‖ subject ‖ \0 ‖ collection ‖ \0 ‖
+ *      record ‖ \0 ‖ recipient_did_url
+ * MUST match `@aithos/data-crypto` `aadForDepositWrap`.
+ */
+function aadDepositWrap(subjectDid, collectionName, recordId, recipientDidUrl) {
+    const prefix = utf8("aithos-data-dek-deposit-v1\0");
+    const parts = [subjectDid, collectionName, recordId, recipientDidUrl].map(utf8);
+    const sep = new Uint8Array([0]);
+    let total = prefix.length;
+    for (let i = 0; i < parts.length; i++) {
+        total += parts[i].length + (i < parts.length - 1 ? sep.length : 0);
+    }
+    const out = new Uint8Array(total);
+    let off = 0;
+    out.set(prefix, off);
+    off += prefix.length;
+    for (let i = 0; i < parts.length; i++) {
+        out.set(parts[i], off);
+        off += parts[i].length;
+        if (i < parts.length - 1) {
+            out.set(sep, off);
+            off += sep.length;
+        }
+    }
+    return out;
+}
 function concat3WithSeps(prefix, a, b, c) {
     const aa = utf8(a);
     const bb = utf8(b);

package/dist/src/index.d.ts

@@ -14,7 +14,7 @@ export { WalletNamespace } from "./wallet.js";
 export type { ComponentStyle, ExtractArgs, ExtractContent, ExtractData, ExtractForm, ExtractFormField, ExtractHeading, ExtractIconDeclaration, ExtractImage, ExtractLink, ExtractLogo, ExtractMeta, ExtractResult, ExtractSection, ExtractStructure, ExtractStyles, FetchAssetArgs, FetchAssetResult, PaletteEntry, VisualSignature, WebNamespaceDeps, } from "./web.js";
 export { WebNamespace, WEB_EXTRACT_SCOPE } from "./web.js";
 export { AithosAuth, DEFAULT_API_BASE_URL, DEFAULT_AUTH_BASE_URL, } from "./auth.js";
-export type { AithosAuthConfig, AithosSession, ApplyPasswordResetInput, ApplyPasswordResetResult, CompleteSsoFirstLoginInput, CompleteSsoFirstLoginResult, CustodialSignInInput, CustodialSignInResult, CustodialSignUpInput, CustodialSignUpResult, DelegateInfo, ImportMandateInput, OwnerInfo, RequestPasswordResetInput, ResendVerificationInput, SignInInput, SignInWithGoogleOptions, SignInWithRecoveryInput, SignUpInput, SignUpResult, VerifyEmailInput, VerifyEmailResult, } from "./auth.js";
+export type { AcceptInviteInput, AcceptInviteResult, AithosAuthConfig, AithosSession, ApplyPasswordResetInput, ApplyPasswordResetResult, CompleteSsoFirstLoginInput, CompleteSsoFirstLoginResult, CustodialSignInInput, CustodialSignInResult, CustodialSignUpInput, CustodialSignUpResult, DelegateInfo, ImportMandateInput, InviteCustodialInput, InviteCustodialResult, OwnerInfo, RequestPasswordResetInput, ResendVerificationInput, SignInInput, SignInWithGoogleOptions, SignInWithRecoveryInput, SignUpInput, SignUpResult, VerifyEmailInput, VerifyEmailResult, } from "./auth.js";
 export type { SignedEnvelope } from "./internal/envelope.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";
@@ -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, createAppendDataClient, type CreateDataClientArgs, type CreateDelegateDataClientArgs, type CreateAppendDataClientArgs, type DataClient, type DataCollection, type ReadonlyDataClient, type ReadonlyDataCollection, type AppendOnlyDataClient, type AppendOnlyDataCollection, 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, createAppendDataClient, } 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,41 @@ 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 **lateral** data capability — deliberately OUTSIDE the
+ * `read ⊂ write ⊂ admin` hierarchy (the same way `gamma.write` sits beside
+ * the ethos scopes). Keeping it a separate type makes the security invariant
+ * structural rather than conventional: `append` can never be reached by
+ * widening a `write`/`admin` scope, so it cannot accidentally carry read.
+ *
+ * `append` authorizes `insert_record` ONLY (no read, update, or delete). The
+ * depositor seals each record's DEK to the owner's public key
+ * ({@link createAppendDataClient}) and holds no read capability — it cannot
+ * decrypt anything in the collection, not even its own deposit.
+ */
+export type DataLateralAction = "append";
+/**
+ * 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}` | `data.${string}.${DataLateralAction}`;
 /**
  * The opt-in scope that authorizes a delegate to spend the subject's
  * compute credits via the Aithos compute proxy. Mirror of