@dstorage-tech/dstorage-sdk 0.0.6 → 0.0.8

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { PaymentAdapter, PaymentNetworkName, TokenSymbol, NetworkType, PaymentAdapterLogger, PaymentQuote, PaymentInstruction, PaymentReceipt, MidnightWalletProvider, StorageAdapterLogger, StorageAdapter, StorageProviderName, StorageUploadResult, StorageQuote, ChainAdapter, ChainProviderName, ChainAdapterLogger, ChainReference, ChainWriteResult, ChainReferenceUpdate, DataReferenceSummary, ChainQuote, WalletBalances } from './types.js';
+import { PaymentAdapter, PaymentNetworkName, TokenSymbol, NetworkType, PaymentAdapterLogger, PaymentQuote, PaymentInstruction, PaymentReceipt, MidnightWalletProvider, StorageAdapterLogger, StorageAdapter, StorageProviderName, StorageUploadResult, RetrieveOptions, StorageQuote, ChainAdapter, ChainProviderName, ChainAdapterLogger, ChainReference, ChainWriteResult, ChainReferenceUpdate, DataReferenceSummary, ChainQuote, WalletBalances } from './types.js';
 export { ChainAdapter, ChainAdapterLogger, ChainProviderName, ChainQuote, ChainReference, ChainReferenceUpdate, ChainWriteResult, DataReferenceSummary, MidnightWalletProvider, NetworkType, PaymentAdapter, PaymentAdapterLogger, PaymentNetworkName, PaymentQuote, PaymentReceipt, StorageAdapter, StorageAdapterLogger, StorageProviderName, StorageQuote, StorageUploadResult, TOKENS, Token, TokenSymbol, WalletBalances } from './types.js';
 import Arweave from 'arweave';
 import Transaction from 'arweave/node/lib/transaction';
