@oxy.so/protocol 1.0.0

package/src/__tests__/canonicalJson.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Canonical JSON tests.
+ *
+ * The whole point of `canonicalize` is that two structurally-equal values
+ * produce identical strings regardless of how their keys were ordered, so a
+ * client which signs and a server which verifies agree on the signing input.
+ * These tests pin that determinism, the array-order guarantee, the nesting
+ * behaviour, and the JSON value/omit semantics.
+ */
+
+import { canonicalize } from '../envelope/canonicalJson';
+
+describe('canonicalize', () => {
+  describe('object key ordering', () => {
+    it('produces identical output regardless of insertion order', () => {
+      const a = canonicalize({ b: 1, a: 2, c: 3 });
+      const b = canonicalize({ c: 3, a: 2, b: 1 });
+      const c = canonicalize({ a: 2, b: 1, c: 3 });
+      expect(a).toBe(b);
+      expect(b).toBe(c);
+      expect(a).toBe('{"a":2,"b":1,"c":3}');
+    });
+
+    it('sorts keys recursively at every level', () => {
+      const value = {
+        z: { y: 1, x: 2 },
+        a: { c: 3, b: { e: 5, d: 4 } },
+      };
+      expect(canonicalize(value)).toBe(
+        '{"a":{"b":{"d":4,"e":5},"c":3},"z":{"x":2,"y":1}}',
+      );
+    });
+
+    it('is order-insensitive across deep nesting', () => {
+      const first = canonicalize({
+        outer: { inner: { p: 1, q: 2 }, lead: 'x' },
+        meta: { issuedAt: 10, version: 1 },
+      });
+      const second = canonicalize({
+        meta: { version: 1, issuedAt: 10 },
+        outer: { lead: 'x', inner: { q: 2, p: 1 } },
+      });
+      expect(first).toBe(second);
+    });
+  });
+
+  describe('array ordering', () => {
+    it('preserves array element order (never sorts arrays)', () => {
+      expect(canonicalize([3, 1, 2])).toBe('[3,1,2]');
+      expect(canonicalize(['b', 'a', 'c'])).toBe('["b","a","c"]');
+    });
+
+    it('distinguishes arrays that differ only in order', () => {
+      expect(canonicalize([1, 2])).not.toBe(canonicalize([2, 1]));
+    });
+
+    it('canonicalizes objects inside arrays without reordering the array', () => {
+      const value = [
+        { b: 1, a: 2 },
+        { d: 3, c: 4 },
+      ];
+      expect(canonicalize(value)).toBe('[{"a":2,"b":1},{"c":4,"d":3}]');
+    });
+  });
+
+  describe('primitives', () => {
+    it('serializes null, booleans, strings and numbers as JSON', () => {
+      expect(canonicalize(null)).toBe('null');
+      expect(canonicalize(true)).toBe('true');
+      expect(canonicalize(false)).toBe('false');
+      expect(canonicalize('hi')).toBe('"hi"');
+      expect(canonicalize(42)).toBe('42');
+      expect(canonicalize(-1.5)).toBe('-1.5');
+      expect(canonicalize(0)).toBe('0');
+    });
+
+    it('escapes strings the same way JSON does', () => {
+      expect(canonicalize('a"b\\c\n')).toBe(JSON.stringify('a"b\\c\n'));
+    });
+  });
+
+  describe('JSON value/omit semantics', () => {
+    it('omits object properties whose value is undefined', () => {
+      expect(canonicalize({ a: 1, b: undefined, c: 3 })).toBe('{"a":1,"c":3}');
+    });
+
+    it('renders undefined array elements as null (preserving length)', () => {
+      expect(canonicalize([1, undefined, 3])).toBe('[1,null,3]');
+    });
+
+    it('respects toJSON (Date and its ISO string canonicalize identically)', () => {
+      const date = new Date('2026-06-26T00:00:00.000Z');
+      expect(canonicalize(date)).toBe(JSON.stringify(date.toISOString()));
+      expect(canonicalize({ at: date })).toBe(
+        canonicalize({ at: '2026-06-26T00:00:00.000Z' }),
+      );
+    });
+  });
+
+  describe('rejects values outside the JSON data model', () => {
+    it('throws on non-finite numbers', () => {
+      expect(() => canonicalize(Number.NaN)).toThrow();
+      expect(() => canonicalize(Number.POSITIVE_INFINITY)).toThrow();
+      expect(() => canonicalize({ x: Number.POSITIVE_INFINITY })).toThrow();
+    });
+
+    it('throws on bigint', () => {
+      expect(() => canonicalize(BigInt(1))).toThrow();
+    });
+
+    it('throws on a bare undefined / function at the top level', () => {
+      expect(() => canonicalize(undefined)).toThrow();
+      expect(() => canonicalize(() => 1)).toThrow();
+    });
+  });
+});

