@salesforce/afv-skills 1.29.0 → 1.31.0

package/skills/platform-encryption-configure/assets/EncryptionKey.settings-meta.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Key-management settings (Shield Platform Encryption).
+  All fields are optional booleans; include only the ones you intend to change.
+    enableCacheOnlyKeys            make the Cache-Only Key Service available
+    enableReplayDetection          protect cache-only key callouts with a nonce
+                                   REQUIRES enableCacheOnlyKeys=true first (one-way dependency).
+    canExternalKeyManagement       allow External Key Management (EKM) connections   [API 63.0+]
+    canManageDataCloudKeys         enable Data 360 key management + initial root key  [API 63.0+]
+    canEncryptTransactionalDatabase  enable transactional database encryption          [API 63.0+]
+    canOptOutOfDerivationWithBYOK  allow opting out of key derivation per uploaded key
+-->
+<EncryptionKeySettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <enableCacheOnlyKeys>true</enableCacheOnlyKeys>
+    <enableReplayDetection>true</enableReplayDetection>
+    <canOptOutOfDerivationWithBYOK>false</canOptOutOfDerivationWithBYOK>
+</EncryptionKeySettings>

package/skills/platform-encryption-configure/assets/PlatformEncryption.settings-meta.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Org-level Platform Encryption policy settings.
+  All fields are optional booleans; include only the ones you intend to change.
+    canEncryptManagedPackageFields  allow encrypting fields in installed managed packages
+    enableDeterministicEncryption   allow the deterministic scheme on supported fields (enables filtering)
+    enableEncryptFieldHistory       apply active key material to field history / feed tracking
+    isMEKForEncryptionRequired      require Manage Encryption Keys perm in addition to baseline perms
+-->
+<PlatformEncryptionSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <enableDeterministicEncryption>true</enableDeterministicEncryption>
+    <enableEncryptFieldHistory>true</enableEncryptFieldHistory>
+    <isMEKForEncryptionRequired>true</isMEKForEncryptionRequired>
+    <canEncryptManagedPackageFields>false</canEncryptManagedPackageFields>
+</PlatformEncryptionSettings>

package/skills/platform-encryption-configure/assets/encrypted-field.field-meta.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>{FIELD_API_NAME}__c</fullName>
+    <label>{FIELD_LABEL}</label>
+    <type>{FIELD_TYPE}</type>
+    <length>{LENGTH}</length>
+    <encryptionScheme>ProbabilisticEncryption</encryptionScheme>
+</CustomField>
+<!--
+  TEMPLATE NOTES — delete this comment block before delivering the file.
+
+  <type>:   Text for string fields up to 255 chars; LongTextArea only for 256+.
+            "long text up to 255 characters" is Text, NOT LongTextArea.
+  <encryptionScheme> must be exactly one of:
+    ProbabilisticEncryption                strongest; NOT filterable/sortable/groupable
+    CaseSensitiveDeterministicEncryption   filterable; exact-case equality
+    CaseInsensitiveDeterministicEncryption filterable; case-normalized equality
+    None                                   removes encryption
+  Only deterministic schemes support filter / sort / group. A query that filters
+  a probabilistically-encrypted field is REJECTED with INVALID_FIELD.
+-->
+

package/skills/platform-encryption-configure/examples/cache-only-keys.settings-meta.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Worked example: enabling Cache-Only Keys WITH replay detection.
+  Note the ordering guarantee — enableCacheOnlyKeys=true is present, which is
+  the precondition for enableReplayDetection=true. Removing enableCacheOnlyKeys
+  (or setting it false) while keeping enableReplayDetection=true is invalid.
+-->
+<EncryptionKeySettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <enableCacheOnlyKeys>true</enableCacheOnlyKeys>
+    <enableReplayDetection>true</enableReplayDetection>
+</EncryptionKeySettings>

package/skills/platform-encryption-configure/references/encryption-schemes.md

