@oxy.so/protocol 1.0.0

package/src/__tests__/envelope.test.ts

@@ -0,0 +1,267 @@
+/**
+ * Signed-record envelope tests — the protocol's canonical signing input,
+ * content address, and explicit-key sign/verify.
+ *
+ * Includes the byte-stability regression guards moved from `@oxy.so/core`'s
+ * signed-record suite (the v1 signing-input string and the deterministic
+ * `computeRecordId`), plus a CANONICAL-BYTES FIXTURE: signing a fixed envelope
+ * with a fixed key must produce the exact same signing input, recordId, derived
+ * publicKey, and DER signature as before the crypto was moved into protocol.
+ * Any drift here invalidates every production signature, so the literals are
+ * locked.
+ */
+
+import { deriveSecp256k1PublicKey } from '../secp256k1';
+import { signedRecordEnvelopeSchema } from '@oxy.so/contracts';
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import {
+  canonicalize,
+  signedRecordSigningInput,
+  computeRecordId,
+  sha256,
+  signMessage,
+  verifySignature,
+  signEnvelope,
+  verifyEnvelopeSignature,
+} from '../index';
+
+describe('signedRecordSigningInput — v1 byte stability (regression guard)', () => {
+  it('produces the exact original canonical bytes for a v1 record', () => {
+    const input = signedRecordSigningInput({
+      version: 1,
+      type: 'identity',
+      subject: 'did:web:oxy.so:u:u1',
+      issuer: 'did:web:oxy.so:u:u1',
+      record: { handle: '@nate' },
+      issuedAt: 1750000000000,
+    });
+    expect(input).toBe(
+      '{"issuedAt":1750000000000,"issuer":"did:web:oxy.so:u:u1","record":{"handle":"@nate"},"subject":"did:web:oxy.so:u:u1","type":"identity","version":1}',
+    );
+  });
+
+  it('does NOT include any v2 chain fields for a v1 record even if they are passed', () => {
+    const input = signedRecordSigningInput({
+      version: 1,
+      type: 'identity',
+      subject: 'did:web:oxy.so:u:u1',
+      issuer: 'did:web:oxy.so:u:u1',
+      record: { handle: '@nate' },
+      issuedAt: 1750000000000,
+      // These must be ignored by the v1 branch — proving v1 bytes are immutable.
+      seq: 5,
+      prev: 'deadbeef',
+      collection: 'app.oxy.identity',
+      rkey: 'self',
+    });
+    expect(input).not.toContain('seq');
+    expect(input).not.toContain('prev');
+    expect(input).not.toContain('collection');
+    expect(input).not.toContain('rkey');
+    expect(input).toBe(
+      '{"issuedAt":1750000000000,"issuer":"did:web:oxy.so:u:u1","record":{"handle":"@nate"},"subject":"did:web:oxy.so:u:u1","type":"identity","version":1}',
+    );
+  });
+
+  it('a v2 record signs over DIFFERENT bytes than the same base fields as v1', () => {
+    const base = {
+      type: 'profile' as const,
+      subject: 'did:web:oxy.so:u:diff',
+      issuer: 'did:web:oxy.so:u:diff',
+      record: { x: 1 },
+      issuedAt: 1750000000000,
+    };
+    const v1Input = signedRecordSigningInput({ version: 1, ...base });
+    const v2Input = signedRecordSigningInput({
+      version: 2,
+      ...base,
+      seq: 0,
+      prev: null,
+      collection: 'app.oxy.reputation',
+      rkey: 'rt_1',
+    });
+    expect(v2Input).not.toBe(v1Input);
+    expect(v2Input).toContain('"seq":0');
+    expect(v2Input).toContain('"prev":null');
+    expect(v2Input).toContain('"collection":"app.oxy.reputation"');
+  });
+});
+
+describe('computeRecordId — deterministic content address', () => {
+  const base: SignedRecordEnvelope = {
+    version: 2,
+    type: 'reputation_attestation',
+    subject: 'did:web:oxy.so:u:rid',
+    issuer: 'did:web:oxy.so',
+    record: { points: 25 },
+    issuedAt: 1750000000000,
+    seq: 0,
+    prev: null,
+    collection: 'app.oxy.reputation',
+    rkey: 'rt_1',
+    publicKey: '03oxykey',
+    alg: 'ES256K-DER-SHA256',
+    signature: 'sig-is-not-part-of-the-id',
+  };
+
+  it('is a 64-char lowercase hex SHA-256 digest', async () => {
+    const id = await computeRecordId(base);
+    expect(id).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('is deterministic for identical signing fields', async () => {
+    const a = await computeRecordId(base);
+    const b = await computeRecordId(base);
+    expect(a).toBe(b);
+  });
+
+  it('equals sha256 of the canonical signing input (content address, excludes publicKey/signature)', async () => {
+    const id = await computeRecordId(base);
+    const expected = await sha256(signedRecordSigningInput(base));
+    expect(id).toBe(expected);
+    // Changing only signature/publicKey does NOT change the recordId.
+    const sameId = await computeRecordId({
+      ...base,
+      signature: 'totally-different',
+      publicKey: 'different-key',
+    });
+    expect(sameId).toBe(id);
+  });
+
+  it('changes when any signed field changes', async () => {
+    const id = await computeRecordId(base);
+    expect(await computeRecordId({ ...base, seq: 1 })).not.toBe(id);
+    expect(await computeRecordId({ ...base, record: { points: 26 } })).not.toBe(id);
+    expect(await computeRecordId({ ...base, prev: 'a'.repeat(64) })).not.toBe(id);
+  });
+
+  it('a v1 record and a v2 record with the same base fields have different recordIds', async () => {
+    const v1Id = await computeRecordId({
+      version: 1,
+      type: 'profile',
+      subject: 'did:web:oxy.so:u:rid',
+      issuer: 'did:web:oxy.so:u:rid',
+      record: { points: 25 },
+      issuedAt: 1750000000000,
+    });
+    const v2Id = await computeRecordId({
+      version: 2,
+      type: 'profile',
+      subject: 'did:web:oxy.so:u:rid',
+      issuer: 'did:web:oxy.so:u:rid',
+      record: { points: 25 },
+      issuedAt: 1750000000000,
+      seq: 0,
+      prev: null,
+      collection: 'app.oxy.profile',
+      rkey: 'self',
+    });
+    expect(v1Id).not.toBe(v2Id);
+  });
+});
+
+/**
+ * CANONICAL-BYTES FIXTURE — the load-bearing "did the move change anything?"
+ * guard. A fixed private key (a well-known secp256k1 test scalar) signing a
+ * fixed v2 envelope must reproduce these exact bytes. The signer uses RFC 6979
+ * deterministic nonces, so the DER signature is reproducible.
+ */
+describe('canonical-bytes fixture (move-invariance guard)', () => {
+  const PRIVATE_KEY = '4c0883a69102937d6231471b5dbb6204fe5129617082792ae468d01a3f362318';
+  const PUBLIC_KEY =
+    '044e3b81af9c2234cad09d679ce6035ed1392347ce64ce405f5dcd36228a25de6e47fd35c4215d1edf53e6f83de344615ce719bdb0fd878f6ed76f06dd277956de';
+  const FIELDS = {
+    version: 2 as const,
+    type: 'app_record',
+    subject: 'did:web:oxy.so:u:fixture',
+    issuer: 'did:web:oxy.so:u:fixture',
+    record: { hello: 'world', n: 1 },
+    issuedAt: 1750000000000,
+    seq: 0,
+    prev: null as string | null,
+    collection: 'app.mention.feed.post',
+    rkey: 'r1',
+  };
+  const EXPECTED_SIGNING_INPUT =
+    '{"collection":"app.mention.feed.post","issuedAt":1750000000000,"issuer":"did:web:oxy.so:u:fixture","prev":null,"record":{"hello":"world","n":1},"rkey":"r1","seq":0,"subject":"did:web:oxy.so:u:fixture","type":"app_record","version":2}';
+  const EXPECTED_RECORD_ID = '46585cdd862525a1437d1fbd17d060ed053b978bb0f9095a3f22818719cab6d1';
+  const EXPECTED_SIGNATURE =
+    '304602210098643efdead01cb84c9ba2162fc7d013ccdb10fe4ce34fe4c52df9e1cfc9e7f7022100c7a94ac532cff4a61d4301b12aeea0598a47ad2a664a8f521f89d68deda63656';
+
+  it('signing input matches the locked canonical bytes', () => {
+    expect(signedRecordSigningInput(FIELDS)).toBe(EXPECTED_SIGNING_INPUT);
+  });
+
+  it('recordId matches the locked content address', async () => {
+    expect(await computeRecordId(FIELDS)).toBe(EXPECTED_RECORD_ID);
+  });
+
+  it('signEnvelope derives the matching public key and the locked signature', async () => {
+    const env = await signEnvelope(FIELDS, PRIVATE_KEY);
+    expect(env.publicKey).toBe(PUBLIC_KEY);
+    expect(env.alg).toBe('ES256K-DER-SHA256');
+    expect(env.signature).toBe(EXPECTED_SIGNATURE);
+    // The derived key is the standard uncompressed SEC1 point for this scalar.
+    expect(env.publicKey).toBe(deriveSecp256k1PublicKey(PRIVATE_KEY));
+  });
+
+  it('signEnvelope is deterministic (RFC 6979) — same input, same signature', async () => {
+    const a = await signEnvelope(FIELDS, PRIVATE_KEY);
+    const b = await signEnvelope(FIELDS, PRIVATE_KEY);
+    expect(a.signature).toBe(b.signature);
+  });
+
+  it('round-trips: the signed envelope verifies and tampering breaks it', async () => {
+    const env = await signEnvelope(FIELDS, PRIVATE_KEY);
+    await expect(verifyEnvelopeSignature(env)).resolves.toBe(true);
+    await expect(verifyEnvelopeSignature({ ...env, seq: 1 })).resolves.toBe(false);
+    await expect(
+      verifyEnvelopeSignature({ ...env, record: { hello: 'tampered', n: 1 } }),
+    ).resolves.toBe(false);
+  });
+
+  it('low-level signMessage / verifySignature agree over the canonical input', async () => {
+    const sig = await signMessage(EXPECTED_SIGNING_INPUT, PRIVATE_KEY);
+    expect(sig).toBe(EXPECTED_SIGNATURE);
+    await expect(verifySignature(EXPECTED_SIGNING_INPUT, sig, PUBLIC_KEY)).resolves.toBe(true);
+    await expect(verifySignature(EXPECTED_SIGNING_INPUT, sig, 'not-a-key')).resolves.toBe(false);
+    expect(canonicalize(FIELDS)).toBe(EXPECTED_SIGNING_INPUT);
+  });
+
+  /**
+   * A2 type-widening guard: opening the envelope `type` from a closed enum to a
+   * string is canonical-bytes-safe AND lets app records onto the shared grammar.
+   * `signedRecordEnvelopeSchema` (the widened contract) is exercised end-to-end
+   * against the real signer/verifier — the schema change must not reject or alter
+   * a production envelope, and an `app.mention.*` record must now validate.
+   */
+  it('the widened base schema accepts a production identity envelope with unchanged canonical bytes', async () => {
+    const identityFields = {
+      version: 1 as const,
+      type: 'identity',
+      subject: 'did:web:oxy.so:u:u1',
+      issuer: 'did:web:oxy.so:u:u1',
+      record: { handle: '@nate' },
+      issuedAt: 1750000000000,
+    };
+    const signed = await signEnvelope(identityFields, PRIVATE_KEY);
+    // The widened schema accepts the production envelope unchanged.
+    const parsed = signedRecordEnvelopeSchema.safeParse(signed);
+    expect(parsed.success).toBe(true);
+    // Its canonical signing bytes are byte-identical to the locked v1 golden —
+    // the enum→string widening does not touch what the signature covers.
+    expect(signedRecordSigningInput(signed)).toBe(
+      '{"issuedAt":1750000000000,"issuer":"did:web:oxy.so:u:u1","record":{"handle":"@nate"},"subject":"did:web:oxy.so:u:u1","type":"identity","version":1}',
+    );
+    await expect(verifyEnvelopeSignature(signed)).resolves.toBe(true);
+  });
+
+  it('the widened base schema accepts the signed app_record envelope (app.mention.feed.post)', async () => {
+    const signed = await signEnvelope(FIELDS, PRIVATE_KEY);
+    expect(signed.type).toBe('app_record');
+    expect(signed.collection).toBe('app.mention.feed.post');
+    const parsed = signedRecordEnvelopeSchema.safeParse(signed);
+    expect(parsed.success).toBe(true);
+    await expect(verifyEnvelopeSignature(signed)).resolves.toBe(true);
+  });
+});

package/src/__tests__/nodeApp.test.ts

@@ -0,0 +1,410 @@
+/**
+ * `createNodeApp` handler tests — supertest over the generic Express factory,
+ * driven by the in-memory `RecordStore`/`BlobStore` harness + an owner-key
+ * `OwnerAuth`. Covers the well-known manifest, owner-authenticated record writes
+ * (happy path, chaining, wrong-signer + malformed + gap rejection), the
+ * collection allowlist, the batch push, the log cursor/cap, and the blob
+ * pin/serve path with signed-header auth + hash validation.
+ */
+
+import { createHash } from 'node:crypto';
+import { createServer } from 'node:http';
+import { connect, type AddressInfo } from 'node:net';
+import request from 'supertest';
+import { createNodeApp, type NodeAppConfig } from '../node/nodeApp';
+import { computeRecordId } from '../envelope/recordId';
+import {
+  buildSignedEnvelope,
+  createInMemoryNodeStore,
+  createTestOwnerAuth,
+  generateKeyPair,
+  signBlobPin,
+  silentLogger,
+  type TestKeyPair,
+} from './nodeHarness';
+
+function makeConfig(
+  nodePublicKey: string,
+  collections: readonly string[] = [],
+  writeRateLimit?: { windowMs: number; max: number; maxEntries?: number },
+): NodeAppConfig {
+  return {
+    wellKnownPath: '/.well-known/oxy-node.json',
+    protocolId: 'oxy-node/1',
+    serviceType: 'OxyPersonalDataNode',
+    mode: 'self-hosted',
+    nodePublicKey,
+    maxBlobBytes: 25 * 1024 * 1024,
+    collections,
+    writeRateLimit,
+  };
+}
+
+// Apps built during a test own a background rate-limiter sweep timer; track them
+// so `afterEach` can stop the timers and leave no open handles between tests.
+const builtApps: Array<ReturnType<typeof createNodeApp>> = [];
+
+function buildApp(
+  owner: TestKeyPair,
+  collections: readonly string[] = [],
+  writeRateLimit?: { windowMs: number; max: number; maxEntries?: number },
+) {
+  const store = createInMemoryNodeStore();
+  const app = createNodeApp({
+    store,
+    config: makeConfig(owner.publicKey, collections, writeRateLimit),
+    ownerAuth: createTestOwnerAuth(owner.publicKey),
+    logger: silentLogger,
+  });
+  builtApps.push(app);
+  return { app, store };
+}
+
+describe('createNodeApp', () => {
+  let owner: TestKeyPair;
+
+  beforeEach(() => {
+    owner = generateKeyPair();
+  });
+
+  afterEach(() => {
+    for (const app of builtApps.splice(0)) {
+      app.stop();
+    }
+  });
+
+  it('GET /.well-known/oxy-node.json returns identity + liveness (incl. serviceType)', async () => {
+    const { app } = buildApp(owner);
+    const res = await request(app).get('/.well-known/oxy-node.json');
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({
+      nodePublicKey: owner.publicKey,
+      mode: 'self-hosted',
+      version: 'oxy-node/1',
+      serviceType: 'OxyPersonalDataNode',
+      head: null,
+    });
+  });
+
+  it('GET /oxy/head reports an empty chain then advances after a write', async () => {
+    const { app } = buildApp(owner);
+    const empty = await request(app).get('/oxy/head');
+    expect(empty.body).toEqual({ seq: null, headRecordId: null, recordCount: 0 });
+
+    const envelope = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 0, prev: null });
+    const recordId = await computeRecordId(envelope);
+    const write = await request(app).post('/records').send(envelope);
+    expect(write.status).toBe(201);
+    expect(write.body).toEqual({ recordId, seq: 0 });
+
+    const head = await request(app).get('/oxy/head');
+    expect(head.body).toEqual({ seq: 0, headRecordId: recordId, recordCount: 1 });
+  });
+
+  it('POST /records accepts an owner-signed envelope and chains the next one', async () => {
+    const { app } = buildApp(owner);
+    const genesis = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 0, prev: null });
+    const genesisId = await computeRecordId(genesis);
+    await request(app).post('/records').send(genesis).expect(201);
+
+    const second = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 1, prev: genesisId, record: { step: 2 } });
+    const secondId = await computeRecordId(second);
+    const res = await request(app).post('/records').send(second);
+    expect(res.status).toBe(201);
+    expect(res.body).toEqual({ recordId: secondId, seq: 1 });
+  });
+
+  it('POST /records rejects a record signed by a NON-owner key (403 not_owner)', async () => {
+    const { app } = buildApp(owner);
+    const attacker = generateKeyPair();
+    const envelope = await buildSignedEnvelope({ privateKey: attacker.privateKey, seq: 0, prev: null });
+    const res = await request(app).post('/records').send(envelope);
+    expect(res.status).toBe(403);
+    expect(res.body).toEqual({ error: 'not_owner' });
+  });
+
+  it('POST /records rejects a malformed envelope (400 invalid_envelope)', async () => {
+    const { app } = buildApp(owner);
+    const res = await request(app).post('/records').send({ not: 'an envelope' });
+    expect(res.status).toBe(400);
+    expect(res.body).toEqual({ error: 'invalid_envelope' });
+  });
+
+  it('POST /records rejects a chain gap (422 chain_gap)', async () => {
+    const { app } = buildApp(owner);
+    const envelope = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 3, prev: null });
+    const res = await request(app).post('/records').send(envelope);
+    expect(res.status).toBe(422);
+    expect(res.body).toEqual({ error: 'chain_gap' });
+  });
+
+  it('POST /records rejects a foreign collection when an allowlist is set (403)', async () => {
+    const { app } = buildApp(owner, ['app.mention.feed.post']);
+    const inAllow = await buildSignedEnvelope({
+      privateKey: owner.privateKey,
+      seq: 0,
+      prev: null,
+      collection: 'app.mention.feed.post',
+    });
+    await request(app).post('/records').send(inAllow).expect(201);
+
+    const foreign = await buildSignedEnvelope({
+      privateKey: owner.privateKey,
+      seq: 1,
+      prev: await computeRecordId(inAllow),
+      collection: 'app.oxy.identity',
+    });
+    const res = await request(app).post('/records').send(foreign);
+    expect(res.status).toBe(403);
+    expect(res.body).toEqual({ error: 'foreign_collection' });
+  });
+
+  it('POST /sync/push verifies + appends a batch in order', async () => {
+    const { app } = buildApp(owner);
+    const genesis = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 0, prev: null });
+    const second = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 1, prev: await computeRecordId(genesis) });
+    const res = await request(app).post('/sync/push').send({ records: [genesis, second] });
+    expect(res.status).toBe(200);
+    expect(res.body.accepted).toBe(2);
+    expect(res.body.results.every((r: { ok: boolean }) => r.ok)).toBe(true);
+  });
+
+  it('GET /oxy/log returns the ordered log from a cursor and caps the limit', async () => {
+    const { app } = buildApp(owner);
+    let prev: string | null = null;
+    const ids: string[] = [];
+    for (let seq = 0; seq < 4; seq += 1) {
+      const envelope = await buildSignedEnvelope({ privateKey: owner.privateKey, seq, prev, record: { seq } });
+      const id = await computeRecordId(envelope);
+      await request(app).post('/records').send(envelope).expect(201);
+      ids.push(id);
+      prev = id;
+    }
+
+    const full = await request(app).get('/oxy/log');
+    expect(full.body.count).toBe(4);
+    expect(full.body.records.map((entry: { seq: number }) => entry.seq)).toEqual([0, 1, 2, 3]);
+    expect(full.body.records[0].recordId).toBe(ids[0]);
+    expect(full.body.head).toEqual({ seq: 3, headRecordId: ids[3] });
+
+    const capped = await request(app).get('/oxy/log').query({ limit: 2 });
+    expect(capped.body.records.map((entry: { seq: number }) => entry.seq)).toEqual([0, 1]);
+
+    const sinceCursor = await request(app).get('/oxy/log').query({ since: ids[1] });
+    expect(sinceCursor.body.records.map((entry: { seq: number }) => entry.seq)).toEqual([2, 3]);
+
+    const unknownCursor = await request(app).get('/oxy/log').query({ since: 'f'.repeat(64) });
+    expect(unknownCursor.body.records).toEqual([]);
+  });
+
+  it('PUT then GET a blob with owner auth + hash validation', async () => {
+    const { app } = buildApp(owner);
+    const bytes = Buffer.from('a pinned media blob');
+    const hash = createHash('sha256').update(bytes).digest('hex');
+
+    const auth = await signBlobPin(hash, owner);
+    const put = await request(app)
+      .put(`/blobs/${hash}`)
+      .set({
+        'x-oxy-node-public-key': auth.publicKey,
+        'x-oxy-node-signature': auth.signature,
+        'x-oxy-node-timestamp': String(auth.timestamp),
+      })
+      .set('Content-Type', 'application/octet-stream')
+      .send(bytes);
+    expect(put.status).toBe(201);
+    expect(put.body).toEqual({ hash, size: bytes.length });
+
+    const get = await request(app).get(`/blobs/${hash}`).buffer(true).parse((res, cb) => {
+      const chunks: Buffer[] = [];
+      res.on('data', (chunk: Buffer) => chunks.push(chunk));
+      res.on('end', () => cb(null, Buffer.concat(chunks)));
+    });
+    expect(get.status).toBe(200);
+    expect(Buffer.isBuffer(get.body) ? get.body : Buffer.from(get.body)).toEqual(bytes);
+  });
+
+  it('GET /blobs/:hash 404s when absent', async () => {
+    const { app } = buildApp(owner);
+    const hash = createHash('sha256').update(Buffer.from('nope')).digest('hex');
+    const res = await request(app).get(`/blobs/${hash}`);
+    expect(res.status).toBe(404);
+  });
+
+  it('PUT /blobs/:hash rejects bytes that do not hash to the address (400 hash_mismatch)', async () => {
+    const { app } = buildApp(owner);
+    const realBytes = Buffer.from('the actual bytes');
+    const claimedHash = createHash('sha256').update(Buffer.from('some other bytes')).digest('hex');
+
+    const auth = await signBlobPin(claimedHash, owner);
+    const res = await request(app)
+      .put(`/blobs/${claimedHash}`)
+      .set({
+        'x-oxy-node-public-key': auth.publicKey,
+        'x-oxy-node-signature': auth.signature,
+        'x-oxy-node-timestamp': String(auth.timestamp),
+      })
+      .set('Content-Type', 'application/octet-stream')
+      .send(realBytes);
+    expect(res.status).toBe(400);
+    expect(res.body).toEqual({ error: 'hash_mismatch' });
+  });
+
+  it('PUT /blobs/:hash rejects a request with no body framing at all (400 empty_blob)', async () => {
+    // `express.raw` assigns `{}` — not an empty Buffer — when the request
+    // carries no body framing (`typeis.hasBody(req)` is false), so `.length` on
+    // it is `undefined` and an emptiness check alone would let it through to
+    // `store.putBlob` and to `size: bytes.length` in the 201 payload. CodeQL
+    // flags that `.length` (js/type-confusion-through-parameter-tampering,
+    // alert #473) because it does not model `Buffer.isBuffer` as a narrowing
+    // guard; this pins the guard that makes the flag a false positive.
+    //
+    // The request is written onto a raw socket because neither supertest nor
+    // `http.request` can express it — both add a `Content-Length` or a
+    // `Transfer-Encoding`, either of which makes `hasBody` true and produces an
+    // empty Buffer instead, exercising only the other half of the guard.
+    const { app, store } = buildApp(owner);
+    const bytes = Buffer.from('a blob that never gets sent');
+    const hash = createHash('sha256').update(bytes).digest('hex');
+    const auth = await signBlobPin(hash, owner);
+
+    const server = createServer(app);
+    await new Promise<void>((resolve) => { server.listen(0, '127.0.0.1', resolve); });
+    const { port } = server.address() as AddressInfo;
+
+    const raw = await new Promise<string>((resolve, reject) => {
+      const socket = connect(port, '127.0.0.1', () => {
+        socket.write(
+          [
+            `PUT /blobs/${hash} HTTP/1.1`,
+            'Host: 127.0.0.1',
+            `x-oxy-node-public-key: ${auth.publicKey}`,
+            `x-oxy-node-signature: ${auth.signature}`,
+            `x-oxy-node-timestamp: ${auth.timestamp}`,
+            'Connection: close',
+            '',
+            '',
+          ].join('\r\n')
+        );
+      });
+      let received = '';
+      socket.setEncoding('utf8');
+      socket.on('data', (chunk: string) => { received += chunk; });
+      socket.on('error', reject);
+      socket.on('end', () => resolve(received));
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.close((err) => (err ? reject(err) : resolve()));
+    });
+
+    expect(raw).toContain('HTTP/1.1 400');
+    expect(raw).toContain('empty_blob');
+    // And nothing was pinned under that address.
+    expect(await store.getBlob(hash)).toBeNull();
+  });
+
+  it('PUT /blobs/:hash rejects an empty body (400 empty_blob)', async () => {
+    const { app, store } = buildApp(owner);
+    const bytes = Buffer.from('another blob that never gets sent');
+    const hash = createHash('sha256').update(bytes).digest('hex');
+    const auth = await signBlobPin(hash, owner);
+
+    const res = await request(app)
+      .put(`/blobs/${hash}`)
+      .set({
+        'x-oxy-node-public-key': auth.publicKey,
+        'x-oxy-node-signature': auth.signature,
+        'x-oxy-node-timestamp': String(auth.timestamp),
+      })
+      .set('Content-Type', 'application/octet-stream')
+      .send(Buffer.alloc(0));
+
+    expect(res.status).toBe(400);
+    expect(res.body).toEqual({ error: 'empty_blob' });
+    expect(await store.getBlob(hash)).toBeNull();
+  });
+
+  it('PUT /blobs/:hash rejects a non-owner signature (403)', async () => {
+    const { app } = buildApp(owner);
+    const bytes = Buffer.from('blob from an impostor');
+    const hash = createHash('sha256').update(bytes).digest('hex');
+    const attacker = generateKeyPair();
+
+    const auth = await signBlobPin(hash, attacker);
+    const res = await request(app)
+      .put(`/blobs/${hash}`)
+      .set({
+        'x-oxy-node-public-key': auth.publicKey,
+        'x-oxy-node-signature': auth.signature,
+        'x-oxy-node-timestamp': String(auth.timestamp),
+      })
+      .set('Content-Type', 'application/octet-stream')
+      .send(bytes);
+    expect(res.status).toBe(403);
+    expect(res.body).toEqual({ error: 'unauthorized' });
+  });
+
+  it('PUT /blobs/:hash requires owner-auth headers (401)', async () => {
+    const { app } = buildApp(owner);
+    const bytes = Buffer.from('unauthenticated');
+    const hash = createHash('sha256').update(bytes).digest('hex');
+    const res = await request(app)
+      .put(`/blobs/${hash}`)
+      .set('Content-Type', 'application/octet-stream')
+      .send(bytes);
+    expect(res.status).toBe(401);
+  });
+
+  it('rate-limits the owner write route after the configured budget (429 rate_limited)', async () => {
+    // A tiny per-window budget makes the limiter deterministic: the 3rd write
+    // within the window is rejected 429 BEFORE the handler runs, regardless of
+    // each request's chain outcome.
+    const { app } = buildApp(owner, [], { windowMs: 60_000, max: 2 });
+    const envelope = await buildSignedEnvelope({ privateKey: owner.privateKey, seq: 0, prev: null });
+
+    const first = await request(app).post('/records').send(envelope);
+    expect(first.status).toBe(201);
+    // Second consumes the last slot (a chain_conflict on the replayed genesis,
+    // but it still counts against the budget — the limiter precedes the handler).
+    const second = await request(app).post('/records').send(envelope);
+    expect(second.status).not.toBe(429);
+    // Third exceeds the budget.
+    const third = await request(app).post('/records').send(envelope);
+    expect(third.status).toBe(429);
+    expect(third.body).toEqual({ error: 'rate_limited' });
+  });
+
+  it('GET /oxy/log coerces an array `since` param to its first value (no 500)', async () => {
+    const { app } = buildApp(owner);
+    let prev: string | null = null;
+    const ids: string[] = [];
+    for (let seq = 0; seq < 3; seq += 1) {
+      const envelope = await buildSignedEnvelope({ privateKey: owner.privateKey, seq, prev, record: { seq } });
+      const id = await computeRecordId(envelope);
+      await request(app).post('/records').send(envelope).expect(201);
+      ids.push(id);
+      prev = id;
+    }
+
+    // `?since[]=<id1>&since[]=<id2>` arrives as a string[] — the handler must
+    // take the FIRST value (a tampered array can never cause type confusion).
+    const res = await request(app).get('/oxy/log').query({ 'since[]': [ids[0], ids[2]] });
+    expect(res.status).toBe(200);
+    // Cursor resolves off ids[0] → records strictly after seq 0 → [1, 2].
+    expect(res.body.records.map((entry: { seq: number }) => entry.seq)).toEqual([1, 2]);
+  });
+
+  it('GET /oxy/log treats an array `limit` param as its first value', async () => {
+    const { app } = buildApp(owner);
+    let prev: string | null = null;
+    for (let seq = 0; seq < 4; seq += 1) {
+      const envelope = await buildSignedEnvelope({ privateKey: owner.privateKey, seq, prev, record: { seq } });
+      await request(app).post('/records').send(envelope).expect(201);
+      prev = await computeRecordId(envelope);
+    }
+
+    const res = await request(app).get('/oxy/log').query({ 'limit[]': ['2', '99'] });
+    expect(res.status).toBe(200);
+    expect(res.body.records.map((entry: { seq: number }) => entry.seq)).toEqual([0, 1]);
+  });
+});