package/src/__tests__/chain.test.ts

@@ -0,0 +1,279 @@
+/**
+ * Chain engine tests — continuity, the verification state machine, and
+ * verify-then-append, all driven over STUB stores + resolvers (no DB, no app
+ * specifics). These lock the engine behaviour the oxy-api adapter relies on:
+ * the same rejection reasons, the same ordering, and the `chain_conflict`
+ * backstop surfaced from the store.
+ */
+
+import { generateSecp256k1KeyPair } from '../secp256k1';
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import {
+  checkContinuity,
+  verifyEnvelope,
+  verifyAndAppend,
+  isAuthorizedKey,
+  type ChainHead,
+  type RecordStore,
+  type AppendOutcome,
+  type ResolvedVerificationMethods,
+  type VerificationMethodResolver,
+} from '../index';
+import { signEnvelope } from '../envelope/sign';
+
+const keyPair = generateSecp256k1KeyPair();
+const PUBLIC_KEY = keyPair.publicKey;
+const PRIVATE_KEY = keyPair.privateKey;
+
+const SUBJECT = 'did:web:oxy.so:u:u1';
+const CUSTODIAL_ISSUER = 'did:web:oxy.so';
+const custodialKeyPair = generateSecp256k1KeyPair();
+const CUSTODIAL_PUBLIC_KEY = custodialKeyPair.publicKey;
+const CUSTODIAL_PRIVATE_KEY = custodialKeyPair.privateKey;
+
+type V2Fields = Parameters<typeof signEnvelope>[0];
+
+function v2Fields(overrides: Partial<V2Fields> = {}): V2Fields {
+  return {
+    version: 2,
+    type: 'app_record',
+    subject: SUBJECT,
+    issuer: SUBJECT,
+    record: { hello: 'world' },
+    issuedAt: 1_700_000_000_000,
+    seq: 0,
+    prev: null,
+    collection: 'app.mention.feed.post',
+    rkey: 'r1',
+    ...overrides,
+  };
+}
+
+/** A resolver that authorizes the subject's own key + an optional custodial key. */
+function resolver(resolved: ResolvedVerificationMethods | null): VerificationMethodResolver {
+  return { resolve: async () => resolved };
+}
+
+const SELF_RESOLVED: ResolvedVerificationMethods = {
+  currentPublicKeys: [PUBLIC_KEY],
+  custodialIssuer: CUSTODIAL_ISSUER,
+  custodialPublicKey: CUSTODIAL_PUBLIC_KEY,
+};
+
+/** A store stub: no chain, no prior record, append echoes a fixed outcome. */
+function stubStore(overrides: Partial<RecordStore> = {}): RecordStore {
+  return {
+    getHead: async () => null,
+    latestIssuedAtForKey: async () => null,
+    append: async (_subject, env, recordId): Promise<AppendOutcome> => ({
+      ok: true,
+      recordId,
+      seq: typeof env.seq === 'number' ? env.seq : -1,
+    }),
+    getLogSince: async () => [],
+    resolveCursorSeq: async () => null,
+    materializeCurrent: async () => null,
+    ...overrides,
+  };
+}
+
+const FAR_FUTURE_NOW = 1_700_000_000_000 + 1_000;
+
+describe('checkContinuity', () => {
+  const head = (headRecordId: string, seq: number): ChainHead => ({ headRecordId, seq, recordCount: seq + 1 });
+
+  it('accepts a v1 record (unchained) regardless of head', async () => {
+    const env = await signEnvelope(
+      { version: 1, type: 'identity', subject: SUBJECT, issuer: SUBJECT, record: { a: 1 }, issuedAt: 1 },
+      PRIVATE_KEY,
+    );
+    expect(checkContinuity(head('a'.repeat(64), 3), env)).toEqual({ ok: true });
+  });
+
+  it('accepts a genesis when there is no head', async () => {
+    const env = await signEnvelope(v2Fields(), PRIVATE_KEY);
+    expect(checkContinuity(null, env)).toEqual({ ok: true });
+  });
+
+  it('rejects a non-genesis with no head as chain_gap', async () => {
+    const env = await signEnvelope(v2Fields({ seq: 1, prev: 'a'.repeat(64) }), PRIVATE_KEY);
+    expect(checkContinuity(null, env)).toEqual({ ok: false, reason: 'chain_gap' });
+  });
+
+  it('rejects a wrong prev as chain_fork', async () => {
+    const env = await signEnvelope(v2Fields({ seq: 1, prev: 'b'.repeat(64) }), PRIVATE_KEY);
+    expect(checkContinuity(head('a'.repeat(64), 0), env)).toEqual({ ok: false, reason: 'chain_fork' });
+  });
+
+  it('rejects a seq gap (correct prev) as bad_seq', async () => {
+    const env = await signEnvelope(v2Fields({ seq: 5, prev: 'a'.repeat(64) }), PRIVATE_KEY);
+    expect(checkContinuity(head('a'.repeat(64), 0), env)).toEqual({ ok: false, reason: 'bad_seq' });
+  });
+
+  it('accepts a correct extension', async () => {
+    const env = await signEnvelope(v2Fields({ seq: 1, prev: 'a'.repeat(64) }), PRIVATE_KEY);
+    expect(checkContinuity(head('a'.repeat(64), 0), env)).toEqual({ ok: true });
+  });
+});
+
+describe('isAuthorizedKey', () => {
+  it('accepts a self-issued record signed by a current key', async () => {
+    const env = await signEnvelope(v2Fields(), PRIVATE_KEY);
+    expect(isAuthorizedKey(SELF_RESOLVED, env)).toEqual({ ok: true });
+  });
+
+  it('rejects a self-issued record whose key is not a current VM', async () => {
+    const env = await signEnvelope(v2Fields(), PRIVATE_KEY);
+    expect(isAuthorizedKey({ currentPublicKeys: ['cafe'] }, env)).toEqual({
+      ok: false,
+      reason: 'public_key_not_a_current_verification_method',
+    });
+  });
+
+  it('accepts a custodial record signed by the custodial key', async () => {
+    const env = await signEnvelope(v2Fields({ issuer: CUSTODIAL_ISSUER }), CUSTODIAL_PRIVATE_KEY);
+    expect(isAuthorizedKey(SELF_RESOLVED, env)).toEqual({ ok: true });
+  });
+
+  it('rejects a custodial record signed by the wrong key', async () => {
+    const env = await signEnvelope(v2Fields({ issuer: CUSTODIAL_ISSUER }), PRIVATE_KEY);
+    expect(isAuthorizedKey(SELF_RESOLVED, env)).toEqual({
+      ok: false,
+      reason: 'public_key_not_a_current_verification_method',
+    });
+  });
+
+  it('rejects an unknown issuer as untrusted_issuer', async () => {
+    const env = await signEnvelope(v2Fields({ issuer: 'did:web:evil.example' }), PRIVATE_KEY);
+    expect(isAuthorizedKey(SELF_RESOLVED, env)).toEqual({ ok: false, reason: 'untrusted_issuer' });
+  });
+
+  it('rejects when the subject cannot be resolved (null) as untrusted_issuer', async () => {
+    const env = await signEnvelope(v2Fields(), PRIVATE_KEY);
+    expect(isAuthorizedKey(null, env)).toEqual({ ok: false, reason: 'untrusted_issuer' });
+  });
+});
+
+describe('verifyEnvelope', () => {
+  it('accepts a fresh, well-signed genesis record', async () => {
+    const env = await signEnvelope(v2Fields(), PRIVATE_KEY);
+    await expect(verifyEnvelope(stubStore(), resolver(SELF_RESOLVED), env, { now: FAR_FUTURE_NOW })).resolves.toEqual({
+      ok: true,
+    });
+  });
+
+  it('rejects a malformed envelope as invalid_envelope', async () => {
+    const env = await signEnvelope(v2Fields(), PRIVATE_KEY);
+    // v2 envelope missing its required chain `seq` fails the base schema.
+    const malformed = { ...env, seq: undefined } as unknown as SignedRecordEnvelope;
+    await expect(verifyEnvelope(stubStore(), resolver(SELF_RESOLVED), malformed)).resolves.toEqual({
+      ok: false,
+      reason: 'invalid_envelope',
+    });
+  });
+
+  // A v2 envelope MUST carry seq/collection/rkey. The base schema enforces this,
+  // and the engine has a defense-in-depth guard (verify.ts) that re-checks them
+  // AFTER the signature check. These lock the observable contract: a properly
+  // SIGNED v2 envelope with a required chain field stripped is rejected
+  // `invalid_envelope` — the engine never appends it on ANY missing field.
+  it.each(['seq', 'collection', 'rkey'] as const)(
+    'rejects a signed v2 envelope missing `%s` as invalid_envelope',
+    async (field) => {
+      const env = await signEnvelope(v2Fields(), PRIVATE_KEY);
+      // Strip the field AFTER signing, so the envelope's signature is still
+      // internally valid — the rejection is purely the missing-chain-field guard.
+      const stripped = { ...env };
+      delete (stripped as Record<string, unknown>)[field];
+      await expect(
+        verifyEnvelope(stubStore(), resolver(SELF_RESOLVED), stripped as SignedRecordEnvelope, { now: FAR_FUTURE_NOW }),
+      ).resolves.toEqual({ ok: false, reason: 'invalid_envelope' });
+    },
+  );
+
+  it('rejects a tampered record as bad_signature', async () => {
+    const env = await signEnvelope(v2Fields(), PRIVATE_KEY);
+    const tampered: SignedRecordEnvelope = { ...env, record: { hello: 'tampered' } };
+    await expect(verifyEnvelope(stubStore(), resolver(SELF_RESOLVED), tampered)).resolves.toEqual({
+      ok: false,
+      reason: 'bad_signature',
+    });
+  });
+
+  it('rejects an unauthorized key as public_key_not_a_current_verification_method', async () => {
+    const env = await signEnvelope(v2Fields(), PRIVATE_KEY);
+    await expect(
+      verifyEnvelope(stubStore(), resolver({ currentPublicKeys: ['cafe'] }), env, { now: FAR_FUTURE_NOW }),
+    ).resolves.toEqual({ ok: false, reason: 'public_key_not_a_current_verification_method' });
+  });
+
+  it('rejects an untrusted issuer', async () => {
+    const env = await signEnvelope(v2Fields({ issuer: 'did:web:evil.example' }), PRIVATE_KEY);
+    await expect(
+      verifyEnvelope(stubStore(), resolver(SELF_RESOLVED), env, { now: FAR_FUTURE_NOW }),
+    ).resolves.toEqual({ ok: false, reason: 'untrusted_issuer' });
+  });
+
+  it('rejects an issuedAt too far in the future', async () => {
+    const env = await signEnvelope(v2Fields({ issuedAt: 2_000_000_000_000 }), PRIVATE_KEY);
+    await expect(
+      verifyEnvelope(stubStore(), resolver(SELF_RESOLVED), env, { now: FAR_FUTURE_NOW }),
+    ).resolves.toEqual({ ok: false, reason: 'issued_in_future' });
+  });
+
+  it('rejects an issuedAt not newer than the latest stored record as stale_issued_at', async () => {
+    const env = await signEnvelope(v2Fields({ issuedAt: 1_700_000_000_000 }), PRIVATE_KEY);
+    const store = stubStore({ latestIssuedAtForKey: async () => 1_700_000_000_000 });
+    await expect(verifyEnvelope(store, resolver(SELF_RESOLVED), env, { now: FAR_FUTURE_NOW })).resolves.toEqual({
+      ok: false,
+      reason: 'stale_issued_at',
+    });
+  });
+
+  it('rejects a non-genesis record with no head as chain_gap', async () => {
+    const env = await signEnvelope(v2Fields({ seq: 1, prev: 'a'.repeat(64) }), PRIVATE_KEY);
+    await expect(
+      verifyEnvelope(stubStore(), resolver(SELF_RESOLVED), env, { now: FAR_FUTURE_NOW }),
+    ).resolves.toEqual({ ok: false, reason: 'chain_gap' });
+  });
+});
+
+describe('verifyAndAppend', () => {
+  it('verifies then appends, returning the store outcome with the computed recordId', async () => {
+    const env = await signEnvelope(v2Fields(), PRIVATE_KEY);
+    const append = jest.fn(
+      async (_s: string, e: SignedRecordEnvelope, recordId: string): Promise<AppendOutcome> => ({
+        ok: true,
+        recordId,
+        seq: e.seq ?? -1,
+      }),
+    );
+    const store = stubStore({ append });
+    const result = await verifyAndAppend(store, resolver(SELF_RESOLVED), env, { now: FAR_FUTURE_NOW });
+    expect(result.ok).toBe(true);
+    expect(append).toHaveBeenCalledTimes(1);
+    const [subject, passedEnv, recordId] = append.mock.calls[0];
+    expect(subject).toBe(SUBJECT);
+    expect(passedEnv).toBe(env);
+    expect(recordId).toMatch(/^[0-9a-f]{64}$/);
+    expect(result).toEqual({ ok: true, recordId, seq: 0 });
+  });
+
+  it('does NOT append when verification fails', async () => {
+    const tampered = { ...(await signEnvelope(v2Fields(), PRIVATE_KEY)), record: { x: 'tampered' } };
+    const append = jest.fn();
+    const store = stubStore({ append });
+    const result = await verifyAndAppend(store, resolver(SELF_RESOLVED), tampered, { now: FAR_FUTURE_NOW });
+    expect(result).toEqual({ ok: false, reason: 'bad_signature' });
+    expect(append).not.toHaveBeenCalled();
+  });
+
+  it('surfaces the store chain_conflict backstop', async () => {
+    const env = await signEnvelope(v2Fields(), PRIVATE_KEY);
+    const store = stubStore({ append: async () => ({ ok: false, reason: 'chain_conflict' }) });
+    await expect(verifyAndAppend(store, resolver(SELF_RESOLVED), env, { now: FAR_FUTURE_NOW })).resolves.toEqual({
+      ok: false,
+      reason: 'chain_conflict',
+    });
+  });
+});

