@aithos/sdk 0.1.0-alpha.4 → 0.1.0-alpha.41

package/dist/src/internal/owner-signers.d.ts

@@ -0,0 +1,78 @@
+import { type BlobPlaintext, type BrowserIdentity, type StoredIdentity } from "@aithos/protocol-client";
+import type { StoredOwnerKeys } from "../key-store.js";
+import { type Signer } from "./signer.js";
+/**
+ * The four signing capabilities of an authenticated owner.
+ *
+ * The `did`, `handle`, `displayName` fields are public metadata.
+ * The four signers expose only `publicKey` + `sign` — never the
+ * underlying seed bytes.
+ */
+export declare class OwnerSigners {
+    #private;
+    readonly did: string;
+    readonly handle: string;
+    readonly displayName: string;
+    readonly root: Signer;
+    readonly public: Signer;
+    readonly circle: Signer;
+    readonly self: Signer;
+    constructor(args: {
+        did: string;
+        handle: string;
+        displayName: string;
+        root: Signer;
+        public: Signer;
+        circle: Signer;
+        self: Signer;
+    });
+    /**
+     * Build from a {@link BrowserIdentity}. The seeds inside `identity`
+     * are defensively copied into fresh signers — mutating the
+     * BrowserIdentity afterwards does not affect the signers, and the
+     * caller may zeroize the original identity immediately.
+     */
+    static fromBrowserIdentity(identity: BrowserIdentity): OwnerSigners;
+    /**
+     * Build from a {@link StoredIdentity} — the persisted shape used by
+     * extension-kit's IndexedDbKeystore (hex-encoded seeds).
+     *
+     * Internally calls `browserIdentityFromStored` to derive
+     * `publicKey`s, then wraps. The caller may discard the StoredIdentity
+     * afterwards.
+     */
+    static fromStoredIdentity(stored: StoredIdentity): OwnerSigners;
+    /**
+     * Build from the SDK's own {@link StoredOwnerKeys} shape — what the
+     * KeyStore round-trips for owner-side resume.
+     */
+    static fromStoredOwnerKeys(stored: StoredOwnerKeys): OwnerSigners;
+    /**
+     * Build from a {@link BlobPlaintext} — the parsed payload of the
+     * password-decrypted vault blob returned by `loginVerify`. Hex
+     * seeds are turned into KeyPairs eagerly; the plaintext input is
+     * not retained.
+     */
+    static fromBlobPlaintext(plaintext: BlobPlaintext): OwnerSigners;
+    /**
+     * Resolve a sphere name to its signer. Convenience for callers that
+     * have the sphere as a string ("public" | "circle" | "self") rather
+     * than a typed accessor.
+     */
+    signerForSphere(sphere: "root" | "public" | "circle" | "self"): Signer;
+    /**
+     * Internal — project to a {@link StoredIdentity} for protocol-client
+     * interop. Reads seed bytes via {@link RawSeedSigner._unsafeKeyPair}
+     * on each signer and hex-encodes them. Throws if any signer is not
+     * a RawSeedSigner (which can happen post-migration to SubtleSigner;
+     * at that point protocol-client must accept Signer-shaped objects
+     * directly and this method goes away).
+     *
+     * @internal
+     */
+    _unsafeStoredIdentity(): StoredIdentity;
+    /** Zeroize all four private seeds. Idempotent. */
+    destroy(): void;
+    get destroyed(): boolean;
+}
+//# sourceMappingURL=owner-signers.d.ts.map

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

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// OwnerSigners — the four-keypair signing capability of an Aithos
+// owner identity, behind the {@link Signer} interface.
+//
+// SDK-internal only — NOT exported from the package barrel.
+//
+// An owner identity has four key roles: `root` (controls the DID
+// document), `public` (signs writes / envelopes for the public zone),
+// `circle` (signs writes for the friends zone), `self` (signs writes
+// for the private zone). All four are Ed25519. The X25519 keys used
+// for HPKE zone encryption are deterministically derived from the
+// Ed25519 seeds at use-site (see protocol-client/crypto/kex), so we
+// only need to hold the Ed25519 signers here.
+//
+// This class is the in-memory home for those signers throughout an
+// authenticated session. The auth namespace owns a single instance,
+// hands references to the compute / wallet / ethos namespaces, and
+// destroys it on `signOut`.
+import { browserIdentityFromStored, } from "@aithos/protocol-client";
+import { RawSeedSigner } from "./signer.js";
+/**
+ * The four signing capabilities of an authenticated owner.
+ *
+ * The `did`, `handle`, `displayName` fields are public metadata.
+ * The four signers expose only `publicKey` + `sign` — never the
+ * underlying seed bytes.
+ */
+export class OwnerSigners {
+    did;
+    handle;
+    displayName;
+    root;
+    public;
+    circle;
+    self;
+    #destroyed = false;
+    constructor(args) {
+        this.did = args.did;
+        this.handle = args.handle;
+        this.displayName = args.displayName;
+        this.root = args.root;
+        this.public = args.public;
+        this.circle = args.circle;
+        this.self = args.self;
+    }
+    /**
+     * Build from a {@link BrowserIdentity}. The seeds inside `identity`
+     * are defensively copied into fresh signers — mutating the
+     * BrowserIdentity afterwards does not affect the signers, and the
+     * caller may zeroize the original identity immediately.
+     */
+    static fromBrowserIdentity(identity) {
+        return new OwnerSigners({
+            did: identity.did,
+            handle: identity.handle,
+            displayName: identity.displayName,
+            root: new RawSeedSigner(identity.root.seed, identity.root.publicKey),
+            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),
+        });
+    }
+    /**
+     * Build from a {@link StoredIdentity} — the persisted shape used by
+     * extension-kit's IndexedDbKeystore (hex-encoded seeds).
+     *
+     * Internally calls `browserIdentityFromStored` to derive
+     * `publicKey`s, then wraps. The caller may discard the StoredIdentity
+     * afterwards.
+     */
+    static fromStoredIdentity(stored) {
+        return OwnerSigners.fromBrowserIdentity(browserIdentityFromStored(stored));
+    }
+    /**
+     * Build from the SDK's own {@link StoredOwnerKeys} shape — what the
+     * KeyStore round-trips for owner-side resume.
+     */
+    static fromStoredOwnerKeys(stored) {
+        return OwnerSigners.fromStoredIdentity({
+            version: "0.1.0",
+            handle: stored.handle,
+            displayName: stored.displayName,
+            did: stored.did,
+            seeds: stored.seedsHex,
+            savedAt: stored.savedAt,
+        });
+    }
+    /**
+     * Build from a {@link BlobPlaintext} — the parsed payload of the
+     * password-decrypted vault blob returned by `loginVerify`. Hex
+     * seeds are turned into KeyPairs eagerly; the plaintext input is
+     * not retained.
+     */
+    static fromBlobPlaintext(plaintext) {
+        return OwnerSigners.fromStoredIdentity({
+            version: "0.1.0",
+            handle: plaintext.identity.handle,
+            displayName: plaintext.identity.displayName,
+            did: plaintext.identity.did,
+            seeds: plaintext.seeds,
+            savedAt: new Date().toISOString(),
+        });
+    }
+    /**
+     * Resolve a sphere name to its signer. Convenience for callers that
+     * have the sphere as a string ("public" | "circle" | "self") rather
+     * than a typed accessor.
+     */
+    signerForSphere(sphere) {
+        if (this.#destroyed) {
+            throw new Error("OwnerSigners: cannot use destroyed signers");
+        }
+        switch (sphere) {
+            case "root":
+                return this.root;
+            case "public":
+                return this.public;
+            case "circle":
+                return this.circle;
+            case "self":
+                return this.self;
+        }
+    }
+    /**
+     * Internal — project to a {@link StoredIdentity} for protocol-client
+     * interop. Reads seed bytes via {@link RawSeedSigner._unsafeKeyPair}
+     * on each signer and hex-encodes them. Throws if any signer is not
+     * a RawSeedSigner (which can happen post-migration to SubtleSigner;
+     * at that point protocol-client must accept Signer-shaped objects
+     * directly and this method goes away).
+     *
+     * @internal
+     */
+    _unsafeStoredIdentity() {
+        if (this.#destroyed) {
+            throw new Error("OwnerSigners: cannot project destroyed signers");
+        }
+        return {
+            version: "0.1.0",
+            handle: this.handle,
+            displayName: this.displayName,
+            did: this.did,
+            seeds: {
+                root: bytesToHexLocal(asRawSeed(this.root, "root")._unsafeKeyPair().seed),
+                public: bytesToHexLocal(asRawSeed(this.public, "public")._unsafeKeyPair().seed),
+                circle: bytesToHexLocal(asRawSeed(this.circle, "circle")._unsafeKeyPair().seed),
+                self: bytesToHexLocal(asRawSeed(this.self, "self")._unsafeKeyPair().seed),
+            },
+            savedAt: new Date().toISOString(),
+        };
+    }
+    /** Zeroize all four private seeds. Idempotent. */
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.root.destroy();
+        this.public.destroy();
+        this.circle.destroy();
+        this.self.destroy();
+        this.#destroyed = true;
+    }
+    get destroyed() {
+        return this.#destroyed;
+    }
+}
+function asRawSeed(s, role) {
+    if (!(s instanceof RawSeedSigner)) {
+        throw new Error(`OwnerSigners._unsafeStoredIdentity: signer for "${role}" is not a RawSeedSigner; this method is incompatible with non-extractable key implementations.`);
+    }
+    return s;
+}
+function bytesToHexLocal(b) {
+    let out = "";
+    for (let i = 0; i < b.length; i++)
+        out += b[i].toString(16).padStart(2, "0");
+    return out;
+}
+//# sourceMappingURL=owner-signers.js.map

