@animalabs/portal-client 0.1.0

package/src/emitter.ts

@@ -0,0 +1,21 @@
+/** Minimal typed event emitter (no `any`, no Node EventEmitter dependency). */
+export class TypedEmitter<Events extends Record<string, (...args: never[]) => void>> {
+  private listeners = new Map<keyof Events, Set<(...args: never[]) => void>>();
+
+  on<K extends keyof Events>(event: K, fn: Events[K]): () => void {
+    let set = this.listeners.get(event);
+    if (!set) this.listeners.set(event, (set = new Set()));
+    set.add(fn as (...args: never[]) => void);
+    return () => this.off(event, fn);
+  }
+
+  off<K extends keyof Events>(event: K, fn: Events[K]): void {
+    this.listeners.get(event)?.delete(fn as (...args: never[]) => void);
+  }
+
+  emit<K extends keyof Events>(event: K, ...args: Parameters<Events[K]>): void {
+    for (const fn of this.listeners.get(event) ?? []) {
+      (fn as (...a: Parameters<Events[K]>) => void)(...args);
+    }
+  }
+}

package/src/enroll.ts

@@ -0,0 +1,126 @@
+/**
+ * Self-enrollment helpers.
+ *
+ * A brand-new agent with no persona/token opens a short-lived WS connection,
+ * presents an invite (an admin-minted access-rights template) plus a desired
+ * name, and receives minted credentials. The credentials are then persisted and
+ * used by a normal PortalClient `identify` (which also gives transport resume).
+ *
+ * This is deliberately separate from PortalClient: the client stays a pure
+ * identify/resume transport, and enrollment is a one-shot bootstrap.
+ */
+import { WebSocket } from 'ws';
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { PORTAL_PROTOCOL_VERSION, isServerFrame } from '@animalabs/portal-protocol';
+
+export interface EnrollOptions {
+  url: string;
+  /** Invite code (access-rights template). */
+  invite: string;
+  /** Desired display name for the new persona. */
+  desiredName: string;
+  /** Optional avatar filename/URL. */
+  avatar?: string;
+  /** Timeout for the enroll handshake (default 15000ms). */
+  timeoutMs?: number;
+  /** Provide a WebSocket impl (tests). Defaults to ws. */
+  wsFactory?: (url: string) => WebSocket;
+}
+
+export interface PortalCredentials {
+  personaId: string;
+  token: string;
+}
+
+/** One-shot: open WS, register, return minted credentials, close. */
+export function enroll(opts: EnrollOptions): Promise<PortalCredentials> {
+  const ws = opts.wsFactory ? opts.wsFactory(opts.url) : new WebSocket(opts.url);
+  const timeoutMs = opts.timeoutMs ?? 15_000;
+  return new Promise<PortalCredentials>((resolve, reject) => {
+    let settled = false;
+    const done = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        ws.close();
+      } catch {
+        /* ignore */
+      }
+      fn();
+    };
+    const timer = setTimeout(
+      () => done(() => reject(new Error('enroll timed out'))),
+      timeoutMs,
+    );
+
+    ws.on('message', (data: Buffer | string) => {
+      let frame: unknown;
+      try {
+        frame = JSON.parse(data.toString());
+      } catch {
+        return;
+      }
+      if (!isServerFrame(frame)) return;
+      const f = frame as { op: string; d?: Record<string, unknown> };
+      if (f.op === 'hello') {
+        ws.send(
+          JSON.stringify({
+            op: 'register',
+            d: {
+              protocolVersion: PORTAL_PROTOCOL_VERSION,
+              invite: opts.invite,
+              desiredName: opts.desiredName,
+              ...(opts.avatar ? { avatar: opts.avatar } : {}),
+            },
+          }),
+        );
+      } else if (f.op === 'registered') {
+        const d = f.d as { personaId: string; token: string };
+        done(() => resolve({ personaId: d.personaId, token: d.token }));
+      } else if (f.op === 'invalid_session') {
+        const reason = (f.d as { reason?: string })?.reason ?? 'rejected';
+        done(() => reject(new Error(`enroll rejected: ${reason}`)));
+      }
+    });
+    ws.on('error', (err: Error) => done(() => reject(err)));
+    ws.on('close', () => done(() => reject(new Error('connection closed before register'))));
+  });
+}
+
+/**
+ * Load persisted credentials, or enroll once and persist them. Idempotent: the
+ * first run of a new agent enrolls and writes `credsPath`; every run after just
+ * reads it. Returns the credentials to hand to a PortalClient.
+ */
+export async function loadOrEnrollCreds(opts: {
+  url: string;
+  /** Where minted creds are cached (JSON: { personaId, token }). */
+  credsPath: string;
+  /** Required only when no creds exist yet. */
+  invite?: string;
+  desiredName?: string;
+  avatar?: string;
+  wsFactory?: (url: string) => WebSocket;
+}): Promise<PortalCredentials> {
+  if (existsSync(opts.credsPath)) {
+    const raw = JSON.parse(readFileSync(opts.credsPath, 'utf8')) as Partial<PortalCredentials>;
+    if (raw.personaId && raw.token) return { personaId: raw.personaId, token: raw.token };
+  }
+  if (!opts.invite || !opts.desiredName) {
+    throw new Error(
+      `no saved credentials at ${opts.credsPath} and no invite/desiredName to enroll with`,
+    );
+  }
+  const creds = await enroll({
+    url: opts.url,
+    invite: opts.invite,
+    desiredName: opts.desiredName,
+    avatar: opts.avatar,
+    wsFactory: opts.wsFactory,
+  });
+  mkdirSync(dirname(opts.credsPath), { recursive: true });
+  writeFileSync(opts.credsPath, JSON.stringify(creds, null, 2) + '\n', { mode: 0o600 });
+  return creds;
+}

package/src/files.ts

@@ -0,0 +1,18 @@
+import type { OutgoingFile } from '@animalabs/portal-protocol';
+
+/**
+ * Build an `OutgoingFile` from in-memory bytes (the portable way to attach a
+ * file — works from any client/host, no relay-side filesystem access).
+ */
+export function fileFromBytes(
+  name: string,
+  data: Buffer | Uint8Array,
+  opts?: { contentType?: string; description?: string },
+): OutgoingFile {
+  return {
+    name,
+    bytes: Buffer.from(data).toString('base64'),
+    ...(opts?.contentType ? { contentType: opts.contentType } : {}),
+    ...(opts?.description ? { description: opts.description } : {}),
+  };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @animalabs/portal-client
+ *
+ * General-purpose client for the portal relay: WS transport, client-side cache,
+ * typed RPC, and transport-level reconnect/resume. No agent semantics — that's
+ * portal-mcpl's job.
+ */
+export { PortalClient } from './client.js';
+export type { PortalClientOptions, PortalClientEvents } from './client.js';
+export { ClientCache } from './cache.js';
+export { TypedEmitter } from './emitter.js';
+export { enroll, loadOrEnrollCreds } from './enroll.js';
+export type { EnrollOptions, PortalCredentials } from './enroll.js';
+export { fileFromBytes } from './files.js';

package/test/enroll.test.ts

@@ -0,0 +1,87 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { WebSocketServer } from 'ws';
+import { mkdtempSync, existsSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { enroll, loadOrEnrollCreds } from '../src/enroll.js';
+
+const PORT = 8795;
+
+/** Minimal relay stand-in: sends `hello`, answers `register` with `registered`
+ *  (or `invalid_session` for invite "bad"). Counts how many registers it saw. */
+function fakeRelay(port: number) {
+  let registers = 0;
+  const wss = new WebSocketServer({ port, host: '127.0.0.1' });
+  wss.on('connection', (ws) => {
+    ws.send(JSON.stringify({ op: 'hello', d: { protocolVersion: 1, heartbeatIntervalMs: 30000 } }));
+    ws.on('message', (data) => {
+      const frame = JSON.parse(data.toString());
+      if (frame.op !== 'register') return;
+      registers++;
+      if (frame.d.invite === 'bad') {
+        ws.send(JSON.stringify({ op: 'invalid_session', d: { resumable: false, reason: 'invite unknown' } }));
+        return;
+      }
+      ws.send(
+        JSON.stringify({
+          op: 'registered',
+          d: {
+            personaId: `minted-${registers}`,
+            token: `tok-${registers}`,
+            persona: { id: `minted-${registers}`, displayName: frame.d.desiredName, avatarUrl: '' },
+          },
+        }),
+      );
+    });
+  });
+  return {
+    url: `ws://127.0.0.1:${port}`,
+    registers: () => registers,
+    close: () => new Promise<void>((r) => wss.close(() => r())),
+  };
+}
+
+test('enroll: returns minted creds; rejects bad invite', async () => {
+  const relay = fakeRelay(PORT);
+  try {
+    const creds = await enroll({ url: relay.url, invite: 'good', desiredName: 'Claude Code' });
+    assert.equal(creds.personaId, 'minted-1');
+    assert.equal(creds.token, 'tok-1');
+
+    await assert.rejects(
+      () => enroll({ url: relay.url, invite: 'bad', desiredName: 'x' }),
+      /invite unknown/,
+    );
+  } finally {
+    await relay.close();
+  }
+});
+
+test('loadOrEnrollCreds: enrolls once then reuses the cached file', async () => {
+  const relay = fakeRelay(PORT + 1);
+  const dir = mkdtempSync(join(tmpdir(), 'portal-creds-'));
+  const credsPath = join(dir, 'nested', 'creds.json');
+  try {
+    const a = await loadOrEnrollCreds({ url: relay.url, credsPath, invite: 'good', desiredName: 'cc' });
+    assert.equal(relay.registers(), 1);
+    assert.ok(existsSync(credsPath));
+
+    // second call: no new register, returns the same persisted creds
+    const b = await loadOrEnrollCreds({ url: relay.url, credsPath, invite: 'good', desiredName: 'cc' });
+    assert.equal(relay.registers(), 1);
+    assert.deepEqual(a, b);
+
+    const onDisk = JSON.parse(readFileSync(credsPath, 'utf8'));
+    assert.equal(onDisk.personaId, a.personaId);
+
+    // without saved creds and without an invite → error
+    await assert.rejects(
+      () => loadOrEnrollCreds({ url: relay.url, credsPath: join(dir, 'absent.json') }),
+      /no saved credentials/,
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+    await relay.close();
+  }
+});

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "composite": true
+  },
+  "include": ["src/**/*", "test/**/*"],
+  "exclude": ["node_modules", "dist"],
+  "references": [{ "path": "../portal-protocol" }]
+}