pancloud-nodejs Administrator & Developer Guide

This guide covers the operational, architectural, and contributor-facing surface of pancloud-nodejs — the Palo Alto Networks Application Framework SDK for Node.js. The User Guide handles getting code talking to the SDK; this document handles deciding whether to ship it, hardening it, running it in production, and extending it.

The audience is the architect choosing an SDK, the platform engineer deploying a service that uses it, the security engineer reviewing the OAuth2 flow, or the contributor opening a pull request against the lib/ tree. Cross-references to specific lines in lib/*.ts are anchored to source commit e0d9e6b.

1. Architecture Overview

pancloud-nodejs is an HTTPS client library. There is no daemon, no sidecar, no background service. Every API call is initiated by your application code; the SDK adds OAuth2 token management, retries, JSON schema validation, and (optionally) a Node Readable stream wrapper.

Data flow

+----------------------+     +----------------------+     +-----------------------------+
|  Your Node.js app    |     |  pancloud-nodejs SDK |     |  Cortex / PAN identity      |
|                      |     |                      |     |                             |
|  - business logic    |     |  Credentials object  |     |  api.paloaltonetworks.com   |
|  - calls SDK methods +---->+  CoreClass.fetchX*   +---->+    /api/oauth2/RequestToken |
|  - consumes results  |     |  retrier (3 / 100ms) |     |    /api/oauth2/RevokeToken  |
|                      |     |  fetch() (Node https)|     |                             |
|                      |     |                      |     |  api.us.paloaltonetworks.com|
|                      |     |  LoggingService      +---->+    logging-service/v1/*     |
|                      |     |  EventService        |     |                             |
|                      |     |  DirectorySyncService|     |  api.eu.paloaltonetworks.com|
|                      |     |                      |     |    event-service/v1/*       |
|                      |     |  Optional:           |     |    directory-sync-service/v1|
|                      |     |  CortexHubHelper     |     |                             |
|                      |     |  L2 correlator       |     |                             |
+----------------------+     +----------------------+     +-----------------------------+

Note

Every outbound request is HTTPS. There is no plaintext fallback, no opt-out for TLS verification, and no proxy configuration in the SDK itself — proxies must be set at the Node runtime level (e.g. via HTTPS_PROXY and an agent), because lib/fetch.ts calls https.request directly without honoring the standard proxy env vars.

Component inventory

Note

lib/exceptions.ts defines a separate, unrelated PanCloudError class that is imported by lib/directorysyncservice.ts (line 1350) — a minor inconsistency with the main error in lib/error.ts. See Section 8 for details.

Class hierarchy at a glance

CoreClass (lib/core.ts)
├── Emitter (lib/emitter.ts)
│   ├── EventService (lib/eventservice.ts)  implements Iterable<Promise<EsEvent[]>>
│   └── LoggingService (lib/loggingservice.ts)
└── DirectorySyncService (lib/directorysyncservice.ts)

Credentials (abstract, lib/credentials.ts)
├── StaticCredentials (no refresh)
├── DevTokenCredentials (apiexplorer.rocks flow)
└── DefaultCredentials (created by CortexCredentialProvider subclasses)

CortexCredentialProvider<T, K> (abstract, lib/credentialprovider.ts)
├── DefaultCredentialsProvider (in-memory)
└── FsCredProvider<T, K> (encrypted JSON file)

CortexHubHelper<T, U, K, M> (abstract, lib/hubhelper.ts)
└── (implementer's storage subclass)

stream.Readable
└── LoggingServiceClient (lib/loggingserviceclient.ts)

Error (built-in)
└── SdkErr (lib/error.ts)
    ├── PanCloudError
    └── ApplicationFrameworkError

Technology stack

Note

The SDK's package.json has empty dependencies and empty devDependencies blocks. Every external API the SDK calls is satisfied by the Node standard library; the tsc toolchain is expected to be installed in your environment, not pulled in as a dev dependency.

Internal data flow: a Logging Service query

app                   LoggingService            CoreClass             Credentials      Cortex API
 |                         |                         |                     |               |
 | factory(cred)           |                         |                     |               |
 |------------------------>|                         |                     |               |
 | query(cfg)              |                         |                     |               |
 |------------------------>|                         |                     |               |
 |                         | fetchPostWrap('/queries', body)               |               |
 |                         |------------------------>|                     |               |
 |                         |                         | checkAutoRefresh()  |               |
 |                         |                         |-------------------->|               |
 |                         |                         |   (refresh if <5min)|               |
 |                         |                         |                     |               |
 |                         |                         | retrier(fetch)      |               |
 |                         |                         |---------------------+-------------->|
 |                         |                         |   POST /queries     |   200 + JSON  |
 |                         |                         |<--------------------+---------------|
 |                         |  isJobResult(rJson)?    |                                     |
 |                         |  jobQueue[queryId]={..} |                                     |
 |                         |  schedule autoPoll      |                                     |
 |  jobPromise             |                                                               |
 |<------------------------|                                                               |
 |                         |  ... auto-poll loop ...                                       |
 |                         |  emitMessage -> user callBack.event                           |
 |                         |  resolve(jobPromise) on JOB_FINISHED                          |
 | (resolved)              |                                                               |
 |<------------------------|                                                               |

2. System Requirements

Runtime

Build-time

Network endpoints

The SDK speaks to two classes of endpoints:

Important

Egress firewalls must allow all four *.paloaltonetworks.com hosts plus app.apiexplorer.rocks (only if you use DevTokenCredentials). The SDK does not honor HTTP_PROXY / HTTPS_PROXY env vars at the library level; if your environment requires a proxy, configure it via https.globalAgent or by overriding the fetch() export.

3. Configuration Reference

This section catalogues every constructor option, factory parameter, and environment variable the SDK reads.

3.1 Environment variables

The envPrefix option lets two providers in the same process read from different env vars (e.g. PROD_CLIENT_ID, STAGING_CLIENT_ID).

3.2 CredentialProviderOptions (memory and filesystem providers)

Defined in lib/credentialprovider.ts:608:

fsCredentialsFactory adds secret: string (mandatory; AES-128 key material) plus envPrefix?: string.

3.3 CoreOptions and EmitterOptions

CoreOptions (lib/core.ts:352) — shared by every service factory:

EmitterOptions (lib/emitter.ts:1867) extends CoreOptions with:

3.4 LsOptions (LoggingService)

3.5 EsOptions (EventService)

3.6 LsQueryCfg (a single Logging Service query)

3.7 EsFilterBuilderCfg (Event Service filter)

3.8 The Credentials constructor

constructor(entryPoint: EntryPoint, guardTime?: number)

3.9 The LoggingServiceClient constructor

new LoggingServiceClient(ls, cfg & { retries?: number, delay?: number }, opts?)

Important

cfg.callBack is silently deleted by the constructor — the streaming wrapper drives polling itself. Do not pass a callback through this path; it is dead code from the consumer's perspective.

4. Deployment & Scaling

Single-process deployment

The default shape: one Node process, one Credentials object, one or more service-client instances. This works up to whatever rate a single event loop can sustain — typically thousands of records per second for the streaming LoggingServiceClient, limited by network round-trip to the regional API.

Deployment surface:

• One process, one Credentials instance per data lake.
• Reuse the Credentials across LoggingService, EventService, DirectorySyncService instances; refreshes are deduped via validUntil.
• Use LoggingServiceClient rather than the raw query API for sustained reads; it backpressures naturally through the Node stream protocol.

Tip

Run with NODE_OPTIONS="--max-old-space-size=512" (or higher) if you turn on the L2 correlation engine with a long timeWindow — the correlator buffer can grow to thousands of entries before the GC fires.

Multi-process scaling

Because each EventService instance binds to a server-side channel, horizontal scale-out is constrained: two processes against the same channel ID compete for events. Two patterns work:

1. Sharded channel IDs: pass channelId: 'shard-A', shard-B, ... to each instance and configure the upstream filter list per shard.
2. One process owns the channel: a single consumer reads events and re-publishes them to a queue (Redis Streams, NATS, Kafka). Workers pick from the queue.

Logging Service queries are stateless from the SDK side — a second process can issue a parallel query without disturbing the first. The server-side limit is the per-tenant concurrent query quota imposed by PAN.

Multi-tenant / multi-datalake deployment

When one process serves many Cortex Data Lake tenants, use fsCredentialsFactory() (or a custom CortexCredentialProvider subclass) and call registerManualDatalake() once per tenant. Each tenant gets its own Credentials object, its own refresh schedule, and its own row in the encrypted PANCLOUD_CONFIG.json.

The CortexHubHelper abstract class is the recommended path for production multi-tenant apps because it covers:

• Authorization-code exchange via the user's browser.
• Tenant-id validation against req.user[tenantKey] in an Express-like request.
• Storage of pending authorization states.
• Datalake metadata (a free-form T parameter) attached to each registered datalake.

You implement six abstract methods (_listDatalake, _getDatalake, _upsertDatalake, _deleteDatalake, requestAuthState, restoreAuthState, deleteAuthState) against your storage of choice (Postgres, DynamoDB, etc.).

Warning

The forceCallbackTenantValidation option in CortexHelperOptions defaults to false. In a multi-tenant deployment, set it to true and ensure your auth middleware populates req.user[tenantKey] so the callback handler can verify the requester actually owns the datalake they are activating.

Container deployment notes

A minimal Dockerfile for a service that uses this SDK:

FROM node:18-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY dist/ ./dist/
USER node
ENV NODE_ENV=production
CMD ["node", "dist/index.js"]

Inject secrets via env vars at runtime:

docker run --rm \
  -e PAN_CLIENT_ID=... \
  -e PAN_CLIENT_SECRET=... \
  -e PAN_REFRESH_TOKEN=... \
  -e PAN_ENTRYPOINT=https://api.us.paloaltonetworks.com \
  my-pancloud-app:latest

For Kubernetes, mount these from a Secret, not a ConfigMap:

envFrom:
  - secretRef:
      name: pancloud-credentials

5. Operations

Monitoring

Every service client exposes a stats getter. Scrape these on a timer:

Tie each to a Prometheus gauge or your APM of choice. Alert thresholds that have proven useful:

• nacks > 0 over 5 minutes → consumer is rejecting events; investigate.
• queries > 0 but records = 0 over an hour → upstream data flow has stopped; check the firewall side.
• apiTransactions grows but polls stays flat → process is paused or blocked.

Tip

The L2 correlator emits its own stats inside EmitterStats.correlationStats (agedOut, dbWaterMark, dbInserts, discardedEvents). A growing dbWaterMark paired with agedOut > 0 suggests the time window is too short for the actual flow lifetimes.

Logging

The SDK uses a single commonLogger exported from lib/common.ts. By default it writes JSON-ish lines prefixed with PANCLOUD: to stdout (level INFO/ALERT) and stderr (level ERROR). To pipe into a structured logger:

import { setLogger, LogLevel } from 'pancloud-nodejs'
import pino from 'pino'

const log = pino()
setLogger({
    level: LogLevel.INFO,
    error: e =>  log.error({ src: e.getSourceClass(), code: e.getErrorCode() }, e.getErrorMessage()),
    alert: (s, m, n) => log.warn({ src: s.className, name: n }, m),
    info:  (s, m, n) => log.info({ src: s.className, name: n }, m),
    debug: (s, m, n, p) => log.debug({ src: s.className, name: n, payload: p }, m)
})

Note

The logger truncates the payload field to 300 characters before emitting. If you need full payload visibility for debugging, replace the logger and avoid the SdkLogger's truncation.

Health checks

There is no built-in /health endpoint — the SDK is a library, not a server. A working liveness check for a service that uses the SDK:

async function healthCheck(cred: Credentials): Promise<boolean> {
    try {
        await cred.autoRefresh()
        return true
    } catch {
        return false
    }
}

This exercises the OAuth2 refresh flow (it is a no-op if the token has plenty of life left) and forces a real IDP round-trip when the cached token is stale.

Tip

For a "deeper" check, run a one-record LoggingService query against a small known time window. If you do, set maxWaitTime: 5000 so the liveness probe times out fast.

Runbook: refresh token revoked

Symptoms: IDENTITY errors from idpRefresh, every service call fails with HTTP 400 from /api/oauth2/RequestToken.

Recovery:

1. Confirm with setLogLevel(LogLevel.DEBUG) that the failure is IDP-side (source: "CortexCredentialProvider").
2. Re-issue a refresh token from the Cortex hub for the affected client_id.
3. Update the running env var (or the PANCLOUD_CONFIG.json for FS-based deployments).
4. Restart the process.

Prevention: rotate refresh tokens deliberately. The SDK auto-stores new refresh tokens that come back in the IDP response (see CortexCredentialProvider.retrieveCortexAccessToken, line ~887), so graceful PAN-side rotations should propagate without operator action.

Runbook: Event Service backlog

Symptoms: polls keeps climbing but records per minute is dropping; PAN-side backlog warning.

Recovery:

1. await es.flush() to drop everything currently buffered (data loss is acceptable if you can re-query).
2. Or, increase batchSize on each filter entry to receive more events per poll round-trip.
3. Or, shard: split the filter list across multiple EventService instances on different channelId values.

Runbook: stuck LoggingServiceClient

Symptoms: Stream never ends, no data events, no error.

Recovery:

1. Check setLogLevel(LogLevel.DEBUG) output for repeated RUNNING responses.
2. If the query has been running > 60 s and the SDK has hit its retries ceiling, the stream emits an error; if not, raise retries and delay in the constructor.
3. Manually stream.destroy() to abort and trigger deleteQuery.

6. Performance

HTTP-level performance

Every service client routes calls through CoreClass.fetchXWrap, which:

1. Increments apiTransactions.
2. Calls checkAutoRefresh() (potentially adding one IDP round-trip if the token is stale).
3. Calls retrier(this, retrierCount, retrierDelay, fetch, url, init).
4. Parses the response as JSON and validates.

The retrier (lib/common.ts:276) catches every exception and retries — including HTTP 5xx responses, but only because the underlying fetch implementation throws on those. This means a single SDK call can take up to retrierCount * (request_time + retrierDelay) seconds in the worst case.

Tip

If your service must respond within strict deadlines (e.g. a webhook that needs to ack within 5 seconds), set retrierCount: 1 and fetchTimeout to a value comfortably under your deadline. The SDK will then surface failures immediately rather than retrying through the deadline.

Auto-poll cost

Both LoggingService and EventService schedule auto-poll iterations every autoPollSleep ms (default 200 ms). For a service that always has data, the SDK uses setImmediate instead of setTimeout to keep the loop tight (EventService.autoPoll, line ~2715). Idle channels fall back to the 200 ms interval.

Per-poll cost is one HTTPS request + one JSON parse + a type-guard walk over the response. On modern Node it is well under 1 ms of CPU plus the network round-trip.

Memory profile of the L2 correlator

The correlator stores one entry per uncorrelated event in db: DbItem[]. Each entry is roughly 200 B (a wrapper plus the underlying event reference). Worst-case buffer size is bounded by dbWaterMark × event size. Tune timeWindow down (e.g. to 60 s) when correlations are expected to occur quickly.

Streaming throughput

LoggingServiceClient is object-mode — each chunk is a JavaScript array, not bytes. The natural backpressure is the Node stream high-water mark on the consumer side; pause the source and the pusher function will stop calling process.nextTick.

For high-record-count queries, prefer LoggingServiceClient to the auto-poll callback pattern: the stream interface gives consumers explicit backpressure, while the callback pattern fires events as fast as the SDK polls them.

Note

The streaming wrapper has its own retry constants (RETRIES = 20, DELAY = 200) that are independent of the parent LoggingService's retrier. Increase these for queries that take longer than 4 s of wall-clock to start producing results.

7. Security

This section is a security review for the architect or AppSec engineer evaluating the SDK.

OAuth2 secret handling

The SDK accepts three categories of secrets:

Caution

Never log secrets. The SDK's debug logger truncates payloads to 300 chars to reduce accidental leakage, but this is not a substitute for reviewing your own code: the SDK's payload printer in commonLogger.debug will print the request body (which contains the refresh token) when it sends a refresh request. Set LogLevel.INFO or higher in production to avoid this.

Encryption at rest (FS provider)

fsCredentialsFactory encrypts the cached tokens in PANCLOUD_CONFIG.json with AES-128-CBC, using key material derived from the caller-provided secret (passIvGenerator in lib/fscredentialprovider.ts). Keep that secret in your secret manager, not next to the file, and restrict the file to the service account.

Tip

For production services that already run a KMS or vault (AWS KMS, GCP KMS, HashiCorp Vault), implement a CortexCredentialProvider subclass that stores credentials there: override loadCredentialsDb, createCredentialsItem, updateCredentialsItem and deleteCredentialsItem to talk to your secret store directly.

TLS verification

lib/fetch.ts calls Node's https.request with no overrides for rejectUnauthorized, no custom CA bundle, and no TLS pinning. The default Node behaviour applies: certificates are validated against the system root store. There is no way to disable verification through the SDK's public API.

If you need a custom CA (e.g. for a corporate MITM proxy), set NODE_EXTRA_CA_CERTS in the environment.

Caution

Do not patch tls.checkServerIdentity to bypass verification "for testing" in code that ships to production. The SDK speaks to public PAN endpoints with public CA-signed certs; there is no legitimate reason for the verification to fail.

Request payload review

The SDK sends these payloads. Audit them against your DLP / network review:

Logs of any of these payloads at debug level expose secrets. Production log policy: never enable LogLevel.DEBUG long-term.

Tenant isolation

CortexCredentialProvider is parameterised by a metadata type T and a tenant-key field K. When you implement a multi-tenant subclass:

• Always set tenantKey so that selectDatalakeByTenant() can filter.
• Validate the tenant ID before calling getCredentialsObject(). CortexHubHelper.getCredentialsObject does this:

  let activeList = await this.credProvider.selectDatalakeByTenant(tenantId as any)
  if (!activeList.includes(datalakeId)) {
      throw new PanCloudError(CortexHubHelper, 'CONFIG', `datalake ${datalakeId} not found`)
  }
  

• Set forceCallbackTenantValidation: true to require the requester's tenant ID to match the state-stored tenant ID during OAuth2 callback.

Warning

A subclass that returns a Credentials object without verifying the requesting tenant owns it has cross-tenant data leakage. Treat getCredentialsObject(datalakeId) as a privileged operation; never expose it to untrusted input.

Refresh-token rotation

PAN's IDP may return a new refresh_token in any refresh response. The SDK detects this:

if (idpResponse.refresh_token) {
    credentials.refreshToken = idpResponse.refresh_token
    commonLogger.info(CortexCredentialProvider, 'Received new Cortex Refresh Token')
}
await this.updateCredentialsItem(datalakeId, credentials)

It then calls the storage subclass's updateCredentialsItem. Make sure your subclass actually persists the new value — a no-op implementation will lose the new refresh token on the next process restart and you will be back to the revoked token.

Recommended cadence:

What NOT to log

• Raw access_token JWTs.
• Raw refresh_token strings.
• The client_secret.
• Customer log payloads — panw.threat, panw.dpi, etc. contain packet captures and URL data subject to your customer's privacy policy.
• Directory Sync entries — usernames, email addresses, group memberships.

Caution

The SDK's debug logger will happily print every HTTP body as it goes over the wire. In production, set LogLevel.INFO (the default) and never override the commonLogger.debug method to write to long-term log storage.

Sensitive-data sinks

8. Developer Internals

This section is for SDK contributors and integrators reading the source.

Repository layout

pancloud-nodejs/
├── lib/                          TypeScript source (canonical)
│   ├── index.ts                  Re-exports the public API
│   ├── core.ts                   CoreClass: HTTP wrappers + retry + refresh
│   ├── common.ts                 Logger, retrier, types, constants
│   ├── credentials.ts            Credentials abstract + Static
│   ├── credentialprovider.ts     CortexCredentialProvider abstract + Default
│   ├── fscredentialprovider.ts   FsCredProvider (encrypted JSON file)
│   ├── devtokencredentials.ts    DevTokenCredentials
│   ├── autocredentials.ts        autoCredentials() selector
│   ├── hubhelper.ts              CortexHubHelper (auth-code flow)
│   ├── loggingservice.ts         LoggingService + LsControlMessage
│   ├── loggingserviceclient.ts   LoggingServiceClient (Readable stream)
│   ├── eventservice.ts           EventService (Iterable + auto-poll)
│   ├── directorysyncservice.ts   DirectorySyncService
│   ├── emitter.ts                Emitter base class (3 topics)
│   ├── l2correlator.ts           MacCorrelator (in-memory L2/L3 join)
│   ├── error.ts                  SdkErr + PanCloudError + ApplicationFrameworkError
│   ├── exceptions.ts             A second, unrelated PanCloudError class (legacy)
│   ├── fetch.ts                  https.request wrapper -> FetchResponse
│   └── util.ts                   Util.dnsDecode + Util.pcaptize
├── test/                         Hand-written TypeScript scenarios (not unit tests)
│   ├── credential.ts, credential_basic.ts, credential_fs.ts
│   ├── eventservice*.ts          11 EventService scenarios
│   ├── loggingservice*.ts        6 LoggingService scenarios
│   ├── dss*.ts                   8 DirectorySync scenarios
│   ├── dnsdecode.ts, pcap.ts     Utility scenarios
│   └── tsconfig.json             Test build config
├── package.json                  name=pancloud, version=1.0.0
├── tsconfig.json                 Library build config
├── README.md
└── .gitignore

State machines

LoggingService query state machine

              query()                             poll() / autoPoll
   START -------------> [submitted]  <-----+--------+
                            |              |        |
                            |              |        |
              JOB_FAILED    |   FINISHED   |        |  RUNNING
                +-----------+--------------+--------+
                |                          |
                v                          v
            [failed]               sequenceNo++
                                          |
                                          | JOB_FINISHED
                                          v
                                     [finished] -- emitterCleanup -> resolve

Key invariants:

• pendingQueries = Object.keys(jobQueue) is rebuilt every transition.
• The auto-poll timer (tout) is scheduled iff pendingQueries.length > 0.
• cancelPoll(qid, err?) removes the entry, resolves or rejects the pending promise, and calls deleteQuery to release server resources.

EventService channel state machine

                  factory()
   START -------------------> [no filter]
                                  |
              filterBuilder() / setFilters()
                                  |
                                  v
                           [filter applied]
                            |       ^
                  poll()    |       | clearFilter()
                            v       |
                       [polling]   ...
                            |
                  filterOptions.callBack provided?
                       /            \
                     yes             no
                      |               |
                      v               v
                [auto-poll loop]  [manual poll only]
                      |
                pause() / resume()

• popts (poll options) is captured from filterOptions.poolOptions on every setFilters call; the auto-poll uses these on every iteration.
• pause() clears the timer and sets polling = false. The current in-flight poll() still resolves.
• resume() calls EventService.autoPoll(this) directly and starts a fresh loop.

Credentials refresh state machine

   getAccessToken()
        |
        v
   accessToken cached?  ---no--->  retrieveAccessToken()  --> stash {token, validUntil}
        |
        yes
        v
   autoRefresh()
        |
        v
   Date.now() + guardTime > validUntil ?  ---yes--->  retrieveAccessToken()
        |
        no
        v
   return cached

Module reference

lib/index.ts

The single export surface. If a name is not in this file, treat it as internal. The 19 public names:

defaultCredentialsFactory, Credentials, DevTokenCredentialsOptions,
DevTokenCredentials, autoCredentials, LoggingService, LsOptions,
LsQueryCfg, LsControlMessage, LoggingServiceClient, EventService,
EsOptions, EsFilterBuilderCfg, EsFilterCfg, DirectorySyncService,
DssOptions, DssQueryFilter, DssObjClass, EmitterInterface,
L2correlation, LogLevel, retrier, commonLogger, OAUTH2SCOPE, EntryPoint,
setLogLevel, setLogger, isSdkError, PanCloudError, Util,
CortexCredentialProvider, CredentialProviderOptions, CredentialsItem,
RefreshResult, defaultCredentialsProviderFactory, isCredentialItem,
CortexClientParams, CortexHelperOptions, CortexHubHelper,
HubIdpCallback, HubIdpStateData, isCortexClientParams,
fsCredentialsFactory

lib/core.ts

CoreClass is the foundation for every service client. Key fields:

Methods of interest:

• setFetchHeaders() rebuilds the Authorization header from cred.getAccessToken().
• checkAutoRefresh() calls cred.autoRefresh() and updates headers iff validUntil changed.
• fetchXWrap is the single internal call site for HTTP. Subclasses call fetchGetWrap, fetchPostWrap, fetchPutWrap, fetchDeleteWrap, or voidXOperation (when the response shape is not interesting).

lib/common.ts

Defines LogLevel, the EntryPoint literal type, and the LogType literal type. The set of LogType values is exhaustively listed in the private LTYPES map (lib/common.ts:110); isKnownLogType() is the type-guard.

The retrier function is the canonical retry primitive. Every service-class fetch is wrapped through it; the IDP refresh is wrapped through it; the developer-token consumption is wrapped through it.

lib/error.ts

The error type hierarchy. SdkErr extends the built-in Error and adds getErrorCode, getErrorMessage, getSourceClass. The two concrete subclasses:

• PanCloudError — SDK-internal failures. Code is one of PARSER, IDENTITY, CONFIG, UNKNOWN.
• ApplicationFrameworkError — non-2xx HTTP responses. The errorMessage and errorCode are pulled from the response JSON.

isSdkError(e) is the duck-typing check the test scripts use to decide between SDK errors and unrelated runtime errors.

lib/exceptions.ts

This file defines a separate, much simpler PanCloudError class with a single message field. It is imported only by lib/directorysyncservice.ts (line 1350: import { PanCloudError } from "./exceptions"). The result is that DSS errors raise instances that do not satisfy the isSdkError predicate. This is a known wart — see the Improvements section.

Code patterns

Type guards for every response

The SDK never trusts a response's shape. Every service handler calls a hand-written type guard before exposing the result. Examples:

• isJobResult(rJson) (lib/loggingservice.ts:3982) — 20+ checks.
• isEsFilter(obj) (lib/eventservice.ts:2308) — recursive validation.
• isDssDomain(obj) (lib/directorysyncservice.ts:1387) — six fields.
• isApexResponse(obj) (lib/devtokencredentials.ts:1255) — two fields.

A response that fails a type guard raises PanCloudError(PARSER, ...) with the original JSON included in the message. This is the SDK's defence against API-side schema changes.

Factory methods, private constructors

Every service client has a private constructor and a static factory method. This forces consumers through the documented entry point and gives the SDK a place to apply future construction-time logic (e.g. async initialization).

CoreOptions propagation

A pattern used consistently: subclasses extend CoreOptions and pass the same options object to super(...), then read their own extensions. Example: EsOptions extends EmitterOptions extends CoreOptions.

The "Emitter" pattern

Emitter (lib/emitter.ts) uses Node's EventEmitter to dispatch on three private topic strings: EVENT_EVENT, PCAP_EVENT, CORR_EVENT. Subclasses (LoggingService, EventService) call emitMessage(e) once per batch; emitMessage runs the L2 correlator (if enabled) and emits to whichever topics have listeners.

Listeners are registered via registerEventListener, registerPcapListener, registerCorrListener. Each returns true if newly registered, false if the same function was already a listener and allowDup is false.

Testing strategy

The repository's test/ directory contains 24 hand-written .ts scenarios, each runnable via the corresponding .js entry point after npm run build:test. They are not unit tests in the Jest/Mocha sense — they are smoke tests that exercise a real Cortex Data Lake using credentials from environment variables. Examples:

• test/loggingservice_basic.ts — synchronous query, decode results.
• test/loggingservice_async_poll.ts — auto-poll callback pattern.
• test/eventservice_correlation.ts — full L2/L3 correlation pipeline.
• test/dss_query_users.ts — DirectorySyncService user query with filter and pagination.

Each test prints to stdout. CI integration is left to the consumer.

Note

A repository-level CI configuration (GitHub Actions, Travis, CircleCI) is not present at commit e0d9e6b.

Improvements / known issues

Contributing

The repository is licensed Apache-2.0 (the per-file headers say so; package.json says ISC — track issue #30 for discrepancies).

Contribution surface area:

1. Open a PR against master of PaloAltoNetworks/pancloud-nodejs.
2. The diff should keep tsc -p tsconfig.json clean (no new warnings).
3. Include a test/<scenario>.ts for any new behaviour, runnable against a real Cortex tenant.
4. Update lib/index.ts if your change adds a public symbol.
5. Update the per-file copyright header to include the current year.

Tip

When you add a new HTTP-calling method, route it through CoreClass.fetchXWrap (or one of its fetchGetWrap/fetchPostWrap wrappers). Calling fetch() directly bypasses both the auto-refresh and the retry logic.

9. Integration Points

Express / Fastify integration (Cortex Hub callback)

CortexHubHelper.authCallbackHandler is shaped like an Express middleware:

app.get('/oauth2/callback', async (req, res, next) => {
    await hubHelper.authCallbackHandler(req as any, res, next)
    if (req.callbackIdp?.error) {
        res.status(400).send(req.callbackIdp.error)
        return
    }
    res.json({ datalakeId: req.callbackIdp?.datalakeId })
})

The handler reads req.query.code and req.query.state, restores the authorization state, exchanges the code for tokens, and stores the result. It populates req.callbackIdp with {error?, message?, datalakeId?}.

Note

The handler calls next() itself. Do not call next() again from outside or you will trigger the next middleware twice. Pass () => {} as the next argument if you have already taken responsibility for the response.

Node Stream ecosystem

LoggingServiceClient is a Readable in object mode. It composes with any object-mode transform or sink:

import { Transform } from 'stream'

const filter = new Transform({
    objectMode: true,
    transform(chunk: any[], _, cb) {
        cb(null, chunk.filter(r => r.severity === 'critical'))
    }
})

stream.pipe(filter).on('data', recs => console.log(recs.length))

Logging frameworks

The commonLogger interface is intentionally minimal so any logger fits. Worked examples for the three most common frameworks:

winston

import winston from 'winston'
import { setLogger, LogLevel } from 'pancloud-nodejs'
const logger = winston.createLogger({ /* ... */ })
setLogger({
    level: LogLevel.INFO,
    error: e => logger.error(e.getErrorMessage(), { code: e.getErrorCode(), src: e.getSourceClass() }),
    alert: (s, m, n) => logger.warn(m, { src: s.className, name: n }),
    info:  (s, m, n) => logger.info(m, { src: s.className, name: n }),
    debug: (s, m, n, p) => logger.debug(m, { src: s.className, name: n, payload: p })
})

