@swivy/core 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @swivy/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Swivy shared types and sealed-export utilities. Testnet preview; production onboarding is gated on the Swop canary.
+
+Public npm distribution is being prepared. Before first publication, use all SDK tarballs
+from one operator-supplied release and verify its SHA256SUMS. After publication:
+
+```sh
+npm install @swivy/core@next
+```
+
+Use an environment app ID and publishable key for browser/mobile apps. Keep environment
+secret keys on the backend and deployment bootstrap credentials with the deployment operator.
+Choose email or SMS in your environment policy; SMS recovery alone does not enable SMS login.
+Never log login codes, runtime sessions or signing material.
+
+Browser apps currently need a same-origin reverse proxy for `/v1/runtime/*`; the API
+does not advertise cross-origin browser access. Backend and native clients can use the API directly.

package/dist/packages/core/src/hpke-open.d.ts

@@ -0,0 +1,25 @@
+export declare function toBase64(bytes: Uint8Array): string;
+export interface SealedExportEncryption {
+    info: string;
+    aad: string;
+    encapsulatedKey: string;
+    ciphertext: string;
+    aead?: string;
+    kem?: string;
+    kdf?: string;
+}
+/** A one-time X25519 key pair for receiving a sealed export. Send `publicKeyBase64`. */
+export declare function generateExportRecipientKeyPair(): {
+    privateKey: Uint8Array;
+    publicKeyBase64: string;
+};
+export declare function openHpkeBase(params: {
+    recipientPrivateKey: Uint8Array;
+    encapsulatedKey: Uint8Array;
+    ciphertext: Uint8Array;
+    info: Uint8Array;
+    aad: Uint8Array;
+    aead?: "aes-128-gcm" | "aes-256-gcm";
+}): Uint8Array;
+/** Open the `encryption` object a sealed export returns. Throws if it was tampered with. */
+export declare function openSealedExport(encryption: SealedExportEncryption, recipientPrivateKey: Uint8Array): string;

package/dist/packages/core/src/hpke-open.js

@@ -0,0 +1,89 @@
+import { gcm } from "@noble/ciphers/aes";
+import { x25519 } from "@noble/curves/ed25519";
+import { extract as hkdfExtract, expand as hkdfExpand } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha256";
+// Client side of Swivy's sealed export: HPKE base mode (RFC 9180) with
+// DHKEM(X25519, HKDF-SHA256), HKDF-SHA256 and AES-GCM. Pure JS, so it runs in browsers,
+// React Native and Node. The signer seals with the same suite (secure-signer/src/hpke.ts).
+const KEM_ID = 0x0020;
+const KDF_ID = 0x0001;
+const encoder = new TextEncoder();
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((total, part) => total + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function i2osp(value, length) {
+    const out = new Uint8Array(length);
+    for (let index = length - 1; index >= 0; index -= 1) {
+        out[index] = value & 0xff;
+        value >>= 8;
+    }
+    return out;
+}
+function labeledExtract(suiteId, salt, label, ikm) {
+    return hkdfExtract(sha256, concat(encoder.encode("HPKE-v1"), suiteId, encoder.encode(label), ikm), salt);
+}
+function labeledExpand(suiteId, prk, label, info, length) {
+    return hkdfExpand(sha256, prk, concat(i2osp(length, 2), encoder.encode("HPKE-v1"), suiteId, encoder.encode(label), info), length);
+}
+function fromBase64(value) {
+    const binary = atob(value);
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+export function toBase64(bytes) {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+/** A one-time X25519 key pair for receiving a sealed export. Send `publicKeyBase64`. */
+export function generateExportRecipientKeyPair() {
+    const privateKey = x25519.utils.randomPrivateKey();
+    return { privateKey, publicKeyBase64: toBase64(x25519.getPublicKey(privateKey)) };
+}
+export function openHpkeBase(params) {
+    const aead = params.aead ?? "aes-256-gcm";
+    if (aead !== "aes-128-gcm" && aead !== "aes-256-gcm") {
+        throw new Error("unsupported_hpke_aead");
+    }
+    const aeadId = aead === "aes-128-gcm" ? 0x0001 : 0x0002;
+    const keyLength = aead === "aes-128-gcm" ? 16 : 32;
+    const recipientPublic = x25519.getPublicKey(params.recipientPrivateKey);
+    const dh = x25519.getSharedSecret(params.recipientPrivateKey, params.encapsulatedKey);
+    const kemSuite = concat(encoder.encode("KEM"), i2osp(KEM_ID, 2));
+    const eaePrk = labeledExtract(kemSuite, new Uint8Array(), "eae_prk", dh);
+    const sharedSecret = labeledExpand(kemSuite, eaePrk, "shared_secret", concat(params.encapsulatedKey, recipientPublic), 32);
+    const suiteId = concat(encoder.encode("HPKE"), i2osp(KEM_ID, 2), i2osp(KDF_ID, 2), i2osp(aeadId, 2));
+    const pskIdHash = labeledExtract(suiteId, new Uint8Array(), "psk_id_hash", new Uint8Array());
+    const infoHash = labeledExtract(suiteId, new Uint8Array(), "info_hash", params.info);
+    const context = concat(new Uint8Array([0]), pskIdHash, infoHash);
+    const secret = labeledExtract(suiteId, sharedSecret, "secret", new Uint8Array());
+    const key = labeledExpand(suiteId, secret, "key", context, keyLength);
+    const nonce = labeledExpand(suiteId, secret, "base_nonce", context, 12);
+    return gcm(key, nonce, params.aad).decrypt(params.ciphertext);
+}
+/** Open the `encryption` object a sealed export returns. Throws if it was tampered with. */
+export function openSealedExport(encryption, recipientPrivateKey) {
+    // Older v1 clients omitted suite labels. Preserve that fixed-suite format,
+    // but never interpret an explicitly different or future suite as v1.
+    if (encryption.info !== "swivy-export-v1"
+        || (encryption.kem !== undefined && encryption.kem !== "DHKEM(X25519, HKDF-SHA256)")
+        || (encryption.kdf !== undefined && encryption.kdf !== "HKDF-SHA256")
+        || (encryption.aead !== undefined && encryption.aead !== "AES-256-GCM")) {
+        throw new Error("unsupported_sealed_export_suite");
+    }
+    const plaintext = openHpkeBase({
+        recipientPrivateKey,
+        encapsulatedKey: fromBase64(encryption.encapsulatedKey),
+        ciphertext: fromBase64(encryption.ciphertext),
+        info: encoder.encode(encryption.info),
+        aad: encoder.encode(encryption.aad),
+    });
+    return new TextDecoder().decode(plaintext);
+}