DEV Community: Darshit Khandelwal

LFDT: Week 5 Report

Darshit Khandelwal — Wed, 29 Jul 2026 13:51:14 +0000

Week 5: Actually Issuing the Credential

Firstly before starting, apologies to everyone who might be following with me, I was busy with my internship interviews, (I had an interview with Google, I would talk about that in some other blog in detail).
So, I was unable to do much of the work, but, now I am back on track with full energy and motivation !
The first four weeks were about building the foundation , the schema, the DID, the GPG verification, the identity binding. Week 5 is where the foundation stops being theoretical. This is the week a real signed credential actually gets issued into a contributor's wallet.

Here's everything that happened.

The Problem This Week Solves

At the end of Week 4, we had a ContributorBinding record in the database that said: "this person's GitHub account, GPG key, and Heka wallet are all confirmed as belonging to the same human."

That's meaningful, but it's still just a database row. It lives entirely inside Heka's infrastructure. A wallet can't hold it. A verifier can't check it independently without calling Heka's API. It's not portable, and it's not self-contained.

What we actually want is a Verifiable Credential — a cryptographically signed document the contributor holds in their own wallet, which any verifier can check without calling home.

Week 5 is how we get there.

What is OID4VCI?

OpenID for Verifiable Credential Issuance (OID4VCI) is the protocol that defines how an issuer hands a credential to a wallet. It's the handshake between Heka (the issuer) and the contributor's wallet (the holder).

The short version of how it works:

The wallet discovers what credentials an issuer can issue, via a .well-known/openid-credential-issuer metadata document
The issuer creates a credential offer — a URI starting with openid-credential-offer:// that the wallet scans or follows
The wallet authenticates and presents proof of key possession
The issuer signs the credential and delivers it

This week implemented steps 1 and 2. Steps 3 and 4 are handled by the existing Credo/AFJ framework already wired into heka-identity-service.

The Static Issuer: One Global Issuer for the Prototype

One design decision I want to explain upfront: we are not building multi-tenant dynamic issuer provisioning. This is a prototype, and the goal is to validate the end-to-end flow cleanly without admin overhead.

Instead, there is a single static global issuer — the pre-existing demo tenant (the same DEMO_USER account already used in heka-auth-service). On every application startup, a bootstrap sequence runs:

Look up the demo user's wallet → get their Credo tenant ID
Open their tenant agent
Check if an OID4VCI issuer record exists for their did:hedera DID
If not → create it (including the GithubContributorCredential profile)
If yes → check if GithubContributorCredential is already in the supported list
If not → add it (idempotent)
If yes → log and skip

The entire sequence is idempotent by design. Restarting the application never creates duplicate issuers or duplicate credential configurations. The bootstrap can fail gracefully (missing wallet, missing DID) without crashing the application — it just logs a warning.

This is the same pattern used by the PrepareWalletService in this codebase. When the infrastructure is ready, everything self-configures.

The GithubContributorCredential Profile

The credential type registered in the issuer metadata is GithubContributorCredentialSdJwt, with a VCT (Verifiable Credential Type) URI of:

https://hiero.ledger.org/vct/GithubContributorCredential

This URI is how wallets and verifiers identify what kind of credential they're dealing with. It's the same identifier defined in the Week 2 schema.

The credential profile declares all five claims:

claims: {
  githubAccountId: { mandatory: true },
  githubUsername:  { mandatory: true },
  gpgFingerprint:  { mandatory: true },
  verifiedAt:      { mandatory: true },
  walletId:        { mandatory: true },
}

SD-JWT: Selective Disclosure in Practice

The credential format is SD-JWT VC (Selective Disclosure JWT Verifiable Credential). The "selective disclosure" part is what makes this interesting.

A standard JWT credential puts all its claims in the open. Anyone who receives it can see everything. An SD-JWT VC lets the holder choose which claims to reveal and which to keep private, on a per-presentation basis.

The "disclosure frame" is what controls this. It's a configuration that tells the signing framework which claims should be placed in cryptographically blinded digest groups (_sd) rather than revealed directly:

// Week 2 disclosure policy
const disclosureFrame = {
  _sd: ['githubUsername', 'gpgFingerprint']
}

What this means in practice:

Claim	Always in the credential?	Can the holder hide it?
`githubAccountId`	✅ Always revealed	No — it's the identity anchor
`verifiedAt`	✅ Always revealed	No — it's the audit timestamp
`walletId`	✅ Always revealed	No — it's the wallet binding
`githubUsername`	Digest only	✅ Yes — holder can choose
`gpgFingerprint`	Digest only	✅ Yes — holder can choose

The design intent: a contributor should be able to prove they are a verified Hiero contributor (by showing their numeric account ID and verification timestamp) without necessarily revealing their GitHub handle or GPG key fingerprint to every verifier. The holder controls what gets shared.

Deterministic Verification Method Selection

When signing the SD-JWT VC, you need to select which verification method (which key) from the issuer DID document to sign with. If you pick differently each time, different verifiers may not be able to reproduce the check.

The approach here is simple and consistent with how the rest of heka-identity-service handles this: take the first verification method from the resolved DID document. For a did:hedera DID with a single key pair (which is the standard setup for the demo tenant), this is always the same key. Deterministic, predictable, no surprise.

The Credential Offer Endpoint

POST /v2/contributor-credential/offer
{ "githubAccountId": "12345678" }

The service:

Looks up the ContributorBinding for the given GitHub account ID
Throws 404 if no binding exists (contributor hasn't completed OAuth login)
Throws 409 if the binding exists but GPG verification is incomplete
Resolves the demo tenant's did:hedera DID
Builds the SD-JWT VC payload from the binding fields
Applies the Week 2 disclosure frame
Calls Credo's createCredentialOffer() directly
Returns the openid-credential-offer:// URI

A key implementation detail on step 7: I'm calling tenantAgent.openid4vc.issuer.createCredentialOffer() directly rather than routing through OpenId4VcIssuanceSessionService.offer(). The reason is that the session service unconditionally calls statusListService.getOrCreate(authInfo) — which needs a full User entity from the database — before checking whether the credential even uses revocation. SD-JWT VCs don't support revocation (it's in the spec). Routing around the status list check for SD-JWT VCs is actually the architecturally correct thing to do here.

Two Bugs Found During Review

I did a deep review pass before calling Week 5 done. Two real bugs caught:

Bug 1: Wrong enum value (silent failure)

The updateIssuerMetadata call was using:

action: 'Add' as const  // ❌ Wrong

The actual enum is:

UpdateIssuerSupportedCredentialsAction.Add = 'add'  // lowercase

The switch statement in issuer.service.ts was hitting the default branch and silently doing nothing. The credential config would never have been registered on existing issuers. Fixed to use the proper enum import.

Bug 2: Fake AuthInfo crashing the status list service

Earlier I was constructing a minimal auth-info object to pass to the session service. The status list service does em.find(CredentialStatusList, { owner: authInfo.user }) — and authInfo.user was undefined, which would have been a runtime crash on every credential offer request. Fixed by bypassing the session service entirely (see step 7 above).

Both bugs were caught by reading the actual source of every dependency — not just the types. TypeScript alone won't catch a structural type that's missing a field when the missing field is only accessed at runtime inside a service you're calling.

Test Coverage

11 unit tests covering:

Bootstrap creates issuer when demo wallet exists and no issuer is registered
Bootstrap skips when credential config already registered
Bootstrap logs warning without throwing when demo wallet is missing
Bootstrap uses the correct 'add' enum value (explicit assertion)
Credential offer returns a valid openid-credential-offer:// URI
Payload carries all five Week 2 claims with correct values
Disclosure frame contains exactly the two selectively disclosable claims
Non-selectively-disclosable claims are absent from _sd
Verification method from DID document is passed through (deterministic selection)
NotFoundException when no binding exists
ConflictException when binding is GPG-unverified
NotFoundException when demo tenant wallet is missing

307 total tests, all passing.

How the Five Weeks Connect

Looking back at the full arc:

Week 1: Project setup, infrastructure, development environment
Week 2: Credential schema, disclosure policy, DID on Hedera testnet
Week 3: GPG challenge-response — cryptographic proof of key ownership
Week 4: Identity binding — tying GPG key, GitHub account, and Heka wallet together permanently
Week 5: OID4VCI issuance — turning that binding into a real signed credential a wallet can hold

Each week was a necessary prerequisite for the next. You can't issue a credential without a schema (Week 2). You can't bind an identity without verifying the key (Week 3). You can't issue a meaningful credential without a completed binding (Week 4).

What's Next

Week 6 moves into the Web Wallet UI and the PR-gating flow — the two pieces that make the credential actually useful. A contributor will be able to present their GithubContributorCredential when opening a PR, and the GitHub App will check the verification status before allowing the PR to be merged.

The credential is now real. Next week it starts doing work.

See you then.

This is part of my LFDT Mentorship 2026 blog series. Each week I write about what I built, what I learned, and what surprised me. If you're working on decentralized identity, verifiable credentials, or open source supply chain security, I'd love to hear from you.

Week 4 - LFX Mentorship

Darshit Khandelwal — Tue, 14 Jul 2026 17:31:55 +0000

A quick note before I start: I was running slightly behind schedule, so I combined Weeks 3 and 4 into one push. The good news is that what came out the other side is more complete than either week would have been in isolation — the two pieces fit together naturally, and building them back-to-back made the design tighter.

Here's everything that happened.

The Problem These Two Weeks Solve

Before Week 3, we had a schema on paper and a DID on the testnet. But nothing was actually checking anything. No one was being verified. No PR was being gated.

The gap was this: how do you take "this person claims to be darshit2308 on GitHub" and turn it into something a machine can trust cryptographically?

That's what Week 3 answered. And Week 4 answered the follow-up question: once you've verified the GPG key, how do you bind that proof permanently to a real identity — one that ties together their GitHub account, their GPG key, and their Heka wallet — so the system doesn't have to re-verify every single time?

Let's go through both.

Week 3: The Cryptographic Foundation

How GPG Challenge-Response Works (and Why We're Doing It This Way)

The core idea is simple but elegant. Your GitHub profile can optionally have GPG public keys attached to it. Anyone can see them. What only you can do is sign something with the matching private key — which never leaves your machine.

So the verification flow goes like this:

You ask Heka for a challenge — a random one-time string called a nonce
Heka generates the nonce, ties it to your GitHub username, and starts a 5-minute countdown
You run one command locally: echo "<nonce>" | gpg --clearsign
You send the signed output back to Heka
Heka fetches your public GPG key directly from github.com/your-username.gpg and checks the math

If the signature is valid, it proves two things at once: you control the private key, and that private key is registered to your GitHub account. You can't fake either of those.

This is not a new idea — it's the same mechanism behind SSH authentication and code signing. We're applying it to contributor identity.

Building the Module

The GPG module lives inside heka-identity-service/src/gpg-challenge/ as a self-contained NestJS module. Three endpoints:

POST /request — Generate a challenge. Takes a GitHub username, returns a nonce. Under the hood, it uses crypto.randomBytes(32) — 256 bits of OS-level randomness — and stores it with a 5-minute expiry.

POST /verify — Verify a signed challenge. This is where the interesting work happens.

GET /status — Check if a GitHub username is verified.

The Security Detail I'm Most Proud Of: Burn Before Verify

The replay attack scenario goes like this: someone intercepts a valid signed payload in transit, and tries submitting it again after you've already verified. If we mark the nonce as consumed after verification succeeds, and the process crashes between those two steps, the attacker can replay the same payload and it'll pass again.

The fix is simple but requires thinking about failure modes:

challenge.consumed = true;
await this.challengeRepo.getEntityManager().flush(); // This happens FIRST
// Only after the DB write commits do we touch the network

The nonce is marked consumed and flushed to the database before any network call or cryptographic work happens. Even if the server crashes mid-verification, the nonce is permanently dead. The contributor just needs to request a fresh one.

This is called "burn before verify" and it eliminates the replay window entirely.

Error Handling: Every Failure Path

One thing I wanted to get right early was making errors actually useful to contributors. There are 10 distinct failure scenarios in this module, and each one returns a specific HTTP status and a message that tells you what to do:

What went wrong	Status
Challenge ID doesn't exist	404
Nonce already used (replay blocked)	400
Challenge expired	400
No GPG key on your GitHub profile	400
GitHub rate limiting us	429
GitHub unreachable	503
GPG key body is empty	400
Key format is unparseable	400
Signed message is malformed	400
Signature is mathematically wrong	200 `{ verified: false }`

That last one is deliberate — a failed signature isn't a server error, it's a valid answer from the verification system. It returns 200 with verified: false rather than throwing an exception.

25 Tests, All Passing

16 unit tests covering every failure path above, with the burn-before-verify ordering explicitly tested (the test verifies that flush() is called before the GitHub API mock fires)
9 integration tests against a real PostgreSQL instance, covering the full HTTP stack including replay via double-submit and expired record insertion via ORM

The GitHub App: Making PRs Actually Respond

The GitHub App lives in a separate repository (GitHub integration code stays separate from heka-identity-service, as agreed in the architecture). It's built on Probot.

Why Probot? Two things I would have had to build myself are handled automatically:

Webhook signature validation: Every incoming request from GitHub is signed with HMAC-SHA256. Probot validates that signature before any application code runs. Invalid signature → 400, nothing fires.

GitHub App authentication: GitHub Apps authenticate using JWT tokens that expire every 10 minutes. Probot manages the entire JWT lifecycle. I never touch it.

The async acknowledgment problem: GitHub requires your webhook endpoint to respond with HTTP 200 within 10 seconds. But checking Heka, creating a check run, and doing DID resolution can take longer than that under real network conditions. Probot solves this cleanly — it returns 200 immediately, and fires application listeners asynchronously through its internal event emitter. The listeners are not in the response path.

Idempotency: GitHub can and does redeliver webhook events. Without idempotency, you'd end up with multiple check runs for the same commit cluttering the PR view. Before creating a new check run, the app looks up whether one already exists for the exact commit SHA and check name. If a non-queued run exists, it exits early. The key is using the SHA (not the PR number) — a new push to the same PR produces a new SHA and correctly triggers a new check, while a retried webhook delivery hits the guard and does nothing.

End-to-end proof: The full flow was validated live on the Heka-Webhook-Fixture repository. A PR opened, Heka's identity check fired, and the check run appeared in the GitHub UI. That closed the loop on Week 3.

Week 4: Binding the Proof to a Real Identity

Week 3 answered "can you prove you own this GPG key?" Week 4 answered the follow-up question: "okay, but now what do we actually do with that proof?"

The answer is a ContributorBinding — a record that ties together three things permanently:

The GitHub OAuth account (with its numeric account ID)
The verified GPG fingerprint
The Heka wallet

Why all three? Because each one alone is insufficient:

GitHub account alone is spoofable
GPG key alone doesn't prove which GitHub account you are
Wallet alone is just a key pair with no human identity attached

The binding is what makes the proof durable. Once created, the system can verify you on future PRs without requiring a fresh GPG signature every single time.

What Changed in the Database

The GpgChallenge entity was upgraded to track not just githubUsername, but also:

githubAccountId — the immutable integer ID from GitHub (users can change their handle, but this never changes, which is how we handle username renames without losing their verification status)
walletId — the Heka wallet of the authenticated user who requested the challenge

Audit Logging: Every State Transition is Recorded

The ContributorOnboardingModule is now wired directly into the GPG verification flow. Every meaningful event gets recorded:

recordChallengeRequested — fires when a challenge is generated, against the contributor's wallet profile
recordProofAccepted — fires when verification succeeds
recordProofRejected — fires when verification fails

This matters for maintainers. If something goes wrong with a contributor's verification status, there's a full audit trail of what happened and when.

The Wallet Enforcement Check

This one is a subtle but important security detail. When a contributor submits their GPG signature for verification, we now check that the walletId submitting the request matches the walletId that originally requested the challenge.

Why does this matter? Without it, someone could theoretically observe that wallet A requested a challenge for username X, then try to claim that verification from wallet B. The wallet enforcement check closes that gap.

The Status Endpoint Rework

The /status endpoint in Week 3 checked the GPG challenges table directly — if a challenge was verified, you're good. That's fine for a prototype, but it has a flaw: it only tells you the GPG proof succeeded. It doesn't tell you whether the full binding (GPG key + GitHub account + Heka wallet) was actually completed.

In Week 4 the endpoint was refactored to check for a finalized ContributorBinding record instead. This means:

verified: true now means the GPG key, GitHub account, and Heka wallet are all tied together and confirmed
There's no state where partial verification gets treated as complete
The GitHub App can trust the status endpoint as a real signal, not just an intermediate step

How the Two Weeks Connect

The progression makes more sense when you see it as one arc:

Week 3 built the cryptographic primitive: "this person controls this GPG key."

Week 4 turned that primitive into a durable identity claim: "this GPG key, this GitHub account, and this Heka wallet all belong to the same person."

Without Week 3, you have no cryptographic proof. Without Week 4, that proof evaporates after each verification and doesn't attach to anything persistent. Together, they're the foundation that Weeks 5 and beyond (OID4VCI issuance, the Web Wallet, PR-gating) are built on top of.

What's Next

Week 5 is OID4VCI issuer metadata and SD-JWT VC issuance — taking the GithubContributorCredential schema from Week 2 and wiring it into Heka's OpenID4VC issuance flow so contributors actually receive a signed credential into their wallet.

The schema design, the DID infrastructure, the GPG verification, and the identity binding are all in place. Next week is where it starts issuing real credentials.

See you then.

This is part of my LFDT Mentorship 2026 blog series. Each week I write about what I built, what I learned, and what surprised me. If you're working on decentralized identity or open source supply chain security, I'd love to hear from you.

Week 3 :The First Real Code

Darshit Khandelwal — Mon, 06 Jul 2026 10:45:05 +0000

Last week was all about schemas, fixtures, and design work. This week, the first real production code went into the Hiero codebase. Two parallel tracks running at the same time: a full NestJS GPG challenge module inside heka-identity-service, and the initial skeleton of the GitHub App that will eventually gate pull requests.

Let me walk through both.

What This Week Was About

The plan for Week 3 had two parallel tracks:

Track A — Inside heka-identity-service:

Port the GPG challenge-response flow from the MVP prototype into a proper NestJS module
Cryptographically secure nonces, 5-minute TTL, single-use enforcement
Full error handling for every failure scenario
Unit and integration tests covering all paths

Track B — In the separate GitHub App repo:

Build the initial Probot adapter skeleton
Webhook signature validation and GitHub App authentication
Async acknowledgment pattern so GitHub doesn't time out waiting for us
Idempotent check run creation

Let's go through both in detail.

Track A: The GPG Challenge Module

What is a GPG Challenge-Response, and why does it matter?

Before I explain what I built, let me quickly explain what problem this solves.

The whole point of this project is to replace "GitHub says this person is who they claim to be" with "this person can cryptographically prove it." The way we do that is through a challenge-response flow:

The contributor asks Heka for a challenge (a random string called a nonce)
Heka generates a nonce and ties it to their GitHub username
The contributor signs that nonce using their GPG private key (which never leaves their machine)
They send the signature back to Heka
Heka fetches the contributor's public GPG key directly from github.com/:username.gpg and verifies the signature mathematically

If verification passes, it proves two things simultaneously: the person controls the GPG private key, and that private key is registered to their GitHub account. You can't fake either of those without physically having the key.

This is the same mechanism used by SSH authentication, code signing, and certificate issuance — it's a well-understood cryptographic primitive.

The NestJS Module Structure

The flow now lives inside heka-identity-service/src/gpg-challenge/ as a self-contained NestJS module:

src/gpg-challenge/
  gpg-challenge.module.ts      ← Module boundary
  gpg-challenge.entity.ts      ← Database schema for challenge sessions
  gpg-challenge.service.ts     ← All the business logic
  gpg-challenge.controller.ts  ← HTTP surface with Swagger docs
  dto/                         ← Typed, validated request bodies

The module is imported in app.module.ts and registered in the ORM config for migrations, so it's a proper first-class citizen of the Heka codebase — not a bolted-on addon.

Generating Secure Nonces

const nonce = crypto.randomBytes(32).toString('hex'); // 256 bits of entropy

This uses Node's built-in crypto module, which pulls randomness from the OS-level CSPRNG (Cryptographically Secure Pseudo-Random Number Generator). The result is 64 hexadecimal characters — genuinely unpredictable, impossible to brute-force.

The nonce is stored alongside the contributor's githubUsername, so it's cryptographically bound to a specific account. You can't take a nonce issued to one user and sign it as a different user.

The 5-Minute TTL and Single-Use Enforcement

const expiresAt = new Date();
expiresAt.setMinutes(expiresAt.getMinutes() + 5);

The TTL is enforced server-side at verification time — not by trusting the client's clock.

The more interesting part is burn-before-verify: the challenge is marked as consumed in the database before any network or cryptographic work happens:

challenge.consumed = true;
await this.challengeRepo.getEntityManager().flush(); // Persisted BEFORE anything else

Why does the order matter? If we verified first and then marked consumed, and the process crashed between those two steps, an attacker who intercepted the signed payload could replay it — the DB would still say "not consumed." By burning the nonce first, even a mid-verification crash leaves the nonce permanently invalidated. This is the correct implementation of replay attack prevention.

Error Handling: Every Failure Path Covered

One thing I'm particularly happy with this week is how comprehensive the error handling is. There are 10 distinct failure scenarios, each with its own HTTP status code and a human-readable message:

Scenario	HTTP Status
Unknown challenge ID	404
Replay attempt (already consumed)	400
Expired challenge	400
GitHub 404 (no GPG key on profile)	400
GitHub rate limit (403/429)	429
GitHub unreachable (network failure)	503
Empty GPG key body	400
Unparseable public key	400
Unparseable armored message	400
Signature math fails	200 `{ verified: false }`

That last one is intentional — a failed signature isn't a server error, it's a valid "no" from the verification system.

The Test Suite

Unit tests (16 tests):

Every failure path above is tested in isolation
The burn-before-verify ordering is verified — the test confirms that flush() is called before the GitHub API mock fires
No real database or network required — uses deep mocks throughout

Integration/E2E tests (9 tests):

Runs against a real PostgreSQL instance with the full NestJS HTTP stack
Covers all 3 endpoints, DTO validation, replay via double-submit, and expired record insertion

Combined: 25 tests, all passing.

Track B: The GitHub App Skeleton

What the GitHub App Actually Does

The GitHub App sits in a separate repository (as decided with my mentor — GitHub integration code stays separate from heka-identity-service). Its job, at the end of the mentorship, will be to:

Receive a webhook when someone opens a PR
Ask Heka whether that contributor is verified
Post a passing or failing check run to the PR

This week's scope was just the skeleton — the infrastructure that makes the above possible. The actual Heka verification call comes in a later week.

Why Probot?

Probot is a Node.js framework specifically designed for building GitHub Apps. It handles two things that would otherwise be painful to implement manually:

Webhook signature validation: Every incoming webhook request from GitHub is signed using HMAC-SHA256. Probot validates that signature before any application code runs. If it's invalid, Probot returns 400 and nothing fires. This is a security guarantee I get for free.

GitHub App authentication: GitHub Apps authenticate using JWT tokens derived from a private key, and those tokens expire every 10 minutes. Probot manages the JWT lifecycle automatically — I never touch it directly.

The Async Acknowledgment Pattern

GitHub has a hard rule: your webhook endpoint must respond with HTTP 200 within 10 seconds, or GitHub marks the delivery as failed and schedules a retry.

The problem is that checking Heka, creating a check run, and resolving a DID can easily take more than 10 seconds under real network conditions. If we handle everything synchronously in the webhook handler, we'll be timing out constantly.

Probot solves this cleanly: it responds 200 to GitHub immediately on receipt, and fires the application listeners asynchronously through its internal event emitter. The listeners are not in the response path.

// Probot guarantees:
//   - HTTP 200 returned to GitHub immediately on receipt (before async
//     listeners complete), satisfying the 10-second delivery timeout

So GitHub gets its 200, and our actual logic runs in the background.

Idempotent Check Runs

This one is important. GitHub can and does re-deliver webhook events — if your server was temporarily unreachable, GitHub will retry. Without idempotency, you'd end up with multiple check runs for the same commit, cluttering the PR UI.

The fix: before creating a new check run, we check whether one already exists for the exact commit SHA and check name. If a non-queued run already exists, we return early:

const existing = await context.octokit.checks.listForRef({
  ...context.repo(),
  ref: sha,
  check_name: CHECK_NAME,
});

The key is using the SHA (not the PR number) as the identifier. A new commit push to the same PR produces a new SHA, which correctly triggers a new check run. A retry of the same webhook event produces the same SHA, which hits the idempotency guard and does nothing.

One Honest Gap

The GitHub App code handles all the right events, the idempotency logic is correct, and the tests pass — but I haven't yet done a live end-to-end test where I actually open a PR in the webhook fixture repository and watch the check run appear in the GitHub UI.

That's the one remaining evidence item not yet checked off for this week. It'll be verified and documented before Week 4 work begins.

What Surprised Me This Week

The burn-before-verify ordering. I initially wrote the code to verify first and mark consumed after. The issue with that is subtle — it feels more "logical" to verify before committing anything, but it creates a tiny window where a replayed nonce could succeed if the process crashes between verification and the consumed flag being set. Flipping the order eliminates that window entirely. Small detail, but the kind of thing that separates a working prototype from a production system.

The Probot architecture. I expected to have to wire up the async response pattern manually, but Probot's design means I get it for free. Understanding why it works that way (the event emitter is separate from the HTTP response path) made it click.

Looking Ahead

Week 4 is GitHub OAuth and contributor binding — implementing the actual GitHub login flow in Heka and persisting the verified contributor binding (account ID, username, wallet ID, GPG fingerprint) with audit events for every state transition. That's where the schema fixtures from Week 2 start being used in anger.

The PR for this week's work is under work, since the code is really a lot to process when reviewed by mentors, so i am trying to find a way, to clean and modularise the code a little bit. If the PR gets ready, i will update this blog.
See you in Week 4!

This post is part of my LFDT Mentorship 2026 blog series. Each week I write about what I built, what I learned, and what actually surprised me along the way.

Week -02

Darshit Khandelwal — Tue, 30 Jun 2026 14:21:36 +0000

Building the GitHubContributorCredential: SD-JWT Design and Hedera DID Verification

This week's goals were:

Define the complete GitHubContributorCredential schema, including contributor DID, GitHub username, GitHub numeric account ID, verified GPG fingerprint, issuer DID, issuance time, expiry, and credential status reference.
Design the SD-JWT disclosure policy and determine which claims are always disclosed versus selectively disclosed.
Create example credential payloads and schema fixtures that can be reused throughout implementation and testing.
Validate the credential model with unit tests covering valid and invalid credential subjects.
Create and resolve a did:hedera DID on Hedera testnet using the operator credentials agreed during Week 1.
Capture proof of successful DID creation and resolution through HashScan and resolver outputs.
Implement deterministic verification-method selection so signing operations never depend on array ordering such as verificationMethod[0].
Add tests covering DID resolution and verification-method selection behavior.

Here's how the week went, day by day.

1. Defining the GitHubContributorCredential schema

GitHubContributorCredential holds every field our system needs to identify a contributor. To keep it usable by the Heka backend service, we split the fields into two categories: standard VC metadata (the outer wrapper) and the credential subject (the actual identity claims).

Standard VC metadata

Issuer DID — the did:hedera identifier of the Heka platform issuing the credential.
Issuance time — the ISO 8601 timestamp of when the proof was generated.
Expiry — when the credential needs to be renewed (e.g., six months or a year from issuance).
Credential status reference — a pointer to the revocation registry on the Hedera network, so Heka can revoke the credential if a contributor's keys are compromised.

Credential subject (the contributor claims)

Contributor DID — the developer's personal did:hedera identifier.
GitHub username — the human-readable handle (e.g., darshit2308).
GitHub numeric account ID — the immutable integer ID GitHub assigns to every account. This matters because a user can change their handle, but the numeric ID never changes.
Verified GPG fingerprint — the cryptographic fingerprint of the key used to sign commits, proving the holder controls the private key registered against their GitHub account.

Putting it all together, here's the schema draft:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "type": ["VerifiableCredential", "GitHubContributorCredential"],
  "issuer": "did:hedera:testnet:z6MkhaXgBZDvotDkL5257faiztiuC2ZXOS",
  "issuanceDate": "2026-06-28T00:00:00Z",
  "expirationDate": "2027-06-28T00:00:00Z",
  "credentialStatus": {
    "id": "https://heka.network/status/123",
    "type": "CredentialStatusList2020"
  },
  "credentialSubject": {
    "id": "did:hedera:testnet:z6Mkq...",
    "githubUsername": "darshit2308",
    "githubAccountId": 4115704,
    "gpgFingerprint": "3AA5C34371567BD2"
  }
}

A quick walkthrough for anyone new to verifiable credentials:

@context tells any parser "read this using W3C Verifiable Credentials rules" — it gives the document its vocabulary.
id is just a unique identifier for the credential document itself.
type declares what kind of credential this is.
Everything else maps to the eight fields described above.

Note for later: CredentialStatusList2020 isn't an officially standardized status type — the current W3C recommendation is the Bitstring Status List spec (BitstringStatusListEntry). Worth revisiting before this goes to production, even if CredentialStatusList2020 stays as an internal placeholder for now.

2. Designing the SD-JWT disclosure policy

Quick primer on SD-JWT (Selective Disclosure JWT) for anyone unfamiliar: it lets a credential holder reveal only the claims required to verify something, without exposing everything else. A simple analogy — a bouncer checking you're over 18 doesn't need your phone number or home address, just proof of age.

So we split GitHubContributorCredential into two buckets: fields that are always disclosed (mandatory for the system to function) and fields that are selectively disclosed (hidden by default, to protect the developer's privacy).

Always disclosed

Issuer DID — Heka needs to know who issued the credential.
Issuance & expiry dates — Heka needs to verify the time limits.
Credential status — Heka must be able to check whether it's been revoked.
Contributor DID (sub) — the developer's public identifier on the Hedera network.

Selectively disclosed

GitHub username — a developer may want to prove they're an authorized LFDT contributor without permanently linking their Hedera DID to a public GitHub handle anyone could scrape.
GitHub numeric account ID — kept hidden unless the backend specifically needs to map the DID to an exact GitHub account.
Verified GPG fingerprint — only revealed when a repository explicitly needs it to verify a signed commit.

3. Example payloads and schema fixtures

Since we won't reveal every field by default, the SD-JWT payload replaces the hidden fields with an _sd (selective disclosure) array of hashes. A first pass looked like this:

{
  "iss": "did:hedera:testnet:z6MkhaXgBZDvotDkL5257faiztiuC2ZXOS",
  "iat": 1782604800,
  "exp": 1814140800,
  "sub": "did:hedera:testnet:z6Mkq...",
  "vct": "GitHubContributorCredential",
  "_sd": [
    "JzYx0... (hash of githubUsername)",
    "Qp2Lm... (hash of githubAccountId)",
    "Xy9Rq... (hash of gpgFingerprint)"
  ],
  "_sd_alg": "sha-256"
}

Public (always-disclosed) fields: iss (issuer), iat (issuance time), exp (expiry), sub (contributor DID), and vct (the credential type — since it's not in _sd, it's visible by default too).

Hidden fields: username, account ID, GPG fingerprint.

_sd_alg declares exactly which hash function was used, so the verifier knows how to check the disclosures later.

The verifier can't just brute-force the hidden fields from the hashes, since that would defeat the point — anyone could disclose everything by guessing. So each hidden claim is paired with a random salt before hashing: the disclosure is really hash(salt + claim_name + claim_value), and only the holder can produce the matching salt+value pair when asked to disclose it.

Where this landed

The finished schema fixture (JSON Schema for the credential subject):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "GitHubContributorCredentialSubject",
  "description": "The exact rules for Heka GitHub Contributor claims",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^did:hedera:.*",
      "description": "The developer's Hedera DID"
    },
    "githubUsername": {
      "type": "string",
      "minLength": 1
    },
    "githubAccountId": {
      "type": "integer",
      "minimum": 1
    },
    "gpgFingerprint": {
      "type": "string",
      "pattern": "^[0-9A-F]{16,40}$",
      "description": "Uppercase HEX fingerprint"
    }
  },
  "required": ["id", "githubUsername", "githubAccountId", "gpgFingerprint"],
  "additionalProperties": false
}

