@aithos/sdk 0.1.0-alpha.45 → 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

@@ -277,4 +277,60 @@ export interface CreateDelegateDataClientArgs {
  * 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

package/dist/src/data.js

@@ -92,6 +92,50 @@ export function createDelegateDataClient(args) {
         },
     });
 }
+/**
+ * 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;
@@ -100,6 +144,9 @@ class DataClientImpl {
     #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
@@ -118,6 +165,8 @@ class DataClientImpl {
         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
@@ -394,7 +443,21 @@ 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 } : {}),
@@ -434,17 +497,21 @@ class DataClientImpl {
         // INCLUDING `proof` with proofValue=""). Delegate path: sign with the
         // grantee key, bare-multibase verificationMethod, and attach the mandate
         // so the PDS resolves the delegation and enforces its scopes.
-        const envelope = this.#delegate
+        // 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: this.#delegate.granteePubkeyMultibase,
+                verificationMethod: mandateSession.granteePubkeyMultibase,
                 signer: {
-                    sign: async (msg) => ed.sign(msg, this.#delegate.delegateSeed),
+                    sign: async (msg) => ed.sign(msg, mandateSession.delegateSeed),
                 },
-                mandate: this.#delegate.mandate,
+                mandate: mandateSession.mandate,
             })
             : await signOwnerEnvelope({
                 iss: this.#did,
@@ -538,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);
@@ -571,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;
@@ -676,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, createDelegateDataClient, type CreateDataClientArgs, type CreateDelegateDataClientArgs, type DataClient, type DataCollection, type ReadonlyDataClient, type ReadonlyDataCollection, 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, createDelegateDataClient, } 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/mandates.d.ts

@@ -14,6 +14,19 @@ export type Scope = "ethos.read.public" | "ethos.read.circle" | "ethos.read.self
  * `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`,
@@ -29,7 +42,7 @@ export type DataAction = "read" | "write" | "admin";
  * Collection names MUST NOT contain `.` (the server splits the scope on
  * `.` and reads the first three segments).
  */
-export type DataScope = `data.${string}.${DataAction}`;
+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

package/dist/src/mandates.js

@@ -250,9 +250,10 @@ function defaultSphereFromScopes(scopes) {
     return "self";
 }
 /** `true` iff `s` is a well-formed data scope `data.<collection>.<action>`
- * with no filter suffix and a non-empty, dot-free collection name. */
+ * with no filter suffix and a non-empty, dot-free collection name. The
+ * lateral `append` action is accepted alongside read/write/admin. */
 function isWellFormedDataScope(s) {
-    return /^data\.[^.]+\.(read|write|admin)$/.test(s);
+    return /^data\.[^.]+\.(read|write|admin|append)$/.test(s);
 }
 /**
  * Validate the SDK-side `compute` namespace and project it onto the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.45",
+  "version": "0.1.0-alpha.47",
   "description": "Aithos SDK — high-level TypeScript developer kit for building agentic apps on the Aithos protocol. Wraps @aithos/protocol-client and exposes the Aithos compute proxy and wallet (Stripe top-up) endpoints.",
   "keywords": [
     "aithos",