@aithos/sdk 0.1.0-alpha.33 → 0.1.0-alpha.35

package/README.md

@@ -213,16 +213,61 @@ await sdk.mandates.create({
 });
 ```
 
+## Calling a third-party Aithos-aware backend
+
+If your app talks to its own backend (a service you built that verifies
+Aithos envelopes per spec §11.2 using
+`@aithos/protocol-core/envelope`), use `sdk.auth.signEnvelope` to sign
+the request with the same primitive that SDK namespaces use internally
+for `api.aithos.be`. No JWT, no shadow session — the user's DID in the
+envelope's `iss` field is the identity.
+
+```ts
+import { AithosSDK, type SignedEnvelope } from "@aithos/sdk";
+
+// Sign a request to your own backend with the active owner's
+// public-sphere key. Default TTL is 60 s.
+const envelope: SignedEnvelope = await sdk.auth.signEnvelope({
+  aud: "https://api.example.com/v1/widgets",
+  method: "myapp.widgets.create",
+  params: { name: "Widget #1" },
+});
+
+await fetch("https://api.example.com/v1/widgets", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({
+    jsonrpc: "2.0",
+    id: crypto.randomUUID(),
+    method: "myapp.widgets.create",
+    params: { name: "Widget #1", _envelope: envelope },
+  }),
+});
+```
+
+The envelope binds the signature to `(iss, aud, method, params_hash,
+nonce, iat, exp)`, so a single envelope cannot be replayed against a
+different endpoint, method, or payload. Throws
+`AithosSDKError("auth_not_signed_in")` if no owner is loaded; throws
+`AithosSDKError("auth_invalid_sphere")` if you pass a sphere outside
+`"root" | "public" | "circle" | "self"` (default is `"public"`).
+
+Server-side, your backend verifies the envelope with
+`@aithos/protocol-core`'s `verifyEnvelope` (the 9-step check from spec
+§11.4) — same algorithm that `api.aithos.be` uses, no re-implementation
+needed.
+
 ## What lives where
 
-| Namespace        | Purpose                                                                                    |
-| ---------------- | ------------------------------------------------------------------------------------------ |
-| `sdk.compute`    | Bedrock invocation through the Aithos compute proxy (signed envelope, wallet enforcement). |
-| `sdk.web`        | Webpage extraction without an LLM through the web extractor proxy (1 mc / call).           |
-| `sdk.wallet`     | Stripe Checkout sessions for credit-pack top-ups, balance helpers.                         |
-| `sdk.ethos`      | Ethos-zone composition / parsing — re-exported from `@aithos/protocol-client`.             |
-| `sdk.onboarding` | First-run identity / DID flows — re-exported.                                              |
-| `sdk.mandates`   | Mint / verify mandates — re-exported.                                                      |
+| Namespace                  | Purpose                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| `sdk.auth`                 | Sign-in, sign-up, key custody — and `signEnvelope` for calls to your own Aithos-aware backend. |
+| `sdk.compute`              | Bedrock invocation through the Aithos compute proxy (signed envelope, wallet enforcement). |
+| `sdk.web`                  | Webpage extraction without an LLM through the web extractor proxy (1 mc / call).           |
+| `sdk.wallet`               | Stripe Checkout sessions for credit-pack top-ups, balance helpers.                         |
+| `sdk.ethos`                | Ethos-zone composition / parsing — re-exported from `@aithos/protocol-client`.             |
+| `sdk.onboarding`           | First-run identity / DID flows — re-exported.                                              |
+| `sdk.mandates`             | Mint / verify mandates — re-exported.                                                      |
 
 ## License
 

package/dist/src/auth.d.ts

@@ -1,6 +1,7 @@
 import { type AithosSessionStore } from "./session-store.js";
 import { type AithosKeyStore } from "./key-store.js";
 import { DelegateActor } from "./internal/delegate-state.js";
+import { type SignedEnvelope } from "./internal/envelope.js";
 import { OwnerSigners } from "./internal/owner-signers.js";
 /** Default URL of the Aithos auth backend. */
 export declare const DEFAULT_AUTH_BASE_URL = "https://auth.aithos.be";
@@ -304,6 +305,70 @@ export declare class AithosAuth {
     getOwnerInfo(): OwnerInfo | null;
     getDelegates(): readonly DelegateInfo[];
     canSignAsOwner(): boolean;
+    /**
+     * Sign an envelope (spec §11.2) as the active owner, to authenticate
+     * a call to a third-party Aithos-aware backend.
+     *
+     * Same primitive that SDK namespaces (`sdk.data`, `sdk.ethos`,
+     * `sdk.mandates`, ...) use internally to sign their own writes to
+     * `api.aithos.be`. Exposed here so apps can sign envelopes for their
+     * own backends — any service that verifies a `SignedEnvelope` per
+     * spec §11.2 (typically using `@aithos/protocol-core/envelope`'s
+     * `verifyEnvelope`) accepts the resulting object.
+     *
+     * The envelope binds the signature to `(iss, aud, method,
+     * params_hash, nonce, iat, exp)`, so it cannot be replayed against a
+     * different endpoint, method, or payload, and expires after
+     * `ttlSeconds` (default 60s, server-side typically caps at 300s).
+     *
+     * Usage:
+     *
+     * ```ts
+     * const envelope = await sdk.auth.signEnvelope({
+     *   aud: "https://api.example.com/v1/widgets",
+     *   method: "myapp.widgets.create",
+     *   params: { name: "Widget #1" },
+     * });
+     * await fetch("https://api.example.com/v1/widgets", {
+     *   method: "POST",
+     *   headers: { "content-type": "application/json" },
+     *   body: JSON.stringify({ ...payload, _envelope: envelope }),
+     * });
+     * ```
+     *
+     * @throws {AithosSDKError} `auth_not_signed_in` if no owner identity
+     *   is loaded (call `signIn` / `signUp` / `signInCustodial` first).
+     * @throws {AithosSDKError} `auth_invalid_sphere` if `sphere` is not
+     *   one of `"root" | "public" | "circle" | "self"`.
+     */
+    signEnvelope(args: {
+        /**
+         * Absolute URL of the target endpoint (scheme + host + path, no
+         * query, no fragment). The receiving server rejects the envelope if
+         * `aud` does not match the actual request URL.
+         */
+        readonly aud: string;
+        /** Fully-qualified JSON-RPC method name. */
+        readonly method: string;
+        /**
+         * Tool payload — what `params_hash` commits to. Will be
+         * JCS-canonicalized (RFC 8785 subset) before hashing, so JS object
+         * key order does not affect the result.
+         */
+        readonly params: unknown;
+        /**
+         * Which of the owner's four sphere keys signs. Default: `"public"`,
+         * which matches what SDK namespaces use for everyday writes.
+         * Choose `"root"`, `"circle"`, or `"self"` only if the receiving
+         * server specifically expects one of those (rare).
+         */
+        readonly sphere?: "root" | "public" | "circle" | "self";
+        /**
+         * Envelope lifetime in seconds. Default 60. Aithos servers cap
+         * at 300; third-party servers may apply their own cap.
+         */
+        readonly ttlSeconds?: number;
+    }): Promise<SignedEnvelope>;
     canSignAsDelegateFor(did: string): boolean;
     /**
      * Internal accessor used by sibling SDK namespaces (compute, wallet,
@@ -325,6 +390,42 @@ export declare class AithosAuth {
      * @internal
      */
     _findDelegateForSubject(did: string): DelegateActor | undefined;
+    /**
+     * Sign in with email + password, dispatching automatically between
+     * the legacy zero-knowledge flow ({@link signIn}) and the custodial
+     * flow ({@link signInCustodial}) based on which mode the account
+     * was provisioned with.
+     *
+     * Use this in apps that want a single sign-in form for users who
+     * may have been created under either mode (e.g. an app that's
+     * migrating from zk to custodial — pre-existing users stay zk
+     * forever, new ones go custodial, the SDK figures it out).
+     *
+     * Strategy: try {@link signInCustodial} first (the modern path).
+     * If the backend reports `auth_invalid_credentials` — which it
+     * uniformly returns for "wrong password", "unknown user", AND
+     * "user exists but not in custodial mode" (anti-enum) — fall
+     * back to {@link signIn} (zk).
+     *
+     * Other failure modes from the custodial path are NOT swallowed:
+     *   - `auth_email_not_verified` → propagate (user is custodial but
+     *     hasn't clicked the confirmation link yet; the app should
+     *     surface a "resend mail" CTA rather than retrying as zk,
+     *     which would also fail and mask the real cause)
+     *   - server / network errors → propagate (don't double the
+     *     incident by retrying through the other flow)
+     *
+     * Latency profile:
+     *   - Pure custodial (success or wrong pwd) : 1 round-trip
+     *   - Pure zk (any outcome)                 : 1 custodial probe + 2 zk
+     *   - Unknown email                         : same as zk worst case
+     *
+     * Anti-enum note: timing slightly leaks the mode (custodial path is
+     * faster than zk). Acceptable for V1 — rate limiting + strong
+     * passwords are the real defenses. A future strict-anti-enum mode
+     * could race both paths in parallel and accept the 2x backend load.
+     */
+    signInAuto(input: SignInInput): Promise<AithosSession>;
     signIn(input: SignInInput): Promise<AithosSession>;
     signUp(input: SignUpInput): Promise<SignUpResult>;
     /**

package/dist/src/auth.js

@@ -26,6 +26,7 @@ import { defaultSessionStore, } from "./session-store.js";
 import { defaultKeyStore, } from "./key-store.js";
 import { parseDelegateBundle, readDelegateBundleText, } from "./internal/delegate-bundle.js";
 import { DelegateActor, DelegateRegistry, } from "./internal/delegate-state.js";
+import { signOwnerEnvelope, } from "./internal/envelope.js";
 import { OwnerSigners } from "./internal/owner-signers.js";
 import { parseRecoveryFile, readRecoveryFileText, serializeRecoveryFile, } from "./internal/recovery-file.js";
 import { AithosSDKError } from "./types.js";
@@ -147,6 +148,64 @@ export class AithosAuth {
     canSignAsOwner() {
         return this.#ownerSigners !== null && !this.#ownerSigners.destroyed;
     }
+    /**
+     * Sign an envelope (spec §11.2) as the active owner, to authenticate
+     * a call to a third-party Aithos-aware backend.
+     *
+     * Same primitive that SDK namespaces (`sdk.data`, `sdk.ethos`,
+     * `sdk.mandates`, ...) use internally to sign their own writes to
+     * `api.aithos.be`. Exposed here so apps can sign envelopes for their
+     * own backends — any service that verifies a `SignedEnvelope` per
+     * spec §11.2 (typically using `@aithos/protocol-core/envelope`'s
+     * `verifyEnvelope`) accepts the resulting object.
+     *
+     * The envelope binds the signature to `(iss, aud, method,
+     * params_hash, nonce, iat, exp)`, so it cannot be replayed against a
+     * different endpoint, method, or payload, and expires after
+     * `ttlSeconds` (default 60s, server-side typically caps at 300s).
+     *
+     * Usage:
+     *
+     * ```ts
+     * const envelope = await sdk.auth.signEnvelope({
+     *   aud: "https://api.example.com/v1/widgets",
+     *   method: "myapp.widgets.create",
+     *   params: { name: "Widget #1" },
+     * });
+     * await fetch("https://api.example.com/v1/widgets", {
+     *   method: "POST",
+     *   headers: { "content-type": "application/json" },
+     *   body: JSON.stringify({ ...payload, _envelope: envelope }),
+     * });
+     * ```
+     *
+     * @throws {AithosSDKError} `auth_not_signed_in` if no owner identity
+     *   is loaded (call `signIn` / `signUp` / `signInCustodial` first).
+     * @throws {AithosSDKError} `auth_invalid_sphere` if `sphere` is not
+     *   one of `"root" | "public" | "circle" | "self"`.
+     */
+    async signEnvelope(args) {
+        if (!this.#ownerSigners || this.#ownerSigners.destroyed) {
+            throw new AithosSDKError("auth_not_signed_in", "signEnvelope: no owner is signed in. Call signIn / signUp / signInCustodial first.");
+        }
+        const sphere = args.sphere ?? "public";
+        if (sphere !== "root" &&
+            sphere !== "public" &&
+            sphere !== "circle" &&
+            sphere !== "self") {
+            throw new AithosSDKError("auth_invalid_sphere", `signEnvelope: invalid sphere "${sphere}". Expected one of: root, public, circle, self.`);
+        }
+        const signer = this.#ownerSigners.signerForSphere(sphere);
+        return signOwnerEnvelope({
+            iss: this.#ownerSigners.did,
+            aud: args.aud,
+            method: args.method,
+            params: args.params,
+            verificationMethod: `${this.#ownerSigners.did}#${sphere}`,
+            signer,
+            ttlSeconds: args.ttlSeconds,
+        });
+    }
     canSignAsDelegateFor(did) {
         const a = this.#delegates.findForSubject(did);
         return a !== undefined && !a.destroyed;
@@ -178,6 +237,63 @@ export class AithosAuth {
         return this.#delegates.findForSubject(did);
     }
     /* ------------------------------------------------------------------------ */
+    /*  Unified email + password — signInAuto (zk / custodial dispatch)         */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Sign in with email + password, dispatching automatically between
+     * the legacy zero-knowledge flow ({@link signIn}) and the custodial
+     * flow ({@link signInCustodial}) based on which mode the account
+     * was provisioned with.
+     *
+     * Use this in apps that want a single sign-in form for users who
+     * may have been created under either mode (e.g. an app that's
+     * migrating from zk to custodial — pre-existing users stay zk
+     * forever, new ones go custodial, the SDK figures it out).
+     *
+     * Strategy: try {@link signInCustodial} first (the modern path).
+     * If the backend reports `auth_invalid_credentials` — which it
+     * uniformly returns for "wrong password", "unknown user", AND
+     * "user exists but not in custodial mode" (anti-enum) — fall
+     * back to {@link signIn} (zk).
+     *
+     * Other failure modes from the custodial path are NOT swallowed:
+     *   - `auth_email_not_verified` → propagate (user is custodial but
+     *     hasn't clicked the confirmation link yet; the app should
+     *     surface a "resend mail" CTA rather than retrying as zk,
+     *     which would also fail and mask the real cause)
+     *   - server / network errors → propagate (don't double the
+     *     incident by retrying through the other flow)
+     *
+     * Latency profile:
+     *   - Pure custodial (success or wrong pwd) : 1 round-trip
+     *   - Pure zk (any outcome)                 : 1 custodial probe + 2 zk
+     *   - Unknown email                         : same as zk worst case
+     *
+     * Anti-enum note: timing slightly leaks the mode (custodial path is
+     * faster than zk). Acceptable for V1 — rate limiting + strong
+     * passwords are the real defenses. A future strict-anti-enum mode
+     * could race both paths in parallel and accept the 2x backend load.
+     */
+    async signInAuto(input) {
+        if (!input.email || !input.password) {
+            throw new AithosSDKError("auth_invalid_input", "signInAuto: email and password are required");
+        }
+        try {
+            const r = await this.signInCustodial(input);
+            return r.session;
+        }
+        catch (e) {
+            // Only fall back on the specific anti-enum sentinel — preserve
+            // other error codes (notably auth_email_not_verified) so the
+            // caller can surface the right UI hint.
+            if (e instanceof AithosSDKError &&
+                e.code === "auth_invalid_credentials") {
+                return await this.signIn(input);
+            }
+            throw e;
+        }
+    }
+    /* ------------------------------------------------------------------------ */
     /*  Email + password — signIn                                                */
     /* ------------------------------------------------------------------------ */
     async signIn(input) {

package/dist/src/data.js

@@ -32,6 +32,7 @@ import { sha256, sha512 } from "@noble/hashes/sha2.js";
 import { XChaCha20Poly1305 } from "@stablelib/xchacha20poly1305";
 import * as ed from "@noble/ed25519";
 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
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ed.etc.sha512Sync = (...m) => 
@@ -256,7 +257,14 @@ class DataClientImpl {
     /* -- JSON-RPC dispatch -- */
     async #call(path, method, params) {
         const aud = `${this.#pdsUrl}${path}`;
-        const envelope = this.#signEnvelope({ aud, method, params });
+        const envelope = await signOwnerEnvelope({
+            iss: this.#did,
+            aud,
+            method,
+            params,
+            verificationMethod: this.#vm,
+            signer: { sign: async (msg) => ed.sign(msg, this.#seed) },
+        });
         const body = {
             jsonrpc: "2.0",
             id: makeUlid(),
@@ -277,35 +285,6 @@ class DataClientImpl {
         }
         return json.result ?? {};
     }
-    /* -- Envelope signing (inlined subset of @aithos/protocol-core/envelope) -- */
-    #signEnvelope(args) {
-        const now = Math.floor(Date.now() / 1000);
-        const exp = now + 60;
-        const nonce = makeUlid();
-        const paramsHash = "sha256-" + sha256Hex(jcsCanonicalize(args.params));
-        const unsigned = {
-            "aithos-envelope": "0.1.0",
-            iss: this.#did,
-            aud: args.aud,
-            method: args.method,
-            iat: now,
-            exp,
-            nonce,
-            params_hash: paramsHash,
-            proof: {
-                type: "Ed25519Signature2020",
-                verificationMethod: this.#vm,
-                created: new Date(now * 1000).toISOString(),
-                proofValue: "",
-            },
-        };
-        const bytes = new TextEncoder().encode(jcsCanonicalize(unsigned));
-        const sig = ed.sign(bytes, this.#seed);
-        return {
-            ...unsigned,
-            proof: { ...unsigned.proof, proofValue: base64url(sig) },
-        };
-    }
     /* -- Crypto helpers -- */
     #collectionUrn(name) {
         return `urn:aithos:collection:${this.#did}:${name}`;

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0-alpha.33";
+export declare const VERSION = "0.1.0-alpha.35";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 export { AithosSDKError } from "./types.js";
@@ -13,6 +13,7 @@ export type { ComponentStyle, ExtractArgs, ExtractContent, ExtractData, ExtractF
 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 { 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";
 export { EthosClient, EthosNamespace, EthosZone, ZONE_NAMES, } from "./ethos.js";

package/dist/src/index.js

@@ -17,7 +17,7 @@
 // Public types specific to the SDK (`AithosSDKConfig`, `AithosSDKError`)
 // are exported from here. Endpoint config (`AithosSdkEndpoints`,
 // `DEFAULT_SDK_ENDPOINTS`) likewise.
-export const VERSION = "0.1.0-alpha.33";
+export const VERSION = "0.1.0-alpha.35";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
 // Re-export protocol-client's JSON-RPC error type so consumers can

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

@@ -0,0 +1,77 @@
+/**
+ * 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;
+    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;
+    /** 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,154 @@
+// 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 { sha256 } from "@noble/hashes/sha2.js";
+/**
+ * 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) {
+    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",
+        iss: args.iss,
+        aud: args.aud,
+        method: args.method,
+        iat,
+        exp,
+        nonce,
+        params_hash: paramsHash,
+        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}`);
+}
+//# sourceMappingURL=envelope.js.map

package/dist/test/envelope.test.d.ts

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

package/dist/test/envelope.test.js

@@ -0,0 +1,318 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Unit tests for the signed-envelope primitive — both the SDK-internal
+// helper `signOwnerEnvelope` and the public surface
+// `AithosAuth.signEnvelope`.
+//
+// Two levels of testing:
+//
+//   1. Internal helper: tests that can inject deterministic `now` and
+//      `nonce` to lock byte-for-byte output. These guard against any
+//      future drift in canonicalization, default TTL, field order, or
+//      crypto wiring.
+//
+//   2. Public surface: tests that exercise the full path through
+//      `AithosAuth.signEnvelope`, including sphere resolution, throw
+//      semantics, and binding to the loaded owner's DID. These guard
+//      the developer contract documented in the JSDoc.
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { createBrowserIdentity, sign as ed25519Sign, verify as ed25519Verify, } from "@aithos/protocol-client";
+import { AithosAuth, AithosSDKError, memoryKeyStore, noopStore, } from "../src/index.js";
+import { signOwnerEnvelope } from "../src/internal/envelope.js";
+import { serializeRecoveryFile } from "../src/internal/recovery-file.js";
+/* -------------------------------------------------------------------------- */
+/*  Test helpers                                                              */
+/* -------------------------------------------------------------------------- */
+/** Build a minimal AithosAuth, no network, no persistence. */
+function makeAuth() {
+    return new AithosAuth({
+        authBaseUrl: "https://auth.test",
+        fetch: (() => {
+            throw new Error("network not expected in this test");
+        }),
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+}
+/** Recovery-file text + DID for a fresh BrowserIdentity. */
+function recoveryTextFor(handle, displayName) {
+    const id = createBrowserIdentity(handle, displayName);
+    return { text: serializeRecoveryFile(id).text, did: id.did };
+}
+/** Inline signer wrapping a raw seed — matches what data.ts does. */
+function inlineSigner(seed) {
+    return {
+        async sign(message) {
+            return ed25519Sign(message, seed);
+        },
+    };
+}
+/** base64url decoder for envelope.proof.proofValue. */
+function base64urlDecode(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;
+}
+/** Canonicalize a JS value the same way envelope.ts does — for the
+ *  test that recomputes the bytes the server would verify against. */
+function canonical(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number")
+        return value.toString();
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map(canonical).join(",") + "]";
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        return ("{" +
+            keys.map((k) => JSON.stringify(k) + ":" + canonical(obj[k])).join(",") +
+            "}");
+    }
+    throw new Error(`Cannot canonicalize ${typeof value}`);
+}
+/* -------------------------------------------------------------------------- */
+/*  signOwnerEnvelope — internal helper                                       */
+/* -------------------------------------------------------------------------- */
+describe("signOwnerEnvelope (internal helper)", () => {
+    it("signs an envelope whose signature verifies under the signer's pubkey", async () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        const envelope = await signOwnerEnvelope({
+            iss: id.did,
+            aud: "https://api.example.com/v1/widgets",
+            method: "myapp.widgets.create",
+            params: { name: "Widget #1" },
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+        });
+        // Re-derive the exact bytes the server would canonicalize and check.
+        const { proof, ...unsignedWithEmptyProof } = envelope;
+        const unsigned = {
+            ...unsignedWithEmptyProof,
+            proof: { ...proof, proofValue: "" },
+        };
+        const bytes = new TextEncoder().encode(canonical(unsigned));
+        const sig = base64urlDecode(envelope.proof.proofValue);
+        assert.ok(ed25519Verify(sig, bytes, id.public.publicKey), "envelope signature must verify under the public-sphere pubkey");
+    });
+    it("produces an envelope conforming to spec §11.2 shape", async () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        const envelope = await signOwnerEnvelope({
+            iss: id.did,
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+        });
+        assert.equal(envelope["aithos-envelope"], "0.1.0");
+        assert.equal(envelope.iss, id.did);
+        assert.equal(envelope.aud, "https://api.example.com/v1/x");
+        assert.equal(envelope.method, "x.do");
+        assert.equal(typeof envelope.iat, "number");
+        assert.equal(typeof envelope.exp, "number");
+        assert.equal(typeof envelope.nonce, "string");
+        assert.ok(envelope.params_hash.startsWith("sha256-"));
+        assert.equal(envelope.proof.type, "Ed25519Signature2020");
+        assert.equal(envelope.proof.verificationMethod, `${id.did}#public`);
+        assert.equal(typeof envelope.proof.created, "string");
+        assert.ok(envelope.proof.proofValue.length > 0);
+    });
+    it("params_hash is canonical — key order does not affect the hash", async () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        const common = {
+            iss: id.did,
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+            now: new Date("2024-01-01T00:00:00.000Z"),
+            nonce: "01HXJZK7MK8VPN0FQR5T6Y2A3Z",
+        };
+        const env1 = await signOwnerEnvelope({
+            ...common,
+            params: { alpha: 1, beta: 2, gamma: [3, 4] },
+        });
+        const env2 = await signOwnerEnvelope({
+            ...common,
+            params: { gamma: [3, 4], alpha: 1, beta: 2 },
+        });
+        assert.equal(env1.params_hash, env2.params_hash, "params_hash must be stable across JS object key order");
+    });
+    it("respects an explicit ttlSeconds", async () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        const envelope = await signOwnerEnvelope({
+            iss: id.did,
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+            now: new Date("2024-01-01T00:00:00.000Z"),
+            ttlSeconds: 173,
+        });
+        assert.equal(envelope.exp - envelope.iat, 173);
+    });
+    it("defaults ttlSeconds to 60 — guards against drift from data.ts's prior behavior", async () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        const envelope = await signOwnerEnvelope({
+            iss: id.did,
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+            now: new Date("2024-01-01T00:00:00.000Z"),
+        });
+        assert.equal(envelope.exp - envelope.iat, 60);
+    });
+    it("nonce defaults to a fresh value per call (unique across calls)", async () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        const args = {
+            iss: id.did,
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+        };
+        const e1 = await signOwnerEnvelope(args);
+        const e2 = await signOwnerEnvelope(args);
+        assert.notEqual(e1.nonce, e2.nonce, "two successive calls must produce different nonces");
+    });
+    it("is deterministic when now and nonce are both injected (regression lock)", async () => {
+        // With identical inputs INCLUDING the override hooks, two calls must
+        // produce byte-for-byte identical envelopes — including the
+        // signature. This catches any future regression in canonicalization,
+        // ordering, default values, or signing path.
+        const id = createBrowserIdentity("alice", "Alice");
+        const args = {
+            iss: id.did,
+            aud: "https://api.example.com/v1/widgets",
+            method: "myapp.widgets.create",
+            params: { name: "Widget #1", count: 3, tags: ["a", "b"] },
+            signer: inlineSigner(id.public.seed),
+            verificationMethod: `${id.did}#public`,
+            now: new Date("2024-01-01T00:00:00.000Z"),
+            nonce: "01HXJZK7MK8VPN0FQR5T6Y2A3Z",
+            ttlSeconds: 120,
+        };
+        const e1 = await signOwnerEnvelope(args);
+        const e2 = await signOwnerEnvelope(args);
+        assert.deepEqual(e1, e2, "envelope must be deterministic under fixed inputs");
+        // Belt and braces: also lock the timestamp arithmetic.
+        assert.equal(e1.iat, 1704067200);
+        assert.equal(e1.exp, 1704067320);
+        assert.equal(e1.nonce, "01HXJZK7MK8VPN0FQR5T6Y2A3Z");
+        assert.equal(e1.proof.created, "2024-01-01T00:00:00.000Z");
+        assert.equal(e1.proof.verificationMethod, `${id.did}#public`);
+    });
+});
+/* -------------------------------------------------------------------------- */
+/*  AithosAuth.signEnvelope — public surface                                  */
+/* -------------------------------------------------------------------------- */
+describe("AithosAuth.signEnvelope (public surface)", () => {
+    it("defaults to the public sphere when no sphere is passed", async () => {
+        const auth = makeAuth();
+        const { text, did } = recoveryTextFor("alice", "Alice");
+        await auth.signInWithRecovery({ file: text });
+        const envelope = await auth.signEnvelope({
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: { ok: true },
+        });
+        assert.equal(envelope.iss, did);
+        assert.equal(envelope.proof.verificationMethod, `${did}#public`);
+    });
+    it("honors explicit sphere overrides (root / public / circle / self)", async () => {
+        const auth = makeAuth();
+        const { text, did } = recoveryTextFor("alice", "Alice");
+        await auth.signInWithRecovery({ file: text });
+        for (const sphere of ["root", "public", "circle", "self"]) {
+            const envelope = await auth.signEnvelope({
+                aud: "https://api.example.com/v1/x",
+                method: "x.do",
+                params: {},
+                sphere,
+            });
+            assert.equal(envelope.proof.verificationMethod, `${did}#${sphere}`, `verificationMethod must end with #${sphere}`);
+        }
+    });
+    it("throws auth_not_signed_in when no owner is loaded", async () => {
+        const auth = makeAuth();
+        await assert.rejects(() => auth.signEnvelope({
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "auth_not_signed_in");
+    });
+    it("throws auth_invalid_sphere when an unknown sphere is passed (untyped caller)", async () => {
+        const auth = makeAuth();
+        const { text } = recoveryTextFor("alice", "Alice");
+        await auth.signInWithRecovery({ file: text });
+        await assert.rejects(() => auth.signEnvelope({
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+            // Untyped callers (e.g. plain JS) could pass anything.
+            sphere: "bogus",
+        }), (e) => e instanceof AithosSDKError &&
+            e.code === "auth_invalid_sphere");
+    });
+    it("envelope ttlSeconds defaults to 60 — non-regression of internal default", async () => {
+        const auth = makeAuth();
+        const { text } = recoveryTextFor("alice", "Alice");
+        await auth.signInWithRecovery({ file: text });
+        const envelope = await auth.signEnvelope({
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+        });
+        assert.equal(envelope.exp - envelope.iat, 60);
+    });
+    it("envelope ttlSeconds is honored when provided", async () => {
+        const auth = makeAuth();
+        const { text } = recoveryTextFor("alice", "Alice");
+        await auth.signInWithRecovery({ file: text });
+        const envelope = await auth.signEnvelope({
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: {},
+            ttlSeconds: 240,
+        });
+        assert.equal(envelope.exp - envelope.iat, 240);
+    });
+    it("envelope signs with the correct sphere key (sig verifies under that pubkey)", async () => {
+        const auth = makeAuth();
+        const id = createBrowserIdentity("alice", "Alice");
+        const { text } = serializeRecoveryFile(id);
+        await auth.signInWithRecovery({ file: text });
+        const envelope = await auth.signEnvelope({
+            aud: "https://api.example.com/v1/x",
+            method: "x.do",
+            params: { x: 1 },
+            sphere: "circle",
+        });
+        // Reconstruct what the server would canonicalize-and-verify.
+        const { proof, ...unsignedWithEmptyProof } = envelope;
+        const unsigned = {
+            ...unsignedWithEmptyProof,
+            proof: { ...proof, proofValue: "" },
+        };
+        const bytes = new TextEncoder().encode(canonical(unsigned));
+        const sig = base64urlDecode(envelope.proof.proofValue);
+        assert.ok(ed25519Verify(sig, bytes, id.circle.publicKey), "envelope signed with sphere 'circle' must verify under circle.publicKey");
+    });
+});
+//# sourceMappingURL=envelope.test.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.33",
-  "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.",
+  "version": "0.1.0-alpha.35",
+  "description": "Aithos SDK \u2014 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",
     "sdk",
@@ -39,6 +39,15 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "check-types": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "npm run clean && npm run build && npm run build:test && cd dist && node --test",
+    "test:watch": "cd dist && node --test --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -54,13 +63,5 @@
   "publishConfig": {
     "access": "public",
     "tag": "alpha"
-  },
-  "scripts": {
-    "build": "tsc",
-    "build:test": "tsc -p tsconfig.test.json",
-    "check-types": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
-    "test": "npm run clean && npm run build && npm run build:test && cd dist && node --test",
-    "test:watch": "cd dist && node --test --watch",
-    "clean": "rm -rf dist"
   }
-}
+}