cdk-turso 0.0.2 → 0.0.4

package/.jsii

@@ -2791,7 +2791,7 @@
   },
   "name": "cdk-turso",
   "readme": {
-    "markdown": "# CDK Turso\n\nCDK construct to create a [Turso cloud](https://docs.turso.tech/turso-cloud) database.\n\n## Installation\n\n```bash\nnpm install cdk-turso\n```\n\n## Usage\n\n```typescript\nimport { Stack } from 'aws-cdk-lib';\nimport { StringParameter } from 'aws-cdk-lib/aws-ssm';\nimport { TursoDatabase } from 'cdk-turso';\n\nconst stack = new Stack();\n\n// SSM Parameter containing your Turso API token\nconst apiToken = new StringParameter(stack, 'TursoApiToken', {\n  parameterName: '/turso/api-token',\n  stringValue: 'your-api-token',\n});\n\nconst database = new TursoDatabase(stack, 'Database', {\n  databaseName: 'my-database',\n  group: 'group-name',\n  organizationSlug: 'my-org',\n  apiToken,\n});\n\n// Use the database attributes\ndatabase.dbId;     // Database ID\ndatabase.hostname; // Database hostname\ndatabase.databaseName; // Database name\n```\n\n## API\n\n### TursoDatabaseProps\n\n| Prop | Type | Required | Description |\n|------|------|----------|-------------|\n| `databaseName` | `string` | Yes | Database name (lowercase, numbers, dashes only, max 64 chars) |\n| `group` | `string` | Yes | Turso group name (must already exist) |\n| `organizationSlug` | `string` | Yes | Organization slug |\n| `apiToken` | `ssm.IParameter` | Yes | SSM Parameter containing the Turso API token |\n| `sizeLimit` | `string` | No | Size limit (e.g., '256mb') |\n| `seed` | `TursoDatabaseSeed` | No | Database seed configuration |\n| `encryption` | `TursoDatabaseEncryption` | No | Encryption configuration |\n\n### TursoDatabaseSeed\n\n```typescript\ninterface TursoDatabaseSeed {\n  readonly type: string;      // Seed type (e.g., 'schema')\n  readonly name: string;       // Seed name\n  readonly timestamp?: string;  // Optional timestamp\n}\n```\n\n### TursoDatabaseEncryption\n\n```typescript\ninterface TursoDatabaseEncryption {\n  readonly encryptionKey: string;    // KMS key ARN\n  readonly encryptionCipher: string; // Cipher type (e.g., 'AES')\n}\n```\n\n### TursoDatabase\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `dbId` | `string` | Turso database ID |\n| `hostname` | `string` | DNS hostname (e.g., `my-db-my-org.turso.io`) for libSQL/HTTP connections |\n| `databaseName` | `string` | Database name |\n\n## Requirements\n\n- Node.js 24.x runtime for the Lambda handler\n- The Lambda handler requires the AWS SDK for JavaScript v3 (pre-installed in Lambda runtime)\n"
+    "markdown": "# CDK Turso\n\nCDK construct to create a [Turso cloud](https://docs.turso.tech/turso-cloud) database.\n\n## Installation\n\n```bash\nnpm install cdk-turso\n```\n\n## Usage\n\n```typescript\nimport { Stack } from 'aws-cdk-lib';\nimport { StringParameter } from 'aws-cdk-lib/aws-ssm';\nimport { TursoDatabase } from 'cdk-turso';\n\nconst stack = new Stack();\n\n// SSM Parameter containing your Turso API token\nconst apiToken = new StringParameter(stack, 'TursoApiToken', {\n  parameterName: '/turso/api-token',\n  stringValue: 'your-api-token',\n});\n\nconst database = new TursoDatabase(stack, 'Database', {\n  databaseName: 'my-database',\n  group: 'group-name',\n  organizationSlug: 'my-org',\n  apiToken,\n});\n\n// Use the database attributes\ndatabase.dbId;     // Database ID\ndatabase.hostname; // Database hostname\ndatabase.databaseName; // Database name\n```\n\n### Auth Token\n\nGenerate a database auth token and store it as a SecureString in SSM Parameter Store:\n\n```typescript\nimport { TursoAuthToken } from 'cdk-turso';\n\nconst authToken = new TursoAuthToken(stack, 'AuthToken', {\n  database,\n  parameterName: '/turso/db-token',\n  expiration: '2w',          // optional, default: 'never'\n  authorization: 'read-only', // optional, default: 'full-access'\n});\n\n// The SSM parameter name where the JWT is stored\nauthToken.parameterName;\n```\n\n## API\n\n### TursoDatabaseProps\n\n| Prop | Type | Required | Description |\n|------|------|----------|-------------|\n| `databaseName` | `string` | Yes | Database name (lowercase, numbers, dashes only, max 64 chars) |\n| `group` | `string` | Yes | Turso group name (must already exist) |\n| `organizationSlug` | `string` | Yes | Organization slug |\n| `apiToken` | `ssm.IParameter` | Yes | SSM Parameter containing the Turso API token |\n| `sizeLimit` | `string` | No | Size limit (e.g., '256mb') |\n| `seed` | `TursoDatabaseSeed` | No | Database seed configuration |\n| `encryption` | `TursoDatabaseEncryption` | No | Encryption configuration |\n\n### TursoDatabaseSeed\n\n```typescript\ninterface TursoDatabaseSeed {\n  readonly type: string;      // Seed type (e.g., 'schema')\n  readonly name: string;       // Seed name\n  readonly timestamp?: string;  // Optional timestamp\n}\n```\n\n### TursoDatabaseEncryption\n\n```typescript\ninterface TursoDatabaseEncryption {\n  readonly encryptionKey: string;    // KMS key ARN\n  readonly encryptionCipher: string; // Cipher type (e.g., 'AES')\n}\n```\n\n### TursoDatabase\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `dbId` | `string` | Turso database ID |\n| `hostname` | `string` | DNS hostname (e.g., `my-db-my-org.turso.io`) for libSQL/HTTP connections |\n| `databaseName` | `string` | Database name |\n| `organizationSlug` | `string` | Organization slug |\n| `apiToken` | `ssm.IParameter` | SSM Parameter containing the Turso API token |\n\n### TursoAuthTokenProps\n\n| Prop | Type | Required | Description |\n|------|------|----------|-------------|\n| `database` | `TursoDatabase` | Yes | The Turso database to create an auth token for |\n| `parameterName` | `string` | Yes | SSM parameter name where the generated JWT will be stored as a SecureString |\n| `expiration` | `string` | No | Token expiry (e.g., `'2w'`, `'1d30m'`). Default: `'never'` |\n| `authorization` | `string` | No | `'full-access'` or `'read-only'`. Default: `'full-access'` |\n\n### TursoAuthToken\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `parameterName` | `string` | The SSM parameter name where the auth token is stored |\n\n## Requirements\n\n- Node.js 24.x runtime for the Lambda handler\n- The Lambda handler requires the AWS SDK for JavaScript v3 (pre-installed in Lambda runtime)\n"
   },
   "repository": {
     "type": "git",
@@ -2804,6 +2804,152 @@
     }
   },
   "types": {
+    "cdk-turso.TursoAuthToken": {
+      "assembly": "cdk-turso",
+      "base": "constructs.Construct",
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "cdk-turso.TursoAuthToken",
+      "initializer": {
+        "docs": {
+          "stability": "stable"
+        },
+        "locationInModule": {
+          "filename": "src/turso-auth-token.ts",
+          "line": 42
+        },
+        "parameters": [
+          {
+            "name": "scope",
+            "type": {
+              "fqn": "constructs.Construct"
+            }
+          },
+          {
+            "name": "id",
+            "type": {
+              "primitive": "string"
+            }
+          },
+          {
+            "name": "props",
+            "type": {
+              "fqn": "cdk-turso.TursoAuthTokenProps"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/turso-auth-token.ts",
+        "line": 36
+      },
+      "name": "TursoAuthToken",
+      "properties": [
+        {
+          "docs": {
+            "stability": "stable",
+            "summary": "The SSM parameter name where the auth token is stored."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/turso-auth-token.ts",
+            "line": 40
+          },
+          "name": "parameterName",
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "src/turso-auth-token:TursoAuthToken"
+    },
+    "cdk-turso.TursoAuthTokenProps": {
+      "assembly": "cdk-turso",
+      "datatype": true,
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "cdk-turso.TursoAuthTokenProps",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/turso-auth-token.ts",
+        "line": 9
+      },
+      "name": "TursoAuthTokenProps",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "The Turso database to create an auth token for."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/turso-auth-token.ts",
+            "line": 13
+          },
+          "name": "database",
+          "type": {
+            "fqn": "cdk-turso.TursoDatabase"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "The SSM parameter name where the generated JWT will be stored as a SecureString."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/turso-auth-token.ts",
+            "line": 19
+          },
+          "name": "parameterName",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "\"full-access\"",
+            "stability": "stable",
+            "summary": "Authorization level for the token."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/turso-auth-token.ts",
+            "line": 33
+          },
+          "name": "authorization",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "\"never\"",
+            "stability": "stable",
+            "summary": "Expiration time for the token (e.g., `\"2w\"`, `\"1d30m\"`)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/turso-auth-token.ts",
+            "line": 26
+          },
+          "name": "expiration",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "src/turso-auth-token:TursoAuthTokenProps"
+    },
     "cdk-turso.TursoDatabase": {
       "assembly": "cdk-turso",
       "base": "constructs.Construct",
@@ -2817,7 +2963,7 @@
         },
         "locationInModule": {
           "filename": "src/turso-database.ts",
-          "line": 38
+          "line": 40
         },
         "parameters": [
           {
@@ -2847,6 +2993,20 @@
       },
       "name": "TursoDatabase",
       "properties": [
+        {
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/turso-database.ts",
+            "line": 38
+          },
+          "name": "apiToken",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_ssm.IParameter"
+          }
+        },
         {
           "docs": {
             "stability": "stable"
@@ -2889,6 +3049,20 @@
           "type": {
             "primitive": "string"
           }
+        },
+        {
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/turso-database.ts",
+            "line": 37
+          },
+          "name": "organizationSlug",
+          "type": {
+            "primitive": "string"
+          }
         }
       ],
       "symbolId": "src/turso-database:TursoDatabase"
@@ -3129,6 +3303,6 @@
       "symbolId": "src/turso-database:TursoDatabaseSeed"
     }
   },
-  "version": "0.0.2",
-  "fingerprint": "jU4E/TYDbNGRf5Tbpypr/Ik9pU3wkHPifpyFsGKuL+A="
+  "version": "0.0.4",
+  "fingerprint": "USxC5s0tkERUA9DB2YybfbXUXWF2FsLi8ae2BIX8WFQ="
 }

package/AGENTS.md

@@ -1,41 +1,143 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidance for AI coding agents working in this repository.
 
 ## Project Overview
 
-CDK construct library for provisioning Turso cloud databases. Built with projen's `AwsCdkConstructLibrary` template, using JSII for potential multi-language support (Python, Java, C#, Go).
+CDK construct library for provisioning Turso cloud databases. Built with projen's `AwsCdkConstructLibrary` template, using JSII for multi-language support. Source must remain JSII-compatible.
 
 ## Commands
 
 ```bash
 npm run build          # Full pipeline: compile → test → package
-npm run compile        # jsii compiler (TypeScript → JS + .d.ts)
-npm run test           # Jest (with coverage) + ESLint
+npm run compile        # jsii compiler (TypeScript → JS + .d.ts) + esbuild handler bundle
+npm run test           # Jest (with coverage) + Biome lint
 npm run test:watch     # Jest in watch mode
-npm run eslint         # ESLint with --fix on src/, test/, projenrc/
 npm run watch          # jsii in watch mode (for development)
+npx projen biome       # Run Biome formatter + linter with --fix
 npx projen             # Regenerate project files from .projenrc.ts
 ```
 
