@oxpulse/intro-protocol 0.2.0

package/README.md

@@ -0,0 +1,54 @@
+# @oxpulse/intro-protocol
+
+**EXPERIMENTAL — version 0.1.0.** The L2 introduction protocol as one
+bounded context: Briar-faithful intro crypto (X25519+HKDF+AEAD, MAC/sig),
+a JSON+Zod wire codec for the 6 intro message types, and Signal-style
+safety-number (SAS) derivation.
+
+> ⚠️ **EXPERIMENTAL.** This package has not been audited. The crypto
+> invariants are documented in [SECURITY.md](./SECURITY.md) but the
+> package is pre-1.0 and the API may change.
+
+## Public surface (flat exports — ADR-003)
+
+All exports are flat from the package root
+(`@oxpulse/intro-protocol`); there are no sub-path exports.
+
+### intro-crypto
+
+- **Labels / version** — `LABEL_SESSION_ID`, `LABEL_MASTER_KEY`,
+  `LABEL_ALICE_MAC_KEY`, `LABEL_BOB_MAC_KEY`, `LABEL_AUTH_MAC`,
+  `LABEL_AUTH_NONCE`, `LABEL_AUTH_SIGN`, `LABEL_ACTIVATE_MAC`,
+  `PROTOCOL_VERSION`
+- **Session ID** — `deriveSessionId`
+- **Role assignment** — `isAliceRole` (constant-time lexicographic compare)
+- **Key derivation** — `deriveMasterKey`, `deriveMacKeys`
+- **Auth transcript** — `buildAuthTranscript`, `TranscriptParty`
+- **AUTH MAC** — `computeAuthMac`, `verifyAuthMac`
+- **AUTH SIG** — `computeAuthSig`, `verifyAuthSig`
+- **ACTIVATE MAC** — `computeActivateMac`, `verifyActivateMac`
+- **AEAD (XChaCha20-Poly1305)** — `sealAead`, `openAead`, `AeadEnvelope`
+
+### intro-wire
+
+- **Schemas** — `IntroRequestV1Schema`, `IntroAcceptV1Schema`,
+  `IntroDeclineV1Schema`, `IntroAuthV1Schema`, `IntroActivateV1Schema`,
+  `IntroAbortV1Schema`, `IntroMessageSchema`
+- **Codec** — `encodeIntroMessage`, `decodeIntroMessage`
+- **Session ID redundancy** — `verifySessionIdRedundancy` (CWE-208 fixed)
+- **Types** — `IntroMessage`, `IntroKind`
+
+### intro-safety-number
+
+- **Safety number** — `deriveSafetyNumber` (60-digit SAS, 12 groups of 5)
+
+## Constant-time comparison (CWE-208 invariant)
+
+`timingSafeEqual` and `timingSafePubkeyEqualB64u` are imported from
+`@oxpulse/crypto-primitives` (the single public source of truth, ADR-008).
+All attacker-influenced cryptographic comparisons in this package use them.
+See [SECURITY.md](./SECURITY.md) for the full threat model and invariants.
+
+## License
+
+AGPL-3.0-or-later. See [LICENSE](./LICENSE).

package/SECURITY.md

