@dignetwork/dig-sdk 0.2.0 → 0.2.1

package/vendor/PROVENANCE.md

@@ -1,102 +0,0 @@
-# Vendored artifacts — provenance
-
-These files are vendored copies of the DIG **read-crypto** WASM (`dig_client`) and its
-wasm-bindgen ES-module glue. They are **byte-identical** to the artifacts shipped by the rest of
-the DIG ecosystem — the `dig-chrome-extension`, the `dig-companion`, and `hub.dig.net` all run the
-**same** `dig_client` WASM, which is built from `chip35_dl_coin`'s `dig-client-wasm` crate.
-
-Vendoring them lets the SDK run the **same** verify + decrypt read path those clients use, in
-either the browser or Node, with no network round-trip for the crypto.
-
-| File | Source (in the dig_ecosystem monorepo) | Notes |
-|---|---|---|
-| `dig_client.mjs` | `modules/dig-companion/node/src/vendor/dig_client.mjs` (← `dig-chrome-extension/dig_client.js`) | wasm-bindgen ES-module glue. Copied verbatim, `.mjs` so Node loads it as an ES module. No code changes. |
-| `dig_client_bg.wasm` | `modules/dig-companion/node/src/vendor/dig_client_bg.wasm` (← `dig-chrome-extension/dig_client_bg.wasm`) | The read-crypto WASM binary. Copied verbatim. |
-| `dig_client.d.ts` | `modules/hub.dig.net/apps/web/public/dig-client/dig_client.d.ts` | The WASM's TypeScript surface. Copied verbatim. |
-
-## Subresource Integrity (SRI)
-
-`dig_client_bg.wasm` SHA-256 (lowercase hex):
-
-```
-ff486be806f908a2a90780e499a04dbd34e10e3b97be0470cb9ee841a1e49e77
-```
-
-This is the **same digest** asserted by:
-
-- `dig-chrome-extension/background.js` → `DIG_CLIENT_WASM_SHA256`
-- `hub.dig.net` `sw.js` and `apps/web/lib/dig-client.js`
-- `dig-companion` `node/src/dig-client.js`
-
-The SDK's loader (`src/loader.ts` → `DIG_CLIENT_WASM_SHA256`) re-verifies this digest at load time
-and **fails closed** if it does not match — a tampered or wrong WASM refuses to run unverified
-crypto, exactly as the extension/companion/hub do.
-
-## Why vendor instead of depend on `@dignetwork/chip35-dl-coin-wasm`?
-
-The published `@dignetwork/chip35-dl-coin-wasm` package exposes **only the CHIP-0035 spend
-builder** (mintStore, meltStore, updateStoreMetadata, …) — it does **not** export the read-crypto
-(retrievalKey / deriveKey / verifyInclusion / decryptChunk). The read-crypto is a **separate**
-wasm artifact (`dig_client`) built from the same repo. So the SDK:
-
-- **depends on** `@dignetwork/chip35-dl-coin-wasm` for spends (re-exported via `@dignetwork/dig-sdk/spend`), and
-- **vendors** the `dig_client` read-crypto WASM here (SRI-pinned) for `DigClient`.
-
-## Updating
-
-If the canonical `dig_client` WASM changes (a new `chip35_dl_coin` release → extension/companion
-bump), re-copy `dig_client.mjs` + `dig_client_bg.wasm` (+ `dig_client.d.ts`) from the ecosystem,
-recompute the SHA-256 of `dig_client_bg.wasm`, and update the `DIG_CLIENT_WASM_SHA256` constant in
-`src/loader.ts` **and** the digest above. Keep this digest in lock-step with the
-extension/companion/hub.
-
-## Publishing the read-crypto wasm — `@dignetwork/dig-client` (roadmap #16)
-
-The read-crypto wasm is currently **vendored** in *every* consumer (this SDK under `vendor/`, plus
-`dig-chrome-extension`, `dig-companion`, and `hub.dig.net`). Each hand-copies the same
-`dig_client_bg.wasm` + glue + `.d.ts` and re-asserts the same SHA-256. That is brittle: a wasm bump
-means re-copying into four+ repos and hoping the digests stay aligned.
-
-**The fix (#16): publish the wasm once as `@dignetwork/dig-client`, so nobody vendors it again.**
-
-### What dig-sdk ships TODAY (the immediate win — no cross-repo dependency)
-
-`@dignetwork/dig-sdk/dig-client` (built from `src/dig-client-entry.ts`) is the clean, publishable
-read-crypto subpath: `DigClient`, the SRI-pinned `loadDigClientWasm`/`configureWasm`,
-`DIG_CLIENT_WASM_SHA256`, and the pure URN helpers, all with `.d.ts`. It runs over the wasm vendored
-here. **The hub and `dig-embed.js` can already depend on `@dignetwork/dig-sdk/dig-client` instead of
-hand-copying the wasm** — that removes most of the duplication now, with the digest enforced in one
-place (`src/loader.ts`).
-
-### What must be published in the CANONICAL repo (the cross-repo step — `chip35_dl_coin`)
-
-The wasm is built from `chip35_dl_coin`'s `dig-client-wasm` crate. To stop vendoring entirely, that
-repo must publish an npm package (proposed name `@dignetwork/dig-client`) containing:
-
-1. `dig_client_bg.wasm` — the read-crypto binary (the artifact this `vendor/` copies verbatim).
-2. `dig_client.mjs` — the wasm-bindgen ES-module glue.
-3. `dig_client.d.ts` — the TypeScript surface.
-4. A package `exports` map so web + Node both resolve the wasm + glue, and an integrity note
-   (the SHA-256) so consumers can SRI-pin it — the **same** digest pinned here.
-
-**Versioning story:** the npm package version tracks the `dig-client-wasm` crate version; each
-release records the wasm SHA-256 in its README/CHANGELOG. The digest — not the npm semver — remains
-the canonical trust anchor: consumers pin and verify the SHA-256 regardless of the package version,
-so a wrong/tampered artifact fails closed even if the version "looks right".
-
-### Wiring dig-sdk to the published package (when it exists) — without breaking the fallback
-
-Once `@dignetwork/dig-client` is published, the ONLY change in dig-sdk is in **`src/loader.ts`**:
-resolve the glue + wasm bytes from the published package (e.g. `import.meta.resolve`/a dep import)
-*before* falling back to the bytes under `vendor/`. The SRI check (`DIG_CLIENT_WASM_SHA256`) is
-unchanged and still gates both paths, so:
-
-- the **public surface of `@dignetwork/dig-sdk/dig-client` does not change** — consumers are
-  unaffected;
-- the **vendored fallback stays intact** — if the dependency is absent (or its bytes don't match the
-  pinned digest), the loader uses `vendor/` exactly as today.
-
-> **TODO (#16, cross-repo):** publish `@dignetwork/dig-client` from `chip35_dl_coin`'s
-> `dig-client-wasm` crate (items 1–4 above), then update `src/loader.ts` to prefer it with the
-> `vendor/` fallback, keeping `DIG_CLIENT_WASM_SHA256` in lock-step. Until then, the vendored path
-> is the source of truth and `@dignetwork/dig-sdk/dig-client` is the consumable entry.

package/vendor/dig_client.d.ts

@@ -1,150 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-
-/**
- * Decrypt a SINGLE GCM-SIV chunk under an explicit 32-byte `key` (hex). Returns
- * the plaintext bytes. A failed tag check (tamper / wrong key) is an error.
- * Low-level escape hatch; most callers want `decryptResource`.
- */
-export function decryptChunk(key_hex: string, ciphertext: Uint8Array): Uint8Array;
-
-/**
- * Full read pipeline for a resource's served ciphertext (Digstore §9.3 + §11),
- * returning the decrypted plaintext bytes. Steps, in order (gate-then-decrypt):
- *
- * 1. **Integrity gate** — verify the served bytes' merkle inclusion against the
- *    chain-anchored `trusted_root_hex` (proof base64 from `X-Dig-Inclusion-Proof`).
- * 2. **Confidentiality** — derive the URN key, split the PLAIN-concatenated
- *    chunk ciphertexts by `chunk_lens` (the per-chunk CIPHERTEXT byte lengths in
- *    order; D5/C9 — NO length framing on the wire), and AES-256-GCM-SIV-open
- *    each, concatenating plaintext in order.
- *
- * `chunk_lens` may be empty for the common single-chunk resource (the whole blob
- * is one GCM-SIV ciphertext). They MUST sum to `ciphertext.len()`.
- */
-export function decryptResource(store_id_hex: string, resource_key: string, ciphertext: Uint8Array, proof_b64: string, trusted_root_hex: string, salt_hex?: string | null, chunk_lens?: Uint32Array | null): Uint8Array;
-
-/**
- * Convenience wrapper around [`decrypt_resource`] returning the plaintext as a
- * UTF-8 string (for HTML/text resources rendered into the sandbox iframe).
- */
-export function decryptResourceToText(store_id_hex: string, resource_key: string, ciphertext: Uint8Array, proof_b64: string, trusted_root_hex: string, salt_hex?: string | null, chunk_lens?: Uint32Array | null): string;
-
-/**
- * Derive the 32-byte AES-256 content key for a resource (Digstore §11.1/§11.4),
- * returned as lowercase hex. `salt_hex` is the 32-byte private-store secret salt
- * (omit / pass `null` for public stores). Mixing in a wrong/missing salt yields
- * a wrong key whose GCM-SIV tag will not verify.
- */
-export function deriveKey(store_id_hex: string, resource_key: string, salt_hex?: string | null): string;
-
-/**
- * Seal a resource's plaintext as ONE AES-256-GCM-SIV blob under its per-URN key — the inverse of
- * the read path's chunk decrypt. The browser uses this to PRE-ENCRYPT a file before upload so the
- * server compiles the `.dig` from ciphertext alone (it never sees plaintext or any key). The
- * output is the resource's whole-file ciphertext; `digstore compile --pre-encrypted` stores it
- * verbatim as the single chunk, and `decryptResource`/`decryptChunk` under the same URN reverses
- * it. `salt_hex` is the store's secret salt for a private store (omit for a public store).
- */
-export function encryptResource(store_id_hex: string, resource_key: string, plaintext: Uint8Array, salt_hex?: string | null): Uint8Array;
-
-/**
- * On module load, install a `globalThis.digClient` object exposing the read
- * API, so non-bundler consumers (the standalone usercontent loader) can call
- * `globalThis.digClient.verifyInclusion(...)` / `.decryptResourceToText(...)`
- * after the wasm initializes. ES-module consumers can instead import the named
- * functions directly. Idempotent and best-effort (no-op if `globalThis` lacks
- * `Object`, e.g. in a non-browser host).
- */
-export function install_global(): void;
-
-/**
- * Reconstruct the canonical ROOT-INDEPENDENT resource URN string for a store +
- * resource key: `urn:dig:chia:<store_id>[/<resource_key>]`. An empty resource
- * key resolves to the §8.5 default view `index.html`. This is the form whose
- * SHA-256 is the retrieval key and whose bytes seed the AES key.
- */
-export function reconstructUrn(store_id_hex: string, resource_key: string): string;
-
-/**
- * Reconstruct a ROOT-PINNED display URN: `urn:dig:chia:<store_id>:<root>/<key>`.
- * Useful for sharing a URN bound to a specific generation; the retrieval/AES
- * keys still use the rootless form (`reconstructUrn`).
- */
-export function reconstructUrnWithRoot(store_id_hex: string, root_hex: string, resource_key: string): string;
-
-/**
- * `retrieval_key = SHA-256(canonical_rootless_urn)`, lowercase hex (Digstore
- * §7.3; API §17). The CDN is addressed by this hash; the URN itself is never
- * sent. An empty resource key resolves to `index.html`.
- */
-export function retrievalKey(store_id_hex: string, resource_key: string): string;
-
-/**
- * Verify that `ciphertext` is included under `trusted_root_hex` via the base64
- * merkle `proof_b64` (Digstore §9.3; API §18). Returns `true` on success and
- * `false` on ANY verification failure (tampered bytes, non-chaining path, or a
- * root mismatch / decoy) — a decoy or wrong-store response returns `false`
- * rather than throwing, so a caller can treat it as "not found in this store".
- * Throws only on malformed inputs (bad base64 / hex / proof encoding).
- */
-export function verifyInclusion(ciphertext: Uint8Array, proof_b64: string, trusted_root_hex: string): boolean;
-
-/**
- * Library version (matches the crate version), for SRI / compatibility checks.
- */
-export function version(): string;
-
-export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
-
-export interface InitOutput {
-    readonly memory: WebAssembly.Memory;
-    readonly decryptChunk: (a: number, b: number, c: number, d: number) => [number, number, number, number];
-    readonly decryptResource: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number) => [number, number, number, number];
-    readonly decryptResourceToText: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number) => [number, number, number, number];
-    readonly deriveKey: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
-    readonly encryptResource: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number, number];
-    readonly install_global: () => void;
-    readonly reconstructUrn: (a: number, b: number, c: number, d: number) => [number, number, number, number];
-    readonly reconstructUrnWithRoot: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
-    readonly retrievalKey: (a: number, b: number, c: number, d: number) => [number, number, number, number];
-    readonly verifyInclusion: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
-    readonly version: () => [number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__hc605e6b36f32dd24: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number) => [number, number, number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__h58cab831a65fd6c8: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number) => [number, number, number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__h68a3f7e1b7047a46: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__h36771739d8dc18ae: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__hd4233470ad4ef59f: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__h61ffc6ac64470c43: (a: number, b: number) => [number, number];
-    readonly __wbindgen_exn_store: (a: number) => void;
-    readonly __externref_table_alloc: () => number;
-    readonly __wbindgen_externrefs: WebAssembly.Table;
-    readonly __wbindgen_destroy_closure: (a: number, b: number) => void;
-    readonly __wbindgen_malloc: (a: number, b: number) => number;
-    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
-    readonly __externref_table_dealloc: (a: number) => void;
-    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
-    readonly __wbindgen_start: () => void;
-}
-
-export type SyncInitInput = BufferSource | WebAssembly.Module;
-
-/**
- * Instantiates the given `module`, which can either be bytes or
- * a precompiled `WebAssembly.Module`.
- *
- * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
- *
- * @returns {InitOutput}
- */
-export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
-
-/**
- * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
- * for everything else, calls `WebAssembly.instantiate` directly.
- *
- * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
- *
- * @returns {Promise<InitOutput>}
- */
-export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;