@oxy.so/protocol 1.6.0 → 1.7.0

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

@@ -151,6 +151,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,10 +205,33 @@ 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)));
+                },
             };
         });
     }

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,10 +196,33 @@ 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)));
+                },
             };
         });
     }

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
@@ -113,19 +119,24 @@ export interface CommonsSocialReceiveSignature {
  * path in `@oxy.so/core`'s `KeyManager` owns iOS sharing.
  */
 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>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/protocol",
-  "version": "1.6.0",
+  "version": "1.7.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",
@@ -158,16 +158,16 @@
   },
   "devDependencies": {
     "@react-native-async-storage/async-storage": "^3.1.1",
-    "@types/express": "^4.17.25",
-    "@types/node": "^22.20.1",
-    "@types/supertest": "^6.0.2",
-    "expo-crypto": "~56.0.3",
-    "expo-modules-core": "~58.0.26",
-    "expo-secure-store": "~57.0.4",
-    "express": "^4.22.2",
-    "jest": "^30.5.1",
-    "supertest": "^7.0.0",
-    "ts-jest": "^29.4.12",
-    "typescript": "^5.9.2"
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.6.6",
+    "@types/supertest": "^7.2.1",
+    "expo-crypto": "~58.0.7",
+    "expo-modules-core": "~58.0.30",
+    "expo-secure-store": "~58.0.2",
+    "express": "^5.3.0",
+    "jest": "^30.5.2",
+    "supertest": "^7.3.1",
+    "ts-jest": "^29.4.15",
+    "typescript": "~6.0.3"
   }
 }

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__/nodeApp.test.ts

@@ -432,11 +432,10 @@ describe('createNodeApp', () => {
       prev = id;
     }
 
-    // `?since[]=<id1>&since[]=<id2>` arrives as a string[] — the handler must
-    // take the FIRST value (a tampered array can never cause type confusion).
-    const res = await request(app)
-      .get('/oxy/log')
-      .query({ 'since[]': [ids[0], ids[2]] });
+    // A repeated `?since=<id1>&since=<id2>` arrives as a string[] under every
+    // Express query parser — the handler must take the FIRST value (a tampered
+    // array can never cause type confusion).
+    const res = await request(app).get('/oxy/log').query(`since=${ids[0]}&since=${ids[2]}`);
     expect(res.status).toBe(200);
     // Cursor resolves off ids[0] → records strictly after seq 0 → [1, 2].
     expect(res.body.records.map((entry: { seq: number }) => entry.seq)).toEqual([1, 2]);
@@ -456,9 +455,7 @@ describe('createNodeApp', () => {
       prev = await computeRecordId(envelope);
     }
 
-    const res = await request(app)
-      .get('/oxy/log')
-      .query({ 'limit[]': ['2', '99'] });
+    const res = await request(app).get('/oxy/log').query('limit=2&limit=99');
     expect(res.status).toBe(200);
     expect(res.body.records.map((entry: { seq: number }) => entry.seq)).toEqual([0, 1]);
   });

package/src/node/nodeApp.ts

@@ -399,7 +399,7 @@ export function createNodeApp(deps: NodeAppDependencies): NodeApp {
   );
 
   // ── Serve a content-addressed blob ───────────────────────────────────────────
-  app.get(`${NODE_BLOBS_PATH}/:hash`, async (req: Request, res: Response, next: NextFunction) => {
+  app.get(`${NODE_BLOBS_PATH}/:hash`, async (req, res, next) => {
     try {
       const hash = req.params.hash.toLowerCase();
       if (!SHA256_HEX.test(hash)) {

package/src/platform/crypto.native.ts

@@ -204,6 +204,19 @@ 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>;
 }
 
 const LOWER_HEX = /^[0-9a-f]+$/;
@@ -226,6 +239,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,15 +304,41 @@ 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;
     });
   }

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;
 }
 
 /**
@@ -119,19 +125,28 @@ export interface CommonsSocialReceiveSignature {
  * path in `@oxy.so/core`'s `KeyManager` owns iOS sharing.
  */
 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>;
 }