-Run a single test file: `npx jest --passWithNoTests test/hello.test.ts`
+Run a single test file:
+```bash
+npx jest --passWithNoTests test/handler.test.ts
+```
 
 ## Projen: Critical Rule
 
-Most configuration files are **generated by projen** and must NOT be edited directly. This includes `package.json`, `.eslintrc.json`, `tsconfig.dev.json`, GitHub workflows, and anything marked with `~~ Generated by projen`. To change project configuration, edit `.projenrc.ts` and run `npx projen`.
+Most config files are **generated by projen** and must NOT be edited directly. This includes `package.json`, `biome.jsonc`, `tsconfig.json`, `tsconfig.dev.json`, GitHub workflows, `.mergify.yml`, and anything marked `~~ Generated by projen`. To change project configuration, edit `.projenrc.ts` and run `npx projen`.
 
 ## Architecture
 
-- **Source**: `src/` — construct classes exported from `src/index.ts`
-- **Tests**: `test/` — Jest tests (`*.test.ts`)
-- **Compiled output**: `lib/` (generated, gitignored)
-- **Distribution**: `dist/` (generated, gitignored)
+```
+src/
+  index.ts                 # Barrel exports — all public symbols re-exported here
+  turso-database.ts        # Main CDK construct
+  handler/index.ts         # Lambda handler for CloudFormation custom resource (bundled via esbuild)
+test/
+  turso-database.test.ts   # Construct unit tests (CDK assertions)
+  handler.test.ts          # Handler unit tests (Jest mocks)
+lib/                       # Compiled output (generated, gitignored)
+dist/                      # Distribution packages (generated, gitignored)
+```
+
 - Peer dependencies: `aws-cdk-lib` (^2.1.0), `constructs` (^10.0.5)