Note: the gpgFingerprint pattern allows 16–40 hex characters. A full GPG fingerprint is conventionally 40 hex characters (SHA-1, 160-bit); a 16-character value is really a GPG key ID, not a fingerprint. Worth tightening this to exactly 40 characters unless we genuinely want to accept short key IDs too.

And the final credential payload fixture, now including credentialStatus so it matches the "always disclosed" policy from Section 2:

{
  "iss": "did:hedera:testnet:z6MkhaXgBZDvotDkL5257faiztiuC2ZXOS",
  "iat": 1782604800,
  "exp": 1814140800,
  "sub": "did:hedera:testnet:z6MkqExampleDeveloperDID",
  "vct": "GitHubContributorCredential",
  "credentialStatus": {
    "id": "https://heka.network/status/123",
    "type": "CredentialStatusList2020"
  },
  "_sd": [
    "JzYx0aB9... (hash of 'githubUsername': 'darshit2308')",
    "Qp2LmC4... (hash of 'githubAccountId': 4115704)",
    "Xy9RqZ1... (hash of 'gpgFingerprint': '3AA5C34371567BD2')"
  ],
  "_sd_alg": "sha-256"
}

These live in the repo as:

heka-identity-service/src/credentials/fixtures/github-contributor-credential.schema.json — the JSON Schema defining what a valid GitHubContributorCredential subject looks like, the same way a government ID schema defines which fields (name, date of birth, etc.) must be present.
heka-identity-service/src/credentials/fixtures/mock-sd-jwt-payload.json — a mock GitHubContributorCredential for a fictional contributor, used across tests.

