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

package/dist/src/apps.js

@@ -26,6 +26,7 @@
 // in V0.2 once the sponsorship-api Lambda exists; for now, devs check
 // their sponsorship via the AWS Console.
 import { base64url, buildSignedEnvelope, sign } from "@aithos/protocol-client";
+import { canonicalize } from "@aithos/protocol-core/canonical";
 import { computeInvokeUrl, walletTopupCheckoutUrl } from "./endpoints.js";
 import { ownerKeyPair } from "./internal/protocol-client-bridge.js";
 import { AithosSDKError } from "./types.js";
@@ -426,18 +427,6 @@ function randomBytes(n) {
  * the hash the signature commits to.
  */
 function jcsCanonicalize(value) {
-    if (value === null || typeof value !== "object") {
-        return JSON.stringify(value);
-    }
-    if (Array.isArray(value)) {
-        return "[" + value.map(jcsCanonicalize).join(",") + "]";
-    }
-    const obj = value;
-    const keys = Object.keys(obj).sort();
-    return ("{" +
-        keys
-            .map((k) => JSON.stringify(k) + ":" + jcsCanonicalize(obj[k]))
-            .join(",") +
-        "}");
+    return canonicalize(value);
 }
 //# sourceMappingURL=apps.js.map

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

@@ -39,6 +39,7 @@ 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 { signOwnerEnvelope } from "./internal/envelope.js";
 // noble/ed25519 v2 needs sha512 wired in for sync sign/verify
@@ -92,6 +93,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 +145,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 +166,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 +444,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 +498,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 +606,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 +710,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 +847,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);
@@ -785,30 +990,12 @@ function sha256Hex(s) {
 /* -------------------------------------------------------------------------- */
 /*  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) {
-    if (value === null)
-        return "null";
-    if (value === undefined)
-        throw new Error("Cannot canonicalize undefined");
-    if (typeof value === "boolean")
-        return value ? "true" : "false";
-    if (typeof value === "number") {
-        if (!Number.isFinite(value))
-            throw new Error("non-finite number");
-        return value.toString();
-    }
-    if (typeof value === "string")
-        return JSON.stringify(value);
-    if (Array.isArray(value)) {
-        return "[" + value.map(jcsCanonicalize).join(",") + "]";
-    }
-    if (typeof value === "object") {
-        const obj = value;
-        const keys = Object.keys(obj).sort();
-        return ("{" +
-            keys.map((k) => JSON.stringify(k) + ":" + jcsCanonicalize(obj[k])).join(",") +
-            "}");
-    }
-    throw new Error(`Cannot canonicalize ${typeof value}`);
+    return canonicalize(value);
 }
 //# sourceMappingURL=data.js.map

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/internal/envelope.js

@@ -19,7 +19,7 @@
  * with `src/data.ts` is intentional and tracked; consolidation into a
  * shared `src/internal/canonical.ts` is planned for a follow-up release.
  */
-import { sha256 } from "@noble/hashes/sha2.js";
+import { signEnvelopeWith } from "@aithos/protocol-core/envelope";
 /**
  * Build, canonicalize and sign an owner-path envelope per spec §11.2.
  *
@@ -33,128 +33,27 @@ import { sha256 } from "@noble/hashes/sha2.js";
  * (non-extractable keys) drop in without breaking callers.
  */
 export async function signOwnerEnvelope(args) {
-    const nowMs = (args.now ?? new Date()).getTime();
-    const iat = Math.floor(nowMs / 1000);
-    const exp = iat + (args.ttlSeconds ?? 60);
-    const nonce = args.nonce ?? makeUlid();
-    const paramsHash = "sha256-" + sha256Hex(jcsCanonicalize(args.params));
-    const unsigned = {
-        "aithos-envelope": "0.1.0",
+    // Delegate to the single envelope source of truth in @aithos/protocol-core.
+    // The canonicalization, params_hash, unsigned-envelope assembly and proof
+    // attachment all live there now; we only supply the pluggable async signer
+    // (preserving the WebCrypto-ready `EnvelopeSigner` abstraction). A
+    // conformance test proves this path is byte-identical to the seed-based
+    // core signer, which is itself byte-identical to the former hand-rolled
+    // implementation — so nothing changes on the wire.
+    const env = await signEnvelopeWith({
         iss: args.iss,
         aud: args.aud,
         method: args.method,
-        iat,
-        exp,
-        nonce,
-        params_hash: paramsHash,
-        // Attach the mandate (delegate path) so the signature commits to the
-        // delegation context. JCS sorts keys, so placement here is irrelevant
-        // to the canonical bytes — what matters is that the server (which
-        // canonicalizes the full envelope incl. mandate + proof/proofValue="")
-        // sees the exact same object.
-        ...(args.mandate !== undefined ? { mandate: args.mandate } : {}),
-        proof: {
-            type: "Ed25519Signature2020",
-            verificationMethod: args.verificationMethod,
-            created: new Date(iat * 1000).toISOString(),
-            proofValue: "",
-        },
-    };
-    const bytes = new TextEncoder().encode(jcsCanonicalize(unsigned));
-    const sig = await args.signer.sign(bytes);
-    return {
-        ...unsigned,
-        proof: { ...unsigned.proof, proofValue: base64url(sig) },
-    };
-}
-/* -------------------------------------------------------------------------- */
-/*  Self-contained helpers (duplicated with src/data.ts for isolation)        */
-/* -------------------------------------------------------------------------- */
-/** Cross-platform CSPRNG: Web Crypto in browser, Node WebCrypto in Node 19+. */
-function cryptoRandom(n) {
-    const buf = new Uint8Array(n);
-    globalThis.crypto?.getRandomValues(buf);
-    return buf;
-}
-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 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).
- *
- * Sorted object keys, no whitespace, finite numbers via `toString()`,
- * strings via `JSON.stringify` (escapes), arrays preserve order.
- * `undefined` is rejected (RFC 8785 §3.2.2).
- */
-function jcsCanonicalize(value) {
-    if (value === null)
-        return "null";
-    if (value === undefined)
-        throw new Error("Cannot canonicalize undefined");
-    if (typeof value === "boolean")
-        return value ? "true" : "false";
-    if (typeof value === "number") {
-        if (!Number.isFinite(value))
-            throw new Error("non-finite number");
-        return value.toString();
-    }
-    if (typeof value === "string")
-        return JSON.stringify(value);
-    if (Array.isArray(value)) {
-        return "[" + value.map(jcsCanonicalize).join(",") + "]";
-    }
-    if (typeof value === "object") {
-        const obj = value;
-        const keys = Object.keys(obj).sort();
-        return ("{" +
-            keys.map((k) => JSON.stringify(k) + ":" + jcsCanonicalize(obj[k])).join(",") +
-            "}");
-    }
-    throw new Error(`Cannot canonicalize ${typeof value}`);
+        params: args.params,
+        verificationMethod: args.verificationMethod,
+        sign: (bytes) => args.signer.sign(bytes),
+        ttlSeconds: args.ttlSeconds,
+        now: args.now,
+        nonce: args.nonce,
+        ...(args.mandate !== undefined
+            ? { mandate: args.mandate }
+            : {}),
+    });
+    return env;
 }
 //# sourceMappingURL=envelope.js.map

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/dist/test/canonical-conformance.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=canonical-conformance.test.d.ts.map

