Docs/integration audit fixes#4
Merged
Merged
Conversation
Discrepancy #1: the SDK has TWO KDF paths but the old doc only showed one. Generic KDF (kdf module) takes a typed opts.strengthen for HKDF-Expand. Singra Vault profile (vault-crypto) takes positional deviceKey + pinned HKDF info 'SINGRA_DEVICE_KEY_V1'. Add both signatures with the wire-format anchor.
Discrepancy #5: the dependency-map said otpauth was 'out of DIS scope' and shipped by singravault, but as of Phase 6 TOTP lives inside @dis/shield/totp. Apps no longer need to install otpauth directly.
…ovides steps) Discrepancy #6: api-design.md suggested 'new MigrationRegistry().register(...).migrateToLatest(...)' as if DIS ships migrations out of the box. It does not. New file docs/migrations.md explains the split: framework in DIS, concrete steps in the app. Includes end-to-end example and a typical 'legacy no-AAD -> sv-vault-v1' step.
Discrepancy #3 + #4: two different functions share the 'migrate to hybrid' verb across modules. The vault-crypto one rewrites a stored private-key blob to pq-v2:. The post-quantum one re-encodes a hybrid ciphertext from v1/legacy to the current v2 byte layout. Split them with explicit 'when to use which' guidance so a KI does not pick the wrong one.
Fehlendes Konzept #7: a step-by-step 'how do I integrate DIS into a new app' guide with end-to-end code for the four common flows (master-password unlock, password change, file attachments, sharing) plus audit-log signatures, TOTP, error handling, and the 'do not do' list. Closes the gap that previously made it impossible for a KI to integrate DIS without reading the source code.
Discrepancy #2: api-design.md mentioned KDF_PARAMS as a public symbol, but the SDK facade does not re-export it. KDF_PARAMS is an alias inside @dis/shield/vault-crypto. The SDK exposes CURRENT_KDF_VERSION and DEFAULT_KDF_PARAMS instead.
Discrepancy #8: the SDK facade re-exports only the 2FA-enrolment TOTP surface (generateTotpSecret, buildTotpUri, verifyTotpCode). The password-manager authenticator helpers (generateTotpCode, buildTotpUriWithOptions) live in @dis/shield/totp directly. Document the split and the reason.
Qualitaet #9: the old api-design only said 'errors are typed and secret-free' in one bullet. Add a full table of error classes, when they fire, and what the app should do. Mentions the no-oracle contract on DisDecryptionError and the legacy/runtime-vs-migration split. Tested against actual throws in src/<module>/index.ts.
Fix #9: the DIS_BRANDING constant is exported from the SDK but never mentioned in the README. Apps that want a 'Powered by DIS' badge had to find it by reading src/index.ts. Add a short section with the import snippet and a pointer to docs/licensing.md for the trademark rules.
Fix #10: a KI that has to figure out 'which Singra app uses which DIS module' had to grep both repos. New file docs/app-to-module.md gives the full mapping table for Vault + Premium, plus a 'for a third app, do not import vault-crypto' note that points new consumers at the integration guide.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.