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

package/dist/src/mandates.js

@@ -1,13 +1,291 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Mathieu Colla
-// Mandates namespace — re-exports of mandate mint/sign primitives.
+// `sdk.mandates` namespace — owner-side mandate lifecycle.
 //
-// A mandate is a signed delegation bundle that grants an app DID the right
-// to act on the user's behalf within a scoped set of operations (read
-// scopes, compute spend cap, TTL). Mandates are required by the compute
-// proxy on every Bedrock call.
+// Three verbs:
+//   create(input)           → mints + publishes + returns the
+//                              shareable .aithos-delegate.json bundle
+//   list()                  → mandates the owner has issued
+//   revoke(mandateId)       → publishes a §4.2 revocation
 //
-// See `@aithos/protocol-client/src/mandate-mint.ts` for the canonical
-// implementation; this namespace re-exports the public surface verbatim.
-export { mintDelegateBundle, signAndPublishMandate, MintError, DEFAULT_READ_SCOPES, TTL_PRESETS, } from "@aithos/protocol-client";
+// Capability boundary: every method requires an owner signed in. We
+// reach the OwnerSigners through `auth._getOwnerSigners()` and project
+// to a `StoredIdentity` for protocol-client interop. When
+// protocol-client gains a Signer-shaped API the projection step
+// disappears.
+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) {
+        this.#deps = deps;
+    }
+    /**
+     * Mint, sign, publish, and package a fresh delegate bundle. The
+     * grantee's keypair is generated inside this call and never
+     * persisted on the owner's machine — the seed flows out via the
+     * returned Blob and only via that Blob.
+     */
+    async create(input) {
+        const owner = this.#requireOwner();
+        // 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.`);
+        }
+        // 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({
+            owner: ownerStored,
+            granteeId: input.granteeId,
+            ...(input.granteeLabel ? { granteeLabel: input.granteeLabel } : {}),
+            actorSphere,
+            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: projectedScopes,
+            expiresAt: mandate.not_after ?? null,
+            bundle: result.bundleBlob,
+            filename: `aithos-delegate-${mandate.id}.json`,
+        };
+    }
+    /**
+     * List mandates issued by the signed-in owner. Pages through
+     * `aithos.list_mandates` until exhausted (or until 5 pages have
+     * been crawled — an owner with more than 1000 active mandates is
+     * out of scope today).
+     */
+    async list() {
+        const owner = this.#requireOwner();
+        const out = [];
+        let cursor;
+        for (let i = 0; i < 5; i++) {
+            const page = await readRpc("aithos.list_mandates", {
+                issuer_did: owner.did,
+                limit: 200,
+                ...(cursor ? { cursor } : {}),
+            });
+            for (const it of page.items) {
+                out.push(toOwnedMandate(it));
+            }
+            if (!page.next_cursor)
+                break;
+            cursor = page.next_cursor;
+        }
+        return out;
+    }
+    /**
+     * Publish a §4.2 revocation for `mandateId`. The mandate stops
+     * authorizing future actions (artifacts dated before `revoked_at`
+     * remain valid — revocation is not retroactive).
+     *
+     * Server-side: handled by `aithos.publish_revocation`. The envelope
+     * is signed by the owner's `#public` sphere — the spec also accepts
+     * `#root`, but `#public` is what the existing app does.
+     *
+     * Throws {@link AithosSDKError} on backend errors. Note that
+     * server-side support is in-flight; this method may surface a
+     * `mandates_-32601` (method not found) until the auth platform
+     * lands the corresponding write handler.
+     */
+    async revoke(mandateId) {
+        const owner = this.#requireOwner();
+        const ownerStored = owner._unsafeStoredIdentity();
+        // TODO(post-alpha): once @aithos/protocol-client exposes a public
+        // configuration API for the `api` endpoint, route this through the
+        // same channel as `readRpc` / `publishZoneEdit` so self-hosters
+        // can override. For now, target the production write surface.
+        const url = "https://api.aithos.be/mcp/primitives/write";
+        const params = {
+            mandate_id: mandateId,
+            revoked_at: new Date().toISOString(),
+        };
+        // Reach into the owner's #public signer for envelope signing via
+        // the centralized migration bridge (will go away when
+        // protocol-client accepts Signer-shaped objects).
+        const publicKp = ownerKeyPair(owner, "public");
+        const envelope = buildSignedEnvelope({
+            iss: ownerStored.did,
+            aud: url,
+            method: "aithos.publish_revocation",
+            verificationMethod: `${ownerStored.did}#public`,
+            params,
+            signer: publicKp,
+        });
+        let res;
+        try {
+            res = await this.#deps.fetch(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: "aithos.publish_revocation",
+                    method: "aithos.publish_revocation",
+                    params: { ...params, _envelope: envelope },
+                }),
+            });
+        }
+        catch (e) {
+            throw new AithosSDKError("network", e.message);
+        }
+        const body = (await res.json().catch(() => null));
+        if (!body) {
+            throw new AithosSDKError("http", `HTTP ${res.status} ${res.statusText} — non-JSON response`, { status: res.status });
+        }
+        if (body.error) {
+            throw new AithosSDKError(`mandates_${body.error.code}`, body.error.message, body.error.data ? { data: body.error.data } : undefined);
+        }
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  Internals                                                               */
+    /* ------------------------------------------------------------------------ */
+    #requireOwner() {
+        const owner = this.#deps.auth._getOwnerSigners();
+        if (!owner || owner.destroyed) {
+            throw new AithosSDKError("mandates_no_owner", "no owner signed in; sign in first");
+        }
+        return owner;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*  Helpers                                                                   */
+/* -------------------------------------------------------------------------- */
+function defaultSphereFromScopes(scopes) {
+    if (scopes.some((s) => s.endsWith(".self")))
+        return "self";
+    if (scopes.some((s) => s.endsWith(".circle")))
+        return "circle";
+    return "public";
+}
+/**
+ * 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 {
+        mandateId: requireString(it, "mandate_id"),
+        issuerDid: requireString(it, "issuer_did"),
+        actorDid: requireString(it, "actor_did"),
+        scopes: filterScopeArray(it["scopes"]),
+        notBefore: typeof it["not_before"] === "number" ? it["not_before"] : null,
+        notAfter: typeof it["not_after"] === "number" ? it["not_after"] : null,
+        createdAt: typeof it["created_at"] === "number" ? it["created_at"] : 0,
+    };
+}
+function requireString(o, key) {
+    const v = o[key];
+    if (typeof v !== "string") {
+        throw new AithosSDKError("mandates_response_malformed", `list_mandates row missing string field ${key}`);
+    }
+    return v;
+}
+function filterScopeArray(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((s) => typeof s === "string");
+}
 //# sourceMappingURL=mandates.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

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

@@ -0,0 +1,28 @@
+/**
+ * `@aithos/sdk/react` — React bindings for the Aithos SDK.
+ *
+ * Drop-in components and hooks for displaying Aithos-hosted assets in
+ * React applications. The package's only peer dependency beyond
+ * `@aithos/sdk` itself is `react` (^18 || ^19).
+ *
+ * Quick start:
+ *
+ *     // 1. Wrap your tree once
+ *     <AssetsClientProvider client={sdk.assets}>
+ *       <App />
+ *     </AssetsClientProvider>
+ *
+ *     // 2. Use anywhere
+ *     <AithosAsset urn={cv.urn} alt="CV" className="w-full" />
+ *     <AithosAsset urn={video.urn} as="video" controls />
+ *     <AithosAsset urn={pdf.urn} as="download" filename="cv.pdf">
+ *       Download my CV
+ *     </AithosAsset>
+ *
+ *     // 3. Or use the hook directly for custom rendering
+ *     const { url, bytes, loading, error } = useAithosAsset(urn);
+ */
+export { AssetsClientProvider, useAssetsClient, type AssetsClientProviderProps, } from "./context.js";
+export { useAithosAsset, type UseAithosAssetState, type UseAithosAssetOptions, } from "./use-aithos-asset.js";
+export { AithosAsset, type AithosAssetProps, type AithosImageProps, type AithosVideoProps, type AithosAudioProps, type AithosDownloadProps, } from "./AithosAsset.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/react/index.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * `@aithos/sdk/react` — React bindings for the Aithos SDK.
+ *
+ * Drop-in components and hooks for displaying Aithos-hosted assets in
+ * React applications. The package's only peer dependency beyond
+ * `@aithos/sdk` itself is `react` (^18 || ^19).
+ *
+ * Quick start:
+ *
+ *     // 1. Wrap your tree once
+ *     <AssetsClientProvider client={sdk.assets}>
+ *       <App />
+ *     </AssetsClientProvider>
+ *
+ *     // 2. Use anywhere
+ *     <AithosAsset urn={cv.urn} alt="CV" className="w-full" />
+ *     <AithosAsset urn={video.urn} as="video" controls />
+ *     <AithosAsset urn={pdf.urn} as="download" filename="cv.pdf">
+ *       Download my CV
+ *     </AithosAsset>
+ *
+ *     // 3. Or use the hook directly for custom rendering
+ *     const { url, bytes, loading, error } = useAithosAsset(urn);
+ */
+export { AssetsClientProvider, useAssetsClient, } from "./context.js";
+export { useAithosAsset, } from "./use-aithos-asset.js";
+export { AithosAsset, } from "./AithosAsset.js";
+//# sourceMappingURL=index.js.map

