@zooid/server 0.0.1

package/src/lib/jwt.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import { createToken, verifyToken } from './jwt';
+
+const TEST_SECRET = 'test-secret-key-for-jwt-testing-purposes';
+
+describe('JWT', () => {
+  describe('createToken', () => {
+    it('creates a valid admin token', async () => {
+      const token = await createToken({ scope: 'admin' }, TEST_SECRET);
+      expect(token).toBeTruthy();
+      expect(typeof token).toBe('string');
+      expect(token.split('.')).toHaveLength(3);
+    });
+
+    it('creates a publish token scoped to a channel', async () => {
+      const token = await createToken(
+        { scope: 'publish', channel: 'test-channel' },
+        TEST_SECRET,
+      );
+      const payload = await verifyToken(token, TEST_SECRET);
+      expect(payload.scope).toBe('publish');
+      expect(payload.channel).toBe('test-channel');
+    });
+
+    it('creates a subscribe token scoped to a channel', async () => {
+      const token = await createToken(
+        { scope: 'subscribe', channel: 'test-channel' },
+        TEST_SECRET,
+      );
+      const payload = await verifyToken(token, TEST_SECRET);
+      expect(payload.scope).toBe('subscribe');
+      expect(payload.channel).toBe('test-channel');
+    });
+
+    it('includes sub claim when provided', async () => {
+      const token = await createToken(
+        { scope: 'publish', channel: 'test-channel', sub: 'bot-1' },
+        TEST_SECRET,
+      );
+      const payload = await verifyToken(token, TEST_SECRET);
+      expect(payload.sub).toBe('bot-1');
+    });
+
+    it('includes iat claim', async () => {
+      const token = await createToken({ scope: 'admin' }, TEST_SECRET);
+      const payload = await verifyToken(token, TEST_SECRET);
+      expect(payload.iat).toBeTypeOf('number');
+    });
+
+    it('includes exp claim when expiry is provided', async () => {
+      const token = await createToken({ scope: 'admin' }, TEST_SECRET, {
+        expiresIn: 3600,
+      });
+      const payload = await verifyToken(token, TEST_SECRET);
+      expect(payload.exp).toBeTypeOf('number');
+      expect(payload.exp! - payload.iat).toBe(3600);
+    });
+
+    it('omits exp claim when no expiry', async () => {
+      const token = await createToken({ scope: 'admin' }, TEST_SECRET);
+      const payload = await verifyToken(token, TEST_SECRET);
+      expect(payload.exp).toBeUndefined();
+    });
+  });
+
+  describe('verifyToken', () => {
+    it('verifies a valid token', async () => {
+      const token = await createToken({ scope: 'admin' }, TEST_SECRET);
+      const payload = await verifyToken(token, TEST_SECRET);
+      expect(payload.scope).toBe('admin');
+    });
+
+    it('rejects a token signed with a different secret', async () => {
+      const token = await createToken({ scope: 'admin' }, TEST_SECRET);
+      await expect(verifyToken(token, 'wrong-secret')).rejects.toThrow();
+    });
+
+    it('rejects a malformed token', async () => {
+      await expect(verifyToken('not-a-jwt', TEST_SECRET)).rejects.toThrow();
+    });
+
+    it('rejects an expired token', async () => {
+      const token = await createToken({ scope: 'admin' }, TEST_SECRET, {
+        expiresIn: -1,
+      });
+      await expect(verifyToken(token, TEST_SECRET)).rejects.toThrow();
+    });
+  });
+});

package/src/lib/jwt.ts

@@ -0,0 +1,28 @@
+import { sign, verify } from 'hono/jwt';
+import type { ZooidJWT } from '../types';
+
+export async function createToken(
+  claims: Partial<ZooidJWT>,
+  secret: string,
+  options?: { expiresIn?: number },
+): Promise<string> {
+  const now = Math.floor(Date.now() / 1000);
+  const payload: Record<string, unknown> = {
+    ...claims,
+    iat: now,
+  };
+
+  if (options?.expiresIn !== undefined) {
+    payload.exp = now + options.expiresIn;
+  }
+
+  return sign(payload, secret, 'HS256');
+}
+
+export async function verifyToken(
+  token: string,
+  secret: string,
+): Promise<ZooidJWT> {
+  const payload = await verify(token, secret, 'HS256');
+  return payload as unknown as ZooidJWT;
+}

package/src/lib/schema-validator.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest';
+import { validateEvent } from './schema-validator';
+
+const schema = {
+  alert: {
+    required: ['level', 'message'],
+    properties: {
+      level: { type: 'string', enum: ['info', 'warn', 'error'] },
+      message: { type: 'string' },
+    },
+  },
+  metric: {
+    required: ['name', 'value'],
+    properties: {
+      name: { type: 'string' },
+      value: { type: 'number' },
+    },
+  },
+};
+
+describe('validateEvent', () => {
+  it('accepts a valid alert event', () => {
+    const result = validateEvent(schema, 'alert', { level: 'info', message: 'hello' });
+    expect(result.valid).toBe(true);
+  });
+
+  it('accepts a valid metric event', () => {
+    const result = validateEvent(schema, 'metric', { name: 'cpu', value: 42 });
+    expect(result.valid).toBe(true);
+  });
+
+  it('rejects event with no type', () => {
+    const result = validateEvent(schema, null, { level: 'info', message: 'hello' });
+    expect(result.valid).toBe(false);
+    expect(result.valid === false && result.error).toContain('must have a type');
+  });
+
+  it('rejects event with undefined type', () => {
+    const result = validateEvent(schema, undefined, {});
+    expect(result.valid).toBe(false);
+    expect(result.valid === false && result.error).toContain('must have a type');
+  });
+
+  it('rejects unknown event type', () => {
+    const result = validateEvent(schema, 'unknown', { foo: 'bar' });
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.error).toContain('Unknown event type');
+      expect(result.error).toContain('alert');
+      expect(result.error).toContain('metric');
+    }
+  });
+
+  it('rejects missing required field', () => {
+    const result = validateEvent(schema, 'alert', { level: 'info' });
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.error).toContain('message');
+    }
+  });
+
+  it('rejects wrong type for a field', () => {
+    const result = validateEvent(schema, 'metric', { name: 'cpu', value: 'not-a-number' });
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.error).toContain('value');
+    }
+  });
+
+  it('rejects invalid enum value', () => {
+    const result = validateEvent(schema, 'alert', { level: 'critical', message: 'oops' });
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.error).toContain('level');
+    }
+  });
+
+  it('accepts data with extra fields (no additionalProperties restriction)', () => {
+    const result = validateEvent(schema, 'alert', { level: 'info', message: 'hi', extra: true });
+    expect(result.valid).toBe(true);
+  });
+
+  it('accepts empty data when no required fields', () => {
+    const schemaNoRequired = {
+      ping: { properties: { ts: { type: 'number' } } },
+    };
+    const result = validateEvent(schemaNoRequired, 'ping', {});
+    expect(result.valid).toBe(true);
+  });
+
+  it('validates boolean type correctly', () => {
+    const boolSchema = {
+      toggle: {
+        required: ['enabled'],
+        properties: { enabled: { type: 'boolean' } },
+      },
+    };
+    expect(validateEvent(boolSchema, 'toggle', { enabled: true }).valid).toBe(true);
+    expect(validateEvent(boolSchema, 'toggle', { enabled: 'yes' }).valid).toBe(false);
+  });
+});

package/src/lib/schema-validator.ts