pino

See Section 5 (Operations) for the full pino example.

bunyan

Adapt the same shape — pass {src: s.className} as the second arg, the message as the first.

Metrics frameworks

Periodically harvest the per-instance stats:

import { Counter } from 'prom-client'

const apiTransactions = new Counter({
    name: 'pancloud_api_transactions_total',
    help: 'Total API transactions performed by the SDK',
    labelNames: ['service']
})

setInterval(() => {
    apiTransactions.labels('logging').inc(ls.getLsStats().apiTransactions)
    apiTransactions.labels('event').inc(es.getEsStats().apiTransactions)
    apiTransactions.labels('directory').inc(dss.getDssStats().apiTransactions)
}, 30_000)

Warning

The stats counters are running totals on the SDK side, not deltas. If you inc() directly with the value, you double-count. Either compute deltas yourself or use a Prometheus Gauge and call set().

Custom credentials sources

To integrate with a non-PAN identity provider that fronts Cortex (for example, an internal STS that issues short-lived Cortex access tokens), subclass Credentials:

import { Credentials, EntryPoint, expTokenExtractor } from 'pancloud-nodejs'

class MySTSCredentials extends Credentials {
    constructor(entryPoint: EntryPoint, private sts: MySTSClient) {
        super(entryPoint)
        this.className = 'MySTSCredentials'
    }
    async retrieveAccessToken(): Promise<void> {
        const token = await this.sts.exchangeForCortexToken()
        this.setAccessToken(token, expTokenExtractor(this, token))
    }
}

