@oxy.so/protocol 1.6.1 → 1.8.0

package/dist/cjs/index.js

@@ -11,7 +11,7 @@
  * subpath so they never enter React Native / web bundles.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadCommonsIdentityBridge = exports.getRandomBytesRN = exports.loadAsyncStorage = exports.loadSecureStore = exports.loadExpoCrypto = exports.loadNodeCrypto = exports.isNodeJS = exports.isReactNative = exports.isAuthorizedKey = exports.REGISTRATION_POW_DIFFICULTY_BITS = exports.meetsRegistrationPowDifficulty = exports.countLeadingZeroBits = exports.registrationPowMessage = exports.verifyCheckpointSignature = exports.signCheckpoint = exports.checkpointHash = exports.checkpointSigningInput = exports.verifyInclusionProof = exports.inclusionProof = exports.buildTransparencyTreeFromHeads = exports.buildTransparencyTree = exports.transparencyLeafHash = exports.EMPTY_TRANSPARENCY_ROOT = exports.verifyAndAppend = exports.DEFAULT_CLOCK_SKEW_MS = exports.verifyEnvelope = exports.checkContinuity = exports.UNCHAINED_SEQ = exports.verifyEnvelopeSignature = exports.signEnvelope = exports.verifySignature = exports.signMessage = exports.computeRecordId = exports.sha256 = exports.signedRecordSigningInput = exports.canonicalize = void 0;
+exports.loadKeychainDefaultAccessGroup = exports.loadCommonsIdentityBridge = exports.getRandomBytesRN = exports.loadAsyncStorage = exports.loadSecureStore = exports.loadExpoCrypto = exports.loadNodeCrypto = exports.isNodeJS = exports.isReactNative = exports.isAuthorizedKey = exports.REGISTRATION_POW_DIFFICULTY_BITS = exports.meetsRegistrationPowDifficulty = exports.countLeadingZeroBits = exports.registrationPowMessage = exports.verifyCheckpointSignature = exports.signCheckpoint = exports.checkpointHash = exports.checkpointSigningInput = exports.verifyInclusionProof = exports.inclusionProof = exports.buildTransparencyTreeFromHeads = exports.buildTransparencyTree = exports.transparencyLeafHash = exports.EMPTY_TRANSPARENCY_ROOT = exports.verifyAndAppend = exports.DEFAULT_CLOCK_SKEW_MS = exports.verifyEnvelope = exports.checkContinuity = exports.UNCHAINED_SEQ = exports.verifyEnvelopeSignature = exports.signEnvelope = exports.verifySignature = exports.signMessage = exports.computeRecordId = exports.sha256 = exports.signedRecordSigningInput = exports.canonicalize = void 0;
 // ---------------------------------------------------------------------------
 // Envelope — canonical JSON, signing input, content address, signing/verify
 // ---------------------------------------------------------------------------
