diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..c8c54c04 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,239 @@ +# Project Overview + +`wallet-sdk` (`@docknetwork/wallet-sdk`) is Truvera's identity wallet SDK — a library (not a +deployed service) that lets a host app receive, store, and manage verifiable credentials. It is +an npm-workspaces monorepo (`packages/*`) versioned with Lerna, built on TypeScript/JavaScript +with Babel and Rollup, tested with Jest and Playwright. Each `packages/*` workspace publishes +independently to npm, most as their own `@docknetwork/wallet-sdk-*` package (the exception is +`wallet-edv-storage`, published as `@docknetwork/wallet-edv-storage`); there is no single bundled +artifact. See the [README](README.md) for the supported platforms and a usage example. + +## Repository Structure + +- `packages/` — the publishable workspaces; see the **Packages** table below. +- `examples/` — standalone example apps (React Native, web, Node, Angular, Flutter, Swift, a + WebView server) that consume the published packages. Not npm workspaces of the root. +- `integration-tests/` — cross-package Jest suites run against real/staging services + (`jest.config.e2e.js`). +- `docs/` — hand-written guides (getting started, cloud wallet, delegation, biometric plugin, + ecosystem tools) plus a generated `docs/api/` reference. +- `scripts/` — repo-level build/test helpers (`build.sh`, `test-ci.sh`, `fix-deps.sh`, + `fix-build-imports.js`). +- `.github/workflows/` — CI: lint/unit test, integration tests, per-example CI, npm publish, npm + audit, docs deploy. + +## Packages + +| Name | Purpose | +|---|---| +| `packages/core` | Wallet orchestration — wallet lifecycle, credential/DID/message providers, verification controller. | +| `packages/wasm` | Crypto and blockchain integration layer (Cheqd, credential-sdk, OID4VCI, SD-JWT, delegation engine). Most other packages sit on top of it, directly or transitively — `dids`, `request-logger`, and `wallet-edv-storage` are the exceptions (no wasm dependency). | +| `packages/data-store` | Storage interface/types and a reference `DataStore` implementation. | +| `packages/data-store-typeorm` | TypeORM-backed persistent storage backend (used by `react-native`, `cli`). | +| `packages/data-store-web` | Browser storage backend (used by `web`). | +| `packages/dids` | `did:key` resolution helpers. | +| `packages/react-native` | React Native bindings — bundles the SDK into a WebView-hosted JS bundle. Consumed externally by `dock-app` (see Architecture Notes). | +| `packages/web` | Browser UMD/ESM bundle of the SDK for non-React-Native web wallets. | +| `packages/cli` | Node CLI for exercising the SDK (BBS/revocation flows) via `ts-node`. | +| `packages/relay-service` | DIDComm relay client used for message-based credential exchange. | +| `packages/wallet-edv-storage` | Encrypted Data Vault storage adapter. Has no real tests — see Testing Strategy. | +| `packages/request-logger` | Small HTTP request-logging utility. | + +`packages/scripts` and `packages/transactions` contain no `package.json` (only stray +`node_modules`) — they are not active workspaces; TODO confirm with maintainers whether they +should be removed. + +Package purposes above are current as of this writing — read each package's own `package.json` +for its exact dependencies and scripts rather than assuming this table stays in sync. + +## Build & Development Commands + +```bash +# Install (patches deps and builds via postinstall — see scripts/fix-deps.sh) +npm install +``` + +```bash +# Build all publishable packages, in dependency order (see scripts/build.sh) +npm run build + +# Unit tests (root Jest run across all packages/**/*.test.{js,ts}, with coverage in CI) +npm test +npm run test:ci + +# Integration tests (jest.config.e2e.js, against real/staging services — needs API keys) +npm run test:integration + +# Lint / format +npm run lint +npm run lint:fix +npm run format +``` + +```bash +# Package-scoped work, e.g.: +npm run build -w @docknetwork/wallet-sdk-core +npm test -w @docknetwork/wallet-sdk-wasm +``` + +```bash +# Maintenance +npm run bump-version # lerna version --no-private (see Working on Changes) +npm run docs # regenerate packages/core's jsdoc reference +``` + +Node/npm versions are not pinned via `engines`/`packageManager` in root `package.json` — CI +workflows disagree (`lint-and-test.yml` and `integration-tests.yaml` use Node 24.14.0; +`npm-publish.yml` and the example-app workflows use 20.2.0). The README states 20.2.0 as the +minimum. Check the specific workflow file rather than assuming one version. + +## Code Style & Conventions + +- **Linting:** a single root `.eslintrc.js` (`@react-native-community` config) covers all + packages; run via `npm run lint` (`eslint './packages/**/*.js'`). +- **Formatting:** Prettier (`.prettierrc.js`: single quotes, trailing commas, `arrowParens: + 'avoid'`), scoped to `src/**/*.{js,json}` via `npm run format`. +- **TypeScript:** a root `tsconfig.json` sets shared compiler options; packages that build with + `tsc` add their own `tsconfig.build.json`. +- **Async style:** prefer `async/await` with `try/catch` over `.then/.catch` chains. +- **Commit messages:** no single enforced format in history — most are short imperative + sentences (`Fix typo`, `Regen package lock`), some longer when a fix needs context. No stated + `Co-Authored-By` convention — ask the user if unsure. + +## Naming Conventions + +- **Packages:** `@docknetwork/wallet-sdk-` under `packages/` (e.g. + `packages/data-store-typeorm` → `@docknetwork/wallet-sdk-data-store-typeorm`); the one exception + is `packages/wallet-edv-storage`, published as `@docknetwork/wallet-edv-storage`. +- **Providers/controllers (core):** `-provider.ts` / `-controller.ts` exporting a + factory or class for that domain, e.g. `packages/core/src/credential-provider.ts`, + `packages/core/src/verification-controller.ts`. +- **Tests:** co-located `.test.ts` (or `.test.js`) beside the source, e.g. + `packages/core/src/wallet.test.ts`; some packages instead use a `__tests__/` directory (e.g. + `packages/data-store/src/__tests__/index.test.ts`). + +## Architecture Notes + +```mermaid +flowchart TD + dids[dids] + wasm[wasm] --> dids + core[core] --> wasm + data-store[data-store] --> wasm + data-store-typeorm[data-store-typeorm] --> wasm + data-store-web[data-store-web] --> wasm + relay-service[relay-service] --> wasm + cli[cli] --> core + cli --> data-store + react-native[react-native] --> core + react-native --> data-store-typeorm + react-native --> dids + react-native --> wasm + web[web] --> core + web --> data-store + web --> data-store-web + + dockapp[dock-app
external repo] -.build-sdk.-> react-native +``` + +**Data flow.** `wasm` wraps the Cheqd blockchain SDK, credential-sdk, and OID4VCI/SD-JWT +libraries and is the dependency most other packages sit on, directly or transitively — `dids`, +`request-logger`, and `wallet-edv-storage` are standalone leaf utilities with no wasm dependency. +`core` builds the wallet API +(documents, DIDs, messages, verification) on top of `wasm` and a storage backend. Storage is +pluggable: `data-store` defines the interface, `data-store-typeorm` and `data-store-web` are +concrete backends. `react-native` and `web` are platform bindings that assemble `core` plus a +storage backend into a distributable bundle; `cli` does the same for a Node environment. The +external `dock-app` repo consumes `packages/react-native`'s built bundle via its own +`build-sdk` script (`../wallet-sdk/packages/react-native/bundler/build-and-copy.js`) — do not +edit `dock-app` from here. + +## Testing Strategy + +- **Unit:** Jest, configured at the root (`jest.config.js`) and run across all packages in one + pass (`npm test` / `npm run test:ci` for the coverage run CI uses). Coverage floors are in + `coverage-thresholds.json` (local circuit breaker) and enforced on PRs by Codecov per + `codecov.yml` — read those files rather than copying the numbers, they are raised over time. + `packages/wallet-edv-storage` declares `"unit:test": "echo no tests"` — treat it as a coverage + gap. +- **Integration/E2E:** `jest.config.e2e.js` runs everything under `integration-tests/` against + real or staging services (`npm run test:integration`); see `.github/workflows/integration-tests.yaml` + for the required secrets. +- **`packages/web`** and **`packages/react-native`**'s `test:bundle*` scripts use Playwright, not + Jest, and are not part of the root Jest run. +- **CI:** `.github/workflows/lint-and-test.yml` is the core PR pipeline (build, lint, test, + Codecov upload). See `.github/workflows/` for the full set, including per-example CI + (`react-native-example-ci.yaml`, `web-wallet-e2e-tests.yml`, `angular-example-ci.yml`, + `nodejs-example-ci.yml`, `webview-server-ci.yml`). + +## Security & Compliance + +- **Secrets:** `.env.example` documents the local env vars (encryption key, relay service URL, + API keys). Real `.env` files are git-ignored; never commit or log one. +- **Dependency scanning:** `.github/workflows/npm-audit.yml` runs `npm audit --audit-level=critical` + plus a `license-checker` gate against AGPL/GPL, weekly and on `package-lock.json` changes. +- **License:** `LICENSE` is the Dock Labs Non-Production License (DL-NPL) — production use + requires a Dock Labs subscription/MSA; non-production dev and testing with fictitious data is + permitted. Not an OSI open-source license — check with maintainers before treating it as one. + +## Working on Changes + +- Grep first: find the closest existing provider/service/backend under the relevant package and + mirror its structure before adding a new one. +- **Cross-package change checklist:** if you touch a shared contract (e.g. `wasm`'s exports, the + `DataStore` interface in `data-store`), update every consuming package + (`core`, `data-store-typeorm`/`data-store-web`, `react-native`/`web`/`cli`) in the same change, + and bump the internal `dependencies`/`peerDependencies` version ranges in their `package.json`s + if a breaking change is intended. +- **Publishing:** package versions are bumped together via `npm run bump-version` + (`lerna version --no-private`); `.github/workflows/npm-publish.yml` then `npm publish`s each + directory under `packages/` independently on a GitHub release — Lerna is not used to publish. +- Prefer small, incremental changes. If a change spans more than one package, say so and confirm + scope before proceeding. + +## Agent Guardrails + +The agent **may**, without asking: +- Add tests, fix bugs, or extend a provider/service/backend that follows an existing pattern + within a single package. +- Refactor within a single package when behaviour is unchanged. + +The agent **must ask** before: +- Changing a cross-package contract (`wasm`'s public exports, the `DataStore` interface, any + package's `dependencies`/`peerDependencies` version). +- Adding a new runtime dependency, or bumping one shared across packages. +- Running `npm run bump-version` or anything that touches `packages/*/package.json` versions. +- Renaming or restructuring `packages/*` directories, or touching `examples/`. + +The agent must **never** modify without explicit direction: +- Build/coverage output: `lib/`, `dist/`, `coverage/`, `reports/`, `node_modules/`. +- `package-lock.json` outside of an intentional dependency change. +- `.github/workflows/npm-publish.yml` and other release-triggering workflows. + +## Extensibility Hooks + +- **New package:** add a directory under `packages/` with its own `package.json`, normally + named `@docknetwork/wallet-sdk-` (see the Naming Conventions exception above); the root + `workspaces: ["packages/*"]` glob picks it up + automatically. Add it to `scripts/build.sh` if it needs to build before packages that depend on + it, and to `.github/workflows/npm-publish.yml`'s publish loop if it should be published. + +## Reference Examples + +- **Provider (core domain logic):** `packages/core/src/credential-provider.ts` +- **Storage backend (TypeORM):** `packages/data-store-typeorm/src/index.ts` +- **Package-scoped Jest test:** `packages/core/src/wallet.test.ts` +- **Rollup-built package:** `packages/relay-service/rollup.config.mjs` + +## Further Reading + +- Per-package guides: [core](packages/core/AGENTS.md), [wasm](packages/wasm/AGENTS.md), + [data-store-typeorm](packages/data-store-typeorm/AGENTS.md), + [react-native](packages/react-native/AGENTS.md), [cli](packages/cli/AGENTS.md). +- [README.md](README.md) — install/usage quickstart. +- [lerna.json](lerna.json) — Lerna config (versioning only, see Working on Changes). +- [jest.config.js](jest.config.js) / [jest.config.e2e.js](jest.config.e2e.js) — unit vs. + integration test config. +- [coverage-thresholds.json](coverage-thresholds.json) / [codecov.yml](codecov.yml) — coverage + gates. +- [docs/](docs/) — hand-written feature guides (getting started, cloud wallet, delegation, etc). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/cli/AGENTS.md b/packages/cli/AGENTS.md new file mode 100644 index 00000000..df586aef --- /dev/null +++ b/packages/cli/AGENTS.md @@ -0,0 +1,33 @@ +# packages/cli — AGENTS.md + +## Purpose + +`@docknetwork/wallet-sdk-cli` is a Node CLI for exercising the SDK outside a host app — driving +`core` + `data-store` (TypeORM/SQLite) from the terminal, plus standalone BBS +verification/revocation scripts. + +## Entry Point & Stack + +`src/index.ts`, run via `ts-node` (no compile step — see `package.json` for the current +version). Depends on `@docknetwork/wallet-sdk-core` and `@docknetwork/wallet-sdk-data-store`. + +## Local commands + +```bash +cd packages/cli +npm run cli # ts-node src/index.ts — interactive CLI (src/commands/) +npm run test:bbs # ts-node src/bbs-verification.ts +npm run test:revocation # ts-node src/bbs-revocation.ts +``` + +There is no `build` or `test` script in this package's `package.json`, and `scripts/build.sh` at +the repo root does not build it — it ships as TypeScript run directly through `ts-node`. + +## Tests + +None. No `*.test.*` files exist under `src/`, and this package is excluded from the root Jest +coverage collection (`!packages/cli/**` in the root `jest.config.js`). Treat as a coverage gap. + +## See also + +[Root AGENTS.md](../../AGENTS.md) diff --git a/packages/core/AGENTS.md b/packages/core/AGENTS.md new file mode 100644 index 00000000..0ee51aff --- /dev/null +++ b/packages/core/AGENTS.md @@ -0,0 +1,33 @@ +# packages/core — AGENTS.md + +## Purpose + +`@docknetwork/wallet-sdk-core` is the wallet orchestration layer: wallet lifecycle, credential +storage/lifecycle, DID management, message handling (DIDComm), and presentation/verification. It +is the API that platform bindings (`react-native`, `web`, `cli`) build on. + +## Entry Point & Stack + +TypeScript (some `.js`/`.test.js` still present), built with `tsc` to `lib/` (see `build` in +`package.json`). See `package.json` for the current version and dependency ranges — it depends +on `@docknetwork/wallet-sdk-wasm` and peer-depends on `@docknetwork/wallet-sdk-data-store`, so a +storage backend must be supplied by the consumer. + +## Local commands + +```bash +cd packages/core +npm test # jest, this package only +npm run build # tsc -p tsconfig.build.json, then fix-build-imports.js +npm run docs # regenerate this package's jsdoc reference into ../../docs/api (generate-docs.js) +``` + +## Tests + +Co-located `*.test.ts`/`*.test.js` beside each source file (e.g. `src/wallet.test.ts`, +`src/credential-provider.test.ts`). Also picked up by the root Jest run +(`npm test` at the repo root) and counted toward the root coverage thresholds. + +## See also + +[Root AGENTS.md](../../AGENTS.md) diff --git a/packages/data-store-typeorm/AGENTS.md b/packages/data-store-typeorm/AGENTS.md new file mode 100644 index 00000000..a08f2c6c --- /dev/null +++ b/packages/data-store-typeorm/AGENTS.md @@ -0,0 +1,32 @@ +# packages/data-store-typeorm — AGENTS.md + +## Purpose + +`@docknetwork/wallet-sdk-data-store-typeorm` is the TypeORM-backed implementation of the +`DataStore` interface defined in `packages/data-store` — persistent (SQLite via `sqlite3` by +default) storage for wallet documents. It is the storage backend `packages/react-native` and +`packages/cli` use. + +## Entry Point & Stack + +TypeScript, built with `tsc` to `lib/` (see `package.json` for the current version). Uses +`typeorm` as a peer dependency and includes its own migrations under `src/migrations` / +`src/migration` plus a `src/migrations-data-source.ts` for running them. + +## Local commands + +```bash +cd packages/data-store-typeorm +npm test # jest, this package only +npm run build # tsc -p tsconfig.build.json, then fix-build-imports.js +``` + +## Tests + +`src/__tests__/` (e.g. `index.test.ts`, `v1-data-store.test.ts`) plus a co-located +`src/entities/document/document.entity.test.ts`. Picked up by the root Jest run and counted +toward the root coverage thresholds. + +## See also + +[Root AGENTS.md](../../AGENTS.md) diff --git a/packages/react-native/AGENTS.md b/packages/react-native/AGENTS.md new file mode 100644 index 00000000..3e610ffe --- /dev/null +++ b/packages/react-native/AGENTS.md @@ -0,0 +1,56 @@ +# packages/react-native — AGENTS.md + +## Purpose + +`@docknetwork/wallet-sdk-react-native` is the React Native binding for the SDK: React +hooks/components (`useWallet`, DID/document hooks, biometric plugins) that a host RN app imports +directly, plus a bundled WebView runtime that runs the actual wasm/crypto work off the RN JS +thread. + +## Entry Point & Stack + +TypeScript/JavaScript, `react-native` as a peer dependency. See `package.json` for the current +version — it depends on `core`, `data-store-typeorm`, `dids`, and `wasm`. + +## Non-obvious mechanism: two separate "build" steps + +- **`lib/` is hand-written source, not build output.** `lib/` here is checked-in React + hooks/components (`lib/wallet.ts`, `lib/index.tsx`, `lib/didHooks.js`, + `lib/credentials/CredentialContext.tsx`, …) consumed as-is by the host app's Metro bundler. This + is why `package.json`'s `"build"` script is a no-op (`echo 'add build script when required'`) — + there is nothing to compile for this half of the package (`request-logger` has the same no-op + `build` script and checked-in `lib/`, for the same reason — it's not unique to this package, + just unusual for a *bundled* platform binding). +- **`bundler/` builds the WebView runtime.** `npm run build:all` (`bundler/build-and-copy.js`) + runs Rollup (`bundler/rollup.config.mjs`) to produce `sandbox.js` and `bundle.js` — the wasm + wallet logic bundled to run inside a hidden WebView — then copies them into RN assets + (`bundler/copy-rn-assets.js`). This is the mechanism the external `dock-app` repo depends on: + its `build-sdk` script calls `bundler/build-and-copy.js` directly + (`../wallet-sdk/packages/react-native/bundler/build-and-copy.js`). Do not rename or move + `bundler/build-and-copy.js` without checking `dock-app` first. + +## Local commands + +```bash +cd packages/react-native +npm test # jest — only lib/**/*.test.js runs here (root jest.config.js excludes + # this package's .test.ts files; see its own jest.config.js) +npm run build:bundle # build the WebView bundle only (bundler/build.js) +npm run build:all # build the WebView bundle and copy it into RN assets +npm run test:bundle # playwright test — exercises the built bundle (bundler/test/) +npm run dev # bundler/server.js, a dev server for the WebView bundle +``` + +## Tests + +Co-located `*.test.js`/`*.test.ts` files exist under `lib/`, but only the `.test.js` ones actually +run: this package's own `jest.config.js` matches `**/!(*.e2e).test.js` (`.js` only), and the root +`jest.config.js` explicitly ignores `packages/react-native/.*\.test\.ts$`. So `lib/wallet.test.ts` +and `lib/didHooks.test.ts` are not executed by either the package's `npm test` or the root Jest +run — treat them as a coverage gap, not exercised suites. Separately, `bundler/test/bundle.test.js` +is a Playwright test (`npm run test:bundle`) that loads the built bundle in a browser — not part +of the root Jest run either. + +## See also + +[Root AGENTS.md](../../AGENTS.md) diff --git a/packages/wasm/AGENTS.md b/packages/wasm/AGENTS.md new file mode 100644 index 00000000..15804f28 --- /dev/null +++ b/packages/wasm/AGENTS.md @@ -0,0 +1,38 @@ +# packages/wasm — AGENTS.md + +## Purpose + +`@docknetwork/wallet-sdk-wasm` is the crypto and blockchain integration layer: it wraps the Cheqd +blockchain SDK (`@docknetwork/cheqd-blockchain-api`/`-modules`), `@docknetwork/credential-sdk`, +OID4VCI/OID4VC, SD-JWT, and the delegation engine behind the SDK's own service/module interfaces. +It is the largest package by file count and the dependency most other `packages/*` workspaces +(directly or transitively) sit on — `dids`, `request-logger`, and `wallet-edv-storage` are +standalone exceptions with no wasm dependency. + +## Entry Point & Stack + +TypeScript/JavaScript under `src/{core,wallet,modules,services,test}`. Built either with Rollup +(`npm run build`, the default) or plain Babel (`npm run build:babel`) — see `package.json` for +which one CI/consumers actually rely on and for the current dependency versions (several +`@docknetwork/*` deps are pinned to exact versions here, not ranges). + +## Local commands + +```bash +cd packages/wasm +npx jest # this package has no "test" script in package.json — run jest directly, + # or use the root `npm test` which includes it +npm run build # rollup -c, then fix-build-imports.js +npm run docs:jsdoc # jsdoc -c jsdoc.conf.json -r src/ +``` + +## Tests + +Co-located `*.test.{js,ts}` beside each source file (e.g. `src/services/credential/oid4vci.test.js`, +`src/core/validation.test.js`); `src/test/fixtures/` holds shared fixture data, not specs. Picked +up by the root Jest run and counted toward the root coverage thresholds +(`coverage-thresholds.json`). + +## See also + +[Root AGENTS.md](../../AGENTS.md)