arkiv-images 0.1.0

package/AGENTS.md

@@ -0,0 +1,29 @@
+# Integrating arkiv-images
+
+This is the consumer guide; it is included in npm. Read [README.md](README.md) explicitly for the public API, runnable examples, dependency versions, limits, data model and recovery behavior. This guide does not replace it.
+
+## Ask the developer
+
+- Local inspection, existing-image retrieval, or a new public upload? The first needs no network; retrieval needs the image key and explicit testnet; only writes need a signing wallet and test funds.
+- Which testnet/RPC and Entity Expiration in blocks? Use the actually tested combination in README. Never infer production or mainnet compatibility.
+- Are the **original image bytes, filename and metadata** safe to make public? The tool keeps EXIF/GPS unchanged. If privacy is required, stop: encryption is a different tool, and this one does not solve it.
+- For retrieval, ask for an image key and optionally an independently trusted SHA-256. Do not confuse an image entity key with its file-manifest key.
+- For browser writes, ask the developer to connect their own MetaMask/Rabby account and confirm transactions. For Node, ask them to configure their key locally as described in README; never request a private key in chat. Provider access keys come from the provider/Hub links there.
+
+Local `inspectImage` and `planImage` can be integrated immediately while legitimate network/product questions remain open.
+
+## Preserve these invariants
+
+- Import only the public package API; do not copy its storage, image validation or chunking implementation into the app. Use the released npm version in consumers.
+- Binary image bytes belong in the payload; queryable metadata belongs in typed attributes. The package schema and dependency own these decisions. Do not search inside payloads or substitute SQL for SDK query syntax.
+- Keep the testnet checks, size limits and integrity validation. No partial image, no silent lossy conversion, no pretending expiration erases history.
+- A browser consumer must fully decode before upload and after retrieval, then render only the allowed raster MIME as an image. Manage/revoke Blob URLs. Filenames are text, not markup.
+- Confirm completion only after `storeImage` resolves. Preserve confirmed hashes/manifest keys on failure, serialize writes, and do not automatically retry ambiguous writes. Check wallet account/network before every signature, including the final root write.
+- Keep secrets out of source, logs, packages and browser bundles. Do not display raw SDK/provider errors. No server signer for the sample.
+- No independent mutation/extension/ownership transfer of the parts. Root existence alone does not prove its referenced chunks are still available.
+
+## Verify the integration
+
+Follow the README in a new consumer. Import the public TypeScript types, run the exact local example, then test the requested network flow. Compare original and retrieved bytes and digest. Test unsupported/oversized files, wrong network, absent key, rejected writes, missing/corrupt chunks and browser decode errors. Distinguish mocked RPC, packed candidate and installed npm release. For UI, render small/medium/large widths and inspect loading, empty and error states. Record versions, network, actual results and unverified items.
+
+Source maintainers: keep this guide, CLAUDE.md and verification in the publication allowlist. Sample instructions and agent guide live in `sample/`, linked from README; explicitly give them to consumer agents. No new skills, MCP, generator, encryption or media-management features belong to this tool.

package/CLAUDE.md