@@ -77,3 +77,4 @@ Object.defineProperty(exports, "loadSecureStore", { enumerable: true, get: funct
 Object.defineProperty(exports, "loadAsyncStorage", { enumerable: true, get: function () { return crypto_1.loadAsyncStorage; } });
 Object.defineProperty(exports, "getRandomBytesRN", { enumerable: true, get: function () { return crypto_1.getRandomBytesRN; } });
 Object.defineProperty(exports, "loadCommonsIdentityBridge", { enumerable: true, get: function () { return crypto_1.loadCommonsIdentityBridge; } });
+Object.defineProperty(exports, "loadKeychainDefaultAccessGroup", { enumerable: true, get: function () { return crypto_1.loadKeychainDefaultAccessGroup; } });

package/dist/cjs/platform/crypto.js

@@ -112,6 +112,7 @@ exports.loadExpoCrypto = loadExpoCrypto;
 exports.loadSecureStore = loadSecureStore;
 exports.loadAsyncStorage = loadAsyncStorage;
 exports.loadCommonsIdentityBridge = loadCommonsIdentityBridge;
+exports.loadKeychainDefaultAccessGroup = loadKeychainDefaultAccessGroup;
 const platform_1 = require("./platform");
 // ---------------------------------------------------------------------------
 // Node `crypto` — Node built-in
@@ -177,3 +178,9 @@ Object.defineProperty(exports, "getRandomBytesRN", { enumerable: true, get: func
 function loadCommonsIdentityBridge() {
     return Promise.resolve(null);
 }
+// ---------------------------------------------------------------------------
+// iOS keychain default access group — native-only; off RN there is no keychain.
+// ---------------------------------------------------------------------------
+function loadKeychainDefaultAccessGroup() {
+    return Promise.resolve({ state: 'unsupported' });
+}

package/dist/cjs/platform/crypto.native.js

@@ -59,6 +59,7 @@ exports.loadExpoCrypto = loadExpoCrypto;
 exports.loadSecureStore = loadSecureStore;
 exports.loadAsyncStorage = loadAsyncStorage;
 exports.loadCommonsIdentityBridge = loadCommonsIdentityBridge;
+exports.loadKeychainDefaultAccessGroup = loadKeychainDefaultAccessGroup;
 const expo_modules_core_1 = require("expo-modules-core");
 const optionalPeer_1 = require("./optionalPeer");
 const random_native_1 = require("./random.native");
@@ -151,6 +152,20 @@ function narrowDescription(value) {
         return null;
     return { v, publicKey };
 }
+/**
+ * The organization answer must name the organization asked for. A Commons that
+ * predates organization keys ignores the `accountId` extra and answers for the
+ * PERSONAL identity, without an echo; that answer is refused here, because a
+ * personal key taken for an organization's is money sent to the wrong person.
+ */
+function echoes(value, accountId) {
+    const r = record(value);
+    return r && r.accountId === accountId ? r : null;
+}
+function narrowOrganizationDescription(value, accountId) {
+    const description = narrowDescription(echoes(value, accountId));
+    return description ? { ...description, accountId } : null;
+}
 function narrowProof(value) {
     const r = record(value);
     const publicKey = hexField(r?.publicKey, 130);
@@ -191,12 +206,77 @@ function loadCommonsIdentityBridge() {
             }
             const m = native;
             return {
-                describe: () => ask(() => m.describe(), narrowDescription),
+                describe: (accountId) => {
+                    if (accountId === undefined)
+                        return ask(() => m.describe(), narrowDescription);
+                    const describeOrganization = m.describeOrganization;
+                    if (typeof describeOrganization !== 'function')
+                        return Promise.resolve(null);
+                    return ask(() => describeOrganization.call(m, accountId), (v) => narrowOrganizationDescription(v, accountId));
+                },
                 proveIdentity: (challenge) => ask(() => m.proveIdentity(challenge), narrowProof),
-                deriveScopedSeed: (info) => ask(() => m.deriveScopedSeed(info), (v) => hexField(v, 64)),
-                signSocialReceive: (index, digest) => ask(() => m.signSocialReceive(index, digest), narrowSocialReceive),
+                deriveScopedSeed: (info, accountId) => {
+                    if (accountId === undefined) {
+                        return ask(() => m.deriveScopedSeed(info), (v) => hexField(v, 64));
+                    }
+                    const derive = m.deriveOrganizationScopedSeed;
+                    if (typeof derive !== 'function')
+                        return Promise.resolve(null);
+                    return ask(() => derive.call(m, info, accountId), (v) => hexField(echoes(v, accountId)?.seed, 64));
+                },
+                signSocialReceive: (index, digest, accountId) => {
+                    if (accountId === undefined) {
+                        return ask(() => m.signSocialReceive(index, digest), narrowSocialReceive);
+                    }
+                    const sign = m.signOrganizationSocialReceive;
+                    if (typeof sign !== 'function')
+                        return Promise.resolve(null);
+                    return ask(() => sign.call(m, index, digest, accountId), (v) => narrowSocialReceive(echoes(v, accountId)));
+                },
             };
         });
     }
     return commonsIdentityBridgePromise;
 }
+// ---------------------------------------------------------------------------
+// iOS keychain default access group (docs/identity/ios-keychain-access-groups.md).
+//
+// Resolved once the native module answers; an `unavailable` probe (a thrown
+// call: before first unlock, or the keychain refused) is not memoized, so the
+// next caller asks again. The answer is narrowed to a plain string — it crossed
+// the native boundary.
+// ---------------------------------------------------------------------------
+/** `<prefix>.<group>`: an App ID prefix (no dots) then a non-empty group. */
+const ACCESS_GROUP = /^[A-Za-z0-9]+\.[A-Za-z0-9.-]+$/;
+let keychainDefaultAccessGroup = null;
+async function loadKeychainDefaultAccessGroup() {
+    if (keychainDefaultAccessGroup) {
+        return keychainDefaultAccessGroup;
+    }
+    const native = (0, expo_modules_core_1.requireOptionalNativeModule)('OxyIdentity');
+    const probe = native?.keychainDefaultAccessGroup;
+    if (!native || typeof probe !== 'function') {
+        keychainDefaultAccessGroup = { state: 'unsupported' };
+        return keychainDefaultAccessGroup;
+    }
+    let answer;
+    try {
+        answer = await probe.call(native);
+    }
+    catch (cause) {
+        return { state: 'unavailable', cause };
+    }
+    if (answer === null || answer === undefined) {
+        // The native side runs only on iOS; anything else answers nothing.
+        keychainDefaultAccessGroup = { state: 'unsupported' };
+        return keychainDefaultAccessGroup;
+    }
+    if (typeof answer !== 'string' || !ACCESS_GROUP.test(answer)) {
+        return {
+            state: 'unavailable',
+            cause: new Error('keychain probe answered something that is not an access group'),
+        };
+    }
+    keychainDefaultAccessGroup = { state: 'resolved', accessGroup: answer };
+    return keychainDefaultAccessGroup;
+}

package/dist/esm/index.js

@@ -37,4 +37,4 @@ export { isAuthorizedKey } from './identity/resolver.js';
 // Platform — runtime predicates + lazy crypto/storage loaders
 // ---------------------------------------------------------------------------
 export { isReactNative, isNodeJS } from './platform/platform.js';
-export { loadNodeCrypto, loadExpoCrypto, loadSecureStore, loadAsyncStorage, getRandomBytesRN, loadCommonsIdentityBridge, } from './platform/crypto.js';
+export { loadNodeCrypto, loadExpoCrypto, loadSecureStore, loadAsyncStorage, getRandomBytesRN, loadCommonsIdentityBridge, loadKeychainDefaultAccessGroup, } from './platform/crypto.js';

package/dist/esm/platform/crypto.js

@@ -135,3 +135,9 @@ export { getRandomBytesRN } from './random.js';
 export function loadCommonsIdentityBridge() {
     return Promise.resolve(null);
 }
+// ---------------------------------------------------------------------------
+// iOS keychain default access group — native-only; off RN there is no keychain.
+// ---------------------------------------------------------------------------
+export function loadKeychainDefaultAccessGroup() {
+    return Promise.resolve({ state: 'unsupported' });
+}

package/dist/esm/platform/crypto.native.js

@@ -142,6 +142,20 @@ function narrowDescription(value) {
         return null;
     return { v, publicKey };
 }
+/**
+ * The organization answer must name the organization asked for. A Commons that
+ * predates organization keys ignores the `accountId` extra and answers for the
+ * PERSONAL identity, without an echo; that answer is refused here, because a
+ * personal key taken for an organization's is money sent to the wrong person.
+ */
+function echoes(value, accountId) {
+    const r = record(value);
+    return r && r.accountId === accountId ? r : null;
+}
+function narrowOrganizationDescription(value, accountId) {
+    const description = narrowDescription(echoes(value, accountId));
+    return description ? { ...description, accountId } : null;
+}
 function narrowProof(value) {
     const r = record(value);
     const publicKey = hexField(r?.publicKey, 130);
@@ -182,12 +196,77 @@ export function loadCommonsIdentityBridge() {
             }
             const m = native;
             return {
-                describe: () => ask(() => m.describe(), narrowDescription),
+                describe: (accountId) => {
+                    if (accountId === undefined)
+                        return ask(() => m.describe(), narrowDescription);
+                    const describeOrganization = m.describeOrganization;
+                    if (typeof describeOrganization !== 'function')
+                        return Promise.resolve(null);
+                    return ask(() => describeOrganization.call(m, accountId), (v) => narrowOrganizationDescription(v, accountId));
+                },
                 proveIdentity: (challenge) => ask(() => m.proveIdentity(challenge), narrowProof),
-                deriveScopedSeed: (info) => ask(() => m.deriveScopedSeed(info), (v) => hexField(v, 64)),
-                signSocialReceive: (index, digest) => ask(() => m.signSocialReceive(index, digest), narrowSocialReceive),
+                deriveScopedSeed: (info, accountId) => {
+                    if (accountId === undefined) {
+                        return ask(() => m.deriveScopedSeed(info), (v) => hexField(v, 64));
+                    }
+                    const derive = m.deriveOrganizationScopedSeed;
+                    if (typeof derive !== 'function')
+                        return Promise.resolve(null);
+                    return ask(() => derive.call(m, info, accountId), (v) => hexField(echoes(v, accountId)?.seed, 64));
+                },
+                signSocialReceive: (index, digest, accountId) => {
+                    if (accountId === undefined) {
+                        return ask(() => m.signSocialReceive(index, digest), narrowSocialReceive);
+                    }
+                    const sign = m.signOrganizationSocialReceive;
+                    if (typeof sign !== 'function')
+                        return Promise.resolve(null);
+                    return ask(() => sign.call(m, index, digest, accountId), (v) => narrowSocialReceive(echoes(v, accountId)));
+                },
             };
         });
     }
     return commonsIdentityBridgePromise;
 }
