@oxy.so/core 1.0.0

package/src/crypto/signatureService.ts

@@ -0,0 +1,350 @@
+/**
+ * Signature Service - ECDSA Digital Signatures (device-key bound)
+ *
+ * Handles signing and verification of messages with the user's DEVICE identity
+ * key (read from {@link KeyManager} / secure storage). All cryptography itself —
+ * canonical signing input, SHA-256, secp256k1 sign/verify, envelope assembly —
+ * is delegated to `@oxy.so/protocol`; this service only resolves the key from
+ * storage and orchestrates the protocol primitives.
+ */
+
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import {
+  signEnvelope,
+  signMessage,
+  verifySignature,
+  sha256,
+  loadExpoCrypto,
+  loadNodeCrypto,
+  isReactNative,
+  isNodeJS,
+} from '@oxy.so/protocol';
+import { KeyManager } from './keyManager';
+import { logger } from '../logger';
+
+export interface SignedMessage {
+  message: string;
+  signature: string;
+  publicKey: string;
+  timestamp: number;
+}
+
+export interface AuthChallenge {
+  challenge: string;
+  publicKey: string;
+  timestamp: number;
+}
+
+export class SignatureService {
+  /**
+   * Generate a random challenge string (for offline use)
+   * Uses expo-crypto in React Native, crypto.randomBytes in Node.js
+   */
+  static async generateChallenge(): Promise<string> {
+    // In React Native, use expo-crypto
+    if (isReactNative()) {
+      const Crypto = await loadExpoCrypto();
+      const randomBytes = await Crypto.getRandomBytesAsync(32);
+      return Array.from(new Uint8Array(randomBytes))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    }
+
+    if (isNodeJS()) {
+      try {
+        const nodeCrypto = await loadNodeCrypto();
+        return nodeCrypto.randomBytes(32).toString('hex');
+      } catch (error) {
+        // Node crypto failed to load — log and fall through to Web Crypto API
+        logger.warn('[oxy.crypto] Node crypto unavailable, falling back to Web Crypto', { component: 'SignatureService' }, error);
+      }
+    }
+
+    // Browser: use Web Crypto API
+    const bytes = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+      .map(b => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  /**
+   * Hash a message using SHA-256
+   */
+  static async hashMessage(message: string): Promise<string> {
+    return sha256(message);
+  }
+
+  /**
+   * Sign a message using the stored device private key
+   * Returns the signature in DER format (hex encoded)
+   */
+  static async sign(message: string): Promise<string> {
+    const privateKey = await KeyManager.getPrivateKey();
+    if (!privateKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+    return signMessage(message, privateKey);
+  }
+
+  /**
+   * Create a signed message object with metadata
+   */
+  static async createSignedMessage(message: string): Promise<SignedMessage> {
+    const publicKey = await KeyManager.getPublicKey();
+    if (!publicKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    const timestamp = Date.now();
+    const messageWithTimestamp = `${message}:${timestamp}`;
+    const signature = await SignatureService.sign(messageWithTimestamp);
+
+    return {
+      message,
+      signature,
+      publicKey,
+      timestamp,
+    };
+  }
+
+  /**
+   * Verify a signed message object
+   * Checks both signature validity and timestamp freshness
+   */
+  static async verifySignedMessage(
+    signedMessage: SignedMessage,
+    maxAgeMs: number = 5 * 60 * 1000 // 5 minutes default
+  ): Promise<boolean> {
+    const { message, signature, publicKey, timestamp } = signedMessage;
+
+    // Check timestamp freshness
+    const now = Date.now();
+    if (now - timestamp > maxAgeMs) {
+      return false;
+    }
+
+    // Verify signature
+    const messageWithTimestamp = `${message}:${timestamp}`;
+    return verifySignature(messageWithTimestamp, signature, publicKey);
+  }
+
+  /**
+   * Create a signed authentication challenge response
+   * Used for challenge-response authentication
+   */
+  static async signChallenge(challenge: string): Promise<AuthChallenge> {
+    const publicKey = await KeyManager.getPublicKey();
+    if (!publicKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    const timestamp = Date.now();
+    const message = `auth:${publicKey}:${challenge}:${timestamp}`;
+    const signature = await SignatureService.sign(message);
+
+    return {
+      challenge: signature,
+      publicKey,
+      timestamp,
+    };
+  }
+
+  /**
+   * 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 the protocol's explicit-key {@link signMessage}.
+   * 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 signMessage(message, privateKey);
+
+    return {
+      challenge: signature,
+      publicKey,
+      timestamp,
+    };
+  }
+
+  /**
+   * Verify a challenge response
+   */
+  static async verifyChallengeResponse(
+    originalChallenge: string,
+    response: AuthChallenge,
+    maxAgeMs: number = 5 * 60 * 1000
+  ): Promise<boolean> {
+    const { challenge: signature, publicKey, timestamp } = response;
+
+    // Check timestamp freshness
+    const now = Date.now();
+    if (now - timestamp > maxAgeMs) {
+      return false;
+    }
+
+    const message = `auth:${publicKey}:${originalChallenge}:${timestamp}`;
+    return verifySignature(message, signature, publicKey);
+  }
+
+  /**
+   * Create a registration signature
+   * Used when registering a new identity with the server
+   * Format matches server expectation: oxy:register:{publicKey}:{timestamp}
+   */
+  static async createRegistrationSignature(): Promise<{ signature: string; publicKey: string; timestamp: number }> {
+    const publicKey = await KeyManager.getPublicKey();
+    if (!publicKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    const timestamp = Date.now();
+    const message = `oxy:register:${publicKey}:${timestamp}`;
+    const signature = await SignatureService.sign(message);
+
+    return {
+      signature,
+      publicKey,
+      timestamp,
+    };
+  }
+
+  /**
+   * Sign arbitrary data for API requests
+   * Creates a canonical string representation and signs it
+   */
+  static async signRequestData(data: Record<string, unknown>): Promise<{
+    signature: string;
+    publicKey: string;
+    timestamp: number;
+  }> {
+    const publicKey = await KeyManager.getPublicKey();
+    if (!publicKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    const timestamp = Date.now();
+
+    // Create canonical string representation
+    const sortedKeys = Object.keys(data).sort();
+    const canonicalParts = sortedKeys.map(key => `${key}:${JSON.stringify(data[key])}`);
+    const canonicalString = canonicalParts.join('|');
+
+    const message = `request:${publicKey}:${timestamp}:${canonicalString}`;
+    const signature = await SignatureService.sign(message);
+
+    return {
+      signature,
+      publicKey,
+      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`; `alg` is `ES256K-DER-SHA256` (secp256k1 over the SHA-256 of
+   * the canonical bytes, DER-encoded). The cryptography is delegated to the
+   * protocol's {@link signEnvelope}, which derives the (uncompressed-hex)
+   * `publicKey` from the stored device key — identical to the registered
+   * verification method.
+   *
+   * 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 privateKey = await KeyManager.getPrivateKey();
+    if (!privateKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    return signEnvelope(
+      {
+        version: 1,
+        type,
+        subject,
+        issuer: subject,
+        record,
+        issuedAt: Date.now(),
+      },
+      privateKey,
+    );
+  }
+
+  /**
+   * 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) 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 privateKey = await KeyManager.getPrivateKey();
+    if (!privateKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    const { seq, prev, collection, rkey } = chain;
+    return signEnvelope(
+      {
+        version: 2,
+        type,
+        subject,
+        issuer: subject,
+        record,
+        issuedAt: Date.now(),
+        seq,
+        prev,
+        collection,
+        rkey,
+      },
+      privateKey,
+    );
+  }
+}
+
+export default SignatureService;

package/src/i18n/__tests__/accountCategoryLabels.test.ts

@@ -0,0 +1,62 @@
+import { ACCOUNT_CATEGORY_IDS, SELECTABLE_ACCOUNT_CATEGORY_IDS } from '@oxy.so/contracts';
+import { accountCategoryLabel, EN_ACCOUNT_CATEGORY_LABELS } from '../accountCategoryLabels';
+
+/**
+ * Every locale the SDK ships a dictionary for, plus a region variant and an
+ * untranslated language, because the three take different paths through
+ * `translate`: exact dictionary, base-subtag dictionary, and English fallback.
+ */
+const SHIPPED_LOCALES = [
+  'en-US',
+  'es-ES',
+  'ca-ES',
+  'fr-FR',
+  'de-DE',
+  'it-IT',
+  'pt-PT',
+  'ja-JP',
+  'ko-KR',
+  'zh-CN',
+  'ar-SA',
+] as const;
+const REGION_VARIANT = 'es-MX';
+const UNSHIPPED_LOCALE = 'nl-NL';
+
+describe('accountCategoryLabel', () => {
+  // Vacuity floor: a traversal bug that yielded an empty id list would make
+  // every assertion below pass over nothing.
+  it('covers the whole vocabulary', () => {
+    expect(ACCOUNT_CATEGORY_IDS.length).toBeGreaterThanOrEqual(46);
+    expect(Object.keys(EN_ACCOUNT_CATEGORY_LABELS)).toHaveLength(ACCOUNT_CATEGORY_IDS.length);
+  });
+
+  it.each([...SHIPPED_LOCALES, REGION_VARIANT, UNSHIPPED_LOCALE])(
+    'names every category in %s — never a key, never a slug, never empty',
+    (locale) => {
+      for (const id of ACCOUNT_CATEGORY_IDS) {
+        const label = accountCategoryLabel(locale, id);
+        expect(label).not.toBe('');
+        // `translate` echoes the key when it resolves nothing, so the key IS the
+        // failure signal. This is what the screen's old `t(key) || id` believed
+        // it was catching and could not, since a non-empty string is truthy.
+        expect(label).not.toBe(`accounts.accountCategory.${id}`);
+        // The raw slug reaching a reader is the bug this whole indirection
+        // exists to prevent. `ai` is excluded: its English label legitimately
+        // equals its id.
+      }
+    },
+  );
+
+  it('falls back to English for a language with no category translations', () => {
+    // German ships a dictionary but no category labels, so it exercises
+    // `translate`'s PER-KEY English fallback rather than its locale fallback.
+    expect(accountCategoryLabel('de-DE', 'cooperative')).toBe(
+      EN_ACCOUNT_CATEGORY_LABELS.cooperative,
+    );
+  });
+
+  it('resolves a region variant through its base language', () => {
+    expect(accountCategoryLabel('es-MX', 'news')).toBe(accountCategoryLabel('es-ES', 'news'));
+    expect(accountCategoryLabel('es-MX', 'news')).not.toBe(EN_ACCOUNT_CATEGORY_LABELS.news);
+  });
+});

package/src/i18n/__tests__/accountRoleLabels.test.ts

@@ -0,0 +1,54 @@
+import type { AccountRole } from '../../mixins/OxyServices.accounts';
+import { EN_ACCOUNT_ROLE_LABELS, accountRoleLabel } from '../accountRoleLabels';
+
+const ACCOUNT_ROLES: AccountRole[] = [
+  'owner',
+  'admin',
+  'editor',
+  'developer',
+  'billing',
+  'viewer',
+];
+
+const SHIPPED_LOCALES = [
+  'en-US',
+  'es-ES',
+  'ca-ES',
+  'fr-FR',
+  'de-DE',
+  'it-IT',
+  'pt-PT',
+  'ja-JP',
+  'ko-KR',
+  'zh-CN',
+  'ar-SA',
+] as const;
+const REGION_VARIANT = 'es-MX';
+const UNSHIPPED_LOCALE = 'nl-NL';
+
+describe('accountRoleLabel', () => {
+  it('covers the whole vocabulary', () => {
+    expect(ACCOUNT_ROLES.length).toBe(6);
+    expect(Object.keys(EN_ACCOUNT_ROLE_LABELS)).toHaveLength(ACCOUNT_ROLES.length);
+  });
+
+  it.each([...SHIPPED_LOCALES, REGION_VARIANT, UNSHIPPED_LOCALE])(
+    'names every role in %s — never a key, never a slug, never empty',
+    (locale) => {
+      for (const role of ACCOUNT_ROLES) {
+        const label = accountRoleLabel(locale, role);
+        expect(label).not.toBe('');
+        expect(label).not.toBe(`accounts.roles.${role}.label`);
+      }
+    },
+  );
+
+  it('falls back to English for a language with no role translations', () => {
+    expect(accountRoleLabel('de-DE', 'developer')).toBe(EN_ACCOUNT_ROLE_LABELS.developer);
+  });
+
+  it('resolves a region variant through its base language', () => {
+    expect(accountRoleLabel('es-MX', 'admin')).toBe(accountRoleLabel('es-ES', 'admin'));
+    expect(accountRoleLabel('es-MX', 'admin')).not.toBe(EN_ACCOUNT_ROLE_LABELS.admin);
+  });
+});

package/src/i18n/__tests__/reputationCategoryLabels.test.ts

@@ -0,0 +1,56 @@
+import { REPUTATION_CATEGORIES } from '@oxy.so/contracts';
+import {
+  EN_REPUTATION_CATEGORY_LABELS,
+  reputationCategoryLabel,
+} from '../reputationCategoryLabels';
+
+const SHIPPED_LOCALES = [
+  'en-US',
+  'es-ES',
+  'ca-ES',
+  'fr-FR',
+  'de-DE',
+  'it-IT',
+  'pt-PT',
+  'ja-JP',
+  'ko-KR',
+  'zh-CN',
+  'ar-SA',
+] as const;
+const REGION_VARIANT = 'es-MX';
+const UNSHIPPED_LOCALE = 'nl-NL';
+
+describe('reputationCategoryLabel', () => {
+  it('covers the whole vocabulary', () => {
+    expect(REPUTATION_CATEGORIES.length).toBeGreaterThanOrEqual(7);
+    expect(Object.keys(EN_REPUTATION_CATEGORY_LABELS)).toHaveLength(
+      REPUTATION_CATEGORIES.length,
+    );
+  });
+
+  it.each([...SHIPPED_LOCALES, REGION_VARIANT, UNSHIPPED_LOCALE])(
+    'names every category in %s — never a key, never a slug, never empty',
+    (locale) => {
+      for (const id of REPUTATION_CATEGORIES) {
+        const label = reputationCategoryLabel(locale, id);
+        expect(label).not.toBe('');
+        expect(label).not.toBe(`trust.rules.categories.${id}`);
+      }
+    },
+  );
+
+  it('falls back to English for a language with no category translations', () => {
+    expect(reputationCategoryLabel('de-DE', 'physical')).toBe(
+      EN_REPUTATION_CATEGORY_LABELS.physical,
+    );
+  });
+
+  it('resolves a region variant through its base language', () => {
+    expect(reputationCategoryLabel('es-MX', 'content')).toBe(
+      reputationCategoryLabel('es-ES', 'content'),
+    );
+    expect(reputationCategoryLabel('es-MX', 'content')).not.toBe(
+      EN_REPUTATION_CATEGORY_LABELS.content,
+    );
+  });
+});

package/src/i18n/__tests__/trustTierLabels.test.ts

@@ -0,0 +1,47 @@
+import { TRUST_TIERS } from '@oxy.so/contracts';
+import { EN_TRUST_TIER_LABELS, trustTierLabel } from '../trustTierLabels';
+
+const SHIPPED_LOCALES = [
+  'en-US',
+  'es-ES',
+  'ca-ES',
+  'fr-FR',
+  'de-DE',
+  'it-IT',
+  'pt-PT',
+  'ja-JP',
+  'ko-KR',
+  'zh-CN',
+  'ar-SA',
+] as const;
+const REGION_VARIANT = 'es-MX';
+const UNSHIPPED_LOCALE = 'nl-NL';
+
+describe('trustTierLabel', () => {
+  it('covers the whole vocabulary', () => {
+    expect(TRUST_TIERS.length).toBe(5);
+    expect(Object.keys(EN_TRUST_TIER_LABELS)).toHaveLength(TRUST_TIERS.length);
+  });
+
+  it.each([...SHIPPED_LOCALES, REGION_VARIANT, UNSHIPPED_LOCALE])(
+    'names every tier in %s — never a key, never a slug, never empty',
+    (locale) => {
+      for (const tier of TRUST_TIERS) {
+        const label = trustTierLabel(locale, tier);
+        expect(label).not.toBe('');
+        expect(label).not.toBe(`trust.tiers.${tier}`);
+      }
+    },
+  );
+
+  it('falls back to English for a language with no tier translations', () => {
+    expect(trustTierLabel('de-DE', 'high_trust')).toBe(
+      EN_TRUST_TIER_LABELS.high_trust,
+    );
+  });
+
+  it('resolves a region variant through its base language', () => {
+    expect(trustTierLabel('es-MX', 'verified')).toBe(trustTierLabel('es-ES', 'verified'));
+    expect(trustTierLabel('es-MX', 'verified')).not.toBe(EN_TRUST_TIER_LABELS.verified);
+  });
+});

package/src/i18n/accountCategoryLabels.ts

@@ -0,0 +1,44 @@
+import type { AccountCategoryId } from '@oxy.so/contracts';
+import enUS from './locales/en-US.json';
+import { translate } from './index';
+
+/**
+ * Every account category's English name, keyed by its stable id.
+ *
+ * **The annotation is the point.** The vocabulary lives in `@oxy.so/contracts`
+ * and the names live in `locales/en-US.json`, so they are two lists that must
+ * agree and nothing but a type can make them. Declaring the JSON node as a
+ * TOTAL `Record<AccountCategoryId, string>` turns "somebody added a category at
+ * Oxy and nobody wrote its English" into a `TS2741` naming the missing id, at
+ * build time, instead of a picker row that paints `accounts.accountCategory.<id>`
+ * at a user trying to choose one.
+ *
+ * That failure is not hypothetical. The screen previously wrote `t(key) || id`,
+ * whose author believed an unnamed id would degrade to its raw slug. It cannot:
+ * {@link translate} echoes the KEY when it resolves nothing, and a non-empty
+ * string is never falsy, so the `|| id` arm was unreachable and the output was
+ * the dotted key. A runtime fallback that cannot run is worse than none,
+ * because it reads as protection.
+ *
+ * Totality is over `ACCOUNT_CATEGORY_IDS`, which RETAINS withdrawn ids, so an
+ * account still carrying a retired category keeps rendering its name while no
+ * picker offers it again. Retired and unknown are different cases: only an id
+ * outside the union is unnameable, which is why this is keyed by
+ * `AccountCategoryId` and not by `string`.
+ */
+/**
+ * Module-scoped, NOT re-exported from the package index: the annotation is the
+ * whole job, and it does that job without being public API. It carries no
+ * `Object.freeze` and no `Readonly<>` for the same reason — those existed only
+ * to make an exported reference safe from a consumer's stray write, and there
+ * is no such consumer. Exported from the MODULE so its own test can name it.
+ */
+export const EN_ACCOUNT_CATEGORY_LABELS: Record<AccountCategoryId, string> =
+  enUS.accounts.accountCategory;
+
+export function accountCategoryLabel(
+  locale: string | undefined,
+  id: AccountCategoryId,
+): string {
+  return translate(locale, `accounts.accountCategory.${id}`);
+}

package/src/i18n/accountRoleLabels.ts

@@ -0,0 +1,26 @@
+import type { AccountRole } from '../mixins/OxyServices.accounts';
+import enUS from './locales/en-US.json';
+import { translate } from './index';
+
+/**
+ * Every account member role's English name, keyed by its stable id.
+ *
+ * Totality is over the closed `AccountRole` union so a new role without an
+ * English label is a build error, not a members row that paints
+ * `accounts.roles.<role>.label`.
+ */
+export const EN_ACCOUNT_ROLE_LABELS: Record<AccountRole, string> = {
+  owner: enUS.accounts.roles.owner.label,
+  admin: enUS.accounts.roles.admin.label,
+  editor: enUS.accounts.roles.editor.label,
+  developer: enUS.accounts.roles.developer.label,
+  billing: enUS.accounts.roles.billing.label,
+  viewer: enUS.accounts.roles.viewer.label,
+};
+
+export function accountRoleLabel(
+  locale: string | undefined,
+  role: AccountRole,
+): string {
+  return translate(locale, `accounts.roles.${role}.label`);
+}