package/dist/src/internal/protocol-client-bridge.d.ts

@@ -0,0 +1,8 @@
+import type { KeyPair } from "@aithos/protocol-client";
+import type { DelegateActor } from "./delegate-state.js";
+import type { OwnerSigners } from "./owner-signers.js";
+/** Extract the raw KeyPair for one of the owner's spheres. */
+export declare function ownerKeyPair(owner: OwnerSigners, sphere: "root" | "public" | "circle" | "self"): KeyPair;
+/** Extract the raw KeyPair held by a delegate actor. */
+export declare function delegateKeyPair(actor: DelegateActor): KeyPair;
+//# sourceMappingURL=protocol-client-bridge.d.ts.map

package/dist/src/internal/protocol-client-bridge.js

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+import { AithosSDKError } from "../types.js";
+import { RawSeedSigner } from "./signer.js";
+/** Extract the raw KeyPair for one of the owner's spheres. */
+export function ownerKeyPair(owner, sphere) {
+    const signer = owner.signerForSphere(sphere);
+    return rawKeyPair(signer, `owner.${sphere}`);
+}
+/** Extract the raw KeyPair held by a delegate actor. */
+export function delegateKeyPair(actor) {
+    return rawKeyPair(actor.signer, `delegate(${actor.mandateId})`);
+}
+function rawKeyPair(signer, role) {
+    if (!(signer instanceof RawSeedSigner)) {
+        throw new AithosSDKError("sdk_unsupported_signer", `${role}: signer is not RawSeedSigner — protocol-client interop requires raw seed access until upstream gains a Signer-shaped API`);
+    }
+    return signer._unsafeKeyPair();
+}
+//# sourceMappingURL=protocol-client-bridge.js.map

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

