@cdot65/prisma-airs-sdk 0.4.0 → 0.5.1

package/README.md

@@ -1,6 +1,6 @@
 # prisma-airs-sdk
 
-TypeScript SDK for Palo Alto Networks **AI Runtime Security (AIRS)**. API-compatible with the official [Python `pan-aisecurity` SDK](https://pypi.org/project/pan-aisecurity/).
+TypeScript SDK for Palo Alto Networks **Prisma AIRS** — covering the full lifecycle from configuration management to operational scanning across all three service domains: **AI Runtime Security**, **AI Red Teaming**, and **Model Security**.
 
 ## Installation
 
@@ -8,14 +8,26 @@ TypeScript SDK for Palo Alto Networks **AI Runtime Security (AIRS)**. API-compat
 npm install @cdot65/prisma-airs-sdk
 ```
 
-Requires Node.js 18+.
+Requires Node.js 18+. Zero external HTTP dependencies (native `fetch` + `crypto`).
+
+## What's Included
+
+| Service                 | Client                | Auth    | Capabilities                                               |
+| ----------------------- | --------------------- | ------- | ---------------------------------------------------------- |
+| **AI Runtime Security** | `Scanner`             | API Key | Sync/async content scanning, prompt injection detection    |
+| **Management**          | `ManagementClient`    | OAuth2  | Security profiles and custom topics CRUD                   |
+| **Model Security**      | `ModelSecurityClient` | OAuth2  | ML model scanning, security groups, rule management        |
+| **AI Red Teaming**      | `RedTeamClient`       | OAuth2  | Automated red team scans, reports, targets, custom attacks |
+
+All OAuth2 services share credentials and handle token lifecycle automatically (caching, proactive refresh, 401/403 auto-retry).
 
 ## Quick Start
 
+### AI Runtime Security — Content Scanning (API Key)
+
 ```ts
 import { init, Scanner, Content } from '@cdot65/prisma-airs-sdk';
 
-// Initialize (mirrors Python's aisecurity.init())
 init({ apiKey: 'YOUR_API_KEY' });
 
 const scanner = new Scanner();
@@ -30,90 +42,82 @@ console.log(result.category); // "benign" | "malicious"
 console.log(result.action); // "allow" | "block"
 ```
 
-## Initialization
+### Management — Configuration CRUD (OAuth2)
+
+CRUD operations for all three Prisma AIRS services use OAuth2:
 
 ```ts
-import { init } from '@cdot65/prisma-airs-sdk';
+import { ManagementClient } from '@cdot65/prisma-airs-sdk';
+
+const client = new ManagementClient(); // reads PANW_MGMT_* env vars
+
+// Security Profiles
+const profiles = await client.profiles.list();
+const created = await client.profiles.create({
+  profile_name: 'my-profile',
+  active: true,
+  policy: {
+    /* ... */
+  },
+});
 
-init({
-  apiKey: 'your-api-key', // or set PANW_AI_SEC_API_KEY env var
-  apiToken: 'your-bearer-token', // or set PANW_AI_SEC_API_TOKEN env var
-  apiEndpoint: 'https://...', // optional, defaults to production
-  numRetries: 3, // optional, 0-5, default 5
+// Custom Topics
+const topic = await client.topics.create({
+  topic_name: 'pii-detector',
+  examples: ['SSN: 123-45-6789'],
 });
 ```
 
-At least one of `apiKey` or `apiToken` must be provided (directly or via environment variables).
-
-## Scanner Methods
+### Model Security — ML Model Scanning (OAuth2)
 
-| Method                                | Description                                |
-| ------------------------------------- | ------------------------------------------ |
-| `syncScan(aiProfile, content, opts?)` | Synchronous inline scan                    |
-| `asyncScan(scanObjects)`              | Batch async scan (up to 5)                 |
-| `queryByScanIds(scanIds)`             | Get results by scan IDs (up to 5)          |
-| `queryByReportIds(reportIds)`         | Get threat reports by report IDs (up to 5) |
+```ts
+import { ModelSecurityClient } from '@cdot65/prisma-airs-sdk';
 
-### Sync Scan
+const client = new ModelSecurityClient(); // falls back to PANW_MGMT_* env vars
 
-```ts
-const result = await scanner.syncScan(
-  { profile_name: 'my-profile' },
-  new Content({ prompt: 'user input', response: 'model output' }),
-  {
-    trId: 'transaction-123',
-    sessionId: 'session-456',
-    metadata: { app_name: 'my-app', ai_model: 'gpt-4' },
-  },
-);
+const scans = await client.scans.list({ limit: 10 });
+const groups = await client.securityGroups.list();
+const rules = await client.securityRules.list();
 ```
 
-### Async Scan
+### AI Red Teaming — Automated Testing (OAuth2)
 
 ```ts
-const result = await scanner.asyncScan([
-  {
-    req_id: 1,
-    scan_req: {
-      ai_profile: { profile_name: 'my-profile' },
-      contents: [{ prompt: 'hello', response: 'world' }],
-    },
-  },
-]);
-```
+import { RedTeamClient } from '@cdot65/prisma-airs-sdk';
 
-### Query Results
+const client = new RedTeamClient(); // falls back to PANW_MGMT_* env vars
 
-```ts
-const results = await scanner.queryByScanIds(['scan-uuid-here']);
-const reports = await scanner.queryByReportIds(['report-id-here']);
+const scans = await client.scans.list({ limit: 5 });
+const targets = await client.targets.list();
+const categories = await client.scans.getCategories();
 ```
 
-## Content Class
-
-```ts
-import { Content } from '@cdot65/prisma-airs-sdk';
+## Authentication
 
-const content = new Content({
-  prompt: 'user prompt',
-  response: 'model response',
-  context: 'grounding context',
-  codePrompt: 'code input',
-  codeResponse: 'code output',
-  toolEvent: {
-    metadata: { ecosystem: 'mcp', method: 'invoke', server_name: 'my-server' },
-    input: '{"query": "test"}',
-  },
-});
+| Auth Method                     | Used By                                                     |
+| ------------------------------- | ----------------------------------------------------------- |
+| **API Key** (HMAC-SHA256)       | AI Runtime Security scans only                              |
+| **OAuth2** (client_credentials) | Everything else — Management CRUD, Red Team, Model Security |
 
-// Serialize
-const json = content.toJSON();
+```bash
+# AI Runtime Security scans
+export PANW_AI_SEC_API_KEY=your-api-key
 
-// Deserialize
-const restored = Content.fromJSON(json);
-const fromFile = Content.fromJSONFile('./content.json');
+# OAuth2 (shared by Management, Red Team, Model Security)
+export PANW_MGMT_CLIENT_ID=your-client-id
+export PANW_MGMT_CLIENT_SECRET=your-client-secret
+export PANW_MGMT_TSG_ID=1234567890
 ```
 
+## Scanner Methods
+
+| Method                                | Description                                |
+| ------------------------------------- | ------------------------------------------ |
+| `syncScan(aiProfile, content, opts?)` | Synchronous inline scan                    |
+| `asyncScan(scanObjects)`              | Batch async scan (up to 5)                 |
+| `queryByScanIds(scanIds)`             | Get results by scan IDs (up to 5)          |
+| `queryByReportIds(reportIds)`         | Get threat reports by report IDs (up to 5) |
+
 ## Error Handling
 
 ```ts
@@ -123,65 +127,26 @@ try {
   await scanner.syncScan(profile, content);
 } catch (err) {
   if (err instanceof AISecSDKException) {
-    console.error(err.message); // includes ErrorType prefix
-    console.error(err.errorType); // ErrorType enum value
+    console.error(err.message);
+    console.error(err.errorType);
   }
 }
 ```
 
 Error types: `SERVER_SIDE_ERROR`, `CLIENT_SIDE_ERROR`, `USER_REQUEST_PAYLOAD_ERROR`, `MISSING_VARIABLE`, `AISEC_SDK_ERROR`, `OAUTH_ERROR`.
 
-## Management API
-
-Separate client for CRUD operations on Security Profiles and Custom Topics via OAuth2 client credentials. See [docs/management-api.md](docs/management-api.md) for full details.
-
-```bash
-# Required env vars (or pass as constructor options)
-export PANW_MGMT_CLIENT_ID=your-client-id
-export PANW_MGMT_CLIENT_SECRET=your-client-secret
-export PANW_MGMT_TSG_ID=1234567890
-# Optional: override for EU/UK/FedRAMP
-# export PANW_MGMT_ENDPOINT=https://api.eu.sase.paloaltonetworks.com/aisec
-```
-
-```ts
-import { ManagementClient } from '@cdot65/prisma-airs-sdk';
-
-const client = new ManagementClient();
-
-// Security Profiles
-const profiles = await client.profiles.list();
-const created = await client.profiles.create({ profile_name: 'my-profile', active: true, policy: { ... } });
-await client.profiles.update(created.profile_id, { ... });
-await client.profiles.delete(created.profile_id);
-
-// Custom Topics
-const topics = await client.topics.list();
-const topic = await client.topics.create({ topic_name: 'pii-detector', examples: ['SSN: 123-45-6789'] });
-await client.topics.update(topic.topic_id, { ... });
-await client.topics.delete(topic.topic_id);
-await client.topics.forceDelete(topic.topic_id); // even if referenced by a profile
-```
-
-## Migration from v0.1
+## Documentation
 
-| v0.1                                    | v0.2                                          |
-| --------------------------------------- | --------------------------------------------- |
-| `new PrismaAirsSdkClient({ apiToken })` | `init({ apiKey }); new Scanner()`             |
-| `client.scanSyncRequest(body)`          | `scanner.syncScan(aiProfile, content, opts?)` |
-| `client.scanAsyncRequest(body)`         | `scanner.asyncScan(scanObjects)`              |
-| `client.getScanResultsByScanIds(ids)`   | `scanner.queryByScanIds(ids)`                 |
-| `client.getThreatScanReports(ids)`      | `scanner.queryByReportIds(ids)`               |
-| `PrismaAirsApiError`                    | `AISecSDKException`                           |
-| `axios` dependency                      | Native `fetch` (zero HTTP deps)               |
+Full documentation at **[cdot65.github.io/prisma-airs-sdk](https://cdot65.github.io/prisma-airs-sdk/)** — includes API reference, service guides, OAuth lifecycle docs, and examples.
 
 ## Development
 
 ```bash
 npm install
-npm run build     # tsup (CJS + ESM + .d.ts)
-npm run test      # vitest
-npm run lint      # eslint
+npm run build          # tsup (CJS + ESM + .d.ts)
+npm run test           # vitest (617 tests, 99%+ coverage)
+npm run lint           # eslint
+npm run typecheck      # tsc --noEmit
 ```
 
 ## License

package/dist/index.cjs

@@ -188,6 +188,7 @@ __export(index_exports, {
   ModelSecurityRuleResponseSchema: () => ModelSecurityRuleResponseSchema,
   ModelSecurityRulesClient: () => ModelSecurityRulesClient,
   ModelSecurityScansClient: () => ModelSecurityScansClient,
+  OAuthClient: () => OAuthClient,
   PAYLOAD_HASH: () => PAYLOAD_HASH,
   PolicySchema: () => PolicySchema,
   PolicyType: () => PolicyType,
@@ -361,7 +362,7 @@ var MAX_NUMBER_OF_BATCH_SCAN_OBJECTS = 5;
 var MAX_CONNECTION_POOL_SIZE = 100;
 var MAX_NUMBER_OF_RETRIES = 5;
 var HTTP_FORCE_RETRY_STATUS_CODES = [500, 502, 503, 504];
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.5.1";
 var USER_AGENT = `PAN-AIRS/${SDK_VERSION}-typescript-sdk`;
 var DEFAULT_MGMT_ENDPOINT = "https://api.sase.paloaltonetworks.com/aisec";
 var DEFAULT_TOKEN_ENDPOINT = "https://auth.apps.paloaltonetworks.com/oauth2/access_token";
@@ -2647,12 +2648,14 @@ var OAuthTokenResponseSchema = import_zod19.z.object({
 });
 
 // src/management/oauth-client.ts
-var TOKEN_BUFFER_MS = 3e4;
+var DEFAULT_TOKEN_BUFFER_MS = 3e4;
 var OAuthClient = class {
   tokenEndpoint;
   clientId;
   clientSecret;
   tsgId;
+  tokenBufferMs;
+  onTokenRefresh;
   accessToken = null;
   expiresAt = 0;
   pendingFetch = null;
@@ -2661,13 +2664,15 @@ var OAuthClient = class {
     this.clientSecret = opts.clientSecret;
     this.tsgId = opts.tsgId;
     this.tokenEndpoint = opts.tokenEndpoint ?? DEFAULT_TOKEN_ENDPOINT;
+    this.tokenBufferMs = opts.tokenBufferMs ?? DEFAULT_TOKEN_BUFFER_MS;
+    this.onTokenRefresh = opts.onTokenRefresh;
   }
   /**
    * Get a valid access token, refreshing if needed.
    * @returns Bearer access token string.
    */
   async getToken() {
-    if (this.accessToken && Date.now() < this.expiresAt - TOKEN_BUFFER_MS) {
+    if (this.accessToken && Date.now() < this.expiresAt - this.tokenBufferMs) {
       return this.accessToken;
     }
     if (this.pendingFetch) {
@@ -2683,6 +2688,40 @@ var OAuthClient = class {
     this.accessToken = null;
     this.expiresAt = 0;
   }
+  /** Check if the current token has passed its expiry time. Returns true if no token exists. */
+  isTokenExpired() {
+    if (!this.accessToken) return true;
+    return Date.now() >= this.expiresAt;
+  }
+  /**
+   * Check if the token is within the pre-expiry buffer window.
+   * Returns true if no token exists.
+   * @param bufferMs - Custom buffer in ms. Defaults to the configured `tokenBufferMs`.
+   */
+  isTokenExpiringSoon(bufferMs) {
+    if (!this.accessToken) return true;
+    const buffer = bufferMs ?? this.tokenBufferMs;
+    return Date.now() >= this.expiresAt - buffer;
+  }
+  /**
+   * Get a snapshot of the current token state without exposing the actual token value.
+   * @returns Current {@link TokenInfo}.
+   */
+  getTokenInfo() {
+    const now = Date.now();
+    const hasToken = this.accessToken !== null;
+    const isExpired = !hasToken || now >= this.expiresAt;
+    const isExpiringSoon = !hasToken || now >= this.expiresAt - this.tokenBufferMs;
+    const expiresInMs = hasToken ? Math.max(0, this.expiresAt - now) : 0;
+    return {
+      hasToken,
+      isValid: hasToken && !isExpiringSoon,
+      isExpired,
+      isExpiringSoon,
+      expiresInMs,
+      expiresAt: hasToken ? this.expiresAt : 0
+    };
+  }
   async fetchToken() {
     const credentials = btoa(`${this.clientId}:${this.clientSecret}`);
     const body = new URLSearchParams({
@@ -2718,6 +2757,12 @@ var OAuthClient = class {
     const data = OAuthTokenResponseSchema.parse(await response.json());
     this.accessToken = data.access_token;
     this.expiresAt = Date.now() + data.expires_in * 1e3;
+    if (this.onTokenRefresh) {
+      try {
+        this.onTokenRefresh(this.getTokenInfo());
+      } catch {
+      }
+    }
     return this.accessToken;
   }
 };
@@ -2749,7 +2794,7 @@ async function managementHttpRequest(opts) {
       return fetch(url.toString(), { method, headers, body: bodyStr });
     },
     onRetryableFailure: async (response2) => {
-      if (response2.status === 401 && !hadTokenRefresh) {
+      if ((response2.status === 401 || response2.status === 403) && !hadTokenRefresh) {
         hadTokenRefresh = true;
         oauthClient.clearToken();
         return true;
@@ -4895,6 +4940,7 @@ var RedTeamClient = class {
   ModelSecurityRuleResponseSchema,
   ModelSecurityRulesClient,
   ModelSecurityScansClient,
+  OAuthClient,
   PAYLOAD_HASH,
   PolicySchema,
   PolicyType,