@crittora/sdk-js 2.0.0

package/docs/API.md

@@ -0,0 +1,225 @@
+# API Reference
+
+This document describes the public SDK surface exposed by `@crittora/sdk-js`.
+
+## Exports
+
+Primary exports:
+
+- `CrittoraClient`
+- `Crittora` (legacy compatibility shim)
+- `bearerToken`
+- `cognitoAuthProvider`
+- `CrittoraError`
+- `ValidationError`
+- `AuthError`
+- `RequestError`
+- `RateLimitError`
+- `EncryptError`
+- `DecryptError`
+
+## CrittoraClient
+
+### Constructor
+
+```ts
+new CrittoraClient(options?: CrittoraClientOptions)
+```
+
+### Options
+
+```ts
+type CrittoraClientOptions = {
+  baseUrl?: string;
+  credentials?: ApiCredentials;
+  auth?: BearerAuthConfig | AuthProvider;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+  retry?: RetryOptions;
+  headers?: Record<string, string>;
+  userAgent?: string;
+};
+```
+
+### Methods
+
+#### `encrypt(input)`
+
+```ts
+encrypt(input: EncryptInput): Promise<EncryptResult>
+```
+
+Input:
+
+```ts
+type EncryptInput = {
+  data: string;
+  permissions?: Permission[];
+};
+```
+
+Result:
+
+```ts
+type EncryptResult = {
+  encryptedData: string;
+  transactionId?: string;
+};
+```
+
+#### `decrypt(input)`
+
+```ts
+decrypt(input: DecryptInput): Promise<DecryptResult>
+```
+
+Input:
+
+```ts
+type DecryptInput = {
+  encryptedData: string;
+  permissions?: Permission[];
+};
+```
+
+Result:
+
+```ts
+type DecryptResult = {
+  decryptedData: string;
+  transactionId?: string;
+};
+```
+
+#### `decryptVerify(input)`
+
+```ts
+decryptVerify(input: DecryptVerifyInput): Promise<DecryptVerifyResult>
+```
+
+Input:
+
+```ts
+type DecryptVerifyInput = {
+  encryptedData: string;
+  permissions?: Permission[];
+};
+```
+
+Result:
+
+```ts
+type DecryptVerifyResult = {
+  decryptedData: string;
+  isValidSignature: boolean;
+  transactionId?: string;
+};
+```
+
+#### `withAuth(auth)`
+
+```ts
+withAuth(auth: AuthProvider | BearerAuthConfig): CrittoraClient
+```
+
+Creates a new client instance with the same transport and credential configuration, but with a different auth source.
+
+#### `auth`
+
+```ts
+get auth(): AuthProvider | undefined
+```
+
+Exposes the resolved auth provider associated with the client instance.
+
+## Auth
+
+### `bearerToken(token)`
+
+```ts
+bearerToken(token: string): AuthProvider
+```
+
+Creates an auth provider that always returns `Authorization: Bearer <token>`.
+
+### `cognitoAuthProvider(config)`
+
+```ts
+cognitoAuthProvider(config: CognitoAuthConfig): CognitoAuthProvider
+```
+
+Configuration:
+
+```ts
+type CognitoAuthConfig = {
+  userPoolId: string;
+  clientId: string;
+  username?: string;
+  password?: string;
+};
+```
+
+Methods:
+
+```ts
+getAuthorizationHeader(): Promise<string | undefined>
+login(credentials?: { username: string; password: string }): Promise<AuthTokens>
+```
+
+Result:
+
+```ts
+type AuthTokens = {
+  idToken: string;
+  accessToken: string;
+  refreshToken: string;
+};
+```
+
+## Legacy API
+
+### `Crittora`
+
+The `Crittora` class is preserved for compatibility with existing consumers.
+
+Methods:
+
+```ts
+authenticate(username: string, password: string): Promise<LegacyAuthResponse>
+encrypt(idToken: string, data: string, permissions?: string[]): Promise<string>
+decrypt(idToken: string, encryptedData: string, permissions?: string[]): Promise<string>
+decryptVerify(
+  idToken: string,
+  encryptedData: string,
+  permissions?: string[]
+): Promise<{ decrypted_data: string; is_valid_signature: boolean }>
+```
+
+This interface is transitional. New integrations should use `CrittoraClient`.
+
+## Errors
+
+### `CrittoraError`
+
+Base SDK error with:
+
+```ts
+type CrittoraError = Error & {
+  code: string;
+  status?: number;
+  requestId?: string;
+  details?: unknown;
+  cause?: unknown;
+}
+```
+
+### Specializations
+
+- `ValidationError`
+- `AuthError`
+- `RequestError`
+- `RateLimitError`
+- `EncryptError`
+- `DecryptError`
+
+Use these types for programmatic handling rather than parsing error messages.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,83 @@
+# Architecture Notes
+
+This document explains the SDK structure and the design decisions behind the current implementation.
+
+## Goals
+
+The SDK is designed to be:
+
+- explicit in configuration
+- safe to run in multi-tenant or multi-environment processes
+- adaptable to different auth models
+- operationally predictable under failure
+
+## Layering
+
+The package is split into a few clear layers:
+
+### Client
+
+[`src/client.ts`](../src/client.ts)
+
+`CrittoraClient` owns client configuration and exposes the public resource methods. It does not own process-global state.
+
+### Auth
+
+[`src/auth/`](../src/auth)
+
+Auth providers are responsible for supplying `Authorization` headers. The client accepts either a bearer config or a concrete `AuthProvider`.
+
+Built-in options:
+
+- `bearerToken(...)`
+- `cognitoAuthProvider(...)`
+
+### Transport
+
+[`src/transport/httpTransport.ts`](../src/transport/httpTransport.ts)
+
+The transport layer is responsible for:
+
+- request construction
+- timeout enforcement
+- retries
+- response parsing
+- error normalization
+
+It accepts both standard JSON responses and legacy API Gateway style payloads that wrap JSON in a `body` string.
+
+### Resources
+
+[`src/resources/crypto.ts`](../src/resources/crypto.ts)
+
+Resource classes translate public SDK models into backend wire payloads and map transport failures into operation-specific SDK errors.
+
+## Model translation
+
+Public SDK models use camelCase because they are intended for direct application use in JavaScript and TypeScript.
+
+Backend payloads still use snake_case. The SDK keeps that translation internal so wire-format concerns do not leak into consumer code.
+
+Examples:
+
+- `encryptedData` -> `encrypted_data`
+- `partnerId` -> `partner_id`
+- `isValidSignature` -> `is_valid_signature`
+
+## Error strategy
+
+The SDK exposes one base error and several specializations so callers can respond at the right layer:
+
+- validation failures
+- auth failures
+- transport or HTTP failures
+- rate limiting
+- operation-level failures
+
+Errors preserve status, details, and request identifiers where available.
+
+## Compatibility strategy
+
+The legacy `Crittora` class remains in the package as a migration bridge. It adapts older positional-call semantics to the new client internally.
+
+This avoids a forced flag day while still moving the primary API toward a better SDK contract.

