@prson/login-verifier 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -17,8 +17,11 @@
17
17
  npm install @prson/login-verifier
18
18
  ```
19
19
 
20
- Node 20 or later. This package is server-side only and has no browser
21
- bundle.
20
+ Server-side only; there's no browser bundle. Runs on Node.js 20 or later,
21
+ Bun, and Cloudflare Workers with the `nodejs_compat` compatibility flag
22
+ (tested 22 Nov 2026). It doesn't run on Vercel Edge or Next.js
23
+ `runtime = "edge"`, which have no `node:crypto`: verify in a Node.js
24
+ route instead. Deno isn't tested yet.
22
25
 
23
26
  ```bash
24
27
  npm install @prson/login-verifier
@@ -134,10 +137,21 @@ const native = await verifySignedFragment(fragment, { expectedAudience: "shop.ex
134
137
 
135
138
  // "One unique, document-verified human at your domain":
136
139
  // { envelope: { scope: "prson-unique-human/1", audience, uniqueIdHash, … }, signature, kid }.
137
- // Checks scope, audience (must equal expectedAudience), expiry and the
138
- // signature over the canonical (sorted-keys) envelope.
139
- const unique = await verifyUniqueHumanId(credential, { expectedAudience: "shop.example.com" });
140
+ // Checks scope, audience (must equal expectedAudience), expiry, the
141
+ // binding to THIS sign-in (nonce + the wallet's sign-in key) and the
142
+ // signature over the canonical (sorted-keys) envelope. Without the binding
143
+ // a copied envelope would work for anyone until it expires.
144
+ const unique = await verifyUniqueHumanId(credential, {
145
+ expectedAudience: "shop.example.com", // or "https://shop.example.com"
146
+ expectedNonce: nonce, // the nonce you passed to verifyPresentation
147
+ expectedCnfX: result.prsonId, // the verified presentation's key
148
+ // allowUnbound: true, // temporary: accept Prson apps older than
149
+ // build 2026110702 (no nonce/cnf; bearer)
150
+ });
140
151
  if (unique.ok) useAsAccountKey(unique.uniqueIdHash); // pairwise: stable here only
152
+ // Failure reasons besides the shared ones: "binding_required" (you didn't
153
+ // pass expectedNonce/expectedCnfX), "unbound" (an old app's envelope),
154
+ // "nonce_mismatch", "cnf_mismatch".
141
155
  ```
142
156
 
143
157
  `resolveIssuerKey(kid, opts?)` fetches (and caches) an issuer key, e.g.
package/dist/index.d.ts CHANGED
@@ -146,15 +146,51 @@ export type UniqueHumanIdEnvelope = {
146
146
  issuingCountry: string | null;
147
147
  signedAt: string;
148
148
  expiresAt: string;
149
+ /** The sign-in's nonce: the one your server issued for this login. */
150
+ nonce?: string;
151
+ /** The wallet's per-site sign-in key (the presentation's `cnf.jwk`, i.e. `prsonId`). */
152
+ cnf?: {
153
+ jwk: {
154
+ kty: "OKP";
155
+ crv: "Ed25519";
156
+ x: string;
157
+ };
158
+ };
149
159
  };
150
160
  export type UniqueHumanIdCredential = {
151
161
  envelope: UniqueHumanIdEnvelope;
152
162
  signature: string;
153
163
  kid: string;
154
164
  };
165
+ export type UniqueHumanIdFailureReason = FragmentVerifyFailureReason
166
+ /** The envelope has no nonce or no cnf (an old app build), and `allowUnbound` isn't set. */
167
+ | "unbound"
168
+ /** `expectedNonce` or `expectedCnfX` wasn't passed. */
169
+ | "binding_required" | "nonce_mismatch" | "cnf_mismatch";
170
+ export type UniqueHumanIdVerifyOptions = FragmentVerifyOptions & {
171
+ /**
172
+ * The nonce your server issued for this sign-in (the one you also pass
173
+ * to `verifyPresentation`). REQUIRED unless `allowUnbound`.
174
+ */
175
+ expectedNonce?: string;
176
+ /**
177
+ * The wallet's sign-in key from the verified presentation:
178
+ * `presentation.prsonId` (= `cnf.jwk.x`). REQUIRED unless `allowUnbound`.
179
+ * Binds the id to this sign-in, so a copied envelope can't be replayed
180
+ * by someone else.
181
+ */
182
+ expectedCnfX?: string;
183
+ /**
184
+ * Accept envelopes without a nonce or cnf (wallets older than build
185
+ * 2026110702). Temporary: an unbound envelope is a bearer token until it
186
+ * expires. When the envelope does carry them, they are still checked
187
+ * against whatever you pass.
188
+ */
189
+ allowUnbound?: boolean;
190
+ };
155
191
  export type UniqueHumanIdVerifyResult = {
156
192
  ok: false;
157
- reason: FragmentVerifyFailureReason;
193
+ reason: UniqueHumanIdFailureReason;
158
194
  detail?: string;
159
195
  } | {
160
196
  ok: true;
@@ -165,8 +201,9 @@ export type UniqueHumanIdVerifyResult = {
165
201
  /**
166
202
  * Verify a unique-human-id credential. Checks, in order: shape, scope,
167
203
  * audience binding (must equal YOUR host — pass `expectedAudience`),
168
- * expiry, and the notary RSA-SHA256 signature against the published
204
+ * expiry, the binding to this sign-in (`expectedNonce`, `expectedCnfX`),
205
+ * and the notary RSA-SHA256 signature against the published
169
206
  * JWKS (kid-pinned). On success, `uniqueIdHash` is safe to use as the
170
207
  * per-domain uniqueness key.
171
208
  */
172
- export declare function verifyUniqueHumanId(credential: UniqueHumanIdCredential, opts?: FragmentVerifyOptions): Promise<UniqueHumanIdVerifyResult>;
209
+ export declare function verifyUniqueHumanId(credential: UniqueHumanIdCredential, opts?: UniqueHumanIdVerifyOptions): Promise<UniqueHumanIdVerifyResult>;
package/dist/index.js CHANGED
@@ -545,7 +545,8 @@ function canonicalStringify(obj) {
545
545
  /**
546
546
  * Verify a unique-human-id credential. Checks, in order: shape, scope,
547
547
  * audience binding (must equal YOUR host — pass `expectedAudience`),
548
- * expiry, and the notary RSA-SHA256 signature against the published
548
+ * expiry, the binding to this sign-in (`expectedNonce`, `expectedCnfX`),
549
+ * and the notary RSA-SHA256 signature against the published
549
550
  * JWKS (kid-pinned). On success, `uniqueIdHash` is safe to use as the
550
551
  * per-domain uniqueness key.
551
552
  */
@@ -563,7 +564,11 @@ export async function verifyUniqueHumanId(credential, opts = {}) {
563
564
  if (env.scope !== "prson-unique-human/1") {
564
565
  return { ok: false, reason: "unsupported_format", detail: `scope ${String(env.scope)}` };
565
566
  }
566
- const expected = (opts.expectedAudience ?? "").trim().toLowerCase();
567
+ // The envelope names the bare host; accept it as "shop.example.com" or as
568
+ // "https://shop.example.com" (the form verifyPresentation takes), so one
569
+ // value works for both checks. Nothing else is stripped: a path, port or
570
+ // other scheme still mismatches.
571
+ const expected = (opts.expectedAudience ?? "").trim().toLowerCase().replace(/^https:\/\//, "").replace(/\/$/, "");
567
572
  if (!expected || expected !== env.audience.toLowerCase()) {
568
573
  return {
569
574
  ok: false,
@@ -575,6 +580,23 @@ export async function verifyUniqueHumanId(credential, opts = {}) {
575
580
  if (new Date(env.expiresAt).getTime() <= now) {
576
581
  return { ok: false, reason: "expired" };
577
582
  }
583
+ // Binding to this sign-in (nonce + the wallet's sign-in key): without it
584
+ // the envelope is a bearer token anyone who copies it can replay.
585
+ const envNonce = typeof env.nonce === "string" ? env.nonce : null;
586
+ const envCnfX = typeof env.cnf?.jwk?.x === "string" ? env.cnf.jwk.x : null;
587
+ if (!opts.allowUnbound) {
588
+ if (!opts.expectedNonce || !opts.expectedCnfX) {
589
+ return { ok: false, reason: "binding_required", detail: "pass expectedNonce and expectedCnfX (the presentation's prsonId)" };
590
+ }
591
+ if (envNonce === null || envCnfX === null)
592
+ return { ok: false, reason: "unbound" };
593
+ }
594
+ if (envNonce !== null && opts.expectedNonce !== undefined && envNonce !== opts.expectedNonce) {
595
+ return { ok: false, reason: "nonce_mismatch" };
596
+ }
597
+ if (envCnfX !== null && opts.expectedCnfX !== undefined && envCnfX !== opts.expectedCnfX) {
598
+ return { ok: false, reason: "cnf_mismatch" };
599
+ }
578
600
  const jwk = await resolveIssuerJwk(credential.kid, opts);
579
601
  if (!jwk)
580
602
  return { ok: false, reason: "issuer_key_resolve_failed", detail: credential.kid };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@prson/login-verifier",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Node.js verifier for SD-JWT-VC presentations issued by the Prson notary and delivered via @prson/login-sdk. Pure-function; no Prson account or API key required.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",