@oxy.so/core 1.6.0 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -118,7 +118,7 @@
     "@oxy.so/telemetry": "^1.1.1",
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "^1.2.0",
+    "@oxy.so/contracts": "^1.3.0",
     "@oxy.so/protocol": "^1.0.1",
     "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",

package/src/server/__tests__/traffic.test.ts

@@ -1,6 +1,61 @@
 import { createEcosystemTraffic } from '../traffic';
 
-jest.mock('../../OxyServices', () => ({ OxyServices: jest.fn(() => ({})) }));
+/**
+ * Every client the publisher builds, so a test can ask what it was handed.
+ *
+ * Named `mock*` because ts-jest hoists `jest.mock` above the imports and only
+ * lets a factory close over a binding with that prefix.
+ */
+const mockClients: Array<{ configureServiceAuth: jest.Mock; getServiceToken: jest.Mock }> = [];
+
+jest.mock('../../OxyServices', () => ({
+  OxyServices: jest.fn(() => {
+    const client = {
+      configureServiceAuth: jest.fn(),
+      getServiceToken: jest.fn(async () => 'token-from-workload'),
+    };
+    mockClients.push(client);
+    return client;
+  }),
+}));
+
+function lastClient() {
+  const client = mockClients[mockClients.length - 1];
+  if (!client) throw new Error('No OxyServices was built.');
+  return client;
+}
+
+/** Accepts every publish and remembers the headers, so nothing reaches a network. */
+function recordingFetch(sent: RequestInit[]) {
+  return jest.fn(async (_input, init) => {
+    sent.push(init as RequestInit);
+    return new Response(null, { status: 204 });
+  }) as unknown as typeof fetch;
+}
+
+function authorizations(sent: RequestInit[]): string[] {
+  return sent.map(init => (init.headers as Record<string, string>).Authorization);
+}
+
+/**
+ * A process with nothing configured and nothing to attest: a laptop.
+ *
+ * Emptied by assignment rather than `delete`, which Biome refuses on a property
+ * access — and `= undefined` would be worse than either, because Node stores the
+ * STRING "undefined" and every check here would read it as a configured value.
+ */
+function clearCredentialEnvironment() {
+  process.env.OXY_ACTIVITY_API_KEY = '';
+  process.env.OXY_ACTIVITY_API_SECRET = '';
+  process.env.OXY_SERVICE_API_KEY = '';
+  process.env.OXY_SERVICE_API_SECRET = '';
+  process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '';
+  process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI = '';
+}
+
+beforeEach(() => {
+  mockClients.length = 0;
+});
 
 it('publishes independently of viewers and waits for registration before removing a stopped instance', async () => {
   const originalFetch = globalThis.fetch;
@@ -47,3 +102,79 @@ it('rejects a partial activity credential instead of mixing it with service cred
     process.env = previous;
   }
 });
+
+/**
+ * Who may publish ecosystem activity, and who is still refused.
+ *
+ * ADR 0026 made "no api key, no secret" a legitimate shape for a first-party
+ * service: it attests its ECS task role instead. This constructor used to throw
+ * on exactly that shape, so the migration it asks for — delete two variables
+ * from a task definition — killed the process at boot, the circuit breaker
+ * rolled the deploy back, and the operator was told the service was stable.
+ */
+describe('ecosystem activity credentials', () => {
+  const previous = { ...process.env };
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    process.env = { ...previous };
+    globalThis.fetch = originalFetch;
+  });
+
+  it('uses a service key pair when the process holds one', async () => {
+    clearCredentialEnvironment();
+    process.env.OXY_SERVICE_API_KEY = 'service-key';
+    process.env.OXY_SERVICE_API_SECRET = 'service-secret';
+    const sent: RequestInit[] = [];
+    globalThis.fetch = recordingFetch(sent);
+
+    const traffic = createEcosystemTraffic({ service: 'mention', region: 'us-west-2' });
+    await traffic.stop();
+
+    expect(lastClient().configureServiceAuth).toHaveBeenCalledWith('service-key', 'service-secret');
+    expect(lastClient().getServiceToken).toHaveBeenCalled();
+  });
+
+  it('lets an explicit credential win over the environment', async () => {
+    clearCredentialEnvironment();
+    process.env.OXY_SERVICE_API_KEY = 'service-key';
+    process.env.OXY_SERVICE_API_SECRET = 'service-secret';
+    const sent: RequestInit[] = [];
+    globalThis.fetch = recordingFetch(sent);
+
+    const traffic = createEcosystemTraffic({ service: 'mention', region: 'us-west-2', credential: async () => 'explicit-token' });
+    await traffic.stop();
+
+    expect(authorizations(sent)).not.toContain('Bearer token-from-workload');
+    expect(authorizations(sent)).toContain('Bearer explicit-token');
+    expect(lastClient().getServiceToken).not.toHaveBeenCalled();
+  });
+
+  it('refuses a process with no credential and nothing to attest', () => {
+    clearCredentialEnvironment();
+
+    // A laptop or a CI box: the container credentials endpoint is not going to
+    // appear later, so saying so at boot beats failing on the first heartbeat.
+    expect(() => createEcosystemTraffic({ service: 'homiio', region: 'us-west-2' })).toThrow(
+      /needs one of: an OXY_ACTIVITY_API_KEY and OXY_ACTIVITY_API_SECRET pair, an OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET pair, or a workload identity/
+    );
+  });
+
+  it('publishes with no key pair at all when the process can attest its workload identity', async () => {
+    clearCredentialEnvironment();
+    // The variable ECS sets on every task, and nothing else does. Stubbed, so
+    // `canAttestWorkloadIdentity()` answers yes without a credentials endpoint.
+    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '/v2/credentials/abc';
+    const sent: RequestInit[] = [];
+    globalThis.fetch = recordingFetch(sent);
+
+    const traffic = createEcosystemTraffic({ service: 'mention', region: 'us-west-2' });
+    await traffic.stop();
+
+    // Unconfigured on purpose: that is what sends `getServiceToken()` down the
+    // workload path instead of handing it half a credential.
+    expect(lastClient().configureServiceAuth).not.toHaveBeenCalled();
+    expect(lastClient().getServiceToken).toHaveBeenCalled();
+    expect(authorizations(sent)).toContain('Bearer token-from-workload');
+  });
+});