package/src/__tests__/didWebResolver.test.ts

@@ -0,0 +1,132 @@
+/**
+ * `createDidWebResolver` tests — `did:web` → `did.json` URL mapping, and the
+ * resolution of a fetched DID document to its current verification keys, driven
+ * by a STUB `NodeFetch` (no network). Locks the multi-subject authorization
+ * input the chain engine consults on relay/ingest paths.
+ */
+
+import type { DidDocument } from '@oxy.so/contracts';
+import { createDidWebResolver, didWebToUrl } from '../node/didWebResolver';
+import type { NodeFetch, NodeFetchResponse } from '../node/httpFetch';
+
+const SUBJECT = 'did:web:node.example:u:owner';
+const KEY_A = `04${'a'.repeat(128)}`;
+const KEY_B = `04${'b'.repeat(128)}`;
+
+function didDoc(overrides: Partial<DidDocument> = {}): DidDocument {
+  return {
+    '@context': ['https://www.w3.org/ns/did/v1'],
+    id: SUBJECT,
+    controller: [SUBJECT],
+    verificationMethod: [
+      { id: `${SUBJECT}#key-1`, type: 'EcdsaSecp256k1VerificationKey2019', controller: SUBJECT, publicKeyHex: KEY_A },
+    ],
+    authentication: [`${SUBJECT}#key-1`],
+    assertionMethod: [`${SUBJECT}#key-1`],
+    alsoKnownAs: [],
+    service: [],
+    ...overrides,
+  };
+}
+
+function jsonResponse(obj: unknown, status = 200): NodeFetchResponse {
+  return {
+    status,
+    headers: {},
+    body: (async function* () {
+      yield Buffer.from(JSON.stringify(obj));
+    })(),
+    destroy() {},
+  };
+}
+
+describe('didWebToUrl', () => {
+  it('maps an apex did:web to its well-known did.json', () => {
+    expect(didWebToUrl('did:web:example.com')).toBe('https://example.com/.well-known/did.json');
+  });
+
+  it('maps a pathed did:web to a path did.json', () => {
+    expect(didWebToUrl('did:web:example.com:u:123')).toBe('https://example.com/u/123/did.json');
+  });
+
+  it('decodes a %3A port in the host segment', () => {
+    expect(didWebToUrl('did:web:localhost%3A3000')).toBe('https://localhost:3000/.well-known/did.json');
+  });
+
+  it('returns null for a non-did:web identifier', () => {
+    expect(didWebToUrl('did:key:z6Mk')).toBeNull();
+    expect(didWebToUrl('not-a-did')).toBeNull();
+  });
+});
+
+describe('createDidWebResolver', () => {
+  it('resolves a subject to the verification keys in its DID document', async () => {
+    const calls: string[] = [];
+    const fetch: NodeFetch = async (url) => {
+      calls.push(url);
+      return jsonResponse(didDoc());
+    };
+    const resolver = createDidWebResolver(fetch);
+    const resolved = await resolver.resolve(SUBJECT);
+    expect(resolved).toEqual({ currentPublicKeys: [KEY_A] });
+    expect(calls).toEqual(['https://node.example/u/owner/did.json']);
+  });
+
+  it('collects every assertionMethod key (deduped)', async () => {
+    const doc = didDoc({
+      verificationMethod: [
+        { id: `${SUBJECT}#key-1`, type: 'EcdsaSecp256k1VerificationKey2019', controller: SUBJECT, publicKeyHex: KEY_A },
+        { id: `${SUBJECT}#key-2`, type: 'EcdsaSecp256k1VerificationKey2019', controller: SUBJECT, publicKeyHex: KEY_B },
+      ],
+      assertionMethod: [`${SUBJECT}#key-1`, `${SUBJECT}#key-2`],
+    });
+    const resolver = createDidWebResolver(async () => jsonResponse(doc));
+    expect(await resolver.resolve(SUBJECT)).toEqual({ currentPublicKeys: [KEY_A, KEY_B] });
+  });
+
+  it('ignores a Multikey VM and collects only the secp256k1 hex keys', async () => {
+    // An atproto-bridged document carries an extra `Multikey` VM (the SAME key in
+    // multibase form, no `publicKeyHex`). The resolver must skip it and resolve to
+    // the hex signing key only.
+    const doc = didDoc({
+      verificationMethod: [
+        { id: `${SUBJECT}#key-1`, type: 'EcdsaSecp256k1VerificationKey2019', controller: SUBJECT, publicKeyHex: KEY_A },
+        { id: `${SUBJECT}#atproto`, type: 'Multikey', controller: SUBJECT, publicKeyMultibase: 'zQ3shFakeMultibaseKey' },
+      ],
+      authentication: [`${SUBJECT}#key-1`, `${SUBJECT}#atproto`],
+      assertionMethod: [`${SUBJECT}#key-1`, `${SUBJECT}#atproto`],
+    });
+    const resolver = createDidWebResolver(async () => jsonResponse(doc));
+    expect(await resolver.resolve(SUBJECT)).toEqual({ currentPublicKeys: [KEY_A] });
+  });
+
+  it('returns null for a non-did:web subject (no fetch)', async () => {
+    const fetch = jest.fn();
+    const resolver = createDidWebResolver(fetch as unknown as NodeFetch);
+    expect(await resolver.resolve('did:key:z6Mk')).toBeNull();
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('returns null on a non-2xx did.json fetch', async () => {
+    const resolver = createDidWebResolver(async () => jsonResponse({ error: 'nope' }, 404));
+    expect(await resolver.resolve(SUBJECT)).toBeNull();
+  });
+
+  it('returns null when the document id does not match the subject', async () => {
+    const resolver = createDidWebResolver(async () => jsonResponse(didDoc({ id: 'did:web:other.example' })));
+    expect(await resolver.resolve(SUBJECT)).toBeNull();
+  });
+
+  it('returns null and reports onError when the fetch throws', async () => {
+    const onError = jest.fn();
+    const boom = new Error('ECONNREFUSED');
+    const resolver = createDidWebResolver(
+      async () => {
+        throw boom;
+      },
+      { onError },
+    );
+    expect(await resolver.resolve(SUBJECT)).toBeNull();
+    expect(onError).toHaveBeenCalledWith(boom, SUBJECT);
+  });
+});