@@ -0,0 +1 @@
+Read [AGENTS.md](AGENTS.md) for the consumer integration guide and invariants.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santiago Trujillo Zuluaga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# arkiv-images
+
+Store a public PNG or JPEG as queryable Arkiv entities, then retrieve and display its original bytes. Small images use one entity. Larger images use the existing `arkiv-chunking` package: a discoverable image entity points to a file manifest, which links the ordered chunks. Retrieval checks size, format, dimensions and SHA-256 before returning the bytes.
+
+**These packages are intended for testnet use.**
+
+Version **0.1.0**. See [verification](docs/verification.md) for release evidence and [the npm registry](https://www.npmjs.com/package/arkiv-images/v/0.1.0) for availability. A locally packed artifact is not a published release.
+
+## Install and inspect an image
+
+ESM, Node **22.10+** with Web Crypto, or a current browser on HTTPS/localhost. The tested dependency combination is SDK **0.8.0**, viem **2.56.3**, `arkiv-chunking` **0.1.0**, Node **22.22.3**. SDK 0.7 and older are incompatible. Other SDK versions, runtimes and networks are not claimed tested; see the evidence matrix below.
+
+```sh
+mkdir image-consumer
+cd image-consumer
+npm init -y
+npm pkg set type=module
+npm install --save-exact arkiv-images@0.1.0 @arkiv-network/sdk@0.8.0 viem@2.56.3
+```
+
+Create `inspect.mjs`:
+
+```js
+import { inspectImage, planImage } from 'arkiv-images';
+
+// Synthetic 1x1 PNG, no personal image or credentials.
+const bytes = new Uint8Array(Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGP4V+L2HwAG5AK4X5zdSAAAAABJRU5ErkJggg==', 'base64'));
+console.log(inspectImage(bytes));
+console.log(planImage(bytes.length));
+```
+
+```sh
+node inspect.mjs
+```
+
+Expected: PNG, width `1`, height `1`, byte length `70`; mode `inline`, `entityCount: 1`, `transactionCount: 1`. This inspection is local: no wallet, RPC, funds or access key. Base64 is used only to embed this tiny example; the package stores binary bytes without base64 overhead.
+
+## Store and retrieve on Tiramisu
+
+Use **Tiramisu testnet, chain ID 7738577**, exported by `@arkiv-network/sdk/chains`. [Network connection details](https://hub.arkiv.network/networks), [test GLM faucet](https://hub.arkiv.network/faucet) and [access keys](https://hub.arkiv.network/api-keys) are provided by the Hub. The RPC used below allows anonymous reads; write access and quotas depend on the provider. A provider access key does not replace a signing wallet. Never put an administrative provider key in a browser.
+
+The [sample](https://github.com/SantiagoDevRel/arkiv-images/blob/feat/image-storage/sample/README.md) uses **MetaMask or Rabby** to sign with the visitor's own wallet. No shared server signer or private key is needed. For a Node integration, configure a dedicated test wallet key **locally**, outside the checkout. Do not send private keys to an agent or put them in chat.
+
+In the consumer above, save `roundtrip.mjs`:
+
+```js
+import { readFile } from 'node:fs/promises';
+import { createPublicClient, createWalletClient } from '@arkiv-network/sdk';
+import { tiramisu } from '@arkiv-network/sdk/chains';
+import { http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { inspectImage, planImage, storeImage, retrieveImage } from 'arkiv-images';
+
+if (!process.env.ARKIV_PRIVATE_KEY) throw new Error('Configure ARKIV_PRIVATE_KEY locally.');
+const bytes = new Uint8Array(await readFile('example.png'));
+console.log(inspectImage(bytes), planImage(bytes.length));
+const transport = () => http(process.env.ARKIV_RPC_URL ?? tiramisu.rpcUrls.default.http[0], {
+  retryCount: 0, timeout: 30_000, fetchOptions: { cache: 'no-store' },
+});
+const publicClient = createPublicClient({ chain: tiramisu, transport: transport() });
+const walletClient = createWalletClient({ chain: tiramisu, transport: transport(),
+  account: privateKeyToAccount(process.env.ARKIV_PRIVATE_KEY) });
+const saved = await storeImage({ publicClient, walletClient, bytes, filename: 'example.png',
+  expirationBlocks: 43_200 });
+const image = await retrieveImage({ publicClient, imageKey: saved.imageKey,
+  expectedSha256: saved.sha256 });
+const identical = image.bytes.length === bytes.length && bytes.every((b,i) => b === image.bytes[i]);
+if (!identical) throw new Error('Image bytes differ');
+console.log({ imageKey: saved.imageKey, sha256: image.sha256, mode: image.mode,
+  bytes: image.bytes.length, identical, expiresAt: String(image.expiresAt) });
+```
+
+Place a **non-sensitive PNG** at `example.png`. Then run:
+
+```sh
+node --env-file=/absolute/path/to/your-local-secret.env roundtrip.mjs
+```
+
+The local secret file uses ordinary `NAME=value` entries for `ARKIV_PRIVATE_KEY` and optionally `ARKIV_RPC_URL`. Supply your own values; no secrets are included here. If those variables already exist in the process environment, use `node roundtrip.mjs`.
+
+Expected: a new 32-byte `imageKey`, SHA-256, the selected storage mode, byte count, `identical: true` and a queried expiration block. Writes spend **test GLM**. Keep the returned image key for retrieval after restarting. A read needs only `publicClient` and `imageKey`, not the wallet. To display the recovered bytes in a browser:
+
+```js
+const image = await retrieveImage({ publicClient, imageKey });
+const blob = new Blob([new Uint8Array(image.bytes)], { type: image.contentType });
+const bitmap = await createImageBitmap(blob); // full browser decode; may reject corrupt pixels
+bitmap.close();
+const url = URL.createObjectURL(blob);
+document.querySelector('img').src = url;
+// When replacing the image or unmounting: URL.revokeObjectURL(url).
+```
+
+## Read an existing image without a wallet
+
+In the same clean consumer, save `read.mjs`:
+
+```js
+import { writeFile } from 'node:fs/promises';
+import { createPublicClient } from '@arkiv-network/sdk';
+import { tiramisu } from '@arkiv-network/sdk/chains';
+import { http } from 'viem';
+import { retrieveImage } from 'arkiv-images';
+
+const publicClient = createPublicClient({ chain: tiramisu,
+  transport: http(tiramisu.rpcUrls.default.http[0], { retryCount: 0 }) });
+const image = await retrieveImage({ publicClient, imageKey: process.argv[2] });
+// Use a fixed local output path, not the untrusted stored filename.
+const output = image.contentType === 'image/png' ? 'recovered.png' : 'recovered.jpg';
+await writeFile(output, image.bytes, { flag: 'wx' });
+console.log({ output, bytes: image.byteLength, sha256: image.sha256 });
+```
+
+Run `node read.mjs YOUR_IMAGE_ENTITY_KEY` with a key returned by a completed upload. Expected: a recovered image file and its byte count/digest. No signing wallet, funds or private key are needed. The output uses exclusive creation: if it already exists, choose another filename rather than silently overwriting it. Entities in the verification evidence can expire, so they are evidence, not permanent fixtures.
+
+## Data model and queries
+
+| Location | Contents |
+|---|---|
+| Image entity attributes | `type: str('arkiv-images/v1')`, `mode: str('inline'|'chunked')`, `mime: str(...)`, `filename: str(...)`, `sha256: bytes32(...)`, `size/width/height: u64(...)`; chunked mode adds `manifest: key(...)` |
+| Inline payload | Original PNG/JPEG binary bytes; content type `image/png` or `image/jpeg` |
+| Chunked image payload | Empty; the `manifest` attribute links to the file, rather than pretending the image is contained in this one payload |
+| File manifest and chunks | The versioned `arkiv-chunking@0.1.0` format; the dependency owns splitting, sequencing, snapshot pagination, completion and integrity checks |
+
+The image entity is created read-only. Filenames are public, indexed attributes; the package does not infer author/version from the image. Queries operate on attributes, never image pixels or payload contents. To discover PNG images:
+
+```js
+import { str } from '@arkiv-network/sdk/attr';
+import { eq } from '@arkiv-network/sdk/query';
+import { IMAGE_TYPE, retrieveImage } from 'arkiv-images';
+
+const query = publicClient.select({ key: true })
+  .where(eq('type', str(IMAGE_TYPE)), eq('mime', str('image/png')))
+  .limit(200);
+for await (const entity of query) {
+  // Narrow by owner or another indexed attribute for a real application.
+  // A single image's retrieval does not enumerate the global catalogue.
+  const image = await retrieveImage({ publicClient, imageKey: entity.key });
+  console.log(entity.key, image.byteLength);
+}
+```
+
+SDK types matter: `u64(2)` is different from `i32(2)`. The actual query expression for this example is `type = str('arkiv-images/v1') AND mime = str('image/png')`, not SQL `SELECT *`.
+
+## Public API
+
+All functions and TypeScript types are exported from `arkiv-images`. Do not import internal build paths.
+
+| Export | Contract |
+|---|---|
+| `inspectImage(bytes, expectedContentType?)` | Returns `ImageInfo`: detected MIME, width, height, byteLength. Validates size, signature and basic container structure; not a full pixel decoder. No network. |
+| `planImage(byteLength)` | Returns `ImagePlan`: inline/chunked mode, bytes, chunk/entity/transaction counts. No network. |
+| `storeImage(options)` | Resolves `StoredImage` after observed confirmations: imageKey, optional manifestKey, digest, dimensions, size, mode, transactionHashes. Required clients, bytes, filename, expirationBlocks; optional contentType/onProgress. |
+| `retrieveImage(options)` | Resolves `RetrievedImage`: original bytes, filename, MIME, dimensions, digest, mode, queried expiresAt. Required publicClient/imageKey; optional expectedSha256/onProgress. Never returns a partial image. |
+| `ImageStorageError`, `ChunkingError` | Typed error codes. Upload errors preserve available manifestKey and confirmed transactionHashes. Raw `cause` is for local diagnostics and may contain provider secrets: never render or log it in the UI. |
+| Types | `ImageInfo`, `ImagePlan`, `StoreImageOptions`, `StoredImage`, `RetrieveImageOptions`, `RetrievedImage`, `ImageContentType`, `ImageErrorCode`, `Progress` |
+| Constants | `VERSION`, `IMAGE_TYPE`, `INLINE_MAX_BYTES`, `MAX_IMAGE_BYTES`, `MAX_IMAGE_PIXELS` |
+
+`onProgress` is the chunk dependency's observational callback: phase `manifest`, `chunks` or `finalize`, completed/total and optional manifestKey. Its total counts **file chunks**, not the final image entity transaction. Inline writes do not emit chunk progress. Only a resolved `storeImage` means the whole upload finished; callback exceptions cannot change a confirmed upload into a failure.
+
+## Limits, visibility and failure semantics
+
+| Policy | Value |
+|---|---|
+| Formats | Static PNG; baseline/progressive JPEG. No SVG, GIF, APNG, WebP, HEIC, PDF or video |
+| Maximum file | **26,214,400 bytes (25 MiB)**, measured before upload; in memory, no streaming |
+| Maximum dimensions | Positive width/height, product at most **40,000,000 pixels** |
+| Inline image | **1–120,000 bytes**, one entity and one transaction |
+| Chunked image | **120,001–26,214,400 bytes**, 100,000-byte chunks; N+2 entities, N+3 confirmed transactions |
+| At 120,001 bytes | 2 chunks + manifest + image entity: 4 entities, 5 transactions |
+| At 1,000,000 bytes | 10 chunks + manifest + image entity: 12 entities, 13 transactions |
+| At 25 MiB | 263 chunks, 265 entities, 266 transactions; this is a policy ceiling, not a claim that uploading this size is quick or economical |
+| Filename | Basename only, 1–128 UTF-8 bytes (SDK `str` attribute limit), no path separators or control characters |
+| Expiration | Explicit whole blocks: `max(64, transactionCount + 32)` through 15,768,000 |
+
+The inline threshold leaves room for attributes and transaction framing. The commonly cited 131,072-byte payload ceiling is **not** an image budget: the complete transaction also has a size limit. [Verification](docs/verification.md) records actual encoded sizes and which boundaries were submitted on Tiramisu. JPEG/PNG are already compressed image formats; converting to PDF or base64 does not remove the storage constraint. A photo's size varies with dimensions, detail and encoding; the sample measures the selected file rather than guessing from megapixels.
+
+**No encryption, metadata stripping, resizing or recompression.** The tool preserves the exact original bytes, including EXIF/GPS, embedded thumbnails and names. Everyone with read access to the public network can retrieve them. The sample requires acknowledgement before uploading. Use synthetic/non-sensitive images. Expiration removes entities from current queries; it does **not** erase historical bytes or copies. This tool offers no read authorization and does not claim confidentiality.
+
+The package performs bounded container checks, not a complete PNG CRC/JPEG entropy decode, antivirus scan or content moderation. A file can pass header checks and still fail full decoding. JPEGs must end at their end-of-image marker; files with trailing padding are rejected even if some decoders accept them. Export such files as a standard JPEG before uploading. The sample calls `createImageBitmap` both before writes and after retrieval. Consumers rendering images must also handle decode failures. Never serve uploaded bytes as HTML or SVG, and never trust a filename as markup.
+
+Chunking is required only for images above the inline threshold and is **reused, not reimplemented**. The dependency is installed with the package. An inline read uses one entity query plus the chain check. A chunked read first loads the image entity, then the file manifest and every required chunk page; it is one JavaScript API call, **not one RPC query**. File pages share the manifest's snapshot block. The initial image query and file query are separate snapshots. A trusted `expectedSha256` pins bytes independently of mutable manifests; a digest proves integrity, not the publisher's identity.
+
+Parts receive relative expiration at their own creation. The manifest is older than the final image entity and can expire first. The root may therefore still exist when the file can no longer be retrieved; retrieval fails clearly. `RetrievedImage.expiresAt` is the earlier queried root/manifest expiration, not a fixed-time availability promise. Do not independently extend, transfer or change parts; these are not supported workflows.
+
+No multi-transaction atomicity, automatic write retries/resume, deduplication, deletion or rollback. If the final image transaction fails, confirmed file entities remain: preserve `manifestKey` and receipts, inspect them, then decide whether to start a new upload. A timeout can follow a successful transaction; the returned list includes only confirmations observed by this call. Serialize writes from the same account. In browser integrations recheck account/network before **every** signing request; the sample provides the implementation.
+
+## Troubleshooting
+
+| Symptom | Resolution |
+|---|---|
+| `INVALID_IMAGE` / browser decode error | Use a valid static PNG or baseline/progressive JPEG within the pixel limit. Changing an extension does not convert a file. |
+| `TOO_LARGE` | Choose a smaller file. The tool does not silently resize it. |
+| `INVALID_INPUT` | Check 32-byte key/hash, filename rules and whole-block expiration. |
+| `NETWORK_MISMATCH` | Configure matching explicit testnet clients; the sample supports only Tiramisu. Check RPC `eth_chainId` too. |
+| Wallet missing, rejected or changed | Enable/connect MetaMask or Rabby; resolve pending requests. Reconnect after changing account and inspect confirmed writes before retrying. |
+| Not enough GLM | Obtain test GLM for the actual signing account on Tiramisu; plan the number of transaction approvals before uploading a large photo. |
+| RPC 401/403/429, `READ_FAILED` | Check your network-specific provider access key/quota/connection. Never retry ambiguous writes automatically. |
+| `NOT_FOUND` | Verify the **image** key and network; entity may have expired. A chunk manifest key is a different type. |
+| `INCOMPLETE_UPLOAD`, `MISSING_CHUNK` | Inspect upload receipts and expiration. Partial images are not returned. |
+| `INVALID_ENTITY`, `INVALID_MANIFEST`, `INVALID_CHUNK`, `HASH_MISMATCH` | Treat the result as invalid; do not bypass checks. A manifest may have changed or content may be damaged. |
+| npm E404 | Check the publication status in verification; do not call a local tarball published. |
+| CommonJS import failure | Use ESM `import`; there is no CommonJS export. |
+
+## Sample, agent guides and development
+
+- [Sample README](https://github.com/SantiagoDevRel/arkiv-images/blob/feat/image-storage/sample/README.md): source checkout, localhost commands and visitor-wallet flow.
+- [Consumer AGENTS.md](AGENTS.md) and [sample AGENTS.md](https://github.com/SantiagoDevRel/arkiv-images/blob/feat/image-storage/sample/AGENTS.md). Give these guides to your agent explicitly. It will not necessarily read files under `node_modules` automatically. Each CLAUDE.md points to the corresponding AGENTS.md.
+- [Verification](docs/verification.md): exact runtimes, dependency versions, simulated vs real checks, publication and unresolved gates.
+
+```sh
+git clone --branch feat/image-storage https://github.com/SantiagoDevRel/arkiv-images.git
+cd arkiv-images
+npm ci
+npm test
+npm run typecheck
+npm pack --pack-destination /absolute/path/to/output
+```
+
+For an unpublished candidate only, replace the npm package argument in a clean consumer with the absolute `.tgz` path. This tests the packed artifact, not registry publication. There are no runtime aliases to sibling repositories.
+
+Browser regression checks use Playwright with a locally installed Chrome. First start the sample dev server in another terminal, then run `npm run test:browser` from the package root. They exercise the actual SDK/package with a controlled RPC and injected wallet, not live funds. Screenshots and results default to `~/Downloads/arkiv-image-storage-98/browser`; set `ARTIFACTS_DIR` to another output directory or `SAMPLE_URL` to another localhost port. These checks are separate from `npm test`.
+
+Provenance: image workflow and PNG/JPEG/25 MiB policy from [Arkiv-Network/usecases-imagedb](https://github.com/Arkiv-Network/usecases-imagedb); public-byte/metadata cautions and transaction budget from the existing Arkiv Cookbook; chunk implementation is the separately published `arkiv-chunking` dependency. The old service's quotas, shared signer and RPC protocol are not added to this package. Test RPC harness and sample token treatments are adapted from arkiv-chunking, with Arkiv UI's documented open font fallbacks.

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+import { type ChunkingPublicClient, type ChunkingWalletClient, type Progress } from 'arkiv-chunking';
+import type { Hex } from 'viem';
+export declare const VERSION = "0.1.0";
+export declare const IMAGE_TYPE = "arkiv-images/v1";
+export declare const INLINE_MAX_BYTES = 120000;
+export declare const MAX_IMAGE_BYTES: number;
+export declare const MAX_IMAGE_PIXELS = 40000000;
+export type ImageContentType = 'image/png' | 'image/jpeg';
+export type ImageErrorCode = 'INVALID_IMAGE' | 'TOO_LARGE' | 'INVALID_INPUT' | 'NETWORK_MISMATCH' | 'NOT_FOUND' | 'INVALID_ENTITY' | 'HASH_MISMATCH' | 'UPLOAD_FAILED' | 'READ_FAILED';
+export declare class ImageStorageError extends Error {
+    readonly code: ImageErrorCode;
+    readonly manifestKey?: Hex;
+    readonly transactionHashes: readonly Hex[];
+    constructor(code: ImageErrorCode, message: string, options?: {
+        cause?: unknown;
+        manifestKey?: Hex;
+        transactionHashes?: readonly Hex[];
+    });
+}
+export { ChunkingError } from 'arkiv-chunking';
+export type { Progress } from 'arkiv-chunking';
+export interface ImageInfo {
+    contentType: ImageContentType;
+    width: number;
+    height: number;
+    byteLength: number;
+}
+export interface ImagePlan {
+    mode: 'inline' | 'chunked';
+    bytes: number;
+    chunkCount: number;
+    entityCount: number;
+    transactionCount: number;
+}
+export interface StoreImageOptions {
+    publicClient: ChunkingPublicClient;
+    walletClient: ChunkingWalletClient;
+    bytes: Uint8Array;
+    filename: string;
+    contentType?: ImageContentType;
+    expirationBlocks: number;
+    onProgress?: (progress: Progress) => void | Promise<void>;
+}
+export interface StoredImage extends ImageInfo {
+    imageKey: Hex;
+    manifestKey?: Hex;
+    sha256: Hex;
+    mode: 'inline' | 'chunked';
+    transactionHashes: Hex[];
+}
+export interface RetrieveImageOptions {
+    publicClient: ChunkingPublicClient;
+    imageKey: Hex;
+    expectedSha256?: Hex;
+    onProgress?: StoreImageOptions['onProgress'];
+}
+export interface RetrievedImage extends ImageInfo {
+    bytes: Uint8Array;
+    filename: string;
+    sha256: Hex;
+    mode: 'inline' | 'chunked';
+    expiresAt: bigint;
+}
+/** Validate size, signature, container dimensions. This is not a full pixel decoder or malware scanner. */
+export declare function inspectImage(bytes: Uint8Array, expectedContentType?: ImageContentType): ImageInfo;
+export declare function planImage(byteLength: number): ImagePlan;
+/** Preserve original file bytes. All bytes, metadata and wallet addresses are public. Never retries writes. */
+export declare function storeImage(options: StoreImageOptions): Promise<StoredImage>;
+/** One SDK call for an inline image; chunked images additionally load and verify the referenced file. */
+export declare function retrieveImage({ publicClient, imageKey, expectedSha256, onProgress }: RetrieveImageOptions): Promise<RetrievedImage>;

package/dist/index.js

@@ -0,0 +1,197 @@
+import { ExpirationTime } from '@arkiv-network/sdk';
+import { bytes32, key, str, u64 } from '@arkiv-network/sdk/attr';
+import { eq } from '@arkiv-network/sdk/query';
+import { uploadFile, downloadFile, hashFile, ChunkingError, DEFAULT_CHUNK_BYTES } from 'arkiv-chunking';
+export const VERSION = '0.1.0';
+export const IMAGE_TYPE = 'arkiv-images/v1';
+export const INLINE_MAX_BYTES = 120_000;
+export const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
+export const MAX_IMAGE_PIXELS = 40_000_000;
+export class ImageStorageError extends Error {
+    code;
+    manifestKey;
+    transactionHashes;
+    constructor(code, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = 'ImageStorageError';
+        this.code = code;
+        this.manifestKey = options.manifestKey;
+        this.transactionHashes = [...(options.transactionHashes ?? [])];
+    }
+}
+export { ChunkingError } from 'arkiv-chunking';
+function fail(code, message) { throw new ImageStorageError(code, message); }
+const hex32 = (v) => typeof v === 'string' && /^0x[\da-f]{64}$/i.test(v);
+/** Validate size, signature, container dimensions. This is not a full pixel decoder or malware scanner. */
+export function inspectImage(bytes, expectedContentType) {
+    if (!(bytes instanceof Uint8Array))
+        fail('INVALID_INPUT', 'Provide image bytes as Uint8Array.');
+    if (bytes.length > MAX_IMAGE_BYTES)
+        fail('TOO_LARGE', `Images must be at most ${MAX_IMAGE_BYTES} bytes.`);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let contentType, width = 0, height = 0;
+    if (bytes.length >= 33 && [137, 80, 78, 71, 13, 10, 26, 10].every((v, i) => bytes[i] === v)) {
+        contentType = 'image/png';
+        if (view.getUint32(8) !== 13 || view.getUint32(12) !== 0x49484452)
+            fail('INVALID_IMAGE', 'PNG must start with an IHDR chunk.');
+        width = view.getUint32(16);
+        height = view.getUint32(20);
+        let offset = 8, hasData = false, ended = false;
+        while (offset + 12 <= bytes.length) {
+            const length = view.getUint32(offset), type = view.getUint32(offset + 4);
+            if (length > bytes.length - offset - 12)
+                fail('INVALID_IMAGE', 'Truncated PNG chunk.');
+            if (type === 0x6163544c)
+                fail('INVALID_IMAGE', 'Animated PNG is not supported.');
+            if (type === 0x49444154)
+                hasData = true;
+            offset += length + 12;
+            if (type === 0x49454e44) {
+                ended = length === 0 && offset === bytes.length;
+                break;
+            }
+        }
+        if (!hasData || !ended)
+            fail('INVALID_IMAGE', 'PNG is missing image data or its final chunk.');
+    }
+    else if (bytes.length >= 4 && bytes[0] === 255 && bytes[1] === 216 && bytes.at(-2) === 255 && bytes.at(-1) === 217) {
+        contentType = 'image/jpeg';
+        let offset = 2;
+        while (offset + 4 <= bytes.length) {
+            if (bytes[offset++] !== 255)
+                fail('INVALID_IMAGE', 'Invalid JPEG marker.');
+            while (bytes[offset] === 255)
+                offset++;
+            const marker = bytes[offset++];
+            if (marker === undefined || marker === 0xda || marker === 0xd9)
+                break;
+            if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7))
+                continue;
+            if (offset + 2 > bytes.length)
+                fail('INVALID_IMAGE', 'Truncated JPEG.');
+            const length = view.getUint16(offset);
+            if (length < 2 || offset + length > bytes.length)
+                fail('INVALID_IMAGE', 'Truncated JPEG segment.');
+            if (marker === 0xc0 || marker === 0xc2) {
+                if (length < 8)
+                    fail('INVALID_IMAGE', 'Invalid JPEG dimensions.');
+                height = view.getUint16(offset + 3);
+                width = view.getUint16(offset + 5);
+            }
+            offset += length;
+        }
+    }
+    else {
+        return fail('INVALID_IMAGE', 'Use a static PNG or baseline/progressive JPEG. Other formats are not supported.');
+    }
+    if (!width || !height || width * height > MAX_IMAGE_PIXELS)
+        fail('INVALID_IMAGE', `Image dimensions must be positive and at most ${MAX_IMAGE_PIXELS} pixels.`);
+    if (expectedContentType !== undefined && expectedContentType !== contentType)
+        fail('INVALID_IMAGE', 'Declared content type does not match the image bytes.');
+    return { contentType, width, height, byteLength: bytes.length };
+}
+export function planImage(byteLength) {
+    if (!Number.isSafeInteger(byteLength) || byteLength < 1)
+        fail('INVALID_INPUT', 'Image byte length must be a positive integer.');
+    if (byteLength > MAX_IMAGE_BYTES)
+        fail('TOO_LARGE', `Images must be at most ${MAX_IMAGE_BYTES} bytes.`);
+    if (byteLength <= INLINE_MAX_BYTES)
+        return { mode: 'inline', bytes: byteLength, chunkCount: 0, entityCount: 1, transactionCount: 1 };
+    const chunkCount = Math.ceil(byteLength / DEFAULT_CHUNK_BYTES);
+    return { mode: 'chunked', bytes: byteLength, chunkCount, entityCount: chunkCount + 2, transactionCount: chunkCount + 3 };
+}
+function filenameValid(filename) {
+    if (typeof filename !== 'string' || !filename || new TextEncoder().encode(filename).length > 128 || /[\x00-\x1f\x7f/\\]/.test(filename) || filename === '.' || filename === '..')
+        fail('INVALID_INPUT', 'Use a basename of 1–128 UTF-8 bytes, without control characters.');
+}
+async function checkNetwork(client, wallet) {
+    if (!client.chain?.testnet || await client.getChainId() !== client.chain.id)
+        fail('NETWORK_MISMATCH', 'Configure an explicit testnet matching the RPC.');
+    if (wallet && (!wallet.account || !wallet.chain?.testnet || wallet.chain.id !== client.chain.id || Number(await wallet.transport.request({ method: 'eth_chainId' })) !== client.chain.id))
+        fail('NETWORK_MISMATCH', 'The wallet and RPC must use the same explicit testnet.');
+}
+/** Preserve original file bytes. All bytes, metadata and wallet addresses are public. Never retries writes. */
+export async function storeImage(options) {
+    const { publicClient, walletClient, filename, expirationBlocks, onProgress } = options;
+    filenameValid(filename);
+    const info = inspectImage(options.bytes, options.contentType), plan = planImage(info.byteLength);
+    if (!Number.isSafeInteger(expirationBlocks) || expirationBlocks < Math.max(64, plan.transactionCount + 32) || expirationBlocks > 15_768_000)
+        fail('INVALID_INPUT', 'Choose a whole-block expiration from max(64, transactionCount + 32) to 15768000.');
+    const bytes = new Uint8Array(options.bytes);
+    let manifestKey;
+    const transactionHashes = [];
+    try {
+        await checkNetwork(publicClient, walletClient);
+        const sha256 = await hashFile(bytes);
+        if (plan.mode === 'chunked') {
+            const stored = await uploadFile({ publicClient, walletClient, bytes, filename, contentType: info.contentType, expirationBlocks, onProgress });
+            manifestKey = stored.manifestKey;
+            transactionHashes.push(...stored.transactionHashes);
+        }
+        await checkNetwork(publicClient, walletClient);
+        const attributes = { type: str(IMAGE_TYPE), mode: str(plan.mode), mime: str(info.contentType), filename: str(filename), sha256: bytes32(sha256), size: u64(bytes.length), width: u64(info.width), height: u64(info.height), ...(manifestKey ? { manifest: key(manifestKey) } : {}) };
+        const stored = await walletClient.createEntity({ attributes, payload: manifestKey ? new Uint8Array() : bytes, contentType: manifestKey ? 'application/octet-stream' : info.contentType, expires: ExpirationTime.fromBlocks(expirationBlocks), flags: { readonly: true } });
+        transactionHashes.push(stored.txHash);
+        return { ...info, imageKey: stored.entityKey, manifestKey, mode: plan.mode, sha256, transactionHashes };
+    }
+    catch (cause) {
+        if (cause instanceof ChunkingError) {
+            manifestKey = cause.manifestKey ?? manifestKey;
+            transactionHashes.push(...cause.transactionHashes);
+        }
+        if (cause instanceof ImageStorageError && !transactionHashes.length)
+            throw cause;
+        throw new ImageStorageError('UPLOAD_FAILED', 'Upload did not complete. Inspect the wallet and available transaction receipts before retrying; any previously written entities remain.', { cause, manifestKey, transactionHashes });
+    }
+}
+function attr(attributes, name, type) {
+    const a = attributes[name];
+    if (!a || typeof a !== 'object' || !('type' in a) || a.type !== type || !('value' in a))
+        return fail('INVALID_ENTITY', `Missing or invalid ${name} attribute.`);
+    return a.value;
+}
+/** One SDK call for an inline image; chunked images additionally load and verify the referenced file. */
+export async function retrieveImage({ publicClient, imageKey, expectedSha256, onProgress }) {
+    if (!hex32(imageKey) || (expectedSha256 !== undefined && !hex32(expectedSha256)))
+        fail('INVALID_INPUT', 'Use a 32-byte image key and, optionally, a 32-byte SHA-256.');
+    try {
+        await checkNetwork(publicClient);
+        const page = await publicClient.select({ payload: true, expiresAt: true, attributes: { type: true, mode: true, mime: true, filename: true, sha256: true, size: true, width: true, height: true, manifest: true } }).where(eq('$key', key(imageKey))).limit(1).fetch();
+        const entity = page.entities[0];
+        if (!entity)
+            fail('NOT_FOUND', 'Image entity not found. Check key, network and Entity Expiration.');
+        const a = entity.attributes;
+        if (attr(a, 'type', 'str') !== IMAGE_TYPE)
+            fail('INVALID_ENTITY', 'This is not an arkiv-images v1 entity.');
+        const mode = attr(a, 'mode', 'str'), mime = attr(a, 'mime', 'str'), filename = attr(a, 'filename', 'str'), digest = attr(a, 'sha256', 'bytes32'), size = attr(a, 'size', 'u64');
+        if ((mode !== 'inline' && mode !== 'chunked') || (mime !== 'image/png' && mime !== 'image/jpeg') || !hex32(digest) || typeof size !== 'bigint' || size < 1n || size > BigInt(MAX_IMAGE_BYTES))
+            fail('INVALID_ENTITY', 'Invalid image storage metadata.');
+        filenameValid(filename);
+        if (expectedSha256 && digest.toLowerCase() !== expectedSha256.toLowerCase())
+            fail('HASH_MISMATCH', 'Image digest differs from the trusted SHA-256.');
+        let bytes = entity.payload, expiresAt = entity.expiresAt;
+        if (mode === 'chunked') {
+            const manifestKey = attr(a, 'manifest', 'key');
+            if (!hex32(manifestKey))
+                fail('INVALID_ENTITY', 'Invalid chunk manifest reference.');
+            const result = await downloadFile({ publicClient, manifestKey, expectedSha256: digest, onProgress });
+            bytes = result.bytes;
+            expiresAt = result.expiresAt < expiresAt ? result.expiresAt : expiresAt;
+            if (result.contentType !== mime || result.filename !== filename)
+                fail('INVALID_ENTITY', 'Image and file metadata disagree.');
+        }
+        else if (bytes.length > INLINE_MAX_BYTES)
+            fail('INVALID_ENTITY', 'Inline payload exceeds the image format limit.');
+        const info = inspectImage(bytes, mime);
+        if (BigInt(bytes.length) !== size || BigInt(info.width) !== attr(a, 'width', 'u64') || BigInt(info.height) !== attr(a, 'height', 'u64'))
+            fail('INVALID_ENTITY', 'Image dimensions or size disagree with attributes.');
+        if (await hashFile(bytes) !== digest.toLowerCase())
+            fail('HASH_MISMATCH', 'Recovered image bytes failed SHA-256 verification.');
+        return { ...info, bytes, filename, sha256: digest.toLowerCase(), mode, expiresAt };
+    }
+    catch (cause) {
+        if (cause instanceof ImageStorageError || cause instanceof ChunkingError)
+            throw cause;
+        throw new ImageStorageError('READ_FAILED', 'Image retrieval failed. Check the RPC connection and access policy.', { cause });
+    }
+}

package/docs/testnet-evidence.json

@@ -0,0 +1,111 @@
+{
+  "package": "arkiv-images@0.1.0",
+  "sdk": "0.8.0",
+  "viem": "2.56.3",
+  "chunking": "0.1.0",
+  "node": "v22.22.3",
+  "chainId": 7738577,
+  "account": "0xa618a2736431f24c26f1c8dac9ca00ecc845a1c6",
+  "wallet": "Rabby / Arkiv Wallet",
+  "cases": [
+    {
+      "mode": "inline",
+      "format": "image/png",
+      "bytes": 120000,
+      "imageKey": "0x21a2b016bbcc1c7195401ad1fb93ad857d42956ec6e77ec3f3c63a800ecfc312",
+      "sha256": "0x31c2782dc1ad3ce9a983c9743ed67337125b433dc08e532da315ed58e63203a4",
+      "width": 320,
+      "height": 200,
+      "transactions": [
+        {
+          "hash": "0x5376fd09019268aff4d79399df49ccaf697c4c674d9b29a2b6c6ad438e20ae56",
+          "blockNumber": "197767",
+          "gasUsed": "4843780",
+          "calldataBytes": 122308,
+          "signedBytes": 122418,
+          "status": "success"
+        }
+      ],
+      "browserByteExact": true,
+      "byteExact": true,
+      "expiresAt": "240967"
+    },
+    {
+      "mode": "chunked",
+      "format": "image/png",
+      "bytes": 120001,
+      "imageKey": "0x85fb5d3f3a337e5cbb832c9a15afbcf5b9bb53ae2e8b62fd5fe13c0931543011",
+      "sha256": "0xc99a39198cd5767d1c5443044e09d554cbf6eddea0fb4f3d89c9bee346cfd0e6",
+      "width": 320,
+      "height": 200,
+      "transactions": [
+        {
+          "hash": "0x2f36b48cb3fca6f0d0caffd0e714bfd357b878e891288b4e69e8efc3d7dc0161",
+          "blockNumber": "197844",
+          "gasUsed": "111184",
+          "calldataBytes": 1988,
+          "signedBytes": 2096,
+          "status": "success"
+        },
+        {
+          "hash": "0x9687de326762655033de634206fcd19a1acd5f6de0144d4c4913741f2d92bf82",
+          "blockNumber": "197863",
+          "gasUsed": "4032200",
+          "calldataBytes": 101348,
+          "signedBytes": 101458,
+          "status": "success"
+        },
+        {
+          "hash": "0x570e64c58a45350bff5f4695a8413a1f0a4acc615a0d4fe2ab074f3fe7b075fe",
+          "blockNumber": "197869",
+          "gasUsed": "839840",
+          "calldataBytes": 21380,
+          "signedBytes": 21488,
+          "status": "success"
+        },
+        {
+          "hash": "0x26ffd70c7bb100591faf7270981478c79ec685a75b447c164fbc3235439a25b8",
+          "blockNumber": "197875",
+          "gasUsed": "45016",
+          "calldataBytes": 516,
+          "signedBytes": 624,
+          "status": "success"
+        },
+        {
+          "hash": "0x8ecb8c9be61e67da24b59e87b8c3605a6545bec71033c4710e7ebe9fa0219ae7",
+          "blockNumber": "197880",
+          "gasUsed": "125384",
+          "calldataBytes": 2500,
+          "signedBytes": 2608,
+          "status": "success"
+        }
+      ],
+      "browserByteExact": true,
+      "byteExact": true,
+      "expiresAt": "241044"
+    },
+    {
+      "mode": "inline",
+      "format": "image/jpeg",
+      "bytes": 2977,
+      "imageKey": "0xef4c88b48ca2f3f0f9a8069d339dff3f894d6ab7e707c3f4741d0e3c2937f472",
+      "sha256": "0x6505b34edf4866c89d73791c5b775ee8588ba62ba54249051891d7833d3b1684",
+      "width": 320,
+      "height": 200,
+      "transactions": [
+        {
+          "hash": "0xa2915a6a40e4ecaa7309193d60d48dbcb8cb51e588ff264806b6ebf06b43639e",
+          "blockNumber": "198040",
+          "gasUsed": "167792",
+          "calldataBytes": 5316,
+          "signedBytes": 5424,
+          "status": "success"
+        }
+      ],
+      "browserByteExact": true,
+      "byteExact": true,
+      "expiresAt": "241240"
+    }
+  ],
+  "lastReadVerifiedAt": "2026-09-08T21:55:43.748Z"
+}

package/docs/verification.md

@@ -0,0 +1,50 @@
+# Verification — arkiv-images 0.1.0
+
+Verification date: 2026-09-08. This report distinguishes real Tiramisu transactions, controlled RPC tests and release gates. The npm archive contains the verification snapshot taken before publication; the [source report](https://github.com/SantiagoDevRel/arkiv-images/blob/feat/image-storage/docs/verification.md) records subsequent registry installation evidence.
+
+## Tested combination
+
+| Component | Actually tested |
+|---|---|
+| Node / npm | 22.22.3 / 10.9.8 |
+| TypeScript | 5.9.3; public consumer types compiled with strict NodeNext, without skipLibCheck |
+| Arkiv SDK / viem | 0.8.0 / 2.56.3 |
+| Chunk dependency | arkiv-chunking 0.1.0 from npm registry |
+| Sample tooling | Vite 8.2.2 |
+| Network | Tiramisu, RPC-confirmed chain ID 7738577 |
+| Live signer | Rabby, explicitly authorized Arkiv Wallet; address in the receipt evidence |
+| Browser automation | Playwright 1.62.1, installed Google Chrome; native pixel decoding |
+
+Other SDK versions, networks, Firefox/Safari, mobile wallet browsers and a real MetaMask extension signing flow are not claimed tested. MetaMask-compatible EIP-1193 requests and EIP-6963 discovery were exercised with an injected test wallet; Rabby performed the real writes.
+
+## Real network, original bytes verified
+
+[Machine-readable receipts and image keys](testnet-evidence.json) include SHA-256, creation blocks, queried expiration, gas, calldata and signed transaction sizes. `node scripts/verify-network.mjs` reads Tiramisu again, compares the recovered bytes with the synthetic source fixtures, and checks all receipts, signer, target, zero native-token value and chain. It performs no writes and will fail when the temporary entities expire.
+
+| Synthetic image | Flow | Confirmed transactions | Largest signed transaction |
+|---|---|---|---|
+| PNG, 120,000 bytes, 320 × 200 | Inline write → query → render → byte equality | 1 | 122,418 bytes |
+| PNG, 120,001 bytes, 320 × 200 | Manifest + 2 chunks + finalize + image entity → reconstruction → render → byte equality | 5 | 101,458 bytes |
+| JPEG, 2,977 bytes, 320 × 200 | Inline write → query → render → byte equality | 1 | 5,424 bytes |
+
+An independent Node reader verified the same original bytes, digests and transaction receipts. Real RPC tests also confirmed missing image (`NOT_FOUND`) and configured-network mismatch (`NETWORK_MISMATCH`). Test GLM was spent only on Tiramisu. No personal photo or private credential is part of the fixtures or published files.
+
+## Controlled regression checks
+
+`npm test`: 13 passing tests with the actual SDK encoder/query decoder and a controlled RPC. Coverage includes validation, threshold planning, inline and chunked byte equality, JPEG, a maximum-length 128-byte filename, rejected writes, wrong chain, absent image, corrupted bytes/metadata, missing chunks and preserved manifest/receipts when final image creation fails. The full 25 MiB roundtrip exercises 263 chunks, 266 transactions and pagination beyond 200 entities. **25 MiB is simulated, not a live-network upload claim.**
+
+`npm run typecheck` and the sample's `npm run build` pass. No lint command exists in this repository.
+
+`npm run test:browser`: isolated browser context, injected wallet and controlled RPC, real SDK/package and pixel decoder. PNG inline, JPEG and chunked PNG upload/retrieve/download pass; download bytes match. Reload-and-read works without the original file or connected wallet. Empty, loading, missing-entity, RPC failure, rejected-signature, wrong-chain and invalid-file states were exercised.
+
+Rendered widths: 390, 599, 600, 601, 768 and 1440 CSS pixels. DOM checks found no horizontal page overflow; computed typography and font loading matched the documented contract. Screenshots at 390/768/1440 also show the real-network JPEG result. Reflow was inspected at 200% CSS zoom; native browser-menu zoom and a physical touch device have not been separately verified. Screenshots are local test artifacts, not a deployed demo.
+
+## Consumer and audit gates
+
+A fresh agent with only the package/sample READMEs, consumer guides and an integration objective installed the packed candidate in a new directory. It ran the exact minimal example, compiled every public type against actual SDK clients, and read the real 120,000-byte image from Tiramisu without a wallet. Invalid format, excessive size, invalid/missing key, unexpected digest and wrong network failed as documented. No blocking documentation gaps were found; its suggestion of a complete anonymous-read example was incorporated.
+
+Claude completed its source/security/logic/browser review after resuming a timed-out session. It independently retrieved all three live images and confirmed the recorded byte equality. It identified stale sample dependency contents and missing npm publication as blocking release gates. Those gates, clean registry consumption and source checkout verification are pending in this pre-publication snapshot; see the source report for their final status. Other observations were addressed through accurate error wording and documented JPEG limitations. The source repository includes the review resolution table in docs/claude-review.md.
+
+## Preview and scope
+
+The sample is available locally at http://127.0.0.1:3082 for developer review before deployment. No public demo deployment is claimed. The Arkiv Hub catalogue entry remains pending because its live-demo prerequisite cannot be met until that review/deploy step. No encryption, PDFs, new skills, MCP integration, scaffolding or unrelated Hub changes were added.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "arkiv-images",
+  "version": "0.1.0",
+  "description": "Store public PNG and JPEG images as Arkiv entities and retrieve verified original bytes.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "LICENSE",
+    "docs/verification.md",
+    "docs/testnet-evidence.json"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.10.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SantiagoDevRel/arkiv-images.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "test:browser": "node test/browser-smoke.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "arkiv-chunking": "0.1.0"
+  },
+  "peerDependencies": {
+    "@arkiv-network/sdk": "0.8.0",
+    "viem": "^2.56.3"
+  },
+  "devDependencies": {
+    "@arkiv-network/sdk": "0.8.0",
+    "@types/node": "22.19.13",
+    "playwright": "1.62.1",
+    "typescript": "5.9.3",
+    "viem": "2.56.3"
+  }
+}