@@ -0,0 +1,34 @@
+# Encryption Schemes
+
+Shield Platform Encryption offers two families of scheme, exposed on `CustomField.encryptionScheme` (Metadata API 44.0+). Choosing between them is a trade-off between cryptographic strength and queryability.
+
+## Valid `encryptionScheme` values
+
+| Value | Filterable / sortable / groupable | When to use |
+|-------|:--:|-------------|
+| `ProbabilisticEncryption` | **No** | Default and strongest. Same plaintext encrypts to different ciphertext each time, so no two values are comparable. Use unless the field must be queried. |
+| `CaseSensitiveDeterministicEncryption` | Yes | Same plaintext always encrypts to the same ciphertext, preserving exact case. Use for exact-match filters where case matters (e.g. codes, tokens). |
+| `CaseInsensitiveDeterministicEncryption` | Yes | Deterministic with case normalized before encryption. Use for equality filters on human-entered text (names, emails) where case should not matter. |
+| `None` | n/a | Removes encryption from the field. |
+
+Only these four strings are accepted. Any other value fails deployment.
+
+## Deterministic vs Probabilistic — the decision
+
+- **Need to filter, sort, group, or use the field in a WHERE clause?** → a deterministic scheme. Deterministic encryption preserves equality so the index can be used.
+- **No query requirement?** → probabilistic. It is cryptographically stronger because identical plaintexts produce different ciphertexts, defeating frequency analysis.
+- **Case matters in matching?** → `CaseSensitive...`. Otherwise `CaseInsensitive...`.
+
+Enabling the deterministic scheme at the org level also requires `enableDeterministicEncryption=true` in `PlatformEncryptionSettings`.
+
+## Query behavior of encrypted fields — the failure mode
+
+A common misconception is that filtering or sorting on a **probabilistically**-encrypted field silently drops the clause or returns zero rows. It does not.
+
+The platform **rejects the query** with an `INVALID_FIELD` error:
+
+```text
+INVALID_FIELD: field '<FieldName>' can not be sorted / filtered / grouped in a query call
+```
+
+This is enforced server-side (see the platform's `QueryBlockingTest` coverage). The correct guidance to a user hitting this is: the query failed because the field is probabilistically encrypted — re-encrypt it with a deterministic scheme if it must be queryable, or remove the field from the filter/sort/group clause. Never tell the user the query "returns nothing" — it errors.

package/skills/platform-encryption-configure/references/key-models.md

@@ -0,0 +1,34 @@
+# Key Management Models
+
+Shield Platform Encryption supports several ways to source and control the key material that protects encrypted data. They differ in *where the key material lives* and *who controls it*.
+
+## The models
+
+| Model | Where key material lives | Who controls it | Metadata / setting |
+|-------|--------------------------|-----------------|--------------------|
+| Salesforce-derived (default) | Salesforce, derived from a tenant secret | Salesforce derivation | none — default |
+| **BYOK** (Bring Your Own Key) | Salesforce, but from *customer-supplied* material | Customer uploads key material; Salesforce stores it | `canOptOutOfDerivationWithBYOK` controls per-key derivation opt-out |
+| **BYOKMS / EKM** (External Key Management) | An *external* key store the customer runs | Customer; Salesforce calls out to the KMS | `canExternalKeyManagement` (API 63.0+) |
+| **Cache-Only Keys** | Outside Salesforce entirely; fetched on demand per callout | Customer hosts a key service; Salesforce caches, never persists | `enableCacheOnlyKeys`, `enableReplayDetection` |
+| **Data 360 keys** | Salesforce, dedicated Data 360 root key | Customer-managed root key | `canManageDataCloudKeys` (API 63.0+) |
+| **Transactional DB** | Salesforce | Org policy | `canEncryptTransactionalDatabase` (API 63.0+) |
+
+## BYOK vs BYOKMS/EKM — the distinction users get wrong
+
+- **BYOK**: you generate key material and *upload* it. Salesforce stores it and uses it like a derived key. The trust boundary still includes Salesforce storing the material.
+- **BYOKMS / EKM**: key material *never leaves your external KMS*. Salesforce makes a callout to the KMS to wrap/unwrap. This keeps the material entirely under your control.
+
+## Cache-Only Keys and replay detection
+
+Cache-Only Keys go further than EKM: Salesforce fetches key material on every use and never persists it — only caches it transiently.
+
+`enableReplayDetection` protects those callouts against replay attacks using a nonce. The contract is a **one-way dependency**:
+
+> *Requires `enableCacheOnlyKeys=true` before setting `enableReplayDetection` to true.*
+
+Two consequences the agent must respect:
+
+1. Enabling Cache-Only Keys does **not** auto-enable replay detection. You must set `enableReplayDetection=true` explicitly.
+2. An org can validly run Cache-Only Keys with replay detection **off**. It is not required.
+
+Setting `enableReplayDetection=true` without `enableCacheOnlyKeys=true` is an invalid combination and will be rejected.

package/skills/platform-encryption-configure/references/tenant-secret-lifecycle.md

@@ -0,0 +1,23 @@
+# Tenant Secret Lifecycle
+
+A **tenant secret** is the per-org root from which Shield derives (or wraps) data encryption keys. Its lifecycle operations are **UI/REST-only** — there is no `*.settings-meta.xml` for rotating, destroying, or uploading a tenant secret. When a user asks about these, return guidance and point them at Setup or the REST/Tooling API, not a metadata file.
+
+## Operations
+
+| Operation | What it does | Surface |
+|-----------|--------------|---------|
+| Generate | Creates a new active tenant secret for a key type | Setup → Key Management, or REST |
+| Rotate | Generates a new tenant secret; existing data stays readable under prior secrets | Setup / REST |
+| Destroy | Permanently destroys key material; data encrypted under it becomes unrecoverable | Setup (destructive, requires confirmation) |
+| BYOK upload | Uploads customer-supplied key material as the tenant secret | Setup / REST |
+| Cache-Only callout setup | Configures the named credential / callout endpoint the key service is fetched from | Setup (Named Credentials) |
+
+## Rotation semantics
+
+Rotating a tenant secret makes a new secret **active**; prior secrets are retained as **archived** so existing ciphertext stays readable. New writes use the active secret. To move existing data onto the new secret, run **background encryption** (a.k.a. the sync/re-encrypt process) — rotation alone does not re-encrypt existing rows.
+
+For BYOK specifically, the sequence is: rotate to (upload) the new key material, then run background encryption to apply it. Uploading new material does not retroactively re-encrypt existing data on its own.
+
+## Destruction semantics
+
+Destroying a tenant secret is **irreversible**. Any data whose keys derive from that secret and has not been re-encrypted under another active secret becomes permanently unreadable. This is intentional (right-to-be-forgotten / crypto-shredding) but must be surfaced as a hard warning — there is no recovery path.

package/skills/platform-encryption-configure/scripts/validate-encryption-metadata.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Validate a Shield Platform Encryption settings/field XML file for the two
+# deterministic contracts this skill must never get wrong:
+#   1. enableReplayDetection=true requires enableCacheOnlyKeys=true (one-way dependency)
+#   2. encryptionScheme must be one of the four valid enum values
+#
+# Usage: validate-encryption-metadata.sh <file.xml>
+#        validate-encryption-metadata.sh --help
+# Output: prints "OK" on success; prints ERROR lines to stderr and exits 1 on failure.
+
+set -euo pipefail
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  echo "Usage: validate-encryption-metadata.sh <file.xml>"
+  echo "Checks: replay-detection dependency, encryptionScheme enum."
+  exit 0
+fi
+
+FILE="${1:-}"
+if [[ -z "$FILE" ]]; then
+  echo "ERROR: no file given. Usage: validate-encryption-metadata.sh <file.xml>" >&2
+  exit 1
+fi
+if [[ ! -f "$FILE" ]]; then
+  echo "ERROR: file not found: $FILE" >&2
+  exit 1
+fi
+
+errors=0
+
+# 1. Replay-detection one-way dependency.
+if grep -q '<enableReplayDetection>true</enableReplayDetection>' "$FILE"; then
+  if ! grep -q '<enableCacheOnlyKeys>true</enableCacheOnlyKeys>' "$FILE"; then
+    echo "ERROR: enableReplayDetection=true requires enableCacheOnlyKeys=true in the same file." >&2
+    errors=$((errors + 1))
+  fi
+fi
+
+# 2. encryptionScheme enum.
+scheme=$(grep -oE '<encryptionScheme>[^<]*</encryptionScheme>' "$FILE" | sed -E 's/<\/?encryptionScheme>//g' || true)
+if [[ -n "$scheme" ]]; then
+  case "$scheme" in
+    ProbabilisticEncryption|CaseSensitiveDeterministicEncryption|CaseInsensitiveDeterministicEncryption|None) ;;
+    *)
+      echo "ERROR: invalid encryptionScheme '$scheme'. Must be one of: ProbabilisticEncryption, CaseSensitiveDeterministicEncryption, CaseInsensitiveDeterministicEncryption, None." >&2
+      errors=$((errors + 1))
+      ;;
+  esac
+fi
+
+if [[ "$errors" -gt 0 ]]; then
+  exit 1
+fi
+echo "OK"