package/dist/src/react/use-aithos-asset.d.ts

@@ -0,0 +1,39 @@
+import type { AssetsClient } from "../assets.js";
+export interface UseAithosAssetState {
+    /** A `blob:` URL pointing at the decrypted plaintext. Use in <img src=…> etc. */
+    readonly url: string | null;
+    /** Raw decrypted bytes. Use when you need the binary itself (e.g. PDF viewer). */
+    readonly bytes: Uint8Array | null;
+    /** IANA media type — useful for routing rendering. */
+    readonly mediaType: string | null;
+    /** Plaintext size in bytes. */
+    readonly sizeBytes: number | null;
+    /** True while the fetch+decrypt is in flight. */
+    readonly loading: boolean;
+    /** Non-null when the fetch/decrypt failed. */
+    readonly error: Error | null;
+}
+export interface UseAithosAssetOptions {
+    /** Override the client from context. Useful for tests. */
+    readonly client?: AssetsClient | null;
+    /**
+     * If `true`, the hook keeps the previous blob URL visible while a
+     * new URN is being fetched, instead of flashing `null`. Default
+     * `false` (more predictable, less visual stutter avoidance).
+     */
+    readonly keepPreviousOnUrnChange?: boolean;
+}
+/**
+ * Fetch + decrypt an Aithos asset and return a stable `blob:` URL.
+ *
+ * Lifecycle:
+ *  - On mount or when `urn` changes, runs `client.fetch(urn)`.
+ *  - On success, creates an object URL from the plaintext bytes.
+ *  - On unmount or before refetching, revokes the URL to free memory.
+ *  - Cancels in-flight fetches if the URN changes mid-flight.
+ *
+ * Throws (via `error`) when no client is available — supply one via
+ * `<AssetsClientProvider>` or the `client` option.
+ */
+export declare function useAithosAsset(urn: string | null | undefined, options?: UseAithosAssetOptions): UseAithosAssetState;
+//# sourceMappingURL=use-aithos-asset.d.ts.map