feat: DIS foundation — crypto core, modular SDK, threat model & migration plan

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+      - run: npm ci
+      - name: Lint
+        run: npm run lint
+      - name: Typecheck
+        run: npm run typecheck
+      - name: Test
+        run: npm test
+      - name: Build
+        run: npm run build
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+      - run: npm ci
+      - name: Dependency audit (fail on high+)
+        run: npm audit --audit-level=high
+      - name: Secret scan (gitleaks)
+        run: |
+          curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v8.24.3/gitleaks_8.24.3_linux_x64.tar.gz \
+            | tar -xz -C /tmp gitleaks
+          /tmp/gitleaks detect --no-git --redact -v --exit-code 1 --source . --config .gitleaks.toml

.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+coverage/
+*.log
+.DS_Store
+.env
+.env.*
+!.env.example
+*.tsbuildinfo

.gitleaks.toml

@@ -0,0 +1,19 @@
+# gitleaks configuration for DIS — Defensive Integration Shield.
+#
+# Extends the upstream default ruleset and adds a narrowly-scoped allowlist for
+# synthetic cryptographic TEST VECTORS. These fixtures contain ephemeral keys
+# (e.g. ML-KEM-768 / RSA private keys) generated solely to prove byte-for-byte
+# decryption compatibility. They are NOT real secrets and correspond to no
+# account or stored data. The allowlist is scoped to dedicated fixture paths so
+# real secrets committed elsewhere are still caught.
+
+title = "DIS gitleaks config"
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Synthetic crypto test vectors (not real secrets)"
+paths = [
+  '''src/post-quantum/__fixtures__/.*''',
+]

CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to DIS
+
+DIS — Defensive Integration Shield is the central cryptographic layer for Singra
+Vault, Singra Premium, and future projects. Crypto code carries unusual risk, so
+contributions follow strict rules.
+
+## Contributor License Agreement (CLA)
+
+By submitting a contribution you agree that:
+
+1. You have the right to submit the work.
+2. You license your contribution under the project license
+   ([PolyForm Noncommercial 1.0.0](LICENSE)), **and** you grant the maintainer a
+   perpetual, irrevocable right to relicense your contribution, including under
+   commercial terms.
+
+This preserves the project's ability to offer commercial licenses. PRs cannot be
+merged without CLA agreement.
+
+## Hard rules (non-negotiable)
+
+- **No invented cryptography.** Only audited primitives (`hash-wasm`, WebCrypto,
+  `@noble/post-quantum`). New crypto dependencies require explicit review per the
+  dependency policy.
+- **AEAD only**, unique nonce per call, AAD where context matters, strong KDFs,
+  key separation, key wrapping, secure randomness.
+- **Never** static salts, password-as-key, unauthenticated CBC, global mutable
+  crypto state, secrets in logs, debug bypasses, or hidden fallbacks.
+- **Formats are append-only.** Never edit an existing versioned format; add a new
+  version. Persisted-format constants are frozen.
+- **Every change ships with tests** — including negative tests (wrong key,
+  tampered data, AAD mismatch, downgrade) and, for formats, test vectors.
+
+## Workflow
+
+1. Branch from `main` (never commit to `main`/`master` directly).
+2. `npm install`
+3. Make the change with focused commits.
+4. Run the full gate locally:
+   ```bash
+   npm run lint
+   npm run typecheck
+   npm test
+   npm run build
+   ```
+5. Open a PR. CI must be green. Security-relevant changes need maintainer review.
+
+## Definition of done
+
+A change is done only when invariants are tested and runtime-critical paths are
+exercised — a green typecheck or build alone is **not** sufficient. Unrun checks
+must be stated honestly in the PR.

LICENSE

