Add applicationContext to request object (#258)

Adds details for the `applicationContext` addition to the SIWF request.

Update the library and generator as well.

---------

Co-authored-by: Wes Biggs <[email protected]>

Author: wesbiggs

docs/src/DataStructures/All.md

@@ -43,3 +43,9 @@ This is JSON stringified and then [`base64url`](https://datatracker.ietf.org/doc
 ### SMS/Phone
 
 {{#include VerifiedPhone.md 0}}
+
+## Context Data
+
+### Application Context Credential
+
+{{#include ApplicationContext.md 0}}

docs/src/DataStructures/ApplicationContext.md

@@ -0,0 +1,63 @@
+# Application Context
+
+## Schema
+
+An application context credential MUST be a W3C Verifiable Credential document containing information about the application requesting user sign-in.
+
+The `type` array for the credential should begin with the string `"ApplicationContextCredential"`.
+
+The `credentialSchema` field should contain an object with the following fields:
+
+- `type`: MUST be `JsonSchema`
+- `id`: MUST be the URL of the published application context credential schema. The latest version is [`https://schemas.frequencyaccess.com/ApplicationContextCredential/bciqe2bsnuaqg7zy3gqjmwha2q5h2bybvr6log2jsb5kjn2hos6irrlq.json`](https://schemas.frequencyaccess.com/ApplicationContextCredential/bciqe2bsnuaqg7zy3gqjmwha2q5h2bybvr6log2jsb5kjn2hos6irrlq.json).
+
+The `credentialSubject` field should contain an object with the following fields:
+
+- `id`: Your provider identifier, expressed as a DID.
+- `application`: A JSON object containing the following keys:
+  - `name`: A map of one or more language tags to human-readable string values. Language tags should follow [BCP-47/RFC-5646](https://www.rfc-editor.org/rfc/rfc5646.html) (as used in the HTTP `Content-Language` header). A content language key of `"*"` indicates a wildcard or default value, as in HTTP.
+  - `logo`: A map of one or more language tags (as above) to objects containing a `url` property. The URL should resolve to an image in the PNG format. The recommended maximum image width for optimal client compatibility is 200 pixels.
+
+### Example
+
+This application context credential describes a hypothetical app called "My Social App".
+
+```json
+{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/undefined-terms/v2"
+  ],
+  "type": [
+    "ApplicationContextCredential",
+    "VerifiableCredential"
+  ],
+  "issuer": "did:web:frequencyaccess.com",
+  "validFrom": "2025-02-12T21:28:08.289+0000",
+  "credentialSchema": {
+    "type": "JsonSchema",
+    "id": "https://schemas.frequencyaccess.com/ApplicationContextCredential/bciqe2bsnuaqg7zy3gqjmwha2q5h2bybvr6log2jsb5kjn2hos6irrlq.json"
+  },
+  "credentialSubject": {
+    "id": "did:dsnp:123456",
+    "application": {
+      "name": {
+        "en": "My Social App",
+        "es": "Mi Aplicación Social"
+      },
+      "logo": {
+        "*": {
+          "url": "https://example.org/logos/my-social-app.png"
+        }
+      }
+    }
+  },
+  "proof": {
+    "type": "DataIntegrityProof",
+    "verificationMethod": "did:web:frequencyaccess.com#z6MkofWExWkUvTZeXb9TmLta5mBT6Qtj58es5Fqg1L5BCWQD",
+    "cryptosuite": "eddsa-rdfc-2022",
+    "proofPurpose": "assertionMethod",
+    "proofValue": "z4jArnPwuwYxLnbBirLanpkcyBpmQwmyn5f3PdTYnxhpy48qpgvHHav6warjizjvtLMg6j3FK3BqbR2nuyT2UTSWC"
+  }
+}
+```

docs/src/DataStructures/SignedRequest.md

@@ -46,6 +46,12 @@
         }
       ]
     }
-  ]
+  ],
+  "applicationContext": {
+    "url": "https://example.org/myapp/siwf-manifest.json",
+    "hash": [
+      "bciqmdvmxd54zve5kifycgsdtoahs5ecf4hal2ts3eexkgocyc5oca2y"
+    ]
+  }
 }
 ```

docs/src/SignatureGeneration.md

@@ -100,6 +100,26 @@ Supported Options:
 
 - See a full list of [Available Credentials](./Credentials.md)
 
+## Step 4 (Recommended): Provide Application Context
+
+To help users understand which application is asking them to sign in, you can provide an `applicationContext` object that contains the URL of an application context credential.
+This is especially important if you want to manage multiple applications under a single provider identity.
+Note that any delegations that are granted by the user will apply to all applications for that provider.
+
+```json
+{
+  // ...
+  "applicationContext": {
+    "url": "https://example.org/myapp/siwf-manifest.json"
+  }
+}
+```
+
+The application context credential is a JSON-formatted verifiable credential that MAY be signed by a credential issuer.
+If you are integrating with Frequency Access, your application context details will be created as part of the provisioning process.
+
+For detailed information on the credential schema and properties, see the [full specification and example](./DataStructures/ApplicationContext.md).
+
 ### Example Using TypeScript/JavaScript
 
 ```typescript
@@ -120,6 +140,11 @@ const credentials = [
   siwf.VerifiedGraphKeyCredential,
 ];
 
+// This is a reference to an application context credential
+const applicationContext = {
+  url: "https://example.org/myapp/context.json",
+};
+
 // This is the URI that the user should return to after authenticating
 const callbackUri: string = getWebOrApplicationCallbackUri();
 
@@ -130,6 +155,7 @@ const encodedSignedRequest = await siwf.generateEncodedSignedRequest(
   callbackUri,
   permissions,
   credentials,
+  applicationContext,
 );
 
 // Options with endpoint selection

libraries/js/src/request.test.ts

@@ -17,9 +17,19 @@ const stockCredentials = [
   VerifiedGraphKeyCredential,
 ];
 
+const exampleApplicationContext = {
+  url: 'https://example.org/myapp/siwf-manifest.json',
+};
+
 describe('request', () => {
   it('correctly generates the signed request', async () => {
-    const generated = await generateSignedRequest('//Alice', 'http://localhost:3000', [1, 2, 100], stockCredentials);
+    const generated = await generateSignedRequest(
+      '//Alice',
+      'http://localhost:3000',
+      [1, 2, 100],
+      stockCredentials,
+      exampleApplicationContext
+    );
 
     expect(generated).toEqual({
       requestedSignatures: {
@@ -57,6 +67,7 @@ describe('request', () => {
           hash: ['bciqmdvmxd54zve5kifycgsdtoahs5ecf4hal2ts3eexkgocyc5oca2y'],
         },
       ],
+      applicationContext: exampleApplicationContext,
     });
   });
 

libraries/js/src/request.ts

@@ -66,14 +66,22 @@ export async function generateSignedRequest(
   providerKeyUri: string,
   callbackUri: string,
   permissions: number[],
-  credentials: SiwfCredentialRequest[] = []
+  credentials: SiwfCredentialRequest[] = [],
+  applicationContext: { url: string } | null = null
 ): Promise<SiwfSignedRequest> {
   await cryptoWaitReady();
   const keyPair = keyring.createFromUri(providerKeyUri);
 
   const signature = keyPair.sign(generateRequestSigningData(callbackUri, permissions, true), {});
 
-  return buildSignedRequest(u8aToHex(signature), keyPair.address, callbackUri, permissions, credentials);
+  return buildSignedRequest(
+    u8aToHex(signature),
+    keyPair.address,
+    callbackUri,
+    permissions,
+    credentials,
+    applicationContext
+  );
 }
 
 /**
@@ -92,7 +100,8 @@ export function buildSignedRequest(
   signerPublicKey: string,
   callbackUri: string,
   permissions: number[],
-  credentials: SiwfCredentialRequest[] = []
+  credentials: SiwfCredentialRequest[] = [],
+  applicationContext: { url: string } | null = null
 ): SiwfSignedRequest {
   if (!isSiwfCredentialsRequest(credentials)) {
     console.error('credentials', credentials);
@@ -120,6 +129,7 @@ export function buildSignedRequest(
       },
     },
     requestedCredentials,
+    applicationContext: applicationContext || undefined,
   };
 }
 
@@ -137,9 +147,16 @@ export async function generateEncodedSignedRequest(
   providerKeyUri: string,
   callbackUri: string,
   permissions: number[],
-  credentials: SiwfCredentialRequest[] = []
+  credentials: SiwfCredentialRequest[] = [],
+  applicationContext: { url: string } | null = null
 ): Promise<string> {
-  const signedRequest = await generateSignedRequest(providerKeyUri, callbackUri, permissions, credentials);
+  const signedRequest = await generateSignedRequest(
+    providerKeyUri,
+    callbackUri,
+    permissions,
+    credentials,
+    applicationContext
+  );
   return encodeSignedRequest(signedRequest);
 }
 

libraries/js/src/types/request.ts

@@ -27,6 +27,7 @@ export interface SiwfSignedRequest {
     };
   };
   requestedCredentials?: SiwfCredentialRequest[];
+  applicationContext?: { url: string };
 }
 
 function isSiwfCredential(input: unknown): input is SiwfCredential {

tools/signed-request-generator/package-lock.json

@@ -20,6 +20,8 @@
 	let isManualSign = false;
 	let permissions: number[] = [];
 	let credentials: SiwfCredential[] = [];
+	let applicationContextPlaceholder = 'https://example.org/my-app-context.json';
+	let applicationContext = '';
 	let isRequiredComplete = false;
 
 	let manualSignature = '';
@@ -47,7 +49,8 @@
 				signerPublicKey,
 				callbackUri,
 				permissions,
-				credentials
+				credentials,
+				{ url: applicationContext }
 			);
 			encodedRequest = encodeSignedRequest(signedRequest);
 			requestJson = JSON.stringify(signedRequest, null, 2);
@@ -76,6 +79,16 @@
 	<div class="mb-4">
 		<Credentials bind:credentials />
 	</div>
+	<div class="mb-4">
+		<label for="applicationContext">Application Context URL*</label>
+		<input
+			type="url"
+			id="applicationContext"
+			bind:value={applicationContext}
+			required
+			placeholder={applicationContextPlaceholder}
+		/>
+	</div>
 	{#if isRequiredComplete}
 		<div class="mb-4">
 			<fieldset style="min-width: 0;">

tools/signed-request-generator/src/components/Form.svelte

@@ -4,5 +4,6 @@ test('can see wallet button when I add a url', async ({ page }) => {
 	await page.goto('/');
 	await expect(page.locator('#callbackUri')).toBeVisible();
 	await page.locator('#callbackUri').fill('http://localhost:3000');
+	await page.locator('#applicationContext').fill('http://example.org');
 	await expect(page.locator('button', { hasText: 'Connect to Wallet' })).toBeVisible();
 });

tools/signed-request-generator/tests/basic.test.ts

@@ -4,6 +4,7 @@ test('can see an output  when I add a url and signature data', async ({ page })
 	await page.goto('/');
 	await expect(page.locator('#callbackUri')).toBeVisible();
 	await page.locator('#callbackUri').fill('http://localhost:3000');
+	await page.locator('#applicationContext').fill('http://example.org');
 	await page.locator('#signMethod-manual').check();
 	await expect(page.locator('#signerPublicKey')).toBeVisible();
 

tools/signed-request-generator/tests/see-signature.test.ts

@@ -4,6 +4,7 @@ test('can see the signature removed when edit signature permission data', async
 	await page.goto('/');
 	await expect(page.locator('#callbackUri')).toBeVisible();
 	await page.locator('#callbackUri').fill('http://localhost:3000');
+	await page.locator('#applicationContext').fill('http://example.org');
 	await page.locator('#signMethod-manual').check();
 	await expect(page.locator('#signerPublicKey')).toBeVisible();
 
@@ -18,6 +19,7 @@ test('can see the signature removed when edit signature callback data', async ({
 	await page.goto('/');
 	await expect(page.locator('#callbackUri')).toBeVisible();
 	await page.locator('#callbackUri').fill('http://localhost:3000');
+	await page.locator('#applicationContext').fill('http://example.org');
 	await page.locator('#signMethod-manual').check();
 	await expect(page.locator('#signerPublicKey')).toBeVisible();