@invisible-labs/sdk 0.6.0-devnet.1

package/README.md

@@ -0,0 +1,210 @@
+# @invisible-labs/sdk
+
+Frontend-integration TypeScript SDK for the Invisible protocol.
+
+This package is the single programmatic entrypoint for every user and LP
+interaction with an attested Invisible coordinator. It is the contract defined
+in [docs/sdk-specification.md](../../docs/sdk-specification.md). The current
+build exposes both the functional normal-user pre-deposit request and the
+frontend coordinator facade.
+
+> Status: **frontend integration SDK**. The attested `/ws-noise` session,
+> normal-user contract request and coordinator session, and LP lifecycle helpers
+> are functional. Target surfaces that are not wired to the live coordinator
+> still throw `NotImplementedError`; no command fakes success.
+
+## Entrypoints
+
+| Import                        | Covers                                                |
+| ----------------------------- | ----------------------------------------------------- |
+| `@invisible-labs/sdk`         | `createSession`, attestation and coordinator controls |
+| `@invisible-labs/sdk/user`    | normal-user commands (private transfer)               |
+| `@invisible-labs/sdk/lp`      | liquidity-provider lifecycle                          |
+| `@invisible-labs/sdk/stats`   | actor-safe read projections                           |
+| `@invisible-labs/sdk/events`  | sync subscriptions                                    |
+| `@invisible-labs/sdk/storage` | storage adapters                                      |
+| `@invisible-labs/sdk/presets` | optional Invisible coordinator endpoint presets       |
+
+Each actor entrypoint is independently importable; pulling one in must not drag
+the others into a consumer bundle.
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the layered module map (mermaid).
+
+## Private-transfer amount limits
+
+Use the public user-entry constants for inclusive preflight validation. Values
+are expressed in lamports, matching the `amountLamports` request field.
+
+```ts
+import { MAX_ENTRY_AMOUNT_LAMPORTS, MIN_ENTRY_AMOUNT_LAMPORTS } from "@invisible-labs/sdk/user";
+
+const isValidEntryAmount = (amountLamports: number) =>
+  amountLamports >= MIN_ENTRY_AMOUNT_LAMPORTS && amountLamports <= MAX_ENTRY_AMOUNT_LAMPORTS;
+```
+
+## Quickstart
+
+```ts
+import { createCoordinatorSession } from "@invisible-labs/sdk/user";
+
+const coordinator = {
+  endpoints: [
+    /* CoordinatorEndpoint[] - supply your own, or use @invisible-labs/sdk/presets */
+  ],
+};
+
+const user = createCoordinatorSession({ coordinator });
+
+await user.runSwap({ amountLamports: 3_000_000_000, payoutSpec });
+```
+
+The quickstart above is the full normal-user transfer path. For a bot or server
+integration that owns the deposit step, use `contractRequest` from
+`@invisible-labs/sdk/user`. It resolves after durable delegation and returns
+`swapId`, `depositAddress`, `depositExpiresAtMs`, `syncSecret`, and the generated
+Recovery Code before waiting for a deposit. Set `payoutPolicy.totalDeadlineMs`
+to `0` for instant payout, or to `3_600_000`, `86_400_000`, or `604_800_000`
+milliseconds for the supported 1-hour, 24-hour, or 7-day scheduled windows.
+
+## What is real vs NO-OP today
+
+Real and usable now:
+
+- `createSession` opens a live WebSocket, runs Noise XX, verifies TDX
+  attestation, and returns an attested `Session`.
+- `createCoordinatorSession` in `@invisible-labs/sdk/user` drives the normal-user
+  contract, sync, refund-withdrawal, and event flow used by the web app.
+- The functional `contractRequest`, `requestRefund`, and `sync` exports in
+  `@invisible-labs/sdk/user` send the same normal-user protocol commands on a
+  caller-owned attested session.
+- `createLpLifecycleClient` and the LP free functions in `@invisible-labs/sdk/lp`
+  drive position open/recover, DKG, funding, refill, withdrawal, confirmation,
+  and listing. Lower-level LP coordinator and DKG helpers remain available.
+- Input validation: `PayoutPolicy` and LP plan checks throw `PolicyValidationError`;
+  LP client-side lifecycle states throw `LpLifecycleError`.
+- The closed `InvisibleError` taxonomy and `normalizeError`.
+- `coordinator.endpoints`, `attestation.current` / `policy` (read-only).
+- `stats.derivedRefundableLamports` (pure local computation).
+- `inMemoryStorage`, `browserStorage`, `extensionStorage`; the `presets`
+  endpoint helpers.
+- `presets.invisibleDevnet(approvedBinaryHash)` targets the public devnet through
+  the hardened Azure coordinator in prod mode with the release MRTD, Intel root,
+  MAA, and exact coordinator binary hash pins. The approved 64-hex binary hash
+  is required at preset construction; no unapproved default is embedded.
+
+Deferred (throws `NotImplementedError` until each target surface is finalized):
+
+- Spec-level user free functions other than the live `contractRequest`,
+  `requestRefund`, and `sync` functions, actor-safe stats, and `events`
+  subscriptions when they are not the frontend-facing coordinator helpers
+  listed above.
+- Server-HKDF storage. The current web app keeps its local recovery material in
+  its persisted app store; SDK consumers can choose their own storage controls.
+
+Before public npm distribution, the remaining deferred functions will either be
+wired to the coordinator helpers or removed from the published surface.
+
+## Recovery material and storage
+
+The SDK does not yet persist recovery material automatically from
+`createSession`. Consumers that need restart or tab-close recovery must keep the
+relevant values themselves, using SDK storage helpers or their own storage layer:
+
+| Material                | Needed for                                       | Current guidance                                                                                                                                                    |
+| ----------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `swapId` + `syncSecret` | Re-sync a private-transfer status view.          | `contractRequest` returns both values and supports `onSyncSecretReady({ secretHex })`; store them before asking the user to deposit.                                |
+| User Recovery Code      | Request an origin-bound private-transfer refund. | Persist `onRecoveryCodeReady({ codeHex })` immediately, or pass caller-managed recovery material. Products with stricter local-storage requirements can encrypt it. |
+| LP Position Code        | Recover and operate an LP position.              | Treat like a seed phrase. The SDK keeps derived LP auth only in memory.                                                                                             |
+
+The Invisible web app currently persists private-transfer `refundCode` and
+`syncSecret` locally so users can resume flows. That is the current product
+tradeoff. Integrators can use `browserStorage` or `extensionStorage` as local
+byte stores, or they can pre-encrypt/wrap values before storing them if their
+product requires that.
+
+Server integrations can keep raw recovery material in their own database/vault,
+or derive material from a master secret with domain-separated HKDF. For
+pre-acceptance material such as `syncSecret`, use a stable context available
+before the coordinator receives `sync_commitment`; `swapId` is only available
+after acceptance.
+
+## Not in this SDK
+
+Protocol-fee (admin) payout is deliberately **out of scope** for the SDK. It
+lives in a separate, fully isolated, non-public admin frontend. See
+[ADR-0120](../../docs/adr/0120-protocol-fee-payout-lives-in-isolated-admin-frontend.md).
+
+## Packaging and publishing
+
+The package is bundled with [tsup](./tsup.config.ts) into a **self-contained
+artifact** so it can be installed by an external consumer that has none of this
+monorepo's workspace links:
+
+- The three workspace-internal packages (`@invisible/shared`, `protocol`,
+  `frost`) are `file:` deps that npm does not rewrite on publish. They are
+  **inlined** into `dist` (`noExternal`) and live in `devDependencies`, so the
+  published runtime `dependencies` contain zero `file:` specifiers.
+- The **FROST wasm** is inlined into the bundle. The SDK uses a swappable wasm
+  loader: from source the web app and vitest use
+  [`frostWasm.dev.ts`](./src/frost/frostWasm.dev.ts) (Vite-friendly asset URL /
+  Node `file:` read), while tsup swaps in
+  [`frostWasm.bundled.ts`](./src/frost/frostWasm.bundled.ts) (esbuild `binary`
+  loader -> inlined bytes) for the published artifact, so there is no runtime
+  asset path or `import.meta.url` resolution to break in a consumer's bundler.
+- Only published third-party packages (`ajv`, `@peculiar/x509`, `@stablelib/*`)
+  stay external and are declared in `dependencies`.
+
+```bash
+npm run prepare:frost   # build or restore frost/pkg for SDK source/bundling
+npm run build           # tsup: bundled dist + .d.ts
+npm run verify:exports  # assert exports, bundled dist, and FROST wasm init
+npm run smoke:prod-attestation -- --host tee-azure.invisible.exchange --mrtd <96-hex> --binary-hash <64-hex-approved> --azure-maa-issuer <https-url> --azure-maa-jwks-url <https-url> --azure-maa-policy-hash <base64url>
+npm run smoke:publish   # publish -> install -> typecheck -> import on Verdaccio
+npm run publish:public:noop # credential-free public manifest validation
+VERSION=<version> NPM_DIST_TAG=devnet npm run publish:public -- --confirm @invisible-labs/sdk@<version>
+```
+
+The SDK `build` and `prepack` scripts run `prepare:frost` first, so direct
+package builds, `smoke:publish`, and `publish:private` are hermetic from a clean
+checkout. In GitHub CI, the first SDK preparation uses the clean FROST WASM
+build path, then later SDK build/pack guards in the same job reuse that prepared
+artifact. From the repository root, `npm run test:sdk` uses the same SDK
+preparer before typecheck, tests, conformance, bundle, export check, and pack
+dry-run. The export check also rejects unresolved workspace imports, rejects the
+source-only FROST wasm loader path in built `dist`, and instantiates the bundled
+FROST wasm once through `dkgRound1`.
+`smoke:prod-attestation` also builds first, then verifies a live production
+coordinator with `createSession`, `requiredMode=prod`, the supplied MRTD and
+approved binary hash pins, Azure MAA pins, and mandatory DCAP collateral.
+
+### Publish flow (Verdaccio -> GitHub Packages -> npmjs)
+
+The package manifest is public-publishable, but public npmjs publication remains
+manual. Private GitHub Packages publishing still stages a versioned copy under
+`@invisible-labs/sdk`. The progression, each step gated on the previous one
+passing:
+
+1. **Local (Verdaccio).** `npm run smoke:publish` boots a throwaway local
+   registry, stages a publishable copy (private flag flipped, unique test
+   version), publishes it, then installs, typechecks, and imports it from a
+   clean consumer project. Zero external footprint. Use this to confirm the
+   tarball works.
+2. **Private remote (GitHub Packages).** Intermediate validation against a real
+   remote without going public. The executable path is `publish:private`, which
+   stages the workspace package as `@invisible-labs/sdk` because GitHub Packages
+   requires the package scope to match the `Invisible-Labs` org. Authenticate
+   with a PAT or `GITHUB_TOKEN` with `write:packages`, then run:
+   ```bash
+   NODE_AUTH_TOKEN=<token> VERSION=0.0.1 npm run publish:private
+   ```
+   The release workflow runs this path automatically for SDK-relevant changes
+   and publishes `<package version>-dev.<run_number>.<run_attempt>` with the
+   private `dev` dist-tag.
+   Consumers install the private `dev` dist-tag and import `@invisible-labs/sdk`
+   directly, with no npm alias; see [`PUBLISHING.md`](./PUBLISHING.md).
+3. **Public validation no-op.** Production promotion runs `publish:public:noop`
+   with the exact `packages/sdk` version. This verifies the public-publishable
+   manifest without npmjs credentials or publication.
+4. **Public (npmjs).** After the release commit is on `main`, an authorized npm
+   publisher runs the manual npmjs publish flow in [`PUBLISHING.md`](./PUBLISHING.md).
+   CI does not publish to npmjs.