Feature/credential selection

bob-listener.js

@@ -4,7 +4,7 @@ import { spawn } from 'node:child_process'
 const PORT = process.env.PORT || 3003
 const AUTO_CONNECT_TO_OEM_SCRIPT_PATH = './scripts/maker-connect-to-oem.ts'
 const PROPOSE_PROOF_SCRIPT_PATH = './scripts/maker-propose-proof-to-oem.ts'
-const ACCEPT_PROOF_SCRIPT_PATH = './scripts/maker-accept-proof-from-oem.ts'
+const ACCEPT_PROOF_SCRIPT_PATH = './scripts/maker-respond-proof-request.ts'
 const TRIGGER_STATES = (process.env.TRIGGER_STATES || 'offer-received,credential-issued')
   .split(',')
   .map((s) => s.trim().toLowerCase())
@@ -15,7 +15,7 @@ const { log, error } = console
 const app = express()
 app.use(express.json({ type: '*/*' }))
 
-// Handle credential events, in our demo this is the credential sent from Alice(MoD) to Bob(Maker)
+// Handle credential events, in our demo this is the credential sent from Alice(Requester) to Bob(Maker)
 app.post('/credentials', (req, res) => {
   const cred = req.body || {}
   credentialRecordId = cred.id

docker-compose-integration-tests.yml

@@ -1,10 +1,14 @@
 # Run stack and integration tests with:
 #
+# export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem" &&
 # docker compose \
 #   -f docker-compose-testnet.yml \
 #   -f docker-compose-integration-tests.yml \
 #   up --build --exit-code-from integration-tests
 #
+# Or as a one-liner:
+# export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem" && docker compose -f docker-compose-testnet.yml -f docker-compose-integration-tests.yml up --build --exit-code-from integration-tests
+#
 
 services:
   integration-tests:
@@ -22,6 +26,7 @@ services:
         condition: service_healthy
     environment:
       - NODE_ENV=test
+      - NODE_EXTRA_CA_CERTS=/rootCA.pem
       - ALICE_BASE_URL=http://alice:3000
       - ALICE_WS_PORT=5003
       - ALICE_DID

docker-compose-testnet.yml

@@ -1,4 +1,4 @@
-# docker compose -f docker-compose-testnet.yml up --build -d
+# export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem" && docker compose -f docker-compose-testnet.yml up --build -d
 
 ##################################################################################
 ## Docker-Compose for a 3-agent testnet + 3-node private IPFS cluster ############
@@ -93,8 +93,8 @@ services:
       - POSTGRES_PORT=5432
       - POSTGRES_USERNAME=postgres
       - POSTGRES_PASSWORD=postgres
-      - AUTO_ACCEPT_CREDENTIALS=always
-      - AUTO_ACCEPT_PROOFS=always
+      - AUTO_ACCEPT_CREDENTIALS=never
+      - AUTO_ACCEPT_PROOFS=contentApproved
       - DID_WEB_ENABLED=true
       - DID_WEB_USE_DEV_CERT=true
       - DID_WEB_PORT=8443

docs/explicit-credential-selection.md

@@ -0,0 +1,169 @@
+# Explicit Credential Selection
+
+When responding to a Proof Request, an agent may hold multiple credentials that satisfy the request's requirements (e.g., multiple credentials from the same issuer, or multiple credentials with the same attribute names). By default, the agent might select any valid credential, which can lead to incorrect data being shared if a specific credential was intended.
+
+The **Explicit Credential Selection** feature allows a client (controller) to specify exactly which credential ID should be used for each requested attribute or predicate.
+
+## The Problem
+
+1. **Ambiguity**: If a user has two "Employee ID" credentials, the agent doesn't know which one to present.
+2. **Complexity**: The underlying Credo-TS `acceptRequest` method requires a highly complex `proofFormats` object containing deep metadata (`schemaId`, `credDefId`, `revocationRegistryId`, raw values, etc.) to specify a credential. Constructing this object on the client side is difficult and error-prone.
+
+## The Solution: Simplified Proof Formats
+
+The `veritable-cloudagent` API supports a **Simplified Proof Format**. Clients can provide a lightweight object specifying only the `credentialId` and `revealed` status for each attribute. The agent's controller then "hydrates" this object by fetching the full credential details from the wallet before passing it to the core agent.
+
+### API Usage
+
+**Endpoint**: `POST /v1/proofs/{proofRecordId}/accept-request`
+
+**Body**:
+
+```json
+{
+  "autoAcceptProof": "contentApproved",
+  "proofFormats": {
+    "anoncreds": {
+      "attributes": {
+        "attribute_name_1": {
+          "credentialId": "credential-uuid-1",
+          "revealed": true
+        },
+        "attribute_name_2": {
+          "credentialId": "credential-uuid-1",
+          "revealed": true
+        }
+      },
+      "predicates": {
+        "predicate_name_1": {
+          "credentialId": "credential-uuid-2"
+        }
+      }
+    }
+  }
+}
+```
+
+### How it Works
+
+The `ProofController` employs a three-path logic flow to handle proof acceptance:
+
+1. **Auto-Selection (No `proofFormats` provided)**
+   * If the client omits `proofFormats`, the agent automatically selects the best available credentials that satisfy the request.
+   * This is useful for simple use cases where ambiguity is not a concern.
+
+2. **Hydration (Simplified `proofFormats` provided)**
+   * The controller detects the simplified format (missing `credentialInfo`).
+   * It queries the agent for all valid credentials for this proof request.
+   * It matches the `credentialId` provided by the client with the available credentials.
+   * It populates the required `credentialInfo` (Schema ID, Cred Def ID, etc.) into the request object.
+   * **Validation**:
+     * If attributes are missing in the simplified format, the API returns a `400 Bad Request`.
+     * If no matching credentials are found to satisfy the request, the API returns a `404 Not Found`.
+
+3. **Pass-Through (Full `proofFormats` provided)**
+   * If the client provides the full, complex Credo-TS proof format, the controller passes it directly to the agent.
+   * This supports advanced use cases where the client needs full control over the cryptographic metadata.
+
+### Example Scenario
+
+**Scenario**: A Manufacturer (Bob) needs to prove the `tdp_reference` of a specific product to an OEM (Charlie). Bob has multiple credentials for different products.
+
+1. **Charlie** sends a Proof Request for `tdp_reference`.
+2. **Bob's Client** inspects the request and identifies that `credential-123` contains the correct TDP reference.
+3. **Bob's Client** calls `accept-request` with:
+
+    ```json
+    {
+      "proofFormats": {
+        "anoncreds": {
+          "attributes": {
+            "tdp_reference": {
+              "credentialId": "credential-123",
+              "revealed": true
+            }
+          },
+          "predicates": {}
+        }
+      }
+    }
+    ```
+
+4. **Bob's Agent** looks up `credential-123`, retrieves its full metadata, and generates a proof using that specific credential.
+
+## Retrieving Proof Context
+
+To construct the `accept-request` body, the client often needs to know what attributes are being requested and what credentials are available.
+
+### 1. Get Proof Record with Content
+
+To avoid making multiple calls, you can fetch the proof record along with its content (request and presentation data) in a single request.
+
+**Endpoint**: `GET /v1/proofs/{proofRecordId}?includeContent=true`
+
+**Response**:
+Returns the `ProofExchangeRecord` with an additional `content` property containing the raw proof format data.
+
+### 2. Get Simplified Proof Content
+
+The raw proof content can be complex to parse. You can request a simplified view that flattens the structure into simple key-value pairs.
+
+**Endpoint**: `GET /v1/proofs/{proofRecordId}/content?view=simplified`
+
+**Response**:
+
+```json
+{
+  "attribute_name_1": "value_1",
+  "attribute_name_2": "value_2"
+}
+```
+
+This is particularly useful for displaying the values of a received proof (Verifier role) or understanding what is being requested (Prover role) without navigating the deep AnonCreds structure.
+
+## Developer Experience
+
+While the simplified format is much cleaner than the raw format, constructing the nested JSON object can still be verbose. It is recommended to use a helper function in your client application to generate this structure.
+
+### Client-Side Helper Example (TypeScript)
+
+> **Important**: The `credentialId` used in the selection payload must be the **Wallet Credential ID** (the ID of the credential stored in the wallet), NOT the **Credential Exchange Record ID** (the ID of the record tracking the issuance process).
+>
+> In Credo-TS, you can access this via `credentialRecord.credentials[0].credentialRecordId`.
+
+```typescript
+/**
+ * Helper to construct the simplified proof format payload.
+ * 
+ * @param selections A map where the key is the attribute name and the value is the credential ID to use.
+ * @returns The formatted payload ready for the API.
+ */
+function createSelection(selections: Record<string, string>) {
+  const attributes: Record<string, { credentialId: string; revealed: boolean }> = {};
+
+  for (const [key, credId] of Object.entries(selections)) {
+    attributes[key] = { credentialId: credId, revealed: true };
+  }
+
+  return {
+    proofFormats: {
+      anoncreds: {
+        attributes
+      }
+    }
+  };
+}
+
+// Usage Example:
+// 1. User selects specific credentials for the requested attributes
+const userSelections = {
+  'name': 'credential-uuid-123',
+  'email': 'credential-uuid-456'
+};
+
+// 2. Generate the payload
+const payload = createSelection(userSelections);
+
+// 3. Send to API
+await client.acceptProofRequest(proofRecordId, payload);
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digicatapult/veritable-cloudagent",
-  "version": "0.16.21",
+  "version": "0.17.0",
   "main": "build/index",
   "type": "module",
   "types": "build/index",
@@ -25,7 +25,7 @@
   "scripts": {
     "depcheck": "depcheck",
     "lint": "eslint .",
-    "lint:fix": "npm run lint -- -- fix",
+    "lint:fix": "eslint . --fix",
     "check": "npm run tsoa:build && tsc --noEmit",
     "clean": "rimraf -rf ./build",
     "build": "npm run clean && npm run tsoa:build && swc ./src -d ./build --strip-leading-paths --copy-files",

scripts/issue-credential.ts

@@ -12,22 +12,21 @@ const connectionParser = z.array(
   })
 )
 interface ParsedArgs {
-  credDefId: string
+  credDefId?: string
   oemDid: string
   makerDid: string
   baseUrl: string
 }
 function printUsageAndExit(code: number): never {
   process.stderr.write(
-    'Usage: issue-credential --oem <oemDid> --maker <makerDid> --cred-def-id <credDefId> [--base-url <url>]\n'
+    'Usage: issue-credential --oem <oemDid> --maker <makerDid> [--cred-def-id <credDefId>] [--base-url <url>]\n'
   )
   process.exit(code)
 }
 
 function parseArgs(argv: string[]): ParsedArgs {
   const args = argv.slice(2)
   const parsed: ParsedArgs = {
-    credDefId: '',
     baseUrl: 'http://localhost:3000',
     oemDid: 'did:web:charlie%3A8443',
     makerDid: 'did:web:bob%3A8443',
@@ -61,14 +60,42 @@ function parseArgs(argv: string[]): ParsedArgs {
 }
 
 async function main() {
-  const { credDefId, oemDid, makerDid, baseUrl } = parseArgs(process.argv)
+  const { credDefId: argsCredDefId, oemDid, makerDid, baseUrl } = parseArgs(process.argv)
   const log = (msg: string, extra?: unknown) => {
     process.stderr.write(`${msg}${extra ? ' ' + JSON.stringify(extra) : ''}\n`)
   }
-  if (credDefId.length === 0) {
-    process.stderr.write('--cred-def-id is required\n')
-    printUsageAndExit(1)
+
+  let credDefId = argsCredDefId
+
+  if (!credDefId) {
+    log(`Looking for credential definitions at ${baseUrl}...`)
+    const credDefsResponse = await fetch(`${baseUrl}/v1/credential-definitions?createdLocally=true`, {
+      method: 'GET',
+      headers: { accept: 'application/json' },
+    })
+
+    if (!credDefsResponse.ok) {
+      throw new Error(
+        `Failed to retrieve credential definitions: ${credDefsResponse.status} ${credDefsResponse.statusText}`
+      )
+    }
+
+    const credDefs = await credDefsResponse.json()
+
+    if (!Array.isArray(credDefs) || credDefs.length === 0) {
+      throw new Error('No credential definitions found on the agent.')
+    }
+
+    // Pick the most recent one (assuming the list is ordered or we just take the last one)
+    const targetCredDef = credDefs[credDefs.length - 1]
+    credDefId = targetCredDef.id
+    log(`Found credential definition: ${credDefId}`)
   }
+
+  if (!credDefId) {
+    throw new Error('Could not determine credential definition ID')
+  }
+
   // get connectionId for bob on alice
   const connections = await fetch(`${baseUrl}/v1/connections`, {
     method: 'GET',
@@ -195,6 +222,7 @@ async function main() {
   }
 
   log('Credential offer sent to maker. Awaiting acceptance...')
+  process.exit(0)
 }
 
 main().catch((e) => process.stderr.write((e as Error).stack + '\n') && process.exit(1))