@fulmenhq/tsfulmen 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Fulpack Module** (`@fulmenhq/tsfulmen/fulpack`) - Security-first archive operations for TAR, TAR.GZ, ZIP, and GZIP formats
+  - **Five Canonical Operations**:
+    - `create()` - Create archives from files/directories with configurable compression
+    - `extract()` - Extract archives with comprehensive security checks
+    - `scan()` - List archive contents without extraction (Pathfinder integration backend)
+    - `verify()` - Validate archive integrity and security before extraction
+    - `info()` - Get quick archive metadata (format, size, compression ratio)
+  - **Security-First Design**:
+    - Path traversal protection (rejects `../` and absolute paths)
+    - Decompression bomb detection (size/ratio/entry count limits)
+    - Symlink safety validation (prevents directory escapes)
+    - Checksum verification via fulhash integration (SHA-256, xxh3-128)
+  - **Four Archive Formats**:
+    - TAR (uncompressed) - Maximum speed for pre-compressed data
+    - TAR.GZ (gzip) - General purpose with best compatibility
+    - ZIP (deflate) - Windows compatibility and random access
+    - GZIP - Single file compression
+  - **Pathfinder Integration**: `scan()` serves as backend for archive discovery
+  - **Comprehensive Documentation**: Full API reference, security guide, format selection guide, and usage examples
+  - **Test Coverage**: 20 tests covering all operations and security checks
+  - **Error Handling**: Structured `FulpackOperationError` with operation context and security violation details
+
+- **Pathfinder Repository Root Discovery** (`findRepositoryRoot`) - Secure upward traversal to find repository markers
+  - **Security-First Design**:
+    - Boundary enforcement (home directory/explicit/filesystem root)
+    - Max depth limiting (default 10 levels)
+    - Symlink loop detection (opt-in with `followSymlinks=true`)
+    - Path constraint validation for workspace boundaries
+    - Cross-platform support (POSIX root, Windows drives, UNC paths)
+  - **Predefined Marker Sets**: GitMarkers, NodeMarkers, PythonMarkers, GoModMarkers, MonorepoMarkers
+  - **Flexible Search**: Stop at first marker (default) or find deepest (monorepo root)
+  - **Helper Functions**: `withMaxDepth`, `withBoundary`, `withStopAtFirst`, `withConstraint`, `withFollowSymlinks`
+  - **Comprehensive Errors**: Structured errors with codes (REPOSITORY_NOT_FOUND, INVALID_BOUNDARY, TRAVERSAL_LOOP, etc.)
+  - **Test Coverage**: 26 tests covering security, boundary enforcement, and cross-platform behavior
+  - **Complete Documentation**: Full pathfinder README with API reference, safe usage patterns, and migration guide
+
 ---
 
 ## [0.1.8] - 2025-11-08

package/README.md

@@ -9,10 +9,10 @@ TypeScript Fulmen helper library for enterprise-scale development.
 ## Status
 
 **Lifecycle Phase:** `alpha` (see [`LIFECYCLE_PHASE`](LIFECYCLE_PHASE))
-**Development Status:** ✅ v0.1.5 - Signal handling, app identity, and FulHash optimization
-**Test Coverage:** 1465 tests passing (100% pass rate, 1481 total)
+**Development Status:** ✅ v0.1.9 - Fulpack archives, pathfinder repository root discovery
+**Test Coverage:** 1638 tests passing (100% pass rate)
 
-TSFulmen v0.1.5 adds cross-platform signal handling with graceful shutdown patterns, complete application identity module, and 22x FulHash performance improvement. See [TSFulmen Overview](docs/tsfulmen_overview.md) for roadmap.
+TSFulmen v0.1.9 adds security-first archive operations (fulpack) for TAR/TAR.GZ/ZIP/GZIP formats and repository root discovery (pathfinder) with boundary enforcement. See [TSFulmen Overview](docs/tsfulmen_overview.md) for roadmap.
 
 ## Features
 
@@ -20,6 +20,7 @@ TSFulmen v0.1.5 adds cross-platform signal handling with graceful shutdown patte
 - ✅ **Telemetry & Metrics** - Counter/gauge/histogram with OTLP export (85 tests)
 - ✅ **Telemetry Instrumentation** - Metrics in config, schema, crucible modules (24 tests)
 - ✅ **FulHash** - Fast hashing with XXH3-128 and SHA-256, 22x faster small inputs (157 tests)
