@aithos/sdk 0.1.0-alpha.39 → 0.1.0-alpha.40

package/dist/src/assets.js

@@ -0,0 +1,533 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * `sdk.assets` — high-level API for the Aithos assets sub-protocol PDS.
+ *
+ * Stores binary content (images, PDFs, audio, video) owned by a
+ * subject, encrypted client-side under per-asset AMKs (Asset Master
+ * Keys), accessible to authorized apps via signed mandates (v0.2).
+ *
+ *     const assets = sdk.assets;
+ *     const avatar = await assets.upload({
+ *       bytes: pngBuffer,
+ *       mediaType: "image/png",
+ *       attachTo: { ethos: { zone: "public", sectionId: "sec_identity" } },
+ *     });
+ *     // avatar.url is a stable CloudFront URL (public asset)
+ *
+ *     const cv = await assets.upload({
+ *       bytes: pdfBuffer,
+ *       mediaType: "application/pdf",
+ *       attachTo: { ethos: { zone: "circle", sectionId: "sec_career_docs" } },
+ *     });
+ *     // cv is private: stored encrypted, fetched via short-lived presigned URL.
+ *
+ *     const bytes = await assets.fetch(cv.urn);
+ *     // decrypted plaintext returned to the caller
+ *
+ * The module wires:
+ *   - AMK generation + wrap (via @aithos/assets-crypto)
+ *   - Bytes encryption with the canonical nonce-prefix on-disk layout
+ *   - RecipientResolver (v0.2-ethos: maps {zone} → recipient set)
+ *   - Direct S3 PUT against the presigned URL returned by init_upload
+ *   - In-memory AMK cache (per asset URN) for sub-second re-fetches
+ *   - Signed envelope JSON-RPC dispatch to /mcp/primitives/{read,write}
+ *
+ * Spec ref: spec/assets/ in the aithos-protocol repo.
+ */
+import { generateAMK, wrapAMKForRecipient, unwrapAMK, encryptAssetBytes, decryptAssetBytes, plaintextSha256Hex, } from "@aithos/assets-crypto";
+import { x25519 } from "@noble/curves/ed25519.js";
+import { sha512 } from "@noble/hashes/sha2.js";
+import { signOwnerEnvelope } from "./internal/envelope.js";
+/* -------------------------------------------------------------------------- */
+/*  Public factory                                                            */
+/* -------------------------------------------------------------------------- */
+export function createAssetsClient(args) {
+    return new AssetsClient(args);
+}
+/* -------------------------------------------------------------------------- */
+/*  AssetsClient implementation                                               */
+/* -------------------------------------------------------------------------- */
+export class AssetsClient {
+    #pdsUrl;
+    #did;
+    #seed;
+    #verificationMethod;
+    #fetch;
+    #resolver;
+    /** Cache: URN → AMK (recovered on first fetch, reused thereafter). */
+    #amkCache = new Map();
+    constructor(args) {
+        this.#pdsUrl = args.pdsUrl.replace(/\/$/, "");
+        this.#did = args.did;
+        this.#seed = args.sphereSeed;
+        this.#verificationMethod = args.verificationMethod;
+        this.#fetch = args.fetch ?? globalThis.fetch.bind(globalThis);
+        this.#resolver = args.recipientResolver ?? defaultSelfResolver(args);
+    }
+    /* ------------------------------------------------------------------ */
+    /*  upload                                                             */
+    /* ------------------------------------------------------------------ */
+    async upload(input) {
+        const regime = resolveRegime(input);
+        const sha = plaintextSha256Hex(input.bytes);
+        // For private regime, generate AMK + wraps eagerly so the
+        // init_upload call already carries the envelope (the server
+        // records it as part of the pending-upload metadata).
+        let amk;
+        let amkEnvelope;
+        let recipientSet;
+        if (regime === "private") {
+            recipientSet = await this.#resolver.resolve({
+                subjectDid: this.#did,
+                context: input.attachTo,
+            });
+            if (recipientSet.recipients.length === 0) {
+                throw new Error("sdk.assets.upload: private regime requires at least one recipient — check RecipientResolver");
+            }
+            amk = generateAMK();
+            // The bytes encryption nonce is computed inside encryptAssetBytes;
+            // the wrap list will be filled below once we know the final URN
+            // (it's bound into the AAD via assetUrn).
+            // We pre-compose a placeholder envelope to satisfy server
+            // validation, then re-emit with the real URN at init+complete.
+            amkEnvelope = {
+                alg: "xchacha20poly1305-ietf",
+                nonce: "",
+                wraps: [],
+            };
+        }
+        // init_upload
+        const initResp = (await this.#callWrite("aithos.assets.init_upload", {
+            subject_did: this.#did,
+            media_type: input.mediaType,
+            size_bytes: input.bytes.length,
+            sha256_of_plaintext: sha,
+            ...(input.attachTo ? { attached_context: serializeContext(input.attachTo) } : {}),
+            regime,
+            ...(input.forwardSecrecy ? { forward_secrecy: input.forwardSecrecy } : {}),
+            ...(amkEnvelope ? { amk_envelope: amkEnvelope } : {}),
+        }));
+        if (initResp.result === "dedup_hit") {
+            // Asset already exists — return existing URN; no PUT needed.
+            const asset = initResp.asset;
+            if (!asset) {
+                throw new Error("sdk.assets.upload: dedup_hit response is missing the asset metadata");
+            }
+            return {
+                urn: initResp.urn,
+                assetId: initResp.asset_id,
+                mediaType: asset.media_type,
+                sizeBytes: asset.size_bytes,
+                sha256OfPlaintext: asset.sha256_of_plaintext,
+                encrypted: asset.encrypted,
+                url: !asset.encrypted ? composePublicUrl(asset) : undefined,
+                dedupHit: true,
+            };
+        }
+        const finalUrn = initResp.urn;
+        // Build the real wraps using the final URN.
+        let blob;
+        let nonceB64;
+        let finalWraps = [];
+        if (regime === "private") {
+            finalWraps = recipientSet.recipients.map((r) => wrapAMKForRecipient({
+                amk: amk,
+                recipientPublicKey: r.x25519PublicKey,
+                recipientDidUrl: r.didUrl,
+                assetUrn: finalUrn,
+            }));
+            const enc = encryptAssetBytes({
+                amk: amk,
+                assetUrn: finalUrn,
+                plaintext: input.bytes,
+            });
+            blob = enc.blob;
+            nonceB64 = enc.nonce_b64;
+        }
+        else {
+            blob = input.bytes;
+        }
+        // PUT bytes to S3. TS lib.dom typings expect BodyInit; a plain
+        // Uint8Array is accepted at runtime by all modern fetch
+        // implementations (browser, Node 18+, undici), but the lib.dom
+        // signature requires a cast to a BodyInit-compatible view.
+        const putResp = await this.#fetch(initResp.upload_url, {
+            method: "PUT",
+            headers: {
+                "content-type": regime === "private" ? "application/octet-stream" : input.mediaType,
+            },
+            body: blob,
+        });
+        if (!putResp.ok) {
+            throw new Error(`sdk.assets.upload: S3 PUT failed with status ${putResp.status}`);
+        }
+        // complete_upload (with real AMK envelope for private uploads)
+        const completePayload = {
+            upload_session: initResp.upload_session,
+            observed_sha256_of_plaintext: sha,
+        };
+        if (regime === "private") {
+            // The server stores the amk_envelope from init_upload — for v0.1
+            // we don't have a separate "update_envelope_on_complete" hook,
+            // so we recompose it here client-side and call authorize_grantee-
+            // style updates if we need to push real wraps. The simpler v0.1
+            // workaround: include the envelope in init_upload from the start
+            // by precomputing the URN client-side — but the URN is allocated
+            // by the server. For now we ship the envelope on complete via a
+            // backwards-compatible extension field, and the backend stores
+            // it on the asset doc.
+            completePayload.amk_envelope = {
+                alg: "xchacha20poly1305-ietf",
+                nonce: nonceB64,
+                wraps: finalWraps,
+            };
+        }
+        const completeResp = (await this.#callWrite("aithos.assets.complete_upload", completePayload));
+        // Cache the AMK locally for the lifetime of this session.
+        if (amk) {
+            this.#amkCache.set(finalUrn, amk);
+        }
+        return {
+            urn: completeResp.urn,
+            assetId: initResp.asset_id,
+            mediaType: input.mediaType,
+            sizeBytes: input.bytes.length,
+            sha256OfPlaintext: sha,
+            encrypted: regime === "private",
+            url: regime === "public"
+                ? composePublicUrl(completeResp.asset)
+                : undefined,
+            dedupHit: false,
+        };
+    }
+    /* ------------------------------------------------------------------ */
+    /*  uploadWithThumbnails                                               */
+    /* ------------------------------------------------------------------ */
+    /**
+     * Upload a primary asset plus one or more thumbnails (downscaled
+     * client-side). Convenience method for the Deep avatar use case and
+     * any UI that displays the same asset at multiple resolutions.
+     *
+     * The thumbnails are attached to the same context as the primary
+     * and uploaded in parallel. They carry the {@link AssetReference}
+     * role `"thumbnail"` when referenced from a section (see
+     * spec/assets/03-asset-descriptors.md §3.2.3).
+     */
+    async uploadWithThumbnails(input) {
+        const primary = await this.upload(input);
+        const thumbnails = await Promise.all(input.sizes.map(async (size) => {
+            const scaledBytes = await input.downscale(input.bytes, size);
+            const thumb = await this.upload({
+                ...input,
+                bytes: scaledBytes,
+                // Thumbnails inherit the primary's attachTo so they live in
+                // the same recipient set.
+            });
+            return { size, result: thumb };
+        }));
+        return { primary, thumbnails };
+    }
+    /* ------------------------------------------------------------------ */
+    /*  fetch                                                              */
+    /* ------------------------------------------------------------------ */
+    async fetch(urn) {
+        const resp = (await this.#callRead("aithos.assets.get_asset", {
+            urn,
+        }));
+        const asset = resp.asset;
+        const r = await this.#fetch(resp.fetch_url);
+        if (!r.ok) {
+            throw new Error(`sdk.assets.fetch: byte fetch failed with status ${r.status}`);
+        }
+        const blob = new Uint8Array(await r.arrayBuffer());
+        let bytes;
+        if (asset.encrypted) {
+            const amk = this.#amkCache.get(urn) ??
+                this.#unwrapAmkForSelf(urn, asset.amk_envelope);
+            this.#amkCache.set(urn, amk);
+            bytes = decryptAssetBytes({
+                amk,
+                assetUrn: urn,
+                blob,
+                expectedSha256Hex: asset.sha256_of_plaintext,
+            });
+        }
+        else {
+            bytes = blob;
+            // SHA verification still applies for public assets.
+            if (plaintextSha256Hex(bytes) !== asset.sha256_of_plaintext) {
+                throw new Error("sdk.assets.fetch: plaintext SHA-256 mismatch on public asset");
+            }
+        }
+        return {
+            urn,
+            mediaType: asset.media_type,
+            sizeBytes: asset.size_bytes,
+            bytes,
+            sha256OfPlaintext: asset.sha256_of_plaintext,
+        };
+    }
+    /* ------------------------------------------------------------------ */
+    /*  head                                                               */
+    /* ------------------------------------------------------------------ */
+    async head(urn) {
+        const r = (await this.#callRead("aithos.assets.head_asset", {
+            urn,
+        }));
+        return r.asset;
+    }
+    /* ------------------------------------------------------------------ */
+    /*  list                                                               */
+    /* ------------------------------------------------------------------ */
+    async list(opts = {}) {
+        const params = {
+            subject_did: this.#did,
+        };
+        if (opts.limit !== undefined)
+            params.limit = opts.limit;
+        if (opts.cursor)
+            params.cursor = opts.cursor;
+        if (opts.order)
+            params.order = opts.order;
+        if (opts.includeOrphaned)
+            params.include_orphaned = true;
+        if (opts.includeTombstoned)
+            params.include_tombstoned = true;
+        if (opts.filter) {
+            const f = {};
+            if (opts.filter.mediaTypePrefix)
+                f.media_type_prefix = opts.filter.mediaTypePrefix;
+            if (opts.filter.sizeBytes)
+                f.size_bytes = opts.filter.sizeBytes;
+            if (opts.filter.createdAfter)
+                f.created_after = opts.filter.createdAfter;
+            if (opts.filter.createdBefore)
+                f.created_before = opts.filter.createdBefore;
+            params.filter = f;
+        }
+        const r = (await this.#callRead("aithos.assets.list_assets", params));
+        return {
+            items: r.items.map((it) => ({
+                urn: it.urn,
+                assetId: it.asset_id,
+                mediaType: it.media_type,
+                sizeBytes: it.size_bytes,
+                sha256OfPlaintext: it.sha256_of_plaintext,
+                encrypted: it.encrypted,
+                state: it.state,
+                referenceCount: it.reference_count,
+                createdAt: it.created_at,
+                modifiedAt: it.modified_at,
+            })),
+            ...(r.next_cursor ? { nextCursor: r.next_cursor } : {}),
+        };
+    }
+    /* ------------------------------------------------------------------ */
+    /*  ref / unref / listReferences                                       */
+    /* ------------------------------------------------------------------ */
+    async ref(urn, reference) {
+        const r = (await this.#callWrite("aithos.assets.ref_asset", {
+            urn,
+            reference,
+        }));
+        return { referenceCount: r.reference_count, gammaRef: r.gamma_ref };
+    }
+    async unref(urn, reference) {
+        const r = (await this.#callWrite("aithos.assets.unref_asset", {
+            urn,
+            reference,
+        }));
+        return { referenceCount: r.reference_count, gammaRef: r.gamma_ref };
+    }
+    async listReferences(urn) {
+        const r = (await this.#callRead("aithos.assets.list_references", {
+            urn,
+        }));
+        return r.items;
+    }
+    /* ------------------------------------------------------------------ */
+    /*  delete                                                             */
+    /* ------------------------------------------------------------------ */
+    async delete(urn) {
+        const r = (await this.#callWrite("aithos.assets.delete_asset", {
+            urn,
+        }));
+        this.#amkCache.delete(urn);
+        return { tombstonedAt: r.tombstoned_at, gammaRef: r.gamma_ref };
+    }
+    /* ------------------------------------------------------------------ */
+    /*  reset cache                                                        */
+    /* ------------------------------------------------------------------ */
+    /** Zero in-memory AMK cache. Useful at user logout. */
+    reset() {
+        for (const k of this.#amkCache.values())
+            k.fill(0);
+        this.#amkCache.clear();
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Internals — envelope dispatch                                      */
+    /* ------------------------------------------------------------------ */
+    async #callRead(method, params) {
+        return this.#dispatch("/mcp/primitives/read", method, params);
+    }
+    async #callWrite(method, params) {
+        return this.#dispatch("/mcp/primitives/write", method, params);
+    }
+    async #dispatch(path, method, params) {
+        const aud = `${this.#pdsUrl}${path}`;
+        const envelope = await this.#signEnvelope({ aud, method, params });
+        const body = {
+            jsonrpc: "2.0",
+            id: makeUlidLite(),
+            method,
+            params: { ...params, _envelope: envelope },
+        };
+        const r = await this.#fetch(aud, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        const json = (await r.json());
+        if (json.error) {
+            const err = new Error(json.error.message);
+            err.code = json.error.code;
+            err.data = json.error.data;
+            throw err;
+        }
+        return json.result ?? {};
+    }
+    async #signEnvelope(args) {
+        return signOwnerEnvelope({
+            iss: this.#did,
+            aud: args.aud,
+            method: args.method,
+            params: args.params,
+            verificationMethod: this.#verificationMethod,
+            signer: {
+                sign: async (msg) => {
+                    // We delegate to @noble/ed25519 directly to avoid pulling the
+                    // SDK's Signer abstraction surface into this module. The
+                    // dependency is already present transitively via assets-crypto.
+                    const { signAsync } = await import("@noble/ed25519");
+                    return signAsync(msg, this.#seed);
+                },
+            },
+        });
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Internals — AMK unwrap for self                                    */
+    /* ------------------------------------------------------------------ */
+    #unwrapAmkForSelf(urn, envelope) {
+        const ourPub = ed25519SeedToX25519PublicKey(this.#seed);
+        void ourPub;
+        const ourPriv = ed25519SeedToX25519PrivateKey(this.#seed);
+        // Try every wrap that names a recipient under our DID. The DID
+        // URL fragment is unconstrained — `#kex`, `#circle-kex`, `#self-kex`
+        // are all candidates. We attempt each wrap whose `recipient`
+        // starts with our DID; AAD binding makes wrong attempts fail
+        // cleanly.
+        const ours = envelope.wraps.filter((w) => w.recipient.startsWith(this.#did));
+        for (const wrap of ours) {
+            try {
+                return unwrapAMK({
+                    wrap,
+                    recipientPrivateKey: ourPriv,
+                    assetUrn: urn,
+                });
+            }
+            catch {
+                // Wrong fragment / wrong key — try the next wrap.
+            }
+        }
+        throw new Error(`sdk.assets.fetch: no AMK wrap for ${this.#did} found in asset ${urn}`);
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*  Default RecipientResolver — self-only                                     */
+/* -------------------------------------------------------------------------- */
+function defaultSelfResolver(args) {
+    return {
+        async resolve(input) {
+            // For the default self-only resolver we always wrap to the
+            // subject's own X25519 sphere key. Other recipients (grantees)
+            // can be added explicitly later via authorize_grantee in v0.2.
+            const pub = ed25519SeedToX25519PublicKey(args.sphereSeed);
+            const didUrl = recipientDidUrlForContext(input.subjectDid, input.context);
+            return {
+                recipients: [{ didUrl, x25519PublicKey: pub }],
+            };
+        },
+    };
+}
+/** Pick a DID URL fragment matching the attaching zone. */
+function recipientDidUrlForContext(subjectDid, context) {
+    if (context?.ethos?.zone === "circle")
+        return `${subjectDid}#circle-kex`;
+    if (context?.ethos?.zone === "self")
+        return `${subjectDid}#self-kex`;
+    if (context?.data)
+        return `${subjectDid}#data-kex`;
+    return `${subjectDid}#kex`;
+}
+function resolveRegime(input) {
+    if (input.regime === "public")
+        return "public";
+    if (input.regime === "private")
+        return "private";
+    if (input.attachTo?.ethos?.zone === "public")
+        return "public";
+    return "private";
+}
+function serializeContext(ctx) {
+    if (ctx.ethos) {
+        return {
+            kind: "ethos",
+            zone: ctx.ethos.zone,
+            ...(ctx.ethos.sectionId ? { section_id: ctx.ethos.sectionId } : {}),
+        };
+    }
+    if (ctx.data) {
+        return {
+            kind: "data",
+            collection_urn: ctx.data.collectionUrn,
+            ...(ctx.data.recordId ? { record_id: ctx.data.recordId } : {}),
+        };
+    }
+    return {};
+}
+function composePublicUrl(asset) {
+    return asset.public_url;
+}
+/**
+ * Derive a 32-byte X25519 private key from an Ed25519 seed via
+ * SHA-512 truncation + clamping. Same construction libsodium uses for
+ * `crypto_sign_ed25519_sk_to_curve25519`.
+ */
+function ed25519SeedToX25519PrivateKey(seed) {
+    if (seed.length !== 32)
+        throw new Error("Ed25519 seed must be 32 bytes");
+    const h = sha512(seed);
+    const sk = new Uint8Array(h.slice(0, 32));
+    // Clamp per X25519 spec
+    sk[0] = sk[0] & 248;
+    sk[31] = sk[31] & 127;
+    sk[31] = sk[31] | 64;
+    return sk;
+}
+function ed25519SeedToX25519PublicKey(seed) {
+    const sk = ed25519SeedToX25519PrivateKey(seed);
+    try {
+        return x25519.getPublicKey(sk);
+    }
+    finally {
+        sk.fill(0);
+    }
+}
+function makeUlidLite() {
+    // Lightweight monotonic-ish id for JSON-RPC `id` field — not
+    // crypto-grade. Production code uses ulid().
+    return (Date.now().toString(36) +
+        Math.random().toString(36).substring(2, 10));
+}
+//# sourceMappingURL=assets.js.map

package/dist/src/index.d.ts

@@ -24,4 +24,5 @@ export * as onboarding from "./onboarding.js";
 export { createBrowserIdentity, browserIdentityFromStored, type BrowserIdentity, } from "@aithos/protocol-client";
 export type { Section } from "@aithos/protocol-client";
 export { createDataClient, type CreateDataClientArgs, type DataClient, type DataCollection, type ListOpts, type AithosSchemaLite, } from "./data.js";
+export { createAssetsClient, AssetsClient, type CreateAssetsClientArgs, type AttachedContext, type AssetUploadInput, type AssetUploadResult, type AssetFetchResult, type AssetBrief, type ListAssetsOpts, type ThumbnailUploadInput, type ThumbnailUploadResult, type RecipientResolver, type RecipientSet, } from "./assets.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -62,4 +62,10 @@ export { createBrowserIdentity, browserIdentityFromStored, } from "@aithos/proto
 // the lifecycle of subject-owned, encrypted, schema-validated records.
 // See spec/data/ in the aithos-protocol repo.
 export { createDataClient, } from "./data.js";
+// `sdk.assets` — Aithos assets sub-protocol PDS client. Upload,
+// fetch, list, ref/unref binary content (images, PDFs, audio, video)
+// owned by a subject. AEAD-encrypted per-asset under AMKs wrapped for
+// the subject's X25519 sphere keys (and, in v0.2, mandate grantees).
+// See spec/assets/ in the aithos-protocol repo.
+export { createAssetsClient, AssetsClient, } from "./assets.js";
 //# sourceMappingURL=index.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