4. Validating the model with Jest

This was my first time writing Jest tests, so a quick summary of what I learned.

We use AJV (Another JSON Schema Validator) to check whether a piece of JSON data conforms to a given JSON Schema — for example, confirming githubAccountId is actually an integer, as the schema requires.

The tests live in heka-identity-service/src/credentials/credential-subject.spec.ts. The .spec.ts suffix is Jest's convention for a specification (test) file, and its job is to verify the schema behaves correctly against both valid and invalid inputs.

A small helper does the heavy lifting of turning a fixture file into a usable object:

const loadFixture = (fileName: string) => {
  return JSON.parse(readFileSync(join(__dirname, "fixtures", fileName), "utf8"));
};

From there, the test suite exercises as many valid and invalid permutations of the credential subject as we could think of — missing fields, wrong types, malformed DIDs, malformed fingerprints — to make sure AJV rejects exactly what it should and accepts exactly what it should.

5. did:hedera DID creation and deterministic verification-method selection

Using the operator credentials agreed on in Week 1, we created and resolved a did:hedera DID on Hedera testnet, with proof of creation and resolution captured via HashScan and the resolver output.

We also implemented deterministic verification-method selection, so signing operations always pick a specific, well-defined verification method rather than relying on array position (e.g., verificationMethod[0]), which isn't guaranteed to be stable. Tests now cover both DID resolution and this selection logic.