package/dist/test/canonical-conformance.test.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * Safety gate for the canonicalization refactor.
+ *
+ * The SDK historically carried three hand-rolled copies of `jcsCanonicalize`
+ * (internal/envelope.ts, data.ts, apps.ts). data.ts uses it to canonicalize a
+ * record payload BEFORE encryption (it feeds the AAD/plaintext), so a single
+ * differing byte vs. the canonicalization used at decrypt/verify time would
+ * silently corrupt data. Before swapping those copies onto
+ * `@aithos/protocol-core`'s `canonicalize`, this test proves the two produce
+ * identical output across a representative corpus.
+ *
+ * Known, accepted divergence: lone UTF-16 surrogates. `JSON.stringify` escapes
+ * them (\uXXXX) whereas core emits the raw code unit. Lone surrogates never
+ * appear in Aithos payloads (record fields are well-formed JSON strings), so
+ * the corpus excludes them by design.
+ */
+import { describe, test } from "node:test";
+import { strict as assert } from "node:assert";
+import { canonicalize } from "@aithos/protocol-core/canonical";
+/** Exact copy of the SDK's legacy jcsCanonicalize (pre-refactor reference). */
+function jcsCanonicalize(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        throw new Error("Cannot canonicalize undefined");
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("non-finite number");
+        return value.toString();
+    }
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map(jcsCanonicalize).join(",") + "]";
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        return ("{" +
+            keys
+                .map((k) => JSON.stringify(k) + ":" + jcsCanonicalize(obj[k]))
+                .join(",") +
+            "}");
+    }
+    throw new Error(`Cannot canonicalize ${typeof value}`);
+}
+const corpus = [
+    null,
+    true,
+    false,
+    0,
+    -1,
+    42,
+    Number.MAX_SAFE_INTEGER,
+    "",
+    "hello",
+    "with \"quotes\" and \\ backslash",
+    "tab\tnewline\nreturn\rbackspace\bform\f",
+    "control
 end",
+    "accented éàùçö and emoji 😀🚀 and 漢字",
+    "slash / and at @ and unicode nbsp",
+    [],
+    [1, 2, 3],
+    ["z", "a", "m"],
+    [{ b: 1, a: 2 }, [3, [4, 5]]],
+    {},
+    { b: 2, a: 1, c: 3 },
+    { z: { y: { x: [1, "two", false, null] } } },
+    { "key with spaces": 1, "weird:char": 2, "": "empty key" },
+    { émoji: "😀", "漢字": 1, A: 0, a: 0 }, // mixed-case + non-ascii keys (UTF-16 order)
+    {
+        record: { name: "Aïko", tags: ["x", "y"], n: 7, active: true, meta: null },
+    },
+];
+describe("canonicalize conformance — core vs legacy SDK jcsCanonicalize", () => {
+    for (const [i, value] of corpus.entries()) {
+        test(`corpus[${i}] is byte-identical`, () => {
+            assert.equal(canonicalize(value), jcsCanonicalize(value));
+        });
+    }
+});
+//# sourceMappingURL=canonical-conformance.test.js.map