@@ -0,0 +1,29 @@
+import type { BrowserIdentity } from "@aithos/protocol-client";
+export interface ParsedRecoveryFile {
+    readonly handle: string;
+    readonly displayName: string;
+    readonly did: string;
+    readonly seedsHex: {
+        readonly root: string;
+        readonly public: string;
+        readonly circle: string;
+        readonly self: string;
+    };
+}
+/**
+ * Parse a recovery JSON string. Throws {@link AithosSDKError} with
+ * `code === "auth_invalid_recovery_file"` if the input is malformed.
+ */
+export declare function parseRecoveryFile(text: string): ParsedRecoveryFile;
+/** Read the file (Blob or already-decoded string) into UTF-8 text. */
+export declare function readRecoveryFileText(file: Blob | string): Promise<string>;
+/**
+ * Build the recovery-file JSON blob from a fresh BrowserIdentity. Used
+ * by `signUp` so the same writer/reader code handles both ends of the
+ * round-trip.
+ */
+export declare function serializeRecoveryFile(identity: BrowserIdentity): {
+    readonly text: string;
+    readonly filename: string;
+};
+//# sourceMappingURL=recovery-file.d.ts.map

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

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+import { AithosSDKError } from "../types.js";
+const HEX_64 = /^[0-9a-f]{64}$/;
+/**
+ * Parse a recovery JSON string. Throws {@link AithosSDKError} with
+ * `code === "auth_invalid_recovery_file"` if the input is malformed.
+ */
+export function parseRecoveryFile(text) {
+    let obj;
+    try {
+        obj = JSON.parse(text);
+    }
+    catch {
+        throw bad("not valid JSON");
+    }
+    if (typeof obj !== "object" || obj === null) {
+        throw bad("not a JSON object");
+    }
+    const o = obj;
+    const ver = o["aithos_recovery_version"];
+    if (typeof ver !== "string" || !ver.startsWith("0.1.0")) {
+        throw bad(`unsupported aithos_recovery_version: ${String(ver)}`);
+    }
+    // Both shapes use snake_case for `display_name` and `seeds_hex`.
+    const handle = o["handle"];
+    const displayName = o["display_name"];
+    const did = o["did"];
+    const seedsRaw = o["seeds_hex"];
+    if (typeof handle !== "string" || !handle)
+        throw bad("missing handle");
+    if (typeof displayName !== "string")
+        throw bad("missing display_name");
+    if (typeof did !== "string" || !did.startsWith("did:")) {
+        throw bad("missing or malformed did");
+    }
+    if (typeof seedsRaw !== "object" || seedsRaw === null) {
+        throw bad("missing seeds_hex");
+    }
+    const seeds = seedsRaw;
+    for (const k of ["root", "public", "circle", "self"]) {
+        const v = seeds[k];
+        if (typeof v !== "string" || !HEX_64.test(v)) {
+            throw bad(`seeds_hex.${k}: expected 64-char lowercase hex`);
+        }
+    }
+    return {
+        handle,
+        displayName,
+        did,
+        seedsHex: {
+            root: seeds["root"],
+            public: seeds["public"],
+            circle: seeds["circle"],
+            self: seeds["self"],
+        },
+    };
+}
+/** Read the file (Blob or already-decoded string) into UTF-8 text. */
+export async function readRecoveryFileText(file) {
+    if (typeof file === "string")
+        return file;
+    return file.text();
+}
+/**
+ * Build the recovery-file JSON blob from a fresh BrowserIdentity. Used
+ * by `signUp` so the same writer/reader code handles both ends of the
+ * round-trip.
+ */
+export function serializeRecoveryFile(identity) {
+    const payload = {
+        aithos_recovery_version: "0.1.0-plaintext",
+        handle: identity.handle,
+        display_name: identity.displayName,
+        did: identity.did,
+        seeds_hex: {
+            root: bytesToHex(identity.root.seed),
+            public: bytesToHex(identity.public.seed),
+            circle: bytesToHex(identity.circle.seed),
+            self: bytesToHex(identity.self.seed),
+        },
+        saved_at: new Date().toISOString(),
+    };
+    return {
+        text: JSON.stringify(payload, null, 2),
+        filename: `aithos-recovery-${identity.handle}.json`,
+    };
+}
+function bad(detail) {
+    return new AithosSDKError("auth_invalid_recovery_file", `recovery file is invalid: ${detail}`);
+}
+function bytesToHex(b) {
+    let out = "";
+    for (let i = 0; i < b.length; i++)
+        out += b[i].toString(16).padStart(2, "0");
+    return out;
+}
+//# sourceMappingURL=recovery-file.js.map

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