package/src/server/traffic.ts

@@ -3,6 +3,12 @@ import { observeTrafficSocket, observeTrafficWebSocket, type TrafficWebSocket, t
 import { randomUUID } from 'node:crypto';
 import type { RequestHandler } from 'express';
 import { OxyServices } from '../OxyServices';
+// Static, unlike the lazy import in `mixins/OxyServices.auth.ts`: that module is
+// reachable from the root barrel, which ships to React Native, so pulling
+// `node:crypto` in eagerly there would cost every mobile bundle. This file is
+// server-only and the server barrel already exports `./workloadIdentity`, so
+// there is nothing here for a phone to load.
+import { canAttestWorkloadIdentity } from './workloadIdentity';
 import { createTrafficCollector, instrumentTrafficFetch, trafficMiddleware, type TrafficFlow, type ServiceEndpoint, resolveOxyServiceEndpoint, infrastructureLocation } from '@oxy.so/telemetry/collector';
 
 export interface EcosystemTrafficOptions {
@@ -36,8 +42,32 @@ export function createEcosystemTraffic(options: EcosystemTrafficOptions): {
   }
   const apiKey = activityKey || process.env.OXY_SERVICE_API_KEY;
   const apiSecret = activitySecret || process.env.OXY_SERVICE_API_SECRET;
-  if (!options.credential && (!apiKey || !apiSecret)) throw new Error('Ecosystem activity requires OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET');
+  /**
+   * Having no key pair is a legitimate configuration now — but only where this
+   * process can prove what it IS (ADR 0026).
+   *
+   * This used to throw on a missing pair, full stop. Every service in the fleet
+   * boots with `OXY_ECOSYSTEM_ACTIVITY_ENABLED=true`, so deleting
+   * `OXY_SERVICE_API_KEY` and `OXY_SERVICE_API_SECRET` from a task definition —
+   * which is the entire migration ADR 0026 asks for — killed the process at
+   * boot. The ECS circuit breaker then rolled the deploy back and reported the
+   * service stable, so the operator saw a rollback with nothing naming its
+   * cause. That is what one line cost, multiplied by fourteen services holding
+   * a secret they no longer need.
+   *
+   * What is still refused: nothing to authenticate with AND nothing to attest.
+   * That is a laptop or a CI box, where the container credentials endpoint is
+   * not going to turn up later, and the honest answer is to say so at boot
+   * rather than to fail on the first heartbeat.
+   */
+  if (!options.credential && (!apiKey || !apiSecret) && !canAttestWorkloadIdentity()) {
+    throw new Error(
+      'Ecosystem activity needs one of: an OXY_ACTIVITY_API_KEY and OXY_ACTIVITY_API_SECRET pair, an OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET pair, or a workload identity this process can attest (ADR 0026).',
+    );
+  }
   const oxy = new OxyServices({ baseURL });
+  // Left unconfigured when there is no pair on purpose: `getServiceToken()`
+  // attests instead of being handed half a credential to fail on.
   if (apiKey && apiSecret) oxy.configureServiceAuth(apiKey, apiSecret);
   const credential = options.credential ?? (() => oxy.getServiceToken());
   const fetcher = globalThis.fetch.bind(globalThis);