+- ✅ **Fulpack** - Archive operations (TAR, TAR.GZ, ZIP, GZIP) with security-first design (20 tests)
 - ✅ **Progressive Logging** - Policy enforcement with Pino profiles (83 tests)
 - ✅ **Crucible Shim** - Typed access to synced schemas, docs, and config defaults (96 tests)
 - ✅ **DocScribe** - Document processing with frontmatter parsing (50+ tests)
@@ -29,7 +30,7 @@ TSFulmen v0.1.5 adds cross-platform signal handling with graceful shutdown patte
 - ✅ **Exit Codes** - Standardized process exit codes with simplified modes and platform detection (34 tests)
 - ✅ **Signal Handling** - Cross-platform signal handling with graceful shutdown and Windows fallback (180 tests)
 - ✅ **Application Identity** - .fulmen/app.yaml discovery with caching and validation (93 tests)
-- ✅ **Pathfinder** - Filesystem traversal with checksums, ignore files, and observability (44 tests)
+- ✅ **Pathfinder** - Filesystem traversal, repository root discovery with security boundaries, checksums, and observability (70 tests)
 - 🚧 **Three-Layer Config Loading** - Defaults → User → BYOC (planned v0.2.x)
 
 ## Installation
@@ -108,6 +109,8 @@ src/
 ├── crucible/    # 🚧 Crucible SSOT shim
 ├── errors/      # ✅ Error handling & propagation
 ├── foundry/     # ✅ Pattern catalogs, HTTP statuses, MIME detection
+├── fulhash/     # ✅ Fast hashing with XXH3-128 and SHA-256
+├── fulpack/     # ✅ Archive operations (TAR, TAR.GZ, ZIP, GZIP)
 ├── logging/     # ✅ Progressive logging with policy enforcement
 ├── pathfinder/  # ✅ Filesystem traversal with checksums and observability
 ├── schema/      # ✅ Schema validation (AJV + CLI)
