import type { HashBytes } from '@did-btcr2/common';
import { CID } from 'multiformats/cid';
/** Default IPFS HTTP gateway used for CAS reads when no CAS config is provided. */
export declare const DEFAULT_CAS_GATEWAY = "https://ipfs.io";
/**
 * Executor interface for content-addressed storage.
 *
 * Implementations handle the actual I/O (IPFS, HTTP gateway, local store, etc.).
 * All hashes are base64url-encoded SHA-256 digests (no padding).
 * @public
 */
export interface CasExecutor {
    /** Retrieve raw bytes by base64url SHA-256 hash. Returns null if not found. */
    retrieve(hash: string): Promise<Uint8Array | null>;
    /** Publish raw bytes and return the base64url SHA-256 hash. */
    publish(data: Uint8Array): Promise<string>;
    /**
     * Whether this executor supports publishing. `undefined` MUST be treated as
     * `true`: an executor that does not declare the capability is assumed
     * writable, so existing custom executors keep working unchanged. Read-only
     * executors (e.g. {@link HttpGatewayCasExecutor}) set `false`, letting
     * callers route around `publish()` instead of discovering the limitation
     * as a thrown error mid-operation.
     */
    readonly canPublish?: boolean;
}
/**
 * Minimal structural view of an IPFS blockstore: get/put raw blocks by CID.
 *
 * Matches the `blockstore` property of an in-process IPFS node (e.g. a Helia
 * instance), so one can be plugged in without this package depending on an
 * IPFS implementation.
 * @public
 */
export interface BlockstoreLike {
    /** Retrieve a raw block by CID. Expected to throw if the block is not found. */
    get(cid: CID): Promise<Uint8Array>;
    /** Store a raw block under the given CID. */
    put(cid: CID, block: Uint8Array): Promise<unknown>;
}
/**
 * Anything exposing a {@link BlockstoreLike} `blockstore` property,
 * e.g. an in-process IPFS node instance.
 * @public
 */
export interface BlockstoreProviderLike {
    blockstore: BlockstoreLike;
}
/**
 * {@link CasExecutor} backed by a caller-supplied in-process blockstore.
 *
 * Stores/retrieves data as raw blocks (`0x55` codec) with SHA-256 hashing.
 * The CID is deterministically derived from the content hash, so lookups
 * by base64url SHA-256 hash translate directly to CID lookups.
 * @public
 */
export declare class BlockstoreCasExecutor implements CasExecutor {
    #private;
    constructor(store: BlockstoreLike | BlockstoreProviderLike);
    retrieve(hash: string): Promise<Uint8Array | null>;
    publish(data: Uint8Array): Promise<string>;
}
/**
 * Read-write {@link CasExecutor} backed by the IPFS HTTP RPC API
 * (the interface a Kubo node exposes, default port 5001).
 *
 * Publishes raw blocks via `block/put` (pinned, raw codec, SHA-256) and
 * retrieves them via `block/get`, using plain `fetch`: no in-process IPFS
 * node required. `publish` verifies that the CID returned by the node
 * matches the CID derived locally from the content hash, so a misconfigured
 * node cannot silently store content under a different address.
 * @public
 */
export declare class IpfsRpcCasExecutor implements CasExecutor {
    #private;
    constructor(rpcUrl: string);
    retrieve(hash: string): Promise<Uint8Array | null>;
    publish(data: Uint8Array): Promise<string>;
}
/**
 * Read-only {@link CasExecutor} backed by an IPFS HTTP gateway.
 *
 * Converts the base64url SHA-256 hash to a CIDv1 (raw codec) and fetches
 * the raw block via the
 * {@link https://specs.ipfs.tech/http-gateways/trustless-gateway/ | Trustless Gateway}
 * protocol.
 *
 * Publishing is not supported: use {@link IpfsRpcCasExecutor} against a
 * node's RPC endpoint, or {@link BlockstoreCasExecutor} with an in-process
 * blockstore, for writes.
 * @public
 */
export declare class HttpGatewayCasExecutor implements CasExecutor {
    #private;
    readonly canPublish = false;
    constructor(gatewayUrl: string);
    retrieve(hash: string): Promise<Uint8Array | null>;
    publish(): Promise<string>;
}
/** Default timeout (ms) for CAS operations. */
export declare const DEFAULT_CAS_TIMEOUT_MS = 30000;
/**
 * Configuration for the CAS (Content-Addressed Storage) driver.
 *
 * Provide exactly one of `executor`, `blockstore`, `rpcUrl`, or `gateway`.
 * Priority if multiple are set: `executor` > `blockstore` > `rpcUrl` > `gateway`.
 * @public
 */
export type CasConfig = {
    /** Custom executor implementation (overrides all other options). */
    executor?: CasExecutor;
    /** In-process blockstore, or anything exposing one (e.g. an IPFS node instance). */
    blockstore?: BlockstoreLike | BlockstoreProviderLike;
    /** IPFS HTTP RPC API endpoint for read-write CAS access (e.g. `'http://127.0.0.1:5001'`). */
    rpcUrl?: string;
    /** IPFS HTTP gateway URL for read-only CAS access (e.g. `'https://ipfs.io'`). */
    gateway?: string;
    /**
     * Timeout in milliseconds for CAS operations. Prevents indefinite hangs
     * when a blockstore lookup, RPC call, or gateway request stalls.
     * Default: 30 000 ms. Set to `0` to disable.
     */
    timeoutMs?: number;
};
/**
 * Content-Addressed Storage API sub-facade.
 *
 * Provides `publish` and `retrieve` for JSON objects using their
 * JCS-canonicalized SHA-256 hash as the content address.
 *
 * The backend is selected from {@link CasConfig}: a custom executor, an
 * in-process blockstore, an IPFS RPC endpoint, or a read-only HTTP gateway.
 *
 * Lazily initialized by {@link DidBtcr2Api} to avoid startup overhead
 * when CAS features are not used.
 * @public
 */
export declare class CasApi {
    #private;
    constructor(config: CasConfig);
    /**
     * Whether the configured executor supports publishing. `true` unless the
     * executor explicitly declares `canPublish: false` (an executor that does
     * not declare the capability is assumed writable, per {@link CasExecutor}).
     */
    get writable(): boolean;
    /**
     * Retrieve a JSON object from the CAS by its SHA-256 hash bytes.
     *
     * The specification requires a resolver to compute the SHA-256 hash of the
     * retrieved content, to compare it to the hash used for the retrieval, and
     * to not use the content if the hashes differ. This method hashes the raw
     * bytes before it parses them.
     * @param hashBytes Raw SHA-256 hash bytes of the JCS-canonicalized object.
     * @returns The parsed JSON object, or `null` if not found.
     * @throws {ResolveError} `MISSING_UPDATE_DATA` if the retrieved bytes do not
     *         hash to `hashBytes`, or if they are not a JSON object.
     */
    retrieve(hashBytes: HashBytes): Promise<object | null>;
    /**
     * Publish a JSON object to the CAS.
     * The object is JCS-canonicalized before storage; the returned hash
     * matches what `canonicalHash` (from @did-btcr2/common) would produce.
     * @param object The JSON object to publish.
     * @returns The base64url-encoded SHA-256 hash (content address).
     */
    publish(object: object): Promise<string>;
}
//# sourceMappingURL=cas.d.ts.map