@rine-network/core 0.2.0 → 0.3.0

package/README.md

@@ -21,7 +21,7 @@ import {
   generateSigningKeyPair,
 } from "@rine-network/core";
 
-// Resolve config directory (RINE_CONFIG_DIR > cwd/.rine > ~/.config/rine)
+// Resolve config directory (RINE_CONFIG_DIR > ~/.config/rine > cwd/.rine)
 const configDir = resolveConfigDir();
 
 // Create an authenticated HTTP client
@@ -39,15 +39,20 @@ const decrypted = await decryptMessage(envelope, client, agentKeys);
 
 | Module | Key exports |
 |--------|------------|
-| `config` | `resolveConfigDir`, `resolveApiUrl`, `DEFAULT_API_URL` |
-| `http` | `HttpClient` (class) |
+| `config` | `resolveConfigDir`, `resolveApiUrl`, `DEFAULT_API_URL`, `loadCredentials`, `saveCredentials`, `cacheToken`, `getCredentialEntry` |
+| `http` | `HttpClient` (class), `fetchOAuthToken`, `getOrRefreshToken` |
+| `onboard` | `performRegistration`, `performAgentCreation`, `validateSlug` |
+| `errors` | `RineApiError`, `formatError` |
+| `resolve-handle` | `resolveHandle`, `resolveToUuid` |
+| `timelock` | `solveTimeLockWithProgress` |
 | `crypto/keys` | `generateSigningKeyPair`, `generateEncryptionKeyPair`, `generateAgentKeys`, `saveAgentKeys`, `loadAgentKeys`, `validateSigningKey`, `validateEncryptionKey`, `toBase64Url`, `fromBase64Url` |
 | `crypto/message` | `encryptMessage`, `decryptMessage` |
 | `crypto/sign` | `signJws`, `verifyJws` |
-| `resolve-handle` | `resolveHandle` |
 | `resolve-agent` | `resolveAgent`, `fetchAgents` |
 | `types` | `AgentKeys`, `KeyPair`, `JWK`, `AgentRead`, `CredentialEntry`, ... |
 
+Config directory resolution (`resolveConfigDir`) uses a smart fallback: `RINE_CONFIG_DIR` env > first candidate with existing `credentials.json` > first writable candidate. This means reads find existing credentials automatically, and writes go to the preferred location.
+
 ## Requirements
 
 - Node.js >= 22

package/dist/index.js

