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

package/dist/src/internal/cmk-wrap.d.ts

@@ -0,0 +1,41 @@
+export interface CmkWrap {
+    readonly recipient: string;
+    readonly alg: "x25519-hkdf-sha256-aead";
+    readonly ephemeral_public: string;
+    readonly wrap_nonce: string;
+    readonly wrapped_key: string;
+}
+/** The CMK envelope stored on a collection. */
+export interface CmkEnvelope {
+    readonly alg: string;
+    readonly wraps: CmkWrap[];
+}
+/**
+ * Derive a 32-byte X25519 private key from an Ed25519 seed via SHA-512
+ * truncation + clamping (libsodium crypto_sign_ed25519_sk_to_curve25519).
+ */
+export declare function ed25519SeedToX25519PrivateKey(seed: Uint8Array): Uint8Array;
+export declare function ed25519SeedToX25519PublicKey(seed: Uint8Array): Uint8Array;
+export declare function wrapCmkForRecipient(args: {
+    cmk: Uint8Array;
+    recipientPublicKey: Uint8Array;
+    recipientDidUrl: string;
+    collectionUrn: string;
+}): CmkWrap;
+/**
+ * Try to unwrap the CMK from `wrap` with `privateKey`. Returns the CMK bytes
+ * on success, or `null` when the AEAD tag fails (wrong key / AAD mismatch) —
+ * the migration relies on this null-return to AUTO-DISCOVER which legacy sphere
+ * seed sealed the wrap (try each, the right one verifies).
+ */
+export declare function tryUnwrapCmk(args: {
+    wrap: {
+        recipient: string;
+        ephemeral_public: string;
+        wrap_nonce: string;
+        wrapped_key: string;
+    };
+    collectionUrn: string;
+    privateKey: Uint8Array;
+}): Uint8Array | null;
+//# sourceMappingURL=cmk-wrap.d.ts.map

