@msdis/shield 0.2.0

package/dist/migrations/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * dis-migrations — explicit, ordered transformation of encrypted payloads.
+ *
+ * Migrations are registered against a (subject, fromVersion) key and run in a
+ * deterministic order. This gives applications a single, testable place to
+ * evolve formats (e.g. re-wrap legacy no-AAD vault items, bump KDF parameters,
+ * re-encrypt under a new cipher) without scattering ad-hoc upgrade code.
+ *
+ * DIS provides the framework and the crypto; the application decides which
+ * migrations to register and how persistence happens.
+ */
+/** Context passed to a migration step. `key` material is caller-supplied. */
+interface MigrationContext {
+    readonly key: CryptoKey;
+    /** Stable identifier the payload is bound to (e.g. entry id). */
+    readonly bindingId?: string;
+}
+/** A single migration: transforms a payload from `fromVersion` to `toVersion`. */
+interface Migration {
+    readonly subject: string;
+    readonly fromVersion: number | 'legacy';
+    readonly toVersion: number;
+    /** Returns the migrated payload string. Must be idempotent on its output. */
+    migrate(payload: string, context: MigrationContext): Promise<string>;
+}
+/** Detects the current version of a payload for a subject. */
+type VersionDetector = (payload: string) => number | 'legacy';
+/** An ordered registry of migrations for one or more subjects. */
+declare class MigrationRegistry {
+    private readonly migrations;
+    private keyOf;
+    /** Registers a migration. Throws if one already exists for the same step. */
+    register(migration: Migration): this;
+    /**
+     * Applies all applicable migrations in sequence until no further migration
+     * exists for the payload's detected version. Guards against cycles.
+     */
+    migrateToLatest(subject: string, payload: string, detect: VersionDetector, context: MigrationContext): Promise<string>;
+}
+
+export { type Migration, type MigrationContext, MigrationRegistry, type VersionDetector };

package/dist/migrations/index.js

@@ -0,0 +1,4 @@
+export { MigrationRegistry } from '../chunk-FUDDBD2G.js';
+import '../chunk-MJO7IJZC.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/post-quantum/index.d.ts

@@ -0,0 +1,153 @@
+/**
+ * DIS — Defensive Integration Shield · post-quantum hybrid key wrapping.
+ * Powered by DIS — Defensive Integration Shield.
+ *
+ * Hybrid key wrapping combining:
+ * - ML-KEM-768 (FIPS 203) for post-quantum key encapsulation
+ * - RSA-4096-OAEP for classical encryption
+ *
+ * In the product threat model this protects sharing and emergency-access
+ * keys against "harvest now, decrypt later" attacks. It is NOT the encryption
+ * layer for vault item payloads, which remain AES-256-GCM encrypted with
+ * user-derived symmetric keys (see `@dis/shield/vault-encryption`).
+ *
+ * Wire format is preserved byte-for-byte from the legacy Singra implementation:
+ *   version(1) || pq_ct(1088) || rsa_ct(512) || iv(12) || aes_ct(variable)
+ * with version bytes 0x01 (RSA-only), 0x02 (legacy hybrid), 0x03 (HKDF-v1),
+ * 0x04 (HKDF-v2, current). Changing any constant below breaks decryption of
+ * already-stored sharing/emergency keys — treat as a hard compatibility gate.
+ *
+ * @see https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf
+ */
+/**
+ * Product-wide security standard version. Centralized so all hybrid/PQ
+ * sharing-key provisioning and runtime enforcement paths stay in sync.
+ */
+declare const SECURITY_STANDARD_VERSION = 1;
+/** Current hybrid ciphertext version (v2 HKDF construction) */
+declare const HYBRID_VERSION = 4;
+interface SharedKeyWrapAadInput {
+    collectionId: string;
+    senderUserId: string;
+    recipientUserId: string;
+    keyVersion: string | number;
+}
+declare function buildSharedKeyWrapAad(input: SharedKeyWrapAadInput): string;
+/**
+ * Generates a new ML-KEM-768 key pair.
+ *
+ * @returns Object with base64-encoded public and secret keys
+ */
+declare function generatePQKeyPair(): PQKeyPair;
+/**
+ * Generates a hybrid key pair combining ML-KEM-768 and RSA-4096.
+ *
+ * @returns Object with both PQ and RSA keys
+ */
+declare function generateHybridKeyPair(): Promise<HybridKeyPair>;
+/**
+ * Encrypts key material using hybrid ML-KEM-768 + RSA-4096-OAEP encryption.
+ *
+ * The supplied key material is encrypted with a randomly generated AES-256 key.
+ * This AES key is then encapsulated/encrypted with both:
+ * 1. ML-KEM-768 (post-quantum KEM)
+ * 2. RSA-4096-OAEP (classically secure)
+ *
+ * Format: version(1) || pq_ciphertext(1088) || rsa_ciphertext(512) || iv(12) || aes_ciphertext(variable)
+ *
+ * @param plaintext - Serialized key material to wrap
+ * @param pqPublicKey - Base64-encoded ML-KEM-768 public key
+ * @param rsaPublicKey - JWK string of RSA-4096 public key
+ * @param aad - Optional additional authenticated data for AES-GCM context binding
+ * @returns Base64-encoded hybrid ciphertext
+ */
+declare function hybridEncrypt(plaintext: string, pqPublicKey: string, rsaPublicKey: string, aad?: string): Promise<string>;
+/**
+ * Decrypts hybrid ML-KEM-768 + RSA-4096-OAEP wrapped key material.
+ *
+ * @param ciphertextBase64 - Base64-encoded hybrid ciphertext
+ * @param pqSecretKey - Base64-encoded ML-KEM-768 secret key
+ * @param rsaPrivateKey - JWK string of RSA-4096 private key
+ * @param aad - Optional additional authenticated data (must match encrypt-time AAD)
+ * @returns Decrypted plaintext
+ * @throws Error if decryption fails or version is unsupported
+ */
+declare function hybridDecrypt(ciphertextBase64: string, pqSecretKey: string, rsaPrivateKey: string, aad?: string): Promise<string>;
+/**
+ * Wraps a shared AES key using hybrid encryption.
+ * Used for shared collections where each member gets a wrapped copy.
+ *
+ * @param sharedKeyJwk - JWK string of the shared AES-256 key
+ * @param pqPublicKey - Base64-encoded ML-KEM-768 public key
+ * @param rsaPublicKey - JWK string of RSA-4096 public key
+ * @param aad - Optional additional authenticated data (e.g. collection ID)
+ * @returns Base64-encoded wrapped key
+ */
+declare function hybridWrapKey(sharedKeyJwk: string, pqPublicKey: string, rsaPublicKey: string, aad: string): Promise<string>;
+/**
+ * Unwraps a shared AES key using hybrid decryption.
+ *
+ * @param wrappedKey - Base64-encoded wrapped key
+ * @param pqSecretKey - Base64-encoded ML-KEM-768 secret key
+ * @param rsaPrivateKey - JWK string of RSA-4096 private key
+ * @param aad - Optional additional authenticated data (must match wrap-time AAD)
+ * @returns JWK string of the shared AES-256 key
+ */
+declare function hybridUnwrapKey(wrappedKey: string, pqSecretKey: string, rsaPrivateKey: string, aad: string): Promise<string>;
+/**
+ * Checks if wrapped key material uses any hybrid (post-quantum) encryption version.
+ * Recognizes legacy hybrid (0x02), standard v1 (0x03), and standard v2 (0x04).
+ *
+ * @param ciphertextBase64 - Base64-encoded ciphertext
+ * @returns true if any hybrid wrapped-key version, false if legacy RSA-only or unknown
+ */
+declare function isHybridEncrypted(ciphertextBase64: string): boolean;
+/**
+ * Checks if a ciphertext uses the current standard encryption (v2 HKDF, version 0x04).
+ * Use this for security enforcement checks where only the latest format is acceptable.
+ *
+ * @param ciphertextBase64 - Base64-encoded ciphertext
+ * @returns true if current standard (0x04), false otherwise
+ */
+declare function isCurrentStandardEncrypted(ciphertextBase64: string): boolean;
+/**
+ * Re-wraps legacy RSA-only or older hybrid key material with current hybrid key wrapping (v2).
+ * Used during migration to post-quantum protection for sharing and emergency keys.
+ *
+ * - Version 0x04: already current, returned unchanged.
+ * - Version 0x03: decrypted with legacy HKDF-v1, re-encrypted with HKDF-v2.
+ * - Version 0x02: decrypted with legacy hybrid path, re-encrypted.
+ * - Version 0x01 / unknown: decrypted with RSA-only, re-encrypted.
+ *
+ * @param legacyCiphertext - Base64-encoded legacy ciphertext
+ * @param rsaPrivateKey - JWK string of RSA private key for decryption
+ * @param pqSecretKey - Base64-encoded ML-KEM-768 secret key (required for hybrid legacy)
+ * @param pqPublicKey - Base64-encoded ML-KEM-768 public key
+ * @param rsaPublicKey - JWK string of RSA public key
+ * @returns Base64-encoded hybrid ciphertext (version 0x04)
+ */
+declare function migrateToHybrid(legacyCiphertext: string, rsaPrivateKey: string, pqSecretKey: string | null, pqPublicKey: string, rsaPublicKey: string, aad?: string): Promise<string>;
+/**
+ * ML-KEM-768 key pair
+ */
+interface PQKeyPair {
+    /** Base64-encoded ML-KEM-768 public key (1184 bytes) */
+    publicKey: string;
+    /** Base64-encoded ML-KEM-768 secret key (2400 bytes) */
+    secretKey: string;
+}
+/**
+ * Combined hybrid key pair with both PQ and classical keys
+ */
+interface HybridKeyPair {
+    /** Base64-encoded ML-KEM-768 public key */
+    pqPublicKey: string;
+    /** Base64-encoded ML-KEM-768 secret key */
+    pqSecretKey: string;
+    /** JWK string of RSA-4096 public key */
+    rsaPublicKey: string;
+    /** JWK string of RSA-4096 private key */
+    rsaPrivateKey: string;
+}
+
+export { HYBRID_VERSION, type HybridKeyPair, type PQKeyPair, SECURITY_STANDARD_VERSION, type SharedKeyWrapAadInput, buildSharedKeyWrapAad, generateHybridKeyPair, generatePQKeyPair, hybridDecrypt, hybridEncrypt, hybridUnwrapKey, hybridWrapKey, isCurrentStandardEncrypted, isHybridEncrypted, migrateToHybrid };

