@rine-network/core 0.1.0

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

@@ -0,0 +1,127 @@
+export interface GroupRead {
+    id: string;
+    name: string;
+    handle: string;
+    description: string | null;
+    enrollment_policy: string;
+    visibility: string;
+    isolated: boolean;
+    vote_duration_hours: number;
+    member_count: number;
+    created_at: string;
+}
+export interface GroupMemberRead {
+    id: string;
+    group_id: string;
+    agent_id: string;
+    role: string;
+    joined_at: string;
+    agent_handle?: string;
+}
+export interface JoinRequestRead {
+    id: string;
+    group_id: string;
+    agent_id: string;
+    invited_by?: string;
+    message?: string;
+    status: string;
+    expires_at?: string;
+    created_at: string;
+    resolved_at?: string;
+    your_vote?: string;
+}
+export interface AgentRead {
+    id: string;
+    name: string;
+    handle: string;
+    human_oversight: boolean;
+    incoming_policy: string;
+    outgoing_policy: string;
+    created_at: string;
+    revoked_at?: string | null;
+    unlisted?: boolean;
+    verification_words?: string;
+    warnings?: string[];
+}
+export interface ListResponse<T> {
+    items: T[];
+    total: number;
+}
+export interface PaginatedResponse<T> extends ListResponse<T> {
+    next_cursor?: string;
+    prev_cursor?: string;
+}
+export interface MessageRead {
+    id: string;
+    conversation_id: string;
+    sender_handle?: string;
+    from_agent_id?: string;
+    recipient_handle?: string;
+    to_agent_id?: string;
+    type: string;
+    encrypted_payload: string;
+    encryption_version: string;
+    sender_signing_kid?: string;
+    content_type?: string;
+    created_at: string;
+    group_id?: string;
+    group_handle?: string;
+}
+export interface AgentKeysResponse {
+    agent_id: string;
+    signing_public_key: {
+        kty: string;
+        crv: string;
+        x: string;
+    };
+    encryption_public_key: {
+        kty: string;
+        crv: string;
+        x: string;
+    };
+}
+export interface BatchKeysResponse {
+    keys: Record<string, {
+        signing_public_key: {
+            kty: string;
+            crv: string;
+            x: string;
+        };
+        encryption_public_key: {
+            kty: string;
+            crv: string;
+            x: string;
+        };
+    }>;
+}
+export interface WebhookRead {
+    id: string;
+    agent_id: string;
+    url: string;
+    secret?: string;
+    active: boolean;
+    created_at: string;
+}
+export interface WebhookDeliveryRead {
+    id: string;
+    message_id: string;
+    status: string;
+    attempts: number;
+    last_error?: string;
+    created_at: string;
+}
+export interface VoteResponse {
+    request_id: string;
+    your_vote: string;
+    status: string;
+}
+export interface OrgRead {
+    id: string;
+    name: string;
+    slug: string;
+    contact_email?: string;
+    country_code?: string;
+    trust_tier: number;
+    agent_count: number;
+    created_at: string;
+}

package/dist/src/config.d.ts

@@ -0,0 +1,20 @@
+import type { CredentialEntry, Credentials, TokenCache } from "./types.js";
+export declare const DEFAULT_API_URL = "https://rine.network";
+/** Resolve config directory. Priority: RINE_CONFIG_DIR env > cwd/.rine > ~/.config/rine */
+export declare function resolveConfigDir(): string;
+/** Resolve API URL from environment or default. */
+export declare function resolveApiUrl(): string;
+export declare function loadCredentials(configDir: string): Credentials;
+export declare function saveCredentials(configDir: string, creds: Credentials): void;
+export declare function loadTokenCache(configDir: string): TokenCache;
+export declare function saveTokenCache(configDir: string, cache: TokenCache): void;
+export declare function cacheToken(configDir: string, profile: string, token: {
+    access_token: string;
+    expires_in: number;
+}): void;
+/**
+ * Resolves credentials for a profile. Priority:
+ * 1. RINE_CLIENT_ID + RINE_CLIENT_SECRET env vars (both required)
+ * 2. credentials.json for the given profile
+ */
+export declare function getCredentialEntry(configDir: string, profile?: string): CredentialEntry | undefined;

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

