phaedo-mcp 0.1.0

package/vendor/envelope.js

@@ -0,0 +1,130 @@
+// Encryption envelope per Phaedo Protocol spec §7.2.
+//
+// Wraps artifact bytes (fingerprint or user configuration) in AES-256-GCM
+// with cleartext metadata bound as Additional Authenticated Data.
+//
+// Mirror of mobile/src/lib/envelope.ts. The two MUST produce bit-identical
+// wire bytes for identical (plaintext, key, metadata) inputs.
+//
+// Loaded as a plain script after protocol.js. Exposes globalThis.Phaedo.Envelope.
+
+(function () {
+  const P = globalThis.Phaedo.Protocol
+
+  // ── Encoding helpers ───────────────────────────────────────────────────────
+
+  function b64uEncode(bytes) {
+    let bin = ''
+    for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i])
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+  }
+
+  function b64uDecode(s) {
+    s = s.replace(/-/g, '+').replace(/_/g, '/')
+    while (s.length % 4) s += '='
+    const bin = atob(s)
+    const bytes = new Uint8Array(bin.length)
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
+    return bytes
+  }
+
+  /**
+   * Stable-key JSON stringify. Sufficient for the metadata AAD path, which
+   * contains only strings. NOT full RFC 8785 — when §8.3 signing lands and we
+   * canonicalize artifact bytes with numeric fields, switch to a JCS impl.
+   */
+  function canonicalStringify(value) {
+    if (value === null || typeof value !== 'object') return JSON.stringify(value)
+    if (Array.isArray(value)) {
+      return '[' + value.map(canonicalStringify).join(',') + ']'
+    }
+    const keys = Object.keys(value).sort()
+    return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalStringify(value[k])).join(',') + '}'
+  }
+
+  function utf8(s) { return new TextEncoder().encode(s) }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  /**
+   * Wrap plaintext bytes in an envelope.
+   *
+   * @param plaintext Uint8Array of canonical artifact bytes
+   * @param key       32-byte AES-256 key derived via HKDF from an ECDH shared secret
+   * @param metadata  Cleartext metadata; bound via GCM AAD
+   * @returns Promise<Envelope>
+   */
+  async function wrap(plaintext, key, metadata) {
+    if (key.length !== P.SIZES.AES_KEY) {
+      throw new Error(`envelope.wrap: key must be ${P.SIZES.AES_KEY} bytes, got ${key.length}`)
+    }
+
+    const iv  = crypto.getRandomValues(new Uint8Array(P.SIZES.AES_IV))
+    const aad = utf8(canonicalStringify(metadata))
+
+    const aesKey = await crypto.subtle.importKey(
+      'raw', key, 'AES-GCM', false, ['encrypt']
+    )
+    const ctAndTagBuf = await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv, additionalData: aad, tagLength: P.SIZES.AES_TAG * 8 },
+      aesKey,
+      plaintext
+    )
+    const ctAndTag = new Uint8Array(ctAndTagBuf)
+    const tagOffset = ctAndTag.length - P.SIZES.AES_TAG
+    const ciphertext = ctAndTag.subarray(0, tagOffset)
+    const tag        = ctAndTag.subarray(tagOffset)
+
+    return {
+      phaedo_envelope_version: P.ENVELOPE_VERSION,
+      alg:                     P.ALG,
+      iv:                      b64uEncode(iv),
+      ciphertext:              b64uEncode(ciphertext),
+      tag:                     b64uEncode(tag),
+      metadata,
+    }
+  }
+
+  /**
+   * Unwrap an envelope. Rejects on version mismatch, algorithm mismatch, or
+   * authentication tag failure (treated as integrity failure per spec §8.1).
+   *
+   * @returns Promise<Uint8Array> plaintext bytes
+   */
+  async function unwrap(envelope, key) {
+    if (envelope.phaedo_envelope_version !== P.ENVELOPE_VERSION) {
+      throw new Error(`envelope.unwrap: unsupported version ${envelope.phaedo_envelope_version}`)
+    }
+    if (envelope.alg !== P.ALG) {
+      throw new Error(`envelope.unwrap: unsupported alg ${envelope.alg}`)
+    }
+    if (key.length !== P.SIZES.AES_KEY) {
+      throw new Error(`envelope.unwrap: key must be ${P.SIZES.AES_KEY} bytes, got ${key.length}`)
+    }
+
+    const iv  = b64uDecode(envelope.iv)
+    const ct  = b64uDecode(envelope.ciphertext)
+    const tag = b64uDecode(envelope.tag)
+    const aad = utf8(canonicalStringify(envelope.metadata))
+
+    if (iv.length  !== P.SIZES.AES_IV)  throw new Error(`envelope.unwrap: iv must be ${P.SIZES.AES_IV} bytes`)
+    if (tag.length !== P.SIZES.AES_TAG) throw new Error(`envelope.unwrap: tag must be ${P.SIZES.AES_TAG} bytes`)
+
+    const ctAndTag = new Uint8Array(ct.length + tag.length)
+    ctAndTag.set(ct, 0)
+    ctAndTag.set(tag, ct.length)
+
+    const aesKey = await crypto.subtle.importKey(
+      'raw', key, 'AES-GCM', false, ['decrypt']
+    )
+    const ptBuf = await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv, additionalData: aad, tagLength: P.SIZES.AES_TAG * 8 },
+      aesKey,
+      ctAndTag
+    )
+    return new Uint8Array(ptBuf)
+  }
+
+  globalThis.Phaedo = globalThis.Phaedo || {}
+  globalThis.Phaedo.Envelope = { wrap, unwrap }
+})()

