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

package/dist/src/auth-api.d.ts

@@ -132,6 +132,87 @@ export type CustodialVerifyEmailApiResponse = {
  * or past its TTL.
  */
 export declare function custodialVerifyEmail(http: HttpClient, input: CustodialVerifyEmailApiInput): Promise<CustodialVerifyEmailApiResponse>;
+/**
+ * Input for {@link custodialInvite}. The app authenticates via `apiKey`
+ * (server-only secret) or `publicKey` (browser-safe, Origin-gated). The
+ * `invitePayload` is an OPAQUE app string delivered verbatim to the invitee
+ * on {@link custodialAccept}. For Aithos invitations it's a delegate bundle
+ * (mandate + seed) serialized as JSON — but the auth backend never parses it;
+ * it stores it bound to a single-use token and returns it at accept time.
+ */
+export interface CustodialInviteApiInput {
+    readonly apiKey?: string;
+    readonly publicKey?: string;
+    readonly email: string;
+    /** Opaque payload delivered to the invitee on accept (e.g. a mandate bundle JSON). */
+    readonly invitePayload: string;
+    /** Token TTL in seconds. Backend clamps to its own min/max. Default backend-side. */
+    readonly ttlSeconds?: number;
+    /** Optional display name pre-filled on the pending account. */
+    readonly displayName?: string;
+}
+export interface CustodialInviteApiResponse {
+    readonly status: "invited";
+    readonly email: string;
+    readonly mailSent: boolean;
+    readonly mailMessageId?: string;
+}
+/**
+ * Send an invitation magic link carrying an opaque payload. The backend
+ * mints a single-use token, stores `{ token, email, invite_payload, ttl }`,
+ * and emails the magic link (same SES path as the verification mail). The
+ * payload (e.g. a mandate bundle) stays server-side — it never rides the
+ * email URL. The invitee redeems it via {@link custodialAccept}.
+ *
+ * No password here: this is an invitation, not an account creation. The
+ * invitee chooses their password when they accept.
+ */
+export declare function custodialInvite(http: HttpClient, input: CustodialInviteApiInput): Promise<CustodialInviteApiResponse>;
+export interface CustodialAcceptApiInput {
+    readonly email: string;
+    readonly token: string;
+    /**
+     * Password. For a brand-new account the invitee SETS it here; for an
+     * existing account they AUTHENTICATE with it. Required unless the backend
+     * accepts a session-bound redemption (not in v1).
+     */
+    readonly password?: string;
+}
+/**
+ * Result of redeeming an invitation. Always `signed_in` on success — the
+ * token is consumed, the account is created (or the existing one is
+ * authenticated), and a full session payload is returned alongside the
+ * `invitePayload` the inviter attached. `accountCreated` distinguishes the
+ * two cases for UX.
+ */
+export interface CustodialAcceptApiResponse {
+    readonly status: "signed_in";
+    readonly session: string;
+    readonly exp: number;
+    readonly did: string;
+    readonly handle: string;
+    readonly displayName: string;
+    readonly seed: Uint8Array;
+    readonly encKey: Uint8Array;
+    readonly blob: Uint8Array;
+    readonly blobNonce: Uint8Array;
+    readonly blobVersion: number;
+    /** The opaque payload the inviter attached (e.g. a mandate bundle JSON). */
+    readonly invitePayload: string;
+    /** True when a new account was provisioned; false when an existing one signed in. */
+    readonly accountCreated: boolean;
+}
+/**
+ * Redeem an invitation token from the magic link. Consumes the token
+ * (single-use), creates the account with the supplied password (or
+ * authenticates an existing account), and returns a session + the inviter's
+ * `invitePayload`.
+ *
+ * Throws `auth_token_invalid_or_expired` (bad/consumed/expired token) or an
+ * auth error if an existing account's password is wrong / a new password is
+ * too weak.
+ */
+export declare function custodialAccept(http: HttpClient, input: CustodialAcceptApiInput): Promise<CustodialAcceptApiResponse>;
 /** Re-send the verification mail for a pending account. The backend
  *  is anti-enum (always 200) and rate-limited 1/h/account, so this is
  *  safe to call even when the user state is unknown. Accepts the same

package/dist/src/auth-api.js

@@ -183,6 +183,86 @@ export async function custodialVerifyEmail(http, input) {
         blobVersion: wire.blob_version,
     };
 }
+/**
+ * Send an invitation magic link carrying an opaque payload. The backend
+ * mints a single-use token, stores `{ token, email, invite_payload, ttl }`,
+ * and emails the magic link (same SES path as the verification mail). The
+ * payload (e.g. a mandate bundle) stays server-side — it never rides the
+ * email URL. The invitee redeems it via {@link custodialAccept}.
+ *
+ * No password here: this is an invitation, not an account creation. The
+ * invitee chooses their password when they accept.
+ */
+export async function custodialInvite(http, input) {
+    if (!input.apiKey && !input.publicKey) {
+        throw new AithosSDKError("auth_missing_api_key", "inviteCustodial requires either apiKey or publicKey");
+    }
+    if (input.apiKey && input.publicKey) {
+        throw new AithosSDKError("auth_invalid_input", "inviteCustodial: pass exactly one of apiKey or publicKey, not both");
+    }
+    const bearer = (input.apiKey ?? input.publicKey);
+    const res = await http.fetchImpl(`${http.authBaseUrl}/auth/custodial/invite`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${bearer}`,
+        },
+        body: JSON.stringify({
+            email: input.email,
+            invite_payload: input.invitePayload,
+            ...(input.ttlSeconds !== undefined ? { ttl_seconds: input.ttlSeconds } : {}),
+            ...(input.displayName ? { display_name: input.displayName } : {}),
+        }),
+    });
+    if (!res.ok)
+        throw await readError(res, "custodial_invite_failed");
+    const wire = (await res.json());
+    return {
+        status: "invited",
+        email: wire.email,
+        mailSent: wire.mail_sent,
+        ...(wire.mail_message_id !== undefined ? { mailMessageId: wire.mail_message_id } : {}),
+    };
+}
+/**
+ * Redeem an invitation token from the magic link. Consumes the token
+ * (single-use), creates the account with the supplied password (or
+ * authenticates an existing account), and returns a session + the inviter's
+ * `invitePayload`.
+ *
+ * Throws `auth_token_invalid_or_expired` (bad/consumed/expired token) or an
+ * auth error if an existing account's password is wrong / a new password is
+ * too weak.
+ */
+export async function custodialAccept(http, input) {
+    const res = await http.fetchImpl(`${http.authBaseUrl}/auth/custodial/accept`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            email: input.email,
+            token: input.token,
+            ...(input.password ? { password: input.password } : {}),
+        }),
+    });
+    if (!res.ok)
+        throw await readError(res, "custodial_accept_failed");
+    const wire = (await res.json());
+    return {
+        status: "signed_in",
+        session: wire.session,
+        exp: wire.exp,
+        did: wire.did,
+        handle: wire.handle,
+        displayName: wire.display_name,
+        seed: b64ToBytes(wire.seed_b64),
+        encKey: b64ToBytes(wire.enc_key_b64),
+        blob: wire.blob_b64 ? b64ToBytes(wire.blob_b64) : new Uint8Array(0),
+        blobNonce: wire.blob_nonce_b64 ? b64ToBytes(wire.blob_nonce_b64) : new Uint8Array(0),
+        blobVersion: wire.blob_version,
+        invitePayload: wire.invite_payload,
+        accountCreated: wire.account_created,
+    };
+}
 /* ---- POST /auth/custodial/verify/resend -------------------------------- */
 /** Re-send the verification mail for a pending account. The backend
  *  is anti-enum (always 200) and rate-limited 1/h/account, so this is

package/dist/src/auth.d.ts

@@ -152,6 +152,64 @@ export interface ImportMandateInput {
     /** Delegate bundle as a Blob or already-decoded JSON string. */
     readonly bundle: Blob | string;
 }
+/**
+ * Input to {@link AithosAuth.inviteCustodial}. Sends an invitation magic link
+ * that carries an opaque payload (typically a delegate bundle) to deliver to
+ * the invitee on accept. Mandate-agnostic: `mandateBundle` may be ANY mandate
+ * (read/write/append/ethos/compute…) — the auth backend stores it verbatim,
+ * bound to a single-use token, and never parses it.
+ *
+ * The app authenticates via `apiKey` (server-only secret) or `publicKey`
+ * (browser-safe, Origin-gated), or the constructor's default `publicKey`.
+ * No user password here — the invitee chooses it when they accept.
+ */
+export interface InviteCustodialInput {
+    readonly apiKey?: string;
+    readonly publicKey?: string;
+    /** Invitee email — receives the magic link. */
+    readonly email: string;
+    /**
+     * The mandate to deliver. Accept the SDK's `MintedMandate.bundle` (Blob),
+     * a JSON string, or a plain bundle object — all normalized to a JSON string.
+     */
+    readonly mandateBundle: Blob | string | Record<string, unknown>;
+    /** Token TTL in seconds (backend clamps to its policy). */
+    readonly ttlSeconds?: number;
+    /** Optional display name pre-filled on the pending account. */
+    readonly displayName?: string;
+}
+/** Result of {@link AithosAuth.inviteCustodial}. */
+export interface InviteCustodialResult {
+    readonly status: "invited";
+    readonly email: string;
+    readonly mailSent: boolean;
+    readonly mailMessageId?: string;
+}
+/**
+ * Input to {@link AithosAuth.acceptInvite}. `email` and `token` come from the
+ * `?email=&token=` query string of the invitation link. `password` is set by
+ * the invitee for a NEW account, or used to authenticate an EXISTING one — so
+ * it's required whenever the user isn't already signed in.
+ */
+export interface AcceptInviteInput {
+    readonly email: string;
+    readonly token: string;
+    readonly password?: string;
+}
+/**
+ * Result of {@link AithosAuth.acceptInvite}. The token is consumed, the
+ * session is hydrated (account created or existing one signed in), and the
+ * invited mandate has been imported into the keystore — `delegate` describes
+ * it. Read `delegate.subjectDid` to identify the issuer (e.g. resolve their
+ * public Ethos via `sdk.ethos.of(delegate.subjectDid)`).
+ */
+export interface AcceptInviteResult {
+    readonly status: "signed_in";
+    readonly session: AithosSession;
+    readonly delegate: DelegateInfo;
+    /** True when a new account was provisioned; false when an existing one signed in. */
+    readonly accountCreated: boolean;
+}
 /**
  * Input to {@link AithosAuth.signUpCustodial}.
  *
@@ -544,6 +602,32 @@ export declare class AithosAuth {
      * past its 1h TTL — surface a "request a fresh link" CTA in that case.
      */
     verifyEmail(input: VerifyEmailInput): Promise<VerifyEmailResult>;
+    /**
+     * Send an invitation magic link carrying a mandate. The issuer (owner)
+     * mints any mandate via {@link AithosSDK.mandates} (read/write/append/…),
+     * then calls this with the bundle: the auth backend stores it bound to a
+     * single-use token and emails the magic link. The mandate (and its delegate
+     * seed) never ride the email URL. The invitee redeems it via
+     * {@link acceptInvite}.
+     *
+     * Generic — knows nothing about the mandate's scope. Authenticate with
+     * `apiKey` (server) or `publicKey` (browser, Origin-gated).
+     */
+    inviteCustodial(input: InviteCustodialInput): Promise<InviteCustodialResult>;
+    /**
+     * Redeem an invitation from the magic link: consume the token, sign in
+     * (create the account with `password`, or authenticate an existing one),
+     * and AUTO-IMPORT the mandate the inviter attached. Returns the session and
+     * the imported {@link DelegateInfo}.
+     *
+     * Mount this on the page declared as the invitation's verify/redirect URL;
+     * read `email` + `token` from `window.location.search`, collect the
+     * `password`, call this.
+     *
+     * Throws `auth_token_invalid_or_expired` (bad/consumed/expired token) or an
+     * auth error if an existing account's password is wrong / a new one is weak.
+     */
+    acceptInvite(input: AcceptInviteInput): Promise<AcceptInviteResult>;
     /**
      * Re-send the verification mail for a pending account. Use when the
      * user reports never having received the welcome mail, or when their

package/dist/src/auth.js

@@ -21,7 +21,7 @@
 // keyStore is the source of truth for "is the user signed in", the
 // JWT is auxiliary for compute/wallet.
 import { browserIdentityFromStored, buildBlobPlaintext, buildSignedEnvelope, createBrowserIdentity, decryptBlob, DEFAULT_KDF, deriveAuthAndEncKeys, encryptBlob, parseBlob, randomNonce, randomSalt, serializeBlob, signedDidDocument, zeroize, } from "@aithos/protocol-client";
-import { custodialResendVerify, custodialResetFinalize, custodialResetRequest, custodialSignIn, custodialSignUp, custodialVerifyEmail, loginChallenge, loginVerify, putBlob, registerAccount, } from "./auth-api.js";
+import { custodialAccept, custodialInvite, custodialResendVerify, custodialResetFinalize, custodialResetRequest, custodialSignIn, custodialSignUp, custodialVerifyEmail, loginChallenge, loginVerify, putBlob, registerAccount, } from "./auth-api.js";
 import { defaultSessionStore, } from "./session-store.js";
 import { defaultKeyStore, } from "./key-store.js";
 import { parseDelegateBundle, readDelegateBundleText, } from "./internal/delegate-bundle.js";
@@ -1029,6 +1029,138 @@ export class AithosAuth {
         this.#sessionStore.set(session);
         return { status: "signed_in", session, passwordMustChange: false };
     }
+    /**
+     * Send an invitation magic link carrying a mandate. The issuer (owner)
+     * mints any mandate via {@link AithosSDK.mandates} (read/write/append/…),
+     * then calls this with the bundle: the auth backend stores it bound to a
+     * single-use token and emails the magic link. The mandate (and its delegate
+     * seed) never ride the email URL. The invitee redeems it via
+     * {@link acceptInvite}.
+     *
+     * Generic — knows nothing about the mandate's scope. Authenticate with
+     * `apiKey` (server) or `publicKey` (browser, Origin-gated).
+     */
+    async inviteCustodial(input) {
+        if (!input.email) {
+            throw new AithosSDKError("auth_invalid_input", "inviteCustodial: email is required");
+        }
+        if (input.mandateBundle === undefined || input.mandateBundle === null) {
+            throw new AithosSDKError("auth_invalid_input", "inviteCustodial: mandateBundle is required");
+        }
+        const apiKey = input.apiKey;
+        const publicKey = input.publicKey ?? this.#publicKey;
+        if (!apiKey && !publicKey) {
+            throw new AithosSDKError("auth_missing_api_key", "inviteCustodial: pass apiKey, or publicKey, or set publicKey on the AithosAuth constructor");
+        }
+        // Normalize the bundle to a JSON string (the opaque invite payload).
+        let invitePayload;
+        if (typeof input.mandateBundle === "string") {
+            invitePayload = input.mandateBundle;
+        }
+        else if (input.mandateBundle instanceof Blob) {
+            invitePayload = await input.mandateBundle.text();
+        }
+        else {
+            invitePayload = JSON.stringify(input.mandateBundle);
+        }
+        const result = await custodialInvite({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, {
+            email: input.email,
+            invitePayload,
+            ...(apiKey ? { apiKey } : publicKey ? { publicKey } : {}),
+            ...(input.ttlSeconds !== undefined ? { ttlSeconds: input.ttlSeconds } : {}),
+            ...(input.displayName ? { displayName: input.displayName } : {}),
+        });
+        return {
+            status: "invited",
+            email: result.email,
+            mailSent: result.mailSent,
+            ...(result.mailMessageId !== undefined ? { mailMessageId: result.mailMessageId } : {}),
+        };
+    }
+    /**
+     * Redeem an invitation from the magic link: consume the token, sign in
+     * (create the account with `password`, or authenticate an existing one),
+     * and AUTO-IMPORT the mandate the inviter attached. Returns the session and
+     * the imported {@link DelegateInfo}.
+     *
+     * Mount this on the page declared as the invitation's verify/redirect URL;
+     * read `email` + `token` from `window.location.search`, collect the
+     * `password`, call this.
+     *
+     * Throws `auth_token_invalid_or_expired` (bad/consumed/expired token) or an
+     * auth error if an existing account's password is wrong / a new one is weak.
+     */
+    async acceptInvite(input) {
+        if (!input.email || !input.token) {
+            throw new AithosSDKError("auth_invalid_input", "acceptInvite: email and token are required");
+        }
+        const resp = await custodialAccept({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, {
+            email: input.email,
+            token: input.token,
+            ...(input.password ? { password: input.password } : {}),
+        });
+        // Materialise the 4 sphere seeds + session — same shape as the verifyEmail
+        // magic-link path. Kept inline (additive; verifyEmail is left untouched).
+        if (resp.seed.byteLength !== 128) {
+            zeroize(resp.seed);
+            zeroize(resp.encKey);
+            throw new AithosSDKError("auth_custodial_seed_format", `acceptInvite: expected 128-byte seed bundle, got ${resp.seed.byteLength}`);
+        }
+        const seedRoot = resp.seed.slice(0, 32);
+        const seedPublic = resp.seed.slice(32, 64);
+        const seedCircle = resp.seed.slice(64, 96);
+        const seedSelf = resp.seed.slice(96, 128);
+        const stored = {
+            version: "0.1.0-hex",
+            did: resp.did,
+            handle: resp.handle,
+            displayName: resp.displayName,
+            seedsHex: {
+                root: bytesToHex(seedRoot),
+                public: bytesToHex(seedPublic),
+                circle: bytesToHex(seedCircle),
+                self: bytesToHex(seedSelf),
+            },
+            savedAt: new Date().toISOString(),
+        };
+        zeroize(resp.seed);
+        zeroize(seedRoot);
+        zeroize(seedPublic);
+        zeroize(seedCircle);
+        zeroize(seedSelf);
+        zeroize(resp.encKey);
+        const identity = browserIdentityFromStored({
+            handle: stored.handle,
+            displayName: stored.displayName,
+            did: stored.did,
+            seeds: stored.seedsHex,
+        });
+        await this.#publishIdentity(identity);
+        if (this.#ownerSigners)
+            this.#ownerSigners.destroy();
+        this.#ownerSigners = OwnerSigners.fromStoredOwnerKeys(stored);
+        await this.#keyStore.saveOwner(stored);
+        const session = {
+            session: resp.session,
+            exp: resp.exp,
+            did: resp.did,
+            handle: resp.handle,
+            blob_b64: bytesToB64Public(resp.blob),
+            blob_nonce_b64: bytesToB64Public(resp.blobNonce),
+            blob_version: resp.blobVersion,
+            enc_key_b64: "",
+            is_first_login: false,
+        };
+        this.#sessionStore.set(session);
+        // Import the invited mandate into the keystore (generic — any scope).
+        const delegate = await this.importMandate({ bundle: resp.invitePayload });
+        return {
+            status: "signed_in",
+            session,
+            delegate,
+            accountCreated: resp.accountCreated,
+        };
+    }
     /**
      * Re-send the verification mail for a pending account. Use when the
      * user reports never having received the welcome mail, or when their

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,98 @@ 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;
+/** An append-only handle on one collection: `insert` and nothing else. */
+export interface AppendOnlyDataCollection {
+    readonly name: string;
+    /**
+     * Deposit a record. The DEK is sealed to the owner's public key, so the
+     * depositor cannot read this (or any) record back. Returns the record id.
+     */
+    insert(record: Record<string, unknown>): Promise<string>;
+}
+/** A client holding a `data.<collection>.append` mandate. Insert-only. */
+export interface AppendOnlyDataClient {
+    /** Get an append-only handle on a collection (schema supplied at
+     * construction — append clients cannot read collection metadata). */
+    collection(name: string): AppendOnlyDataCollection;
+    /** Drop in-memory cache. */
+    reset(): void;
+}
+export interface CreateAppendDataClientArgs {
+    /** PDS base URL (same endpoint the owner writes to). */
+    readonly pdsUrl: string;
+    /** DID of the SUBJECT who owns the target collection (the mandate issuer). */
+    readonly subjectDid: string;
+    /**
+     * The owner's `#data` Ed25519 public key (multibase z…). The depositor
+     * derives the owner's X25519 wrap target from it and seals each DEK to it.
+     * Source: the append mandate / invitation, or the owner's DID document.
+     */
+    readonly ownerDataPubkeyMultibase: string;
+    /** The signed mandate carrying `data.<collection>.append`. */
+    readonly mandate: SignedMandate;
+    /** The depositor's Ed25519 seed (32 bytes) — the grantee key the mandate is
+     * bound to. Signs each insert envelope. NEVER used to read. */
+    readonly delegateSeed: Uint8Array;
+    /** Defaults to `mandate.grantee.pubkey`. */
+    readonly granteePubkeyMultibase?: string;
+    /**
+     * Schema of the target collection(s). The append client builds records
+     * locally (it cannot fetch collection metadata), so the caller MUST supply
+     * the schema(s) used by the collection it deposits into. The first entry is
+     * used as the default; multiple may be passed for multi-collection clients.
+     */
+    readonly schema: AithosSchemaLite;
+    /** Additional schemas (looked up by id alongside `schema`). */
+    readonly schemas?: readonly AithosSchemaLite[];
+    /** `fetch` override (tests). */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * 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 declare function createAppendDataClient(args: CreateAppendDataClientArgs): AppendOnlyDataClient;
 //# sourceMappingURL=data.d.ts.map