@oxy.so/core 7.23.2 → 7.25.0

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/dist/types/server/appAssertion.d.ts

@@ -23,8 +23,8 @@ export declare const oxyAppAssertionClaimsSchema: z.ZodObject<{
     sid: z.ZodString;
     app: z.ZodString;
     platform: z.ZodEnum<{
-        android: "android";
         ios: "ios";
+        android: "android";
         web: "web";
     }>;
     iat: z.ZodNumber;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.23.2",
+  "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",
@@ -181,8 +181,8 @@
   "dependencies": {
     "@noble/ciphers": "^2.4.0",
     "@noble/hashes": "^2.4.0",
-    "@oxy.so/contracts": "^6.10.0",
-    "@oxy.so/protocol": "^1.6.1",
+    "@oxy.so/contracts": "^6.11.0",
+    "@oxy.so/protocol": "^1.7.0",
     "@oxy.so/telemetry": "^2.1.0",
     "@scure/bip39": "^2.4.0",
     "buffer": "^6.0.3",

package/src/api/accounts.ts

@@ -18,13 +18,26 @@ import type { AccountAccessGrant, OrganizationType } from '@oxy.so/contracts';
  * no per-request "acting-as" header. Identity is carried by the session/token,
  * so a switch propagates through reload and cross-domain exactly like a login.
  */
-import type { AgentKeyOperation, AgentKeyOperationProof } from '@oxy.so/contracts';
+import type {
+  AgentKeyOperation,
+  AgentKeyOperationProof,
+  OrganizationIdentityKeyState,
+  OrganizationKeyApplyRequest,
+  OrganizationKeyChallenge,
+  OrganizationKeyChallengeRequest,
+  OrganizationKeyOperation,
+} from '@oxy.so/contracts';
 import {
   agentKeyListResponseCheck,
   agentKeyOperationChallengeCheck,
   agentKeyOperationCheck,
   agentKeyOperationResultCheck,
   executeAgentKeyOperationCheck,
+  organizationIdentityKeyStateCheck,
+  organizationKeyApplyRequestCheck,
+  organizationKeyChallengeCheck,
+  organizationKeyChallengeRequestCheck,
+  organizationKeyProofClaims,
   parseContract,
 } from '@oxy.so/contracts/client';
 import type { User } from '../models/interfaces';
@@ -457,6 +470,124 @@ export class AccountAgentKeysApi {
   }
 }
 
+/** A secp256k1 key pair held on this device: lowercase hex, the public key uncompressed. */
+export interface OrganizationKeyPair {
+  privateKey: string;
+  publicKey: string;
+}
+
+/**
+ * `oxy.accounts.identityKey` — an organization's identity key (ADR 0061): its
+ * DID `#key-1`, the key Peable derives its FairCoin receive addresses from.
+ * Only the organization's owners and admins may read or change it; the key is
+ * created and held in Commons and never signs anybody in.
+ *
+ * `get` answers `publicKey: null` for an organization that has no key yet (its
+ * DID lists no `#key-1`): that is when a client shows its owners "Set up the
+ * organization's Peable wallet". A 403 (`ORGANIZATION_KEY_FORBIDDEN`) means the
+ * signed-in person is not an owner or admin of a claimed, active organization.
+ */
+export class AccountIdentityKeyApi {
+  constructor(private readonly ctx: OxyContext) {}
+
+  /** The organization's key (`null` without one) and every key it has had, oldest first. */
+  async get(accountId: string): Promise<OrganizationIdentityKeyState> {
+    return parseContract(
+      organizationIdentityKeyStateCheck,
+      await this.ctx.request<unknown>(
+        'GET',
+        `/accounts/${enc(accountId)}/identity-key`,
+        undefined,
+        { cache: false },
+      ),
+    );
+  }
+
+  /** A one-use challenge for one change, with the claims every signer signs. */
+  async requestChallenge(
+    accountId: string,
+    request: OrganizationKeyChallengeRequest,
+  ): Promise<OrganizationKeyChallenge> {
+    return parseContract(
+      organizationKeyChallengeCheck,
+      await this.ctx.request<unknown>(
+        'POST',
+        `/accounts/${enc(accountId)}/identity-key/challenge`,
+        parseContract(organizationKeyChallengeRequestCheck, request),
+        { cache: false },
+      ),
+    );
+  }
+
+  /** Apply a change with its signatures (see {@link link} for the whole ceremony). */
+  async apply(
+    accountId: string,
+    request: OrganizationKeyApplyRequest,
+  ): Promise<OrganizationIdentityKeyState> {
+    return parseContract(
+      organizationIdentityKeyStateCheck,
+      await this.ctx.request<unknown>(
+        'POST',
+        `/accounts/${enc(accountId)}/identity-key`,
+        parseContract(organizationKeyApplyRequestCheck, request),
+        { cache: false },
+      ),
+    );
+  }
+
+  /**
+   * Commons' whole ceremony. NATIVE-ONLY: the actor is THIS device's personal
+   * root (`KeyManager`), which must be the signed-in person's. `key` is the
+   * organization key the device generated (`create`, or `replace` with a new
+   * one); `previousKey` is the current organization key when the device holds
+   * it, so the replacement is recorded as proven by it.
+   */
+  async link(
+    accountId: string,
+    input: {
+      operation: OrganizationKeyOperation;
+      key: OrganizationKeyPair;
+      previousKey?: OrganizationKeyPair;
+    },
+  ): Promise<OrganizationIdentityKeyState> {
+    const { KeyManager, signIdentityProof } = await import('../crypto/index');
+    const [rootPrivateKey, rootPublicKey] = await Promise.all([
+      KeyManager.getPrivateKey(),
+      KeyManager.getPublicKey(),
+    ]);
+    if (!rootPrivateKey || !rootPublicKey) {
+      throw new Error('No identity on this device to sign with');
+    }
+    const challenge = await this.requestChallenge(accountId, {
+      operation: input.operation,
+      publicKey: input.key.publicKey,
+    });
+    const root = rootPublicKey.trim().toLowerCase();
+    if (challenge.actorPublicKey !== root) {
+      throw new Error("This device's identity is not the signed-in account's");
+    }
+    const sign = async (signer: OrganizationKeyPair, publicKey: string) =>
+      (
+        await signIdentityProof(
+          { privateKey: signer.privateKey, publicKey },
+          organizationKeyProofClaims(challenge, publicKey),
+        )
+      ).signature;
+    const previousPublicKey = challenge.previousPublicKey;
+    return this.apply(accountId, {
+      operation: input.operation,
+      publicKey: challenge.publicKey,
+      challenge: challenge.challenge,
+      expiresAt: challenge.expiresAt,
+      actorSignature: await sign({ privateKey: rootPrivateKey, publicKey: root }, root),
+      keySignature: await sign(input.key, challenge.publicKey),
+      ...(input.previousKey && previousPublicKey
+        ? { previousKeySignature: await sign(input.previousKey, previousPublicKey) }
+        : {}),
+    });
+  }
+}
+
 export interface AccountInvitation {
   id: string;
   accountId: string;
@@ -540,11 +671,14 @@ export class AccountsApi {
   readonly members: AccountMembersApi;
   readonly invitations: AccountInvitationsApi;
   readonly agentKeys: AccountAgentKeysApi;
+  /** An organization's identity key: its DID `#key-1` and Peable wallet key (ADR 0061). */
+  readonly identityKey: AccountIdentityKeyApi;
 
   constructor(private readonly ctx: OxyContext) {
     this.members = new AccountMembersApi(ctx);
     this.invitations = new AccountInvitationsApi(ctx);
     this.agentKeys = new AccountAgentKeysApi(ctx);
+    this.identityKey = new AccountIdentityKeyApi(ctx);
   }
 
   /**

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';

package/src/crypto/keyManager.ts

@@ -30,7 +30,8 @@ import {
 } from '@oxy.so/protocol/secp256k1';
 import { isDev, logger } from '../logger';
 import { deriveScopedSeedFromKey, signSocialReceiveDigest } from './identityDerivations';
-import type { IdentitySignerStore } from './identitySigner';
+import { type IdentitySignerStore, registerIdentitySignerStore } from './identitySigner';
+import { getOrganizationPrivateKey, isOrganizationAccountId } from './organizationKeys';
 import {
   type IdentityMarker,
   clearIdentityMarker,
@@ -457,6 +458,7 @@ export class KeyManager {
    */
   static setIdentitySignerStore(store: IdentitySignerStore | null): void {
     KeyManager.identitySignerStore = store;
+    registerIdentitySignerStore(store);
     KeyManager.invalidateSharedCache();
   }
 
@@ -3237,14 +3239,26 @@ export 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 async deriveScopedSeed(info: string): Promise<Uint8Array | null> {
+  static async deriveScopedSeed(
+    info: string,
+    opts?: { accountId?: string },
+  ): Promise<Uint8Array | null> {
     if (isWebPlatform()) {
       return null;
     }
+    if (opts?.accountId !== undefined) {
+      return KeyManager._deriveOrganizationScopedSeed(info, opts.accountId);
+    }
     if (isAndroid()) {
       if (KeyManager.identitySignerStore) {
         // Commons: its own key.
@@ -3263,6 +3277,28 @@ export class KeyManager {
     return deriveScopedSeedFromKey(privateKey, info);
   }
 
+  /**
+   * {@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 async _deriveOrganizationScopedSeed(
+    info: string,
+    accountId: string,
+  ): Promise<Uint8Array | null> {
+    if (!isOrganizationAccountId(accountId)) {
+      return null;
+    }
+    if (isAndroid() && !KeyManager.identitySignerStore) {
+      const bridge = await loadCommonsIdentityBridge();
+      const seed = (await bridge?.deriveScopedSeed(info, accountId)) ?? null;
+      return seed ? hexToBytes(seed) : null;
+    }
+    const privateKey = await getOrganizationPrivateKey(accountId);
+    return privateKey ? deriveScopedSeedFromKey(privateKey, info) : null;
+  }
+
   /**
    * Sign a 32-byte digest (a transaction sighash, lowercase hex) with the
    * identity's social-receive child key `index`: the non-hardened BIP32 child
@@ -3270,8 +3306,9 @@ export 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.
@@ -3279,10 +3316,24 @@ export class KeyManager {
   static async signSocialReceive(
     index: number,
     digest: string,
+    opts?: { accountId?: string },
   ): Promise<CommonsSocialReceiveSignature | null> {
     if (isWebPlatform()) {
       return null;
     }
+    const accountId = opts?.accountId;
+    if (accountId !== undefined) {
+      // An organization key (ADR 0061 D6); never the personal one in its place.
+      if (!isOrganizationAccountId(accountId)) {
+        return null;
+      }
+      if (isAndroid() && !KeyManager.identitySignerStore) {
+        const bridge = await loadCommonsIdentityBridge();
+        return (await bridge?.signSocialReceive(index, digest, accountId)) ?? null;
+      }
+      const organizationKey = await getOrganizationPrivateKey(accountId);
+      return organizationKey ? signSocialReceiveDigest(organizationKey, index, digest) : null;
+    }
     if (isAndroid() && !KeyManager.identitySignerStore) {
       // Every app but Commons: Commons signs.
       const bridge = await loadCommonsIdentityBridge();