+// ---------------------------------------------------------------------------
+// iOS keychain default access group (docs/identity/ios-keychain-access-groups.md).
+//
+// Resolved once the native module answers; an `unavailable` probe (a thrown
+// call: before first unlock, or the keychain refused) is not memoized, so the
+// next caller asks again. The answer is narrowed to a plain string — it crossed
+// the native boundary.
+// ---------------------------------------------------------------------------
+/** `<prefix>.<group>`: an App ID prefix (no dots) then a non-empty group. */
+const ACCESS_GROUP = /^[A-Za-z0-9]+\.[A-Za-z0-9.-]+$/;
+let keychainDefaultAccessGroup = null;
+export async function loadKeychainDefaultAccessGroup() {
+    if (keychainDefaultAccessGroup) {
+        return keychainDefaultAccessGroup;
+    }
+    const native = requireOptionalNativeModule('OxyIdentity');
+    const probe = native?.keychainDefaultAccessGroup;
+    if (!native || typeof probe !== 'function') {
+        keychainDefaultAccessGroup = { state: 'unsupported' };
+        return keychainDefaultAccessGroup;
+    }
+    let answer;
+    try {
+        answer = await probe.call(native);
+    }
+    catch (cause) {
+        return { state: 'unavailable', cause };
+    }
+    if (answer === null || answer === undefined) {
+        // The native side runs only on iOS; anything else answers nothing.
+        keychainDefaultAccessGroup = { state: 'unsupported' };
+        return keychainDefaultAccessGroup;
+    }
+    if (typeof answer !== 'string' || !ACCESS_GROUP.test(answer)) {
+        return {
+            state: 'unavailable',
+            cause: new Error('keychain probe answered something that is not an access group'),
+        };
+    }
+    keychainDefaultAccessGroup = { state: 'resolved', accessGroup: answer };
+    return keychainDefaultAccessGroup;
+}

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, loadCommonsIdentityBridge, } from './platform/crypto';
-export type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike, } from './platform/expoTypes';
+export { loadNodeCrypto, loadExpoCrypto, loadSecureStore, loadAsyncStorage, getRandomBytesRN, loadCommonsIdentityBridge, loadKeychainDefaultAccessGroup, } from './platform/crypto';
+export type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike, KeychainDefaultAccessGroup, } 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 { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike } from './expoTypes';
-export type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike, };
+import type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike, KeychainDefaultAccessGroup } from './expoTypes';
+export type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike, KeychainDefaultAccessGroup, };
 export declare function loadNodeCrypto(): Promise<typeof import('crypto')>;
 export declare function loadExpoCrypto(): Promise<ExpoCryptoLike>;
 export declare function loadSecureStore(): Promise<ExpoSecureStoreLike>;
