@oxy.so/protocol 1.8.0 → 1.10.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.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;
+exports.loadKeychainApplicationAccessGroup = 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
 // ---------------------------------------------------------------------------
@@ -78,3 +78,4 @@ Object.defineProperty(exports, "loadAsyncStorage", { enumerable: true, get: func
 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; } });
+Object.defineProperty(exports, "loadKeychainApplicationAccessGroup", { enumerable: true, get: function () { return crypto_1.loadKeychainApplicationAccessGroup; } });

package/dist/cjs/platform/crypto.js

@@ -113,6 +113,7 @@ exports.loadSecureStore = loadSecureStore;
 exports.loadAsyncStorage = loadAsyncStorage;
 exports.loadCommonsIdentityBridge = loadCommonsIdentityBridge;
 exports.loadKeychainDefaultAccessGroup = loadKeychainDefaultAccessGroup;
+exports.loadKeychainApplicationAccessGroup = loadKeychainApplicationAccessGroup;
 const platform_1 = require("./platform");
 // ---------------------------------------------------------------------------
 // Node `crypto` — Node built-in
@@ -184,3 +185,6 @@ function loadCommonsIdentityBridge() {
 function loadKeychainDefaultAccessGroup() {
     return Promise.resolve({ state: 'unsupported' });
 }
+function loadKeychainApplicationAccessGroup(_prefix) {
+    return Promise.resolve({ state: 'unsupported' });
+}

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

@@ -60,6 +60,7 @@ exports.loadSecureStore = loadSecureStore;
 exports.loadAsyncStorage = loadAsyncStorage;
 exports.loadCommonsIdentityBridge = loadCommonsIdentityBridge;
 exports.loadKeychainDefaultAccessGroup = loadKeychainDefaultAccessGroup;
+exports.loadKeychainApplicationAccessGroup = loadKeychainApplicationAccessGroup;
 const expo_modules_core_1 = require("expo-modules-core");
 const optionalPeer_1 = require("./optionalPeer");
 const random_native_1 = require("./random.native");
@@ -134,6 +135,8 @@ async function loadAsyncStorage() {
 var random_native_2 = require("./random.native");
 Object.defineProperty(exports, "getRandomBytesRN", { enumerable: true, get: function () { return random_native_2.getRandomBytesRN; } });
 const LOWER_HEX = /^[0-9a-f]+$/;
+/** A lowercase uncompressed SEC1 public key, as Commons names every key it holds. */
+const PUBLIC_KEY = /^04[0-9a-f]{128}$/;
 function record(value) {
     return typeof value === 'object' && value !== null ? value : null;
 }
@@ -166,6 +169,39 @@ function narrowOrganizationDescription(value, accountId) {
     const description = narrowDescription(echoes(value, accountId));
     return description ? { ...description, accountId } : null;
 }
+/**
+ * A retired-key answer must name the key asked for, and the scope asked for:
+ * the organization's `accountId`, or none for the person. A Commons before
+ * protocol 4 ignores `keyPublicKey` and answers with the CURRENT key, without
+ * the echo; that answer is refused here.
+ */
+function echoesRetired(value, publicKey, accountId) {
+    const r = record(value);
+    if (!r || r.keyPublicKey !== publicKey)
+        return null;
+    return (r.accountId ?? undefined) === accountId ? r : null;
+}
+/**
+ * The list must be every entry a well-formed public key: one malformed entry
+ * means an answer this side does not understand, and the whole answer is
+ * `null` rather than a list missing a key the wallet would then never sweep.
+ */
+function narrowRetiredKeys(value, accountId) {
+    const r = record(value);
+    if (!r || (r.accountId ?? undefined) !== accountId)
+        return null;
+    const keys = r.publicKeys;
+    if (!Array.isArray(keys))
+        return null;
+    const out = [];
+    for (const key of keys) {
+        if (typeof key !== 'string' || !PUBLIC_KEY.test(key))
+            return null;
+        if (!out.includes(key))
+            out.push(key);
+    }
+    return out;
+}
 function narrowProof(value) {
     const r = record(value);
     const publicKey = hexField(r?.publicKey, 130);
@@ -233,6 +269,26 @@ function loadCommonsIdentityBridge() {
                         return Promise.resolve(null);
                     return ask(() => sign.call(m, index, digest, accountId), (v) => narrowSocialReceive(echoes(v, accountId)));
                 },
+                listRetiredKeys: (accountId) => {
+                    const list = m.listRetiredKeys;
+                    if (typeof list !== 'function')
+                        return Promise.resolve(null);
+                    return ask(() => list.call(m, accountId ?? null), (v) => narrowRetiredKeys(v, accountId));
+                },
+                deriveRetiredScopedSeed: (info, publicKey, accountId) => {
+                    const derive = m.deriveRetiredScopedSeed;
+                    if (typeof derive !== 'function' || !PUBLIC_KEY.test(publicKey)) {
+                        return Promise.resolve(null);
+                    }
+                    return ask(() => derive.call(m, info, publicKey, accountId ?? null), (v) => hexField(echoesRetired(v, publicKey, accountId)?.seed, 64));
+                },
+                signRetiredSocialReceive: (index, digest, publicKey, accountId) => {
+                    const sign = m.signRetiredSocialReceive;
+                    if (typeof sign !== 'function' || !PUBLIC_KEY.test(publicKey)) {
+                        return Promise.resolve(null);
+                    }
+                    return ask(() => sign.call(m, index, digest, publicKey, accountId ?? null), (v) => narrowSocialReceive(echoesRetired(v, publicKey, accountId)));
+                },
             };
         });
     }
@@ -280,3 +336,50 @@ async function loadKeychainDefaultAccessGroup() {
     keychainDefaultAccessGroup = { state: 'resolved', accessGroup: answer };
     return keychainDefaultAccessGroup;
 }
+// ---------------------------------------------------------------------------
+// iOS keychain application access group (ADR 0062 D6): `<prefix><bundle id>`,
+// the group every app is a member of and no other app can name — where an app
+// keeps the items that are its alone. Same caching as the default group: a
+// resolved or unsupported answer is constant for the binary; a thrown probe is
+// asked again.
+// ---------------------------------------------------------------------------
+/** A team prefix as the default group carries it: no dots, then one dot. */
+const KEYCHAIN_PREFIX = /^[A-Za-z0-9]+\.$/;
+let keychainApplicationAccessGroup = null;
+async function loadKeychainApplicationAccessGroup(prefix) {
+    if (keychainApplicationAccessGroup) {
+        return keychainApplicationAccessGroup;
+    }
+    if (!KEYCHAIN_PREFIX.test(prefix)) {
+        return {
+            state: 'unavailable',
+            cause: new Error('keychain application group probe needs a team prefix'),
+        };
+    }
+    const native = (0, expo_modules_core_1.requireOptionalNativeModule)('OxyIdentity');
+    const probe = native?.keychainApplicationAccessGroup;
+    if (!native || typeof probe !== 'function') {
+        keychainApplicationAccessGroup = { state: 'unsupported' };
+        return keychainApplicationAccessGroup;
+    }
+    let answer;
+    try {
+        answer = await probe.call(native, prefix);
+    }
+    catch (cause) {
+        return { state: 'unavailable', cause };
+    }
+    if (answer === null || answer === undefined) {
+        // Not entitled (or not iOS): this binary keeps the placement it was built for.
+        keychainApplicationAccessGroup = { state: 'unsupported' };
+        return keychainApplicationAccessGroup;
+    }
+    if (typeof answer !== 'string' || !answer.startsWith(prefix) || !ACCESS_GROUP.test(answer)) {
+        // A native bug, not a locked keychain: asking again would answer the same,
+        // and `unavailable` would leave the app without storage. Keep the
+        // placement this build had before the probe existed.
+        return { state: 'unsupported' };
+    }
+    keychainApplicationAccessGroup = { state: 'resolved', accessGroup: answer };
+    return keychainApplicationAccessGroup;
+}

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, loadKeychainDefaultAccessGroup, } from './platform/crypto.js';
+export { loadNodeCrypto, loadExpoCrypto, loadSecureStore, loadAsyncStorage, getRandomBytesRN, loadCommonsIdentityBridge, loadKeychainDefaultAccessGroup, loadKeychainApplicationAccessGroup, } from './platform/crypto.js';

package/dist/esm/platform/crypto.js

@@ -141,3 +141,6 @@ export function loadCommonsIdentityBridge() {
 export function loadKeychainDefaultAccessGroup() {
     return Promise.resolve({ state: 'unsupported' });
 }
+export function loadKeychainApplicationAccessGroup(_prefix) {
+    return Promise.resolve({ state: 'unsupported' });
+}

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

@@ -124,6 +124,8 @@ export async function loadAsyncStorage() {
 // Metro pointed at the same file.
 export { getRandomBytesRN } from './random.native.js';
 const LOWER_HEX = /^[0-9a-f]+$/;
+/** A lowercase uncompressed SEC1 public key, as Commons names every key it holds. */
+const PUBLIC_KEY = /^04[0-9a-f]{128}$/;
 function record(value) {
     return typeof value === 'object' && value !== null ? value : null;
 }
@@ -156,6 +158,39 @@ function narrowOrganizationDescription(value, accountId) {
     const description = narrowDescription(echoes(value, accountId));
     return description ? { ...description, accountId } : null;
 }
+/**
+ * A retired-key answer must name the key asked for, and the scope asked for:
+ * the organization's `accountId`, or none for the person. A Commons before
+ * protocol 4 ignores `keyPublicKey` and answers with the CURRENT key, without
+ * the echo; that answer is refused here.
+ */
+function echoesRetired(value, publicKey, accountId) {
+    const r = record(value);
+    if (!r || r.keyPublicKey !== publicKey)
+        return null;
+    return (r.accountId ?? undefined) === accountId ? r : null;
+}
+/**
+ * The list must be every entry a well-formed public key: one malformed entry
+ * means an answer this side does not understand, and the whole answer is
+ * `null` rather than a list missing a key the wallet would then never sweep.
+ */
+function narrowRetiredKeys(value, accountId) {
+    const r = record(value);
+    if (!r || (r.accountId ?? undefined) !== accountId)
+        return null;
+    const keys = r.publicKeys;
+    if (!Array.isArray(keys))
+        return null;
+    const out = [];
+    for (const key of keys) {
+        if (typeof key !== 'string' || !PUBLIC_KEY.test(key))
+            return null;
+        if (!out.includes(key))
+            out.push(key);
+    }
+    return out;
+}
 function narrowProof(value) {
     const r = record(value);
     const publicKey = hexField(r?.publicKey, 130);
@@ -223,6 +258,26 @@ export function loadCommonsIdentityBridge() {
                         return Promise.resolve(null);
                     return ask(() => sign.call(m, index, digest, accountId), (v) => narrowSocialReceive(echoes(v, accountId)));
                 },
+                listRetiredKeys: (accountId) => {
+                    const list = m.listRetiredKeys;
+                    if (typeof list !== 'function')
+                        return Promise.resolve(null);
+                    return ask(() => list.call(m, accountId ?? null), (v) => narrowRetiredKeys(v, accountId));
+                },
+                deriveRetiredScopedSeed: (info, publicKey, accountId) => {
+                    const derive = m.deriveRetiredScopedSeed;
+                    if (typeof derive !== 'function' || !PUBLIC_KEY.test(publicKey)) {
+                        return Promise.resolve(null);
+                    }
+                    return ask(() => derive.call(m, info, publicKey, accountId ?? null), (v) => hexField(echoesRetired(v, publicKey, accountId)?.seed, 64));
+                },
+                signRetiredSocialReceive: (index, digest, publicKey, accountId) => {
+                    const sign = m.signRetiredSocialReceive;
+                    if (typeof sign !== 'function' || !PUBLIC_KEY.test(publicKey)) {
+                        return Promise.resolve(null);
+                    }
+                    return ask(() => sign.call(m, index, digest, publicKey, accountId ?? null), (v) => narrowSocialReceive(echoesRetired(v, publicKey, accountId)));
+                },
             };
         });
     }