+- Handler bundled separately: `esbuild src/handler/index.ts --bundle --platform=node --target=node24 --outfile=lib/handler/index.js --external:@aws-sdk/*`
+- Pre-commit hook (husky): runs `npx projen biome && npx projen build`
+
+## Code Style (enforced by Biome)
+
+Biome is the sole linter and formatter. ESLint is disabled.
+
+### Formatting
+- **2-space** indentation (spaces, not tabs)
+- **80-char** max line width
+- **Double quotes** for strings: `"hello"` not `'hello'`
+- **Semicolons as needed** — omit them; Biome inserts only where syntactically required
+- **Trailing commas** on all multi-line constructs (arrays, objects, parameters)
+- **Arrow parentheses**: always, even for single parameter `(x) => x`
+- **Bracket spacing**: `{ a }` not `{a}`
+
+### Linting Rules
+- `noUnusedImports`: error
+- `noUnusedVariables`: error
+- `noConfusingVoidType`: error
+- `noNonNullAssertion`: allowed in `**/*.test.ts` only
+- `useNodejsImportProtocol`: off — use `"path"` not `"node:path"`
+
+## Import Conventions
+
+### Ordering
+1. AWS CDK / framework imports (`aws-cdk-lib`, `aws-cdk-lib/*`, `constructs`)
+2. External packages (`@aws-sdk/client-ssm`)
+3. Node.js builtins (`import * as path from "path"`)
+4. Relative imports (`"./turso-database"`, `"../src"`)
+
+### Style
+- **Named imports** with destructuring: `import { CustomResource, Duration } from "aws-cdk-lib"`
+- **Namespace imports** for Node builtins: `import * as path from "path"`
+- **`type` keyword** for type-only imports: `import type { IParameter } from "aws-cdk-lib/aws-ssm"`
+- **Inline `type`** in mixed imports: `import { type SomeType, someValue } from "..."`
+- Use deep CDK imports: `aws-cdk-lib/aws-lambda`, `aws-cdk-lib/aws-ssm`, `aws-cdk-lib/custom-resources`
+- Barrel exports in `src/index.ts` are **alphabetically sorted**
+
+## Naming Conventions
+
+| Category | Convention | Example |
+|---|---|---|
+| Source files | kebab-case `.ts` | `turso-database.ts` |
+| Test files | `{source-name}.test.ts` | `handler.test.ts` |
+| Classes | PascalCase | `TursoDatabase` |
+| Props interfaces | `{ClassName}Props` | `TursoDatabaseProps` |
+| Sub-config interfaces | `{ClassName}{Feature}` | `TursoDatabaseEncryption` |
+| Interface properties | `readonly`, camelCase | `readonly databaseName: string` |
+| Public class properties | `public readonly`, camelCase | `public readonly dbId: string` |
+| Functions | camelCase | `handler`, `getApiToken` |
+| CDK resource IDs | PascalCase string | `"Handler"`, `"Provider"` |
+| CF resource properties | PascalCase string | `"DatabaseName"`, `"Group"` |
+| Environment variables | SCREAMING_SNAKE_CASE | `TURSO_API_TOKEN_PARAMETER_NAME` |
+
+## TypeScript
+
+- `strict: true` — all strict checks enabled (`noImplicitAny`, `strictNullChecks`, `strictPropertyInitialization`, etc.)
+- `noUnusedLocals: true`, `noUnusedParameters: true`, `noImplicitReturns: true`
+- `noFallthroughCasesInSwitch: true`
+- Target: `ES2020`, Module: `CommonJS`
+
+## CDK Construct Patterns
+
+- Extend `Construct` from `constructs`, not from `aws-cdk-lib`
+- Constructor signature: `constructor(scope: Construct, id: string, props: XxxProps)`
+- Call `super(scope, id)` first
+- Validate inputs in constructor with `throw new Error(...)` for bad values
+- Custom resource pattern: Lambda Function → Provider → CustomResource
+- Expose outputs as `public readonly` properties via `cr.getAttString("AttrName")`
+
+## Error Handling
+
+- **Constructor validation**: throw `new Error(...)` with clear messages for invalid props (regex checks, length limits)
+- **Handler errors**: include HTTP status and response text: `throw new Error(\`Failed to create: ${response.status} ${errorText}\`)`
+- **Environment checks**: throw early if required env vars are missing
+- **Idempotent deletes**: tolerate 404 on delete operations
+- **Graceful handling**: skip delete for unknown/failed physical resource IDs
+
+## Testing Patterns
+
+- Use `describe("ClassName", () => { ... })` as outer wrapper
+- Use **`test()`** (not `it()`) for individual cases
+- Test names are descriptive sentences: `"creates custom resource with correct properties"`
 