The code-level detail for both of these — along with the full schema, fixtures, and Jest suite above — is in the PR linked below; it's a better reference than a paraphrase here.

PR for reference: hiero-ledger/heka-identity-platform#179

Week - 1 (Phase 1)

Darshit Khandelwal — Mon, 22 Jun 2026 14:10:41 +0000

Week 1 of My LFDT Mentorship: Architecture, Hedera, and Getting Everything Running

Welcome to the first post of my LFDT (Linux Foundation Decentralized Trust) mentorship blog! Each week I'll be writing about what I built, what I learned, and — honestly — what confused me along the way.

Week 1 was all about planning, architecture decisions, and setting up the groundwork before any real code gets written. No flashy features yet, but a lot of important decisions that will shape everything that comes after. Let's get into it.

The Week at a Glance

Here's a quick summary of everything on my plate this week:

Align the implementation plan with my mentor and confirm the interpretation of Issue #87
Finalize the target architecture for the whole project
Sort out the Hedera testnet setup and operator credentials
Understand the revocation strategy and its scope during mentorship
Set up the local Heka development environment
Install and configure a GitHub App for local testing
Create a webhook fixture repository for replaying PR events
Prepare a PR slicing plan for incremental delivery

Aligning with the Mentor & Locking Down the Plan

The week started with a sync with my mentor to get the implementation plan nailed down. The good news is, the week-by-week plan has been finalized after a proper discussion, and the interpretation of Issue #87 has been confirmed. With the plan locked in, I can move forward with confidence in the coming weeks.

