@oxy.so/protocol 1.0.0

package/src/__tests__/nodeClient.test.ts

@@ -0,0 +1,177 @@
+/**
+ * `NodeClient` round-trip tests — drive the client against a REAL `createNodeApp`
+ * server (booted on an ephemeral port) through a Node `http` transport adapter
+ * (the same `NodeFetch` shape oxy-api adapts from `safeFetch`). Locks the
+ * head/log/records/blobs surface end-to-end, including the gap/fork rejection
+ * reasons surfaced as `NodeClientError` and the blob pin/serve round trip.
+ */
+
+import http from 'node:http';
+import { createHash } from 'node:crypto';
+import type { AddressInfo } from 'node:net';
+import { createNodeApp, type NodeAppConfig } from '../node/nodeApp';
+import { NodeClient, NodeClientError, trimTrailingSlashes } from '../node/nodeClient';
+import type { NodeFetch } from '../node/httpFetch';
+import { computeRecordId } from '../envelope/recordId';
+import {
+  buildSignedEnvelope,
+  createInMemoryNodeStore,
+  createTestOwnerAuth,
+  generateKeyPair,
+  signBlobPin,
+  silentLogger,
+  type TestKeyPair,
+} from './nodeHarness';
+
+/** A Node `http` transport satisfying the injected `NodeFetch` contract. */
+const httpFetch: NodeFetch = (url, init) =>
+  new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const req = http.request(
+      {
+        hostname: u.hostname,
+        port: u.port,
+        path: `${u.pathname}${u.search}`,
+        method: init.method,
+        headers: init.headers,
+      },
+      (res) => {
+        resolve({
+          status: res.statusCode ?? 0,
+          headers: res.headers,
+          body: res,
+          destroy: () => res.destroy(),
+        });
+      },
+    );
+    req.on('error', reject);
+    if (init.body) {
+      req.write(Buffer.from(init.body));
+    }
+    req.end();
+  });
+
+function makeConfig(nodePublicKey: string): NodeAppConfig {
+  return {
+    wellKnownPath: '/.well-known/oxy-node.json',
+    protocolId: 'oxy-node/1',
+    serviceType: 'OxyPersonalDataNode',
+    mode: 'self-hosted',
+    nodePublicKey,
+    maxBlobBytes: 25 * 1024 * 1024,
+    collections: [],
+  };
+}
+
+describe('trimTrailingSlashes', () => {
+  it('removes one or many trailing slashes', () => {
+    expect(trimTrailingSlashes('https://node.example')).toBe('https://node.example');
+    expect(trimTrailingSlashes('https://node.example/')).toBe('https://node.example');
+    expect(trimTrailingSlashes('https://node.example////')).toBe('https://node.example');
+  });
+
+  it('preserves interior slashes and the empty string', () => {
+    expect(trimTrailingSlashes('https://node.example/oxy/log')).toBe('https://node.example/oxy/log');
+    expect(trimTrailingSlashes('')).toBe('');
+    expect(trimTrailingSlashes('///')).toBe('');
+  });
+
+  it('is linear-time on a long all-slash input (no ReDoS backtracking)', () => {
+    const pathological = `https://node.example${'/'.repeat(200_000)}`;
+    const start = Date.now();
+    expect(trimTrailingSlashes(pathological)).toBe('https://node.example');
+    // A linear scan of 200k chars completes in well under a tenth of a second;
+    // a backtracking regex would be orders of magnitude slower.
+    expect(Date.now() - start).toBeLessThan(100);
+  });
+});
+
+describe('NodeClient (end-to-end against createNodeApp)', () => {
+  let owner: TestKeyPair;
+  let app: ReturnType<typeof createNodeApp>;
+  let server: http.Server;
+  let client: NodeClient;
+
+  beforeEach(async () => {
+    owner = generateKeyPair();
+    app = createNodeApp({
+      store: createInMemoryNodeStore(),
+      config: makeConfig(owner.publicKey),
+      ownerAuth: createTestOwnerAuth(owner.publicKey),
+      logger: silentLogger,
+    });
+    server = await new Promise<http.Server>((resolve) => {
+      const s = app.listen(0, () => resolve(s));
+    });
+    const { port } = server.address() as AddressInfo;
+    client = new NodeClient({ baseUrl: `http://127.0.0.1:${port}`, fetch: httpFetch });
+  });
+
+  afterEach(async () => {
+    app.stop();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  it('head() reports an empty chain, then advances after writes', async () => {
+    expect(await client.head()).toEqual({ seq: null, headRecordId: null, recordCount: 0 });
+
+    const genesis = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 0, prev: null });
+    const genesisId = await computeRecordId(genesis);
+    expect(await client.writeRecord(genesis)).toEqual({ recordId: genesisId, seq: 0 });
+
+    expect(await client.head()).toEqual({ seq: 0, headRecordId: genesisId, recordCount: 1 });
+  });
+
+  it('writeRecord chains records and log() returns them in order', async () => {
+    const genesis = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 0, prev: null });
+    const genesisId = await computeRecordId(genesis);
+    await client.writeRecord(genesis);
+
+    const second = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 1, prev: genesisId });
+    const secondId = await computeRecordId(second);
+    expect(await client.writeRecord(second)).toEqual({ recordId: secondId, seq: 1 });
+
+    const page = await client.log(-1, 100);
+    expect(page.count).toBe(2);
+    expect(page.records.map((r) => (r as { seq: number }).seq)).toEqual([0, 1]);
+    expect((page.records[1] as { recordId: string }).recordId).toBe(secondId);
+    expect(page.head).toEqual({ seq: 1, headRecordId: secondId });
+
+    const since = await client.log(0, 100);
+    expect(since.records.map((r) => (r as { seq: number }).seq)).toEqual([1]);
+  });
+
+  it('writeRecord surfaces a chain gap as a NodeClientError (422 chain_gap)', async () => {
+    const gap = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 3, prev: null });
+    await expect(client.writeRecord(gap)).rejects.toMatchObject({ status: 422, reason: 'chain_gap' });
+    await expect(client.writeRecord(gap)).rejects.toBeInstanceOf(NodeClientError);
+  });
+
+  it('writeRecord surfaces a chain fork as a NodeClientError (422 chain_fork)', async () => {
+    const genesis = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 0, prev: null });
+    await client.writeRecord(genesis);
+
+    const fork = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 1, prev: 'f'.repeat(64) });
+    await expect(client.writeRecord(fork)).rejects.toMatchObject({ status: 422, reason: 'chain_fork' });
+  });
+
+  it('writeRecord surfaces a non-owner write as a NodeClientError (403 not_owner)', async () => {
+    const attacker = generateKeyPair();
+    const envelope = await buildSignedEnvelope({ privateKey: attacker.privateKey, seq: 0, prev: null });
+    await expect(client.writeRecord(envelope)).rejects.toMatchObject({ status: 403, reason: 'not_owner' });
+  });
+
+  it('putBlob then getBlob round-trips; getBlob returns null when absent', async () => {
+    const bytes = Buffer.from('client-pinned blob bytes');
+    const hash = createHash('sha256').update(bytes).digest('hex');
+
+    expect(await client.getBlob(hash)).toBeNull();
+
+    const auth = await signBlobPin(hash, owner);
+    expect(await client.putBlob(hash, bytes, auth)).toEqual({ hash, size: bytes.length });
+
+    const fetched = await client.getBlob(hash);
+    expect(fetched).not.toBeNull();
+    expect(Buffer.from(fetched as Uint8Array).equals(bytes)).toBe(true);
+  });
+});

