# Keystone Identity Policies & Fluent Builder

This module manages Keystone Identity Policies, including security preset profiles (`high`, `medium`, `low`), modular schema composition, and the fluent configuration builder.

---

## 📖 Documentation Index

*   **[Policy Architecture](../../../../../docs/identity/ARCHITECTURE.md)**: Conceptual design of separate pool behaviors, verbs, and composed schemas.
*   **[Implementation Roadmap](./IMPLEMENTATION.md)**: Current development checklist and tasks.

---

## 🛠️ Usage: Fluent Builder API

The `KeystoneProfileBuilder` provides a fluid interface to construct, enrich, and customize Keystone configurations before genesis.

### Basic Identity Creation

```typescript
import { KeystoneProfileBuilder } from "@ibgib/core-gib/dist/keystone/policy/keystone-profile-builder.mjs";

// Build a medium-security identity config salted for a specific user
const configs = KeystoneProfileBuilder
    .buildKeystone('medium')
    .withUsername('alice')
    .withEmail('alice@example.com')
    .withDescription('Main user identity for Space-Gib')
    .compileConfigs();

// Pass these configurations directly to genesis
const identity = await keystoneService.genesis({
    masterSecret,
    configs,
    metaspace,
    space
});
```

### Unifying Identity Details

The metadata provided to `withUsername`, `withEmail`, `withDescription`, and `withDetails` are automatically consolidated into the unified `frameDetails` field of the genesis frame:

```typescript
const configs = KeystoneProfileBuilder
    .buildKeystone('low')
    .withUsername('bob')
    .withDetails({
        device: 'Pixel 8 Pro',
        os: 'Android 14'
    })
    .compileConfigs();
```

### Runtime Customizations

If an application needs to customize a specific pool's parameters dynamically (for example, raising KDF hash rounds on the sync pool for higher-security environments), use `customizePool`:

```typescript
const configs = KeystoneProfileBuilder
    .buildKeystone('medium')
    .withUsername('charlie')
    .customizePool('sync', {
        rounds: 5, // Override base medium profile rounds
    })
    .compileConfigs();
```

---

## ⚠️ TypeScript & JSON Config Integration

If downstream projects import or load their own JSON configurations (e.g., custom `.json` files representing schemas or behavior configurations) rather than relying solely on the built-in profiles, TypeScript requires explicit path tracking in projects using `"composite": true`.

To prevent compiler errors like `TS6307: File '...' is not listed within the file list...`, ensure your project's `tsconfig.json` contains:

1. `"resolveJsonModule": true` under `compilerOptions` to allow static importing of JSON files as ES modules.
2. The folder/wildcard path of the JSON files added to the `"include"` array. For example:

```json
{
  "compilerOptions": {
    "composite": true,
    "resolveJsonModule": true,
    "module": "ESNext"
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.mts",
    "src/custom-policies/*.json"
  ]
}
```

