Merge pull request #5 from AmeyParle/main

Improve JS examples and add HTTP DID resolution example

Author: chrishooooo-netizen

examples/README.md

@@ -1,37 +1,36 @@
 # TRAIL Protocol - Examples
 
-Working examples demonstrating how to use the `did:trail` DID method in practice.
+This directory contains practical examples for working with the `did:trail` DID method.
 
 ## Sample DID Documents
 
 | File | Description |
 |------|-------------|
-| `self-did-document.json` | Self-issued DID (Tier 0) - no registry, local trust only |
-| `org-did-document.json` | Organization DID with KYB attestation (Tier 1) |
-| `agent-did-document.json` | AI Agent DID with full trust chain (Tier 2) |
+| `self-did-document.json` | Example self-mode DID Document |
+| `org-did-document.json` | Example organization DID Document |
+| `agent-did-document.json` | Example agent DID Document |
 
 ## Code Examples
 
-> Coming soon - contributions welcome! See [Issue #4](https://github.com/trailprotocol/trail-did-method/issues/4).
+The JavaScript examples live in [`examples/js/`](./js/) and demonstrate:
 
-Planned examples:
+- DID generation in `self`, `org`, and `agent` modes
+- DID Document creation
+- local/offline resolution for `did:trail:self`
+- Verifiable Credential issuance and verification
+- tamper detection using `DataIntegrityProof`
 
-- **JavaScript/Node.js** - DID resolution, VC verification
-- More languages welcome via PR
+See [`examples/js/README.md`](./js/README.md) for setup instructions and how to run the scripts.
 
 ## Reference Implementation
 
-The [`@trailprotocol/core`](https://www.npmjs.com/package/@trailprotocol/core) npm package provides the full reference implementation:
+The [`@trailprotocol/core`](https://www.npmjs.com/package/@trailprotocol/core) npm package provides the reference implementation for:
 
 - DID generation and resolution
 - JSON Canonicalization (JCS, RFC 8785)
 - DataIntegrityProof (`eddsa-jcs-2023`)
 - Verifiable Credential issuance and verification
 
-```bash
-npm install @trailprotocol/core
-```
-
 ## Contributing
 
-See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines. `examples/` is a great entry point for first-time contributors.
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines. The `examples/` directory is a good entry point for first-time contributors.

examples/js/README.md

@@ -1,51 +1,72 @@
 # TRAIL Protocol - JavaScript Examples
 
-Working examples showing how to use `did:trail` with Node.js.
+This directory contains runnable JavaScript examples for the `did:trail` DID method using the `@trailprotocol/core` reference implementation.
 
 ## Prerequisites
 
-- Node.js 18+ (uses built-in `crypto` module)
+- Node.js 18 or newer
 - npm
 
 ## Setup
 
+From this directory:
+
 ```bash
-cd examples/js
 npm install
 ```
 
-## Examples
+## Run the examples
+
+### DID resolution example
 
-### DID Resolution (`did-resolution.js`)
+```bash
+npm run did-resolution
+```
 
-Creates DIDs in all three modes (self, org, agent), builds DID Documents, and resolves a self-issued DID offline.
+This script demonstrates:
+
+- generating an Ed25519 keypair
+- creating `did:trail:self`, `did:trail:org`, and `did:trail:agent` identifiers
+- building DID Documents
+- resolving a `did:trail:self` DID locally, without contacting a registry
+
+### Verifiable Credential example
 
 ```bash
-node did-resolution.js
+npm run vc-verification
 ```
 
-**What you'll learn:**
-- Ed25519 keypair generation
-- The three DID modes and their trust tiers
-- DID Document structure (W3C DID Core 1.0)
-- Offline resolution for self-mode DIDs
+This script demonstrates:
+
+- issuing a self-signed Verifiable Credential
+- inspecting the `DataIntegrityProof`
+- verifying the credential signature
+- detecting tampering by modifying a signed field and verifying again
 
-### VC Verification (`vc-verification.js`)
+Note: the tampered credential is expected to fail verification because the proof no longer matches the modified credential contents.
 
-Issues a self-signed Verifiable Credential with a DataIntegrityProof, then verifies it - including a tamper detection test.
+### HTTP registry resolution example
 
 ```bash
-node vc-verification.js
+npm run resolve-http
 ```
 
-**What you'll learn:**
-- Verifiable Credentials 2.0 structure
-- DataIntegrityProof with `eddsa-jcs-2023` cryptosuite
-- JSON Canonicalization (JCS, RFC 8785)
-- Cryptographic verification and tamper detection
+Or with a custom DID:
+
+```bash
+bash resolve-http.sh "did:trail:org:acme-corp-eu-a7f3b2c1e9d04f5a"
+```
+
+This demonstrates the HTTP resolution pattern for registry-backed `did:trail` identifiers.
+
+Note: The HTTP resolution example documents the expected API pattern. Live responses require a running TRAIL registry instance (public registry coming soon).
+
+## Package metadata
+
+The local `package.json` defines:
 
-## Reference
+- `npm run did-resolution`
+- `npm run vc-verification`
+- `npm run resolve-http`
 
-- [`@trailprotocol/core`](https://www.npmjs.com/package/@trailprotocol/core) - Full API reference
-- [TRAIL DID Method Spec](../../did-method-spec.md) - Specification v1.1.0
-- [CONTRIBUTING.md](../../CONTRIBUTING.md) - How to contribute
+and requires Node.js `>=18.0.0`.

examples/js/did-resolution.js

@@ -5,9 +5,9 @@
  *
  * Demonstrates how to:
  * 1. Generate an Ed25519 keypair
- * 2. Create did:trail DIDs (self, org, agent)
+ * 2. Create did:trail DIDs in self, org, and agent modes
  * 3. Build DID Documents
- * 4. Resolve a did:trail DID offline (self-mode)
+ * 4. Resolve a did:trail:self DID locally (offline)
  *
  * Prerequisites:
  *   npm install @trailprotocol/core
@@ -29,42 +29,46 @@ async function main() {
   // -------------------------------------------------------
   // Step 1: Generate an Ed25519 keypair
   // -------------------------------------------------------
+  // This keypair is the cryptographic root of the DID identity.
   const keys = generateKeyPair();
   console.log('=== Key Generation ===');
   console.log('Public key (multibase):', keys.publicKeyMultibase);
   console.log('Public key (JWK):', JSON.stringify(keys.publicKeyJwk, null, 2));
   console.log();
 
   // -------------------------------------------------------
-  // Step 2: Create DIDs in all three modes
+  // Step 2: Create DIDs in all three TRAIL modes
   // -------------------------------------------------------
-
-  // Self DID (Tier 0) - no registry needed, local trust only
   const selfDid = createSelfDid(keys.publicKeyMultibase);
+  const orgDid = createOrgDid('Acme Corporation', keys.publicKeyMultibase);
+  const agentDid = createAgentDid('Sales Assistant', keys.publicKeyMultibase);
+
   console.log('=== DID Creation ===');
   console.log('Self DID: ', selfDid);
-
-  // Org DID (Tier 1) - for organizations with KYB attestation
-  const orgDid = createOrgDid('Acme Corporation', keys.publicKeyMultibase);
   console.log('Org DID:  ', orgDid);
-
-  // Agent DID (Tier 2) - for AI agents with full trust chain
-  const agentDid = createAgentDid('Sales Assistant', keys.publicKeyMultibase);
   console.log('Agent DID:', agentDid);
   console.log();
 
+  console.log('Mode summary:');
+  console.log('  self  -> local/offline identity using embedded public key');
+  console.log('  org   -> organization identifier format for registry-backed use');
+  console.log('  agent -> agent/service identifier format, typically linked to a parent org');
+  console.log();
+
   // -------------------------------------------------------
   // Step 3: Build DID Documents
   // -------------------------------------------------------
+  // A DID Document describes the public keys, verification methods,
+  // and optional services associated with a DID.
   console.log('=== DID Documents ===');
 
-  // Self DID Document - simplest form
+  // Self DID Document: simplest form, suitable for local/offline verification.
   const selfDoc = createDidDocument(selfDid, keys, { mode: 'self' });
   console.log('Self DID Document:');
   console.log(JSON.stringify(selfDoc, null, 2));
   console.log();
 
-  // Agent DID Document - with parent organization reference
+  // Agent DID Document: includes a parent organization reference and registry service.
   const agentDoc = createDidDocument(agentDid, keys, {
     mode: 'agent',
     parentOrganization: orgDid,
@@ -77,8 +81,8 @@ async function main() {
   // -------------------------------------------------------
   // Step 4: Resolve a self DID (offline resolution)
   // -------------------------------------------------------
-  // Self-mode DIDs can be resolved without a registry because
-  // the public key is embedded in the DID itself.
+  // Self-mode DIDs can be resolved without a registry because the
+  // public key is embedded directly in the DID identifier.
   console.log('=== DID Resolution ===');
   const resolver = new TrailResolver();
   const result = await resolver.resolve(selfDid);
@@ -90,10 +94,9 @@ async function main() {
   console.log('  Trust Tier:', result.didDocument['trail:trailTrustTier']);
   console.log();
 
-  // TODO: Add registry-based resolution for org/agent DIDs
-  // (requires a running TRAIL Registry instance)
-
+  // Registry-based resolution for org/agent DIDs is typically performed
+  // via the TRAIL registry HTTP API rather than offline reconstruction.
   console.log('Done. All examples completed successfully.');
 }
 
-main().catch(console.error);
+main().catch(console.error);

examples/js/package.json

@@ -5,12 +5,13 @@
   "description": "TRAIL Protocol usage examples for Node.js",
   "scripts": {
     "did-resolution": "node did-resolution.js",
-    "vc-verification": "node vc-verification.js"
+    "vc-verification": "node vc-verification.js",
+    "resolve-http": "bash resolve-http.sh"
   },
   "dependencies": {
     "@trailprotocol/core": "^0.1.0"
   },
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}

examples/js/resolve-http.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+# TRAIL Protocol - curl/HTTP DID Resolution Example
+#
+# Demonstrates the HTTP resolution pattern for registry-backed
+# did:trail identifiers (typically org/agent mode).
+#
+# Usage:
+#   ./resolve-http.sh "did:trail:org:acme-corp-eu-a7f3b2c1e9d04f5a"
+
+# Note:
+# This example demonstrates the expected HTTP request format for
+# registry-backed DID resolution. A successful live response depends
+# on the public registry endpoint being reachable from your environment.
+
+
+set -euo pipefail
+
+DID="${1:-did:trail:org:acme-corp-eu-a7f3b2c1e9d04f5a}"
+BASE_URL="https://registry.trailprotocol.org/1.0/identifiers"
+
+echo "Resolving DID via TRAIL registry API..."
+echo "DID: $DID"
+echo
+
+curl -sS \
+  -H "Accept: application/did+ld+json" \
+  "${BASE_URL}/${DID}"
+
+echo

examples/js/vc-verification.js

@@ -7,7 +7,7 @@
  * 1. Create a self-signed Verifiable Credential (VC 2.0)
  * 2. Inspect the DataIntegrityProof (eddsa-jcs-2023)
  * 3. Verify the credential cryptographically
- * 4. Detect tampering (negative test)
+ * 4. Detect tampering with a negative test
  *
  * Prerequisites:
  *   npm install @trailprotocol/core
@@ -39,12 +39,12 @@ async function main() {
   // -------------------------------------------------------
   // createSelfSignedCredential(issuerDid, subjectDid, claims, privateKeyBytes)
   //
-  // This creates a VC 2.0 credential with a DataIntegrityProof
-  // using the eddsa-jcs-2023 cryptosuite (Ed25519 + JCS RFC 8785).
-  // For self-signed VCs, issuer and subject are the same DID.
+  // This creates a VC with a DataIntegrityProof using the
+  // eddsa-jcs-2023 cryptosuite (Ed25519 + JCS canonicalization).
+  // In this example, issuer and subject are the same DID.
   const credential = createSelfSignedCredential(
     issuerDid,
-    issuerDid, // subject = issuer (self-signed)
+    issuerDid,
     {
       type: 'TrailTrustAttestation',
       aiSystemType: 'agent',
@@ -72,23 +72,28 @@ async function main() {
   // -------------------------------------------------------
   // Step 4: Verify the credential
   // -------------------------------------------------------
-  // verifyCredential(vc, publicKeyBytes) checks:
-  // - Required VC fields (@context, type, issuer, issuanceDate, credentialSubject)
-  // - DataIntegrityProof signature validity
+  // verifyCredential(vc, publicKeyBytes) checks required VC fields
+  // and verifies the DataIntegrityProof signature.
   console.log('=== Verification ===');
   const result = verifyCredential(credential, issuerKeys.publicKeyBytes);
   console.log('Credential valid:', result.valid);
   console.log('Errors:', result.errors.length === 0 ? 'none' : result.errors);
   console.log();
 
+  console.log('Verification summary:');
+  console.log('  A valid credential passes signature verification.');
+  console.log('  Any change to signed content should invalidate the proof.');
+  console.log();
+
   // -------------------------------------------------------
   // Step 5: Tamper detection (negative test)
   // -------------------------------------------------------
-  // Modify the credential and verify again - should fail
-  // because the signature no longer matches the content.
+  // This simulates someone modifying a signed field after issuance.
+  // Because the proof was created over the original credential
+  // contents, verification should now fail.
   console.log('=== Tamper Detection ===');
   const tampered = JSON.parse(JSON.stringify(credential));
-  tampered.credentialSubject.trailTrustTier = 2; // Attacker tries to upgrade trust tier
+  tampered.credentialSubject.trailTrustTier = 2;
 
   const tamperedResult = verifyCredential(tampered, issuerKeys.publicKeyBytes);
   console.log('Tampered credential valid:', tamperedResult.valid, '(expected: false)');
@@ -98,4 +103,4 @@ async function main() {
   console.log('Done. All examples completed successfully.');
 }
 
-main().catch(console.error);
+main().catch(console.error);