[WALLET-202] Add US nationality scope

README.md

@@ -259,9 +259,10 @@ Proof supports the `scope` parameter of the [OID4VP specification](https://openi
 
 Supported `scope` and their associated [Credential Type](#credential-type):
 
-| scope                                                 | Credential Type     |
-| ----------------------------------------------------- | ------------------- |
-| `urn:proof:params:scope:verifiable-credentials:basic` | `ProofCredentialV1` |
+| scope                                                          | Credential Type     |
+| -------------------------------------------------------------- | ------------------- |
+| `urn:proof:params:scope:verifiable-credentials:basic`          | `ProofCredentialV1` |
+| `urn:proof:params:scope:verifiable-credentials:nationality:us` | `ProofCredentialV1` |
 
 #### Transaction Templates
 

packages/common/src/constants.ts

@@ -2,5 +2,8 @@ import type { CredentialID } from "./types.ts";
 
 export const DEFAULT_CREDENTIAL_ID: CredentialID = "proof_id_default";
 
+export const NATIONALITY_US_CREDENTIAL_ID: CredentialID =
+  "proof_id_nationality_us";
+
 export const PROOF_CREDENTIAL_V1_VCT =
   "https://credentials.notarize.com/ProofCredentialV1";

packages/common/src/index.ts

@@ -8,7 +8,11 @@ export type {
   Format,
 } from "./types.ts";
 
-export { DEFAULT_CREDENTIAL_ID, PROOF_CREDENTIAL_V1_VCT } from "./constants.ts";
+export {
+  DEFAULT_CREDENTIAL_ID,
+  NATIONALITY_US_CREDENTIAL_ID,
+  PROOF_CREDENTIAL_V1_VCT,
+} from "./constants.ts";
 
 export type {
   DCQLQuery,

packages/common/src/types.ts

@@ -2,7 +2,9 @@ export type Environment =
   "localhost" | "next" | "staging" | "sandbox" | "production";
 export type ResponseMode = "fragment" | "direct_post";
 export type ResponseType = "vp_token";
-export type Scope = "urn:proof:params:scope:verifiable-credentials:basic";
-export type CredentialID = "proof_id_default";
+export type Scope =
+  | "urn:proof:params:scope:verifiable-credentials:basic"
+  | "urn:proof:params:scope:verifiable-credentials:nationality:us";
+export type CredentialID = "proof_id_default" | "proof_id_nationality_us";
 export type CredentialType = "ProofCredentialV1";
 export type Format = "dc+sd-jwt";

packages/common/test/authorization.test.mjs

@@ -40,6 +40,19 @@ test("createClient builds a scope-based authorize URL (fragment default)", () =>
   );
 });
 
+test("createClient accepts the nationality scope", () => {
+  const url = new URL(
+    createClient(CONFIG).authorizationUrl({
+      nonce: "n-124",
+      scope: "urn:proof:params:scope:verifiable-credentials:nationality:us",
+    }),
+  );
+  assert.equal(
+    url.searchParams.get("scope"),
+    "urn:proof:params:scope:verifiable-credentials:nationality:us",
+  );
+});
+
 test("direct_post uses response_uri instead of redirect_uri", () => {
   const url = new URL(
     createClient({ ...CONFIG, responseMode: "direct_post" }).authorizationUrl({

packages/server/src/proof_credential_factory.ts

@@ -17,6 +17,10 @@ export const getProofCredential = async (
       claims["age_equal_or_over"] !== undefined
         ? (claims["age_equal_or_over"] as Record<string, boolean>)
         : undefined;
+    const national =
+      claims["is_national"] !== undefined
+        ? (claims["is_national"] as Record<string, boolean>)
+        : undefined;
 
     return new ProofCredentialV1({
       sdjwt,
@@ -39,6 +43,9 @@ export const getProofCredential = async (
       ...(ages?.["65"] !== undefined && {
         is_over_65: ages?.["65"] as boolean,
       }),
+      ...(national?.["us"] !== undefined && {
+        is_national_us: national?.["us"] as boolean,
+      }),
     });
   } else {
     throw new Error(`unknown ProofCredential for vct: ${vct}`);

packages/server/src/proof_credentials.ts

@@ -41,6 +41,7 @@ type ProofCredentialV1Params = {
   is_over_18?: boolean;
   is_over_21?: boolean;
   is_over_65?: boolean;
+  is_national_us?: boolean;
 } & CredentialParams;
 
 export class ProofCredentialV1 extends Credential {
@@ -49,6 +50,7 @@ export class ProofCredentialV1 extends Credential {
   public readonly isOver18: boolean | undefined;
   public readonly isOver21: boolean | undefined;
   public readonly isOver65: boolean | undefined;
+  public readonly isNationalUS: boolean | undefined;
   private readonly birth_date: string | undefined;
 
   constructor(params: ProofCredentialV1Params) {
@@ -59,6 +61,7 @@ export class ProofCredentialV1 extends Credential {
     this.isOver18 = params.is_over_18;
     this.isOver21 = params.is_over_21;
     this.isOver65 = params.is_over_65;
+    this.isNationalUS = params.is_national_us;
   }
 
   public credentialType(): CredentialType {
@@ -75,3 +78,7 @@ export class ProofCredentialV1 extends Credential {
       : undefined;
   }
 }
+// this definition is a compile time guard, `satisfies` fails typecheck if a `CredentialType` has no class
+const _CREDENTIAL_CLASSES = {
+  ProofCredentialV1,
+} satisfies Record<CredentialType, unknown>;

packages/server/src/utils.ts

@@ -1,9 +1,11 @@
-import {
-  type CredentialID,
-  DEFAULT_CREDENTIAL_ID,
-} from "@proof.com/proof-vc-common";
+import type { CredentialID } from "@proof.com/proof-vc-common";
 
-const CREDENTIAL_IDS: CredentialID[] = [DEFAULT_CREDENTIAL_ID];
+const CREDENTIAL_ID_SET = {
+  proof_id_default: true,
+  proof_id_nationality_us: true,
+} satisfies Record<CredentialID, true>;
+
+export const CREDENTIAL_IDS = Object.keys(CREDENTIAL_ID_SET) as CredentialID[];
 
 export const credentialIdAsType = (s: string): CredentialID => {
   for (const credentialId of CREDENTIAL_IDS) {

packages/server/src/verifier.ts

@@ -6,7 +6,7 @@ import { ES256, ES384, ES512, hasher } from "@owf/crypto";
 import { base64urlDecode } from "@owf/identity-common";
 
 import type { ProofCredential, TrustRoot, VPToken } from "./types.ts";
-import { credentialIdAsType } from "./utils.ts";
+import { CREDENTIAL_IDS, credentialIdAsType } from "./utils.ts";
 import { getProofCredential } from "./proof_credential_factory.ts";
 import { verifyChain } from "./certificates/chain_validator.ts";
 import { getTrustRoot } from "./certificates/trust_store/index.ts";
@@ -136,10 +136,12 @@ export function createVerifier(config: VerifierConfig): Verifier {
       string[]
     >;
     const vpToken = {} as VPToken;
+    for (const credentialId of CREDENTIAL_IDS) {
+      vpToken[credentialId] = [];
+    }
 
     for (const [key, encodedSDJWTs] of Object.entries(records)) {
       const credentialId = credentialIdAsType(key);
-      vpToken[credentialId] = [];
       for (const encodedSDJWT of encodedSDJWTs) {
         const credential = await verify({
           encodedSDJWT,

packages/server/test/proof_credential.test.mjs

@@ -0,0 +1,35 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { PROOF_CREDENTIAL_V1_VCT } from "../dist/index.js";
+import { getProofCredential } from "../dist/proof_credential_factory.js";
+
+const sdjwtWith = (claims) => ({ getClaims: async () => claims });
+
+test("maps is_national.us onto isNationalUS", async () => {
+  const credential = await getProofCredential(
+    sdjwtWith({
+      vct: PROOF_CREDENTIAL_V1_VCT,
+      age_equal_or_over: { 18: true },
+      is_national: { us: true },
+    }),
+  );
+
+  assert.equal(credential.isNationalUS, true);
+  assert.equal(credential.isOver18, true);
+  assert.equal(credential.givenName, undefined);
+  assert.equal(credential.familyName, undefined);
+});
+
+test("leaves isNationalUS undefined when is_national is absent", async () => {
+  const credential = await getProofCredential(
+    sdjwtWith({
+      vct: PROOF_CREDENTIAL_V1_VCT,
+      given_name: "Frodo",
+      age_equal_or_over: { 18: true },
+    }),
+  );
+
+  assert.equal(credential.isNationalUS, undefined);
+  assert.equal(credential.givenName, "Frodo");
+});

packages/server/test/verify.test.mjs

@@ -121,3 +121,14 @@ test("rejects a chain that does not match the configured trust root", async () =
     "not issued by next in chain",
   );
 });
+
+test("verifyVPToken populates every credential id absent from the response", async () => {
+  const encodedVPToken = Buffer.from(JSON.stringify({}), "utf8").toString(
+    "base64url",
+  );
+  const vpToken = await development.verifyVPToken({ encodedVPToken });
+  assert.deepEqual(vpToken, {
+    proof_id_default: [],
+    proof_id_nationality_us: [],
+  });
+});