Pass an instance to any service factory.

KMS-backed credential storage

To store refresh tokens in a KMS-encrypted backing store, subclass CortexCredentialProvider and implement the abstract methods:

class KmsCredProvider extends CortexCredentialProvider<MyMeta, 'tenantId'> {
    async createCredentialsItem(dlid, item, meta) {
        const ciphertext = await kms.encrypt(JSON.stringify(item.refreshToken))
        await db.put({ dlid, ciphertext, ...meta })
    }
    async loadCredentialsDb() { /* fetch from db, decrypt */ }
    async updateCredentialsItem(dlid, item) { /* re-encrypt and store */ }
    async deleteCredentialsItem(dlid) { /* delete from db */ }
    async selectDatalakeByTenant(tenantId) { /* query by tenant index */ }
    protected credentialsObjectFactory(dlid, ep, gt, prefetch) {
        return this.defaultCredentialsObjectFactory(dlid, ep, gt, prefetch)
    }
}

This is the recommended path for production multi-tenant deployments; the shipped FsCredProvider is a development convenience.

Webhook-style integrations

For "push log records into the Logging Service" pipelines, use LoggingService.write(vendorName, logType, data[]). The vendor name and log type must be pre-registered with PAN; the data array must match the registered schema:

const result = await ls.write('AcmeCorp', 'panw.system', [
    { uuid: '...', timestamp: '...', source: '...', severity: 'info', message: '...' }
])
console.log(`accepted ${result.uuids.length} records`)

The response carries the assigned UUIDs; persist them for end-to-end trace correlation.

Migrating from raw HTTPS calls

Code that already speaks to the Cortex API directly via fetch() or axios can migrate incrementally:

1. Replace your token-refresh logic with autoCredentials() or defaultCredentialsProviderFactory(). Pass the resulting Credentials to a single LoggingService instance.
2. Replace your manual https.request to /queries with ls.query(cfg).
3. For long-running streams, replace your hand-rolled poll loop with LoggingServiceClient (which gives you backpressure for free).
4. Keep your monitoring in place — the SDK's stats getters expose the same counters you were probably already tracking.

Note

The SDK does not own retries or backoff above the request-level retrier. Long-term failures (e.g. PAN region down) bubble up as exceptions; your application is responsible for circuit-breaker behaviour, dead-letter queues, and operator-facing alerts.