### Example auth.json for ERR_INVALID_URL

Source: https://github.com/tickernelz/opencode-kiro-auth/blob/master/README.md

An example of the `auth.json` file structure to check when encountering an ERR_INVALID_URL error. Ensure the 'kiro' object and 'key' are correctly formatted.

```json
{
  "kiro": {
    "type": "api",
    "key": "whatever"
  }
}
```

--------------------------------

### Install Kiro Auth Plugin in OpenCode

Source: https://github.com/tickernelz/opencode-kiro-auth/blob/master/README.md

Add the '@zhafron/opencode-kiro-auth' plugin to your opencode.json or opencode.jsonc file. This configuration also sets up the 'kiro' provider with multiple Claude model definitions.

```json
{
  "plugin": ["@zhafron/opencode-kiro-auth"],
  "provider": {
    "kiro": {
      "models": {
        "claude-sonnet-4-5": {
          "name": "Claude Sonnet 4.5",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-sonnet-4-5-thinking": {
          "name": "Claude Sonnet 4.5 Thinking",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
            "medium": { "thinkingConfig": { "thinkingBudget": 16384 } },
            "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
          }
        },
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-sonnet-4-6-thinking": {
          "name": "Claude Sonnet 4.6 Thinking",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
            "medium": { "thinkingConfig": { "thinkingBudget": 16384 } },
            "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
          }
        },
        "claude-haiku-4-5": {
          "name": "Claude Haiku 4.5",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "claude-opus-4-5": {
          "name": "Claude Opus 4.5",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-opus-4-5-thinking": {
          "name": "Claude Opus 4.5 Thinking",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
            "medium": { "thinkingConfig": { "thinkingBudget": 16384 } },
            "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
          }
        },
        "claude-opus-4-6": {
          "name": "Claude Opus 4.6",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-opus-4-6-thinking": {
          "name": "Claude Opus 4.6 Thinking",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
            "medium": { "thinkingConfig": { "thinkingBudget": 16384 } },
            "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
          }
        },
        "claude-opus-4-6-1m": {
          "name": "Claude Opus 4.6 (1M Context)",
          "limit": { "context": 1000000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-opus-4-6-1m-thinking": {
          "name": "Claude Opus 4.6 (1M Context) Thinking",
          "limit": { "context": 1000000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
            "medium": { "thinkingConfig": { "thinkingBudget": 16384 } },
            "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
          }
        },
        "claude-sonnet-4-5-1m": {
          "name": "Claude Sonnet 4.5 (1M Context)",
          "limit": { "context": 1000000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-sonnet-4-6-1m": {
          "name": "Claude Sonnet 4.6 (1M Context)",
          "limit": { "context": 1000000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-sonnet-4-6-1m-thinking": {
          "name": "Claude Sonnet 4.6 (1M Context) Thinking",
          "limit": { "context": 1000000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
            "medium": { "thinkingConfig": { "thinkingBudget": 16384 } },
            "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
          }
        },
        "auto": { "name": "Auto (1.0x)" }
      }
    }
  }
}
```

--------------------------------

### Initiate Device Code Authentication

Source: https://context7.com/tickernelz/opencode-kiro-auth/llms.txt

Starts the OAuth device code flow for AWS Builder ID or IAM Identity Center. Requires AWS region and the start URL for your company's AWS SSO instance. Returns verification URLs and device codes for user authorization.

```typescript
import { authorizeKiroIDC } from '@zhafron/opencode-kiro-auth';

// Start device authorization flow
const authResult = await authorizeKiroIDC('us-east-1', 'https://your-company.awsapps.com/start');

console.log('Verification URL:', authResult.verificationUriComplete);
console.log('User Code:', authResult.userCode);
console.log('Device Code:', authResult.deviceCode);
console.log('Expires In:', authResult.expiresIn, 'seconds');
```

--------------------------------

### Configure Kiro Provider in opencode.json

Source: https://context7.com/tickernelz/opencode-kiro-auth/llms.txt

Add the Kiro auth plugin to your opencode.json and configure the available Claude models. This setup enables the plugin to manage access to different Claude AI versions.

