@artblocks/abx-storage 0.1.0-alpha.0

package/dist/cloud.d.ts

@@ -0,0 +1,105 @@
+import type { Hex } from 'viem';
+import type { DirEntry, StorageBackend, StoredContent } from './backend.js';
+/**
+ * S3-compatible **cloud** object storage — one adapter for AWS S3, Cloudflare R2,
+ * Backblaze B2, MinIO, and anything else that speaks the S3 API. It signs plain
+ * `fetch` requests with AWS Signature V4 using only `node:crypto`, so it adds
+ * **zero dependencies** (no AWS SDK, no native module) — the toolkit's minimal-deps
+ * ethos, kept. Content is stored path-style and addressed by its commitment hash.
+ */
+export interface CloudStorageConfig {
+    /** S3 endpoint origin, e.g. `https://<acct>.r2.cloudflarestorage.com` or `https://s3.us-east-1.amazonaws.com`. */
+    endpoint: string;
+    bucket: string;
+    /** `auto` for R2; the bucket's region for AWS (e.g. `us-east-1`). */
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Key prefix for stored objects. Default `abx/content/`. */
+    prefix?: string;
+    /** SigV4 service name. Default `s3`. */
+    service?: string;
+    /**
+     * Public READ base for objects — distinct from the signed-API `endpoint`. The bucket's
+     * public URL or a CDN in front of it (e.g. `https://<bucket>.s3.<region>.amazonaws.com`,
+     * `https://s3.<region>.amazonaws.com/<bucket>`, or `https://cdn.you.xyz`), such that
+     * `<publicBase>/<key>` fetches the object. Required to bake direct object URLs on-chain
+     * (the `url`/`url-template` image patterns) or to serve images off this node's `/image` route.
+     * Unset → node-served only (the resolver serves via `get()`); no direct URLs.
+     */
+    publicBase?: string;
+}
+/** The AWS SigV4 signing key: an HMAC chain over date → region → service. */
+export declare function deriveSigningKey(secret: string, dateStamp: string, region: string, service: string): Buffer;
+export interface SigV4Input {
+    method: string;
+    canonicalUri: string;
+    canonicalQuery: string;
+    headers: Record<string, string>;
+    payloadHash: string;
+    amzDate: string;
+    dateStamp: string;
+    region: string;
+    service: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+}
+/**
+ * Compute an AWS Signature V4 authorization for a request. Pure and deterministic
+ * (date is an input), so it verifies against AWS's published test vectors.
+ */
+export declare function sigv4Signature(p: SigV4Input): {
+    authorization: string;
+    signature: string;
+    signedHeaders: string;
+};
+export declare class CloudStorageBackend implements StorageBackend {
+    private readonly cfg;
+    readonly id = "cloud";
+    /** The public READ base (`<publicBase>/<key>`), when configured — see {@link StorageBackend.publicBase}. */
+    readonly publicBase?: string;
+    private readonly origin;
+    private readonly prefix;
+    private readonly service;
+    constructor(cfg: CloudStorageConfig);
+    private key;
+    private send;
+    /** Signed S3 request against an arbitrary object key (the key-based core of {@link send}). */
+    private sendKey;
+    put(hash: Hex, content: StoredContent): Promise<void>;
+    get(hash: Hex): Promise<StoredContent | null>;
+    has(hash: Hex): Promise<boolean>;
+    /**
+     * The public READ URL for the object (`<publicBase>/<key>`), or null if no public base is
+     * configured (then the resolver serves the bytes through its own `/image` route). Note: S3 is
+     * NOT content-addressed, so this URL has no on-chain integrity anchor of its own — the on-chain
+     * keccak256 remains the anchor (verify any served bytes against it).
+     */
+    locator(hash: Hex): Promise<string | null>;
+    /**
+     * Write bytes at an EXACT key (not content-addressed), overwriting in place — the
+     * deterministic-thumbnail primitive. `key` is the object path relative to the bucket root
+     * (and to {@link publicBase}), e.g. `orbit-weave/0.png`, so `<publicBase>/<key>` is the stable
+     * URL an on-chain `url-template` names. No `prefix` is prepended: the key IS the public path,
+     * fully determined by what was baked on-chain.
+     */
+    putObject(key: string, content: StoredContent): Promise<void>;
+    /** Read bytes previously written by {@link putObject} at `key`, or null (404). */
+    getObject(key: string): Promise<StoredContent | null>;
+    /**
+     * Upload a directory of files under a content-derived prefix and return its public base
+     * (`<publicBase>/<dirPrefix>`), so `<base>/0.png` resolves — the S3 form of the O(1) directory
+     * pattern (one on-chain `url-template`). The prefix is a hash of the (name, bytes) set, so the
+     * same inputs re-upload to the same location (idempotent) and distinct collections never collide.
+     */
+    putDirectory(entries: DirEntry[]): Promise<{
+        base: string;
+    }>;
+    health(): Promise<{
+        ok: boolean;
+        detail?: string;
+    }>;
+}
+/** Build a cloud-storage config from the environment (works for AWS S3, R2, B2, MinIO). */
+export declare function cloudConfigFromEnv(): CloudStorageConfig;
+//# sourceMappingURL=cloud.d.ts.map

