@oxyhq/core 3.10.0 → 3.11.0

package/src/crypto/__tests__/keyManager.atomicity.test.ts

@@ -21,7 +21,7 @@ import { setPlatformOS } from '../../utils/platform';
 // Fault-injectable in-memory secure store. `failPlan` lets a test make a
 // specific (op, key) pair throw to simulate a keychain that fails mid-write or
 // is transiently locked.
-const failPlan: { failKey?: string; failOp?: 'set' | 'get' } = {};
+const failPlan: { failKey?: string; failOp?: 'set' | 'get'; failTimes?: number } = {};
 
 jest.mock(
   'expo-secure-store',
@@ -29,6 +29,14 @@ jest.mock(
     const store = new Map<string, string>();
     const maybeFail = (op: 'set' | 'get', key: string) => {
       if (failPlan.failOp === op && failPlan.failKey === key) {
+        if (failPlan.failTimes !== undefined) {
+          failPlan.failTimes -= 1;
+          if (failPlan.failTimes <= 0) {
+            failPlan.failKey = undefined;
+            failPlan.failOp = undefined;
+            failPlan.failTimes = undefined;
+          }
+        }
         throw new Error(`Simulated ${op} failure for ${key}`);
       }
     };
@@ -51,6 +59,7 @@ jest.mock(
         store.clear();
         failPlan.failKey = undefined;
         failPlan.failOp = undefined;
+        failPlan.failTimes = undefined;
       },
       __getStore__: () => store,
       __failPlan__: failPlan,
@@ -92,7 +101,7 @@ jest.mock('../../utils/platformCrypto', () => ({
 interface SecureStoreTestHandle {
   __resetStore__: () => void;
   __getStore__: () => Map<string, string>;
-  __failPlan__: { failKey?: string; failOp?: 'set' | 'get' };
+  __failPlan__: { failKey?: string; failOp?: 'set' | 'get'; failTimes?: number };
 }
 
 describe('KeyManager atomicity & recoverability under flaky storage', () => {
@@ -146,6 +155,36 @@ describe('KeyManager atomicity & recoverability under flaky storage', () => {
     expect(m.get('oxy_identity_backup_public_key')).toBe(originalPublic);
   });
 
+  it('a failed final backup refresh rejects and rolls back instead of succeeding with a stale backup', async () => {
+    const originalPublic = await KeyManager.createIdentity();
+    const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
+    const originalPriv = ss.__getStore__().get('oxy_identity_private_key');
+    resetCaches();
+
+    // Let the new primary write and verify, then fail exactly once while
+    // refreshing the backup to the new identity. This used to return success
+    // with primary=B and backup=A, enabling a later absent-primary restore to
+    // silently switch back to A.
+    ss.__failPlan__.failOp = 'set';
+    ss.__failPlan__.failKey = 'oxy_identity_backup_public_key';
+    ss.__failPlan__.failTimes = 1;
+    await expect(KeyManager.createIdentity({ overwrite: true })).rejects.toBeDefined();
+
+    resetCaches();
+
+    // The operation failed atomically: primary and backup both still identify
+    // the original account, so callers cannot observe success with a stale
+    // cross-account backup.
+    expect(await KeyManager.hasIdentity()).toBe(true);
+    expect(await KeyManager.getPublicKey()).toBe(originalPublic);
+    const m = ss.__getStore__();
+    expect(m.get('oxy_identity_private_key')).toBe(originalPriv);
+    expect(m.get('oxy_identity_public_key')).toBe(originalPublic);
+    expect(m.get('oxy_identity_backup_private_key')).toBe(originalPriv);
+    expect(m.get('oxy_identity_backup_public_key')).toBe(originalPublic);
+  });
+
+
   it('restoreIdentityFromBackup does NOT clobber a healthy primary that is only transiently unreadable', async () => {
     const original = await KeyManager.createIdentity();
     const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;

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

@@ -0,0 +1,64 @@
+/**
+ * `signChallengeWithSharedKey` tests.
+ *
+ * Verifies the shared-key challenge signer mirrors `signChallenge` exactly —
+ * same `auth:${publicKey}:${challenge}:${timestamp}` message format so the
+ * server verification path is unchanged — but sources the SHARED key from
+ * `KeyManager` (not the primary device key). We mock the shared key access with
+ * a REAL elliptic secp256k1 keypair so signing/verification is genuine.
+ */
+
+import { ec as EC } from 'elliptic';
+import { KeyManager } from '../keyManager';
+import { SignatureService } from '../signatureService';
+
+const ec = new EC('secp256k1');
+
+describe('SignatureService.signChallengeWithSharedKey', () => {
+  const sharedKeyPair = ec.genKeyPair();
+  const sharedPublicKey = sharedKeyPair.getPublic('hex');
+  const sharedPrivateKey = sharedKeyPair.getPrivate('hex');
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('signs with the shared key and uses the unchanged message format', async () => {
+    jest.spyOn(KeyManager, 'getSharedPublicKey').mockResolvedValue(sharedPublicKey);
+    jest.spyOn(KeyManager, 'getSharedPrivateKey').mockResolvedValue(sharedPrivateKey);
+    // Guard: it must NOT fall back to the primary device key.
+    const primarySpy = jest.spyOn(KeyManager, 'getPublicKey');
+
+    const result = await SignatureService.signChallengeWithSharedKey('chal-123');
+
+    expect(result.publicKey).toBe(sharedPublicKey);
+    expect(typeof result.challenge).toBe('string'); // the signature
+    expect(typeof result.timestamp).toBe('number');
+    expect(primarySpy).not.toHaveBeenCalled();
+
+    // The signature verifies against the SAME message format `signChallenge`
+    // uses, proving the format is unchanged and the shared key signed it.
+    const message = `auth:${sharedPublicKey}:chal-123:${result.timestamp}`;
+    await expect(
+      SignatureService.verify(message, result.challenge, sharedPublicKey),
+    ).resolves.toBe(true);
+  });
+
+  it('throws when no shared identity exists', async () => {
+    jest.spyOn(KeyManager, 'getSharedPublicKey').mockResolvedValue(null);
+    jest.spyOn(KeyManager, 'getSharedPrivateKey').mockResolvedValue(null);
+
+    await expect(
+      SignatureService.signChallengeWithSharedKey('chal-123'),
+    ).rejects.toThrow(/No shared identity/);
+  });
+
+  it('throws when the shared private key is missing even if the public key is present', async () => {
+    jest.spyOn(KeyManager, 'getSharedPublicKey').mockResolvedValue(sharedPublicKey);
+    jest.spyOn(KeyManager, 'getSharedPrivateKey').mockResolvedValue(null);
+
+    await expect(
+      SignatureService.signChallengeWithSharedKey('chal-123'),
+    ).rejects.toThrow(/No shared identity/);
+  });
+});

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

@@ -0,0 +1,125 @@
+/**
+ * Signed-record envelope tests.
+ *
+ * Exercises the full client-side path: `SignatureService.signRecord` builds an
+ * envelope whose signature covers the canonical JSON of every field EXCEPT
+ * `publicKey`/`signature`, and `SignatureService.verifyRecord` round-trips it.
+ * We mock `KeyManager`'s key access with a REAL elliptic secp256k1 keypair, so
+ * the signing/verification is genuine cryptography (not a stub).
+ */
+
+import { ec as EC } from 'elliptic';
+import type { SignedRecordEnvelope } from '@oxyhq/contracts';
+import { KeyManager } from '../keyManager';
+import { SignatureService, signedRecordSigningInput } from '../signatureService';
+import { canonicalize } from '../canonicalJson';
+
+const ec = new EC('secp256k1');
+
+describe('SignatureService.signRecord / verifyRecord', () => {
+  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();
+  });
+
+  it('builds a well-formed self-issued envelope', async () => {
+    const subject = 'did:web:oxy.so:u:abc123';
+    const record = { displayName: 'Nate', bio: 'builder' };
+
+    const envelope = await SignatureService.signRecord('profile', subject, record);
+
+    expect(envelope.version).toBe(1);
+    expect(envelope.type).toBe('profile');
+    expect(envelope.subject).toBe(subject);
+    expect(envelope.issuer).toBe(subject); // self-issued
+    expect(envelope.record).toEqual(record);
+    expect(envelope.publicKey).toBe(publicKey);
+    expect(envelope.alg).toBe('ES256K-DER-SHA256');
+    expect(typeof envelope.signature).toBe('string');
+    expect(envelope.signature.length).toBeGreaterThan(0);
+    expect(typeof envelope.issuedAt).toBe('number');
+  });
+
+  it('round-trips: a freshly signed record verifies', async () => {
+    const envelope = await SignatureService.signRecord('identity', 'did:web:oxy.so:u:u1', {
+      handle: '@nate',
+      nested: { a: 1, b: [2, 3] },
+    });
+    await expect(SignatureService.verifyRecord(envelope)).resolves.toBe(true);
+  });
+
+  it('signs the canonical JSON of every field except publicKey + signature', async () => {
+    const subject = 'did:web:oxy.so:u:u2';
+    const record = { z: 1, a: 2 };
+    const envelope = await SignatureService.signRecord('profile', subject, record);
+
+    const expectedInput = canonicalize({
+      version: envelope.version,
+      type: envelope.type,
+      subject: envelope.subject,
+      issuer: envelope.issuer,
+      record: envelope.record,
+      issuedAt: envelope.issuedAt,
+    });
+
+    // The helper reproduces exactly that input from the envelope.
+    expect(signedRecordSigningInput(envelope)).toBe(expectedInput);
+    // And it omits publicKey/signature.
+    expect(expectedInput).not.toContain(envelope.publicKey);
+    expect(expectedInput).not.toContain(envelope.signature);
+
+    // The signature verifies against that exact input + the embedded key.
+    await expect(
+      SignatureService.verify(expectedInput, envelope.signature, envelope.publicKey),
+    ).resolves.toBe(true);
+  });
+
+  describe('tamper detection', () => {
+    let envelope: SignedRecordEnvelope;
+
+    beforeEach(async () => {
+      envelope = await SignatureService.signRecord('profile', 'did:web:oxy.so:u:u3', {
+        displayName: 'Original',
+        score: 10,
+      });
+    });
+
+    it('rejects a mutated record', async () => {
+      const tampered: SignedRecordEnvelope = {
+        ...envelope,
+        record: { ...envelope.record, displayName: 'Tampered' },
+      };
+      await expect(SignatureService.verifyRecord(tampered)).resolves.toBe(false);
+    });
+
+    it('rejects a changed subject', async () => {
+      const tampered: SignedRecordEnvelope = { ...envelope, subject: 'did:web:oxy.so:u:evil' };
+      await expect(SignatureService.verifyRecord(tampered)).resolves.toBe(false);
+    });
+
+    it('rejects a changed issuedAt', async () => {
+      const tampered: SignedRecordEnvelope = { ...envelope, issuedAt: envelope.issuedAt + 1 };
+      await expect(SignatureService.verifyRecord(tampered)).resolves.toBe(false);
+    });
+
+    it('rejects verification against an unrelated public key', async () => {
+      const otherKey = ec.genKeyPair().getPublic('hex');
+      const tampered: SignedRecordEnvelope = { ...envelope, publicKey: otherKey };
+      await expect(SignatureService.verifyRecord(tampered)).resolves.toBe(false);
+    });
+  });
+
+  it('throws when no identity is stored', async () => {
+    jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(null);
+    await expect(
+      SignatureService.signRecord('identity', 'did:web:oxy.so:u:u4', {}),
+    ).rejects.toThrow(/No identity found/);
+  });
+});

package/src/crypto/canonicalJson.ts

@@ -0,0 +1,120 @@
+/**
+ * Canonical JSON (RFC 8785 / JCS-style) serialization.
+ *
+ * `canonicalize(value)` produces a deterministic string for any JSON-compatible
+ * value so that a client which SIGNS a record and a server which VERIFIES it
+ * agree byte-for-byte on the signing input — regardless of the order in which
+ * object keys happen to be written, how the value was deserialized, or which
+ * runtime built it.
+ *
+ * This is the load-bearing primitive for the self-sovereign identity layer's
+ * signed records (`SignatureService.signRecord` + the API's record-verify path):
+ * both sides import THIS function from `@oxyhq/core`, so cross-implementation
+ * number/string formatting differences cannot cause a verify mismatch.
+ *
+ * Rules (the JSON Canonicalization Scheme subset we need):
+ *  - Objects: keys are sorted (ascending, by UTF-16 code unit — the default
+ *    `Array.prototype.sort` order) and serialized recursively. Properties whose
+ *    value is `undefined`, a function, or a symbol are OMITTED (matching
+ *    `JSON.stringify` object semantics).
+ *  - Arrays: element order is PRESERVED; `undefined`/function/symbol elements
+ *    serialize to `null` (matching `JSON.stringify` array semantics).
+ *  - `null`, booleans, strings, and finite numbers serialize via the standard
+ *    JSON representation.
+ *  - Values exposing a `toJSON()` method (e.g. `Date`) are replaced by its
+ *    result first, then serialized — so a `Date` and its ISO-string equivalent
+ *    canonicalize identically (the wire always carries the string form).
+ *  - Non-finite numbers (`NaN`, `Infinity`) and `bigint` are not part of the
+ *    JSON data model and throw, rather than silently producing `null`.
+ *
+ * Platform-agnostic — zero dependencies, no `require()`, no react/react-native/
+ * expo. Safe in the dual CJS + ESM build.
+ */
+
+/** Object exposing a `toJSON()` serialization hook (e.g. `Date`). */
+interface ToJsonable {
+  toJSON: () => unknown;
+}
+
+function hasToJSON(value: object): value is ToJsonable {
+  return typeof (value as { toJSON?: unknown }).toJSON === 'function';
+}
+
+/**
+ * Serialize a single value into its canonical JSON fragment. Recursive; called
+ * on each nested member. Object keys are sorted at every level.
+ */
+function serialize(value: unknown): string {
+  if (value === null) {
+    return 'null';
+  }
+
+  const valueType = typeof value;
+
+  if (valueType === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new Error('canonicalize: non-finite numbers cannot be serialized');
+    }
+    return JSON.stringify(value);
+  }
+
+  if (valueType === 'string' || valueType === 'boolean') {
+    return JSON.stringify(value);
+  }
+
+  if (valueType === 'bigint') {
+    throw new Error('canonicalize: bigint values cannot be serialized');
+  }
+
+  if (Array.isArray(value)) {
+    const items = value.map((item) => {
+      const itemType = typeof item;
+      // JSON array semantics: undefined / function / symbol become null so the
+      // element positions (and therefore the array length) are preserved.
+      if (item === undefined || itemType === 'function' || itemType === 'symbol') {
+        return 'null';
+      }
+      return serialize(item);
+    });
+    return `[${items.join(',')}]`;
+  }
+
+  if (valueType === 'object') {
+    const obj = value as object;
+    if (hasToJSON(obj)) {
+      return serialize(obj.toJSON());
+    }
+
+    const record = obj as Record<string, unknown>;
+    const parts: string[] = [];
+    for (const key of Object.keys(record).sort()) {
+      const member = record[key];
+      const memberType = typeof member;
+      // JSON object semantics: properties with undefined / function / symbol
+      // values are omitted entirely.
+      if (member === undefined || memberType === 'function' || memberType === 'symbol') {
+        continue;
+      }
+      parts.push(`${JSON.stringify(key)}:${serialize(member)}`);
+    }
+    return `{${parts.join(',')}}`;
+  }
+
+  // undefined / function / symbol at the top level have no JSON representation.
+  throw new Error(`canonicalize: cannot serialize a value of type ${valueType}`);
+}
+
+/**
+ * Produce the canonical JSON string for `value`.
+ *
+ * Deterministic: two structurally-equal values yield identical strings even if
+ * their object keys were written in different orders. Use this — never an
+ * ad-hoc `JSON.stringify` of a hand-sorted object — as the signing input for
+ * signed records, so client signing and server verification cannot drift.
+ *
+ * @throws if `value` (or any nested member used as the top-level/primitive)
+ *   contains a non-finite number or a `bigint`, which have no JSON form.
+ */
+export function canonicalize(value: unknown): string {
+  return serialize(value);
+}

package/src/crypto/keyManager.ts

@@ -85,9 +85,9 @@ const STORAGE_KEYS = {
 /**
  * iOS Keychain Access Group for sharing identities across Oxy apps
  * All Oxy apps must have this access group enabled in their entitlements
- * Format: [Team ID].com.oxy.shared or group.com.oxy.shared
+ * Format: [Team ID].so.oxy.shared or group.so.oxy.shared
  */
-const IOS_KEYCHAIN_GROUP = 'group.com.oxy.shared';
+const IOS_KEYCHAIN_GROUP = 'group.so.oxy.shared';
 
 /**
  * Android Account Manager type for shared authentication
@@ -795,11 +795,25 @@ export class KeyManager {
     }
 
     // Step 3: The new primary is durable and functional. NOW it is safe to
-    // refresh the backup to the new key. If this final backup write fails the
-    // user still has a fully working primary, and the backup still holds the
-    // PREVIOUS good identity — so we log and continue rather than failing the
-    // whole operation (failing here would be strictly worse: a working
-    // primary would be reported as an error to the caller).
+    // refresh the backup to the new key. This is part of the successful write
+    // contract: returning success while the backup still belongs to the
+    // previous identity would allow a later restore with an absent primary to
+    // silently switch the device back to the previous account. Snapshot the
+    // backup first so a partial backup refresh can be rolled back along with
+    // the primary before surfacing the failure.
+    let priorBackupPrivate: string | null;
+    let priorBackupPublic: string | null;
+    let priorBackupTimestamp: string | null;
+    try {
+      priorBackupPrivate = await store.getItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY);
+      priorBackupPublic = await store.getItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+      priorBackupTimestamp = await store.getItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP);
+    } catch (error) {
+      logger.error('Failed to snapshot identity backup before refresh', error, { component: 'KeyManager' });
+      await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
+      throw new IdentityPersistError('Failed to snapshot identity backup before refresh', error);
+    }
+
     try {
       await store.setItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY, canonicalPrivate, {
         keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
@@ -807,11 +821,10 @@ export class KeyManager {
       await store.setItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY, canonicalPublic);
       await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
     } catch (error) {
-      logger.warn(
-        'Primary identity persisted successfully but refreshing the backup failed; primary is usable, backup may be stale',
-        { component: 'KeyManager' },
-        error,
-      );
+      logger.error('Failed to refresh identity backup after primary write', error, { component: 'KeyManager' });
+      await KeyManager._rollbackBackup(store, priorBackupPrivate, priorBackupPublic, priorBackupTimestamp);
+      await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
+      throw new IdentityPersistError('Failed to refresh identity backup after primary write', error);
     }
 
     // Update cache only after we are certain the identity is durable.
@@ -819,6 +832,43 @@ export class KeyManager {
     KeyManager.cachedHasIdentity = true;
   }
 
+  /**
+   * Restore the backup slot to a previously-snapshotted state. Best-effort so
+   * the original persistence error remains the one surfaced to the caller.
+   *
+   * @internal
+   */
+  private static async _rollbackBackup(
+    store: Awaited<ReturnType<typeof initSecureStore>>,
+    priorBackupPrivate: string | null,
+    priorBackupPublic: string | null,
+    priorBackupTimestamp: string | null,
+  ): Promise<void> {
+    try {
+      if (priorBackupPrivate) {
+        await store.setItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY, priorBackupPrivate, {
+          keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+        });
+      } else {
+        try { await store.deleteItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY); } catch { /* best effort */ }
+      }
+
+      if (priorBackupPublic) {
+        await store.setItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY, priorBackupPublic);
+      } else {
+        try { await store.deleteItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY); } catch { /* best effort */ }
+      }
+
+      if (priorBackupTimestamp) {
+        await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, priorBackupTimestamp);
+      } else {
+        try { await store.deleteItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP); } catch { /* best effort */ }
+      }
+    } catch (rollbackError) {
+      logger.error('Failed to roll back identity backup after a failed refresh', rollbackError, { component: 'KeyManager' });
+    }
+  }
+
   /**
    * Restore the primary slot to a previously-snapshotted (privA, pubA) pair,
    * or delete it entirely if there was no prior identity. Best-effort: every

package/src/crypto/signatureService.ts

@@ -6,7 +6,9 @@
  */
 
 import { ec as EC } from 'elliptic';
+import type { SignedRecordEnvelope } from '@oxyhq/contracts';
 import { KeyManager } from './keyManager';
+import { canonicalize } from './canonicalJson';
 import { isReactNative, isNodeJS } from '../utils/platform';
 import { loadExpoCrypto, loadNodeCrypto } from '../utils/platformCrypto';
 import { logger } from '../utils/loggerUtils';
@@ -14,6 +16,30 @@ import { isDev } from '../shared/utils/debugUtils';
 
 const ec = new EC('secp256k1');
 
+/**
+ * The signing-input portion of a {@link SignedRecordEnvelope}: every field
+ * 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.
+ */
+export type SignedRecordSigningFields = Pick<
+  SignedRecordEnvelope,
+  'version' | 'type' | 'subject' | 'issuer' | 'record' | 'issuedAt'
+>;
+
+/**
+ * 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`
+ * (client signing) and `@oxyhq/api` (server verification) both call this, so a
+ * record signed by a client and verified by the server cannot drift.
+ */
+export function signedRecordSigningInput(fields: SignedRecordSigningFields): string {
+  const { version, type, subject, issuer, record, issuedAt } = fields;
+  return canonicalize({ version, type, subject, issuer, record, issuedAt });
+}
+
 /**
  * Compute SHA-256 hash of a string
  */
@@ -236,6 +262,39 @@ export class SignatureService {
     };
   }
 
+  /**
+   * Create a signed authentication challenge response using the SHARED identity
+   * key (the cross-app `group.so.oxy.shared` keychain key), not the primary
+   * device key.
+   *
+   * Mirrors {@link signChallenge} exactly — same message format
+   * (`auth:${publicKey}:${challenge}:${timestamp}`) so the server verification
+   * path is unchanged — but sources the shared public/private key from
+   * `KeyManager` and signs with `signWithKey`. Used by "Sign in with Oxy"
+   * same-device shared-keychain SSO (Mechanism A): a sibling native app proves
+   * control of the shared identity to mint its own session.
+   *
+   * Throws if no shared identity exists (native-only; the shared keychain is
+   * unavailable on web).
+   */
+  static async signChallengeWithSharedKey(challenge: string): Promise<AuthChallenge> {
+    const publicKey = await KeyManager.getSharedPublicKey();
+    const privateKey = await KeyManager.getSharedPrivateKey();
+    if (!publicKey || !privateKey) {
+      throw new Error('No shared identity found. Cannot sign with the shared key.');
+    }
+
+    const timestamp = Date.now();
+    const message = `auth:${publicKey}:${challenge}:${timestamp}`;
+    const signature = await SignatureService.signWithKey(message, privateKey);
+
+    return {
+      challenge: signature,
+      publicKey,
+      timestamp,
+    };
+  }
+
   /**
    * Verify a challenge response
    */