@@ -270,3 +325,50 @@ export async function loadKeychainDefaultAccessGroup() {
     keychainDefaultAccessGroup = { state: 'resolved', accessGroup: answer };
     return keychainDefaultAccessGroup;
 }
+// ---------------------------------------------------------------------------
+// iOS keychain application access group (ADR 0062 D6): `<prefix><bundle id>`,
+// the group every app is a member of and no other app can name — where an app
+// keeps the items that are its alone. Same caching as the default group: a
+// resolved or unsupported answer is constant for the binary; a thrown probe is
+// asked again.
+// ---------------------------------------------------------------------------
+/** A team prefix as the default group carries it: no dots, then one dot. */
+const KEYCHAIN_PREFIX = /^[A-Za-z0-9]+\.$/;
+let keychainApplicationAccessGroup = null;
+export async function loadKeychainApplicationAccessGroup(prefix) {
+    if (keychainApplicationAccessGroup) {
+        return keychainApplicationAccessGroup;
+    }
+    if (!KEYCHAIN_PREFIX.test(prefix)) {
+        return {
+            state: 'unavailable',
+            cause: new Error('keychain application group probe needs a team prefix'),
+        };
+    }
+    const native = requireOptionalNativeModule('OxyIdentity');
+    const probe = native?.keychainApplicationAccessGroup;
+    if (!native || typeof probe !== 'function') {
+        keychainApplicationAccessGroup = { state: 'unsupported' };
+        return keychainApplicationAccessGroup;
+    }
+    let answer;
+    try {
+        answer = await probe.call(native, prefix);
+    }
+    catch (cause) {
+        return { state: 'unavailable', cause };
+    }
+    if (answer === null || answer === undefined) {
+        // Not entitled (or not iOS): this binary keeps the placement it was built for.
+        keychainApplicationAccessGroup = { state: 'unsupported' };
+        return keychainApplicationAccessGroup;
+    }
+    if (typeof answer !== 'string' || !answer.startsWith(prefix) || !ACCESS_GROUP.test(answer)) {
+        // A native bug, not a locked keychain: asking again would answer the same,
+        // and `unavailable` would leave the app without storage. Keep the
+        // placement this build had before the probe existed.
+        return { state: 'unsupported' };
+    }
+    keychainApplicationAccessGroup = { state: 'resolved', accessGroup: answer };
+    return keychainApplicationAccessGroup;
+}

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

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

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

@@ -117,6 +117,14 @@ export interface CommonsSocialReceiveSignature {
  *
  * 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).
