@oxyhq/core 3.11.0 → 3.12.0

package/dist/types/utils/profileLinks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Normalized profile link shape for display.
+ *
+ * `id` is a stable key for list rendering (the source entry's id when present,
+ * otherwise the source index as a string). `url` is always a non-empty string.
+ */
+export interface ProfileLink {
+    id: string;
+    title?: string;
+    url: string;
+}
+/** Source shape of a single `User.linksMetadata` entry. */
+export interface ProfileLinkMetadata {
+    url: string;
+    title?: string;
+    description?: string;
+    image?: string;
+    id?: string;
+}
+/**
+ * Normalizes a user's profile links into a clean display shape.
+ *
+ * Pure, no side effects, no I/O.
+ *
+ * - Prefers `linksMetadata` when it is a non-empty array: maps each entry to
+ *   `{ id, title, url }`, using `entry.id` when present and falling back to the
+ *   entry index. Entries without a non-empty string `url` are dropped.
+ * - Otherwise falls back to the legacy `links` string array: maps each string to
+ *   `{ id: <index>, url }` (no title). Empty/non-string values are dropped.
+ * - Returns `[]` when both are absent or empty (including when `linksMetadata`
+ *   is present but every entry is dropped — it does NOT fall back to `links`).
+ *
+ * URLs are trimmed and blanks are filtered out. This does NOT add a scheme such
+ * as `https://`; prefixing is a display concern left to the caller.
+ */
+export declare function normalizeProfileLinks(linksMetadata?: ProfileLinkMetadata[], links?: string[]): ProfileLink[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -98,7 +98,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.3.0",
+    "@oxyhq/contracts": "0.4.0",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",

package/src/crypto/__tests__/signedRecord.test.ts

@@ -11,7 +11,7 @@
 import { ec as EC } from 'elliptic';
 import type { SignedRecordEnvelope } from '@oxyhq/contracts';
 import { KeyManager } from '../keyManager';
-import { SignatureService, signedRecordSigningInput } from '../signatureService';
+import { SignatureService, signedRecordSigningInput, computeRecordId } from '../signatureService';
 import { canonicalize } from '../canonicalJson';
 
 const ec = new EC('secp256k1');
@@ -123,3 +123,223 @@ describe('SignatureService.signRecord / verifyRecord', () => {
     ).rejects.toThrow(/No identity found/);
   });
 });
+
+/**
+ * Critical regression guard: the v1 signing input MUST be byte-identical to the
+ * original scheme. Every `identity`/`profile` record already in production was
+ * signed over exactly these bytes, so any change to {@link signedRecordSigningInput}
+ * for v1 would invalidate them all. This locks the exact canonical string.
+ */
+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}',
+    );
+  });
+});
+
+describe('SignatureService.signRecordV2 / verifyRecord (v2 hash chain)', () => {
+  const keyPair = ec.genKeyPair();
+  const publicKey = keyPair.getPublic('hex');
+
+  beforeEach(() => {
+    jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(publicKey);
+    jest.spyOn(KeyManager, 'getKeyPairObject').mockResolvedValue(keyPair);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  const chain = {
+    seq: 0,
+    prev: null as string | null,
+    collection: 'app.oxy.reputation',
+    rkey: 'rt_1',
+  };
+
+  it('builds a well-formed v2 envelope carrying the chain fields', async () => {
+    const subject = 'did:web:oxy.so:u:abc123';
+    const envelope = await SignatureService.signRecordV2(
+      'reputation_attestation',
+      subject,
+      { points: 25 },
+      chain,
+    );
+
+    expect(envelope.version).toBe(2);
+    expect(envelope.type).toBe('reputation_attestation');
+    expect(envelope.subject).toBe(subject);
+    expect(envelope.issuer).toBe(subject); // self-issued
+    expect(envelope.seq).toBe(0);
+    expect(envelope.prev).toBeNull();
+    expect(envelope.collection).toBe('app.oxy.reputation');
+    expect(envelope.rkey).toBe('rt_1');
+    expect(envelope.publicKey).toBe(publicKey);
+    expect(envelope.alg).toBe('ES256K-DER-SHA256');
+    expect(typeof envelope.signature).toBe('string');
+  });
+
+  it('round-trips: a freshly signed v2 record verifies', async () => {
+    const envelope = await SignatureService.signRecordV2(
+      'validation_verdict',
+      'did:web:oxy.so:u:v1',
+      { verdict: 'approve' },
+      { seq: 3, prev: 'a'.repeat(64), collection: 'app.oxy.validation', rkey: 'req_9' },
+    );
+    await expect(SignatureService.verifyRecord(envelope)).resolves.toBe(true);
+  });
+
+  it('covers the chain fields in the signed bytes (tampering breaks verify)', async () => {
+    const envelope = await SignatureService.signRecordV2(
+      'reputation_attestation',
+      'did:web:oxy.so:u:t1',
+      { points: 8 },
+      chain,
+    );
+
+    await expect(
+      SignatureService.verifyRecord({ ...envelope, seq: 1 }),
+    ).resolves.toBe(false);
+    await expect(
+      SignatureService.verifyRecord({ ...envelope, prev: 'b'.repeat(64) }),
+    ).resolves.toBe(false);
+    await expect(
+      SignatureService.verifyRecord({ ...envelope, collection: 'app.evil' }),
+    ).resolves.toBe(false);
+    await expect(
+      SignatureService.verifyRecord({ ...envelope, rkey: 'other' }),
+    ).resolves.toBe(false);
+  });
+
+  it('a v2 envelope signs over DIFFERENT bytes than the same base fields as v1', async () => {
+    const subject = 'did:web:oxy.so:u:diff';
+    const record = { x: 1 };
+    const v2 = await SignatureService.signRecordV2('profile', subject, record, chain);
+
+    const v1Input = signedRecordSigningInput({
+      version: 1,
+      type: 'profile',
+      subject,
+      issuer: subject,
+      record,
+      issuedAt: v2.issuedAt,
+    });
+    const v2Input = signedRecordSigningInput(v2);
+    expect(v2Input).not.toBe(v1Input);
+    expect(v2Input).toContain('"seq":0');
+    expect(v2Input).toContain('"prev":null');
+    expect(v2Input).toContain('"collection":"app.oxy.reputation"');
+  });
+
+  it('throws when no identity is stored', async () => {
+    jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(null);
+    await expect(
+      SignatureService.signRecordV2('identity', 'did:web:oxy.so:u:u4', {}, chain),
+    ).rejects.toThrow(/No identity found/);
+  });
+});
+
+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 SignatureService.hashMessage(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);
+  });
+});

package/src/crypto/signatureService.ts

@@ -21,25 +21,58 @@ const ec = new EC('secp256k1');
  * EXCEPT the `publicKey` and `signature`. Both the client (when signing) and
  * the server (when verifying) canonicalize exactly these fields, so they agree
  * on the bytes that the signature covers.
+ *
+ * The v2 chain fields (`seq`/`prev`/`collection`/`rkey`) are optional: a v1
+ * envelope omits them and is signed over only the base fields; a v2 envelope
+ * carries them and includes them in the signed bytes.
  */
 export type SignedRecordSigningFields = Pick<
   SignedRecordEnvelope,
   'version' | 'type' | 'subject' | 'issuer' | 'record' | 'issuedAt'
->;
+> &
+  Partial<Pick<SignedRecordEnvelope, 'seq' | 'prev' | 'collection' | 'rkey'>>;
 
 /**
  * Compute the canonical signing input for a signed-record envelope.
  *
- * This is the single definition of "what the signature covers": the canonical
- * JSON of `{version, type, subject, issuer, record, issuedAt}`. `@oxyhq/core`
+ * This is the single definition of "what the signature covers". `@oxyhq/core`
  * (client signing) and `@oxyhq/api` (server verification) both call this, so a
  * record signed by a client and verified by the server cannot drift.
+ *
+ * - **v1**: the canonical JSON of `{version, type, subject, issuer, record,
+ *   issuedAt}` — BYTE-IDENTICAL to the original scheme, so every signature
+ *   already in production keeps verifying.
+ * - **v2**: the canonical JSON additionally includes the hash-chain fields
+ *   `{seq, prev, collection, rkey}`. Because {@link canonicalize} sorts keys,
+ *   the on-the-wire field order is irrelevant; the resulting canonical key
+ *   order is `collection, issuedAt, issuer, prev, record, rkey, seq, subject,
+ *   type, version`. `prev` is `null` at genesis (serialized as `null`, not
+ *   omitted), so it is always part of the signed bytes.
  */
 export function signedRecordSigningInput(fields: SignedRecordSigningFields): string {
   const { version, type, subject, issuer, record, issuedAt } = fields;
+  if (version === 2) {
+    const { seq, prev, collection, rkey } = fields;
+    return canonicalize({ version, type, subject, issuer, record, issuedAt, seq, prev, collection, rkey });
+  }
   return canonicalize({ version, type, subject, issuer, record, issuedAt });
 }
 
+/**
+ * Compute the `recordId` (content address) of a signed record: the SHA-256 hex
+ * digest of its canonical {@link signedRecordSigningInput}.
+ *
+ * Deterministic and stable across runtimes (it reuses the same canonicalization
+ * + SHA-256 the signature itself is built on). The recordId is what `prev`
+ * references in the per-subject hash chain, so `@oxyhq/core` (client) and
+ * `@oxyhq/api` (server) MUST compute it identically — both call this function.
+ * It is taken over the SIGNING input (excluding `publicKey`/`signature`), so it
+ * is a pure content address of the record's meaning, independent of who signed.
+ */
+export async function computeRecordId(fields: SignedRecordSigningFields): Promise<string> {
+  return sha256(signedRecordSigningInput(fields));
+}
+
 /**
  * Compute SHA-256 hash of a string
  */