```json
{
  "plugin": ["@zhafron/opencode-kiro-auth"],
  "provider": {
    "kiro": {
      "models": {
        "claude-sonnet-4-5": {
          "name": "Claude Sonnet 4.5",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-sonnet-4-5-thinking": {
          "name": "Claude Sonnet 4.5 Thinking",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
            "medium": { "thinkingConfig": { "thinkingBudget": 16384 } },
            "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
          }
        },
        "claude-haiku-4-5": {
          "name": "Claude Haiku 4.5",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "claude-opus-4-5": {
          "name": "Claude Opus 4.5",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-sonnet-4-5-1m": {
          "name": "Claude Sonnet 4.5 (1M Context)",
          "limit": { "context": 1000000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        }
      }
    }
  }
}
```

--------------------------------

### Manage Multiple Accounts with Strategies

Source: https://context7.com/tickernelz/opencode-kiro-auth/llms.txt

Loads accounts from disk using a specified selection strategy (e.g., 'lowest-usage'). Supports adding new accounts, updating usage statistics, marking accounts as rate-limited or unhealthy, and saving account data.

```typescript
import { AccountManager } from '@zhafron/opencode-kiro-auth';
import type { ManagedAccount, AccountSelectionStrategy } from '@zhafron/opencode-kiro-auth';

// Load accounts from disk with selection strategy
const accountManager = await AccountManager.loadFromDisk('lowest-usage');

// Get account count and list
console.log('Total accounts:', accountManager.getAccountCount());
const accounts = accountManager.getAccounts();

// Select next healthy account based on strategy
const selectedAccount = accountManager.getCurrentOrNext();
if (selectedAccount) {
  console.log('Selected:', selectedAccount.email);
  console.log('Usage:', selectedAccount.usedCount, '/', selectedAccount.limitCount);
}

// Add a new account
const newAccount: ManagedAccount = {
  id: 'unique-account-id',
  email: 'user@example.com',
  authMethod: 'idc',
  region: 'us-east-1',
  refreshToken: 'refresh-token',
  accessToken: 'access-token',
  expiresAt: Date.now() + 3600000,
  rateLimitResetTime: 0,
  isHealthy: true,
  failCount: 0,
  usedCount: 0,
  limitCount: 1000
};
accountManager.addAccount(newAccount);

// Update usage statistics
accountManager.updateUsage('account-id', {
  usedCount: 50,
  limitCount: 1000,
  email: 'user@example.com'
});

// Mark account as rate limited (cooldown period)
accountManager.markRateLimited(selectedAccount, 60000); // 60 second cooldown

// Mark account as unhealthy with recovery time
accountManager.markUnhealthy(selectedAccount, 'Token expired', Date.now() + 300000);

// Save all accounts to disk
await accountManager.saveToDisk();
```

--------------------------------

### Initialize Kiro OAuth Plugin

Source: https://context7.com/tickernelz/opencode-kiro-auth/llms.txt

Import and use `KiroOAuthPlugin` or `createKiroPlugin` to integrate the Kiro authentication provider into OpenCode. The plugin handles session synchronization, token refresh, and request routing automatically.

```typescript
import { KiroOAuthPlugin, createKiroPlugin } from '@zhafron/opencode-kiro-auth';

// Default plugin instance for the 'kiro' provider
export { KiroOAuthPlugin };

// Custom plugin creation with a different provider ID
const customKiroPlugin = createKiroPlugin('my-kiro-provider');

// Plugin is loaded by OpenCode and returns auth configuration
// The plugin automatically:
// - Syncs sessions from kiro-cli on initialization
// - Manages token refresh before expiration
// - Handles request routing through healthy accounts
// - Provides OAuth methods for authentication
```

--------------------------------

### Hot-swap Local Plugin Dist Folder

Source: https://github.com/tickernelz/opencode-kiro-auth/blob/master/README.md

Use this script to replace the cached plugin's dist folder with your local build for testing. It creates a timestamped backup before replacing.

