@paramira/did-e2e 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 phuman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# @paramira/did-e2e
 
-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.
+Pairwise end-to-end encryption between two `did:iwacu:` identities — no
+DIDComm, no Credo, no wallet. Ed25519-to-X25519 key conversion, ECDH,
+HKDF-SHA256, XChaCha20-Poly1305. A relay carrying the result sees only an
+opaque tagged blob; it can route the message without ever reading it.
+
+```js
+import { encryptForDid, decryptFromDid, isEncrypted } from '@paramira/did-e2e'
+
+// alice and bob are each { did, privateKeyBytes } — the same two fields
+// every paramira identity object already carries.
+const message = await encryptForDid('hey', bob.did, alice)
+
+isEncrypted(message) // -> true — a relay can check this without decrypting
+
+const result = await decryptFromDid(message, bob)
+// -> { plaintext: 'hey', fromDid: alice.did }
+
+// Addressed to someone else, not yet encrypted, or tampered with —
+// decryptFromDid() never throws and never returns garbage, only null.
+await decryptFromDid(message, carol) // -> null
+```
+
+`myIdentity` needs just `{ did, privateKeyBytes }` (the raw 32-byte
+Ed25519 seed) — the exact shape `@paramira/identity`'s `generateKeypair()`
+already returns, so a real identity object passes straight through with
+no adapting.
+
+## What this protects, and what it doesn't
+
+Message *content* is end-to-end encrypted — only the recipient's private
+key can read it, not a relay, not a bridge, not an intermediary carrying
+it toward its destination. `from`/`to` DIDs travel in the clear inside
+the encrypted blob's own JSON, though — a relay or bridge still needs
+that to know where to send it next, and the recipient needs it to know
+which shared secret to derive. That means this package hides *what* was
+said, not *who said it to whom* — full metadata-hiding (traffic-analysis
+resistance) is a separate, larger concern this package deliberately
+doesn't attempt.
+
+## Where this came from
+
+Extracted out of `apps/isoko/src/services/secureChannel.ts`, where this
+exact logic already existed, worked, and shipped in a real app — just
+untested (isoko had zero test coverage for it) and not reusable outside
+that one React Native codebase. The `domain` option on both functions
+exists solely so isoko's own re-export can keep deriving the exact keys
+it always has (`{ domain: 'isoko-e2e' }`) — anyone starting fresh should
+leave it at the default and never think about it again.
+
+Built for `docs/plans/intercommunity-relays.md`'s Plan B — the inner,
+peer-sealed layer of a two-layer envelope for messages crossing between
+communities on separately self-managed relays. The outer, community-
+sealed layer is a job for `@paramira/aes-gcm` instead (a symmetric key
+derived from the community's own `cellSecret`), not this package — see
+that plan for the full two-layer design and why each layer is a
+different primitive.

package/index.d.ts

@@ -0,0 +1,28 @@
+export const SECURE_TAG: string
+
+export interface DidIdentity {
+  did: string
+  privateKeyBytes: Uint8Array
+}
+
+export interface DidE2eOptions {
+  /** Domain-separates the derived key. Leave at the default unless you
+   * need to match an already-shipped wire format (see isoko's own
+   * re-export, which passes 'isoko-e2e' for exactly this reason). */
+  domain?: string
+}
+
+export function encryptForDid(
+  plaintext: string,
+  recipientDid: string,
+  myIdentity: DidIdentity,
+  options?: DidE2eOptions,
+): Promise<string>
+
+export function decryptFromDid(
+  message: string,
+  myIdentity: DidIdentity,
+  options?: DidE2eOptions,
+): Promise<{ plaintext: string, fromDid: string } | null>
+
+export function isEncrypted(message: string): boolean

package/index.js

@@ -0,0 +1,126 @@
+/**
+ * Pairwise end-to-end encryption between two did:iwacu: identities.
+ *
+ * Key exchange: Ed25519 -> X25519 conversion + ECDH shared secret
+ * Encryption:   XChaCha20-Poly1305 (authenticated, nonce-misuse-resistant)
+ * KDF:          HKDF-SHA256 over the ECDH output
+ *
+ * A relay carrying the result of encryptForDid() only ever sees an opaque
+ * tagged blob — it routes but cannot read content. `from`/`to` DIDs
+ * travel in the clear inside that blob (needed so the recipient knows
+ * which shared secret to derive, and so a relay/bridge knows where to
+ * send it next) — this protects content, not who's-talking-to-whom
+ * metadata; full metadata-hiding is a deliberately separate, later
+ * concern (see docs/plans/intercommunity-relays.md's own open questions).
+ *
+ * Extracted out of apps/isoko/src/services/secureChannel.ts, where this
+ * logic already existed and worked, just app-specific and untested. The
+ * `domain` option exists solely so isoko's own re-export of these
+ * functions can keep deriving the exact same keys it always has
+ * (`domain: 'isoko-e2e'`) — anyone using this package fresh should leave
+ * it at the default.
+ */
+import { ed25519, x25519 } from '@noble/curves/ed25519.js'
+import { xchacha20poly1305 } from '@noble/ciphers/chacha.js'
+import { hkdf } from '@noble/hashes/hkdf.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { publicKeyFromDid } from '@paramira/identity'
+
+/** Prefixes every encrypted payload — lets a caller cheaply tell an
+ * encrypted message apart from a plain one (see isEncrypted()) without
+ * attempting a decrypt. Kept as the literal isoko already shipped with,
+ * not re-versioned, so nothing already-relayed/queued stops parsing. */
+export const SECURE_TAG = '__e2e__:'
+
+const DEFAULT_DOMAIN = 'paramira-e2e'
+
+function bytesToB64(bytes) {
+  let bin = ''
+  for (const b of bytes) bin += String.fromCharCode(b)
+  return btoa(bin)
+}
+
+function b64ToBytes(s) {
+  return Uint8Array.from(atob(s), c => c.charCodeAt(0))
+}
+
+function toX25519Pub(publicKeyBytes) {
+  return ed25519.utils.toMontgomery(publicKeyBytes)
+}
+
+function toX25519Priv(privateKeyBytes) {
+  return ed25519.utils.toMontgomerySecret(privateKeyBytes)
+}
+
+function deriveKey(sharedSecret, info) {
+  return hkdf(sha256, sharedSecret, new Uint8Array(0), new TextEncoder().encode(info), 32)
+}
+
+function randomBytes(n) {
+  const arr = new Uint8Array(n)
+  crypto.getRandomValues(arr)
+  return arr
+}
+
+/**
+ * Encrypt `plaintext` so only `recipientDid`'s own private key can read
+ * it. `myIdentity` needs just `{ did, privateKeyBytes }` — the same two
+ * fields every paramira identity object already carries (see
+ * @paramira/identity's own Identity shape), so a caller's real identity
+ * object can be passed straight through with no adapting.
+ */
+export async function encryptForDid(plaintext, recipientDid, myIdentity, options = {}) {
+  const domain = options.domain ?? DEFAULT_DOMAIN
+  const myX25519Priv = toX25519Priv(myIdentity.privateKeyBytes)
+  const theirX25519Pub = toX25519Pub(publicKeyFromDid(recipientDid))
+  const sharedSecret = x25519.getSharedSecret(myX25519Priv, theirX25519Pub)
+  const key = deriveKey(sharedSecret, `${domain}:${myIdentity.did}:${recipientDid}`)
+
+  const nonce = randomBytes(24)
+  const cipher = xchacha20poly1305(key, nonce)
+  const ciphertext = cipher.encrypt(new TextEncoder().encode(plaintext))
+
+  const payload = {
+    from: myIdentity.did,
+    to: recipientDid,
+    nonce: bytesToB64(nonce),
+    ct: bytesToB64(ciphertext),
+  }
+  return SECURE_TAG + JSON.stringify(payload)
+}
+
+/**
+ * Reverse encryptForDid(). Returns `null` — never throws, never returns
+ * garbage — for anything that isn't a genuine, correctly-addressed,
+ * untampered message for `myIdentity`: a plain (unencrypted) message, a
+ * message addressed to someone else, a malformed payload, or a payload
+ * whose auth tag doesn't verify (wrong key or tampered ciphertext —
+ * XChaCha20-Poly1305's own guarantee).
+ */
+export async function decryptFromDid(message, myIdentity, options = {}) {
+  if (!message.startsWith(SECURE_TAG)) return null
+  const domain = options.domain ?? DEFAULT_DOMAIN
+  try {
+    const payload = JSON.parse(message.slice(SECURE_TAG.length))
+    if (payload.to !== myIdentity.did) return null
+
+    const myX25519Priv = toX25519Priv(myIdentity.privateKeyBytes)
+    const senderX25519Pub = toX25519Pub(publicKeyFromDid(payload.from))
+    const sharedSecret = x25519.getSharedSecret(myX25519Priv, senderX25519Pub)
+    const key = deriveKey(sharedSecret, `${domain}:${payload.from}:${payload.to}`)
+
+    const nonce = b64ToBytes(payload.nonce)
+    const ct = b64ToBytes(payload.ct)
+    const cipher = xchacha20poly1305(key, nonce)
+    const plaintext = new TextDecoder().decode(cipher.decrypt(ct))
+    return { plaintext, fromDid: payload.from }
+  } catch {
+    return null
+  }
+}
+
+/** Cheaply tell an encrypted message apart from a plain one, without
+ * attempting a decrypt. */
+export function isEncrypted(message) {
+  return typeof message === 'string' && message.startsWith(SECURE_TAG)
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@paramira/did-e2e",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Pairwise end-to-end encryption between two did:iwacu: identities — Ed25519-to-X25519 conversion, ECDH, HKDF, XChaCha20-Poly1305. A relay carrying the result sees only an opaque blob.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/phuman/paramira.git",
+    "directory": "packages/did-e2e"
+  },
+  "keywords": [
+    "did",
+    "end-to-end-encryption",
+    "ed25519",
+    "x25519",
+    "ecdh",
+    "paramira"
+  ],
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./index.js"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^2.2.0",
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "@paramira/identity": "0.1.1"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
 }