@@ -0,0 +1,116 @@
+# Security policy — @oxpulse/intro-protocol
+
+**EXPERIMENTAL — version 0.1.0.** This package has not been independently
+audited. The invariants below are documented for review and regression
+testing; they are not a substitute for a formal audit.
+
+## Threat model
+
+This package implements the **L2 introduction protocol**: two parties
+(Alice and Bob) are introduced by a mutual introducer over a QR code /
+introduction channel. The threat model is:
+
+- The **introducer** is partially trusted — they choose which two parties
+  to introduce but must not be able to forge a session undetected.
+- **Long-term Ed25519 pubkeys** are PUBLIC — they are exchanged over the
+  QR code / introduction channel in cleartext. They are not secret material.
+- The **introducer's public key** is attacker-influenced (a malicious
+  introducer controls it). The **wire sessionId** is attacker-influenced
+  (a malicious introducer or man-in-the-channel can set it).
+- **Ephemeral X25519 keys**, the **master key**, **MAC keys**, and the
+  **AEAD key** are secret and never transmitted.
+- The channel is asynchronous (sdk-inbox-bridge sealed payloads); there is
+  no live key-agreement handshake, so redundancy checks and MACs/signatures
+  carry the integrity guarantee.
+
+## CWE-208 fix — `verifySessionIdRedundancy` (ADR-011)
+
+**Vulnerable (before):** `verifySessionIdRedundancy` compared the wire
+sessionId to the locally-derived sessionId with plain `===`:
+
+```ts
+return msg.sessionId === derivedSessionId;
+```
+
+A plain `===` on a crypto-derived base64url string short-circuits on the
+first mismatched character, leaking the first-mismatch byte position via
+timing. Because the wire sessionId is attacker-influenced (a malicious
+introducer controls it), this created a **timing oracle**: an attacker
+could iteratively guess the locally-derived sessionId one byte at a time
+by measuring how long the comparison ran before returning `false`. This
+violates **OWASP ASVS V11.3.1** and is classified as **CWE-208**
+(Observable Timing Discrepancy).
+
+**Fixed (now):** The comparison uses `timingSafePubkeyEqualB64u` from
+`@oxpulse/crypto-primitives`, which decodes both base64url strings to
+bytes and compares with `timingSafeEqual` (XOR-reduce over all bytes,
+returns `false` on length mismatch — length is non-secret). No
+short-circuit path based on byte content remains.
+
+```ts
+return timingSafePubkeyEqualB64u(msg.sessionId, derivedSessionId);
+```
+
+A regression test (`intro-wire.test.ts`) asserts the fix: two sessionIds
+differing only in the last byte return `false` without throwing, and the
+function returns a boolean for equal, first-char-differing, last-char-
+differing, and different-length inputs.
+
+## Constant-time invariants
+
+**INVARIANT:** Every comparison of an attacker-influenced cryptographic
+identifier uses `timingSafeEqual` (raw bytes) or
+`timingSafePubkeyEqualB64u` (base64url strings), imported from
+`@oxpulse/crypto-primitives`. Plain `===` is NEVER used on crypto-derived
+b64u strings, MAC tags, signatures, or sessionIds.
+
+The functions that enforce this:
+
+| Function | Compares | Constant-time? |
+|---|---|---|
+| `verifySessionIdRedundancy` | wire sessionId vs derived sessionId (b64u) | ✅ `timingSafePubkeyEqualB64u` |
+| `verifyAuthMac` | expected HMAC vs received HMAC (bytes) | ✅ `timingSafeEqual` |
+| `verifyActivateMac` | expected HMAC vs received HMAC (bytes) | ✅ `timingSafeEqual` |
+| `verifyAuthSig` | Ed25519 signature (delegated to `ed25519.verify`) | ✅ (noble verifies in constant time) |
+| `isAliceRole` | local pubkey vs peer pubkey (bytes) | ✅ walks all bytes, branchless decide |
+
+## Non-constant-time — safe because public (ADR-012)
+
+Two comparisons in this package are intentionally NOT constant-time. This
+is safe because the values being compared are PUBLIC over the QR code /
+introduction channel — they are not secret, so leaking the
+first-differing-byte position via timing reveals nothing an attacker does
+not already know.
+
+### `lexLess` (intro-safety-number.ts)
+
+`lexLess` orders the two long-term pubkeys (lex-smaller first) before
+CBOR-encoding the safety-number input. It returns early on the first
+differing byte. This is safe because:
+
+1. The pubkeys are already public (transmitted in cleartext over the
+   QR / introduction channel).
+2. The ordering only determines array position in the CBOR input — it
+   does not gate any security decision on secret data.
+3. A constant-time version (`isAliceRole` in intro-crypto.ts) exists where
+   the comparison itself IS security-relevant (role assignment).
+
+See **ADR-012** for the full reasoning.
+
+### SAS human comparison (SECURITY_COST-8)
+
+`deriveSafetyNumber` returns a 60-digit Short Authentication String (SAS)
+intended to be read aloud or compared visually by the two human parties
+over an authenticated side channel (in-person, phone call). The comparison
+is performed by **humans**, who are inherently non-constant-time. No
+constant-time comparison is required or meaningful for the SAS value
+itself — the security property comes from the human comparing the full
+string, not from a code-level equality check. The underlying
+`deriveSafetyNumber` computation is deterministic and side-channel-free
+(pure SHA-512 + CBOR, no secret-dependent branches on attacker-controlled
+input beyond the public pubkey ordering).
+
+## Reporting a vulnerability
+
+Do NOT open a public GitHub issue for a security vulnerability. Email the
+maintainer privately. See the repository root for contact details.

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @oxpulse/intro-protocol — L2 introduction protocol (bounded context).
+ *
+ * ADR-010: One package containing intro-crypto + intro-wire + intro-safety-number.
+ * ADR-003: Flat public re-exports — no sub-path exports.
+ *
+ * EXPERIMENTAL (0.1.0). See SECURITY.md for the threat model and
+ * constant-time invariants.
+ */
+export { LABEL_SESSION_ID, LABEL_MASTER_KEY, LABEL_ALICE_MAC_KEY, LABEL_BOB_MAC_KEY, LABEL_AUTH_MAC, LABEL_AUTH_NONCE, LABEL_AUTH_SIGN, LABEL_ACTIVATE_MAC, PROTOCOL_VERSION, deriveSessionId, isAliceRole, deriveMasterKey, deriveMacKeys, wipeMacKeys, wipe, buildAuthTranscript, computeAuthMac, verifyAuthMac, computeAuthSig, verifyAuthSig, computeActivateMac, verifyActivateMac, sealAead, openAead, envelopeToWireB64u, wireB64uToEnvelope, type TranscriptParty, type AeadEnvelope, type AeadLabel, } from './intro-crypto.ts';
+export { IntroRequestV1Schema, IntroAcceptV1Schema, IntroDeclineV1Schema, IntroAuthV1Schema, IntroActivateV1Schema, IntroAbortV1Schema, IntroMessageSchema, encodeIntroMessage, decodeIntroMessage, verifySessionIdRedundancy, type IntroMessage, type IntroKind, } from './intro-wire.ts';
+export { deriveSafetyNumber } from './intro-safety-number.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,eAAe,EACf,aAAa,EACb,WAAW,EACX,IAAI,EACJ,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,QAAQ,EACR,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @oxpulse/intro-protocol — L2 introduction protocol (bounded context).
+ *
+ * ADR-010: One package containing intro-crypto + intro-wire + intro-safety-number.
+ * ADR-003: Flat public re-exports — no sub-path exports.
+ *
+ * EXPERIMENTAL (0.1.0). See SECURITY.md for the threat model and
+ * constant-time invariants.
+ */
+// intro-crypto — Briar-faithful crypto primitives (X25519+HKDF+AEAD, MAC/sig)
+export { LABEL_SESSION_ID, LABEL_MASTER_KEY, LABEL_ALICE_MAC_KEY, LABEL_BOB_MAC_KEY, LABEL_AUTH_MAC, LABEL_AUTH_NONCE, LABEL_AUTH_SIGN, LABEL_ACTIVATE_MAC, PROTOCOL_VERSION, deriveSessionId, isAliceRole, deriveMasterKey, deriveMacKeys, wipeMacKeys, wipe, buildAuthTranscript, computeAuthMac, verifyAuthMac, computeAuthSig, verifyAuthSig, computeActivateMac, verifyActivateMac, sealAead, openAead, envelopeToWireB64u, wireB64uToEnvelope, } from "./intro-crypto.js";
+// intro-wire — JSON+Zod wire codec for the 6 intro message types
+export { IntroRequestV1Schema, IntroAcceptV1Schema, IntroDeclineV1Schema, IntroAuthV1Schema, IntroActivateV1Schema, IntroAbortV1Schema, IntroMessageSchema, encodeIntroMessage, decodeIntroMessage, verifySessionIdRedundancy, } from "./intro-wire.js";
+// intro-safety-number — Signal-style safety number (SAS) derivation
+export { deriveSafetyNumber } from "./intro-safety-number.js";

package/dist/intro-crypto.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Briar-faithful crypto primitives for the L2 introduction protocol.
+ *
+ * All functions are pure — no side-effects beyond the returned values.
+ * Implements sub-spec §4.2 (labels, key derivation, MAC/sig, AEAD).
+ *
+ * Label encoding: UTF-8 at use-site, no NUL terminators (architect nit #2).
+ * MAC comparison: always constant-time via timingSafeEqual (W4).
+ *
+ * ADR-010: This module is part of the @oxpulse/intro-protocol bounded
+ * context (intro-crypto + intro-wire + intro-safety-number in ONE package).
+ *
+ * ADR-008: timingSafeEqual + timingSafePubkeyEqualB64u are imported from
+ * @oxpulse/crypto-primitives (the single public source of truth for
+ * constant-time comparison). concatBytes + utf8 stay local here — they are
+ * internal general-purpose helpers, not part of the crypto-primitives
+ * public surface.
+ */
+export declare const LABEL_SESSION_ID = "oxpulse-intro-v1/SESSION_ID";
+export declare const LABEL_MASTER_KEY = "oxpulse-intro-v1/MASTER_KEY";
+export declare const LABEL_ALICE_MAC_KEY = "oxpulse-intro-v1/ALICE_MAC_KEY";
+export declare const LABEL_BOB_MAC_KEY = "oxpulse-intro-v1/BOB_MAC_KEY";
+export declare const LABEL_AUTH_MAC = "oxpulse-intro-v1/AUTH_MAC";
+export declare const LABEL_AUTH_NONCE = "oxpulse-intro-v1/AUTH_NONCE";
+export declare const LABEL_AUTH_SIGN = "oxpulse-intro-v1/AUTH_SIGN";
+export declare const LABEL_ACTIVATE_MAC = "oxpulse-intro-v1/ACTIVATE_MAC";
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * Best-effort zeroization of secret key material (ADR-013 / #216).
+ *
+ * Overwrites the buffer with zeros. JS zeroization is best-effort — V8 may
+ * copy Uint8Array contents during GC compaction, so this is NOT a guarantee
+ * that no copy survives — but it is the recognized hardening baseline and
+ * the SECURITY.md threat model already promises these values are secret.
+ *
+ * Callers MUST wipe:
+ *   - ephemeral private keys after `deriveMasterKey`
+ *   - `masterKey` when done with all derived MAC keys + AEAD operations
+ *   - MAC keys via {@link wipeMacKeys} when the handshake completes/aborts
+ *
+ * Returns the same Uint8Array reference (now zeroed) for convenience.
+ */
+export declare function wipe(u: Uint8Array): Uint8Array;
+/**
+ * Derives a deterministic 16-byte (22-char base64url) session ID.
+ *
+ * input  = utf8(LABEL_SESSION_ID) || introducerPub || firstPub || secondPub
+ * result = SHA-256(input)[0..16] encoded as base64url
+ *
+ * All pubkeys must be 32-byte Ed25519 pubkeys (raw bytes, not base64url).
+ * Callers holding b64u strings decode first: `b64uDecodeBytes(b64uStr)`
+ * from `@oxpulse/crypto-primitives`.
+ *
+ * alicePub + bobPub are canonical-ordered internally via {@link isAliceRole}
+ * (lex-smaller pubkey first), matching {@link buildAuthTranscript}. This
+ * guarantees both parties produce identical sessionIds regardless of which
+ * side calls deriveSessionId(introducer, own, peer) — see ADR-013 / #217.
+ *
+ * @param introducerPub - Introducer long-term Ed25519 pubkey (32 bytes)
+ * @param alicePub      - Alice ephemeral pubkey (32 bytes) — auto role-ordered
+ * @param bobPub        - Bob ephemeral pubkey (32 bytes)   — auto role-ordered
+ */
+export declare function deriveSessionId(introducerPub: Uint8Array, alicePub: Uint8Array, bobPub: Uint8Array): string;
+/**
+ * Constant-time lexicographic compare of two Ed25519/X25519 pubkeys.
+ * Returns true if localPubkey < peerPubkey (Alice role).
+ * Returns false on equal (tiebreaker: peer is Alice, local is Bob).
+ */
+export declare function isAliceRole(localPubkey: Uint8Array, peerPubkey: Uint8Array): boolean;
+/**
+ * Derives the shared master key from an ephemeral X25519 DH + HKDF.
+ *
+ * ikm  = X25519(ownEphPriv, peerEphPub)  — wiped before return (#216)
+ * salt = utf8(LABEL_MASTER_KEY)
+ * info = [PROTOCOL_VERSION] || aliceEphPub || bobEphPub
+ * return HKDF-SHA256(salt, ikm, info, 32)
+ *
+ * aliceEphPub + bobEphPub are role-ordered so both parties use identical info.
+ * The caller is responsible for wiping the returned masterKey (via {@link wipe})
+ * once all MAC keys are derived and AEAD operations complete, and for wiping
+ * the ownEphPriv argument after this call returns.
+ */
+export declare function deriveMasterKey(ownEphPriv: Uint8Array, peerEphPub: Uint8Array, aliceEphPub: Uint8Array, bobEphPub: Uint8Array): Uint8Array;
+/**
+ * Derives alice and bob MAC keys from masterKey via HKDF-Expand-only.
+ *
+ * expand(masterKey, utf8(LABEL_ALICE_MAC_KEY), 32)
+ * expand(masterKey, utf8(LABEL_BOB_MAC_KEY),   32)
+ *
+ * Uses `expand` (HKDF-Expand) directly — masterKey is already a PRK.
+ */
+export declare function deriveMacKeys(masterKey: Uint8Array): {
+    alice: Uint8Array;
+    bob: Uint8Array;
+};
+/**
+ * Best-effort zeroize both MAC keys returned by {@link deriveMacKeys} (#216).
+ *
+ * Call when the handshake completes or aborts and the MAC keys are no longer
+ * needed. After this call, `keys.alice` and `keys.bob` are zeroed — further
+ * use will produce wrong results / throw, which is the intended fail-closed
+ * behaviour.
+ */
+export declare function wipeMacKeys(keys: {
+    alice: Uint8Array;
+    bob: Uint8Array;
+}): void;
+export interface TranscriptParty {
+    longTermPubkey: Uint8Array;
+    acceptedAt: number;
+    ephPub: Uint8Array;
+    transportProps: Record<string, unknown>;
+}
+/**
+ * Builds the canonical CBOR auth transcript.
+ *
+ * canonicalCBOR([
+ *   introducer.longTermPub,
+ *   [alice.longTermPub, alice.acceptedAt, alice.ephPub, alice.transportProps],
+ *   [bob.longTermPub,   bob.acceptedAt,   bob.ephPub,   bob.transportProps],
+ * ])
+ *
+ * Parties are canonically ordered: the party whose longTermPubkey is
+ * lexicographically smaller (isAliceRole) is always listed first.
+ * This ensures both sides produce identical CBOR bytes regardless of
+ * which side calls buildAuthTranscript(introducer, own, peer).
+ */
+export declare function buildAuthTranscript(introducerLongTermPub: Uint8Array, ownSide: TranscriptParty, peerSide: TranscriptParty): Uint8Array;
+/**
+ * Computes HMAC-SHA256(ownMacKey, utf8(LABEL_AUTH_MAC) || sessionId || transcript).
+ *
+ * sessionId is mixed in explicitly (ADR-013 / #218 nit #7) so the binding to
+ * the introducer's announced sessionId survives future transcript-shape
+ * changes. Previously the binding was only transitive (sessionId inputs are
+ * also transcript fields); explicit binding is more robust against refactor.
+ */
+export declare function computeAuthMac(ownMacKey: Uint8Array, sessionId: Uint8Array, transcript: Uint8Array): Uint8Array;
+/**
+ * Verifies the peer's auth MAC.
+ *
+ * Recomputes HMAC-SHA256(peerMacKey, utf8(LABEL_AUTH_MAC) || sessionId ||
+ * canonicalTranscript) and compares using constant-time equality.
+ *
+ * With canonical-ordering in buildAuthTranscript, both sides produce identical
+ * transcript bytes — the verifier passes its own locally-built transcript, which
+ * equals the sender's transcript exactly (the "swap" is identity by design).
+ */
+export declare function verifyAuthMac(peerMacKey: Uint8Array, sessionId: Uint8Array, canonicalTranscript: Uint8Array, receivedMac: Uint8Array): boolean;
+/**
+ * Computes the auth signature.
+ *
+ * nonce = HMAC-SHA256(ownMacKey, utf8(LABEL_AUTH_NONCE) || sessionId || transcript)
+ * return Ed25519-sign(ownLongTermPriv, utf8(LABEL_AUTH_SIGN) || nonce)
+ *
+ * sessionId is mixed into the nonce explicitly (ADR-013 / #218 nit #7) for
+ * the same reason as in {@link computeAuthMac} — explicit binding survives
+ * future transcript-shape changes.
+ */
+export declare function computeAuthSig(ownLongTermPriv: Uint8Array, ownMacKey: Uint8Array, sessionId: Uint8Array, transcript: Uint8Array): Uint8Array;
+/**
+ * Verifies the peer's auth signature.
+ *
+ * nonce = HMAC-SHA256(peerMacKey, utf8(LABEL_AUTH_NONCE) || sessionId ||
+ *                     canonicalTranscript)
+ * return Ed25519-verify(peerLongTermPub, utf8(LABEL_AUTH_SIGN) || nonce, receivedSig)
+ *
+ * With canonical-ordering in buildAuthTranscript, both sides produce identical
+ * transcript bytes — pass the locally-built canonical transcript here.
+ */
+export declare function verifyAuthSig(peerLongTermPub: Uint8Array, peerMacKey: Uint8Array, sessionId: Uint8Array, canonicalTranscript: Uint8Array, receivedSig: Uint8Array): boolean;
+/**
+ * Computes HMAC-SHA256(ownMacKey, utf8(LABEL_ACTIVATE_MAC) || sessionId).
+ */
+export declare function computeActivateMac(ownMacKey: Uint8Array, sessionId: Uint8Array): Uint8Array;
+/**
+ * Verifies activate MAC using constant-time comparison.
+ */
+export declare function verifyActivateMac(peerMacKey: Uint8Array, sessionId: Uint8Array, receivedMac: Uint8Array): boolean;
+export interface AeadEnvelope {
+    nonce: Uint8Array;
+    ciphertext: Uint8Array;
+}
+/** Permitted labels for AEAD operations — prevents cross-context misuse. */
+export type AeadLabel = typeof LABEL_AUTH_MAC | typeof LABEL_ACTIVATE_MAC;
+/**
+ * Encrypts plaintext with XChaCha20-Poly1305.
+ *
+ * nonce  = random(24B)
+ * AAD    = utf8(label) || sessionId
+ * cipher = XChaCha20-Poly1305(masterKey, nonce, AAD)
+ * return { nonce, ciphertext: cipher.encrypt(plaintext) }
+ */
+export declare function sealAead(masterKey: Uint8Array, label: AeadLabel, sessionId: Uint8Array, plaintext: Uint8Array): AeadEnvelope;
+/**
+ * Decrypts an AEAD envelope. Throws on authentication tag mismatch.
+ *
+ * AAD    = utf8(label) || sessionId  (must match seal-time values)
+ * cipher = XChaCha20-Poly1305(masterKey, env.nonce, AAD)
+ * return cipher.decrypt(env.ciphertext)
+ */
+export declare function openAead(masterKey: Uint8Array, label: AeadLabel, sessionId: Uint8Array, env: AeadEnvelope): Uint8Array;
+/**
+ * Serialize an AeadEnvelope to the wire-format base64url string
+ * `b64u(nonce || ciphertext)`.
+ */
+export declare function envelopeToWireB64u(env: AeadEnvelope): string;
+/**
+ * Parse a wire-format base64url string `b64u(nonce || ciphertext)` into an
+ * AeadEnvelope. Throws if the input is shorter than the 24-byte nonce.
+ *
+ * Note: uses `b64uDecodeBytes` from `@oxpulse/crypto-primitives` — for
+ * attacker-influenced inputs callers should pre-validate via the wire Zod
+ * schema, which constrains the charset to base64url.
+ */
+export declare function wireB64uToEnvelope(s: string): AeadEnvelope;
+//# sourceMappingURL=intro-crypto.d.ts.map

package/dist/intro-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intro-crypto.d.ts","sourceRoot":"","sources":["../src/intro-crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAwBH,eAAO,MAAM,gBAAgB,gCAAmC,CAAC;AACjE,eAAO,MAAM,gBAAgB,gCAAmC,CAAC;AACjE,eAAO,MAAM,mBAAmB,mCAAmC,CAAC;AACpE,eAAO,MAAM,iBAAiB,iCAAmC,CAAC;AAClE,eAAO,MAAM,cAAc,8BAAmC,CAAC;AAC/D,eAAO,MAAM,gBAAgB,gCAAmC,CAAC;AACjE,eAAO,MAAM,eAAe,+BAAmC,CAAC;AAChE,eAAO,MAAM,kBAAkB,kCAAmC,CAAC;AAEnE,eAAO,MAAM,gBAAgB,IAAO,CAAC;AA4BrC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,UAAU,GAAG,UAAU,CAG9C;AAWD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,UAAU,EACzB,QAAQ,EAAE,UAAU,EACpB,MAAM,EAAE,UAAU,GACjB,MAAM,CAeR;AAMD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAgBpF;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAG,UAAU,EACvB,UAAU,EAAG,UAAU,EACvB,WAAW,EAAE,UAAU,EACvB,SAAS,EAAI,UAAU,GACtB,UAAU,CAQZ;AAMD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,UAAU,GAAG;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,UAAU,CAAA;CAAE,CAI3F;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,UAAU,CAAA;CAAE,GAAG,IAAI,CAG9E;AAMD,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,UAAU,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,qBAAqB,EAAE,UAAU,EACjC,OAAO,EAAG,eAAe,EACzB,QAAQ,EAAE,eAAe,GACxB,UAAU,CAqBZ;AAMD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAG,UAAU,EACtB,SAAS,EAAG,UAAU,EACtB,UAAU,EAAE,UAAU,GACrB,UAAU,CAEZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAW,UAAU,EAC/B,SAAS,EAAY,UAAU,EAC/B,mBAAmB,EAAE,UAAU,EAC/B,WAAW,EAAU,UAAU,GAC9B,OAAO,CAGT;AAMD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,eAAe,EAAE,UAAU,EAC3B,SAAS,EAAQ,UAAU,EAC3B,SAAS,EAAQ,UAAU,EAC3B,UAAU,EAAO,UAAU,GAC1B,UAAU,CAIZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,eAAe,EAAM,UAAU,EAC/B,UAAU,EAAW,UAAU,EAC/B,SAAS,EAAY,UAAU,EAC/B,mBAAmB,EAAE,UAAU,EAC/B,WAAW,EAAU,UAAU,GAC9B,OAAO,CAQT;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,UAAU,CAE3F;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAG,UAAU,EACvB,SAAS,EAAI,UAAU,EACvB,WAAW,EAAE,UAAU,GACtB,OAAO,CAGT;AAMD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAO,UAAU,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG,OAAO,cAAc,GAAG,OAAO,kBAAkB,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,UAAU,EACrB,KAAK,EAAM,SAAS,EACpB,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,UAAU,GACpB,YAAY,CAMd;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,UAAU,EACrB,KAAK,EAAM,SAAS,EACpB,SAAS,EAAE,UAAU,EACrB,GAAG,EAAQ,YAAY,GACtB,UAAU,CAIZ;AAYD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,YAAY,CAM1D"}