-## Code Style (enforced by ESLint)
+### Construct Tests
+- Helper function `createStack()` at top of describe block for shared setup
+- CDK assertions: `Template.fromStack(stack)`, `template.hasResource()`, `template.hasResourceProperties()`
+- Partial matching: `Match.arrayWith([...])`, `Match.objectLike({...})`
+- Validation tests: `expect(() => { ... }).toThrow("exact message")`
+- Import constructs from barrel: `import { TursoDatabase } from "../src"`
 
-- 2-space indentation, single quotes, semicolons required
-- 150-char max line length
-- Member ordering: public → protected → private; static → instance
-- Import ordering: builtin → external, alphabetized
-- Strict TypeScript: `noImplicitAny`, `strictNullChecks`, target ES2020
+### Handler Tests
+- `jest.mock()` at file top level, before imports
+- Mock `global.fetch` per test: `global.fetch = jest.fn()`
+- `beforeEach`: clear mocks, set env vars, configure default mock responses
+- `afterEach`: clean up env vars
+- Async error assertions: `await expect(handler(...)).rejects.toThrow("message")`
+- Argument checking: `expect(mockFetch).toHaveBeenCalledWith(url, expect.objectContaining({...}))`

package/API.md

@@ -2,6 +2,118 @@
 
 ## Constructs <a name="Constructs" id="Constructs"></a>
 
