[viethqb]

Summary

Platform docs for egret-data/platform#760 (merge 2d2c3f35, "vended credentials follow catalog grants"). The S3 credentials egret's Iceberg catalog vends on a table load now follow the Catalog Client's grant: a read grant (table, namespace or catalog) vends read-only credentials (s3:GetObject, s3:GetObjectVersion on the table's location), and write or manage vends read-write-delete, with or without the delegation header and on …/credentials. This PR documents the rule, the behaviour change (an engine or client with only read grants can read but no longer write; egret-provisioned Trino and StarRocks hold catalog · manage and are unaffected), the symptom a read-only client now sees when it writes, and an upgrade note. It closes KI-311 and adds KI-315 and KI-316.

Changes

• Catalog detail (control-plane/catalogs/catalog-detail.md): a new subsection under What each operation needs, Storage credentials follow the grant (#storage-credentials-follow-the-grant):
  • a table of grant → vended credentials (read → Get only; write/manage → read-write-delete; none → the load is 403);
  • the same rule with the header, without it, and on /credentials; only client-managed asks for none; a mixed role (namespace read plus write on one table) gets read-write-delete on that table only; create/stage-create vend read-write-delete on the new location; a view load is read-only;
  • a read-only engine or client fails at the object store on its first upload, before anything reaches the catalog (PyIceberg's ACCESS_DENIED during CreateMultipartUpload, quoted from the live check); provisioned engines hold catalog · manage;
  • the ~1 h lifetime and shared cached key (KI-315).
  • The Connect section links to it. The limits drop the KI-311 bullet and list KI-315 and KI-316.
• Storage and catalog: the vended-credentials paragraph says the credentials follow the grant. The "One warehouse, one prefix" caution says the overlap check compares endpoints as written (KI-316).
• Catalog and storage errors: a new symptom row (a write fails at the object store with access denied while reads work → the role has only read; nothing was committed), and a paragraph under Credentials vending fails.
• FAQ: a new question, "Why can a catalog client read a table but not write to it, with access denied from the object store?".
• Upgrade: a version note for #760: no migration, no API change; what each grant now gets; the behaviour change for read-only engines and clients; provisioned engines unaffected (Trino checked); credentials vended before the upgrade stay valid until they expire.
• Engines: Provision an engine says the engine's client is under the warehouse's engine role (catalog · manage), and its limits note that an existing engine role is reused without checking its grants, so a narrowed one makes the engine read-only. Register an external engine says the Catalog Client's role decides whether the engine can write.
• Known issues: the intro is updated. One row closed, two added:
  • KI-311 closed with Status: fixed in platform #760: read grant → read-only credentials, write/manage → read-write-delete, with or without the header and on /credentials, view loads read-only; measured in the live check.
  • KI-315 (Limitation, S3): vended credentials live about 1 h and are cached per (location, permission), so a revoked or narrowed grant's credentials keep working until they expire, and callers with the same permission on a table share one key.
  • KI-316 (Security, S3, low severity, needs an admin misconfiguration): two warehouses sharing a location whose storage connections write the endpoint differently are not seen as overlapping, so a namespace writer in one can register a forged metadata file at the other's table location and get read-write-delete credentials there.
• REST API reference: regenerated from openapi.json at 2d2c3f35 with scripts/gen-api-reference.mjs. No diff (#760 has no API shape change), so nothing is committed. (Platform main's current openapi.json differs only in the workflow page, from #761; that belongs in #761's docs.)

Screenshots

None changed: #760 has no UI change. No re-shoot.

Notes

• KI-315 and KI-316 are the next free numbers after main (KI-314). No docs PR is open.
• KI-316 is from the independent review of #760 (read from the code; the cross-warehouse case was not reproduced). The same-warehouse refusal (409) was measured and pinned in #760's tests.
• The behaviour change is narrower than "can no longer write" suggests for catalog writes: a read-only client was already refused commits with 403. What it loses is writing and deleting the table's files directly; its writes now fail at the object store instead of at the commit. The pages say so.
• Every egret-provisioned path attaches with the warehouse's engine role (attach_to_engine(…, None) in every caller), so "an engine attached with a read-only role" means a self-run engine configured with a read-only client, or an engine role an administrator narrowed.
• No Trino or StarRocks error text for a read-only write was measured, so the pages quote only PyIceberg's.
• Every statement was checked against crates/egret-catalog-engine/src/authorizer.rs, mount.rs, warehouse.rs and crates/egret-engine-mgmt/src/{catalog_apply,engines}.rs at 2d2c3f35/main, the spec (D1–D4, C1–C14, §10, §11) and the live-check evidence.
• English only: the docs repo has no i18n/vi mirror.
• Build: npm run typecheck and npm run build pass locally (en and vi locales; no broken links or anchors reported).

Checklist

• Wording taken from the spec, the merged code and the live check at 2d2c3f35
• npm run typecheck and npm run build pass
• KI-311 closed; new rows with the next free IDs
• REST API reference regenerated (no diff for #760)
• Screenshots: none affected
• No secrets, tokens or real data added

🤖 Generated with Claude Code