Skip to content

add admin commands - #2219

Draft
alexcos20 wants to merge 1 commit into
feature/peerId_in_all_signaturesfrom
feature/add_all_admin_commands
Draft

alexcos20 wants to merge 1 commit into
feature/peerId_in_all_signaturesfrom
feature/add_all_admin_commands

Conversation

@alexcos20

Copy link
Copy Markdown
Member

Node admin methods on ProviderInstance (every admin command over HTTP and P2P)

Summary

Adds first-class client methods for every Ocean Node admin-gated protocol command, over both
transports (HTTP and P2P), each taking a Signer (or, where the node allows it, an auth token) and
signing internally. Previously ocean.js fully covered only getLogs (list) and setMaintenance, and
half-covered fetchConfig / pushConfig (P2P-only, caller built and signed the payload).

Callers now get one method per admin action, with the transport chosen automatically by
ProviderInstance and the signature built internally — no hand-rolled signing, nonce handling, or
peerId resolution.

This branches off feature/peerId_in_all_signatures (PR #2217) and inherits its peerId-bound
signing, so every new admin signature binds the target node's peerId with no extra code.

New API (BaseProvider facade → HttpProvider + P2pProvider)

Method Node command Body params Returns Auth
stopNode(nodeUri, signer, signal?) STOP_NODE — Promise<void> signer only
adminStopJob(nodeUri, signer, jobId, signal?) STOP_JOB (new constant) jobId Promise<any> signer only
reindexTx(nodeUri, signer, chainId, txId, signal?) REINDEX_TX chainId, txId Promise<NodeAdminJobStatus> signer only
reindexChain(nodeUri, signer, chainId, block?, signal?) REINDEX_CHAIN chainId, block? Promise<NodeAdminJobStatus> signer only
handleIndexingThread(nodeUri, signer, action, chainId?, signal?) HANDLE_INDEXING_THREAD action, chainId? Promise<void> signer only
collectFees(nodeUri, signer, params, signal?) COLLECT_FEES chainId, tokenAddress, destinationAddress, tokenAmount? Promise<CollectFeesResult> signer only
getNodeLog(nodeUri, signerOrToken, logId, signal?) GET_LOGS logId Promise<NodeLogEntry> signer or token
getNodeConfig(nodeUri, signerOrToken, signal?) FETCH_CONFIG — Promise<Record<string, any>> signer or token
setNodeConfig(nodeUri, signer, config, signal?) PUSH_CONFIG config Promise<Record<string, any>> signer only
getNodeDetailedStatus(nodeUri, signal?) DETAILED_STATUS — Promise<NodeStatus> unsigned / public

The existing fetchConfig / pushConfig are kept and marked @deprecated in favour of
getNodeConfig / setNodeConfig.

Signing: inherited peerId binding (ocean-node #1619 / ocean.js #2217)

The admin methods reuse the single per-transport signing chokepoint, getSignedCommandParams, so the
signed message is address + nonce + command + issuerPeerId with the node's peerId resolved
automatically (HTTP from getNodeStatus(nodeUri).id; P2P from the peerId already in nodeUri). No
admin method builds a signature or the peerId binding by hand, and there is no empty-peerId fallback.

Auth tokens: read-only vs mutating split (ocean-node #1616)

The node now accepts scoped auth tokens only for the two read-only admin commands and keeps every
mutating admin command signature-only. The client enforces the same split up front:

  • Mutating (stopNode, adminStopJob, reindexTx, reindexChain, handleIndexingThread,
    collectFees, setNodeConfig): a string auth token is rejected client-side by
    assertAdminSigner before any network call (no nonce lookup, no STATUS round-trip, no POST).
  • Read-only (getNodeConfig → FETCH_CONFIG, getNodeLog → GET_LOGS): accept a signer or a
    JWT. A token is sent in the Authorization header (exactly as downloadNodeLogs does) and the
    token path skips peerId resolution and signing.

This is implemented with a private sendAdminCommand(…, allowAuthToken = false) helper in each
provider — allowAuthToken: true is passed only by getNodeConfig / getNodeLog.

Scoped-token minting (a scope/audience/validUntil on generateAuthToken) lands in ocean.js
PR #2214
(the companion to ocean-node #1616). This admin PR is intended to converge with #2214 and
#2217 on rc_11.0.0; see Reconciliation with #2214 below.

Types & constants (src/@types/Provider.ts)

  • PROTOCOL_COMMANDS.STOP_JOB = 'stopJob' added.
  • New exported types: IndexingThreadAction, NodeAdminJobStatus, CollectFeesParams,
    CollectFeesResult.
  • NodeStatus gains optional c2dClusters?, supportedSchemas?, authTokenPolicy?.

Behaviour details enforced by the node (documented in JSDoc)

  • Optional params are sent only when not undefined/null — block: 0, chainId: 0 and
    tokenAmount: 0 are meaningful and ARE sent (no truthiness tests). tokenAmount is sent verbatim
    (the node scales it).
  • Error parity is preserved: HTTP rejections surface as OceanNodeProviderError (with httpStatus),
    P2P rejections as the already-thrown P2pError — neither is converted to the other.
  • Dangerous-command consequences are called out in JSDoc: stopNode exits the node process;
    collectFees without tokenAmount sweeps the whole balance; setNodeConfig shallow-merges and can
    replace the keys block; over P2P a transport error after stopNode can mean the node already
    stopped.

Drive-by fix

HttpProvider.downloadNodeLogs built its query string by unescaped concatenation. It now uses
URLSearchParams (public parameter list and order unchanged), so moduleName / level are properly
encoded. Covered by a new unit case (moduleName: 'a b&c' → moduleName=a+b%26c).

Tests

  • Unit — test/unit/AdminCommands.test.ts (new, no infra): 89 passing. Table-driven over all
    methods on both transports. Asserts: the peerId-bound signed message
    (address + nonce + command + issuerPeerId, and that the old unbound message does not verify);
    no node field in the body; the optional-param rules (including 0); HTTP → OceanNodeProviderError
    and P2P → P2pError; the auth-token split (mutating methods reject a token with zero fetches;
    read-only methods accept it via the Authorization header with no signature); getNodeDetailedStatus
    unsigned; and transport dispatch for all ten methods.
  • test/unit/MaintenanceMode.test.ts: 24 passing, unchanged.
  • Integration — test/integration/Provider.test.ts (added describe): written but NOT run. They
    need ocean-node PRs Bump vm2 from 3.9.9 to 3.9.11 #1616 and Bump typescript from 4.7.4 to 4.8.4 #1619 merged plus Barge, so they are intentionally left to run once
    those land. They type-check (via tsc --noEmit in lint). The suite resolves an admin signer from the
    node's allowedAdmins (falling back to the well-known Barge admin key) and skips cleanly otherwise;
    it never calls stopNode or a blockless reindexChain (both would disrupt the shared node) — those
    stay unit-only.

Docs

README.md feature list and a new "Node administration" section in Cheatsheet.md. Generated files
(CHANGELOG.md, docs/, dist/lib.json) are untouched; the version is not bumped (release is the
maintainer's step — this is an additive, minor-bump change).

Reconciliation with #2214 (scoped auth tokens)

#2214 and #2217 are siblings off rc_11.0.0 and do not contain each other; they conflict on
generateAuthToken and NodeStatus. This admin work currently sits on #2217. Once #2214 and #2217
are merged together (so generateAuthToken carries both the peerId binding and the scoped-token
options + OJ-03), this branch rebases onto that combined base and adapts as follows:

  • Drop our duplicate additions now owned by Feat/scoped auth tokens #2214: PROTOCOL_COMMANDS.STOP_JOB and
    NodeStatus.authTokenPolicy (Feat/scoped auth tokens #2214 types the latter as AuthTokenPolicy, not any). Keep our
    c2dClusters / supportedSchemas.
  • Integration token test switches to Feat/scoped auth tokens #2214's signature:
    generateAuthToken(signer, url, { validUntil, scope }) (the old 2-arg call throws once Feat/scoped auth tokens #2214
    lands), and the it.skip('a token scoped to getLogs only is rejected by getNodeConfig') is
    un-skipped by minting a token scoped to getLogs only.
  • Optionally use Feat/scoped auth tokens #2214's CommandCatalog (adminReadonly / tokenAuth annotations) to drive the
    read-only vs mutating split instead of the hardcoded allowAuthToken flags — the catalog already
    marks fetchConfig / getLogs as adminReadonly + tokenAuth and the mutating admin commands as
    scope-disallowed.

The signature-building for the admin commands themselves is unaffected (they reuse
getSignedCommandParams, which both PRs leave as the chokepoint).

Rollout

Ship after (or together with) ocean-node #1619 (universal peerId-bound signing) and #1616
(scoped auth tokens + read-only-admin token opt-in). An upgraded client talking to an old node (or
vice versa) mismatches on the signed message; the read-only auth-token integration cases are gated on
the node advertising authTokenPolicy and skip against older nodes.

@coderabbitai

coderabbitai Bot commented Nov 22, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@alexcos20 alexcos20 added the Status: Blocked Blocked by dependency, platform requirement, etc (add comment to detail the reason) label Nov 22, 2026
@alexcos20 alexcos20 self-assigned this Nov 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Status: Blocked Blocked by dependency, platform requirement, etc (add comment to detail the reason)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant