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

package/dist/src/rotate.js

@@ -0,0 +1,298 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * Ethos rotation — building blocks.
+ *
+ * This module currently ships the foundational, fully-tested piece of the
+ * "rotate an Ethos completely" feature: {@link buildSignedRotatedDidDocument},
+ * which produces a root-signed did.json that rotates one or more sphere keys
+ * (and carries / adds the optional `#data` sphere), extending `aithos.rotated[]`
+ * so it is accepted by the existing `aithos.rotate_sphere_key` primitive.
+ *
+ * Root is NEVER rotated — it IS the DID (`did:aithos:<root-mb>`). Rotating it
+ * would change the DID (= a new identity).
+ *
+ * Browser-safe: only depends on `@aithos/protocol-core/{did,canonical}`
+ * (node-free) + the SDK's own X25519 derivation + @noble. So it runs both in
+ * the migration script (node) and in a future in-browser app.aithos.be/rotate
+ * page.
+ *
+ * NOTE (scope): the *full* `rotateEthos` orchestration also re-encrypts the
+ * Ethos circle/self ZONES under the new sphere keys (publish a fresh edition)
+ * before the rotated sphere keys take effect — otherwise existing encrypted
+ * zone content sealed to the old sphere kex becomes unreadable. That zone
+ * recopy goes through `@aithos/protocol-client`'s editor (loadEditSnapshot /
+ * publishZoneEdit) and is built/tested separately. This module deliberately
+ * exposes only the did.json builder so callers can't accidentally rotate the
+ * Ethos sphere keys without the matching zone recopy.
+ */
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha2.js";
+import { canonicalize } from "@aithos/protocol-core/canonical";
+import { ed25519PublicKeyToMultibase, x25519PublicKeyToMultibase, } from "@aithos/protocol-core/did";
+import { ed25519SeedToX25519PublicKey } from "./internal/cmk-wrap.js";
+// noble/ed25519 v2 needs a sync sha512 for sync sign.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ed.etc.sha512Sync = (...m) => 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+sha512(ed.etc.concatBytes(...m));
+const SPHERES = ["public", "circle", "self"];
+/**
+ * Build + sign a rotated did.json. The result rotates every Ethos sphere whose
+ * seed differs from the previously-published key, appends one `rotated[]` entry
+ * per changed sphere (preserving prior history), carries / adds `#data`, and is
+ * signed by `#root`. Ready to POST via `aithos.rotate_sphere_key`.
+ *
+ * @param seeds        the post-rotation seeds (same root, new sphere seeds).
+ * @param previousDoc  the currently-published did.json (old pubkeys + history).
+ * @param displayName  display name to carry on the doc.
+ * @param reason       audit reason recorded on each new rotated entry.
+ */
+export function buildSignedRotatedDidDocument(seeds, previousDoc, displayName, reason = "rotate") {
+    const rootPub = ed.getPublicKey(seeds.root);
+    const did = "did:aithos:" + ed25519PublicKeyToMultibase(rootPub);
+    if (previousDoc.id !== did) {
+        throw new Error("buildSignedRotatedDidDocument: root seed does not match previousDoc.id — root (and the DID) is never rotated");
+    }
+    const now = new Date().toISOString();
+    const verificationMethod = SPHERES.map((sphere) => ({
+        id: `${did}#${sphere}`,
+        type: "Ed25519VerificationKey2020",
+        controller: did,
+        publicKeyMultibase: ed25519PublicKeyToMultibase(ed.getPublicKey(seeds[sphere])),
+    }));
+    const keyAgreement = SPHERES.map((sphere) => ({
+        id: `${did}#${sphere}-kex`,
+        type: "X25519KeyAgreementKey2020",
+        controller: did,
+        publicKeyMultibase: x25519PublicKeyToMultibase(ed25519SeedToX25519PublicKey(seeds[sphere])),
+    }));
+    if (seeds.data) {
+        verificationMethod.push({
+            id: `${did}#data`,
+            type: "Ed25519VerificationKey2020",
+            controller: did,
+            publicKeyMultibase: ed25519PublicKeyToMultibase(ed.getPublicKey(seeds.data)),
+        });
+        keyAgreement.push({
+            id: `${did}#data-kex`,
+            type: "X25519KeyAgreementKey2020",
+            controller: did,
+            publicKeyMultibase: x25519PublicKeyToMultibase(ed25519SeedToX25519PublicKey(seeds.data)),
+        });
+    }
+    // Carry prior history + append one entry per Ethos sphere whose key changed.
+    const prevKeyOf = (sphere) => previousDoc.verificationMethod.find((vm) => vm.id === `${did}#${sphere}`)?.publicKeyMultibase;
+    const rotated = [...(previousDoc.aithos.rotated ?? [])];
+    for (const sphere of SPHERES) {
+        const oldKey = prevKeyOf(sphere);
+        const newKey = ed25519PublicKeyToMultibase(ed.getPublicKey(seeds[sphere]));
+        if (oldKey && oldKey !== newKey) {
+            rotated.push({ sphere, previous_key: oldKey, rotated_at: now, reason });
+        }
+    }
+    const unsigned = {
+        "@context": ["https://www.w3.org/ns/did/v1", "https://aithos.dev/spec/v0.1"],
+        id: did,
+        verificationMethod,
+        keyAgreement,
+        aithos: { version: "0.1.0", display_name: displayName, created_at: now, rotated },
+        proof: {
+            type: "Ed25519Signature2020",
+            created: now,
+            verificationMethod: `${did}#root`,
+            proofPurpose: "assertionMethod",
+            proofValue: "",
+        },
+    };
+    const bytes = new TextEncoder().encode(canonicalize(unsigned));
+    const sig = ed.sign(bytes, seeds.root);
+    return { ...unsigned, proof: { ...unsigned.proof, proofValue: base64url(sig) } };
+}
+function base64url(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/* ========================================================================== */
+/*  rotateEthos — full rotation orchestration                                 */
+/* ========================================================================== */
+import { loadEditSnapshot, publishZoneEdit, } from "@aithos/protocol-client";
+import { addDataSphereWrap } from "./migrate.js";
+import { DEFAULT_API_BASE_URL } from "./auth.js";
+import { signOwnerEnvelope } from "./internal/envelope.js";
+import { parseRecoveryFile, } from "./internal/recovery-file.js";
+/**
+ * Fully rotate an Ethos: new public/circle/self/#data keys (root unchanged),
+ * re-encrypt the Ethos zones under the new keys (fresh edition), and dual-wrap
+ * every data collection toward the new #data. Entirely client-side; uses only
+ * existing API primitives (rotate_sphere_key, publish_ethos_edition via the
+ * protocol-client editor, rotate_cmk). Returns a new recovery file — persist it.
+ *
+ * Option (a) semantics: the new head edition (carrying all current content) is
+ * fully verifiable under the new keys; pre-rotation edition snapshots are not
+ * re-verifiable against the rotated did.json (rotated[] retains the old keys so
+ * a rotated[]-aware verifier can be added later without re-rotating).
+ */
+export async function rotateEthos(recovery, opts = {}) {
+    const rec = typeof recovery === "string" ? parseRecoveryFile(recovery) : recovery;
+    const fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const apiBaseUrl = (opts.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
+    const reason = opts.reason ?? "full-rotation";
+    const did = rec.did;
+    const rootSeed = hexToBytes(rec.seedsHex.root);
+    const log = opts.onProgress ?? (() => { });
+    // 1. Fetch the currently-published did.json.
+    log("fetching current did.json");
+    const idRes = await apiRpc(fetchImpl, apiBaseUrl, "aithos.get_identity", { did }, did, rootSeed);
+    const previousDoc = (idRes.object ?? idRes);
+    // 2. Generate fresh seeds (root kept).
+    const newSeeds = {
+        root: rootSeed,
+        public: randomSeed32(),
+        circle: randomSeed32(),
+        self: randomSeed32(),
+        data: randomSeed32(),
+    };
+    const newDataHex = bytesToHex(newSeeds.data);
+    // 3. Probe whether an Ethos edition exists (mockable apiRpc — NOT the
+    //    protocol-client editor, so this stays testable). Absent → -32020.
+    let hadEdition = true;
+    try {
+        log("probing for an existing edition");
+        await apiRpc(fetchImpl, apiBaseUrl, "aithos.get_ethos_manifest", { did }, did, rootSeed);
+    }
+    catch (e) {
+        if (e.code === -32020 || /not found/i.test(String(e.message))) {
+            hadEdition = false;
+        }
+        else {
+            throw e;
+        }
+    }
+    if (hadEdition && opts.skipZones && !opts.force) {
+        throw new Error("rotateEthos: this Ethos has an edition with (possibly encrypted) zone content, but skipZones was set. " +
+            "Rotating the sphere keys without recopying the zones would orphan that content. " +
+            "Pass force: true only if you are certain the zones hold nothing to preserve.");
+    }
+    // 4. Publish the rotated did.json (root-signed) via rotate_sphere_key.
+    log("publishing rotated did.json");
+    const rotatedDoc = buildSignedRotatedDidDocument(newSeeds, previousDoc, rec.displayName, reason);
+    await apiRpc(fetchImpl, apiBaseUrl, "aithos.rotate_sphere_key", { new_did_document: rotatedDoc }, did, rootSeed);
+    // 5. Republish a fresh edition under the NEW identity → zones re-sealed under
+    //    the new sphere keys (LIVE: protocol-client editor, ambient api endpoint).
+    //    loadEditSnapshot decrypts circle/self with the OLD keys; publishZoneEdit
+    //    re-seals them under the NEW identity.
+    let editionRepublished = false;
+    if (hadEdition && !opts.skipZones) {
+        log("loading current edition (old keys) + republishing (new keys)");
+        const snap = await loadEditSnapshot(did, toStoredIdentity(rec));
+        const newStored = toStoredIdentity({
+            handle: rec.handle,
+            displayName: rec.displayName,
+            did,
+            seedsHex: {
+                root: rec.seedsHex.root,
+                public: bytesToHex(newSeeds.public),
+                circle: bytesToHex(newSeeds.circle),
+                self: bytesToHex(newSeeds.self),
+                data: newDataHex,
+            },
+        });
+        await publishZoneEdit({
+            identity: newStored,
+            snapshot: snap,
+            newPublicSections: snap.publicSections ?? [],
+            ...(snap.circleSections ? { newCircleSections: snap.circleSections } : {}),
+            ...(snap.selfSections ? { newSelfSections: snap.selfSections } : {}),
+        });
+        editionRepublished = true;
+    }
+    // 6. Dual-wrap every collection toward the NEW #data (unwrap with old seeds).
+    log("re-keying collections toward the new #data");
+    const collections = await addDataSphereWrap(rec, {
+        ...(opts.pdsUrl ? { pdsUrl: opts.pdsUrl } : {}),
+        fetch: fetchImpl,
+        targetDataSeedHex: newDataHex,
+    });
+    // 7. New recovery (all new seeds; persist!).
+    const updatedRecoveryFile = JSON.stringify({
+        aithos_recovery_version: "0.1.0-plaintext",
+        handle: rec.handle,
+        display_name: rec.displayName,
+        did,
+        seeds_hex: {
+            root: rec.seedsHex.root,
+            public: bytesToHex(newSeeds.public),
+            circle: bytesToHex(newSeeds.circle),
+            self: bytesToHex(newSeeds.self),
+            data: newDataHex,
+        },
+        saved_at: new Date().toISOString(),
+    }, null, 2);
+    return {
+        did,
+        rotatedSpheres: ["public", "circle", "self"],
+        editionRepublished,
+        hadEdition,
+        collections,
+        updatedRecoveryFile,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  helpers                                                                   */
+/* -------------------------------------------------------------------------- */
+function toStoredIdentity(rec) {
+    return {
+        handle: rec.handle,
+        displayName: rec.displayName,
+        did: rec.did,
+        seeds: {
+            root: rec.seedsHex.root,
+            public: rec.seedsHex.public,
+            circle: rec.seedsHex.circle,
+            self: rec.seedsHex.self,
+            ...(rec.seedsHex.data ? { data: rec.seedsHex.data } : {}),
+        },
+    };
+}
+async function apiRpc(fetchImpl, apiBaseUrl, method, params, did, rootSeed) {
+    const url = `${apiBaseUrl}/mcp/primitives/${method.includes("get_") ? "read" : "write"}`;
+    const envelope = await signOwnerEnvelope({
+        iss: did,
+        aud: url,
+        method,
+        params,
+        verificationMethod: `${did}#root`,
+        signer: { sign: async (m) => ed.sign(m, rootSeed) },
+    });
+    const r = await fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: `rotate_${Date.now()}`, method, params: { ...params, _envelope: envelope } }),
+    });
+    const j = (await r.json());
+    if (j.error) {
+        throw Object.assign(new Error(`${method} failed: ${j.error.message}`), { code: j.error.code });
+    }
+    return j.result ?? {};
+}
+function randomSeed32() {
+    const buf = new Uint8Array(32);
+    globalThis.crypto?.getRandomValues(buf);
+    return buf;
+}
+function hexToBytes(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(hex.substr(i * 2, 2), 16);
+    return out;
+}
+function bytesToHex(b) {
+    let out = "";
+    for (let i = 0; i < b.length; i++)
+        out += b[i].toString(16).padStart(2, "0");
+    return out;
+}
+//# sourceMappingURL=rotate.js.map

