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

package/dist/src/data.js

@@ -0,0 +1,1124 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * `sdk.data` — the Aithos data sub-protocol PDS as a plain database.
+ *
+ * Records (contacts, prospects, messages, …) live under a subject's identity,
+ * encrypted client-side, sealed under the subject's dedicated **`#data`**
+ * sphere. A developer never chooses a sphere, never handles a key — the SDK
+ * derives everything from the session. There are exactly two ways in, both off
+ * the auth session:
+ *
+ *     // 1. As the OWNER (signed in) — your own database:
+ *     const db = auth.data;                 // === auth.ownerDataClient()
+ *     const id = await db.collection("contacts").insert({ name: "Jean" });
+ *     const leads = await db.collection("contacts").list({ filter: { status: "lead" } });
+ *
+ *     // 2. As a DELEGATE (you imported a mandate) — the subject's database:
+ *     const db = auth.delegateDataClient();  // single active mandate; or { subjectDid }
+ *     await db.collection("prospects").insert({ ... });  // needs data.prospects.write
+ *
+ * `auth.data` returns whichever applies to how you connected, with an identical
+ * CRUD surface. Owner-only operations (createCollection, authorizeDelegate,
+ * registerSchema) belong to the owner and throw `-32042` on the delegate path:
+ * the owner holds the CMK and decides who may access the collection (a one-time
+ * onboarding step), then the delegate does record CRUD bounded by its scope.
+ *
+ * The low-level `createDataClient` / `createDelegateDataClient` (which take a
+ * raw seed) are NOT exported from the package — they exist only as internals of
+ * the session accessors above. This is deliberate: passing a seed by hand is
+ * exactly what let an app seal data under the wrong key.
+ *
+ * Under the hood the module handles: envelope signing per spec §11, CMK / DEK
+ * lifecycle (generate, wrap, unwrap), per-record AEAD encryption, the split
+ * between indexable metadata (server-visible) and encrypted payload
+ * (server-blind), and JSON-RPC dispatch.
+ *
+ * Vendor schemas (`aithos.x.<vendor>.<name>.v<N>`) are passed via the
+ * `{ schemas: [...] }` option on the session accessor; the SDK uses them to
+ * split records into indexable metadata and encrypted payload.
+ *
+ * Spec ref: spec/data/01..10 of the aithos-protocol repo.
+ */
+import { x25519 } from "@noble/curves/ed25519.js";
+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 { canonicalize } from "@aithos/protocol-core/canonical";
+import { contactsV1 } from "./data-schema-contacts-v1.js";
+import { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
+import { signOwnerEnvelope } from "./internal/envelope.js";
+// noble/ed25519 v2 needs sha512 wired in for sync sign/verify
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ed.etc.sha512Sync = (...m) => 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+sha512(ed.etc.concatBytes(...m));
+/* -------------------------------------------------------------------------- */
+/*  Schema registry (local)                                                   */
+/* -------------------------------------------------------------------------- */
+const SCHEMAS = new Map([
+    [contactsV1.schema, contactsV1],
+]);
+/* -------------------------------------------------------------------------- */
+/*  Public factory                                                            */
+/* -------------------------------------------------------------------------- */
+export function createDataClient(args) {
+    return new DataClientImpl(args);
+}
+/**
+ * Build a data client that operates on a subject's collections under a
+ * mandate (delegate path). It signs every request as the delegate
+ * (bare-multibase verificationMethod + the mandate attached to the
+ * envelope) and decrypts/encrypts records using the CMK the owner
+ * re-wrapped for this delegate via {@link DataClient.authorizeDelegate}.
+ *
+ * Record CRUD is bounded by the mandate scope: reads need
+ * `data.<col>.read`, writes need `data.<col>.write` (or `.admin` /
+ * wildcard) — enforced client-side and by the PDS. Owner-only operations
+ * (createCollection, authorizeDelegate, revokeDelegate, registerSchema)
+ * always throw `-32042`: the owner holds the CMK and controls access.
+ *
+ * @internal Prefer the session accessor `auth.data` (owner) / the delegate
+ * session over hand-constructing this with a raw seed.
+ */
+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
+     * can override a core schema locally if it really wants to, though
+     * the immutability rule of spec §3.5 strongly discourages this).
+     */
+    #localSchemas;
+    // Per-collection CMK cache: cleared on reset()
+    #cmkCache = new Map();
+    #colCache = new Map();
+    constructor(args) {
+        this.#pdsUrl = (args.pdsUrl ?? DEFAULT_SDK_ENDPOINTS.pds).replace(/\/$/, "");
+        this.#did = args.did;
+        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]));
+    }
+    /** Owner-only operations: collection lifecycle (create/ensure), delegate
+     * management (authorize/revoke) and schema registration. A delegate — even
+     * with a write mandate — cannot perform these: the owner holds the CMK and
+     * controls who may access the collection. The PDS enforces the same. */
+    #assertOwner(op) {
+        if (this.#delegate) {
+            const e = new Error(`sdk.data: "${op}" is owner-only. A delegate (even with a write mandate) cannot ` +
+                `create collections, authorize/revoke delegates, or register schemas — the owner ` +
+                `holds the CMK and controls access. Record CRUD (insert/get/list/update/delete) ` +
+                `is available to a delegate whose mandate carries the matching scope.`);
+            e.code = -32042;
+            throw e;
+        }
+    }
+    /** Record-write guard. Owner: always allowed. Delegate: allowed iff the
+     * mandate carries a write/admin scope for this collection (data.<col>.write,
+     * data.*.write, data.<col>.admin, data.*.admin). The PDS enforces the same;
+     * this is the fast, precise local error. */
+    #assertCanWrite(op, collectionName) {
+        if (!this.#delegate)
+            return; // owner can always write
+        const scopes = this.#delegate.mandate.scopes ?? [];
+        const needed = [
+            `data.${collectionName}.write`,
+            `data.*.write`,
+            `data.${collectionName}.admin`,
+            `data.*.admin`,
+        ];
+        const ok = scopes.some((s) => needed.includes(s.split(".").slice(0, 3).join(".")));
+        if (!ok) {
+            const e = new Error(`sdk.data: "${op}" on "${collectionName}" requires a data.${collectionName}.write ` +
+                `(or .admin / wildcard) scope. This mandate grants: [${scopes.join(", ")}].`);
+            e.code = -32042;
+            throw e;
+        }
+    }
+    /**
+     * Resolve a schema id to its lite definition. App-supplied schemas
+     * (via `createDataClient({ schemas })`) take precedence over the
+     * SDK-bundled core registry.
+     */
+    #resolveSchema(schemaId) {
+        return this.#localSchemas.get(schemaId) ?? SCHEMAS.get(schemaId) ?? null;
+    }
+    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);
+        const recipientPublic = ed25519SeedToX25519PublicKey(this.#seed);
+        const wrap = this.#wrapCmkForRecipient({
+            cmk,
+            recipientPublicKey: recipientPublic,
+            recipientDidUrl,
+            collectionUrn,
+        });
+        try {
+            await this.#call("/mcp/primitives/write", "aithos.data.create_collection", {
+                subject_did: this.#did,
+                collection_name: args.name,
+                schema: args.schema,
+                ...(args.forwardSecrecy ? { forward_secrecy: args.forwardSecrecy } : {}),
+                cmk_envelope: {
+                    alg: "xchacha20poly1305-ietf",
+                    wraps: [wrap],
+                },
+            });
+            // Cache CMK in memory for subsequent ops on this collection.
+            this.#cmkCache.set(args.name, cmk);
+        }
+        finally {
+            // 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,
+        });
+        const items = r.items ?? [];
+        return items.map((c) => ({
+            name: c.name,
+            schema: c.schema,
+            record_count: c.record_count,
+        }));
+    }
+    async listGammaEntries(opts = {}) {
+        const params = { subject_did: this.#did };
+        if (opts.limit !== undefined)
+            params.limit = opts.limit;
+        if (opts.opPrefix)
+            params.op_prefix = opts.opPrefix;
+        if (opts.verify)
+            params.verify = true;
+        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");
+        }
+        const r = (await this.#call("/mcp/primitives/write", "aithos.data.register_schema", {
+            subject_did: this.#did,
+            schema_doc: schemaDoc,
+        }));
+        return {
+            schemaId: r.schema_id,
+            docHash: r.doc_hash,
+            created: r.created,
+            ...(r.created_at ? { createdAt: r.created_at } : {}),
+        };
+    }
+    async getSchema(schemaId, opts = {}) {
+        const params = { schema: schemaId };
+        // Vendor schemas always need a subject_did to address the right
+        // registry ; for core schemas the PDS ignores it but we still send
+        // ours so the auth check (envelope iss === subject_did) lines up.
+        params.subject_did = opts.subjectDid ?? this.#did;
+        try {
+            const r = (await this.#call("/mcp/primitives/read", "aithos.data.get_schema", params));
+            return r.schema;
+        }
+        catch (e) {
+            if (e.code === -32070)
+                return null;
+            throw e;
+        }
+    }
+    reset() {
+        for (const k of this.#cmkCache.values())
+            k.fill(0);
+        this.#cmkCache.clear();
+        this.#colCache.clear();
+    }
+    /* -- Internals used by DataCollection -- */
+    async _ensureCollection(name) {
+        const cached = this.#colCache.get(name);
+        if (cached)
+            return cached;
+        // Fetch metadata from PDS
+        const meta = (await this.#call("/mcp/primitives/read", "aithos.data.get_collection", {
+            subject_did: this.#did,
+            collection_name: name,
+        }));
+        // Defensive structural validation — some PDS responses have been
+        // observed (alpha.27 era) returning a meta object that lacks
+        // `cmk_envelope` for missing collections, instead of the documented
+        // -32020 JSON-RPC error. Without this check, the next line crashes
+        // with "Cannot read properties of undefined (reading 'wraps')" which
+        // bypasses the upper-layer's missing-collection handling. We re-emit
+        // a clean -32020 here so callers can detect "collection not found"
+        // uniformly.
+        if (!meta ||
+            !meta.cmk_envelope ||
+            !Array.isArray(meta.cmk_envelope.wraps) ||
+            !meta.urn ||
+            !meta.schema) {
+            const err = new Error(`sdk.data: collection "${name}" not found or malformed ` +
+                `(meta missing required field). PDS returned: ${JSON.stringify(meta).slice(0, 200)}`);
+            err.code = -32020;
+            throw err;
+        }
+        // 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`;
+        // A collection may carry MORE THAN ONE wrap under our recipient label —
+        // e.g. after the #data-sphere dual-read migration an owner collection holds
+        // both the legacy-sphere-sealed wrap (kept so the old app keeps reading) and
+        // a #data-sealed wrap (both labelled `${did}#data-kex`). The label alone
+        // can't tell them apart (it's fixed regardless of the sealing key), so we
+        // try EVERY matching wrap with our key and keep the one that actually
+        // decrypts. For the common single-wrap case this is identical to the old
+        // `find` + unwrap behaviour.
+        const matching = meta.cmk_envelope.wraps.filter((w) => w.recipient === ourRecipient);
+        if (matching.length === 0) {
+            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 privateKey = ed25519SeedToX25519PrivateKey(unwrapSeed);
+        let cmk;
+        for (const wrap of matching) {
+            try {
+                cmk = this.#unwrapCmk({ wrap, collectionUrn: meta.urn, privateKey });
+                break;
+            }
+            catch {
+                // Wrong wrap for this key (e.g. the legacy-sphere wrap when we hold the
+                // #data key, or vice-versa) — try the next same-label wrap.
+            }
+        }
+        if (!cmk) {
+            throw new Error(`sdk.data: found ${matching.length} CMK wrap(s) for ${ourRecipient} in collection ${name}, ` +
+                `but none could be unwrapped with this client's key. The collection may be sealed to a ` +
+                `different sphere/key than the one this client was constructed with.`);
+        }
+        this.#cmkCache.set(name, cmk);
+        let schema = this.#resolveSchema(meta.schema);
+        if (!schema) {
+            // Auto-resolve a PUBLISHED vendor schema from the PDS. This lets any
+            // up-to-date client read ANY collection whose owner registered its schema
+            // (via registerSchema) without the reading app having to bundle the lite
+            // locally — the published JSON Schema's `aithos:indexable` / `aithos:auto`
+            // annotations are the authoritative field split (they mirror the writer's
+            // lite by convention). Falls through to the error if nothing is published.
+            try {
+                const published = await this.getSchema(meta.schema, { subjectDid: this.#did });
+                if (published)
+                    schema = liteFromPublishedSchema(published);
+            }
+            catch {
+                // network / not-found — leave `schema` undefined (reads still work)
+            }
+        }
+        // Do NOT throw when the schema is unknown: reads decrypt from the CMK +
+        // metadata/payload alone (the schema is only needed to SPLIT on write).
+        // Leaving `schema` undefined keeps the collection fully readable; an
+        // insert/update will surface a precise "schema required to write" error.
+        const state = { name, urn: meta.urn, ...(schema ? { schema } : {}), schemaId: meta.schema };
+        this.#colCache.set(name, state);
+        return state;
+    }
+    async _insert(state, record) {
+        this.#assertCanWrite("insert", state.name);
+        const cmk = this.#cmkCache.get(state.name);
+        if (!cmk)
+            throw new Error("CMK not loaded");
+        const { metadata, payload } = splitRecord(record, requireSchema(state));
+        const recordId = `record_${makeUlid()}`;
+        const encrypted = this.#encryptPayload({
+            collectionName: state.name,
+            recordId,
+            payload,
+            cmk,
+        });
+        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;
+    }
+    async _get(state, recordId) {
+        let raw;
+        try {
+            raw = await this.#call("/mcp/primitives/read", "aithos.data.get_record", {
+                collection_urn: state.urn,
+                record_id: recordId,
+            });
+        }
+        catch (e) {
+            if (e.code === -32020)
+                return null;
+            throw e;
+        }
+        return this.#decryptRecord(state, raw);
+    }
+    async _list(state, opts = {}) {
+        const params = {
+            collection_urn: state.urn,
+        };
+        if (opts.filter)
+            params.filter = opts.filter;
+        if (opts.order)
+            params.order = opts.order;
+        if (opts.limit !== undefined)
+            params.limit = opts.limit;
+        if (opts.cursor)
+            params.cursor = opts.cursor;
+        const r = (await this.#call("/mcp/primitives/read", "aithos.data.list_records", params));
+        // 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.#assertCanWrite("update", state.name);
+        const cmk = this.#cmkCache.get(state.name);
+        if (!cmk)
+            throw new Error("CMK not loaded");
+        const { metadata, payload } = splitRecord(record, requireSchema(state));
+        const encrypted = this.#encryptPayload({
+            collectionName: state.name,
+            recordId,
+            payload,
+            cmk,
+        });
+        await this.#call("/mcp/primitives/write", "aithos.data.update_record", {
+            collection_urn: state.urn,
+            record_id: recordId,
+            metadata,
+            payload: encrypted,
+        });
+    }
+    async _delete(state, recordId) {
+        this.#assertCanWrite("delete", state.name);
+        await this.#call("/mcp/primitives/write", "aithos.data.delete_record", {
+            collection_urn: state.urn,
+            record_id: recordId,
+        });
+    }
+    /* -- JSON-RPC dispatch -- */
+    async #call(path, method, params) {
+        const aud = `${this.#pdsUrl}${path}`;
+        // 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(),
+            method,
+            params: { ...params, _envelope: envelope },
+        };
+        const r = await this.#fetch(aud, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        const json = (await r.json());
+        if (json.error) {
+            const err = new Error(json.error.message);
+            err.code = json.error.code;
+            err.data = json.error.data;
+            throw err;
+        }
+        return json.result ?? {};
+    }
+    /* -- Crypto helpers -- */
+    #collectionUrn(name) {
+        return `urn:aithos:collection:${this.#did}:${name}`;
+    }
+    #wrapCmkForRecipient(args) {
+        const ephSk = x25519.utils.randomSecretKey();
+        const ephPk = x25519.getPublicKey(ephSk);
+        const shared = x25519.getSharedSecret(ephSk, args.recipientPublicKey);
+        const wrapKey = hkdf(sha256, shared, utf8("aithos-data-cmk-wrap-v1"), utf8(args.recipientDidUrl), 32);
+        const wrapNonce = randomBytes24();
+        const aad = aadCmkWrap(args.collectionUrn, args.recipientDidUrl);
+        const aead = new XChaCha20Poly1305(wrapKey);
+        const wrapped = aead.seal(wrapNonce, args.cmk, aad);
+        wrapKey.fill(0);
+        shared.fill(0);
+        return {
+            recipient: args.recipientDidUrl,
+            alg: "x25519-hkdf-sha256-aead",
+            ephemeral_public: base64Std(ephPk),
+            wrap_nonce: base64Std(wrapNonce),
+            wrapped_key: base64Std(wrapped),
+        };
+    }
+    #unwrapCmk(args) {
+        const ephPk = fromBase64(args.wrap.ephemeral_public);
+        const wrapNonce = fromBase64(args.wrap.wrap_nonce);
+        const wrappedKey = fromBase64(args.wrap.wrapped_key);
+        const shared = x25519.getSharedSecret(args.privateKey, ephPk);
+        const wrapKey = hkdf(sha256, shared, utf8("aithos-data-cmk-wrap-v1"), utf8(args.wrap.recipient), 32);
+        const aad = aadCmkWrap(args.collectionUrn, args.wrap.recipient);
+        const aead = new XChaCha20Poly1305(wrapKey);
+        const cmk = aead.open(wrapNonce, wrappedKey, aad);
+        wrapKey.fill(0);
+        shared.fill(0);
+        if (!cmk)
+            throw new Error("sdk.data: CMK unwrap failed (wrong key or AAD mismatch)");
+        return cmk;
+    }
+    #encryptPayload(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 aead = new XChaCha20Poly1305(dek);
+            const ciphertext = aead.seal(nonce, plaintext, aad);
+            const dekWrapNonce = randomBytes24();
+            const dekAad = aadDekWrap(this.#did, args.collectionName, args.recordId);
+            const dekAead = new XChaCha20Poly1305(args.cmk);
+            const wrapped = dekAead.seal(dekWrapNonce, dek, dekAad);
+            const dekWrap = new Uint8Array(dekWrapNonce.length + wrapped.length);
+            dekWrap.set(dekWrapNonce, 0);
+            dekWrap.set(wrapped, dekWrapNonce.length);
+            return {
+                alg: "xchacha20poly1305-ietf",
+                nonce: base64Std(nonce),
+                ciphertext: base64Std(ciphertext),
+                dek_wrapped_for_cmk: base64Std(dekWrap),
+            };
+        }
+        finally {
+            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 };
+        }
+        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);
+            const aad = aadRecord(this.#did, state.name, raw.record_id);
+            const aead = new XChaCha20Poly1305(dek);
+            const plaintext = aead.open(nonce, ciphertext, aad);
+            if (!plaintext)
+                throw new Error("sdk.data: payload decrypt failed");
+            const payload = JSON.parse(new TextDecoder().decode(plaintext));
+            return { record_id: raw.record_id, ...raw.metadata, ...payload };
+        }
+        finally {
+            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, requireSchema(state));
+        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, schemaId: schema.schema };
+    }
+}
+class DataCollectionImpl {
+    client;
+    name;
+    constructor(client, name) {
+        this.client = client;
+        this.name = name;
+    }
+    async insert(record) {
+        const state = await this.client._ensureCollection(this.name);
+        return this.client._insert(state, record);
+    }
+    async get(recordId) {
+        const state = await this.client._ensureCollection(this.name);
+        return this.client._get(state, recordId);
+    }
+    async list(opts) {
+        const state = await this.client._ensureCollection(this.name);
+        return this.client._list(state, opts);
+    }
+    async update(recordId, record) {
+        const state = await this.client._ensureCollection(this.name);
+        return this.client._update(state, recordId, record);
+    }
+    async delete(recordId) {
+        const state = await this.client._ensureCollection(this.name);
+        return this.client._delete(state, recordId);
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*  Record split (metadata vs payload)                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * Derive an {@link AithosSchemaLite} from a PUBLISHED JSON Schema document (the
+ * shape `aithos.data.get_schema` / `registerSchema` round-trip). The field
+ * split is read from the per-property annotations:
+ *   - `aithos:indexable: true` → indexable (server-visible, filter/sort)
+ *   - `aithos:auto: …`         → auto (server-populated, e.g. created_at)
+ *   - anything else            → encrypted (AEAD'd client-side)
+ *
+ * These annotations are authoritative — by convention they mirror the writer's
+ * own lite — so a reader that never bundled the schema can still split records
+ * correctly. `defaults` is left empty (it only matters for inserts; the writer
+ * supplies its own).
+ */
+export function liteFromPublishedSchema(doc) {
+    const d = doc;
+    const props = d.properties ?? {};
+    const indexable = new Set();
+    const encrypted = new Set();
+    const auto = new Set();
+    for (const [k, v] of Object.entries(props)) {
+        const hasAuto = v?.["aithos:auto"] !== undefined;
+        const isIndexable = v?.["aithos:indexable"] === true;
+        if (hasAuto)
+            auto.add(k);
+        if (isIndexable)
+            indexable.add(k);
+        if (!isIndexable && !hasAuto)
+            encrypted.add(k);
+    }
+    return {
+        schema: d["aithos:schema"] ?? "",
+        indexable,
+        encrypted,
+        auto,
+        defaults: {},
+    };
+}
+/**
+ * Return the collection's write schema or throw a precise error. Writes need
+ * the schema to split a record into indexable metadata vs encrypted payload (and
+ * so the PDS can validate); reads never call this.
+ */
+function requireSchema(state) {
+    if (!state.schema) {
+        const e = new Error(`sdk.data: writing to "${state.name}" needs its schema "${state.schemaId}", which is ` +
+            `neither bundled in this client (createDataClient({ schemas: [...] })) nor published on ` +
+            `the PDS (registerSchema). Reads work without it — only inserts/updates require it.`);
+        e.code = -32602;
+        throw e;
+    }
+    return state.schema;
+}
+function splitRecord(record, schema) {
+    const metadata = {};
+    const payload = {};
+    for (const [k, v] of Object.entries(record)) {
+        if (schema.auto.has(k))
+            continue; // server-set
+        if (schema.indexable.has(k)) {
+            metadata[k] = v;
+        }
+        else if (schema.encrypted.has(k)) {
+            payload[k] = v;
+        }
+        else {
+            // Unknown field — drop. Server will reject in any case (additionalProperties: false).
+        }
+    }
+    return { metadata, payload };
+}
+/* -------------------------------------------------------------------------- */
+/*  Crypto helpers                                                            */
+/* -------------------------------------------------------------------------- */
+function randomBytes32() {
+    return cryptoRandom(32);
+}
+function randomBytes24() {
+    return cryptoRandom(24);
+}
+/** Cross-platform CSPRNG: Web Crypto in browser, Node WebCrypto in Node 19+. */
+function cryptoRandom(n) {
+    const buf = new Uint8Array(n);
+    // globalThis.crypto exists in browsers and in Node 19+
+    globalThis.crypto?.getRandomValues(buf);
+    return buf;
+}
+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);
+    const sep = new Uint8Array([0]);
+    const r = utf8(recipient);
+    const out = new Uint8Array(p.length + c.length + sep.length + r.length);
+    let off = 0;
+    out.set(p, off);
+    off += p.length;
+    out.set(c, off);
+    off += c.length;
+    out.set(sep, off);
+    off += sep.length;
+    out.set(r, off);
+    return out;
+}
+function aadDekWrap(subjectDid, collectionName, recordId) {
+    const p = utf8("aithos-data-dek-v1\0");
+    return concat3WithSeps(p, subjectDid, collectionName, recordId);
+}
+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);
+    const cc = utf8(c);
+    const sep = new Uint8Array([0]);
+    const total = prefix.length + aa.length + sep.length + bb.length + sep.length + cc.length;
+    const out = new Uint8Array(total);
+    let off = 0;
+    out.set(prefix, off);
+    off += prefix.length;
+    out.set(aa, off);
+    off += aa.length;
+    out.set(sep, off);
+    off += sep.length;
+    out.set(bb, off);
+    off += bb.length;
+    out.set(sep, off);
+    off += sep.length;
+    out.set(cc, off);
+    return out;
+}
+/**
+ * Derive a 32-byte X25519 private key from an Ed25519 seed via SHA-512
+ * truncation + clamping. Mirrors libsodium's
+ * crypto_sign_ed25519_sk_to_curve25519 for the secret-key side. Used so
+ * a single Ed25519 sphere seed can both sign envelopes and key-agree
+ * with mandate recipients.
+ */
+function ed25519SeedToX25519PrivateKey(seed) {
+    if (seed.length !== 32)
+        throw new Error("Ed25519 seed must be 32 bytes");
+    const h = sha512(seed);
+    const sk = new Uint8Array(h.slice(0, 32));
+    // Clamp per X25519 spec
+    sk[0] = sk[0] & 248;
+    sk[31] = sk[31] & 127;
+    sk[31] = sk[31] | 64;
+    return sk;
+}
+function ed25519SeedToX25519PublicKey(seed) {
+    const sk = ed25519SeedToX25519PrivateKey(seed);
+    try {
+        return x25519.getPublicKey(sk);
+    }
+    finally {
+        sk.fill(0);
+    }
+}
+function makeUlid() {
+    // Lightweight ULID — millisecond timestamp + 80 bits of randomness.
+    // Crockford base32. For tests this is sufficient; production uses
+    // the canonical ulid package.
+    const tsBuf = new Uint8Array(6);
+    let ts = Date.now();
+    for (let i = 5; i >= 0; i--) {
+        tsBuf[i] = ts & 0xff;
+        ts = Math.floor(ts / 256);
+    }
+    const rndBuf = cryptoRandom(10);
+    const all = new Uint8Array(16);
+    all.set(tsBuf, 0);
+    all.set(rndBuf, 6);
+    const alphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+    let bits = 0;
+    let value = 0;
+    let out = "";
+    for (const b of all) {
+        value = (value << 8) | b;
+        bits += 8;
+        while (bits >= 5) {
+            out += alphabet[(value >> (bits - 5)) & 0x1f];
+            bits -= 5;
+        }
+    }
+    if (bits > 0)
+        out += alphabet[(value << (5 - bits)) & 0x1f];
+    return out.slice(0, 26);
+}
+/** Standard base64 (with `=` padding). Browser + Node compatible. */
+function base64Std(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
+/** base64url (URL-safe, no padding). */
+function base64url(bytes) {
+    return base64Std(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64(s) {
+    // Accept either standard base64 or base64url
+    const std = s.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = std + "=".repeat((4 - (std.length % 4)) % 4);
+    const bin = atob(padded);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function sha256Hex(s) {
+    const d = sha256(new TextEncoder().encode(s));
+    let hex = "";
+    for (const b of d)
+        hex += b.toString(16).padStart(2, "0");
+    return hex;
+}
+/* -------------------------------------------------------------------------- */
+/*  JCS-style canonicalization (RFC 8785 subset)                              */
+/* -------------------------------------------------------------------------- */
+// Single canonicalization source of truth: @aithos/protocol-core. Kept as a
+// local alias so the encryption-AAD call sites read naturally; the byte output
+// is proven identical to the former hand-rolled JCS by
+// test/canonical-conformance.test.ts (critical: this feeds pre-encryption
+// canonicalization, so any drift would corrupt data).
+function jcsCanonicalize(value) {
+    return canonicalize(value);
+}
+//# sourceMappingURL=data.js.map