package/dist/post-quantum/index.js

@@ -0,0 +1,3 @@
+export { HYBRID_VERSION, SECURITY_STANDARD_VERSION, buildSharedKeyWrapAad, generateHybridKeyPair, generatePQKeyPair, hybridDecrypt, hybridEncrypt, hybridUnwrapKey, hybridWrapKey, isCurrentStandardEncrypted, isHybridEncrypted, migrateToHybrid } from '../chunk-T3IV7SHD.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/post-quantum/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/random/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * dis-random — secure random generation.
+ *
+ * Always sources entropy from the active crypto provider's CSPRNG
+ * (`getRandomValues`). DIS never uses `Math.random` for any value that affects
+ * confidentiality, integrity, or unpredictability.
+ */
+/** Returns `length` cryptographically secure random bytes. */
+declare function randomBytes(length: number): Uint8Array;
+/**
+ * Fills an existing `ArrayBufferView` with cryptographically secure random
+ * bytes in place. Used by callers that own a buffer they want to overwrite
+ * (e.g. secure-memory scrubbing) without allocating a second array.
+ */
+declare function fillRandom<T extends ArrayBufferView>(view: T): T;
+/**
+ * Returns a cryptographically secure random integer in the inclusive range
+ * `[min, max]` using rejection sampling to avoid modulo bias.
+ *
+ * Byte-for-byte equivalent to the `getSecureRandomInt` helpers in Singra Vault
+ * (password generator, backup-code generator): it draws `ceil(log2(range)/8)`
+ * bytes big-endian and rejects values above the largest multiple of `range`.
+ */
+declare function randomInt(min: number, max: number): number;
+/** Returns a RFC 4122 v4 UUID using the provider's CSPRNG. */
+declare function randomUuid(): string;
+
+export { fillRandom, randomBytes, randomInt, randomUuid };

package/dist/random/index.js

