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

package/dist/src/migrate.d.ts

@@ -0,0 +1,105 @@
+import { type ParsedRecoveryFile } from "./internal/recovery-file.js";
+import { type CmkEnvelope } from "./internal/cmk-wrap.js";
+export interface MigrateOptions {
+    /** api.aithos.be base URL. Defaults to {@link DEFAULT_API_BASE_URL}. */
+    readonly apiBaseUrl?: string;
+    /** PDS base URL. Defaults to `https://pds.aithos.be`. Pass the raw
+     *  execute-api URL when the vanity host isn't live in your environment. */
+    readonly pdsUrl?: string;
+    /** Custom fetch (tests / SSR). Defaults to globalThis.fetch. */
+    readonly fetch?: typeof fetch;
+    /** When true, compute and report planned rekeys but DO NOT write. */
+    readonly dryRun?: boolean;
+    /**
+     * How to onboard a collection onto #data:
+     *   - "replace" (default): swap the owner wrap from the legacy sphere to
+     *     #data. Use for a clean cutover when NOTHING still reads the collection
+     *     under the old key. WARNING: breaks any app still reading under the
+     *     legacy key (e.g. linkedone reading under #root).
+     *   - "add": KEEP the legacy owner wrap and ADD a second owner wrap sealed to
+     *     #data (dual-read). Both the legacy app and a #data client can read the
+     *     same data. Requires @aithos/sdk with the multi-wrap owner reader
+     *     (this release). Safe, non-destructive — recommended for live accounts.
+     */
+    readonly mode?: "replace" | "add";
+    /**
+     * Re-key collections toward a DIFFERENT `#data` key than the one in the
+     * recovery file. Used by `rotateEthos`: unwrap with the recovery's (old)
+     * sphere seeds, wrap toward this NEW `#data` seed. When omitted, the target
+     * is the recovery file's own `#data` seed (the normal migration case).
+     */
+    readonly targetDataSeedHex?: string;
+    /** Progress callback for CLIs / UIs. */
+    readonly onProgress?: (e: MigrateProgress) => void;
+}
+export type MigrateProgress = {
+    phase: "ensure-data-sphere";
+    status: "start" | "added" | "already-present";
+} | {
+    phase: "rekey";
+    status: "collection";
+    collection: string;
+    result: CollectionRekeyStatus;
+};
+export interface EnsureDataSphereResult {
+    readonly did: string;
+    /** True when this call added #data (false = already present server-side). */
+    readonly added: boolean;
+    /** The #data sphere seed (hex). The caller MUST persist this — it's the new
+     *  key the account signs/reads data under. Returned even when `added` is
+     *  false (it's the same seed that's now published). */
+    readonly dataSeedHex: string;
+    /** Convenience: the recovery file serialized WITH the #data seed merged in. */
+    readonly updatedRecoveryFile: string;
+}
+export type CollectionRekeyStatus = "rekeyed" | "data-wrap-added" | "already-data" | "planned" | "skipped-no-owner-wrap" | "unwrap-failed";
+export interface CollectionRekeyEntry {
+    readonly name: string;
+    readonly urn: string;
+    readonly status: CollectionRekeyStatus;
+    /** Which seed successfully unwrapped the CMK (auto-discovery result). */
+    readonly unwrappedWith?: SphereName;
+    /** Count of non-owner (delegate) wraps preserved into the new envelope. */
+    readonly delegateWrapsPreserved?: number;
+    /** Pre-mutation cmk_envelope, kept so a human can roll back if needed. */
+    readonly backupEnvelope?: CmkEnvelope;
+}
+export interface RekeyReport {
+    readonly did: string;
+    readonly dryRun: boolean;
+    readonly collections: readonly CollectionRekeyEntry[];
+}
+export interface FullMigrationResult {
+    readonly ensure: EnsureDataSphereResult;
+    readonly rekey: RekeyReport;
+    /** Recovery file with the #data seed — persist this for the user. */
+    readonly updatedRecoveryFile: string;
+}
+type SphereName = "data" | "data-old" | "self" | "circle" | "public" | "root";
+/**
+ * Idempotently add the `#data` sphere to a (possibly legacy) identity and
+ * re-publish its did.json. Accepts either a parsed recovery file or the raw
+ * recovery JSON text.
+ */
+export declare function ensureDataSphere(owner: ParsedRecoveryFile | string, opts?: MigrateOptions): Promise<EnsureDataSphereResult>;
+/**
+ * Re-wrap every collection's CMK from its legacy sphere to the owner's `#data`
+ * key. Idempotent: collections already readable under `#data` are skipped.
+ * Requires that the recovery file carries a `#data` seed (run
+ * {@link ensureDataSphere} first, or pass {@link FullMigrationResult}).
+ */
+export declare function rekeyLegacyCollections(owner: ParsedRecoveryFile | string, opts?: MigrateOptions): Promise<RekeyReport>;
+/**
+ * Dual-read onboarding: KEEP each collection's legacy owner wrap and ADD a
+ * second owner wrap sealed to #data, so the existing app (reading under the
+ * legacy key) AND a #data client both decrypt the same data. Non-destructive.
+ * Thin wrapper over {@link rekeyLegacyCollections} with `mode: "add"`.
+ */
+export declare function addDataSphereWrap(owner: ParsedRecoveryFile | string, opts?: MigrateOptions): Promise<RekeyReport>;
+/**
+ * Run the full migration: ensureDataSphere then rekeyLegacyCollections.
+ * Returns the updated recovery file (with the #data seed) — persist it.
+ */
+export declare function migrateLegacyEthosToDataSphere(recoveryText: string, opts?: MigrateOptions): Promise<FullMigrationResult>;
+export {};
+//# sourceMappingURL=migrate.d.ts.map

