Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,7 @@ jobs:
persist-credentials: false
repository: 'oceanprotocol/ocean.js'
path: 'ocean.js'
ref: 'feature/peerId_in_all_signatures'
- name: Build ocean-js
working-directory: ${{ github.workspace }}/ocean.js
run: |
Expand Down
5 changes: 1 addition & 4 deletions .github/workflows/docker.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,7 @@ on:
pull_request:
branches:
- 'main'
- 'next-4'
- 'deps/node_v24'
- 'feature/user_input_subsidy'
- 'feature/subsidy_provider'
- 'rc_*'

env:
DOCKERHUB_IMAGE: ${{ 'oceanprotocol/ocean-node' }}
Expand Down
63 changes: 53 additions & 10 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,45 @@ change closes. Client libraries that construct the `decryptDDO` message themselv

---

## Release note — universal peerId-bound signing (BREAKING, since Ocean Node v5.1.0)

Previously only `decryptDDO` (ON-02, above) bound its signature to the destination node's peerId.
As of **v5.1.0** **every** signature-authenticated command — ordinary (user) commands **and** admin
commands — binds the signed message to the **destination (verifier) node's own peerId**. This closes
signature replay across nodes for all commands: a signature minted for node A is rejected by node B.

For every signed command **except `decryptDDO`** (which additionally binds its resource fields — see
the `POST /api/services/decrypt` and P2P `decryptDDO` sections), the signed message is the
concatenation:

```
consumerAddress + nonce + command + issuerPeerId
```

- `consumerAddress` — the caller's EVM address (the same value sent as `consumerAddress` / `address`),
in the casing you actually signed (see **Address casing**).
- `nonce` — the per-caller monotonic nonce, as a string.
- `command` — the **exact** command string the request carries, same casing as sent (e.g. `encrypt`,
`download`, `startCompute`, `persistentStorageCreateBucket`, `serviceStart`, `serviceExtend`,
`setMaintenance`).
- `issuerPeerId` — the **target node's own peerId**. Discover it once per node from the `id` field of
that node's `status` response (`POST /directCommand` with `{"command":"status"}`) or the `nodeId`
returned by its root `GET /`, then bind the same value into every signed request to that node.

This applies to all signature-authenticated families, including **persistent storage**
(`persistentStorageCreateBucket`, `persistentStorageUploadFile`, `persistentStorageDeleteFile`, …),
**services** (`serviceStart`, `serviceExtend`, `serviceStop`, …), compute (`startCompute` /
`freeStartCompute`), `encrypt` / `encryptFile`, `download`, `validateDDO`, and the admin commands.

**Breaking change.** This is a coordinated signer/verifier change with **no empty-peerId fallback**: a
request whose signed message omits `issuerPeerId` (the pre-v5.1.0 `consumerAddress + nonce + command`
format) is rejected with a `consumer address and nonce signature mismatch` error. Client libraries
that build the signed message themselves must adopt the new format and upgrade in lockstep with the
node. `ocean.js` resolves the peerId automatically (from the node `status`) before signing, so callers
using it need no change.

---

## Address casing

Every EVM address you send (`consumerAddress`, `owner`, `address`, `decrypterAddress`,
Expand Down Expand Up @@ -1416,10 +1455,13 @@ asset/service and consumer. This endpoint requires an `Authorization` header or
`nonce` + `signature` pair.

This is a distinct command from `PolicyServerPassthrough`, so the signed message uses its
own command string: `consumerAddress + nonce + "PolicyServerInitialize"`.
own command string and is bound to the node's peerId (see the universal signing release note
above): `consumerAddress + nonce + "PolicyServerInitialize" + issuerPeerId`.

The verified `consumerAddress` is the one forwarded to the PolicyServer; the caller's
`authorization`, `nonce` and `signature` are added to the `policyServer` object.
`authorization`, `nonce` and `signature` are added to the `policyServer` object, together with
this node's `issuerPeerId`, so a PolicyServer that re-verifies the forwarded signature can rebuild
the peer-bound message. (ocean-node has already verified the signature locally.)

#### Parameters

Expand Down Expand Up @@ -2389,7 +2431,7 @@ List buckets for a given `owner`. Results are filtered by bucket access lists fo
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message (consumerAddress + nonce + command) |
| signature | string | v | signed message (consumerAddress + nonce + command + issuerPeerId) |
| nonce | string | v | request nonce |
| chainId | number | v | chain id (used by auth/signature checks) |
| owner | string | v | bucket owner to filter by |
Expand Down Expand Up @@ -2420,7 +2462,7 @@ List files in a bucket.
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message (consumerAddress + nonce + command) |
| signature | string | v | signed message (consumerAddress + nonce + command + issuerPeerId) |
| nonce | string | v | request nonce |