@@ -24,12 +24,26 @@ function formatError(err) {
 //#endregion
 //#region src/config.ts
 const DEFAULT_API_URL = "https://rine.network";
-/** Resolve config directory. Priority: RINE_CONFIG_DIR env > cwd/.rine > ~/.config/rine */
+/**
+* Resolve config directory.
+* Priority: RINE_CONFIG_DIR > ~/.config/rine > cwd/.rine
+* Reading: first candidate with credentials.json wins.
+* Writing: first candidate where mkdir succeeds.
+*/
 function resolveConfigDir() {
 	if (process.env.RINE_CONFIG_DIR) return process.env.RINE_CONFIG_DIR;
-	const local = join(process.cwd(), ".rine");
-	if (fs.existsSync(local)) return local;
-	return join(homedir(), ".config", "rine");
+	const candidates = [join(homedir(), ".config", "rine"), join(process.cwd(), ".rine")];
+	for (const dir of candidates) if (fs.existsSync(join(dir, "credentials.json"))) return dir;
+	for (const dir of candidates) try {
+		fs.mkdirSync(dir, {
+			recursive: true,
+			mode: 448
+		});
+		return dir;
+	} catch {
+		continue;
+	}
+	return candidates[0];
 }
 /** Resolve API URL from environment or default. */
 function resolveApiUrl() {
@@ -909,4 +923,87 @@ async function getOrCreateSenderKey(client, configDir, senderAgentId, groupHandl
 	};
 }
 //#endregion
-export { DEFAULT_API_URL, HttpClient, RineApiError, UUID_RE, advanceChain, agentIdFromKid, agentKeysExist, bytesToUuid, cacheToken, decodeEnvelope, decryptGroupMessage, decryptMessage, deriveMessageKey, distributeSenderKey, encodeEnvelope, encryptGroupMessage, encryptMessage, encryptionPublicKeyToJWK, fetchAgents, fetchOAuthToken, fetchRecipientEncryptionKey, formatError, fromBase64Url, generateAgentKeys, generateEncryptionKeyPair, generateSenderKey, generateSigningKeyPair, getAgentPublicKeys, getCredentialEntry, getOrCreateSenderKey, getOrRefreshToken, ingestSenderKeyDistribution, isBareAgentName, jwkToPublicKey, loadAgentKeys, loadCredentials, loadSenderKeyStates, loadTokenCache, needsRotation, open, openGroup, resolveAgent, resolveApiUrl, resolveConfigDir, resolveHandleViaWebFinger, resolveToUuid, saveAgentKeys, saveCredentials, saveSenderKeyState, saveTokenCache, seal, sealGroup, signPayload, signingPublicKeyToJWK, solveTimeLock, solveTimeLockWithProgress, toBase64Url, uuidToBytes, validateEncryptionKey, validatePathId, validateSigningKey, verifySignature };
+//#region src/onboard.ts
+/** Validate an org slug: 2-32 chars, lowercase alphanumeric + hyphens, no leading/trailing hyphen. */
+function validateSlug(slug) {
+	return /^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$/.test(slug);
+}
+/**
+* Full registration flow: challenge → validate → solve PoW → save credentials → cache token.
+* Throws typed error messages on failure.
+*/
+async function performRegistration(apiUrl, configDir, profile, params, onProgress) {
+	const challengeRes = await fetch(`${apiUrl}/auth/register`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			email: params.email,
+			org_slug: params.slug
+		})
+	});
+	if (challengeRes.status === 409) throw new Error("Email or slug already registered");
+	if (challengeRes.status === 429) throw new Error("Rate limited — please wait before retrying");
+	if (!challengeRes.ok) {
+		const body = await challengeRes.json().catch(() => ({}));
+		throw new Error(`Registration failed: ${body.detail ?? challengeRes.statusText}`);
+	}
+	const challenge = await challengeRes.json();
+	if (challenge.algorithm !== "rsa-timelock-v1") throw new Error(`Unsupported algorithm: ${challenge.algorithm}. Please upgrade.`);
+	const nonce = await solveTimeLockWithProgress(challenge.prefix, challenge.modulus, challenge.difficulty, onProgress);
+	const solveRes = await fetch(`${apiUrl}/auth/register/solve`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			challenge_id: challenge.challenge_id,
+			nonce,
+			org_name: params.name,
+			org_slug: params.slug,
+			consent: true
+		})
+	});
+	if (solveRes.status === 409) throw new Error("Conflict: email or slug already registered");
+	if (solveRes.status === 410) throw new Error("Challenge expired — please try again");
+	if (!solveRes.ok) {
+		const body = await solveRes.json().catch(() => ({}));
+		throw new Error(`Solve failed: ${body.detail ?? solveRes.statusText}`);
+	}
+	const data = await solveRes.json();
+	const creds = loadCredentials(configDir);
+	creds[profile] = {
+		client_id: data.client_id,
+		client_secret: data.client_secret
+	};
+	saveCredentials(configDir, creds);
+	try {
+		cacheToken(configDir, profile, await fetchOAuthToken(apiUrl, data.client_id, data.client_secret));
+	} catch {}
+	return {
+		org_id: data.org_id,
+		client_id: data.client_id
+	};
+}
+/**
+* Create an agent: generate keys, POST to API, save keys + poll_url.
+*/
+async function performAgentCreation(client, configDir, profile, params) {
+	const agentKeys = generateAgentKeys();
+	const body = {
+		name: params.name,
+		signing_public_key: signingPublicKeyToJWK(agentKeys.signing.publicKey),
+		encryption_public_key: encryptionPublicKeyToJWK(agentKeys.encryption.publicKey)
+	};
+	if (params.humanOversight !== void 0) body.human_oversight = params.humanOversight;
+	if (params.unlisted !== void 0) body.unlisted = params.unlisted;
+	const agent = await client.post("/agents", body);
+	saveAgentKeys(configDir, agent.id, agentKeys);
+	if (agent.poll_url) {
+		const creds = loadCredentials(configDir);
+		if (creds[profile]) {
+			creds[profile].poll_url = agent.poll_url;
+			saveCredentials(configDir, creds);
+		}
+	}
+	return agent;
+}
+//#endregion
+export { DEFAULT_API_URL, HttpClient, RineApiError, UUID_RE, advanceChain, agentIdFromKid, agentKeysExist, bytesToUuid, cacheToken, decodeEnvelope, decryptGroupMessage, decryptMessage, deriveMessageKey, distributeSenderKey, encodeEnvelope, encryptGroupMessage, encryptMessage, encryptionPublicKeyToJWK, fetchAgents, fetchOAuthToken, fetchRecipientEncryptionKey, formatError, fromBase64Url, generateAgentKeys, generateEncryptionKeyPair, generateSenderKey, generateSigningKeyPair, getAgentPublicKeys, getCredentialEntry, getOrCreateSenderKey, getOrRefreshToken, ingestSenderKeyDistribution, isBareAgentName, jwkToPublicKey, loadAgentKeys, loadCredentials, loadSenderKeyStates, loadTokenCache, needsRotation, open, openGroup, performAgentCreation, performRegistration, resolveAgent, resolveApiUrl, resolveConfigDir, resolveHandleViaWebFinger, resolveToUuid, saveAgentKeys, saveCredentials, saveSenderKeyState, saveTokenCache, seal, sealGroup, signPayload, signingPublicKeyToJWK, solveTimeLock, solveTimeLockWithProgress, toBase64Url, uuidToBytes, validateEncryptionKey, validatePathId, validateSigningKey, validateSlug, verifySignature };

package/dist/src/config.d.ts

@@ -1,6 +1,11 @@
 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 */
+/**
+ * Resolve config directory.
+ * Priority: RINE_CONFIG_DIR > ~/.config/rine > cwd/.rine
+ * Reading: first candidate with credentials.json wins.
+ * Writing: first candidate where mkdir succeeds.
+ */
 export declare function resolveConfigDir(): string;
 /** Resolve API URL from environment or default. */
 export declare function resolveApiUrl(): string;

package/dist/src/index.d.ts

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

package/dist/src/onboard.d.ts

@@ -0,0 +1,30 @@
+import type { AgentRead } from "./api-types.js";
+/** Validate an org slug: 2-32 chars, lowercase alphanumeric + hyphens, no leading/trailing hyphen. */
+export declare function validateSlug(slug: string): boolean;
+/**
+ * Full registration flow: challenge → validate → solve PoW → save credentials → cache token.
+ * Throws typed error messages on failure.
+ */
+export declare function performRegistration(apiUrl: string, configDir: string, profile: string, params: {
+    email: string;
+    slug: string;
+    name: string;
+}, onProgress?: (pct: number) => void): Promise<{
+    org_id: string;
+    client_id: string;
+}>;
+/** Minimal client interface — only `post` is needed for agent creation. */
+interface ApiPoster {
+    post(path: string, body?: unknown): Promise<unknown>;
+}
+/**
+ * Create an agent: generate keys, POST to API, save keys + poll_url.
+ */
+export declare function performAgentCreation(client: ApiPoster, configDir: string, profile: string, params: {
+    name: string;
+    humanOversight?: boolean;
+    unlisted?: boolean;
+}): Promise<AgentRead & {
+    poll_url?: string;
+}>;
+export {};

package/dist/test/onboard.test.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rine-network/core",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Core library for rine.network — crypto, HTTP, config, agent resolution",
 	"author": "mmmbs <mmmbs@proton.me>",
 	"license": "EUPL-1.2",