@@ -85,3 +85,4 @@ export declare function loadAsyncStorage(): Promise<{
 }>;
 export { getRandomBytesRN } from './random';
 export declare function loadCommonsIdentityBridge(): Promise<CommonsIdentityBridge | null>;
+export declare function loadKeychainDefaultAccessGroup(): Promise<KeychainDefaultAccessGroup>;

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 { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike } from './expoTypes';
-export type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike, };
+import type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike, KeychainDefaultAccessGroup } from './expoTypes';
+export type { CommonsIdentityBridge, CommonsIdentityDescription, CommonsIdentityProof, CommonsSocialReceiveSignature, ExpoCryptoLike, ExpoSecureStoreLike, KeychainDefaultAccessGroup, };
 /** Persistent KV storage surface used from `@react-native-async-storage/async-storage`. */
 type AsyncStorageLike = {
     getItem: (key: string) => Promise<string | null>;
@@ -67,3 +67,4 @@ export declare function loadAsyncStorage(): Promise<{
 }>;
 export { getRandomBytesRN } from './random.native';
 export declare function loadCommonsIdentityBridge(): Promise<CommonsIdentityBridge | null>;
+export declare function loadKeychainDefaultAccessGroup(): Promise<KeychainDefaultAccessGroup>;

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

@@ -79,6 +79,12 @@ export interface CommonsIdentityDescription {
     v: number;
     /** The identity's public key, lowercase uncompressed SEC1 hex. */
     publicKey: string;
+    /**
+     * Set only on an answer for an ORGANIZATION key (ADR 0061 D6): the account id
+     * Commons echoed, always equal to the one asked for. An answer without it is
+     * the personal identity and is never taken as an organization's.
+     */
+    accountId?: string;
 }
 /**
  * A signed server challenge from Commons (`proveIdentity`). The fields plug
@@ -109,23 +115,52 @@ export interface CommonsSocialReceiveSignature {
  * 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.
+ * On iOS these methods resolve `null`: the keychain access groups in
+ * `@oxy.so/core`'s `KeyManager` own iOS sharing (docs/identity/ios-keychain-access-groups.md).
  */
 export interface CommonsIdentityBridge {
-    /** The public key of the identity Commons holds. */
-    describe(): Promise<CommonsIdentityDescription | null>;
+    /**
+     * The public key of the identity Commons holds, or, with `accountId`, of that
+     * organization's key (ADR 0061 D6).
+     */
+    describe(accountId?: string): 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.
+     * HKDF-SHA256 over the identity key (or, with `accountId`, the organization's
+     * key), 32 bytes as lowercase hex, identical to `KeyManager.deriveScopedSeed`
+     * on the device that holds the key. Commons allows each caller package only
+     * its own `info` labels.
      */
-    deriveScopedSeed(info: string): Promise<string | null>;
+    deriveScopedSeed(info: string, accountId?: 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.
+     * of the identity, or with `accountId`, of that organization's key. Allowed
+     * for the wallet app only.
      */
-    signSocialReceive(index: number, digest: string): Promise<CommonsSocialReceiveSignature | null>;
+    signSocialReceive(index: number, digest: string, accountId?: string): Promise<CommonsSocialReceiveSignature | null>;
 }
+/**
+ * What the iOS keychain says about this app's DEFAULT access group: the first
+ * entry of its `keychain-access-groups` entitlement, team prefix included
+ * (`ABCDE12345.so.oxy.identity`). The value is read back from a probe item the
+ * native module writes without a group, because JavaScript cannot see the
+ * entitlements or the team prefix (`$(AppIdentifierPrefix)` expands at build
+ * time), and `kSecAttrAccessGroup` must equal an entitlement value exactly.
+ *
+ * - `resolved`: the group string, as the keychain reported it.
+ * - `unsupported`: not iOS, or a native build whose `OxyIdentity` module
+ *   predates the probe. Callers keep the single-group behaviour that build was
+ *   made for.
+ * - `unavailable`: the probe threw (before first unlock, keychain refused).
+ *   Transient; never cached.
+ */
+export type KeychainDefaultAccessGroup = {
+    state: 'resolved';
+    accessGroup: string;
+} | {
+    state: 'unsupported';
+} | {
+    state: 'unavailable';
+    cause: unknown;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/protocol",
-  "version": "1.6.1",
+  "version": "1.8.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",
@@ -133,7 +133,7 @@
   },
   "dependencies": {
     "@noble/curves": "^2.4.0",
-    "@oxy.so/contracts": "^6.5.0"
+    "@oxy.so/contracts": "^6.11.0"
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "<4.0.0",

package/src/__tests__/commonsIdentityBridge.test.ts

@@ -87,6 +87,85 @@ describe('loadCommonsIdentityBridge (native)', () => {
     await expect(bridge?.signSocialReceive(0, '11'.repeat(32))).resolves.toBeNull();
   });
 
+  test('organization requests go to the organization methods and must echo the account', async () => {
+    const ORG = '0123456789abcdef01234567';
+    const calls: unknown[][] = [];
+    mockNative({
+      describe: async () => ({ v: 2, publicKey: PUBLIC_KEY }),
+      proveIdentity: async () => null,
+      deriveScopedSeed: async () => 'cd'.repeat(32),
+      signSocialReceive: async () => ({ signature: '3045bb', publicKey: `02${'ef'.repeat(32)}` }),
+      describeOrganization: async (accountId: string) => {
+        calls.push(['describeOrganization', accountId]);
+        return { v: 3, publicKey: PUBLIC_KEY, accountId };
+      },
+      deriveOrganizationScopedSeed: async (info: string, accountId: string) => {
+        calls.push(['deriveOrganizationScopedSeed', info, accountId]);
+        return { seed: 'ee'.repeat(32), accountId };
+      },
+      signOrganizationSocialReceive: async (index: number, digest: string, accountId: string) => {
+        calls.push(['signOrganizationSocialReceive', index, digest, accountId]);
+        return { signature: '3046cc', publicKey: `03${'aa'.repeat(32)}`, accountId };
+      },
+    });
+    const bridge = await loadBridge();
+    await expect(bridge?.describe(ORG)).resolves.toEqual({
+      v: 3,
+      publicKey: PUBLIC_KEY,
+      accountId: ORG,
+    });
+    await expect(bridge?.deriveScopedSeed('peable/faircoin/v1', ORG)).resolves.toBe(
+      'ee'.repeat(32),
+    );
+    await expect(bridge?.signSocialReceive(4, '11'.repeat(32), ORG)).resolves.toEqual({
+      signature: '3046cc',
+      publicKey: `03${'aa'.repeat(32)}`,
+    });
+    // The personal path is untouched.
+    await expect(bridge?.describe()).resolves.toEqual({ v: 2, publicKey: PUBLIC_KEY });
+    expect(calls).toEqual([
+      ['describeOrganization', ORG],
+      ['deriveOrganizationScopedSeed', 'peable/faircoin/v1', ORG],
+      ['signOrganizationSocialReceive', 4, '11'.repeat(32), ORG],
+    ]);
+  });
+
+  test('an organization answer without the echo, or for another account, is null', async () => {
+    const ORG = '0123456789abcdef01234567';
+    mockNative({
+      describe: async () => ({ v: 2, publicKey: PUBLIC_KEY }),
+      proveIdentity: async () => null,
+      deriveScopedSeed: async () => 'cd'.repeat(32),
+      signSocialReceive: async () => null,
+      // An old Commons ignored the extra and answered for the personal key.
+      describeOrganization: async () => ({ v: 2, publicKey: PUBLIC_KEY }),
+      deriveOrganizationScopedSeed: async () => ({ seed: 'ee'.repeat(32), accountId: 'other' }),
+      signOrganizationSocialReceive: async () => ({
+        signature: '3046cc',
+        publicKey: `03${'aa'.repeat(32)}`,
+      }),
+    });
+    const bridge = await loadBridge();
+    await expect(bridge?.describe(ORG)).resolves.toBeNull();
+    await expect(bridge?.deriveScopedSeed('peable/faircoin/v1', ORG)).resolves.toBeNull();
+    await expect(bridge?.signSocialReceive(0, '11'.repeat(32), ORG)).resolves.toBeNull();
+  });
+
+  test('a native module without the organization methods answers no organization', async () => {
+    mockNative({
+      describe: async () => ({ v: 2, publicKey: PUBLIC_KEY }),
+      proveIdentity: async () => null,
+      deriveScopedSeed: async () => 'cd'.repeat(32),
+      signSocialReceive: async () => ({ signature: '3045bb', publicKey: `02${'ef'.repeat(32)}` }),
+    });
+    const bridge = await loadBridge();
+    await expect(bridge?.describe('0123456789abcdef01234567')).resolves.toBeNull();
+    await expect(bridge?.deriveScopedSeed('x', '0123456789abcdef01234567')).resolves.toBeNull();
+    await expect(
+      bridge?.signSocialReceive(0, '11'.repeat(32), '0123456789abcdef01234567'),
+    ).resolves.toBeNull();
+  });
+
   test('the web / Node variant never has a bridge', async () => {
     const mod = await import('../platform/crypto');
     await expect(mod.loadCommonsIdentityBridge()).resolves.toBeNull();

package/src/__tests__/keychainDefaultAccessGroup.test.ts

@@ -0,0 +1,65 @@
+/**
+ * The iOS keychain probe (docs/identity/ios-keychain-access-groups.md): its
+ * answer crossed the native boundary, so only a `<prefix>.<group>` string is a
+ * group; a thrown probe is `unavailable` and asked again, never cached.
+ */
+function mockNative(native: unknown): void {
+  jest.doMock('expo-modules-core', () => ({ requireOptionalNativeModule: () => native }), {
+    virtual: true,
+  });
+}
+
+async function probe() {
+  const mod = await import('../platform/crypto.native');
+  return mod.loadKeychainDefaultAccessGroup();
+}
+
+describe('loadKeychainDefaultAccessGroup (native)', () => {
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  test('a native module without the probe is unsupported', async () => {
+    mockNative({ describe: async () => null });
+    await expect(probe()).resolves.toEqual({ state: 'unsupported' });
+    jest.resetModules();
+    mockNative(null);
+    await expect(probe()).resolves.toEqual({ state: 'unsupported' });
+  });
+
+  test('passes a team-prefixed group through, and remembers it', async () => {
+    const keychainDefaultAccessGroup = jest.fn(async () => 'ABCDE12345.so.oxy.identity');
+    mockNative({ keychainDefaultAccessGroup });
+    const mod = await import('../platform/crypto.native');
+    await expect(mod.loadKeychainDefaultAccessGroup()).resolves.toEqual({
+      state: 'resolved',
+      accessGroup: 'ABCDE12345.so.oxy.identity',
+    });
+    await mod.loadKeychainDefaultAccessGroup();
+    expect(keychainDefaultAccessGroup).toHaveBeenCalledTimes(1);
+  });
+
+  test('a throw is unavailable and asked again; junk is unavailable', async () => {
+    let locked = true;
+    mockNative({
+      keychainDefaultAccessGroup: async () => {
+        if (locked) throw new Error('errSecInteractionNotAllowed');
+        return 'ABCDE12345.group.so.oxy.shared';
+      },
+    });
+    const mod = await import('../platform/crypto.native');
+    expect((await mod.loadKeychainDefaultAccessGroup()).state).toBe('unavailable');
+    locked = false;
+    expect((await mod.loadKeychainDefaultAccessGroup()).state).toBe('resolved');
+    for (const junk of [42, 'nodot', '.leading', { group: 'x' }]) {
+      jest.resetModules();
+      mockNative({ keychainDefaultAccessGroup: async () => junk });
+      expect((await probe()).state).toBe('unavailable');
+    }
+  });
+
+  test('the web / Node variant is unsupported', async () => {
+    const mod = await import('../platform/crypto');
+    await expect(mod.loadKeychainDefaultAccessGroup()).resolves.toEqual({ state: 'unsupported' });
+  });
+});

package/src/index.ts

@@ -99,6 +99,7 @@ export {
   loadAsyncStorage,
   getRandomBytesRN,
   loadCommonsIdentityBridge,
+  loadKeychainDefaultAccessGroup,
 } from './platform/crypto';
 
 // ---------------------------------------------------------------------------
@@ -115,4 +116,5 @@ export type {
   CommonsSocialReceiveSignature,
   ExpoCryptoLike,
   ExpoSecureStoreLike,
+  KeychainDefaultAccessGroup,
 } from './platform/expoTypes';

package/src/platform/crypto.native.ts

@@ -60,6 +60,7 @@ import type {
   CommonsSocialReceiveSignature,
   ExpoCryptoLike,
   ExpoSecureStoreLike,
+  KeychainDefaultAccessGroup,
 } from './expoTypes';
 import { missingOptionalPeerError } from './optionalPeer';
 import { requireExpoCrypto } from './random.native';
@@ -73,6 +74,7 @@ export type {
   CommonsSocialReceiveSignature,
   ExpoCryptoLike,
   ExpoSecureStoreLike,
+  KeychainDefaultAccessGroup,
 };
 
 // ---------------------------------------------------------------------------
@@ -204,6 +206,25 @@ interface OxyIdentityNativeModule {
   proveIdentity(challenge: string): Promise<unknown>;
   deriveScopedSeed(info: string): Promise<unknown>;
   signSocialReceive(index: number, digest: string): Promise<unknown>;
+  /**
+   * Organization keys (ADR 0061 D6), added in `@oxy.so/services` after the four
+   * above: an older native module lacks them, and every organization request
+   * then answers `null`, never the personal identity. Each answer echoes the
+   * `accountId` Commons answered for.
+   */
+  describeOrganization?(accountId: string): Promise<unknown>;
+  deriveOrganizationScopedSeed?(info: string, accountId: string): Promise<unknown>;
+  signOrganizationSocialReceive?(
+    index: number,
+    digest: string,
+    accountId: string,
+  ): Promise<unknown>;
+  /**
+   * iOS only, added with the keychain access-group split: the access group a
+   * probe item written WITHOUT a group landed in (the app's default group).
+   * Older native modules and Android lack it.
+   */
+  keychainDefaultAccessGroup?(): Promise<unknown>;
 }
 
 const LOWER_HEX = /^[0-9a-f]+$/;
@@ -226,6 +247,25 @@ function narrowDescription(value: unknown): CommonsIdentityDescription | null {
   return { v, publicKey };
 }
 
+/**
+ * The organization answer must name the organization asked for. A Commons that
+ * predates organization keys ignores the `accountId` extra and answers for the
+ * PERSONAL identity, without an echo; that answer is refused here, because a
+ * personal key taken for an organization's is money sent to the wrong person.
+ */
+function echoes(value: unknown, accountId: string): Record<string, unknown> | null {
+  const r = record(value);
+  return r && r.accountId === accountId ? r : null;
+}
+
+function narrowOrganizationDescription(
+  value: unknown,
+  accountId: string,
+): CommonsIdentityDescription | null {
+  const description = narrowDescription(echoes(value, accountId));
+  return description ? { ...description, accountId } : null;
+}
+
 function narrowProof(value: unknown): CommonsIdentityProof | null {
   const r = record(value);
   const publicKey = hexField(r?.publicKey, 130);
@@ -272,17 +312,88 @@ export function loadCommonsIdentityBridge(): Promise<CommonsIdentityBridge | nul
       }
       const m = native as OxyIdentityNativeModule;
       return {
-        describe: () => ask(() => m.describe(), narrowDescription),
+        describe: (accountId?: string) => {
+          if (accountId === undefined) return ask(() => m.describe(), narrowDescription);
+          const describeOrganization = m.describeOrganization;
+          if (typeof describeOrganization !== 'function') return Promise.resolve(null);
+          return ask(
+            () => describeOrganization.call(m, accountId),
+            (v) => narrowOrganizationDescription(v, accountId),
+          );
+        },
         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),
+        deriveScopedSeed: (info: string, accountId?: string) => {
+          if (accountId === undefined) {
+            return ask(
+              () => m.deriveScopedSeed(info),
+              (v) => hexField(v, 64),
+            );
+          }
+          const derive = m.deriveOrganizationScopedSeed;
+          if (typeof derive !== 'function') return Promise.resolve(null);
+          return ask(
+            () => derive.call(m, info, accountId),
+            (v) => hexField(echoes(v, accountId)?.seed, 64),
+          );
+        },
+        signSocialReceive: (index: number, digest: string, accountId?: string) => {
+          if (accountId === undefined) {
+            return ask(() => m.signSocialReceive(index, digest), narrowSocialReceive);
+          }
+          const sign = m.signOrganizationSocialReceive;
+          if (typeof sign !== 'function') return Promise.resolve(null);
+          return ask(
+            () => sign.call(m, index, digest, accountId),
+            (v) => narrowSocialReceive(echoes(v, accountId)),
+          );
+        },
       } satisfies CommonsIdentityBridge;
     });
   }
   return commonsIdentityBridgePromise;
 }