+ *
+ * The three `*Retired*` methods (Commons protocol 4) reach a key the person,
+ * or the organization with `accountId`, rotated away from, by its public key,
+ * for SPENDING the coins still at its addresses: never for signing in. They are
+ * always present on the bridge and resolve `null` on a native module or a
+ * Commons that predates them; an answer that does not echo the key (and the
+ * account) asked for is refused, because the current key taken for a retired
+ * one is a payment signed by the wrong key.
  */
 export interface CommonsIdentityBridge {
     /**
@@ -139,6 +147,26 @@ export interface CommonsIdentityBridge {
      * for the wallet app only.
      */
     signSocialReceive(index: number, digest: string, accountId?: string): Promise<CommonsSocialReceiveSignature | null>;
+    /**
+     * The public keys (lowercase uncompressed SEC1 hex, de-duplicated) of the
+     * retired keys Commons holds for the person, or with `accountId` for that
+     * organization, minus the current one. `[]` when it holds none; `null` when
+     * Commons cannot say (absent, refused, or older than retired keys). Allowed
+     * for the wallet app only.
+     */
+    listRetiredKeys(accountId?: string): Promise<string[] | null>;
+    /**
+     * {@link deriveScopedSeed} over the key of that scope whose public key is
+     * `publicKey` (current or retired), never another key: `null` when Commons
+     * does not hold it.
+     */
+    deriveRetiredScopedSeed(info: string, publicKey: string, accountId?: string): Promise<string | null>;
+    /**
+     * {@link signSocialReceive} with the social-receive child `index` of the key
+     * of that scope whose public key is `publicKey` (current or retired), never
+     * another key. Allowed for the wallet app only.
+     */
+    signRetiredSocialReceive(index: number, digest: string, publicKey: string, accountId?: string): Promise<CommonsSocialReceiveSignature | null>;
 }
 /**
  * What the iOS keychain says about this app's DEFAULT access group: the first
@@ -164,3 +192,31 @@ export type KeychainDefaultAccessGroup = {
     state: 'unavailable';
     cause: unknown;
 };
+/**
+ * What the iOS keychain says about this app's OWN access group: its
+ * application identifier, `<prefix><bundle id>` (`ABCDE12345.so.oxy.mention`).
+ * Apple makes every app a member of that group whatever its
+ * `keychain-access-groups` lists, and no other app can name it, so it is where
+ * an app keeps the items that are its alone (its session credential): the
+ * keychain's counterpart of Android's per-app storage (ADR 0062 D6).
+ *
+ * The native module writes a probe item into that group EXPLICITLY and answers
+ * the group only when the keychain took it.
+ *
+ * - `resolved`: the group string.
+ * - `unsupported`: not iOS, a native build whose `OxyIdentity` module predates
+ *   this probe, a keychain that refused the group as not entitled, or an answer
+ *   that is not this team's group. Constant for the binary: callers keep the
+ *   placement that build was made for.
+ * - `unavailable`: the probe threw (before first unlock). Transient; never
+ *   cached.
+ */
+export type KeychainApplicationAccessGroup = {
+    state: 'resolved';
+    accessGroup: string;
+} | {
+    state: 'unsupported';
+} | {
+    state: 'unavailable';
+    cause: unknown;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/protocol",
-  "version": "1.8.0",
+  "version": "1.10.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.11.0"
+    "@oxy.so/contracts": "^6.12.0"
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "<4.0.0",

package/src/__tests__/commonsIdentityBridge.test.ts

@@ -166,6 +166,175 @@ describe('loadCommonsIdentityBridge (native)', () => {
     ).resolves.toBeNull();
   });
 
