Skip to main content

Release 0.5.8 — Skills FGA, catalog API keys BFF, and RBAC migrations

Sri Aradhyula
Sri Aradhyula

Chart: oci://ghcr.io/cnoe-io/charts/ai-platform-engineering:0.5.8 (when published) Previous release: 0.5.4

Highlights​

0.5.8 continues enterprise RBAC work: skill team shares reconcile through the shared OpenFGA shareable-resource module, catalog API keys can be minted from the CAIPE UI BFF without the supervisor, and admin ReBAC migrations cover agent/skill FGA backfills. See the upgrade guide below for the catalog API key hash change before upgrading production.

What's New​

Skills and catalog​

  • Catalog API keys in the BFF — mint, list, and revoke keys via /api/catalog-api-keys without proxying to the supervisor (see breaking change if you already minted keys).
  • Skill FGA reconcile — per-skill team shares use the shared reconcileShareableResource path; admin migration agent_skill_openfga_reconcile_v1 backfills owner and team tuples from Mongo.

RBAC​

  • Agent user:* wildcard — visibility changes correctly add/remove org-wide grants on dynamic agents.
  • Skills team sharing — members can team-share skills from the Skill Builder with the same teams picker pattern as agents and knowledge bases.

Breaking Changes​

Catalog API key hash​

Stored catalog API key digests changed algorithm:

BeforeAfter (0.5.8)
AlgorithmSHA-256 of pepper + ":" + secretHMAC-SHA256 with CAIPE_CATALOG_API_KEY_PEPPER (or SKILLS_API_KEY_PEPPER) as the HMAC key
BFFN/A or legacy proxyui/src/lib/catalog-api-keys.ts
Pythonskills_middleware/api_keys_store.pySame HMAC format as BFF

Impact: Any row in the catalog_api_keys collection created before this change will fail verification after upgrade. Clients must receive a newly minted key.

Not affected: Key format on the wire is unchanged ({key_id}.{secret}). Pepper env vars are unchanged; only how the secret is hashed at rest changed.

Security​

  • Catalog key hashing uses HMAC-SHA256 and unbiased randomInt for secret generation (CodeQL-hardened).
  • Set CAIPE_CATALOG_API_KEY_PEPPER to a long random value in production (see ui/env.example).

Known Issues​

None documented for this pre-release note.

Upgrade​

helm upgrade ai-platform-engineering \
  oci://ghcr.io/cnoe-io/charts/ai-platform-engineering \
  --version 0.5.8 \
  -f your-values.yaml

Upgrade Guide: 0.5.4 → 0.5.8​

Overview​

Most deployments can upgrade the chart first, then run admin ReBAC migrations from Admin → ReBAC migrations. If you use catalog API keys (Skills Gateway / X-Caipe-Catalog-Key), plan a short key rotation window — see Catalog API key hash below.

Catalog API key hash​

Required when: the catalog_api_keys MongoDB collection contains keys minted before 0.5.8 (BFF or supervisor).

Skip when: the collection is empty or you do not use catalog API keys.

1. Confirm pepper is set consistently​

Use the same pepper on the CAIPE UI (BFF) and any Python path that validates keys (supervisor / skills middleware):

# ui deployment / secret
CAIPE_CATALOG_API_KEY_PEPPER=<openssl rand -hex 32>

# skills middleware / supervisor (if applicable)
SKILLS_API_KEY_PEPPER=<same value>

Do not change the pepper during rotation unless you intend to invalidate all keys.

2. Rotate keys​

For each active key:

  1. In the UI (or via API), revoke the old key_id.
  2. Mint a new key and distribute the new {key_id}.{secret} to clients (CI, local CAIPE_CATALOG_KEY, install scripts, etc.).
  3. Update automation that cached the old secret.

Optional (dev/test only): drop the collection and re-mint from scratch:

// MongoDB — destructive; production use revoke + mint instead
db.catalog_api_keys.deleteMany({})

3. Verify​

curl -sS -H "X-Caipe-Catalog-Key: <new-key>" \
  "https://<your-ui>/api/skills/catalog" | head

Expect 200 (or your normal catalog response), not 401.

Helm Values Changes​

Document full values.yaml diff when the 0.5.8 chart is published. Set catalog pepper via existing UI/skills env wiring (see ui/env.example).

Data Migrations​

Run pending migrations from Admin → ReBAC migrations, including when applicable:

  • agent_skill_openfga_reconcile_v1 — backfill skill owner/team FGA tuples
  • agent_shared_team_grants_backfill_v1 — agent shared_with_teams → OpenFGA
  • Other 0.5.8 manifest entries shown as behind in the migrations UI

Upgrade Runbook​

1. Rotate catalog API keys (if used)​

Complete Catalog API key hash before or immediately after deploy so clients are not left with invalid keys.

2. Update chart version​

helm upgrade ai-platform-engineering \
  oci://ghcr.io/cnoe-io/charts/ai-platform-engineering \
  --version 0.5.8 \
  -f your-values.yaml

3. Run ReBAC migrations​

Use the admin migrations UI with the confirmation strings shown per migration.

4. Verify​

  • Skills list/catalog with a new catalog API key
  • Team-shared skills visible to team members after FGA reconcile migration
  • Dynamic agent global/team visibility behaves as expected