+
+// ---------------------------------------------------------------------------
+// iOS keychain default access group (docs/identity/ios-keychain-access-groups.md).
+//
+// Resolved once the native module answers; an `unavailable` probe (a thrown
+// call: before first unlock, or the keychain refused) is not memoized, so the
+// next caller asks again. The answer is narrowed to a plain string — it crossed
+// the native boundary.
+// ---------------------------------------------------------------------------
+
+/** `<prefix>.<group>`: an App ID prefix (no dots) then a non-empty group. */
+const ACCESS_GROUP = /^[A-Za-z0-9]+\.[A-Za-z0-9.-]+$/;
+
+let keychainDefaultAccessGroup: KeychainDefaultAccessGroup | null = null;
+
+export async function loadKeychainDefaultAccessGroup(): Promise<KeychainDefaultAccessGroup> {
+  if (keychainDefaultAccessGroup) {
+    return keychainDefaultAccessGroup;
+  }
+  const native = requireOptionalNativeModule<Partial<OxyIdentityNativeModule>>('OxyIdentity');
+  const probe = native?.keychainDefaultAccessGroup;
+  if (!native || typeof probe !== 'function') {
+    keychainDefaultAccessGroup = { state: 'unsupported' };
+    return keychainDefaultAccessGroup;
+  }
+  let answer: unknown;
+  try {
+    answer = await probe.call(native);
+  } catch (cause) {
+    return { state: 'unavailable', cause };
+  }
+  if (answer === null || answer === undefined) {
+    // The native side runs only on iOS; anything else answers nothing.
+    keychainDefaultAccessGroup = { state: 'unsupported' };
+    return keychainDefaultAccessGroup;
+  }
+  if (typeof answer !== 'string' || !ACCESS_GROUP.test(answer)) {
+    return {
+      state: 'unavailable',
+      cause: new Error('keychain probe answered something that is not an access group'),
+    };
+  }
+  keychainDefaultAccessGroup = { state: 'resolved', accessGroup: answer };
+  return keychainDefaultAccessGroup;
+}