```bash
PLUGIN_DIR="$HOME/.cache/opencode/node_modules/@zhafron/opencode-kiro-auth"
TS=$(date +%Y%m%d-%H%M%S)
cp -a "$PLUGIN_DIR/dist" "$PLUGIN_DIR/dist.bak.$TS"
rm -rf "$PLUGIN_DIR/dist"
cp -a "/absolute/path/to/opencode-kiro-auth/dist" "$PLUGIN_DIR/dist"
echo "Backup at: $PLUGIN_DIR/dist.bak.$TS"
```

--------------------------------

### OpenCode Kiro Plugin Configuration

Source: https://github.com/tickernelz/opencode-kiro-auth/blob/master/README.md

The main configuration file for the OpenCode Kiro plugin. Adjust settings like auto-sync, account selection, regions, and timeouts.

```json
{
  "auto_sync_kiro_cli": true,
  "account_selection_strategy": "lowest-usage",
  "default_region": "us-east-1",
  "idc_start_url": "https://your-company.awsapps.com/start",
  "idc_region": "us-east-1",
  "rate_limit_retry_delay_ms": 5000,
  "rate_limit_max_retries": 3,
  "max_request_iterations": 20,
  "request_timeout_ms": 120000,
  "token_expiry_buffer_ms": 120000,
  "usage_sync_max_retries": 3,
  "usage_tracking_enabled": true,
  "enable_log_api_request": false
}
```

--------------------------------

### Configure via Environment Variables

Source: https://context7.com/tickernelz/opencode-kiro-auth/llms.txt

Override all configuration options using environment variables. This is particularly useful for CI/CD pipelines and containerized deployments where direct configuration file access might be limited.

```bash
# Account selection strategy: sticky, round-robin, or lowest-usage
export KIRO_ACCOUNT_SELECTION_STRATEGY="lowest-usage"

# Default AWS region for API calls
export KIRO_DEFAULT_REGION="us-east-1"

# Rate limiting configuration
export KIRO_RATE_LIMIT_RETRY_DELAY_MS="5000"
export KIRO_RATE_LIMIT_MAX_RETRIES="3"

# Request configuration
export KIRO_MAX_REQUEST_ITERATIONS="20"
export KIRO_REQUEST_TIMEOUT_MS="120000"

# Token refresh buffer (refresh tokens this many ms before expiry)
export KIRO_TOKEN_EXPIRY_BUFFER_MS="300000"

# Usage tracking and logging
export KIRO_USAGE_TRACKING_ENABLED="true"
export KIRO_ENABLE_LOG_API_REQUEST="false"

# Usage sync retries
export KIRO_USAGE_SYNC_MAX_RETRIES="3"
```

--------------------------------

### Add Kiro Auth Placeholder

Source: https://github.com/tickernelz/opencode-kiro-auth/blob/master/README.md

Add a minimal placeholder entry to `auth.json` to resolve issues where the plugin sync never triggers for Google/GitHub OAuth users. This ensures OpenCode treats the provider as connected.

```json
{
  "kiro": {
    "type": "api",
    "key": "placeholder"
  }
}
```

--------------------------------

### Configure Kiro Behavior in kiro.json

Source: https://context7.com/tickernelz/opencode-kiro-auth/llms.txt

Customize the plugin's behavior by setting options in `~/.config/opencode/kiro.json`. This file allows for user-level, project-level, and environment variable overrides for various settings.

```json
{
  "auto_sync_kiro_cli": true,
  "account_selection_strategy": "lowest-usage",
  "default_region": "us-east-1",
  "idc_start_url": "https://your-company.awsapps.com/start",
  "idc_region": "us-east-1",
  "idc_profile_arn": "arn:aws:iam::123456789012:role/QDevProfile",
  "rate_limit_retry_delay_ms": 5000,
  "rate_limit_max_retries": 3,
  "max_request_iterations": 20,
  "request_timeout_ms": 120000,
  "token_expiry_buffer_ms": 300000,
  "usage_sync_max_retries": 3,
  "usage_tracking_enabled": true,
  "enable_log_api_request": false
}
```

--------------------------------

### Synchronize Kiro CLI Authentication Sessions

Source: https://context7.com/tickernelz/opencode-kiro-auth/llms.txt

Automatically synchronize authentication sessions from the local Kiro CLI database into the plugin's SQLite database. Supports bidirectional synchronization by writing updated tokens back to the Kiro CLI.

