blockintel-gate-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 BlockIntel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,386 @@
+# BlockIntel Gate SDK
+
+Production-grade TypeScript/Node.js SDK for [BlockIntel Gate](https://blockintel.ai) Hot Path API.
+
+## Installation
+
+```bash
+npm install @blockintel/gate-sdk
+```
+
+## Requirements
+
+- Node.js >= 18.0.0 (uses global `fetch` API)
+- TypeScript >= 5.0.0 (optional, for type definitions)
+
+## Quick Start
+
+### HMAC Authentication
+
+```typescript
+import { GateClient } from '@blockintel/gate-sdk';
+
+const gate = new GateClient({
+  baseUrl: process.env.GATE_BASE_URL!,
+  tenantId: process.env.GATE_TENANT_ID!,
+  auth: {
+    mode: 'hmac',
+    keyId: process.env.GATE_KEY_ID!,
+    secret: process.env.GATE_HMAC_SECRET!,
+  },
+  enableStepUp: true,
+});
+
+// Evaluate a transaction
+const response = await gate.evaluate({
+  txIntent: {
+    from: '0x1234567890123456789012345678901234567890',
+    to: '0x0987654321098765432109876543210987654321',
+    value: '1000000000000000000', // 1 ETH in wei
+    data: '0x...',
+    nonce: 42,
+    gasPrice: '20000000000',
+    gasLimit: '21000',
+    chainId: 1,
+  },
+  signingContext: {
+    signerId: 'my-signer-id',
+    source: {
+      repo: 'myorg/myrepo',
+      workflow: 'deploy-production',
+      environment: 'production',
+    },
+    wallet: {
+      address: '0x1234...',
+      type: 'hardware',
+    },
+  },
+});
+
+if (response.decision === 'ALLOW') {
+  // Proceed with transaction
+  console.log('Transaction approved:', response.correlationId);
+} else if (response.decision === 'REQUIRE_STEP_UP') {
+  // Poll for step-up decision
+  const final = await gate.awaitStepUpDecision({
+    requestId: response.stepUp!.requestId,
+  });
+
+  if (final.status === 'APPROVED') {
+    // Proceed with transaction
+    console.log('Step-up approved:', final.correlationId);
+  } else {
+    // Block transaction
+    console.log('Step-up denied or expired:', final.status);
+  }
+} else {
+  // BLOCK
+  console.log('Transaction blocked:', response.reasonCodes);
+}
+```
+
+### API Key Authentication
+
+```typescript
+import { GateClient } from '@blockintel/gate-sdk';
+
+const gate = new GateClient({
+  baseUrl: process.env.GATE_BASE_URL!,
+  tenantId: process.env.GATE_TENANT_ID!,
+  auth: {
+    mode: 'apiKey',
+    apiKey: process.env.GATE_API_KEY!,
+  },
+});
+
+const response = await gate.evaluate({
+  txIntent: {
+    from: '0x123...',
+    to: '0x456...',
+    value: '1000000000000000000',
+  },
+});
+```
+
+### Step-Up Polling
+
+```typescript
+// Manual polling
+const status = await gate.getStepUpStatus({
+  requestId: 'stepup-request-id',
+});
+
+console.log('Status:', status.status); // PENDING | APPROVED | DENIED | EXPIRED
+
+// Automatic polling with timeout
+const result = await gate.awaitStepUpDecision({
+  requestId: 'stepup-request-id',
+  maxWaitMs: 15000, // 15 seconds
+  intervalMs: 250,  // Poll every 250ms
+});
+
+console.log('Final status:', result.status);
+console.log('Elapsed time:', result.elapsedMs, 'ms');
+```
+
+**Polling behavior:**
+- `404 NOT_FOUND` → request ID does not exist OR does not belong to the tenant
+- `EXPIRED` → TTL exceeded (deterministic), even if DynamoDB TTL has not deleted the item yet
+- `PENDING` → waiting for external approval
+- `APPROVED | DENIED` → terminal states
+
+## Configuration
+
+### `GateClientConfig`
+
+```typescript
+interface GateClientConfig {
+  baseUrl: string;                    // Gate Hot Path API base URL
+  tenantId: string;                   // Your tenant ID
+  auth:                                // Authentication
+    | { mode: 'hmac'; keyId: string; secret: string }
+    | { mode: 'apiKey'; apiKey: string };
+  timeoutMs?: number;                 // Request timeout (default: 15000ms)
+  userAgent?: string;                 // User agent (default: '@blockintel/gate-sdk/<version>')
+  clockSkewMs?: number;               // Clock skew tolerance (default: 120000ms)
+  enableStepUp?: boolean;             // Enable step-up support (default: false)
+  stepUp?: {
+    pollingIntervalMs?: number;       // Polling interval (default: 250ms)
+    maxWaitMs?: number;               // Max wait time (default: 15000ms)
+    treatRequireStepUpAsBlockWhenDisabled?: boolean; // Transform REQUIRE_STEP_UP to BLOCK (default: true)
+  };
+```
+
+When step-up is disabled, the SDK treats `REQUIRE_STEP_UP` as `BLOCK` by default to preserve Gate-only safety, unless the caller explicitly overrides this behavior.
+}
+```
+
+### Environment Variables
+
+```bash
+# Required
+GATE_BASE_URL=https://gate.blockintelai.net
+GATE_TENANT_ID=your-tenant-id
+
+# HMAC Authentication
+GATE_KEY_ID=your-key-id
+GATE_HMAC_SECRET=your-secret
+
+# OR API Key Authentication
+GATE_API_KEY=your-api-key
+```
+
+## API Reference
+
+### `GateClient.evaluate(req, opts?)`
+
+Evaluate a transaction defense request.
+
+**Parameters:**
+- `req: DefenseEvaluateRequestV2` - Transaction and signing context
+- `opts?: { requestId?: string }` - Optional request ID (auto-generated if not provided)
+
+**Returns:** `Promise<DefenseEvaluateResponseV2>`
+
+**Response:**
+```typescript
+{
+  decision: 'ALLOW' | 'BLOCK' | 'REQUIRE_STEP_UP';
+  reasonCodes: string[];
+  policyVersion?: string;
+  correlationId?: string;
+  stepUp?: {
+    requestId: string;
+    ttlSeconds?: number;
+  };
+}
+```
+
+### `GateClient.getStepUpStatus(args)`
+
+Get current step-up status.
+
+**Parameters:**
+- `args: { requestId: string; tenantId?: string }`
+
+**Returns:** `Promise<StepUpStatusResponse>`
+
+**Status Types:**
+- `PENDING` - Waiting for decision
+- `APPROVED` - Step-up approved
+- `DENIED` - Step-up denied
+- `EXPIRED` - Step-up expired (TTL exceeded)
+
+**Polling behavior:**
+- Returns `404 NOT_FOUND` if request ID does not exist OR does not belong to the tenant
+- Returns `EXPIRED` deterministically if TTL exceeded, even if DynamoDB TTL has not deleted the item yet
+
+### `GateClient.awaitStepUpDecision(args)`
+
+Poll step-up status until decision is reached or timeout.
+
+**Parameters:**
+- `args: { requestId: string; maxWaitMs?: number; intervalMs?: number }`
+
+**Returns:** `Promise<StepUpFinalResult>`
+
+## Error Handling
+
+The SDK uses custom error types:
+
+```typescript
+import { GateError, GateErrorCode, StepUpNotConfiguredError } from '@blockintel/gate-sdk';
+
+try {
+  const response = await gate.evaluate({ ... });
+} catch (error) {
+  if (error instanceof GateError) {
+    console.error('Error code:', error.code);
+    console.error('Status:', error.status);
+    console.error('Request ID:', error.requestId);
+    console.error('Correlation ID:', error.correlationId);
+  }
+}
+```
+
+**Error Codes:**
+- `NETWORK_ERROR` - Network connection failed
+- `TIMEOUT` - Request timeout
+- `NOT_FOUND` - Resource not found (404)
+- `UNAUTHORIZED` - Authentication failed (401)
+- `FORBIDDEN` - Access denied (403)
+- `RATE_LIMITED` - Rate limit exceeded (429)
+- `SERVER_ERROR` - Server error (5xx)
+- `INVALID_RESPONSE` - Invalid response format
+- `STEP_UP_NOT_CONFIGURED` - Step-up required but not enabled
+- `STEP_UP_TIMEOUT` - Step-up polling timeout
+
+## Authentication
+
+### HMAC v1 Signing
+
+The SDK implements HMAC v1 signing for secure authentication:
+
+**Signing String:**
+```
+<HTTP_METHOD>\n
+<PATH>\n
+<TENANT_ID>\n
+<TIMESTAMP_MS>\n
+<REQUEST_ID>\n
+<SHA256_HEX_OF_BODY>\n
+```
+
+**Signature:**
+```
+HMAC-SHA256(secret, signingString) as hex
+```
+
+**Headers:**
+- `X-GATE-TENANT-ID`
+- `X-GATE-KEY-ID`
+- `X-GATE-TIMESTAMP-MS`
+- `X-GATE-REQUEST-ID`
+- `X-GATE-SIGNATURE`
+
+### API Key
+
+For simpler onboarding, use API key authentication:
+
+**Headers:**
+- `X-API-KEY`
+- `X-GATE-TENANT-ID`
+- `X-GATE-REQUEST-ID`
+- `X-GATE-TIMESTAMP-MS`
+
+## Step-Up Flow
+
+Step-up is a feature-flagged capability that allows Gate to defer decisions to an external approval system.
+
+**Flow:**
+1. SDK calls `evaluate()` → Gate returns `REQUIRE_STEP_UP`
+2. SDK polls `/defense/stepup/status` until decision is reached
+3. External system (Control Plane) approves/denies via separate API
+4. SDK receives final decision: `APPROVED`, `DENIED`, or `EXPIRED`
+
+**Important:**
+- Hot Path **never** approves/denies step-up
+- Approve/deny happens **only** on Control Plane
+- SDK only polls status from Hot Path
+- **The SDK never performs approve/deny actions. Step-up resolution is handled exclusively by the Control Plane.**
+
+Gate-only deployments should leave step-up disabled; the SDK will never "wait" unless step-up is enabled.
+
+**TTL Guardrails:**
+- Default: 600 seconds
+- Min: 300 seconds
+- Max: 900 seconds
+
+## Retry Logic
+
+The SDK automatically retries failed requests:
+
+- **Max Attempts:** 3
+- **Retry On:** Network errors, timeouts, 429, 5xx
+- **Never Retry On:** 4xx (except 429)
+- **Backoff:** Exponential with jitter (100ms base, 2x factor, 800ms max)
+
+**Request ID Stability:**
+- Same `requestId` is used across all retries
+- Ensures idempotency on Gate server
+
+## Secret Rotation
+
+For HMAC authentication, secret rotation is the customer's responsibility:
+
+1. Update environment variable with new secret
+2. SDK reads from config at runtime (no caching)
+3. Restart application to use new secret
+
+The SDK does not cache secrets across process restarts unless the user explicitly does so.
+
+## Security
+
+- **HTTPS Required:** SDK validates HTTPS in production (localhost exception)
+- **Secret Protection:** Never logs secrets or API keys
+- **Clock Skew:** Configurable tolerance for timestamp validation
+- **Replay Protection:** Request ID + timestamp prevent replay attacks
+
+## TypeScript Support
+
+Full TypeScript definitions are included:
+
+```typescript
+import type {
+  DefenseEvaluateRequestV2,
+  DefenseEvaluateResponseV2,
+  GateDecision,
+  StepUpStatusResponse,
+  GateStepUpStatus,
+  StepUpFinalResult,
+} from '@blockintel/gate-sdk';
+```
+
+## Examples
+
+See [examples](./examples) directory for complete examples:
+- [HMAC Authentication](./examples/hmac-auth.ts)
+- [API Key Authentication](./examples/api-key-auth.ts)
+- [Step-Up Flow](./examples/step-up-flow.ts)
+
+## Publishing
+
+- Package versions are immutable once published (NPM does not allow overwriting a released version). Always bump the version before tagging a release.
+
+See [PUBLISHING.md](./PUBLISHING.md) for detailed publishing instructions.
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) file.
+
+## Support
+
+- **Documentation:** https://docs.blockintel.ai
+- **Issues:** https://github.com/4KInc/blockintel-ai/issues
+- **Email:** support@blockintel.ai
+