+### TursoAuthToken <a name="TursoAuthToken" id="cdk-turso.TursoAuthToken"></a>
+
+#### Initializers <a name="Initializers" id="cdk-turso.TursoAuthToken.Initializer"></a>
+
+```typescript
+import { TursoAuthToken } from 'cdk-turso'
+
+new TursoAuthToken(scope: Construct, id: string, props: TursoAuthTokenProps)
+```
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#cdk-turso.TursoAuthToken.Initializer.parameter.scope">scope</a></code> | <code>constructs.Construct</code> | *No description.* |
+| <code><a href="#cdk-turso.TursoAuthToken.Initializer.parameter.id">id</a></code> | <code>string</code> | *No description.* |
+| <code><a href="#cdk-turso.TursoAuthToken.Initializer.parameter.props">props</a></code> | <code><a href="#cdk-turso.TursoAuthTokenProps">TursoAuthTokenProps</a></code> | *No description.* |
+
+---
+
+##### `scope`<sup>Required</sup> <a name="scope" id="cdk-turso.TursoAuthToken.Initializer.parameter.scope"></a>
+
+- *Type:* constructs.Construct
+
+---
+
+##### `id`<sup>Required</sup> <a name="id" id="cdk-turso.TursoAuthToken.Initializer.parameter.id"></a>
+
+- *Type:* string
+
+---
+
+##### `props`<sup>Required</sup> <a name="props" id="cdk-turso.TursoAuthToken.Initializer.parameter.props"></a>
+
+- *Type:* <a href="#cdk-turso.TursoAuthTokenProps">TursoAuthTokenProps</a>
+
+---
+
+#### Methods <a name="Methods" id="Methods"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#cdk-turso.TursoAuthToken.toString">toString</a></code> | Returns a string representation of this construct. |
+
+---
+
+##### `toString` <a name="toString" id="cdk-turso.TursoAuthToken.toString"></a>
+
+```typescript
+public toString(): string
+```
+
+Returns a string representation of this construct.
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#cdk-turso.TursoAuthToken.isConstruct">isConstruct</a></code> | Checks if `x` is a construct. |
+
+---
+
+##### ~~`isConstruct`~~ <a name="isConstruct" id="cdk-turso.TursoAuthToken.isConstruct"></a>
+
+```typescript
+import { TursoAuthToken } from 'cdk-turso'
+
+TursoAuthToken.isConstruct(x: any)
+```
+
+Checks if `x` is a construct.
+
+###### `x`<sup>Required</sup> <a name="x" id="cdk-turso.TursoAuthToken.isConstruct.parameter.x"></a>
+
+- *Type:* any
+
+Any object.
+
+---
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#cdk-turso.TursoAuthToken.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
+| <code><a href="#cdk-turso.TursoAuthToken.property.parameterName">parameterName</a></code> | <code>string</code> | The SSM parameter name where the auth token is stored. |
+
+---
+
+##### `node`<sup>Required</sup> <a name="node" id="cdk-turso.TursoAuthToken.property.node"></a>
+
+```typescript
+public readonly node: Node;
+```
+
+- *Type:* constructs.Node
+
+The tree node.
+
+---
+
+##### `parameterName`<sup>Required</sup> <a name="parameterName" id="cdk-turso.TursoAuthToken.property.parameterName"></a>
+
+```typescript
+public readonly parameterName: string;
+```
+
+- *Type:* string
+
+The SSM parameter name where the auth token is stored.
+
+---
+
+
 ### TursoDatabase <a name="TursoDatabase" id="cdk-turso.TursoDatabase"></a>
 
 #### Initializers <a name="Initializers" id="cdk-turso.TursoDatabase.Initializer"></a>
@@ -85,9 +197,11 @@ Any object.
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <code><a href="#cdk-turso.TursoDatabase.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
+| <code><a href="#cdk-turso.TursoDatabase.property.apiToken">apiToken</a></code> | <code>aws-cdk-lib.aws_ssm.IParameter</code> | *No description.* |
 | <code><a href="#cdk-turso.TursoDatabase.property.databaseName">databaseName</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#cdk-turso.TursoDatabase.property.dbId">dbId</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#cdk-turso.TursoDatabase.property.hostname">hostname</a></code> | <code>string</code> | DNS hostname for the database (e.g., `my-db-my-org.turso.io`). Use with libSQL or HTTP connections. |
+| <code><a href="#cdk-turso.TursoDatabase.property.organizationSlug">organizationSlug</a></code> | <code>string</code> | *No description.* |
 
 ---
 
@@ -103,6 +217,16 @@ The tree node.
 
 ---
 