@@ -515,6 +518,240 @@ const type = await detectMimeType(buffer, {
 });
 ```
 
+### Fulpack - Archive Operations
+
+Secure archive creation, extraction, and inspection with security-first design for TAR, TAR.GZ, ZIP, and GZIP formats.
+
+**Features:**
+
+- Five canonical operations: `create()`, `extract()`, `scan()`, `verify()`, `info()`
+- Four archive formats: TAR (uncompressed), TAR.GZ (gzip), ZIP (deflate), GZIP (single file)
+- Security-first design: path traversal protection, decompression bomb detection, symlink safety validation
+- Checksum verification via fulhash integration (SHA-256, xxh3-128)
+- Pathfinder integration: `scan()` backend for archive discovery
+- Streaming architecture for memory-efficient operations
+
+**Basic Usage:**
+
+```typescript
+import {
+  create,
+  extract,
+  scan,
+  verify,
+  info,
+  ArchiveFormat,
+} from "@fulmenhq/tsfulmen/fulpack";
+
+// Create TAR.GZ archive
+const archiveInfo = await create(
+  "./src", // Source directory
+  "./dist/app.tar.gz", // Output archive
+  ArchiveFormat.TAR_GZ, // Format
+  { compression_level: 9 }, // Options
+);
+
+// Extract archive with security checks
+const result = await extract(
+  "./dist/app.tar.gz", // Archive path
+  "./output", // Destination
+  { overwrite: "skip" }, // Skip existing files
+);
+
+console.log(
+  `Extracted ${result.extracted_count} files, skipped ${result.skipped_count}`,
+);
+```
+
+**Scan Archives (Pathfinder Integration):**
+
+```typescript
+// Scan archive contents without extraction
+const entries = await scan("./data.tar.gz");
+
+// Filter entries using standard JavaScript
+const csvFiles = entries.filter(
+  (e) => e.type === "file" && e.path.endsWith(".csv"),
+);
+console.log(`Found ${csvFiles.length} CSV files`);
+
+// Check for specific files
+const hasConfig = entries.some((e) => e.path === "config/app.json");
+
+// Get total uncompressed size
+const totalSize = entries.reduce((sum, e) => sum + e.size, 0);
+console.log(`Total size: ${(totalSize / 1024 / 1024).toFixed(2)} MB`);
+```
+
+**Security Validation:**
+
+```typescript
+// Verify archive integrity before extraction
+const validation = await verify("./untrusted.tar.gz");
+
+if (!validation.valid) {
+  console.error("Archive validation failed:");
+  validation.errors.forEach((err) =>
+    console.error(`  - ${err.code}: ${err.message}`),
+  );
+  process.exit(1);
+}
+
+// Check security validations performed
+console.log("Security checks:", validation.checks_performed.join(", "));
+// Output: structure_valid, no_path_traversal, symlinks_safe, no_decompression_bomb
+```
+
+**Archive Metadata:**
+
+```typescript
+// Get quick metadata without extraction
+const metadata = await info("./backup.tar.gz");
+
+console.log(`Format: ${metadata.format}`);
+console.log(`Entries: ${metadata.entry_count}`);
+console.log(
+  `Compressed: ${(metadata.compressed_size / 1024 / 1024).toFixed(2)} MB`,
+);
+console.log(
+  `Uncompressed: ${(metadata.total_size / 1024 / 1024).toFixed(2)} MB`,
+);
+console.log(`Ratio: ${metadata.compression_ratio.toFixed(2)}:1`);
+```
+
+**Format Selection:**
+
+```typescript
+// TAR (uncompressed) - Fastest for pre-compressed data
+await create("./images", "./backup.tar", ArchiveFormat.TAR);
+
+// TAR.GZ - General purpose, best compatibility
+await create("./src", "./release.tar.gz", ArchiveFormat.TAR_GZ, {
+  compression_level: 9,
+  exclude_patterns: ["**/*.test.ts", "**/node_modules/**"],
+});
+
+// ZIP - Windows compatibility, random access
+await create(["./config", "./scripts"], "./deploy.zip", ArchiveFormat.ZIP);
+
+// GZIP - Single file compression
+await create("./large-data.csv", "./large-data.csv.gz", ArchiveFormat.GZIP);
+```
+
+### Pathfinder - Repository Root Discovery
+
+Find repository markers (`.git`, `package.json`, etc.) by walking up the directory tree with security-first design, boundary enforcement, and comprehensive error handling.
+
+**Features:**
+
+- Security-first design with boundary enforcement (home directory/explicit/filesystem root ceilings)
+- Max depth limiting (default 10 levels) to prevent excessive traversal
+- Symlink loop detection with opt-in following
+- Path constraint validation for workspace boundaries
+- Cross-platform support (POSIX root, Windows drives, UNC paths)
+- Predefined marker sets for common ecosystems (Git, Node, Python, Go, Monorepo)
+- Structured errors with context for debugging
+
+**Basic Usage:**
+
+```typescript
+import {
+  findRepositoryRoot,
+  GitMarkers,
+  NodeMarkers,
+} from "@fulmenhq/tsfulmen/pathfinder";
+
+// Find Git repository root from current directory
+const gitRoot = await findRepositoryRoot(process.cwd(), GitMarkers);
+console.log(`Git root: ${gitRoot}`);
+
+// Find Node.js project root
+const nodeRoot = await findRepositoryRoot("./src/components", NodeMarkers);
+console.log(`Node root: ${nodeRoot}`);
+```
+
+**Predefined Marker Sets:**
+
+```typescript
+import {
+  GitMarkers, // [".git"]
+  NodeMarkers, // ["package.json", "package-lock.json"]
+  PythonMarkers, // ["pyproject.toml", "setup.py", "requirements.txt", "Pipfile"]
+  GoModMarkers, // ["go.mod"]
+  MonorepoMarkers, // ["lerna.json", "pnpm-workspace.yaml", "nx.json", "turbo.json", "rush.json"]
+} from "@fulmenhq/tsfulmen/pathfinder";
+```
+
+**Security Boundaries:**
+
+```typescript
+import {
+  ConstraintType,
+  EnforcementLevel,
+} from "@fulmenhq/tsfulmen/pathfinder";
+
+// Secure search within project boundary
+const root = await findRepositoryRoot("./src/components", GitMarkers, {
+  boundary: "/home/user/projects/myapp", // Don't search above project
+  constraint: {
+    root: "/home/user/projects", // Enforce workspace constraint
+    type: ConstraintType.WORKSPACE,
+    enforcementLevel: EnforcementLevel.STRICT,
+  },
+});
+```
+
+**Monorepo Support:**
+
+```typescript
+// Find deepest marker (closest to filesystem root) for monorepo roots
+// Directory: /monorepo/.git and /monorepo/packages/app/.git
+
+// stopAtFirst=true (default) - finds /monorepo/packages/app
+const packageRoot = await findRepositoryRoot(
+  "/monorepo/packages/app/src/index.ts",
+  GitMarkers,
+);
+
+// stopAtFirst=false - finds /monorepo (deepest/monorepo root)
+const monorepoRoot = await findRepositoryRoot(
+  "/monorepo/packages/app/src/index.ts",
+  GitMarkers,
+  { stopAtFirst: false },
+);
+```
+
+**Error Handling:**
+
+```typescript
+import { PathfinderErrorCode } from "@fulmenhq/tsfulmen/pathfinder";
+
+try {
+  const root = await findRepositoryRoot("./src", GitMarkers);
+  console.log(`Found: ${root}`);
+} catch (error) {
+  if (error.data?.code === PathfinderErrorCode.REPOSITORY_NOT_FOUND) {
+    console.error("No repository marker found");
+    console.error(`Searched from: ${error.data.context.startPath}`);
+    console.error(`Max depth: ${error.data.context.maxDepth}`);
+  } else if (error.data?.code === PathfinderErrorCode.TRAVERSAL_LOOP) {
+    console.error("Cyclic symlink detected:", error.data.context);
+  } else {
+    throw error; // Re-throw unexpected errors
+  }
+}
+```
+
+**Default Behavior:**
+
+- **`maxDepth`**: `10` - Prevents excessive traversal
+- **`boundary`**: User home directory (if start path under home), otherwise filesystem root
+- **`stopAtFirst`**: `true` - Returns first marker found (closest to start path)
+- **`followSymlinks`**: `false` - Security: symlinks not followed by default
+- **`constraint`**: `undefined` - No additional path constraints
+
+See [Pathfinder README](src/pathfinder/README.md) for complete API documentation.
+
 ### Pathfinder - Filesystem Discovery
 
 Enterprise filesystem traversal with pattern matching, ignore files, optional checksums, and comprehensive observability.

package/config/crucible-ts/devsecops/lorage-central/activity/v1.0.0/defaults.yaml

@@ -0,0 +1,19 @@
+# config/devsecops/lorage-central/activity/v1.0.0/defaults.yaml
+# L'Orage Central Activity Record Defaults
+# Description: Default audit config (e.g., event templates; emitted auto).
+# Rationale: Structured logging defaults; retain per policy.audit.
+# Version: v1.0.0 (Ties to schema; integrates gofulmen).
+# Example Event Template (auto-populated in REPL)
+eventTemplate:
+  eventType: unlock # From enum
+  outcome: success
+  metadata:
+    sessionId: "sess-default-001"
+    userId: "user-anon-123"
+    duration: "5s"
+    details: {method: totp}
+backend: # Refs policy.audit
+  level: structured
+  retain: 30d
+# Usage: REPL emits: {id: evt-default-unlock-001, timestamp: now, tenant: tnt-uuid-123-prod-us, ...}
+# Stored in audit backend (e.g., Turso table); no defaults for id/timestamp (runtime).

package/config/crucible-ts/devsecops/lorage-central/credentials/v1.0.0/defaults.yaml

@@ -0,0 +1,21 @@
+# config/devsecops/lorage-central/credentials/v1.0.0/defaults.yaml
+# L'Orage Central Root Credentials Defaults
+# Description: Default metadata for root creds (e.g., bootstrap key; no values—refs only).
+# Rationale: Secure defaults (1y expiry); used in seeding/actions.
+# Version: v1.0.0 (Ties to schema; backend from policy).
+id: default-bootstrap-key
+tenant: tnt-uuid-123-prod-us # From registry
+type: gpg-key
+ref: "gpg://keyring/default-bootstrap" # Opaque; decrypted at runtime
+metadata:
+  created: "2025-11-09T12:00:00Z"
+  expires: "2026-11-09T12:00:00Z" # 1y default
+  purpose: tenant-bootstrap
+  rotation:
+    interval: 365d
+    method: manual
+backend: # Refs policy.isolation.store
+  type: gpg-file
+  enc: true
+# Usage: In recipe.actions or seeding: ref this for bootstrap; REPL checks expiry.
+# Example: For Turso, type: turso-root, ref: "turso://root-auth".

package/config/crucible-ts/devsecops/lorage-central/policy/v1.0.0/defaults.yaml

@@ -0,0 +1,36 @@
+# config/devsecops/lorage-central/policy/v1.0.0/defaults.yaml
+# L'Orage Central Tenant Policy Defaults
+# Description: Default policy for new tenants (loaded via three-layer config; overrides in .fulmen/lorage.yaml).
+# Rationale: Secure MVP defaults (short TTL, MFA required, Turso backend); confidential example (obscure publicId).
+# Version: v1.0.0 (Ties to schema; auto-applies dataSensitivity guards from registry).
+tenant: tnt-uuid-123-prod-us # Obscure publicId from registry (confidential=true; no client exposure)
+session:
+  ttl:
+    default: 15m # Force re-unlock per session
+    ops:
+      deploy: 1h
+      query: 5m
+      seed: 30m
+  maxConcurrent: 1 # Strict isolation
+mfa:
+  required: true # Auto-true if registry.dataSensitivity.pii=true
+  methods: [totp, webauthn] # From auth-methods taxonomy
+  fallback: cli-prompt
+isolation:
+  store:
+    type: turso # HA default
+    conn:
+      url: "turso://default-db" # Placeholder; ref root-credentials
+      auth: {ref: "gpg://keyring/default-bootstrap"}
+    enc: false # Enable for cloud-free
+  crossAccess: false
+geoRestrictions: [eu-west-1] # From registry.geo (e.g., EU for GDPR)
+cloudRestrictions: [aws, doc] # From registry.cloud
+dataSensitivityGuards:
+  pii: false # Auto-from registry; triggers mfa/geo if true
+  phi: false # Triggers enc/audit if true
+audit:
+  level: structured # gofulmen integration
+  retain: 30d
+# Usage: REPL loads defaults + overrides; validates against schema/registry.
+# Example Override: For PHI tenant, set dataSensitivityGuards.phi: true → auto-enc=true.

package/config/crucible-ts/devsecops/lorage-central/recipe/v1.0.0/defaults.yaml

@@ -0,0 +1,61 @@
+# config/devsecops/lorage-central/recipe/v1.0.0/defaults.yaml
+# L'Orage Central Recipe Defaults
+# Description: Default recipe config (e.g., for Mattermost MVP); loaded via three-layer.
+# Rationale: Declarative base (components/phases); procedural actions for bootstrap.
+# Version: v1.0.0 (Ties to schema; refs taxonomies for provider/backend/phase).
+name: mattermost-stack # Slug-safe
+type: deploy
+target:
+  provider: doc # From infra-providers
+  region: nyc3
+  backend: opentofu # From toolchains
+components:
+  - name: postgres
+    image: postgres:15
+    phase: storage # From infra-phases (order 3)
+    ports: [5432]
+    env:
+      POSTGRES_DB: mattermost
+    secrets:
+      - ref: "gpg://keyring/acme/db-pass"
+        injectAs: POSTGRES_PASSWORD
+    dependsOn: [] # No deps for base DB
+    module: db-postgres # Tofu module
+  - name: mattermost
+    image: mattermost/mattermost-team:latest
+    phase: compute # Order 4
+    ports: [8065]
+    env:
+      MM_POSTGRES_URL: "postgres://user:pass@localhost:5432/mattermost"
+    secrets:
+      - ref: "gpg://keyring/acme/mm-secret"
+        injectAs: MM_SECRET
+    dependsOn: [postgres]
+    module: app-mattermost
+actions:
+  - type: bootstrap
+    phase: bootstrap # Order 0; procedural for key gen
+    cmd: "gpg --gen-key --batch acme-bootstrap" # Example script
+    dependsOn: []
+  - type: script
+    phase: network # Order 2
+    cmd: "doctl compute vpc create --name acme-vpc" # SDK wrapper for VPC
+    dependsOn: [bootstrap]
+secrets:
+  backend: gpg-keyring # Refs policy.isolation.store
+  globalRefs:
+    - ref: "turso://shared-network-key"
+validate:
+  - type: health
+    endpoint: "http://localhost:8065/health"
+  - type: connect
+    endpoint: "postgres://localhost:5432/mattermost"
+diff: # For seed type
+  from: v1-0
+  to: v1-1
+  changes:
+    - op: add
+      path: /entries/mm-secret
+      value: {ref: "gpg://keyring/acme/mm-secret"}
+# Usage: REPL: lorage deploy --recipe mattermost-stack (loads defaults + overrides; topo-sorts phases/actions).
+# Example: For Open edX, add k3s module in compute phase, network action for LB.

package/config/crucible-ts/devsecops/lorage-central/runbooks/v1.0.0/defaults.yaml

@@ -0,0 +1,50 @@
+# config/devsecops/lorage-central/runbooks/v1.0.0/defaults.yaml
+# L'Orage Central Runbook Defaults
+# Description: Default runbook config (e.g., global-network prototype); loaded via three-layer.
+# Rationale: Serializes Markdown prototypes (e.g., from .plans/research/); executable in REPL.
+# Version: v1.0.0 (Ties to schema; refs phases/recipe for steps).
+id: global-network # Slug-safe
+title: Global Enterprise Network Setup
+tenantScope: [all] # Or specific publicIds
+description: >-
+  Beginnings of the Runbook: Global Enterprise Picture with Tenants. Our runbook will live in the IDE... (from prototypes).
+phases:
+  - id: bootstrap # From infra-phases
+    title: Initial Setup
+    description: "Core Components: Provision monitoring first."
+    steps:
+      - id: vaultwarden-init
+        type: script
+        content: "docker run -d --name vaultwarden vaultwarden/server:latest" # Bootstrap secrets
+        dependsOn: []
+        parallel: false
+      - id: prometheus-setup
+        type: action
+        ref: prometheus-stack # Ref recipe
+        dependsOn: [vaultwarden-init]
+  - id: network # Order 2
+    title: Networking Backbone
+    description: "Zero-trust backbone (Cloudflare Gateway); VPC peering for hybrids."
+    steps:
+      - id: tenant-table
+        type: table
+        content: |
+          | Tenant | Type | Focus | Clouds (Priority) | Secrets Scope | Initial Infra Needs |
+          |--------|------|-------|-------------------|---------------|---------------------|
+          | fulmenhq | Ecosystem | Tonnerre templates | AWS/GCP (core), Cloudflare (edge), Hetzner/DO (cost-opt) | IaC vars, SDK keys | OpenTofu state backend (S3), CI/CD pipelines |
+          | 3 Leaps Sponsored | Internal | Sponsored OSS | Cloudflare (Workers/DNS), Azure (AI), Hetzner (compute) | API tokens, DB creds | Worker deployments, basic storage |
+          | 3 Leaps Commercial | External | Client-specific | Client-dictated (AWS/Azure/GCP) | Isolated vaults | Hybrid connectivity, compliance-heavy |
+        dependsOn: []
+        parallel: true # Table review parallel with setup
+      - id: vpc-peering-setup
+        type: script
+        content: "doctl compute vpc create --name global-vpc" # Create VPC for hybrid peering
+        dependsOn: [tenant-table]
+        validate:
+          type: custom
+          script: "check-vpc-connectivity.sh"
+audit:
+  backend: postgres
+  retention: 30
+# Usage: REPL: lorage runbook global-network --phase network (executes steps, audits).
+# Example: From prototypes—serialize Markdown tables/scripts; future: Conditional for tenant.geo.

package/config/crucible-ts/devsecops/lorage-central/tenant/v1.0.0/defaults.yaml

@@ -0,0 +1,28 @@
+# config/devsecops/lorage-central/tenant/v1.0.0/defaults.yaml
+# L'Orage Central Tenant Registry Defaults
+# Description: Default registry for new clients/tenants (loaded via three-layer; e.g., bootstrap new client).
+# Rationale: Confidential example (obscure publicIds); multi-tenant per client (prod/dev).
+# Version: v1.0.0 (Ties to schema; geo/cloud from taxonomies).
+client:
+  id: default-client-internal
+  name: Default Client # Confidential; not exposed
+  confidential: true # Obscure publicIds (UUID-based)
+tenants:
+  - publicId: tnt-uuid-123-prod-us # Globally unique/obscure
+    purpose: production-mattermost
+    geo: [na] # From geo-regions (expands to us/ca)
+    cloud: [doc, aws] # From infra-providers
+    dataSensitivity:
+      pii: false
+      phi: false
+      other: [] # e.g., [pci-dss]
+  - publicId: tnt-uuid-456-dev-eu
+    purpose: development-testing
+    geo: [eu] # Expands to de/fr/gb/ch (conventions)
+    cloud: [gcp]
+    dataSensitivity:
+      pii: true # Triggers policy guards (mfa/geo)
+      phi: false
+globalUniqueness: true # Enforced (UUID for anon)
+# Usage: REPL loads defaults + client overrides; validates publicId uniqueness.
+# Example: For confidential client, generate UUID publicIds; pii=true → policy.mfa.required=true.