@rine-network/core 0.4.4 → 0.5.0

package/dist/src/api-types.d.ts

@@ -9,6 +9,10 @@ export interface GroupRead {
     vote_duration_hours: number;
     member_count: number;
     created_at: string;
+    mls_enabled?: boolean;
+    mls_group_id?: string | null;
+    mls_pending?: boolean;
+    mls_cipher_suite?: number | null;
 }
 export interface GroupMemberRead {
     id: string;
@@ -86,6 +90,11 @@ export interface AgentKeysResponse {
         crv: string;
         x: string;
     };
+    pq_encryption_public_key?: {
+        kty: string;
+        alg: string;
+        x: string;
+    };
 }
 export interface BatchKeysResponse {
     keys: Record<string, {
@@ -99,6 +108,11 @@ export interface BatchKeysResponse {
             crv: string;
             x: string;
         };
+        pq_encryption_public_key?: {
+            kty: string;
+            alg: string;
+            x: string;
+        };
     }>;
 }
 export interface WebhookRead {

package/dist/src/crypto/hybrid.d.ts

@@ -0,0 +1,8 @@
+import type { KeyPair } from "./keys.js";
+declare const VERSION_HYBRID = 3;
+declare const MLKEM_CT_SIZE = 1088;
+export { VERSION_HYBRID, MLKEM_CT_SIZE };
+/** Generate an ML-KEM-768 key pair for post-quantum key encapsulation. */
+export declare function generatePqKeyPair(): KeyPair;
+export declare function sealHybrid(recipientX25519Pk: Uint8Array, recipientMlKemPk: Uint8Array, innerEnvelope: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
+export declare function openHybrid(recipientX25519Sk: Uint8Array, recipientMlKemSk: Uint8Array, encryptedPayload: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;

package/dist/src/crypto/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./hpke.js";
+export * from "./hybrid.js";
 export * from "./sign.js";
 export * from "./envelope.js";
 export * from "./keys.js";
@@ -6,3 +7,7 @@ export * from "./sender-keys.js";
 export * from "./sender-keys-helpers.js";
 export * from "./message.js";
 export * from "./ingest.js";
+export * from "./mls.js";
+export * from "./mls-init.js";
+export * from "./mls-api.js";
+export * from "./mls-state.js";

package/dist/src/crypto/keys.d.ts

@@ -4,6 +4,12 @@ export interface JWK {
     x: string;
     d?: string;
 }
+/** Public-key encoding for ML-KEM-768 (post-quantum). Not a standard OKP JWK. */
+export interface PqJWK {
+    kty: string;
+    alg: string;
+    x: string;
+}
 export interface KeyPair {
     privateKey: Uint8Array;
     publicKey: Uint8Array;
@@ -11,6 +17,7 @@ export interface KeyPair {
 export interface AgentKeys {
     signing: KeyPair;
     encryption: KeyPair;
+    pqEncryption?: KeyPair;
 }
 export declare function toBase64Url(bytes: Uint8Array): string;
 export declare function fromBase64Url(s: string): Uint8Array;
@@ -20,9 +27,12 @@ export declare function generateAgentKeys(): AgentKeys;
 export declare function signingPublicKeyToJWK(publicKey: Uint8Array): JWK;
 export declare function encryptionPublicKeyToJWK(publicKey: Uint8Array): JWK;
 export declare function jwkToPublicKey(jwk: JWK): Uint8Array;
+export declare function pqPublicKeyToJWK(publicKey: Uint8Array): PqJWK;
+export declare function jwkToPqPublicKey(jwk: PqJWK): Uint8Array;
 export declare function agentIdFromKid(kid: string): string;
 export declare function validatePathId(id: string, label: string): void;
 export declare function saveAgentKeys(configDir: string, agentId: string, keys: AgentKeys): void;
+export declare function savePqEncryptionKey(configDir: string, agentId: string, pqKeyPair: KeyPair): void;
 export declare function loadAgentKeys(configDir: string, agentId: string): AgentKeys;
 export declare function validateSigningKey(bytes: Uint8Array): void;
 export declare function validateEncryptionKey(bytes: Uint8Array): void;

package/dist/src/crypto/message.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from "../http.js";
-import { type AgentKeys } from "./keys.js";
+import { type AgentKeys, type PqJWK, signingPublicKeyToJWK } from "./keys.js";
 import { type SenderKeyState } from "./sender-keys.js";
 export interface EncryptResult {
     encrypted_payload: string;
@@ -13,19 +13,40 @@ export interface DecryptResult {
     verified: boolean;
     verificationStatus: VerificationStatus;
 }
-export declare function encryptMessage(configDir: string, senderAgentId: string, recipientEncryptionPk: Uint8Array, payload: unknown): Promise<EncryptResult>;
-export declare function fetchRecipientEncryptionKey(client: HttpClient, agentId: string): Promise<Uint8Array>;
+export declare function encryptMessage(configDir: string, senderAgentId: string, recipientEncryptionPk: Uint8Array, payload: unknown, recipientPqEncryptionPk?: Uint8Array): Promise<EncryptResult>;
+export interface RecipientKeys {
+    encryption: Uint8Array;
+    pqEncryption?: Uint8Array;
+}
+/** Fetch a recipient's encryption keys, including the optional PQ key for hybrid mode. */
+export declare function fetchRecipientKeys(client: HttpClient, agentId: string): Promise<RecipientKeys>;
 export declare function decryptMessage(configDir: string, recipientAgentId: string, encryptedPayloadB64: string, client: HttpClient): Promise<DecryptResult>;
 export declare function encryptGroupMessage(configDir: string, senderAgentId: string, groupId: string, senderKeyState: SenderKeyState, payload: unknown): Promise<{
     result: EncryptResult;
     updatedState: SenderKeyState;
 }>;
+/**
+ * Encrypt a payload for an MLS-active group.
+ *
+ * Mirrors {@link encryptGroupMessage} but uses MLS instead of sender keys.
+ * The signed inner envelope (kid + Ed25519 signature + plaintext) is the MLS
+ * application-message payload, so {@link decryptGroupMessage}'s 0x04 branch can
+ * run `decodeEnvelope` + `verifyEnvelopeSender` unchanged. The MLS ciphertext is
+ * prefixed with {@link VERSION_MLS} (0x04) and base64url-encoded to match the
+ * version-byte dispatch in `decryptGroupMessage`.
+ *
+ * State is keyed by the rine group UUID (`groupId`), the same identifier used by
+ * `decryptGroupMessage` and the MLS API routes — never the opaque `mls_group_id`
+ * latch or the MLS-internal group id.
+ */
+export declare function encryptMlsGroupMessage(configDir: string, senderAgentId: string, groupId: string, payload: unknown): Promise<EncryptResult>;
 export declare function decryptGroupMessage(configDir: string, recipientAgentId: string, groupId: string, encryptedPayloadB64: string, client: HttpClient): Promise<DecryptResult>;
 export declare function getAgentPublicKeys(configDir: string, agentId: string, agentKeys?: AgentKeys): {
-    signing_public_key: import("./keys.js").JWK;
+    signing_public_key: ReturnType<typeof signingPublicKeyToJWK>;
     encryption_public_key: {
         kty: string;
         crv: string;
         x: string;
     };
+    pq_encryption_public_key?: PqJWK;
 };

package/dist/src/crypto/mls-api.d.ts

@@ -0,0 +1,91 @@
+import type { HttpClient } from "../http.js";
+declare function toBase64(bytes: Uint8Array): string;
+declare function fromBase64(s: string): Uint8Array;
+export { toBase64 as mlsToBase64, fromBase64 as mlsFromBase64 };
+export interface MlsInitResponse {
+    mls_pending: boolean;
+    members: {
+        agent_id: string;
+        has_key_package: boolean;
+    }[];
+}
+export interface MlsCommitBody {
+    commit: string;
+    welcomes?: {
+        agent_id: string;
+        welcome: string;
+    }[];
+    group_info?: string;
+    cipher_suite?: number;
+    epoch?: number;
+}
+export interface MlsCommitResponse {
+    epoch: number | null;
+    delivered_to: number;
+    confirmed?: boolean;
+}
+export interface MlsAckResponse {
+    confirmed: boolean;
+    acks: number;
+    needed: number;
+}
+export interface MlsNackResponse {
+    quarantined: boolean;
+}
+export interface MlsHandshakeEntry {
+    id: string;
+    epoch: number | null;
+    blob: string;
+    created_at: string;
+}
+export interface MlsWelcomeEntry {
+    id: string;
+    group_id: string | null;
+    blob: string;
+    created_at: string;
+}
+export interface MlsProposalResponse {
+    id: string;
+    delivered_to: number;
+}
+export interface MlsGroupInfoResponse {
+    group_info: string | null;
+    epoch: number | null;
+}
+export declare function uploadKeyPackages(client: HttpClient, agentId: string, packages: string[]): Promise<{
+    stored: number;
+}>;
+export declare function claimKeyPackages(client: HttpClient, agentId: string, count?: number): Promise<{
+    packages: string[];
+    agent_id: string;
+}>;
+export declare function mlsInit(client: HttpClient, groupId: string, extraHeaders?: Record<string, string>): Promise<MlsInitResponse>;
+export declare function mlsCommit(client: HttpClient, groupId: string, body: MlsCommitBody, extraHeaders?: Record<string, string>): Promise<MlsCommitResponse>;
+/**
+ * ACK a handshake the local client processed cleanly (H4). Once MLS_ACK_QUORUM
+ * distinct clean ACKs land server-side, the tentative commit + its GroupInfo are
+ * confirmed and mls_confirmed_epoch advances. extraHeaders is threaded so a
+ * multi-agent client ACKs as the right acting agent (sibling /groups bug: do not
+ * drop extraHeaders here).
+ */
+export declare function mlsAck(client: HttpClient, groupId: string, body: {
+    object_id: string;
+}, extraHeaders?: Record<string, string>): Promise<MlsAckResponse>;
+/**
+ * NACK a handshake the local client could NOT process (H4). The server marks the
+ * delivery and lazily rolls the tentative commit back. A NACK is non-destructive:
+ * it only ever un-advances unconfirmed, never-served state. extraHeaders threaded.
+ */
+export declare function mlsNack(client: HttpClient, groupId: string, body: {
+    object_id: string;
+    epoch: number;
+    reason?: string;
+}, extraHeaders?: Record<string, string>): Promise<MlsNackResponse>;
+export declare function fetchHandshakes(client: HttpClient, groupId: string, sinceEpoch?: number, extraHeaders?: Record<string, string>): Promise<{
+    handshakes: MlsHandshakeEntry[];
+}>;
+export declare function fetchWelcomes(client: HttpClient, agentId: string): Promise<{
+    welcomes: MlsWelcomeEntry[];
+}>;
+export declare function fetchGroupInfo(client: HttpClient, groupId: string, extraHeaders?: Record<string, string>): Promise<MlsGroupInfoResponse>;
+export declare function submitProposal(client: HttpClient, groupId: string, proposal: string, extraHeaders?: Record<string, string>): Promise<MlsProposalResponse>;

package/dist/src/crypto/mls-init.d.ts

@@ -0,0 +1,6 @@
+import { type CiphersuiteImpl, type MlsContext } from "ts-mls";
+/** Lazily initializes and returns the MLS cipher suite singleton. */
+export declare function getMlsCipherSuite(): Promise<CiphersuiteImpl>;
+/** Lazily initializes and returns the MLS context singleton. */
+export declare function getMlsContext(): Promise<MlsContext>;
+export declare const MLS_CIPHER_SUITE_ID = 1;

package/dist/src/crypto/mls-state.d.ts

@@ -0,0 +1,29 @@
+export interface MlsEpochMetadata {
+    groupId: string;
+    epoch: number;
+    cipherSuite: number;
+}
+export declare function saveMlsState(configDir: string, agentId: string, groupId: string, stateBlob: Uint8Array, metadata: MlsEpochMetadata): void;
+export declare function loadMlsState(configDir: string, agentId: string, groupId: string): {
+    stateBlob: Uint8Array;
+    metadata: MlsEpochMetadata;
+} | null;
+export declare function deleteMlsState(configDir: string, agentId: string, groupId: string): void;
+export declare function cacheMlsSelfRead(configDir: string, agentId: string, groupId: string, encryptedPayload: string, envelope: Uint8Array): void;
+export declare function lookupMlsSelfRead(configDir: string, agentId: string, groupId: string, encryptedPayload: string): Uint8Array | null;
+export interface StoredKeyPackage {
+    ref: string;
+    publicBlob: Uint8Array;
+    privateBlob: Uint8Array;
+}
+export declare function savePrivateKeyPackages(configDir: string, agentId: string, packages: Array<{
+    ref: Uint8Array;
+    publicBlob: Uint8Array;
+    privateBlob: Uint8Array;
+}>): void;
+export declare function loadPrivateKeyPackage(configDir: string, agentId: string, ref: Uint8Array): {
+    publicBlob: Uint8Array;
+    privateBlob: Uint8Array;
+} | null;
+export declare function deletePrivateKeyPackage(configDir: string, agentId: string, ref: Uint8Array): void;
+export declare function listPrivateKeyPackages(configDir: string, agentId: string): StoredKeyPackage[];

package/dist/src/crypto/mls.d.ts

@@ -0,0 +1,63 @@
+export declare const VERSION_MLS = 4;
+export interface MlsGroupState {
+    groupId: string;
+    epoch: number;
+    cipherSuite: number;
+}
+export declare function generateMlsKeyPackage(signingKey: Uint8Array): Promise<{
+    publicBlob: Uint8Array;
+    privateBlob: Uint8Array;
+    keyPackageRef: Uint8Array;
+}>;
+export declare function createMlsGroup(signingKey: Uint8Array, _cipherSuite?: number): Promise<{
+    stateBlob: Uint8Array;
+    groupInfo: Uint8Array;
+    commitBlob: Uint8Array;
+    epoch: number;
+}>;
+export declare function addMemberToMlsGroup(stateBlob: Uint8Array, keyPackageBlob: Uint8Array): Promise<{
+    commitBlob: Uint8Array;
+    welcomeBlob: Uint8Array;
+    updatedState: Uint8Array;
+    groupInfo: Uint8Array;
+    epoch: number;
+}>;
+export declare function removeMemberFromMlsGroup(stateBlob: Uint8Array, leafIndex: number): Promise<{
+    commitBlob: Uint8Array;
+    updatedState: Uint8Array;
+    groupInfo: Uint8Array;
+    epoch: number;
+}>;
+export declare function processMlsWelcome(welcomeBlob: Uint8Array, keyPackageBlob: Uint8Array, privateKeyBlob: Uint8Array): Promise<{
+    stateBlob: Uint8Array;
+    groupId: string;
+    epoch: number;
+    cipherSuite: number;
+}>;
+export declare function processMlsCommit(stateBlob: Uint8Array, commitBlob: Uint8Array): Promise<{
+    updatedState: Uint8Array;
+    epoch: number;
+}>;
+/**
+ * Self-join an MLS group via an RFC 9420 external commit (no Welcome required).
+ * The joiner mints a fresh KeyPackage with its own Ed25519 signing key, derives
+ * a fresh init_secret against the published GroupInfo's external_pub, and emits
+ * a public External Commit that existing members process to advance the epoch.
+ * Returns the public commit (to broadcast), the joiner's new state, a fresh
+ * GroupInfo (so the NEXT external joiner has a current-epoch token), and the new
+ * epoch. `resync: false` — the joiner is a brand-new member, not in the tree.
+ */
+export declare function externalJoinMlsGroup(signingKey: Uint8Array, groupInfoBlob: Uint8Array): Promise<{
+    commitBlob: Uint8Array;
+    stateBlob: Uint8Array;
+    groupInfo: Uint8Array;
+    epoch: number;
+}>;
+export declare function encryptMlsAppMessage(stateBlob: Uint8Array, plaintext: Uint8Array): Promise<{
+    ciphertext: Uint8Array;
+    updatedState: Uint8Array;
+}>;
+export declare function decryptMlsAppMessage(stateBlob: Uint8Array, ciphertext: Uint8Array): Promise<{
+    plaintext: Uint8Array;
+    updatedState: Uint8Array;
+}>;

package/dist/src/errors.d.ts

@@ -2,6 +2,7 @@ export declare class RineApiError extends Error {
     readonly status: number;
     readonly detail: string;
     readonly raw?: unknown | undefined;
-    constructor(status: number, detail: string, raw?: unknown | undefined);
+    readonly code?: string | undefined;
+    constructor(status: number, detail: string, raw?: unknown | undefined, code?: string | undefined);
 }
 export declare function formatError(err: unknown): string;

package/dist/src/index.d.ts

@@ -8,4 +8,6 @@ export * from "./resolve-agent.js";
 export * from "./timelock.js";
 export * from "./sender-key-ops.js";
 export * from "./crypto/index.js";
+export * from "./mls-ops.js";
+export { externalJoinMlsGroup } from "./mls-ops.js";
 export { performRegistration, performAgentCreation, validateSlug } from "./onboard.js";

package/dist/src/mls-ops-join.d.ts

@@ -0,0 +1,24 @@
+import type { HttpClient } from "./http.js";
+/**
+ * Self-join an MLS-active group via an RFC 9420 external commit (Phase 6).
+ *
+ * Used for OPEN enrollment, where the rine server adds a joiner to the group
+ * with no member in the loop — so nobody mints a Welcome and the joiner is a
+ * rine member but not yet an MLS member. The joiner fetches the group's latest
+ * published GroupInfo, derives a fresh init_secret against its external_pub,
+ * and posts a public External Commit that existing members process (via the
+ * EXISTING syncMlsGroup path) to advance the epoch.
+ *
+ * State is keyed by the RINE group UUID (groupId) — the same key
+ * encrypt/decryptGroupMessage use — so the joiner can immediately send/receive.
+ *
+ * Epoch-conflict handling (research-guided, RFC 9420 §12.4.3.2 + RFC 9750):
+ * a GroupInfo is single-use per epoch. If a competing external join lands first,
+ * our GroupInfo is stale and our commit targets a stale epoch (members reject).
+ * We do a single discard-and-rebuild retry against a freshly-fetched GroupInfo;
+ * on a second failure we surface a clear, actionable terminal error rather than
+ * looping (an unbounded retry against an advancing epoch is a self-DoS).
+ */
+export declare function externalJoinMlsGroup(configDir: string, agentId: string, groupId: string, client: HttpClient, extraHeaders?: Record<string, string>): Promise<{
+    epoch: number;
+}>;

package/dist/src/mls-ops-sync.d.ts

@@ -0,0 +1,23 @@
+import type { HttpClient } from "./http.js";
+/**
+ * Fetch all pending MLS welcomes for an agent and process them, establishing
+ * local group state for each group the agent has been added to.
+ */
+export declare function processMlsWelcomes(configDir: string, agentId: string, client: HttpClient): Promise<{
+    processed: number;
+    groupIds: string[];
+}>;
+/**
+ * Remove a member from an MLS group by leaf index and post the remove commit.
+ */
+export declare function removeMlsGroupMember(configDir: string, agentId: string, groupId: string, leafIndex: number, client: HttpClient, extraHeaders?: Record<string, string>): Promise<{
+    epoch: number;
+}>;
+/**
+ * Sync local MLS group state by fetching and applying all commits posted
+ * since the current epoch.
+ */
+export declare function syncMlsGroup(configDir: string, agentId: string, groupId: string, client: HttpClient, extraHeaders?: Record<string, string>): Promise<{
+    epoch: number;
+    processed: number;
+}>;

package/dist/src/mls-ops.d.ts

@@ -0,0 +1,25 @@
+import type { HttpClient } from "./http.js";
+export { processMlsWelcomes, removeMlsGroupMember, syncMlsGroup } from "./mls-ops-sync.js";
+export { externalJoinMlsGroup } from "./mls-ops-join.js";
+/**
+ * Generate and upload MLS key packages for an agent, enabling other agents
+ * to add them to MLS groups.
+ */
+export declare function publishMlsKeyPackages(configDir: string, agentId: string, client: HttpClient, count?: number): Promise<{
+    stored: number;
+}>;
+/**
+ * Initialize an MLS group: create the group state, add all members who have
+ * uploaded key packages, and post the initial commit + welcomes to the server.
+ */
+export declare function initMlsGroup(configDir: string, agentId: string, groupId: string, client: HttpClient, extraHeaders?: Record<string, string>): Promise<{
+    epoch: number;
+    membersAdded: number;
+}>;
+/**
+ * Add a single member to an existing MLS group by claiming their key package
+ * and posting an add commit + welcome.
+ */
+export declare function addMlsGroupMember(configDir: string, agentId: string, groupId: string, memberAgentId: string, client: HttpClient, extraHeaders?: Record<string, string>): Promise<{
+    epoch: number;
+}>;

package/dist/src/types.d.ts

@@ -16,4 +16,6 @@ export interface ApiError {
         msg: string;
         type: string;
     }[];
+    /** Structured error code for typed errors, e.g. "epoch_conflict". */
+    error?: string;
 }

package/dist/test/crypto/hybrid.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/crypto/message-hybrid.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/crypto/mls.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/mls-external-join.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/mls-ops.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rine-network/core",
-	"version": "0.4.4",
+	"version": "0.5.0",
 	"description": "Core library for rine.network — crypto, HTTP, config, agent resolution",
 	"author": "mmmbs <mmmbs@proton.me>",
 	"license": "EUPL-1.2",
@@ -27,7 +27,9 @@
 		"@hpke/core": "^1.9.0",
 		"@hpke/dhkem-x25519": "^1.8.0",
 		"@noble/curves": "^2.0.1",
-		"@noble/hashes": "^2.0.1"
+		"@noble/hashes": "^2.0.1",
+		"@noble/post-quantum": "^0.6.1",
+		"ts-mls": "^2.0.0-rc.13"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^1.9.0",