package/vendor/identity.js

@@ -0,0 +1,122 @@
+// Long-term X25519 identity keypair for this Phaedo extension instance.
+//
+// The private key is the extension's persistent cryptographic identity.
+// Used at pair time to derive a shared pair_key with a paired vault device,
+// and at session start to authenticate the extension's ephemeral session pubkey.
+//
+// Persistence: stored INSIDE the vault (encrypted under the vault's AES-GCM
+// session key, see vault.js). This means using the identity requires the
+// vault to be unlocked. Acceptable because pairing and authorize flows are
+// only meaningful when the user is actively present.
+//
+// Loaded as a plain script after vault.js. Exposes globalThis.Phaedo.Identity.
+
+(function () {
+  const VAULT_FIELD = 'identity_v0.1'  // sub-key inside the vault object
+
+  function b64uEncode(bytes) {
+    let bin = ''
+    for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i])
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+  }
+
+  function b64uDecode(s) {
+    s = s.replace(/-/g, '+').replace(/_/g, '/')
+    while (s.length % 4) s += '='
+    const bin = atob(s)
+    const bytes = new Uint8Array(bin.length)
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
+    return bytes
+  }
+
+  async function generate() {
+    const kp = await crypto.subtle.generateKey({ name: 'X25519' }, true, ['deriveBits'])
+    const publicKeyRaw = new Uint8Array(await crypto.subtle.exportKey('raw', kp.publicKey))
+    const privateKeyJwk = await crypto.subtle.exportKey('jwk', kp.privateKey)
+    return { publicKey: publicKeyRaw, privateKey: kp.privateKey, privateKeyJwk }
+  }
+
+  async function importStored(stored) {
+    const publicKey  = b64uDecode(stored.publicKey)
+    const privateKey = await crypto.subtle.importKey(
+      'jwk', stored.privateKeyJwk, { name: 'X25519' }, false, ['deriveBits']
+    )
+    return { publicKey, privateKey }
+  }
+
+  /**
+   * Return the extension's identity, generating one on first call.
+   * Throws if the vault is locked — caller must unlock first.
+   *
+   * @returns {Promise<{ publicKey: Uint8Array, privateKey: CryptoKey }>}
+   */
+  async function getOrCreate() {
+    const vault = await globalThis.phaedoVault.read()
+    if (!vault) throw new Error('Phaedo.Identity: vault is locked')
+
+    if (vault[VAULT_FIELD]) {
+      return importStored(vault[VAULT_FIELD])
+    }
+
+    const fresh = await generate()
+    await globalThis.phaedoVault.update({
+      [VAULT_FIELD]: {
+        publicKey:     b64uEncode(fresh.publicKey),
+        privateKeyJwk: fresh.privateKeyJwk,
+      },
+    })
+    return { publicKey: fresh.publicKey, privateKey: fresh.privateKey }
+  }
+
+  /**
+   * Compute the long-term ECDH shared secret with a peer's identity pubkey.
+   * @param {Uint8Array} peerPublicKey — 32 raw X25519 public key bytes
+   * @returns {Promise<Uint8Array>} 32-byte shared secret (NOT a session key — feed through HKDF)
+   */
+  async function deriveSharedWithPeer(peerPublicKey) {
+    if (peerPublicKey.length !== 32) {
+      throw new Error(`Phaedo.Identity.deriveSharedWithPeer: peer pubkey must be 32 bytes, got ${peerPublicKey.length}`)
+    }
+    const { privateKey } = await getOrCreate()
+    const peerKey = await crypto.subtle.importKey(
+      'raw', peerPublicKey, { name: 'X25519' }, false, []
+    )
+    const shared = await crypto.subtle.deriveBits({ name: 'X25519', public: peerKey }, privateKey, 256)
+    return new Uint8Array(shared)
+  }
+
+  /** Just the public key. Convenience for QR display / pairing. */
+  async function getPublicKey() {
+    const { publicKey } = await getOrCreate()
+    return publicKey
+  }
+
+  /**
+   * Generate a fresh ephemeral X25519 keypair. Used per-session in the
+   * authorize handshake. The returned privateKey CryptoKey will be GC'd
+   * when its references drop — keep the closure scope tight.
+   */
+  async function generateEphemeral() {
+    const kp = await crypto.subtle.generateKey({ name: 'X25519' }, true, ['deriveBits'])
+    const publicKey = new Uint8Array(await crypto.subtle.exportKey('raw', kp.publicKey))
+    return { publicKey, privateKey: kp.privateKey }
+  }
+
+  /** ECDH between an ephemeral private key and a peer's ephemeral pubkey bytes. */
+  async function deriveEphemeralShared(selfEphPrivate, peerEphPublicBytes) {
+    if (peerEphPublicBytes.length !== 32) {
+      throw new Error(`Phaedo.Identity.deriveEphemeralShared: peer eph pubkey must be 32 bytes, got ${peerEphPublicBytes.length}`)
+    }
+    const peerKey = await crypto.subtle.importKey(
+      'raw', peerEphPublicBytes, { name: 'X25519' }, false, []
+    )
+    const shared = await crypto.subtle.deriveBits({ name: 'X25519', public: peerKey }, selfEphPrivate, 256)
+    return new Uint8Array(shared)
+  }
+
+  globalThis.Phaedo = globalThis.Phaedo || {}
+  globalThis.Phaedo.Identity = {
+    getOrCreate, deriveSharedWithPeer, getPublicKey,
+    generateEphemeral, deriveEphemeralShared,
+  }
+})()