@@ -308,6 +367,73 @@ export class SignatureService {
       timestamp,
     };
   }
+
+  /**
+   * Build a signed-record envelope for a self-issued identity/profile record.
+   *
+   * The envelope is self-issued: `issuer` equals `subject` (the signer's DID).
+   * The signature covers the canonical JSON of every field EXCEPT `publicKey`
+   * and `signature` (see {@link signedRecordSigningInput}); `alg` is
+   * `ES256K-DER-SHA256` (secp256k1 over the SHA-256 of the canonical bytes,
+   * DER-encoded), the same scheme this service uses everywhere else.
+   *
+   * Requires a stored identity (native secure storage); throws if none exists.
+   *
+   * @param type - The record category (`'identity'` or `'profile'`).
+   * @param subject - The subject DID the record is about (also the issuer).
+   * @param record - The arbitrary record payload to attest to.
+   */
+  static async signRecord(
+    type: SignedRecordEnvelope['type'],
+    subject: string,
+    record: Record<string, unknown>,
+  ): Promise<SignedRecordEnvelope> {
+    const publicKey = await KeyManager.getPublicKey();
+    if (!publicKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    const version = 1 as const;
+    const issuer = subject;
+    const issuedAt = Date.now();
+    const signingInput = signedRecordSigningInput({
+      version,
+      type,
+      subject,
+      issuer,
+      record,
+      issuedAt,
+    });
+    const signature = await SignatureService.sign(signingInput);
+
+    return {
+      version,
+      type,
+      subject,
+      issuer,
+      record,
+      issuedAt,
+      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
+   * `publicKey`.
+   *
+   * Note: this confirms the signature is internally consistent with the
+   * embedded `publicKey`. It does NOT establish that `publicKey` is an
+   * authorized verification method for `subject` — that authorization check is
+   * the server's responsibility (it asserts the key is a current verification
+   * method on the subject's DID).
+   */
+  static async verifyRecord(envelope: SignedRecordEnvelope): Promise<boolean> {
+    const signingInput = signedRecordSigningInput(envelope);
+    return SignatureService.verify(signingInput, envelope.signature, envelope.publicKey);
+  }
 }
 
 export default SignatureService;

package/src/i18n/locales/en-US.json

@@ -129,6 +129,15 @@
       "title": "Reputation = Trust & Growth",
       "body": "Oxy Trust is a reputation system that reacts to what you do. Helpful, respectful, constructive actions earn it. Harmful or low‑effort stuff chips it away. More reputation can unlock benefits; low reputation can limit features. It keeps things fair and rewards real contribution."
     },
+    "name": {
+      "title": "What's your name?",
+      "body": "Add your name so people know who you are.",
+      "firstLabel": "First name",
+      "firstPlaceholder": "Your first name",
+      "lastLabel": "Last name",
+      "lastPlaceholder": "Your last name",
+      "saveFailed": "Could not save your name"
+    },
     "avatar": {
       "title": "Make It Yours",
       "body": "Add an avatar so people recognize you. It will show anywhere you show up here. Skip if you want — you can add it later.",

package/src/i18n/locales/es-ES.json

@@ -849,6 +849,15 @@
       "title": "Reputación = Confianza y crecimiento",
       "body": "Oxy Trust es un sistema de reputación que reacciona a lo que haces. Las acciones útiles, respetuosas y constructivas la aumentan. Las acciones dañinas o de poco esfuerzo la reducen. Más reputación puede desbloquear beneficios; poca reputación puede limitar funciones. Mantiene la justicia y recompensa la contribución real."
     },
+    "name": {
+      "title": "¿Cuál es tu nombre?",
+      "body": "Añade tu nombre para que la gente sepa quién eres.",
+      "firstLabel": "Nombre",
+      "firstPlaceholder": "Tu nombre",
+      "lastLabel": "Apellidos",
+      "lastPlaceholder": "Tus apellidos",
+      "saveFailed": "No se pudo guardar tu nombre"
+    },
     "avatar": {
       "title": "Hazlo tuyo",
       "body": "Añade un avatar para que te reconozcan. Se mostrará donde aparezcas aquí. Puedes omitirlo — puedes añadirlo más tarde.",