package/dist/src/sdk.d.ts

@@ -1,9 +1,11 @@
 import type { AithosAuth } from "./auth.js";
-import { ComputeNamespace } from "./compute.js";
+import { AppsNamespace } from "./apps.js";
+import { ComputeNamespace, type ComputeWorkingSet } from "./compute.js";
 import { type AithosSdkEndpoints } from "./endpoints.js";
-import { EthosNamespace } from "./ethos.js";
+import { EthosNamespace, type ZoneName } from "./ethos.js";
 import { MandatesNamespace } from "./mandates.js";
 import { WalletNamespace } from "./wallet.js";
+import { WebNamespace } from "./web.js";
 export interface AithosSDKConfig {
     /**
      * The {@link AithosAuth} instance the SDK reads sign-in state from.
@@ -44,8 +46,40 @@ export declare class AithosSDK {
     readonly ethos: EthosNamespace;
     /** Mandate lifecycle namespace — create / list / revoke. */
     readonly mandates: MandatesNamespace;
+    /** Web extraction namespace — aithos.web_extract through the web extractor proxy. */
+    readonly web: WebNamespace;
+    /**
+     * App lifecycle namespace — sponsorship mandates + app-credit top-ups.
+     * V0.1 (2026-05-27 — draft §13). Lets a developer pre-pay a pool that
+     * funds compute calls from their app's users within explicit caps.
+     */
+    readonly apps: AppsNamespace;
     constructor(config: AithosSDKConfig);
     /** DID of the currently signed-in owner, or null if no owner is loaded. */
     get userDid(): string | null;
+    /**
+     * Build the client-decrypted working-set for an agentic conversation.
+     *
+     * Reads the requested ethos zones for `did` through {@link EthosNamespace}
+     * (which decrypts client-side using the active owner/delegate keys) and
+     * packages them into the {@link ComputeWorkingSet} shape that
+     * `sdk.compute.runConversation({ workingSet })` consumes.
+     *
+     * Only zones the session can actually read are included: a zone the
+     * mandate does not grant (or whose delegate wrap is missing) throws
+     * `ethos_zone_unreadable` / `ethos_anonymous_private_zone` on read and is
+     * silently skipped — so the working-set is naturally bounded by what the
+     * caller is authorized to see. The proxy never holds a decryption key;
+     * this is where the plaintext is produced (see PLATFORM-COMPUTE-AGENTIC-MCP.md §4).
+     *
+     * Structured (gamma) data collections are not loaded here in v1 — attach
+     * them to the returned object's `data` field yourself if needed.
+     *
+     * @param did     Subject DID whose ethos to read (usually the signed-in owner).
+     * @param opts.zones  Zones to attempt. Defaults to all three.
+     */
+    buildWorkingSet(did: string, opts?: {
+        readonly zones?: readonly ZoneName[];
+    }): Promise<ComputeWorkingSet>;
 }
 //# sourceMappingURL=sdk.d.ts.map