package/dist/cloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["../src/cloud.ts"],"names":[],"mappings":"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"}

package/dist/cloud.js

@@ -0,0 +1,203 @@
+import { createHash, createHmac } from 'node:crypto';
+const EMPTY_SHA256 = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
+function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function hmac(key, data) {
+    return createHmac('sha256', key).update(data, 'utf8').digest();
+}
+/** The AWS SigV4 signing key: an HMAC chain over date → region → service. */
+export function deriveSigningKey(secret, dateStamp, region, service) {
+    const kDate = hmac('AWS4' + secret, dateStamp);
+    const kRegion = hmac(kDate, region);
+    const kService = hmac(kRegion, service);
+    return hmac(kService, 'aws4_request');
+}
+/** RFC-3986 encode one path segment (encodeURIComponent leaves `!'()*` alone). */
+function rfc3986(segment) {
+    return encodeURIComponent(segment).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
+}
+function encodePath(path) {
+    return path.split('/').map(rfc3986).join('/');
+}
+/**
+ * Compute an AWS Signature V4 authorization for a request. Pure and deterministic
+ * (date is an input), so it verifies against AWS's published test vectors.
+ */
+export function sigv4Signature(p) {
+    const lower = {};
+    for (const [k, v] of Object.entries(p.headers))
+        lower[k.toLowerCase()] = v.trim().replace(/\s+/g, ' ');
+    const names = Object.keys(lower).sort();
+    const canonicalHeaders = names.map((n) => `${n}:${lower[n]}\n`).join('');
+    const signedHeaders = names.join(';');
+    const canonicalRequest = [p.method, p.canonicalUri, p.canonicalQuery, canonicalHeaders, signedHeaders, p.payloadHash].join('\n');
+    const scope = `${p.dateStamp}/${p.region}/${p.service}/aws4_request`;
+    const stringToSign = ['AWS4-HMAC-SHA256', p.amzDate, scope, sha256Hex(canonicalRequest)].join('\n');
+    const signature = createHmac('sha256', deriveSigningKey(p.secretAccessKey, p.dateStamp, p.region, p.service))
+        .update(stringToSign, 'utf8')
+        .digest('hex');
+    return {
+        authorization: `AWS4-HMAC-SHA256 Credential=${p.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+        signature,
+        signedHeaders,
+    };
+}
+export class CloudStorageBackend {
+    cfg;
+    id = 'cloud';
+    /** The public READ base (`<publicBase>/<key>`), when configured — see {@link StorageBackend.publicBase}. */
+    publicBase;
+    origin;
+    prefix;
+    service;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.origin = cfg.endpoint.replace(/\/+$/, '');
+        this.prefix = cfg.prefix ?? 'abx/content/';
+        this.service = cfg.service ?? 's3';
+        this.publicBase = cfg.publicBase ? cfg.publicBase.replace(/\/+$/, '') : undefined;
+    }
+    key(hash) {
+        return `${this.prefix}${hash.toLowerCase().replace(/^0x/, '')}`;
+    }
+    send(method, hash, body, contentType) {
+        return this.sendKey(method, this.key(hash), body, contentType);
+    }
+    /** Signed S3 request against an arbitrary object key (the key-based core of {@link send}). */
+    async sendKey(method, key, body, contentType) {
+        const path = `/${this.cfg.bucket}/${key}`;
+        const url = `${this.origin}${path}`;
+        const host = new URL(url).host;
+        const amzDate = new Date().toISOString().replace(/[:-]|\.\d{3}/g, '');
+        const dateStamp = amzDate.slice(0, 8);
+        const payloadHash = body ? sha256Hex(body) : EMPTY_SHA256;
+        const signHeaders = { host, 'x-amz-content-sha256': payloadHash, 'x-amz-date': amzDate };
+        if (contentType)
+            signHeaders['content-type'] = contentType;
+        const { authorization } = sigv4Signature({
+            method,
+            canonicalUri: encodePath(path),
+            canonicalQuery: '',
+            headers: signHeaders,
+            payloadHash,
+            amzDate,
+            dateStamp,
+            region: this.cfg.region,
+            service: this.service,
+            accessKeyId: this.cfg.accessKeyId,
+            secretAccessKey: this.cfg.secretAccessKey,
+        });
+        // `host` is managed by fetch; the rest must match what we signed.
+        const headers = { authorization, 'x-amz-content-sha256': payloadHash, 'x-amz-date': amzDate };
+        if (contentType)
+            headers['content-type'] = contentType;
+        return fetch(url, { method, headers, body });
+    }
+    async put(hash, content) {
+        const res = await this.send('PUT', hash, content.bytes, content.contentType);
+        if (!res.ok)
+            throw new Error(`Cloud storage PUT failed (${res.status}): ${await res.text()}`);
+    }
+    async get(hash) {
+        const res = await this.send('GET', hash);
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`Cloud storage GET failed (${res.status}): ${await res.text()}`);
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        return { bytes, contentType: res.headers.get('content-type') ?? 'application/octet-stream' };
+    }
+    async has(hash) {
+        const res = await this.send('HEAD', hash);
+        if (res.status === 404)
+            return false;
+        if (!res.ok)
+            throw new Error(`Cloud storage HEAD failed (${res.status})`);
+        return true;
+    }
+    /**
+     * The public READ URL for the object (`<publicBase>/<key>`), or null if no public base is
+     * configured (then the resolver serves the bytes through its own `/image` route). Note: S3 is
+     * NOT content-addressed, so this URL has no on-chain integrity anchor of its own — the on-chain
+     * keccak256 remains the anchor (verify any served bytes against it).
+     */
+    async locator(hash) {
+        return this.publicBase ? `${this.publicBase}/${this.key(hash)}` : null;
+    }
+    /**
+     * Write bytes at an EXACT key (not content-addressed), overwriting in place — the
+     * deterministic-thumbnail primitive. `key` is the object path relative to the bucket root
+     * (and to {@link publicBase}), e.g. `orbit-weave/0.png`, so `<publicBase>/<key>` is the stable
+     * URL an on-chain `url-template` names. No `prefix` is prepended: the key IS the public path,
+     * fully determined by what was baked on-chain.
+     */
+    async putObject(key, content) {
+        const res = await this.sendKey('PUT', key.replace(/^\/+/, ''), content.bytes, content.contentType);
+        if (!res.ok)
+            throw new Error(`Cloud storage PUT (${key}) failed (${res.status}): ${await res.text()}`);
+    }
+    /** Read bytes previously written by {@link putObject} at `key`, or null (404). */
+    async getObject(key) {
+        const res = await this.sendKey('GET', key.replace(/^\/+/, ''));
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`Cloud storage GET (${key}) failed (${res.status}): ${await res.text()}`);
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        return { bytes, contentType: res.headers.get('content-type') ?? 'application/octet-stream' };
+    }
+    /**
+     * Upload a directory of files under a content-derived prefix and return its public base
+     * (`<publicBase>/<dirPrefix>`), so `<base>/0.png` resolves — the S3 form of the O(1) directory
+     * pattern (one on-chain `url-template`). The prefix is a hash of the (name, bytes) set, so the
+     * same inputs re-upload to the same location (idempotent) and distinct collections never collide.
+     */
+    async putDirectory(entries) {
+        if (!this.cfg.publicBase) {
+            throw new Error('cloud directory upload needs a public read base — set ABX_S3_PUBLIC_BASE (or --public-base) to your ' +
+                'bucket public URL / CDN, e.g. https://<bucket>.s3.<region>.amazonaws.com or https://cdn.you.xyz. ' +
+                "It's baked on-chain, so prefer a domain/CDN you control (moving it is then DNS, not a tx).");
+        }
+        const dirHash = sha256Hex(entries.map((e) => `${e.name}:${sha256Hex(e.bytes)}`).join('|')).slice(0, 32);
+        const dirPrefix = `${this.prefix}dir/${dirHash}`;
+        for (const e of entries) {
+            const res = await this.sendKey('PUT', `${dirPrefix}/${e.name}`, e.bytes, e.contentType);
+            if (!res.ok)
+                throw new Error(`Cloud storage directory PUT failed for ${e.name} (${res.status}): ${await res.text()}`);
+        }
+        return { base: `${this.cfg.publicBase.replace(/\/+$/, '')}/${dirPrefix}` };
+    }
+    async health() {
+        // A signed read of a key that won't exist: 404 → endpoint reachable + credentials
+        // accepted; a 401/403 → bad credentials; a network error → wrong endpoint.
+        const probe = ('0x' + '00'.repeat(32));
+        try {
+            await this.get(probe);
+            return { ok: true, detail: `${this.origin}/${this.cfg.bucket} (region ${this.cfg.region})` };
+        }
+        catch (e) {
+            return { ok: false, detail: e.message };
+        }
+    }
+}
+/** Build a cloud-storage config from the environment (works for AWS S3, R2, B2, MinIO). */
+export function cloudConfigFromEnv() {
+    const need = (k) => {
+        const v = process.env[k];
+        if (!v)
+            throw new Error(`Cloud storage backend needs ${k} (set ABX_S3_ENDPOINT/BUCKET/ACCESS_KEY_ID/SECRET_ACCESS_KEY).`);
+        return v;
+    };
+    return {
+        endpoint: need('ABX_S3_ENDPOINT'),
+        bucket: need('ABX_S3_BUCKET'),
+        region: process.env.ABX_S3_REGION ?? 'auto',
+        accessKeyId: need('ABX_S3_ACCESS_KEY_ID'),
+        secretAccessKey: need('ABX_S3_SECRET_ACCESS_KEY'),
+        prefix: process.env.ABX_S3_PREFIX ?? 'abx/content/',
+        service: 's3',
+        publicBase: process.env.ABX_S3_PUBLIC_BASE,
+    };
+}
+//# sourceMappingURL=cloud.js.map

package/dist/cloud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.js","sourceRoot":"","sources":["../src/cloud.ts"],"names":[],"mappings":"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"}

package/dist/content-index.d.ts

@@ -0,0 +1,22 @@
+import type { Hex } from 'viem';
+/**
+ * The off-chain `keccak → pointer` index used by backends whose native content id
+ * isn't the commitment hash (IPFS CID, Arweave txid). It's the necessary bridge
+ * until a pointer commitment is recorded on-chain — small JSON next to the
+ * projection, and removable the day the pointer lives on-chain.
+ */
+export interface IndexEntry {
+    /** The backend's native id for the content — an IPFS CID or an Arweave txid. */
+    pointer: string;
+    contentType: string;
+}
+export declare class ContentIndex {
+    readonly path: string;
+    private data;
+    constructor(dataDir?: string);
+    private key;
+    get(hash: Hex): IndexEntry | null;
+    has(hash: Hex): boolean;
+    set(hash: Hex, entry: IndexEntry): void;
+}
+//# sourceMappingURL=content-index.d.ts.map

package/dist/content-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-index.d.ts","sourceRoot":"","sources":["../src/content-index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,MAAM,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,YAAY;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,IAAI,CAA6B;gBAE7B,OAAO,CAAC,EAAE,MAAM;IAO5B,OAAO,CAAC,GAAG;IAIX,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,UAAU,GAAG,IAAI;IAIjC,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO;IAIvB,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;CAIxC"}

package/dist/content-index.js

@@ -0,0 +1,26 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+export class ContentIndex {
+    path;
+    data;
+    constructor(dataDir) {
+        const base = dataDir ?? process.env.ABX_DATA_DIR ?? resolve(process.cwd(), '.abx-self-host');
+        mkdirSync(base, { recursive: true });
+        this.path = resolve(base, 'content-index.json');
+        this.data = existsSync(this.path) ? JSON.parse(readFileSync(this.path, 'utf8')) : {};
+    }
+    key(hash) {
+        return hash.toLowerCase();
+    }
+    get(hash) {
+        return this.data[this.key(hash)] ?? null;
+    }
+    has(hash) {
+        return this.key(hash) in this.data;
+    }
+    set(hash, entry) {
+        this.data[this.key(hash)] = entry;
+        writeFileSync(this.path, JSON.stringify(this.data, null, 2));
+    }
+}
+//# sourceMappingURL=content-index.js.map

package/dist/content-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-index.js","sourceRoot":"","sources":["../src/content-index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAC,MAAM,SAAS,CAAC;AAC3E,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAelC,MAAM,OAAO,YAAY;IACd,IAAI,CAAS;IACd,IAAI,CAA6B;IAEzC,YAAY,OAAgB;QAC1B,MAAM,IAAI,GAAG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,gBAAgB,CAAC,CAAC;QAC7F,SAAS,CAAC,IAAI,EAAE,EAAC,SAAS,EAAE,IAAI,EAAC,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvH,CAAC;IAEO,GAAG,CAAC,IAAS;QACnB,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC;IAC5B,CAAC;IAED,GAAG,CAAC,IAAS;QACX,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC;IAC3C,CAAC;IAED,GAAG,CAAC,IAAS;QACX,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC;IACrC,CAAC;IAED,GAAG,CAAC,IAAS,EAAE,KAAiB;QAC9B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC;QAClC,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/fs.d.ts

@@ -0,0 +1,23 @@
+import type { Hex } from 'viem';
+import type { StorageBackend, StoredContent } from './backend.js';
+/**
+ * The reference backend: content-addressed files on the local disk — "store the
+ * bytes on your droplet and serve them." Zero dependencies, the natural floor for
+ * a self-hoster. Bytes live at `<dataDir>/content/<hash>`, with the MIME type in a
+ * sidecar so `get` can replay it. Deleting the directory loses the content (it is
+ * the source of truth) — exactly why custody is switchable but never lapsable.
+ */
+export declare class LocalFsBackend implements StorageBackend {
+    readonly id = "fs";
+    readonly dir: string;
+    constructor(dataDir?: string);
+    private path;
+    put(hash: Hex, content: StoredContent): Promise<void>;
+    get(hash: Hex): Promise<StoredContent | null>;
+    has(hash: Hex): Promise<boolean>;
+    health(): Promise<{
+        ok: boolean;
+        detail?: string;
+    }>;
+}
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,MAAM,CAAC;AAC9B,OAAO,KAAK,EAAC,cAAc,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAEhE;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,cAAc;IACnD,QAAQ,CAAC,EAAE,QAAQ;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAET,OAAO,CAAC,EAAE,MAAM;IAM5B,OAAO,CAAC,IAAI;IAIN,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAS7C,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;IAIhC,MAAM,IAAI,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;CAWxD"}

package/dist/fs.js

@@ -0,0 +1,50 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+/**
+ * The reference backend: content-addressed files on the local disk — "store the
+ * bytes on your droplet and serve them." Zero dependencies, the natural floor for
+ * a self-hoster. Bytes live at `<dataDir>/content/<hash>`, with the MIME type in a
+ * sidecar so `get` can replay it. Deleting the directory loses the content (it is
+ * the source of truth) — exactly why custody is switchable but never lapsable.
+ */
+export class LocalFsBackend {
+    id = 'fs';
+    dir;
+    constructor(dataDir) {
+        const base = dataDir ?? process.env.ABX_DATA_DIR ?? resolve(process.cwd(), '.abx-self-host');
+        this.dir = resolve(base, 'content');
+        mkdirSync(this.dir, { recursive: true });
+    }
+    path(hash) {
+        return join(this.dir, hash.toLowerCase().replace(/^0x/, ''));
+    }
+    async put(hash, content) {
+        writeFileSync(this.path(hash), content.bytes);
+        writeFileSync(this.path(hash) + '.type', content.contentType, 'utf8');
+    }
+    async get(hash) {
+        const p = this.path(hash);
+        if (!existsSync(p))
+            return null;
+        const bytes = new Uint8Array(readFileSync(p));
+        const typePath = p + '.type';
+        const contentType = existsSync(typePath) ? readFileSync(typePath, 'utf8') : 'application/octet-stream';
+        return { bytes, contentType };
+    }
+    async has(hash) {
+        return existsSync(this.path(hash));
+    }
+    async health() {
+        try {
+            const probe = join(this.dir, '.probe');
+            writeFileSync(probe, 'ok');
+            readFileSync(probe);
+            rmSync(probe);
+            return { ok: true, detail: `writable: ${this.dir}` };
+        }
+        catch (e) {
+            return { ok: false, detail: e.message };
+        }
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAC,MAAM,SAAS,CAAC;AACnF,OAAO,EAAC,IAAI,EAAE,OAAO,EAAC,MAAM,WAAW,CAAC;AAIxC;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IAChB,EAAE,GAAG,IAAI,CAAC;IACV,GAAG,CAAS;IAErB,YAAY,OAAgB;QAC1B,MAAM,IAAI,GAAG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,gBAAgB,CAAC,CAAC;QAC7F,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACpC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,EAAC,SAAS,EAAE,IAAI,EAAC,CAAC,CAAC;IACzC,CAAC;IAEO,IAAI,CAAC,IAAS;QACpB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAS,EAAE,OAAsB;QACzC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9C,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAS;QACjB,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9C,MAAM,QAAQ,GAAG,CAAC,GAAG,OAAO,CAAC;QAC7B,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,0BAA0B,CAAC;QACvG,OAAO,EAAC,KAAK,EAAE,WAAW,EAAC,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAS;QACjB,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YACvC,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC3B,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,KAAK,CAAC,CAAC;YACd,OAAO,EAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,IAAI,CAAC,GAAG,EAAE,EAAC,CAAC;QACrD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,EAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAG,CAAW,CAAC,OAAO,EAAC,CAAC;QACnD,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @artblocks/abx-storage — Layer 3 reference byte custody.
+ *
+ * Holds the source-of-truth bytes a token's on-chain content commitment points
+ * at, content-addressed by that hash, behind a pluggable backend. The reference
+ * backend is local disk; cloud / content-addressed backends slot in behind the
+ * same interface.
+ */
+export type { StorageBackend, StoredContent } from './backend.js';
+export { hashContent, contentTypeFromPath } from './backend.js';
+export { LocalFsBackend } from './fs.js';
+export { CloudStorageBackend, cloudConfigFromEnv, deriveSigningKey, sigv4Signature, type CloudStorageConfig, type SigV4Input, } from './cloud.js';
+export { ContentIndex, type IndexEntry } from './content-index.js';
+export { IpfsBackend, ipfsConfigFromEnv, type IpfsConfig } from './ipfs.js';
+export { ArweaveBackend, HttpBundlerUploader, TurboUploader, arweaveConfigFromEnv, arweaveFunding, arweaveProvider, turboIdentity, resolveTurboIdentity, turboIdentityAddress, isEthIdentity, ARWEAVE_FREE_UPLOAD_LIMIT, turboUploadCostUsd, turboUploadWinc, turboUploadId, turboBalanceForAddress, type ArweaveConfig, type ArweaveProvider, type ArweaveUploader, type ArweaveFunding, type TurboIdentity, } from './arweave.js';
+export { generateArweaveJwk, arweaveAddress, type ArweaveJwk } from './arweave-identity.js';
+export { resolveBackend, type ResolveStorageOptions } from './resolve.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,YAAY,EAAC,cAAc,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAChE,OAAO,EAAC,WAAW,EAAE,mBAAmB,EAAC,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAC,cAAc,EAAC,MAAM,SAAS,CAAC;AACvC,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAC,YAAY,EAAE,KAAK,UAAU,EAAC,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAC,WAAW,EAAE,iBAAiB,EAAE,KAAK,UAAU,EAAC,MAAM,WAAW,CAAC;AAC1E,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,yBAAyB,EACzB,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAC,kBAAkB,EAAE,cAAc,EAAE,KAAK,UAAU,EAAC,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EAAC,cAAc,EAAE,KAAK,qBAAqB,EAAC,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export { hashContent, contentTypeFromPath } from './backend.js';
+export { LocalFsBackend } from './fs.js';
+export { CloudStorageBackend, cloudConfigFromEnv, deriveSigningKey, sigv4Signature, } from './cloud.js';
+export { ContentIndex } from './content-index.js';
+export { IpfsBackend, ipfsConfigFromEnv } from './ipfs.js';
+export { ArweaveBackend, HttpBundlerUploader, TurboUploader, arweaveConfigFromEnv, arweaveFunding, arweaveProvider, turboIdentity, resolveTurboIdentity, turboIdentityAddress, isEthIdentity, ARWEAVE_FREE_UPLOAD_LIMIT, turboUploadCostUsd, turboUploadWinc, turboUploadId, turboBalanceForAddress, } from './arweave.js';
+export { generateArweaveJwk, arweaveAddress } from './arweave-identity.js';
+export { resolveBackend } from './resolve.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAC,WAAW,EAAE,mBAAmB,EAAC,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAC,cAAc,EAAC,MAAM,SAAS,CAAC;AACvC,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,GAGf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAC,YAAY,EAAkB,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAC,WAAW,EAAE,iBAAiB,EAAkB,MAAM,WAAW,CAAC;AAC1E,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,yBAAyB,EACzB,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,sBAAsB,GAMvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAC,kBAAkB,EAAE,cAAc,EAAkB,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EAAC,cAAc,EAA6B,MAAM,cAAc,CAAC"}

package/dist/ipfs.d.ts

@@ -0,0 +1,62 @@
+import type { Hex } from 'viem';
+import type { DirEntry, StorageBackend, StoredContent } from './backend.js';
+/**
+ * IPFS byte custody, two modes:
+ *  - **`kubo`** — add + pin to an IPFS node you run (the Kubo HTTP API), retrieve
+ *    via your gateway. Self-hosted, dep-free.
+ *  - **`pinata`** — pin through a managed service (Pinata), retrieve via a gateway.
+ *    Same shape for other pinning services.
+ *
+ * IPFS addresses by **CID**, but the toolkit keys content by its keccak256
+ * commitment. Until a CID commitment is recorded on-chain, this backend keeps an
+ * off-chain `keccak → {cid, contentType}` index next to the projection — localized
+ * here, and removable the day the CID lives on-chain (the commitment extension
+ * already allows multiple kinds).
+ */
+export interface IpfsConfig {
+    mode: 'kubo' | 'pinata';
+    /** Gateway base for retrieval, e.g. `http://127.0.0.1:8080` or `https://gateway.pinata.cloud`. */
+    gateway: string;
+    /** Kubo API base, e.g. `http://127.0.0.1:5001`. */
+    apiUrl?: string;
+    /** Pinata API base. Default `https://api.pinata.cloud`. */
+    pinataEndpoint?: string;
+    /** Pinata JWT — secret, from env, never persisted to config. */
+    pinataJwt?: string;
+}
+export declare class IpfsBackend implements StorageBackend {
+    private readonly cfg;
+    readonly id = "ipfs";
+    private readonly index;
+    constructor(cfg: IpfsConfig, dataDir?: string);
+    put(hash: Hex, content: StoredContent): Promise<void>;
+    get(hash: Hex): Promise<StoredContent | null>;
+    has(hash: Hex): Promise<boolean>;
+    /**
+     * The **gateway HTTPS URL** for the pinned bytes (`<gateway>/ipfs/<cid>`) — the production-safe
+     * form an NFT `image` needs, since browsers, wallets, and most marketplaces can't render a raw
+     * `ipfs://<cid>`. The CID is content-addressed so the bytes are resolvable through *any* gateway
+     * (and verifiable against the on-chain keccak256); we serve a concrete, reachable one. A pinning
+     * service + a public gateway is therefore part of operating IPFS custody — a local gateway
+     * (`127.0.0.1`/`localhost`) produces a URL only this machine can resolve. Null until pinned.
+     */
+    locator(hash: Hex): Promise<string | null>;
+    /**
+     * Pin a directory of files as ONE IPFS object and return its gateway base
+     * (`<gateway>/ipfs/<dirCID>`), so `<base>/0.png` resolves. The CID is content-addressed →
+     * gateway-agnostic integrity for the whole set. Pinata only (kubo directory add is deferred).
+     */
+    putDirectory(entries: DirEntry[]): Promise<{
+        base: string;
+    }>;
+    health(): Promise<{
+        ok: boolean;
+        detail?: string;
+    }>;
+    private form;
+    private addKubo;
+    private addPinata;
+}
+/** Build an IPFS config from the environment (non-secret values; PINATA_JWT is the secret). */
+export declare function ipfsConfigFromEnv(): IpfsConfig;
+//# sourceMappingURL=ipfs.d.ts.map

package/dist/ipfs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipfs.d.ts","sourceRoot":"","sources":["../src/ipfs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,MAAM,CAAC;AAC9B,OAAO,KAAK,EAAC,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAG1E;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,kGAAkG;IAClG,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,qBAAa,WAAY,YAAW,cAAc;IAIpC,OAAO,CAAC,QAAQ,CAAC,GAAG;IAHhC,QAAQ,CAAC,EAAE,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAER,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM;IAIxD,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAU7C,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;IAItC;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAKhD;;;;OAIG;IACG,YAAY,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAC;IAuB1D,MAAM,IAAI,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;IAiBvD,OAAO,CAAC,IAAI;YAME,OAAO;YAUP,SAAS;CAYxB;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,IAAI,UAAU,CAS9C"}