package/vendor/kdf.js

@@ -0,0 +1,114 @@
+// Key derivation helpers using native WebCrypto HKDF-SHA-256.
+//
+// Mirror of mobile/src/lib/kdf.ts. Both sides produce identical bytes for
+// identical inputs.
+//
+// Loaded as a plain script after protocol.js. Exposes globalThis.Phaedo.Kdf.
+
+(function () {
+  const P = globalThis.Phaedo.Protocol
+
+  function utf8(s) { return new TextEncoder().encode(s) }
+
+  async function hkdfBytes(ikm, salt, info, outputLen) {
+    const key = await crypto.subtle.importKey('raw', ikm, 'HKDF', false, ['deriveBits'])
+    const bits = await crypto.subtle.deriveBits(
+      { name: 'HKDF', hash: 'SHA-256', salt, info },
+      key,
+      outputLen * 8,
+    )
+    return new Uint8Array(bits)
+  }
+
+  async function derivePairKey(sharedSecret, clientId) {
+    return hkdfBytes(
+      sharedSecret,
+      utf8(clientId),
+      utf8(P.HKDF_INFO.PAIR_KEY),
+      P.SIZES.AES_KEY,
+    )
+  }
+
+  /**
+   * Seed-transfer key for QR-free pairing (spec §8.4). HKDF-Expand of the
+   * SAS-verified pair_key under a distinct context, so the AES-GCM seed
+   * envelope never reuses pair_key's HMAC-in-authorize role. Re-derivable
+   * from the stored pair_key, so the seed ship step holds no extra state.
+   */
+  async function deriveSeedKey(pairKey) {
+    return hkdfBytes(
+      pairKey,
+      new Uint8Array(0),
+      utf8(P.HKDF_INFO.SEED_KEY),
+      P.SIZES.AES_KEY,
+    )
+  }
+
+  async function deriveSessionKey(ephemeralShared, sessionToken) {
+    return hkdfBytes(
+      ephemeralShared,
+      utf8(sessionToken),
+      utf8(P.HKDF_INFO.SESSION_KEY),
+      P.SIZES.AES_KEY,
+    )
+  }
+
+  function compareBytes(a, b) {
+    const n = Math.min(a.length, b.length)
+    for (let i = 0; i < n; i++) {
+      if (a[i] !== b[i]) return a[i] - b[i]
+    }
+    return a.length - b.length
+  }
+
+  async function deriveSAS(pubA, pubB) {
+    const [first, second] = compareBytes(pubA, pubB) <= 0 ? [pubA, pubB] : [pubB, pubA]
+    const combined = new Uint8Array(first.length + second.length)
+    combined.set(first, 0)
+    combined.set(second, first.length)
+    return hkdfBytes(
+      combined,
+      new Uint8Array(0),
+      utf8(P.HKDF_INFO.SAS_FINGERPRINT),
+      P.SIZES.SAS_BYTES,
+    )
+  }
+
+  const EPH_AUTH_LABEL = 'phaedo-eph-auth-v0.1'
+
+  /**
+   * HMAC-SHA-256(pair_key, role_label || ephPub).
+   * Binds the ephemeral exchange in authorize to the established pair_key.
+   * @param role 'ext' or 'vault' — prevents MAC replay across directions.
+   */
+  async function authEphemeral(pairKey, role, ephPub) {
+    const label = utf8(`${EPH_AUTH_LABEL}|${role}|`)
+    const msg = new Uint8Array(label.length + ephPub.length)
+    msg.set(label, 0)
+    msg.set(ephPub, label.length)
+    const macKey = await crypto.subtle.importKey(
+      'raw', pairKey, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']
+    )
+    return new Uint8Array(await crypto.subtle.sign('HMAC', macKey, msg))
+  }
+
+  /** Constant-time MAC verification. */
+  async function verifyAuthEphemeral(pairKey, role, ephPub, expectedMac) {
+    const computed = await authEphemeral(pairKey, role, ephPub)
+    if (computed.length !== expectedMac.length) return false
+    let diff = 0
+    for (let i = 0; i < computed.length; i++) diff |= computed[i] ^ expectedMac[i]
+    return diff === 0
+  }
+
+  /** Format SAS bytes as a human-readable "XX-XX-XX-XX" hex string. */
+  function formatSAS(sasBytes) {
+    return Array.from(sasBytes, b => b.toString(16).padStart(2, '0').toUpperCase()).join('-')
+  }
+
+  globalThis.Phaedo = globalThis.Phaedo || {}
+  globalThis.Phaedo.Kdf = {
+    derivePairKey, deriveSeedKey, deriveSessionKey, deriveSAS, formatSAS,
+    authEphemeral, verifyAuthEphemeral,
+  }
+})()

