feat: DIS foundation — crypto core, modular SDK, threat model & migration plan#1
Merged
Merged
Conversation
Implements the framework-agnostic crypto core (encoding, random, secure-memory, kdf/Argon2id, aead/AES-256-GCM, vault-encryption, key-management, file-encryption, integrity, format-versioning, migrations) with byte-compatible Singra formats. 42 tests (positive + negative + vectors), lint, typecheck, build all green. Adds architecture/threat-model/crypto-review/migration/licensing docs, PolyForm Noncommercial license, and CI with dependency + secret scanning. Co-Authored-By: Gaming Gruppe <einmalmaik@gmail.com>
Contributor
Author
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
Co-Authored-By: Gaming Gruppe <einmalmaik@gmail.com>
Co-Authored-By: Gaming Gruppe <einmalmaik@gmail.com>
Hard-coded vectors produced by the legacy Singra cryptoService prove DIS reads already-stored production ciphertext (KDF v1/v2, AEAD ±AAD, sv-vault-v1 envelope, usk-wrap-v2 bundle). Phase 1 cutover gate. Co-Authored-By: Gaming Gruppe <einmalmaik@gmail.com>
Faithful port of Singra pqCryptoService into @dis/shield/post-quantum. Wire format preserved byte-for-byte (version bytes 0x01-0x04, HKDF v1/v2, ver||pq_ct||rsa_ct||iv||aes_ct layout). Adds round-trip, fail-closed (wrong AAD / tampered) and a legacy golden-vector test proving DIS decrypts already-stored v0x04 hybrid ciphertext. Exposed via the SDK facade and as an optional @noble/post-quantum peer. Co-Authored-By: Gaming Gruppe <einmalmaik@gmail.com>
Gitleaks flagged the synthetic ML-KEM secret key in the PQ golden-vector test as a generic secret (high entropy). Move the vector into a dedicated __fixtures__ file documented as non-secret synthetic test material and narrowly allowlist that path in .gitleaks.toml (default ruleset still applies everywhere else). Co-Authored-By: Gaming Gruppe <einmalmaik@gmail.com>
…module Adds @dis/shield/vault-crypto — the stable, named API Singra Vault/Premium consume so the apps need zero crypto code of their own. It composes the audited DIS primitives (kdf, aead, vault-encryption, key-management, asymmetric, post-quantum) and owns the application-specific versioned formats (sv-vault-v1, usk-wrap-v2, usk-v1 private-key wrap, pq-v2 hybrid keypair envelope, v3 verification hash, KDF auto-upgrade, re-encryption). Adds @dis/shield/asymmetric (RSA-OAEP-4096) and key-management helpers (createDeterministicWrappedUserKey, AES-GCM JWK shared keys). 16 profile tests prove byte-compat with legacy Singra golden vectors via the profile API plus round-trips for every profile-only format. 66 DIS tests green. Co-Authored-By: Gaming Gruppe <einmalmaik@gmail.com>
Co-Authored-By: Gaming Gruppe <einmalmaik@gmail.com>
…acy-migration logging - isCurrentVaultItemEnvelope now fails closed (throws) on unknown in-family sv-vault-* versions instead of returning false, matching legacy behaviour - decryptVaultItem/decryptVaultItemForMigration emit the legacy no-AAD marker via console.warn when the migration-only fallback is used - add profile tests locking both behaviours Co-Authored-By: Gaming Gruppe <einmalmaik@gmail.com>
npm audit flagged a critical advisory in vitest <4.1.0 (Vitest UI server arbitrary file read/exec). Dev-only dependency; no production crypto impact. All 68 tests pass on vitest 4. Co-Authored-By: Gaming Gruppe <einmalmaik@gmail.com>
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.
Summary
Establishes DIS — Defensive Integration Shield as the central, framework-agnostic crypto layer that Singra Vault, Singra Premium, and future projects will depend on exclusively. This PR is Phase 0 (foundation): it implements and tests the portable primitives and ships all analysis deliverables. No application code is changed yet — the app cutover is gated on user approval and the compatibility proof described in
docs/migration-plan.md.DIS invents no cryptography. It composes audited primitives only: Argon2id (
hash-wasm), AES-256-GCM / HKDF-SHA-256 / SHA-256 (WebCrypto), ML-KEM-768 hybrid (@noble/post-quantum, phase 2).What's implemented (all tested: 42 tests, lint, typecheck, build green)
One package
@dis/shieldwith tree-shakeable subpath exports per module:core— typed error hierarchy (secret-free), encoding, constants, injectableCryptoProviderseam (only place a global is touched)random— CSPRNG bytes/UUID, neverMath.randomsecure-memory—SecureBuffer(wipe + FinalizationRegistry fallback, constant-timeequals)kdf— Argon2id with immutable versioned params (v1 64 MiB, v2 128 MiB, t=3, p=4, 32B) + optional HKDF strengthening for device-key bindingaead— AES-256-GCM, fresh 96-bit IV per call, 128-bit tag, AAD; all failures collapse to one opaqueDisDecryptionError(no oracle)format-versioning— prefix-tagged envelopes; unknown in-family versions fail closedvault-encryption—sv-vault-v1:items with entryId as AAD (defeats row-swap); legacy no-AAD readable only via explicit migration APIkey-management— content-key (usk-wrap-v2:) wrap/unwrap +rotateEncryptionKeysthat re-wraps without re-encrypting vault datafile-encryption— chunked (4 MiB) attachment encryption, per-file random key, manifest root + per-chunk AAD binding owner/item/file/revision/root/index/count; storage-agnostic (caller suppliesreadChunk/writeChunk)integrity— SHA-256, constant-time compare,verifyPayloadIntegritymigrations— ordered, cycle-guardedMigrationRegistryStable SDK facade (
@dis/shield) exposes the requested API names:encryptVaultEntry/decryptVaultEntry,encryptAttachment/decryptAttachment,deriveMasterKey,rotateEncryptionKeys,verifyPayloadIntegrity, plusDIS_BRANDING = "Powered by DIS — Defensive Integration Shield".Format compatibility
All persisted-format constants (envelope prefixes,
IV‖CT‖taglayout, AAD strings, HKDFinfo, KDF params) reproduce Singra's formats byte-for-byte, so apps can adopt DIS with no data re-encryption. Formats are append-only (new version, never edit).Deliverables (in
docs/)architecture.md,crypto-dependency-map.md,trust-boundaries.md,threat-model.md(24 threats + accepted residual risks),risk-analysis.md(risk-ordered refactor plan),api-design.md(+ breaking-change policy),crypto-review.md,migration-plan.md,licensing.md. PlusLICENSE(PolyForm Noncommercial 1.0.0 — source-available, noncommercial, with dual-licensing path),CONTRIBUTING.md(CLA),SECURITY.md, and CI (lint/typecheck/test/build+npm audit+ gitleaks secret scan).License decision (see
docs/licensing.md)Honest framing: a strict OSI "open source" license cannot forbid commercial use. Chose PolyForm Noncommercial 1.0.0 (SPDX
PolyForm-Noncommercial-1.0.0) — explicit noncommercial restriction, professionally drafted, clearer than Commons Clause; AGPL rejected (doesn't restrict commercial use). Commercial use via maintainer dual-licensing (CLA preserves this).Not done in this PR (next phases, gated)
pqCryptoService) intokey-management(Phase 2)../singravault/srcpath alias, lint-ban rawcrypto.subtle, make build fail without DIS (Phases 3–4)Honest test status
npm run lint,npm run typecheck,npm test(42 passing),npm run buildall run green locally. Cross-implementation golden-vector tests against live production payloads are not yet present (tracked as the Phase 1 gate) — byte-compatibility is currently asserted via format structure, not yet against captured production ciphertext.Link to Devin session: https://app.devin.ai/sessions/24b35de4890f41edb8a0250d5f4aba7c