@coordination-network/user-app-core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethereum Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# `@coordination-network/user-app-core`
+
+The three `@coordination-network/user-app-link` operations a user app serves —
+`registration.sign`, `credential.issue`, `presentation.create` — implemented over injected device,
+storage, HTTP and proving ports. One operation per flow, each behind one consent. Runs
+unchanged on the Expo app (`expo-secure-store`, a native prover) and the browser app (IndexedDB,
+`bb.js` in a Worker): every platform difference lives in the ports, not here.
+
+This package holds no business logic. It holds keys, held credentials, and revocation secrets, and
+serves any number of network member apps over the deep-link protocol.
+
+## Use
+
+```ts
+import { createUserAppService } from "@coordination-network/user-app-core"
+import { createRequestHandler } from "@coordination-network/user-app-link"
+
+const service = createUserAppService({
+    store, // Store from @coordination-network/wallet, e.g. expo-secure-store-backed
+    deviceKey, // DeviceKey: a DeviceSigner plus ecdh() and getSecurityLevel()
+    proofGenerator, // ProofGenerator from @coordination-network/wallet
+    http: { getJson, postJson },
+    consent: async (summary) => showConsentScreen(summary),
+    review: async (summary) => showShareScreen(summary),
+    progress: (op, step) => showStep(op, step)
+})
+
+if (!(await service.isOnboarded())) {
+    await service.createIdentity()
+}
+
+const handler = createRequestHandler({ handlers: service.handlers, consent: service.consent })
+const responseUrl = await handler.handle(incomingUrl)
+```
+
+`service.consent` is the single gate `createRequestHandler` calls before dispatch; `Wallet`'s own
+`ConsentPrompt` is wired to a constant `true` internally, so one deep link never shows two consent
+screens. `presentation.create` asks once more through `review`, but only after the proof exists,
+so the question is about what the proof reveals rather than about starting the work. Handler
+bodies run one at a time — a second deep link arriving mid-sync waits for the first to finish
+rather than interleaving with it.
+
+`service.readIdentity()` is how the app's own Identity screen reads the identity. No operation
+hands it over a link: a member app that wants a `networkId` asks for a signed registration request
+and reads the one inside it.
+
+## Ports
+
+- `store` / `proofGenerator` — `@coordination-network/wallet`'s own interfaces, taken verbatim.
+- `deviceKey: DeviceKey` — extends `@coordination-network/credential`'s `DeviceSigner`
+  (`getPublicKeyJwk`, `sign`, `signDigest`) with `ecdh(peerPublicKey)` (the X coordinate of
+  `hwPriv · peerPublicKey`, 32 raw bytes — feeds `deriveEddsaKeypair`) and `getSecurityLevel()`.
+  Extending rather than replacing `DeviceSigner` means a `DeviceKey` is accepted as-is by `Wallet`,
+  `buildZkPresentationInputs` and `deriveDeviceKeyCommitment`. `SecurityLevel` is reported, never
+  enforced — fail-closed policy belongs in `apps/identity-testbed`, not here.
+- `http: HttpClient` — `getJson`/`postJson`, each returning `{ status, body }`. Deliberately
+  structural: no DOM or Node fetch types leak into either app, and a test fake is three lines.
+- `consent: UserConsentPrompt` — `(summary: ConsentSummary) => Promise<boolean>`. The summary is
+  values, never prose: the caller, the rows a screen folds behind its technical toggle, and — on
+  the two ops that scope one — the programme and country. The app writes the sentence, so it can
+  name the caller mid-line in the caller's own colour. `ConsentSummary` is keyed by `op`, so a
+  screen switching on it gets `scope` typed rather than optional. At prompt time no credential has
+  been selected yet for `presentation.create`, so its summary names the verifier, programme and
+  country rather than a credential — that is the material fact anyway.
+- `review: PresentationReviewPrompt` — `(summary: PresentationReview) => Promise<boolean>`, asked
+  after `presentation.create` has built its proof and before it is posted. The summary names the
+  verifier, programme, country and the credential's issuer, which the proof itself reveals. `false`
+  refuses with `CONSENT_DENIED`.
+- `progress: (op, step) => void` — named steps inside a long handler, for a screen that shows what
+  the wallet is doing. `credential.issue` reports six; `presentation.create` reports three.
+- `now?: () => number` — defaults to `Date.now`; inject it for deterministic tests.
+
+## Two honesty notes
+
+**Revocation is answered by the issuer, never by the asker.** A member publishes a revocation
+registry covering only its own credentials, so a verifier's snapshot cannot say whether another
+member's credential still stands. `presentation.create` therefore takes no `revocationsUrl`: each
+candidate credential is checked against the snapshot its own issuer published, read from this
+package's issuer index. A candidate found revoked refuses with `CREDENTIAL_REVOKED`, before any
+proof is built and without posting anything.
+
+**The approved-issuer cross-check is real on both sides.** `GET /v1/issuers` returns both the
+`leaves` and a `root` the server read from chain independently of them, and `Wallet` compares that
+`approvedIssuerRoot` against the tree rebuilt from `leaves` before trusting either — the same
+property `GET /v1/revocations/snapshot`'s own `root` already had.
+
+## Store keys
+
+`credential.issue` and `presentation.create` each construct a fresh `Wallet` over the same
+persistent `store` `ports` supplies; `registration.sign` never needs one. `Wallet` owns the `key:`
+and `vc:`-prefixed entries in that store; this package owns two prefixes of its own:
+
+- `user-app-core:device-secret` — the one device secret this package ever holds (unlike `Wallet`'s
+  own per-`networkId` key store, this package supports exactly one identity at a time).
+- `user-app-core:issuer-index:<issuerNetworkId>` — what a credential body cannot give back: the
+  issuer's `networkId` (the body carries its Baby Jubjub public key instead), the plaintext
+  programme (the body carries a hash), the country, when this wallet stored it, and where that
+  issuer publishes its approved-issuer set and revocation snapshot. Written by `credential.issue`;
+  read by `presentation.create` to reach the right snapshot, by `listCredentials` to name the
+  issuer, and by `credential.issue` itself to answer `alreadyHeld`.
+
+The revocation secret is no longer stored between deep links: `credential.issue` generates it,
+opens the credential with it and hands it to `Wallet` inside one call, so it never leaves that
+function.
+
+`erase()` deletes every key in `store`, not only this package's own three prefixes and `Wallet`'s —
+a host app shares the same store for its own state (the user app keeps its stack descriptor there),
+so a full wipe reaches that too. A caller that wants to survive `erase()` keeps its own state
+elsewhere.
+
+## Selecting a credential for `presentation.create`
+
+`presentation.create`'s params carry no credential id. Held credentials are filtered to those whose
+body matches the requested programme and country — no status filter — and each survivor is then
+synced against its own issuer's snapshot. The one expiring latest among those still `valid` wins,
+ties broken by id for determinism. None valid but one revoked throws `CREDENTIAL_REVOKED`; none at
+all throws `NO_CREDENTIAL`. Both stay distinguishable from a `PROOF_FAILED` thrown once proving has
+actually started.
+
+## Tests
+
+```sh
+yarn test:library user-app-core --watchman=false
+```
+
+Real collaborators are used wherever they are pure: a real `Wallet` over a real `MemoryStore`, a
+software P-256 `DeviceKey` (`LocalP256Signer` plus a plain ECDH), real `ApprovedIssuerSet` and
+`RevocationRegistry`, and credentials issued with the real `issueZkCredential`. Only the proof
+generator and the HTTP port are faked.
+
+## License
+
+MIT, see [`LICENSE`](./LICENSE).