package/vendor/protocol.js

@@ -0,0 +1,56 @@
+// Phaedo Protocol constants. Single source of truth on the extension side.
+// Matches mobile/src/lib/protocol.ts — keep both in sync.
+// See docs/protocol/v0.1.md for the authoritative spec.
+//
+// Loaded as a plain script before vault.js and popup.js. Exposes globalThis.Phaedo.Protocol.
+
+(function () {
+  const Protocol = {
+    /** Phaedo Protocol version. Sent on the wire in pairing payloads. */
+    VERSION: '0.1.1',
+
+    /** Envelope format version. Goes into phaedo_envelope_version field per spec §7.2. */
+    ENVELOPE_VERSION: '0.1',
+
+    /** Portable export wrapper version. Goes into phaedo_export_version per spec §8.2. */
+    EXPORT_VERSION: '0.1',
+
+    /** Encryption algorithm. v0.1 normative: AES-256-GCM only. Spec §7.1. */
+    ALG: 'AES-256-GCM',
+
+    /**
+     * HKDF info labels. Domain separation between key derivation contexts.
+     * MUST be byte-identical on mobile and extension or keys will diverge.
+     */
+    HKDF_INFO: {
+      PAIR_KEY:        'phaedo-pair-key-v0.1',
+      SESSION_KEY:     'phaedo-session-v0.1',
+      SAS_FINGERPRINT: 'phaedo-sas-v0.1',
+      // Seed-transfer key for QR-free pairing (spec §8.4). A sub-key of
+      // pair_key so the GCM seed envelope never reuses pair_key's HMAC role.
+      SEED_KEY:        'phaedo-seed-v0.1',
+    },
+
+    /** Sizes in bytes — fixed by spec §7.2. */
+    SIZES: {
+      X25519_PUBKEY:  32,
+      X25519_PRIVKEY: 32,
+      AES_KEY:        32,
+      AES_IV:         12,
+      AES_TAG:        16,
+      HKDF_SALT:      16,
+      SAS_BYTES:      4,
+    },
+
+    /** Artifact kind tags in envelope metadata. Spec §7.2. */
+    ARTIFACT_KIND: {
+      FINGERPRINT:        'fingerprint',
+      USER_CONFIGURATION: 'user_configuration',
+      EXCHANGE_BATCH:     'exchange_batch',     // Loop 2 qualifying-session batch (the local-pass payload shape)
+    },
+  }
+
+  // Attach to globalThis so content scripts, popup, and interview adapters all see it.
+  globalThis.Phaedo = globalThis.Phaedo || {}
+  globalThis.Phaedo.Protocol = Protocol
+})()