@@ -0,0 +1,140 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose. However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software. Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software. For example:
+
+> Required Notice: Copyright Maunting Studios (https://github.com/einmalmaik/dis)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice. Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be
+liable to you for any damages arising out of these terms or
+the use or nature of the software, under any kind of legal
+claim.
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+---
+
+Required Notice: Copyright (c) 2025-2026 Maunting Studios
+
+For commercial licensing of DIS — Defensive Integration Shield,
+contact the licensor. See `docs/licensing.md` for the full
+licensing rationale and dual-licensing options.

README.md

@@ -0,0 +1,95 @@
+# DIS — Defensive Integration Shield
+
+> **Powered by DIS — Defensive Integration Shield**
+
+DIS is a central, framework-agnostic cryptographic security platform. It is the
+single place where encryption, key management, secure data formats, KDFs,
+versioning, and future migrations live — so that consuming applications
+(Singra Vault, Singra Premium, and future projects) hold **no direct crypto
+logic** and depend only on stable, versioned public APIs.
+
+DIS **does not invent cryptography**. It composes audited, established
+primitives:
+
+| Concern | Primitive | Source |
+| --- | --- | --- |
+| Password KDF | Argon2id (versioned params) | [`hash-wasm`](https://github.com/Daninet/hash-wasm) |
+| Authenticated encryption | AES-256-GCM (96-bit IV, 128-bit tag) | WebCrypto `SubtleCrypto` |
+| Key separation / wrapping | HKDF-SHA-256 + AES-GCM | WebCrypto |
+| Random | CSPRNG | WebCrypto `getRandomValues` |
+| Post-quantum (optional) | ML-KEM-768 hybrid | [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) |
+
+## Status
+
+This is the **foundation release** (`0.1.0`). The pure, portable primitives
+(encoding, random, secure memory, KDF, AEAD, vault-entry encryption, key
+wrapping/rotation, chunked file encryption, integrity, format versioning,
+migration framework) are implemented and tested. The post-quantum hybrid
+sharing layer and the application cutover are tracked in
+[`docs/migration-plan.md`](docs/migration-plan.md).
+
+## Install
+
+```bash
+npm install @dis/shield
+# Optional, only if you use the post-quantum sharing module:
+npm install @noble/post-quantum
+```
+
+Requires Node `>=20.19.0` or a browser with WebCrypto.
+
+## Usage
+
+```ts
+import {
+  deriveMasterKey,
+  encryptVaultEntry,
+  decryptVaultEntry,
+  createWrappedUserKey,
+  rotateEncryptionKeys,
+} from '@dis/shield';
+
+const salt = '...'; // base64, stored per account
+const kek = await deriveMasterKey(masterPassword, salt); // Argon2id -> AES-GCM key
+
+const sealed = await encryptVaultEntry({ password: 's3cret' }, kek, entryId);
+const data = await decryptVaultEntry(sealed, kek, entryId);
+```
+
+Narrow imports are tree-shakeable:
+
+```ts
+import { encryptBytes } from '@dis/shield/aead';
+import { deriveRawKey } from '@dis/shield/kdf';
+```
+
+## Modules
+
+| Entry point | Responsibility |
+| --- | --- |
+| `@dis/shield/core` | Errors, encoding, constants, crypto-provider abstraction |
+| `@dis/shield/random` | Secure random bytes / UUIDs |
+| `@dis/shield/secure-memory` | `SecureBuffer` for key material |
+| `@dis/shield/kdf` | Argon2id, versioned parameters, HKDF strengthening |
+| `@dis/shield/aead` | AES-256-GCM encrypt/decrypt with AAD |
+| `@dis/shield/format-versioning` | Versioned, prefix-tagged envelopes |
+| `@dis/shield/vault-encryption` | Vault-entry sealing (entry-id AAD binding) |
+| `@dis/shield/file-encryption` | Chunked attachment encryption + manifests |
+| `@dis/shield/key-management` | Content-key wrap / unwrap / rotation |
+| `@dis/shield/post-quantum` | ML-KEM-768 + RSA-4096 hybrid key wrapping (sharing / emergency access) |
+| `@dis/shield/integrity` | SHA-256, constant-time compare, verification |
+| `@dis/shield/migrations` | Ordered, explicit payload migrations |
+
+## Security
+
+See [`docs/`](docs/) for the architecture overview, threat model,
+trust-boundary analysis, crypto review, and migration plan. Security
+properties are only claimed where they are backed by code, tests, or
+documentation. Anything unverified is labelled `not verified`.
+
+## License
+
+[PolyForm Noncommercial 1.0.0](LICENSE) — source-available, free for
+noncommercial use. **Not free for commercial use.** See
+[`docs/licensing.md`](docs/licensing.md) for the rationale, trademark/branding
+rules, and commercial dual-licensing.

SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+DIS is a cryptographic library. Please treat vulnerabilities responsibly.
+
+## Reporting
+
+Do **not** open public issues for security vulnerabilities. Report privately via
+GitHub Security Advisories on this repository (or contact the maintainer
+directly). Include affected versions, reproduction, and impact. We aim to
+acknowledge within a few days.
+
+## Security model
+
+- DIS composes only audited primitives (Argon2id via `hash-wasm`, AES-256-GCM /
+  HKDF / SHA-256 via WebCrypto, ML-KEM-768 via `@noble/post-quantum`). It does
+  not invent cryptography.
+- Security properties, accepted residual risks, and unverified assumptions are
+  documented in [`docs/threat-model.md`](docs/threat-model.md) and
+  [`docs/crypto-review.md`](docs/crypto-review.md).
+- Persisted formats are versioned and authenticated; unknown versions fail
+  closed; legacy unauthenticated payloads are readable only on an explicit
+  migration path.
+
+## Supported versions
+
+Pre-1.0: only the latest `0.x` minor receives fixes.