@oxy.so/core 1.7.0 → 1.7.3

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

@@ -0,0 +1,22 @@
+/**
+ * Registration proof-of-work — the CLIENT half of the anti-automation nonce
+ * `register()` (`mixins/OxyServices.auth.ts`) submits alongside the
+ * registration signature. The message format, difficulty and the full design
+ * rationale (why 16 bits, why sequential nonces are fine, what this is and
+ * isn't a defense against) live in `@oxy.so/protocol`'s
+ * `auth/registrationPow.ts` — this file is only the solve loop.
+ */
+import './polyfill';
+/**
+ * Grind a nonce for `publicKey`/`timestamp` that clears
+ * {@link REGISTRATION_POW_DIFFICULTY_BITS}, returned as a decimal counter.
+ *
+ * Hashes with `@noble/hashes/sha256` — pure JS, synchronous, identical output
+ * on web/Node/React Native with no native module and no per-attempt bridge
+ * crossing (see the difficulty constant's own doc for why that distinction is
+ * the whole point). Nonces are sequential (0, 1, 2, …) rather than random: the
+ * candidate space a hash function spreads solutions across is dense either
+ * way, so a counter finds one exactly as reliably as randomness would, without
+ * needing a randomness source at all.
+ */
+export declare function solveRegistrationPow(publicKey: string, timestamp: number): Promise<string>;

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -391,10 +391,10 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         /**
          * Whether this process can prove what it is (ADR 0026).
          *
-         * The check and the module that performs it are loaded LAZILY and only on a
-         * Node host. `@oxy.so/core`'s root barrel reaches React Native and Expo, and
-         * `server/workloadIdentity` imports `node:crypto` — a static import here
-         * would pull it into every mobile bundle for a path a phone can never take.
+         * The internal package subpath selects a client implementation for native
+         * and browser bundlers, and the signer only for Node hosts. The runtime
+         * Node guard avoids calling attestation on clients; the module boundary
+         * keeps node:crypto out of their bundle graphs (a guard alone cannot).
          *
          * @internal
          */

package/dist/types/server/workloadIdentity.client.d.ts

@@ -0,0 +1,4 @@
+import type { WorkloadServiceToken, WorkloadServiceTokenOptions } from './workloadIdentity';
+/** Workload attestation belongs to a Node host, never a browser or device. */
+export declare function canAttestWorkloadIdentity(): boolean;
+export declare function requestWorkloadServiceToken(_options: WorkloadServiceTokenOptions): Promise<WorkloadServiceToken>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.7.0",
+  "version": "1.7.3",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -59,7 +59,17 @@
       },
       "default": "./dist/esm/logger/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./internal/workload-identity": {
+      "types": "./dist/types/server/workloadIdentity.d.ts",
+      "react-native": "./dist/esm/server/workloadIdentity.client.js",
+      "browser": "./dist/esm/server/workloadIdentity.client.js",
+      "node": {
+        "import": "./dist/esm/server/workloadIdentity.js",
+        "require": "./dist/cjs/server/workloadIdentity.js"
+      },
+      "default": "./dist/esm/server/workloadIdentity.client.js"
+    }
   },
   "files": [
     "NOTICE",
@@ -80,7 +90,7 @@
     "directory": "packages/core"
   },
   "author": "OxyHQ",
