@dstorage-tech/dstorage-sdk 0.0.4 → 0.0.6

package/README.md

@@ -1,5 +1,7 @@
 # dStorage SDK
 
+> ⚠️ **Active development (v0.0.x)**: APIs may still change. It's safe to follow the guides, but hold off on production use for now.
+
 > Privacy-first data layer for dApps — client-side encryption + decentralised storage + on-chain coordination in a single SDK.
 
 For teams building privacy-sensitive dApps (health, identity, finance, and enterprise workflows) that need strong client-side confidentiality without operating plaintext data infrastructure.
@@ -131,10 +133,14 @@ import { DStorage, ArweaveStorageAdapter } from "@dstorage-tech/dstorage-sdk";
 ```
 
 Bundlers configured for a browser target (Vite, webpack 5+, Rollup, esbuild) resolve the
-plain import to a pre-built, minified, browser-safe bundle automatically via the
-`"browser"` condition in `package.json`'s `exports` map — it excludes all Node.js-only
-code (`node:fs`, LevelDB, etc.). For tooling that doesn't resolve conditional exports, or
-for explicit clarity, the same bundle is also available at the `/browser` subpath:
+plain import to a pre-built, browser-safe bundle automatically via the `"browser"`
+condition in `package.json`'s `exports` map. It is not minified — minification strips
+the `/* @vite-ignore */` comments that tell a bundler to skip static analysis of
+Node-only code paths (e.g. `MidnightChainAdapter`'s facade/provider mode, which
+dynamically imports `fs` and LevelDB). Those Node-only paths are present in the bundle
+but statically unreachable in connector mode. For tooling that doesn't resolve
+conditional exports, or for explicit clarity, the same bundle is also available at the
+`/browser` subpath:
 
 ```typescript
 import {
@@ -511,6 +517,20 @@ const adapter = await KeypairEncryptionAdapter.fromPassword(
 
 **Authenticated Encryption with Associated Data (AEAD)**. The Poly1305 tag covers the ciphertext. Any bit-flip in the on-chain encrypted pointer causes decryption to throw before the SDK ever attempts to fetch from storage.
 
+**AAD context binding**. Beyond integrity, each ciphertext is bound to its _role and position_ via Additional Authenticated Data (AAD). The AAD is not encrypted — it is a plain label passed alongside the ciphertext — but the Poly1305 MAC covers it, so any mismatch causes decryption to fail. The SDK uses four distinct labels:
+
+| Label      | Value                         | Purpose                                                      |
+| ---------- | ----------------------------- | ------------------------------------------------------------ |
+| Payload    | `"dstorage:payload:v1"`       | Single-shot file uploads (non-chunked user content)          |
+| Manifest   | `"dstorage:manifest:v1"`      | The chunked upload manifest (distinct from user content)     |
+| Chunk      | `"dstorage:chunk:v1:<i>/<n>"` | Each chunk in a chunked upload, bound to its index and total |
+| Storage ID | `"dstorage:storageId:v1"`     | The storage pointer encrypted on-chain                       |
+
+This means a ciphertext produced for one role cannot be silently substituted into another. In particular:
+
+- A storage gateway that reorders or swaps chunk blobs causes decryption to throw — the MAC was computed with a different index label.
+- A user file whose plaintext happens to look like a manifest JSON cannot be misinterpreted as one — a payload ciphertext (encrypted with `"dstorage:payload:v1"`) will fail MAC verification when the SDK attempts to decrypt it as a manifest (with `"dstorage:manifest:v1"`). Manifest detection is cryptographic, not JSON-shape-based.
+
 ### Storage ID format
 
 The SDK treats `storageId` as an opaque string — the crypto layer encrypts its UTF-8 bytes (see [Wire formats](#wire-formats) above), so there is no length or format requirement at the SDK level. Today's Arweave-family adapters (`ArweaveStorageAdapter`, `ArweaveLocalStorageAdapter`, `ArweaveBundlerStorageAdapter`) all return 43-character base64url strings — 32 random bytes encoded without padding, matching the Arweave transaction ID format — but a storage adapter for a different network (e.g. an IPFS CID or another content-addressed ID) can return any string shape without requiring changes to the encryption layer.

package/dist/browser.d.mts

@@ -1949,170 +1949,6 @@ declare const METADATA_ONLY_OWNER_SECRET_SALT: Uint8Array;
  */
 declare const chunkAad: (index: number, total: number) => Uint8Array;
 
-/**
- * @dstorage/core — metaTx/types.ts
- *
- * All public interfaces and type aliases for the MetaTx orchestrator.
- */
-
-type MetaTxStepId = "estimate" | "encrypt" | "payment_storage" | "upload" | "chain_reference" | "complete";
-type MetaTxStepStatus = "pending" | "running" | "done" | "error";
-interface MetaTxStepState {
-    id: MetaTxStepId;
-    label: string;
-    description: string;
-    status: MetaTxStepStatus;
-    /** Live detail message updated during the step */
-    detail?: string;
-    /** Duration in ms (set when done) */
-    durationMs?: number;
-    startedAt?: number;
-}
-interface MetaTxProgress {
-    steps: MetaTxStepState[];
-    currentStepId: MetaTxStepId | null;
-    overallStatus: "idle" | "awaiting_confirmation" | "running" | "complete" | "error";
-    /** Cost estimate — set after 'estimate' step completes */
-    estimate?: CostEstimate;
-    /** Final receipt — set when complete */
-    receipt?: MetaTxReceipt;
-    /** Error message if overallStatus is 'error' */
-    error?: string;
-}
-interface MetaTxReceipt {
-    dataId: string;
-    storageId: string;
-    /** Undefined when no chain adapter is configured (storage-only mode). */
-    chainRefId?: string;
-    /** Original file info */
-    file: {
-        name: string;
-        type: string;
-        sizeBytes: number;
-    };
-    /** Payment receipts */
-    storagePayment: PaymentReceipt;
-    /** Undefined when no chain adapter is configured. */
-    chainPayment?: PaymentReceipt;
-    /** Tokens used */
-    storageToken: TokenSymbol;
-    /** Undefined when no chain adapter is configured. */
-    chainToken?: TokenSymbol;
-    /** Contract invoked (if selected) */
-    contract?: {
-        address: string;
-        name: string;
-    };
-    completedAt: number;
-    /** Duration of the full meta-transaction in ms */
-    totalDurationMs: number;
-}
-interface MetaTxConfig {
-    /** Optional metadata to attach to the on-chain reference */
-    metadata?: Record<string, string>;
-    /** Selected contract address (from the contract registry) */
-    contractAddress?: string;
-    /** Selected contract name (for display / receipt) */
-    contractName?: string;
-}
-/**
- * Crypto materials for a single upload: a fresh random DEK wrapped in a
- * key envelope, ready to encrypt payload and storageId.
- *
- * For private uploads: uploadScheme encrypts content; dek is the per-upload
- * Data Encryption Key used both to encrypt content AND to derive
- * ownerSecret = HKDF(dek, rawStorageId). Any KEK holder can re-derive the
- * ownerSecret by unwrapping the envelope DEK.
- * For public uploads: uploadScheme is null; ownerSeed is a random secret wrapped
- * under every KEK in keyEnvelope, and ownerSecret = HKDF(ownerSeed, rawStorageId).
- * Any single KEK holder can re-derive the ownerSecret by unwrapping the envelope.
- */
-interface UploadCrypto {
-    /** XChaChaScheme built from a fresh random DEK. null for public uploads. */
-    uploadScheme: CryptoScheme | null;
-    /** JSON-encoded KeyEnvelope wrapping the DEK (private) or ownerSeed (public) under every KEK. */
-    keyEnvelope: string;
-    /** Encryption scheme identifier to record on-chain. "" for public uploads. */
-    encryptionScheme: EncryptionScheme;
-    /**
-     * The raw per-upload DEK for private uploads; undefined for public uploads.
-     * Used by MetaTx to derive ownerSecret = HKDF(dek, rawStorageId) after upload.
-     * Not stored anywhere — must not be persisted.
-     */
-    dek?: Uint8Array;
-    /**
-     * The raw ownerSeed for public uploads; undefined for private uploads.
-     * Used by MetaTx to derive ownerSecret = HKDF(ownerSeed, rawStorageId) after upload.
-     * Not stored anywhere — must not be persisted.
-     */
-    ownerSeed?: Uint8Array;
-}
-/**
- * Minimal SDK surface required by MetaTx.
- * Implemented by DStorage — MetaTx receives the SDK instance directly
- * rather than individual adapters/keys/address to avoid redundant constructor args.
- */
-interface DStorageContext {
-    readonly storageAdapter: StorageAdapter;
-    readonly chainAdapter: ChainAdapter | undefined;
-    /** Wallet address of the connected user, or null if using init() / facade mode. */
-    readonly connectedAddress: string | null;
-    /**
-     * Generate a fresh random DEK, wrap it under the KEK, and return the
-     * upload crypto materials needed to encrypt payload and storageId.
-     * @param isPublic  Pass true to skip encryption (returns null scheme + no envelope).
-     */
-    prepareUploadCrypto(isPublic?: boolean): Promise<UploadCrypto>;
-    /** Estimate the full cost (storage + chain) for a given payload size. */
-    estimateCost(sizeBytes: number): Promise<CostEstimate>;
-}
-
-/**
- * @dstorage/core — metaTx/utils.ts
- *
- * Helpers used internally by MetaTx and one exported utility.
- */
-
-/**
- * Return the default chain payment token for a given chain provider name.
- */
-declare function defaultChainToken(chainProvider: string): TokenSymbol;
-
-/**
- * @dstorage/core — metaTx/MetaTx.ts
- *
- * The MetaTx orchestrator.
- *
- * Presents a single conceptual action to the user while internally executing:
- *   [0] Estimate   → compute storage + chain costs
- *   [1] Encrypt    → XChaCha20-Poly1305 encrypt the file client-side
- *   [2] PayStorage → simulate storage payment (AR / MOCK)
- *   [3] Upload     → upload encrypted blob to decentralised storage
- *   [4] Reference  → pay chain fee + write CID + metadata reference on-chain
- *   [✓] Complete   → return full receipt
- *
- * Usage:
- *   const metaTx = new MetaTx(dStorage);
- *   metaTx.onProgress((progress) => updateUI(progress));
- *   const receipt = await metaTx.execute(file);
- */
-
-declare class MetaTx {
-    private sdk;
-    private progressCallback;
-    private steps;
-    private startedAt;
-    constructor(sdk: DStorageContext);
-    /** Register a progress listener. Called after every step state change. */
-    onProgress(cb: (progress: MetaTxProgress) => void): this;
-    execute(file: File, config?: MetaTxConfig): Promise<MetaTxReceipt>;
-    private startStep;
-    private updateStepDetail;
-    private completeStep;
-    private getStep;
-    private emit;
-}
-
 /**
  * @dstorage/core — dStorage.ts
  *
@@ -2131,7 +1967,7 @@ declare class MetaTx {
  *   await ds.removeReference(chainRefId);
  */
 
-declare class DStorage implements DStorageContext {
+declare class DStorage {
     private config;
     private wallet;
     /** Encryption adapters — each wraps/unwraps per-upload DEKs using its own algorithm. */
@@ -2288,26 +2124,6 @@ declare class DStorage implements DStorageContext {
      * Estimate the full cost (storage + chain) for a given payload size before committing.
      */
     estimateCost(sizeBytes: number): Promise<CostEstimate>;
-    /**
-     * Execute a full meta-transaction for a file:
-     * estimate → encrypt → pay storage → upload → pay chain → write reference
-     *
-     * Presents the entire flow as a single action with step-by-step progress.
-     *
-     * @param file        The File to encrypt and store
-     * @param onProgress  Callback fired on every step state change
-     * @param config      Optional token overrides and metadata
-     */
-    executeMetaTransaction(file: File, onProgress: (progress: MetaTxProgress) => void, config?: MetaTxConfig): Promise<MetaTxReceipt>;
-    /**
-     * Generate a fresh random DEK, wrap it under the KEK(s), and return the crypto
-     * materials needed by MetaTx to encrypt payload and storageId.
-     *
-     * For private stores: the DEK is wrapped under every available KEK. The ownerSecret
-     * can later be re-derived as HKDF(dek, rawStorageId) by any KEK holder.
-     * For public stores: a random ownerSeed is generated and wrapped under all KEKs (same pattern).
-     */
-    prepareUploadCrypto(isPublic?: boolean): Promise<UploadCrypto>;
     /**
      * Upload large content by splitting into CHUNK_SIZE pieces, encrypting each
      * independently, and storing a manifest that ties them together.
@@ -2391,8 +2207,6 @@ declare const CoreErrorCode: {
     readonly LIST_REFS_NOT_SUPPORTED: 10061;
     readonly REMOVE_REF_REQUIRES_CHAIN: 10070;
     readonly REMOVE_REF_NOT_SUPPORTED: 10071;
-    readonly META_TX_REQUIRES_ENCRYPTION: 10080;
-    readonly PREPARE_UPLOAD_NO_PROVIDERS: 10081;
     readonly MANIFEST_INVALID_STRUCTURE: 10090;
     readonly MANIFEST_CHUNK_COUNT_MISMATCH: 10091;
     readonly MANIFEST_NOT_CONTIGUOUS: 10092;
@@ -2400,7 +2214,6 @@ declare const CoreErrorCode: {
     readonly CHUNK_OVERFLOWS_TOTAL_SIZE: 10094;
     readonly REASSEMBLY_SIZE_MISMATCH: 10095;
     readonly NOT_INITIALIZED: 10100;
-    readonly META_TX_UNKNOWN_STEP: 10200;
     readonly UNKNOWN_ERROR: 10999;
 };
 type CoreErrorCode = (typeof CoreErrorCode)[keyof typeof CoreErrorCode];
@@ -2415,4 +2228,4 @@ declare class StorePartialError extends DStorageError {
 }
 declare function isStorePartialError(err: unknown): err is StorePartialError;
 
-export { ARWEAVE_LOCAL, 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, type DStorageContext, DStorageError, type EncryptionAdapter, EncryptionErrorCode, type EncryptionScheme, type FromKdfParamsConfig, 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, MetaTx, type MetaTxConfig, type MetaTxProgress, type MetaTxReceipt, type MetaTxStepId, type MetaTxStepState, type MetaTxStepStatus, MnemonicEncryptionAdapter, 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 UploadCrypto, type WalletInfo, type WrappedDekResult, type XChaChaPayload, XChaChaScheme, arlocalGateway, base64urlToBytes, buildKeyEnvelope, bytesToBase64url, chunkAad, computeBlake3, computeBlake3Hex, decryptStorageIdXChaCha, decryptXChaCha, defaultChainToken, deriveKek, deriveOwnerSecret, deriveSymmetricKeyFromSeed, deserializeXChaChaPayload, encryptStorageIdXChaCha, encryptXChaCha, findWrapper, generateDek, generatePqsPassword, hexToBytes, isDStorageError, isManifest, isStorePartialError, mlkemGenerateKeypair, mlkemGenerateKeypairFromSeed, mlkemUnwrapDek, mlkemWrapDek, parseKeyEnvelope, serializeKeyEnvelope, serializeXChaChaPayload, unwrapKey, wrapKey };
+export { ARWEAVE_LOCAL, 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, 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, MnemonicEncryptionAdapter, 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 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, wrapKey };