@siafoundation/sia-storage 0.0.14 → 0.1.0

package/README.md

@@ -113,6 +113,9 @@ Near-identical surfaces. Real differences:
 
 - App identifier: `appMeta.appId: string (hex)` on browser, `appMeta.id: Buffer(32)` on Node.
 - Numeric sizes are `number` on browser, `bigint` on Node. Byte arrays are `Uint8Array` on browser, `Buffer` on Node (`Buffer` is a `Uint8Array` subclass; both accept either as input).
+- Sharing key seeds are hex `string` on browser, `Buffer` on Node. This covers `SharingKey.seed()`, `SharingKey.fromSeed(seed)`, and `SharedSdk.connect(indexerUrl, seed)`.
+- `sdk.unshareObject(key, object)` takes a `PinnedObject` on browser and an object id `string` on Node.
+- `sdk.hosts(query?)` and `sharedSdk.hosts(query?)` accept a `HostQuery` on browser; on Node they take no arguments.
 
 ## API
 
@@ -128,7 +131,7 @@ Near-identical surfaces. Real differences:
 
 ### `Sdk`
 
-Returned from `Builder.register()` or `Builder.connected()`.
+Returned from `Builder.register()`, `Builder.connected()`, or `Builder.connectPreAuthorized()`.
 
 | | |
 |---|---|
@@ -138,9 +141,14 @@ Returned from `Builder.register()` or `Builder.connected()`.
 | `uploadPacked(options?)` | `PackedUpload` for batching small files into shared slabs. |
 | `object(key)` / `deleteObject(key)` / `pinObject(object)` | Object CRUD. |
 | `updateObjectMetadata(object)` | Push local metadata changes to the indexer. |
-| `shareObject(object, validUntil)` / `sharedObject(url)` | Create / consume share URLs. |
+| `objectShareUrl(object, validUntil)` / `objectFromShareUrl(url)` | Create / consume share URLs. |
 | `objectEvents(cursor?, limit)` | Paginated change feed. |
-| `hosts()` / `slab(id)` / `account()` / `pruneSlabs()` | Indexer reads. |
+| `hosts(query?)` / `slab(id)` / `account()` / `pruneSlabs()` | Indexer reads. |
+| `createSharingKey(description, expiresAt?)` | Create a `SharingKey` for read-only sharing. |
+| `sharingKeys(offset, limit)` / `sharingKey(key)` | List keys / fetch one key's `KeyRecord`. |
+| `shareObject(key, object)` / `unshareObject(key, object)` | Attach / detach an object on a sharing key. |
+| `sharedObjects(key, offset, limit)` | Objects attached to a sharing key. |
+| `revokeSharingKey(key)` | Delete the key and detach all of its objects. |
 
 ### `Builder`
 
@@ -153,6 +161,9 @@ Returned from `Builder.register()` or `Builder.connected()`.
 | `waitForApproval()` | Resolves once the user approves. |
 | `register(phrase)` | Finish onboarding with a new recovery phrase → `Sdk`. |
 | `connected(appKey)` | Reconnect with a saved `AppKey` → `Sdk \| null`. |
+| `reconnecting()` | Whether the approved connect key already has an account. |
+| `matchesExistingAppKey(phrase)` | Whether a phrase derives an already-registered app key. |
+| `connectPreAuthorized(seed, phrase)` | Skip the approval flow with a pre-authorized key's 32-byte seed → `Sdk`. |
 
 ### `AppKey`
 
@@ -164,7 +175,7 @@ Returned from `Builder.register()` or `Builder.connected()`.
 
 `new PinnedObject()` for new uploads, or `sdk.object(key)`.
 
-`id()` · `size()` · `encodedSize()` · `slabs()` · `metadata()` · `updateMetadata(bytes)` · `createdAt()` · `updatedAt()` · `seal(appKey)` · `PinnedObject.open(appKey, sealed)`
+`id()` · `size()` · `encodedSize()` · `slabs()` · `metadata()` · `updateMetadata(bytes)` · `truncate(length: bigint)` · `createdAt()` · `updatedAt()` · `seal(appKey)` · `PinnedObject.open(appKey, sealed)`
 
 ### `PackedUpload`
 
@@ -172,6 +183,30 @@ From `sdk.uploadPacked()`.
 
 `add(stream)` · `finalize()` · `cancel()` · `remaining()` · `length()` · `slabs()`
 