+  describe('retired keys', () => {
+    const ORG = '0123456789abcdef01234567';
+    const RETIRED = `04${'cd'.repeat(64)}`;
+    const OTHER = `04${'ef'.repeat(64)}`;
+    const base = {
+      describe: async () => ({ v: 4, publicKey: PUBLIC_KEY }),
+      proveIdentity: async () => null,
+      deriveScopedSeed: async () => 'cd'.repeat(32),
+      signSocialReceive: async () => ({ signature: '3045bb', publicKey: `02${'ef'.repeat(32)}` }),
+    };
+
+    test('requests carry the key and the scope, and well-formed echoed answers pass', async () => {
+      const calls: unknown[][] = [];
+      mockNative({
+        ...base,
+        listRetiredKeys: async (accountId: string | null) => {
+          calls.push(['listRetiredKeys', accountId]);
+          return accountId === null
+            ? { publicKeys: [RETIRED, OTHER, RETIRED] }
+            : { publicKeys: [OTHER], accountId };
+        },
+        deriveRetiredScopedSeed: async (
+          info: string,
+          publicKey: string,
+          accountId: string | null,
+        ) => {
+          calls.push(['deriveRetiredScopedSeed', info, publicKey, accountId]);
+          return accountId === null
+            ? { seed: 'aa'.repeat(32), keyPublicKey: publicKey }
+            : { seed: 'bb'.repeat(32), keyPublicKey: publicKey, accountId };
+        },
+        signRetiredSocialReceive: async (
+          index: number,
+          digest: string,
+          publicKey: string,
+          accountId: string | null,
+        ) => {
+          calls.push(['signRetiredSocialReceive', index, digest, publicKey, accountId]);
+          return {
+            signature: '3046cc',
+            publicKey: `03${'aa'.repeat(32)}`,
+            keyPublicKey: publicKey,
+          };
+        },
+      });
+      const bridge = await loadBridge();
+      // De-duplicated, in Commons' order.
+      await expect(bridge?.listRetiredKeys()).resolves.toEqual([RETIRED, OTHER]);
+      await expect(bridge?.listRetiredKeys(ORG)).resolves.toEqual([OTHER]);
+      await expect(bridge?.deriveRetiredScopedSeed('peable/faircoin/v1', RETIRED)).resolves.toBe(
+        'aa'.repeat(32),
+      );
+      await expect(bridge?.deriveRetiredScopedSeed('peable/faircoin/v1', OTHER, ORG)).resolves.toBe(
+        'bb'.repeat(32),
+      );
+      await expect(bridge?.signRetiredSocialReceive(7, '11'.repeat(32), RETIRED)).resolves.toEqual({
+        signature: '3046cc',
+        publicKey: `03${'aa'.repeat(32)}`,
+      });
+      expect(calls).toEqual([
+        ['listRetiredKeys', null],
+        ['listRetiredKeys', ORG],
+        ['deriveRetiredScopedSeed', 'peable/faircoin/v1', RETIRED, null],
+        ['deriveRetiredScopedSeed', 'peable/faircoin/v1', OTHER, ORG],
+        ['signRetiredSocialReceive', 7, '11'.repeat(32), RETIRED, null],
+      ]);
+    });
+
+    test('an answer without the key echo, or for another key or scope, is null', async () => {
+      mockNative({
+        ...base,
+        // An older Commons ignored keyPublicKey and answered with the CURRENT key.
+        deriveRetiredScopedSeed: async (
+          _info: string,
+          publicKey: string,
+          accountId: string | null,
+        ) =>
+          accountId === null
+            ? { seed: 'aa'.repeat(32) }
+            : { seed: 'bb'.repeat(32), keyPublicKey: publicKey },
+        signRetiredSocialReceive: async (
+          _index: number,
+          _digest: string,
+          _publicKey: string,
+          accountId: string | null,
+        ) =>
+          accountId === null
+            ? { signature: '3046cc', publicKey: `03${'aa'.repeat(32)}`, keyPublicKey: OTHER }
+            : {
+                signature: '3046cc',
+                publicKey: `03${'aa'.repeat(32)}`,
+                keyPublicKey: RETIRED,
+                accountId: 'fedcba9876543210fedcba98',
+              },
+        // A personal answer for an organization request, and vice versa.
+        listRetiredKeys: async (accountId: string | null) =>
+          accountId === null
+            ? { publicKeys: [RETIRED], accountId: ORG }
+            : { publicKeys: [RETIRED] },
+      });
+      const bridge = await loadBridge();
+      await expect(
+        bridge?.deriveRetiredScopedSeed('peable/faircoin/v1', RETIRED),
+      ).resolves.toBeNull();
+      // The key echo is there but the account echo is missing.
+      await expect(
+        bridge?.deriveRetiredScopedSeed('peable/faircoin/v1', RETIRED, ORG),
+      ).resolves.toBeNull();
+      await expect(
+        bridge?.signRetiredSocialReceive(0, '11'.repeat(32), RETIRED),
+      ).resolves.toBeNull();
+      await expect(
+        bridge?.signRetiredSocialReceive(0, '11'.repeat(32), RETIRED, ORG),
+      ).resolves.toBeNull();
+      await expect(bridge?.listRetiredKeys()).resolves.toBeNull();
+      await expect(bridge?.listRetiredKeys(ORG)).resolves.toBeNull();
+    });
+
+    test('a list with a malformed entry is refused whole; an empty list is an answer', async () => {
+      const answers: unknown[] = [
+        { publicKeys: [RETIRED, `04${'CD'.repeat(64)}`] },
+        { publicKeys: [RETIRED, `02${'aa'.repeat(32)}`] },
+        { publicKeys: [RETIRED, 7] },
+        { publicKeys: RETIRED },
+        { publicKeys: [] },
+      ];
+      mockNative({ ...base, listRetiredKeys: async () => answers.shift() });
+      const bridge = await loadBridge();
+      await expect(bridge?.listRetiredKeys()).resolves.toBeNull();
+      await expect(bridge?.listRetiredKeys()).resolves.toBeNull();
+      await expect(bridge?.listRetiredKeys()).resolves.toBeNull();
+      await expect(bridge?.listRetiredKeys()).resolves.toBeNull();
+      await expect(bridge?.listRetiredKeys()).resolves.toEqual([]);
+    });
+
+    test('a malformed public key is never sent to Commons', async () => {
+      const derive = jest.fn(async () => ({ seed: 'aa'.repeat(32), keyPublicKey: 'x' }));
+      const sign = jest.fn(async () => null);
+      mockNative({ ...base, deriveRetiredScopedSeed: derive, signRetiredSocialReceive: sign });
+      const bridge = await loadBridge();
+      await expect(bridge?.deriveRetiredScopedSeed('peable/faircoin/v1', 'x')).resolves.toBeNull();
+      await expect(
+        bridge?.deriveRetiredScopedSeed('peable/faircoin/v1', RETIRED.toUpperCase()),
+      ).resolves.toBeNull();
+      await expect(
+        bridge?.signRetiredSocialReceive(0, '11'.repeat(32), `02${'aa'.repeat(32)}`),
+      ).resolves.toBeNull();
+      expect(derive).not.toHaveBeenCalled();
+      expect(sign).not.toHaveBeenCalled();
+    });
+
+    test('a native module without the retired functions answers null, never the current key', async () => {
+      const derive = jest.fn(base.deriveScopedSeed);
+      const sign = jest.fn(base.signSocialReceive);
+      mockNative({ ...base, deriveScopedSeed: derive, signSocialReceive: sign });
+      const bridge = await loadBridge();
+      expect(bridge).not.toBeNull();
+      await expect(bridge?.listRetiredKeys()).resolves.toBeNull();
+      await expect(
+        bridge?.deriveRetiredScopedSeed('peable/faircoin/v1', RETIRED),
+      ).resolves.toBeNull();
+      await expect(
+        bridge?.signRetiredSocialReceive(0, '11'.repeat(32), RETIRED, ORG),
+      ).resolves.toBeNull();
+      expect(derive).not.toHaveBeenCalled();
+      expect(sign).not.toHaveBeenCalled();
+    });
+  });
+
   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

@@ -63,3 +63,68 @@ describe('loadKeychainDefaultAccessGroup (native)', () => {
     await expect(mod.loadKeychainDefaultAccessGroup()).resolves.toEqual({ state: 'unsupported' });
   });
 });