@@ -0,0 +1,5 @@
+export { fillRandom, randomBytes, randomInt, randomUuid } from '../chunk-3HCT6A2P.js';
+import '../chunk-CYIGDF63.js';
+import '../chunk-MJO7IJZC.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/random/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/secure-memory/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * dis-secure-storage / secure-memory — memory-safe handling of key material.
+ *
+ * Ported from Singra Vault's SecureBuffer. Provides controlled, callback-scoped
+ * access to sensitive bytes with explicit zeroing on destroy and a
+ * FinalizationRegistry fallback. This is defense-in-depth: JavaScript cannot
+ * guarantee memory wiping (GC is non-deterministic, strings are immutable), but
+ * controlled access plus best-effort zeroing materially reduces exposure
+ * (cf. KeePass CVE-2023-32784).
+ */
+/** A wrapper for sensitive binary data with controlled access and zeroing. */
+declare class SecureBuffer {
+    private buffer;
+    private destroyed;
+    constructor(size: number);
+    /** Copies `bytes` into a new SecureBuffer. The source is NOT auto-zeroed. */
+    static fromBytes(bytes: Uint8Array): SecureBuffer;
+    /** Builds a SecureBuffer from a hex string (spaces/dashes allowed). */
+    static fromHex(hex: string): SecureBuffer;
+    /** Allocates a SecureBuffer filled with CSPRNG bytes. */
+    static random(size: number): SecureBuffer;
+    /** Synchronous controlled access. Do not retain the buffer past `fn`. */
+    use<T>(fn: (data: Uint8Array) => T): T;
+    /** Asynchronous controlled access. */
+    useAsync<T>(fn: (data: Uint8Array) => Promise<T>): Promise<T>;
+    get size(): number;
+    get isDestroyed(): boolean;
+    /** Zeros the buffer and marks it destroyed. Idempotent. */
+    destroy(): void;
+    /** Returns a mutable copy of the contents (caller must zero it). */
+    toBytes(): Uint8Array;
+    /** Constant-time equality comparison against another buffer. */
+    equals(other: SecureBuffer | Uint8Array): boolean;
+}
+/** Runs `fn` with a temporary SecureBuffer that is always destroyed afterwards. */
+declare function withSecureBuffer<T>(bytes: Uint8Array, fn: (secure: SecureBuffer) => Promise<T>): Promise<T>;
+/** Zeros multiple buffers. Convenience for `finally` cleanup blocks. */
+declare function zeroBuffers(...buffers: (Uint8Array | null | undefined)[]): void;
+
+export { SecureBuffer, withSecureBuffer, zeroBuffers };

package/dist/secure-memory/index.js