+### `SharingKey`
+
+From `sdk.createSharingKey()`, or `SharingKey.fromSeed(seed)` to import one.
+
+`publicKey` · `seed()` · `SharingKey.fromSeed(seed)`
+
+### `KeyRecord`
+
+The indexer's record for a sharing key, from `sdk.sharingKey()` or `sdk.sharingKeys()`.
+
+`key` · `description` · `stats`
+
+### `SharedSdk`
+
+`SharedSdk.connect(indexerUrl, seed)` — read-only access for a recipient holding a
+sharing key's seed. Downloads are paid for by the key's owner.
+
+| | |
+|---|---|
+| `stats()` | The key's `KeyStats` snapshot. |
+| `object(id)` / `objects(offset, limit)` | Read the objects the key grants access to. |
+| `download(object, options?)` | Returns a `ReadableStream`. |
+| `hosts(query?)` | Hosts serving this key's objects. |
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Account, AppKey, AppMetadata, Builder, DownloadOptions, Host, HostQuery, ObjectEvent, PackedUpload, PinnedObject, PinnedSlab, Sdk, SealedObject, Sector, ShardProgress, Slab, UploadOptions, encodedSize, generateRecoveryPhrase, setLogger, validateRecoveryPhrase } from '../wasm/sia_storage_wasm.js';
+export { Account, AppKey, AppMetadata, Builder, DownloadOptions, Host, HostQuery, KeyRecord, KeyStats, ObjectEvent, PackedUpload, PinnedObject, PinnedSlab, Sdk, SealedObject, Sector, ShardProgress, SharedSdk, SharingKey, Slab, UploadOptions, encodedSize, generateRecoveryPhrase, setLogger, validateRecoveryPhrase } from '../wasm/sia_storage_wasm.js';
 
 /** Initialize the WASM module. Safe to call multiple times. */
 declare function initSia(): Promise<void>;

package/dist/index.js