@@ -0,0 +1,59 @@
+import { type KeyPair } from "@aithos/protocol-client";
+/**
+ * Capability to produce Ed25519 signatures over a fixed key. The key
+ * material itself is not exposed — only the public key (which is, by
+ * definition, public) and the {@link sign} method.
+ *
+ * `sign` returns a Promise<Uint8Array> even when the underlying
+ * implementation is synchronous (e.g. {@link RawSeedSigner}) so future
+ * implementations backed by `crypto.subtle.sign` can drop in without
+ * breaking callers.
+ */
+export interface Signer {
+    /** 32-byte Ed25519 public key. */
+    readonly publicKey: Uint8Array;
+    /** Sign `message` and return the 64-byte Ed25519 signature. */
+    sign(message: Uint8Array): Promise<Uint8Array>;
+    /** Zeroize any private material the signer holds. Idempotent. */
+    destroy(): void;
+}
+/**
+ * Today's implementation: wraps a raw 32-byte Ed25519 seed and signs
+ * via `@noble/ed25519`. Holds the seed in a defensively-copied
+ * Uint8Array bound to a private field, so mutating the constructor
+ * input afterwards does not affect the signer.
+ *
+ * Migration note: when we move to Web Crypto non-extractable keys,
+ * this class is replaced by a `SubtleSigner` that holds a `CryptoKey`
+ * reference and calls `crypto.subtle.sign("Ed25519", key, message)`.
+ * The {@link Signer} interface stays the same, so all callers (the
+ * SessionVault, the auth namespace, the ethos publish path) keep
+ * working unchanged.
+ */
+export declare class RawSeedSigner implements Signer {
+    #private;
+    readonly publicKey: Uint8Array;
+    /**
+     * @param seed       32-byte Ed25519 seed (the private half).
+     * @param publicKey  32-byte Ed25519 public key matching `seed`.
+     * Both arrays are defensively copied — the caller may zeroize their
+     * originals immediately.
+     */
+    constructor(seed: Uint8Array, publicKey: Uint8Array);
+    sign(message: Uint8Array): Promise<Uint8Array>;
+    destroy(): void;
+    /**
+     * Internal escape hatch for protocol-client interop. Returns a KeyPair
+     * usable with `buildSignedEnvelope({ signer })` and friends, which
+     * today take a raw seed. Marked `_unsafe` because it surfaces the
+     * private seed bytes — only callers within `@aithos/sdk` should use
+     * it, and never propagate the result outside the SDK boundary.
+     *
+     * When protocol-client gains a Signer-shaped API (post-alpha), this
+     * method goes away and SubtleSigner becomes pluggable upstream.
+     *
+     * @internal
+     */
+    _unsafeKeyPair(): KeyPair;
+}
+//# sourceMappingURL=signer.d.ts.map

