Call Verification Example Utilities

Intro

This project provides utility scripts to generate and verify JWTs (JSON Web Tokens) for blockchain-enabled call verification, similar to the STIR/SHAKEN model. It supports creating key pairs, signing JWTs with private keys, and verifying them with public keys using ES256 (ECDSA P-256 + SHA-256).

---

How It Works

The caller verification flow includes:

• Key pair generation (ES256)

• JWT signing for originating phone numbers

• JWT verification using public keys

• Integration with KNS and the Sui blockchain

Requires:

• Node.js 22+

• ts-node installed globally (npm install -g ts-node)

• Project dependencies (npm install)

---

🛠️ Scripts Overview

Script	Description
generate-key.ts	Generates ES256 private/public key pair
authorize.ts	Signs a JWT using private key
verify.ts	Verifies a JWT using public key

---

🔐 1. Generate Key Pair

bashCopyEditts-node generate-key.ts [--private <privateKeyFilename>] [--public <publicKeyFilename>]

Output:

• es256-private-key-{timestamp}.pem

• es256-public-key-{timestamp}.pem

---

✍️ 2. Sign a JWT

bashCopyEditts-node ./authorize.ts <e164 OrigTN> <e164 DestTN> <CallID> <privateKeyFile> <outputJwtFile>

Example:

bashCopyEditts-node ./authorize.ts "[phone]" "[phone]" "abcdefg" ./es256-private-key.pem ./es256-signed.jwt

Output: es256-signed.jwt (JWT file)

---

✅ 3. Verify a JWT

bashCopyEditts-node ./verify.ts <jwtFile> <publicKeyFile>

Example:

bashCopyEditts-node ./verify.ts es256-signed.jwt es256-public-key.pem

Output:

• Decoded JWT (header, payload, signature)

• Verification status

---

🔁 Workflow Example

bashCopyEditts-node ./generate-key.ts
ts-node ./authorize.ts "[phone]" "[phone]" "abcdefg" es256-private-key.pem es256-signed.jwt
ts-node ./verify.ts es256-signed.jwt es256-public-key.pem

---

🐍 Python JWT Verification

Setup:

bashCopyEditcd python
python3 -m venv venv
source venv/bin/activate
pip install pyjwt cryptography

Verify:

bashCopyEditcd python
python verify.py ../es256-signed.jwt ../es256-public-key.pem

---

💻 .NET JWT Verification

Setup:

bashCopyEditsudo snap install dotnet-sdk

Verify:

bashCopyEditcd dotnet
dotnet run ../es256-signed.jwt ../es256-public-key.pem

---

🔗 SUI Blockchain Integration

📥 Keystore Registration

bashCopyEditts-node ./register-keystore.ts <publicKeyFile> <name> <creator> <imageUrl> <rawPrivateKey>

Example:

bashCopyEditts-node ./register-keystore.ts ./public_key.pem "Keystore v1" "Karrier One" "https://placehold.co/600x600.png?text=Keystore" "BASE64+SUI+PRIVATE+KEY"

---

🔍 Lookup KNS Object ID

Development:

bashCopyEditcurl --location 'https://kns-api.karrier.dev/kns/object-id-lookup' \
--header 'x-api-key: testkey' \
--header 'Content-Type: application/json' \
--data '{ "phoneNumber": "[phone]" }'

Production:

bashCopyEditcurl --location 'https://kns-api.karrier.one/kns/object-id-lookup' \
--header 'x-api-key: testkey' \
--header 'Content-Type: application/json' \
--data '{ "phoneNumber": "[phone]" }'

---

🔗 Map KNS ID to Certificate Registry

Add Entry:

bashCopyEditts-node ./map-kns-registry-add.ts <knsObjectId> <keyStoreObjectId> <rawPrivateKey>

Update Entry:

bashCopyEditts-node ./map-kns-registry-update.ts <knsObjectId> <keyStoreObjectId> <rawPrivateKey>

Remove Entry:

bashCopyEditts-node ./map-kns-registry-remove.ts <knsObjectId> <rawPrivateKey>

Dump Table:

bashCopyEditts-node ./map-kns-registry-dump.ts

---

🔑 Lookup Public Key for Phone Number

bashCopyEditts-node ./lookup-number-key.ts "[phone]"

Also supports:

bashCopyEditcurl --location 'https://kns-api.karrier.dev/kns/object-id-lookup' \
--header 'x-api-key: testkey' \
--header 'Content-Type: application/json' \
--data '{ "phoneNumber": "[phone]" }'

Response:

jsonCopyEdit{
  "objectId": "0xe8f55da072575d83ea17c6ee357edb344fa243aae071d552bdc4a7d69f740dec",
  "registries": []
}

---

🔁 Full JWT Verification Flow

Originating Server:

bashCopyEditts-node ./authorize.ts "[phone]" es256-private-key.pem es256-signed.jwt

Terminating Server:

bashCopyEditts-node ./verify-full-flow.ts es256-signed.jwt

API Call:

bashCopyEditcurl --location 'https://kns-api.karrier.dev/kns/call-signature-verification' \
--header 'x-api-key: testkey' \
--header 'Content-Type: application/json' \
--data '{
  "jwt": "<signed-jwt>",
  "origTN":"[phone]",
  "destTN":"[phone]"
}'

Response:

jsonCopyEdit{
  "success": true
}

---

Conclusion

This utility toolkit bridges identity, telecom, and blockchain technologies using JWT-based verification. It's ideal for telcos and platforms implementing secure call validation with the Karrier Number System.

For support or questions, contact [e-mail].

🔗 Reference

https://github.com/Karrier-One/caller-verification