@@ -3,10 +3,13 @@ import wasmInit from "../wasm/sia_storage_wasm.js";
 import {
   AppKey,
   Builder,
+  KeyRecord,
   ObjectEvent,
   PackedUpload,
   PinnedObject,
   Sdk,
+  SharedSdk,
+  SharingKey,
   encodedSize,
   generateRecoveryPhrase,
   setLogger,
@@ -20,10 +23,13 @@ async function initSia() {
 export {
   AppKey,
   Builder,
+  KeyRecord,
   ObjectEvent,
   PackedUpload,
   PinnedObject,
   Sdk,
+  SharedSdk,
+  SharingKey,
   encodedSize,
   generateRecoveryPhrase,
   initSia,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Browser entry; lazily initializes WASM on first use.\n\nimport wasmInit from '../wasm/sia_storage_wasm.js'\n\nlet initPromise: Promise<unknown> | null = null\n\n/** Initialize the WASM module. Safe to call multiple times. */\nexport async function initSia(): Promise<void> {\n  if (!initPromise) initPromise = wasmInit()\n  await initPromise\n}\n\nexport {\n  AppKey,\n  Builder,\n  ObjectEvent,\n  PackedUpload,\n  PinnedObject,\n  Sdk,\n  encodedSize,\n  generateRecoveryPhrase,\n  setLogger,\n  validateRecoveryPhrase,\n} from '../wasm/sia_storage_wasm.js'\nexport type {\n  Account,\n  AppMetadata,\n  DownloadOptions,\n  Host,\n  HostQuery,\n  PinnedSlab,\n  Sector,\n  SealedObject,\n  ShardProgress,\n  Slab,\n  UploadOptions,\n} from '../wasm/sia_storage_wasm.js'\n"],"mappings":";AAEA,OAAO,cAAc;AAUrB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAnBP,IAAI,cAAuC;AAG3C,eAAsB,UAAyB;AAC7C,MAAI,CAAC,YAAa,eAAc,SAAS;AACzC,QAAM;AACR;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Browser entry; lazily initializes WASM on first use.\n\nimport wasmInit from '../wasm/sia_storage_wasm.js'\n\nlet initPromise: Promise<unknown> | null = null\n\n/** Initialize the WASM module. Safe to call multiple times. */\nexport async function initSia(): Promise<void> {\n  if (!initPromise) initPromise = wasmInit()\n  await initPromise\n}\n\nexport {\n  AppKey,\n  Builder,\n  KeyRecord,\n  ObjectEvent,\n  PackedUpload,\n  PinnedObject,\n  Sdk,\n  SharedSdk,\n  SharingKey,\n  encodedSize,\n  generateRecoveryPhrase,\n  setLogger,\n  validateRecoveryPhrase,\n} from '../wasm/sia_storage_wasm.js'\nexport type {\n  Account,\n  AppMetadata,\n  DownloadOptions,\n  Host,\n  HostQuery,\n  KeyStats,\n  PinnedSlab,\n  Sector,\n  SealedObject,\n  ShardProgress,\n  Slab,\n  UploadOptions,\n} from '../wasm/sia_storage_wasm.js'\n"],"mappings":";AAEA,OAAO,cAAc;AAUrB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAtBP,IAAI,cAAuC;AAG3C,eAAsB,UAAyB;AAC7C,MAAI,CAAC,YAAa,eAAc,SAAS;AACzC,QAAM;AACR;","names":[]}

package/dist/index.node.cjs

@@ -22,10 +22,13 @@ var index_node_exports = {};
 __export(index_node_exports, {
   AppKey: () => AppKey,
   Builder: () => Builder,
+  KeyRecord: () => KeyRecord,
   ObjectEvent: () => ObjectEvent,
   PackedUpload: () => PackedUpload,
   PinnedObject: () => PinnedObject,
   Sdk: () => Sdk,
+  SharedSdk: () => SharedSdk,
+  SharingKey: () => SharingKey,
   encodedSize: () => encodedSize,
   generateRecoveryPhrase: () => generateRecoveryPhrase,
   initSia: () => initSia,
@@ -71,6 +74,9 @@ var {
   PinnedObject,
   PackedUpload,
   ObjectEvent,
+  SharingKey,
+  KeyRecord,
+  SharedSdk,
   generateRecoveryPhrase,
   validateRecoveryPhrase,
   setLogger,
@@ -83,10 +89,13 @@ async function initSia() {
 0 && (module.exports = {
   AppKey,
   Builder,
+  KeyRecord,
   ObjectEvent,
   PackedUpload,
   PinnedObject,
   Sdk,
+  SharedSdk,
+  SharingKey,
   encodedSize,
   generateRecoveryPhrase,
   initSia,

package/dist/index.node.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.node.ts","../src/node/load.ts","../src/node/napi.ts"],"sourcesContent":["export * from './node/napi'\nexport type * from './node/napi'\n","import type * as Addon from './napi.generated'\n\nlet addon: typeof Addon | null = null\n\nexport function loadNativeAddon(): typeof Addon {\n  if (addon) return addon\n\n  const platform = process.platform\n  const arch = process.arch\n\n  try {\n    if (platform === 'darwin' && arch === 'arm64') {\n      addon = require('@siafoundation/sia-storage-darwin-arm64')\n    } else if (platform === 'darwin' && arch === 'x64') {\n      addon = require('@siafoundation/sia-storage-darwin-x64')\n    } else if (platform === 'linux' && arch === 'x64') {\n      addon = require('@siafoundation/sia-storage-linux-x64-gnu')\n    } else if (platform === 'linux' && arch === 'arm64') {\n      addon = require('@siafoundation/sia-storage-linux-arm64-gnu')\n    } else if (platform === 'win32' && arch === 'x64') {\n      addon = require('@siafoundation/sia-storage-win32-x64-msvc')\n    }\n  } catch {}\n\n  if (!addon) {\n    throw new Error(\n      `@siafoundation/sia-storage: Native addon not found for ${platform}-${arch}. ` +\n        `Install @siafoundation/sia-storage-${platform}-${arch} or use the browser/WASM build.`,\n    )\n  }\n\n  return addon\n}\n","import { loadNativeAddon } from './load'\n\nconst addon = loadNativeAddon()\n\nexport const {\n  AppKey,\n  Builder,\n  Sdk,\n  PinnedObject,\n  PackedUpload,\n  ObjectEvent,\n  generateRecoveryPhrase,\n  validateRecoveryPhrase,\n  setLogger,\n  encodedSize,\n} = addon\n\nexport type * from './napi.generated'\n\n/** Force-load the native addon to surface missing-binary errors at startup. */\nexport async function initSia(): Promise<void> {\n  loadNativeAddon()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACEA,IAAI,QAA6B;AAE1B,SAAS,kBAAgC;AAC9C,MAAI,MAAO,QAAO;AAElB,QAAM,WAAW,QAAQ;AACzB,QAAM,OAAO,QAAQ;AAErB,MAAI;AACF,QAAI,aAAa,YAAY,SAAS,SAAS;AAC7C,cAAQ,QAAQ,yCAAyC;AAAA,IAC3D,WAAW,aAAa,YAAY,SAAS,OAAO;AAClD,cAAQ,QAAQ,uCAAuC;AAAA,IACzD,WAAW,aAAa,WAAW,SAAS,OAAO;AACjD,cAAQ,QAAQ,0CAA0C;AAAA,IAC5D,WAAW,aAAa,WAAW,SAAS,SAAS;AACnD,cAAQ,QAAQ,4CAA4C;AAAA,IAC9D,WAAW,aAAa,WAAW,SAAS,OAAO;AACjD,cAAQ,QAAQ,2CAA2C;AAAA,IAC7D;AAAA,EACF,QAAQ;AAAA,EAAC;AAET,MAAI,CAAC,OAAO;AACV,UAAM,IAAI;AAAA,MACR,0DAA0D,QAAQ,IAAI,IAAI,wCAClC,QAAQ,IAAI,IAAI;AAAA,IAC1D;AAAA,EACF;AAEA,SAAO;AACT;;;AC9BA,IAAMA,SAAQ,gBAAgB;AAEvB,IAAM;AAAA,EACX;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,IAAIA;AAKJ,eAAsB,UAAyB;AAC7C,kBAAgB;AAClB;","names":["addon"]}
+{"version":3,"sources":["../src/index.node.ts","../src/node/load.ts","../src/node/napi.ts"],"sourcesContent":["export * from './node/napi'\nexport type * from './node/napi'\n","import type * as Addon from './napi.generated'\n\nlet addon: typeof Addon | null = null\n\nexport function loadNativeAddon(): typeof Addon {\n  if (addon) return addon\n\n  const platform = process.platform\n  const arch = process.arch\n\n  try {\n    if (platform === 'darwin' && arch === 'arm64') {\n      addon = require('@siafoundation/sia-storage-darwin-arm64')\n    } else if (platform === 'darwin' && arch === 'x64') {\n      addon = require('@siafoundation/sia-storage-darwin-x64')\n    } else if (platform === 'linux' && arch === 'x64') {\n      addon = require('@siafoundation/sia-storage-linux-x64-gnu')\n    } else if (platform === 'linux' && arch === 'arm64') {\n      addon = require('@siafoundation/sia-storage-linux-arm64-gnu')\n    } else if (platform === 'win32' && arch === 'x64') {\n      addon = require('@siafoundation/sia-storage-win32-x64-msvc')\n    }\n  } catch {}\n\n  if (!addon) {\n    throw new Error(\n      `@siafoundation/sia-storage: Native addon not found for ${platform}-${arch}. ` +\n        `Install @siafoundation/sia-storage-${platform}-${arch} or use the browser/WASM build.`,\n    )\n  }\n\n  return addon\n}\n","import { loadNativeAddon } from './load'\n\nconst addon = loadNativeAddon()\n\nexport const {\n  AppKey,\n  Builder,\n  Sdk,\n  PinnedObject,\n  PackedUpload,\n  ObjectEvent,\n  SharingKey,\n  KeyRecord,\n  SharedSdk,\n  generateRecoveryPhrase,\n  validateRecoveryPhrase,\n  setLogger,\n  encodedSize,\n} = addon\n\nexport type * from './napi.generated'\n\n/** Force-load the native addon to surface missing-binary errors at startup. */\nexport async function initSia(): Promise<void> {\n  loadNativeAddon()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACEA,IAAI,QAA6B;AAE1B,SAAS,kBAAgC;AAC9C,MAAI,MAAO,QAAO;AAElB,QAAM,WAAW,QAAQ;AACzB,QAAM,OAAO,QAAQ;AAErB,MAAI;AACF,QAAI,aAAa,YAAY,SAAS,SAAS;AAC7C,cAAQ,QAAQ,yCAAyC;AAAA,IAC3D,WAAW,aAAa,YAAY,SAAS,OAAO;AAClD,cAAQ,QAAQ,uCAAuC;AAAA,IACzD,WAAW,aAAa,WAAW,SAAS,OAAO;AACjD,cAAQ,QAAQ,0CAA0C;AAAA,IAC5D,WAAW,aAAa,WAAW,SAAS,SAAS;AACnD,cAAQ,QAAQ,4CAA4C;AAAA,IAC9D,WAAW,aAAa,WAAW,SAAS,OAAO;AACjD,cAAQ,QAAQ,2CAA2C;AAAA,IAC7D;AAAA,EACF,QAAQ;AAAA,EAAC;AAET,MAAI,CAAC,OAAO;AACV,UAAM,IAAI;AAAA,MACR,0DAA0D,QAAQ,IAAI,IAAI,wCAClC,QAAQ,IAAI,IAAI;AAAA,IAC1D;AAAA,EACF;AAEA,SAAO;AACT;;;AC9BA,IAAMA,SAAQ,gBAAgB;AAEvB,IAAM;AAAA,EACX;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,IAAIA;AAKJ,eAAsB,UAAyB;AAC7C,kBAAgB;AAClB;","names":["addon"]}

package/dist/index.node.d.ts

@@ -1,5 +1,14 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
 /**
  * An AppKey is used to sign requests to the indexer.
  *
@@ -38,8 +47,49 @@ export declare class Builder {
   responseUrl(): string
   /** Waits for the connection request to be approved. */
   waitForApproval(): Promise<void>
-  /** Registers the application with the indexer using the provided mnemonic. */
+  /**
+   * Returns whether the connect key the user approved with already has an
+   * account for this application. Only valid after `waitForApproval` has
+   * resolved.
+   *
+   * The connect key may have accounts under more than one recovery phrase.
+   * Use `matchesExistingAppKey` to check a particular phrase.
+   */
+  reconnecting(): boolean
+  /**
+   * Returns whether `mnemonic` derives an application key that is already
+   * registered with the indexer. Unlike `register`, the builder remains
+   * usable. Only valid after `waitForApproval` has resolved.
+   */
+  matchesExistingAppKey(mnemonic: string): Promise<boolean>
+  /**
+   * Registers the application with the indexer using the provided mnemonic.
+   *
+   * A different recovery phrase registers a new application key even when
+   * `reconnecting()` is true.
+   */
   register(mnemonic: string): Promise<Sdk>
+  /**
+   * Connects using a pre-authorized key, bypassing the interactive approval
+   * flow, and returns the SDK directly. `preAuthorizedKey` is the 32-byte
+   * pre-authorized private key seed; `mnemonic` derives the application key.
+   */
+  connectPreAuthorized(preAuthorizedKey: Buffer, mnemonic: string): Promise<Sdk>
+}
+
+/**
+ * The indexer's record for a sharing key, including how many objects it grants
+ * access to and how much space they use.
+ */
+export declare class KeyRecord {
+  /** The key this record describes. */
+  get key(): SharingKey
+  get description(): string
+  /**
+   * A snapshot of how many objects the key grants access to and how much
+   * space they use.
+   */
+  get stats(): KeyStats
 }
 
 /** An object event from the indexer. */
@@ -120,6 +170,8 @@ export declare class PinnedObject {
   id(): string
   /** Returns the total size of the object. */
   size(): bigint
+  /** Returns a new object truncated to the requested length. */
+  truncate(length: bigint): PinnedObject
   /** Returns the total encoded size after erasure coding. */
   encodedSize(): bigint
   /** Returns the slabs that make up the object. */
@@ -135,6 +187,23 @@ export declare class PinnedObject {
 }
 
 export declare class Sdk {
+  /** Creates a sharing key. Attach objects to it with `Sdk.shareObject`. */
+  createSharingKey(description: string, expiresAt?: Date | undefined | null): Promise<SharingKey>
+  /** Lists the account's sharing keys, most recently created first. */
+  sharingKeys(offset: number, limit: number): Promise<Array<KeyRecord>>
+  /** Fetches the indexer's record for a key, including its counts. */
+  sharingKey(key: SharingKey): Promise<KeyRecord>
+  /**
+   * Attaches an object to a sharing key, re-sealing its encryption keys under
+   * the key so recipients can decrypt it.
+   */
+  shareObject(key: SharingKey, object: PinnedObject): Promise<void>
+  /** Lists and decrypts the objects attached to a sharing key. */
+  sharedObjects(key: SharingKey, offset: number, limit: number): Promise<Array<PinnedObject>>
+  /** Detaches an object from a sharing key. */
+  unshareObject(key: SharingKey, id: string): Promise<void>
+  /** Revokes a sharing key, deleting it and detaching all of its objects. */
+  revokeSharingKey(key: SharingKey): Promise<void>
   /** Returns the application key used by the SDK. */
   appKey(): AppKey
   /**
@@ -181,13 +250,58 @@ export declare class Sdk {
   /** Returns the current account. */
   account(): Promise<Account>
   /** Creates a signed URL for sharing an object. */
-  shareObject(object: PinnedObject, validUntil: Date): string
+  objectShareUrl(object: PinnedObject, validUntil: Date): string
   /** Retrieves a shared object from a signed URL. */
-  sharedObject(sharedUrl: string): Promise<PinnedObject>
+  objectFromShareUrl(sharedUrl: string): Promise<PinnedObject>
   /** Pins an object to the indexer. */
   pinObject(object: PinnedObject): Promise<void>
 }
 
+/**
+ * A read-only SDK for the objects a sharing key grants access to.
+ *
+ * Unlike `Sdk`, it authenticates with a sharing key rather than an app key and
+ * cannot upload, pin, or delete. Downloads are paid for by the key's owner.
+ */
+export declare class SharedSdk {
+  /**
+   * Connects to `indexer_url` as the recipient of the sharing key derived
+   * from `seed`, the 32-byte seed the key's owner handed out.
+   */
+  static connect(indexerUrl: string, seed: Buffer): Promise<SharedSdk>
+  /** Fetches the sharing key's stats from the indexer. */
+  stats(): Promise<KeyStats>
+  /** Fetches and decrypts one object the key grants access to. */
+  object(id: string): Promise<PinnedObject>
+  /** Lists and decrypts a page of the objects the key grants access to. */
+  objects(offset: number, limit: number): Promise<Array<PinnedObject>>
+  /**
+   * Returns the hosts serving this key's objects. Mirrors `Sdk.hosts()` but
+   * is scoped to the sharing key, so the set is already limited to hosts
+   * holding its objects.
+   */
+  hosts(): Promise<Array<Host>>
+  /** Streams a shared object's data, paying hosts with the owner's tokens. */
+  download(object: PinnedObject, options?: DownloadOptions | undefined | null): ReadableStream
+}
+
+/**
+ * A sharing key, granting read-only access to the objects attached to it.
+ *
+ * It is just the credential; the operations that use it live on `Sdk`.
+ */
+export declare class SharingKey {
+  /** The key's public half, which identifies it on the indexer. */
+  get publicKey(): string
+  /**
+   * The 32-byte seed a recipient needs to read the key's objects. Pair it
+   * with the indexer url in `SharedSdk.connect`.
+   */
+  seed(): Buffer
+  /** Imports a sharing key from the 32-byte seed its owner handed out. */
+  static fromSeed(seed: Buffer): SharingKey
+}
+
 /** An account registered on the indexer. */
 export interface Account {
   accountKey: string
@@ -203,7 +317,7 @@ export interface Account {
 /** The protocol used in a network address. */
 export declare const enum AddressProtocol {
   SiaMux = 'SiaMux',
-  Quic = 'Quic'
+  Quic = 'Quic',
 }
 
 /** Application info. */
@@ -249,6 +363,20 @@ export interface Host {
   goodForUpload: boolean
 }
 
+/**
+ * A snapshot of what a sharing key grants access to. The counts reflect the
+ * moment the record was fetched, not a live view.
+ */
+export interface KeyStats {
+  objectCount: bigint
+  objectSize: bigint
+  pinnedData: bigint
+  pinnedSize: bigint
+  expiresAt?: Date
+  createdAt: Date
+  updatedAt: Date
+}
+
 /** A network address of a storage provider on the Sia network. */
 export interface NetAddress {
   protocol: AddressProtocol

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siafoundation/sia-storage",
-  "version": "0.0.14",
+  "version": "0.1.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -48,11 +48,11 @@
     "publish-npm": "bun run scripts/publish.ts"
   },
   "optionalDependencies": {
-    "@siafoundation/sia-storage-darwin-arm64": "0.0.14",
-    "@siafoundation/sia-storage-darwin-x64": "0.0.14",
-    "@siafoundation/sia-storage-linux-x64-gnu": "0.0.14",
-    "@siafoundation/sia-storage-linux-arm64-gnu": "0.0.14",
-    "@siafoundation/sia-storage-win32-x64-msvc": "0.0.14"
+    "@siafoundation/sia-storage-darwin-arm64": "0.1.0",
+    "@siafoundation/sia-storage-darwin-x64": "0.1.0",
+    "@siafoundation/sia-storage-linux-x64-gnu": "0.1.0",
+    "@siafoundation/sia-storage-linux-arm64-gnu": "0.1.0",
+    "@siafoundation/sia-storage-win32-x64-msvc": "0.1.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.12",