Deciding the Target Architecture

One of the bigger decisions this week was figuring out where everything actually lives, contributor onboarding, GitHub integration, credential issuance, DID management, and verification policy logic all need a home.

Here's what we landed on:

heka-identity-service — This is where the core modules live: contributor onboarding, credential issuance, DID management, and verification policy logic. All of this gets built as a dedicated module within this repo.
A separate GitHub repository — The GitHub integration code (the Probot app, webhook handling, check-run posting) lives in its own repo, completely separate from heka-identity-service. This keeps Heka clean and focused on identity, and makes the GitHub-specific code easier to extend or extract later.

There are still a few grey areas to iron out over the next couple of weeks, but the overall direction is clear and agreed upon.

Understanding Hedera: Consensus Nodes vs Mirror Nodes

If you're already familiar with Hedera's architecture, feel free to skip ahead to the next section!

Before I explain how Hedera fits into this project, let me share something I was confused about early on: what's the difference between a consensus node and a mirror node?

Unlike older blockchains (like Ethereum) that use a single node type for everything, Hedera splits the workload into two completely different node types to keep the network fast.

1. Consensus Node — The Write Database

This is where you send new transactions (like creating an account or logging a DID document to the ledger).
Its job is to receive the transaction, verify it, agree on a timestamp, and write it to the ledger as fast as possible.
Because it's hyper-focused on speed and new writes, it's not great at answering questions about old or historical data.