package/dist/src/internal/signer.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Internal Signer abstraction.
+//
+// SDK-internal only — NOT exported from the package barrel. The whole
+// point of this file is to draw the line between "what the SDK consumer
+// sees" (no seeds, no key bytes, just verbs like `addSection` and
+// `publish`) and "how the SDK signs internally" (today: raw Ed25519
+// seeds via @noble; tomorrow: non-extractable CryptoKeys via
+// crypto.subtle).
+//
+// The {@link Signer} interface is the contract. {@link RawSeedSigner}
+// is today's implementation. When we migrate to Web Crypto
+// non-extractable keys, a {@link SubtleSigner} drops in beside it
+// implementing the same interface, and nothing visible to the SDK
+// consumer changes.
+//
+// `sign` is async-shaped from the start so the migration to
+// `crypto.subtle.sign` (which is async) doesn't ripple through the
+// caller graph as a breaking interface change.
+import { sign as ed25519Sign } from "@aithos/protocol-client";
+/**
+ * Today's implementation: wraps a raw 32-byte Ed25519 seed and signs
+ * via `@noble/ed25519`. Holds the seed in a defensively-copied
+ * Uint8Array bound to a private field, so mutating the constructor
+ * input afterwards does not affect the signer.
+ *
+ * Migration note: when we move to Web Crypto non-extractable keys,
+ * this class is replaced by a `SubtleSigner` that holds a `CryptoKey`
+ * reference and calls `crypto.subtle.sign("Ed25519", key, message)`.
+ * The {@link Signer} interface stays the same, so all callers (the
+ * SessionVault, the auth namespace, the ethos publish path) keep
+ * working unchanged.
+ */
+export class RawSeedSigner {
+    publicKey;
+    #seed;
+    #destroyed = false;
+    /**
+     * @param seed       32-byte Ed25519 seed (the private half).
+     * @param publicKey  32-byte Ed25519 public key matching `seed`.
+     * Both arrays are defensively copied — the caller may zeroize their
+     * originals immediately.
+     */
+    constructor(seed, publicKey) {
+        if (seed.length !== 32) {
+            throw new Error(`RawSeedSigner: seed must be 32 bytes, got ${seed.length}`);
+        }
+        if (publicKey.length !== 32) {
+            throw new Error(`RawSeedSigner: publicKey must be 32 bytes, got ${publicKey.length}`);
+        }
+        this.#seed = new Uint8Array(seed);
+        this.publicKey = new Uint8Array(publicKey);
+    }
+    async sign(message) {
+        if (this.#destroyed) {
+            throw new Error("RawSeedSigner: cannot sign with a destroyed signer");
+        }
+        return ed25519Sign(message, this.#seed);
+    }
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#seed.fill(0);
+        this.#destroyed = true;
+    }
+    /**
+     * Internal escape hatch for protocol-client interop. Returns a KeyPair
+     * usable with `buildSignedEnvelope({ signer })` and friends, which
+     * today take a raw seed. Marked `_unsafe` because it surfaces the
+     * private seed bytes — only callers within `@aithos/sdk` should use
+     * it, and never propagate the result outside the SDK boundary.
+     *
+     * When protocol-client gains a Signer-shaped API (post-alpha), this
+     * method goes away and SubtleSigner becomes pluggable upstream.
+     *
+     * @internal
+     */
+    _unsafeKeyPair() {
+        if (this.#destroyed) {
+            throw new Error("RawSeedSigner: cannot use a destroyed signer");
+        }
+        return { seed: this.#seed, publicKey: this.publicKey };
+    }
+}
+//# sourceMappingURL=signer.js.map