@oxy.so/core 7.24.0 → 7.25.0

package/dist/esm/crypto/organizationKeys.js

@@ -0,0 +1,336 @@
+/**
+ * Organization keys on the device (ADR 0061 D6).
+ *
+ * An organization's identity key is created in Commons by one of its owners or
+ * admins, from a fresh 24-word phrase (`seed[0:32]`, the personal-root
+ * derivation), and is published as the organization's DID `#key-1`. Commons
+ * holds it beside the person's own root, under the organization's account id;
+ * other Oxy apps reach it the way they reach the personal identity, by
+ * derivation and never by the key:
+ *
+ * - iOS: the keychain access group `group.so.oxy.shared`, like the personal
+ *   shared slot. Only Commons writes it.
+ * - Android: Commons' own expo-secure-store slot, mirrored into the identity
+ *   signer store (`./identitySigner`) that Commons' identity host answers
+ *   `accountId` requests from. Every other app asks Commons over IPC
+ *   (`loadCommonsIdentityBridge`), and never gets the key.
+ *
+ * The phrase is kept only in Commons, on the device that created or imported
+ * it, so an owner can show it to another owner (ADR 0061 D5); it never reaches
+ * the keychain group, an IPC answer or a log.
+ *
+ * This module imports nothing from `./keyManager` (which imports it): the
+ * signer store comes from `./identitySigner`'s registry.
+ */
+import { generateMnemonic, mnemonicToSeed, validateMnemonic } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english.js';
+import { loadCommonsIdentityBridge, loadSecureStore, } from '@oxy.so/protocol';
+import { deriveSecp256k1PublicKey, isValidSecp256k1PrivateKey, isValidSecp256k1PublicKey, normalizeSecp256k1PrivateKey, normalizeSecp256k1PublicKey, } from '@oxy.so/protocol/secp256k1';
+import { logger } from '../logger/index.js';
+import { isAndroid, isIOS, isWeb } from '../utils/platform.js';
+import { registeredIdentitySignerStore } from './identitySigner.js';
+/** Same set the server's account ids come from: a legacy 24-hex id or a lowercase uuid. */
+const ACCOUNT_ID = /^(?:[0-9a-f]{24}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+const IOS_KEYCHAIN_GROUP = 'group.so.oxy.shared';
+/** Android, Commons-local: its own Keystore key, shared with no personal slot. */
+const ANDROID_KEYCHAIN_SERVICE = 'oxy_org_identity';
+const MNEMONIC_KEYCHAIN_SERVICE = 'oxy_org_identity_mnemonic';
+const INDEX_KEYCHAIN_SERVICE = 'oxy_org_identity_index';
+const INDEX_STORAGE_KEY = 'oxy_org_identity_index_v1';
+const ORGANIZATION_PHRASE_WORDS = 24;
+/** Whether `value` is an account id an organization key can be stored under. */
+export function isOrganizationAccountId(value) {
+    return ACCOUNT_ID.test(value);
+}
+function assertAccountId(accountId) {
+    if (!isOrganizationAccountId(accountId)) {
+        throw new Error('organization key: accountId must be a 24-hex or uuid account id');
+    }
+}
+const privateKeyName = (accountId) => `oxy_org_identity_private_key.${accountId}`;
+const publicKeyName = (accountId) => `oxy_org_identity_public_key.${accountId}`;
+const mnemonicName = (accountId) => `oxy_org_identity_mnemonic.${accountId}`;
+function toHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/** Lowercase uncompressed public key of `privateKey`. */
+function publicKeyOf(privateKey) {
+    return deriveSecp256k1PublicKey(normalizeSecp256k1PrivateKey(privateKey));
+}
+/** True only when both halves are well-formed AND the public key derives from the private one. */
+export function isHealthyOrganizationKeyPair(privateKey, publicKey) {
+    if (!privateKey || !publicKey)
+        return false;
+    if (!isValidSecp256k1PrivateKey(privateKey) || !isValidSecp256k1PublicKey(publicKey)) {
+        return false;
+    }
+    try {
+        return publicKeyOf(privateKey) === normalizeSecp256k1PublicKey(publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+function normalizePhrase(phrase) {
+    return phrase.trim().toLowerCase().split(/\s+/).join(' ');
+}
+async function pairFromPhrase(phrase) {
+    const normalized = normalizePhrase(phrase);
+    if (normalized.split(' ').length !== ORGANIZATION_PHRASE_WORDS ||
+        !validateMnemonic(normalized, wordlist)) {
+        throw new Error('organization key: not a valid 24-word recovery phrase');
+    }
+    const seed = await mnemonicToSeed(normalized);
+    const privateKey = toHex(seed.subarray(0, 32));
+    return { privateKey, publicKey: publicKeyOf(privateKey) };
+}
+/**
+ * A fresh organization key: a 24-word phrase and the pair derived from it
+ * exactly as a personal root is (`seed[0:32]`). Stores NOTHING: the caller shows
+ * the phrase, links the key (`oxy.accounts.identityKey`), and only then calls
+ * {@link storeOrganizationKey}.
+ */
+export async function generateOrganizationKey() {
+    const mnemonic = generateMnemonic(wordlist, 256);
+    return { mnemonic, ...(await pairFromPhrase(mnemonic)) };
+}
+/**
+ * The pair a 24-word organization phrase derives. Stores nothing; the caller
+ * checks the public key against the organization's DID `#key-1` before keeping
+ * it (ADR 0061 D5).
+ */
+export async function organizationKeyFromPhrase(phrase) {
+    return pairFromPhrase(phrase);
+}
+async function secureStore() {
+    return loadSecureStore();
+}
+async function readIndex(store) {
+    const raw = await store.getItemAsync(INDEX_STORAGE_KEY, {
+        keychainService: INDEX_KEYCHAIN_SERVICE,
+    });
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed)
+            ? parsed.filter((id) => typeof id === 'string' && isOrganizationAccountId(id))
+            : [];
+    }
+    catch (error) {
+        logger.warn('Organization key index unreadable; treating as empty', {
+            component: 'OrganizationKeys',
+            error: error instanceof Error ? error.name : 'unknown',
+        });
+        return [];
+    }
+}
+async function writeIndex(store, ids) {
+    await store.setItemAsync(INDEX_STORAGE_KEY, JSON.stringify([...new Set(ids)].sort()), {
+        keychainService: INDEX_KEYCHAIN_SERVICE,
+    });
+}
+/** Where this platform keeps the pair: the iOS keychain group, or Commons' own Android slot. */
+function pairOptions(store, forPrivateWrite) {
+    if (isIOS()) {
+        return forPrivateWrite
+            ? {
+                keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+                keychainAccessGroup: IOS_KEYCHAIN_GROUP,
+            }
+            : { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
+    }
+    return forPrivateWrite
+        ? {
+            keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+            keychainService: ANDROID_KEYCHAIN_SERVICE,
+        }
+        : { keychainService: ANDROID_KEYCHAIN_SERVICE };
+}
+/** The pair from this app's own storage (iOS group; Android Commons slot, then signer store). */
+async function readLocalPair(accountId) {
+    if (isWeb())
+        return null;
+    if (isAndroid()) {
+        const signer = registeredIdentitySignerStore();
+        if (!signer)
+            return null; // Only Commons holds organization keys on Android.
+        const store = await secureStore();
+        const options = pairOptions(store, false);
+        const privateKey = await store.getItemAsync(privateKeyName(accountId), options);
+        const publicKey = await store.getItemAsync(publicKeyName(accountId), options);
+        if (privateKey && publicKey && isHealthyOrganizationKeyPair(privateKey, publicKey)) {
+            return {
+                privateKey: normalizeSecp256k1PrivateKey(privateKey),
+                publicKey: normalizeSecp256k1PublicKey(publicKey),
+            };
+        }
+        // The signer store is a rung: a wiped expo-secure-store slot still has it.
+        const mirrored = (await signer.readOrganization?.(accountId)) ?? null;
+        return mirrored && isHealthyOrganizationKeyPair(mirrored.privateKey, mirrored.publicKey)
+            ? mirrored
+            : null;
+    }
+    if (!isIOS())
+        return null;
+    const store = await secureStore();
+    const options = pairOptions(store, false);
+    const privateKey = await store.getItemAsync(privateKeyName(accountId), options);
+    const publicKey = await store.getItemAsync(publicKeyName(accountId), options);
+    return privateKey && publicKey && isHealthyOrganizationKeyPair(privateKey, publicKey)
+        ? {
+            privateKey: normalizeSecp256k1PrivateKey(privateKey),
+            publicKey: normalizeSecp256k1PublicKey(publicKey),
+        }
+        : null;
+}
+/**
+ * Keep an organization key on this device. Commons only: on Android it needs
+ * the identity signer store Commons registers, so the identity host can serve
+ * it; on iOS only Commons calls it (the keychain group is shared).
+ *
+ * Refuses a pair whose public key does not derive from its private key, and a
+ * phrase that does not derive the pair. Overwrites whatever this device held for
+ * the organization (a replaced key is the caller's decision, ADR 0061 D7).
+ */
+export async function storeOrganizationKey(accountId, key) {
+    assertAccountId(accountId);
+    if (isWeb())
+        throw new Error('organization key: only a native device holds one');
+    if (!isHealthyOrganizationKeyPair(key.privateKey, key.publicKey)) {
+        throw new Error('organization key: the public key does not derive from the private key');
+    }
+    const privateKey = normalizeSecp256k1PrivateKey(key.privateKey);
+    const publicKey = normalizeSecp256k1PublicKey(key.publicKey);
+    if (key.mnemonic !== undefined) {
+        const fromPhrase = await pairFromPhrase(key.mnemonic);
+        if (fromPhrase.publicKey !== publicKey) {
+            throw new Error('organization key: the phrase derives a different key');
+        }
+    }
+    const signer = isAndroid() ? registeredIdentitySignerStore() : null;
+    if (isAndroid() && !signer?.writeOrganization) {
+        throw new Error('On Android only Commons holds organization keys; this app has no identity signer store for them.');
+    }
+    const store = await secureStore();
+    await store.setItemAsync(privateKeyName(accountId), privateKey, pairOptions(store, true));
+    await store.setItemAsync(publicKeyName(accountId), publicKey, pairOptions(store, false));
+    if (signer?.writeOrganization &&
+        !(await signer.writeOrganization(accountId, privateKey, publicKey))) {
+        throw new Error(`The identity signer store (${signer.name}) did not confirm the organization key.`);
+    }
+    if (key.mnemonic !== undefined) {
+        await store.setItemAsync(mnemonicName(accountId), normalizePhrase(key.mnemonic), {
+            keychainService: MNEMONIC_KEYCHAIN_SERVICE,
+            keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+        });
+    }
+    else {
+        await store.deleteItemAsync(mnemonicName(accountId), {
+            keychainService: MNEMONIC_KEYCHAIN_SERVICE,
+        });
+    }
+    await writeIndex(store, [...(await readIndex(store)), accountId]);
+}
+/**
+ * The organization's public key as THIS device can reach it, or `null`.
+ * iOS: the keychain group. Android: Commons' own slot inside Commons, and
+ * Commons' identity host (`describe` with `accountId`) everywhere else. Compare
+ * it with the organization's DID `#key-1` before receiving (Peable ADR 0002).
+ */
+export async function getOrganizationPublicKey(accountId) {
+    if (!isOrganizationAccountId(accountId) || isWeb())
+        return null;
+    try {
+        if (isAndroid() && !registeredIdentitySignerStore()) {
+            const bridge = await loadCommonsIdentityBridge();
+            const description = (await bridge?.describe(accountId)) ?? null;
+            return description?.accountId === accountId ? description.publicKey : null;
+        }
+        return (await readLocalPair(accountId))?.publicKey ?? null;
+    }
+    catch (error) {
+        logger.warn('Failed to read an organization public key', {
+            component: 'OrganizationKeys',
+            error: error instanceof Error ? error.name : 'unknown',
+        });
+        return null;
+    }
+}
+/**
+ * The organization's private key, where this app may hold it: Commons (both
+ * platforms) and, on iOS, the keychain group. `null` on Android outside
+ * Commons. Use it to sign within the app only; never transmit it.
+ */
+export async function getOrganizationPrivateKey(accountId) {
+    if (!isOrganizationAccountId(accountId))
+        return null;
+    try {
+        return (await readLocalPair(accountId))?.privateKey ?? null;
+    }
+    catch (error) {
+        logger.warn('Failed to read an organization private key', {
+            component: 'OrganizationKeys',
+            error: error instanceof Error ? error.name : 'unknown',
+        });
+        return null;
+    }
+}
+/** The organization's phrase, if this device created or imported it with one. Commons only. */
+export async function getOrganizationRecoveryPhrase(accountId) {
+    if (!isOrganizationAccountId(accountId) || isWeb())
+        return null;
+    const store = await secureStore();
+    return store.getItemAsync(mnemonicName(accountId), {
+        keychainService: MNEMONIC_KEYCHAIN_SERVICE,
+    });
+}
+/** The organizations this device keeps a key for (Commons' own index). */
+export async function listOrganizationKeys() {
+    if (isWeb())
+        return [];
+    return readIndex(await secureStore());
+}
+/** Forget an organization key on this device: its pair, its phrase, its signer copy and its index entry. */
+export async function deleteOrganizationKey(accountId) {
+    assertAccountId(accountId);
+    if (isWeb())
+        return;
+    const store = await secureStore();
+    const options = pairOptions(store, false);
+    await store.deleteItemAsync(privateKeyName(accountId), options);
+    await store.deleteItemAsync(publicKeyName(accountId), options);
+    await store.deleteItemAsync(mnemonicName(accountId), {
+        keychainService: MNEMONIC_KEYCHAIN_SERVICE,
+    });
+    const signer = isAndroid() ? registeredIdentitySignerStore() : null;
+    await signer?.clearOrganization?.(accountId);
+    await writeIndex(store, (await readIndex(store)).filter((id) => id !== accountId));
+}
+/**
+ * Commons on Android: copy every held organization key into the identity
+ * signer store again, so the identity host answers for it after that file was
+ * rebuilt (its self-heal leaves it empty). Call on every boot, beside
+ * `KeyManager.syncSharedIdentity`. Resolves how many it mirrored. Elsewhere 0.
+ */
+export async function syncOrganizationKeys() {
+    const signer = isAndroid() ? registeredIdentitySignerStore() : null;
+    if (!signer?.writeOrganization || !signer.readOrganization)
+        return 0;
+    const store = await secureStore();
+    let mirrored = 0;
+    for (const accountId of await readIndex(store)) {
+        const options = pairOptions(store, false);
+        const privateKey = await store.getItemAsync(privateKeyName(accountId), options);
+        const publicKey = await store.getItemAsync(publicKeyName(accountId), options);
+        if (!privateKey || !publicKey || !isHealthyOrganizationKeyPair(privateKey, publicKey))
+            continue;
+        const current = await signer.readOrganization(accountId);
+        if (current?.publicKey.toLowerCase() === publicKey.toLowerCase())
+            continue;
+        if (await signer.writeOrganization(accountId, normalizeSecp256k1PrivateKey(privateKey), publicKey.toLowerCase())) {
+            mirrored += 1;
+        }
+    }
+    return mirrored;
+}

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

@@ -26,4 +26,22 @@ export interface IdentitySignerStore {
     write(privateKey: string, publicKey: string): Promise<boolean>;
     /** Drop the stored key pair. */
     clear(): Promise<void>;
+    /**
+     * An ORGANIZATION key Commons holds (ADR 0061 D6), by the organization's
+     * account id: the copy the identity host answers `accountId` requests from.
+     * Optional so a store built before organization keys still type-checks; a
+     * store without them cannot hold an organization key.
+     */
+    readOrganization?(accountId: string): Promise<{
+        privateKey: string;
+        publicKey: string;
+    } | null>;
+    /** Replace that organization's pair. Resolves whether a read-back confirmed it. */
+    writeOrganization?(accountId: string, privateKey: string, publicKey: string): Promise<boolean>;
+    /** Drop that organization's pair. */
+    clearOrganization?(accountId: string): Promise<void>;
 }
+/** @internal */
+export declare function registerIdentitySignerStore(store: IdentitySignerStore | null): void;
+/** @internal */
+export declare function registeredIdentitySignerStore(): IdentitySignerStore | null;

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

@@ -17,6 +17,8 @@ export { readIdentityMarker, updateIdentityMarker } from './identityMarker';
 export type { IdentityMarker } from './identityMarker';
 export type { IdentityDeviceBackupStore } from './deviceBackup';
 export type { IdentitySignerStore } from './identitySigner';
+export { generateOrganizationKey, organizationKeyFromPhrase, storeOrganizationKey, getOrganizationPublicKey, getOrganizationPrivateKey, getOrganizationRecoveryPhrase, listOrganizationKeys, deleteOrganizationKey, syncOrganizationKeys, isOrganizationAccountId, isHealthyOrganizationKeyPair, } from './organizationKeys';
+export type { OrganizationKeyPair, GeneratedOrganizationKey, StoredOrganizationKey, } from './organizationKeys';
 export { SignatureService } from './signatureService';
 export type { SignedMessage, AuthChallenge } from './signatureService';
 export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase';

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

@@ -5,7 +5,7 @@
  * Private keys are stored securely using expo-secure-store and never leave the device.
  */
 import { type CommonsSocialReceiveSignature } from '@oxy.so/protocol';
-import type { IdentitySignerStore } from './identitySigner';
+import { type IdentitySignerStore } from './identitySigner';
 import { type IdentityMarker } from './identityMarker';
 import { type IdentityDeviceBackupStore } from './deviceBackup';
 /**
@@ -726,11 +726,26 @@ export declare class KeyManager {
      * Both reproduce from the user's Oxy recovery phrase, so the seed is
      * recoverable, and the IPC answer is byte-identical to the local one.
      *
+     * With `opts.accountId` the seed is derived from that ORGANIZATION's key
+     * instead (ADR 0061 D6), from the same places: Commons' own copy, the iOS
+     * keychain group, or Commons' identity host. It never falls back to the
+     * personal key.
+     *
      * @param info Context/domain-binding label (distinct labels → independent seeds).
+     * @param opts.accountId An organization's account id, for its key.
      * @returns 32 bytes of derived keying material, or `null` on web / when no
      *          identity key is available to this app.
      */
-    static deriveScopedSeed(info: string): Promise<Uint8Array | null>;
+    static deriveScopedSeed(info: string, opts?: {
+        accountId?: string;
+    }): Promise<Uint8Array | null>;
+    /**
+     * {@link deriveScopedSeed} over an ORGANIZATION key (ADR 0061 D6): Commons'
+     * own copy inside Commons and on iOS the keychain group, everywhere else on
+     * Android Commons' identity host. Never falls back to the personal key: an
+     * organization this device cannot reach is `null`.
+     */
+    private static _deriveOrganizationScopedSeed;
     /**
      * Sign a 32-byte digest (a transaction sighash, lowercase hex) with the
      * identity's social-receive child key `index`: the non-hardened BIP32 child
@@ -738,13 +753,16 @@ export declare class KeyManager {
      * signature is RFC 6979, low-S, DER hex; `publicKey` is the child's
      * compressed public key for the scriptSig.
      *
-     * Key source: as {@link deriveScopedSeed}. On Android outside Commons the
-     * signature comes from Commons, which allows it for the wallet app only.
+     * Key source: as {@link deriveScopedSeed}, including `opts.accountId` for an
+     * organization's key (ADR 0061 D6). On Android outside Commons the signature
+     * comes from Commons, which allows it for the wallet app only.
      *
      * @returns the signature, or `null` on web / when no identity key is
      *          available to this app.
      */
-    static signSocialReceive(index: number, digest: string): Promise<CommonsSocialReceiveSignature | null>;
+    static signSocialReceive(index: number, digest: string, opts?: {
+        accountId?: string;
+    }): Promise<CommonsSocialReceiveSignature | null>;
     /**
      * Get a shortened version of the public key for display
      * Format: first 8 chars...last 8 chars

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

@@ -0,0 +1,90 @@
+/**
+ * Organization keys on the device (ADR 0061 D6).
+ *
+ * An organization's identity key is created in Commons by one of its owners or
+ * admins, from a fresh 24-word phrase (`seed[0:32]`, the personal-root
+ * derivation), and is published as the organization's DID `#key-1`. Commons
+ * holds it beside the person's own root, under the organization's account id;
+ * other Oxy apps reach it the way they reach the personal identity, by
+ * derivation and never by the key:
+ *
+ * - iOS: the keychain access group `group.so.oxy.shared`, like the personal
+ *   shared slot. Only Commons writes it.
+ * - Android: Commons' own expo-secure-store slot, mirrored into the identity
+ *   signer store (`./identitySigner`) that Commons' identity host answers
+ *   `accountId` requests from. Every other app asks Commons over IPC
+ *   (`loadCommonsIdentityBridge`), and never gets the key.
+ *
+ * The phrase is kept only in Commons, on the device that created or imported
+ * it, so an owner can show it to another owner (ADR 0061 D5); it never reaches
+ * the keychain group, an IPC answer or a log.
+ *
+ * This module imports nothing from `./keyManager` (which imports it): the
+ * signer store comes from `./identitySigner`'s registry.
+ */
+/** A secp256k1 pair: private key 64 hex, public key lowercase uncompressed (`04…`, 130 hex). */
+export interface OrganizationKeyPair {
+    privateKey: string;
+    publicKey: string;
+}
+/** A new organization key and the 24-word phrase it derives from. */
+export interface GeneratedOrganizationKey extends OrganizationKeyPair {
+    mnemonic: string;
+}
+/** What {@link storeOrganizationKey} keeps: the pair, and the phrase when the device has it. */
+export interface StoredOrganizationKey extends OrganizationKeyPair {
+    mnemonic?: string;
+}
+/** Whether `value` is an account id an organization key can be stored under. */
+export declare function isOrganizationAccountId(value: string): boolean;
+/** True only when both halves are well-formed AND the public key derives from the private one. */
+export declare function isHealthyOrganizationKeyPair(privateKey: string | null | undefined, publicKey: string | null | undefined): boolean;
+/**
+ * A fresh organization key: a 24-word phrase and the pair derived from it
+ * exactly as a personal root is (`seed[0:32]`). Stores NOTHING: the caller shows
+ * the phrase, links the key (`oxy.accounts.identityKey`), and only then calls
+ * {@link storeOrganizationKey}.
+ */
+export declare function generateOrganizationKey(): Promise<GeneratedOrganizationKey>;
+/**
+ * The pair a 24-word organization phrase derives. Stores nothing; the caller
+ * checks the public key against the organization's DID `#key-1` before keeping
+ * it (ADR 0061 D5).
+ */
+export declare function organizationKeyFromPhrase(phrase: string): Promise<OrganizationKeyPair>;
+/**
+ * Keep an organization key on this device. Commons only: on Android it needs
+ * the identity signer store Commons registers, so the identity host can serve
+ * it; on iOS only Commons calls it (the keychain group is shared).
+ *
+ * Refuses a pair whose public key does not derive from its private key, and a
+ * phrase that does not derive the pair. Overwrites whatever this device held for
+ * the organization (a replaced key is the caller's decision, ADR 0061 D7).
+ */
+export declare function storeOrganizationKey(accountId: string, key: StoredOrganizationKey): Promise<void>;
+/**
+ * The organization's public key as THIS device can reach it, or `null`.
+ * iOS: the keychain group. Android: Commons' own slot inside Commons, and
+ * Commons' identity host (`describe` with `accountId`) everywhere else. Compare
+ * it with the organization's DID `#key-1` before receiving (Peable ADR 0002).
+ */
+export declare function getOrganizationPublicKey(accountId: string): Promise<string | null>;
+/**
+ * The organization's private key, where this app may hold it: Commons (both
+ * platforms) and, on iOS, the keychain group. `null` on Android outside
+ * Commons. Use it to sign within the app only; never transmit it.
+ */
+export declare function getOrganizationPrivateKey(accountId: string): Promise<string | null>;
+/** The organization's phrase, if this device created or imported it with one. Commons only. */
+export declare function getOrganizationRecoveryPhrase(accountId: string): Promise<string | null>;
+/** The organizations this device keeps a key for (Commons' own index). */
+export declare function listOrganizationKeys(): Promise<string[]>;
+/** Forget an organization key on this device: its pair, its phrase, its signer copy and its index entry. */
+export declare function deleteOrganizationKey(accountId: string): Promise<void>;
+/**
+ * Commons on Android: copy every held organization key into the identity
+ * signer store again, so the identity host answers for it after that file was
+ * rebuilt (its self-heal leaves it empty). Call on every boot, beside
+ * `KeyManager.syncSharedIdentity`. Resolves how many it mirrored. Elsewhere 0.
+ */
+export declare function syncOrganizationKeys(): Promise<number>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.24.0",
+  "version": "7.25.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -182,7 +182,7 @@
     "@noble/ciphers": "^2.4.0",
     "@noble/hashes": "^2.4.0",
     "@oxy.so/contracts": "^6.11.0",
-    "@oxy.so/protocol": "^1.6.1",
+    "@oxy.so/protocol": "^1.7.0",
     "@oxy.so/telemetry": "^2.1.0",
     "@scure/bip39": "^2.4.0",
     "buffer": "^6.0.3",

package/src/crypto/identitySigner.ts

@@ -23,4 +23,32 @@ export interface IdentitySignerStore {
   write(privateKey: string, publicKey: string): Promise<boolean>;
   /** Drop the stored key pair. */
   clear(): Promise<void>;
+  /**
+   * An ORGANIZATION key Commons holds (ADR 0061 D6), by the organization's
+   * account id: the copy the identity host answers `accountId` requests from.
+   * Optional so a store built before organization keys still type-checks; a
+   * store without them cannot hold an organization key.
+   */
+  readOrganization?(accountId: string): Promise<{ privateKey: string; publicKey: string } | null>;
+  /** Replace that organization's pair. Resolves whether a read-back confirmed it. */
+  writeOrganization?(accountId: string, privateKey: string, publicKey: string): Promise<boolean>;
+  /** Drop that organization's pair. */
+  clearOrganization?(accountId: string): Promise<void>;
+}
+
+/**
+ * The store Commons registered, readable by modules that `KeyManager` itself
+ * imports (`./organizationKeys`), which therefore cannot import `KeyManager`.
+ * Written only by `KeyManager.setIdentitySignerStore`. @internal
+ */
+let registeredSignerStore: IdentitySignerStore | null = null;
+
+/** @internal */
+export function registerIdentitySignerStore(store: IdentitySignerStore | null): void {
+  registeredSignerStore = store;
+}
+
+/** @internal */
+export function registeredIdentitySignerStore(): IdentitySignerStore | null {
+  return registeredSignerStore;
 }

package/src/crypto/index.ts

@@ -26,6 +26,25 @@ export { readIdentityMarker, updateIdentityMarker } from './identityMarker';
 export type { IdentityMarker } from './identityMarker';
 export type { IdentityDeviceBackupStore } from './deviceBackup';
 export type { IdentitySignerStore } from './identitySigner';
+// Organization keys on the device (docs/adr/0061-organization-identity-key.md D6)
+export {
+  generateOrganizationKey,
+  organizationKeyFromPhrase,
+  storeOrganizationKey,
+  getOrganizationPublicKey,
+  getOrganizationPrivateKey,
+  getOrganizationRecoveryPhrase,
+  listOrganizationKeys,
+  deleteOrganizationKey,
+  syncOrganizationKeys,
+  isOrganizationAccountId,
+  isHealthyOrganizationKeyPair,
+} from './organizationKeys';
+export type {
+  OrganizationKeyPair,
+  GeneratedOrganizationKey,
+  StoredOrganizationKey,
+} from './organizationKeys';
 export { SignatureService } from './signatureService';
 export type { SignedMessage, AuthChallenge } from './signatureService';
 export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase';