[INJIWEB-1793] Technical documentation for VC Status check design #995
Conversation
Signed-off-by: jackjain <[email protected]>
…check endpoints Signed-off-by: jackjain <[email protected]>
Signed-off-by: jackjain <[email protected]>
Signed-off-by: jackjain <[email protected]>
Signed-off-by: jackjain <[email protected]>
Signed-off-by: jackjain <[email protected]>
Signed-off-by: jackjain <[email protected]>
Signed-off-by: jackjain <[email protected]>
Signed-off-by: jackjain <[email protected]>
…add caching strategy Signed-off-by: jackjain <[email protected]>
Signed-off-by: jackjain <[email protected]>
Signed-off-by: jackjain <[email protected]>
Signed-off-by: jackjain <[email protected]>
WalkthroughA new design document details a Verifiable Credentials (VC) status-check system: workflows for viewing, user-initiated, and add-time checks; API contracts; database schema changes; a 24-hour status-list cache; and integration points/adjustments for the VC Verifier library. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant API
participant DB
participant Cache
participant Verifier
participant ExternalStatusList
Client->>API: Request credential(s) with status
API->>DB: Fetch stored VC records
DB-->>API: Return VC(s)
API->>Cache: Check status-list credential cache (per VC)
alt Cache hit
Cache-->>API: Return status-list credential
else Cache miss
API->>Verifier: Request status list credential (verify & fetch)
Verifier->>ExternalStatusList: Fetch status list credential
ExternalStatusList-->>Verifier: Return status list credential
Verifier-->>API: Return status-list credential result
API->>Cache: Store status-list credential (24h TTL)
end
API->>Verifier: Verify VC schema/signature and check status using status-list credential
Verifier-->>API: Return status and schema/signature verdicts
API->>DB: Update `status_checks` and `status_last_checked_at` (if configured)
API-->>Client: Respond with VC(s) and status fields (isSchemaAndSignatureValid, isExpired, statusChecks, lastCheckedAt)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 🧹 Recent nitpick comments
📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used🧠 Learnings (4)📓 Common learnings📚 Learning: 2026-01-16T02:30:15.809ZApplied to files:
📚 Learning: 2026-01-16T02:19:06.698ZApplied to files:
📚 Learning: 2026-01-16T02:31:35.817ZApplied to files:
🪛 LanguageTooldocs/VCStatusCheckDesign.md[grammar] ~9-~9: Use a hyphen to join words. (QB_NEW_EN_HYPHEN) 🪛 markdownlint-cli2 (0.18.1)docs/VCStatusCheckDesign.md5-5: Heading levels should only increment by one level at a time (MD001, heading-increment) 312-312: Bare URL used (MD034, no-bare-urls) ⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
🔇 Additional comments (8)
✏️ Tip: You can disable this entire section by setting Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Fix all issues with AI agents
In `@docs/VCStatusCheckDesign.md`:
- Line 300: The NOT NULL constraint on the status_last_checked_at column will
block inserting newly created credentials before an async status check; update
the schema or docs so insertion succeeds by either making status_last_checked_at
nullable or assigning a sensible default (e.g., set status_last_checked_at =
created_at) during credential creation, and clearly document the chosen behavior
in the VCStatusCheckDesign.md (referencing status_last_checked_at and the
credential creation flow/Flow 3) so implementers know whether the check is async
and when the column is populated.
- Line 66: The doc shows inconsistent lastCheckedAt semantics: Flow 1 sets
lastCheckedAt to the cache creation time while Flow 2 sets it to the current
time; pick a single authoritative behavior (either always set lastCheckedAt to
the actual check time or always use the cache creation timestamp) and update the
design text to standardize it (or explicitly document the intentional
difference). Update the sections referencing lastCheckedAt (the Flow 1
description that ties it to "cache creation time" and the Flow 2 description
that sets it to "current time") so both flows use the chosen convention and add
a brief note explaining the rationale and any impact on cache staleness or
auditability.
- Around line 341-345: The field naming is inconsistent: update the data class
CredentialStatusResult to reflect that multiple status list credentials may be
returned by renaming statusListCredential to statusListCredentials and changing
its type to List<JsonLDObject>? (or MutableList/Sequence as appropriate), then
update all references, usages and documentation (design text lines mentioning
"status list credential(s)" and "status list credential cache") to use the
plural name and iterate over the list where multiple lists are expected so
callers handle zero/one/many uniformly; alternatively, if you intend a
single-entry result, adjust the design text to explicitly state it's only one
credential and keep the singular name across code and docs.
- Line 297: The is_expired column should not be nullable: change the schema for
is_expired to NOT NULL with a sensible default (e.g., DEFAULT FALSE) and add a
migration to backfill existing NULL values (compute expiration from the
credential's expires_at or set FALSE if unknown); update any code paths that
create or refresh credentials to explicitly compute and set is_expired based on
current time and the credential expiry field so it remains deterministic;
alternatively, if NULL must be preserved for a documented state, add
documentation explaining exactly when is_expired can be NULL instead of changing
the schema.
- Around line 302-305: The migration currently sets
verifiable_credential.is_schema_signature_valid = true and
status_last_checked_at = now() for all rows which misrepresents unverified
credentials; change the migration to initialize is_schema_signature_valid to
NULL (or add a new enum/status value like "not_yet_verified") and set
status_last_checked_at = NULL, enqueue all credential IDs for asynchronous
verification via the existing status-check worker (or create a background job)
to update is_schema_signature_valid and status_last_checked_at when verified,
and update docs/UI to surface the "not_yet_verified" state so users know which
credentials have not been verified yet.
- Around line 155-162: The sequence diagram's Flow 3 contradictorily returns an
error and then proceeds to store the credential and show a success—fix by
treating "status list not applicable" as a normal (non-error) path: remove the
error-return and user-error steps (the lines where "Mimoto-->>InjiWeb: return
error" and "InjiWeb-->User: Show error message to the user") so the flow remains
Mimoto->>Database: Store credential (verifiable_credential table) ->
Database-->>Mimoto: Acknowledgement -> Mimoto-->>InjiWeb: Success ->
InjiWeb-->User: Show success message; ensure only the success branch stores the
credential and not the error branch.
🧹 Nitpick comments (5)
docs/VCStatusCheckDesign.md (5)
15-17: Clarify the cache availability requirement and its implications.The design states that if the status list cache is missing or partially available, the status check will be skipped. Consider documenting:
- What happens to the user experience when status checks are skipped?
- Should there be a background job to populate missing cache entries?
- How will users be informed that their credential status wasn't verified?
16-16: Clarify the "minimum time" logic for multiple status lists.The statement "if there are multiple list involved then minimum time will be updated in the database" is ambiguous. Consider clarifying:
- Why is the minimum time chosen rather than the maximum or the time of the most recent check?
- Could this lead to confusion where
lastCheckedAtdoesn't reflect when some status lists were actually verified?
320-346: Clarify whystatusListCredentialis null when using cache.Line 347 states: "The new field will be null when status list credential is fetched from cache or if its not applicable for the credential."
However, when the status list credential is fetched from cache, the actual credential data is available in the cache. Why not return it in
CredentialStatusResult? This would:
- Provide consistency regardless of cache hits/misses
- Allow callers to access the status list credential without additional cache lookups
- Simplify downstream logic
If there's a specific reason for this design choice (e.g., performance, avoiding duplication), please document it in the design.
318-318: Document the rationale for 24-hour cache TTL.A 24-hour TTL for revocation status seems long from a security perspective, as credentials could remain accessible for up to a day after being revoked. While this may be acceptable for performance reasons, consider:
- Documenting the security vs. performance trade-off
- Noting whether this aligns with industry standards for VC status checking
- Clarifying whether this TTL is appropriate for all status purposes (revocation, suspension, etc.)
9-9: Address documentation formatting issues.Static analysis tools have identified minor formatting issues:
- Line 9: "High level" should be hyphenated as "high-level" when used as an adjective
- Line 5: Heading level jumps from h1 to h3, skipping h2 (should use
##instead of###)- Line 314: Bare URL should be enclosed in angle brackets or proper markdown link syntax
These are minor documentation quality issues that improve readability.
📝 Proposed formatting fixes
-### Overview +## Overview -### High level user flow +### High-level user flow -- **Value**: - - `statusListCredential`: The actual bitstring retrieved from the status list credential +- **Value**: + - `statusListCredential`: The actual bitstring retrieved from the status list credential (e.g., <https://injicertify-farmer.dev-int-inji.mosip.net/v1/certify/credentials/status-list/a7b3ac9a-861a-4fa3-9c85-27e79d35fad3>)Also applies to: 5-5, 314-314
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/VCStatusCheckDesign.md
🧰 Additional context used
🪛 LanguageTool
docs/VCStatusCheckDesign.md
[grammar] ~9-~9: Use a hyphen to join words.
Context: ...rent status of the credential. ### High level user flow #### Flow : User lands ...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
docs/VCStatusCheckDesign.md
5-5: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
314-314: Bare URL used
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: build-maven-apitest-mimoto / maven-build
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
Signed-off-by: jackjain <[email protected]>
1 participant
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.