```typescript
import { syncFromKiroCli, writeToKiroCli } from '@zhafron/opencode-kiro-auth';

// Sync all sessions from kiro-cli database
// Reads from: ~/Library/Application Support/kiro-cli/data.db (macOS)
//            ~/.config/kiro-cli/data.db (Linux)
//            %APPDATA%/kiro-cli/data.db (Windows)
await syncFromKiroCli();

// After sync, accounts are available in the plugin's SQLite database
// Located at: ~/.config/opencode/kiro.db

// Write updated tokens back to kiro-cli (bidirectional sync)
const account = {
  id: 'account-id',
  authMethod: 'idc',
  accessToken: 'new-access-token',
  refreshToken: 'new-refresh-token',
  expiresAt: Date.now() + 3600000
};
await writeToKiroCli(account);
```

--------------------------------

### Revert Local Plugin Dist Folder

Source: https://github.com/tickernelz/opencode-kiro-auth/blob/master/README.md

Use this script to revert to a previous version of the plugin's dist folder by restoring the timestamped backup.

```bash
PLUGIN_DIR="$HOME/.cache/opencode/node_modules/@zhafron/opencode-kiro-auth"
rm -rf "$PLUGIN_DIR/dist"
mv "$PLUGIN_DIR/dist.bak.YYYYMMDD-HHMMSS" "$PLUGIN_DIR/dist"
```

--------------------------------

### Model Resolution and Mapping

Source: https://context7.com/tickernelz/opencode-kiro-auth/llms.txt

Provides utilities for mapping user-friendly model names to AWS CodeWhisperer identifiers and checking model context window sizes. Supports standard and thinking variants.

```typescript
import { MODEL_MAPPING, SUPPORTED_MODELS, isLongContextModel } from '@zhafron/opencode-kiro-auth';

// Available model mappings
console.log('Supported models:', SUPPORTED_MODELS);
// ['claude-haiku-4-5', 'claude-sonnet-4-5', 'claude-sonnet-4-5-thinking',
//  'claude-opus-4-5', 'claude-sonnet-4-5-1m', 'auto', 'deepseek-3.2', ...]

// Model name resolution
const kiroModelId = MODEL_MAPPING['claude-sonnet-4-5'];  // 'claude-sonnet-4.5'
const thinkingModel = MODEL_MAPPING['claude-sonnet-4-5-thinking'];  // 'claude-sonnet-4.5'

// Check for 1M context models
console.log(isLongContextModel('claude-sonnet-4-5'));     // false (200K)
console.log(isLongContextModel('claude-sonnet-4-5-1m')); // true (1M)
```

--------------------------------

### Define ManagedAccount Type Structure

Source: https://context7.com/tickernelz/opencode-kiro-auth/llms.txt

Illustrates the structure of the ManagedAccount type, which holds authentication credentials, health status, and usage tracking for AWS accounts. Ensure all required fields are populated for proper functionality.

```typescript
import type { ManagedAccount, KiroAuthMethod, KiroRegion } from '@zhafron/opencode-kiro-auth';

const account: ManagedAccount = {
  // Unique identifier (SHA-256 hash of email + method + clientId + profileArn)
  id: 'deterministic-unique-id',

  // User email (or placeholder for IAM Identity Center)
  email: 'user@example.com',

  // Authentication method: 'idc' (Identity Center) or 'desktop' (Builder ID)
  authMethod: 'idc' as KiroAuthMethod,

  // AWS region for API calls (derived from profileArn or default)
  region: 'us-east-1' as KiroRegion,

  // OIDC region for token refresh (may differ from API region)
  oidcRegion: 'us-east-1' as KiroRegion,

  // OIDC client credentials (required for IDC)
  clientId: 'oidc-client-id',
  clientSecret: 'oidc-client-secret',

  // IAM Identity Center profile ARN (optional, for IDC accounts)
  profileArn: 'arn:aws:iam::123456789012:role/QDevProfile',

  // Identity Center start URL (optional)
  startUrl: 'https://your-company.awsapps.com/start',

  // OAuth tokens
  refreshToken: 'refresh-token-string',
  accessToken: 'access-token-string',
  expiresAt: Date.now() + 3600000,  // Token expiration timestamp

  // Rate limiting
  rateLimitResetTime: 0,  // Timestamp when rate limit resets

  // Health tracking
  isHealthy: true,
  unhealthyReason: undefined,  // Error message if unhealthy
  recoveryTime: undefined,     // Timestamp when account can be retried
  failCount: 0,                // Consecutive failure count

  // Usage tracking
  usedCount: 50,    // Requests used this period
  limitCount: 1000, // Total request limit
  lastSync: Date.now(),  // Last usage sync timestamp
  lastUsed: Date.now()   // Last request timestamp
};
```