package/dist/test/envelope-core-conformance.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=envelope-core-conformance.test.d.ts.map

package/dist/test/envelope-core-conformance.test.js

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * Conformance for the envelope-signing refactor.
+ *
+ * `signOwnerEnvelope` now delegates to `@aithos/protocol-core`'s
+ * `signEnvelopeWith` (pluggable async signer) instead of carrying a private
+ * JCS + signing implementation. These tests assert the migrated path is
+ * correct and stable:
+ *
+ *   1. the produced envelope's `proof.proofValue` verifies against the signer's
+ *      public key over core's canonical signing bytes (i.e. the server will
+ *      accept it);
+ *   2. `params_hash` equals core's `envelopeParamsHash(params)`;
+ *   3. with a fixed clock + nonce the output is deterministic (snapshot), which
+ *      is what guarantees the wire format did not shift under the refactor.
+ *
+ * Note: this suite needs the SDK to resolve a build of `@aithos/protocol-core`
+ * that exposes `signEnvelopeWith` (>= 0.6.3). Run via `npm test`.
+ */
+import { describe, test } from "node:test";
+import { strict as assert } from "node:assert";
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import { envelopeParamsHash, envelopeSigningBytes, } from "@aithos/protocol-core/envelope";
+import { signOwnerEnvelope } from "../src/internal/envelope.js";
+ed.etc.sha512Sync = (...m) => sha512(ed.etc.concatBytes(...m));
+const SEED = new Uint8Array(32).fill(11);
+const PUB = ed.getPublicKey(SEED);
+const NOW = new Date("2026-05-31T12:00:00.000Z");
+const NONCE = "01J0ENVELOPECONFORMANCE0000";
+const ISS = "did:aithos:z6MkEnvelopeConformance";
+const VM = `${ISS}#public`;
+const base = {
+    iss: ISS,
+    aud: "https://api.aithos.be/mcp/primitives/write",
+    method: "aithos.data.insert_record",
+    params: { b: 2, a: 1, nested: { y: [3, 1, 2], x: "z" } },
+    verificationMethod: VM,
+    signer: { sign: async (bytes) => ed.sign(bytes, SEED) },
+    ttlSeconds: 60,
+    now: NOW,
+    nonce: NONCE,
+};
+describe("signOwnerEnvelope — core delegation conformance", () => {
+    test("proofValue verifies against signing bytes (server will accept)", async () => {
+        const env = await signOwnerEnvelope({ ...base });
+        const sig = b64urlDecode(env.proof.proofValue);
+        assert.equal(ed.verify(sig, envelopeSigningBytes(env), PUB), true);
+    });
+    test("params_hash matches core.envelopeParamsHash", async () => {
+        const env = await signOwnerEnvelope({ ...base });
+        assert.equal(env.params_hash, envelopeParamsHash(base.params));
+    });
+    test("deterministic under fixed clock + nonce (wire-format snapshot)", async () => {
+        const a = await signOwnerEnvelope({ ...base });
+        const b = await signOwnerEnvelope({ ...base });
+        assert.equal(JSON.stringify(a), JSON.stringify(b));
+        assert.equal(a["aithos-envelope"], "0.1.0");
+        assert.equal(a.iat, 1780228800);
+        assert.equal(a.exp, 1780228860);
+        assert.equal(a.nonce, NONCE);
+        assert.equal(a.proof.verificationMethod, VM);
+    });
+});
+function b64urlDecode(s) {
+    const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - (s.length % 4));
+    const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + pad;
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+//# sourceMappingURL=envelope-core-conformance.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.45",
+  "version": "0.1.0-alpha.48",
   "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",
@@ -58,6 +58,7 @@
   "peerDependencies": {
     "@aithos/assets-crypto": ">=0.1.0-alpha.1 <0.2.0",
     "@aithos/protocol-client": "^0.1.0-alpha.14",
+    "@aithos/protocol-core": ">=0.6.3 <0.7.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
@@ -71,6 +72,7 @@
   "devDependencies": {
     "@aithos/assets-crypto": "^0.1.0-alpha.1",
     "@aithos/protocol-client": "^0.1.0-alpha.14",
+    "@aithos/protocol-core": ">=0.6.3 <0.7.0",
     "@types/node": "^24.12.2",
     "fake-indexeddb": "^6.2.5",
     "typescript": "^5.9.2"