@@ -419,6 +452,72 @@ export class SignatureService {
     };
   }
 
+  /**
+   * Build a signed-record envelope (v2) carrying the per-subject hash-chain
+   * fields.
+   *
+   * Identical to {@link signRecord} (self-issued: `issuer === subject`; same
+   * `ES256K-DER-SHA256` scheme over {@link signedRecordSigningInput}) but
+   * `version` is `2` and the signed bytes additionally cover the chain fields:
+   *
+   * @param type - The record category.
+   * @param subject - The subject DID the record is about (also the issuer).
+   * @param record - The arbitrary record payload to attest to.
+   * @param chain - The hash-chain coordinates:
+   *   - `seq` — strictly-increasing sequence number for this subject's chain.
+   *   - `prev` — the `recordId` of the previous record, or `null` at genesis.
+   *   - `collection` + `rkey` — the AtProto-style record key.
+   *
+   * The caller is responsible for fetching the current chain head (so `seq` /
+   * `prev` are correct) before signing. Requires a stored identity; throws if
+   * none exists.
+   */
+  static async signRecordV2(
+    type: SignedRecordEnvelope['type'],
+    subject: string,
+    record: Record<string, unknown>,
+    chain: { seq: number; prev: string | null; collection: string; rkey: string },
+  ): Promise<SignedRecordEnvelope> {
+    const publicKey = await KeyManager.getPublicKey();
+    if (!publicKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    const version = 2 as const;
+    const issuer = subject;
+    const issuedAt = Date.now();
+    const { seq, prev, collection, rkey } = chain;
+    const signingInput = signedRecordSigningInput({
+      version,
+      type,
+      subject,
+      issuer,
+      record,
+      issuedAt,
+      seq,
+      prev,
+      collection,
+      rkey,
+    });
+    const signature = await SignatureService.sign(signingInput);
+
+    return {
+      version,
+      type,
+      subject,
+      issuer,
+      record,
+      issuedAt,
+      seq,
+      prev,
+      collection,
+      rkey,
+      publicKey,
+      alg: 'ES256K-DER-SHA256',
+      signature,
+    };
+  }
+
   /**
    * Verify a signed-record envelope: recompute the canonical signing input from
    * the envelope's own fields and check the signature against the envelope's

package/src/index.ts

@@ -89,6 +89,8 @@ export {
     getNormalizedUserHandle,
 } from './utils/userHandle';
 export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHandle';
+export { normalizeProfileLinks } from './utils/profileLinks';
+export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 
 // ---------------------------------------------------------------------------
 // Applications (multi-user apps: membership, roles, credentials)
@@ -183,6 +185,32 @@ export type {
     RemoveDomainResult,
 } from './mixins/OxyServices.identity';
 
+// ---------------------------------------------------------------------------
+// Civic / Commons "Oxy ID" (public signed cards + Oxy ID QR payload) and Fase 2
+// anti-gaming (real-life attestation QR + validator/jury). Wire shapes
+// (PublicCard, SignedPublicCard, RealLifeAttestationResult,
+// ValidationRequestSummary, ValidationVoteResult, ValidationVerdict, …) live in
+// `@oxyhq/contracts` — import them from there. The SDK adds the client verdict
+// wrapper, the QR payload parsers/builders, and the submit inputs/results.
+// ---------------------------------------------------------------------------
+export {
+    parseIdPayload,
+    parseAttestPayload,
+    verifyPublicCardAttestation,
+} from './mixins/OxyServices.civic';
+export type {
+    CivicCardResult,
+    IdCardRef,
+    AttestQrPayload,
+    ParsedAttestPayload,
+    SubmitRealLifeAttestationInput,
+    DenyValidationResult,
+    VouchForPersonInput,
+    WithdrawVouchResult,
+    IssueCredentialInput,
+    RevokeCredentialResult,
+} from './mixins/OxyServices.civic';
+
 // ---------------------------------------------------------------------------
 // Auth helpers (token refresh, error normalisation, retry policies)
 // ---------------------------------------------------------------------------
@@ -230,7 +258,7 @@ export {
     IdentityPersistError,
 } from './crypto/keyManager';
 export type { KeyPair } from './crypto/keyManager';
-export { SignatureService, signedRecordSigningInput } from './crypto/signatureService';
+export { SignatureService, signedRecordSigningInput, computeRecordId } from './crypto/signatureService';
 export type { SignedMessage, AuthChallenge, SignedRecordSigningFields } from './crypto/signatureService';
 export { canonicalize } from './crypto/canonicalJson';
 export { RecoveryPhraseService } from './crypto/recoveryPhrase';