@@ -346,6 +346,12 @@ declare class ManagedPaymentAdapter extends ArweavePaymentAdapter {
  *
  *   • storageId (txId) is PUBLIC on Arweave. Data security relies entirely on
  *     the XChaCha20-Poly1305 encryption applied by @dstorage/crypto before reaching here.
+ *
+ *   • retrieve()'s content-hash check only defends against a malicious gateway when
+ *     called with an `expectedContentHash` anchor sourced independently of this
+ *     gateway (see skipIntegrityCheck below) — @dstorage/core supplies this
+ *     automatically from the on-chain reference. Without an anchor, the check falls
+ *     back to a gateway-supplied tag and only catches non-adversarial corruption.
  */
 
 interface ArweaveGatewayConfig {
@@ -413,9 +419,17 @@ interface ArweaveAdapterConfig {
     confirmationTimeoutMs?: number;
     /**
      * When true, skip the BLAKE3 content-hash check on retrieve.
-     * By default (false) the adapter fetches the transaction metadata and verifies
-     * that the `X-Content-Hash` tag recorded at upload time matches the retrieved
-     * bytes. Set to true only if you trust the gateway entirely or are using an
+     * By default (false) the adapter verifies retrieved bytes against a content hash.
+     * The strength of that guarantee depends on the hash's source:
+     *   - When retrieve() is called with `options.expectedContentHash` (as
+     *     `@dstorage/core` does automatically, from the on-chain ChainReference),
+     *     verification is anchored to that chain-committed value and holds even
+     *     against a fully malicious/colluding gateway.
+     *   - Without an anchor, the adapter falls back to the `X-Content-Hash` tag
+     *     fetched from this same gateway — that only catches non-adversarial
+     *     corruption in transit, since a malicious gateway controls both the tag
+     *     and the bytes and can make them consistent with each other.
+     * Set to true only if you trust the gateway entirely or are using an
      * Arweave node that does not expose the transaction metadata endpoint.
      */
     skipIntegrityCheck?: boolean;
@@ -450,7 +464,7 @@ declare class ArweaveStorageAdapter implements StorageAdapter {
     constructor(config?: ArweaveAdapterConfig);
     private getClient;
     store(data: Uint8Array, metadata?: Record<string, string>): Promise<StorageUploadResult>;
-    retrieve(id: string): Promise<{
+    retrieve(id: string, options?: RetrieveOptions): Promise<{
         bytes: Uint8Array;
         tags: Record<string, string>;
     }>;
@@ -489,6 +503,11 @@ declare class ArweaveStorageAdapter implements StorageAdapter {
  *
  * ── Retrieve flow ─────────────────────────────────────────────────────────────
  *   Standard Arweave gateway fetch (identical to ArweaveStorageAdapter.retrieve).
+ *   Its content-hash check only defends against a malicious gateway when called
+ *   with an `expectedContentHash` anchor sourced independently of this gateway
+ *   (see skipIntegrityCheck below) — @dstorage/core supplies this automatically
+ *   from the on-chain reference. Without an anchor, the check falls back to a
+ *   gateway-supplied tag and only catches non-adversarial corruption.
  *
  * ── Peer dependency ───────────────────────────────────────────────────────────
  *   No extra install needed — @dha-team/arbundles ships as a dependency of @ardrive/turbo-sdk.
@@ -541,10 +560,32 @@ interface ArweaveBundlerAdapterConfig {
     maxRetrieveSizeBytes?: number;
     /**
      * Skip BLAKE3 content-hash verification on retrieve.
+     * By default (false) the adapter verifies retrieved bytes against a content hash.
+     * The strength of that guarantee depends on the hash's source:
+     *   - When retrieve() is called with `options.expectedContentHash` (as
+     *     `@dstorage/core` does automatically, from the on-chain ChainReference),
+     *     verification is anchored to that chain-committed value and holds even
+     *     against a fully malicious/colluding gateway.
+     *   - Without an anchor, the adapter falls back to the `X-Content-Hash` tag
+     *     fetched from this same gateway — that only catches non-adversarial
+     *     corruption in transit, since a malicious gateway controls both the tag
+     *     and the bytes and can make them consistent with each other.
      * Only set to true when connecting to a fully trusted gateway.
-     * Defaults to false.
      */
     skipIntegrityCheck?: boolean;
+    /**
+     * Maximum time in milliseconds to wait for any single retrieve() request
+     * (metadata or data fetch) before aborting. Defaults to 30_000 ms (30 s).
+     * Pass `0` to disable the timeout entirely (not recommended for production).
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Maximum number of bytes allowed in the transaction metadata/tags JSON
+     * response fetched during retrieve(). Guards against a hostile or
+     * misbehaving gateway returning an oversized body to exhaust memory.
+     * Defaults to 1_048_576 (1 MiB) — metadata/tags are always tiny in practice.
+     */
+    maxMetadataResponseBytes?: number;
     /**
      * Optional logger for SDK operational output.
      */
@@ -573,12 +614,16 @@ declare class ArweaveBundlerStorageAdapter implements StorageAdapter {
     private readonly gateway;
     private readonly maxRetrieveSizeBytes;
     private readonly skipIntegrityCheck;
+    private readonly requestTimeoutMs;
+    private readonly maxMetadataResponseBytes;
     protected readonly logger: StorageAdapterLogger | undefined;
     /** RSA-4096 public key modulus (512 bytes) parsed from the auth token at construction time. */
     private readonly ownerPublicKey;
     constructor(config?: ArweaveBundlerAdapterConfig);
     store(data: Uint8Array, metadata?: Record<string, string>): Promise<StorageUploadResult>;
-    retrieve(id: string): Promise<{
+    /** Adds an AbortSignal.timeout() to a fetch init object (when requestTimeoutMs > 0). */
+    private _withTimeout;
+    retrieve(id: string, options?: RetrieveOptions): Promise<{
         bytes: Uint8Array;
         tags: Record<string, string>;
     }>;
@@ -1335,6 +1380,34 @@ declare function computeBlake3(bytes: Uint8Array): Promise<Uint8Array>;
 /** BLAKE3 hash of `bytes`, returned as a 64-character lowercase hex string. */
 declare function computeBlake3Hex(bytes: Uint8Array): Promise<string>;
 
+/**
+ * @dstorage/crypto — boundedFetch.ts
+ * Shared helper for reading a fetch Response body with a hard size cap —
+ * used by chain/storage HTTP adapters to avoid a hostile or misbehaving
+ * gateway exhausting memory with an oversized response.
+ */
+interface BoundedTextReadOptions {
+    /** Maximum number of bytes/characters allowed in the response body. */
+    maxBytes: number;
+    /** Error code to throw (caller-owned, package-specific) when the cap is exceeded. */
+    code: number;
+    /** Prefix identifying the caller/operation in the thrown error message. */
+    component: string;
+}
+/**
+ * Reads a fetch Response body as text, aborting once the accumulated size
+ * exceeds `maxBytes`.
+ *
+ * Uses a streaming reader when the Response exposes `.body` (always true for
+ * real `fetch()` responses), so a gateway that omits or lies about
+ * `Content-Length` (e.g. chunked transfer encoding) can't force an unbounded
+ * read — the read is aborted as soon as the limit is crossed, before the
+ * full body is buffered. Falls back to a single `.text()` read + post-hoc
+ * length check only when `.body` is unavailable (e.g. non-streaming
+ * environments or simple test doubles).
+ */
+declare function readResponseTextWithLimit(res: Response, opts: BoundedTextReadOptions): Promise<string>;
+
 /**
  * @dstorage/chain — adapters/midnightSimulator.ts
  *
@@ -1418,6 +1491,19 @@ interface HttpGatewayChainAdapterConfig {
      */
     customFetch?: typeof fetch;
     logger?: ChainAdapterLogger;
+    /**
+     * Maximum time in milliseconds to wait for any single request before aborting.
+     * Defaults to 30_000 ms (30 s). Pass `0` to disable the timeout entirely
+     * (not recommended for production).
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Maximum number of bytes allowed in a `readReference`/`listReferences`
+     * JSON response body. Guards against a hostile or misbehaving gateway
+     * returning an oversized body to exhaust memory. Defaults to 10_485_760
+     * (10 MiB) — generous for reference/list JSON payloads.
+     */
+    maxResponseBytes?: number;
 }
 declare class HttpGatewayChainAdapter implements ChainAdapter {
     readonly name: ChainProviderName;
@@ -1429,7 +1515,11 @@ declare class HttpGatewayChainAdapter implements ChainAdapter {
     private readonly readUrl;
     private readonly listUrl;
     private readonly deleteUrl;
+    private readonly requestTimeoutMs;
+    private readonly maxResponseBytes;
     constructor(config: HttpGatewayChainAdapterConfig);
+    /** Adds an AbortSignal.timeout() to a fetch init object (when requestTimeoutMs > 0). */
+    private _withTimeout;
     writeReference(ref: ChainReference): Promise<ChainWriteResult>;
     updateReference(refId: string, update: ChainReferenceUpdate, _ownerSecret?: Uint8Array, _newOwnerSecret?: Uint8Array): Promise<void>;
     readReference(refId: string): Promise<ChainReference>;
@@ -1769,6 +1859,8 @@ declare const EncryptionErrorCode: {
     readonly PASSWORD_SEQUENTIAL_RUN: 13008;
     readonly PASSWORD_KEYBOARD_WALK: 13009;
     readonly PASSWORD_ENTROPY_TOO_LOW: 13010;
+    readonly PASSWORD_SCRYPT_N_TOO_LOW: 13011;
+    readonly PASSWORD_SCRYPT_N_NOT_POWER_OF_TWO: 13012;
 };
 type EncryptionErrorCode = (typeof EncryptionErrorCode)[keyof typeof EncryptionErrorCode];
 
@@ -1997,6 +2089,12 @@ interface PasswordEncryptionAdapterConfig {
     /**
      * Custom scrypt parameters. Only used when `preset` is not provided.
      * Prefer `preset` for well-known configurations.
+     *
+     * `N` is rejected if it is below 32768 (OWASP 2024 minimum, 32 MB
+     * memory-hard) or is not a power of two — this floor also applies when
+     * reconstructing via `fromKdfParams()`, since a downgraded or corrupted
+     * stored value could otherwise collapse the KDF to something trivially
+     * brute-forceable.
      */
     params?: {
         N?: number;
@@ -2628,6 +2726,7 @@ declare const CoreErrorCode: {
     readonly STORAGE_ADAPTER_MISMATCH: 10052;
     readonly RETRIEVE_BY_REF_ID_ENVELOPE_EMPTY: 10053;
     readonly CONTENT_HASH_MISMATCH: 10054;
+    readonly METADATA_PARSE_FAILED: 10055;
     readonly LIST_REFS_REQUIRES_CHAIN: 10060;
     readonly LIST_REFS_NOT_SUPPORTED: 10061;
     readonly REMOVE_REF_REQUIRES_CHAIN: 10070;
@@ -2638,6 +2737,7 @@ declare const CoreErrorCode: {
     readonly DECRYPT_CHUNK_FAILED: 10093;
     readonly CHUNK_OVERFLOWS_TOTAL_SIZE: 10094;
     readonly REASSEMBLY_SIZE_MISMATCH: 10095;
+    readonly MANIFEST_PARSE_FAILED: 10096;
     readonly NOT_INITIALIZED: 10100;
     readonly UNKNOWN_ERROR: 10999;
 };
@@ -2653,4 +2753,4 @@ declare class StorePartialError extends DStorageError {
 }
 declare function isStorePartialError(err: unknown): err is StorePartialError;
 
-export { ARWEAVE_LOCAL, type AdapterWalletProvider, type ArweaveBundlerAdapterConfig, ArweaveBundlerStorageAdapter, type ArweaveLocalAdapterConfig, type ArweaveLocalBalance, ArweaveLocalError, ArweaveLocalHelper, type ArweaveLocalHelperConfig, type ArweaveLocalInfo, ArweaveLocalStorageAdapter, ArweavePaymentAdapter, ArweaveStorageAdapter, CHUNK_SIZE, type ChunkEntry, type ChunkManifest, CoreErrorCode, type CostEstimate, CryptoErrorCode, type CryptoScheme, DStorage, type DStorageConfig, DStorageError, type EncryptionAdapter, EncryptionErrorCode, type EncryptionScheme, type FromKdfParamsConfig, HttpGatewayChainAdapter, type HttpGatewayChainAdapterConfig, KDF_PRESETS, type KdfPreset, KeyDeriver, type KeyEnvelope, type KeyWrapper, KeypairEncryptionAdapter, type ListReferencesOptions, type Logger, MANIFEST_AAD, METADATA_AAD, METADATA_ONLY_OWNER_SECRET_SALT, type MLKemVariant, ManagedPaymentAdapter, MidnightChainAdapter, type MidnightChainAdapterConfig, MidnightSimulatorChainAdapter, MnemonicEncryptionAdapter, NETWORKS, PAYLOAD_AAD, PasswordEncryptionAdapter, type PasswordEncryptionAdapterConfig, type RegisterReferenceOptions, type RegisterReferenceResult, type RetrieveResult, type StoreOptions, StorePartialError, type StoreProgress, type StoreRecovery, type StoreResult, type StoredKdfParams, type UpdateResult, type WalletAddresses, type WalletInfo, type WrappedDekResult, type XChaChaPayload, XChaChaScheme, arlocalGateway, base64urlToBytes, buildKeyEnvelope, bytesToBase64url, chunkAad, computeBlake3, computeBlake3Hex, decryptStorageIdXChaCha, decryptXChaCha, deriveKek, deriveOwnerSecret, deriveSymmetricKeyFromSeed, deserializeXChaChaPayload, encryptStorageIdXChaCha, encryptXChaCha, findWrapper, generateDek, generatePqsPassword, hexToBytes, isDStorageError, isManifest, isStorePartialError, mlkemGenerateKeypair, mlkemGenerateKeypairFromSeed, mlkemUnwrapDek, mlkemWrapDek, parseKeyEnvelope, serializeKeyEnvelope, serializeXChaChaPayload, unwrapKey, waitForFacadeSync, wrapKey };
+export { ARWEAVE_LOCAL, type AdapterWalletProvider, type ArweaveBundlerAdapterConfig, ArweaveBundlerStorageAdapter, type ArweaveLocalAdapterConfig, type ArweaveLocalBalance, ArweaveLocalError, ArweaveLocalHelper, type ArweaveLocalHelperConfig, type ArweaveLocalInfo, ArweaveLocalStorageAdapter, ArweavePaymentAdapter, ArweaveStorageAdapter, type BoundedTextReadOptions, CHUNK_SIZE, type ChunkEntry, type ChunkManifest, CoreErrorCode, type CostEstimate, CryptoErrorCode, type CryptoScheme, DStorage, type DStorageConfig, DStorageError, type EncryptionAdapter, EncryptionErrorCode, type EncryptionScheme, type FromKdfParamsConfig, HttpGatewayChainAdapter, type HttpGatewayChainAdapterConfig, KDF_PRESETS, type KdfPreset, KeyDeriver, type KeyEnvelope, type KeyWrapper, KeypairEncryptionAdapter, type ListReferencesOptions, type Logger, MANIFEST_AAD, METADATA_AAD, METADATA_ONLY_OWNER_SECRET_SALT, type MLKemVariant, ManagedPaymentAdapter, MidnightChainAdapter, type MidnightChainAdapterConfig, MidnightSimulatorChainAdapter, MnemonicEncryptionAdapter, NETWORKS, PAYLOAD_AAD, PasswordEncryptionAdapter, type PasswordEncryptionAdapterConfig, type RegisterReferenceOptions, type RegisterReferenceResult, type RetrieveResult, type StoreOptions, StorePartialError, type StoreProgress, type StoreRecovery, type StoreResult, type StoredKdfParams, type UpdateResult, type WalletAddresses, type WalletInfo, type WrappedDekResult, type XChaChaPayload, XChaChaScheme, arlocalGateway, base64urlToBytes, buildKeyEnvelope, bytesToBase64url, chunkAad, computeBlake3, computeBlake3Hex, decryptStorageIdXChaCha, decryptXChaCha, deriveKek, deriveOwnerSecret, deriveSymmetricKeyFromSeed, deserializeXChaChaPayload, encryptStorageIdXChaCha, encryptXChaCha, findWrapper, generateDek, generatePqsPassword, hexToBytes, isDStorageError, isManifest, isStorePartialError, mlkemGenerateKeypair, mlkemGenerateKeypairFromSeed, mlkemUnwrapDek, mlkemWrapDek, parseKeyEnvelope, readResponseTextWithLimit, serializeKeyEnvelope, serializeXChaChaPayload, unwrapKey, waitForFacadeSync, wrapKey };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PaymentAdapter, PaymentNetworkName, TokenSymbol, NetworkType, PaymentAdapterLogger, PaymentQuote, PaymentInstruction, PaymentReceipt, MidnightWalletProvider, StorageAdapterLogger, StorageAdapter, StorageProviderName, StorageUploadResult, StorageQuote, ChainAdapter, ChainProviderName, ChainAdapterLogger, ChainReference, ChainWriteResult, ChainReferenceUpdate, DataReferenceSummary, ChainQuote, WalletBalances } from './types.js';
+import { PaymentAdapter, PaymentNetworkName, TokenSymbol, NetworkType, PaymentAdapterLogger, PaymentQuote, PaymentInstruction, PaymentReceipt, MidnightWalletProvider, StorageAdapterLogger, StorageAdapter, StorageProviderName, StorageUploadResult, RetrieveOptions, StorageQuote, ChainAdapter, ChainProviderName, ChainAdapterLogger, ChainReference, ChainWriteResult, ChainReferenceUpdate, DataReferenceSummary, ChainQuote, WalletBalances } from './types.js';
 export { ChainAdapter, ChainAdapterLogger, ChainProviderName, ChainQuote, ChainReference, ChainReferenceUpdate, ChainWriteResult, DataReferenceSummary, MidnightWalletProvider, NetworkType, PaymentAdapter, PaymentAdapterLogger, PaymentNetworkName, PaymentQuote, PaymentReceipt, StorageAdapter, StorageAdapterLogger, StorageProviderName, StorageQuote, StorageUploadResult, TOKENS, Token, TokenSymbol, WalletBalances } from './types.js';
 import Arweave from 'arweave';
 import Transaction from 'arweave/node/lib/transaction';
@@ -346,6 +346,12 @@ declare class ManagedPaymentAdapter extends ArweavePaymentAdapter {
  *
  *   • storageId (txId) is PUBLIC on Arweave. Data security relies entirely on
  *     the XChaCha20-Poly1305 encryption applied by @dstorage/crypto before reaching here.
+ *
+ *   • retrieve()'s content-hash check only defends against a malicious gateway when
+ *     called with an `expectedContentHash` anchor sourced independently of this
+ *     gateway (see skipIntegrityCheck below) — @dstorage/core supplies this
+ *     automatically from the on-chain reference. Without an anchor, the check falls
+ *     back to a gateway-supplied tag and only catches non-adversarial corruption.
  */
 
 interface ArweaveGatewayConfig {
@@ -413,9 +419,17 @@ interface ArweaveAdapterConfig {
     confirmationTimeoutMs?: number;
     /**
      * When true, skip the BLAKE3 content-hash check on retrieve.
-     * By default (false) the adapter fetches the transaction metadata and verifies
-     * that the `X-Content-Hash` tag recorded at upload time matches the retrieved
-     * bytes. Set to true only if you trust the gateway entirely or are using an
+     * By default (false) the adapter verifies retrieved bytes against a content hash.
+     * The strength of that guarantee depends on the hash's source:
+     *   - When retrieve() is called with `options.expectedContentHash` (as
+     *     `@dstorage/core` does automatically, from the on-chain ChainReference),
+     *     verification is anchored to that chain-committed value and holds even
+     *     against a fully malicious/colluding gateway.
+     *   - Without an anchor, the adapter falls back to the `X-Content-Hash` tag
+     *     fetched from this same gateway — that only catches non-adversarial
+     *     corruption in transit, since a malicious gateway controls both the tag
+     *     and the bytes and can make them consistent with each other.
+     * Set to true only if you trust the gateway entirely or are using an
      * Arweave node that does not expose the transaction metadata endpoint.
      */
     skipIntegrityCheck?: boolean;
@@ -450,7 +464,7 @@ declare class ArweaveStorageAdapter implements StorageAdapter {
     constructor(config?: ArweaveAdapterConfig);
     private getClient;
     store(data: Uint8Array, metadata?: Record<string, string>): Promise<StorageUploadResult>;
-    retrieve(id: string): Promise<{
+    retrieve(id: string, options?: RetrieveOptions): Promise<{
         bytes: Uint8Array;
         tags: Record<string, string>;
     }>;
@@ -489,6 +503,11 @@ declare class ArweaveStorageAdapter implements StorageAdapter {
  *
  * ── Retrieve flow ─────────────────────────────────────────────────────────────
  *   Standard Arweave gateway fetch (identical to ArweaveStorageAdapter.retrieve).
+ *   Its content-hash check only defends against a malicious gateway when called
+ *   with an `expectedContentHash` anchor sourced independently of this gateway
+ *   (see skipIntegrityCheck below) — @dstorage/core supplies this automatically
+ *   from the on-chain reference. Without an anchor, the check falls back to a
+ *   gateway-supplied tag and only catches non-adversarial corruption.
  *
  * ── Peer dependency ───────────────────────────────────────────────────────────
  *   No extra install needed — @dha-team/arbundles ships as a dependency of @ardrive/turbo-sdk.
@@ -541,10 +560,32 @@ interface ArweaveBundlerAdapterConfig {
     maxRetrieveSizeBytes?: number;
     /**
      * Skip BLAKE3 content-hash verification on retrieve.
+     * By default (false) the adapter verifies retrieved bytes against a content hash.
+     * The strength of that guarantee depends on the hash's source:
+     *   - When retrieve() is called with `options.expectedContentHash` (as
+     *     `@dstorage/core` does automatically, from the on-chain ChainReference),
+     *     verification is anchored to that chain-committed value and holds even
+     *     against a fully malicious/colluding gateway.
+     *   - Without an anchor, the adapter falls back to the `X-Content-Hash` tag
+     *     fetched from this same gateway — that only catches non-adversarial
+     *     corruption in transit, since a malicious gateway controls both the tag
+     *     and the bytes and can make them consistent with each other.
      * Only set to true when connecting to a fully trusted gateway.
-     * Defaults to false.
      */
     skipIntegrityCheck?: boolean;
+    /**
+     * Maximum time in milliseconds to wait for any single retrieve() request
+     * (metadata or data fetch) before aborting. Defaults to 30_000 ms (30 s).
+     * Pass `0` to disable the timeout entirely (not recommended for production).
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Maximum number of bytes allowed in the transaction metadata/tags JSON
+     * response fetched during retrieve(). Guards against a hostile or
+     * misbehaving gateway returning an oversized body to exhaust memory.
+     * Defaults to 1_048_576 (1 MiB) — metadata/tags are always tiny in practice.
+     */
+    maxMetadataResponseBytes?: number;
     /**
      * Optional logger for SDK operational output.
      */
@@ -573,12 +614,16 @@ declare class ArweaveBundlerStorageAdapter implements StorageAdapter {
     private readonly gateway;
     private readonly maxRetrieveSizeBytes;
     private readonly skipIntegrityCheck;
+    private readonly requestTimeoutMs;
+    private readonly maxMetadataResponseBytes;
     protected readonly logger: StorageAdapterLogger | undefined;
     /** RSA-4096 public key modulus (512 bytes) parsed from the auth token at construction time. */
     private readonly ownerPublicKey;
     constructor(config?: ArweaveBundlerAdapterConfig);
     store(data: Uint8Array, metadata?: Record<string, string>): Promise<StorageUploadResult>;
-    retrieve(id: string): Promise<{
+    /** Adds an AbortSignal.timeout() to a fetch init object (when requestTimeoutMs > 0). */
+    private _withTimeout;
+    retrieve(id: string, options?: RetrieveOptions): Promise<{
         bytes: Uint8Array;
         tags: Record<string, string>;
     }>;
@@ -1335,6 +1380,34 @@ declare function computeBlake3(bytes: Uint8Array): Promise<Uint8Array>;
 /** BLAKE3 hash of `bytes`, returned as a 64-character lowercase hex string. */
 declare function computeBlake3Hex(bytes: Uint8Array): Promise<string>;
 
+/**
+ * @dstorage/crypto — boundedFetch.ts
+ * Shared helper for reading a fetch Response body with a hard size cap —
+ * used by chain/storage HTTP adapters to avoid a hostile or misbehaving
+ * gateway exhausting memory with an oversized response.
+ */
+interface BoundedTextReadOptions {
+    /** Maximum number of bytes/characters allowed in the response body. */
+    maxBytes: number;
+    /** Error code to throw (caller-owned, package-specific) when the cap is exceeded. */
+    code: number;
+    /** Prefix identifying the caller/operation in the thrown error message. */
+    component: string;
+}
+/**
+ * Reads a fetch Response body as text, aborting once the accumulated size
+ * exceeds `maxBytes`.
+ *
+ * Uses a streaming reader when the Response exposes `.body` (always true for
+ * real `fetch()` responses), so a gateway that omits or lies about
+ * `Content-Length` (e.g. chunked transfer encoding) can't force an unbounded
+ * read — the read is aborted as soon as the limit is crossed, before the
+ * full body is buffered. Falls back to a single `.text()` read + post-hoc
+ * length check only when `.body` is unavailable (e.g. non-streaming
+ * environments or simple test doubles).
+ */
+declare function readResponseTextWithLimit(res: Response, opts: BoundedTextReadOptions): Promise<string>;
+
 /**
  * @dstorage/chain — adapters/midnightSimulator.ts
  *
@@ -1418,6 +1491,19 @@ interface HttpGatewayChainAdapterConfig {
      */
     customFetch?: typeof fetch;
     logger?: ChainAdapterLogger;
+    /**
+     * Maximum time in milliseconds to wait for any single request before aborting.
+     * Defaults to 30_000 ms (30 s). Pass `0` to disable the timeout entirely
+     * (not recommended for production).
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Maximum number of bytes allowed in a `readReference`/`listReferences`
+     * JSON response body. Guards against a hostile or misbehaving gateway
+     * returning an oversized body to exhaust memory. Defaults to 10_485_760
+     * (10 MiB) — generous for reference/list JSON payloads.
+     */
+    maxResponseBytes?: number;
 }
 declare class HttpGatewayChainAdapter implements ChainAdapter {
     readonly name: ChainProviderName;
@@ -1429,7 +1515,11 @@ declare class HttpGatewayChainAdapter implements ChainAdapter {
     private readonly readUrl;
     private readonly listUrl;
     private readonly deleteUrl;
+    private readonly requestTimeoutMs;
+    private readonly maxResponseBytes;
     constructor(config: HttpGatewayChainAdapterConfig);
+    /** Adds an AbortSignal.timeout() to a fetch init object (when requestTimeoutMs > 0). */
+    private _withTimeout;
     writeReference(ref: ChainReference): Promise<ChainWriteResult>;
     updateReference(refId: string, update: ChainReferenceUpdate, _ownerSecret?: Uint8Array, _newOwnerSecret?: Uint8Array): Promise<void>;
     readReference(refId: string): Promise<ChainReference>;
@@ -1769,6 +1859,8 @@ declare const EncryptionErrorCode: {
     readonly PASSWORD_SEQUENTIAL_RUN: 13008;
     readonly PASSWORD_KEYBOARD_WALK: 13009;
     readonly PASSWORD_ENTROPY_TOO_LOW: 13010;
+    readonly PASSWORD_SCRYPT_N_TOO_LOW: 13011;
+    readonly PASSWORD_SCRYPT_N_NOT_POWER_OF_TWO: 13012;
 };
 type EncryptionErrorCode = (typeof EncryptionErrorCode)[keyof typeof EncryptionErrorCode];
 
@@ -1997,6 +2089,12 @@ interface PasswordEncryptionAdapterConfig {
     /**
      * Custom scrypt parameters. Only used when `preset` is not provided.
      * Prefer `preset` for well-known configurations.
+     *
+     * `N` is rejected if it is below 32768 (OWASP 2024 minimum, 32 MB
+     * memory-hard) or is not a power of two — this floor also applies when
+     * reconstructing via `fromKdfParams()`, since a downgraded or corrupted
+     * stored value could otherwise collapse the KDF to something trivially
+     * brute-forceable.
      */
     params?: {
         N?: number;
@@ -2628,6 +2726,7 @@ declare const CoreErrorCode: {
     readonly STORAGE_ADAPTER_MISMATCH: 10052;
     readonly RETRIEVE_BY_REF_ID_ENVELOPE_EMPTY: 10053;
     readonly CONTENT_HASH_MISMATCH: 10054;
+    readonly METADATA_PARSE_FAILED: 10055;
     readonly LIST_REFS_REQUIRES_CHAIN: 10060;
     readonly LIST_REFS_NOT_SUPPORTED: 10061;
     readonly REMOVE_REF_REQUIRES_CHAIN: 10070;
@@ -2638,6 +2737,7 @@ declare const CoreErrorCode: {
     readonly DECRYPT_CHUNK_FAILED: 10093;
     readonly CHUNK_OVERFLOWS_TOTAL_SIZE: 10094;
     readonly REASSEMBLY_SIZE_MISMATCH: 10095;
+    readonly MANIFEST_PARSE_FAILED: 10096;
     readonly NOT_INITIALIZED: 10100;
     readonly UNKNOWN_ERROR: 10999;
 };
@@ -2653,4 +2753,4 @@ declare class StorePartialError extends DStorageError {
 }
 declare function isStorePartialError(err: unknown): err is StorePartialError;
 
-export { ARWEAVE_LOCAL, type AdapterWalletProvider, type ArweaveBundlerAdapterConfig, ArweaveBundlerStorageAdapter, type ArweaveLocalAdapterConfig, type ArweaveLocalBalance, ArweaveLocalError, ArweaveLocalHelper, type ArweaveLocalHelperConfig, type ArweaveLocalInfo, ArweaveLocalStorageAdapter, ArweavePaymentAdapter, ArweaveStorageAdapter, CHUNK_SIZE, type ChunkEntry, type ChunkManifest, CoreErrorCode, type CostEstimate, CryptoErrorCode, type CryptoScheme, DStorage, type DStorageConfig, DStorageError, type EncryptionAdapter, EncryptionErrorCode, type EncryptionScheme, type FromKdfParamsConfig, HttpGatewayChainAdapter, type HttpGatewayChainAdapterConfig, KDF_PRESETS, type KdfPreset, KeyDeriver, type KeyEnvelope, type KeyWrapper, KeypairEncryptionAdapter, type ListReferencesOptions, type Logger, MANIFEST_AAD, METADATA_AAD, METADATA_ONLY_OWNER_SECRET_SALT, type MLKemVariant, ManagedPaymentAdapter, MidnightChainAdapter, type MidnightChainAdapterConfig, MidnightSimulatorChainAdapter, MnemonicEncryptionAdapter, NETWORKS, PAYLOAD_AAD, PasswordEncryptionAdapter, type PasswordEncryptionAdapterConfig, type RegisterReferenceOptions, type RegisterReferenceResult, type RetrieveResult, type StoreOptions, StorePartialError, type StoreProgress, type StoreRecovery, type StoreResult, type StoredKdfParams, type UpdateResult, type WalletAddresses, type WalletInfo, type WrappedDekResult, type XChaChaPayload, XChaChaScheme, arlocalGateway, base64urlToBytes, buildKeyEnvelope, bytesToBase64url, chunkAad, computeBlake3, computeBlake3Hex, decryptStorageIdXChaCha, decryptXChaCha, deriveKek, deriveOwnerSecret, deriveSymmetricKeyFromSeed, deserializeXChaChaPayload, encryptStorageIdXChaCha, encryptXChaCha, findWrapper, generateDek, generatePqsPassword, hexToBytes, isDStorageError, isManifest, isStorePartialError, mlkemGenerateKeypair, mlkemGenerateKeypairFromSeed, mlkemUnwrapDek, mlkemWrapDek, parseKeyEnvelope, serializeKeyEnvelope, serializeXChaChaPayload, unwrapKey, waitForFacadeSync, wrapKey };
+export { ARWEAVE_LOCAL, type AdapterWalletProvider, type ArweaveBundlerAdapterConfig, ArweaveBundlerStorageAdapter, type ArweaveLocalAdapterConfig, type ArweaveLocalBalance, ArweaveLocalError, ArweaveLocalHelper, type ArweaveLocalHelperConfig, type ArweaveLocalInfo, ArweaveLocalStorageAdapter, ArweavePaymentAdapter, ArweaveStorageAdapter, type BoundedTextReadOptions, CHUNK_SIZE, type ChunkEntry, type ChunkManifest, CoreErrorCode, type CostEstimate, CryptoErrorCode, type CryptoScheme, DStorage, type DStorageConfig, DStorageError, type EncryptionAdapter, EncryptionErrorCode, type EncryptionScheme, type FromKdfParamsConfig, HttpGatewayChainAdapter, type HttpGatewayChainAdapterConfig, KDF_PRESETS, type KdfPreset, KeyDeriver, type KeyEnvelope, type KeyWrapper, KeypairEncryptionAdapter, type ListReferencesOptions, type Logger, MANIFEST_AAD, METADATA_AAD, METADATA_ONLY_OWNER_SECRET_SALT, type MLKemVariant, ManagedPaymentAdapter, MidnightChainAdapter, type MidnightChainAdapterConfig, MidnightSimulatorChainAdapter, MnemonicEncryptionAdapter, NETWORKS, PAYLOAD_AAD, PasswordEncryptionAdapter, type PasswordEncryptionAdapterConfig, type RegisterReferenceOptions, type RegisterReferenceResult, type RetrieveResult, type StoreOptions, StorePartialError, type StoreProgress, type StoreRecovery, type StoreResult, type StoredKdfParams, type UpdateResult, type WalletAddresses, type WalletInfo, type WrappedDekResult, type XChaChaPayload, XChaChaScheme, arlocalGateway, base64urlToBytes, buildKeyEnvelope, bytesToBase64url, chunkAad, computeBlake3, computeBlake3Hex, decryptStorageIdXChaCha, decryptXChaCha, deriveKek, deriveOwnerSecret, deriveSymmetricKeyFromSeed, deserializeXChaChaPayload, encryptStorageIdXChaCha, encryptXChaCha, findWrapper, generateDek, generatePqsPassword, hexToBytes, isDStorageError, isManifest, isStorePartialError, mlkemGenerateKeypair, mlkemGenerateKeypairFromSeed, mlkemUnwrapDek, mlkemWrapDek, parseKeyEnvelope, readResponseTextWithLimit, serializeKeyEnvelope, serializeXChaChaPayload, unwrapKey, waitForFacadeSync, wrapKey };