@oxyhq/core 3.14.0 → 3.15.0

package/src/mixins/OxyServices.nodes.ts

@@ -0,0 +1,348 @@
+/**
+ * User-Node Methods Mixin (self-sovereign identity layer — Fase 5 user nodes)
+ *
+ * The client surface for a user's personal data NODE — the decentralised store
+ * that holds an authentic copy of their signed-record chain. Commons drives all
+ * of this:
+ *
+ *  - {@link OxyServicesNodesMixin.registerNode} registers (or re-registers) a
+ *    SELF-HOSTED node. Registration is NOT a bespoke endpoint — it is a signed
+ *    `type:'node'` v2 record (`collection: 'app.oxy.node'`, `rkey: 'self'`,
+ *    last-writer-wins) published through the EXISTING `POST /identity/records`
+ *    path; the server verifies it and materializes the operational
+ *    {@link UserNodeStatus} cache as a side effect, so the registration's
+ *    authority is the user's own signature, never an Oxy grant.
+ *  - {@link OxyServicesNodesMixin.getMyNode} reads the caller's cached node
+ *    status (`GET /nodes/me`) — the fast, stale-but-instant projection plus the
+ *    live liveness badge Oxy maintains with background probes.
+ *  - {@link OxyServicesNodesMixin.removeMyNode} revokes the registration
+ *    (`DELETE /nodes/me`) so the node leaves the DID document and the liveness
+ *    sweeps.
+ *  - {@link OxyServicesNodesMixin.provisionManagedVault} asks Oxy to operate a
+ *    MANAGED vault on the caller's behalf (`POST /nodes/managed`) — the
+ *    "Create your vault" convenience for non-technical users (Oxy custodial-signs
+ *    the node record; `managed:true, controller:'oxy'`).
+ *  - {@link OxyServicesNodesMixin.notifyNodeIngest} sends an unauthenticated
+ *    HINT (`POST /nodes/ingest/notify/:userId`) that a user's node has new
+ *    records; the server fully re-verifies before ingesting, so the hint can
+ *    never inject data.
+ *
+ * `registerNode` signs on the caller's per-subject hash chain with the on-device
+ * identity key (reusing {@link SignatureService.signRecordV2} — the same
+ * `ES256K-DER-SHA256` scheme + {@link signedRecordSigningInput} the identity and
+ * civic mixins use), so it is NATIVE-ONLY: it throws on web (where `KeyManager`
+ * has no key) and when no user is authenticated. Reading the node status,
+ * revoking, provisioning a managed vault, and sending an ingest hint are plain
+ * authenticated/public requests with no signing.
+ *
+ * The wire shapes here are API-INTERNAL (the F5 user-node surface is not yet a
+ * published `@oxyhq/contracts` schema), so {@link UserNodeStatus} mirrors the
+ * server's `serializeNode` projection exactly. Dates cross the wire as ISO
+ * strings.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+import { SignatureService } from '../crypto/signatureService';
+import { buildUserDid } from './OxyServices.identity';
+import { CACHE_TIMES } from './mixinHelpers';
+
+/**
+ * AtProto-style collection (NSID) for a user-node registration record — matches
+ * the server's `NODE_COLLECTION`. A user has exactly one node, so the record is
+ * keyed by the constant {@link NODE_RKEY} (last-writer-wins): re-registering
+ * over-writes the single `self` record rather than appending a second node.
+ */
+const NODE_COLLECTION = 'app.oxy.node';
+
+/**
+ * The AtProto-style record key for the single node registration — matches the
+ * server's `NODE_RKEY`. Constant (`'self'`) because a user has one node.
+ */
+const NODE_RKEY = 'self';
+
+/**
+ * Cache-key prefix of every node read (`GET /nodes/me`). Swept after a
+ * register / revoke / managed-provision so a re-read reflects the new node
+ * (or its absence) instead of a stale cached one. The identity tag is a key
+ * SUFFIX, so this prefix invalidates the resource for every cached identity.
+ */
+const NODES_CACHE_PREFIX = 'GET:/nodes/';
+
+/**
+ * Cache-key prefix of the current user's `GET /users/me`. Swept alongside the
+ * node caches because the user's derived DID document embeds an `#oxy-node`
+ * service entry derived from the node row, so registering / revoking / managing
+ * a node changes user-facing identity state.
+ */
+const USERS_ME_CACHE_PREFIX = 'GET:/users/me';
+
+/** How Oxy and the node move records: the node pulls (default), or Oxy pushes. */
+export type UserNodeMode = 'pull' | 'push';
+
+/**
+ * Who operates the node:
+ *  - `self` — the user self-hosts the node (registered by their own signed
+ *    `type:'node'` record).
+ *  - `oxy`  — Oxy operates a MANAGED vault on the user's behalf (custodial-signed
+ *    `type:'node'` record; the `controller:[OXY_DID]` model).
+ */
+export type UserNodeController = 'self' | 'oxy';
+
+/**
+ * Liveness badge of a node, maintained ONLY by Oxy's background probes:
+ *  - `active`      — the last probe reached the node's liveness manifest.
+ *  - `unreachable` — the last probe failed (DNS/connect/timeout/non-2xx); the
+ *    cached row is still served, only the badge changes.
+ *  - `revoked`     — the user removed the registration; excluded from the DID
+ *    document and from liveness sweeps.
+ */
+export type UserNodeLivenessStatus = 'active' | 'unreachable' | 'revoked';
+
+/**
+ * The caller's registered node, as projected by the server's `serializeNode`
+ * (`GET /nodes/me`, `POST /nodes/managed`). A denormalised, fast-to-read copy of
+ * the authoritative signed `type:'node'` record plus the live liveness state Oxy
+ * maintains in the background.
+ *
+ * `mode` / `managed` / `controller` / `status` are always present (server fields
+ * with defaults); the probe/sync fields and `nodeDid` are present only once set.
+ * The `Date` fields cross the wire as ISO-8601 strings.
+ */
+export interface UserNodeStatus {
+  /** Optional DID the node advertises for itself (informational). */
+  nodeDid?: string;
+  /** The node's public HTTPS base URL (where its liveness manifest lives). */
+  endpoint: string;
+  /** The node's secp256k1 public key (hex) — records it signs verify against this. */
+  nodePublicKey: string;
+  /** Transport direction. `pull` (the node paces its own sync) by default. */
+  mode: UserNodeMode;
+  /** Whether Oxy operates this node on the user's behalf (managed vault). */
+  managed: boolean;
+  /** Operator of the node — `self` (user self-hosts) or `oxy` (managed vault). */
+  controller: UserNodeController;
+  /** Liveness badge — maintained only by background probes, never a read handler. */
+  status: UserNodeLivenessStatus;
+  /** Last time a probe reached the node successfully (ISO-8601). */
+  lastSeenAt?: string;
+  /** Last time a probe ran, success or failure (ISO-8601). */
+  lastProbeAt?: string;
+  /** Human-readable reason the last probe OR ingest failed (cleared on success). */
+  lastError?: string;
+  /** Last synced chain `seq` for two-way sync (advanced only by the ingest worker). */
+  cursor?: number;
+  /** Last time the ingest worker ran a pull for this node (ISO-8601). */
+  lastSyncedAt?: string;
+  /** When the node was first registered (ISO-8601). */
+  createdAt: string;
+  /** When the node row was last updated (ISO-8601). */
+  updatedAt: string;
+}
+
+/**
+ * Input for {@link OxyServicesNodesMixin.registerNode} — the operational facts of
+ * the user's self-hosted node that go into the signed `type:'node'` record.
+ */
+export interface RegisterNodeInput {
+  /** The node's public HTTPS base URL (where its liveness manifest is served). */
+  endpoint: string;
+  /** The node's secp256k1 public key (hex) — records the node signs verify against this. */
+  nodePublicKey: string;
+  /** Transport direction; defaults to `'pull'` when omitted. */
+  mode?: UserNodeMode;
+}
+
+/** Result of {@link OxyServicesNodesMixin.removeMyNode} (`DELETE /nodes/me`). */
+export interface RemoveNodeResult {
+  /** `true` when an active registration was flipped to `revoked`. */
+  revoked: boolean;
+}
+
+/**
+ * The current chain head as returned by `GET /identity/records/:userId/chain/head`.
+ * `headRecordId` is `null` and `seq` is `-1` when the subject has no chain yet,
+ * so the next record's coordinates are always `seq: head.seq + 1` (genesis = 0)
+ * and `prev: head.headRecordId` (genesis = null).
+ */
+interface ChainHeadResponse {
+  headRecordId: string | null;
+  seq: number;
+  recordCount: number;
+}
+
+export function OxyServicesNodesMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * Register (or re-register) the caller's SELF-HOSTED personal data node.
+     *
+     * Builds the `{ endpoint, nodePublicKey, mode }` node record, signs a v2
+     * envelope on the caller's own per-subject hash chain (fetching the current
+     * chain head first so `seq`/`prev` are never stale), and publishes it through
+     * the EXISTING `POST /identity/records` path — which verifies the signature
+     * and materializes the operational node cache as a side effect. The signed
+     * record (not this call) is the authority; re-registering over-writes the
+     * single `self` record (last-writer-wins).
+     *
+     * NATIVE-ONLY: signs with the on-device identity key (throws on web / when no
+     * identity or no authenticated user — the guard fires before any network).
+     * `mode` defaults to `'pull'`. After a successful publish the node + `/users/me`
+     * GET caches are swept, then the freshly-materialized status is returned.
+     *
+     * Throws if the chain record stored but the server skipped materialization
+     * (e.g. a malformed endpoint the server rejected) — an unexpected state rather
+     * than a silent `null`.
+     *
+     * @param input - The node's endpoint, public key, and optional transport mode.
+     */
+    async registerNode(input: RegisterNodeInput): Promise<UserNodeStatus> {
+      try {
+        const userId = this.getCurrentUserId();
+        if (!userId) {
+          throw new Error('No authenticated user — sign in before registering a node.');
+        }
+        const subject = buildUserDid(userId);
+        const record: Record<string, unknown> = {
+          endpoint: input.endpoint,
+          nodePublicKey: input.nodePublicKey,
+          mode: input.mode ?? 'pull',
+        };
+
+        // Fetch the caller's chain head fresh (uncached) so seq/prev are correct
+        // → no bad_seq / chain_fork — exactly as the identity/civic signers do.
+        const head = await this.makeRequest<ChainHeadResponse>(
+          'GET',
+          `/identity/records/${encodeURIComponent(userId)}/chain/head`,
+          undefined,
+          { cache: false },
+        );
+        const envelope = await SignatureService.signRecordV2('node', subject, record, {
+          seq: head.seq + 1,
+          prev: head.headRecordId,
+          collection: NODE_COLLECTION,
+          rkey: NODE_RKEY,
+        });
+
+        await this.makeRequest(
+          'POST',
+          '/identity/records',
+          envelope,
+          { cache: false },
+        );
+        this._sweepNodeCaches();
+
+        const node = await this.getMyNode();
+        if (!node) {
+          throw new Error('Node registration stored but the node could not be materialized.');
+        }
+        return node;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Read the caller's registered node status (`GET /nodes/me`), or `null` when
+     * the caller has no node. Auth required; short-TTL cached (the liveness badge
+     * is background-maintained) and swept after the caller's own
+     * register / revoke / managed-provision.
+     */
+    async getMyNode(): Promise<UserNodeStatus | null> {
+      try {
+        const res = await this.makeRequest<{ node: UserNodeStatus | null }>(
+          'GET',
+          '/nodes/me',
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
+        );
+        return res.node ?? null;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Revoke the caller's node registration (`DELETE /nodes/me`). The node flips
+     * to `revoked` server-side (leaving the DID document and liveness sweeps).
+     * Auth required; the node + `/users/me` GET caches are swept on success.
+     *
+     * Maps the server's `{ success }` to the SDK's `{ revoked }` semantic.
+     */
+    async removeMyNode(): Promise<RemoveNodeResult> {
+      try {
+        const res = await this.makeRequest<{ success: boolean }>(
+          'DELETE',
+          '/nodes/me',
+          undefined,
+          { cache: false },
+        );
+        this._sweepNodeCaches();
+        return { revoked: res.success === true };
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Provision (or refresh) an Oxy-operated MANAGED vault for the caller
+     * (`POST /nodes/managed`) — the "Create your vault" convenience for
+     * non-technical users. Oxy custodial-signs the node registration onto the
+     * caller's chain and returns the materialized node (`managed:true,
+     * controller:'oxy'`). Idempotent server-side. Auth required; the owner id is
+     * resolved from the session, never the body. The node + `/users/me` GET caches
+     * are swept on success.
+     */
+    async provisionManagedVault(): Promise<UserNodeStatus> {
+      try {
+        const res = await this.makeRequest<{ node: UserNodeStatus }>(
+          'POST',
+          '/nodes/managed',
+          undefined,
+          { cache: false },
+        );
+        this._sweepNodeCaches();
+        return res.node;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Send an ingest HINT that a user's node has new records
+     * (`POST /nodes/ingest/notify/:userId`). Unauthenticated by design and
+     * fire-and-forget on the server (it only schedules a background re-pull of the
+     * named user's OWN node, then fully re-verifies — a notify can never inject
+     * data), so this resolves once the 202 hint is accepted and returns nothing.
+     *
+     * @param userId - The user whose node may have new records. URL-encoded.
+     */
+    async notifyNodeIngest(userId: string): Promise<void> {
+      try {
+        await this.makeRequest<{ accepted: boolean }>(
+          'POST',
+          `/nodes/ingest/notify/${encodeURIComponent(userId)}`,
+          undefined,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Sweep the GET caches a node mutation invalidates: every node read
+     * (`GET:/nodes/`) so a re-read reflects the new node / its absence, and
+     * `/users/me` because the user's derived DID document embeds an `#oxy-node`
+     * service entry that changes on register / revoke / manage. Public rather
+     * than `private` because mixins compose into an exported anonymous class
+     * where TypeScript cannot represent a private member in the emitted
+     * declaration file (TS4094) — mirrors the civic / identity cache sweepers.
+     */
+    _sweepNodeCaches(): void {
+      this.clearCacheByPrefix(NODES_CACHE_PREFIX);
+      this.clearCacheByPrefix(USERS_ME_CACHE_PREFIX);
+    }
+  };
+}

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();
+    });
+  });
+});