package/dist/src/migrate.js

@@ -0,0 +1,367 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * Legacy `#data` sphere migration.
+ *
+ * Identities created before the dedicated `#data` sphere landed
+ * (spec/data/02-key-hierarchy.md) have only root/public/circle/self keys and
+ * therefore:
+ *   1. their published did.json has no `#data` / `#data-kex` entry, and
+ *   2. their existing data collections' CMK is wrapped to the X25519 key
+ *      derived from whatever sphere seed the *old* app passed to
+ *      `createDataClient({ sphereSeed })` (in practice `#self`/`#public`), even
+ *      though the wrap is LABELLED `${did}#data-kex` (the label is hard-coded
+ *      in the SDK regardless of the seed).
+ *
+ * This module performs a two-step, idempotent, owner-only migration so the
+ * account converges on the protocol-intended `#data` convention:
+ *
+ *   A. {@link ensureDataSphere} — generate a `#data` keypair (if absent),
+ *      re-publish the did.json with the appended `#data` + `#data-kex` entries
+ *      (root-signed) via the additive `aithos.augment_identity` primitive.
+ *
+ *   B. {@link rekeyLegacyCollections} — for each collection, unwrap the CMK
+ *      with the (auto-discovered) legacy sphere seed, re-wrap the SAME CMK to
+ *      the `#data` X25519 key (label unchanged: `${did}#data-kex`), and persist
+ *      via the existing `aithos.data.rotate_cmk` primitive. The CMK value is
+ *      unchanged, so per-record DEKs stay valid — no record rewrap. Delegate
+ *      wraps are preserved.
+ *
+ * Guardrails: dry-run mode, a pre-mutation backup of every `cmk_envelope`, a
+ * LOCAL round-trip verification (the freshly built `#data` wrap is unwrapped
+ * with the data seed and checked byte-equal to the CMK) BEFORE any server
+ * write, and idempotence (a collection already readable under `#data` is left
+ * untouched).
+ *
+ * Nothing here mutates any existing handler or primitive: A uses the new
+ * additive `aithos.augment_identity`, B reuses the existing `rotate_cmk`.
+ */
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha2.js";
+import { browserIdentityFromStored, signedDidDocument, } from "@aithos/protocol-client";
+import { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
+import { DEFAULT_API_BASE_URL } from "./auth.js";
+import { signOwnerEnvelope } from "./internal/envelope.js";
+import { parseRecoveryFile, serializeRecoveryFile, } from "./internal/recovery-file.js";
+import { ed25519SeedToX25519PrivateKey, ed25519SeedToX25519PublicKey, tryUnwrapCmk, wrapCmkForRecipient, } 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));
+/* -------------------------------------------------------------------------- */
+/*  A — ensureDataSphere                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * Idempotently add the `#data` sphere to a (possibly legacy) identity and
+ * re-publish its did.json. Accepts either a parsed recovery file or the raw
+ * recovery JSON text.
+ */
+export async function ensureDataSphere(owner, opts = {}) {
+    const rec = typeof owner === "string" ? parseRecoveryFile(owner) : owner;
+    const fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const apiBaseUrl = (opts.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
+    opts.onProgress?.({ phase: "ensure-data-sphere", status: "start" });
+    // Generate a #data seed if the recovery file doesn't carry one yet.
+    const hadData = typeof rec.seedsHex.data === "string";
+    const dataSeedHex = hadData ? rec.seedsHex.data : bytesToHex(randomSeed32());
+    // Rebuild the full identity (incl. #data) and produce a root-signed did.json
+    // that carries the appended #data + #data-kex entries.
+    const identity = browserIdentityFromStored({
+        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,
+            data: dataSeedHex,
+        },
+    });
+    const signedDoc = signedDidDocument(identity);
+    // Publish via the additive augment_identity primitive (idempotent server-side).
+    const rootSeed = hexToBytes(rec.seedsHex.root);
+    const url = `${apiBaseUrl}/mcp/primitives/write`;
+    const params = {
+        did_document: signedDoc,
+        handle: rec.handle,
+        display_name: rec.displayName,
+    };
+    const res = await jsonRpc(fetchImpl, url, "aithos.augment_identity", params, {
+        iss: rec.did,
+        aud: url,
+        verificationMethod: `${rec.did}#root`,
+        signSeed: rootSeed,
+    });
+    const added = res.data_sphere_added ?? !hadData;
+    // Merge the #data seed into a recovery file the caller can persist.
+    const updatedRecoveryFile = serializeRecoveryWithData(rec, dataSeedHex);
+    opts.onProgress?.({
+        phase: "ensure-data-sphere",
+        status: added ? "added" : "already-present",
+    });
+    return { did: rec.did, added, dataSeedHex, updatedRecoveryFile };
+}
+/* -------------------------------------------------------------------------- */
+/*  B — rekeyLegacyCollections                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * Re-wrap every collection's CMK from its legacy sphere to the owner's `#data`
+ * key. Idempotent: collections already readable under `#data` are skipped.
+ * Requires that the recovery file carries a `#data` seed (run
+ * {@link ensureDataSphere} first, or pass {@link FullMigrationResult}).
+ */
+export async function rekeyLegacyCollections(owner, opts = {}) {
+    const rec = typeof owner === "string" ? parseRecoveryFile(owner) : owner;
+    if (!rec.seedsHex.data && !opts.targetDataSeedHex) {
+        throw new Error("rekeyLegacyCollections: recovery file has no #data seed. Run ensureDataSphere first and persist its updatedRecoveryFile (or pass targetDataSeedHex for a rotation).");
+    }
+    const fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const pdsUrl = (opts.pdsUrl ?? DEFAULT_SDK_ENDPOINTS.pds).replace(/\/$/, "");
+    const dryRun = opts.dryRun ?? false;
+    const mode = opts.mode ?? "replace";
+    const did = rec.did;
+    const rootSeed = hexToBytes(rec.seedsHex.root);
+    const dataKexRecipient = `${did}#data-kex`;
+    // Target #data key the wraps will be sealed TO. Defaults to the recovery's
+    // own #data; rotateEthos passes a fresh one (rotation).
+    const targetDataSeed = opts.targetDataSeedHex
+        ? hexToBytes(opts.targetDataSeedHex)
+        : hexToBytes(rec.seedsHex.data); // guard above guarantees one of the two
+    const dataPub = ed25519SeedToX25519PublicKey(targetDataSeed);
+    const dataPriv = ed25519SeedToX25519PrivateKey(targetDataSeed);
+    // Candidate seeds to UNWRAP an existing owner wrap with (auto-discovery). The
+    // target #data key is NOT in this list — "already sealed to target" is
+    // detected separately via `dataPriv`. When rotating (target ≠ recovery
+    // #data), the recovery's OLD #data is a valid unwrap key, included as
+    // "data-old".
+    const candidates = [
+        { name: "self", priv: ed25519SeedToX25519PrivateKey(hexToBytes(rec.seedsHex.self)) },
+        { name: "circle", priv: ed25519SeedToX25519PrivateKey(hexToBytes(rec.seedsHex.circle)) },
+        { name: "public", priv: ed25519SeedToX25519PrivateKey(hexToBytes(rec.seedsHex.public)) },
+        { name: "root", priv: ed25519SeedToX25519PrivateKey(rootSeed) },
+        ...(opts.targetDataSeedHex && rec.seedsHex.data
+            ? [{ name: "data-old", priv: ed25519SeedToX25519PrivateKey(hexToBytes(rec.seedsHex.data)) }]
+            : []),
+    ];
+    const readUrl = `${pdsUrl}/mcp/primitives/read`;
+    const writeUrl = `${pdsUrl}/mcp/primitives/write`;
+    const signRoot = {
+        iss: did,
+        verificationMethod: `${did}#root`,
+        signSeed: rootSeed,
+    };
+    // 1. Enumerate collections.
+    const listed = (await jsonRpc(fetchImpl, readUrl, "aithos.data.list_collections", { subject_did: did }, { ...signRoot, aud: readUrl }));
+    const names = (listed.items ?? []).map((c) => c.name);
+    const collections = [];
+    for (const name of names) {
+        const entry = await rekeyOne({
+            fetchImpl,
+            readUrl,
+            writeUrl,
+            signRoot,
+            did,
+            name,
+            candidates,
+            dataPub,
+            dataPriv,
+            dataKexRecipient,
+            dryRun,
+            mode,
+        });
+        collections.push(entry);
+        opts.onProgress?.({ phase: "rekey", status: "collection", collection: name, result: entry.status });
+    }
+    return { did, dryRun, collections };
+}
+/**
+ * Dual-read onboarding: KEEP each collection's legacy owner wrap and ADD a
+ * second owner wrap sealed to #data, so the existing app (reading under the
+ * legacy key) AND a #data client both decrypt the same data. Non-destructive.
+ * Thin wrapper over {@link rekeyLegacyCollections} with `mode: "add"`.
+ */
+export async function addDataSphereWrap(owner, opts = {}) {
+    return rekeyLegacyCollections(owner, { ...opts, mode: "add" });
+}
+async function rekeyOne(a) {
+    const meta = (await jsonRpc(a.fetchImpl, a.readUrl, "aithos.data.get_collection", { subject_did: a.did, collection_name: a.name }, { ...a.signRoot, aud: a.readUrl }));
+    const urn = meta.urn ?? `urn:aithos:collection:${a.did}:${a.name}`;
+    const env = meta.cmk_envelope;
+    if (!env || !Array.isArray(env.wraps)) {
+        return { name: a.name, urn, status: "skipped-no-owner-wrap" };
+    }
+    // Owner wraps carry the label ${did}#data-kex (delegate wraps use a
+    // did:key:...#data-kex recipient). After a dual-read "add" there can be more
+    // than one owner wrap (legacy-sealed + #data-sealed).
+    const ownerWraps = env.wraps.filter((w) => w.recipient === a.dataKexRecipient);
+    if (ownerWraps.length === 0) {
+        return { name: a.name, urn, status: "skipped-no-owner-wrap", backupEnvelope: env };
+    }
+    const dataPriv = a.dataPriv; // private key of the TARGET #data
+    // Idempotence: is any owner wrap ALREADY readable under the target #data?
+    const alreadyData = ownerWraps.some((w) => tryUnwrapCmk({ wrap: w, collectionUrn: urn, privateKey: dataPriv }) !== null);
+    if (alreadyData) {
+        // add mode: a #data reader already exists → nothing to do.
+        // replace mode: if the SOLE owner wrap is #data we're done; if a legacy
+        // wrap also lingers we still consider it "already-data" (a #data reader
+        // exists) and leave it — replace's job is to *enable* #data, already true.
+        return { name: a.name, urn, status: "already-data", unwrappedWith: "data" };
+    }
+    // Auto-discover the legacy seed that sealed an owner wrap (try each wrap with
+    // each non-#data candidate). #data already excluded by the check above.
+    let cmk = null;
+    let usedSeed;
+    outer: for (const w of ownerWraps) {
+        for (const cand of a.candidates) {
+            const out = tryUnwrapCmk({ wrap: w, collectionUrn: urn, privateKey: cand.priv });
+            if (out) {
+                cmk = out;
+                usedSeed = cand.name;
+                break outer;
+            }
+        }
+    }
+    if (!cmk || !usedSeed) {
+        // Sealed to a key we don't hold (app-derived / foreign) — do NOT touch it.
+        return { name: a.name, urn, status: "unwrap-failed", backupEnvelope: env };
+    }
+    // Build the #data wrap of the SAME CMK (recipient label unchanged).
+    const dataWrap = wrapCmkForRecipient({
+        cmk,
+        recipientPublicKey: a.dataPub,
+        recipientDidUrl: a.dataKexRecipient,
+        collectionUrn: urn,
+    });
+    // GUARDRAIL: verify the new #data wrap round-trips to EXACTLY this CMK before
+    // any server write.
+    const verify = tryUnwrapCmk({ wrap: dataWrap, collectionUrn: urn, privateKey: dataPriv });
+    if (!verify || !bytesEqual(verify, cmk)) {
+        return { name: a.name, urn, status: "unwrap-failed", backupEnvelope: env };
+    }
+    let newEnvelope;
+    let delegateWrapsPreserved;
+    if (a.mode === "add") {
+        // Keep EVERYTHING (legacy owner wrap + delegate wraps) and append #data.
+        newEnvelope = { alg: env.alg, wraps: [...env.wraps, dataWrap] };
+        delegateWrapsPreserved = env.wraps.filter((w) => w.recipient !== a.dataKexRecipient).length;
+    }
+    else {
+        // replace: drop the legacy owner wrap(s), keep delegates, set #data as the
+        // sole owner wrap.
+        const delegateWraps = env.wraps.filter((w) => w.recipient !== a.dataKexRecipient);
+        newEnvelope = { alg: env.alg, wraps: [dataWrap, ...delegateWraps] };
+        delegateWrapsPreserved = delegateWraps.length;
+    }
+    if (a.dryRun) {
+        return { name: a.name, urn, status: "planned", unwrappedWith: usedSeed, delegateWrapsPreserved, backupEnvelope: env };
+    }
+    await jsonRpc(a.fetchImpl, a.writeUrl, "aithos.data.rotate_cmk", { collection_urn: urn, new_cmk_envelope: newEnvelope }, { ...a.signRoot, aud: a.writeUrl });
+    return {
+        name: a.name,
+        urn,
+        status: a.mode === "add" ? "data-wrap-added" : "rekeyed",
+        unwrappedWith: usedSeed,
+        delegateWrapsPreserved,
+        backupEnvelope: env,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  Combined helper                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * Run the full migration: ensureDataSphere then rekeyLegacyCollections.
+ * Returns the updated recovery file (with the #data seed) — persist it.
+ */
+export async function migrateLegacyEthosToDataSphere(recoveryText, opts = {}) {
+    const ensure = await ensureDataSphere(recoveryText, opts);
+    // Re-parse with the freshly merged #data seed so rekey has it.
+    const recWithData = parseRecoveryFile(ensure.updatedRecoveryFile);
+    const rekey = await rekeyLegacyCollections(recWithData, opts);
+    return { ensure, rekey, updatedRecoveryFile: ensure.updatedRecoveryFile };
+}
+async function jsonRpc(fetchImpl, url, method, params, ctx) {
+    const envelope = await signOwnerEnvelope({
+        iss: ctx.iss,
+        aud: ctx.aud,
+        method,
+        params,
+        verificationMethod: ctx.verificationMethod,
+        signer: { sign: async (msg) => ed.sign(msg, ctx.signSeed) },
+    });
+    const body = {
+        jsonrpc: "2.0",
+        id: `migrate_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+        method,
+        params: { ...params, _envelope: envelope },
+    };
+    const r = await fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const json = (await r.json());
+    if (json.error) {
+        const err = new Error(`${method} failed: ${json.error.message}`);
+        err.code = json.error.code;
+        err.data = json.error.data;
+        throw err;
+    }
+    return json.result ?? {};
+}
+/* -------------------------------------------------------------------------- */
+/*  Small utils                                                               */
+/* -------------------------------------------------------------------------- */
+function randomSeed32() {
+    const buf = new Uint8Array(32);
+    globalThis.crypto?.getRandomValues(buf);
+    return buf;
+}
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0)
+        throw new Error("hex must be even-length");
+    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;
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+/**
+ * Serialize a recovery file (SDK shape) with the #data seed merged in. We don't
+ * have a BrowserIdentity here, so we build the canonical SDK shape directly —
+ * matching `serializeRecoveryFile`'s output shape (used elsewhere for the
+ * round-trip parse test).
+ */
+function serializeRecoveryWithData(rec, dataSeedHex) {
+    void serializeRecoveryFile; // referenced for shape parity; we emit the same fields
+    const payload = {
+        aithos_recovery_version: "0.1.0-plaintext",
+        handle: rec.handle,
+        display_name: rec.displayName,
+        did: rec.did,
+        seeds_hex: {
+            root: rec.seedsHex.root,
+            public: rec.seedsHex.public,
+            circle: rec.seedsHex.circle,
+            self: rec.seedsHex.self,
+            data: dataSeedHex,
+        },
+        saved_at: new Date().toISOString(),
+    };
+    return JSON.stringify(payload, null, 2);
+}
+//# sourceMappingURL=migrate.js.map

package/dist/src/react/AithosAsset.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `<AithosAsset>` — drop-in component for displaying Aithos-hosted
+ * binary content with the simplest possible API:
+ *
+ *     <AithosAsset urn={cv.urn} alt="CV" className="w-full" />
+ *     <AithosAsset urn={video.urn} as="video" controls />
+ *     <AithosAsset urn={song.urn} as="audio" controls />
+ *     <AithosAsset urn={cv.urn} as="download" filename="cv.pdf">
+ *       Download my CV (PDF)
+ *     </AithosAsset>
+ *
+ * The component handles the full lifecycle:
+ *  - Fetch + decrypt via the assets client (from context or `client` prop).
+ *  - Show `fallback` while loading.
+ *  - Show `errorFallback` (or alt text in img-mode) on failure.
+ *  - Revoke the `blob:` URL on unmount or URN change.
+ *
+ * For public assets attached to the Ethos public zone, you can also
+ * just use the stable CloudFront URL directly (`<img src={asset.url} />`).
+ * This component is meant for private regime assets that require
+ * client-side decryption.
+ */
+import type { ReactNode, ImgHTMLAttributes, VideoHTMLAttributes, AudioHTMLAttributes, AnchorHTMLAttributes } from "react";
+import type { AssetsClient } from "../assets.js";
+interface AithosAssetBaseProps {
+    /** Asset URN, e.g. `urn:aithos:asset:did:aithos:z6Mkr…:asset_01J…`. */
+    readonly urn: string;
+    /** Override the assets client from context. */
+    readonly client?: AssetsClient | null;
+    /** Rendered while the fetch+decrypt is in flight. */
+    readonly fallback?: ReactNode;
+    /** Rendered on fetch/decrypt failure. `as="img"` defaults to showing alt instead. */
+    readonly errorFallback?: ReactNode;
+    /** Called once the asset is decrypted and ready to display. */
+    readonly onLoad?: () => void;
+    /** Called when the fetch/decrypt fails. */
+    readonly onError?: (err: Error) => void;
+    /**
+     * If `true`, keep the previous asset visible while a new URN is
+     * being fetched, instead of flashing the fallback. Default `false`.
+     */
+    readonly keepPreviousOnUrnChange?: boolean;
+}
+export interface AithosImageProps extends AithosAssetBaseProps, Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "onLoad" | "onError"> {
+    readonly as?: "img";
+}
+export interface AithosVideoProps extends AithosAssetBaseProps, Omit<VideoHTMLAttributes<HTMLVideoElement>, "src" | "onLoad" | "onError"> {
+    readonly as: "video";
+}
+export interface AithosAudioProps extends AithosAssetBaseProps, Omit<AudioHTMLAttributes<HTMLAudioElement>, "src" | "onLoad" | "onError"> {
+    readonly as: "audio";
+}
+export interface AithosDownloadProps extends AithosAssetBaseProps, Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "onLoad" | "onError"> {
+    readonly as: "download";
+    /** Suggested filename in the browser's download dialog. */
+    readonly filename?: string;
+    readonly children?: ReactNode;
+}
+export type AithosAssetProps = AithosImageProps | AithosVideoProps | AithosAudioProps | AithosDownloadProps;
+/**
+ * One component, four media kinds. The `as` prop selects between
+ * `<img>` (default), `<video>`, `<audio>`, and a styled `<a download>`.
+ */
+export declare function AithosAsset(props: AithosAssetProps): ReactNode;
+export {};
+//# sourceMappingURL=AithosAsset.d.ts.map

package/dist/src/react/AithosAsset.js

@@ -0,0 +1,67 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect } from "react";
+import { useAithosAsset } from "./use-aithos-asset.js";
+/* -------------------------------------------------------------------------- */
+/*  Component                                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * One component, four media kinds. The `as` prop selects between
+ * `<img>` (default), `<video>`, `<audio>`, and a styled `<a download>`.
+ */
+export function AithosAsset(props) {
+    const { urn, client, fallback, errorFallback, onLoad, onError, keepPreviousOnUrnChange, ...rest } = props;
+    const state = useAithosAsset(urn, {
+        client: client ?? undefined,
+        keepPreviousOnUrnChange,
+    });
+    // onLoad / onError side-effects
+    useEffect(() => {
+        if (state.url && onLoad)
+            onLoad();
+    }, [state.url, onLoad]);
+    useEffect(() => {
+        if (state.error && onError)
+            onError(state.error);
+    }, [state.error, onError]);
+    // Loading
+    if (state.loading) {
+        return (fallback ?? null);
+    }
+    // Error
+    if (state.error) {
+        if (errorFallback !== undefined) {
+            return errorFallback;
+        }
+        // For img-mode, the alt attribute is a sensible default error
+        // surface (the browser renders the alt text when src is broken).
+        if (rest.as === undefined || rest.as === "img") {
+            const imgProps = rest;
+            // eslint-disable-next-line jsx-a11y/alt-text
+            return _jsx("img", { ...imgProps, src: undefined });
+        }
+        return null;
+    }
+    // No URL yet (no URN supplied → idle state)
+    if (!state.url) {
+        return null;
+    }
+    // Dispatch on `as`
+    const as = rest.as ?? "img";
+    const { as: _consumed, ...domProps } = rest;
+    void _consumed;
+    if (as === "img") {
+        return (_jsx("img", { ...domProps, src: state.url }));
+    }
+    if (as === "video") {
+        return (_jsx("video", { ...domProps, src: state.url }));
+    }
+    if (as === "audio") {
+        return (_jsx("audio", { ...domProps, src: state.url }));
+    }
+    if (as === "download") {
+        const { filename, children, ...anchorRest } = domProps;
+        return (_jsx("a", { ...anchorRest, href: state.url, download: filename ?? true, children: children }));
+    }
+    return null;
+}
+//# sourceMappingURL=AithosAsset.js.map

package/dist/src/react/context.d.ts

@@ -0,0 +1,29 @@
+/**
+ * React context for the Aithos assets client.
+ *
+ * App roots wrap their tree with `<AssetsClientProvider client={sdk.assets}>`
+ * once, then child components use `<AithosAsset urn="..." />` (or the
+ * `useAithosAsset` hook) without having to thread the client through
+ * props.
+ */
+import { type ReactNode } from "react";
+import type { AssetsClient } from "../assets.js";
+export interface AssetsClientProviderProps {
+    /** The SDK's assets client — typically `sdk.assets`. */
+    readonly client: AssetsClient;
+    readonly children?: ReactNode;
+}
+/**
+ * Provider that exposes an {@link AssetsClient} to descendants.
+ *
+ * Typical placement: as high in the React tree as the authenticated
+ * session lives (e.g. inside the auth boundary).
+ */
+export declare function AssetsClientProvider(props: AssetsClientProviderProps): any;
+/**
+ * Return the {@link AssetsClient} from the nearest provider, or `null`
+ * if no provider is present. Components SHOULD accept an override via
+ * an explicit `client` prop and fall back to this hook when omitted.
+ */
+export declare function useAssetsClient(): AssetsClient | null;
+//# sourceMappingURL=context.d.ts.map

package/dist/src/react/context.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * React context for the Aithos assets client.
+ *
+ * App roots wrap their tree with `<AssetsClientProvider client={sdk.assets}>`
+ * once, then child components use `<AithosAsset urn="..." />` (or the
+ * `useAithosAsset` hook) without having to thread the client through
+ * props.
+ */
+import { createContext, useContext } from "react";
+const AssetsClientContext = createContext(null);
+/**
+ * Provider that exposes an {@link AssetsClient} to descendants.
+ *
+ * Typical placement: as high in the React tree as the authenticated
+ * session lives (e.g. inside the auth boundary).
+ */
+export function AssetsClientProvider(props) {
+    return (_jsx(AssetsClientContext.Provider, { value: props.client, children: props.children }));
+}
+/**
+ * Return the {@link AssetsClient} from the nearest provider, or `null`
+ * if no provider is present. Components SHOULD accept an override via
+ * an explicit `client` prop and fall back to this hook when omitted.
+ */
+export function useAssetsClient() {
+    return useContext(AssetsClientContext);
+}
+//# sourceMappingURL=context.js.map