@oxyhq/core 3.10.1 → 3.11.0

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/index.ts

@@ -51,6 +51,13 @@ export type { SilentAuthOptions } from './mixins/OxyServices.silent';
 export type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
 export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
+// "Sign in with Oxy" — handoff (Workstream C)
+export type {
+    CommonsSignInHandle,
+    CommonsSignInStatus,
+    CommonsApprovalInfo,
+    CommonsSignInActionResult,
+} from './mixins/OxyServices.auth';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type {
     CreateManagedAccountInput,
@@ -159,6 +166,23 @@ export type {
     ReverseReputationTransactionInput,
 } from './mixins/OxyServices.reputation';
 
+// ---------------------------------------------------------------------------
+// Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping,
+// verified domains). Wire shapes (DidDocument, SignedRecordEnvelope,
+// AuthMethodsResponse, VerifiedDomain, DomainVerificationInstructions,
+// ExportBundle) live in `@oxyhq/contracts` — import them directly from there.
+// ---------------------------------------------------------------------------
+export { buildUserDid } from './mixins/OxyServices.identity';
+export type {
+    IdentityRecordType,
+    UnlinkableAuthMethodType,
+    LinkAuthMethodResult,
+    PublishRecordResult,
+    VerifyRecordResult,
+    VerifyDomainResult,
+    RemoveDomainResult,
+} from './mixins/OxyServices.identity';
+
 // ---------------------------------------------------------------------------
 // Auth helpers (token refresh, error normalisation, retry policies)
 // ---------------------------------------------------------------------------
@@ -206,8 +230,9 @@ export {
     IdentityPersistError,
 } from './crypto/keyManager';
 export type { KeyPair } from './crypto/keyManager';
-export { SignatureService } from './crypto/signatureService';
-export type { SignedMessage, AuthChallenge } from './crypto/signatureService';
+export { SignatureService, signedRecordSigningInput } from './crypto/signatureService';
+export type { SignedMessage, AuthChallenge, SignedRecordSigningFields } from './crypto/signatureService';
+export { canonicalize } from './crypto/canonicalJson';
 export { RecoveryPhraseService } from './crypto/recoveryPhrase';
 export type { RecoveryPhraseResult } from './crypto/recoveryPhrase';
 

package/src/mixins/OxyServices.assets.ts

@@ -486,7 +486,9 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
     public async fetchAssetContent(url: string, type: 'text'): Promise<string>;
     public async fetchAssetContent(url: string, type: 'blob'): Promise<Blob>;
     public async fetchAssetContent(url: string, type: 'text' | 'blob') {
-      const response = await fetch(url, { credentials: 'include' });
+      const response = await fetch(url, {
+        credentials: shouldSendAssetCredentials(url, this.getBaseURL()) ? 'include' : 'omit',
+      });
       if (!response?.ok) {
         throw new Error(`Failed to fetch asset content (status ${response?.status})`);
       }
@@ -494,3 +496,16 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
     }
   };
 }
+
+/**
+ * Only send ambient credentials (cookies) when the asset URL is same-origin with
+ * the configured API base. Caller-supplied cross-origin asset URLs must not leak
+ * the user's cookies to arbitrary hosts.
+ */
+function shouldSendAssetCredentials(url: string, baseURL: string): boolean {
+  try {
+    return new URL(url).origin === new URL(baseURL).origin;
+  } catch {
+    return false;
+  }
+}