#### Response (200)
Expand Down Expand Up @@ -2449,7 +2491,7 @@ Return the `fileObject` for a specific file in a bucket (useful for passing refe
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message (consumerAddress + nonce + command) |
| signature | string | v | signed message (consumerAddress + nonce + command + issuerPeerId) |
| nonce | string | v | request nonce |

#### Response (200)
Expand Down Expand Up @@ -2478,7 +2520,7 @@ identically.
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message (consumerAddress + nonce + command) |
| signature | string | v | signed message (consumerAddress + nonce + command + issuerPeerId) |
| nonce | string | v | request nonce |

#### Response (200)
Expand Down Expand Up @@ -2509,7 +2551,7 @@ Upload a file to a bucket. The request body is treated as raw bytes.
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message (consumerAddress + nonce + command) |
| signature | string | v | signed message (consumerAddress + nonce + command + issuerPeerId) |
| nonce | string | v | request nonce |

#### Request Body
Expand Down Expand Up @@ -2540,7 +2582,7 @@ Delete a file from a bucket.
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message (consumerAddress + nonce + command) |
| signature | string | v | signed message (consumerAddress + nonce + command + issuerPeerId) |
| nonce | string | v | request nonce |
| chainId | number | v | chain id (used by auth/signature checks) |

Expand All @@ -2562,8 +2604,9 @@ it expires, is stopped, or is extended. See [`services.md`](./services.md) for t
and security model.

All routes live under `/api/services`. Every command except `serviceTemplates` is
authenticated by a signature over `consumerAddress` + `nonce` + `command` (or an auth-token
`Authorization` header). Cost is computed only from the environment's server-side pricing and
authenticated by a signature over `consumerAddress` + `nonce` + `command` + `issuerPeerId` (the
target node's peerId — see the universal signing release note above) or an auth-token
`Authorization` header. Cost is computed only from the environment's server-side pricing and
charged to the authenticated `consumerAddress`.

> **Note:** service containers run hardened (`no-new-privileges`, `CapDrop: ['ALL']`), so a
Expand Down
6 changes: 5 additions & 1 deletion src/components/core/handler/policyServer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,11 @@ export class PolicyServerInitializeHandler extends CommandHandler {
...task.policyServer,
authorization: task.authorization,
nonce: task.nonce,
signature: task.signature
signature: task.signature,
// The request signature is bound to this node's peerId (anti-replay), so a policy
// server that re-verifies the forwarded signature needs the same peerId to rebuild
// the signed message. ocean-node has already verified it locally regardless.
issuerPeerId: this.getOceanNode().getKeyManager().getPeerIdString()
}
)
if (!policyStatus.success) {
Expand Down
11 changes: 4 additions & 7 deletions src/components/core/utils/nonceHandler.ts
Original file line number Diff line number Diff line change
Expand Up @@ -182,13 +182,10 @@ async function validateNonceAndSignature(
error: 'nonce: ' + nonce + ' is not a valid nonce'
}
}
// ON-02: DECRYPT_DDO binds the signed message to THIS (verifier) node's peerId, exactly as
// CREATE_AUTH_TOKEN does, so a signature harvested from one node cannot be replayed at another.
const issuerPeerId =
command === PROTOCOL_COMMANDS.CREATE_AUTH_TOKEN ||
command === PROTOCOL_COMMANDS.DECRYPT_DDO
? OceanNode.getInstance().getKeyManager().getPeerIdString()
: ''
// Every signed command binds the signed message to THIS (verifier) node's peerId, so a
// signature harvested from (or sent to) one node cannot be replayed against another node.
// (DECRYPT_DDO additionally binds resource fields via its dedicated builder, below.)
const issuerPeerId = OceanNode.getInstance().getKeyManager().getPeerIdString()
if (
await verifyConsumerSignature(
consumer,
Expand Down
3 changes: 2 additions & 1 deletion src/test/integration/algorithmsAccess.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -448,7 +448,8 @@ describe('********** Trusted algorithms Flow', () => {
const messageHashBytes = createHashForSignature(
await consumerAccount.getAddress(),
nonce,
PROTOCOL_COMMANDS.COMPUTE_START
PROTOCOL_COMMANDS.COMPUTE_START,
oceanNode.getKeyManager().getPeerIdString()
)
const signature = await safeSign(consumerAccount, messageHashBytes)
const startComputeTask: PaidComputeStartCommand = {
Expand Down
4 changes: 3 additions & 1 deletion src/test/integration/auth.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,9 @@ describe('********** Auth Token Integration Tests', () => {
const invalidateHash = createHashForSignature(
consumerAddress,
newNonce,
PROTOCOL_COMMANDS.INVALIDATE_AUTH_TOKEN
PROTOCOL_COMMANDS.INVALIDATE_AUTH_TOKEN,
// every signed command binds the verifier node's peerId (anti-replay)
oceanNode.getKeyManager().getPeerIdString()
)
const invalidateSignature = await safeSign(consumerAccount, invalidateHash)

Expand Down
Loading
Loading