package/docs/MIGRATION.md

@@ -0,0 +1,187 @@
+# Migration Guide
+
+This guide covers migration from the legacy `Crittora` API to `CrittoraClient`.
+
+## Why migrate
+
+The v2 client gives you:
+
+- isolated client instances
+- explicit environment and credential wiring
+- typed object-based inputs
+- cleaner auth composition
+- structured error handling
+
+## Before and after
+
+### Construction
+
+Before:
+
+```ts
+import { Crittora } from "@crittora/sdk-js";
+
+const sdk = new Crittora();
+```
+
+After:
+
+```ts
+import { CrittoraClient } from "@crittora/sdk-js";
+
+const client = new CrittoraClient({
+  baseUrl: "https://api.crittoraapis.com",
+  credentials: {
+    apiKey: process.env.CRITTORA_API_KEY!,
+    accessKey: process.env.CRITTORA_ACCESS_KEY!,
+    secretKey: process.env.CRITTORA_SECRET_KEY!,
+  },
+});
+```
+
+### Authentication
+
+Before:
+
+```ts
+const { IdToken } = await sdk.authenticate(username, password);
+```
+
+After:
+
+```ts
+import { cognitoAuthProvider } from "@crittora/sdk-js";
+
+const auth = cognitoAuthProvider({
+  userPoolId: "us-east-1_Tmljk4Uiw",
+  clientId: "5cvaao4qgphfp38g433vi5e82u",
+});
+
+const { idToken } = await auth.login({ username, password });
+```
+
+### Encrypt
+
+Before:
+
+```ts
+const encrypted = await sdk.encrypt(idToken, data, ["read"]);
+```
+
+After:
+
+```ts
+const encrypted = await client
+  .withAuth({ type: "bearer", token: idToken })
+  .encrypt({
+    data,
+    permissions: [
+      {
+        partnerId: "default",
+        actions: ["read"],
+      },
+    ],
+  });
+```
+
+### Decrypt
+
+Before:
+
+```ts
+const decrypted = await sdk.decrypt(idToken, encryptedData);
+```
+
+After:
+
+```ts
+const decrypted = await client
+  .withAuth({ type: "bearer", token: idToken })
+  .decrypt({
+    encryptedData,
+  });
+```
+
+### Decrypt and verify
+
+Before:
+
+```ts
+const result = await sdk.decryptVerify(idToken, encryptedData);
+console.log(result.decrypted_data, result.is_valid_signature);
+```
+
+After:
+
+```ts
+const result = await client
+  .withAuth({ type: "bearer", token: idToken })
+  .decryptVerify({
+    encryptedData,
+  });
+
+console.log(result.decryptedData, result.isValidSignature);
+```
+
+## Type changes
+
+Main public naming changes:
+
+- `encrypted_data` -> `encryptedData`
+- `decrypted_data` -> `decryptedData`
+- `is_valid_signature` -> `isValidSignature`
+
+Permission changes:
+
+Before:
+
+```ts
+["read", "write"]
+```
+
+After:
+
+```ts
+[
+  {
+    partnerId: "default",
+    actions: ["read", "write"],
+  },
+]
+```
+
+## Error handling changes
+
+Before, callers often had to catch broad errors.
+
+After, callers can branch on typed SDK errors:
+
+```ts
+import { DecryptError, RateLimitError, RequestError } from "@crittora/sdk-js";
+
+try {
+  await client.decrypt({ encryptedData });
+} catch (error) {
+  if (error instanceof RateLimitError) {
+    // handle throttling
+  } else if (error instanceof DecryptError) {
+    // handle decrypt failure
+  } else if (error instanceof RequestError) {
+    // handle transport or non-2xx responses
+  } else {
+    throw error;
+  }
+}
+```
+
+## Transitional strategy
+
+Recommended migration sequence:
+
+1. Replace `new Crittora()` with `new CrittoraClient(...)`.
+2. Move token acquisition into an auth provider or your own auth layer.
+3. Convert positional method calls to object inputs.
+4. Update call sites to camelCase response fields.
+5. Replace generic error handling with typed error handling.
+
+The legacy `Crittora` export remains available for staged migrations, but new code should not be added against it.

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@crittora/sdk-js",
+  "version": "2.0.0",
+  "description": "Crittora JavaScript SDK",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "docs",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "jest",
+    "clean": "rimraf dist",
+    "build": "NODE_ENV=production tsc",
+    "prepare": "NODE_ENV=production npm run build",
+    "prepublishOnly": "npm run verify",
+    "prepack": "NODE_ENV=production npm run build",
+    "lint": "eslint . --ext .ts",
+    "verify": "npm run clean && npm run build && npm run test",
+    "release": "npm run verify && npm version patch && npm publish",
+    "release:patch": "npm run verify && npm version patch && npm publish",
+    "release:minor": "npm run verify && npm version minor && npm publish",
+    "release:major": "npm run verify && npm version major && npm publish"
+  },
+  "keywords": [
+    "encryption",
+    "signing",
+    "sdk",
+    "cryptography",
+    "crittora"
+  ],
+  "author": "Erik Rowan <erik@crittora.com>, Gerardo I. Ornelas <gerardo@crittora.com>",
+  "license": "MIT",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./auth-cognito": {
+      "types": "./dist/auth/cognito.d.ts",
+      "require": "./dist/auth/cognito.js",
+      "default": "./dist/auth/cognito.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "require": "./dist/errors.js",
+      "default": "./dist/errors.js"
+    }
+  },
+  "dependencies": {
+    "amazon-cognito-identity-js": "^6.3.12"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.14.10",
+    "jest": "^29.7.0",
+    "prettier": "^2.8.0",
+    "rimraf": "^5.0.0",
+    "ts-jest": "^29.2.2",
+    "typescript": "^5.5.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Crittora/crittora-sdk-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Crittora/crittora-sdk-js/issues"
+  },
+  "homepage": "https://github.com/Crittora/crittora-sdk-js#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}