package/src/__tests__/nodeHarness.ts

@@ -0,0 +1,151 @@
+/**
+ * Shared test harness for the `@oxy.so/protocol/node` suites — an in-memory
+ * `RecordStore`/`BlobStore`, an owner-key `OwnerAuth`, a silent logger, and a
+ * signed-envelope forge. Not a test file (no `.test.ts` suffix) — imported by
+ * the node app / client suites so they exercise `createNodeApp` + `NodeClient`
+ * against a faithful (continuity-enforcing) store with no DB and no real crypto
+ * service.
+ */
+
+import { generateSecp256k1KeyPair } from '../secp256k1';
+import { createHash } from 'node:crypto';
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import { checkContinuity } from '../chain/continuity';
+import { signEnvelope, signMessage, verifySignature } from '../envelope/sign';
+import type { AppendOutcome, ChainHead } from '../chain/types';
+import type { BlobStore, RecordStore } from '../chain/recordStore';
+import { BlobHashMismatchError, type NodeLogger, type OwnerAuth } from '../node/nodeApp';
+
+export interface TestKeyPair {
+  privateKey: string;
+  publicKey: string;
+}
+
+/** Generate a secp256k1 keypair (uncompressed hex public key, matching the signer). */
+export function generateKeyPair(): TestKeyPair {
+  const kp = generateSecp256k1KeyPair();
+  return { privateKey: kp.privateKey, publicKey: kp.publicKey };
+}
+
+export const DEFAULT_SUBJECT = 'did:web:node.example:u:owner';
+
+export interface BuildEnvelopeOptions {
+  privateKey: string;
+  seq: number;
+  prev: string | null;
+  subject?: string;
+  issuer?: string;
+  type?: string;
+  collection?: string;
+  rkey?: string;
+  record?: Record<string, unknown>;
+  issuedAt?: number;
+}
+
+/** Forge a fully-signed v2 envelope with the protocol signer. */
+export function buildSignedEnvelope(options: BuildEnvelopeOptions): Promise<SignedRecordEnvelope> {
+  const subject = options.subject ?? DEFAULT_SUBJECT;
+  return signEnvelope(
+    {
+      version: 2,
+      type: options.type ?? 'app_record',
+      subject,
+      issuer: options.issuer ?? subject,
+      record: options.record ?? { hello: 'world' },
+      issuedAt: options.issuedAt ?? 1_700_000_000_000 + options.seq,
+      seq: options.seq,
+      prev: options.prev,
+      collection: options.collection ?? 'app.oxy.identity',
+      rkey: options.rkey ?? 'self',
+    },
+    options.privateKey,
+  );
+}
+
+/** A continuity-enforcing in-memory `RecordStore` + `BlobStore` (single chain). */
+export function createInMemoryNodeStore(): RecordStore & BlobStore {
+  const records: Array<{ env: SignedRecordEnvelope; recordId: string }> = [];
+  const recordIds = new Set<string>();
+  const blobs = new Map<string, Buffer>();
+  let head: ChainHead | null = null;
+
+  return {
+    async getHead(): Promise<ChainHead | null> {
+      return head;
+    },
+    async append(_subject, env, recordId): Promise<AppendOutcome> {
+      const continuity = checkContinuity(head, env);
+      if (!continuity.ok) {
+        return continuity;
+      }
+      if (recordIds.has(recordId)) {
+        return { ok: false, reason: 'chain_conflict' };
+      }
+      const seq = env.seq ?? -1;
+      records.push({ env, recordId });
+      recordIds.add(recordId);
+      head = { headRecordId: recordId, seq, recordCount: records.length };
+      return { ok: true, recordId, seq };
+    },
+    async getLogSince(_subject, sinceSeq, limit): Promise<SignedRecordEnvelope[]> {
+      return records
+        .filter((r) => (r.env.seq ?? -1) > sinceSeq)
+        .slice(0, limit)
+        .map((r) => r.env);
+    },
+    async resolveCursorSeq(_subject, recordId): Promise<number | null> {
+      const found = records.find((r) => r.recordId === recordId);
+      return found ? found.env.seq ?? -1 : null;
+    },
+    async materializeCurrent(_subject, collection, rkey): Promise<SignedRecordEnvelope | null> {
+      const matching = records.filter((r) => r.env.collection === collection && r.env.rkey === rkey);
+      return matching.length ? matching[matching.length - 1].env : null;
+    },
+    async latestIssuedAtForKey(_subject, env): Promise<number | null> {
+      const matching = records.filter((r) => r.env.collection === env.collection && r.env.rkey === env.rkey);
+      return matching.length ? matching[matching.length - 1].env.issuedAt : null;
+    },
+    async putBlob(hash, bytes): Promise<void> {
+      const buf = Buffer.from(bytes);
+      const actual = createHash('sha256').update(buf).digest('hex');
+      const address = hash.toLowerCase();
+      if (actual !== address) {
+        throw new BlobHashMismatchError(address, actual);
+      }
+      blobs.set(address, buf);
+    },
+    async getBlob(hash): Promise<Uint8Array | null> {
+      return blobs.get(hash.toLowerCase()) ?? null;
+    },
+  };
+}
+
+/** An `OwnerAuth` bound to `ownerPublicKey`, verifying the node-style pin message. */
+export function createTestOwnerAuth(ownerPublicKey: string): OwnerAuth {
+  const owner = ownerPublicKey.toLowerCase();
+  return {
+    isOwnerKey(publicKey: string): boolean {
+      return publicKey.toLowerCase() === owner;
+    },
+    async verifyBlobPin(hash, auth): Promise<boolean> {
+      if (auth.publicKey.toLowerCase() !== owner) {
+        return false;
+      }
+      const message = `oxy-node:blob-pin:${hash}:${auth.timestamp}`;
+      return verifySignature(message, auth.signature, auth.publicKey);
+    },
+  };
+}
+
+/** Sign the owner pin authorization headers for a blob hash. */
+export async function signBlobPin(
+  hash: string,
+  owner: TestKeyPair,
+): Promise<{ publicKey: string; signature: string; timestamp: number }> {
+  const timestamp = Date.now();
+  const signature = await signMessage(`oxy-node:blob-pin:${hash}:${timestamp}`, owner.privateKey);
+  return { publicKey: owner.publicKey, signature, timestamp };
+}
+
+/** A logger that swallows output (the suites assert on responses, not logs). */
+export const silentLogger: NodeLogger = { error() {} };