@@ -0,0 +1,5 @@
+export { SecureBuffer, withSecureBuffer, zeroBuffers } from '../chunk-RTAJJZKO.js';
+import '../chunk-CYIGDF63.js';
+import '../chunk-MJO7IJZC.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/secure-memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/signing/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * dis-signing — asymmetric digital signatures.
+ *
+ * Primitive: ECDSA over the NIST P-256 curve with SHA-256, via WebCrypto.
+ * Public keys are exchanged as SPKI bytes; private keys are generated
+ * non-extractable so they never leave the device. Signatures are the raw
+ * `r || s` concatenation WebCrypto produces (fixed 64 bytes for P-256), which
+ * is the exact wire form Singra Vault's op-log device signatures use.
+ *
+ * Canonicalisation of the signed payload is the caller's responsibility — DIS
+ * signs and verifies opaque byte strings and never interprets their structure.
+ */
+/** Raw byte length of a P-256 ECDSA signature (`r || s`, 32 bytes each). */
+declare const ECDSA_P256_SIGNATURE_LENGTH = 64;
+interface EcdsaP256KeyPair {
+    readonly privateKey: CryptoKey;
+    readonly publicKey: CryptoKey;
+    /** SPKI-encoded public key bytes, ready to be base64url-encoded for storage. */
+    readonly publicKeySpki: Uint8Array;
+}
+/**
+ * Generates a fresh non-extractable ECDSA P-256 key pair and exports the
+ * public key as SPKI bytes.
+ */
+declare function generateEcdsaP256KeyPair(): Promise<EcdsaP256KeyPair>;
+/** Imports an SPKI-encoded P-256 public key for signature verification. */
+declare function importEcdsaP256PublicKeySpki(spki: Uint8Array): Promise<CryptoKey>;
+/**
+ * Signs `data` with an ECDSA P-256 private key, returning the raw 64-byte
+ * `r || s` signature. Throws {@link DisInvalidArgumentError} if WebCrypto
+ * returns an unexpected length (defends against curve/algorithm misuse).
+ */
+declare function signEcdsaP256(privateKey: CryptoKey, data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Verifies a raw 64-byte `r || s` ECDSA P-256 signature over `data`. Returns
+ * `false` for an invalid signature; throws {@link DisInvalidArgumentError} if
+ * the signature is not the expected length.
+ */
+declare function verifyEcdsaP256(publicKey: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+
+export { ECDSA_P256_SIGNATURE_LENGTH, type EcdsaP256KeyPair, generateEcdsaP256KeyPair, importEcdsaP256PublicKeySpki, signEcdsaP256, verifyEcdsaP256 };

package/dist/signing/index.js

@@ -0,0 +1,5 @@
+export { ECDSA_P256_SIGNATURE_LENGTH, generateEcdsaP256KeyPair, importEcdsaP256PublicKeySpki, signEcdsaP256, verifyEcdsaP256 } from '../chunk-AB2WZ7Y2.js';
+import '../chunk-CYIGDF63.js';
+import '../chunk-MJO7IJZC.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/signing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/totp/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * dis-totp — time-based one-time passwords (RFC 6238).
+ *
+ * Thin wrapper over the audited `otpauth` library so applications never embed
+ * the OTP primitive directly. Parameters are pinned to the values Singra Vault
+ * uses (SHA-1, 6 digits, 30-second period, 160-bit secrets) so existing
+ * enrolled authenticators keep working unchanged.
+ *
+ * SHA-1 here is the standardised HMAC inside the TOTP construction (RFC 6238),
+ * which every authenticator app implements; it is not used as a hash for any
+ * security decision elsewhere.
+ */
+/** TOTP parameters, fixed to remain compatible with enrolled authenticators. */
+declare const TOTP_ALGORITHM: "SHA1";
+declare const TOTP_DIGITS = 6;
+declare const TOTP_PERIOD_SECONDS = 30;
+/** Secret size in bytes (160-bit) as produced by {@link generateTotpSecret}. */
+declare const TOTP_SECRET_SIZE = 20;
+/** HMAC algorithms RFC 6238 permits and authenticator apps implement. */
+type TotpAlgorithm = 'SHA1' | 'SHA256' | 'SHA512';
+/**
+ * Parameters for third-party TOTP entries (password-manager authenticator
+ * storage). Unlike Singra's own 2FA enrolment — which is pinned to
+ * SHA-1 / 6 digits / 30 s — imported entries carry whatever parameters the
+ * issuing service chose, so each knob is explicit here.
+ */
+interface TotpCodeOptions {
+    /** HMAC algorithm. Defaults to {@link TOTP_ALGORITHM}. */
+    readonly algorithm?: TotpAlgorithm;
+    /** Code length. Defaults to {@link TOTP_DIGITS}. */
+    readonly digits?: number;
+    /** Time step in seconds. Defaults to {@link TOTP_PERIOD_SECONDS}. */
+    readonly period?: number;
+    /** Epoch milliseconds to generate for. Defaults to the current time. */
+    readonly timestamp?: number;
+}
+interface TotpParams {
+    /** Issuer label shown in the authenticator app. */
+    readonly issuer: string;
+    /** Account label (typically the user's email). */
+    readonly label: string;
+    /** Base32-encoded shared secret. */
+    readonly secret: string;
+}
+/** Generates a new base32-encoded 160-bit TOTP secret. */
+declare function generateTotpSecret(): string;
+/** Builds the `otpauth://` provisioning URI for a QR code. */
+declare function buildTotpUri(params: TotpParams): string;
+/**
+ * Generates the TOTP code for a base32 `secret` with explicit parameters —
+ * the primitive behind a password manager's authenticator view. Throws
+ * {@link DisInvalidArgumentError} on a malformed secret so callers can decide
+ * how to surface the error.
+ */
+declare function generateTotpCode(secret: string, options?: TotpCodeOptions): string;
+/**
+ * Builds the `otpauth://` provisioning URI for an entry with explicit
+ * parameters (third-party authenticator entries). Singra's own 2FA enrolment
+ * should keep using {@link buildTotpUri}, which pins the Singra parameter set.
+ */
+declare function buildTotpUriWithOptions(params: TotpParams, options?: Omit<TotpCodeOptions, 'timestamp'>): string;
+/**
+ * Verifies a TOTP `code` against a base32 `secret`, allowing `window` periods
+ * of clock drift on either side (default 1 = ±30s). Returns `true` on a match.
+ * Malformed secrets/codes return `false` rather than throwing.
+ */
+declare function verifyTotpCode(secret: string, code: string, window?: number): boolean;
+
+export { TOTP_ALGORITHM, TOTP_DIGITS, TOTP_PERIOD_SECONDS, TOTP_SECRET_SIZE, type TotpAlgorithm, type TotpCodeOptions, type TotpParams, buildTotpUri, buildTotpUriWithOptions, generateTotpCode, generateTotpSecret, verifyTotpCode };

package/dist/totp/index.js

@@ -0,0 +1,4 @@
+export { TOTP_ALGORITHM, TOTP_DIGITS, TOTP_PERIOD_SECONDS, TOTP_SECRET_SIZE, buildTotpUri, buildTotpUriWithOptions, generateTotpCode, generateTotpSecret, verifyTotpCode } from '../chunk-OA5ARYJM.js';
+import '../chunk-MJO7IJZC.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/totp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}