package/dist/src/internal/cmk-wrap.js

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * CMK wrap / unwrap primitives for the data sub-protocol.
+ *
+ * These are a CANONICAL, byte-identical copy of the private crypto used by
+ * `DataClientImpl` in `../data.ts` (`#wrapCmkForRecipient` / `#unwrapCmk` and
+ * the X25519-seed derivation). They are factored out here so the legacy
+ * #data-sphere migration (`../migrate.ts`) can re-wrap a collection's CMK to
+ * the owner's `#data` key WITHOUT going through the high-level `DataClient`
+ * (which is hard-wired to a single sphere seed and so cannot unwrap a wrap
+ * sealed to a *different* legacy sphere).
+ *
+ * INVARIANT: the wire format produced here MUST stay byte-identical to
+ * `data.ts`. `test/cmk-wrap-conformance.test.ts` proves it by cross-unwrapping
+ * (data.ts wraps → cmk-wrap unwraps, and vice-versa). If you change one, change
+ * both and keep that test green — a drift here silently corrupts migrated data.
+ */
+import { x25519 } from "@noble/curves/ed25519.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha256, sha512 } from "@noble/hashes/sha2.js";
+import { XChaCha20Poly1305 } from "@stablelib/xchacha20poly1305";
+/* -------------------------------------------------------------------------- */
+/*  X25519 seed derivation (mirrors data.ts)                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * Derive a 32-byte X25519 private key from an Ed25519 seed via SHA-512
+ * truncation + clamping (libsodium crypto_sign_ed25519_sk_to_curve25519).
+ */
+export function ed25519SeedToX25519PrivateKey(seed) {
+    if (seed.length !== 32)
+        throw new Error("Ed25519 seed must be 32 bytes");
+    const h = sha512(seed);
+    const sk = new Uint8Array(h.slice(0, 32));
+    sk[0] = sk[0] & 248;
+    sk[31] = sk[31] & 127;
+    sk[31] = sk[31] | 64;
+    return sk;
+}
+export function ed25519SeedToX25519PublicKey(seed) {
+    const sk = ed25519SeedToX25519PrivateKey(seed);
+    try {
+        return x25519.getPublicKey(sk);
+    }
+    finally {
+        sk.fill(0);
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*  Wrap / unwrap (mirrors data.ts #wrapCmkForRecipient / #unwrapCmk)         */
+/* -------------------------------------------------------------------------- */
+export function wrapCmkForRecipient(args) {
+    const ephSk = x25519.utils.randomSecretKey();
+    const ephPk = x25519.getPublicKey(ephSk);
+    const shared = x25519.getSharedSecret(ephSk, args.recipientPublicKey);
+    const wrapKey = hkdf(sha256, shared, utf8("aithos-data-cmk-wrap-v1"), utf8(args.recipientDidUrl), 32);
+    const wrapNonce = randomBytes24();
+    const aad = aadCmkWrap(args.collectionUrn, args.recipientDidUrl);
+    const aead = new XChaCha20Poly1305(wrapKey);
+    const wrapped = aead.seal(wrapNonce, args.cmk, aad);
+    wrapKey.fill(0);
+    shared.fill(0);
+    return {
+        recipient: args.recipientDidUrl,
+        alg: "x25519-hkdf-sha256-aead",
+        ephemeral_public: base64Std(ephPk),
+        wrap_nonce: base64Std(wrapNonce),
+        wrapped_key: base64Std(wrapped),
+    };
+}
+/**
+ * Try to unwrap the CMK from `wrap` with `privateKey`. Returns the CMK bytes
+ * on success, or `null` when the AEAD tag fails (wrong key / AAD mismatch) —
+ * the migration relies on this null-return to AUTO-DISCOVER which legacy sphere
+ * seed sealed the wrap (try each, the right one verifies).
+ */
+export function tryUnwrapCmk(args) {
+    const ephPk = fromBase64(args.wrap.ephemeral_public);
+    const wrapNonce = fromBase64(args.wrap.wrap_nonce);
+    const wrappedKey = fromBase64(args.wrap.wrapped_key);
+    const shared = x25519.getSharedSecret(args.privateKey, ephPk);
+    const wrapKey = hkdf(sha256, shared, utf8("aithos-data-cmk-wrap-v1"), utf8(args.wrap.recipient), 32);
+    const aad = aadCmkWrap(args.collectionUrn, args.wrap.recipient);
+    const aead = new XChaCha20Poly1305(wrapKey);
+    const cmk = aead.open(wrapNonce, wrappedKey, aad);
+    wrapKey.fill(0);
+    shared.fill(0);
+    return cmk ?? null;
+}
+/* -------------------------------------------------------------------------- */
+/*  Local helpers (byte-identical to data.ts)                                 */
+/* -------------------------------------------------------------------------- */
+function aadCmkWrap(collectionUrn, recipient) {
+    const p = utf8("aithos-data-cmk-v1\0");
+    const c = utf8(collectionUrn);
+    const sep = new Uint8Array([0]);
+    const r = utf8(recipient);
+    const out = new Uint8Array(p.length + c.length + sep.length + r.length);
+    let off = 0;
+    out.set(p, off);
+    off += p.length;
+    out.set(c, off);
+    off += c.length;
+    out.set(sep, off);
+    off += sep.length;
+    out.set(r, off);
+    return out;
+}
+function utf8(s) {
+    return new TextEncoder().encode(s);
+}
+function randomBytes24() {
+    const buf = new Uint8Array(24);
+    globalThis.crypto?.getRandomValues(buf);
+    return buf;
+}
+function base64Std(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
+function fromBase64(s) {
+    const std = s.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = std + "=".repeat((4 - (std.length % 4)) % 4);
+    const bin = atob(padded);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+//# sourceMappingURL=cmk-wrap.js.map

package/dist/src/internal/delegate-bundle.js

@@ -50,13 +50,18 @@ export function parseDelegateBundle(text) {
     }
     const m = mandate;
     const mandateId = m["id"];
-    const subjectDid = m["subject_did"] ?? m["subjectDid"];
+    // The mandate subject's DID is carried by `issuer` in the wire format
+    // emitted by `mintDelegateBundle()` (cf. SignedMandate.issuer in
+    // protocol-client). We accept the legacy `subject_did` / camelCase
+    // variants too so older test fixtures and any externally-minted
+    // bundles using the older shape keep working.
+    const subjectDid = m["issuer"] ?? m["subject_did"] ?? m["subjectDid"];
     const grantee = m["grantee"];
     if (typeof mandateId !== "string" || !mandateId) {
         throw bad("mandate.id missing");
     }
     if (typeof subjectDid !== "string" || !subjectDid.startsWith("did:")) {
-        throw bad("mandate.subject_did missing or malformed");
+        throw bad("mandate.issuer missing or malformed (expected a `did:` URL)");
     }
     if (typeof grantee !== "object" || grantee === null) {
         throw bad("mandate.grantee missing");

package/dist/src/internal/envelope.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Minimal signing surface required to produce an envelope's
+ * `proof.proofValue`. Intentionally narrower than {@link Signer} so
+ * callers that don't want to construct a full `RawSeedSigner` can pass
+ * a one-shot inline adapter. Every {@link Signer} satisfies this
+ * interface structurally.
+ */
+export interface EnvelopeSigner {
+    sign(message: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * The wire-format envelope per spec §11.2. Apps that POST this to a
+ * backend serialize the whole object as JSON (alongside the rest of
+ * `params`) under `params._envelope`.
+ */
+export interface SignedEnvelope {
+    readonly "aithos-envelope": "0.1.0";
+    readonly iss: string;
+    readonly aud: string;
+    readonly method: string;
+    readonly iat: number;
+    readonly exp: number;
+    readonly nonce: string;
+    readonly params_hash: string;
+    /**
+     * Full signed mandate — present ONLY for a delegate-signed envelope
+     * (§11.6). When present, `proof.verificationMethod` is the delegate's
+     * bare Ed25519 multibase (matching `mandate.grantee.pubkey`) and the
+     * server resolves the signer to that key after verifying the mandate.
+     * The field is part of the signed bytes (the signature commits to the
+     * delegation context), so it cannot be swapped out in transit.
+     */
+    readonly mandate?: unknown;
+    readonly proof: {
+        readonly type: "Ed25519Signature2020";
+        readonly verificationMethod: string;
+        readonly created: string;
+        readonly proofValue: string;
+    };
+}
+export interface SignOwnerEnvelopeArgs {
+    /** Subject DID — issuer of the envelope (`iss` field). */
+    readonly iss: string;
+    /**
+     * Absolute URL of the target endpoint (scheme + host + path, no query,
+     * no fragment). The server verifier rejects envelopes where `aud`
+     * does not match the actual endpoint being called.
+     */
+    readonly aud: string;
+    /** Fully-qualified JSON-RPC method name. */
+    readonly method: string;
+    /** Tool payload — what `params_hash` commits to. */
+    readonly params: unknown;
+    /**
+     * Anything that can produce an Ed25519 signature over a byte
+     * sequence. In practice: one of the four owner sphere signers
+     * loaded post sign-in, or an inline adapter wrapping a raw seed.
+     */
+    readonly signer: EnvelopeSigner;
+    /**
+     * Verification method URL — typically `${did}#${sphere}`. The server
+     * resolves this against the issuer's DID document to find the
+     * matching public key.
+     */
+    readonly verificationMethod: string;
+    /**
+     * Full signed mandate, attached to the envelope for a delegate-signed
+     * call (§11.6). When set, `verificationMethod` MUST be the delegate's
+     * bare Ed25519 multibase (matching `mandate.grantee.pubkey`) and
+     * `signer` MUST be the delegate's key. Omit for owner-path envelopes.
+     */
+    readonly mandate?: unknown;
+    /** Envelope lifetime in seconds. Default 60. Server caps at 300. */
+    readonly ttlSeconds?: number;
+    /** Clock override for deterministic tests. Defaults to `new Date()`. */
+    readonly now?: Date;
+    /** Nonce override for deterministic tests. Defaults to a fresh ULID. */
+    readonly nonce?: string;
+}
+/**
+ * Build, canonicalize and sign an owner-path envelope per spec §11.2.
+ *
+ * The unsigned envelope is JCS-canonicalized (RFC 8785 subset), the
+ * bytes signed with Ed25519, and the resulting signature attached as
+ * `proof.proofValue` (base64url).
+ *
+ * Async return type — even though `Signer.sign` may resolve
+ * synchronously today (via `RawSeedSigner`), the interface is shaped
+ * async so that future implementations backed by `crypto.subtle.sign`
+ * (non-extractable keys) drop in without breaking callers.
+ */
+export declare function signOwnerEnvelope(args: SignOwnerEnvelopeArgs): Promise<SignedEnvelope>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/src/internal/envelope.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * Aithos signed-envelope helper — SDK-internal.
+ *
+ * Implements the `aithos-envelope` v0.1.0 wire format from spec §11.2.
+ * Used by SDK namespaces (sdk.data, sdk.ethos, sdk.mandates, ...) to
+ * sign their writes to api.aithos.be, AND by the public method
+ * {@link AithosAuth.signEnvelope} so apps can sign envelopes for
+ * arbitrary third-party Aithos-aware backends with the same primitive.
+ *
+ * NOT exported from the package barrel. The corresponding `SignedEnvelope`
+ * type IS re-exported from `src/index.ts` for consumer typing.
+ *
+ * Reference algorithm: `@aithos/protocol-core/envelope.ts:signEnvelope`.
+ * This file duplicates a self-contained subset of the helpers (JCS,
+ * SHA-256, base64url, ULID, CSPRNG) to keep the SDK's signing path
+ * decoupled from internal changes elsewhere in the SDK. The duplication
+ * with `src/data.ts` is intentional and tracked; consolidation into a
+ * shared `src/internal/canonical.ts` is planned for a follow-up release.
+ */
+import { signEnvelopeWith } from "@aithos/protocol-core/envelope";
+/**
+ * Build, canonicalize and sign an owner-path envelope per spec §11.2.
+ *
+ * The unsigned envelope is JCS-canonicalized (RFC 8785 subset), the
+ * bytes signed with Ed25519, and the resulting signature attached as
+ * `proof.proofValue` (base64url).
+ *
+ * Async return type — even though `Signer.sign` may resolve
+ * synchronously today (via `RawSeedSigner`), the interface is shaped
+ * async so that future implementations backed by `crypto.subtle.sign`
+ * (non-extractable keys) drop in without breaking callers.
+ */
+export async function signOwnerEnvelope(args) {
+    // 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,
+        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/internal/owner-signers.d.ts

@@ -17,6 +17,8 @@ export declare class OwnerSigners {
     readonly public: Signer;
     readonly circle: Signer;
     readonly self: Signer;
+    /** Optional dedicated #data sphere signer (absent on legacy owners). */
+    readonly data?: Signer;
     constructor(args: {
         did: string;
         handle: string;
@@ -25,6 +27,7 @@ export declare class OwnerSigners {
         public: Signer;
         circle: Signer;
         self: Signer;
+        data?: Signer;
     });
     /**
      * Build from a {@link BrowserIdentity}. The seeds inside `identity`
@@ -59,7 +62,7 @@ export declare class OwnerSigners {
      * have the sphere as a string ("public" | "circle" | "self") rather
      * than a typed accessor.
      */
-    signerForSphere(sphere: "root" | "public" | "circle" | "self"): Signer;
+    signerForSphere(sphere: "root" | "public" | "circle" | "self" | "data"): Signer;
     /**
      * Internal — project to a {@link StoredIdentity} for protocol-client
      * interop. Reads seed bytes via {@link RawSeedSigner._unsafeKeyPair}
@@ -71,7 +74,7 @@ export declare class OwnerSigners {
      * @internal
      */
     _unsafeStoredIdentity(): StoredIdentity;
-    /** Zeroize all four private seeds. Idempotent. */
+    /** Zeroize all private seeds. Idempotent. */
     destroy(): void;
     get destroyed(): boolean;
 }

package/dist/src/internal/owner-signers.js

@@ -34,6 +34,8 @@ export class OwnerSigners {
     public;
     circle;
     self;
+    /** Optional dedicated #data sphere signer (absent on legacy owners). */
+    data;
     #destroyed = false;
     constructor(args) {
         this.did = args.did;
@@ -43,6 +45,7 @@ export class OwnerSigners {
         this.public = args.public;
         this.circle = args.circle;
         this.self = args.self;
+        this.data = args.data;
     }
     /**
      * Build from a {@link BrowserIdentity}. The seeds inside `identity`
@@ -59,6 +62,11 @@ export class OwnerSigners {
             public: new RawSeedSigner(identity.public.seed, identity.public.publicKey),
             circle: new RawSeedSigner(identity.circle.seed, identity.circle.publicKey),
             self: new RawSeedSigner(identity.self.seed, identity.self.publicKey),
+            ...(identity.data
+                ? {
+                    data: new RawSeedSigner(identity.data.seed, identity.data.publicKey),
+                }
+                : {}),
         });
     }
     /**
@@ -120,6 +128,11 @@ export class OwnerSigners {
                 return this.circle;
             case "self":
                 return this.self;
+            case "data":
+                if (!this.data) {
+                    throw new Error("OwnerSigners: this owner has no #data sphere (legacy account)");
+                }
+                return this.data;
         }
     }
     /**
@@ -146,11 +159,18 @@ export class OwnerSigners {
                 public: bytesToHexLocal(asRawSeed(this.public, "public")._unsafeKeyPair().seed),
                 circle: bytesToHexLocal(asRawSeed(this.circle, "circle")._unsafeKeyPair().seed),
                 self: bytesToHexLocal(asRawSeed(this.self, "self")._unsafeKeyPair().seed),
+                // Preserve the optional #data seed on vault re-encryption — dropping it
+                // here would silently lose the data sphere on the next delegate-add.
+                ...(this.data
+                    ? {
+                        data: bytesToHexLocal(asRawSeed(this.data, "data")._unsafeKeyPair().seed),
+                    }
+                    : {}),
             },
             savedAt: new Date().toISOString(),
         };
     }
-    /** Zeroize all four private seeds. Idempotent. */
+    /** Zeroize all private seeds. Idempotent. */
     destroy() {
         if (this.#destroyed)
             return;
@@ -158,6 +178,7 @@ export class OwnerSigners {
         this.public.destroy();
         this.circle.destroy();
         this.self.destroy();
+        this.data?.destroy();
         this.#destroyed = true;
     }
     get destroyed() {

package/dist/src/internal/recovery-file.d.ts

@@ -8,6 +8,8 @@ export interface ParsedRecoveryFile {
         readonly public: string;
         readonly circle: string;
         readonly self: string;
+        /** Optional dedicated #data sphere seed (absent on legacy recovery files). */
+        readonly data?: string;
     };
 }
 /**

package/dist/src/internal/recovery-file.js

@@ -44,6 +44,11 @@ export function parseRecoveryFile(text) {
             throw bad(`seeds_hex.${k}: expected 64-char lowercase hex`);
         }
     }
+    // #data is optional (absent on legacy recovery files); validate when present.
+    const dataSeed = seeds["data"];
+    if (dataSeed !== undefined && (typeof dataSeed !== "string" || !HEX_64.test(dataSeed))) {
+        throw bad("seeds_hex.data: expected 64-char lowercase hex");
+    }
     return {
         handle,
         displayName,
@@ -53,6 +58,7 @@ export function parseRecoveryFile(text) {
             public: seeds["public"],
             circle: seeds["circle"],
             self: seeds["self"],
+            ...(typeof dataSeed === "string" ? { data: dataSeed } : {}),
         },
     };
 }
@@ -78,6 +84,7 @@ export function serializeRecoveryFile(identity) {
             public: bytesToHex(identity.public.seed),
             circle: bytesToHex(identity.circle.seed),
             self: bytesToHex(identity.self.seed),
+            ...(identity.data ? { data: bytesToHex(identity.data.seed) } : {}),
         },
         saved_at: new Date().toISOString(),
     };

package/dist/src/key-store.d.ts

@@ -19,6 +19,16 @@ export interface StoredOwnerKeys {
         readonly public: string;
         readonly circle: string;
         readonly self: string;
+        /**
+         * Dedicated `#data` sphere seed (spec/data/02-key-hierarchy.md) — the key
+         * that signs ALL data/asset PDS operations (create, edit, manage
+         * collections), keeping the root cold. Present on owners created since the
+         * `#data` sphere landed. Absent only on legacy owners, which predate it and
+         * therefore have no dedicated PDS key — migrate them to `#data` (the backend
+         * does this lazily on next custodial sign-in; self-custody/SSO already carry
+         * it). Signing PDS ops under any other sphere is a legacy anti-pattern.
+         */
+        readonly data?: string;
     };
     /** ISO-8601 timestamp of the original save. Informational. */
     readonly savedAt: string;

package/dist/src/key-store.js

@@ -213,6 +213,12 @@ function validOwnerOrNull(v) {
         if (s[k].length !== 64)
             return null;
     }
+    // #data is optional (absent on legacy owners); validate only when present.
+    if (s["data"] !== undefined) {
+        if (typeof s["data"] !== "string" || s["data"].length !== 64) {
+            return null;
+        }
+    }
     if (typeof o["savedAt"] !== "string")
         return null;
     return o;

package/dist/src/mandates.d.ts

@@ -8,7 +8,52 @@ import type { AithosSdkEndpoints } from "./endpoints.js";
  * directly in `scopes` is rejected at runtime; the compiler can't enforce
  * it (callers who up-cast to string[] would slip through), so the runtime
  * check is the real gate. */
-export type Scope = "ethos.read.public" | "ethos.read.circle" | "ethos.read.self" | "ethos.write.public" | "ethos.write.circle" | "ethos.write.self";
+/** An ethos verb (draft `bundle-v0.3-section-verb-scopes.md` §4.8.2′). */
+export type EthosVerb = "read" | "edit" | "append" | "delete" | "write";
+/** A writable ethos zone. */
+export type EthosZone = "public" | "circle" | "self";
+/**
+ * An ethos scope: a whole-zone grant (`ethos.edit.self`) or one narrowed to a
+ * subset of sections by a per-scope selector (`ethos.edit.self#id=X`,
+ * `ethos.append.self#prefix=gmail:`, `ethos.read.circle#tag=bio`). Plus the
+ * legacy whole-everything read `ethos.read.all`. §4.8′.
+ */
+export type EthosScope = `ethos.${EthosVerb}.${EthosZone}` | `ethos.${EthosVerb}.${EthosZone}#${string}` | "ethos.read.all";
+export type Scope = EthosScope | DataScope;
+/** Action a data mandate may authorize on a collection. `write` implies
+ * `read`; `admin` implies `write`. Mirrors the data sub-protocol grammar
+ * `data.<collection>.<action>` (Aithos-protocol `spec/data/04-mandates.md`
+ * §4.2) and the server-side check `requireScope` in data-backend. */
+export type DataAction = "read" | "write" | "admin";
+/**
+ * A **lateral** data capability — deliberately OUTSIDE the
+ * `read ⊂ write ⊂ admin` hierarchy (the same way `gamma.write` sits beside
+ * the ethos scopes). Keeping it a separate type makes the security invariant
+ * structural rather than conventional: `append` can never be reached by
+ * widening a `write`/`admin` scope, so it cannot accidentally carry read.
+ *
+ * `append` authorizes `insert_record` ONLY (no read, update, or delete). The
+ * depositor seals each record's DEK to the owner's public key
+ * ({@link createAppendDataClient}) and holds no read capability — it cannot
+ * decrypt anything in the collection, not even its own deposit.
+ */
+export type DataLateralAction = "append";
+/**
+ * A data-access scope: `data.<collection>.<action>`, or the cross-collection
+ * wildcard `data.*.<action>`. Examples: `data.contacts.read`,
+ * `data.depots.write`, `data.*.read`.
+ *
+ * Note on `actor_sphere`: data mandates are minted under `actor_sphere:
+ * "self"` (the owner's highest-authority sphere). The sphere is *not* the
+ * access axis for data — the collection is. `actor_sphere` is informative
+ * here; the cryptographic binding is the grantee's key + the CMK wrap, per
+ * spec §4.4. A dedicated `#data` sphere key (independent rotation) MAY be
+ * introduced later without changing this scope grammar.
+ *
+ * Collection names MUST NOT contain `.` (the server splits the scope on
+ * `.` and reads the first three segments).
+ */
+export type DataScope = `data.${string}.${DataAction}` | `data.${string}.${DataLateralAction}`;
 /**
  * The opt-in scope that authorizes a delegate to spend the subject's
  * compute credits via the Aithos compute proxy. Mirror of
@@ -86,6 +131,18 @@ export interface CreateMandateInput {
      * which is what a consent UI can review.
      */
     readonly compute?: CreateMandateComputeInput;
+    /**
+     * When the mandate becomes valid. Optional — when omitted, the
+     * underlying mint helper signs with `not_before = now - 30s` (see
+     * `MANDATE_NOTBEFORE_OFFSET_SECONDS_DEFAULT` in
+     * `@aithos/protocol-client`) so a server whose clock runs slightly
+     * behind the client doesn't reject the freshly-minted mandate as
+     * `not yet valid`.
+     *
+     * Pass an explicit `Date` only for advanced flows (delayed-activation
+     * mandates, deterministic tests).
+     */
+    readonly notBefore?: Date;
 }
 export interface MintedMandate {
     /** Unique mandate id (matches `mandate.id` inside the bundle). */

package/dist/src/mandates.js

@@ -64,6 +64,17 @@ export class MandatesNamespace {
                 `not by adding "${COMPUTE_INVOKE_SCOPE}" to scopes[]. The namespace forces ` +
                 `an explicit budget and is what a consent UI reviews.`);
         }
+        // Fail fast on malformed data scopes so the misuse surfaces at the SDK
+        // boundary, not as an opaque server rejection at first delegate call.
+        // Accepts `data.<collection>.<action>` and the wildcard `data.*.<action>`.
+        for (const s of input.scopes) {
+            if (s.startsWith("data.") &&
+                !isWellFormedDataScope(s)) {
+                throw new AithosSDKError("mandates_invalid_scopes", `Malformed data scope "${s}". Expected data.<collection>.<action> ` +
+                    `(action = read | write | admin), e.g. "data.contacts.read" or ` +
+                    `"data.*.read". Collection names must not contain ".".`);
+            }
+        }
         // Validate + project the compute namespace if present, then derive
         // the final scopes/constraints to send to the protocol layer.
         const computeProjection = projectCompute(input.compute);
@@ -92,6 +103,7 @@ export class MandatesNamespace {
                     },
                 }
                 : {}),
+            ...(input.notBefore ? { notBefore: input.notBefore } : {}),
         });
         const mandate = result.mandate;
         return {
@@ -206,11 +218,42 @@ export class MandatesNamespace {
 /*  Helpers                                                                   */
 /* -------------------------------------------------------------------------- */
 function defaultSphereFromScopes(scopes) {
-    if (scopes.some((s) => s.endsWith(".self")))
+    // Data scopes are sphere-NEUTRAL: they're permitted under self & circle (and
+    // public once the allowlist includes them), and the data access axis is the
+    // collection, not the sphere (the sphere is informative — see {@link DataScope}).
+    // So the actor_sphere of a combined Ethos+data mandate is decided by the
+    // ETHOS scopes alone; data scopes neither raise nor lower it. This makes
+    // `ethos.read.public + data.X.read` default to `public`, `ethos.read.circle
+    // + data.X.read` to `circle`, etc. A caller can always override via
+    // `actorSphere`.
+    const ethos = scopes.filter((s) => !s.startsWith("data."));
+    // Ethos write scopes pin the sphere EXACTLY (a write mandate must be signed
+    // by the sphere it writes to — `validateScopesAgainstSphere`).
+    if (ethos.some((s) => s === "ethos.write.public"))
+        return "public";
+    if (ethos.some((s) => s === "ethos.write.circle"))
+        return "circle";
+    if (ethos.some((s) => s === "ethos.write.self"))
         return "self";
-    if (scopes.some((s) => s.endsWith(".circle")))
+    // Ethos read scopes: narrowest sphere that permits them.
+    if (ethos.some((s) => s.endsWith(".self")))
+        return "self";
+    if (ethos.some((s) => s.endsWith(".circle")))
         return "circle";
-    return "public";
+    // Remaining Ethos scopes (ethos.read.public / .all / gamma.read) → public.
+    if (ethos.length > 0)
+        return "public";
+    // Data-only mandate: sign under `self`. self is the owner's highest-trust
+    // sphere, always permits the scope at mint time (no dependency on the
+    // public-sphere allowlist), and keeps the data grant off the most-exposed
+    // #public key. (Override with `actorSphere` for a public/circle label.)
+    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. The
+ * lateral `append` action is accepted alongside read/write/admin. */
+function isWellFormedDataScope(s) {
+    return /^data\.[^.]+\.(read|write|admin|append)$/.test(s);
 }
 /**
  * Validate the SDK-side `compute` namespace and project it onto the