package/dist/src/sdk.js

@@ -1,10 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Mathieu Colla
-import { ComputeNamespace } from "./compute.js";
+import { AppsNamespace } from "./apps.js";
+import { ComputeNamespace, } from "./compute.js";
 import { resolveEndpoints } from "./endpoints.js";
+import { configureEndpoints as configureProtocolClientEndpoints } from "@aithos/protocol-client";
 import { EthosNamespace } from "./ethos.js";
 import { MandatesNamespace } from "./mandates.js";
+import { AithosSDKError } from "./types.js";
 import { WalletNamespace } from "./wallet.js";
+import { WebNamespace } from "./web.js";
 export class AithosSDK {
     /** Resolved endpoint configuration (defaults + caller overrides). */
     endpoints;
@@ -20,6 +24,14 @@ export class AithosSDK {
     ethos;
     /** Mandate lifecycle namespace — create / list / revoke. */
     mandates;
+    /** Web extraction namespace — aithos.web_extract through the web extractor proxy. */
+    web;
+    /**
+     * App lifecycle namespace — sponsorship mandates + app-credit top-ups.
+     * V0.1 (2026-05-27 — draft §13). Lets a developer pre-pay a pool that
+     * funds compute calls from their app's users within explicit caps.
+     */
+    apps;
     constructor(config) {
         if (!config.auth) {
             throw new TypeError("AithosSDK: config.auth is required");
@@ -30,6 +42,10 @@ export class AithosSDK {
         this.endpoints = resolveEndpoints(config.endpoints);
         this.appDid = config.appDid;
         this.auth = config.auth;
+        // Ethos reads/writes flow through @aithos/protocol-client, which keeps its
+        // own (module-scoped) api/cdn config. Propagate ours so that pointing the
+        // SDK at a dev account (endpoints.api/cdn) also redirects the ethos calls.
+        configureProtocolClientEndpoints({ api: this.endpoints.api, cdn: this.endpoints.cdn });
         const fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
         this.compute = new ComputeNamespace({
             auth: config.auth,
@@ -53,10 +69,65 @@ export class AithosSDK {
             endpoints: this.endpoints,
             fetch: fetchImpl,
         });
+        this.web = new WebNamespace({
+            auth: config.auth,
+            appDid: config.appDid,
+            endpoints: this.endpoints,
+            fetch: fetchImpl,
+        });
+        this.apps = new AppsNamespace({
+            auth: config.auth,
+            appDid: config.appDid,
+            endpoints: this.endpoints,
+            fetch: fetchImpl,
+        });
     }
     /** DID of the currently signed-in owner, or null if no owner is loaded. */
     get userDid() {
         return this.auth.getOwnerInfo()?.did ?? null;
     }
+    /**
+     * Build the client-decrypted working-set for an agentic conversation.
+     *
+     * Reads the requested ethos zones for `did` through {@link EthosNamespace}
+     * (which decrypts client-side using the active owner/delegate keys) and
+     * packages them into the {@link ComputeWorkingSet} shape that
+     * `sdk.compute.runConversation({ workingSet })` consumes.
+     *
+     * Only zones the session can actually read are included: a zone the
+     * mandate does not grant (or whose delegate wrap is missing) throws
+     * `ethos_zone_unreadable` / `ethos_anonymous_private_zone` on read and is
+     * silently skipped — so the working-set is naturally bounded by what the
+     * caller is authorized to see. The proxy never holds a decryption key;
+     * this is where the plaintext is produced (see PLATFORM-COMPUTE-AGENTIC-MCP.md §4).
+     *
+     * Structured (gamma) data collections are not loaded here in v1 — attach
+     * them to the returned object's `data` field yourself if needed.
+     *
+     * @param did     Subject DID whose ethos to read (usually the signed-in owner).
+     * @param opts.zones  Zones to attempt. Defaults to all three.
+     */
+    async buildWorkingSet(did, opts) {
+        const zones = opts?.zones ?? ["public", "circle", "self"];
+        const client = await this.ethos.of(did);
+        const ethos = {};
+        for (const zone of zones) {
+            try {
+                const sections = await client.zone(zone).sections();
+                ethos[zone] = sections.map((s) => ({
+                    id: s.id,
+                    title: s.title,
+                    body: s.body,
+                }));
+            }
+            catch (e) {
+                // Zone not granted / not decryptable for this session → skip it.
+                if (e instanceof AithosSDKError)
+                    continue;
+                throw e;
+            }
+        }
+        return { ethos };
+    }
 }
 //# sourceMappingURL=sdk.js.map

package/dist/src/transcribe-resilience.d.ts

@@ -0,0 +1,57 @@
+export type LocalPendingStatus = "uploading" | "running" | "completed" | "failed";
+export interface LocalPendingEntry {
+    readonly jobId: string;
+    readonly status: LocalPendingStatus;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly meta?: Record<string, unknown>;
+}
+/**
+ * Framework-agnostic observable registry of in-flight transcription jobs.
+ * Persisted to localStorage when available (so it survives reloads), with
+ * an in-memory fallback otherwise. Subscribe with `subscribe(listener)`;
+ * read with `getSnapshot()` (stable reference between mutations, so it
+ * plugs directly into React's `useSyncExternalStore`).
+ */
+export declare class LocalPendingTranscribeTracker {
+    #private;
+    constructor();
+    /** Current entries. Stable reference until the next mutation. */
+    getSnapshot(): readonly LocalPendingEntry[];
+    list(): readonly LocalPendingEntry[];
+    /** Subscribe to changes. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    upsert(jobId: string, status: LocalPendingStatus, meta?: Record<string, unknown>): void;
+    remove(jobId: string): void;
+    clear(): void;
+}
+export interface TranscribeDraftMeta {
+    readonly title?: string;
+    readonly tag?: string;
+    readonly contentType?: string;
+}
+export interface TranscribeDraftRecord {
+    readonly draftId: string;
+    readonly blob: Blob;
+    readonly metadata: TranscribeDraftMeta;
+    readonly createdAt: number;
+}
+export declare class TranscribeDraftUnavailableError extends Error {
+    constructor();
+}
+/**
+ * IndexedDB-backed queue of recorded audio Blobs. Save a recording the
+ * instant it finishes (before any network), then `upload` it when the
+ * user confirms — so a flaky network or a closed tab never loses audio.
+ * Browser-only: methods reject with {@link TranscribeDraftUnavailableError}
+ * when IndexedDB is absent.
+ */
+export declare class TranscribeDraftStore {
+    save(blob: Blob, meta?: TranscribeDraftMeta): Promise<{
+        readonly draftId: string;
+    }>;
+    list(): Promise<readonly TranscribeDraftRecord[]>;
+    get(draftId: string): Promise<TranscribeDraftRecord | null>;
+    delete(draftId: string): Promise<void>;
+}
+//# sourceMappingURL=transcribe-resilience.d.ts.map