@oxyhq/core 3.14.0 → 3.16.0

package/src/mixins/__tests__/OxyServices.nodes.test.ts

@@ -0,0 +1,341 @@
+/**
+ * User-Node Mixin tests (self-sovereign identity layer — Fase 5 user nodes).
+ *
+ * Stubs `makeRequest` so the tests run with no network, then asserts:
+ *  - `registerNode` fetches the caller's chain head (uncached), signs a
+ *    self-issued v2 `type:'node'` envelope (record `{ endpoint, nodePublicKey,
+ *    mode }`, seq=head+1, prev=head id, collection `app.oxy.node`, rkey `self`),
+ *    POSTs it to the EXISTING `/identity/records` path, sweeps the node +
+ *    `/users/me` GET caches, then returns the freshly-read status. `mode`
+ *    defaults to `pull`; an explicit `mode` is forwarded; genesis coords apply
+ *    when there is no head. It is NATIVE-ONLY: a signing failure (no on-device
+ *    identity) propagates, and no-auth throws before any network. It does NOT
+ *    sweep when the POST fails, and throws when the node fails to materialize.
+ *  - `getMyNode` shapes the cached GET `/nodes/me` and unwraps `.node` (or null).
+ *  - `removeMyNode` DELETEs `/nodes/me`, maps `{success}`→`{revoked}`, and sweeps.
+ *  - `provisionManagedVault` POSTs `/nodes/managed`, returns `.node`, and sweeps.
+ *  - `notifyNodeIngest` POSTs the URL-encoded hint path and resolves void.
+ *
+ * The write tests mock `SignatureService.signRecordV2` (asserting the exact
+ * record + chain coords) so they isolate the SDK's request shaping from native
+ * key storage — mirroring the civic mixin tests.
+ */
+
+import type { SignedRecordEnvelope } from '@oxyhq/contracts';
+import { OxyServices } from '../../OxyServices';
+import { SignatureService } from '../../crypto/signatureService';
+import type { UserNodeStatus } from '../OxyServices.nodes';
+
+const NODE_PUBLIC_KEY = `04${'ab'.repeat(63)}`; // 128 hex chars (uncompressed secp256k1)
+
+const sampleNode: UserNodeStatus = {
+  endpoint: 'https://node.example.com',
+  nodePublicKey: NODE_PUBLIC_KEY,
+  mode: 'pull',
+  managed: false,
+  controller: 'self',
+  status: 'active',
+  createdAt: '2026-06-27T00:00:00.000Z',
+  updatedAt: '2026-06-27T00:00:00.000Z',
+};
+
+describe('OxyServices.nodes', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+    jest.spyOn(oxy, 'getCurrentUserId').mockReturnValue('user-123');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe('registerNode', () => {
+    const signedEnvelope: SignedRecordEnvelope = {
+      version: 2,
+      type: 'node',
+      subject: 'did:web:oxy.so:u:user-123',
+      issuer: 'did:web:oxy.so:u:user-123',
+      record: { endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY, mode: 'pull' },
+      issuedAt: 1700000000000,
+      seq: 4,
+      prev: 'rec-3',
+      collection: 'app.oxy.node',
+      rkey: 'self',
+      publicKey: 'pub',
+      alg: 'ES256K-DER-SHA256',
+      signature: 'sig',
+    };
+
+    it('signs a v2 node record on the caller chain, POSTs /identity/records, sweeps, and returns the status', async () => {
+      const signV2Spy = jest.spyOn(SignatureService, 'signRecordV2').mockResolvedValue(signedEnvelope);
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      // 1st makeRequest = chain head; 2nd = POST /identity/records; 3rd = GET /nodes/me.
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 })
+        .mockResolvedValueOnce({ envelope: signedEnvelope, verified: true })
+        .mockResolvedValueOnce({ node: sampleNode });
+
+      const result = await oxy.registerNode({
+        endpoint: 'https://node.example.com',
+        nodePublicKey: NODE_PUBLIC_KEY,
+        mode: 'pull',
+      });
+
+      // Fetched the caller's chain head first (uncached).
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(
+        1,
+        'GET',
+        '/identity/records/user-123/chain/head',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+      // Signed a self-issued v2 `node` record: subject=caller DID, exact record,
+      // seq=head+1, prev=head id, collection app.oxy.node, rkey self.
+      expect(signV2Spy).toHaveBeenCalledWith(
+        'node',
+        'did:web:oxy.so:u:user-123',
+        { endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY, mode: 'pull' },
+        { seq: 4, prev: 'rec-3', collection: 'app.oxy.node', rkey: 'self' },
+      );
+      // Published via the EXISTING /identity/records path (NOT a bespoke endpoint).
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(
+        2,
+        'POST',
+        '/identity/records',
+        signedEnvelope,
+        expect.objectContaining({ cache: false }),
+      );
+      // Re-read the freshly-materialized status (cached GET /nodes/me).
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(
+        3,
+        'GET',
+        '/nodes/me',
+        undefined,
+        expect.objectContaining({ cache: true }),
+      );
+      // Swept the node + /users/me GET caches after the publish.
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/nodes/');
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/users/me');
+      expect(result).toEqual(sampleNode);
+    });
+
+    it('forwards an explicit push mode in the signed record', async () => {
+      const signV2Spy = jest
+        .spyOn(SignatureService, 'signRecordV2')
+        .mockResolvedValue(signedEnvelope);
+      jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 })
+        .mockResolvedValueOnce({ envelope: signedEnvelope, verified: true })
+        .mockResolvedValueOnce({ node: sampleNode });
+
+      await oxy.registerNode({
+        endpoint: 'https://node.example.com',
+        nodePublicKey: NODE_PUBLIC_KEY,
+        mode: 'push',
+      });
+
+      expect(signV2Spy).toHaveBeenCalledWith(
+        'node',
+        'did:web:oxy.so:u:user-123',
+        { endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY, mode: 'push' },
+        { seq: 4, prev: 'rec-3', collection: 'app.oxy.node', rkey: 'self' },
+      );
+    });
+
+    it('defaults mode to pull and uses genesis coords when there is no chain head', async () => {
+      const signV2Spy = jest
+        .spyOn(SignatureService, 'signRecordV2')
+        .mockResolvedValue(signedEnvelope);
+      jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: null, seq: -1, recordCount: 0 })
+        .mockResolvedValueOnce({ envelope: signedEnvelope, verified: true })
+        .mockResolvedValueOnce({ node: sampleNode });
+
+      await oxy.registerNode({
+        endpoint: 'https://node.example.com',
+        nodePublicKey: NODE_PUBLIC_KEY,
+      });
+
+      expect(signV2Spy).toHaveBeenCalledWith(
+        'node',
+        'did:web:oxy.so:u:user-123',
+        { endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY, mode: 'pull' },
+        { seq: 0, prev: null, collection: 'app.oxy.node', rkey: 'self' },
+      );
+    });
+
+    it('throws when no user is authenticated (before any network)', async () => {
+      jest.spyOn(oxy, 'getCurrentUserId').mockReturnValue(null);
+      const signV2Spy = jest.spyOn(SignatureService, 'signRecordV2');
+
+      await expect(
+        oxy.registerNode({ endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY }),
+      ).rejects.toThrow(/No authenticated user/);
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+      expect(signV2Spy).not.toHaveBeenCalled();
+    });
+
+    it('propagates a signing failure (native-only: no on-device identity)', async () => {
+      const signV2Spy = jest
+        .spyOn(SignatureService, 'signRecordV2')
+        .mockRejectedValue(new Error('No identity found. Please create or import an identity first.'));
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 });
+
+      await expect(
+        oxy.registerNode({ endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY }),
+      ).rejects.toThrow(/No identity found/);
+      // Only the chain-head read happened; no publish, no sweep.
+      expect(signV2Spy).toHaveBeenCalledTimes(1);
+      expect(makeRequestSpy).toHaveBeenCalledTimes(1);
+      expect(sweepSpy).not.toHaveBeenCalled();
+    });
+
+    it('does NOT sweep caches when the publish POST fails', async () => {
+      jest.spyOn(SignatureService, 'signRecordV2').mockResolvedValue(signedEnvelope);
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 })
+        .mockRejectedValueOnce(new Error('Signed record rejected: chain_fork'));
+
+      await expect(
+        oxy.registerNode({ endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY }),
+      ).rejects.toThrow();
+      expect(sweepSpy).not.toHaveBeenCalled();
+    });
+
+    it('throws when the node was stored on the chain but not materialized', async () => {
+      jest.spyOn(SignatureService, 'signRecordV2').mockResolvedValue(signedEnvelope);
+      jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 })
+        .mockResolvedValueOnce({ envelope: signedEnvelope, verified: true })
+        .mockResolvedValueOnce({ node: null });
+
+      await expect(
+        oxy.registerNode({ endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY }),
+      ).rejects.toThrow(/could not be materialized/);
+    });
+  });
+
+  describe('getMyNode', () => {
+    it('GETs /nodes/me (cached) and unwraps the node', async () => {
+      makeRequestSpy.mockResolvedValue({ node: sampleNode });
+
+      const result = await oxy.getMyNode();
+
+      expect(result).toEqual(sampleNode);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'GET',
+        '/nodes/me',
+        undefined,
+        expect.objectContaining({ cache: true }),
+      );
+    });
+
+    it('returns null when the caller has no node', async () => {
+      makeRequestSpy.mockResolvedValue({ node: null });
+      await expect(oxy.getMyNode()).resolves.toBeNull();
+    });
+
+    it('rejects on a transport failure', async () => {
+      makeRequestSpy.mockRejectedValue(new Error('network down'));
+      await expect(oxy.getMyNode()).rejects.toThrow();
+    });
+  });
+
+  describe('removeMyNode', () => {
+    it('DELETEs /nodes/me, maps success→revoked, and sweeps caches', async () => {
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockResolvedValue({ success: true });
+
+      const result = await oxy.removeMyNode();
+
+      expect(result).toEqual({ revoked: true });
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'DELETE',
+        '/nodes/me',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/nodes/');
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/users/me');
+    });
+
+    it('does NOT sweep caches when the DELETE fails', async () => {
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockRejectedValue(new Error('No active node registration to revoke'));
+
+      await expect(oxy.removeMyNode()).rejects.toThrow();
+      expect(sweepSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('provisionManagedVault', () => {
+    it('POSTs /nodes/managed, returns the node, and sweeps caches', async () => {
+      const managedNode: UserNodeStatus = {
+        ...sampleNode,
+        managed: true,
+        controller: 'oxy',
+      };
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockResolvedValue({ node: managedNode });
+
+      const result = await oxy.provisionManagedVault();
+
+      expect(result).toEqual(managedNode);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/nodes/managed',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/nodes/');
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/users/me');
+    });
+
+    it('does NOT sweep caches when provisioning fails', async () => {
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockRejectedValue(new Error('Managed vaults are not available right now'));
+
+      await expect(oxy.provisionManagedVault()).rejects.toThrow();
+      expect(sweepSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('notifyNodeIngest', () => {
+    it('POSTs the ingest-notify hint and resolves void', async () => {
+      makeRequestSpy.mockResolvedValue({ accepted: true });
+
+      await expect(oxy.notifyNodeIngest('user-9')).resolves.toBeUndefined();
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/nodes/ingest/notify/user-9',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('URL-encodes the userId path segment', async () => {
+      makeRequestSpy.mockResolvedValue({ accepted: true });
+      await oxy.notifyNodeIngest('a/b');
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/nodes/ingest/notify/a%2Fb',
+        undefined,
+        expect.anything(),
+      );
+    });
+
+    it('rejects on a transport failure', async () => {
+      makeRequestSpy.mockRejectedValue(new Error('network down'));
+      await expect(oxy.notifyNodeIngest('user-9')).rejects.toThrow();
+    });
+  });
+});

package/src/mixins/__tests__/commonsSignIn.test.ts

@@ -102,26 +102,27 @@ describe('OxyServices — "Sign in with Oxy" handoff', () => {
   });
 
   describe('getCommonsApprovalInfo (approver)', () => {
-    it('GETs the server-resolved approval info by authorizeCode', async () => {
-      const info = {
-        application: {
-          id: 'app1',
-          name: 'Mention',
-          type: 'first_party' as const,
-          isOfficial: true,
-          isInternal: false,
-          scopes: ['profile'],
-        },
+    const baseInfo = {
+      application: {
+        id: 'app1',
+        name: 'Mention',
+        type: 'first_party' as const,
+        isOfficial: true,
+        isInternal: false,
         scopes: ['profile'],
-        boundOrigin: 'https://mention.earth',
-        expiresAt: 1700000300000,
-        status: 'pending',
-      };
-      makeRequestSpy.mockResolvedValue(info);
+      },
+      scopes: ['profile'],
+      boundOrigin: 'https://mention.earth',
+      expiresAt: 1700000300000,
+      status: 'pending',
+    };
+
+    it('GETs the server-resolved approval info by authorizeCode', async () => {
+      makeRequestSpy.mockResolvedValue({ ...baseInfo, originVerified: true });
 
       const result = await oxy.getCommonsApprovalInfo('code-1');
 
-      expect(result).toEqual(info);
+      expect(result).toEqual({ ...baseInfo, originVerified: true });
       expect(makeRequestSpy).toHaveBeenCalledWith(
         'GET',
         '/auth/session/approve-info/code-1',
@@ -129,6 +130,30 @@ describe('OxyServices — "Sign in with Oxy" handoff', () => {
         expect.objectContaining({ cache: false }),
       );
     });
+
+    it('coerces a missing originVerified to false (fail-safe to "not verified")', async () => {
+      makeRequestSpy.mockResolvedValue(baseInfo);
+
+      const result = await oxy.getCommonsApprovalInfo('code-1');
+
+      expect(result.originVerified).toBe(false);
+    });
+
+    it('coerces a non-boolean originVerified to false', async () => {
+      makeRequestSpy.mockResolvedValue({ ...baseInfo, originVerified: 'yes' });
+
+      const result = await oxy.getCommonsApprovalInfo('code-1');
+
+      expect(result.originVerified).toBe(false);
+    });
+
+    it('passes through a server originVerified:false unchanged', async () => {
+      makeRequestSpy.mockResolvedValue({ ...baseInfo, originVerified: false });
+
+      const result = await oxy.getCommonsApprovalInfo('code-1');
+
+      expect(result.originVerified).toBe(false);
+    });
   });
 
   describe('approveCommonsSignIn (approver)', () => {

package/src/mixins/__tests__/connectedApps.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Connected-apps (OAuth grants) SDK tests.
+ *
+ * `listConnectedApps()` reads the user's authorized applications from
+ * `GET /auth/grants` and caches the response (identity-scoped). `revokeAppGrant`
+ * deletes a grant via `DELETE /auth/grants/:applicationId` and MUST invalidate
+ * the cached `GET:/auth/grants` so a re-read observes the removal instead of the
+ * STALE pre-revoke list (mirrors the privacy/follow invalidation contract).
+ */
+
+import { OxyServices } from '../../OxyServices';
+import type { ConnectedApp } from '../OxyServices.applications';
+
+/** Build a non-verified JWT whose payload decodes to the given claims. */
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
+}
+
+/** A JSON `Response` mimicking the API's `{ data: ... }` success envelope. */
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+const APP_A: ConnectedApp = {
+  applicationId: 'app-a',
+  name: 'App A',
+  logoUrl: 'https://cdn.example/a.png',
+  scopes: ['profile', 'email'],
+  firstGrantedAt: '2026-01-01T00:00:00.000Z',
+  lastUsedAt: '2026-06-01T00:00:00.000Z',
+};
+
+const APP_B: ConnectedApp = {
+  applicationId: 'app-b',
+  name: 'App B',
+  scopes: ['profile'],
+  firstGrantedAt: '2026-02-01T00:00:00.000Z',
+  lastUsedAt: '2026-06-02T00:00:00.000Z',
+};
+
+describe('connected apps (OAuth grants)', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('lists connected apps, unwrapping the { data } envelope', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse([APP_A, APP_B]));
+    const apps = await oxy.listConnectedApps();
+    expect(apps).toEqual([APP_A, APP_B]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toBe('http://test.invalid/auth/grants');
+    expect(init?.method).toBe('GET');
+  });
+
+  it('caches the list within the TTL (second read is a cache hit)', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse([APP_A]));
+    expect(await oxy.listConnectedApps()).toEqual([APP_A]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Second read within the TTL must not hit the network.
+    expect(await oxy.listConnectedApps()).toEqual([APP_A]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('revokes a grant via DELETE /auth/grants/:applicationId', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ revoked: true }));
+    await expect(oxy.revokeAppGrant('app-a')).resolves.toBeUndefined();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toBe('http://test.invalid/auth/grants/app-a');
+    expect(init?.method).toBe('DELETE');
+  });
+
+  it('busts the cached list after revokeAppGrant', async () => {
+    // 1) Warm the cache.
+    fetchMock.mockResolvedValueOnce(jsonResponse([APP_A, APP_B]));
+    expect(await oxy.listConnectedApps()).toEqual([APP_A, APP_B]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // A second read is a cache hit (no extra network call).
+    await oxy.listConnectedApps();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // 2) Revoke — must invalidate the cached list.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ revoked: true }));
+    await oxy.revokeAppGrant('app-a');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    // 3) Re-read MUST re-fetch and observe the revoked app gone.
+    fetchMock.mockResolvedValueOnce(jsonResponse([APP_B]));
+    const after = await oxy.listConnectedApps();
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(after).toEqual([APP_B]);
+  });
+
+  it('invalidates the exact GET:/auth/grants key on revoke', async () => {
+    const clearSpy = jest.spyOn(oxy, 'clearCacheEntry');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ revoked: true }));
+    await oxy.revokeAppGrant('app-a');
+    expect(clearSpy).toHaveBeenCalledWith('GET:/auth/grants');
+    clearSpy.mockRestore();
+  });
+});

package/src/mixins/__tests__/getFileDownloadUrl.test.ts

@@ -7,10 +7,9 @@
  *   - PUBLIC (no access token planted, no `expiresIn`) → the clean CDN form
  *     `${cloudURL}/<id>[?variant=...]` (default `https://cloud.oxy.so/<id>`),
  *     which CloudFront resolves against the public media origin.
- *   - SIGNED / PRIVATE (an access token is present OR `expiresIn` is passed) →
- *     the authenticated API origin form
- *     `${baseURL}/assets/<id>/stream?...&token=...` — private assets are not on
- *     the public CDN.
+ *   - EXPIRING ORIGIN FALLBACK (`expiresIn` is passed) → the API origin
+ *     stream form without a bearer token in the query string. Callers that need
+ *     private access should use `getFileDownloadUrlAsync()` for a scoped URL.
  */
 
 import { OxyServices } from '../../OxyServices';
@@ -50,38 +49,24 @@ describe('OxyServices.getFileDownloadUrl', () => {
       );
     });
 
-    it('can omit the token for persisted public image URLs while authenticated', () => {
+  });
+
+  describe('token-safe URL generation', () => {
+    it('does not include the in-memory access token in synchronous image URLs', () => {
       const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
       oxy.setTokens('access-token-abc');
 
-      const url = oxy.getFileDownloadUrl('file123', 'thumb', undefined, {
-        omitToken: true,
-      });
+      const url = oxy.getFileDownloadUrl('file123', 'thumb');
 
       expect(url).toBe('https://cloud.oxy.so/file123?variant=thumb');
       expect(url).not.toContain('access-token-abc');
       expect(url).not.toContain('token=');
     });
-  });
 
-  describe('signed / private assets → authenticated API origin', () => {
-    it('returns the stream endpoint with the token when an access token is present', () => {
+    it('routes through the stream endpoint when expiresIn is requested without embedding a token', () => {
       const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
       oxy.setTokens('access-token-abc');
 
-      const url = oxy.getFileDownloadUrl('file123', 'thumb');
-
-      expect(url.startsWith('https://api.oxy.so/assets/file123/stream?')).toBe(true);
-      const params = new URLSearchParams(url.split('?')[1]);
-      expect(params.get('variant')).toBe('thumb');
-      expect(params.get('token')).toBe('access-token-abc');
-      expect(params.get('fallback')).toBe('placeholderVisible');
-      expect(url).not.toContain('cloud.oxy.so');
-    });
-
-    it('routes through the stream endpoint when expiresIn is requested even without a token', () => {
-      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
-
       const url = oxy.getFileDownloadUrl('file123', 'thumb', 3600);
 
       expect(url.startsWith('https://api.oxy.so/assets/file123/stream?')).toBe(true);
@@ -90,6 +75,7 @@ describe('OxyServices.getFileDownloadUrl', () => {
       expect(params.get('variant')).toBe('thumb');
       expect(params.get('fallback')).toBe('placeholderVisible');
       expect(params.get('token')).toBeNull();
+      expect(url).not.toContain('access-token-abc');
       expect(url).not.toContain('cloud.oxy.so');
     });
   });

package/src/mixins/index.ts

@@ -31,6 +31,8 @@ import { OxyServicesManagedAccountsMixin } from './OxyServices.managedAccounts';
 import { OxyServicesContactsMixin } from './OxyServices.contacts';
 import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
+import { OxyServicesNodesMixin } from './OxyServices.nodes';
+import { OxyServicesLinksMixin } from './OxyServices.links';
 
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
@@ -66,6 +68,8 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 
 /**
@@ -134,6 +138,12 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesAppDataMixin,
     // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
     OxyServicesCivicMixin,
+    // User nodes / decentralization (Fase 5): register/read/revoke/manage the
+    // caller's personal data node + ingest hint.
+    OxyServicesNodesMixin,
+    // Link previews / unfurls: SDK-owned link-metadata resolution via oxy-api,
+    // so apps stop scraping link metadata locally.
+    OxyServicesLinksMixin,
 
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,