package/src/platform/crypto.ts

@@ -80,6 +80,7 @@ import type {
   CommonsSocialReceiveSignature,
   ExpoCryptoLike,
   ExpoSecureStoreLike,
+  KeychainDefaultAccessGroup,
 } from './expoTypes';
 
 // Re-export the interfaces so consumers can import them from the same
@@ -91,6 +92,7 @@ export type {
   CommonsSocialReceiveSignature,
   ExpoCryptoLike,
   ExpoSecureStoreLike,
+  KeychainDefaultAccessGroup,
 };
 
 // ---------------------------------------------------------------------------
@@ -176,3 +178,11 @@ export { getRandomBytesRN } from './random';
 export function loadCommonsIdentityBridge(): Promise<CommonsIdentityBridge | null> {
   return Promise.resolve(null);
 }
+
+// ---------------------------------------------------------------------------
+// iOS keychain default access group — native-only; off RN there is no keychain.
+// ---------------------------------------------------------------------------
+
+export function loadKeychainDefaultAccessGroup(): Promise<KeychainDefaultAccessGroup> {
+  return Promise.resolve({ state: 'unsupported' });
+}

package/src/platform/expoTypes.ts

@@ -82,6 +82,12 @@ export interface CommonsIdentityDescription {
   v: number;
   /** The identity's public key, lowercase uncompressed SEC1 hex. */
   publicKey: string;
+  /**
+   * Set only on an answer for an ORGANIZATION key (ADR 0061 D6): the account id
+   * Commons echoed, always equal to the one asked for. An answer without it is
+   * the personal identity and is never taken as an organization's.
+   */
+  accountId?: string;
 }
 
 /**
@@ -115,23 +121,52 @@ export interface CommonsSocialReceiveSignature {
  * 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.
+ * On iOS these methods resolve `null`: the keychain access groups in
+ * `@oxy.so/core`'s `KeyManager` own iOS sharing (docs/identity/ios-keychain-access-groups.md).
  */
 export interface CommonsIdentityBridge {
-  /** The public key of the identity Commons holds. */
-  describe(): Promise<CommonsIdentityDescription | null>;
+  /**
+   * The public key of the identity Commons holds, or, with `accountId`, of that
+   * organization's key (ADR 0061 D6).
+   */
+  describe(accountId?: string): 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.
+   * HKDF-SHA256 over the identity key (or, with `accountId`, the organization's
+   * key), 32 bytes as lowercase hex, identical to `KeyManager.deriveScopedSeed`
+   * on the device that holds the key. Commons allows each caller package only
+   * its own `info` labels.
    */
-  deriveScopedSeed(info: string): Promise<string | null>;
+  deriveScopedSeed(info: string, accountId?: 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.
+   * of the identity, or with `accountId`, of that organization's key. Allowed
+   * for the wallet app only.
    */
-  signSocialReceive(index: number, digest: string): Promise<CommonsSocialReceiveSignature | null>;
+  signSocialReceive(
+    index: number,
+    digest: string,
+    accountId?: string,
+  ): Promise<CommonsSocialReceiveSignature | null>;
 }
+
+/**
+ * What the iOS keychain says about this app's DEFAULT access group: the first
+ * entry of its `keychain-access-groups` entitlement, team prefix included
+ * (`ABCDE12345.so.oxy.identity`). The value is read back from a probe item the
+ * native module writes without a group, because JavaScript cannot see the
+ * entitlements or the team prefix (`$(AppIdentifierPrefix)` expands at build
+ * time), and `kSecAttrAccessGroup` must equal an entitlement value exactly.
+ *
+ * - `resolved`: the group string, as the keychain reported it.
+ * - `unsupported`: not iOS, or a native build whose `OxyIdentity` module
+ *   predates the probe. Callers keep the single-group behaviour that build was
+ *   made for.
+ * - `unavailable`: the probe threw (before first unlock, keychain refused).
+ *   Transient; never cached.
+ */
+export type KeychainDefaultAccessGroup =
+  | { state: 'resolved'; accessGroup: string }
+  | { state: 'unsupported' }
+  | { state: 'unavailable'; cause: unknown };