package/src/__tests__/optionalNativePeers.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Guards the optional-peer contract of the React Native platform fork.
+ *
+ * `expo-crypto`, `expo-secure-store` and `@react-native-async-storage/async-storage`
+ * are declared OPTIONAL peer dependencies. A STATIC `import` of any of them
+ * contradicts that: Metro resolves every static import in the eager graph, so an
+ * app that omits the optional peer does not degrade — its whole native bundle
+ * fails with `Unable to resolve module <peer>`, pointing at a dependency the app
+ * never mentions. Because `@oxy.so/core`'s `crypto/polyfill` imports
+ * `@oxy.so/protocol`'s ROOT entry, `platform/crypto.native.ts` sits in the eager
+ * graph of every React Native app in the fleet, so the blast radius is total.
+ *
+ * Two tests, deliberately different in kind:
+ *
+ *  1. A STATIC guard over the module graph reachable from `src/index.ts`
+ *     (including the `.native.ts` siblings Metro substitutes), which fails on
+ *     any future static import of an optional peer anywhere in that graph.
+ *  2. A BEHAVIOURAL check that the fork imports cleanly when the peers are
+ *     missing and only throws — with an actionable message — at the point where
+ *     the capability is used.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+const SRC_DIR = resolve(__dirname, '..');
+const ROOT_ENTRY = join(SRC_DIR, 'index.ts');
+
+const packageJson = JSON.parse(
+  readFileSync(resolve(SRC_DIR, '..', 'package.json'), 'utf8'),
+) as {
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+};
+
+const optionalPeers = Object.entries(packageJson.peerDependenciesMeta ?? {})
+  .filter(([, meta]) => meta.optional === true)
+  .map(([name]) => name);
+
+/**
+ * Static `import`/`export … from` specifiers, excluding the `import type` /
+ * `export type` forms, which are fully erased at build time and therefore never
+ * become a Metro dependency.
+ */
+function valueImportSpecifiers(source: string): string[] {
+  const specifiers: string[] = [];
+  const pattern = /(?:^|\n)\s*(?:import|export)\s+(?!type\s)([\s\S]*?)\sfrom\s+['"]([^'"]+)['"]/g;
+  let match = pattern.exec(source);
+  while (match !== null) {
+    specifiers.push(match[2]);
+    match = pattern.exec(source);
+  }
+  // Bare side-effect imports (`import 'foo';`) have no `from` clause.
+  const sideEffectPattern = /(?:^|\n)\s*import\s+['"]([^'"]+)['"]/g;
+  let sideEffect = sideEffectPattern.exec(source);
+  while (sideEffect !== null) {
+    specifiers.push(sideEffect[1]);
+    sideEffect = sideEffectPattern.exec(source);
+  }
+  return specifiers;
+}
+
+function resolveRelative(fromFile: string, specifier: string): string | null {
+  const base = resolve(dirname(fromFile), specifier);
+  for (const candidate of [`${base}.ts`, join(base, 'index.ts')]) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Every source file Metro can pull into a React Native bundle through the root
+ * entry. Metro substitutes `<base>.native.ts` for `<base>.ts` on native, so each
+ * reachable module contributes its `.native` sibling too.
+ */
+function reachableFromRootEntry(): string[] {
+  const seen = new Set<string>();
+  const queue = [ROOT_ENTRY];
+  while (queue.length > 0) {
+    const file = queue.shift() as string;
+    if (seen.has(file)) {
+      continue;
+    }
+    seen.add(file);
+
+    const nativeSibling = file.replace(/\.ts$/, '.native.ts');
+    if (nativeSibling !== file && existsSync(nativeSibling) && !seen.has(nativeSibling)) {
+      queue.push(nativeSibling);
+    }
+
+    for (const specifier of valueImportSpecifiers(readFileSync(file, 'utf8'))) {
+      if (!specifier.startsWith('.')) {
+        continue;
+      }
+      const resolved = resolveRelative(file, specifier);
+      if (resolved !== null) {
+        queue.push(resolved);
+      }
+    }
+  }
+  return [...seen];
+}
+
+describe('optional peer dependencies are never statically imported', () => {
+  it('declares the React Native modules as optional peers', () => {
+    expect(optionalPeers).toEqual(
+      expect.arrayContaining([
+        'expo-crypto',
+        'expo-secure-store',
+        '@react-native-async-storage/async-storage',
+      ]),
+    );
+  });
+
+  it('has no static import of an optional peer anywhere in the root-entry graph', () => {
+    const offenders: string[] = [];
+    for (const file of reachableFromRootEntry()) {
+      for (const specifier of valueImportSpecifiers(readFileSync(file, 'utf8'))) {
+        if (optionalPeers.includes(specifier)) {
+          offenders.push(`${file.slice(SRC_DIR.length + 1)} statically imports '${specifier}'`);
+        }
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it('reaches the React Native crypto fork from the root entry', () => {
+    // Sanity check on the walker itself: if this ever stops holding, the guard
+    // above would pass vacuously.
+    expect(reachableFromRootEntry()).toEqual(
+      expect.arrayContaining([join(SRC_DIR, 'platform', 'crypto.native.ts')]),
+    );
+  });
+});
+
+describe('crypto.native optional-peer degradation', () => {
+  const MODULE_PATH = '../platform/crypto.native';
+
+  function unresolvable(name: string): () => never {
+    return () => {
+      throw new Error(`Cannot find module '${name}'`);
+    };
+  }
+
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  it('imports cleanly when every optional peer is missing', () => {
+    jest.isolateModules(() => {
+      jest.doMock('expo-modules-core', () => ({ requireOptionalNativeModule: () => null }), {
+        virtual: true,
+      });
+      jest.doMock('expo-crypto', unresolvable('expo-crypto'), { virtual: true });
+      jest.doMock('expo-secure-store', unresolvable('expo-secure-store'), { virtual: true });
+      jest.doMock(
+        '@react-native-async-storage/async-storage',
+        unresolvable('@react-native-async-storage/async-storage'),
+        { virtual: true },
+      );
+
+      expect(() => require(MODULE_PATH)).not.toThrow();
+    });
+  });
+
+  it('throws an actionable error per capability when the peer is missing', async () => {
+    await jest.isolateModulesAsync(async () => {
+      jest.doMock('expo-modules-core', () => ({ requireOptionalNativeModule: () => null }), {
+        virtual: true,
+      });
+      jest.doMock('expo-crypto', unresolvable('expo-crypto'), { virtual: true });
+      jest.doMock('expo-secure-store', unresolvable('expo-secure-store'), { virtual: true });
+      jest.doMock(
+        '@react-native-async-storage/async-storage',
+        unresolvable('@react-native-async-storage/async-storage'),
+        { virtual: true },
+      );
+
+      const mod = require(MODULE_PATH) as typeof import('../platform/crypto.native');
+
+      await expect(mod.loadExpoCrypto()).rejects.toThrow(/npx expo install expo-crypto/);
+      await expect(mod.loadSecureStore()).rejects.toThrow(/npx expo install expo-secure-store/);
+      await expect(mod.loadAsyncStorage()).rejects.toThrow(
+        /npx expo install @react-native-async-storage\/async-storage/,
+      );
+      expect(() => mod.getRandomBytesRN(8)).toThrow(/npx expo install expo-crypto/);
+
+      // The Metro resolution failure is reported, not swallowed.
+      expect(() => mod.getRandomBytesRN(8)).toThrow(/Cannot find module 'expo-crypto'/);
+    });
+  });
+
+  it('returns the real modules when the optional peers are installed', async () => {
+    const bytes = new Uint8Array([1, 2, 3, 4]);
+    const fakeCrypto = {
+      getRandomBytes: () => bytes,
+      getRandomBytesAsync: async () => bytes,
+      digestStringAsync: async () => 'digest',
+      CryptoDigestAlgorithm: { SHA256: 'SHA-256' },
+    };
+    const fakeSecureStore = {
+      setItemAsync: async () => undefined,
+      getItemAsync: async () => null,
+      deleteItemAsync: async () => undefined,
+      WHEN_UNLOCKED_THIS_DEVICE_ONLY: 1,
+      WHEN_UNLOCKED: 2,
+    };
+    const fakeAsyncStorage = {
+      getItem: async () => null,
+      setItem: async () => undefined,
+      removeItem: async () => undefined,
+    };
+
+    await jest.isolateModulesAsync(async () => {
+      jest.doMock('expo-modules-core', () => ({ requireOptionalNativeModule: () => null }), {
+        virtual: true,
+      });
+      jest.doMock('expo-crypto', () => fakeCrypto, { virtual: true });
+      jest.doMock('expo-secure-store', () => fakeSecureStore, { virtual: true });
+      jest.doMock('@react-native-async-storage/async-storage', () => ({ default: fakeAsyncStorage }), {
+        virtual: true,
+      });
+
+      const mod = require(MODULE_PATH) as typeof import('../platform/crypto.native');
+
+      await expect(mod.loadExpoCrypto()).resolves.toBe(fakeCrypto);
+      await expect(mod.loadSecureStore()).resolves.toBe(fakeSecureStore);
+      await expect(mod.loadAsyncStorage()).resolves.toEqual({ default: fakeAsyncStorage });
+      expect(mod.getRandomBytesRN(4)).toBe(bytes);
+    });
+  });
+});