+
+describe('loadKeychainApplicationAccessGroup (native, ADR 0062 D6)', () => {
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  const load = async (prefix = 'ABCDE12345.') =>
+    (await import('../platform/crypto.native')).loadKeychainApplicationAccessGroup(prefix);
+
+  test('a native module without the probe, or a refused group, is unsupported', async () => {
+    mockNative({ keychainDefaultAccessGroup: async () => 'ABCDE12345.group.so.oxy.shared' });
+    await expect(load()).resolves.toEqual({ state: 'unsupported' });
+    jest.resetModules();
+    mockNative({ keychainApplicationAccessGroup: async () => null });
+    await expect(load()).resolves.toEqual({ state: 'unsupported' });
+  });
+
+  test('passes this team’s group through with the prefix, and remembers it', async () => {
+    const keychainApplicationAccessGroup = jest.fn(async () => 'ABCDE12345.so.oxy.mention');
+    mockNative({ keychainApplicationAccessGroup });
+    const mod = await import('../platform/crypto.native');
+    await expect(mod.loadKeychainApplicationAccessGroup('ABCDE12345.')).resolves.toEqual({
+      state: 'resolved',
+      accessGroup: 'ABCDE12345.so.oxy.mention',
+    });
+    await mod.loadKeychainApplicationAccessGroup('ABCDE12345.');
+    expect(keychainApplicationAccessGroup).toHaveBeenCalledTimes(1);
+    expect(keychainApplicationAccessGroup).toHaveBeenCalledWith('ABCDE12345.');
+  });
+
+  test('a throw is unavailable and asked again; a bad prefix is never sent', async () => {
+    let locked = true;
+    const keychainApplicationAccessGroup = jest.fn(async () => {
+      if (locked) throw new Error('errSecInteractionNotAllowed');
+      return 'ABCDE12345.so.oxy.mention';
+    });
+    mockNative({ keychainApplicationAccessGroup });
+    const mod = await import('../platform/crypto.native');
+    expect((await mod.loadKeychainApplicationAccessGroup('ABCDE12345.')).state).toBe('unavailable');
+    locked = false;
+    expect((await mod.loadKeychainApplicationAccessGroup('ABCDE12345.')).state).toBe('resolved');
+    jest.resetModules();
+    mockNative({ keychainApplicationAccessGroup });
+    keychainApplicationAccessGroup.mockClear();
+    for (const prefix of ['', 'ABCDE12345', 'A.B.']) {
+      expect((await load(prefix)).state).toBe('unavailable');
+    }
+    expect(keychainApplicationAccessGroup).not.toHaveBeenCalled();
+  });
+
+  test('another team’s group or junk is unsupported: the earlier placement, never no storage', async () => {
+    for (const junk of [42, 'XYZ.so.oxy.mention', 'ABCDE12345.', { group: 'x' }]) {
+      jest.resetModules();
+      mockNative({ keychainApplicationAccessGroup: async () => junk });
+      expect((await load()).state).toBe('unsupported');
+    }
+  });
+
+  test('the web / Node variant is unsupported', async () => {
+    const mod = await import('../platform/crypto');
+    await expect(mod.loadKeychainApplicationAccessGroup('ABCDE12345.')).resolves.toEqual({
+      state: 'unsupported',
+    });
+  });
+});

package/src/index.ts

@@ -100,6 +100,7 @@ export {
   getRandomBytesRN,
   loadCommonsIdentityBridge,
   loadKeychainDefaultAccessGroup,
+  loadKeychainApplicationAccessGroup,
 } from './platform/crypto';
 
 // ---------------------------------------------------------------------------
@@ -116,5 +117,6 @@ export type {
   CommonsSocialReceiveSignature,
   ExpoCryptoLike,
   ExpoSecureStoreLike,
+  KeychainApplicationAccessGroup,
   KeychainDefaultAccessGroup,
 } from './platform/expoTypes';

package/src/platform/crypto.native.ts

@@ -60,6 +60,7 @@ import type {
   CommonsSocialReceiveSignature,
   ExpoCryptoLike,
   ExpoSecureStoreLike,
+  KeychainApplicationAccessGroup,
   KeychainDefaultAccessGroup,
 } from './expoTypes';
 import { missingOptionalPeerError } from './optionalPeer';
@@ -74,6 +75,7 @@ export type {
   CommonsSocialReceiveSignature,
   ExpoCryptoLike,
   ExpoSecureStoreLike,
+  KeychainApplicationAccessGroup,
   KeychainDefaultAccessGroup,
 };
 
@@ -225,9 +227,36 @@ interface OxyIdentityNativeModule {
    * Older native modules and Android lack it.
    */
   keychainDefaultAccessGroup?(): Promise<unknown>;
+  /**
+   * iOS only, added after the default-group probe (ADR 0062 D6): writes a
+   * probe item into `<prefix><bundle id>` explicitly and answers that group,
+   * or `null` when the keychain refused it as not entitled. Older native
+   * modules and Android lack it.
+   */
+  keychainApplicationAccessGroup?(prefix: string): Promise<unknown>;
+  /**
+   * Retired keys (Commons protocol 4), added after the organization methods and
+   * just as absent on an older native module. `accountId` is `null` for the
+   * person. Each answer echoes the `keyPublicKey` (and the `accountId`) Commons
+   * answered for.
+   */
+  listRetiredKeys?(accountId: string | null): Promise<unknown>;
+  deriveRetiredScopedSeed?(
+    info: string,
+    publicKey: string,
+    accountId: string | null,
+  ): Promise<unknown>;
+  signRetiredSocialReceive?(
+    index: number,
+    digest: string,
+    publicKey: string,
+    accountId: string | null,
+  ): Promise<unknown>;
 }
 
 const LOWER_HEX = /^[0-9a-f]+$/;
+/** A lowercase uncompressed SEC1 public key, as Commons names every key it holds. */
+const PUBLIC_KEY = /^04[0-9a-f]{128}$/;
 
 function record(value: unknown): Record<string, unknown> | null {
   return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null;
@@ -266,6 +295,40 @@ function narrowOrganizationDescription(
   return description ? { ...description, accountId } : null;
 }
 
+/**
+ * A retired-key answer must name the key asked for, and the scope asked for:
+ * the organization's `accountId`, or none for the person. A Commons before
+ * protocol 4 ignores `keyPublicKey` and answers with the CURRENT key, without
+ * the echo; that answer is refused here.
+ */
+function echoesRetired(
+  value: unknown,
+  publicKey: string,
+  accountId: string | undefined,
+): Record<string, unknown> | null {
+  const r = record(value);
+  if (!r || r.keyPublicKey !== publicKey) return null;
+  return (r.accountId ?? undefined) === accountId ? r : null;
+}
+
+/**
+ * The list must be every entry a well-formed public key: one malformed entry
+ * means an answer this side does not understand, and the whole answer is
+ * `null` rather than a list missing a key the wallet would then never sweep.
+ */
+function narrowRetiredKeys(value: unknown, accountId: string | undefined): string[] | null {
+  const r = record(value);
+  if (!r || (r.accountId ?? undefined) !== accountId) return null;
+  const keys = r.publicKeys;
+  if (!Array.isArray(keys)) return null;
+  const out: string[] = [];
+  for (const key of keys) {
+    if (typeof key !== 'string' || !PUBLIC_KEY.test(key)) return null;
+    if (!out.includes(key)) out.push(key);
+  }
+  return out;
+}
+
 function narrowProof(value: unknown): CommonsIdentityProof | null {
   const r = record(value);
   const publicKey = hexField(r?.publicKey, 130);
@@ -347,6 +410,39 @@ export function loadCommonsIdentityBridge(): Promise<CommonsIdentityBridge | nul
             (v) => narrowSocialReceive(echoes(v, accountId)),
           );
         },
+        listRetiredKeys: (accountId?: string) => {
+          const list = m.listRetiredKeys;
+          if (typeof list !== 'function') return Promise.resolve(null);
+          return ask(
+            () => list.call(m, accountId ?? null),
+            (v) => narrowRetiredKeys(v, accountId),
+          );
+        },
+        deriveRetiredScopedSeed: (info: string, publicKey: string, accountId?: string) => {
+          const derive = m.deriveRetiredScopedSeed;
+          if (typeof derive !== 'function' || !PUBLIC_KEY.test(publicKey)) {
+            return Promise.resolve(null);
+          }
+          return ask(
+            () => derive.call(m, info, publicKey, accountId ?? null),
+            (v) => hexField(echoesRetired(v, publicKey, accountId)?.seed, 64),
+          );
+        },
+        signRetiredSocialReceive: (
+          index: number,
+          digest: string,
+          publicKey: string,
+          accountId?: string,
+        ) => {
+          const sign = m.signRetiredSocialReceive;
+          if (typeof sign !== 'function' || !PUBLIC_KEY.test(publicKey)) {
+            return Promise.resolve(null);
+          }
+          return ask(
+            () => sign.call(m, index, digest, publicKey, accountId ?? null),
+            (v) => narrowSocialReceive(echoesRetired(v, publicKey, accountId)),
+          );
+        },
       } satisfies CommonsIdentityBridge;
     });
   }
@@ -397,3 +493,55 @@ export async function loadKeychainDefaultAccessGroup(): Promise<KeychainDefaultA
   keychainDefaultAccessGroup = { state: 'resolved', accessGroup: answer };
   return keychainDefaultAccessGroup;
 }
+
+// ---------------------------------------------------------------------------
+// iOS keychain application access group (ADR 0062 D6): `<prefix><bundle id>`,
+// the group every app is a member of and no other app can name — where an app
+// keeps the items that are its alone. Same caching as the default group: a
+// resolved or unsupported answer is constant for the binary; a thrown probe is
+// asked again.
+// ---------------------------------------------------------------------------
+
+/** A team prefix as the default group carries it: no dots, then one dot. */
+const KEYCHAIN_PREFIX = /^[A-Za-z0-9]+\.$/;
+
+let keychainApplicationAccessGroup: KeychainApplicationAccessGroup | null = null;
+
+export async function loadKeychainApplicationAccessGroup(
+  prefix: string,
+): Promise<KeychainApplicationAccessGroup> {
+  if (keychainApplicationAccessGroup) {
+    return keychainApplicationAccessGroup;
+  }
+  if (!KEYCHAIN_PREFIX.test(prefix)) {
+    return {
+      state: 'unavailable',
+      cause: new Error('keychain application group probe needs a team prefix'),
+    };
+  }
+  const native = requireOptionalNativeModule<Partial<OxyIdentityNativeModule>>('OxyIdentity');
+  const probe = native?.keychainApplicationAccessGroup;
+  if (!native || typeof probe !== 'function') {
+    keychainApplicationAccessGroup = { state: 'unsupported' };
+    return keychainApplicationAccessGroup;
+  }
+  let answer: unknown;
+  try {
+    answer = await probe.call(native, prefix);
+  } catch (cause) {
+    return { state: 'unavailable', cause };
+  }
+  if (answer === null || answer === undefined) {
+    // Not entitled (or not iOS): this binary keeps the placement it was built for.
+    keychainApplicationAccessGroup = { state: 'unsupported' };
+    return keychainApplicationAccessGroup;
+  }
+  if (typeof answer !== 'string' || !answer.startsWith(prefix) || !ACCESS_GROUP.test(answer)) {
+    // A native bug, not a locked keychain: asking again would answer the same,
+    // and `unavailable` would leave the app without storage. Keep the
+    // placement this build had before the probe existed.
+    return { state: 'unsupported' };
+  }
+  keychainApplicationAccessGroup = { state: 'resolved', accessGroup: answer };
+  return keychainApplicationAccessGroup;
+}