2. Mirror Node — The Read Database

The mirror node sits quietly alongside the consensus node and constantly copies (mirrors) every approved transaction.
Its only job is to take that raw blockchain data and organize it into a highly searchable traditional database (like PostgreSQL), and expose a REST API that developers can query.
Important caveat: you cannot send new transactions to the mirror node — it's strictly read-only.

How This Applies to Our Project

In practice, the two node types serve two completely different purposes in our system:

Writing (creating/updating a DID): Our backend uses the consensus node, authorized via operator credentials from our .env. The SDK signs the transaction automatically using the operator key.
Reading (showing transaction history or verifying an identity): The frontend makes a standard HTTP GET request directly to the mirror node's REST API — completely bypassing the consensus node.

Our .env will look something like this:

HEDERA_NETWORK=
OPERATOR_ID=
OPERATOR_KEY=
NODE_IP=
MIRROR_NODE_IP=

HBAR Balance & Revocation Strategy

After clarifying with my mentor Alexander, I now have the credentials for the operator account. The account comes loaded with enough test HBAR tokens to cover everything I need during development — creating, updating, and querying DIDs. So the token balance won't be a blocker at all.

On the revocation front: implementing a full, hardened VC revocation mechanism is out of scope for this mentorship. The focus right now is on building a working prototype, so revocation will either be tackled in the second half of the mentorship or saved for post-mentorship work. For now, the expectation is lightweight documentation and runbook-level treatment — not a working mechanism.

Setting Up the Local Dev Environment

This was the most hands-on part of the week. Getting the local Heka environment running required wiring together three tools: Nginx, Ngrok, and a GitHub App. Let me walk through how they fit together.

The Nginx Routing Rules

Nginx listens on Port 8080 and applies two simple routing rules to every incoming request:

# Rule 1: Route GitHub Webhooks → Probot GitHub App (Port 3000)
location /api/webhook {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

# Rule 2: Route everything else → Heka Core Backend (Port 3001)
location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

In plain English:

If the request is to /api/webhook → forward it to the GitHub App on Port 3000
Everything else → forward it to the main Heka backend on Port 3001

Why Ngrok Is Necessary

Here's the catch: Nginx only listens on localhost. But when GitHub fires a webhook event, "localhost" from GitHub's perspective means GitHub's own servers — not your machine. It would send the event into the void, find nothing, and drop it silently.

Ngrok solves this by creating a public tunnel from your local Port 8080 directly to the internet:

ngrok http 8080

Ngrok gives you a temporary public URL — something like https://something.ngrok-free.app. You paste this into your GitHub App's webhook URL settings. Now the entire flow works end-to-end:

GitHub fires a PR event
        ↓
Hits the public Ngrok URL
        ↓
Ngrok tunnels it to Port 8080 on your local machine
        ↓
Nginx reads the request and applies the two routing rules
        ↓
Correct service handles it (Port 3000 or 3001)

A one-liner to remember the whole pipeline:

GitHub labels it and sends it → Ngrok blindly transports it → Nginx reads it and diverts it.

Webhook Fixture Repository

To avoid opening real pull requests every single time I want to test webhook handling, I created a dedicated fixture repository for generating and replaying PR events during development.

You can find it here: darshit2308/Heka-Webhook-Fixture

The PR Slicing Plan

To keep development incremental and mentor-reviewable, I've planned out the PR delivery sequence. This is tentative for now, but here's the rough order:

ADRs and credential profile documentation
Deterministic DID verification method helper and Hedera secret validation
GPG challenge lifecycle module with tests
GitHub App adapter skeleton and check-run creation (separate repo from Heka, per mentor direction)
GitHub OAuth and contributor binding
Contributor credential OID4VCI support
Heka Web Wallet prototype (lives inside the Heka repository; non-Askar key management)
Heka Web UI onboarding flow
Repository config parser and policy schema
OID4VP verification integration (Web Wallet as the primary target)
Lifecycle and recovery documentation (runbooks; no revocation implementation)
E2E test suite, docs, and final demo artifacts

Looking Ahead

Week 1 was heavy on planning, decisions, and setup — but that's exactly how it should be. A solid foundation now means fewer surprises (and fewer painful rewrites) later. Starting next week, the real implementation begins: ADRs, the DID helper utilities, and the first PR going out the door.

Stay tuned for Week 2!

This post is part of my ongoing LFDT Mentorship 2026 blog series. Feel free to reach out if you have questions or want to discuss anything covered here!

Starting My LFX Mentorship Journey: Building Contributor Identity Verification for Hiero

Darshit Khandelwal — Sun, 14 Jun 2026 19:25:09 +0000

Today, June 15th, 2026, I officially start my 6-month LFX mentorship under the Linux Foundation Decentralized Trust (LFDT) program. I will be working on a project called Hiero Contributor Identity Verification Prototype, under the guidance of my mentor Alexander Shenshin.

*## What am I building, and why does it matter? *
In open-source projects, anyone can open a pull request. But how does a project maintainer know that the person submitting code is actually who they claim to be? Right now, most projects simply trust GitHub usernames, which can be faked, compromised, or shared.
This project solves that by building a real identity verification layer on top of GitHub's contribution workflow. When a contributor opens a pull request, instead of just trusting their username, the system cryptographically verifies their identity using:

Decentralized Identifiers (DIDs) anchored on the Hedera blockchain
Verifiable Credentials issued through the OID4VCI standard
GPG cryptographic signatures tied to their GitHub account
Verifiable Presentations verified at pull request time through OID4VP

In simple terms, a contributor proves they are who they say they are, once, and that proof travels with every pull request they open, automatically. (There is another alternative, that is, instead of storing the proof, we can create the proof of user's validity on dynamically, after every Pull Request opened. Although, this is an open question and would be clarified by the end of week-1).

*## What will I be documenting here? *
I plan to post weekly updates throughout this mentorship. Each post will cover what I built that week, the architectural decisions I made and, more importantly, why I made them, and what I learned or found difficult.
Specifically, I will be tracking:

1) Weekly progress updates on implementation
2) Architecture Decision Records explaining key technical choices
3) Demo videos after every major milestone
4) Honest reflections on blockers, mistakes, and lessons learned

I have some experience working with decentralized identity standards like OID4VCI and OID4VP from my previous projects, so i will try to explain the concepts too in as much detail as possible, to help the community.

## How can these posts be useful to you
These posts can be a genuine learning chance for individuals who are thinking to study concepts like DIDs, and dive into blockchain.
If you are working on decentralized identity, Hedera, open-source tooling, or LFX mentorship yourself, you can follow along.

Thanks a lot for reading until here!!
We can connect here:
linkedin: https://www.linkedin.com/in/darshit-khandelwal-49bb25288
GitHub: https://github.com/darshit2308