+##### `apiToken`<sup>Required</sup> <a name="apiToken" id="cdk-turso.TursoDatabase.property.apiToken"></a>
+
+```typescript
+public readonly apiToken: IParameter;
+```
+
+- *Type:* aws-cdk-lib.aws_ssm.IParameter
+
+---
+
 ##### `databaseName`<sup>Required</sup> <a name="databaseName" id="cdk-turso.TursoDatabase.property.databaseName"></a>
 
 ```typescript
@@ -135,9 +259,90 @@ DNS hostname for the database (e.g., `my-db-my-org.turso.io`). Use with libSQL o
 
 ---
 
+##### `organizationSlug`<sup>Required</sup> <a name="organizationSlug" id="cdk-turso.TursoDatabase.property.organizationSlug"></a>
+
+```typescript
+public readonly organizationSlug: string;
+```
+
+- *Type:* string
+
+---
+
 
 ## Structs <a name="Structs" id="Structs"></a>
 
+### TursoAuthTokenProps <a name="TursoAuthTokenProps" id="cdk-turso.TursoAuthTokenProps"></a>
+
+#### Initializer <a name="Initializer" id="cdk-turso.TursoAuthTokenProps.Initializer"></a>
+
+```typescript
+import { TursoAuthTokenProps } from 'cdk-turso'
+
+const tursoAuthTokenProps: TursoAuthTokenProps = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#cdk-turso.TursoAuthTokenProps.property.database">database</a></code> | <code><a href="#cdk-turso.TursoDatabase">TursoDatabase</a></code> | The Turso database to create an auth token for. |
+| <code><a href="#cdk-turso.TursoAuthTokenProps.property.parameterName">parameterName</a></code> | <code>string</code> | The SSM parameter name where the generated JWT will be stored as a SecureString. |
+| <code><a href="#cdk-turso.TursoAuthTokenProps.property.authorization">authorization</a></code> | <code>string</code> | Authorization level for the token. |
+| <code><a href="#cdk-turso.TursoAuthTokenProps.property.expiration">expiration</a></code> | <code>string</code> | Expiration time for the token (e.g., `"2w"`, `"1d30m"`). |
+
+---
+
+##### `database`<sup>Required</sup> <a name="database" id="cdk-turso.TursoAuthTokenProps.property.database"></a>
+
+```typescript
+public readonly database: TursoDatabase;
+```
+
+- *Type:* <a href="#cdk-turso.TursoDatabase">TursoDatabase</a>
+
+The Turso database to create an auth token for.
+
+---
+
+##### `parameterName`<sup>Required</sup> <a name="parameterName" id="cdk-turso.TursoAuthTokenProps.property.parameterName"></a>
+
+```typescript
+public readonly parameterName: string;
+```
+
+- *Type:* string
+
+The SSM parameter name where the generated JWT will be stored as a SecureString.
+
+---
+
+##### `authorization`<sup>Optional</sup> <a name="authorization" id="cdk-turso.TursoAuthTokenProps.property.authorization"></a>
+
+```typescript
+public readonly authorization: string;
+```
+
+- *Type:* string
+- *Default:* "full-access"
+
+Authorization level for the token.
+
+---
+
+##### `expiration`<sup>Optional</sup> <a name="expiration" id="cdk-turso.TursoAuthTokenProps.property.expiration"></a>
+
+```typescript
+public readonly expiration: string;
+```
+
+- *Type:* string
+- *Default:* "never"
+
+Expiration time for the token (e.g., `"2w"`, `"1d30m"`).
+
+---
+
 ### TursoDatabaseEncryption <a name="TursoDatabaseEncryption" id="cdk-turso.TursoDatabaseEncryption"></a>
 
 #### Initializer <a name="Initializer" id="cdk-turso.TursoDatabaseEncryption.Initializer"></a>

package/README.md

@@ -36,6 +36,24 @@ database.hostname; // Database hostname
 database.databaseName; // Database name
 ```
 
+### Auth Token
+
+Generate a database auth token and store it as a SecureString in SSM Parameter Store:
+
+```typescript
+import { TursoAuthToken } from 'cdk-turso';
+
+const authToken = new TursoAuthToken(stack, 'AuthToken', {
+  database,
+  parameterName: '/turso/db-token',
+  expiration: '2w',          // optional, default: 'never'
+  authorization: 'read-only', // optional, default: 'full-access'
+});
+
+// The SSM parameter name where the JWT is stored
+authToken.parameterName;
+```
+
 ## API
 
 ### TursoDatabaseProps
@@ -76,6 +94,23 @@ interface TursoDatabaseEncryption {
 | `dbId` | `string` | Turso database ID |
 | `hostname` | `string` | DNS hostname (e.g., `my-db-my-org.turso.io`) for libSQL/HTTP connections |
 | `databaseName` | `string` | Database name |
+| `organizationSlug` | `string` | Organization slug |
+| `apiToken` | `ssm.IParameter` | SSM Parameter containing the Turso API token |
+
+### TursoAuthTokenProps
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `database` | `TursoDatabase` | Yes | The Turso database to create an auth token for |
+| `parameterName` | `string` | Yes | SSM parameter name where the generated JWT will be stored as a SecureString |
+| `expiration` | `string` | No | Token expiry (e.g., `'2w'`, `'1d30m'`). Default: `'never'` |
+| `authorization` | `string` | No | `'full-access'` or `'read-only'`. Default: `'full-access'` |
+
+### TursoAuthToken
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `parameterName` | `string` | The SSM parameter name where the auth token is stored |
 
 ## Requirements