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

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

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

@@ -0,0 +1,128 @@
+/**
+ * Stored owner identity material. Treat as opaque from the consumer's
+ * point of view — its internal shape may evolve between SDK versions
+ * (e.g. when we migrate to `CryptoKey` references). Custom KeyStore
+ * implementations should round-trip the value as-is rather than
+ * peeking inside.
+ *
+ * @public
+ */
+export interface StoredOwnerKeys {
+    /** Schema version. Today: `"0.1.0-hex"`. */
+    readonly version: "0.1.0-hex";
+    readonly did: string;
+    readonly handle: string;
+    readonly displayName: string;
+    /** Hex-encoded 32-byte Ed25519 seeds — one per sphere. */
+    readonly seedsHex: {
+        readonly root: string;
+        readonly public: string;
+        readonly circle: string;
+        readonly self: string;
+    };
+    /** ISO-8601 timestamp of the original save. Informational. */
+    readonly savedAt: string;
+}
+/**
+ * Stored delegate session material. Opaque from the consumer's
+ * point of view; see {@link StoredOwnerKeys}.
+ *
+ * @public
+ */
+export interface StoredDelegateKeys {
+    readonly version: "0.1.0-hex";
+    /** DID of the subject whose ethos this mandate authorizes. */
+    readonly subjectDid: string;
+    /** Mandate id — used as the storage key. */
+    readonly mandateId: string;
+    /** Full §4.2 SignedMandate, stored as opaque JSON. */
+    readonly mandate: Record<string, unknown>;
+    /** Grantee URN, e.g. `urn:aithos:agent:bob1`. */
+    readonly granteeId: string;
+    /** Multibase-encoded Ed25519 grantee pubkey, matches `mandate.grantee.pubkey`. */
+    readonly granteePubkeyMultibase: string;
+    /** Hex-encoded 32-byte delegate Ed25519 seed. */
+    readonly delegateSeedHex: string;
+    readonly importedAt: string;
+}
+/**
+ * Persistence backend for owner identity material and delegate
+ * bundles. Methods are async because an IndexedDB-backed
+ * implementation is the default and IDB's API is async — sync stores
+ * are still trivial to write (`memoryKeyStore`) by returning
+ * pre-resolved promises.
+ *
+ * Implementations should never throw on missing records: a fresh
+ * device returns `null` from `loadOwner` and `[]` from
+ * `listDelegates`. They should only throw on hard I/O failures
+ * (quota exceeded, schema corruption). The SDK treats throws as
+ * "store unavailable, fall through to re-auth".
+ *
+ * @public
+ */
+export interface AithosKeyStore {
+    loadOwner(): Promise<StoredOwnerKeys | null>;
+    saveOwner(owner: StoredOwnerKeys): Promise<void>;
+    clearOwner(): Promise<void>;
+    listDelegates(): Promise<readonly StoredDelegateKeys[]>;
+    loadDelegate(mandateId: string): Promise<StoredDelegateKeys | null>;
+    saveDelegate(d: StoredDelegateKeys): Promise<void>;
+    removeDelegate(mandateId: string): Promise<void>;
+    clearAllDelegates(): Promise<void>;
+}
+/**
+ * In-memory key store. Loses everything on page reload — useful for
+ * tests, SSR, ephemeral CLI tools, and any workflow where you want a
+ * deliberately short-lived session.
+ *
+ * @public
+ */
+export declare function memoryKeyStore(): AithosKeyStore;
+/**
+ * Default IndexedDB database name used by {@link indexedDbKeyStore}.
+ * Apps that want to coexist with other Aithos-aware libs (or scope
+ * sessions per-tenant) can pass a custom `dbName`.
+ */
+export declare const DEFAULT_KEYSTORE_DB_NAME = "aithos-sdk-keys";
+interface IndexedDbKeyStoreOptions {
+    /** Database name. Defaults to {@link DEFAULT_KEYSTORE_DB_NAME}. */
+    readonly dbName?: string;
+    /**
+     * Inject a non-default IDBFactory — used by tests. Apps should not
+     * pass this; the global `indexedDB` is the right choice everywhere
+     * else.
+     *
+     * @internal
+     */
+    readonly factory?: IDBFactory;
+}
+/**
+ * IndexedDB-backed key store. Default in browser environments —
+ * persists across reloads and browser restarts, scoped to the
+ * page's origin.
+ *
+ * Storage shape today:
+ *
+ *   - object store `owner`     — single record at key `"self"`,
+ *                                shape {@link StoredOwnerKeys}
+ *   - object store `delegates` — keyPath `mandateId`, shape
+ *                                {@link StoredDelegateKeys}
+ *
+ * Both stores live in DB `aithos-sdk-keys` (configurable via
+ * `dbName`) at version 1. Future versions will trigger an upgrade
+ * transaction that migrates records into the new shape.
+ *
+ * @public
+ */
+export declare function indexedDbKeyStore(opts?: IndexedDbKeyStoreOptions): AithosKeyStore;
+/**
+ * Pick a sensible default: {@link indexedDbKeyStore} when an IDBFactory
+ * is reachable (browser environments), {@link memoryKeyStore} otherwise
+ * (Node, edge runtimes — apps running there should pass their own
+ * keystore explicitly).
+ *
+ * @public
+ */
+export declare function defaultKeyStore(): AithosKeyStore;
+export {};
+//# sourceMappingURL=key-store.d.ts.map