-  "license": "Apache-2.0",
+  "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://oxy.so",
   "engines": {
     "node": ">=18.0.0"
@@ -119,7 +129,7 @@
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
     "@oxy.so/contracts": "^1.3.0",
-    "@oxy.so/protocol": "^1.0.1",
+    "@oxy.so/protocol": "^1.1.0",
     "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",
     "express-rate-limit": "^8.6.0",

package/src/__tests__/fixEsmImports.test.ts

@@ -0,0 +1,132 @@
+/**
+ * `scripts/fix-esm-imports.mjs` must rewrite DYNAMIC relative imports too.
+ *
+ * ## The failure this exists for, which happened
+ *
+ * This package writes relative specifiers without an extension — legal under
+ * `moduleResolution: bundler`, illegal in Node's ESM resolver — and the
+ * post-build script adds the extension back. For its first life the script's
+ * pattern was `(?:from|import)\s+['"]`, which cannot match `import('./x')`:
+ * the keyword is followed by a parenthesis, not whitespace. Every dynamic
+ * import therefore shipped extensionless in `dist/esm`.
+ *
+ * `OxyServices.getServiceToken()` loads `../server/workloadIdentity` that way
+ * to decide whether this process can attest its workload identity (ADR 0026),
+ * and it does so inside a `try/catch` that reads any failure as "cannot attest
+ * here". So in every ESM consumer of the BUILT package the ADR 0026 fallback
+ * was dead, and a service whose task role attests perfectly well was told
+ * `Service credentials not provided` — which is what a deployment sees the
+ * moment its key pair is removed, and the reason `mention-mcp` and `alia` could
+ * not complete the migration while `mention`, `allo` and `alia-integrations`
+ * (all CommonJS, where `require()` supplies the extension) already had.
+ *
+ * ## Why this spawns the real script
+ *
+ * The defect is in the build OUTPUT, and core's CI job runs jest without
+ * building the package, so a test that reads `dist/esm` would pass by finding
+ * nothing. `serviceTokenWorkloadFallback.test.ts` cannot catch it either: jest
+ * resolves extensionless specifiers, and it mocks that module by name. The one
+ * thing that measures the real behaviour without a build is to run the script
+ * over a fixture and read what it wrote.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const script = path.resolve(__dirname, '../../scripts/fix-esm-imports.mjs');
+
+function runOnFixture(files: Record<string, string>): Record<string, string> {
+  const root = mkdtempSync(path.join(tmpdir(), 'oxy-core-esm-fix-'));
+  try {
+    for (const [name, source] of Object.entries(files)) {
+      const full = path.join(root, name);
+      mkdirSync(path.dirname(full), { recursive: true });
+      writeFileSync(full, source);
+    }
+    const result = spawnSync(process.execPath, [script, root], { encoding: 'utf8' });
+    expect(result.status).toBe(0);
+    const out: Record<string, string> = {};
+    for (const name of Object.keys(files)) {
+      out[name] = readFileSync(path.join(root, name), 'utf8');
+    }
+    return out;
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+describe('fix-esm-imports', () => {
+  it('adds .js to a dynamic relative import', () => {
+    const out = runOnFixture({
+      'server/workloadIdentity.js': 'export const canAttestWorkloadIdentity = () => true;\n',
+      'mixins/auth.js': [
+        'export async function canUse() {',
+        "  const { canAttestWorkloadIdentity } = await import('../server/workloadIdentity');",
+        '  return canAttestWorkloadIdentity();',
+        '}',
+        '',
+      ].join('\n'),
+    });
+
+    expect(out['mixins/auth.js']).toContain("await import('../server/workloadIdentity.js')");
+  });
+
+  it('rewrites every dynamic import in a file, not only the first', () => {
+    const out = runOnFixture({
+      'server/workloadIdentity.js': 'export const a = 1;\nexport const b = 2;\n',
+      'mixins/auth.js': [
+        "const first = await import('../server/workloadIdentity');",
+        "const second = await import('../server/workloadIdentity');",
+        '',
+      ].join('\n'),
+    });
+
+    const matches = out['mixins/auth.js'].match(/workloadIdentity\.js/g) ?? [];
+    expect(matches).toHaveLength(2);
+    // And nothing was left extensionless.
+    expect(out['mixins/auth.js']).not.toMatch(/workloadIdentity'/);
+  });
+
+  it('tolerates whitespace between the keyword and the parenthesis', () => {
+    const out = runOnFixture({
+      'server/workloadIdentity.js': 'export const a = 1;\n',
+      'mixins/auth.js': "const m = await import(\n  '../server/workloadIdentity'\n);\n",
+    });
+
+    expect(out['mixins/auth.js']).toContain("'../server/workloadIdentity.js'");
+  });
+
+  it('resolves a dynamic directory import to its index', () => {
+    const out = runOnFixture({
+      'server/index.js': 'export const a = 1;\n',
+      'mixins/auth.js': "const m = await import('../server');\n",
+    });
+
+    expect(out['mixins/auth.js']).toContain("'../server/index.js'");
+  });
+
+  it('still rewrites the static forms, and leaves bare and already-suffixed specifiers alone', () => {
+    const out = runOnFixture({
+      'server/workloadIdentity.js': 'export const a = 1;\n',
+      'mixins/auth.js': [
+        "import { a } from '../server/workloadIdentity';",
+        "import '../server/workloadIdentity';",
+        "export { a as b } from '../server/workloadIdentity';",
+        "import { createHash } from 'node:crypto';",
+        "import { z } from 'zod';",
+        "const late = await import('./sibling.js');",
+        '',
+      ].join('\n'),
+      'mixins/sibling.js': 'export const s = 1;\n',
+    });
+
+    const source = out['mixins/auth.js'];
+    expect(source.match(/workloadIdentity\.js/g) ?? []).toHaveLength(3);
+    expect(source).toContain("import { createHash } from 'node:crypto';");
+    expect(source).toContain("import { z } from 'zod';");
+    expect(source).toContain("await import('./sibling.js')");
+    expect(source).not.toContain('sibling.js.js');
+  });
+});

package/src/crypto/__tests__/registrationPow.test.ts

@@ -0,0 +1,61 @@
+/**
+ * The client half of registration proof-of-work: `solveRegistrationPow` must
+ * find a nonce that an INDEPENDENT hasher (not the one it used to search)
+ * agrees clears the shared difficulty — otherwise the client and the server
+ * (`packages/api`, which hashes with Node's `crypto`, not `@noble/hashes`)
+ * could silently disagree about what "solved" means.
+ */
+
+import crypto from 'crypto';
+import {
+  meetsRegistrationPowDifficulty,
+  registrationPowMessage,
+  REGISTRATION_POW_DIFFICULTY_BITS,
+} from '@oxy.so/protocol';
+import { solveRegistrationPow } from '../registrationPow';
+
+function nodeDigestOf(publicKey: string, timestamp: number, nonce: string): string {
+  return crypto
+    .createHash('sha256')
+    .update(registrationPowMessage(publicKey, timestamp, nonce))
+    .digest('hex');
+}
+
+describe('solveRegistrationPow', () => {
+  it('finds a nonce that Node crypto (not @noble/hashes) also agrees clears the difficulty', async () => {
+    const publicKey = 'test-public-key';
+    const timestamp = 1_700_000_000_000;
+
+    const nonce = await solveRegistrationPow(publicKey, timestamp);
+    const digest = nodeDigestOf(publicKey, timestamp, nonce);
+
+    expect(meetsRegistrationPowDifficulty(digest, REGISTRATION_POW_DIFFICULTY_BITS)).toBe(true);
+  });
+
+  it('is deterministic: the same publicKey/timestamp always yields the same nonce', async () => {
+    const publicKey = 'deterministic-key';
+    const timestamp = 1_700_000_000_001;
+
+    const first = await solveRegistrationPow(publicKey, timestamp);
+    const second = await solveRegistrationPow(publicKey, timestamp);
+
+    expect(second).toBe(first);
+  });
+
+  it('binds the nonce to publicKey and timestamp, not just to itself', async () => {
+    const timestamp = 1_700_000_000_002;
+    const nonce = await solveRegistrationPow('bound-key', timestamp);
+
+    // The nonce solves its OWN message under the shared difficulty check...
+    expect(
+      meetsRegistrationPowDifficulty(nodeDigestOf('bound-key', timestamp, nonce), REGISTRATION_POW_DIFFICULTY_BITS)
+    ).toBe(true);
+    // ...but the message it was solved for is bound to that exact publicKey —
+    // reusing the nonce string under an unrelated one hashes to something
+    // unrelated, i.e. `registrationPowMessage` actually mixes `publicKey` in
+    // rather than the digest depending on `nonce` alone.
+    expect(registrationPowMessage('bound-key', timestamp, nonce)).not.toBe(
+      registrationPowMessage('a-different-key', timestamp, nonce)
+    );
+  });
+});

package/src/crypto/registrationPow.ts

@@ -0,0 +1,60 @@
+/**
+ * Registration proof-of-work — the CLIENT half of the anti-automation nonce
+ * `register()` (`mixins/OxyServices.auth.ts`) submits alongside the
+ * registration signature. The message format, difficulty and the full design
+ * rationale (why 16 bits, why sequential nonces are fine, what this is and
+ * isn't a defense against) live in `@oxy.so/protocol`'s
+ * `auth/registrationPow.ts` — this file is only the solve loop.
+ */
+
+import './polyfill';
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils';
+import {
+  meetsRegistrationPowDifficulty,
+  registrationPowMessage,
+  REGISTRATION_POW_DIFFICULTY_BITS,
+} from '@oxy.so/protocol';
+
+/**
+ * How many attempts the grind loop runs before yielding to the event loop.
+ *
+ * A synchronous hot loop long enough to matter (an average solve at 16 bits
+ * is 65,536 attempts) would otherwise block the JS thread for its entire
+ * duration — on a mobile app that means no touch response, no animation, for
+ * up to roughly a second. Yielding periodically keeps the UI responsive
+ * during the grind at the cost of a handful of event-loop round trips, which
+ * is imperceptible next to the grind itself.
+ */
+const YIELD_EVERY_N_ATTEMPTS = 2000;
+
+function yieldToEventLoop(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+/**
+ * Grind a nonce for `publicKey`/`timestamp` that clears
+ * {@link REGISTRATION_POW_DIFFICULTY_BITS}, returned as a decimal counter.
+ *
+ * Hashes with `@noble/hashes/sha256` — pure JS, synchronous, identical output
+ * on web/Node/React Native with no native module and no per-attempt bridge
+ * crossing (see the difficulty constant's own doc for why that distinction is
+ * the whole point). Nonces are sequential (0, 1, 2, …) rather than random: the
+ * candidate space a hash function spreads solutions across is dense either
+ * way, so a counter finds one exactly as reliably as randomness would, without
+ * needing a randomness source at all.
+ */
+export async function solveRegistrationPow(publicKey: string, timestamp: number): Promise<string> {
+  for (let nonce = 0; ; nonce += 1) {
+    const candidate = String(nonce);
+    const digest = bytesToHex(
+      sha256(utf8ToBytes(registrationPowMessage(publicKey, timestamp, candidate)))
+    );
+    if (meetsRegistrationPowDifficulty(digest, REGISTRATION_POW_DIFFICULTY_BITS)) {
+      return candidate;
+    }
+    if (nonce % YIELD_EVERY_N_ATTEMPTS === YIELD_EVERY_N_ATTEMPTS - 1) {
+      await yieldToEventLoop();
+    }
+  }
+}

package/src/mixins/OxyServices.auth.ts

@@ -19,6 +19,7 @@ export {
 } from '../utils/commonsApproval';
 import { OxyAuthenticationError } from '../OxyServices.errors';
 import { KeyManager } from '../crypto/keyManager';
+import { solveRegistrationPow } from '../crypto/registrationPow';
 import { SignatureService } from '../crypto/signatureService';
 import { loadNodeCrypto } from '@oxy.so/protocol';
 import { logger } from '../logger';
@@ -646,17 +647,17 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
     /**
      * Whether this process can prove what it is (ADR 0026).
      *
-     * The check and the module that performs it are loaded LAZILY and only on a
-     * Node host. `@oxy.so/core`'s root barrel reaches React Native and Expo, and
-     * `server/workloadIdentity` imports `node:crypto` — a static import here
-     * would pull it into every mobile bundle for a path a phone can never take.
+     * The internal package subpath selects a client implementation for native
+     * and browser bundlers, and the signer only for Node hosts. The runtime
+     * Node guard avoids calling attestation on clients; the module boundary
+     * keeps node:crypto out of their bundle graphs (a guard alone cannot).
      *
      * @internal
      */
     async _canUseWorkloadIdentity(): Promise<boolean> {
       if (typeof process === 'undefined' || !process.versions?.node) return false;
       try {
-        const { canAttestWorkloadIdentity } = await import('../server/workloadIdentity');
+        const { canAttestWorkloadIdentity } = await import('@oxy.so/core/internal/workload-identity');
         return canAttestWorkloadIdentity();
       } catch {
         // A bundler that dropped the server subpath, or a runtime without it.
@@ -683,7 +684,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       if (entry?.token && entry.expiresAt > now + 60_000) return entry.token;
       if (entry?.pending) return entry.pending;
 
-      const { requestWorkloadServiceToken } = await import('../server/workloadIdentity');
+      const { requestWorkloadServiceToken } = await import('@oxy.so/core/internal/workload-identity');
       const seeded = entry ?? {
         token: '',
         expiresAt: 0,
@@ -844,10 +845,16 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       timestamp: number
     ): Promise<{ message: string; user: User }> {
       try {
+        // Advisory for now (server soft-enforces — see
+        // `SessionController.register`), but solved unconditionally so every
+        // client is already sending it once the server starts requiring it.
+        const powNonce = await solveRegistrationPow(publicKey, timestamp);
+
         const res = await this.makeRequest<{ message: string; user: User }>('POST', '/auth/register', {
           publicKey,
           signature,
           timestamp,
+          powNonce,
         }, { cache: false, skipAuth: true });
 
         if (!res || (typeof res === 'object' && Object.keys(res).length === 0)) {

package/src/server/__tests__/workloadIdentity.client.test.ts

@@ -0,0 +1,16 @@
+import { canAttestWorkloadIdentity, requestWorkloadServiceToken } from '../workloadIdentity.client';
+
+describe('client workload identity boundary', () => {
+  it('cannot attest even when Node process globals are present', () => {
+    expect(process.versions.node).toBeTruthy();
+    expect(canAttestWorkloadIdentity()).toBe(false);
+  });
+
+  it('rejects before contacting a server when explicitly requested', async () => {
+    const fetchSpy = jest.spyOn(globalThis, 'fetch');
+    await expect(requestWorkloadServiceToken({ baseUrl: 'https://example.test' }))
+      .rejects.toThrow('only available on a Node host');
+    expect(fetchSpy).not.toHaveBeenCalled();
+    fetchSpy.mockRestore();
+  });
+});

package/src/server/workloadIdentity.client.ts

@@ -0,0 +1,12 @@
+import type { WorkloadServiceToken, WorkloadServiceTokenOptions } from './workloadIdentity';
+
+/** Workload attestation belongs to a Node host, never a browser or device. */
+export function canAttestWorkloadIdentity(): boolean {
+  return false;
+}
+
+export async function requestWorkloadServiceToken(
+  _options: WorkloadServiceTokenOptions,
+): Promise<WorkloadServiceToken> {
+  throw new Error('Workload identity is only available on a Node host');
+}