mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 17:35:10 +03:00
Wen Bo Xie
2681a21f5c
Add a guide that compares classic and scoped personal access tokens, explains how account roles constrain token permissions, and walks through creating and testing a project-scoped token. Include generated tables mapping permissions to Management API endpoints and MCP tools, and link the guide from docs navigation and Studio token sheets. Move the scoped-token permission catalog from Studio into shared-data. Studio and docs generation now share permission names, categories, descriptions, risk metadata, modes, scopes, and display order. Generate the tables from the shared catalog, OpenAPI x-fga-permissions, and the downloaded MCP permission map. Exclude Workers permissions until the feature is live. Run regeneration through the docs Makefile, verify checked-in output in CI, and refresh it in the weekly Management API workflow. Add Dashboard and Docs ownership plus contributor guidance so permission changes stay synchronized.
119 lines
6.7 KiB
Makefile
119 lines
6.7 KiB
Makefile
REPO_DIR=$(shell pwd)
|
|
GENERATOR_DIR=../../../packages/generator
|
|
|
|
.PHONY: run download download.api.v1 download.mcp-tools-permissions download.storage.v1 download.tsdoc.v2 download.server.v1 transform dereference.api.v1 dereference.auth.v1 dereference.storage.v0 generate generate.sections.api.v1 generate.partials.access-control format
|
|
|
|
run: download transform generate format
|
|
|
|
|
|
###############################################################################
|
|
# Download all the specs
|
|
###############################################################################
|
|
# comment out download.auth.v1 temporarily, we're manually creating the file
|
|
# download: download.api.v1 download.auth.v1 download.storage.v1 download.tsdoc.v2
|
|
download: download.api.v1 download.mcp-tools-permissions download.storage.v1 download.tsdoc.v2 download.server.v1
|
|
|
|
download.api.v1:
|
|
curl -sS https://api.supabase.com/api/v1-json > $(REPO_DIR)/api_v1_openapi.json
|
|
curl -sS https://api.supabase.com/api/v2-json > $(REPO_DIR)/api_v2_openapi.json
|
|
|
|
# Download tool permissions from the public Management API projection of its enforcement rules.
|
|
download.mcp-tools-permissions:
|
|
curl -sSf https://api.supabase.com/platform/mcp-tools-permissions > $(REPO_DIR)/mcp_tools_permissions.json
|
|
npx prettier --write $(REPO_DIR)/mcp_tools_permissions.json
|
|
|
|
# This flow needs to be updated, so we'l comment out for the moment
|
|
# Manual flow for now:
|
|
# — get swagger.json (https://supabase.github.io/gotrue/swagger.json)
|
|
# — manually convert via swagger editor -> open api v3 spec
|
|
# dereference.tsdoc.v2 -> auth_v1_openapi_deparsed.json
|
|
|
|
# download.auth.v1:
|
|
# curl -sS https://supabase.github.io/gotrue/swagger.json > $(REPO_DIR)/auth_v1_openapi.json
|
|
|
|
download.storage.v1:
|
|
curl -sS https://supabase.github.io/storage/api.json > $(REPO_DIR)/storage_v0_openapi.json
|
|
|
|
# No longer updated
|
|
# download.tsdoc.v1:
|
|
# curl -sS https://supabase.github.io/supabase-js/v1/spec.json > $(REPO_DIR)/enrichments/tsdoc_v1/supabase.json
|
|
# curl -sS https://supabase.github.io/gotrue-js/v1/spec.json > $(REPO_DIR)/enrichments/tsdoc_v1/gotrue.json
|
|
# curl -sS https://supabase.github.io/postgrest-js/v1/spec.json > $(REPO_DIR)/enrichments/tsdoc_v1/postgrest.json
|
|
# curl -sS https://supabase.github.io/realtime-js/v1/spec.json > $(REPO_DIR)/enrichments/tsdoc_v1/realtime.json
|
|
# curl -sS https://supabase.github.io/storage-js/v1/spec.json > $(REPO_DIR)/enrichments/tsdoc_v1/storage.json
|
|
# curl -sS https://supabase.github.io/functions-js/v1/spec.json > $(REPO_DIR)/enrichments/tsdoc_v1/functions.json
|
|
|
|
download.tsdoc.v2:
|
|
curl -sS https://supabase.github.io/supabase-js/supabase-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/supabase.json
|
|
curl -sS https://supabase.github.io/supabase-js/auth-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/gotrue.json
|
|
curl -sS https://supabase.github.io/supabase-js/postgrest-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/postgrest.json
|
|
curl -sS https://supabase.github.io/supabase-js/realtime-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/realtime.json
|
|
curl -sS https://supabase.github.io/supabase-js/storage-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/storage.json
|
|
curl -sS https://supabase.github.io/supabase-js/functions-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/functions.json
|
|
|
|
download.server.v1:
|
|
curl -sSf https://supabase.github.io/server/spec.json > $(REPO_DIR)/reference/server/v1/server.json
|
|
|
|
download.analytics.v0:
|
|
curl -sS https://logflare.app/api/openapi > $(REPO_DIR)/analytics_v0_openapi.json
|
|
|
|
###############################################################################
|
|
# Transform docs into working files
|
|
###############################################################################
|
|
# `download.tsdoc.v2` now writes raw TypeDoc JSON directly under
|
|
# `reference/javascript/v2/` — the new pipeline (`scripts/build-reference-content.ts`,
|
|
# wired into `predev`/`prebuild` via `codegen:references:new`) walks those files
|
|
# at build time, so no separate `dereference` / `combine` step is needed.
|
|
transform: dereference.api.v1 dereference.auth.v1 dereference.storage.v0
|
|
|
|
# NOTE: no --dereferenced here — api_v2_openapi.json has a circular ref
|
|
# (APIErrorObject.issues -> APIErrorObject) that Redocly can't flatten to
|
|
# JSON. v1 uses the same approach for consistency.
|
|
# $refs are resolved manually in writeApiReferenceSections
|
|
dereference.api.v1:
|
|
npx --package=@redocly/cli redocly bundle -o $(REPO_DIR)/transforms/api_v1_openapi_deparsed.json $(REPO_DIR)/api_v1_openapi.json
|
|
npx --package=@redocly/cli redocly bundle -o $(REPO_DIR)/transforms/api_v2_openapi_deparsed.json $(REPO_DIR)/api_v2_openapi.json
|
|
|
|
dereference.auth.v1:
|
|
npx --package=@redocly/cli redocly bundle --dereferenced -o $(REPO_DIR)/transforms/auth_v1_openapi_deparsed.json $(REPO_DIR)/auth_v1_openapi.json
|
|
|
|
dereference.storage.v0:
|
|
npx --package=@redocly/cli redocly bundle --dereferenced -o $(REPO_DIR)/transforms/storage_v0_openapi_deparsed.json $(REPO_DIR)/storage_v0_openapi.json
|
|
|
|
dereference.analytics.v0:
|
|
npx --package=@redocly/cli redocly bundle --dereferenced -o $(REPO_DIR)/transforms/analytics_v0_openapi_deparsed.json $(REPO_DIR)/analytics_v0_openapi.json
|
|
|
|
###############################################################################
|
|
# Generate sections from OpenAPI 3.0
|
|
###############################################################################
|
|
generate: generate.sections.api.v1 generate.partials.access-control
|
|
|
|
generate.sections.api.v1:
|
|
npx tsx $(REPO_DIR)/sections/generateMgmtApiSections.cts \
|
|
$(REPO_DIR)/transforms/api_v1_openapi_deparsed.json \
|
|
$(REPO_DIR)/transforms/api_v2_openapi_deparsed.json \
|
|
$(REPO_DIR)/common-api-sections.json
|
|
|
|
# Generate PAT guide tables from Management API inputs and Studio's shared permission catalog.
|
|
generate.partials.access-control:
|
|
npx tsx $(REPO_DIR)/sections/generateAccessControlPartials.mts \
|
|
$(REPO_DIR)/transforms/api_v1_openapi_deparsed.json \
|
|
$(REPO_DIR)/transforms/api_v2_openapi_deparsed.json \
|
|
$(REPO_DIR)/mcp_tools_permissions.json \
|
|
$(REPO_DIR)/../content/_partials/access-control/scoped_pat_permissions.mdx \
|
|
$(REPO_DIR)/../content/_partials/access-control/scoped_pat_mcp_tools.mdx
|
|
npx prettier --write $(REPO_DIR)/../content/_partials/access-control/*.mdx
|
|
|
|
###############################################################################
|
|
# Validate OpenAPI 3.0
|
|
###############################################################################
|
|
|
|
validate.analytics.v0:
|
|
npx --package=@redocly/cli redocly lint --extends=minimal $(REPO_DIR)/analytics_v0_openapi.json
|
|
|
|
###############################################################################
|
|
# Format everything - easier for git to track changes.
|
|
###############################################################################
|
|
format:
|
|
npx prettier --cache --write .
|