package/src/platform/crypto.ts

@@ -80,6 +80,7 @@ import type {
   CommonsSocialReceiveSignature,
   ExpoCryptoLike,
   ExpoSecureStoreLike,
+  KeychainApplicationAccessGroup,
   KeychainDefaultAccessGroup,
 } from './expoTypes';
 
@@ -92,6 +93,7 @@ export type {
   CommonsSocialReceiveSignature,
   ExpoCryptoLike,
   ExpoSecureStoreLike,
+  KeychainApplicationAccessGroup,
   KeychainDefaultAccessGroup,
 };
 
@@ -186,3 +188,9 @@ export function loadCommonsIdentityBridge(): Promise<CommonsIdentityBridge | nul
 export function loadKeychainDefaultAccessGroup(): Promise<KeychainDefaultAccessGroup> {
   return Promise.resolve({ state: 'unsupported' });
 }
+
+export function loadKeychainApplicationAccessGroup(
+  _prefix: string,
+): Promise<KeychainApplicationAccessGroup> {
+  return Promise.resolve({ state: 'unsupported' });
+}

package/src/platform/expoTypes.ts

@@ -123,6 +123,14 @@ export interface CommonsSocialReceiveSignature {
  *
  * 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).
+ *
+ * The three `*Retired*` methods (Commons protocol 4) reach a key the person,
+ * or the organization with `accountId`, rotated away from, by its public key,
+ * for SPENDING the coins still at its addresses: never for signing in. They are
+ * always present on the bridge and resolve `null` on a native module or a
+ * Commons that predates them; an answer that does not echo the key (and the
+ * account) asked for is refused, because the current key taken for a retired
+ * one is a payment signed by the wrong key.
  */
 export interface CommonsIdentityBridge {
   /**
@@ -149,6 +157,35 @@ export interface CommonsIdentityBridge {
     digest: string,
     accountId?: string,
   ): Promise<CommonsSocialReceiveSignature | null>;
+  /**
+   * The public keys (lowercase uncompressed SEC1 hex, de-duplicated) of the
+   * retired keys Commons holds for the person, or with `accountId` for that
+   * organization, minus the current one. `[]` when it holds none; `null` when
+   * Commons cannot say (absent, refused, or older than retired keys). Allowed
+   * for the wallet app only.
+   */
+  listRetiredKeys(accountId?: string): Promise<string[] | null>;
+  /**
+   * {@link deriveScopedSeed} over the key of that scope whose public key is
+   * `publicKey` (current or retired), never another key: `null` when Commons
+   * does not hold it.
+   */
+  deriveRetiredScopedSeed(
+    info: string,
+    publicKey: string,
+    accountId?: string,
+  ): Promise<string | null>;
+  /**
+   * {@link signSocialReceive} with the social-receive child `index` of the key
+   * of that scope whose public key is `publicKey` (current or retired), never
+   * another key. Allowed for the wallet app only.
+   */
+  signRetiredSocialReceive(
+    index: number,
+    digest: string,
+    publicKey: string,
+    accountId?: string,
+  ): Promise<CommonsSocialReceiveSignature | null>;
 }
 
 /**
@@ -170,3 +207,27 @@ export type KeychainDefaultAccessGroup =
   | { state: 'resolved'; accessGroup: string }
   | { state: 'unsupported' }
   | { state: 'unavailable'; cause: unknown };
+
+/**
+ * What the iOS keychain says about this app's OWN access group: its
+ * application identifier, `<prefix><bundle id>` (`ABCDE12345.so.oxy.mention`).
+ * Apple makes every app a member of that group whatever its
+ * `keychain-access-groups` lists, and no other app can name it, so it is where
+ * an app keeps the items that are its alone (its session credential): the
+ * keychain's counterpart of Android's per-app storage (ADR 0062 D6).
+ *
+ * The native module writes a probe item into that group EXPLICITLY and answers
+ * the group only when the keychain took it.
+ *
+ * - `resolved`: the group string.
+ * - `unsupported`: not iOS, a native build whose `OxyIdentity` module predates
+ *   this probe, a keychain that refused the group as not entitled, or an answer
+ *   that is not this team's group. Constant for the binary: callers keep the
+ *   placement that build was made for.
+ * - `unavailable`: the probe threw (before first unlock). Transient; never
+ *   cached.
+ */
+export type KeychainApplicationAccessGroup =
+  | { state: 'resolved'; accessGroup: string }
+  | { state: 'unsupported' }
+  | { state: 'unavailable'; cause: unknown };