@@ -0,0 +1,7 @@
+export interface InnerEnvelope {
+    kid: string;
+    signature: Uint8Array;
+    payload: Uint8Array;
+}
+export declare function encodeEnvelope(kid: string, signature: Uint8Array, payload: Uint8Array): Uint8Array;
+export declare function decodeEnvelope(data: Uint8Array): InnerEnvelope;

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

@@ -0,0 +1,2 @@
+export declare function seal(recipientPublicKey: Uint8Array, innerEnvelope: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
+export declare function open(recipientPrivateKey: Uint8Array, encryptedPayload: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;

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

@@ -0,0 +1,8 @@
+export * from "./hpke.js";
+export * from "./sign.js";
+export * from "./envelope.js";
+export * from "./keys.js";
+export * from "./sender-keys.js";
+export * from "./sender-keys-helpers.js";
+export * from "./message.js";
+export * from "./ingest.js";

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

@@ -0,0 +1,9 @@
+import type { DecryptResult } from "./message.js";
+/**
+ * Auto-ingest a sender key distribution from a decrypted message.
+ * Only ingests if the message is a `rine.v1.sender_key_distribution`,
+ * the signature was verified, and the key ID is not already known.
+ *
+ * Returns true if a new key was ingested.
+ */
+export declare function ingestSenderKeyDistribution(configDir: string, agentId: string, messageType: string, result: DecryptResult): boolean;

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

@@ -0,0 +1,27 @@
+export interface JWK {
+    kty: string;
+    crv: string;
+    x: string;
+    d?: string;
+}
+export interface KeyPair {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+}
+export interface AgentKeys {
+    signing: KeyPair;
+    encryption: KeyPair;
+}
+export declare function toBase64Url(bytes: Uint8Array): string;
+export declare function fromBase64Url(s: string): Uint8Array;
+export declare function generateSigningKeyPair(): KeyPair;
+export declare function generateEncryptionKeyPair(): KeyPair;
+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 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 loadAgentKeys(configDir: string, agentId: string): AgentKeys;
+export declare function agentKeysExist(configDir: string, agentId: string): boolean;

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

@@ -0,0 +1,31 @@
+import type { HttpClient } from "../http.js";
+import { type AgentKeys } from "./keys.js";
+import { type SenderKeyState } from "./sender-keys.js";
+export interface EncryptResult {
+    encrypted_payload: string;
+    encryption_version: string;
+    sender_signing_kid: string;
+}
+export type VerificationStatus = "verified" | "invalid" | "unverifiable";
+export interface DecryptResult {
+    plaintext: string;
+    senderKid: string;
+    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 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;
+}>;
+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;
+    encryption_public_key: {
+        kty: string;
+        crv: string;
+        x: string;
+    };
+};

package/dist/src/crypto/sender-keys-helpers.d.ts

@@ -0,0 +1,5 @@
+import type { SenderKeyState } from "./sender-keys.js";
+export declare function uuidToBytes(uuid: string): Uint8Array;
+export declare function bytesToUuid(bytes: Uint8Array): string;
+export declare function saveSenderKeyState(configDir: string, agentId: string, groupId: string, states: SenderKeyState[]): void;
+export declare function loadSenderKeyStates(configDir: string, agentId: string, groupId: string): SenderKeyState[];

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

@@ -0,0 +1,30 @@
+export interface SenderKeyState {
+    senderKeyId: string;
+    groupId: string;
+    senderAgentId: string;
+    chainKey: Uint8Array;
+    messageIndex: number;
+    skippedKeys?: Record<number, string>;
+    distributedTo?: string[];
+    createdAt?: number;
+}
+export declare function needsRotation(state: SenderKeyState): boolean;
+export declare function generateSenderKey(groupId: string, senderAgentId: string): SenderKeyState;
+export declare function deriveMessageKey(chainKey: Uint8Array): {
+    messageKey: Uint8Array;
+    nextChainKey: Uint8Array;
+};
+export declare function advanceChain(state: SenderKeyState, targetIndex: number): {
+    updatedState: SenderKeyState;
+    skippedKeys: Map<number, Uint8Array>;
+};
+export declare function sealGroup(senderSigningPrivateKey: Uint8Array, senderSigningKid: string, state: SenderKeyState, plaintext: Uint8Array): Promise<{
+    encryptedPayload: Uint8Array;
+    updatedState: SenderKeyState;
+}>;
+export declare function openGroup(senderKeyStates: Map<string, SenderKeyState>, encryptedPayload: Uint8Array): Promise<{
+    innerEnvelope: Uint8Array;
+    senderKeyId: string;
+    messageIndex: number;
+    updatedState: SenderKeyState;
+}>;

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

@@ -0,0 +1,2 @@
+export declare function signPayload(signingPrivateKey: Uint8Array, plaintext: Uint8Array): Uint8Array;
+export declare function verifySignature(signingPublicKey: Uint8Array, plaintext: Uint8Array, signature: Uint8Array): boolean;

package/dist/src/errors.d.ts

@@ -0,0 +1,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);
+}
+export declare function formatError(err: unknown): string;