package/dist/src/key-store.js

@@ -0,0 +1,244 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/* -------------------------------------------------------------------------- */
+/*  In-memory implementation                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * In-memory key store. Loses everything on page reload — useful for
+ * tests, SSR, ephemeral CLI tools, and any workflow where you want a
+ * deliberately short-lived session.
+ *
+ * @public
+ */
+export function memoryKeyStore() {
+    let owner = null;
+    const delegates = new Map();
+    return {
+        async loadOwner() {
+            return owner;
+        },
+        async saveOwner(o) {
+            owner = o;
+        },
+        async clearOwner() {
+            owner = null;
+        },
+        async listDelegates() {
+            return [...delegates.values()];
+        },
+        async loadDelegate(mandateId) {
+            return delegates.get(mandateId) ?? null;
+        },
+        async saveDelegate(d) {
+            delegates.set(d.mandateId, d);
+        },
+        async removeDelegate(mandateId) {
+            delegates.delete(mandateId);
+        },
+        async clearAllDelegates() {
+            delegates.clear();
+        },
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  IndexedDB implementation                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * Default IndexedDB database name used by {@link indexedDbKeyStore}.
+ * Apps that want to coexist with other Aithos-aware libs (or scope
+ * sessions per-tenant) can pass a custom `dbName`.
+ */
+export const DEFAULT_KEYSTORE_DB_NAME = "aithos-sdk-keys";
+const STORE_OWNER = "owner";
+const STORE_DELEGATES = "delegates";
+/** The single owner record always lives at this key — the store has no keyPath. */
+const OWNER_KEY = "self";
+/**
+ * IndexedDB-backed key store. Default in browser environments —
+ * persists across reloads and browser restarts, scoped to the
+ * page's origin.
+ *
+ * Storage shape today:
+ *
+ *   - object store `owner`     — single record at key `"self"`,
+ *                                shape {@link StoredOwnerKeys}
+ *   - object store `delegates` — keyPath `mandateId`, shape
+ *                                {@link StoredDelegateKeys}
+ *
+ * Both stores live in DB `aithos-sdk-keys` (configurable via
+ * `dbName`) at version 1. Future versions will trigger an upgrade
+ * transaction that migrates records into the new shape.
+ *
+ * @public
+ */
+export function indexedDbKeyStore(opts = {}) {
+    const dbName = opts.dbName ?? DEFAULT_KEYSTORE_DB_NAME;
+    const factory = opts.factory ??
+        (typeof indexedDB !== "undefined" ? indexedDB : undefined);
+    if (!factory) {
+        throw new Error("indexedDbKeyStore: no IDBFactory available — pass `factory` for non-browser environments or use memoryKeyStore() instead.");
+    }
+    const open = () => new Promise((resolve, reject) => {
+        const req = factory.open(dbName, 1);
+        req.onupgradeneeded = () => {
+            const db = req.result;
+            if (!db.objectStoreNames.contains(STORE_OWNER)) {
+                db.createObjectStore(STORE_OWNER);
+            }
+            if (!db.objectStoreNames.contains(STORE_DELEGATES)) {
+                db.createObjectStore(STORE_DELEGATES, { keyPath: "mandateId" });
+            }
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error("indexedDB.open failed"));
+    });
+    const tx = async (stores, mode, run) => {
+        const db = await open();
+        try {
+            const t = db.transaction([...stores], mode);
+            const result = await Promise.resolve(run(t));
+            await new Promise((resolve, reject) => {
+                t.oncomplete = () => resolve();
+                t.onerror = () => reject(t.error ?? new Error("transaction failed"));
+                t.onabort = () => reject(t.error ?? new Error("transaction aborted"));
+            });
+            return result;
+        }
+        finally {
+            db.close();
+        }
+    };
+    const reqAsPromise = (req) => new Promise((resolve, reject) => {
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error("IDBRequest failed"));
+    });
+    return {
+        async loadOwner() {
+            return tx([STORE_OWNER], "readonly", async (t) => {
+                const v = await reqAsPromise(t.objectStore(STORE_OWNER).get(OWNER_KEY));
+                return validOwnerOrNull(v);
+            });
+        },
+        async saveOwner(owner) {
+            await tx([STORE_OWNER], "readwrite", (t) => {
+                t.objectStore(STORE_OWNER).put(owner, OWNER_KEY);
+            });
+        },
+        async clearOwner() {
+            await tx([STORE_OWNER], "readwrite", (t) => {
+                t.objectStore(STORE_OWNER).delete(OWNER_KEY);
+            });
+        },
+        async listDelegates() {
+            return tx([STORE_DELEGATES], "readonly", async (t) => {
+                const all = await reqAsPromise(t.objectStore(STORE_DELEGATES).getAll());
+                return all
+                    .map(validDelegateOrNull)
+                    .filter((d) => d !== null);
+            });
+        },
+        async loadDelegate(mandateId) {
+            return tx([STORE_DELEGATES], "readonly", async (t) => {
+                const v = await reqAsPromise(t.objectStore(STORE_DELEGATES).get(mandateId));
+                return validDelegateOrNull(v);
+            });
+        },
+        async saveDelegate(d) {
+            await tx([STORE_DELEGATES], "readwrite", (t) => {
+                t.objectStore(STORE_DELEGATES).put(d);
+            });
+        },
+        async removeDelegate(mandateId) {
+            await tx([STORE_DELEGATES], "readwrite", (t) => {
+                t.objectStore(STORE_DELEGATES).delete(mandateId);
+            });
+        },
+        async clearAllDelegates() {
+            await tx([STORE_DELEGATES], "readwrite", (t) => {
+                t.objectStore(STORE_DELEGATES).clear();
+            });
+        },
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  Default picker                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * Pick a sensible default: {@link indexedDbKeyStore} when an IDBFactory
+ * is reachable (browser environments), {@link memoryKeyStore} otherwise
+ * (Node, edge runtimes — apps running there should pass their own
+ * keystore explicitly).
+ *
+ * @public
+ */
+export function defaultKeyStore() {
+    if (typeof indexedDB !== "undefined") {
+        try {
+            return indexedDbKeyStore();
+        }
+        catch {
+            return memoryKeyStore();
+        }
+    }
+    return memoryKeyStore();
+}
+/* -------------------------------------------------------------------------- */
+/*  Runtime validators                                                        */
+/*                                                                             */
+/*  Storage values come from JSON-shaped records that may have been written   */
+/*  by an older SDK version, by a corrupted process, or by an attacker with   */
+/*  IDB write access. The SDK trusts only records that round-trip through     */
+/*  these validators; anything else is treated as "no record" so the resume   */
+/*  path falls through to re-auth.                                            */
+/* -------------------------------------------------------------------------- */
+function validOwnerOrNull(v) {
+    if (typeof v !== "object" || v === null)
+        return null;
+    const o = v;
+    if (o["version"] !== "0.1.0-hex")
+        return null;
+    if (typeof o["did"] !== "string")
+        return null;
+    if (typeof o["handle"] !== "string")
+        return null;
+    if (typeof o["displayName"] !== "string")
+        return null;
+    const seeds = o["seedsHex"];
+    if (typeof seeds !== "object" || seeds === null)
+        return null;
+    const s = seeds;
+    for (const k of ["root", "public", "circle", "self"]) {
+        if (typeof s[k] !== "string")
+            return null;
+        if (s[k].length !== 64)
+            return null;
+    }
+    if (typeof o["savedAt"] !== "string")
+        return null;
+    return o;
+}
+function validDelegateOrNull(v) {
+    if (typeof v !== "object" || v === null)
+        return null;
+    const o = v;
+    if (o["version"] !== "0.1.0-hex")
+        return null;
+    if (typeof o["subjectDid"] !== "string")
+        return null;
+    if (typeof o["mandateId"] !== "string")
+        return null;
+    if (typeof o["granteeId"] !== "string")
+        return null;
+    if (typeof o["granteePubkeyMultibase"] !== "string")
+        return null;
+    if (typeof o["delegateSeedHex"] !== "string")
+        return null;
+    if (o["delegateSeedHex"].length !== 64)
+        return null;
+    if (typeof o["mandate"] !== "object" || o["mandate"] === null)
+        return null;
+    if (typeof o["importedAt"] !== "string")
+        return null;
+    return o;
+}
+//# sourceMappingURL=key-store.js.map