@oxy.so/protocol 1.1.3 → 1.2.0

package/dist/types/index.d.ts

@@ -29,5 +29,5 @@ export { registrationPowMessage, countLeadingZeroBits, meetsRegistrationPowDiffi
 export { isAuthorizedKey } from './identity/resolver';
 export type { VerificationMethodResolver, ResolvedVerificationMethods, KeyAuthorization, } from './identity/resolver';
 export { isReactNative, isNodeJS } from './platform/platform';
-export { loadNodeCrypto, loadExpoCrypto, loadSecureStore, loadAsyncStorage, getRandomBytesRN, loadSharedIdentityBridge, } from './platform/crypto';
-export type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge } from './platform/expoTypes';
+export { loadNodeCrypto, loadExpoCrypto, loadSecureStore, loadAsyncStorage, getRandomBytesRN, loadCommonsIdentityBridge, } from './platform/crypto';
+export type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike, } from './platform/expoTypes';

package/dist/types/platform/crypto.d.ts

@@ -71,8 +71,8 @@
  * see a file containing only specifiers it can understand — no tricks, no
  * runtime parsing risks.
  */
-import type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge } from './expoTypes';
-export type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge };
+import type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike } from './expoTypes';
+export type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike, };
 export declare function loadNodeCrypto(): Promise<typeof import('crypto')>;
 export declare function loadExpoCrypto(): Promise<ExpoCryptoLike>;
 export declare function loadSecureStore(): Promise<ExpoSecureStoreLike>;
@@ -84,4 +84,4 @@ export declare function loadAsyncStorage(): Promise<{
     };
 }>;
 export { getRandomBytesRN } from './random';
-export declare function loadSharedIdentityBridge(): Promise<SharedIdentityBridge | null>;
+export declare function loadCommonsIdentityBridge(): Promise<CommonsIdentityBridge | null>;

package/dist/types/platform/crypto.native.d.ts

@@ -51,8 +51,8 @@
  * `expo-modules-core` is a NON-optional peer (every RN app has it via `expo`),
  * so it stays a plain static import.
  */
-import type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge } from './expoTypes';
-export type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge };
+import type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike } from './expoTypes';
+export type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike, };
 /** Persistent KV storage surface used from `@react-native-async-storage/async-storage`. */
 type AsyncStorageLike = {
     getItem: (key: string) => Promise<string | null>;
@@ -66,4 +66,4 @@ export declare function loadAsyncStorage(): Promise<{
     default: AsyncStorageLike;
 }>;
 export { getRandomBytesRN } from './random.native';
-export declare function loadSharedIdentityBridge(): Promise<SharedIdentityBridge | null>;
+export declare function loadCommonsIdentityBridge(): Promise<CommonsIdentityBridge | null>;

package/dist/types/platform/expoTypes.d.ts

@@ -73,27 +73,59 @@ export interface ExpoSecureStoreLike {
      */
     readonly WHEN_UNLOCKED: number;
 }
+/** What Commons says about the identity it holds (`describe`). */
+export interface CommonsIdentityDescription {
+    /** Protocol version of the Commons identity host. */
+    v: number;
+    /** The identity's public key, lowercase uncompressed SEC1 hex. */
+    publicKey: string;
+}
+/**
+ * A signed server challenge from Commons (`proveIdentity`). The fields plug
+ * straight into `POST /auth/verify`: Commons signed
+ * `sha256("auth:${publicKey}:${challenge}:${timestamp}")`, DER hex.
+ */
+export interface CommonsIdentityProof {
+    publicKey: string;
+    signature: string;
+    timestamp: number;
+}
+/** A social-receive input signature from Commons (`signSocialReceive`). */
+export interface CommonsSocialReceiveSignature {
+    /** DER hex, low-S, over the 32-byte digest the caller sent. */
+    signature: string;
+    /** The child key's compressed SEC1 public key, for the scriptSig. */
+    publicKey: string;
+}
 /**
- * Structural interface for the `@oxy.so/expo-oxy-identity` native module — the
- * cross-app shared Oxy identity bridge.
+ * Structural interface for the `OxyIdentity` native module in
+ * `@oxy.so/services`: the client side of the identity Commons holds.
  *
- * On Android the keypair crosses the process boundary through a
- * signature-protected `ContentProvider` hosted by Commons; on iOS every method
- * is a no-op (the Keychain Access Group path in `@oxy.so/core`'s `KeyManager`
- * owns iOS sharing). Typed structurally here so `@oxy.so/protocol` and
- * `@oxy.so/core` can reference the bridge without a hard dependency on the
- * optional native module.
+ * On Android every method is one signature-protected `ContentProvider.call()`
+ * into Commons (`so.oxy.commons[.dev].identity`). Commons is the only app that
+ * holds the private key, and no method returns it or anything it can be
+ * recovered from: callers get the public key, signatures and domain-separated
+ * derivations, the way apps get tokens from `AccountManager`. Every method
+ * resolves `null` when Commons is not installed, holds no identity, or refuses
+ * the caller.
+ *
+ * On iOS the module is a stub that resolves `null`: the Keychain Access Group
+ * path in `@oxy.so/core`'s `KeyManager` owns iOS sharing.
  */
-export interface SharedIdentityBridge {
-    /** Read the shared keypair, or null when none is available on this device. */
-    getShared(): Promise<{
-        privateKey: string;
-        publicKey: string;
-    } | null>;
-    /** Persist the shared keypair into this app's hardware-backed store (Commons only). */
-    putShared(privateKey: string, publicKey: string): Promise<void>;
-    /** Whether a shared identity is readable on this device. */
-    hasShared(): Promise<boolean>;
-    /** Remove the shared identity from this app's local store (best-effort). */
-    clearShared(): Promise<void>;
+export interface CommonsIdentityBridge {
+    /** The public key of the identity Commons holds. */
+    describe(): Promise<CommonsIdentityDescription | null>;
+    /** Sign a server challenge (64 lowercase hex) for `POST /auth/verify`. */
+    proveIdentity(challenge: string): Promise<CommonsIdentityProof | null>;
+    /**
+     * HKDF-SHA256 over the identity key, 32 bytes as lowercase hex, identical to
+     * `KeyManager.deriveScopedSeed(info)` on the device that holds the key.
+     * Commons allows each caller package only its own `info` labels.
+     */
+    deriveScopedSeed(info: string): Promise<string | null>;
+    /**
+     * Sign a 32-byte digest (64 hex) with the social-receive child key `index`
+     * of the identity. Allowed for the wallet app only.
+     */
+    signSocialReceive(index: number, digest: string): Promise<CommonsSocialReceiveSignature | null>;
 }

package/dist/types/secp256k1.d.ts

@@ -41,5 +41,13 @@ export declare function normalizeSecp256k1PublicKey(publicKeyHex: string, compre
 export declare function signSecp256k1Digest(privateKeyHex: string, digestHex: string, options?: Secp256k1SignatureOptions): string;
 /** Verify a DER-encoded ECDSA signature, accepting historical high-S signatures. */
 export declare function verifySecp256k1Digest(publicKeyHex: string, digestHex: string, signatureDerHex: string): boolean;
+/**
+ * `(privateKey + tweak) mod n`, the scalar step of BIP32 non-hardened child
+ * derivation (`CKDpriv`: the tweak is `IL`, the left half of the HMAC-SHA512).
+ *
+ * Throws, as BIP32 requires, when the tweak is not below the curve order or
+ * the sum is zero: that child is invalid and the caller must not use it.
+ */
+export declare function tweakAddSecp256k1PrivateKey(privateKeyHex: string, tweakHex: string): string;
 /** Derive the fixed-width 32-byte ECDH x-coordinate shared secret. */
 export declare function deriveSecp256k1SharedSecret(privateKeyHex: string, publicKeyHex: string): Uint8Array;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/protocol",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Oxy Protocol — the app-agnostic base substrate: signed-record envelope, canonical JSON, signature/verification, and platform crypto. Reused by any Oxy app to decentralize its own content.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -131,7 +131,7 @@
   },
   "dependencies": {
     "@noble/curves": "^1.9.7",
-    "@oxy.so/contracts": "^3.0.0",
+    "@oxy.so/contracts": "^4.4.0",
     "zod": "^3.25.64"
   },
   "peerDependencies": {

package/src/__tests__/commonsIdentityBridge.test.ts

@@ -0,0 +1,109 @@
+/**
+ * The Commons identity bridge narrows every native answer to its exact shape.
+ *
+ * What `OxyIdentity` returns crossed a process boundary (a ContentProvider call
+ * into Commons), so a partial or malformed answer must read as "Commons could
+ * not help" (`null`), never as a half-filled value a caller then signs in with.
+ */
+
+const PUBLIC_KEY = `04${'ab'.repeat(64)}`;
+
+function mockNative(native: unknown): void {
+  jest.doMock('expo-modules-core', () => ({ requireOptionalNativeModule: () => native }), { virtual: true });
+}
+
+async function loadBridge() {
+  const mod = await import('../platform/crypto.native');
+  return mod.loadCommonsIdentityBridge();
+}
+
+describe('loadCommonsIdentityBridge (native)', () => {
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  test('null when the module is not linked', async () => {
+    mockNative(null);
+    await expect(loadBridge()).resolves.toBeNull();
+  });
+
+  test('null when the module predates the Commons methods', async () => {
+    mockNative({ getShared: async () => null });
+    await expect(loadBridge()).resolves.toBeNull();
+  });
+
+  test('passes well-formed answers through', async () => {
+    const calls: unknown[][] = [];
+    mockNative({
+      describe: async () => ({ v: 2, publicKey: PUBLIC_KEY }),
+      proveIdentity: async (challenge: string) => {
+        calls.push(['proveIdentity', challenge]);
+        return { publicKey: PUBLIC_KEY, signature: '3044aa', timestamp: 1_700_000_000_000 };
+      },
+      deriveScopedSeed: async (info: string) => {
+        calls.push(['deriveScopedSeed', info]);
+        return 'cd'.repeat(32);
+      },
+      signSocialReceive: async (index: number, digest: string) => {
+        calls.push(['signSocialReceive', index, digest]);
+        return { signature: '3045bb', publicKey: `02${'ef'.repeat(32)}` };
+      },
+    });
+    const bridge = await loadBridge();
+    expect(bridge).not.toBeNull();
+    await expect(bridge?.describe()).resolves.toEqual({ v: 2, publicKey: PUBLIC_KEY });
+    await expect(bridge?.proveIdentity('00'.repeat(32))).resolves.toEqual({
+      publicKey: PUBLIC_KEY,
+      signature: '3044aa',
+      timestamp: 1_700_000_000_000,
+    });
+    await expect(bridge?.deriveScopedSeed('peable/faircoin/v1')).resolves.toBe('cd'.repeat(32));
+    await expect(bridge?.signSocialReceive(3, '11'.repeat(32))).resolves.toEqual({
+      signature: '3045bb',
+      publicKey: `02${'ef'.repeat(32)}`,
+    });
+    expect(calls).toEqual([
+      ['proveIdentity', '00'.repeat(32)],
+      ['deriveScopedSeed', 'peable/faircoin/v1'],
+      ['signSocialReceive', 3, '11'.repeat(32)],
+    ]);
+  });
+
+  test('malformed or partial answers, and rejections, are null', async () => {
+    mockNative({
+      describe: async () => ({ v: 2, publicKey: 'not-hex' }),
+      proveIdentity: async () => ({ publicKey: PUBLIC_KEY, signature: '3044aa' }),
+      deriveScopedSeed: async () => 'cd'.repeat(16),
+      signSocialReceive: async () => {
+        throw new Error('refused');
+      },
+    });
+    const bridge = await loadBridge();
+    await expect(bridge?.describe()).resolves.toBeNull();
+    await expect(bridge?.proveIdentity('00'.repeat(32))).resolves.toBeNull();
+    await expect(bridge?.deriveScopedSeed('x')).resolves.toBeNull();
+    await expect(bridge?.signSocialReceive(0, '11'.repeat(32))).resolves.toBeNull();
+  });
+
+  test('the web / Node variant never has a bridge', async () => {
+    const mod = await import('../platform/crypto');
+    await expect(mod.loadCommonsIdentityBridge()).resolves.toBeNull();
+  });
+});
+
+describe('tweakAddSecp256k1PrivateKey', () => {
+  test('adds modulo the curve order and rejects invalid children', async () => {
+    const { tweakAddSecp256k1PrivateKey } = await import('../secp256k1');
+    expect(tweakAddSecp256k1PrivateKey('01', `${'0'.repeat(63)}2`)).toBe(`${'0'.repeat(63)}3`);
+    const nMinusOne = 'fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364140';
+    // (n - 1) + 2 wraps to 1.
+    expect(tweakAddSecp256k1PrivateKey(nMinusOne, `${'0'.repeat(63)}2`)).toBe(`${'0'.repeat(63)}1`);
+    // (n - 1) + 1 is zero: an invalid child.
+    expect(() => tweakAddSecp256k1PrivateKey(nMinusOne, `${'0'.repeat(63)}1`)).toThrow('zero');
+    // A tweak at or above n is invalid.
+    expect(() =>
+      tweakAddSecp256k1PrivateKey('01', 'fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141'),
+    ).toThrow('curve order');
+    expect(() => tweakAddSecp256k1PrivateKey('01', 'zz')).toThrow();
+  });
+});

package/src/index.ts

@@ -98,7 +98,7 @@ export {
   loadSecureStore,
   loadAsyncStorage,
   getRandomBytesRN,
-  loadSharedIdentityBridge,
+  loadCommonsIdentityBridge,
 } from './platform/crypto';
 
 // ---------------------------------------------------------------------------
@@ -108,4 +108,11 @@ export {
 // without importing `typeof import('expo-crypto')` / `typeof import('expo-secure-store')`
 // (which would trigger NodeNext type pollution in server packages).
 // ---------------------------------------------------------------------------
-export type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge } from './platform/expoTypes';
+export type {
+  CommonsIdentityBridge,
+  CommonsIdentityDescription,
+  CommonsIdentityProof,
+  CommonsSocialReceiveSignature,
+  ExpoCryptoLike,
+  ExpoSecureStoreLike,
+} from './platform/expoTypes';

package/src/platform/crypto.native.ts

@@ -53,13 +53,27 @@
  */
 
 import { requireOptionalNativeModule } from 'expo-modules-core';
-import type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge } from './expoTypes';
+import type {
+  CommonsIdentityBridge,
+  CommonsIdentityDescription,
+  CommonsIdentityProof,
+  CommonsSocialReceiveSignature,
+  ExpoCryptoLike,
+  ExpoSecureStoreLike,
+} from './expoTypes';
 import { missingOptionalPeerError } from './optionalPeer';
 import { requireExpoCrypto } from './random.native';
 
 // Re-export the interfaces so consumers can import them from the same
 // entry-point they use for the loaders (mirrors the default variant).
-export type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge };
+export type {
+  CommonsIdentityBridge,
+  CommonsIdentityDescription,
+  CommonsIdentityProof,
+  CommonsSocialReceiveSignature,
+  ExpoCryptoLike,
+  ExpoSecureStoreLike,
+};
 
 // ---------------------------------------------------------------------------
 // Optional peer resolution.
@@ -170,44 +184,98 @@ export async function loadAsyncStorage(): Promise<{ default: AsyncStorageLike }>
 export { getRandomBytesRN } from './random.native';
 
 // ---------------------------------------------------------------------------
-// Shared identity bridge — `@oxy.so/expo-oxy-identity` (native-only, OPTIONAL).
+// Commons identity bridge — the `OxyIdentity` native module in
+// `@oxy.so/services` (native-only, OPTIONAL).
+//
+// Resolved through expo-modules-core's `requireOptionalNativeModule`, a static
+// import Metro always resolves, never through a runtime-computed
+// `import(moduleName)`: that compiles to `require(variable)` in the CJS build,
+// which Metro cannot resolve in a consuming repo (the bridge silently resolved
+// `null` there once). `requireOptionalNativeModule` returns `null` when the
+// module is not autolinked (web, or an app without `@oxy.so/services`).
 //
-// `@oxy.so/expo-oxy-identity` is the in-repo Expo module autolinked into the
-// identity apps (Commons + the reader RPs). We resolve its NATIVE module
-// directly via expo-modules-core's `requireOptionalNativeModule('OxyIdentity')`
-// — a static import Metro always resolves — instead of dynamically importing the
-// module's JS wrapper. A runtime-computed `import(moduleName)` compiled to a
-// `require(variable)` in the CJS build, which Metro cannot resolve in a consuming
-// repo (the bridge silently resolved `null` there — the cross-app SSO bug). Since
-// the native module is what actually holds the shared identity, going through the
-// native registry is both correct and Metro-safe. `requireOptionalNativeModule`
-// returns `null` (never throws) when the module is not autolinked (web, or apps
-// that don't ship it), so `@oxy.so/core`'s `KeyManager` cleanly falls back to its
-// package-private store.
+// Everything the native side returns is UNTRUSTED here: it crossed a process
+// boundary. Each answer is narrowed to its exact shape, and anything else is
+// `null` ("Commons could not help"), never a partial value.
 // ---------------------------------------------------------------------------
 
-let sharedIdentityBridgePromise: Promise<SharedIdentityBridge | null> | null = null;
+interface OxyIdentityNativeModule {
+  describe(): Promise<unknown>;
+  proveIdentity(challenge: string): Promise<unknown>;
+  deriveScopedSeed(info: string): Promise<unknown>;
+  signSocialReceive(index: number, digest: string): Promise<unknown>;
+}
+
+const LOWER_HEX = /^[0-9a-f]+$/;
+
+function record(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+function hexField(value: unknown, length?: number): string | null {
+  if (typeof value !== 'string' || !LOWER_HEX.test(value)) return null;
+  if (length !== undefined && value.length !== length) return null;
+  return value;
+}
+
+function narrowDescription(value: unknown): CommonsIdentityDescription | null {
+  const r = record(value);
+  const publicKey = hexField(r?.publicKey, 130);
+  const v = typeof r?.v === 'number' ? r.v : Number(r?.v);
+  if (!publicKey || !Number.isInteger(v)) return null;
+  return { v, publicKey };
+}
+
+function narrowProof(value: unknown): CommonsIdentityProof | null {
+  const r = record(value);
+  const publicKey = hexField(r?.publicKey, 130);
+  const signature = hexField(r?.signature);
+  const timestamp = typeof r?.timestamp === 'number' ? r.timestamp : Number(r?.timestamp);
+  if (!publicKey || !signature || !Number.isSafeInteger(timestamp) || timestamp <= 0) return null;
+  return { publicKey, signature, timestamp };
+}
+
+function narrowSocialReceive(value: unknown): CommonsSocialReceiveSignature | null {
+  const r = record(value);
+  const signature = hexField(r?.signature);
+  const publicKey = hexField(r?.publicKey, 66);
+  if (!signature || !publicKey) return null;
+  return { signature, publicKey };
+}
+
+/** Run one native call; a rejection or an unexpected shape is `null`. */
+async function ask<T>(call: () => Promise<unknown>, narrow: (value: unknown) => T | null): Promise<T | null> {
+  try {
+    return narrow(await call());
+  } catch {
+    return null;
+  }
+}
+
+let commonsIdentityBridgePromise: Promise<CommonsIdentityBridge | null> | null = null;
 
-export function loadSharedIdentityBridge(): Promise<SharedIdentityBridge | null> {
-  if (!sharedIdentityBridgePromise) {
-    sharedIdentityBridgePromise = Promise.resolve().then(() => {
-      const native = requireOptionalNativeModule<Partial<SharedIdentityBridge>>('OxyIdentity');
+export function loadCommonsIdentityBridge(): Promise<CommonsIdentityBridge | null> {
+  if (!commonsIdentityBridgePromise) {
+    commonsIdentityBridgePromise = Promise.resolve().then(() => {
+      const native = requireOptionalNativeModule<Partial<OxyIdentityNativeModule>>('OxyIdentity');
       if (
-        native &&
-        typeof native.getShared === 'function' &&
-        typeof native.putShared === 'function' &&
-        typeof native.hasShared === 'function' &&
-        typeof native.clearShared === 'function'
+        !native ||
+        typeof native.describe !== 'function' ||
+        typeof native.proveIdentity !== 'function' ||
+        typeof native.deriveScopedSeed !== 'function' ||
+        typeof native.signSocialReceive !== 'function'
       ) {
-        return {
-          getShared: native.getShared.bind(native),
-          putShared: native.putShared.bind(native),
-          hasShared: native.hasShared.bind(native),
-          clearShared: native.clearShared.bind(native),
-        } satisfies SharedIdentityBridge;
+        return null;
       }
-      return null;
+      const m = native as OxyIdentityNativeModule;
+      return {
+        describe: () => ask(() => m.describe(), narrowDescription),
+        proveIdentity: (challenge: string) => ask(() => m.proveIdentity(challenge), narrowProof),
+        deriveScopedSeed: (info: string) => ask(() => m.deriveScopedSeed(info), (v) => hexField(v, 64)),
+        signSocialReceive: (index: number, digest: string) =>
+          ask(() => m.signSocialReceive(index, digest), narrowSocialReceive),
+      } satisfies CommonsIdentityBridge;
     });
   }
-  return sharedIdentityBridgePromise;
+  return commonsIdentityBridgePromise;
 }

package/src/platform/crypto.ts

@@ -73,11 +73,25 @@
  */
 
 import { isReactNative } from './platform';
-import type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge } from './expoTypes';
+import type {
+  CommonsIdentityBridge,
+  CommonsIdentityDescription,
+  CommonsIdentityProof,
+  CommonsSocialReceiveSignature,
+  ExpoCryptoLike,
+  ExpoSecureStoreLike,
+} from './expoTypes';
 
 // Re-export the interfaces so consumers can import them from the same
 // entry-point they use for the loaders.
-export type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge };
+export type {
+  CommonsIdentityBridge,
+  CommonsIdentityDescription,
+  CommonsIdentityProof,
+  CommonsSocialReceiveSignature,
+  ExpoCryptoLike,
+  ExpoSecureStoreLike,
+};
 
 // ---------------------------------------------------------------------------
 // Node `crypto` — Node built-in
@@ -154,14 +168,11 @@ export async function loadAsyncStorage(): Promise<{
 export { getRandomBytesRN } from './random';
 
 // ---------------------------------------------------------------------------
-// Shared identity bridge — `@oxy.so/expo-oxy-identity` (native-only).
+// Commons identity bridge — the `OxyIdentity` native module (native-only).
 //
-// The default (web / Node) variant has no cross-app identity channel, so this
-// always resolves to `null`. `@oxy.so/core`'s `KeyManager` treats `null` as "no
-// bridge" and falls back to its package-private store — which is correct on web
-// (there is no shared identity there).
+// Web and Node have no Commons to ask, so this always resolves to `null`.
 // ---------------------------------------------------------------------------
 
-export function loadSharedIdentityBridge(): Promise<SharedIdentityBridge | null> {
+export function loadCommonsIdentityBridge(): Promise<CommonsIdentityBridge | null> {
   return Promise.resolve(null);
 }

package/src/platform/expoTypes.ts

@@ -76,24 +76,62 @@ export interface ExpoSecureStoreLike {
   readonly WHEN_UNLOCKED: number;
 }
 
+/** What Commons says about the identity it holds (`describe`). */
+export interface CommonsIdentityDescription {
+  /** Protocol version of the Commons identity host. */
+  v: number;
+  /** The identity's public key, lowercase uncompressed SEC1 hex. */
+  publicKey: string;
+}
+
 /**
- * Structural interface for the `@oxy.so/expo-oxy-identity` native module — the
- * cross-app shared Oxy identity bridge.
+ * A signed server challenge from Commons (`proveIdentity`). The fields plug
+ * straight into `POST /auth/verify`: Commons signed
+ * `sha256("auth:${publicKey}:${challenge}:${timestamp}")`, DER hex.
+ */
+export interface CommonsIdentityProof {
+  publicKey: string;
+  signature: string;
+  timestamp: number;
+}
+
+/** A social-receive input signature from Commons (`signSocialReceive`). */
+export interface CommonsSocialReceiveSignature {
+  /** DER hex, low-S, over the 32-byte digest the caller sent. */
+  signature: string;
+  /** The child key's compressed SEC1 public key, for the scriptSig. */
+  publicKey: string;
+}
+
+/**
+ * Structural interface for the `OxyIdentity` native module in
+ * `@oxy.so/services`: the client side of the identity Commons holds.
+ *
+ * On Android every method is one signature-protected `ContentProvider.call()`
+ * into Commons (`so.oxy.commons[.dev].identity`). Commons is the only app that
+ * holds the private key, and no method returns it or anything it can be
+ * recovered from: callers get the public key, signatures and domain-separated
+ * derivations, the way apps get tokens from `AccountManager`. Every method
+ * resolves `null` when Commons is not installed, holds no identity, or refuses
+ * the caller.
  *
- * On Android the keypair crosses the process boundary through a
- * signature-protected `ContentProvider` hosted by Commons; on iOS every method
- * is a no-op (the Keychain Access Group path in `@oxy.so/core`'s `KeyManager`
- * owns iOS sharing). Typed structurally here so `@oxy.so/protocol` and
- * `@oxy.so/core` can reference the bridge without a hard dependency on the
- * optional native module.
+ * On iOS the module is a stub that resolves `null`: the Keychain Access Group
+ * path in `@oxy.so/core`'s `KeyManager` owns iOS sharing.
  */
-export interface SharedIdentityBridge {
-  /** Read the shared keypair, or null when none is available on this device. */
-  getShared(): Promise<{ privateKey: string; publicKey: string } | null>;
-  /** Persist the shared keypair into this app's hardware-backed store (Commons only). */
-  putShared(privateKey: string, publicKey: string): Promise<void>;
-  /** Whether a shared identity is readable on this device. */
-  hasShared(): Promise<boolean>;
-  /** Remove the shared identity from this app's local store (best-effort). */
-  clearShared(): Promise<void>;
+export interface CommonsIdentityBridge {
+  /** The public key of the identity Commons holds. */
+  describe(): Promise<CommonsIdentityDescription | null>;
+  /** Sign a server challenge (64 lowercase hex) for `POST /auth/verify`. */
+  proveIdentity(challenge: string): Promise<CommonsIdentityProof | null>;
+  /**
+   * HKDF-SHA256 over the identity key, 32 bytes as lowercase hex, identical to
+   * `KeyManager.deriveScopedSeed(info)` on the device that holds the key.
+   * Commons allows each caller package only its own `info` labels.
+   */
+  deriveScopedSeed(info: string): Promise<string | null>;
+  /**
+   * Sign a 32-byte digest (64 hex) with the social-receive child key `index`
+   * of the identity. Allowed for the wallet app only.
+   */
+  signSocialReceive(index: number, digest: string): Promise<CommonsSocialReceiveSignature | null>;
 }

package/src/secp256k1.ts

@@ -190,6 +190,33 @@ export function verifySecp256k1Digest(
   });
 }
 
+/**
+ * `(privateKey + tweak) mod n`, the scalar step of BIP32 non-hardened child
+ * derivation (`CKDpriv`: the tweak is `IL`, the left half of the HMAC-SHA512).
+ *
+ * Throws, as BIP32 requires, when the tweak is not below the curve order or
+ * the sum is zero: that child is invalid and the caller must not use it.
+ */
+export function tweakAddSecp256k1PrivateKey(
+  privateKeyHex: string,
+  tweakHex: string,
+): string {
+  const n = secp256k1.Point.Fn.ORDER;
+  const key = BigInt(`0x${normalizeSecp256k1PrivateKey(privateKeyHex)}`);
+  if (typeof tweakHex !== "string" || tweakHex.length !== 64 || !HEX.test(tweakHex)) {
+    throw new Error("secp256k1 tweak must be exactly 32 bytes of hexadecimal data");
+  }
+  const tweak = BigInt(`0x${tweakHex}`);
+  if (tweak >= n) {
+    throw new Error("secp256k1 tweak is not below the curve order");
+  }
+  const child = (key + tweak) % n;
+  if (child === 0n) {
+    throw new Error("secp256k1 tweaked private key is zero");
+  }
+  return child.toString(16).padStart(64, "0");
+}
+
 /** Derive the fixed-width 32-byte ECDH x-coordinate shared secret. */
 export function deriveSecp256k1SharedSecret(
   privateKeyHex: string,