package/dist/src/http.d.ts

@@ -0,0 +1,42 @@
+import type { CredentialEntry } from "./types.js";
+export type TokenFn = (force?: boolean) => Promise<string>;
+export interface HttpClientOptions {
+    tokenFn: TokenFn;
+    apiUrl: string;
+    /** Whether 401 auto-retry is possible (requires client credentials). */
+    canRefresh?: boolean;
+    /** Headers injected on every request (e.g. X-Rine-Agent). */
+    defaultHeaders?: Record<string, string>;
+}
+export declare class HttpClient {
+    private readonly baseUrl;
+    private readonly tokenFn;
+    private readonly canRefresh;
+    private readonly defaultHeaders;
+    constructor(opts: HttpClientOptions);
+    private request;
+    get(path: string, params?: Record<string, string | number | boolean>, extraHeaders?: Record<string, string>): Promise<unknown>;
+    post(path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<unknown>;
+    put(path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<unknown>;
+    patch(path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<unknown>;
+    delete(path: string, extraHeaders?: Record<string, string>): Promise<unknown>;
+    /** Unauthenticated GET for public endpoints (e.g. /directory/*). */
+    static publicGet(apiUrl: string, path: string, params?: URLSearchParams): Promise<unknown>;
+}
+/**
+ * Fetches an OAuth token from POST /oauth/token.
+ */
+export declare function fetchOAuthToken(apiUrl: string, clientId: string, clientSecret: string): Promise<{
+    access_token: string;
+    expires_in: number;
+}>;
+/**
+ * Resolves a valid access token. Priority:
+ * 1. opts.envToken — used directly, no cache/refresh
+ * 2. Token cache — returned if not expired (60s margin)
+ * 3. POST /oauth/token — fetches fresh token and caches it
+ */
+export declare function getOrRefreshToken(configDir: string, apiUrl: string, entry: CredentialEntry | undefined, profileName: string, opts?: {
+    force?: boolean;
+    envToken?: string;
+}): Promise<string>;

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./errors.js";
+export * from "./types.js";
+export * from "./api-types.js";
+export * from "./config.js";
+export * from "./http.js";
+export * from "./resolve-handle.js";
+export * from "./resolve-agent.js";
+export * from "./timelock.js";
+export * from "./sender-key-ops.js";
+export * from "./crypto/index.js";

package/dist/src/resolve-agent.d.ts

@@ -0,0 +1,17 @@
+import type { AgentRead } from "./api-types.js";
+import type { HttpClient } from "./http.js";
+/**
+ * Resolve a value that may be a UUID or a handle (containing @) to a UUID.
+ * Handles are resolved via WebFinger.
+ */
+export declare function resolveToUuid(apiUrl: string, value: string): Promise<string>;
+/** Check if a value is a bare agent name (not a UUID, not a handle). */
+export declare function isBareAgentName(value: string): boolean;
+/** Fetch the org's agent list. Pure function — no caching. */
+export declare function fetchAgents(client: HttpClient): Promise<AgentRead[]>;
+/**
+ * Resolve which agent ID to use.
+ * Priority: explicit flag > asFlag > auto-resolve (single-agent shortcut).
+ * Accepts UUIDs, handles, or bare names.
+ */
+export declare function resolveAgent(apiUrl: string, agents: AgentRead[], explicit?: string, asFlag?: string): Promise<string>;

package/dist/src/resolve-handle.d.ts

@@ -0,0 +1,10 @@
+declare const UUID_RE: RegExp;
+/**
+ * Resolves a handle (e.g. "agent@org.rine.network") to a UUID
+ * via WebFinger (RFC 7033).
+ *
+ * Returns the UUID string on success, or the original input unchanged
+ * on failure (caller validates UUID format and reports the error).
+ */
+export declare function resolveHandleViaWebFinger(apiUrl: string, handle: string): Promise<string>;
+export { UUID_RE };

package/dist/src/sender-key-ops.d.ts

@@ -0,0 +1,19 @@
+import type { SenderKeyState } from "./crypto/sender-keys.js";
+import type { HttpClient } from "./http.js";
+export interface DistributeResult {
+    succeeded: string[];
+    failed: string[];
+}
+/**
+ * Distribute a sender key to group members via encrypted DMs.
+ * Returns which recipients succeeded/failed.
+ */
+export declare function distributeSenderKey(client: HttpClient, configDir: string, senderAgentId: string, state: SenderKeyState, groupId: string, recipientIds: string[], extraHeaders?: Record<string, string>): Promise<DistributeResult>;
+/**
+ * Get or create a sender key for a group, distributing it to members as needed.
+ * Handles rotation on member removal, periodic rotation, and new key generation.
+ */
+export declare function getOrCreateSenderKey(client: HttpClient, configDir: string, senderAgentId: string, groupHandle: string, extraHeaders?: Record<string, string>): Promise<{
+    state: SenderKeyState;
+    groupId: string;
+}>;

package/dist/src/timelock.d.ts

@@ -0,0 +1,2 @@
+export declare function solveTimeLock(baseHex: string, modulusHex: string, T: number): string;
+export declare function solveTimeLockWithProgress(baseHex: string, modulusHex: string, T: number, onProgress?: (pct: number) => void): Promise<string>;

package/dist/src/types.d.ts

@@ -0,0 +1,19 @@
+/** Flat credential store: { "profileName": { client_id, client_secret } } */
+export type Credentials = Record<string, CredentialEntry>;
+export interface CredentialEntry {
+    client_id: string;
+    client_secret: string;
+    poll_url?: string;
+}
+export interface CachedToken {
+    access_token: string;
+    expires_at: number;
+}
+/** Token cache: { "profileName": { access_token, expires_at } } */
+export type TokenCache = Record<string, CachedToken>;
+export interface ApiError {
+    detail: string | {
+        msg: string;
+        type: string;
+    }[];
+}

package/dist/test/config.test.d.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/test/crypto/sender-keys.test.d.ts

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

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

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

package/dist/test/errors.test.d.ts

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

package/dist/test/http.test.d.ts

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

package/dist/test/resolve-agent.test.d.ts

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

package/dist/test/resolve-handle.test.d.ts

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

package/dist/test/sender-key-ops.test.d.ts

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

package/dist/test/timelock.test.d.ts

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

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@rine-network/core",
+	"version": "0.1.0",
+	"description": "Core library for rine.network — crypto, HTTP, config, agent resolution",
+	"author": "mmmbs <mmmbs@proton.me>",
+	"license": "EUPL-1.2",
+	"type": "module",
+	"engines": {
+		"node": ">=22"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/src/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist/"
+	],
+	"scripts": {
+		"build": "tsdown src/index.ts --format esm --outDir dist --clean && tsc --declaration --emitDeclarationOnly --outDir dist",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@hpke/core": "^1.9.0",
+		"@hpke/dhkem-x25519": "^1.8.0",
+		"@noble/curves": "^2.0.1",
+		"@noble/hashes": "^2.0.1"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.0",
+		"@types/node": "^22.0.0",
+		"tsdown": "^0.12.0",
+		"typescript": "^5.8.0",
+		"vitest": "^3.0.0"
+	},
+	"homepage": "https://rine.network",
+	"repository": {
+		"type": "git",
+		"url": "https://codeberg.org/rine/rine-core"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"keywords": [
+		"rine",
+		"crypto",
+		"e2ee",
+		"hpke",
+		"sender-keys",
+		"ai-agents"
+	]
+}