PolicySessionResolver

Opens the policy-server session that ocean-node checks on a download or compute job. Nautilus holds one per instance, built from its credentials and sessionStore; use it directly only with the standalone access(config, context) / compute(config, context) functions (as context.policySessions).

Usage

const policySessions = new PolicySessionResolver({
  credentials: new WaltIdCredentialProvider(node, { walletApi: 'https://wallet.example.org' })
})
 
const session = await policySessions.resolve({ 
  node, // the node that checks the policy
  asset, 
  serviceId: 'a-service-id', 
  consumerAddress: '0x…' // signer.getAddress(), unchanged
}) 

What resolve does

1. Neither the asset nor the service has credentials ({} counts as having them): null.
2. A cached session for (node, asset, service, consumer), opened less than sessionTtlMs ago: that one. A session that needed a presentation is first checked again (checkSessionId), since the verifier forgets it when it expires or restarts. An entry that is too old, or that the check does not report verified, is deleted and the steps below run again.
3. The node is known to have no policy server (hasPolicyServer() is false: its status says isPSConfigured: false, or an earlier initiate showed it): null. When the status does not say, as on upstream ocean-node 4.2.0, step 5 tells.
4. The service asks for a verifiable presentation and no credential provider is set: throws, before anything is signed.
5. initiate, for node.policySessionAddress(consumerAddress): the address the node forwards to the policy server (for a Signer, consumerAddress itself; for a JWT, the address in the token). A node without a policy server answers with a 404 and no body: null; no session is cached, and hasPolicyServer() answers false for 10 minutes unless it knew the node to have one. Otherwise the policy server checks it and opens a session, or refuses (PolicyDeniedError). The session id is message.sessionId; the openid4vp request is message.redirectUri.
6. Only when the SSIpolicy asks for credentials: the provider's present(), then checkSessionId, which must report verificationResult: true (else PolicyDeniedError). When present() throws because the verifier refused the presentation (a CredentialPresentationError with reason: 'verifier-rejected', or any other error, from a custom provider), checkSessionId is read too, best effort and cut after 15 seconds: if the verifier's record names failed policies, a PolicyDeniedError with them, the provider's error as its cause; otherwise the provider's error, unchanged. A CredentialPresentationError for a step before the verifier is thrown as it is, without the read. Either way nothing is cached.
7. The session is cached and returned as the payload for the node's policyServer slot: a presented session in memory only, unless persistPresentedSessions.

Options

Methods

resolve(request) · setCredentialProvider(credentials | undefined) · clearSessions()

Errors

policyResults come through the node (for a download, the publisher's choice of node), so each name and error is cut at 100 characters and stripped of control characters, and at most 50 are kept, failures first. reason lists what fits of the failed policies within its 200 characters and counts the rest (; 2 more in policyResults). A policy's error can quote a value of the presented credential: don't send them to a central log. No error carries the session id; NAUTILUS_DEBUG=sensitive with the policy topic shows the verifier's whole record (debugging).

See credential-gated assets.