@@ -0,0 +1,64 @@
+import { Validator } from '@cfworker/json-schema';
+
+export type ValidationResult = {
+  valid: true;
+} | {
+  valid: false;
+  error: string;
+};
+
+/**
+ * Validate an event against a channel's schema.
+ *
+ * The schema is a map of event types to JSON Schema-like property definitions:
+ * ```json
+ * {
+ *   "alert": {
+ *     "required": ["level", "message"],
+ *     "properties": { "level": { "type": "string" }, "message": { "type": "string" } }
+ *   }
+ * }
+ * ```
+ *
+ * This function converts the type entry into a proper JSON Schema and validates
+ * using @cfworker/json-schema (Cloudflare Workers compatible).
+ */
+export function validateEvent(
+  schema: Record<string, { required?: string[]; properties?: Record<string, unknown> }>,
+  type: string | null | undefined,
+  data: unknown,
+): ValidationResult {
+  if (!type) {
+    return { valid: false, error: 'Event must have a type when publishing to a strict channel' };
+  }
+
+  const typeSchema = schema[type];
+  if (!typeSchema) {
+    const allowed = Object.keys(schema).join(', ');
+    return { valid: false, error: `Unknown event type "${type}". Allowed types: ${allowed}` };
+  }
+
+  // Build a JSON Schema object from the type definition
+  const jsonSchema: Record<string, unknown> = {
+    type: 'object',
+    properties: typeSchema.properties ?? {},
+  };
+  if (typeSchema.required) {
+    jsonSchema.required = typeSchema.required;
+  }
+
+  const validator = new Validator(jsonSchema, '7', false);
+  const result = validator.validate(data);
+
+  if (!result.valid) {
+    const errors = result.errors
+      .map((e) => {
+        const loc = e.instanceLocation === '#' ? 'data' : e.instanceLocation.replace('#/', 'data.');
+        return `${loc}: ${e.error}`;
+      })
+      .join('; ');
+    return { valid: false, error: `Validation failed for type "${type}": ${errors}` };
+  }
+
+  return { valid: true };
+}

package/src/lib/signing.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import {
+  generateKeyPair,
+  signPayload,
+  verifySignature,
+  exportPublicKey,
+} from './signing';
+
+describe('Ed25519 signing', () => {
+  it('generates a key pair', async () => {
+    const keyPair = await generateKeyPair();
+    expect(keyPair.privateKey).toBeTruthy();
+    expect(keyPair.publicKey).toBeTruthy();
+  });
+
+  it('signs a payload and produces a base64 signature', async () => {
+    const keyPair = await generateKeyPair();
+    const timestamp = '2026-02-17T14:30:00Z';
+    const body = '{"test":"data"}';
+    const signature = await signPayload(keyPair.privateKey, timestamp, body);
+    expect(typeof signature).toBe('string');
+    expect(signature.length).toBeGreaterThan(0);
+  });
+
+  it('verifies a valid signature', async () => {
+    const keyPair = await generateKeyPair();
+    const timestamp = '2026-02-17T14:30:00Z';
+    const body = '{"test":"data"}';
+    const signature = await signPayload(keyPair.privateKey, timestamp, body);
+    const valid = await verifySignature(
+      keyPair.publicKey,
+      signature,
+      timestamp,
+      body,
+    );
+    expect(valid).toBe(true);
+  });
+
+  it('rejects a tampered body', async () => {
+    const keyPair = await generateKeyPair();
+    const timestamp = '2026-02-17T14:30:00Z';
+    const body = '{"test":"data"}';
+    const signature = await signPayload(keyPair.privateKey, timestamp, body);
+    const valid = await verifySignature(
+      keyPair.publicKey,
+      signature,
+      timestamp,
+      '{"test":"tampered"}',
+    );
+    expect(valid).toBe(false);
+  });
+
+  it('rejects a tampered timestamp', async () => {
+    const keyPair = await generateKeyPair();
+    const timestamp = '2026-02-17T14:30:00Z';
+    const body = '{"test":"data"}';
+    const signature = await signPayload(keyPair.privateKey, timestamp, body);
+    const valid = await verifySignature(
+      keyPair.publicKey,
+      signature,
+      '2026-02-17T15:00:00Z',
+      body,
+    );
+    expect(valid).toBe(false);
+  });
+
+  it('exports public key as base64 SPKI', async () => {
+    const keyPair = await generateKeyPair();
+    const exported = await exportPublicKey(keyPair.publicKey);
+    expect(typeof exported).toBe('string');
+    expect(exported).toMatch(/^[A-Za-z0-9+/]+=*$/);
+  });
+});

package/src/lib/signing.ts

@@ -0,0 +1,60 @@
+export async function generateKeyPair(): Promise<CryptoKeyPair> {
+  return crypto.subtle.generateKey('Ed25519', true, [
+    'sign',
+    'verify',
+  ]) as Promise<CryptoKeyPair>;
+}
+
+export async function signPayload(
+  privateKey: CryptoKey,
+  timestamp: string,
+  body: string,
+): Promise<string> {
+  const message = new TextEncoder().encode(`${timestamp}.${body}`);
+  const signature = await crypto.subtle.sign('Ed25519', privateKey, message);
+  return arrayBufferToBase64(signature);
+}
+
+export async function verifySignature(
+  publicKey: CryptoKey,
+  signature: string,
+  timestamp: string,
+  body: string,
+): Promise<boolean> {
+  const message = new TextEncoder().encode(`${timestamp}.${body}`);
+  const sigBytes = base64ToArrayBuffer(signature);
+  return crypto.subtle.verify('Ed25519', publicKey, sigBytes, message);
+}
+
+export async function exportPublicKey(publicKey: CryptoKey): Promise<string> {
+  const exported = await crypto.subtle.exportKey('spki', publicKey);
+  return arrayBufferToBase64(exported);
+}
+
+export async function importPrivateKey(base64: string): Promise<CryptoKey> {
+  const keyData = base64ToArrayBuffer(base64);
+  return crypto.subtle.importKey('pkcs8', keyData, 'Ed25519', true, ['sign']);
+}
+
+export async function importPublicKey(base64: string): Promise<CryptoKey> {
+  const keyData = base64ToArrayBuffer(base64);
+  return crypto.subtle.importKey('spki', keyData, 'Ed25519', true, ['verify']);
+}
+
+function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}

package/src/lib/ulid.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { generateUlid } from './ulid';
+
+describe('ULID generation', () => {
+  it('generates a 26-character string', () => {
+    const id = generateUlid();
+    expect(id).toHaveLength(26);
+  });
+
+  it('generates unique IDs', () => {
+    const ids = new Set(Array.from({ length: 100 }, () => generateUlid()));
+    expect(ids.size).toBe(100);
+  });
+
+  it('generates time-ordered IDs (lexicographic sort = chronological)', () => {
+    const id1 = generateUlid();
+    const id2 = generateUlid();
+    expect(id2 > id1).toBe(true);
+  });
+
+  it('contains only valid Crockford Base32 characters', () => {
+    const id = generateUlid();
+    expect(id).toMatch(/^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$/);
+  });
+});

package/src/lib/ulid.ts

@@ -0,0 +1,8 @@
+export { monotonicFactory } from 'ulidx';
+import { monotonicFactory } from 'ulidx';
+
+const monotonic = monotonicFactory();
+
+export function generateUlid(): string {
+  return monotonic();
+}

package/src/lib/validation.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { isValidChannelId } from './validation';
+
+describe('Channel ID validation', () => {
+  it('accepts valid slugs', () => {
+    expect(isValidChannelId('polymarket-signals')).toBe(true);
+    expect(isValidChannelId('abc')).toBe(true);
+    expect(isValidChannelId('my-channel-123')).toBe(true);
+  });
+
+  it('rejects too short (< 3 chars)', () => {
+    expect(isValidChannelId('ab')).toBe(false);
+    expect(isValidChannelId('a')).toBe(false);
+    expect(isValidChannelId('')).toBe(false);
+  });
+
+  it('rejects too long (> 64 chars)', () => {
+    expect(isValidChannelId('a'.repeat(65))).toBe(false);
+  });
+
+  it('rejects uppercase', () => {
+    expect(isValidChannelId('MyChannel')).toBe(false);
+  });
+
+  it('rejects special characters', () => {
+    expect(isValidChannelId('my_channel')).toBe(false);
+    expect(isValidChannelId('my.channel')).toBe(false);
+    expect(isValidChannelId('my channel')).toBe(false);
+  });
+
+  it('rejects leading/trailing hyphens', () => {
+    expect(isValidChannelId('-my-channel')).toBe(false);
+    expect(isValidChannelId('my-channel-')).toBe(false);
+  });
+});

package/src/lib/validation.ts

@@ -0,0 +1,8 @@
+/**
+ * Validate a channel ID slug.
+ * Rules: lowercase alphanumeric + hyphens, 3-64 chars, no leading/trailing hyphens.
+ */
+export function isValidChannelId(id: string): boolean {
+  if (id.length < 3 || id.length > 64) return false;
+  return /^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(id);
+}

package/src/lib/xml.ts

@@ -0,0 +1,13 @@
+import { XMLBuilder } from 'fast-xml-parser';
+
+const builder = new XMLBuilder({
+  ignoreAttributes: false,
+  attributeNamePrefix: '@_',
+  format: true,
+  suppressEmptyNode: true,
+  processEntities: false,
+});
+
+export function buildXml(obj: Record<string, unknown>): string {
+  return '<?xml version="1.0" encoding="UTF-8"?>\n' + builder.build(obj);
+}

package/src/middleware/auth.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect } from 'vitest';
+import { Hono } from 'hono';
+import { requireAuth, requireScope } from './auth';
+import { createToken } from '../lib/jwt';
+
+const JWT_SECRET = 'test-jwt-secret';
+
+function createTestApp() {
+  const app = new Hono<{
+    Bindings: { ZOOID_JWT_SECRET: string };
+    Variables: { jwtPayload: { scope: string; channel?: string } };
+  }>();
+
+  app.get('/public', (c) => c.json({ ok: true }));
+
+  app.get('/protected', requireAuth(), (c) => {
+    return c.json({ scope: c.get('jwtPayload').scope });
+  });
+
+  app.get('/admin', requireAuth(), requireScope('admin'), (c) => {
+    return c.json({ admin: true });
+  });
+
+  app.post(
+    '/publish/:channelId',
+    requireAuth(),
+    requireScope('publish', { channelParam: 'channelId' }),
+    (c) => {
+      return c.json({ published: true });
+    },
+  );
+
+  return app;
+}
+
+describe('Auth middleware', () => {
+  const app = createTestApp();
+
+  it('allows unauthenticated access to public routes', async () => {
+    const res = await app.request('/public', {}, { ZOOID_JWT_SECRET: JWT_SECRET });
+    expect(res.status).toBe(200);
+  });
+
+  it('rejects requests without Authorization header', async () => {
+    const res = await app.request(
+      '/protected',
+      {},
+      { ZOOID_JWT_SECRET: JWT_SECRET },
+    );
+    expect(res.status).toBe(401);
+  });
+
+  it('rejects requests with invalid token', async () => {
+    const res = await app.request(
+      '/protected',
+      { headers: { Authorization: 'Bearer invalid-token' } },
+      { ZOOID_JWT_SECRET: JWT_SECRET },
+    );
+    expect(res.status).toBe(401);
+  });
+
+  it('allows requests with valid token', async () => {
+    const token = await createToken({ scope: 'admin' }, JWT_SECRET);
+    const res = await app.request(
+      '/protected',
+      { headers: { Authorization: `Bearer ${token}` } },
+      { ZOOID_JWT_SECRET: JWT_SECRET },
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { scope: string };
+    expect(body.scope).toBe('admin');
+  });
+
+  it('enforces admin scope', async () => {
+    const token = await createToken(
+      { scope: 'publish', channel: 'test' },
+      JWT_SECRET,
+    );
+    const res = await app.request(
+      '/admin',
+      { headers: { Authorization: `Bearer ${token}` } },
+      { ZOOID_JWT_SECRET: JWT_SECRET },
+    );
+    expect(res.status).toBe(403);
+  });
+
+  it('allows admin scope on admin route', async () => {
+    const token = await createToken({ scope: 'admin' }, JWT_SECRET);
+    const res = await app.request(
+      '/admin',
+      { headers: { Authorization: `Bearer ${token}` } },
+      { ZOOID_JWT_SECRET: JWT_SECRET },
+    );
+    expect(res.status).toBe(200);
+  });
+
+  it('rejects publish token for wrong channel', async () => {
+    const token = await createToken(
+      { scope: 'publish', channel: 'channel-a' },
+      JWT_SECRET,
+    );
+    const res = await app.request(
+      '/publish/channel-b',
+      {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}` },
+      },
+      { ZOOID_JWT_SECRET: JWT_SECRET },
+    );
+    expect(res.status).toBe(403);
+  });
+
+  it('allows admin token on any channel-scoped route', async () => {
+    const token = await createToken({ scope: 'admin' }, JWT_SECRET);
+    const res = await app.request(
+      '/publish/any-channel',
+      {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}` },
+      },
+      { ZOOID_JWT_SECRET: JWT_SECRET },
+    );
+    expect(res.status).toBe(200);
+  });
+});