@pamoja/session 0.1.15 → 0.1.16

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Ergonomic facade over the generated session binding.
+ *
+ * Two devices that already know each other's public keys can agree on a session
+ * key without ever sending it, and then exchange messages that are confidential,
+ * cannot be altered undetected, and cannot be replayed. That is the whole of
+ * what a small device usually needs from transport security, at a fraction of
+ * what a TLS stack costs it.
+ *
+ * The role is re-exported as a runtime {@link Role} object, because the
+ * generated enum is types-only.
+ *
+ * @packageDocumentation
+ */
+import type { Role as RoleName } from '@pamoja/native';
+import { AgreementKey as NativeAgreementKey, type SealedMessage } from '@pamoja/native';
+export { AgreementKey } from '@pamoja/native';
+export type { SealedMessage };
+/**
+ * Which side of a session a device is on.
+ *
+ * The two devices must choose opposite roles: the role decides the order the
+ * public keys are mixed in and which direction each side tags its messages
+ * with, so a session where both sides claim the same role opens nothing.
+ *
+ * Provided as a runtime object plus a matching string-union type.
+ */
+export declare const Role: {
+    /** The device that opens the session. */
+    readonly Initiator: RoleName;
+    /** The device that answers. */
+    readonly Responder: RoleName;
+};
+/** One of the {@link Role} choices. */
+export type Role = RoleName;
+/** A confidential, tamper-evident, replay-protected channel with one peer. */
+export declare class Session {
+    #private;
+    /**
+     * Establishes a session with a peer.
+     *
+     * @param local - This device's key-agreement secret.
+     * @param peerPublicKey - The peer's 32-byte public key, already authenticated
+     *   by pinning or by a signature.
+     * @param salt - A fresh per-session salt both sides share, exchanged in the
+     *   clear. Reusing one with the same pair of keys reuses the session key, so
+     *   it must change each session.
+     * @param role - Whether this device opens the session or answers.
+     */
+    constructor(local: NativeAgreementKey, peerPublicKey: Buffer, salt: Buffer, role: Role);
+    /**
+     * Seals a message for the peer.
+     *
+     * @param plaintext - The message to protect.
+     * @param aad - Data authenticated but not encrypted, so it stays readable on
+     *   the wire yet cannot be altered: a device identifier or a routing header
+     *   belongs here.
+     * @returns The ciphertext, with the counter and tag to send beside it.
+     */
+    seal(plaintext: Buffer, aad?: Buffer): SealedMessage;
+    /**
+     * Opens a message from the peer.
+     *
+     * @param sealed - The ciphertext with the counter and tag that arrived with
+     *   it.
+     * @param aad - The same associated data the sender authenticated.
+     * @returns The plaintext.
+     * @throws When the counter repeats or is older than the replay window still
+     *   tracks, and when the tag does not authenticate. Nothing readable is ever
+     *   returned from a message that failed either check.
+     */
+    open(sealed: SealedMessage, aad?: Buffer): Buffer;
+}
+/**
+ * Computes a keyed hash over a message.
+ *
+ * This is the primitive a host uses to authenticate a pairing exchange or a
+ * single command, where a whole session would be more than the job needs.
+ */
+export declare function hmacSha256(key: Buffer, message: Buffer): Buffer;
+/** Expands input keying material into `length` bytes bound to `info`. */
+export declare function hkdfSha256(salt: Buffer, ikm: Buffer, info: Buffer, length: number): Buffer;

package/dist/index.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Ergonomic facade over the generated session binding.
+ *
+ * Two devices that already know each other's public keys can agree on a session
+ * key without ever sending it, and then exchange messages that are confidential,
+ * cannot be altered undetected, and cannot be replayed. That is the whole of
+ * what a small device usually needs from transport security, at a fraction of
+ * what a TLS stack costs it.
+ *
+ * The role is re-exported as a runtime {@link Role} object, because the
+ * generated enum is types-only.
+ *
+ * @packageDocumentation
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Session_inner;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Session = exports.Role = exports.AgreementKey = void 0;
+exports.hmacSha256 = hmacSha256;
+exports.hkdfSha256 = hkdfSha256;
+const native_1 = require("@pamoja/native");
+var native_2 = require("@pamoja/native");
+Object.defineProperty(exports, "AgreementKey", { enumerable: true, get: function () { return native_2.AgreementKey; } });
+/**
+ * Which side of a session a device is on.
+ *
+ * The two devices must choose opposite roles: the role decides the order the
+ * public keys are mixed in and which direction each side tags its messages
+ * with, so a session where both sides claim the same role opens nothing.
+ *
+ * Provided as a runtime object plus a matching string-union type.
+ */
+exports.Role = {
+    /** The device that opens the session. */
+    Initiator: 'Initiator',
+    /** The device that answers. */
+    Responder: 'Responder',
+};
+/** A confidential, tamper-evident, replay-protected channel with one peer. */
+class Session {
+    /**
+     * Establishes a session with a peer.
+     *
+     * @param local - This device's key-agreement secret.
+     * @param peerPublicKey - The peer's 32-byte public key, already authenticated
+     *   by pinning or by a signature.
+     * @param salt - A fresh per-session salt both sides share, exchanged in the
+     *   clear. Reusing one with the same pair of keys reuses the session key, so
+     *   it must change each session.
+     * @param role - Whether this device opens the session or answers.
+     */
+    constructor(local, peerPublicKey, salt, role) {
+        _Session_inner.set(this, void 0);
+        __classPrivateFieldSet(this, _Session_inner, new native_1.Session(local, peerPublicKey, salt, role), "f");
+    }
+    /**
+     * Seals a message for the peer.
+     *
+     * @param plaintext - The message to protect.
+     * @param aad - Data authenticated but not encrypted, so it stays readable on
+     *   the wire yet cannot be altered: a device identifier or a routing header
+     *   belongs here.
+     * @returns The ciphertext, with the counter and tag to send beside it.
+     */
+    seal(plaintext, aad) {
+        return __classPrivateFieldGet(this, _Session_inner, "f").seal(plaintext, aad);
+    }
+    /**
+     * Opens a message from the peer.
+     *
+     * @param sealed - The ciphertext with the counter and tag that arrived with
+     *   it.
+     * @param aad - The same associated data the sender authenticated.
+     * @returns The plaintext.
+     * @throws When the counter repeats or is older than the replay window still
+     *   tracks, and when the tag does not authenticate. Nothing readable is ever
+     *   returned from a message that failed either check.
+     */
+    open(sealed, aad) {
+        return __classPrivateFieldGet(this, _Session_inner, "f").open(sealed, aad);
+    }
+}
+exports.Session = Session;
+_Session_inner = new WeakMap();
+/**
+ * Computes a keyed hash over a message.
+ *
+ * This is the primitive a host uses to authenticate a pairing exchange or a
+ * single command, where a whole session would be more than the job needs.
+ */
+function hmacSha256(key, message) {
+    return (0, native_1.hmacSha256Digest)(key, message);
+}
+/** Expands input keying material into `length` bytes bound to `info`. */
+function hkdfSha256(salt, ikm, info, length) {
+    return (0, native_1.hkdfSha256Expand)(salt, ikm, info, length);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pamoja/session",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "X25519 key agreement, HKDF, and ChaCha20-Poly1305 with an anti-replay window, with no TLS stack.",
   "license": "MIT",
   "publishConfig": {
@@ -34,6 +34,6 @@
     "node": ">= 16"
   },
   "dependencies": {
-    "@pamoja/native": "0.1.15"
+    "@pamoja/native": "0.1.16"
   }
 }