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

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

@@ -0,0 +1,93 @@
+/**
+ * Minimal signing surface required to produce an envelope's
+ * `proof.proofValue`. Intentionally narrower than {@link Signer} so
+ * callers that don't want to construct a full `RawSeedSigner` can pass
+ * a one-shot inline adapter. Every {@link Signer} satisfies this
+ * interface structurally.
+ */
+export interface EnvelopeSigner {
+    sign(message: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * The wire-format envelope per spec §11.2. Apps that POST this to a
+ * backend serialize the whole object as JSON (alongside the rest of
+ * `params`) under `params._envelope`.
+ */
+export interface SignedEnvelope {
+    readonly "aithos-envelope": "0.1.0";
+    readonly iss: string;
+    readonly aud: string;
+    readonly method: string;
+    readonly iat: number;
+    readonly exp: number;
+    readonly nonce: string;
+    readonly params_hash: string;
+    /**
+     * Full signed mandate — present ONLY for a delegate-signed envelope
+     * (§11.6). When present, `proof.verificationMethod` is the delegate's
+     * bare Ed25519 multibase (matching `mandate.grantee.pubkey`) and the
+     * server resolves the signer to that key after verifying the mandate.
+     * The field is part of the signed bytes (the signature commits to the
+     * delegation context), so it cannot be swapped out in transit.
+     */
+    readonly mandate?: unknown;
+    readonly proof: {
+        readonly type: "Ed25519Signature2020";
+        readonly verificationMethod: string;
+        readonly created: string;
+        readonly proofValue: string;
+    };
+}
+export interface SignOwnerEnvelopeArgs {
+    /** Subject DID — issuer of the envelope (`iss` field). */
+    readonly iss: string;
+    /**
+     * Absolute URL of the target endpoint (scheme + host + path, no query,
+     * no fragment). The server verifier rejects envelopes where `aud`
+     * does not match the actual endpoint being called.
+     */
+    readonly aud: string;
+    /** Fully-qualified JSON-RPC method name. */
+    readonly method: string;
+    /** Tool payload — what `params_hash` commits to. */
+    readonly params: unknown;
+    /**
+     * Anything that can produce an Ed25519 signature over a byte
+     * sequence. In practice: one of the four owner sphere signers
+     * loaded post sign-in, or an inline adapter wrapping a raw seed.
+     */
+    readonly signer: EnvelopeSigner;
+    /**
+     * Verification method URL — typically `${did}#${sphere}`. The server
+     * resolves this against the issuer's DID document to find the
+     * matching public key.
+     */
+    readonly verificationMethod: string;
+    /**
+     * Full signed mandate, attached to the envelope for a delegate-signed
+     * call (§11.6). When set, `verificationMethod` MUST be the delegate's
+     * bare Ed25519 multibase (matching `mandate.grantee.pubkey`) and
+     * `signer` MUST be the delegate's key. Omit for owner-path envelopes.
+     */
+    readonly mandate?: unknown;
+    /** Envelope lifetime in seconds. Default 60. Server caps at 300. */
+    readonly ttlSeconds?: number;
+    /** Clock override for deterministic tests. Defaults to `new Date()`. */
+    readonly now?: Date;
+    /** Nonce override for deterministic tests. Defaults to a fresh ULID. */
+    readonly nonce?: string;
+}
+/**
+ * Build, canonicalize and sign an owner-path envelope per spec §11.2.
+ *
+ * The unsigned envelope is JCS-canonicalized (RFC 8785 subset), the
+ * bytes signed with Ed25519, and the resulting signature attached as
+ * `proof.proofValue` (base64url).
+ *
+ * Async return type — even though `Signer.sign` may resolve
+ * synchronously today (via `RawSeedSigner`), the interface is shaped
+ * async so that future implementations backed by `crypto.subtle.sign`
+ * (non-extractable keys) drop in without breaking callers.
+ */
+export declare function signOwnerEnvelope(args: SignOwnerEnvelopeArgs): Promise<SignedEnvelope>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/src/internal/envelope.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * Aithos signed-envelope helper — SDK-internal.
+ *
+ * Implements the `aithos-envelope` v0.1.0 wire format from spec §11.2.
+ * Used by SDK namespaces (sdk.data, sdk.ethos, sdk.mandates, ...) to
+ * sign their writes to api.aithos.be, AND by the public method
+ * {@link AithosAuth.signEnvelope} so apps can sign envelopes for
+ * arbitrary third-party Aithos-aware backends with the same primitive.
+ *
+ * NOT exported from the package barrel. The corresponding `SignedEnvelope`
+ * type IS re-exported from `src/index.ts` for consumer typing.
+ *
+ * Reference algorithm: `@aithos/protocol-core/envelope.ts:signEnvelope`.
+ * This file duplicates a self-contained subset of the helpers (JCS,
+ * SHA-256, base64url, ULID, CSPRNG) to keep the SDK's signing path
+ * decoupled from internal changes elsewhere in the SDK. The duplication
+ * with `src/data.ts` is intentional and tracked; consolidation into a
+ * shared `src/internal/canonical.ts` is planned for a follow-up release.
+ */
+import { signEnvelopeWith } from "@aithos/protocol-core/envelope";
+/**
+ * Build, canonicalize and sign an owner-path envelope per spec §11.2.
+ *
+ * The unsigned envelope is JCS-canonicalized (RFC 8785 subset), the
+ * bytes signed with Ed25519, and the resulting signature attached as
+ * `proof.proofValue` (base64url).
+ *
+ * Async return type — even though `Signer.sign` may resolve
+ * synchronously today (via `RawSeedSigner`), the interface is shaped
+ * async so that future implementations backed by `crypto.subtle.sign`
+ * (non-extractable keys) drop in without breaking callers.
+ */
+export async function signOwnerEnvelope(args) {
+    // Delegate to the single envelope source of truth in @aithos/protocol-core.
+    // The canonicalization, params_hash, unsigned-envelope assembly and proof
+    // attachment all live there now; we only supply the pluggable async signer
+    // (preserving the WebCrypto-ready `EnvelopeSigner` abstraction). A
+    // conformance test proves this path is byte-identical to the seed-based
+    // core signer, which is itself byte-identical to the former hand-rolled
+    // implementation — so nothing changes on the wire.
+    const env = await signEnvelopeWith({
+        iss: args.iss,
+        aud: args.aud,
+        method: args.method,
+        params: args.params,
+        verificationMethod: args.verificationMethod,
+        sign: (bytes) => args.signer.sign(bytes),
+        ttlSeconds: args.ttlSeconds,
+        now: args.now,
+        nonce: args.nonce,
+        ...(args.mandate !== undefined
+            ? { mandate: args.mandate }
+            : {}),
+    });
+    return env;
+}
+//# sourceMappingURL=envelope.js.map

package/dist/src/mandates.d.ts

@@ -1,12 +1,99 @@
 import type { AithosAuth } from "./auth.js";
 import type { AithosSdkEndpoints } from "./endpoints.js";
-/** Capability scope the SDK accepts. Server-side ultimately decides. */
-export type Scope = "ethos.read.public" | "ethos.read.circle" | "ethos.read.self" | "ethos.write.public" | "ethos.write.circle" | "ethos.write.self";
+/** Capability scope the SDK accepts. Server-side ultimately decides.
+ *
+ * Note: `compute.invoke` is intentionally NOT in this union. The token-
+ * spending capability is opt-in via the dedicated {@link CreateMandateInput.compute}
+ * namespace — see {@link MandatesNamespace.create}. Passing `compute.invoke`
+ * directly in `scopes` is rejected at runtime; the compiler can't enforce
+ * it (callers who up-cast to string[] would slip through), so the runtime
+ * check is the real gate. */
+export type Scope = "ethos.read.public" | "ethos.read.circle" | "ethos.read.self" | "ethos.write.public" | "ethos.write.circle" | "ethos.write.self" | DataScope;
+/** Action a data mandate may authorize on a collection. `write` implies
+ * `read`; `admin` implies `write`. Mirrors the data sub-protocol grammar
+ * `data.<collection>.<action>` (Aithos-protocol `spec/data/04-mandates.md`
+ * §4.2) and the server-side check `requireScope` in data-backend. */
+export type DataAction = "read" | "write" | "admin";
+/**
+ * A **lateral** data capability — deliberately OUTSIDE the
+ * `read ⊂ write ⊂ admin` hierarchy (the same way `gamma.write` sits beside
+ * the ethos scopes). Keeping it a separate type makes the security invariant
+ * structural rather than conventional: `append` can never be reached by
+ * widening a `write`/`admin` scope, so it cannot accidentally carry read.
+ *
+ * `append` authorizes `insert_record` ONLY (no read, update, or delete). The
+ * depositor seals each record's DEK to the owner's public key
+ * ({@link createAppendDataClient}) and holds no read capability — it cannot
+ * decrypt anything in the collection, not even its own deposit.
+ */
+export type DataLateralAction = "append";
+/**
+ * A data-access scope: `data.<collection>.<action>`, or the cross-collection
+ * wildcard `data.*.<action>`. Examples: `data.contacts.read`,
+ * `data.depots.write`, `data.*.read`.
+ *
+ * Note on `actor_sphere`: data mandates are minted under `actor_sphere:
+ * "self"` (the owner's highest-authority sphere). The sphere is *not* the
+ * access axis for data — the collection is. `actor_sphere` is informative
+ * here; the cryptographic binding is the grantee's key + the CMK wrap, per
+ * spec §4.4. A dedicated `#data` sphere key (independent rotation) MAY be
+ * introduced later without changing this scope grammar.
+ *
+ * Collection names MUST NOT contain `.` (the server splits the scope on
+ * `.` and reads the first three segments).
+ */
+export type DataScope = `data.${string}.${DataAction}` | `data.${string}.${DataLateralAction}`;
+/**
+ * The opt-in scope that authorizes a delegate to spend the subject's
+ * compute credits via the Aithos compute proxy. Mirror of
+ * `COMPUTE_INVOKE_SCOPE` in `@aithos/protocol-core` v0.4.0.
+ *
+ * The SDK's `mandates.create()` injects this scope automatically when
+ * the caller passes a `compute` namespace, and refuses to mint a
+ * mandate where the caller put it directly into `scopes` — this is
+ * what makes "compute is a separate, conscious decision" hold at the
+ * API surface.
+ */
+export declare const COMPUTE_INVOKE_SCOPE: "compute.invoke";
 /**
  * Which sphere of the owner signs the mandate. Bounds the upper-most
  * scope set the mandate can carry.
  */
 export type ActorSphere = "public" | "circle" | "self";
+/**
+ * Compute-spending capability — opt-in only, never implied by ethos
+ * scopes.
+ *
+ * When `compute` is set on {@link CreateMandateInput}, the SDK:
+ *   1. Adds the `compute.invoke` scope to the minted mandate.
+ *   2. Maps the caller's caps onto `constraints.compute` in the
+ *      protocol's snake_case shape (= what the verifier reads).
+ *   3. Forbids the caller from passing `compute.invoke` in `scopes`
+ *      directly — that would let an app slip the scope past a
+ *      consent UI that only reviews `compute`.
+ *
+ * At least one of `dailyCapMicrocredits` or `totalCapMicrocredits` MUST
+ * be set: an unbounded compute mandate is the kind of bearer-token
+ * footgun this whole namespace exists to prevent. Validation happens
+ * at the SDK boundary (here) AND at the protocol layer (the
+ * server-side verifier rejects capless 0.4.0 mandates), so a bug in
+ * either tier still fails closed.
+ *
+ * `maxCreditsPerCall` is a per-invocation safety net for runaway
+ * single requests. `allowedModels`, when set, restricts which Bedrock
+ * model ids the delegate may target (the proxy's own allowlist still
+ * applies on top).
+ */
+export interface CreateMandateComputeInput {
+    /** Hard cap on credits debited per UTC day under this mandate. */
+    readonly dailyCapMicrocredits?: number;
+    /** Hard cap on credits debited over the whole mandate lifetime. */
+    readonly totalCapMicrocredits?: number;
+    /** Hard cap on credits debited by any single invocation. */
+    readonly maxCreditsPerCall?: number;
+    /** Allowlist of Bedrock model ids the delegate may invoke. */
+    readonly allowedModels?: readonly string[];
+}
 export interface CreateMandateInput {
     /** Grantee URN — usually `urn:aithos:agent:<extension-id>` or similar. */
     readonly granteeId: string;
@@ -23,6 +110,28 @@ export interface CreateMandateInput {
     readonly scopes: readonly Scope[];
     /** Lifetime in seconds. */
     readonly ttlSeconds: number;
+    /**
+     * Opt-in compute (token-spending) capability — adds the
+     * `compute.invoke` scope and a bounded `constraints.compute` budget
+     * to the mandate. See {@link CreateMandateComputeInput}.
+     *
+     * NEVER add `compute.invoke` to `scopes` directly — the SDK rejects
+     * that path so the caller has to pass through this typed namespace,
+     * which is what a consent UI can review.
+     */
+    readonly compute?: CreateMandateComputeInput;
+    /**
+     * When the mandate becomes valid. Optional — when omitted, the
+     * underlying mint helper signs with `not_before = now - 30s` (see
+     * `MANDATE_NOTBEFORE_OFFSET_SECONDS_DEFAULT` in
+     * `@aithos/protocol-client`) so a server whose clock runs slightly
+     * behind the client doesn't reject the freshly-minted mandate as
+     * `not yet valid`.
+     *
+     * Pass an explicit `Date` only for advanced flows (delayed-activation
+     * mandates, deterministic tests).
+     */
+    readonly notBefore?: Date;
 }
 export interface MintedMandate {
     /** Unique mandate id (matches `mandate.id` inside the bundle). */

package/dist/src/mandates.js

@@ -16,6 +16,18 @@
 import { buildSignedEnvelope, mintDelegateBundle, readRpc, } from "@aithos/protocol-client";
 import { ownerKeyPair } from "./internal/protocol-client-bridge.js";
 import { AithosSDKError } from "./types.js";
+/**
+ * The opt-in scope that authorizes a delegate to spend the subject's
+ * compute credits via the Aithos compute proxy. Mirror of
+ * `COMPUTE_INVOKE_SCOPE` in `@aithos/protocol-core` v0.4.0.
+ *
+ * The SDK's `mandates.create()` injects this scope automatically when
+ * the caller passes a `compute` namespace, and refuses to mint a
+ * mandate where the caller put it directly into `scopes` — this is
+ * what makes "compute is a separate, conscious decision" hold at the
+ * API surface.
+ */
+export const COMPUTE_INVOKE_SCOPE = "compute.invoke";
 export class MandatesNamespace {
     #deps;
     constructor(deps) {
@@ -29,12 +41,47 @@ export class MandatesNamespace {
      */
     async create(input) {
         const owner = this.#requireOwner();
-        if (input.scopes.length === 0) {
-            throw new AithosSDKError("mandates_invalid_scopes", "scopes must be a non-empty list");
+        // A mandate must carry at least one capability — either ethos
+        // scopes, the compute namespace, or both. A "compute-only" mandate
+        // (`scopes: []` + `compute: { ... }`) is legitimate: it gives the
+        // grantee no access to the subject's ethos data, only the right
+        // to spend a bounded amount of compute credits in their name.
+        // Useful for creative assistants, brainstorming agents, etc.
+        if (input.scopes.length === 0 && input.compute === undefined) {
+            throw new AithosSDKError("mandates_invalid_scopes", "scopes must be a non-empty list (or pass `compute` for a compute-only mandate)");
         }
         if (input.ttlSeconds <= 0) {
             throw new AithosSDKError("mandates_invalid_ttl", "ttlSeconds must be > 0");
         }
+        // Forbid `compute.invoke` smuggled in via `scopes[]`. The whole
+        // point of the dedicated `compute` namespace is that adding token-
+        // spending capability requires a typed, named, reviewable input —
+        // not a string lost in a generic list. Type-checking can't catch
+        // this (the union doesn't include the literal, but callers can
+        // up-cast); the runtime check is what holds.
+        if (input.scopes.some((s) => s === COMPUTE_INVOKE_SCOPE)) {
+            throw new AithosSDKError("mandates_invalid_scopes", `Pass token-spending capability via the dedicated 'compute' namespace, ` +
+                `not by adding "${COMPUTE_INVOKE_SCOPE}" to scopes[]. The namespace forces ` +
+                `an explicit budget and is what a consent UI reviews.`);
+        }
+        // Fail fast on malformed data scopes so the misuse surfaces at the SDK
+        // boundary, not as an opaque server rejection at first delegate call.
+        // Accepts `data.<collection>.<action>` and the wildcard `data.*.<action>`.
+        for (const s of input.scopes) {
+            if (s.startsWith("data.") &&
+                !isWellFormedDataScope(s)) {
+                throw new AithosSDKError("mandates_invalid_scopes", `Malformed data scope "${s}". Expected data.<collection>.<action> ` +
+                    `(action = read | write | admin), e.g. "data.contacts.read" or ` +
+                    `"data.*.read". Collection names must not contain ".".`);
+            }
+        }
+        // Validate + project the compute namespace if present, then derive
+        // the final scopes/constraints to send to the protocol layer.
+        const computeProjection = projectCompute(input.compute);
+        const projectedScopes = [...input.scopes];
+        if (computeProjection) {
+            projectedScopes.push(COMPUTE_INVOKE_SCOPE);
+        }
         const actorSphere = input.actorSphere ?? defaultSphereFromScopes(input.scopes);
         const ownerStored = owner._unsafeStoredIdentity();
         const result = await mintDelegateBundle({
@@ -42,15 +89,28 @@ export class MandatesNamespace {
             granteeId: input.granteeId,
             ...(input.granteeLabel ? { granteeLabel: input.granteeLabel } : {}),
             actorSphere,
-            scopes: [...input.scopes],
+            scopes: projectedScopes,
             ttlSeconds: input.ttlSeconds,
+            // protocol-client v0.1.0-alpha.11 ships MandateConstraints without
+            // the `compute` field; the wire format accepts it though (the
+            // canonicalizer just serializes whatever's in the object). We
+            // up-cast through `unknown` to bypass the structural check until
+            // protocol-client picks up protocol-core 0.4.0 types.
+            ...(computeProjection
+                ? {
+                    constraints: {
+                        compute: computeProjection,
+                    },
+                }
+                : {}),
+            ...(input.notBefore ? { notBefore: input.notBefore } : {}),
         });
         const mandate = result.mandate;
         return {
             mandateId: mandate.id,
             subjectDid: mandate.subject_did,
             granteeId: input.granteeId,
-            scopes: input.scopes,
+            scopes: projectedScopes,
             expiresAt: mandate.not_after ?? null,
             bundle: result.bundleBlob,
             filename: `aithos-delegate-${mandate.id}.json`,
@@ -158,11 +218,94 @@ export class MandatesNamespace {
 /*  Helpers                                                                   */
 /* -------------------------------------------------------------------------- */
 function defaultSphereFromScopes(scopes) {
-    if (scopes.some((s) => s.endsWith(".self")))
+    // Data scopes are sphere-NEUTRAL: they're permitted under self & circle (and
+    // public once the allowlist includes them), and the data access axis is the
+    // collection, not the sphere (the sphere is informative — see {@link DataScope}).
+    // So the actor_sphere of a combined Ethos+data mandate is decided by the
+    // ETHOS scopes alone; data scopes neither raise nor lower it. This makes
+    // `ethos.read.public + data.X.read` default to `public`, `ethos.read.circle
+    // + data.X.read` to `circle`, etc. A caller can always override via
+    // `actorSphere`.
+    const ethos = scopes.filter((s) => !s.startsWith("data."));
+    // Ethos write scopes pin the sphere EXACTLY (a write mandate must be signed
+    // by the sphere it writes to — `validateScopesAgainstSphere`).
+    if (ethos.some((s) => s === "ethos.write.public"))
+        return "public";
+    if (ethos.some((s) => s === "ethos.write.circle"))
+        return "circle";
+    if (ethos.some((s) => s === "ethos.write.self"))
+        return "self";
+    // Ethos read scopes: narrowest sphere that permits them.
+    if (ethos.some((s) => s.endsWith(".self")))
         return "self";
-    if (scopes.some((s) => s.endsWith(".circle")))
+    if (ethos.some((s) => s.endsWith(".circle")))
         return "circle";
-    return "public";
+    // Remaining Ethos scopes (ethos.read.public / .all / gamma.read) → public.
+    if (ethos.length > 0)
+        return "public";
+    // Data-only mandate: sign under `self`. self is the owner's highest-trust
+    // sphere, always permits the scope at mint time (no dependency on the
+    // public-sphere allowlist), and keeps the data grant off the most-exposed
+    // #public key. (Override with `actorSphere` for a public/circle label.)
+    return "self";
+}
+/** `true` iff `s` is a well-formed data scope `data.<collection>.<action>`
+ * with no filter suffix and a non-empty, dot-free collection name. The
+ * lateral `append` action is accepted alongside read/write/admin. */
+function isWellFormedDataScope(s) {
+    return /^data\.[^.]+\.(read|write|admin|append)$/.test(s);
+}
+/**
+ * Validate the SDK-side `compute` namespace and project it onto the
+ * snake_case shape the protocol layer canonicalizes into the mandate.
+ *
+ * Returns `null` if the caller passed nothing — that's the "no compute
+ * authorization" path. Throws {@link AithosSDKError} on any structural
+ * problem (camelCase mirror of the rules `validateComputeAuthorization`
+ * enforces server-side; we duplicate them here so a misuse fails at the
+ * SDK boundary with a precise error rather than only blowing up at mint).
+ */
+function projectCompute(c) {
+    if (c === undefined)
+        return null;
+    const hasDaily = typeof c.dailyCapMicrocredits === "number";
+    const hasTotal = typeof c.totalCapMicrocredits === "number";
+    if (!hasDaily && !hasTotal) {
+        throw new AithosSDKError("mandates_invalid_compute", "compute namespace requires at least one of dailyCapMicrocredits " +
+            "or totalCapMicrocredits — an unbounded compute mandate is a bearer " +
+            "token to drain the subject's wallet.");
+    }
+    for (const [field, value] of [
+        ["dailyCapMicrocredits", c.dailyCapMicrocredits],
+        ["totalCapMicrocredits", c.totalCapMicrocredits],
+        ["maxCreditsPerCall", c.maxCreditsPerCall],
+    ]) {
+        if (value === undefined)
+            continue;
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new AithosSDKError("mandates_invalid_compute", `compute.${field} must be a positive integer (got ${value}).`);
+        }
+    }
+    if (c.allowedModels !== undefined) {
+        if (!Array.isArray(c.allowedModels)) {
+            throw new AithosSDKError("mandates_invalid_compute", "compute.allowedModels must be an array of strings.");
+        }
+        for (const m of c.allowedModels) {
+            if (typeof m !== "string" || m.length === 0) {
+                throw new AithosSDKError("mandates_invalid_compute", `compute.allowedModels entries must be non-empty strings (got ${JSON.stringify(m)}).`);
+            }
+        }
+    }
+    const wire = {};
+    if (hasDaily)
+        wire.daily_cap_microcredits = c.dailyCapMicrocredits;
+    if (hasTotal)
+        wire.total_cap_microcredits = c.totalCapMicrocredits;
+    if (c.maxCreditsPerCall !== undefined)
+        wire.max_credits_per_call = c.maxCreditsPerCall;
+    if (c.allowedModels !== undefined)
+        wire.allowed_models = [...c.allowedModels];
+    return wire;
 }
 function toOwnedMandate(it) {
     return {

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