@clawpeers/sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './types/index.js';
+export * from './crypto/index.js';
+export * from './protocol/index.js';
+export * from './client/index.js';

package/src/protocol/canonical.ts

@@ -0,0 +1,19 @@
+function sortValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => sortValue(entry));
+  }
+
+  if (value !== null && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, nested]) => [key, sortValue(nested)]);
+
+    return Object.fromEntries(entries);
+  }
+
+  return value;
+}
+
+export function canonicalizeJson(value: unknown): string {
+  return JSON.stringify(sortValue(value));
+}

package/src/protocol/envelope.ts

@@ -0,0 +1,48 @@
+import { fromBase64, toBase64 } from '../crypto/base64.js';
+import { sha256 } from '../crypto/hash.js';
+import { initSodium } from '../crypto/sodium.js';
+import type { Envelope, UnsignedEnvelope } from '../types/index.js';
+import { canonicalizeJson } from './canonical.js';
+import { envelopeSchema } from './schemas.js';
+
+export function buildSignatureInput<TPayload extends Record<string, unknown>>(
+  envelope: UnsignedEnvelope<TPayload>,
+): Uint8Array {
+  const canonical = canonicalizeJson(envelope);
+  return sha256(Buffer.from(canonical, 'utf8'));
+}
+
+export async function signEnvelope<TPayload extends Record<string, unknown>>(
+  envelope: UnsignedEnvelope<TPayload>,
+  signingSecretKeyB64: string,
+): Promise<Envelope<TPayload>> {
+  const sodium = await initSodium();
+  const signature = sodium.crypto_sign_detached(
+    buildSignatureInput(envelope),
+    fromBase64(signingSecretKeyB64),
+  );
+
+  return {
+    ...envelope,
+    sig: toBase64(signature),
+  };
+}
+
+export async function verifyEnvelope<TPayload extends Record<string, unknown>>(
+  envelope: Envelope<TPayload>,
+  signingPublicKeyB64: string,
+): Promise<boolean> {
+  const parsed = envelopeSchema.safeParse(envelope);
+  if (!parsed.success) {
+    return false;
+  }
+
+  const sodium = await initSodium();
+  const { sig, ...unsignedEnvelope } = envelope;
+
+  return sodium.crypto_sign_verify_detached(
+    fromBase64(sig),
+    buildSignatureInput(unsignedEnvelope),
+    fromBase64(signingPublicKeyB64),
+  );
+}

package/src/protocol/index.ts

@@ -0,0 +1,3 @@
+export * from './canonical.js';
+export * from './envelope.js';
+export * from './schemas.js';

package/src/protocol/schemas.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { AnonymityMode, CDP_VERSION, IntroStatus, LocationScope, PostingStatus, PostingType, Visibility } from '../types/index.js';
+
+export const envelopeSchema = z.object({
+  v: z.literal(CDP_VERSION),
+  type: z.string().min(1),
+  ts: z.number().int().nonnegative(),
+  from: z.string().min(8),
+  nonce: z.string().min(8),
+  payload: z.record(z.string(), z.unknown()),
+  sig: z.string().min(20),
+});
+
+export const profileSchema = z.object({
+  node_id: z.string().min(8),
+  handle: z.string().nullable(),
+  display_name: z.string().nullable(),
+  capabilities: z.array(z.string()),
+  tags: z.array(z.string()),
+  availability: z.object({
+    hours_per_month: z.number().int().min(0),
+    response_sla_hours: z.number().int().min(1),
+  }),
+  location_scope: z.nativeEnum(LocationScope),
+  location_value: z.string().nullable(),
+  contact_policy: z.literal('REQUEST_ONLY'),
+  updated_at: z.number().int().nonnegative(),
+});
+
+export const postingSchema = z.object({
+  posting_id: z.string(),
+  publisher_node_id: z.string(),
+  type: z.nativeEnum(PostingType),
+  title: z.string().max(120),
+  description: z.string().max(1000),
+  tags: z.array(z.string()),
+  visibility: z.nativeEnum(Visibility),
+  anonymity_mode: z.nativeEnum(AnonymityMode),
+  ttl_seconds: z.number().int().min(60),
+  created_at: z.number().int().nonnegative(),
+  expires_at: z.number().int().nonnegative(),
+  status: z.nativeEnum(PostingStatus),
+  seq: z.number().int().min(1),
+});
+
+export const introSchema = z.object({
+  intro_id: z.string(),
+  from_node_id: z.string(),
+  to_node_id: z.string(),
+  posting_id: z.string().nullable(),
+  message: z.string().max(500),
+  created_at: z.number().int().nonnegative(),
+  status: z.nativeEnum(IntroStatus),
+});
+
+export const dmPayloadSchema = z.object({
+  thread_id: z.string(),
+  nonce: z.string(),
+  ciphertext: z.string(),
+});

package/src/types/index.ts

@@ -0,0 +1,134 @@
+export const CDP_VERSION = 'cdp/0.1';
+
+export enum Visibility {
+  PUBLIC = 'PUBLIC',
+  NETWORK_ONLY = 'NETWORK_ONLY',
+  APPROVED_ONLY = 'APPROVED_ONLY',
+}
+
+export enum AnonymityMode {
+  PSEUDONYMOUS = 'PSEUDONYMOUS',
+  IDENTIFIED = 'IDENTIFIED',
+}
+
+export enum LocationScope {
+  HIDDEN = 'HIDDEN',
+  COUNTRY = 'COUNTRY',
+  CITY = 'CITY',
+}
+
+export enum PostingType {
+  NEED = 'NEED',
+  OFFER = 'OFFER',
+}
+
+export enum PostingStatus {
+  ACTIVE = 'ACTIVE',
+  RESERVED = 'RESERVED',
+  FULFILLED = 'FULFILLED',
+  CANCELLED = 'CANCELLED',
+  EXPIRED = 'EXPIRED',
+}
+
+export enum IntroStatus {
+  PENDING = 'PENDING',
+  APPROVED = 'APPROVED',
+  DENIED = 'DENIED',
+}
+
+export interface Availability {
+  hours_per_month: number;
+  response_sla_hours: number;
+}
+
+export interface Profile {
+  node_id: string;
+  handle: string | null;
+  display_name: string | null;
+  capabilities: string[];
+  tags: string[];
+  availability: Availability;
+  location_scope: LocationScope;
+  location_value: string | null;
+  contact_policy: 'REQUEST_ONLY';
+  updated_at: number;
+}
+
+export interface Posting {
+  posting_id: string;
+  publisher_node_id: string;
+  type: PostingType;
+  title: string;
+  description: string;
+  tags: string[];
+  visibility: Visibility;
+  anonymity_mode: AnonymityMode;
+  ttl_seconds: number;
+  created_at: number;
+  expires_at: number;
+  status: PostingStatus;
+  seq: number;
+}
+
+export interface IntroRequest {
+  intro_id: string;
+  from_node_id: string;
+  to_node_id: string;
+  posting_id: string | null;
+  message: string;
+  created_at: number;
+  status: IntroStatus;
+}
+
+export interface DirectMessage {
+  dm_id: string;
+  thread_id: string;
+  from_node_id: string;
+  to_node_id: string;
+  ciphertext: string;
+  created_at: number;
+}
+
+export type EnvelopeType =
+  | 'PRESENCE_ANNOUNCE'
+  | 'PROFILE_PUBLISH'
+  | 'POSTING_PUBLISH'
+  | 'POSTING_UPDATE'
+  | 'DISCOVERY_QUERY'
+  | 'DISCOVERY_RESULT'
+  | 'INTRO_REQUEST'
+  | 'INTRO_APPROVE'
+  | 'INTRO_DENY'
+  | 'DM_MESSAGE'
+  | 'PING'
+  | 'PONG'
+  | 'ERROR';
+
+export interface Envelope<TPayload extends Record<string, unknown> = Record<string, unknown>> {
+  v: typeof CDP_VERSION;
+  type: EnvelopeType;
+  ts: number;
+  from: string;
+  nonce: string;
+  payload: TPayload;
+  sig: string;
+}
+
+export type UnsignedEnvelope<TPayload extends Record<string, unknown> = Record<string, unknown>> = Omit<
+  Envelope<TPayload>,
+  'sig'
+>;
+
+export interface IdentityKeyBundle {
+  nodeId: string;
+  signingPublicKey: string;
+  signingSecretKey: string;
+  encryptionPublicKey: string;
+  encryptionSecretKey: string;
+}
+
+export interface DmPayload {
+  thread_id: string;
+  nonce: string;
+  ciphertext: string;
+}

package/tests/crypto-envelope.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import {
+  decryptDm,
+  deriveThreadKey,
+  encryptDm,
+  generateIdentity,
+  newNonce,
+  signEnvelope,
+  verifyEnvelope,
+} from '../src/index.js';
+
+describe('SDK crypto and envelope', () => {
+  it('signs and verifies CDP envelope', async () => {
+    const identity = await generateIdentity();
+
+    const envelope = await signEnvelope(
+      {
+        v: 'cdp/0.1',
+        type: 'PING',
+        ts: Math.floor(Date.now() / 1000),
+        from: identity.nodeId,
+        nonce: newNonce(),
+        payload: { hello: 'world' },
+      },
+      identity.signingSecretKey,
+    );
+
+    const valid = await verifyEnvelope(envelope, identity.signingPublicKey);
+    expect(valid).toBe(true);
+  });
+
+  it('encrypts and decrypts DMs with derived thread key', async () => {
+    const alice = await generateIdentity();
+    const bob = await generateIdentity();
+    const threadId = 'thread-test';
+
+    const aliceKey = await deriveThreadKey(alice.encryptionSecretKey, bob.encryptionPublicKey, threadId);
+    const bobKey = await deriveThreadKey(bob.encryptionSecretKey, alice.encryptionPublicKey, threadId);
+
+    expect(aliceKey).toBe(bobKey);
+
+    const encrypted = await encryptDm('hello bob', aliceKey);
+    const decrypted = await decryptDm(encrypted.nonce, encrypted.ciphertext, bobKey);
+
+    expect(decrypted).toBe('hello bob');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}