--------------------------------

### Transform OpenAI Request to AWS CodeWhisperer SDK Format

Source: https://context7.com/tickernelz/opencode-kiro-auth/llms.txt

Use this function to convert OpenAI-compatible chat completion requests into the format required by the AWS CodeWhisperer API. It handles message history, tool calls, and supports enabling 'thinking mode' with a specified token budget.

```typescript
import { transformToSdkRequest } from '@zhafron/opencode-kiro-auth';
import type { KiroAuthDetails, SdkPreparedRequest } from '@zhafron/opencode-kiro-auth';

const auth: KiroAuthDetails = {
  refresh: 'encoded-refresh-token',
  access: 'access-token',
  expires: Date.now() + 3600000,
  authMethod: 'idc',
  region: 'us-east-1',
  profileArn: 'arn:aws:iam::123456789012:role/QDevProfile'
};

const openAIRequest = {
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Write a hello world in Python' }
  ],
  tools: [{
    type: 'function',
    function: {
      name: 'execute_code',
      description: 'Execute Python code',
      parameters: { type: 'object', properties: { code: { type: 'string' } } }
    }
  }]
};

// Transform with thinking mode enabled
const sdkRequest: SdkPreparedRequest = transformToSdkRequest(
  openAIRequest,
  'claude-sonnet-4-5-thinking',
  auth,
  true,   // thinking mode enabled
  20000   // thinking budget tokens
);

// Result structure:
// {
//   conversationState: {
//     chatTriggerType: 'MANUAL',
//     conversationId: 'uuid',
//     history: [...],
//     currentMessage: { userInputMessage: {...} }
//   },
//   profileArn: 'arn:aws:iam::...',
//   streaming: true,
//   effectiveModel: 'claude-sonnet-4.5',
//   conversationId: 'uuid',
//   region: 'us-east-1'
// }
```

--------------------------------

### Manage OIDC Refresh Tokens and Access Token Expiry

Source: https://context7.com/tickernelz/opencode-kiro-auth/llms.txt

Encode and decode OIDC refresh tokens for AWS Builder ID or IAM Identity Center. Check if an access token has expired, including a configurable buffer period to proactively refresh.

```typescript
import {
  encodeRefreshToken,
  decodeRefreshToken,
  accessTokenExpired
} from '@zhafron/opencode-kiro-auth';
import type { KiroAuthDetails, RefreshParts } from '@zhafron/opencode-kiro-auth';

// Encode refresh token with credentials for IDC
const idcParts: RefreshParts = {
  refreshToken: 'actual-refresh-token',
  clientId: 'oidc-client-id',
  clientSecret: 'oidc-client-secret',
  authMethod: 'idc'
};
const encodedToken = encodeRefreshToken(idcParts);
// Result: 'actual-refresh-token|oidc-client-id|oidc-client-secret|idc'

// Decode refresh token back to parts
const decoded = decodeRefreshToken(encodedToken);
console.log(decoded.authMethod);  // 'idc'
console.log(decoded.clientId);    // 'oidc-client-id'

// Check if access token needs refresh (with 2-minute buffer)
const auth: KiroAuthDetails = {
  access: 'access-token',
  refresh: encodedToken,
  expires: Date.now() + 60000,  // Expires in 1 minute
  authMethod: 'idc',
  region: 'us-east-1'
};

const needsRefresh = accessTokenExpired(auth, 120000);  // true (within 2-minute buffer)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.